@markup-carve/carve-wasm 0.1.1 → 0.1.3

package/README.md

@@ -48,6 +48,20 @@ 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
@@ -132,11 +146,25 @@ toHtmlWithOptions('# A\n\np\n', { sections: false })
 toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
 ```
 
-Every field is optional - `sections` (default `true`), `symbols` (same trusted-raw
-contract as `toHtmlWithSymbols`), `extensions` (an array of names; takes
-precedence over `full`), and `full` (default `false`, enabling the preview set).
-Omitting the object, or passing `null`, renders with defaults, so the three
-shorthands above remain the zero-config forms.
+Every field is optional. Omitting the object, or passing `null`, renders with
+defaults, so the three shorthands above remain the zero-config forms.
+
+| Field | Default | What it does |
+|---|---|---|
+| `sections` | `true` | Wrap each top-level heading and its content in a `<section>` |
+| `symbols` | none | `:name:` to value, TRUSTED-RAW (see above) |
+| `extensions` | none | Array of registry names; takes precedence over `full` |
+| `full` | `false` | Enable the preview extension set |
+| `rawHtml` | `true` | Emit an explicit passthrough as markup; `false` escapes it |
+| `profile` | none | `full` / `article` / `comment` / `minimal`; rejection throws |
+| `profileBaseHost` | none | The host the profile's link policy counts as internal |
+| `mode` | `interactive` | `static` renders the self-contained form: no client scripts |
+| `sourceLine` | `false` | Stamp top-level blocks with `data-source-line` |
+| `positions` | `false` | Keep source offsets on the nodes |
+| `labels` | none | Override engine-written strings, for a page not in English |
+| `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 |
 
 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
@@ -154,6 +182,72 @@ Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
 rather than the element carrying it. The endnotes
 `<section role="doc-endnotes">` is a separate construct and is still emitted.
 
+### Rendering a document you did not write
+
+`rawHtml: false` renders an explicit passthrough - the `=html` raw block and the
+`` `…`{=html} `` inline raw span - as escaped text instead of markup. It is the
+switch carve-js spells `allowRawHtml`.
+
+```js
+toHtmlWithOptions(fromTheReader, { rawHtml: false })
+```
+
+Reach for it whenever the document comes from somewhere other than the person
+running the page: a shared link, a comment field, a pasted file. A passthrough is
+the one construct that puts author-controlled markup on your origin, so leaving
+it on for a document a reader supplied is a way to run their script.
+
+The symbols map is unaffected and stays TRUSTED-RAW either way - it is
+configuration the host wrote, not content the document carries.
+
+### Rendering with a profile
+
+`rawHtml: false` closes the passthrough vector. It does not cap input length,
+deny a construct, or constrain link schemes - that is what a profile is for, and
+the four presets match the ones the spec and the sibling bindings describe.
+
+```js
+toHtmlWithOptions(fromTheReader, { profile: 'comment', rawHtml: false })
+```
+
+**A rejected document throws.** The engine's infallible entry point turns a
+profile rejection - input past `max_length`, or a denied construct when the
+action is Error - into an EMPTY STRING, and a caller cannot tell that from a
+document that legitimately rendered to nothing. This binding renders through the
+fallible one, so a rejection arrives as an `Error` whose `name` is
+`ProfileViolationError` and whose `violations` array carries one message per
+refused construct.
+
+```js
+try {
+  html = toHtmlWithOptions(fromTheReader, { profile: 'comment' })
+} catch (error) {
+  if (error.name === 'ProfileViolationError') report(error.violations)
+}
+```
+
+### Editing a tree, and reading one back
+
+`parseJson` serializes a document out. `astJsonToHtml` renders one back, and
+`astJsonToCarve` writes one back as source, so a host that reads the tree in
+order to change something can display and save the result without a server.
+
+```js
+const tree = JSON.parse(parseJson(source))
+tree.children.unshift({ type: 'heading', level: 1, children: [{ type: 'text', value: 'Added' }] })
+const html = astJsonToHtml(JSON.stringify(tree), { full: true })
+const carve = astJsonToCarve(JSON.stringify(tree))
+```
+
+A tree carrying something no Carve source can spell is refused by
+`astJsonToCarve` rather than written approximately, and an invalid tree throws
+from either.
+
+`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.
+
 ### TypeScript
 
 The package ships `.d.ts` declarations. Types are inferred automatically when
@@ -173,13 +267,23 @@ const html: string = toHtml('_Hello_')
 | `toHtml` | `(source: string) => string` | Core renderer, no extensions |
 | `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: `{ sections?, symbols?, full? }`, every field optional |
