docs: improve README with Node.js quick start, package guide, and missing wrapper READMEs

- Add "Choosing a package" decision guide for Node.js developers
- Add Node.js quick start example showing drop-in migration
- Reorder package table: drop-in replacements first, then core WASM, then NAPI
- Add missing scopes CLI command to CLI section
- Rename "Internals" to "Why srcmap is fast" with clearer framing
- Create READMEs for @srcmap/gen-mapping, @srcmap/source-map, and @srcmap/remapping
  with full API compatibility tables, usage examples, and migration guides

Author: BartWaardenburg

README.md

@@ -206,16 +206,39 @@ Run `cd benchmarks && npm run download-fixtures && npm run bench:real-world` to
 
 srcmap ships WASM and NAPI bindings for use in Node.js — useful for symbolication services, error monitoring, and bulk source map operations.
 
+### Choosing a package
+
+- **Consuming source maps?** → [`@srcmap/trace-mapping`](https://www.npmjs.com/package/@srcmap/trace-mapping) (drop-in for `@jridgewell/trace-mapping`)
+- **Generating source maps?** → [`@srcmap/gen-mapping`](https://www.npmjs.com/package/@srcmap/gen-mapping) (drop-in for `@jridgewell/gen-mapping`)
+- **Using Mozilla's API?** → [`@srcmap/source-map`](https://www.npmjs.com/package/@srcmap/source-map) (drop-in for `source-map` v0.6)
+- **Composing/remapping?** → [`@srcmap/remapping`](https://www.npmjs.com/package/@srcmap/remapping) (drop-in for `@ampproject/remapping`)
+- **Batch lookups or low-level control?** → [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) (raw WASM API, fastest for bulk ops)
+
+### Quick start (Node.js)
+
+```js
+// Swap the import — the rest of your code stays the same
+import { TraceMap, originalPositionFor } from '@srcmap/trace-mapping'
+
+const map = new TraceMap(sourceMapJsonOrObject)
+const pos = originalPositionFor(map, { line: 43, column: 10 })
+// { source: 'src/app.ts', line: 11, column: 4, name: 'handleClick' }
+
+map.free() // Release WASM memory (or use `using` with Symbol.dispose)
+```
+
+### All packages
+
 | Package | Description |
 |---|---|
-| [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) | Parser + consumer (WASM) |
-| [`@srcmap/generator-wasm`](https://www.npmjs.com/package/@srcmap/generator-wasm) | Source map builder (WASM) |
-| [`@srcmap/remapping-wasm`](https://www.npmjs.com/package/@srcmap/remapping-wasm) | Concatenation + composition (WASM) |
-| [`@srcmap/symbolicate-wasm`](https://www.npmjs.com/package/@srcmap/symbolicate-wasm) | Stack trace symbolication (WASM) |
 | [`@srcmap/trace-mapping`](https://www.npmjs.com/package/@srcmap/trace-mapping) | Drop-in for `@jridgewell/trace-mapping` (WASM) |
 | [`@srcmap/gen-mapping`](https://www.npmjs.com/package/@srcmap/gen-mapping) | Drop-in for `@jridgewell/gen-mapping` (WASM) |
 | [`@srcmap/source-map`](https://www.npmjs.com/package/@srcmap/source-map) | Drop-in for Mozilla `source-map` v0.6 (WASM) |
 | [`@srcmap/remapping`](https://www.npmjs.com/package/@srcmap/remapping) | Drop-in for `@ampproject/remapping` (WASM) |
+| [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) | Parser + consumer (WASM) |
+| [`@srcmap/generator-wasm`](https://www.npmjs.com/package/@srcmap/generator-wasm) | Source map builder (WASM) |
+| [`@srcmap/remapping-wasm`](https://www.npmjs.com/package/@srcmap/remapping-wasm) | Concatenation + composition (WASM) |
+| [`@srcmap/symbolicate-wasm`](https://www.npmjs.com/package/@srcmap/symbolicate-wasm) | Stack trace symbolication (WASM) |
 | [`@srcmap/sourcemap`](https://www.npmjs.com/package/@srcmap/sourcemap) | Parser + consumer (NAPI) |
 | [`@srcmap/codec`](https://www.npmjs.com/package/@srcmap/codec) | VLQ codec (NAPI) |
 
@@ -234,18 +257,19 @@ srcmap encode mappings.json --json          # Encode back to VLQ
 srcmap concat a.js.map b.js.map -o bundle.js.map              # Concatenate
 srcmap remap minified.js.map --dir ./maps -o composed.js.map  # Compose
 srcmap symbolicate stack.txt --dir ./maps --json               # Symbolicate
+srcmap scopes bundle.js.map --json          # Inspect ECMA-426 scopes & bindings
 srcmap schema                               # All commands as JSON (for agents)
 ```
 
 All commands support `--json` for structured output.
 
-## Internals
+## Why srcmap is fast
 
-- **Flat Mapping struct** — 28 bytes (6 × u32 + bool), cache-friendly contiguous layout
-- **Inlined VLQ decoder** — single-char fast path for values −15..15 (~85% of real-world VLQ values)
+- **Cache-friendly layout** — 28-byte flat Mapping struct in contiguous memory (6 × u32 + bool)
+- **Single-char VLQ fast path** — ~85% of real-world values decode in one operation
 - **Lazy reverse index** — only built on first `generated_position_for` call
-- **Binary search lookups** — O(log n) for both forward and reverse queries
-- **Borrowed deserialization** — `mappings` string borrowed from JSON input (zero-copy)
+- **Binary search** — O(log n) for both forward and reverse lookups
+- **Zero-copy parsing** — `mappings` string borrowed directly from JSON input
 - **Pre-counted capacity** — segment and line counts estimated before allocation
 
 ## Development

packages/gen-mapping/README.md

@@ -0,0 +1,77 @@
+# @srcmap/gen-mapping
+
+[![npm](https://img.shields.io/npm/v/@srcmap/gen-mapping.svg)](https://www.npmjs.com/package/@srcmap/gen-mapping)
+[![CI](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml)
+
+Drop-in replacement for [`@jridgewell/gen-mapping`](https://github.com/jridgewell/gen-mapping) powered by Rust via WebAssembly.
+
+Same API, same types, same behavior. Swap the import and get source map generation backed by Rust under the hood.
+
+## Install
+
+```bash
+npm install @srcmap/gen-mapping
+```
+
+## Usage
+
+```js
+// Before:
+// import { GenMapping, addMapping, toEncodedMap } from '@jridgewell/gen-mapping'
+
+// After:
+import { GenMapping, addMapping, toEncodedMap } from '@srcmap/gen-mapping'
+
+const map = new GenMapping({ file: 'bundle.js' })
+
+addMapping(map, {
+  generated: { line: 1, column: 0 },
+  source: 'src/app.ts',
+  original: { line: 10, column: 4 },
+  name: 'handleClick',
+  content: 'const handleClick = () => { ... }',
+})
+
+const encoded = toEncodedMap(map)
+
+// Cleanup WASM memory (optional, also via `using` with Symbol.dispose)
+map.free()
+```
+
+## API compatibility
+
+All exports from `@jridgewell/gen-mapping` are supported:
+
+| Export | Description |
+|--------|-------------|
+| `GenMapping` | Main class — creates a new source map builder |
+| `addMapping(map, mapping)` | Add a mapping (1-based lines, 0-based columns) |
+| `maybeAddMapping(map, mapping)` | Add only if it differs from the previous mapping on the same line |
+| `setSourceContent(map, source, content)` | Set source content for a source file |
+| `setIgnore(map, source, ignore?)` | Mark a source as ignored |
+| `toEncodedMap(map)` | Return as encoded source map (VLQ string mappings) |
+| `toDecodedMap(map)` | Return as decoded source map (array mappings) |
+| `allMappings(map)` | Return all mappings as `Mapping[]` |
+| `fromMap(input)` | Construct from an existing source map |
+
+### Line/column convention
+
+Follows `@jridgewell/gen-mapping` conventions:
+- `addMapping` / `maybeAddMapping`: **1-based lines**, 0-based columns
+- Decoded mappings output: **0-based lines**, 0-based columns
+
+## Differences from @jridgewell/gen-mapping
+
+- **WASM memory**: Call `map.free()` when done, or use `using map = new GenMapping(...)` with `Symbol.dispose`
+- **VLQ encoding runs in WASM**: No JS-side encoding overhead
+
+## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)
+
+High-performance source map tooling written in Rust. See also:
+- [`@srcmap/trace-mapping`](https://www.npmjs.com/package/@srcmap/trace-mapping) - Drop-in for `@jridgewell/trace-mapping` (consumer)
+- [`@srcmap/remapping`](https://www.npmjs.com/package/@srcmap/remapping) - Drop-in for `@ampproject/remapping` (composition)
+- [`@srcmap/generator-wasm`](https://www.npmjs.com/package/@srcmap/generator-wasm) - Lower-level WASM generator API
+
+## License
+
+MIT

packages/remapping/README.md

@@ -0,0 +1,92 @@
+# @srcmap/remapping
+
+[![npm](https://img.shields.io/npm/v/@srcmap/remapping.svg)](https://www.npmjs.com/package/@srcmap/remapping)
+[![CI](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml)
+
+Drop-in replacement for [`@jridgewell/remapping`](https://github.com/jridgewell/remapping) and [`@ampproject/remapping`](https://github.com/nicolo-ribaudo/remapping) powered by Rust via WebAssembly.
+
+Same API, same types, same behavior. Swap the import and get source map composition backed by Rust under the hood.
+
+## Install
+
+```bash
+npm install @srcmap/remapping
+```
+
+## Usage
+
+```js
+// Before:
+// import remapping from '@jridgewell/remapping'
+// import remapping from '@ampproject/remapping'
+
+// After:
+import remapping from '@srcmap/remapping'
+
+// Remap a single source map through a loader
+const composed = remapping(minifiedMap, (sourcefile) => {
+  // Return the upstream source map for this file, or null
+  return upstreamMaps[sourcefile] ?? null
+})
+
+console.log(composed.sources)    // Original sources
+console.log(composed.mappings)   // Composed VLQ mappings
+console.log(composed.toString()) // JSON string
+```
+
+### Compose an array of source maps
+
+```js
+// When you have the full chain: [minified map, intermediate map, original map]
+const composed = remapping([minifiedMap, intermediateMap], (sourcefile) => {
+  return upstreamMaps[sourcefile] ?? null
+})
+```
+
+### Options
+
+```js
+const composed = remapping(minifiedMap, loader, {
+  excludeContent: true, // Omit sourcesContent from the output
+})
+```
+
+## API compatibility
+
+| Export | Description |
+|--------|-------------|
+| `remapping(input, loader, options?)` | Remap a single source map through a loader |
+| `remapping(inputs[], loader, options?)` | Compose an array of source maps |
+| `SourceMap` | Result class with `version`, `file`, `mappings`, `sources`, `sourcesContent`, `names`, `ignoreList` |
+
+The `loader` function receives a source filename and should return the upstream source map (as a JSON string, parsed object, or decoded source map), or `null` if no upstream map exists.
+
+### SourceMap result
+
+| Property / Method | Type | Description |
+|--------|------|-------------|
+| `version` | `number` | Source map version (always 3) |
+| `file` | `string \| undefined` | Output filename |
+| `mappings` | `string` | VLQ-encoded mappings |
+| `sources` | `(string \| null)[]` | Source filenames |
+| `sourcesContent` | `(string \| null)[] \| undefined` | Inline source contents |
+| `names` | `string[]` | Name strings |
+| `ignoreList` | `number[] \| undefined` | Indices of ignored sources |
+| `toString()` | `string` | Serialize as JSON string |
+| `toJSON()` | `RawSourceMap` | Return as parsed object |
+
+## Differences from @jridgewell/remapping
+
+- **WASM-powered**: Composition runs in Rust via WebAssembly
+- **Indexed source maps**: Handled natively (no JS-side flattening)
+
+## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)
+
+High-performance source map tooling written in Rust. See also:
+- [`@srcmap/trace-mapping`](https://www.npmjs.com/package/@srcmap/trace-mapping) - Drop-in for `@jridgewell/trace-mapping` (consumer)
+- [`@srcmap/gen-mapping`](https://www.npmjs.com/package/@srcmap/gen-mapping) - Drop-in for `@jridgewell/gen-mapping` (generator)
+- [`@srcmap/remapping-wasm`](https://www.npmjs.com/package/@srcmap/remapping-wasm) - Lower-level WASM remapping API
+
+## License
+
+MIT

packages/source-map/README.md

@@ -0,0 +1,107 @@
+# @srcmap/source-map
+
+[![npm](https://img.shields.io/npm/v/@srcmap/source-map.svg)](https://www.npmjs.com/package/@srcmap/source-map)
+[![CI](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml)
+
+Drop-in replacement for [Mozilla's `source-map`](https://github.com/nicolo-ribaudo/source-map-js) v0.6 API powered by Rust via WebAssembly.
+
+Same `SourceMapConsumer` and `SourceMapGenerator` classes, same behavior. Swap the import and get source map operations backed by Rust under the hood.
+
+## Install
+
+```bash
+npm install @srcmap/source-map
+```
+
+## Usage
+
+### Consumer
+
+```js
+// Before:
+// import { SourceMapConsumer } from 'source-map'
+
+// After:
+import { SourceMapConsumer } from '@srcmap/source-map'
+
+const consumer = new SourceMapConsumer(sourceMapJsonOrObject)
+
+const pos = consumer.originalPositionFor({ line: 43, column: 10 })
+// { source: 'src/app.ts', line: 11, column: 4, name: 'handleClick' }
+
+const content = consumer.sourceContentFor('src/app.ts')
+
+consumer.eachMapping((mapping) => {
+  console.log(mapping.generatedLine, mapping.generatedColumn)
+})
+
+// Cleanup WASM memory
+consumer.destroy()
+```
+
+### Generator
+
+```js
+import { SourceMapGenerator } from '@srcmap/source-map'
+
+const generator = new SourceMapGenerator({ file: 'bundle.js' })
+
+generator.addMapping({
+  generated: { line: 1, column: 0 },
+  source: 'src/app.ts',
+  original: { line: 10, column: 4 },
+  name: 'handleClick',
+})
+
+generator.setSourceContent('src/app.ts', sourceCode)
+
+const json = generator.toJSON()
+const str = generator.toString()
+
+generator.destroy()
+```
+
+## API compatibility
+
+### SourceMapConsumer
+
+| Method / Property | Description |
+|--------|-------------|
+| `originalPositionFor(needle)` | Forward lookup (1-based lines, 0-based columns) |
+| `generatedPositionFor(needle)` | Reverse lookup |
+| `eachMapping(callback)` | Iterate all mappings in generated order |
+| `sourceContentFor(source)` | Get source content for a file |
+| `sources` | Resolved source file URLs |
+| `sourcesContent` | Inline source contents |
+| `file` | Output filename |
+| `sourceRoot` | Source root prefix |
+| `destroy()` | Free WASM resources |
+| `GREATEST_LOWER_BOUND` / `LEAST_UPPER_BOUND` | Search bias constants |
+
+### SourceMapGenerator
+
+| Method | Description |
+|--------|-------------|
+| `addMapping(mapping)` | Add a mapping (object-based API) |
+| `setSourceContent(source, content)` | Set source content for a file |
+| `applySourceMap(consumer, source?, path?)` | Apply a consumer's mappings to this generator |
+| `toJSON()` | Return as parsed source map object |
+| `toString()` | Return as JSON string |
+| `destroy()` | Free WASM resources |
+
+## Differences from Mozilla source-map
+
+- **Synchronous API**: No `SourceMapConsumer.with()` or promise-based initialization — construction is synchronous
+- **WASM memory**: Call `consumer.destroy()` / `generator.destroy()` when done to free WASM memory
+- **Indexed source maps**: Handled natively by the WASM engine
+
+## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)
+
+High-performance source map tooling written in Rust. See also:
+- [`@srcmap/trace-mapping`](https://www.npmjs.com/package/@srcmap/trace-mapping) - Drop-in for `@jridgewell/trace-mapping`
+- [`@srcmap/gen-mapping`](https://www.npmjs.com/package/@srcmap/gen-mapping) - Drop-in for `@jridgewell/gen-mapping`
+- [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) - Lower-level WASM API (0-based lines)
+
+## License
+
+MIT