@takazudo/zfb-md-wasm 0.1.0-next.80

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+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,217 @@
+# @takazudo/zfb-md-wasm
+
+A WebAssembly build of [zfb](https://github.com/Takazudo/zudo-front-builder)'s
+markdown / MDX → JavaScript conversion pipeline, for **browser-side dynamic
+conversion**. The headline use case is **CMS live preview**: convert MDX to a
+runnable ES module (or markdown to HTML) in the browser, on every keystroke,
+with output **parity** to what zfb produces at build time.
+
+Parity is the reason this package exists instead of running
+[`@mdx-js/mdx`](https://mdxjs.com/) in the browser: `@mdx-js/mdx` is a
+_different_ pipeline, so its preview would not match zfb's built output.
+`zfb-md-wasm` compiles the same Rust pipeline zfb itself uses, so a preview is
+faithful to the real thing.
+
+Node ≥ 20 can also load the package (this is what the test suite uses), but the
+browser is the target. A server with shell access should keep calling the `zfb`
+binary directly.
+
+## Install
+
+```sh
+pnpm add @takazudo/zfb-md-wasm
+```
+
+## Two API tiers
+
+Both functions take the markdown/MDX `source` and an options object (every
+field optional; `{}` selects all defaults). Both return a result object plus a
+`diagnostics` array — **expected failures come back as diagnostics, never as a
+thrown error** (see the trap contract below for what _does_ throw).
+
+### `compile(source, options?)` — MDX → ES-module JS
+
+Full MDX → JSX → SWC → ES module. The emitted module has a `MDXContent`
+default export (a component function) using the automatic JSX runtime.
+
+```ts
+import { compile } from "@takazudo/zfb-md-wasm";
+
+const { code, frontmatter, diagnostics } = await compile(
+  "---\ntitle: Hello\n---\n\n# Welcome\n\n<Callout>Sum is {1 + 2}</Callout>\n",
+  { filename: "post.mdx", jsxRuntime: "preact" },
+);
+// code        -> ES-module JS source (string) or null on failure
+// frontmatter -> { title: "Hello" }
+// diagnostics -> []
+```
+
+Frontmatter values are returned in the `frontmatter` field — they are **not**
+exposed as an in-content binding. The compiled module has no `frontmatter`
+variable in scope, so a `{frontmatter.title}` reference inside the source
+would throw `ReferenceError` at runtime; read the values from the result
+object instead.
+
+### `renderHtml(source, options?)` — markdown → HTML
+
+Markdown → hast → HTML string, **skipping SWC at runtime**. Use this for a
+plain-markdown preview when you don't need to evaluate a component module.
+
+```ts
+import { renderHtml } from "@takazudo/zfb-md-wasm";
+
+const { html, frontmatter, diagnostics } = await renderHtml(
+  "# Heading\n\nSome **bold** text.\n",
+  { filename: "post.md" },
+);
+// html -> "<h1>Heading</h1><p>Some <strong>bold</strong> text.</p>"
+```
+
+`renderHtml` accepts and ignores `jsxRuntime` / `development`, so one options
+object can serve both tiers.
+
+### `version()` / `init()`
+
+`version()` returns the package version for host-side compatibility checks.
+Published artifacts are stamped with the release semver at build time; local
+development builds fall back to the Rust manifest placeholder.
+`init()` eagerly loads and instantiates the wasm module; it's optional (every
+call instantiates on first use) but useful to front-load the one-time
+fetch/compile cost at app startup.
+
+## Options shape
+
+```ts
+interface ZfbMdWasmOptions {
+  filename?: string;              // must end .md/.mdx; drives frontmatter dispatch + diagnostics
+  jsxRuntime?: "preact" | "react"; // compile only; default "preact"
+  development?: boolean;          // compile only; default false
+  pipeline?: {
+    theme?: string | null;        // a syntect theme name, or null for no highlighting
+    gfm?: {
+      strikethrough?: boolean; table?: boolean; autolinkLiteral?: boolean;
+      taskListItem?: boolean; footnoteDefinition?: boolean;
+    };
+    cjkFriendly?: boolean;
+    hardBreaks?: boolean;
+    features?: Record<string, unknown>; // zfb's MarkdownFeaturesConfig, verbatim
+  };
+}
+```
+
+`pipeline` is zfb's **resolved features config** as JSON — the same shape zfb
+derives from `zfb.config.ts` at build time. See "Limitations" for why it's
+resolved JSON rather than a config file. Unknown fields are rejected at both
+nesting levels (an `options`-source diagnostic).
+
+## Evaluating compiled modules in a browser
+
+`compile()` returns ES-module _source_. To run it, turn it into a module (a
+blob URL is the usual trick) and dynamic-import it:
+
+```ts
+const { code, diagnostics } = await compile(source, { filename: "preview.mdx" });
+if (code === null) {
+  // Compilation failed — render `diagnostics` instead of a module.
+  return;
+}
+const url = URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
+const { default: MDXContent } = await import(/* @vite-ignore */ url);
+URL.revokeObjectURL(url);
+// render <MDXContent components={{ Callout }} /> with your framework
+```
+
+Pass your PascalCase components (the `<Callout>` in the source above) through
+the module's `components` prop.
+
+### ⚠️ You must supply the JSX runtime — and the preact case needs one alias
+
+The compiled module imports its JSX runtime by bare specifier
+(`preact/jsx-runtime` or `react/jsx-runtime`), so the page must resolve those —
+via an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
+or your bundler.
+
+**There is one asymmetry to know about.** zfb's emitter takes the JSX _factory_
+from your chosen runtime but **always imports `Fragment` from
+`react/jsx-runtime`**, regardless of `jsxRuntime`. This is zfb's production
+emitter shape (so it's parity-correct, not a bug) — but it means a **preact**
+consumer must alias `react/jsx-runtime` onto preact's, or `Fragment` will fail
+to resolve at runtime:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "preact/jsx-runtime": "https://esm.sh/preact/jsx-runtime",
+      "react/jsx-runtime": "https://esm.sh/preact/jsx-runtime"
+    }
+  }
+</script>
+```
+
+A `react` consumer just maps `react/jsx-runtime` to React's own and needs no
+alias.
+
+## Node usage
+
+For tests and tooling, the package loads and runs under Node ≥ 20 with no extra
+setup — the same `compile` / `renderHtml` / `version` API. This is exactly how
+this package's own vitest suite exercises the wasm.
+
+## Parity guarantee & limitations
+
+Output matches zfb's native pipeline on a fixed fixture corpus (the parity
+suite gates exact-match). Deliberate limitations of the browser build:
+
+- **Filesystem-bound plugins are inert.** `transclude`, `imageDimensions`, and
+  `linkValidation` are registered but never touch a filesystem (there is none),
+  exactly as zfb's own MDX loader runs them with build-context roots unarmed.
+  Host-callback versions are a possible future epic.
+- **Config is resolved JSON, not `zfb.config.ts`.** Evaluating a TypeScript
+  config needs a JS engine; that stays build-side. Resolve your config to JSON
+  first and pass it as `pipeline`.
+- **No cross-file features.** Route-table link resolution and cross-file anchor
+  resolution need the whole project graph, which a single-document browser call
+  doesn't have.
+- **The single artifact carries SWC even for `renderHtml`-only use.** One
+  cdylib can't tree-shake SWC away when only `renderHtml` is called; a slim
+  `renderHtml`-only artifact is a documented possible follow-up.
+- **Syntax highlighting uses syntect's `fancy-regex` backend** (native zfb uses
+  `oniguruma`, which can't compile to wasm). The two are byte-identical on
+  zfb's fixture corpus; any grammar-level divergences are tracked in the
+  crate's informational backend-divergence test.
+
+## Artifact size
+
+Shipping SWC in the bytes makes this a large module. The build applies a
+size-optimized cargo profile (`opt-level = "z"`, LTO, one codegen unit,
+`panic = "abort"`) plus `wasm-opt`, which roughly halves the raw binary. The
+current build produces **~2.9 MB raw / ~1.3 MB gzipped** for the `.wasm`. The CI
+`wasm-md` job prints the authoritative gzipped size on every run — treat that
+as the source of truth rather than this figure, which can drift.
+
+## Error / trap / re-init contract
+
+- **Expected failures never throw.** Parse errors, malformed options JSON,
+  unknown themes, a bad filename — all come back as structured `Diagnostic[]`
+  entries (`{ severity, source, message, line, column }`) on a normal result,
+  with `code` / `html` set to `null`. `line`/`column` are 1-based; for
+  `markdown` / `frontmatter` sources they point into the original source, for
+  `options` into the options JSON.
+- **A wasm _trap_ is always a bug, and it poisons the instance.** On
+  `wasm32-unknown-unknown` a Rust panic (or other internal fault) lowers to a
+  wasm trap; `catch_unwind` is not reliable recovery, so the instance is dead
+  afterward. This wrapper handles that for you: it catches the
+  `WebAssembly.RuntimeError`, **drops the poisoned instance and re-instantiates
+  a fresh one in the background** (from the cached compiled module, so no
+  recompile), and throws a `ZfbMdWasmTrapError` for that one call. The next
+  `compile` / `renderHtml` / `version` call transparently uses the fresh
+  instance. The API is stateless per call, so re-init is lossless.
+
+  If you ever see a `ZfbMdWasmTrapError`, please report it with the input that
+  triggered it — the crate is designed never to trap on structured input.
+  (Fuzzing the trap surface is a documented follow-up.)
+
+## License
+
+MIT © Takeshi Takatsudo

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import type { CompileResult, RenderHtmlResult, ZfbMdWasmOptions } from "./types.js";
+/**
+ * Thrown when a wasm call traps (a Rust panic, or another internal fault
+ * that lowers to a wasm trap). This is always a bug, never an expected
+ * input-validation failure -- expected failures (parse errors, malformed
+ * options JSON, unknown themes, ...) come back as structured
+ * `Diagnostic[]` in a normal `CompileResult`/`RenderHtmlResult`, never as a
+ * thrown error. See this package's README "Error / trap / re-init
+ * contract" section.
+ *
+ * By the time this is thrown, the poisoned instance has already been dropped
+ * and a replacement has been instantiated (from the cached compiled module, so
+ * no recompile). Concurrent trap reporters for the same poisoned generation
+ * wait for that same replacement instead of each starting another one; the
+ * next `compile` / `renderHtml` / `version` call transparently uses the fresh
+ * instance.
+ */
+export declare class ZfbMdWasmTrapError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Thrown once this wrapper has already recovered from too many wasm traps in
+ * one module lifetime. ES module records cannot be evicted, and wasm-bindgen
+ * `--target web` glue cannot be safely re-used after initialization, so the
+ * only bounded behavior after repeated poisoning is to stop recovering and ask
+ * the host to reload/recreate the JS realm before trying again.
+ */
+export declare class ZfbMdWasmTrapRecoveryLimitError extends Error {
+    constructor(maxRecoveries: number, cause: unknown);
+}
+/**
+ * Eagerly loads and instantiates the wasm module. Optional -- `compile` /
+ * `renderHtml` / `version` all call this implicitly on first use -- but
+ * useful to front-load the one-time fetch/compile cost, e.g. on app
+ * startup before the first user-triggered call.
+ */
+export declare function init(): Promise<void>;
+/**
+ * Compile MDX source into ES-module JavaScript. Mirrors the crate's
+ * `compile(source, options_json) -> string` export, with JSON
+ * marshaling handled for you.
+ */
+export declare function compile(source: string, options?: ZfbMdWasmOptions): Promise<CompileResult>;
+/**
+ * Render markdown source to an HTML fragment (no SWC at runtime). Mirrors
+ * the crate's `renderHtml(source, options_json) -> string` export, with
+ * JSON marshaling handled for you.
+ */
+export declare function renderHtml(source: string, options?: ZfbMdWasmOptions): Promise<RenderHtmlResult>;
+/**
+ * Package version for host-side compatibility checks.
+ *
+ * Release artifacts are stamped with the published package semver at build
+ * time; local development builds fall back to the Rust manifest placeholder.
+ */
+export declare function version(): Promise<string>;
+/**
+ * @internal Test-only (zfb#1577's trap/re-init test). Forces a genuine wasm
+ * trap on the currently-active instance by invoking its raw `compile` export
+ * with a garbage return pointer, so the result-doubleword `i32.store` lands
+ * outside the instance's linear memory -- a `WebAssembly.RuntimeError:
+ * memory access out of bounds`. From the JS host's point of view this is
+ * the same exception class a real Rust panic->unreachable trap produces
+ * (both are `instanceof WebAssembly.RuntimeError`), which is what
+ * `callWasm`'s catch clause keys on -- so this exercises the real
+ * catch-and-reinstantiate path without needing to coax an actual Rust panic
+ * out of a crate that is deliberately designed to never panic on structured
+ * input. This is NOT part of the supported public API: it is a named export
+ * of the package entry, so a `import { __forceTrapForTests } from
+ * "@takazudo/zfb-md-wasm"` does resolve -- but the `__`-prefix marks it
+ * internal, and the raw ABI details it pokes at (argument order, retptr
+ * convention) are wasm-bindgen internals that can change on a wasm-bindgen
+ * version bump. Do not call it outside this package's own tests.
+ */
+export declare function __forceTrapForTests(): Promise<void>;
+/**
+ * @internal Test-only observability for the trap recovery contract. This is a
+ * named export only so the built-package Vitest suite can assert the public
+ * wrapper's concurrency/cap behavior without mocking the wasm-bindgen glue.
+ */
+export declare function __getTrapRecoveryStateForTests(): {
+    currentGeneration: number;
+    freshInstanceStarts: number;
+    maxTrapRecoveries: number;
+    trapRecoveriesStarted: number;
+    terminal: boolean;
+};
+export type { CompileResult, RenderHtmlResult, Diagnostic, DiagnosticSource, ZfbMdWasmOptions, PipelineOptions, GfmOptions, MarkdownFeaturesConfig, JsxRuntime, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,229 @@
+const GLUE_URL = new URL("./wasm/zfb_md_wasm.js", import.meta.url);
+const WASM_URL = new URL("./wasm/zfb_md_wasm_bg.wasm", import.meta.url);
+function isNode() {
+    return typeof process !== "undefined" && !!process.versions?.node;
+}
+// Node's built-in `fetch` does not support `file:` URLs, so the wasm bytes
+// must be read from disk directly there; browsers (and other fetch-capable
+// hosts, e.g. a bundler-served dev server) go through `fetch` against the
+// module-relative URL, which is the standard wasm-bindgen `--target web`
+// browser consumption path.
+async function loadWasmBytes() {
+    if (isNode()) {
+        const [{ readFile }, { fileURLToPath }] = await Promise.all([
+            import("node:fs/promises"),
+            import("node:url"),
+        ]);
+        const buf = await readFile(fileURLToPath(WASM_URL));
+        return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    }
+    const res = await fetch(WASM_URL);
+    if (!res.ok) {
+        throw new Error(`zfb-md-wasm: failed to fetch wasm binary: ${res.status} ${res.statusText}`);
+    }
+    return res.arrayBuffer();
+}
+let compiledModulePromise;
+function getCompiledModule() {
+    compiledModulePromise ??= loadWasmBytes().then((bytes) => WebAssembly.compile(bytes));
+    return compiledModulePromise;
+}
+const MAX_TRAP_RECOVERIES = 16;
+let currentGeneration = 0;
+let trapRecoveriesStarted = 0;
+let freshInstanceStarts = 0;
+let terminalTrapRecoveryError;
+/**
+ * Instantiates a fresh copy of the wasm-bindgen glue module.
+ *
+ * wasm-bindgen's `--target web` output guards `init`/`initSync` with an
+ * "already initialized" early return keyed on a module-scope singleton, so
+ * recovering from a trapped (poisoned) instance requires a genuinely fresh ES
+ * module record -- re-calling `initSync` on the existing module record is a
+ * no-op. Re-importing the same specifier with a distinct query string yields a
+ * new module record per the ECMAScript module spec (Node and browsers agree on
+ * this); the underlying `WebAssembly.Module` (compiled code) is cached and
+ * reused via `getCompiledModule`, so this only re-runs cheap instantiation,
+ * never a recompile. Module-record growth is bounded by
+ * `MAX_TRAP_RECOVERIES`: once that many poisoned instances have been replaced,
+ * recovery stops permanently and callers receive
+ * `ZfbMdWasmTrapRecoveryLimitError` instead of minting another module record.
+ */
+async function freshInstance(generation) {
+    freshInstanceStarts += 1;
+    const [module, glue] = await Promise.all([
+        getCompiledModule(),
+        import(
+        /* @vite-ignore */ `${GLUE_URL.href}?zfbMdWasmGen=${generation}`),
+    ]);
+    const raw = glue.initSync({ module });
+    return { generation, glue, raw };
+}
+let instancePromise;
+function getInstance() {
+    if (terminalTrapRecoveryError) {
+        return Promise.reject(terminalTrapRecoveryError);
+    }
+    instancePromise ??= freshInstance(currentGeneration);
+    return instancePromise;
+}
+/**
+ * Thrown when a wasm call traps (a Rust panic, or another internal fault
+ * that lowers to a wasm trap). This is always a bug, never an expected
+ * input-validation failure -- expected failures (parse errors, malformed
+ * options JSON, unknown themes, ...) come back as structured
+ * `Diagnostic[]` in a normal `CompileResult`/`RenderHtmlResult`, never as a
+ * thrown error. See this package's README "Error / trap / re-init
+ * contract" section.
+ *
+ * By the time this is thrown, the poisoned instance has already been dropped
+ * and a replacement has been instantiated (from the cached compiled module, so
+ * no recompile). Concurrent trap reporters for the same poisoned generation
+ * wait for that same replacement instead of each starting another one; the
+ * next `compile` / `renderHtml` / `version` call transparently uses the fresh
+ * instance.
+ */
+export class ZfbMdWasmTrapError extends Error {
+    constructor(cause) {
+        super("zfb-md-wasm: the wasm instance trapped (a Rust panic or internal fault) and has been " +
+            "automatically re-instantiated. This is always a bug in zfb-md-wasm -- please report it " +
+            "with the input that triggered it.");
+        this.name = "ZfbMdWasmTrapError";
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown once this wrapper has already recovered from too many wasm traps in
+ * one module lifetime. ES module records cannot be evicted, and wasm-bindgen
+ * `--target web` glue cannot be safely re-used after initialization, so the
+ * only bounded behavior after repeated poisoning is to stop recovering and ask
+ * the host to reload/recreate the JS realm before trying again.
+ */
+export class ZfbMdWasmTrapRecoveryLimitError extends Error {
+    constructor(maxRecoveries, cause) {
+        super(`zfb-md-wasm: wasm trap recovery limit reached after ${maxRecoveries} ` +
+            `successful re-instantiations. Further automatic recovery is disabled to avoid ` +
+            `unbounded ES module record growth. Reload the JS realm before using zfb-md-wasm ` +
+            `again, and please report the input that triggered the repeated traps.`);
+        this.name = "ZfbMdWasmTrapRecoveryLimitError";
+        this.cause = cause;
+    }
+}
+function isTrap(err) {
+    return typeof WebAssembly !== "undefined" && err instanceof WebAssembly.RuntimeError;
+}
+async function recoverAfterTrap(observedGeneration, cause) {
+    if (terminalTrapRecoveryError) {
+        throw terminalTrapRecoveryError;
+    }
+    // CAS-style single-flight: only the reporter that observed the currently
+    // active generation advances it and starts a fresh instantiation. Other
+    // concurrent reporters trapped on an older instance, so they await the
+    // already-started replacement instead of minting another module record.
+    if (observedGeneration !== currentGeneration) {
+        await getInstance();
+        return;
+    }
+    if (trapRecoveriesStarted >= MAX_TRAP_RECOVERIES) {
+        terminalTrapRecoveryError = new ZfbMdWasmTrapRecoveryLimitError(MAX_TRAP_RECOVERIES, cause);
+        instancePromise = undefined;
+        throw terminalTrapRecoveryError;
+    }
+    trapRecoveriesStarted += 1;
+    currentGeneration += 1;
+    instancePromise = freshInstance(currentGeneration);
+    await instancePromise;
+}
+async function callWasm(fn) {
+    const instance = await getInstance();
+    try {
+        return fn(instance);
+    }
+    catch (err) {
+        if (!isTrap(err)) {
+            throw err;
+        }
+        // Drop the poisoned instance and re-instantiate it from the cached compiled
+        // module. Concurrent trap reporters single-flight through the same
+        // generation advance, so one poisoned generation creates at most one fresh
+        // module record.
+        await recoverAfterTrap(instance.generation, err);
+        throw new ZfbMdWasmTrapError(err);
+    }
+}
+/**
+ * Eagerly loads and instantiates the wasm module. Optional -- `compile` /
+ * `renderHtml` / `version` all call this implicitly on first use -- but
+ * useful to front-load the one-time fetch/compile cost, e.g. on app
+ * startup before the first user-triggered call.
+ */
+export async function init() {
+    await getInstance();
+}
+/**
+ * Compile MDX source into ES-module JavaScript. Mirrors the crate's
+ * `compile(source, options_json) -> string` export, with JSON
+ * marshaling handled for you.
+ */
+export async function compile(source, options = {}) {
+    const optionsJson = JSON.stringify(options);
+    const json = await callWasm(({ glue }) => glue.compile(source, optionsJson));
+    return JSON.parse(json);
+}
+/**
+ * Render markdown source to an HTML fragment (no SWC at runtime). Mirrors
+ * the crate's `renderHtml(source, options_json) -> string` export, with
+ * JSON marshaling handled for you.
+ */
+export async function renderHtml(source, options = {}) {
+    const optionsJson = JSON.stringify(options);
+    const json = await callWasm(({ glue }) => glue.renderHtml(source, optionsJson));
+    return JSON.parse(json);
+}
+/**
+ * Package version for host-side compatibility checks.
+ *
+ * Release artifacts are stamped with the published package semver at build
+ * time; local development builds fall back to the Rust manifest placeholder.
+ */
+export async function version() {
+    return callWasm(({ glue }) => glue.version());
+}
+/**
+ * @internal Test-only (zfb#1577's trap/re-init test). Forces a genuine wasm
+ * trap on the currently-active instance by invoking its raw `compile` export
+ * with a garbage return pointer, so the result-doubleword `i32.store` lands
+ * outside the instance's linear memory -- a `WebAssembly.RuntimeError:
+ * memory access out of bounds`. From the JS host's point of view this is
+ * the same exception class a real Rust panic->unreachable trap produces
+ * (both are `instanceof WebAssembly.RuntimeError`), which is what
+ * `callWasm`'s catch clause keys on -- so this exercises the real
+ * catch-and-reinstantiate path without needing to coax an actual Rust panic
+ * out of a crate that is deliberately designed to never panic on structured
+ * input. This is NOT part of the supported public API: it is a named export
+ * of the package entry, so a `import { __forceTrapForTests } from
+ * "@takazudo/zfb-md-wasm"` does resolve -- but the `__`-prefix marks it
+ * internal, and the raw ABI details it pokes at (argument order, retptr
+ * convention) are wasm-bindgen internals that can change on a wasm-bindgen
+ * version bump. Do not call it outside this package's own tests.
+ */
+export async function __forceTrapForTests() {
+    await callWasm(({ raw }) => {
+        raw.compile(0xfffffff0, 0, 0, 0, 0);
+    });
+}
+/**
+ * @internal Test-only observability for the trap recovery contract. This is a
+ * named export only so the built-package Vitest suite can assert the public
+ * wrapper's concurrency/cap behavior without mocking the wasm-bindgen glue.
+ */
+export function __getTrapRecoveryStateForTests() {
+    return {
+        currentGeneration,
+        freshInstanceStarts,
+        maxTrapRecoveries: MAX_TRAP_RECOVERIES,
+        trapRecoveriesStarted,
+        terminal: !!terminalTrapRecoveryError,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CompileResult, RenderHtmlResult, ZfbMdWasmOptions } from \"./types.js\";\n\n// The wasm-bindgen-generated glue lives at ./wasm/zfb_md_wasm.{js,d.ts} plus\n// the ./wasm/zfb_md_wasm_bg.wasm binary, produced by `pnpm build`\n// (scripts/build.mjs) -- not checked in, see .gitignore. `pnpm build` must\n// run before this module is imported (or before `tsc` can typecheck it).\ntype WasmGlueModule = typeof import(\"./wasm/zfb_md_wasm.js\");\ntype WasmRawExports = import(\"./wasm/zfb_md_wasm.js\").InitOutput;\n\nconst GLUE_URL = new URL(\"./wasm/zfb_md_wasm.js\", import.meta.url);\nconst WASM_URL = new URL(\"./wasm/zfb_md_wasm_bg.wasm\", import.meta.url);\n\nfunction isNode(): boolean {\n  return typeof process !== \"undefined\" && !!process.versions?.node;\n}\n\n// Node's built-in `fetch` does not support `file:` URLs, so the wasm bytes\n// must be read from disk directly there; browsers (and other fetch-capable\n// hosts, e.g. a bundler-served dev server) go through `fetch` against the\n// module-relative URL, which is the standard wasm-bindgen `--target web`\n// browser consumption path.\nasync function loadWasmBytes(): Promise<ArrayBuffer> {\n  if (isNode()) {\n    const [{ readFile }, { fileURLToPath }] = await Promise.all([\n      import(\"node:fs/promises\"),\n      import(\"node:url\"),\n    ]);\n    const buf = await readFile(fileURLToPath(WASM_URL));\n    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;\n  }\n  const res = await fetch(WASM_URL);\n  if (!res.ok) {\n    throw new Error(`zfb-md-wasm: failed to fetch wasm binary: ${res.status} ${res.statusText}`);\n  }\n  return res.arrayBuffer();\n}\n\nlet compiledModulePromise: Promise<WebAssembly.Module> | undefined;\n\nfunction getCompiledModule(): Promise<WebAssembly.Module> {\n  compiledModulePromise ??= loadWasmBytes().then((bytes) => WebAssembly.compile(bytes));\n  return compiledModulePromise;\n}\n\nconst MAX_TRAP_RECOVERIES = 16;\n\nlet currentGeneration = 0;\nlet trapRecoveriesStarted = 0;\nlet freshInstanceStarts = 0;\nlet terminalTrapRecoveryError: ZfbMdWasmTrapRecoveryLimitError | undefined;\n\ninterface Instance {\n  generation: number;\n  glue: WasmGlueModule;\n  raw: WasmRawExports;\n}\n\n/**\n * Instantiates a fresh copy of the wasm-bindgen glue module.\n *\n * wasm-bindgen's `--target web` output guards `init`/`initSync` with an\n * \"already initialized\" early return keyed on a module-scope singleton, so\n * recovering from a trapped (poisoned) instance requires a genuinely fresh ES\n * module record -- re-calling `initSync` on the existing module record is a\n * no-op. Re-importing the same specifier with a distinct query string yields a\n * new module record per the ECMAScript module spec (Node and browsers agree on\n * this); the underlying `WebAssembly.Module` (compiled code) is cached and\n * reused via `getCompiledModule`, so this only re-runs cheap instantiation,\n * never a recompile. Module-record growth is bounded by\n * `MAX_TRAP_RECOVERIES`: once that many poisoned instances have been replaced,\n * recovery stops permanently and callers receive\n * `ZfbMdWasmTrapRecoveryLimitError` instead of minting another module record.\n */\nasync function freshInstance(generation: number): Promise<Instance> {\n  freshInstanceStarts += 1;\n  const [module, glue] = await Promise.all([\n    getCompiledModule(),\n    import(\n      /* @vite-ignore */ `${GLUE_URL.href}?zfbMdWasmGen=${generation}`\n    ) as Promise<WasmGlueModule>,\n  ]);\n  const raw = glue.initSync({ module });\n  return { generation, glue, raw };\n}\n\nlet instancePromise: Promise<Instance> | undefined;\n\nfunction getInstance(): Promise<Instance> {\n  if (terminalTrapRecoveryError) {\n    return Promise.reject(terminalTrapRecoveryError);\n  }\n  instancePromise ??= freshInstance(currentGeneration);\n  return instancePromise;\n}\n\n/**\n * Thrown when a wasm call traps (a Rust panic, or another internal fault\n * that lowers to a wasm trap). This is always a bug, never an expected\n * input-validation failure -- expected failures (parse errors, malformed\n * options JSON, unknown themes, ...) come back as structured\n * `Diagnostic[]` in a normal `CompileResult`/`RenderHtmlResult`, never as a\n * thrown error. See this package's README \"Error / trap / re-init\n * contract\" section.\n *\n * By the time this is thrown, the poisoned instance has already been dropped\n * and a replacement has been instantiated (from the cached compiled module, so\n * no recompile). Concurrent trap reporters for the same poisoned generation\n * wait for that same replacement instead of each starting another one; the\n * next `compile` / `renderHtml` / `version` call transparently uses the fresh\n * instance.\n */\nexport class ZfbMdWasmTrapError extends Error {\n  constructor(cause: unknown) {\n    super(\n      \"zfb-md-wasm: the wasm instance trapped (a Rust panic or internal fault) and has been \" +\n        \"automatically re-instantiated. This is always a bug in zfb-md-wasm -- please report it \" +\n        \"with the input that triggered it.\",\n    );\n    this.name = \"ZfbMdWasmTrapError\";\n    this.cause = cause;\n  }\n}\n\n/**\n * Thrown once this wrapper has already recovered from too many wasm traps in\n * one module lifetime. ES module records cannot be evicted, and wasm-bindgen\n * `--target web` glue cannot be safely re-used after initialization, so the\n * only bounded behavior after repeated poisoning is to stop recovering and ask\n * the host to reload/recreate the JS realm before trying again.\n */\nexport class ZfbMdWasmTrapRecoveryLimitError extends Error {\n  constructor(maxRecoveries: number, cause: unknown) {\n    super(\n      `zfb-md-wasm: wasm trap recovery limit reached after ${maxRecoveries} ` +\n        `successful re-instantiations. Further automatic recovery is disabled to avoid ` +\n        `unbounded ES module record growth. Reload the JS realm before using zfb-md-wasm ` +\n        `again, and please report the input that triggered the repeated traps.`,\n    );\n    this.name = \"ZfbMdWasmTrapRecoveryLimitError\";\n    this.cause = cause;\n  }\n}\n\nfunction isTrap(err: unknown): boolean {\n  return typeof WebAssembly !== \"undefined\" && err instanceof WebAssembly.RuntimeError;\n}\n\nasync function recoverAfterTrap(observedGeneration: number, cause: unknown): Promise<void> {\n  if (terminalTrapRecoveryError) {\n    throw terminalTrapRecoveryError;\n  }\n\n  // CAS-style single-flight: only the reporter that observed the currently\n  // active generation advances it and starts a fresh instantiation. Other\n  // concurrent reporters trapped on an older instance, so they await the\n  // already-started replacement instead of minting another module record.\n  if (observedGeneration !== currentGeneration) {\n    await getInstance();\n    return;\n  }\n\n  if (trapRecoveriesStarted >= MAX_TRAP_RECOVERIES) {\n    terminalTrapRecoveryError = new ZfbMdWasmTrapRecoveryLimitError(MAX_TRAP_RECOVERIES, cause);\n    instancePromise = undefined;\n    throw terminalTrapRecoveryError;\n  }\n\n  trapRecoveriesStarted += 1;\n  currentGeneration += 1;\n  instancePromise = freshInstance(currentGeneration);\n  await instancePromise;\n}\n\nasync function callWasm<T>(fn: (instance: Instance) => T): Promise<T> {\n  const instance = await getInstance();\n  try {\n    return fn(instance);\n  } catch (err) {\n    if (!isTrap(err)) {\n      throw err;\n    }\n    // Drop the poisoned instance and re-instantiate it from the cached compiled\n    // module. Concurrent trap reporters single-flight through the same\n    // generation advance, so one poisoned generation creates at most one fresh\n    // module record.\n    await recoverAfterTrap(instance.generation, err);\n    throw new ZfbMdWasmTrapError(err);\n  }\n}\n\n/**\n * Eagerly loads and instantiates the wasm module. Optional -- `compile` /\n * `renderHtml` / `version` all call this implicitly on first use -- but\n * useful to front-load the one-time fetch/compile cost, e.g. on app\n * startup before the first user-triggered call.\n */\nexport async function init(): Promise<void> {\n  await getInstance();\n}\n\n/**\n * Compile MDX source into ES-module JavaScript. Mirrors the crate's\n * `compile(source, options_json) -> string` export, with JSON\n * marshaling handled for you.\n */\nexport async function compile(\n  source: string,\n  options: ZfbMdWasmOptions = {},\n): Promise<CompileResult> {\n  const optionsJson = JSON.stringify(options);\n  const json = await callWasm(({ glue }) => glue.compile(source, optionsJson));\n  return JSON.parse(json) as CompileResult;\n}\n\n/**\n * Render markdown source to an HTML fragment (no SWC at runtime). Mirrors\n * the crate's `renderHtml(source, options_json) -> string` export, with\n * JSON marshaling handled for you.\n */\nexport async function renderHtml(\n  source: string,\n  options: ZfbMdWasmOptions = {},\n): Promise<RenderHtmlResult> {\n  const optionsJson = JSON.stringify(options);\n  const json = await callWasm(({ glue }) => glue.renderHtml(source, optionsJson));\n  return JSON.parse(json) as RenderHtmlResult;\n}\n\n/**\n * Package version for host-side compatibility checks.\n *\n * Release artifacts are stamped with the published package semver at build\n * time; local development builds fall back to the Rust manifest placeholder.\n */\nexport async function version(): Promise<string> {\n  return callWasm(({ glue }) => glue.version());\n}\n\n/**\n * @internal Test-only (zfb#1577's trap/re-init test). Forces a genuine wasm\n * trap on the currently-active instance by invoking its raw `compile` export\n * with a garbage return pointer, so the result-doubleword `i32.store` lands\n * outside the instance's linear memory -- a `WebAssembly.RuntimeError:\n * memory access out of bounds`. From the JS host's point of view this is\n * the same exception class a real Rust panic->unreachable trap produces\n * (both are `instanceof WebAssembly.RuntimeError`), which is what\n * `callWasm`'s catch clause keys on -- so this exercises the real\n * catch-and-reinstantiate path without needing to coax an actual Rust panic\n * out of a crate that is deliberately designed to never panic on structured\n * input. This is NOT part of the supported public API: it is a named export\n * of the package entry, so a `import { __forceTrapForTests } from\n * \"@takazudo/zfb-md-wasm\"` does resolve -- but the `__`-prefix marks it\n * internal, and the raw ABI details it pokes at (argument order, retptr\n * convention) are wasm-bindgen internals that can change on a wasm-bindgen\n * version bump. Do not call it outside this package's own tests.\n */\nexport async function __forceTrapForTests(): Promise<void> {\n  await callWasm(({ raw }) => {\n    raw.compile(0xfffffff0, 0, 0, 0, 0);\n  });\n}\n\n/**\n * @internal Test-only observability for the trap recovery contract. This is a\n * named export only so the built-package Vitest suite can assert the public\n * wrapper's concurrency/cap behavior without mocking the wasm-bindgen glue.\n */\nexport function __getTrapRecoveryStateForTests(): {\n  currentGeneration: number;\n  freshInstanceStarts: number;\n  maxTrapRecoveries: number;\n  trapRecoveriesStarted: number;\n  terminal: boolean;\n} {\n  return {\n    currentGeneration,\n    freshInstanceStarts,\n    maxTrapRecoveries: MAX_TRAP_RECOVERIES,\n    trapRecoveriesStarted,\n    terminal: !!terminalTrapRecoveryError,\n  };\n}\n\nexport type {\n  CompileResult,\n  RenderHtmlResult,\n  Diagnostic,\n  DiagnosticSource,\n  ZfbMdWasmOptions,\n  PipelineOptions,\n  GfmOptions,\n  MarkdownFeaturesConfig,\n  JsxRuntime,\n} from \"./types.js\";\n"]}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/** `zfb_content::facade::PipelineOptions`'s `gfm` sub-object, verbatim. */
+export interface GfmOptions {
+    strikethrough?: boolean;
+    table?: boolean;
+    autolinkLiteral?: boolean;
+    taskListItem?: boolean;
+    footnoteDefinition?: boolean;
+}
+/**
+ * `MarkdownFeaturesConfig` (see `crates/zfb-md-ast/src/features_config.rs`).
+ * Left as an open record here -- the wasm boundary passes it through to the
+ * Rust `deny_unknown_fields` deserializer verbatim, which is the
+ * authoritative validator for its keys.
+ */
+export type MarkdownFeaturesConfig = Record<string, unknown>;
+/** `zfb_content::facade::PipelineOptions`, verbatim. */
+export interface PipelineOptions {
+    /** A syntect theme name, or `null` for no syntax highlighting. */
+    theme?: string | null;
+    gfm?: GfmOptions;
+    cjkFriendly?: boolean;
+    hardBreaks?: boolean;
+    features?: MarkdownFeaturesConfig;
+}
+/** `jsxRuntime` option values. Consumed only by `compile`. */
+export type JsxRuntime = "preact" | "react";
+/**
+ * The options JSON document shared by `compile` and `renderHtml`. Every
+ * field is optional; `{}` selects all defaults. Unknown fields are
+ * rejected by the Rust side at both nesting levels (`deny_unknown_fields`).
+ */
+export interface ZfbMdWasmOptions {
+    /**
+     * Must end in `.md` or `.mdx`. Drives frontmatter dispatch and
+     * diagnostics display. Defaults to `<anonymous>.mdx` for `compile` and
+     * `<anonymous>.md` for `renderHtml`.
+     */
+    filename?: string;
+    /** Consumed only by `compile`; `renderHtml` accepts and ignores it. */
+    jsxRuntime?: JsxRuntime;
+    /** Consumed only by `compile`; `renderHtml` accepts and ignores it. */
+    development?: boolean;
+    pipeline?: PipelineOptions;
+}
+/** `source` values a `Diagnostic` can carry. */
+export type DiagnosticSource = "options" | "frontmatter" | "markdown" | "compile";
+/**
+ * One diagnostic entry. `line`/`column` are 1-based. For `"markdown"` /
+ * `"frontmatter"` they point into the *original source* (frontmatter lines
+ * included). For `"options"` they point into the *options JSON document*.
+ * `null` when the underlying error carries no location.
+ */
+export interface Diagnostic {
+    severity: "error";
+    source: DiagnosticSource;
+    message: string;
+    line: number | null;
+    column: number | null;
+}
+/** Result document of `compile`. */
+export interface CompileResult {
+    /** ES-module JS source on success, `null` on failure. */
+    code: string | null;
+    /** Parsed YAML frontmatter as JSON, `null` when absent or unextractable. */
+    frontmatter: unknown;
+    diagnostics: Diagnostic[];
+}
+/** Result document of `renderHtml`. */
+export interface RenderHtmlResult {
+    /** HTML fragment on success, `null` on failure. */
+    html: string | null;
+    frontmatter: unknown;
+    diagnostics: Diagnostic[];
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Mirrors the JSON contracts of the `zfb-md-wasm` Rust crate (zfb#1576)
+// literally -- see that crate's `src/lib.rs` rustdoc for the authoritative
+// shape. Keep this file in lock-step with the crate when the crate's
+// options/result shapes change.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,qEAAqE;AACrE,gCAAgC","sourcesContent":["// Mirrors the JSON contracts of the `zfb-md-wasm` Rust crate (zfb#1576)\n// literally -- see that crate's `src/lib.rs` rustdoc for the authoritative\n// shape. Keep this file in lock-step with the crate when the crate's\n// options/result shapes change.\n\n/** `zfb_content::facade::PipelineOptions`'s `gfm` sub-object, verbatim. */\nexport interface GfmOptions {\n  strikethrough?: boolean;\n  table?: boolean;\n  autolinkLiteral?: boolean;\n  taskListItem?: boolean;\n  footnoteDefinition?: boolean;\n}\n\n/**\n * `MarkdownFeaturesConfig` (see `crates/zfb-md-ast/src/features_config.rs`).\n * Left as an open record here -- the wasm boundary passes it through to the\n * Rust `deny_unknown_fields` deserializer verbatim, which is the\n * authoritative validator for its keys.\n */\nexport type MarkdownFeaturesConfig = Record<string, unknown>;\n\n/** `zfb_content::facade::PipelineOptions`, verbatim. */\nexport interface PipelineOptions {\n  /** A syntect theme name, or `null` for no syntax highlighting. */\n  theme?: string | null;\n  gfm?: GfmOptions;\n  cjkFriendly?: boolean;\n  hardBreaks?: boolean;\n  features?: MarkdownFeaturesConfig;\n}\n\n/** `jsxRuntime` option values. Consumed only by `compile`. */\nexport type JsxRuntime = \"preact\" | \"react\";\n\n/**\n * The options JSON document shared by `compile` and `renderHtml`. Every\n * field is optional; `{}` selects all defaults. Unknown fields are\n * rejected by the Rust side at both nesting levels (`deny_unknown_fields`).\n */\nexport interface ZfbMdWasmOptions {\n  /**\n   * Must end in `.md` or `.mdx`. Drives frontmatter dispatch and\n   * diagnostics display. Defaults to `<anonymous>.mdx` for `compile` and\n   * `<anonymous>.md` for `renderHtml`.\n   */\n  filename?: string;\n  /** Consumed only by `compile`; `renderHtml` accepts and ignores it. */\n  jsxRuntime?: JsxRuntime;\n  /** Consumed only by `compile`; `renderHtml` accepts and ignores it. */\n  development?: boolean;\n  pipeline?: PipelineOptions;\n}\n\n/** `source` values a `Diagnostic` can carry. */\nexport type DiagnosticSource = \"options\" | \"frontmatter\" | \"markdown\" | \"compile\";\n\n/**\n * One diagnostic entry. `line`/`column` are 1-based. For `\"markdown\"` /\n * `\"frontmatter\"` they point into the *original source* (frontmatter lines\n * included). For `\"options\"` they point into the *options JSON document*.\n * `null` when the underlying error carries no location.\n */\nexport interface Diagnostic {\n  severity: \"error\";\n  source: DiagnosticSource;\n  message: string;\n  line: number | null;\n  column: number | null;\n}\n\n/** Result document of `compile`. */\nexport interface CompileResult {\n  /** ES-module JS source on success, `null` on failure. */\n  code: string | null;\n  /** Parsed YAML frontmatter as JSON, `null` when absent or unextractable. */\n  frontmatter: unknown;\n  diagnostics: Diagnostic[];\n}\n\n/** Result document of `renderHtml`. */\nexport interface RenderHtmlResult {\n  /** HTML fragment on success, `null` on failure. */\n  html: string | null;\n  frontmatter: unknown;\n  diagnostics: Diagnostic[];\n}\n"]}

package/dist/wasm/zfb_md_wasm.d.ts

@@ -0,0 +1,63 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Compile MDX source into ES-module JavaScript.
+ *
+ * Returns a JSON string: `{ "code": string|null, "frontmatter": json,
+ * "diagnostics": Diagnostic[] }` — see the crate docs for the options
+ * and diagnostics shapes.
+ */
+export function compile(source: string, options_json: string): string;
+
+/**
+ * Render markdown source to an HTML fragment (no SWC at runtime).
+ *
+ * Returns a JSON string: `{ "html": string|null, "frontmatter": json,
+ * "diagnostics": Diagnostic[] }` — see the crate docs for the options
+ * and diagnostics shapes. Exported to JS as `renderHtml`.
+ */
+export function renderHtml(source: string, options_json: string): string;
+
+/**
+ * This package's release version, stamped by CI at compile time.
+ *
+ * Development builds without `ZFB_RELEASE_VERSION` fall back to this crate's
+ * manifest version (`CARGO_PKG_VERSION`).
+ */
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly compile: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly renderHtml: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly version: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/dist/wasm/zfb_md_wasm.js

@@ -0,0 +1,275 @@
+/* @ts-self-types="./zfb_md_wasm.d.ts" */
+
+/**
+ * Compile MDX source into ES-module JavaScript.
+ *
+ * Returns a JSON string: `{ "code": string|null, "frontmatter": json,
+ * "diagnostics": Diagnostic[] }` — see the crate docs for the options
+ * and diagnostics shapes.
+ * @param {string} source
+ * @param {string} options_json
+ * @returns {string}
+ */
+export function compile(source, options_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(options_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.compile(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred3_0 = r0;
+        deferred3_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Render markdown source to an HTML fragment (no SWC at runtime).
+ *
+ * Returns a JSON string: `{ "html": string|null, "frontmatter": json,
+ * "diagnostics": Diagnostic[] }` — see the crate docs for the options
+ * and diagnostics shapes. Exported to JS as `renderHtml`.
+ * @param {string} source
+ * @param {string} options_json
+ * @returns {string}
+ */
+export function renderHtml(source, options_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(options_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.renderHtml(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred3_0 = r0;
+        deferred3_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * This package's release version, stamped by CI at compile time.
+ *
+ * Development builds without `ZFB_RELEASE_VERSION` fall back to this crate's
+ * manifest version (`CARGO_PKG_VERSION`).
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.version(retptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred1_0 = r0;
+        deferred1_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+    }
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+    };
+    return {
+        __proto__: null,
+        "./zfb_md_wasm_bg.js": import0,
+    };
+}
+
+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) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+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;
+}
+
+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 wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('zfb_md_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/dist/wasm/zfb_md_wasm_bg.wasm.d.ts

@@ -0,0 +1,10 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const compile: (a: number, b: number, c: number, d: number, e: number) => void;
+export const renderHtml: (a: number, b: number, c: number, d: number, e: number) => void;
+export const version: (a: number) => void;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_export: (a: number, b: number) => number;
+export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_export3: (a: number, b: number, c: number) => void;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@takazudo/zfb-md-wasm",
+  "version": "0.1.0-next.80",
+  "private": false,
+  "type": "module",
+  "description": "zfb's md/mdx -> JS/HTML conversion pipeline compiled to WebAssembly, for browser-side dynamic conversion (CMS live preview with parity to zfb's production output).",
+  "keywords": [
+    "zfb",
+    "zfb-md-wasm",
+    "markdown",
+    "mdx",
+    "wasm",
+    "webassembly",
+    "cms",
+    "live-preview"
+  ],
+  "license": "MIT",
+  "author": "Takeshi Takatsudo <takazudo@gmail.com> (https://github.com/Takazudo)",
+  "homepage": "https://takazudomodular.com/pj/zudo-front-builder/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Takazudo/zudo-front-builder.git",
+    "directory": "crates/zfb-md-wasm/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/Takazudo/zudo-front-builder/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "binaryen": "130.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}