+| `toHtmlWithOptions` | `(source: string, options?: object \| null) => string` | General form; see the options table above. Throws `ProfileViolationError` when a profile rejects the document |
 | `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 |
 | `toAnsiWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked ANSI render |
 | `toCarveWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked canonical Carve render (lossless) |
 | `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 |
+| `lintCarve` | `(source: string) => LintWarning[]` | Degradation diagnostics, with the rule ids carve-js and carve-php share |
+| `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 |
+| `fromBbcode` | `(source: string) => string` | Convert BBCode source to Carve; 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
@@ -210,121 +314,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.
-
-## 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.

package/carve_wasm.d.ts

@@ -1,6 +1,79 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export interface LintWarning {
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    column: number;
+    /** Stable rule id, shared with carve-js and carve-php. */
+    rule: string;
+    message: string;
+    /** 0-based BYTE offset into the source, inclusive. */
+    start: number;
+    /** 0-based BYTE offset into the source, exclusive. */
+    end: number;
+}
+
+export interface Stamp {
+    /** The spec version the document was last processed under. */
+    version: string;
+    /** The engine that wrote the marker, when it recorded one. */
+    generatedBy: string | null;
+}
+
+export type SourceEditKind = "formatting" | "syntax-migration" | "quick-fix" | "refactor";
+export interface SourceEdit {
+    /** Inclusive UTF-8 byte offset. */
+    start: number;
+    /** Exclusive UTF-8 byte offset. */
+    end: number;
+    replacement: string;
+    kind: SourceEditKind;
+    code: string;
+}
+export interface SourceSuggestion extends SourceEdit { message: string; }
+export interface SourcePatch {
+    version: 1;
+    sourceFingerprint: string;
+    sourceBytes: number;
+    edits: SourceEdit[];
+    unresolved: SourceSuggestion[];
+}
+
+
+
+/**
+ * Apply a trusted patch after its source length and fingerprint still match.
+ */
+export function applySourcePatch(source: string, patch: any): string;
+
+/**
+ * Render an AST-JSON document (PART 12) back to canonical Carve source.
+ *
+ * The round trip a host needs to SAVE an edited tree, rather than only display
+ * it. A tree holding something no Carve source can spell is refused rather
+ * than written approximately.
+ */
+export function astJsonToCarve(json: string): string;
+
+/**
+ * Render an AST-JSON document (PART 12) to HTML.
+ *
+ * The other half of `parseJson`. A host that reads the tree in a browser does
+ * it to CHANGE something, and until now there was no way to render the result:
+ * the binding could serialize a tree out and not take one back.
+ *
+ * Takes the same options object as [`to_html_with_options`], so an edited tree
+ * renders under the profile, labels and switches the host already configured.
+ */
+export function astJsonToHtml(json: string, options?: object | null): string;
+
+/**
+ * Build the smallest single UTF-8 byte-range replacement between two sources.
+ */
+export function createSourcePatch(source: string, replacement: string, kind: string, code: string): SourcePatch;
+
 /**
  * Every extension name this build accepts, in registry order.
  *
@@ -9,6 +82,24 @@
  */
 export function extensions(): string[];
 
+/**
+ * Convert BBCode source to Carve.
+ *
+ * Rejects input past the engine's `BBCODE_MAX_INPUT_LENGTH` rather than
+ * working on it: the importer's cost is superlinear in places, and a browser
+ * host cannot afford to find that out on the main thread.
+ */
+export function fromBbcode(source: string): string;
+
+/**
+ * Convert Djot source to Carve.
+ *
+ * Carve diverges from Djot deliberately - the emphasis delimiters are swapped,
+ * among others - so a Djot document is not Carve source and pasting one in
+ * renders wrongly rather than failing.
+ */
+export function fromDjot(source: string): string;
+
 export function fromHtml(source: string, mode?: string | null): any;
 
 export function fromMarkdown(source: string): any;
@@ -21,6 +112,25 @@ export function fromMarkdown(source: string): any;
  */
 export function htmlToCarve(source: string, mode?: string | null): any;
 
+/**
+ * Lint a document for the degradations PART 15 describes.
+ *
+ * Returns an array of `{ line, column, rule, message, start, end }`. The rule
+ * ids are shared with carve-js and carve-php, so the same trigger reports the
+ * same id everywhere. Offsets are BYTE offsets into the source, matching the
+ * engine.
+ *
+ * Built as JS objects rather than a JSON string: a message carries arbitrary
+ * document text, and hand-rolled JSON escaping is where that goes wrong.
+ */
+export function lintCarve(source: string): LintWarning[];
+
+/**
+ * Whether a document was last processed under an older spec version than
+ * `currentVersion`. An unstamped document counts as needing review.
+ */
+export function needsReview(source: string, current_version: string): boolean;
+
 /**
  * Parse Carve source and return its AST as a JSON string.
  *
@@ -41,12 +151,22 @@ export function htmlToCarve(source: string, mode?: string | null): any;
  */
 export function parseJson(source: string): string;
 
+/**
+ * Read a document's provenance marker: `{ version, generatedBy }`, or `null`.
+ */
+export function readStamp(source: string): Stamp | null;
+
 export function toAnsi(source: string): string;
 
 export function toAnsiWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 export function toCarve(source: string): string;
 
+/**
+ * Preview canonical formatting as a source-preserving patch.
+ */
+export function toCarvePatch(source: string): SourcePatch;
+
 export function toCarveWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 export function toHtml(source: string): string;
@@ -76,6 +196,8 @@ export function toHtmlFull(source: string, symbols?: object | null): string;
  * // '<h1 id="A">A</h1>\n<p>p</p>'
  *
  * toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
+ *
+ * toHtmlWithOptions(untrusted, { rawHtml: false })
  * ```
  *
  * Every field is optional:
