zfb-md-wasm

Reference for @takazudo/zfb-md-wasm — the WebAssembly build of zfb's markdown/MDX pipeline. Exports, async signatures, option/result types (ZfbMdWasmOptions, ParseDialect, PipelineOptions, Diagnostic, ParseToAstOptions, HighlightCodeOptions, HighlightRole), the raw mdast shape, and package entry points.

Overview

@takazudo/zfb-md-wasm ships zfb's markdown/MDX → JS/HTML pipeline compiled to WebAssembly. This page is the signature/type reference. For the narrative walkthrough — installing the package, evaluating a compiled module in a browser, the JSX-runtime import-map setup, and the parity guarantee's limitations — see Browser Markdown Preview.

This package is unrelated to importing a .wasm module into an SSR route at build time — that is a separate feature covered in Importing Wasm.

Exports

init, compile, renderHtml, parseToAst, highlightCode, and version are all async — every call returns a Promise, whether or not the underlying wasm module is already instantiated.

init()

function init(): Promise<void>

Eagerly instantiate the wasm module. Calling it up front only controls when the fetch/compile cost happens — every other function initializes the module lazily on first use if init() was never called.

compile(source, options?)

function compile(source: string, options?: ZfbMdWasmOptions): Promise<CompileResult>

MDX → JSX → SWC → ES-module JS, the same emitter zfb's own build uses. options defaults to {}. jsxRuntime and development are consumed only here — renderHtml accepts and silently ignores both. Conversely, dialect is consumed only by renderHtml; compile accepts and ignores it, so one options object can serve either call.

renderHtml(source, options?)

function renderHtml(source: string, options?: ZfbMdWasmOptions): Promise<RenderHtmlResult>

Markdown/MDX → mdast → visitors → hast → HTML string, skipping SWC entirely. options defaults to {}. Without an explicit dialect, a .md filename selects CommonMark and .mdx selects MDX; omitting filename uses "<anonymous>.md", hence CommonMark. dialect: "markdown" | "mdx" overrides either valid extension without waiving the extension gate.

parseToAst(source, options?)

function parseToAst(source: string, options?: ParseToAstOptions): Promise<ParseToAstResult>

Markdown/MDX → raw mdast tree. Takes the distinct, closed ParseToAstOptions document, not ZfbMdWasmOptions — its pipeline sub-object only accepts gfm (see Validation and position contract). options defaults to {}.

highlightCode(code, options)

function highlightCode(code: string, options: HighlightCodeOptions): Promise<HighlightCodeResult>

Direct semantic-class syntax highlighting for an arbitrary source string — no Markdown fence involved, and no options default: language is required.

version()

function version(): Promise<string>

Release-stamped package version string. Published artifacts stamp this with the package semver during release; local development builds fall back to the Rust manifest version placeholder.

toMdastRoot(ast)

function toMdastRoot(ast: MdastRoot | null): Root // ecosystem "mdast" Root (@types/mdast)

Validates a raw parseToAst().ast tree and returns a detached, @types/mdast-compatible Root, typed against the same mdast/mdast-util-directive/mdast-util-mdx content-model registries the ecosystem uses. This strict adapter is intentionally separate from the forward-compatible raw tier parseToAst returns: an unsupported or malformed node throws MdastAdapterError instead of being silently dropped or coerced. Synchronous — it does not touch the wasm boundary at all.

Error classes

• ZfbMdWasmTrapError extends Error — thrown by the async call that observed a wasm trap. Constructed with (cause: unknown), exposed via .cause. The trapped instance is dropped and a fresh one started from the cached compiled WebAssembly.Module before this error is thrown, so the very next call already uses the replacement — no caches or globals survive between calls, so re-instantiation loses nothing but time.

• ZfbMdWasmTrapRecoveryLimitError extends Error — thrown instead of ZfbMdWasmTrapError once 16 automatic trap recoveries have been exhausted for the process. Constructed with (maxRecoveries: number, cause: unknown), cause exposed via .cause. Further recovery stays disabled (to avoid unbounded ES module record growth) until the JS realm is reloaded.

• MdastAdapterError extends TypeError — thrown by toMdastRoot. Carries path: string (a JSON-path-like pointer into the offending node, e.g. "$.children[2].value") and nodeType: string | null (the node's observed type, or null when the value wasn't even a typed record).

Type reference

ZfbMdWasmOptions

The options document shared by compile and renderHtml. Every field is optional; {} selects all defaults.

PipelineOptions

