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, 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, so one options object can serve either call.

renderHtml(source, options?)

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

Markdown → mdast → visitors → hast → HTML string, skipping SWC entirely. options defaults to {}.

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

Two subpath exports, both compiled from the same crate but shipping distinct wasm artifacts:

Each subpath's exports map resolves a browser condition (a static, bundler-friendly resource path used by src/browser.ts / src/highlight-browser.ts) ahead of a default condition (the dynamic Node-fs-or-fetch loader in src/index.ts / src/highlight.ts); both conditions share the same types entry and the same underlying createWasmApi runtime.

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

• 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.