@markup-carve/carve-wasm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Scherer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# carve-wasm
+
+WebAssembly build of the [Carve](https://markup-carve.github.io/carve/) markup
+renderer, compiled from
+[carve-rs](https://github.com/markup-carve/carve-rs). Lets the Rust
+implementation run client-side in the browser and backs the **Rust (WASM)**
+engine in the [Carve playground](https://markup-carve.github.io/carve/playground).
+
+## Install
+
+```bash
+npm install @markup-carve/carve-wasm
+```
+
+> Publishing to npm is pending. Until the package is live you can build locally
+> (see [Build](#build) below) or consume the `pkg/` output directly.
+
+## Usage
+
+### HTML migration
+
+`htmlToCarve(html, mode)` returns `{ value, report }`, using the same HTML5
+import policy and canonical writer as carve-rs. Modes are `safe` (default),
+`semantic`, and trusted-only `roundtrip`.
+
+```js
+const { value, report } = htmlToCarve('<p>Hello <strong>world</strong></p>', 'safe')
+```
+
+### Core renderer
+
+Renders Carve markup to HTML with no extensions enabled.
+
+The published package is the **bundler** target (webpack, Vite, Rollup, ...):
+the wasm initializes automatically, so the exports are synchronous - no `init()`
+call.
+
+```js
+import { toHtml } from '@markup-carve/carve-wasm'
+
+const html = toHtml('# Hello, Carve!')
+document.body.innerHTML = html
+```
+
+### Extensions
+
+`extensions()` reports every extension this build accepts. The list comes from
+the engine, so it cannot fall behind what the engine has:
+
+```js
+import { extensions, toHtmlWithOptions } from '@markup-carve/carve-wasm'
+
+extensions()
+// ['autolink', 'citations', 'code-callouts', 'code-group', ...]
+
+toHtmlWithOptions(src, { extensions: ['glossary', 'table-of-contents'] })
+```
+
+Names are kebab-case; snake_case (`math_block`) is accepted too. An unknown name
+throws, because an ignored extension renders as missing behavior that looks
+like a Carve bug.
+
+### Full renderer (preview set)
+
+`toHtmlFull` enables the preview set the playground uses: tab normalisation,
+`<details>` fences, Mermaid diagrams, wikilinks, autolink, list-table, math
+blocks, heading permalinks, citations, code callouts, external-link decoration,
+code groups, and tabs.
+
+It is a curated subset rather than everything registered. Extensions that
+rewrite a document that never asked - `heading-numbers` numbers every heading,
+`table-of-contents` injects a TOC - are wrong for a preview. Name them
+explicitly through `toHtmlWithOptions` when you want them.
+
+```js
+import { toHtmlFull } from '@markup-carve/carve-wasm'
+
+const html = toHtmlFull('# Hello\n\n``` mermaid\ngraph TD; A-->B\n```\n')
+document.body.innerHTML = html
+```
+
+### Symbols
+
+A `:name:` symbol renders its literal `:name:` source unless the name is in the
+**symbols map**. Pass one as a plain object (or a `Map`) to `toHtmlWithSymbols`,
+or as the optional second argument of `toHtmlFull`:
+
+```js
+import { toHtmlWithSymbols } from '@markup-carve/carve-wasm'
+
+toHtmlWithSymbols('Ship it :rocket:', { rocket: '🚀' })
+// => '<p>Ship it 🚀</p>'
+
+toHtmlWithSymbols('Ship it :rocket: :shrug:', { rocket: '🚀' })
+// => '<p>Ship it 🚀 :shrug:</p>'   (an unmapped name stays literal)
+```
+
+The word-boundary guard is unaffected by an active map: `a:b:c`, `10:30:` and
+`me@example.com` never become symbols. Names and values must both be strings; a
+non-string value throws a `TypeError`.
+
+> **Security: symbol values are TRUSTED RAW output.**
+> A mapped value is inserted into the output **unescaped** - the same trust
+> class as a static `renderers` callback. `{ b: '<b>x</b>' }` emits a real
+> `<b>` element, not escaped text. This is deliberate (processor configuration
+> is trusted). **Never build a symbols map out of untrusted / user-supplied
+> input.**
+
+### Section wrappers
+
+A top-level heading is wrapped, along with the content following it up to the
+next same-or-shallower heading, in a `<section>` carrying the heading's id (spec
+PART 9 §13). Only the id moves - `{#install .featured}` gives
+`<section id="install"><h2 class="featured">` - and a heading inside a
+blockquote, div or list item is not wrapped at all.
+
+`toHtmlWithOptions` is the general entry point, and `sections: false` renders
+headings flat with the id back on the `<h*>`:
+
+```js
+import { toHtmlWithOptions } from '@markup-carve/carve-wasm'
+
+toHtmlWithOptions('# A\n\np\n', { sections: false })
+// '<h1 id="A">A</h1>\n<p>p</p>'
+
+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.
+
+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.
+
+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
+stop matching once a wrapper sits in between. It is the one output change that
+breaks a document whose *source* migrated cleanly.
+
+Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
+`[Heading][]` references and heading numbering all resolve against the slug
+rather than the element carrying it. The endnotes
+`<section role="doc-endnotes">` is a separate construct and is still emitted.
+
+### TypeScript
+
+The package ships `.d.ts` declarations. Types are inferred automatically when
+imported from `@markup-carve/carve-wasm`.
+
+```ts
+import { toHtml, toHtmlFull, version } from '@markup-carve/carve-wasm'
+
+console.log(`carve-wasm v${version()}`)
+const html: string = toHtml('_Hello_')
+```
+
+## API
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `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 |
+| `parseJson` | `(source: string) => string` | The parsed AST as JSON (PART 12 exchange shape) |
+| `version` | `() => string` | Returns the carve-wasm package version |
+
+### The parsed AST
+
+`parseJson` returns the document as a JSON string - the [PART 12 exchange
+shape](https://markup-carve.github.io/carve/ast-json), the same tree every Carve
+engine publishes, so a consumer written against one implementation reads
+another's output.
+
+```js
+import { parseJson } from '@markup-carve/carve-wasm'
+
+const ast = JSON.parse(parseJson('# Title\n\nBody[^a].\n\n[^a]: note\n'))
+ast.children.map((n) => n.type) // ['heading', 'paragraph', 'footnote']
+ast.children[0].pos             // { startLine: 1, startColumn: 1, ... }
+```
+
+The root carries exactly `type`, `children` and `srcByteLength`; frontmatter and
+footnote definitions are block nodes inside `children`, not root fields. Every
+node except the root carries `pos` when the engine could place it - 1-based
+lines and columns, 0-based offsets, ends exclusive, counted in Unicode
+**codepoints**, not bytes or UTF-16 units. A node the engine could not place,
+such as reassembled table-cell text, carries no `pos` at all rather than an
+invented one.
+
+A string rather than a JS object: the caller runs `JSON.parse`, which the
+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
+
+`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
+```
+
+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
+```
+
+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.

package/carve_wasm.d.ts

@@ -0,0 +1,120 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Every extension name this build accepts, in registry order.
+ *
+ * Taken from the engine, so a new extension is reachable as soon as the pin
+ * moves. Nothing here lists names.
+ */
+export function extensions(): string[];
+
+/**
+ * Import HTML through the Rust HTML5 DOM and canonical Carve writer.
+ *
+ * Returns `{ value, report }`; `report.diagnostics` makes every lossy import
+ * decision observable. `roundtrip` is only safe for Carve-produced HTML.
+ */
+export function htmlToCarve(source: string, mode?: string | null): any;
+
+/**
+ * Parse Carve source and return its AST as a JSON string.
+ *
+ * The PART 12 exchange shape (https://markup-carve.github.io/carve/ast-json):
+ * the same tree every Carve engine publishes, so a consumer written against
+ * one implementation reads another's output. The root carries exactly `type`,
+ * `children` and `srcByteLength`; frontmatter and footnote definitions are
+ * block nodes inside `children`, not root fields.
+ *
+ * Returns a STRING rather than a JS object: the caller runs `JSON.parse`, which
+ * is what a browser does natively and faster than building the object graph
+ * across the wasm boundary one property at a time. It also keeps the bytes
+ * available for a caller that stores or forwards them.
+ *
+ * Position tracking is on for this entry point and nowhere else. PART 12 §4
+ * lets an engine gate tracking behind a parse option but requires the
+ * serialized form to carry it, and rendering would pay for spans nobody reads.
+ */
+export function parseJson(source: string): string;
+
+export function toHtml(source: string): string;
+
+/**
+ * Render with the preview extension set enabled (`PREVIEW_EXTENSIONS`), so the
+ * WASM engine matches an extensions-on host such as the docs Playground rather
+ * than the core-only `toHtml`.
+ *
+ * The set is curated, not "everything the engine has": `heading-numbers` and
+ * `table-of-contents` rewrite a document that never asked for it, which is
+ * wrong for a preview. Callers who want an exact set pass `extensions` to
+ * `toHtmlWithOptions`, and `extensions()` reports what this build accepts.
+ *
+ * The optional second argument is the same **symbols map** as
+ * [`to_html_with_symbols`], with the same trusted-raw contract: mapped values
+ * are emitted UNESCAPED, so never feed it untrusted input.
+ */
+export function toHtmlFull(source: string, symbols?: object | null): string;
+
+/**
+ * Render with an options object, the general form of the three shorthands
+ * above.
+ *
+ * ```js
+ * toHtmlWithOptions('# A\n\np\n', { sections: false })
+ * // '<h1 id="A">A</h1>\n<p>p</p>'
+ *
+ * toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
+ * ```
+ *
+ * Every field is optional:
+ *
+ * * `sections` (default `true`) - wrap each top-level heading, and the content
+ *   following it up to the next same-or-shallower heading, in a
+ *   `<section id="…">` (spec PART 9 §13). `false` renders headings flat with
+ *   the id back on the `<h*>` and the former section children as siblings.
+ *   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 - the
+ *   wrapper is the one output change a clean source migration still breaks.
+ * * `symbols` - the same map as [`to_html_with_symbols`], with the same
+ *   TRUSTED-RAW contract: mapped values are emitted UNESCAPED, so never build
+ *   it from untrusted input.
+ * * `extensions` - an array of extension names to enable, e.g.
+ *   `["glossary", "table-of-contents"]`. `extensions()` reports what this
+ *   build accepts. An unknown name throws: a silently ignored extension would
+ *   render as missing behavior that looks like a Carve bug. Takes precedence
+ *   over `full`.
+ * * `full` (default `false`) - enable the preview extension set instead of
+ *   rendering core-only.
+ *
+ * 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
+ * that is recognized does throw, because that changes behavior silently.
+ *
+ * Turning sections off changes nothing else. Ids, collision dedup, `</#id>`
+ * crossrefs, implicit `[Heading][]` references and heading numbering all
+ * resolve against the slug rather than the element carrying it, and the
+ * endnotes `<section role="doc-endnotes">` is a separate construct that is
+ * still emitted.
+ */
+export function toHtmlWithOptions(source: string, options?: object | null): string;
+
+/**
+ * Render with the core profile and a **symbols map**: `{ rocket: "🚀" }` (a
+ * plain object or a `Map`). A `:name:` symbol whose name is in the map renders
+ * the mapped value; an unmapped `:name:` stays literal `:name:` text, and the
+ * leading word-boundary guard still applies (`a:b:c`, `10:30:`,
+ * `me@example.com` never become symbols).
+ *
+ * Names and values must both be strings; a non-string value throws a JS
+ * `TypeError`.
+ *
+ * SECURITY: a mapped value is inserted as **TRUSTED RAW output in the target
+ * format** - it is NOT escaped, the same trust class as the static `renderers`
+ * map. So `{ b: "<b>x</b>" }` emits a real `<b>` element, not escaped text.
+ * This is deliberate: processor configuration is trusted. NEVER build a
+ * symbols map out of untrusted / user-supplied input.
+ */
+export function toHtmlWithSymbols(source: string, symbols?: object | null): string;
+
+export function version(): string;

package/carve_wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./carve_wasm.d.ts" */
+
+import * as wasm from "./carve_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./carve_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    extensions, htmlToCarve, parseJson, toHtml, toHtmlFull, toHtmlWithOptions, toHtmlWithSymbols, version
+} from "./carve_wasm_bg.js";

package/carve_wasm_bg.js

@@ -0,0 +1,482 @@
+/**
+ * Every extension name this build accepts, in registry order.
+ *
+ * Taken from the engine, so a new extension is reachable as soon as the pin
+ * moves. Nothing here lists names.
+ * @returns {string[]}
+ */
+export function extensions() {
+    const ret = wasm.extensions();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+
+/**
+ * Import HTML through the Rust HTML5 DOM and canonical Carve writer.
+ *
+ * Returns `{ value, report }`; `report.diagnostics` makes every lossy import
+ * decision observable. `roundtrip` is only safe for Carve-produced HTML.
+ * @param {string} source
+ * @param {string | null} [mode]
+ * @returns {any}
+ */
+export function htmlToCarve(source, mode) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    var ptr1 = isLikeNone(mode) ? 0 : passStringToWasm0(mode, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    const ret = wasm.htmlToCarve(ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Parse Carve source and return its AST as a JSON string.
+ *
+ * The PART 12 exchange shape (https://markup-carve.github.io/carve/ast-json):
+ * the same tree every Carve engine publishes, so a consumer written against
+ * one implementation reads another's output. The root carries exactly `type`,
+ * `children` and `srcByteLength`; frontmatter and footnote definitions are
+ * block nodes inside `children`, not root fields.
+ *
+ * Returns a STRING rather than a JS object: the caller runs `JSON.parse`, which
+ * is what a browser does natively and faster than building the object graph
+ * across the wasm boundary one property at a time. It also keeps the bytes
+ * available for a caller that stores or forwards them.
+ *
+ * Position tracking is on for this entry point and nowhere else. PART 12 §4
+ * lets an engine gate tracking behind a parse option but requires the
+ * serialized form to carry it, and rendering would pay for spans nobody reads.
+ * @param {string} source
+ * @returns {string}
+ */
+export function parseJson(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.parseJson(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
+ * @returns {string}
+ */
+export function toHtml(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.toHtml(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);
+    }
+}
+
+/**
+ * Render with the preview extension set enabled (`PREVIEW_EXTENSIONS`), so the
+ * WASM engine matches an extensions-on host such as the docs Playground rather
+ * than the core-only `toHtml`.
+ *
+ * The set is curated, not "everything the engine has": `heading-numbers` and
+ * `table-of-contents` rewrite a document that never asked for it, which is
+ * wrong for a preview. Callers who want an exact set pass `extensions` to
+ * `toHtmlWithOptions`, and `extensions()` reports what this build accepts.
+ *
+ * The optional second argument is the same **symbols map** as
+ * [`to_html_with_symbols`], with the same trusted-raw contract: mapped values
+ * are emitted UNESCAPED, so never feed it untrusted input.
+ * @param {string} source
+ * @param {object | null} [symbols]
+ * @returns {string}
+ */
+export function toHtmlFull(source, symbols) {
+    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.toHtmlFull(ptr0, len0, isLikeNone(symbols) ? 0 : addToExternrefTable0(symbols));
+        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 with an options object, the general form of the three shorthands
+ * above.
+ *
+ * ```js
+ * toHtmlWithOptions('# A\n\np\n', { sections: false })
+ * // '<h1 id="A">A</h1>\n<p>p</p>'
+ *
+ * toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
+ * ```
+ *
+ * Every field is optional:
+ *
+ * * `sections` (default `true`) - wrap each top-level heading, and the content
+ *   following it up to the next same-or-shallower heading, in a
+ *   `<section id="…">` (spec PART 9 §13). `false` renders headings flat with
+ *   the id back on the `<h*>` and the former section children as siblings.
+ *   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 - the
+ *   wrapper is the one output change a clean source migration still breaks.
+ * * `symbols` - the same map as [`to_html_with_symbols`], with the same
+ *   TRUSTED-RAW contract: mapped values are emitted UNESCAPED, so never build
+ *   it from untrusted input.
+ * * `extensions` - an array of extension names to enable, e.g.
+ *   `["glossary", "table-of-contents"]`. `extensions()` reports what this
+ *   build accepts. An unknown name throws: a silently ignored extension would
+ *   render as missing behavior that looks like a Carve bug. Takes precedence
+ *   over `full`.
+ * * `full` (default `false`) - enable the preview extension set instead of
+ *   rendering core-only.
+ *
+ * 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
+ * that is recognized does throw, because that changes behavior silently.
+ *
+ * Turning sections off changes nothing else. Ids, collision dedup, `</#id>`
+ * crossrefs, implicit `[Heading][]` references and heading numbering all
+ * resolve against the slug rather than the element carrying it, and the
+ * endnotes `<section role="doc-endnotes">` is a separate construct that is
+ * still emitted.
+ * @param {string} source
+ * @param {object | null} [options]
+ * @returns {string}
+ */
+export function toHtmlWithOptions(source, options) {
+    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.toHtmlWithOptions(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);
+    }
+}
+
+/**
+ * Render with the core profile and a **symbols map**: `{ rocket: "🚀" }` (a
+ * plain object or a `Map`). A `:name:` symbol whose name is in the map renders
+ * the mapped value; an unmapped `:name:` stays literal `:name:` text, and the
+ * leading word-boundary guard still applies (`a:b:c`, `10:30:`,
+ * `me@example.com` never become symbols).
+ *
+ * Names and values must both be strings; a non-string value throws a JS
+ * `TypeError`.
+ *
+ * SECURITY: a mapped value is inserted as **TRUSTED RAW output in the target
+ * format** - it is NOT escaped, the same trust class as the static `renderers`
+ * map. So `{ b: "<b>x</b>" }` emits a real `<b>` element, not escaped text.
+ * This is deliberate: processor configuration is trusted. NEVER build a
+ * symbols map out of untrusted / user-supplied input.
+ * @param {string} source
+ * @param {object | null} [symbols]
+ * @returns {string}
+ */
+export function toHtmlWithSymbols(source, symbols) {
+    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.toHtmlWithSymbols(ptr0, len0, isLikeNone(symbols) ? 0 : addToExternrefTable0(symbols));
+        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);
+    }
+}
+
+/**
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.version();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+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_is_null_344c8750a8525473(arg0) {
+    const ret = arg0 === null;
+    return ret;
+}
+export function __wbg___wbindgen_is_undefined_c0cca72b82b86f4d(arg0) {
+    const ret = arg0 === undefined;
+    return ret;
+}
+export function __wbg___wbindgen_string_get_914df97fcfa788f2(arg0, arg1) {
+    const obj = arg1;
+    const ret = typeof(obj) === 'string' ? obj : undefined;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg___wbindgen_throw_81fc77679af83bc6(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+}
+export function __wbg_entries_616b1a459b85be0b(arg0) {
+    const ret = Object.entries(arg0);
+    return ret;
+}
+export function __wbg_entries_7d89e479ff037f54(arg0) {
+    const ret = arg0.entries();
+    return ret;
+}
+export function __wbg_from_741da0f916ab74aa(arg0) {
+    const ret = Array.from(arg0);
+    return ret;
+}
+export function __wbg_get_4848e350b40afc16(arg0, arg1) {
+    const ret = arg0[arg1 >>> 0];
+    return ret;
+}
+export function __wbg_get_f96702c6245e4ef9() { return handleError(function (arg0, arg1) {
+    const ret = Reflect.get(arg0, arg1);
+    return ret;
+}, arguments); }
+export function __wbg_get_unchecked_7d7babe32e9e6a54(arg0, arg1) {
+    const ret = arg0[arg1 >>> 0];
+    return ret;
+}
+export function __wbg_instanceof_Map_a10a2795ef4bfe97(arg0) {
+    let result;
+    try {
+        result = arg0 instanceof Map;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
+export function __wbg_instanceof_Object_72ee0c53dd8f0726(arg0) {
+    let result;
+    try {
+        result = arg0 instanceof Object;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
+export function __wbg_isArray_db61795ad004c139(arg0) {
+    const ret = Array.isArray(arg0);
+    return ret;
+}
+export function __wbg_length_6e821edde497a532(arg0) {
+    const ret = arg0.length;
+    return ret;
+}
+export function __wbg_new_47dfee3855dec446(arg0, arg1) {
+    const ret = new TypeError(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
+export function __wbg_new_4f9fafbb3909af72() {
+    const ret = new Object();
+    return ret;
+}
+export function __wbg_parse_545d11396395fbbd() { return handleError(function (arg0, arg1) {
+    const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
+    return ret;
+}, arguments); }
+export function __wbg_set_8ee2d34facb8466e() { return handleError(function (arg0, arg1, arg2) {
+    const ret = Reflect.set(arg0, arg1, arg2);
+    return ret;
+}, arguments); }
+export function __wbindgen_cast_0000000000000001(arg0, arg1) {
+    // Cast intrinsic for `Ref(String) -> Externref`.
+    const ret = getStringFromWasm0(arg0, arg1);
+    return ret;
+}
+export function __wbindgen_init_externref_table() {
+    const table = wasm.__wbindgen_externrefs;
+    const offset = table.grow(4);
+    table.set(0, undefined);
+    table.set(offset + 0, undefined);
+    table.set(offset + 1, null);
+    table.set(offset + 2, true);
+    table.set(offset + 3, false);
+}
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+
+let wasm;
+export function __wbg_set_wasm(val) {
+    wasm = val;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@markup-carve/carve-wasm",
+  "type": "module",
+  "description": "WASM bindings for the Carve parser and HTML renderer.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markup-carve/carve-wasm"
+  },
+  "files": [
+    "carve_wasm_bg.wasm",
+    "carve_wasm.js",
+    "carve_wasm_bg.js",
+    "carve_wasm.d.ts"
+  ],
+  "main": "carve_wasm.js",
+  "homepage": "https://markup-carve.github.io/carve/",
+  "types": "carve_wasm.d.ts",
+  "sideEffects": [
+    "./carve_wasm.js",
+    "./snippets/*"
+  ]
+}