# Amber — full documentation for agents

> Amber is a free, open-source (MIT) JavaScript and TypeScript runtime built with Rust and V8. One `amber` binary runs scripts, Jest-style tests, bundling, single-file compile, a small package installer, an HTTP serve command, and an opt-in capability sandbox for agent tools. It is not a drop-in Node.js replacement: each API is labeled Stable, Preview, Experimental, or Not supported.

Generated from https://amberjs.com at build time. Index: https://amberjs.com/llms.txt

---

URL: https://amberjs.com/index.md

# Amber v1.17.0 — JavaScript and TypeScript runtime in Rust and V8

> Amber is a free, open-source (MIT) JavaScript and TypeScript runtime built with Rust and V8. One `amber` binary runs scripts, Jest-style tests, bundling, single-file compile, a small package installer, an HTTP serve command, and an opt-in capability sandbox for agent tools. It is not a drop-in Node.js replacement: each API is labeled Stable, Preview, Experimental, or Not supported.

HTML: https://amberjs.com/ · Index for agents: https://amberjs.com/llms.txt

## Key facts

- Current release: v1.17.0. Install: `curl -fsSL https://get.amberjs.com/install.sh | sh` (macOS/Linux) or `irm https://get.amberjs.com/install.ps1 | iex` (Windows PowerShell). See [Installation](https://amberjs.com/docs/installation.md).
- License: MIT, free and open source. Source: https://github.com/zh30/amberjs
- Pricing: none. Amber is free to use; there is no paid tier, plan, or license fee.
- Status labels: Stable / Preview / Experimental / Not supported, from [docs/CURRENT_SCOPE.md](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md). 69 Stable contracts (G1–G69). Full table: [Compatibility](https://amberjs.com/compatibility.md).
- Node conformance scorecard: 56/56 PASS on main.
- Amber is not a drop-in replacement for Node.js, Bun, or Deno, and publishes no current performance numbers.

Amber runs JavaScript and TypeScript files from a single `amber` binary. It ships a test runner, a bundler, a single-file compiler, a small package installer, an HTTP serve command, and a permission sandbox for running agent tools.

Amber is open source under the MIT license. The source lives at [github.com/zh30/amberjs](https://github.com/zh30/amberjs).

## What Amber is

- **A V8 runtime written in Rust.** The CLI runs scripts on V8 through `src/runtime_minimal.rs`. TypeScript and TSX are transpiled with oxc before they run.
- **One binary, many commands.** `amber run`, `amber test`, `amber bundle`, `amber compile`, `amber install`, and `amber serve` all live in the same executable.
- **A Node.js and Web API surface with written contracts.** Each Stable API has a contract file in `docs/` and an integration test in `tests/`. The contract lists what works and where it stops.
- **A host for agent tools.** `amber run --sandbox` denies file, network, environment, and process access unless you allow it. `amber session` and `amber mcp` call exported functions from a tool file over JSON-RPC.

## What Amber is not

Amber is **not** a drop-in replacement for Node.js, Bun, or Deno. Many Node modules are partial, and several are Preview. Use the [compatibility page](https://amberjs.com/compatibility.md) to check an API before you depend on it.

Amber does not publish performance numbers today. Older benchmark tables in the repository are historical and were not re-run for this release.

## How to read this manual

Every capability carries one of four labels:

| Label | Meaning |
| :--- | :--- |
| **Stable** | Pinned by a contract document and an executable test that runs in CI. Limits are listed next to the API. |
| **Preview** | In the default build and usable, but the contract or edge cases are still being tightened. |
| **Experimental** | Code exists, but it is not a product promise until it is re-verified. |
| **Not supported** | Deliberately out of scope. Amber fails closed instead of pretending. |

The single source of truth for these labels is [`docs/CURRENT_SCOPE.md`](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md). If this site and that file disagree, the file wins.

## Next steps

- [Install Amber](https://amberjs.com/docs/installation.md)
- [Run your first script](https://amberjs.com/docs/quick-start.md)
- [Browse the CLI](https://amberjs.com/docs/cli-usage.md)
- [Check Node.js compatibility](https://amberjs.com/docs/node-compat.md)


## Pages

- [Compatibility & scope](https://amberjs.com/compatibility.md)
- [Docs index](https://amberjs.com/docs.md)
- [Full text for agents](https://amberjs.com/llms-full.txt)

---

URL: https://amberjs.com/compatibility.md

# Compatibility & scope (Amber v1.17.0)

> What Amber v1.17.0 supports: Stable contracts, Preview and Experimental surfaces, and deliberate non-goals, mirrored from docs/CURRENT_SCOPE.md.

HTML: https://amberjs.com/compatibility · Index for agents: https://amberjs.com/llms.txt

Source of truth: [docs/CURRENT_SCOPE.md](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md). If this page and that file disagree, the file wins.

- Stable contracts: G1–G69 (some rows group several ids; some are marked tentative or provisional).
- Node conformance scorecard: **56/56 PASS** ([scorecard](https://github.com/zh30/amberjs/blob/main/tests/conformance/scorecard.md)). CI fails if fewer than 55 pass or any fixture fails or is skipped. A passing fixture is a regression gate; it does not by itself make an API Stable.
- Performance: Amber publishes no current performance numbers. Older benchmark tables in the repository are historical.

## Stable

Pinned by a contract document and an executable CI test. Limits are listed next to each API; anything not listed is not promised.

### CLI & tooling

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| amber run / eval / repl | `amber run <file> · amber eval <code> · amber repl` | base scope | V8 execution through runtime_minimal; repl is the basic shell. | — |
| amber test | `amber test [files...]` | base scope | Jest-style describe / test / expect with discovery. --parallel exits 2. | — |
| amber bundle | `amber bundle <entry>` | G1 | oxc IIFE bundle; static import/require only; not webpack/esbuild parity. | [BUNDLE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BUNDLE_CONTRACT.md) |
| amber compile | `amber compile <entry> -o <bin>` | G2 | Host single-executable on Linux/macOS/Windows; no cross-compile, no native addons. | [COMPILE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/COMPILE_CONTRACT.md) |
| amber install | `amber install [--frozen-lockfile]` | G3 | Direct deps from package.json with lockfile pins and SRI checks; not npm/yarn/pnpm. | [INSTALL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/INSTALL_CONTRACT.md) |
| amber run --export-tools | `amber run --export-tools <file>` | G4 | Prints tool schemas as JSON and exits; never executes the file or calls a model. | [EXPORT_TOOLS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/EXPORT_TOOLS_CONTRACT.md) |
| amber run --inspect | `--inspect · --inspect-brk · --inspect-port` | G5 | CDP subset on 127.0.0.1 (Runtime.evaluate); no breakpoints or stepping. | [INSPECT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/INSPECT_CONTRACT.md) |
| --watch | `amber run --watch · amber test --watch` | G6 | Full re-exec on change plus a localhost reload WebSocket; not in-place HMR. | [WATCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WATCH_CONTRACT.md) |
| amber serve | `amber serve [--port] [script]` | G41 | HTTP/1.1 health document or fetch-handler bridge; one request per connection. | [SERVE_HTTP_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTP_CONTRACT.md) |
| amber serve --https | `amber serve --https --cert --key` | G7 | rustls TLS, HTTP/1.1 only; no HTTP/2, keep-alive, chunked bodies or static files. | [SERVE_HTTPS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTPS_CONTRACT.md) |
| TypeScript / TSX | `.ts · .tsx · .mts · .cts · .jsx` | G36 | oxc transpile-only with .ts stack remap; not tsc — no type-checking. | [TYPESCRIPT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TYPESCRIPT_CONTRACT.md) |
| amber session / amber mcp | `amber session <tools> · amber mcp <tools>` | base scope | Agent tool execution over stdin JSON-RPC and an MCP stdio server. | — |
| amber snapshot | `amber snapshot [build\|status\|clean]` | base scope | Manage V8 startup snapshots with mmap backing. | — |

### Runtime

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| Capability sandbox | `--sandbox · --allow-* · --permission-policy · --audit-log` | base scope | Deny-by-default fs/net/env/run with exact allows and a JSONL audit trail. | — |
| Deterministic execution | `--seed <u64> · --freeze-time <spec>` | base scope | Seeded Math.random / getRandomValues and a frozen virtual clock. | — |
| amber:ai | `Tensor · LLM · AgentPipeline` | base scope | In-process TypedArray tensors, local streaming LLM, pipelines. Cargo feature "ai" is empty. | — |
| WebAssembly streaming | `WebAssembly.compileStreaming · instantiateStreaming` | base scope | V8 Wasm; streaming compile from Response. amber:wasm zero-copy helpers are Preview. | — |
| WinterTC baseline | `DOMException · URLPattern · navigator · amber:sockets · import.meta` | base scope | ECMA-429 minimum common API, wintertc export conditions, TCP + rustls sockets. | — |

### Node.js APIs

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| CommonJS require | `require · module · require.resolve · createRequire` | G28 (provisional) | node_modules walk, package.json exports/imports/main; not the Node Module class. | [REQUIRE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/REQUIRE_CONTRACT.md) |
| fs | `fs · fs/promises` | G8 | Byte I/O, mkdir, stat, fds, readdir dirents, promises; no glob / cp / opendir / statfs. | [FS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FS_CONTRACT.md) |
| fs.watch / fs.watchFile | `fs.watch · fs.watchFile · fs.unwatchFile` | G64 (tentative) | Real OS watcher (notify) and stat polling; no fs.promises.watch. | [FS_WATCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FS_WATCH_CONTRACT.md) |
| path | `path · path.posix` | G17 | POSIX semantics; path.win32 methods are the POSIX implementations. | [PATH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/PATH_CONTRACT.md) |
| events | `EventEmitter · once` | G18 | Full listener API and static once; no events.on async iterator. | [NODE_EVENTS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_EVENTS_CONTRACT.md) |
| buffer | `Buffer` | G19 | from / alloc / concat / toString / slice; readUInt* and compare are outside. | [BUFFER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BUFFER_CONTRACT.md) |
| os | `platform · arch · cpus · tmpdir · homedir …` | G20 | Host info subset; cpus()[].speed / times are outside. | [OS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_CONTRACT.md) |
| os.hostname | `os.hostname()` | G62 | Real gethostname / GetComputerNameW; not a DNS FQDN. | [OS_HOSTNAME_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_HOSTNAME_CONTRACT.md) |
| os.networkInterfaces | `os.networkInterfaces()` | G63 | Real OS enumerator; MAC is best-effort. | [OS_NETWORK_INTERFACES_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_NETWORK_INTERFACES_CONTRACT.md) |
| zlib (sync) | `gzipSync · deflateSync · inflateRawSync …` | G21 | Six sync codecs; no brotli, no zlib.constants. | [ZLIB_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ZLIB_CONTRACT.md) |
| zlib (async callbacks) | `gzip · gunzip · deflate · inflate · deflateRaw · inflateRaw` | G48 · G58 (tentative) | Callbacks on a later tick; no streaming createGzip family. | [ZLIB_ASYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ZLIB_ASYNC_CONTRACT.md) |
| util | `format · inspect · promisify · callbackify · types` | G22 · G59 | Basics plus util.types.isArrayBuffer / isRegExp; inspect ignores depth / colors. | [UTIL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/UTIL_CONTRACT.md) |
| process | `nextTick · env · cwd · stdout.write · hrtime · memoryUsage` | G22 · G44 · G53 · G54 | Basics only; hrtime is epoch-based, heap numbers are estimates; exit / stdin stay Preview. | [PROCESS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/PROCESS_CONTRACT.md) |
| crypto | `createHash · createHmac · randomBytes · randomUUID · timingSafeEqual` | G23 | md5 / sha* / blake3 digests; KDF, sign/verify and KeyObject stay Preview. | [NODE_CRYPTO_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_CRYPTO_CONTRACT.md) |
| crypto cipheriv | `createCipheriv · createDecipheriv (AES-CBC / GCM / CTR)` | G43 · G51 · G52 | AES-128/192/256 CBC, GCM (auth tag, AAD) and CTR; no password createCipher. | [NODE_CRYPTO_CIPHERIV_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_CRYPTO_CIPHERIV_CONTRACT.md) |
| stream | `Readable · Writable · PassThrough · pipe` | G24 | Flowing push / pipe; no backpressure. Transform / Duplex / pipeline stay Preview. | [NODE_STREAM_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_STREAM_CONTRACT.md) |
| child_process (sync) | `execSync · spawnSync` | G25 | Sandbox-aware; no timeout / cwd / env options. | [CHILD_PROCESS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_CONTRACT.md) |
| child_process (async) | `exec · execFile · spawn` | G47 · G60 (tentative) | Captured output via callback on a later turn; no live stdio pipes. | [CHILD_PROCESS_ASYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_ASYNC_CONTRACT.md) |
| child_process.fork | `fork · child.send · process.send` | G67 (tentative) | Real OS process with JSON IPC over localhost TCP. | [CHILD_PROCESS_FORK_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_FORK_CONTRACT.md) |
| url | `fileURLToPath · pathToFileURL` | G26 | POSIX file URL helpers; legacy parse / format are outside. | [NODE_URL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_URL_CONTRACT.md) |
| dns | `lookup · resolve4 · resolve6 · reverse · getServers` | G27 · G65 (provisional) | Host getaddrinfo / getnameinfo, sync; no dns.promises or setServers. | [DNS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DNS_CONTRACT.md) |
| http (server) | `http.createServer · listen · req / res` | G37 (tentative) | Buffered responses; the http client, Agent, https and http2 are not supported. | [HTTP_SERVER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/HTTP_SERVER_CONTRACT.md) |
| net | `net.createServer · net.connect` | G45 · G61 (tentative) | Real TCP listen / accept / connect; no TLS, unix sockets or full duplex parity. | [NET_SERVER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NET_SERVER_CONTRACT.md) |
| querystring | `parse · stringify · escape · unescape` | G38 | Fixed & / = separators; no options. | [QUERYSTRING_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/QUERYSTRING_CONTRACT.md) |
| string_decoder | `StringDecoder` | G39 · G68 | utf8, latin1, ascii, base64, hex, utf16le with partial-unit buffering; no base64url. | [STRING_DECODER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/STRING_DECODER_CONTRACT.md) |
| assert | `ok · strictEqual · deepStrictEqual · throws · match · rejects` | G40 · G69 | Strict assertions; loose equal coercion and the deepEqual alias are not pinned. | [ASSERT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ASSERT_CONTRACT.md) |
| timers | `timers · timers/promises` | G42 · G50 | Module timers and Promise setTimeout / setImmediate with AbortSignal. | [TIMERS_MODULE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TIMERS_MODULE_CONTRACT.md) |
| readline | `createInterface · question` | G46 (tentative) | One line from host stdin; no history, completer or readline.promises. | [READLINE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/READLINE_CONTRACT.md) |
| tty | `tty.isatty` | G49 | Real isatty on Unix; always false on Windows today. | [TTY_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TTY_CONTRACT.md) |
| vm | `runInThisContext · runInNewContext · Script` | G55 · G66 (tentative) | Same-context run and a fresh-context property-copy sandbox; not Contextify parity. | [VM_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/VM_CONTRACT.md) |
| diagnostics_channel | `channel · subscribe · tracingChannel.traceSync` | G56 (tentative) | Current-isolate pub/sub; no tracePromise. | [DIAGNOSTICS_CHANNEL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DIAGNOSTICS_CHANNEL_CONTRACT.md) |
| async_hooks | `AsyncResource · AsyncLocalStorage` | G57 (tentative) | ALS run / getStore / snapshot; createHook is not supported. | [ASYNC_HOOKS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ASYNC_HOOKS_CONTRACT.md) |

### Web APIs

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| fetch | `fetch · Request · Response · Headers` | G9 | Streaming body reader, redirects, integrity, AbortSignal; no browser CORS origin. | [FETCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FETCH_CONTRACT.md) |
| URL & encoding | `URL · URLSearchParams · TextEncoder · TextDecoder · structuredClone` | G10 | No IDNA; TextDecoder is UTF-8 only. | [URL_ENCODING_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/URL_ENCODING_CONTRACT.md) |
| Blob / File / FormData | `Blob · File · FormData` | G11 | Multipart fetch bodies; text() / arrayBuffer() are synchronous. | [BLOB_FORMDATA_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BLOB_FORMDATA_CONTRACT.md) |
| Events & channels | `EventTarget · AbortController · MessageChannel · BroadcastChannel` | G12 | No DOM tree; BroadcastChannel stays within one isolate. | [EVENTS_CHANNELS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/EVENTS_CHANNELS_CONTRACT.md) |
| Streams, compression, timers | `ReadableStream · CompressionStream · setTimeout · performance` | G13 | Queuing strategies do not apply backpressure. | [STREAMS_TIMERS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/STREAMS_TIMERS_CONTRACT.md) |
| Web Crypto | `crypto.subtle · getRandomValues · randomUUID` | G14 | SHA, HMAC, AES, PBKDF2, ECDH, Ed25519, ECDSA, RSA; no HKDF / RSA-PSS / X25519. | [WEB_CRYPTO_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WEB_CRYPTO_CONTRACT.md) |
| WebSocket (client) | `new WebSocket('ws://…')` | G15 | Real ws:// handshake; no subprotocols or permessage-deflate; not a server. | [WEBSOCKET_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WEBSOCKET_CONTRACT.md) |
| Workers | `Worker · worker_threads · navigator.serviceWorker` | G16 | Dedicated workers with JSON messages; no SharedWorker or module workers. | [WORKERS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WORKERS_CONTRACT.md) |
| atob / btoa | `atob · btoa` | G29 | Standard Base64; throws plain Error, not DOMException. | [ATOB_BTOA_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ATOB_BTOA_CONTRACT.md) |
| ErrorEvent / onerror | `ErrorEvent · globalThis.onerror` | G30 (provisional) | Uncaught throws can be handled by onerror; not a document error pipeline. | [ERROR_EVENT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ERROR_EVENT_CONTRACT.md) |
| Clipboard (text) | `navigator.clipboard.writeText / readText` | G31 | Process-local text store, not the OS clipboard; no ClipboardItem. | [CLIPBOARD_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CLIPBOARD_CONTRACT.md) |
| DOMParser | `new DOMParser().parseFromString()` | G32 | Read-only HTML / XML parse tree with selectors; not a live DOM. | [DOMPARSER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DOMPARSER_CONTRACT.md) |
| Background Sync | `registration.sync · SyncEvent` | G33 | Fires on the same CLI isolate; not Periodic Sync. | [BACKGROUND_SYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BACKGROUND_SYNC_CONTRACT.md) |
| Cache Storage | `caches.open · cache.match / put` | G34 | In-process store; not an HTTP cache and not persisted. | [CACHE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CACHE_CONTRACT.md) |
| Service worker fetch | `FetchEvent.respondWith` | G35 | Activated worker intercepts page fetch; scope is not matched. | [SW_FETCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SW_FETCH_CONTRACT.md) |

## Preview

In the default build and usable, but the contract or edge cases are still being tightened.

- **Rest of src/nodejs_core/** — Node modules and methods outside the contracts above: stream Transform / Duplex / pipeline, crypto KDF / sign / KeyObject, process.exit / stdin, perf_hooks, and more.
- **Rest of src/web_api/** — Web APIs outside the Stable contracts, such as ExtendableEvent. Treated per-API, not as blanket Web compatibility.
- **amber:wasm** — Zero-copy WebAssembly.Memory / ArrayBuffer helpers and mmap module load.

## Experimental

Code exists, but it is not a product promise until it is re-verified.

- **amber init · create · add · remove · prune · upgrade · x** — Package and scaffolding commands outside the Stable amber install contract.
- **amber debug** — Debug command; use the Stable --inspect CDP subset instead.
- **N-API hello loader** — process.dlopen can load a C hello addon. Not Node ABI compatibility; Prisma and sharp are out of scope.
- **Cargo features** — benchmarks and observability are CI-checked. cloudnative, enterprise, multilang and tch are not CI-gated; feature "ai" is empty.
- **Distribution channels** — GHCR image is linux/amd64 only. The winget manifest lives in-repo and is not submitted.

### Present in the binary but not classified by CURRENT_SCOPE (treated as Experimental)

`amber fmt`, `amber lint`, `amber bench`, `amber task`, `amber types`, `amber lsp`, `amber profile`, `amber deploy`, `amber record / replay`, `--virtual-fs`, `--import-map`, `amber:mcp`, `amber:kv`, `amber:bus`, `amber:grammar`, `amber:checkpoint`, `amber:weights`, `amber:tools`, `amber:security`, `amber:std`, `amber:db`, `amber:vector`, `amber:pool`, `amber:ffi`

## Not supported (non-goals)

Deliberately out of scope today. Where possible Amber throws or rejects instead of returning fake data.

- **SharedWorker · module workers** — new Worker(url, { type: 'module' }) throws.
- **Push · Notification · Payment** — Push subscription rejects. These browser surfaces are deferred.
- **ClipboardItem** — clipboard.read / write reject with an Error naming ClipboardItem.
- **http client · Agent · https · http2** — Use the Stable Web fetch for outbound HTTP. Only the http server subset is Stable.
- **Streaming zlib · brotli** — createGzip / createDeflate families, brotli and zlib.constants are not implemented.
- **Type-checking** — TypeScript is transpile-only. Run tsc --noEmit in CI if you need type errors.
- **fs.glob · fs.cp · fs.opendir · fs.statfs** — Not implemented; also no fs.promises.watch.
- **Parallel tests · cross-compile** — amber test --parallel exits 2. amber compile only targets the host OS.
- **npm workspaces · lifecycle scripts** — amber install does not run scripts, link .bin, or read yarn / pnpm lockfiles.

---

URL: https://amberjs.com/docs/introduction.md

# Introduction

> Amber is a JavaScript and TypeScript runtime built with Rust and V8. This manual covers v1.17.0.

HTML: https://amberjs.com/docs/introduction · Index for agents: https://amberjs.com/llms.txt

Amber runs JavaScript and TypeScript files from a single `amber` binary. It ships a test runner, a bundler, a single-file compiler, a small package installer, an HTTP serve command, and a permission sandbox for running agent tools.

Amber is open source under the MIT license. The source lives at [github.com/zh30/amberjs](https://github.com/zh30/amberjs).

## What Amber is

- **A V8 runtime written in Rust.** The CLI runs scripts on V8 through `src/runtime_minimal.rs`. TypeScript and TSX are transpiled with oxc before they run.
- **One binary, many commands.** `amber run`, `amber test`, `amber bundle`, `amber compile`, `amber install`, and `amber serve` all live in the same executable.
- **A Node.js and Web API surface with written contracts.** Each Stable API has a contract file in `docs/` and an integration test in `tests/`. The contract lists what works and where it stops.
- **A host for agent tools.** `amber run --sandbox` denies file, network, environment, and process access unless you allow it. `amber session` and `amber mcp` call exported functions from a tool file over JSON-RPC.

## What Amber is not

Amber is **not** a drop-in replacement for Node.js, Bun, or Deno. Many Node modules are partial, and several are Preview. Use the [compatibility page](https://amberjs.com/compatibility.md) to check an API before you depend on it.

Amber does not publish performance numbers today. Older benchmark tables in the repository are historical and were not re-run for this release.

## How to read this manual

Every capability carries one of four labels:

| Label | Meaning |
| :--- | :--- |
| **Stable** | Pinned by a contract document and an executable test that runs in CI. Limits are listed next to the API. |
| **Preview** | In the default build and usable, but the contract or edge cases are still being tightened. |
| **Experimental** | Code exists, but it is not a product promise until it is re-verified. |
| **Not supported** | Deliberately out of scope. Amber fails closed instead of pretending. |

The single source of truth for these labels is [`docs/CURRENT_SCOPE.md`](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md). If this site and that file disagree, the file wins.

## Next steps

- [Install Amber](https://amberjs.com/docs/installation.md)
- [Run your first script](https://amberjs.com/docs/quick-start.md)
- [Browse the CLI](https://amberjs.com/docs/cli-usage.md)
- [Check Node.js compatibility](https://amberjs.com/docs/node-compat.md)


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/installation.md

# Installation

> Install the amber binary from a release archive, or build it from source with Cargo.

HTML: https://amberjs.com/docs/installation · Index for agents: https://amberjs.com/llms.txt

## macOS and Linux

```bash
curl -fsSL https://get.amberjs.com/install.sh | sh
```

The script downloads the release archive for your OS and CPU from GitHub Releases and installs it as `~/.amber/bin/amber`. Add that directory to your `PATH` if the script asks you to.

You can change what it installs with environment variables:

| Variable | Default | Purpose |
| :--- | :--- | :--- |
| `AMBER_VERSION` | latest release | Tag to install, for example `v1.17.0` |
| `AMBER_INSTALL_DIR` | `~/.amber/bin` | Where the `amber` binary goes |
| `AMBER_REPO` | `zh30/amberjs` | GitHub repository to download from |

```bash
AMBER_VERSION=v1.17.0 AMBER_INSTALL_DIR=~/.local/bin sh -c "$(curl -fsSL https://get.amberjs.com/install.sh)"
```

## Windows

```powershell
irm https://get.amberjs.com/install.ps1 | iex
```

The PowerShell script installs `amber.exe` under `%LOCALAPPDATA%\amber\bin`. It honors the same `AMBER_VERSION`, `AMBER_INSTALL_DIR`, and `AMBER_REPO` variables.

## Build from source

Building from source is the most direct path and is part of the Stable scope.

```bash
git clone https://github.com/zh30/amberjs
cd amberjs
cargo build --release
./target/release/amber --version
```

The repository pins its Rust toolchain in `rust-toolchain.toml`. The first build downloads a prebuilt V8 library through the `v8` crate, so it needs network access.

## Release assets

Each GitHub release publishes archives for Linux, macOS, and Windows, plus checksums, an SBOM, and cosign signatures. The archives are named `amber-v<version>-<target>`.

## Other channels

A Homebrew formula, a GHCR container image (`ghcr.io/zh30/amberjs`, linux/amd64 only), and a winget manifest exist in the repository. They are **Experimental** distribution channels, so this manual does not recommend them yet.

## Verify the install

```bash
amber --version
amber eval "1 + 1"
```


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/quick-start.md

# Quick start

> Run a script, a TypeScript file, a test, and an HTTP handler in a few minutes.

HTML: https://amberjs.com/docs/quick-start · Index for agents: https://amberjs.com/llms.txt

## 1. Evaluate a snippet

```bash
amber eval "1 + 1"
```

## 2. Run a JavaScript file

```js
// hello.js
const os = require("node:os");
console.log(`Hello from Amber on ${os.platform()}`);
```

```bash
amber run hello.js
```

## 3. Run TypeScript directly

There is no build step. Amber erases types with oxc and runs the result.

```ts
// greet.ts
interface User {
  name: string;
}

const greet = (user: User): string => `Hello, ${user.name}`;
console.log(greet({ name: "Amber" }));
```

```bash
amber run greet.ts
```

Types are **not** checked. Run `tsc --noEmit` in CI if you want type errors. See [TypeScript](https://amberjs.com/docs/typescript.md).

## 4. Write a test

```js
// math.test.js
describe("math", () => {
  test("adds numbers", () => {
    expect(1 + 2).toBe(3);
  });
});
```

```bash
amber test math.test.js
amber test          # discover every test file under the current directory
amber test --watch  # re-run when a watched file changes
```

## 5. Serve HTTP

```js
// server.js
module.exports = {
  fetch(request) {
    return new Response("Hello from Amber");
  },
};
```

```bash
amber serve --port 3000 server.js
curl http://localhost:3000/
```

`amber serve` handles one HTTP/1.1 request per connection. It is a small handler bridge, not a general web server. See [Server mode](https://amberjs.com/docs/server-mode.md).

## 6. Use the REPL

```bash
amber repl
```

## Where next

- [CLI reference](https://amberjs.com/docs/cli-usage.md) lists every command and its maturity.
- [Node.js compatibility](https://amberjs.com/docs/node-compat.md) shows which modules are Stable.
- [Agent sandbox](https://amberjs.com/docs/agent-sandbox.md) shows how to run untrusted tool code.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/cli-usage.md

# CLI reference

> Every amber subcommand in v1.17.0, grouped by maturity. Checked against src/main.rs.

HTML: https://amberjs.com/docs/cli-usage · Index for agents: https://amberjs.com/llms.txt

Run `amber --help` or `amber <command> --help` for the full flag list on your build.

## Stable commands

| Command | What it does | Contract |
| :--- | :--- | :--- |
| `amber run <file> [args...]` | Run a JS or TS file | — |
| `amber eval <code>` | Evaluate a snippet and print the result | — |
| `amber repl` | Interactive REPL | — |
| `amber test [file]` | Discover and run Jest-style tests | [Testing](https://amberjs.com/docs/testing.md) |
| `amber bundle <entry> -o <out>` | Pack a local module graph into one JS file | [`BUNDLE_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/BUNDLE_CONTRACT.md) |
| `amber compile <entry> -o <bin>` | Build a single executable for this host | [`COMPILE_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/COMPILE_CONTRACT.md) |
| `amber install [--frozen-lockfile]` | Install direct dependencies from `package.json` | [`INSTALL_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/INSTALL_CONTRACT.md) |
| `amber serve [file]` | Serve a fetch handler over HTTP/1.1 | [`SERVE_HTTP_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTP_CONTRACT.md) |
| `amber serve --https --cert --key` | Same, over rustls TLS | [`SERVE_HTTPS_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTPS_CONTRACT.md) |
| `amber session <file>` | JSON-RPC tool session over stdin and stdout | [MCP & sessions](https://amberjs.com/docs/mcp-protocol.md) |
| `amber mcp <file>` | MCP stdio server for a tool file | [MCP & sessions](https://amberjs.com/docs/mcp-protocol.md) |
| `amber snapshot build\|status\|clean` | Manage the V8 startup snapshot | — |
| `amber version` / `amber --version` | Print the version | — |

## Stable `amber run` flags

| Flag | What it does | Contract |
| :--- | :--- | :--- |
| `--watch`, `-w` | Re-run the entry when a watched file changes | [`WATCH_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/WATCH_CONTRACT.md) |
| `--inspect`, `--inspect-brk`, `--inspect-port` | A small CDP endpoint on `127.0.0.1` | [`INSPECT_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/INSPECT_CONTRACT.md) |
| `--export-tools` | Print tool schemas as JSON and exit, without running the file | [`EXPORT_TOOLS_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/EXPORT_TOOLS_CONTRACT.md) |

`--watch` restarts the whole process after the previous run returns. It is not hot module replacement.

## Permission and determinism flags

These flags work on `run`, `test`, `serve`, `session`, `mcp`, and the other commands that execute code.

| Flag | What it does |
| :--- | :--- |
| `--sandbox` | Deny file, network, environment, and child-process access by default |
| `--allow-read <path>` / `--allow-write <path>` | Allow one exact path (repeatable) |
| `--allow-net <host>` / `--allow-listen <host>` | Allow outbound connections or listeners for a host or URL |
| `--allow-env <NAME>` / `--allow-run <command>` | Allow one variable or one command |
| `--deny-fs`, `--deny-net`, `--deny-env`, `--deny-run` | Deny one capability without the full sandbox |
| `--permission-policy <file>` | Load allow and deny rules from JSON |
| `--audit-log <file>` | Append each permission decision as JSONL |
| `--seed <u64>` | Seed `Math.random`, `crypto.getRandomValues`, and `crypto.randomBytes` |
| `--freeze-time <spec>` | Freeze `Date.now`, `new Date()`, and `performance.now` |
| `--timeout <ms>` / `--max-memory <MB>` | Stop runaway scripts |

See [Agent sandbox](https://amberjs.com/docs/agent-sandbox.md) for examples.

## Experimental commands

These commands exist, but they are outside the Stable scope. Expect rough edges.

| Command | Notes |
| :--- | :--- |
| `amber debug <file>` | Older debug entry point. Use `amber run --inspect` instead. |
| `amber init`, `amber create` | Project scaffolding |
| `amber add`, `amber remove`, `amber prune`, `amber upgrade` | Package edits outside the `amber install` contract |
| `amber x <pkg>` (aliases `dlx`, `bunx`) | Run a package binary without installing |
| `amber test --parallel` | Rejected with exit code 2. V8 isolates are not shared across threads. |

## Present but not classified

The binary also includes these commands. `CURRENT_SCOPE.md` does not classify them yet, so this manual treats them as Experimental: `amber fmt`, `amber lint`, `amber bench`, `amber task`, `amber types`, `amber lsp`, `amber profile`, `amber deploy`, `amber record`, and `amber replay`, plus the `--import-map` and `--virtual-fs` flags. See [Experimental](https://amberjs.com/docs/experimental.md).

## Exit codes

Contracted failures print a prefix such as `error: amber serve:` or `error: amber install:` and exit non-zero. Misuse of a flag, such as `amber test --parallel`, exits 2.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/typescript.md

# TypeScript

> Run .ts and .tsx files directly. Amber transpiles with oxc and does not type-check.

HTML: https://amberjs.com/docs/typescript · Index for agents: https://amberjs.com/llms.txt

TypeScript transpile-only is **Stable** (G36). The contract is [`docs/TYPESCRIPT_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/TYPESCRIPT_CONTRACT.md).

## What runs

- Entry files ending in `.ts`, `.tsx`, `.mts`, `.cts`, or `.jsx`.
- Files loaded with CommonJS `require` that use those extensions.
- `amber eval` snippets that look like TypeScript or JSX.

```ts
// app.ts
type Status = "ok" | "error";

function report(status: Status): string {
  return `status=${status}`;
}

console.log(report("ok"));
```

```bash
amber run app.ts
```

## How it works

Amber uses oxc to strip types and emit JavaScript, then runs it on V8.

- `using` declarations and Stage 3 decorators are lowered to ES2022.
- TSX emits classic `React.createElement` calls.
- When a source map is active, stack traces point at `.ts` lines.
- A parse or transform error fails the run. Amber does not guess.

## What it does not do

This is **not** `tsc`. These are permanent non-goals for this surface:

- Type checking. A file with type errors still runs.
- `tsconfig.json` programs, path aliases, and project references.
- The automatic JSX runtime and `emitDecoratorMetadata`.

Run `tsc --noEmit` in CI if you need type errors to fail the build.

## Type definitions for Amber APIs

`amber types` prints type definitions for Amber built-ins. That command is not classified in the scope page yet, so treat its output as Experimental.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/testing.md

# Test runner

> amber test discovers and runs Jest-style tests without extra dependencies.

HTML: https://amberjs.com/docs/testing · Index for agents: https://amberjs.com/llms.txt

The test runner is **Stable**: discovery, execution, and `--watch`. The watch behavior is pinned by [`docs/WATCH_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/WATCH_CONTRACT.md).

## Write a test

```js
// math.test.js
describe("math", () => {
  test("adds numbers", () => {
    expect(2 + 3).toBe(5);
  });

  test("maps arrays", () => {
    const doubled = [1, 2, 3].map((n) => n * 2);
    expect(doubled).toEqual([2, 4, 6]);
  });
});
```

The globals `describe`, `test`, `it`, and `expect` are installed for you. TypeScript test files work the same way.

## Run tests

```bash
amber test                 # discover and run every test file
amber test math.test.js    # run one file
amber test --watch         # re-run the discovered set on change
amber test -t "adds"       # filter by test name (regex)
amber test --bail          # stop after the first failure
```

## Discovery

Without a file argument, `amber test` walks the current directory for these patterns:

```text
*.test.js  *.test.ts  *.test.mjs
*.spec.js  *.spec.ts  *.spec.mjs
```

It skips `node_modules`, `manual`, and `__snapshots__` directories. `--watch` does not pick up new test files created after it starts.

## What the harness provides

The built-in harness includes the common Jest surface:

- Hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach`.
- Modifiers: `test.skip`, `test.only`, `test.todo`, `test.each`, and the same on `describe` and `it`.
- Matchers such as `toBe`, `toEqual`, `toStrictEqual`, `toMatchObject`, `toContain`, `toHaveLength`, `toHaveProperty`, `toThrow`, `toBeCloseTo`, and `.not`.
- Mocks with `jest.fn()` and `jest.spyOn()`, plus the `toHaveBeenCalled*` matchers.
- Module factories with `jest.mock(specifier, factory)`. This is an alias of `jest.doMock`: it is not hoisted, so call it before the `require` it should affect.
- File snapshots with `toMatchSnapshot` (`--update-snapshots` rewrites them).

The Stable promise covers discovery, execution, exit status, and watch mode. Individual matchers, snapshots, and `--coverage` are not separately contracted, so check them on your build.

## Limits

- `amber test --parallel` is rejected with exit code 2. V8 isolates are not shared across threads.
- This is not Jest. Config files, custom reporters, automatic mock hoisting, and fake timers are not part of the runner.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/server-mode.md

# Server mode

> Serve a fetch-style handler over HTTP/1.1, with optional rustls TLS.

HTML: https://amberjs.com/docs/server-mode · Index for agents: https://amberjs.com/llms.txt

Plain `amber serve` is **Stable** (G41) and `amber serve --https` is **Stable** (G7). Their contracts are [`SERVE_HTTP_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTP_CONTRACT.md) and [`SERVE_HTTPS_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTPS_CONTRACT.md).

## A handler

Export a function, an object with `fetch`, or a `default` export. The handler receives a `Request` and returns a `Response`.

```js
// server.js
module.exports = {
  fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/health") {
      return Response.json({ ok: true });
    }
    return new Response(`Hello from ${url.pathname}`);
  },
};
```

```bash
amber serve --port 3000 server.js
curl http://localhost:3000/health
```

| Flag | Default | Meaning |
| :--- | :--- | :--- |
| `--port`, `-p` | `3000` | Port. `0` picks a free port and prints it. |
| `--host` | `localhost` | Bind address |
| `--https` | off | Turn on TLS |
| `--cert`, `--key` | — | Unencrypted PEM files, required with `--https` |

With no script, `amber serve` answers with a JSON health document.

## HTTPS

```bash
amber serve --https --cert cert.pem --key key.pem --port 8443 server.js
```

The certificate file lists the leaf certificate first. Keys may be PKCS#8, PKCS#1 RSA, or SEC1. Missing or unreadable material exits with code 2 before the server listens.

## Limits

Both modes share the same framing limits:

- One HTTP/1.1 request per connection. No keep-alive.
- Headers up to 16 KiB and 64 fields, bodies up to 1 MiB, 10 second read and write timeouts.
- No chunked bodies, streaming responses, HTTP/2, WebSocket upgrades, or static file serving.

`amber serve` is a handler bridge, not a general web server. Put a reverse proxy in front of it for production traffic.

## Node `http` servers

If you prefer `require('http').createServer`, the narrow Node `http` server is a separate Stable contract (tentative G37). It supports keep-alive, but buffers each response until `end()`. The `http.request` client, `Agent`, `https`, and `http2` are not supported. See [Node.js compatibility](https://amberjs.com/docs/node-compat.md).


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/package-manager.md

# Package installer

> Install direct dependencies from package.json, with lockfile pins and integrity checks. Not an npm replacement.

HTML: https://amberjs.com/docs/package-manager · Index for agents: https://amberjs.com/llms.txt

`amber install` is **Stable** (G3) for the subset in [`docs/INSTALL_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/INSTALL_CONTRACT.md).

## Usage

```bash
amber install
amber install --frozen-lockfile
```

## What it does

- Reads `dependencies` and `devDependencies` from `./package.json`.
- Downloads tarballs from `https://registry.npmjs.org` into `node_modules`.
- When `./package-lock.json` has a top-level `dependencies` entry for a package, checks the version request, the `resolved` URL, and `integrity`.
- Hashes every tarball before unpacking it (SRI `sha512`, `sha384`, `sha256`, or `sha1`, else the SHA-1 `shasum`).
- `--frozen-lockfile` fails if the lock is missing or a direct request does not match it, and never rewrites the lock.

Contracted failures print `error: amber install:` and exit non-zero.

## What it does not do

`amber install` is not npm, yarn, or pnpm. These are outside the contract:

- Workspaces, lifecycle scripts (`postinstall` and friends), and `.bin` links.
- Custom registries and `.npmrc`.
- Installing `peerDependencies`.
- The lockfile `packages` map, nested lock entries, `yarn.lock`, and `pnpm-lock.yaml`.
- Lock pins for transitive dependencies. Unlocked ranges follow registry order, not the highest matching semver.

`optionalDependencies` download errors do not fail the command.

## Experimental package commands

`amber add`, `amber remove`, `amber prune`, `amber upgrade`, `amber init`, `amber create`, and `amber x` (also `dlx` and `bunx`) exist but are **Experimental**. They are outside the install contract.

```bash
amber add lodash@4.17.21   # Experimental
amber x cowsay hello       # Experimental
```


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/bundling-compilation.md

# Bundle and compile

> amber bundle packs a module graph into one file. amber compile turns it into a single executable for this host.

HTML: https://amberjs.com/docs/bundling-compilation · Index for agents: https://amberjs.com/llms.txt

## amber bundle

`amber bundle` is **Stable** (G1) for the contract in [`docs/BUNDLE_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/BUNDLE_CONTRACT.md).

```bash
amber bundle src/index.ts -o dist/app.js
amber bundle src/index.ts -o dist/app.js --minify --sourcemap
```

It reads static `import` and `require` calls from a local JS, TS, or JSON graph and writes one IIFE with oxc.

### Limits

- Only static `import` and `require` are followed.
- Unresolved bare specifiers stay as runtime `require()` calls.
- A missing relative import or a non-JS/JSON asset fails with `error: amber bundle:`.
- `--sourcemap` writes a SourceMap v3 file that lists sources, but `mappings` is empty.
- `--target` only writes a header comment. `--tree-shake` is accepted and ignored.
- Only `package.json` `"main"` is used, not `"exports"`.

This is not webpack, Rollup, or esbuild.

## amber compile

`amber compile` is **Stable** (G2) for the contract in [`docs/COMPILE_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/COMPILE_CONTRACT.md).

```bash
amber compile src/cli.ts -o mytool
./mytool --help
```

It copies the running `amber` executable and appends the bundled script with an `AMBER_STANDALONE` trailer. On macOS the payload goes in a `__AMBER` Mach-O segment and the binary is ad-hoc signed.

### Limits

- Linux, macOS, and Windows hosts only. There is no cross-compilation.
- The output uses the same dynamic linker as the `amber` that built it.
- Native `.node` addons are rejected.
- Dynamic `import()` and computed `require()` fail the compile.
- There is no embedded virtual filesystem. `--help` and `--version` are passed through to your script.

This is not pkg, nexe, or `bun build --compile`.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/debugging.md

# Debugging

> A small Chrome DevTools Protocol endpoint for evaluating code in a running script.

HTML: https://amberjs.com/docs/debugging · Index for agents: https://amberjs.com/llms.txt

`amber run --inspect` and `--inspect-brk` are **Stable** (G5) for the CDP subset in [`docs/INSPECT_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/INSPECT_CONTRACT.md).

## Usage

```bash
amber run --inspect app.js
amber run --inspect-brk app.js            # wait for the client before running
amber run --inspect --inspect-port 9300 app.js
```

The listener binds to `127.0.0.1` (default port 9229; port 0 is rejected). It answers:

- `GET /json/version` and `GET /json/list`.
- `Runtime.evaluate` on the user isolate.
- `Runtime.runIfWaitingForDebugger` and `Debugger.resume`, which release `--inspect-brk`.

## Limits

This is **not** Chrome DevTools or the V8 inspector.

- There are no breakpoints, stepping, or scope inspection.
- Other CDP methods return JSON-RPC error `-32601`.
- `Runtime.evaluate` only runs while the isolate thread is free: during the pause or between event-loop tasks. It does not interrupt a synchronous turn.
- Results carry a `description` only.
- `--watch` and `--workers` greater than 1 are rejected with `--inspect`.

## Other tools

`amber debug`, `amber lsp`, and `amber profile` exist in the binary but are not in the Stable scope. See [Experimental](https://amberjs.com/docs/experimental.md).


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/stability.md

# Stability levels

> How Amber decides what is Stable, Preview, Experimental, or not supported.

HTML: https://amberjs.com/docs/stability · Index for agents: https://amberjs.com/llms.txt

Amber labels every capability. The labels come from [`docs/CURRENT_SCOPE.md`](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md), which is the user-facing source of truth. The [compatibility page](https://amberjs.com/compatibility.md) renders the same data as a searchable table.

## The four levels

**Stable.** The capability is reachable from the `amber` binary, has a contract document in `docs/`, and has an executable test in `tests/` that runs in CI. The contract lists its limits next to the API. As of v1.17.0, 69 contracts are numbered G1 to G69.

Some Stable rows are marked **tentative** or **provisional**. They passed the graduation rule, but their id or edges may still be adjusted. Read the contract before relying on an edge case.

**Preview.** The capability is in the default build and useful, but its contract, diagnostics, or edge cases are still being tightened. Most of `src/nodejs_core/` and `src/web_api/` outside the Stable contracts are Preview.

**Experimental.** Code exists, but it is not a product promise until it is re-verified. This includes some CLI commands, optional Cargo features, and the N-API hello loader.

**Not supported.** Deliberately out of scope today. Where possible, Amber throws or rejects with a clear error instead of returning fake data.

## Graduation rule

A capability moves up only when all of these are true:

1. It is reachable through `src/main.rs` or a documented library API in `src/lib.rs`.
2. Its behavior is described without relying on historical stage reports.
3. Current tests or smoke commands cover the documented behavior.
4. Known limitations are documented next to the capability.
5. Feature-gated work has a passing feature check.

Checklist progress in the planning documents does not promote anything by itself.

## Conformance scorecard

`tests/conformance/` holds Node-style fixtures that run on every CI build. The current scorecard is **56/56 PASS**, and CI fails if fewer than 55 pass or any fixture fails or is skipped.

```bash
cargo build
./tests/conformance/run_conformance.sh
cat tests/conformance/scorecard.md
```

The express, fastify, and hono smoke fixtures need those packages under `benchmarks/idle_memory/node_modules`. Without them they report SKIP and the gate fails. CI installs them first.

Some fixtures exercise framework smoke paths or `http2` basics. A passing fixture is a regression gate. It does not by itself make an API Stable.

## Performance

Amber does not publish a stable performance claim today. Any number must include the date, commit, exact command, build profile, hardware, harness, and correctness checks. Older benchmark tables in the repository are historical.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/node-compat.md

# Node.js compatibility

> Which Node modules are Stable, what each contract covers, and what stays out.

HTML: https://amberjs.com/docs/node-compat · Index for agents: https://amberjs.com/llms.txt

Amber is not a drop-in Node.js replacement. Each module below is Stable only for the methods named in its contract. Everything else in `src/nodejs_core/` is Preview. For a searchable view, use the [compatibility page](https://amberjs.com/compatibility.md).

## Modules and loading

| API | Id | Notes |
| :--- | :--- | :--- |
| CommonJS `require`, `module.exports`, `require.resolve`, `createRequire` | G28 (provisional) | `node_modules` walk, `"exports"` / `"imports"` / `"main"`, JSON, TS, and ESM via `require`. No `require.cache`; resolve errors have no `code`. |
| `node:` and bare builtin names | G28 | Loading a builtin does not make its whole API Stable. |

## File system and paths

| API | Id | Notes |
| :--- | :--- | :--- |
| `fs`, `fs/promises` | G8 | Byte read and write, `mkdir`, `stat`, `copyFile`, `rm`, `realpath`, fds, `chmod`, `access`, `existsSync`, `readdir` dirents, system errors. Async work runs on the isolate thread at the next tick. |
| `fs.watch`, `fs.watchFile` | G64 (tentative) | Real OS watcher and stat polling. No `fs.promises.watch`. |
| `path` | G17 | POSIX semantics. `path.win32` only changes `sep` and `delimiter`. |

`fs.glob`, `fs.cp`, `fs.opendir`, and `fs.statfs` are not implemented.

## Core utilities

| API | Id | Notes |
| :--- | :--- | :--- |
| `events` (`EventEmitter`) | G18 | No `events.on` async iterator. |
| `buffer` / `Buffer` | G19 | `from`, `alloc`, `concat`, `byteLength`, `toString`, `slice`. `compare` and `readUInt*` are outside the pin. |
| `util` | G22, G59 | `format`, shallow `inspect`, `promisify`, `callbackify`, `inherits`, listed `util.types`. |
| `process` | G22, G44, G53, G54 | `nextTick`, `env`, `cwd`, `pid`, `platform`, `stdout.write`, `hrtime`, `memoryUsage`. Heap fields are estimates; `process.on` / `off` are no-ops and not Stable. |
| `os` | G20, G62, G63 | Host info, `hostname`, real `networkInterfaces`. |
| `querystring` | G38 | Fixed `&` and `=` separators. |
| `string_decoder` | G39, G68 | UTF-8 plus latin1, ascii, base64, hex, utf16le. No `base64url`. |
| `assert` | G40, G69 | `ok`, `strictEqual`, `deepStrictEqual`, `throws`, `match`, `rejects`, and a few more. Loose `equal` semantics are not pinned. |
| `timers`, `timers/promises` | G42, G50 | Same functions as the globals; Promise `setTimeout` and `setImmediate` with `AbortSignal`. |
| `tty.isatty` | G49 | Always `false` on Windows today. |
| `vm` | G55, G66 (tentative) | `runInThisContext` and `runInNewContext`. Not full Contextify. |
| `diagnostics_channel` | G56 (tentative) | `channel` pub/sub and `tracingChannel.traceSync`. |
| `async_hooks` | G57 (tentative) | `AsyncResource` and `AsyncLocalStorage`. No `createHook`. |
| `readline` | G46 (tentative) | `question()` on host stdin and stdout only. |

## Crypto and compression

| API | Id | Notes |
| :--- | :--- | :--- |
| `crypto` hashes and random | G23 | `createHash`, `createHmac` (md5, sha1, sha256, sha384, sha512, blake3), `randomBytes`, `randomUUID`, `timingSafeEqual`. Returns `Uint8Array`. |
| `crypto` AES ciphers | G43, G51, G52 | `createCipheriv` / `createDecipheriv` for AES-CBC, AES-GCM, and AES-CTR. |
| `zlib` | G21, G48, G58 | Sync and callback gzip, deflate, and raw deflate. |

KDF, sign and verify, key pairs, `KeyObject`, brotli, and streaming `createGzip` are not Stable.

## Processes and networking

| API | Id | Notes |
| :--- | :--- | :--- |
| `child_process` sync | G25 | `execSync`, `spawnSync`. `pid` is `0`. |
| `child_process` async | G47, G60, G67 | `exec`, `execFile`, `spawn` with captured output, and `fork` with JSON IPC. No live stdio pipes. |
| `http` server | G37 (tentative) | `createServer`, `listen`, buffered responses, keep-alive. |
| `net` server and client | G45, G61 (tentative) | `createServer` listen and accept; `net.connect` client. |
| `dns` | G27, G65 | `lookup`, `resolve*`, `reverse`, `getServers` from the OS resolver. |
| `url` | G26 | POSIX `fileURLToPath` and `pathToFileURL`. Legacy `parse` is outside. |
| `stream` | G24 | `Readable`, `Writable`, `PassThrough`. No `Transform`, `Duplex`, or `pipeline`. |

## Not supported

These fail or reject instead of pretending to work:

- `http.request`, `http.get`, `http.Agent`, the `https` module, and `http2`.
- Streaming `zlib.createGzip` family, brotli, and `zlib.constants`.
- Node native addons beyond the Experimental N-API hello loader.

## Conformance

The Node conformance scorecard in `tests/conformance/` is 56/56 on main. See [Stability levels](https://amberjs.com/docs/stability.md) for what that number does and does not mean.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/web-apis.md

# Web APIs

> The Web-platform globals Amber pins with contracts, and the ones it deliberately leaves out.

HTML: https://amberjs.com/docs/web-apis · Index for agents: https://amberjs.com/llms.txt

Each row below is Stable only for its contract. The rest of `src/web_api/` is Preview. There is no document, DOM tree, or browser origin in Amber, so several APIs behave like their server-side cousins rather than the browser versions.

## Networking

| API | Id | Notes |
| :--- | :--- | :--- |
| `fetch`, `Request`, `Response`, `Headers` | G9 | Streaming body reader, redirect modes, `AbortSignal`, `integrity`. `text()` and `json()` are synchronous. `response.body` is not a `ReadableStream` instance. |
| `WebSocket` client | G15 | `ws://` handshake, text and binary frames. No subprotocols or `permessage-deflate`. Not a server. |

## Data and encoding

| API | Id | Notes |
| :--- | :--- | :--- |
| `URL`, `URLSearchParams` | G10 | No IDNA. |
| `TextEncoder`, `TextDecoder` | G10 | UTF-8 only. |
| `structuredClone` | G10 | The types in the contract, including `ArrayBuffer` transfer. |
| `atob`, `btoa` | G29 | Throws `Error`, not `DOMException`. |
| `Blob`, `File`, `FormData` | G11 | `text()` and `arrayBuffer()` return values, not Promises. |
| `crypto.subtle`, `crypto.randomUUID`, `getRandomValues` | G14 | SHA, HMAC, AES, PBKDF2, ECDH, Ed25519, ECDSA, RSA. No HKDF, RSA-PSS, or X25519. |
| `DOMParser` | G32 | Read-only parse tree for HTML and XML. Not a live DOM. |

## Events, streams, and timers

| API | Id | Notes |
| :--- | :--- | :--- |
| `Event`, `EventTarget`, `CustomEvent`, `AbortController` | G12 | No tree, so propagation does not cross parents. |
| `MessageChannel`, `BroadcastChannel` | G12 | Same-isolate delivery. |
| `ErrorEvent`, global `onerror` | G30 (provisional) | Constructed events are not `instanceof Event`. |
| `ReadableStream`, `WritableStream`, `TransformStream` | G13 | No backpressure from queuing strategies. |
| `CompressionStream`, `DecompressionStream` | G13 | gzip, deflate, deflate-raw; one member per `write`. |
| `setTimeout`, `setInterval`, `queueMicrotask`, `performance` | G13 | `now`, `mark`, `measure`. |

## Workers and service workers

| API | Id | Notes |
| :--- | :--- | :--- |
| Dedicated `Worker`, `worker_threads` | G16 | One thread and isolate per worker. Messages are JSON. |
| `navigator.serviceWorker.register` | G16 | Install and activate lifecycle, `clients.claim()`. |
| Service-worker `fetch` interception | G35 | `FetchEvent.respondWith` from an activated worker. |
| `caches` (Cache Storage) | G34 | In-process memory store. Not an HTTP cache and not persistent. |
| Background Sync | G33 | Fires on the same isolate. Not Periodic Sync. |
| `navigator.clipboard.writeText` / `readText` | G31 | Process-local string, not the OS clipboard. |

## WinterTC baseline

`DOMException`, `URLPattern`, `navigator`, queuing strategies, `ReadableStream.from`, `amber:sockets`, `wintercg` / `wintertc` export conditions, and `import.meta.main` / `env` / `resolve` are part of the Stable scope. See [WinterTC](https://amberjs.com/docs/wintertc-compliance.md).

## Not supported

- `SharedWorker` and module workers (`{ type: "module" }` throws).
- Push subscriptions, `Notification`, and the Payment Request API.
- `ClipboardItem` read and write (rejects with an error naming `ClipboardItem`).
- `CacheStorage.match`, `matchAll`, and the `ignore*` options.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/wintertc-compliance.md

# WinterTC baseline

> ECMA-429 minimum common Web API, runtime keys, and the Sockets API.

HTML: https://amberjs.com/docs/wintertc-compliance · Index for agents: https://amberjs.com/llms.txt

Amber implements the WinterTC (Ecma TC55, formerly WinterCG) baseline so Web-platform code written for edge runtimes can run unchanged where the APIs overlap. This baseline is part of the Stable scope in `CURRENT_SCOPE.md`.

## ECMA-429 minimum common Web API

| API | Behavior |
| :--- | :--- |
| `DOMException` | Global constructor with `name`, `message`, `code`, and legacy constants |
| `globalThis.self` | Alias of `globalThis` |
| `reportError(error)` | Calls `onerror` when set |
| `PromiseRejectionEvent` | Dispatched on unhandled rejections through `onunhandledrejection` |
| `navigator.userAgent` | `Amber/<version>` |
| `navigator.hardwareConcurrency`, `language`, `platform` | Present |
| `URLPattern` | `test()` and `exec()` with `:param` groups |
| `ByteLengthQueuingStrategy`, `CountQueuingStrategy` | Global constructors |
| `ReadableStream.from` | Iterable and async-iterable sources |

## Runtime keys

`package.json` `"exports"` conditions include `wintercg` and `wintertc` ahead of `node`. `import.meta.resolve` uses the same resolver, so a package that publishes `"wintercg": "./winter.js"` resolves to that file instead of its `"node"` entry.

`import.meta.main` is `true` for the CLI entry module. `import.meta.env` maps process environment variables.

## Sockets API

```js
const { connect } = require("amber:sockets");

const socket = connect(
  { hostname: "example.com", port: 443 },
  { secureTransport: "on" },
);
// socket.readable and socket.writable are Web streams.
```

`secureTransport: "on"` and `socket.startTls()` run a real rustls client handshake. Connecting with TLS to a plain TCP port fails with a TLS error instead of silently staying in cleartext.

## Tests

```bash
cargo test --test wintertc_compliance_tests -- --test-threads=1
```


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/agent-sandbox.md

# Agent sandbox

> Run tool code with file, network, environment, and process access denied unless you allow it.

HTML: https://amberjs.com/docs/agent-sandbox · Index for agents: https://amberjs.com/llms.txt

The permission sandbox, the JSONL audit log, and deterministic time and randomness are **Stable**. They are the safety layer for running code that an agent or model wrote.

## Deny by default

```bash
amber run --sandbox tool.js
```

Under `--sandbox`, JavaScript cannot read or write files, open network connections or listeners, read environment variables, or start child processes. A denied call throws an error that contains `permission denied` before the operation runs. The entry file itself can still be read.

## Allow exactly what you need

```bash
amber run --sandbox \
  --allow-read ./data/input.txt \
  --allow-write ./out/result.json \
  --allow-net api.example.com \
  --allow-env API_TOKEN \
  --allow-run git \
  tool.js
```

Each `--allow-*` flag is repeatable and matches an exact path, host or URL, variable name, or command name. `--allow-listen` does the same for servers.

To deny one capability without the full sandbox, use `--deny-fs`, `--deny-net`, `--deny-env`, or `--deny-run`.

## Policy files

Put the same rules in JSON and pass `--permission-policy` (alias `--policy`):

```json
{
  "permissions": {
    "deny_fs": true,
    "deny_net": true,
    "allow_read": ["./data/input.txt"],
    "allow_net": ["api.example.com"]
  }
}
```

```bash
amber run --permission-policy policy.json tool.js
```

## Audit log

```bash
amber run --sandbox --allow-read ./data --audit-log audit.jsonl tool.js
```

Each permission decision is appended as one JSON line with its kind, action, resource, and decision. Nothing else from your program is written to the log.

## Deterministic runs

```bash
amber run --seed 42 --freeze-time 2026-01-01T00:00:00Z agent.js
```

- `--seed` makes `Math.random()`, `crypto.getRandomValues()`, and `crypto.randomBytes()` reproducible.
- `--freeze-time` pins `Date.now()`, `new Date()`, and `performance.now()` to a fixed timestamp or ISO 8601 string.

## Resource limits

```bash
amber run --timeout 5000 --max-memory 256 tool.js
```

`--timeout` stops a script after that many milliseconds. `--max-memory` caps the isolate heap in megabytes.

## What this is not

The sandbox is a permission broker inside one process. It is not an OS-level jail, a container, or a seccomp profile. Run untrusted code in a container or VM as well if the threat model needs it.

The `--virtual-fs` flag and the `amber:security` module exist in the binary but are not in the Stable scope. See [Experimental](https://amberjs.com/docs/experimental.md).


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/mcp-protocol.md

# Tools, sessions, and MCP

> Export functions from a file, then call them through a JSON-RPC session or an MCP stdio server.

HTML: https://amberjs.com/docs/mcp-protocol · Index for agents: https://amberjs.com/llms.txt

`amber run --export-tools` (G4), `amber session`, and `amber mcp` are **Stable**. Models stay outside Amber: these commands only load a tool file and call its exports under the same runtime and permission broker as `amber run`.

## A tool file

```ts
// tools.ts

/** Add two numbers. */
export function add({ a, b }: { a: number; b: number }) {
  return a + b;
}

/** Read a UTF-8 file. */
export function readText({ path }: { path: string }) {
  return require("node:fs").readFileSync(path, "utf8");
}
```

## Export schemas

```bash
amber run --export-tools tools.ts
```

```json
{"tools":[{"name":"add","description":"Add two numbers.","inputSchema":{"type":"object"}}, ...]}
```

The command prints JSON and exits. It does not run the file or call a model. Contract: [`EXPORT_TOOLS_CONTRACT.md`](https://github.com/zh30/amberjs/blob/main/docs/EXPORT_TOOLS_CONTRACT.md).

Limits:

- Only lines that start with `export function` or `export async function` are listed. `export const`, arrow functions, and `export default` are not.
- The description comes from the nearby `//` or `/** */` comment, with `@` tags dropped.
- `inputSchema` is always `{"type":"object"}`. TypeScript types and `@param` tags are not turned into JSON Schema.
- A sibling `tools.json` replaces source scanning entirely.

## JSON-RPC session

```bash
amber session --sandbox --allow-read ./data tools.ts
```

`amber session` reads one JSON-RPC request per line on stdin and writes one response per line on stdout.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add","arguments":{"a":2,"b":3}}}
```

It also answers `initialize`, `ping`, and empty `prompts/list` and `resources/list`. Tool errors return code `-32000`; unknown methods return `-32601`.

## MCP stdio server

```bash
amber mcp tools.ts
amber mcp --inspect tools.ts   # list the tools and exit
```

`amber mcp` speaks MCP protocol version `2024-11-05` with `initialize`, `tools/list`, and `tools/call`. Tool results come back as one text content item, with `isError` set on failure.

Messages are framed with `Content-Length` headers in both directions, the way LSP frames messages. If your MCP host only speaks newline-delimited JSON over stdio, check that it can talk to this framing before you wire it up.

Pass `--isolate-per-call` to `session` or `mcp` to give every `tools/call` a fresh isolate.

## Combine with the sandbox

Every permission flag works here too. This is the intended pattern for agent hosts:

```bash
amber mcp --sandbox --allow-read ./workspace --audit-log audit.jsonl tools.ts
```

## The `amber:mcp` module

A JavaScript `McpServer` API is also present as `amber:mcp`. It is not in the Stable scope, so treat it as Experimental. The Stable surface is the CLI described above.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/ai-engine.md

# amber:ai

> Typed-array tensors, a built-in text embedding, and an LLM interface for local model files.

HTML: https://amberjs.com/docs/ai-engine · Index for agents: https://amberjs.com/llms.txt

`amber:ai` is in the Stable scope and compiles in the default build. It does not need the `ai` Cargo feature, which is empty. Read the notes on `LLM` below before building on it.

```js
const { Tensor, LLM, AgentPipeline, embed, cosineSimilarity } = require("amber:ai");
```

## Tensor

`Tensor` wraps a `Float32Array` and a shape. Operations do not copy the backing buffer when they can avoid it.

```js
const a = new Tensor([1, 2, 3, 4], [2, 2]);
const b = new Tensor([5, 6, 7, 8], [2, 2]);

a.matmul(b).toArray(); // [[19, 22], [43, 50]]

const v1 = new Tensor([1, 2, 3]);
const v2 = new Tensor([4, 5, 6]);
v1.dot(v2);              // 32
v1.norm();               // 3.7416...
v1.cosineSimilarity(v2); // 0.9746...
new Tensor([2, 1, 0.1]).softmax().toArray();
```

## Embeddings

```js
const vector = embed("hello world");          // Float32Array, 64 dims by default
const other = embed("hello there", { dimensions: 128 });
```

`embed` is a deterministic, hashed-token embedding computed in Rust. It is fast and reproducible, but it is **not** a learned semantic model. Use it for tests, deduplication, or rough lexical similarity. For semantic search, load a real embedding model and feed its output into `Tensor`.

## LLM

```js
const llm = await LLM.load("./models/model.gguf");
const result = await llm.generate("Summarize this file.");

for await (const chunk of llm.generateStream("Write a haiku.")) {
  process.stdout.write(chunk);
}
```

When `LLM.load` can open the model file, generation runs locally through Candle. The default build runs on the CPU. CUDA and Metal need a source build with the `cuda` or `metal` Cargo feature, and those features are not CI-gated.

**Important:** when the model cannot be loaded, `LLM.load` does not throw. It returns an `LLM` backed by a built-in template generator that produces placeholder text, and placeholder JSON when you pass a schema. That output is not model output. Check that your model path loads before you trust a result.

## AgentPipeline

```js
const pipeline = new AgentPipeline({
  model: llm,
  tools: [{ name: "echo", execute: (input) => input }],
});

const step = await pipeline.step("hello");
// { status: "completed", output: "...", historyLength: 2 }
```

`AgentPipeline` records history and holds registered tools. `step()` sends the input to `model.generate()` and stores the reply. It does not plan or call tools by itself; your code decides when to call `tool.execute`.

## Not in scope

The getters `weights`, `tools`, `kv`, `bus`, `grammar`, and `checkpoint` on `amber:ai` point to modules that are not classified in the scope page. Treat them as Experimental.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/wasm-interop.md

# WebAssembly

> Standard WebAssembly on V8, Stable streaming compilation, and the Preview amber:wasm zero-copy helpers.

HTML: https://amberjs.com/docs/wasm-interop · Index for agents: https://amberjs.com/llms.txt

## Standard WebAssembly

V8 compiles and runs WebAssembly. The standard JavaScript API works as usual:

```js
const bytes = require("node:fs").readFileSync("add.wasm");
const { instance } = await WebAssembly.instantiate(bytes, {});
instance.exports.add(1, 2);
```

`WebAssembly.compileStreaming` and `WebAssembly.instantiateStreaming` are **Stable**. They accept a `Response` or a `Promise<Response>` and consume the body without routing it through a string.

```js
const { instance } = await WebAssembly.instantiateStreaming(fetch("https://example.com/add.wasm"));
```

## amber:wasm (Preview)

`amber:wasm` adds host helpers so JavaScript and WebAssembly can share a backing store instead of copying buffers:

- `WebAssembly.Memory.buffer` can share pages with a V8 `ArrayBuffer`.
- Large `.wasm` files are memory-mapped on load instead of copied into the isolate first.

```js
const wasm = require("amber:wasm");

const memory = new WebAssembly.Memory({ initial: 1 });
const shared = wasm.shareMemory(memory);

shared.uint8[0] = 77;      // writes straight into linear memory
shared.float32[1] = 3.14;  // bytes 4..8
shared.ptr;                // bigint host address of linear memory

memory.asUint8Array(0, 1)[0]; // 77
```

This module is **Preview**. Its API may change, and it is covered by `tests/wasm_zero_copy_tests.rs` rather than a Stable contract. The FFI pointer helpers and `Tensor` views on the same module are Preview too.

## Not claimed

- A custom Wasm compiler or JIT. V8 does the work.
- WASI. There is no drop-in WASI host.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)

---

URL: https://amberjs.com/docs/experimental.md

# Experimental surfaces

> Commands, flags, and modules that ship in the binary but are not product promises yet.

HTML: https://amberjs.com/docs/experimental · Index for agents: https://amberjs.com/llms.txt

The `amber` binary contains more than the Stable scope. This page lists what else is there, so nothing is hidden. None of it is promised. Each item needs fresh verification before it can graduate under the [graduation rule](https://amberjs.com/docs/stability.md).

## Classified as Experimental

These are listed as Experimental in `CURRENT_SCOPE.md`:

| Surface | Notes |
| :--- | :--- |
| `amber debug` | Older debug entry. Prefer `amber run --inspect`. |
| `amber init`, `amber create` | Project scaffolding |
| `amber add`, `amber remove`, `amber prune`, `amber upgrade` | Package edits outside the `amber install` contract |
| `amber x` (`dlx`, `bunx`) | Run a package binary without installing |
| `amber test --parallel` | Rejected with exit code 2 |
| N-API hello loader | `process.dlopen` can load a C hello addon. Not a Node ABI commitment; Prisma and sharp are out of scope. |
| Optional Cargo features | `benchmarks` and `observability` compile in CI. `cloudnative`, `enterprise`, and `multilang` are not CI-gated. The `tch` feature is not in this tree (it pulled unpatched `zip` 0.6). The `ai` feature is empty. |
| Homebrew, GHCR, winget | Distribution channels. The GHCR image is linux/amd64 only; the winget manifest is not submitted. |

## Present but not classified

These exist in `src/main.rs` or as `amber:*` modules, but the scope page does not classify them. This manual treats them as Experimental:

| Surface | What it claims to do |
| :--- | :--- |
| `amber fmt`, `amber lint` | Format and lint JS and TS files |
| `amber bench` | Run microbenchmarks |
| `amber task` | Run a `package.json` script |
| `amber types` | Print type definitions for Amber built-ins |
| `amber lsp` | Language Server Protocol server |
| `amber profile` | Write a `.cpuprofile` |
| `amber deploy` | Generate Docker, standalone, or Kubernetes scaffolding |
| `amber record`, `amber replay` | Record and replay an execution trace |
| `--import-map` | Remap bare specifiers from a JSON import map |
| `--virtual-fs` | In-memory filesystem overlay |
| `amber:mcp` | JavaScript `McpServer` API |
| `amber:kv`, `amber:db`, `amber:vector` | Embedded storage helpers |
| `amber:bus`, `amber:grammar`, `amber:checkpoint`, `amber:weights`, `amber:tools` | Agent helper modules |
| `amber:security`, `amber:std`, `amber:pool`, `amber:ffi` | Assorted host modules |

Earlier versions of this site documented several of these as finished features, often with speed claims. Those pages were removed in the v1.17 docs rewrite because the claims were never re-verified. Old links redirect here.

## Want one of these to graduate?

Open an issue at [github.com/zh30/amberjs/issues](https://github.com/zh30/amberjs/issues) with your use case. Graduation needs a written contract, executable tests in CI, and documented limits.


---

Status labels and limits: [Compatibility](https://amberjs.com/compatibility.md) · [Docs index](https://amberjs.com/docs.md) · [Overview](https://amberjs.com/index.md)