@@ -98,6 +220,31 @@ export function toHtmlFull(source: string, symbols?: object | null): string;
  *   over `full`.
  * * `full` (default `false`) - enable the preview extension set instead of
  *   rendering core-only.
+ * * `rawHtml` (default `true`) - render an explicit passthrough - the `=html`
+ *   raw block and the `` `…`{=html} `` inline raw span - as markup. `false`
+ *   emits it as escaped text instead, the same switch carve-js spells
+ *   `allowRawHtml`. A host that renders a document it did not author (a shared
+ *   link, a comment field, anything a reader supplies) wants `false`: without
+ *   it a passthrough is a way to run script on the host's origin.
+ * * `profile` - one of `"full"`, `"article"`, `"comment"`, `"minimal"`. The
+ *   rest of the untrusted-input story: input length, denied constructs, link
+ *   policy. A document the profile REJECTS throws a `ProfileViolationError`
+ *   carrying `violations`, rather than resolving to an empty string.
+ * * `profileBaseHost` - the host counted as internal when the profile's link
+ *   policy distinguishes internal from external links.
+ * * `mode` - `"interactive"` (default) or `"static"`, the self-contained form
+ *   for print, PDF and archival: no client scripts.
+ * * `sourceLine` (default `false`) - stamp top-level blocks with
+ *   `data-source-line`, for editor preview scroll-sync.
+ * * `positions` (default `false`) - keep source offsets on the nodes.
+ * * `labels` - override the engine-written strings (admonition names, the
+ *   endnotes heading, backlink text) for a page that is not in English. These
+ *   are TEXT and are escaped where they land, unlike `symbols`.
+ * * `smartTypography` - `"glyph"` (default) resolves `...` to an ellipsis,
+ *   `"source"` keeps the author's run.
+ * * `lowercaseHeadingIds` (default `false`) and `asciiHeadingIds`
+ *   (`"off"` (default), `"fold"`, `"strict"`) - the slug policy, for a host
+ *   whose anchors have to match another generator's.
  *
  * An unrecognized key is ignored: the object is configuration, and a caller
  * who mistypes one deserves the render to still work. A wrong TYPE on a key

