@markup-carve/carve-wasm 0.1.2 → 0.1.4

package/README.md

@@ -27,9 +27,29 @@ import policy and canonical writer as carve-rs. Modes are `safe` (default),
 const { value, report } = htmlToCarve('<p>Hello <strong>world</strong></p>', 'safe')
 ```
 
+`htmlToAst(html, mode)` is the same importer returning the TREE instead of the
+source, so a host that wants a tree does not re-parse what the importer just
+wrote. It returns the same `{ value, report }` shape, with `value` holding AST
+JSON.
+
+```js
+const { value, report } = htmlToAst('<p>Hello <b>world</b></p>', 'safe')
+astJsonToHtml(value)
+```
+
+> **The report is not always identical, and the difference is the point.**
+> A loss only a WRITER takes is not reported by `htmlToAst`, because no writer
+> ran (PART 12 §16). A `<figure>` wrapping a table, or a table with an explicit
+> head/body/foot grouping, has no Carve spelling: `htmlToCarve` reports
+> `structure-unspellable` for it and `htmlToAst` does not, because the tree
+> keeps the thing the source would have lost.
+
 Portable migration code can use `fromHtml(html, mode)` and
-`fromMarkdown(markdown)`. Both return `{ value, report }`; Markdown carries an
-empty diagnostics list because the engine migrates the document whole.
+`fromMarkdown(markdown)`. Both return `{ value, report }`. Version 2 reports use
+the shared fidelity vocabulary. Markdown, Djot, and BBCode conservatively emit
+`fidelity-unverified` as `dropped` / `fallback` until their importers expose
+construct-level outcomes; an empty diagnostic list is therefore never used to
+imply fidelity that was not assessed.
 
 ### Core renderer
 
@@ -42,12 +62,27 @@ call.
 ```js
 import { toHtml } from '@markup-carve/carve-wasm'
 
-// The other core targets are toMarkdown, toPlainText, toAnsi, and toCarve.
+// The other core targets are toMarkdown, toPlainText, toAnsi, and toCarve,
+// each with a *WithOptions form that takes the options object below.
 
 const html = toHtml('# Hello, Carve!')
 document.body.innerHTML = html
 ```
 
+### Source-preserving patches
+
+Tools can prepare canonical formatting as stale-safe UTF-8 byte edits:
+
+```js
+const patch = toCarvePatch(source)
+const formatted = applySourcePatch(source, patch)
+```
+
+`createSourcePatch(source, replacement, kind, code)` prepares the same wire
+shape for another complete replacement. Its ranges are UTF-8 byte offsets. The
+fingerprint and byte length catch accidental staleness; they are not a
+cryptographic signature. Treat a patch as trusted edit instructions.
+
 ### Extensions
 
 `extensions()` reports every extension this build accepts. The list comes from
@@ -151,12 +186,17 @@ defaults, so the three shorthands above remain the zero-config forms.
 | `smartTypography` | `glyph` | `source` keeps the author's run instead of the glyph |
 | `lowercaseHeadingIds` | `false` | Lowercase the generated heading ids |
 | `asciiHeadingIds` | `off` | `fold` transliterates, `strict` guarantees ASCII |
+| `mentionUrl` | none | URL template for `@mention`; `{name}` / `{user}` take the encoded name |
+| `tagUrl` | none | URL template for `#tag`; `{name}` takes the encoded name |
 
 An unrecognized key is ignored, because the object is configuration and a typo
 should not break a render. A recognized key with the wrong type throws a
 `TypeError` instead of being coerced: JS truthiness would read
 `{ sections: 'false' }` as `true`, the opposite of what was written.
 