Mirrors zfb_content::facade::PipelineOptions verbatim.

GfmOptions

CodeHighlightOptions

zfb_content::facade::CodeHighlightOptions, verbatim.

CompileResult / RenderHtmlResult

Diagnostic

One diagnostic entry. line/column are the sole supported diagnostic location and are 1-based.

ParseToAstOptions

The distinct, closed options document consumed by parseToAst. Visitor/serializer options are not accepted.

ParseToAstResult

HighlightCodeOptions

Options for direct arbitrary-code semantic class highlighting.

HighlightCodeResult and HighlightDiagnostic

HighlightDiagnostic fields: severity: "error" | "warning", source: "options" | "highlight" | "internal", message: string, line: number | null (always null — JSON option parse locations are 1-based but this call never reports one), column: number | null (same).

Invalid options (missing/empty language, an unsupported mode, a bad classPrefix, an unknown role key, or extra fields) return { html: null, diagnostics: [{ severity: "error", source: "options", … }] }. An unknown but non-empty language is different: it succeeds with escaped fallback markup and a { severity: "warning", source: "highlight" } diagnostic.

HighlightRole

The fixed 18-role semantic taxonomy highlightCode emits (mechanically checked against Rust's canonical HiRole::FULL_NAMES):

The default class for each role is ${classPrefix}${suffix} (default classPrefix is "hi-"); roleClasses overrides use the full name as the key (keyword), never the class suffix (kw).

Raw mdast shape (parseToAst / toMdastRoot)

parseToAst's ast field is a serialized raw markdown-rs mdast tree (MdastRoot, always a root-typed Root node when present) — the parser's own node shape converted through its serde representation into an open, unist-shaped carrier, and deliberately pre-zfb-visitors. Every node in the tree always carries a position: { start: AstPosition; end: AstPosition }; AstPoint's column and offset (0-based) are JavaScript UTF-16 code units, matching String.prototype.slice, mdast-util-to-hast, and remark/unist's own convention — not Unicode scalar values, so a surrogate-pair character (most emoji) advances column/offset by 2, not 1.

The full core-mdast and MDX node set (Root, Paragraph, Heading, List, Code, Link, MdxJsxFlowElement, …) plus a forward-compatible UnknownMdastNode catch-all are all re-exported as named types from the package for callers who want to narrow on node.type. Two documented divergences from remark-parse/remark-mdx: mdxJsxAttribute (and its value/expression-attribute siblings) carry no position — markdown-rs does not model attribute positions; and top-level MDX import/export degrade to paragraphs (no mdxjsEsm nodes, no estree data) since the wasm boundary hosts no JS/acorn parser. _markdownRsStops (on MDX expression/ESM nodes) is internal, unstable, markdown-rs re-parse bookkeeping and — unlike position — is UTF-8 byte-based; never slice a string with it.

With directives: true (see ParseToAstOptions, default false), the tree can also carry the three generic remark-directive node types, all sharing the same DirectiveNodeBase shape (position, name, attributes, children):

• containerDirective — block form, :::name

• leafDirective — block form, ::name

• textDirective — inline form, :name

DirectiveNodeBase's name is the directive's name string, and attributes is a Record<string, string> — a boolean attribute is represented as an empty string, never true or an omitted key. With directives left at its default false, directive-looking text survives exactly as markdown-rs parsed it and none of these three node types ever appear.

toMdastRoot (see above) converts this raw tier into a strict, ecosystem-compatible tree for consumers that want ordinary mdast/unist-util-visit tooling instead of the raw carrier.

Validation and position contract

• Unknown fields are rejected, on the Rust side, deny_unknown_fields-style, at both nesting levels of ZfbMdWasmOptions (top level and pipeline). ParseToAstOptions is a separate, stricter closed document: its pipeline sub-object accepts only gfm — passing theme, cjkFriendly, hardBreaks, codeHighlight, or features there is rejected, even though those are valid PipelineOptions fields for compile/renderHtml.

• Diagnostic.line/.column (from compile/renderHtml) and AstPoint.column/.offset (from parseToAst) share the same JavaScript UTF-16 code unit convention described above. Pure-ASCII sources have byte offsets equal to UTF-16 offsets, so this only matters once a source has non-ASCII content.

Package entry points

The root (.) remains the complete compatibility API. Existing root and ./highlight imports require no migration. The additive ./render and ./parse entries are isolated SWC-free graphs: they omit swc_core and zfb-render while intentionally retaining zfb-content and syntect-fancy. Parse is not syntect-free.

The focused resource pairs are private and non-interchangeable:

wasm-render/zfb_md_wasm_render_glue.zfb-resource.mjs
wasm-render/zfb_md_wasm_render_bg.wasm
wasm-parse/zfb_md_wasm_parse_glue.zfb-resource.mjs
wasm-parse/zfb_md_wasm_parse_bg.wasm

Their declaration sidecars stay in their matching directories. Each entry creates one independent createWasmApi state (compiled module, instance, generation, retry state, and terminal state). Importing multiple entries intentionally loads independent pairs and instances.

Direct Node and browser-aware imports use the same subpath:

import { renderHtml } from "@takazudo/zfb-md-wasm/render";
import { parseToAst, toMdastRoot } from "@takazudo/zfb-md-wasm/parse";

For lazy browser loading, import from a user action. The browser condition uses static ?url edges to only the selected entry's pair:

renderButton.addEventListener("click", async () => {
  const { renderHtml } = await import("@takazudo/zfb-md-wasm/render");
  const { html } = await renderHtml(source, { filename: "preview.md" });
  preview.innerHTML = html ?? "";
});

parseButton.addEventListener("click", async () => {
  const { parseToAst, toMdastRoot } = await import("@takazudo/zfb-md-wasm/parse");
  const parsed = await parseToAst(source, { filename: "preview.md" });
  const root = parsed.ast === null ? null : toMdastRoot(parsed.ast);
  inspect(root);
});

compile is root-only and returns module source requiring host evaluation, the JSX runtime, and components. toMdastRoot is a controlled consumer-side adapter; an AST-to-React renderer may interpret the resulting data. No slim entry evaluates author JavaScript. renderHtml is not a sanitizer and raw HTML remains untrusted; MDX JSX/expression/ESM-shaped AST nodes remain inert data.

Shipped artifact sizes and locked ceilings

These are the shipped 2.15.0 artifact rows — optimized final wasm after wasm-bindgen and wasm-opt, Node gzipSync(..., { level: 9 }), and glue bytes/gzip:

The #2447 decision snapshot found the split package layout at 3,638,607 B versus 2,314,818 B for root plus highlight, a 210 s clean production ceiling, and a selected-snapshot median of 155.015 s [153.496, 165.977]. Locked gzip-9 ceilings are root 1,600,000 B, highlight 880,000 B, render 1,100,000 B, and parse 325,000 B; the complete packed tarball ceiling is 3,900,000 B. All four ship inside their ceilings, with 83,617 B (root), 62,049 B (highlight), 8,322 B (render), and 41,009 B (parse) of headroom. These are 2.15.0 measurements, not permanent promises — re-measure against the version you actually install.

Sizes are guarded; content digests are not. The byte sizes above are held by shipped-sizes.json and asserted in CI, so they move only on a deliberate artifact change. SHA-256 digests are a different matter: every release stamps its own version string into each .wasm — the value version() returns — so all four digests change on every release, including a documentation-only patch whose compiled code is identical and whose byte sizes do not move at all. If you verify these artifacts by content digest rather than by semver, re-pin on every upgrade; never read "sizes unchanged" as "nothing to re-verify".

Gating swc_core out of the highlight graph (#2449/#2450) was a provability win, not a size win. The #2447 SWC-retaining baseline was 1,484,705 B raw and 767,009 B gzip-9; the #2450 result was 7,965 B smaller raw and 8,765 B smaller gzip-9 (758,244 B) — wasm-opt was already dead-stripping the unreachable swc_core, and #2450's exact-parity and no-swc_core assertions turned that emergent property into a guaranteed one. The delta that matters to a highlight-only consumer is root versus highlight: the highlight artifact is 1,860,620 B smaller raw and 698,432 B smaller gzip-9, landing at about 45% of root's raw bytes and 54% of its gzipped bytes.

The package is ESM-only ("type": "module", no require support) and requires Node ≥ 20.0.0. Call version() (above) at runtime, or check the installed package's own package.json, rather than trusting a version number baked into this page — it drifts release to release.

See also

• Playground — try the browser-based Rust pipeline interactively.

• Browser Markdown Preview — the narrative guide: installation, evaluating a compiled module, the JSX-runtime import-map footgun, lazy resource loading, and the parity guarantee's explicit limitations.

• Importing Wasm — the separate, unrelated feature of importing a .wasm module into an SSR route at build time.

• Syntax Highlighting — native zfb's syntect setup, for comparison with this package's fancy-regex backend.