@markup-carve/carve-wasm 0.1.5 → 0.1.6

package/carve_wasm_bg.js

@@ -1,3 +1,72 @@
+/**
+ * A parser snapshot retained between editor updates. Call `free()` when done.
+ */
+export class ParserSession {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ParserSessionFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_parsersession_free(ptr, 0);
+    }
+    /**
+     * Apply byte edits; a rejected edit leaves the session unchanged.
+     * @param {string} changes
+     * @returns {string}
+     */
+    edit(changes) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(changes, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.parsersession_edit(this.__wbg_ptr, 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);
+        }
+    }
+    /**
+     * @param {string} source
+     */
+    constructor(source) {
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.parsersession_new(ptr0, len0);
+        this.__wbg_ptr = ret >>> 0;
+        ParserSessionFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * The current result, with byte ranges and parser-work counters.
+     * @returns {string}
+     */
+    snapshot() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.parsersession_snapshot(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) ParserSession.prototype[Symbol.dispose] = ParserSession.prototype.free;
+
 /**
  * Replay patch JSON onto a PART 12 tree, returning the result as AST JSON.
  * @param {string} ast
@@ -99,7 +168,7 @@ export function applyReversibleAstPatch(ast, patch, inverse) {
 /**
  * Apply a trusted patch after its source length and fingerprint still match.
  * @param {string} source
- * @param {any} patch
+ * @param {SourcePatch} patch
  * @returns {string}
  */
 export function applySourcePatch(source, patch) {
@@ -127,7 +196,7 @@ export function applySourcePatch(source, patch) {
  * Render an AST-JSON document (PART 12) to ANSI-styled text. See
  * [`ast_json_to_markdown`], including what a tree without positions costs.
  * @param {string} json
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function astJsonToAnsi(json, options) {
@@ -191,7 +260,7 @@ export function astJsonToCarve(json) {
  * 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]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function astJsonToHtml(json, options) {
@@ -235,7 +304,7 @@ export function astJsonToHtml(json, options) {
  * order available to a tree without spans, so it is reported here rather than
  * repaired.
  * @param {string} json
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function astJsonToMarkdown(json, options) {
@@ -263,7 +332,7 @@ export function astJsonToMarkdown(json, options) {
  * Render an AST-JSON document (PART 12) to plain text. See
  * [`ast_json_to_markdown`], including what a tree without positions costs.
  * @param {string} json
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function astJsonToPlainText(json, options) {
@@ -438,7 +507,7 @@ export function createSourcePatch(source, replacement, kind, code) {
  * and a span on a node that came from a child would point into a source the
  * caller did not pass.
  * @param {string} source
- * @param {object} options
+ * @param {IncludeOptions} options
  * @returns {IncludeExpansion}
  */
 export function expandIncludes(source, options) {
@@ -666,8 +735,9 @@ export function lintAccessibility(source) {
  *
  * 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.
+ * same id everywhere. Offsets count UTF-16 CODE UNITS, so they index the
+ * JavaScript string the caller holds; the engine answers in bytes and this
+ * wrapper converts (#164).
  *
  * 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.
@@ -690,8 +760,8 @@ export function lintCarve(source) {
  * `lintCarve` is the option-less form. Which degradations exist depends on the
  * extensions in play, so a host that renders with a set has to lint with it.
  * @param {string} source
- * @param {object | null} [options]
- * @returns {LintWarning[]}
+ * @param {RenderOptions | null} options
+ * @returns {any}
  */
 export function lintCarveWithOptions(source, options) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -872,7 +942,7 @@ export function parseJson(source) {
  * `positions` is not read: every serialized tree this binding produces carries
  * them, as in [`parse_json`].
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function parseJsonWithOptions(source, options) {
@@ -995,8 +1065,8 @@ export function readStamp(source) {
  *
  * `changes` is a JSON array of `{ range: [start, end], replacement }`.
  *
- * THE OFFSETS ARE UTF-8 BYTE OFFSETS, which is what `parseJson` positions and
- * `createSourcePatch` ranges already mean. A browser editor counts UTF-16 code
+ * THE OFFSETS ARE UTF-8 BYTE OFFSETS, matching `createSourcePatch` ranges.
+ * `parseJson` positions count Unicode codepoints instead. A browser editor counts UTF-16 code
  * units, so a host holding a `selectionStart` converts before calling - an
  * offset that lands inside a multi-byte character is refused rather than
  * guessed at.
@@ -1006,9 +1076,9 @@ export function readStamp(source) {
  * result the caller asked for.
  *
  * `reusedPreviousTree` says whether the parse reused any of the previous one.
- * The pinned engine always reports `false` - it validates and applies the
- * edits and then parses the whole source - so a host should read this as the
- * engine's own answer rather than assume work was saved.
+ * The engine can reuse unchanged plain paragraphs. Other syntax falls back
+ * to a full parse. This function rebuilds the initial snapshot from source;
+ * use a parser session to retain it across edits.
  * @param {string} source
  * @param {string} changes
  * @returns {string}
@@ -1122,7 +1192,7 @@ export function toAnsi(source) {
  * Render to ANSI text with an options object. See
  * [`to_markdown_with_options`].
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function toAnsiWithOptions(source, options) {
@@ -1148,14 +1218,14 @@ export function toAnsiWithOptions(source, options) {
 
 /**
  * @param {string} source
- * @param {boolean | null} [strict]
- * @param {number | null} [maximum]
+ * @param {boolean | null} strict
+ * @param {number | null} maximum
  * @returns {any}
  */
 export function toAnsiWithReport(source, strict, maximum) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.toAnsiWithReport(ptr0, len0, isLikeNone(strict) ? 0xFFFFFF : strict ? 1 : 0, isLikeNone(maximum) ? 0x100000001 : (maximum) >>> 0);
+    const ret = wasm.toAnsiWithReport(ptr0, len0, isLikeNone(strict) ? 0 : addToExternrefTable0(strict), isLikeNone(maximum) ? 0 : addToExternrefTable0(maximum));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -1202,7 +1272,7 @@ export function toCarvePatch(source) {
  * `profile` is the only option this target reads; see
  * [`to_markdown_with_options`] for why.
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function toCarveWithOptions(source, options) {
@@ -1228,14 +1298,14 @@ export function toCarveWithOptions(source, options) {
 
 /**
  * @param {string} source
- * @param {boolean | null} [strict]
- * @param {number | null} [maximum]
+ * @param {boolean | null} strict
+ * @param {number | null} maximum
  * @returns {any}
  */
 export function toCarveWithReport(source, strict, maximum) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.toCarveWithReport(ptr0, len0, isLikeNone(strict) ? 0xFFFFFF : strict ? 1 : 0, isLikeNone(maximum) ? 0x100000001 : (maximum) >>> 0);
+    const ret = wasm.toCarveWithReport(ptr0, len0, isLikeNone(strict) ? 0 : addToExternrefTable0(strict), isLikeNone(maximum) ? 0 : addToExternrefTable0(maximum));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -1379,7 +1449,7 @@ export function toHtmlFull(source, symbols) {
  * endnotes `<section role="doc-endnotes">` is a separate construct that is
  * still emitted.
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function toHtmlWithOptions(source, options) {
@@ -1461,8 +1531,8 @@ export function toHtmlWithOptions(source, options) {
  * string with nowhere to put that, and so it rejects `renderers` rather than
  * dropping the failures.
  * @param {string} source
- * @param {object | null} [options]
- * @returns {StaticRenderResult}
+ * @param {StaticRenderOptions | null} options
+ * @returns {any}
  */
 export function toHtmlWithRenderers(source, options) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -1476,14 +1546,14 @@ export function toHtmlWithRenderers(source, options) {
 
 /**
  * @param {string} source
- * @param {boolean | null} [strict]
- * @param {number | null} [maximum]
+ * @param {boolean | null} strict
+ * @param {number | null} maximum
  * @returns {any}
  */
 export function toHtmlWithReport(source, strict, maximum) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.toHtmlWithReport(ptr0, len0, isLikeNone(strict) ? 0xFFFFFF : strict ? 1 : 0, isLikeNone(maximum) ? 0x100000001 : (maximum) >>> 0);
+    const ret = wasm.toHtmlWithReport(ptr0, len0, isLikeNone(strict) ? 0 : addToExternrefTable0(strict), isLikeNone(maximum) ? 0 : addToExternrefTable0(maximum));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -1571,7 +1641,7 @@ export function toMarkdown(source) {
  * `smartTypography` are inert there. They are accepted rather than refused
  * because one options object is meant to serve every target.
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function toMarkdownWithOptions(source, options) {
@@ -1597,14 +1667,14 @@ export function toMarkdownWithOptions(source, options) {
 
 /**
  * @param {string} source
- * @param {boolean | null} [strict]
- * @param {number | null} [maximum]
+ * @param {boolean | null} strict
+ * @param {number | null} maximum
  * @returns {any}
  */
 export function toMarkdownWithReport(source, strict, maximum) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.toMarkdownWithReport(ptr0, len0, isLikeNone(strict) ? 0xFFFFFF : strict ? 1 : 0, isLikeNone(maximum) ? 0x100000001 : (maximum) >>> 0);
+    const ret = wasm.toMarkdownWithReport(ptr0, len0, isLikeNone(strict) ? 0 : addToExternrefTable0(strict), isLikeNone(maximum) ? 0 : addToExternrefTable0(maximum));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -1634,7 +1704,7 @@ export function toPlainText(source) {
  * Render to plain text with an options object. See
  * [`to_markdown_with_options`].
  * @param {string} source
- * @param {object | null} [options]
+ * @param {RenderOptions | null} options
  * @returns {string}
  */
 export function toPlainTextWithOptions(source, options) {
@@ -1660,14 +1730,14 @@ export function toPlainTextWithOptions(source, options) {
 
 /**
  * @param {string} source
- * @param {boolean | null} [strict]
- * @param {number | null} [maximum]
+ * @param {boolean | null} strict
+ * @param {number | null} maximum
  * @returns {any}
  */
 export function toPlainTextWithReport(source, strict, maximum) {
     const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.toPlainTextWithReport(ptr0, len0, isLikeNone(strict) ? 0xFFFFFF : strict ? 1 : 0, isLikeNone(maximum) ? 0x100000001 : (maximum) >>> 0);
+    const ret = wasm.toPlainTextWithReport(ptr0, len0, isLikeNone(strict) ? 0 : addToExternrefTable0(strict), isLikeNone(maximum) ? 0 : addToExternrefTable0(maximum));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -2023,6 +2093,10 @@ export function __wbindgen_init_externref_table() {
     table.set(offset + 2, true);
     table.set(offset + 3, false);
 }
+const ParserSessionFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_parsersession_free(ptr >>> 0, 1));
+
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
     wasm.__wbindgen_externrefs.set(idx, obj);

package/docs/compatibility.md

@@ -0,0 +1,89 @@
+# Package compatibility
+
+The release tarball contains these entry points:
+
+| Import | Initialization | Intended host |
+| --- | --- | --- |
+| `@markup-carve/carve-wasm` | Automatic | Node or a browser bundler with native WASM imports |
+| `@markup-carve/carve-wasm/node` | Automatic | Node ESM and CommonJS |
+| `@markup-carve/carve-wasm/web` | `await init()` | Browser modules and module workers |
+| `@markup-carve/carve-wasm/render` | `await init()` | Browser hosts that only render HTML |
+| `@markup-carve/carve-wasm/offsets` | None | UTF-16, UTF-8 and codepoint boundary conversion |
+
+The root export selects the Node entry through the `node` condition. Browser
+bundlers select the bundler entry. A bundler that enables Node conditions for a
+browser build should use `/web` explicitly.
+
+## Browser modules
+
+Resolve the package through a bundler or serve the package directory, retaining
+its hierarchy. The full entry points share the package-root WASM file. Initialization is asynchronous; rendering after it is
+synchronous.
+
+```js
+import init, { toHtmlWithOptions } from '@markup-carve/carve-wasm/web'
+await init()
+const html = toHtmlWithOptions(source, { rawHtml: false, profile: 'comment' })
+```
+
+The rendering-only entry uses the same pattern. It has no parser JSON,
+importers, reports, includes or editor APIs. Both entries export a default
+initializer that can take the WASM module or URL when the default relative URL
+is unsuitable. Serve `.wasm` as `application/wasm` for streaming compilation.
+
+CI installs the npm tarball and tests Vite 8.3.2 production bundles in
+Chromium, Firefox and WebKit through Playwright 1.61.1. Vite's build target is
+`esnext` because these entries use top-level await. Earlier Vite releases may
+need a WASM plugin for the root bundler entry; they are outside this tested
+matrix. This matrix does not establish a minimum browser version.
+
+## Node and TypeScript
+
+Node 22 is tested with both `import` and `require`. The Node build loads its
+package-root WASM file synchronously, so copying only its JavaScript file fails.
+
+TypeScript 5.9.3 is tested with `strict: true`, `skipLibCheck: false` and
+`NodeNext` module resolution against the installed tarball. wasm-bindgen emits
+`Symbol.dispose` declarations for `ParserSession`; include `ESNext.Disposable`
+in `compilerOptions.lib` when the rest of the project targets ES2022. Explicit
+`session.free()` remains supported.
+
+## Editors and workers
+
+Edit ranges use UTF-8 byte offsets. Browser selection ranges use UTF-16 code
+units; AST positions use Unicode codepoints. Convert against the source the
+edit applies to, before sending it to a worker. See `/offsets` and the
+[incremental API reference](reference.md#re-parsing-while-someone-types).
+
+[carve-worker.mjs](../examples/carve-worker.mjs) initializes `/web` once and
+retains one `ParserSession`. Messages carry `id` and `action`: `open` takes
+`source`, `edit` takes `changes`, `render` takes `source`, and `close` frees the
+session. Replies contain `value` or `error`. The consumer suite tests this
+protocol in each browser. Create it with a bundler-resolved module worker:
+
+```js
+const worker = new Worker(new URL('./carve-worker.mjs', import.meta.url), {
+  type: 'module',
+})
+```
+
+Copy the example into the application beside this call. Free retained sessions
+when documents close, and terminate workers when the host closes them.
+
+## Fidelity and resource limits
+
+HTML import projects through a DOM and cannot retain all Carve source
+constructs. Its `roundtrip` mode is for trusted Carve-produced HTML. The corpus
+ledger records output differences, while the stability gate requires a second
+import to settle. Inspect conversion reports before accepting imported source.
+Markdown, Djot and BBCode migration reports still mark fidelity as unverified.
+
+ProseMirror reports dropped nodes, degraded nodes and canonical source changes.
+A nonempty report requires a host decision before replacing the original
+source. Preserve the original source when an editor cannot represent it.
+
+The engine limits nesting to 200 levels. CI checks that depth in browsers and
+measures the Node stack needed by serialization separately. Larger documents
+still consume synchronous CPU time; move work into a worker when it would block
+an editor. `scripts/benchmark.mjs` measures the shipped package, but its elapsed
+times are machine-dependent and are not latency guarantees.