package/carve_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./carve_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    extensions, fromHtml, fromMarkdown, htmlToCarve, parseJson, toAnsi, toAnsiWithReport, toCarve, toCarveWithReport, toHtml, toHtmlFull, toHtmlWithOptions, toHtmlWithReport, toHtmlWithSymbols, toMarkdown, toMarkdownWithReport, toPlainText, toPlainTextWithReport, version
+    applySourcePatch, astJsonToCarve, astJsonToHtml, createSourcePatch, extensions, fromBbcode, fromDjot, fromHtml, fromMarkdown, htmlToCarve, lintCarve, needsReview, parseJson, readStamp, toAnsi, toAnsiWithReport, toCarve, toCarvePatch, toCarveWithReport, toHtml, toHtmlFull, toHtmlWithOptions, toHtmlWithReport, toHtmlWithSymbols, toMarkdown, toMarkdownWithReport, toPlainText, toPlainTextWithReport, version
 } from "./carve_wasm_bg.js";

package/carve_wasm_bg.js

@@ -1,3 +1,118 @@
+/**
+ * Apply a trusted patch after its source length and fingerprint still match.
+ * @param {string} source
+ * @param {any} patch
+ * @returns {string}
+ */
+export function applySourcePatch(source, patch) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.applySourcePatch(ptr0, len0, patch);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Render an AST-JSON document (PART 12) back to canonical Carve source.
+ *
+ * The round trip a host needs to SAVE an edited tree, rather than only display
+ * it. A tree holding something no Carve source can spell is refused rather
+ * than written approximately.
+ * @param {string} json
+ * @returns {string}
+ */
+export function astJsonToCarve(json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.astJsonToCarve(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Render an AST-JSON document (PART 12) to HTML.
+ *
+ * The other half of `parseJson`. A host that reads the tree in a browser does
+ * it to CHANGE something, and until now there was no way to render the result:
+ * the binding could serialize a tree out and not take one back.
+ *
+ * Takes the same options object as [`to_html_with_options`], so an edited tree
+ * renders under the profile, labels and switches the host already configured.
+ * @param {string} json
+ * @param {object | null} [options]
+ * @returns {string}
+ */
+export function astJsonToHtml(json, options) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.astJsonToHtml(ptr0, len0, isLikeNone(options) ? 0 : addToExternrefTable0(options));
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Build the smallest single UTF-8 byte-range replacement between two sources.
+ * @param {string} source
+ * @param {string} replacement
+ * @param {string} kind
+ * @param {string} code
+ * @returns {SourcePatch}
+ */
+export function createSourcePatch(source, replacement, kind, code) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(replacement, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passStringToWasm0(kind, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len2 = WASM_VECTOR_LEN;
+    const ptr3 = passStringToWasm0(code, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len3 = WASM_VECTOR_LEN;
+    const ret = wasm.createSourcePatch(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Every extension name this build accepts, in registry order.
  *
@@ -12,6 +127,60 @@ export function extensions() {
     return v1;
 }
 
+/**
+ * Convert BBCode source to Carve.
+ *
+ * Rejects input past the engine's `BBCODE_MAX_INPUT_LENGTH` rather than
+ * working on it: the importer's cost is superlinear in places, and a browser
+ * host cannot afford to find that out on the main thread.
+ * @param {string} source
+ * @returns {string}
+ */
+export function fromBbcode(source) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.fromBbcode(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Convert Djot source to Carve.
+ *
+ * Carve diverges from Djot deliberately - the emphasis delimiters are swapped,
+ * among others - so a Djot document is not Carve source and pasting one in
+ * renders wrongly rather than failing.
+ * @param {string} source
+ * @returns {string}
+ */
+export function fromDjot(source) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.fromDjot(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * @param {string} source
  * @param {string | null} [mode]
@@ -64,6 +233,45 @@ export function htmlToCarve(source, mode) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Lint a document for the degradations PART 15 describes.
+ *
+ * Returns an array of `{ line, column, rule, message, start, end }`. The rule
+ * ids are shared with carve-js and carve-php, so the same trigger reports the
+ * same id everywhere. Offsets are BYTE offsets into the source, matching the
+ * engine.
+ *
+ * Built as JS objects rather than a JSON string: a message carries arbitrary
+ * document text, and hand-rolled JSON escaping is where that goes wrong.
+ * @param {string} source
+ * @returns {LintWarning[]}
+ */
+export function lintCarve(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.lintCarve(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Whether a document was last processed under an older spec version than
+ * `currentVersion`. An unstamped document counts as needing review.
+ * @param {string} source
+ * @param {string} current_version
+ * @returns {boolean}
+ */
+export function needsReview(source, current_version) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(current_version, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.needsReview(ptr0, len0, ptr1, len1);
+    return ret !== 0;
+}
+
 /**
  * Parse Carve source and return its AST as a JSON string.
  *
@@ -99,6 +307,21 @@ export function parseJson(source) {
     }
 }
 
+/**
+ * Read a document's provenance marker: `{ version, generatedBy }`, or `null`.
+ * @param {string} source
+ * @returns {Stamp | null}
+ */
+export function readStamp(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.readStamp(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {string} source
  * @returns {string}
@@ -153,6 +376,21 @@ export function toCarve(source) {
     }
 }
 
+/**
+ * Preview canonical formatting as a source-preserving patch.
+ * @param {string} source
+ * @returns {SourcePatch}
+ */
+export function toCarvePatch(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.toCarvePatch(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {string} source
  * @param {boolean | null} [strict]
@@ -235,6 +473,8 @@ export function toHtmlFull(source, symbols) {
  * // '<h1 id="A">A</h1>\n<p>p</p>'
  *
  * toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
+ *
+ * toHtmlWithOptions(untrusted, { rawHtml: false })
  * ```
  *
  * Every field is optional:
@@ -257,6 +497,31 @@ export function toHtmlFull(source, symbols) {
  *   over `full`.
  * * `full` (default `false`) - enable the preview extension set instead of
  *   rendering core-only.
+ * * `rawHtml` (default `true`) - render an explicit passthrough - the `=html`
+ *   raw block and the `` `…`{=html} `` inline raw span - as markup. `false`
+ *   emits it as escaped text instead, the same switch carve-js spells
+ *   `allowRawHtml`. A host that renders a document it did not author (a shared
+ *   link, a comment field, anything a reader supplies) wants `false`: without
+ *   it a passthrough is a way to run script on the host's origin.
+ * * `profile` - one of `"full"`, `"article"`, `"comment"`, `"minimal"`. The
+ *   rest of the untrusted-input story: input length, denied constructs, link
+ *   policy. A document the profile REJECTS throws a `ProfileViolationError`
+ *   carrying `violations`, rather than resolving to an empty string.
+ * * `profileBaseHost` - the host counted as internal when the profile's link
+ *   policy distinguishes internal from external links.
+ * * `mode` - `"interactive"` (default) or `"static"`, the self-contained form
+ *   for print, PDF and archival: no client scripts.
+ * * `sourceLine` (default `false`) - stamp top-level blocks with
+ *   `data-source-line`, for editor preview scroll-sync.
+ * * `positions` (default `false`) - keep source offsets on the nodes.
+ * * `labels` - override the engine-written strings (admonition names, the
+ *   endnotes heading, backlink text) for a page that is not in English. These
+ *   are TEXT and are escaped where they land, unlike `symbols`.
+ * * `smartTypography` - `"glyph"` (default) resolves `...` to an ellipsis,
+ *   `"source"` keeps the author's run.
+ * * `lowercaseHeadingIds` (default `false`) and `asciiHeadingIds`
+ *   (`"off"` (default), `"fold"`, `"strict"`) - the slug policy, for a host
+ *   whose anchors have to match another generator's.
  *
  * An unrecognized key is ignored: the object is configuration, and a caller
  * who mistypes one deserves the render to still work. A wrong TYPE on a key
@@ -433,19 +698,82 @@ export function version() {
         wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
     }
 }
+export function __wbg_Error_2e59b1b37a9a34c3(arg0, arg1) {
+    const ret = Error(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
+export function __wbg_Number_e6ffdb596c888833(arg0) {
+    const ret = Number(arg0);
+    return ret;
+}
+export function __wbg_String_8564e559799eccda(arg0, arg1) {
+    const ret = String(arg1);
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg___wbindgen_bigint_get_as_i64_2c5082002e4826e2(arg0, arg1) {
+    const v = arg1;
+    const ret = typeof(v) === 'bigint' ? v : undefined;
+    getDataViewMemory0().setBigInt64(arg0 + 8 * 1, isLikeNone(ret) ? BigInt(0) : ret, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+}
 export function __wbg___wbindgen_boolean_get_a86c216575a75c30(arg0) {
     const v = arg0;
     const ret = typeof(v) === 'boolean' ? v : undefined;
     return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
 }
+export function __wbg___wbindgen_debug_string_dd5d2d07ce9e6c57(arg0, arg1) {
+    const ret = debugString(arg1);
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg___wbindgen_in_4bd7a57e54337366(arg0, arg1) {
+    const ret = arg0 in arg1;
+    return ret;
+}
+export function __wbg___wbindgen_is_bigint_6c98f7e945dacdde(arg0) {
+    const ret = typeof(arg0) === 'bigint';
+    return ret;
+}
+export function __wbg___wbindgen_is_function_49868bde5eb1e745(arg0) {
+    const ret = typeof(arg0) === 'function';
+    return ret;
+}
 export function __wbg___wbindgen_is_null_344c8750a8525473(arg0) {
     const ret = arg0 === null;
     return ret;
 }
+export function __wbg___wbindgen_is_object_40c5a80572e8f9d3(arg0) {
+    const val = arg0;
+    const ret = typeof(val) === 'object' && val !== null;
+    return ret;
+}
+export function __wbg___wbindgen_is_string_b29b5c5a8065ba1a(arg0) {
+    const ret = typeof(arg0) === 'string';
+    return ret;
+}
 export function __wbg___wbindgen_is_undefined_c0cca72b82b86f4d(arg0) {
     const ret = arg0 === undefined;
     return ret;
 }
+export function __wbg___wbindgen_jsval_eq_7d430e744a913d26(arg0, arg1) {
+    const ret = arg0 === arg1;
+    return ret;
+}
+export function __wbg___wbindgen_jsval_loose_eq_3a72ae764d46d944(arg0, arg1) {
+    const ret = arg0 == arg1;
+    return ret;
+}
+export function __wbg___wbindgen_number_get_7579aab02a8a620c(arg0, arg1) {
+    const obj = arg1;
+    const ret = typeof(obj) === 'number' ? obj : undefined;
+    getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+}
 export function __wbg___wbindgen_string_get_914df97fcfa788f2(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'string' ? obj : undefined;
@@ -457,6 +785,14 @@ export function __wbg___wbindgen_string_get_914df97fcfa788f2(arg0, arg1) {
 export function __wbg___wbindgen_throw_81fc77679af83bc6(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
+export function __wbg_call_7f2987183bb62793() { return handleError(function (arg0, arg1) {
+    const ret = arg0.call(arg1);
+    return ret;
+}, arguments); }
+export function __wbg_done_547d467e97529006(arg0) {
+    const ret = arg0.done;
+    return ret;
+}
 export function __wbg_entries_616b1a459b85be0b(arg0) {
     const ret = Object.entries(arg0);
     return ret;
@@ -473,6 +809,10 @@ export function __wbg_get_4848e350b40afc16(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
+export function __wbg_get_ed0642c4b9d31ddf() { return handleError(function (arg0, arg1) {
+    const ret = Reflect.get(arg0, arg1);
+    return ret;
+}, arguments); }
 export function __wbg_get_f96702c6245e4ef9() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
@@ -481,6 +821,20 @@ export function __wbg_get_unchecked_7d7babe32e9e6a54(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
+export function __wbg_get_with_ref_key_6412cf3094599694(arg0, arg1) {
+    const ret = arg0[arg1];
+    return ret;
+}
+export function __wbg_instanceof_ArrayBuffer_ff7c1337a5e3b33a(arg0) {
+    let result;
+    try {
+        result = arg0 instanceof ArrayBuffer;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
 export function __wbg_instanceof_Map_a10a2795ef4bfe97(arg0) {
     let result;
     try {
@@ -501,10 +855,32 @@ export function __wbg_instanceof_Object_72ee0c53dd8f0726(arg0) {
     const ret = result;
     return ret;
 }
+export function __wbg_instanceof_Uint8Array_4b8da683deb25d72(arg0) {
+    let result;
+    try {
+        result = arg0 instanceof Uint8Array;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
 export function __wbg_isArray_db61795ad004c139(arg0) {
     const ret = Array.isArray(arg0);
     return ret;
 }
+export function __wbg_isSafeInteger_ea83862ba994770c(arg0) {
+    const ret = Number.isSafeInteger(arg0);
+    return ret;
+}
+export function __wbg_iterator_de403ef31815a3e6() {
+    const ret = Symbol.iterator;
+    return ret;
+}
+export function __wbg_length_0c32cb8543c8e4c8(arg0) {
+    const ret = arg0.length;
+    return ret;
+}
 export function __wbg_length_6e821edde497a532(arg0) {
     const ret = arg0.length;
     return ret;
@@ -517,6 +893,10 @@ export function __wbg_new_4f9fafbb3909af72() {
     const ret = new Object();
     return ret;
 }
+export function __wbg_new_a560378ea1240b14(arg0) {
+    const ret = new Uint8Array(arg0);
+    return ret;
+}
 export function __wbg_new_e3b04b4d53d1b593(arg0, arg1) {
     const ret = new Error(getStringFromWasm0(arg0, arg1));
     return ret;
@@ -525,18 +905,42 @@ export function __wbg_new_f3c9df4f38f3f798() {
     const ret = new Array();
     return ret;
 }
+export function __wbg_next_01132ed6134b8ef5(arg0) {
+    const ret = arg0.next;
+    return ret;
+}
+export function __wbg_next_b3713ec761a9dbfd() { return handleError(function (arg0) {
+    const ret = arg0.next();
+    return ret;
+}, arguments); }
 export function __wbg_parse_545d11396395fbbd() { return handleError(function (arg0, arg1) {
     const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
     return ret;
 }, arguments); }
+export function __wbg_prototypesetcall_3e05eb9545565046(arg0, arg1, arg2) {
+    Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
+}
 export function __wbg_push_6bdbc990be5ac37b(arg0, arg1) {
     const ret = arg0.push(arg1);
     return ret;
 }
+export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
+    arg0[arg1] = arg2;
+}
+export function __wbg_set_6c60b2e8ad0e9383(arg0, arg1, arg2) {
+    arg0[arg1 >>> 0] = arg2;
+}
 export function __wbg_set_8ee2d34facb8466e() { return handleError(function (arg0, arg1, arg2) {
     const ret = Reflect.set(arg0, arg1, arg2);
     return ret;
 }, arguments); }
+export function __wbg_set_name_ab9c98596fd7310a(arg0, arg1, arg2) {
+    arg0.name = getStringFromWasm0(arg1, arg2);
+}
+export function __wbg_value_7f6052747ccf940f(arg0) {
+    const ret = arg0.value;
+    return ret;
+}
 export function __wbindgen_cast_0000000000000001(arg0) {
     // Cast intrinsic for `F64 -> Externref`.
     const ret = arg0;
@@ -547,6 +951,11 @@ export function __wbindgen_cast_0000000000000002(arg0, arg1) {
     const ret = getStringFromWasm0(arg0, arg1);
     return ret;
 }
+export function __wbindgen_cast_0000000000000003(arg0) {
+    // Cast intrinsic for `U64 -> Externref`.
+    const ret = BigInt.asUintN(64, arg0);
+    return ret;
+}
 export function __wbindgen_init_externref_table() {
     const table = wasm.__wbindgen_externrefs;
     const offset = table.grow(4);
@@ -562,6 +971,71 @@ function addToExternrefTable0(obj) {
     return idx;
 }
 
+function debugString(val) {
+    // primitive types
+    const type = typeof val;
+    if (type == 'number' || type == 'boolean' || val == null) {
+        return  `${val}`;
+    }
+    if (type == 'string') {
+        return `"${val}"`;
+    }
+    if (type == 'symbol') {
+        const description = val.description;
+        if (description == null) {
+            return 'Symbol';
+        } else {
+            return `Symbol(${description})`;
+        }
+    }
+    if (type == 'function') {
+        const name = val.name;
+        if (typeof name == 'string' && name.length > 0) {
+            return `Function(${name})`;
+        } else {
+            return 'Function';
+        }
+    }
+    // objects
+    if (Array.isArray(val)) {
+        const length = val.length;
+        let debug = '[';
+        if (length > 0) {
+            debug += debugString(val[0]);
+        }
+        for(let i = 1; i < length; i++) {
+            debug += ', ' + debugString(val[i]);
+        }
+        debug += ']';
+        return debug;
+    }
+    // Test for built-in
+    const builtInMatches = /\[object ([^\]]+)\]/.exec(toString.call(val));
+    let className;
+    if (builtInMatches && builtInMatches.length > 1) {
+        className = builtInMatches[1];
+    } else {
+        // Failed to match the standard '[object ClassName]'
+        return toString.call(val);
+    }
+    if (className == 'Object') {
+        // we're a user defined class or Object
+        // JSON.stringify avoids problems with cycles, and is generally much
+        // easier than looping through ownProperties of `val`.
+        try {
+            return 'Object(' + JSON.stringify(val) + ')';
+        } catch (_) {
+            return 'Object';
+        }
+    }
+    // errors
+    if (val instanceof Error) {
+        return `${val.name}: ${val.message}\n${val.stack}`;
+    }
+    // TODO we could test for more things here, like `Set`s and `Map`s.
+    return className;
+}
+
 function getArrayJsValueFromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     const mem = getDataViewMemory0();
@@ -573,6 +1047,11 @@ function getArrayJsValueFromWasm0(ptr, len) {
     return result;
 }
 
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
 let cachedDataViewMemory0 = null;
 function getDataViewMemory0() {
     if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@markup-carve/carve-wasm",
   "type": "module",
   "description": "WASM bindings for the Carve parser and HTML renderer.",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",