+`renderers` is the one recognized key `toHtmlWithOptions` refuses; it belongs to
+[`toHtmlWithRenderers`](#static-renderers).
+
 This exists for a host whose CSS or JS assumes rendered blocks are direct
 children of the content container - the `.stack > * + *` spacing idiom,
 `:first-child`, `nth-child()` counting, `element.children` walks - all of which
@@ -212,6 +252,131 @@ try {
 }
 ```
 
+**Every target takes the profile, not only HTML.** `toMarkdownWithOptions`,
+`toPlainTextWithOptions`, `toAnsiWithOptions`, `toCarveWithOptions` and
+`parseJsonWithOptions` read the same options object, so a document held to a
+profile on its way to HTML is held to it on its way to Markdown or into a stored
+tree. Without them a host could export the same untrusted document unfiltered.
+
+```js
+toMarkdownWithOptions(fromTheReader, { profile: 'comment' })
+```
+
+What those targets actually read is narrower than HTML's list: `profile` and
+`smartTypography` change their output, extensions run, and `symbols`, `labels`,
+`sections`, `sourceLine`, `mode` and the heading-id switches are HTML-side
+concerns the engine's other renderers do not consult. `renderers` is refused
+there as it is on `toHtmlWithOptions`.
+
+`toCarveWithOptions` is narrower again and reads `profile` alone. The canonical
+writer is parse-only by contract, so extensions and `smartTypography` are inert
+there; they are accepted rather than refused so that one options object can be
+handed to every target.
+
+`applyProfile` runs the same filter over an AST-JSON document and hands back the
+filtered tree instead of HTML, for a host that wants to store, diff or re-render
+what the filter left. `violations` reports what it degraded or stripped, which
+the HTML path discards.
+
+```js
+const { json, violations } = applyProfile(parseJson(fromTheReader), 'comment')
+if (violations.length > 0) tell(violations.map((v) => v.message))
+const html = astJsonToHtml(json)
+```
+
+It reads `profileBaseHost` and `smartTypography` from its options object and
+nothing else. It does **not** enforce the profile's `max_length`, which the
+engine applies to the SOURCE bytes before a parse - a host filtering untrusted
+input still needs that bound on the way in.
+
+### Static renderers
+
+`mode: 'static'` renders the self-contained form, which carries no client
+scripts - so a formula in the document has to be typeset while the HTML is being
+written, by the host. `toHtmlWithRenderers(source, options)` takes the same
+options object plus a `renderers.math` callback and returns
+`{ html, rendererErrors }`.
+
+```js
+import katex from 'katex'
+import { toHtmlWithRenderers } from '@markup-carve/carve-wasm'
+
+const { html, rendererErrors } = toHtmlWithRenderers(source, {
+  mode: 'static',
+  extensions: ['math-block'],
+  renderers: {
+    math: (tex, display) => katex.renderToString(tex, { displayMode: display }),
+  },
+})
+```
+
+The callback is called once per ` ```math ` fence, with the TeX source and a
+display flag. Without it, static output keeps the `\[…\]` source for a client to
+typeset later - never blank.
+
+> **Security: what a renderer returns is TRUSTED RAW HTML.**
+> The string is inserted **unescaped**, the same trust class as a `symbols`
+> value. There is one difference worth stating: a symbol value is host
+> configuration keyed by a **name**, while a renderer is host configuration that
+> is **handed document content** and typically echoes some of it back. A host
+> rendering documents it did not author is accepting whatever its renderer makes
+> of that input, so the escaping is the renderer's job.
+
+**The callback must be synchronous.** wasm-bindgen cannot await across it, so an
+`async` renderer returns a Promise the engine has no way to resolve. That is
+reported as a failure rather than stringified into the document.
+
+`renderers.diagrams` is the same callback one level down, keyed by the fence's
+css class:
+
+```js
+const { html, rendererErrors } = toHtmlWithRenderers(source, {
+  mode: 'static',
+  extensions: ['fenced-render', 'fenced-render-graphviz'],
+  renderers: {
+    diagrams: {
+      mermaid: (source) => prerendered.get(source),
+      graphviz: (source) => dotToSvg(source),
+    },
+  },
+})
+```
+
+Mermaid itself cannot be passed here: its `render` returns a Promise from v10
+on. What a browser host can do is render its diagrams beforehand, by whatever
+async means it likes, and pass the lookup as the one-line callback above.
+
+A fence whose class nobody configured degrades to an escaped source block, and
+that is reported by nothing - the callback is never called, so the binding
+cannot see the miss. A configured key the document never uses is silent for the
+same reason. Keys are checked for shape only: an unknown one is accepted,
+because validating it would mean keeping the list of fence classes by hand here
+until [markup-carve/carve-rs#1670](https://github.com/markup-carve/carve-rs/issues/1670)
+puts the class on the registry entry.
+
+A callback that throws, or returns anything but a string, does not abort the
+render. The node it was called for emits nothing and the failure is reported:
+
+```js
+const { html, rendererErrors } = toHtmlWithRenderers(source, {
+  mode: 'static',
+  extensions: ['math-block'],
+  renderers: { math: () => { throw new Error('bad TeX') } },
+})
+// rendererErrors: [{ renderer: 'math', display: true, source: 'E = mc^2', message: '…bad TeX' }]
+```
+
+A diagram failure is an entry in the same array, with `renderer` naming the css
+class and no `display` - that flag is the math callback's second argument.
+
+That is why this is a separate entry point: `toHtmlWithOptions` returns a bare
+string with nowhere to report a failing callback, and a silently empty figure is
+the degradation `lintCarve` exists to warn about. Every other check is at READ
+time, matching the rest of the options object - a non-callable `math`, a
+non-object `renderers` and a non-callable `diagrams` value all throw a
+`TypeError` before the render starts, so a misconfigured host finds out without
+needing a document that happens to contain a formula.
+
 ### Editing a tree, and reading one back
 
 `parseJson` serializes a document out. `astJsonToHtml` renders one back, and
@@ -225,15 +390,234 @@ const html = astJsonToHtml(JSON.stringify(tree), { full: true })
 const carve = astJsonToCarve(JSON.stringify(tree))
 ```
 
+`astJsonToMarkdown`, `astJsonToPlainText` and `astJsonToAnsi` are the same seam
+for the other targets. Each takes the options object, and the profile filter and
+the `before_render` hooks run as they do on the HTML path. Without them a host
+holding a tree reached Markdown through `astJsonToCarve` and `toMarkdown`: a
+canonical write, a re-parse and a second render for one answer.
+
 A tree carrying something no Carve source can spell is refused by
 `astJsonToCarve` rather than written approximately, and an invalid tree throws
 from either.
 
+Ordering follows the tree. Section 7 orders collected definitions by source
+position, so a tree carrying spans prints its footnote and link definitions in
+source order and a tree carrying none prints them in label order.
+`toMarkdown` parses with positions on and always gets the first; these entry
+points get whatever their producer built.
+
 `lintCarve` returns the degradation diagnostics as
 `{ line, column, rule, message, start, end }`, with the rule ids carve-js and
 carve-php use for the same triggers. Offsets are BYTE offsets into the source,
 matching the engine.
 
+### Include expansion
+
+`expandIncludes(source, options)` runs the `{{ path }}` pass (spec PART 9 §19)
+over a document and hands back the expanded tree as AST JSON, alongside the
+warnings and the dependency list a host needs for reporting and file watching.
+
+```js
+import { expandIncludes, astJsonToHtml } from '@markup-carve/carve-wasm'
+
+const files = new Map([['child.crv', 'Included body.\n']])
+
+const { json, warnings, dependencies } = expandIncludes(source, {
+  resolve: (path, ctx) => files.get(path) ?? null,
+})
+document.body.innerHTML = astJsonToHtml(json)
+```
+
+**The resolver has to be synchronous, and that decides who can use this.** A
+browser host that would resolve a path over the network cannot: `fetch` returns
+a Promise and wasm-bindgen cannot await across the call. A host whose files are
+already in memory can - an editor with its open buffers, a bundler, a VFS, a
+test harness. An `async` resolver is not silently ignored: the Promise is
+reported in `resolverErrors` and the directive stays literal, the same way an
+`async` `renderers.math` is handled.
+
+`resolve` returns the child's source as a string, or `{ source, id }` when it
+can name the file canonically. **Supply the id where you have one** - it is what
+the cycle guard compares, so two spellings of one file (`b.crv`, `./b.crv`)
+defeat it without one and only the depth limit stops the recursion. `null`
+refuses the directive as `not-found`, and `{ denial }` refuses it in one of the
+classes §19 names: `outside-root`, `not-found`, `no-root`, `include-denied`,
+`include-unresolved`. The class reaches the caller on the dependency.
+
+`ctx` carries `{ sourcePath, stack, depth }`. `stack` is the include chain, root
+first, and its last entry is the file containing the directive - which is what
+relative resolution keys off.
+
+| Field | Default | What it does |
+|---|---|---|
+| `resolve` | required | `(path, ctx) => source \| { source, id } \| { denial } \| null` |
+| `sourcePath` | none | Identity of the root document, for cycle detection and warning attribution |
+| `extensions` | none | Registry names to parse each CHILD with; pass the set the parent was parsed with |
+| `maxDepth` | `16` | Transitive include depth |
+| `maxBytes` | `max(1 MB, 8 x source bytes)` | Expanded-source byte budget |
+| `maxResolverCalls` | `1000` | Resolver calls for one expansion |
+| `maxWarnings` | `100` | Warnings retained; one per distinct rule always survives |
+
+The budgets are part of the contract rather than a detail. They bound what a
+document of directives can make a host do, and a host serving documents it did
+not write is the one that should lower them.
+
+The result is `{ json, warnings, suppressedWarnings, dependencies,
+chargedBytes, resolverErrors }`. `dependencies` lists every target touched,
+including the ones that did not resolve: a host watching only the files it read
+would never learn that a missing target now exists, so the preview would stay
+stale at the moment the author fixes it. `chargedBytes` is what the budget was
+charged, which is otherwise unobservable from outside.
+
+The tree carries no positions. Expansion merges nodes from several files, and a
+span on a node that came from a child would point into a source the caller
+never passed.
+### Re-parsing while someone types
+
+`parseSnapshot(source)` parses a document and keeps what a later `reparse` needs.
+`reparse(source, changes)` applies a batch of edits and parses the result. Both
+return one JSON string.
+
+```js
+import { parseSnapshot, reparse } from '@markup-carve/carve-wasm'
+
+const first = JSON.parse(parseSnapshot('# One\n'))
+const next = JSON.parse(reparse(first.source, JSON.stringify([
+  { range: [2, 5], replacement: 'Two' },
+])))
+next.source // '# Two\n'
+```
+
+Each result is `{ source, document, sourceLayout, changedSource,
+reusedPreviousTree }`. `document` is the PART 12 tree, `sourceLayout` is what
+`parseSourceLayoutJson` produces, and `changedSource` is the byte ranges this
+parse covered - the whole document on a first parse, the edits on a re-parse.
+
+The snapshot crosses as JSON rather than as a handle. Every other entry point
+in this package is a pure function that owns nothing, and the engine's snapshot
+holds only the source, so there is no tree kept alive in wasm memory for a
+handle to point at.
+
+> **The offsets are UTF-8 byte offsets.**
+> That is what `parseJson` positions and `createSourcePatch` ranges already
+> mean. A browser editor counts UTF-16 code units, so a host holding a
+> `selectionStart` converts before calling. An offset landing inside a
+> multi-byte character is refused rather than guessed at: `é` is two bytes, and
+> `[0, 1]` throws.
+
+A malformed change throws: overlapping ranges, an end past the source, and a
+range splitting a code point are all a broken caller contract rather than a
+result the caller asked for. An empty change list is not one - it re-parses the
+source unchanged, which is what a host batching keystrokes will hit.
+
+`reusedPreviousTree` is the engine's own answer about whether any of the
+previous parse was reused. **The pinned engine always reports `false`**: it
+validates and applies the edits and then parses the whole source. Read the flag
+rather than assuming work was saved.
+### Tree patches
+
+`createAstPatch(before, after)` is the difference between two PART 12 trees,
+and `applyAstPatch(ast, patch)` replays it. Trees and patches both cross as
+JSON strings, the same way `parseJson` and `astJsonToHtml` hand a tree across.
+
+```js
+import { parseJson, createAstPatch, applyAstPatch } from '@markup-carve/carve-wasm'
+
+const patch = createAstPatch(parseJson('# One\n'), parseJson('# Two\n'))
+applyAstPatch(parseJson('# One\n'), patch) // the '# Two' tree, as JSON
+```
+
+The operations are the position-independent `{ op, path, value }` wire shape,
+so a patch stays meaningful against a tree that moved underneath it. That is
+the opposite trade from `createSourcePatch`, which pins byte ranges and
+fingerprints them against staleness.
+
+The engine's `ast_patch_to_json` and `ast_patch_from_json` have no binding of
+their own. With the patch crossing as JSON they are exactly this pair's
+encoding, and calling them would convert JSON a host already holds.
+
+`createReversibleAstPatch(before, after)` returns
+`{ forward, inverse, beforeFingerprint, afterFingerprint }` as one JSON string,
+and `applyReversibleAstPatch(ast, patch, inverse)` replays either direction.
+
+```js
+const step = createReversibleAstPatch(before, after)
+const redone = applyReversibleAstPatch(before, step)
+const undone = applyReversibleAstPatch(after, step, true)
+```
+
+**The undo stack is yours.** Every entry point here is a pure function that
+owns nothing, so there is no history kept in this package to undo against, and
+a browser host already has somewhere to keep one. What the reversible pair adds
+over two `createAstPatch` calls is the precondition: applying a step to a tree
+whose fingerprint is not the one it was made against throws, so an undo cannot
+land on a document that has moved on.
+
+### Three-way merge
+
+`mergeAst(base, ours, theirs, options)` merges two edits of one document. Two
+people editing one document is a browser problem, so the audience is here.
+
+```js
+import { parseJson, mergeAst } from '@markup-carve/carve-wasm'
+
+const { ok, ast, conflicts } = JSON.parse(mergeAst(base, ours, theirs))
+```
+
+**A conflict is a value, not a throw.** It is the result you asked for: `ok` is
+false, `ast` is null, and `conflicts` says where and why. A throw is for a
+contract you broke, and an unparseable tree still gets one, naming which of the
+three it was.
+
+Each conflict is `{ path, reason, base, ours, theirs }`, with `reason` one of
+`both-changed`, `delete-edit` or `concurrent-sequence-edit`. That shape and
+those names are carve-js's, so a host merging with either engine reads one
+contract. The Rust engine carries no `deleted` flags, so carve-js's optional
+`deleted` field is absent here rather than guessed at.
+
+`options.resolve` answers conflicts while the merge runs:
+
+```js
+const merged = JSON.parse(mergeAst(base, ours, theirs, {
+  resolve: (conflict) => (conflict.path.startsWith('/children/0') ? 'ours' : null),
+}))
+```
+
+It returns `'base'`, `'ours'`, `'theirs'`, `{ value }` to replace the field
+outright, or `null` to leave that conflict standing.
+
+> **The resolver must be synchronous.**
+> A resolver that asks a server, or asks the user, returns a Promise the merge
+> cannot await. That is reported in `resolverErrors` with the conflict's path,
+> and the conflict is left unresolved - never swallowed, and never stringified
+> into the tree. Returning `null` is the supported way to decline; a Promise is
+> a mistake.
+
+### ProseMirror
+
+`toProseMirror(source)` converts Carve to the ProseMirror document shape, and
+`fromProseMirror(doc)` writes one back as canonical Carve source. ProseMirror
+runs in a browser and nowhere else, so this binding is the whole audience for
+the engine's bridge - without it a host wiring a Carve editor either round-trips
+to a server or reimplements the node mapping in JS, where it drifts from the
+engine's.
+
+```js
+const { json, dropped, degraded } = toProseMirror(source)
+editor.commands.setContent(JSON.parse(json))
+const saved = fromProseMirror(JSON.stringify(editor.getJSON()))
+```
+
+`json` is a JSON string, the same choice `parseJson` makes. The two maps are
+`Carve node type -> reason`: `dropped` where the content is gone (an
+abbreviation definition has no editor node), `degraded` where the text survives
+without its node type (a soft break becomes whitespace, smart typography
+resolves to the glyph). Both are empty for a document the model holds exactly.
+
+A payload the schema map does not describe is refused rather than written
+approximately. Round-tripping normalizes the source the way `toCarve` does, and
+the reported degradations do not come back - `a ... b` returns as `a … b`.
+
 ### TypeScript
 
 The package ships `.d.ts` declarations. Types are inferred automatically when
@@ -254,6 +638,12 @@ const html: string = toHtml('_Hello_')
 | `toHtmlWithSymbols` | `(source: string, symbols?: object \| null) => string` | Core renderer + a `:name:` -> value symbols map (values are raw, see above) |
 | `toHtmlFull` | `(source: string, symbols?: object \| null) => string` | Core + common extensions (matches playground), optional symbols map |
 | `toHtmlWithOptions` | `(source: string, options?: object \| null) => string` | General form; see the options table above. Throws `ProfileViolationError` when a profile rejects the document |
+| `toHtmlWithRenderers` | `(source: string, options?: object \| null) => StaticRenderResult` | The options object plus `renderers.math` and `renderers.diagrams`, for `mode: 'static'`; returns `{ html, rendererErrors }` |
+| `toMarkdownWithOptions` | `(source: string, options?: object \| null) => string` | Markdown under the same options object. Throws `ProfileViolationError` when a profile rejects the document |
+| `toPlainTextWithOptions` | `(source: string, options?: object \| null) => string` | Plain text under the same options object |
+| `toAnsiWithOptions` | `(source: string, options?: object \| null) => string` | ANSI text under the same options object |
+| `toCarveWithOptions` | `(source: string, options?: object \| null) => string` | Canonical Carve under the same options object; reads `profile` only |
+| `parseJsonWithOptions` | `(source: string, options?: object \| null) => string` | The AST as JSON under the same options object; positions are always on |
 | `toHtmlWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | HTML plus bounded `raw-format-dropped` losses; strict mode throws `RenderLossError` |
 | `toMarkdownWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked Markdown render |
 | `toPlainTextWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked plain-text render |
@@ -262,11 +652,38 @@ const html: string = toHtml('_Hello_')
 | `parseJson` | `(source: string) => string` | The parsed AST as JSON (PART 12 exchange shape) |
 | `astJsonToHtml` | `(json: string, options?: object \| null) => string` | Render an AST-JSON document; takes the same options object |
 | `astJsonToCarve` | `(json: string) => string` | Write an AST-JSON document back as canonical Carve source |
+| `astJsonToMarkdown` | `(json: string, options?: object \| null) => string` | Render an AST-JSON document to Markdown; takes the same options object |
+| `astJsonToPlainText` | `(json: string, options?: object \| null) => string` | Render an AST-JSON document to plain text |
+| `astJsonToAnsi` | `(json: string, options?: object \| null) => string` | Render an AST-JSON document to ANSI-styled text |
+| `applyProfile` | `(json: string, profile: string, options?: object \| null) => ProfileFilterResult` | Filter an AST-JSON document through a profile, keeping the tree and what the filter did |
 | `lintCarve` | `(source: string) => LintWarning[]` | Degradation diagnostics, with the rule ids carve-js and carve-php share |
+| `lintCarveWithOptions` | `(source: string, options?: object \| null) => LintWarning[]` | The same linter for the extension set the host renders with |
+| `lintAccessibility` | `(source: string) => AccessibilityDiagnostic[]` | The second diagnostic family, with its own rule ids and a severity |
+| `stampCarve` | `(formatted: string, generatedBy: string, form?: "line" \| "block") => string` | Write the provenance marker `readStamp` reads |
+| `sanitizeSvg` | `(source: string, options?: object \| null) => SanitizeResult` | Sanitize an SVG document; strict unless an option says otherwise |
+| `parseLocator` | `(loc: string) => ParsedLocator` | Parse a citation locator into label, value and suffix |
+| `parseSourceLayoutJson` | `(source: string) => string` | The PART 12 §13 source-layout sidecar |
+| `markdownToAstJson` | `(source: string) => string` | Import Markdown straight to the tree, skipping the Carve-source round trip |
+| `htmlToAst` | `(html: string, mode?: string) => MigrationResult` | Import HTML straight to the tree; `{ value, report }` with the tree in `value` |
+| `expandIncludes` | `(source: string, options: object) => IncludeExpansion` | Expand `{{ path }}` through a SYNCHRONOUS `resolve`; returns the tree plus warnings, dependencies and resolver failures |
+| `parseSnapshot` | `(source: string) => string` | Parse and keep what a `reparse` needs; JSON `{ source, document, sourceLayout, changedSource, reusedPreviousTree }` |
+| `reparse` | `(source: string, changes: string) => string` | Apply a JSON array of `{ range: [start, end], replacement }` in UTF-8 BYTE offsets and re-parse |
+| `mergeAst` | `(base: string, ours: string, theirs: string, options?: object) => string` | Three-way merge; JSON `{ ok, ast, conflicts, resolverErrors }`, a conflict being a value |
+| `createAstPatch` | `(before: string, after: string) => string` | The difference between two PART 12 trees, as `{ op, path, value }` patch JSON |
+| `applyAstPatch` | `(ast: string, patch: string) => string` | Replay patch JSON onto a tree |
+| `createReversibleAstPatch` | `(before: string, after: string) => string` | The same difference with its inverse and both fingerprints |
+| `applyReversibleAstPatch` | `(ast: string, patch: string, inverse?: boolean) => string` | Replay a reversible patch either way; a fingerprint mismatch throws |
+| `toProseMirror` | `(source: string) => ProseMirrorResult` | Convert to the ProseMirror document shape, with what the model could not hold |
+| `fromProseMirror` | `(doc: string) => string` | Convert a ProseMirror document back to canonical Carve source |
 | `readStamp` | `(source: string) => { version, generatedBy } \| null` | The document's provenance marker, if it carries one |
 | `needsReview` | `(source: string, currentVersion: string) => boolean` | Whether the stamp predates `currentVersion`; unstamped counts as yes |
 | `fromDjot` | `(source: string) => string` | Convert Djot source to Carve |
+| `migrateDjot` | `(source: string) => { value, report }` | Convert Djot with a v2 fidelity report |
 | `fromBbcode` | `(source: string) => string` | Convert BBCode source to Carve; throws past the engine's size cap |
+| `migrateBbcode` | `(source: string) => { value, report }` | Convert BBCode with a v2 fidelity report; throws past the engine's size cap |
+| `createSourcePatch` | `(source, replacement, kind, code) => SourcePatch` | Build a minimal UTF-8 byte-range patch |
+| `toCarvePatch` | `(source: string) => SourcePatch` | Preview canonical formatting as a patch |
+| `applySourcePatch` | `(source: string, patch: SourcePatch) => string` | Validate and apply trusted patch instructions |
 | `version` | `() => string` | Returns the carve-wasm package version |
 
 ### The parsed AST
@@ -297,151 +714,14 @@ browser does natively and faster than building the object graph across the wasm
 boundary one property at a time - and it keeps the bytes available for a caller
 that stores or forwards them.
 
-## carve-rs dependency pin
+## Development
 
-`Cargo.toml` pins an exact carve-rs commit, and `Cargo.lock` is committed
-alongside it:
-
-```toml
-carve = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "..." }
-```
-
-Read the current revision out of `Cargo.toml` rather than from a copy here - a
-revision quoted in prose goes stale the first time someone bumps the manifest
-without noticing the duplicate.
-
-The engine is published as `carve-lang` (carve-rs renamed it from `carve`), so a
-pin at any revision past that rename needs `package = "carve-lang"` as above.
-
-The crate previously tracked carve-rs' default branch with no committed lock.
-That never went stale, but it went the other way: every build resolved whatever
-had landed upstream since, so the published package could carry an engine no CI
-run here had ever built, and two clones a day apart could disagree. The pin
-makes an engine change a reviewable line in a diff.
-
-When bumping the `rev`, regenerate and commit `Cargo.lock` in the same change.
-The lock records the resolved revision plus the rest of the tree; leaving it
-behind gives every fresh clone a dirty working tree on its first build and lets
-the package resolve to an engine other than the one that was tested.
-
-```sh
-cargo update -p carve-lang --precise <sha>   # or edit the rev and re-lock
-cargo test && wasm-pack build --target nodejs && node tests/smoke.mjs
-CARVE_SPEC_CORPUS=/path/to/carve/tests/corpus node tests/corpus.mjs
-```
-
-`scripts/check-engine-floor.py` is what notices a pin left behind. CI runs it
-against the revision carve-rb embeds:
-
-```sh
-python3 scripts/check-engine-floor.py \
-    --engine <carve-rs checkout> --manifest Cargo.toml --lock Cargo.lock \
-    --sibling-name carve-rb --sibling-manifest <carve-rb>/ext/carve/Cargo.toml \
-    --changelog CHANGELOG.md
-```
-
-It fails when this pin is a strict ancestor of the sibling's, and it also fails
-when the `[Unreleased]` changelog section names a revision the build does not
-embed - a revision quoted in prose is a second copy of the pin, and the second
-copy is the one nothing else reads. A floor rather than a leash: it is
-deliberately not a distance check against carve-rs `main`, which merges
-continuously and would be red from the moment any pull request opens there.
-
-That last line is the one that can tell a drifted pin from a current one.
-`smoke.mjs` asserts hand-written expectations, which a stale engine satisfies
-happily; `corpus.mjs` renders all ~530 mandatory spec documents through the
-**built** artifact and requires byte-identical HTML. Without `CARVE_SPEC_CORPUS`
-it prints a notice and exits 0, so a checkout without the spec repo still runs
-the suite. CI always sets it.
-
-It measures the binding as much as the engine: carve-rs is corpus-checked
-upstream, but that says nothing about whether the wasm-bindgen layer drops a
-field or mangles an option on the way through.
-
-Regenerate the whole lock MSRV-aware, or it will quietly break the `rust-version`
-this crate advertises. A plain `cargo generate-lockfile` on a current toolchain
-picks the newest `wasm-bindgen`, which needs a newer Rust than the 1.75 declared
-above - fine while CI only runs `stable`, and a hard failure for anyone actually
-building on the floor:
-
-```sh
-CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback cargo generate-lockfile
-```
-
-Nothing in CI catches this today, since the workflow uses `stable` only. Adding
-a 1.75 job (carve-rs has one) would turn it from a review question into a build
-failure.
-
-## Build
-
-The published package uses the **bundler** target (matching the release
-workflow):
-
-```bash
-cargo test
-wasm-pack build --target bundler --scope markup-carve
-```
-
-`wasm-pack` emits the package into `pkg/`. For a no-bundler / `<script type=module>`
-setup use `--target web` (which exports a default `init()` you must `await`
-before calling the renderers); for Node use `--target nodejs`.
-
-Point the test suite at any built package with `CARVE_WASM_PKG`, rather than
-only at `pkg/`:
-
-```sh
-CARVE_WASM_PKG=some/other/pkg node tests/smoke.mjs
-```
-
-Both wasm-pack targets load. Unset, it is `pkg/`, so nothing changes for the
-ordinary loop.
-
-### Rendering-only browser build
-
-All capabilities are enabled by default, so ordinary builds and the published
-package keep their complete API. A browser host that only renders Carve to HTML
-can leave the importers, reports, AST serialization, and other output formats
-out of its artifact:
-
-```sh
-wasm-pack build --target web --release --out-dir pkg-render . --no-default-features
-```
-
-The basic HTML rendering exports, including `toHtml`, `toHtmlFull`, and
-`toHtmlWithOptions`, remain available. Checked rendering through
-`toHtmlWithReport` is part of the omitted `reports` capability. The optional
-features are:
-
-| Feature | Exports |
-| --- | --- |
-| `html-import` | `htmlToCarve`, `fromHtml` |
-| `markdown-import` | `fromMarkdown` |
-| `reports` | all five `*WithReport` renderers |
-| `ast-json` | `parseJson`, `astJsonToHtml`, `astJsonToCarve` |
-| `other-renderers` | the basic Markdown, plain-text, ANSI, and Carve renderers |
-| `lint` | `lintCarve` |
-| `stamp` | `readStamp`, `needsReview` |
-| `other-imports` | `fromDjot`, `fromBbcode` |
-
-Use a separate output directory as above if a full build also exists in the
-checkout.
-
-## Release
-
-Publishing is gated. `.github/workflows/release.yml` has two jobs, and
-`publish` declares `verify` in `needs:`, so it cannot start while the gate
-fails. The gate is `scripts/verify-release-artifact.mjs`, and it is runnable by
-hand against a local build:
-
-```sh
-wasm-pack build --target bundler --scope markup-carve
-CARVE_SPEC_CORPUS=/path/to/carve/tests/corpus node scripts/verify-release-artifact.mjs
-```
+The reference material a contributor needs lives in `docs/`, so this page can
+stay about USING the package:
 
-It runs `npm pack` and drives `tests/smoke.mjs` and `tests/corpus.mjs` at the
-UNPACKED tarball, not at `pkg/`. The difference matters: npm uploads what the
-generated `files` list names, so a payload file left out of it would never
-reach the registry and would never have been tested either. The corpus
-population comes from the spec's example pages, so a truncated corpus fails
-here instead of passing over a subset, and an unset `CARVE_SPEC_CORPUS` is
-refused rather than skipped.
+- [Building](docs/building.md) - the wasm-pack targets, pointing the tests at a
+  built package, and the rendering-only browser profile.
+- [The carve-rs pin](docs/engine-pin.md) - why the engine is pinned to an exact
+  commit, and how to move it.
+- [Releasing](docs/releasing.md) - the gate, what it refuses, and the runbook
+  for cutting a version.