zfb-md-wasm

@takazudo/zfb-md-wasm のリファレンス — zfb の markdown/MDX パイプラインの WebAssembly ビルド。エクスポート、async のシグネチャ、オプション / 結果の型（ZfbMdWasmOptions、ParseDialect、PipelineOptions、Diagnostic、ParseToAstOptions、HighlightCodeOptions、HighlightRole）、生の mdast の形、パッケージのエントリポイント。

概要

@takazudo/zfb-md-wasm は、zfb の markdown/MDX → JS/HTML パイプラインを WebAssembly にコンパイルして提供します。このページはシグネチャと型のリファレンスです。パッケージのインストール、ブラウザでのコンパイル済みモジュールの評価、JSX ランタイムの import map 設定、パリティ保証の制限といったナラティブな解説については、ブラウザでの Markdown プレビュー を参照してください。

このパッケージは、ビルド時に .wasm モジュールを SSR ルートへインポートすることとは無関係です — そちらは別の機能で、Wasm のインポート で扱います。

エクスポート

init、compile、renderHtml、parseToAst、highlightCode、version はすべて async です — 基盤となる wasm モジュールが既にインスタンス化されているかどうかにかかわらず、各呼び出しは Promise を返します。

init()

function init(): Promise<void>

wasm モジュールを事前にインスタンス化します。前もって呼び出すことで制御できるのは、fetch / コンパイルのコストが いつ 発生するかだけです — init() を一度も呼ばなかった場合、他のすべての関数は初回使用時にモジュールを遅延的に初期化します。

compile(source, options?)

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

MDX → JSX → SWC → ES モジュール JS。zfb 自身のビルドが使うのと同じエミッタです。options のデフォルトは {} です。jsxRuntime と development はここでのみ消費され、renderHtml は両方を受け取りますが黙って無視します。反対に、dialect は renderHtml だけが消費し、compile は受け取って無視するため、1 つのオプションオブジェクトでどちらの呼び出しにも使えます。

renderHtml(source, options?)

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

Markdown/MDX → mdast → ビジター → hast → HTML 文字列。SWC を完全にスキップします。options のデフォルトは {} です。明示的な dialect がない場合、.md のファイル名は CommonMark、.mdx は MDX を選びます。filename を省略すると "<anonymous>.md" が使われるため CommonMark になります。dialect: "markdown" | "mdx" は、拡張子のゲートを免除せずに、どちらの有効な拡張子も上書きします。

parseToAst(source, options?)

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

Markdown/MDX → 生の mdast ツリー。ZfbMdWasmOptions では なく、独立した閉じた ParseToAstOptions ドキュメントを受け取ります — その pipeline サブオブジェクトは gfm のみを受け付けます（バリデーションと位置の契約 を参照）。options のデフォルトは {} です。

highlightCode(code, options)

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

任意のソース文字列に対する、直接的なセマンティッククラスのシンタックスハイライト — Markdown のフェンスは関与せず、options のデフォルトもありません。language は必須です。

version()

function version(): Promise<string>

リリース時にスタンプされるパッケージのバージョン文字列。公開されるアーティファクトはリリース時にパッケージの semver をスタンプします。ローカルの開発ビルドでは、Rust マニフェストのバージョンのプレースホルダにフォールバックします。

toMdastRoot(ast)

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

生の parseToAst().ast ツリーを検証し、切り離された @types/mdast 互換の Root を返します。型はエコシステムが使うのと同じ mdast / mdast-util-directive / mdast-util-mdx のコンテンツモデルレジストリに対して付けられます。この厳密なアダプタは、parseToAst が返す前方互換の生の階層とは意図的に分けられています。サポートされていない、または不正なノードは、黙って破棄されたり強制変換されたりするのではなく、MdastAdapterError を スロー します。同期処理であり、wasm の境界には一切触れません。

エラークラス

• ZfbMdWasmTrapError extends Error — wasm トラップを観測した async 呼び出しがスローします。(cause: unknown) で構築され、.cause で公開されます。このエラーがスローされる 前 に、トラップしたインスタンスは破棄され、キャッシュ済みのコンパイル済み WebAssembly.Module から新しいインスタンスが起動されます。そのため、直後の呼び出しはすでに置き換え後のインスタンスを使います — 呼び出し間で存続するキャッシュやグローバルはないため、再インスタンス化で失われるのは時間だけです。

• ZfbMdWasmTrapRecoveryLimitError extends Error — プロセスで自動トラップ回復を 16 回使い切ると、ZfbMdWasmTrapError の代わりにスローされます。(maxRecoveries: number, cause: unknown) で構築され、cause は .cause で公開されます。それ以降の回復は（ES モジュールレコードの無制限な増加を避けるため）、JS レルムがリロードされるまで無効のままになります。

• MdastAdapterError extends TypeError — toMdastRoot がスローします。path: string（問題のノードを指す JSON パス風のポインタ、例: "$.children[2].value"）と nodeType: string | null（観測されたノードの type、または値が型付きレコードですらなかった場合は null）を持ちます。

型リファレンス

ZfbMdWasmOptions

compile と renderHtml が共有するオプションドキュメント。すべてのフィールドは任意で、{} はすべてのデフォルトを選びます。

PipelineOptions

zfb_content::facade::PipelineOptions をそのまま反映します。

GfmOptions

CodeHighlightOptions

zfb_content::facade::CodeHighlightOptions をそのまま。

CompileResult / RenderHtmlResult

Diagnostic

1 つの診断エントリ。line / column はサポートされる唯一の診断位置で、1 始まりです。

ParseToAstOptions

parseToAst が消費する、独立した閉じたオプションドキュメント。ビジター / シリアライザのオプションは受け付けません。

ParseToAstResult

HighlightCodeOptions

任意コードの直接的なセマンティッククラスハイライトのためのオプション。

HighlightCodeResult と HighlightDiagnostic

HighlightDiagnostic のフィールド: severity: "error" | "warning"、source: "options" | "highlight" | "internal"、message: string、line: number | null（常に null — JSON オプションのパース位置は 1 始まりですが、この呼び出しは位置を報告しません）、column: number | null（同じ）。

無効なオプション（language の欠落 / 空文字列、サポートされない mode、不正な classPrefix、未知のロールキー、余分なフィールド）は { html: null, diagnostics: [{ severity: "error", source: "options", … }] } を返します。未知だが空でない language は別で、エスケープされたフォールバックの markup と { severity: "warning", source: "highlight" } の診断とともに成功します。

HighlightRole

highlightCode が出力する、固定された 18 個のロールからなるセマンティックな分類体系（Rust の正規の HiRole::FULL_NAMES に対して機械的に検証されています）:

各ロールのデフォルトクラスは ${classPrefix}${suffix} です（デフォルトの classPrefix は "hi-"）。roleClasses の上書きはキーに フルネーム（keyword）を使い、クラスのサフィックス（kw）は使いません。

生の mdast の形（parseToAst / toMdastRoot）

parseToAst の ast フィールドは、シリアライズされた 生の markdown-rs mdast ツリー（MdastRoot。存在する場合は常に root 型の Root ノード）です — パーサ自身のノードの形を、その serde 表現を通して、開いた unist 形状のキャリアへ変換したもので、意図的に zfb ビジター適用 前 です。ツリー内のすべてのノードは常に position: { start: AstPosition; end: AstPosition } を持ちます。AstPoint の column と offset（0 始まり）は JavaScript の UTF-16 コードユニット で、String.prototype.slice、mdast-util-to-hast、remark/unist 自身の規約と一致します — Unicode スカラー値ではないため、サロゲートペアの文字（多くの絵文字）は column / offset を 1 ではなく 2 進めます。

コア mdast と MDX の完全なノードセット（Root、Paragraph、Heading、List、Code、Link、MdxJsxFlowElement、…）に加えて、前方互換の UnknownMdastNode キャッチオールが、node.type で型を絞り込みたい呼び出し元のために、名前付きの型としてパッケージから再エクスポートされています。remark-parse / remark-mdx からの、文書化された 2 つの相違点: mdxJsxAttribute（およびその値属性 / 式属性の兄弟）は position を持ちません — markdown-rs は属性の位置をモデル化しません。また、トップレベルの MDX import / export は段落へと格下げされます（mdxjsEsm ノードなし、estree データなし） — wasm の境界には JS/acorn パーサが存在しないためです。_markdownRsStops（MDX の式 / ESM ノードに付く）は内部的で不安定な、markdown-rs の再パース用の管理情報であり、position とは異なり UTF-8 バイト ベースです。これで文字列をスライスしては決していけません。

directives: true の場合（ParseToAstOptions を参照。デフォルトは false）、ツリーは 3 つの汎用 remark-directive ノード型も持てます。いずれも同じ DirectiveNodeBase の形（position、name、attributes、children）を共有します:

• containerDirective — ブロック形式、:::name

• leafDirective — ブロック形式、::name

• textDirective — インライン形式、:name

DirectiveNodeBase の name はディレクティブの名前文字列で、attributes は Record<string, string> です — 真偽値の属性は空文字列で表され、true やキーの省略にはなりません。directives をデフォルトの false のままにすると、ディレクティブのように見えるテキストは markdown-rs がパースしたそのままで残り、これら 3 つのノード型はどれも現れません。

toMdastRoot（上記参照）は、この生の階層を、生のキャリアではなく通常の mdast / unist-util-visit のツールを使いたい利用者のために、厳密でエコシステム互換のツリーへ変換します。

バリデーションと位置の契約

• 未知のフィールドは拒否されます。Rust 側で deny_unknown_fields 方式により、ZfbMdWasmOptions の 両方の ネストレベル（トップレベルと pipeline）で行われます。ParseToAstOptions は 別の、より厳格な 閉じたドキュメントです: その pipeline サブオブジェクトは gfm のみを受け付けます — theme、cjkFriendly、hardBreaks、codeHighlight、features をそこに渡すと、たとえそれらが compile / renderHtml にとって有効な PipelineOptions フィールドであっても拒否されます。

• Diagnostic.line / .column（compile / renderHtml 由来）と AstPoint.column / .offset（parseToAst 由来）は、上で説明した同じ JavaScript の UTF-16 コードユニット 規約を共有します。純粋な ASCII のソースはバイトオフセットが UTF-16 オフセットと等しいため、これが問題になるのはソースに非 ASCII のコンテンツが含まれる場合だけです。

パッケージのエントリポイント

ルート（.）は完全な後方互換 API のままです。既存のルートと ./highlight のインポートに移行は必要ありません。追加された ./render と ./parse は独立した SWC-free グラフです。swc_core と zfb-render を除外しつつ、 zfb-content と syntect-fancy は意図的に保持します。parse は syntect-free ではありません。

focused エントリのリソースペアは非公開で、互いに置き換えられません:

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

宣言サイドカーも対応するディレクトリに閉じています。各エントリは独立した createWasmApi 状態（コンパイル済みモジュール、インスタンス、世代、リトライ状態、 終端状態）を作ります。複数エントリをインポートすると、独立したペアとインスタンスが 意図どおりロードされます。

Node の直接利用とブラウザ対応バンドラでは、同じサブパスをインポートします:

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

ブラウザで遅延ロードする場合は、ユーザー操作からインポートします。browser 条件は 選択したエントリ自身のペアだけへ静的な ?url エッジを張ります:

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 はルートだけにあり、ホストによる評価、JSX ランタイム、コンポーネントを必要とする モジュールソースを返します。toMdastRoot は、すでにパースされたデータを利用側の制御された AST-to-React レンダラーで解釈するためのアダプタです。slim エントリは author JavaScript を評価しません。 renderHtml はサニタイザーではなく、生 HTML は信頼できないままです。MDX の JSX / 式 / ESM 形状の AST ノードは不活性なデータとして扱われます。

出荷アーティファクトのサイズと上限

出荷された 2.15.0 のアーティファクトの行は次のとおりです。final wasm は wasm-bindgen と wasm-opt を通した最適化後の値、gzip-9 は Node の gzipSync(..., { level: 9 })、glue は グルーコードのバイト数とその gzip です:

#2447 の決定スナップショットでは、split パッケージの構成が 3,638,607 B、root + highlight が 2,314,818 B、クリーンな本番 4 ステップの上限は 210 秒、選択されたスナップショットの中央値は 155.015 秒 [153.496, 165.977] でした。固定された gzip-9 の上限は root 1,600,000 B、highlight 880,000 B、 render 1,100,000 B、parse 325,000 B、完全な packed tarball は 3,900,000 B です。4 つのエントリは いずれも上限の内側で出荷されており、上限までの余裕は root 83,617 B、highlight 62,049 B、 render 8,322 B、parse 41,009 B です。これらは永続的な保証ではなく 2.15.0 の測定値です — 実際にインストールしたバージョンで測り直してください。

サイズは保証されますが、コンテンツダイジェストは保証されません。 上記のバイトサイズは shipped-sizes.json が保持し CI がアサートしているため、意図的なアーティファクト変更が あったときにしか動きません。SHA-256 ダイジェストは事情が異なります。各リリースは自身の バージョン文字列を個々の .wasm に焼き込む（version() が返す値です）ため、コンパイル結果が 同一でバイトサイズがまったく動かないドキュメントのみのパッチであっても、4 つのダイジェストは 毎リリース変わります。semver ではなくコンテンツダイジェストでこれらのアーティファクトを 検証している場合は、アップグレードのたびに再ピン留めしてください。「サイズが変わっていない」を 「再検証は不要」と読み替えてはいけません。

highlight グラフから swc_core をゲートで外したこと（#2449 / #2450）は、 証明可能性の勝利であって、サイズの勝利ではありません。#2447 の SWC 保持ベースラインは raw 1,484,705 B、gzip-9 767,009 B で、#2450 の結果は raw で 7,965 B、gzip-9 で 8,765 B（結果は 758,244 B）小さくなりました。wasm-opt は 到達不能な swc_core を既にデッドストリップしていたのであり、#2450 の完全パリティと swc_core 不在のアサーションが、その創発的な性質を保証されたものへと変えました。 highlight だけを使う利用者にとって意味のある差は、root と highlight の差のほうです: raw で 1,860,620 B、gzip-9 で 698,432 B 小さく、highlight は root の raw バイトの約 45%、 gzip 後のバイトの約 54% に収まります。

各サブパスの exports マップは、default 条件（src/index.ts / src/highlight.ts にある、動的な Node の fs または fetch ローダ）よりも先に browser 条件（src/browser.ts / src/highlight-browser.ts が使う、静的でバンドラフレンドリーなリソースパス）を解決します。両方の条件は同じ types エントリと、同じ基盤の createWasmApi ランタイムを共有します。

このパッケージは ESM 専用 で（"type": "module"、require のサポートなし）、Node ≥ 20.0.0 を必要とします。このページに焼き込まれたバージョン番号を信頼するのではなく、実行時に version()（上記）を呼ぶか、インストール済みパッケージ自身の package.json を確認してください — バージョン番号はリリースごとに変わります。

関連項目

• Playground — ブラウザで Rust パイプラインをインタラクティブに試せます。

• ブラウザでの Markdown プレビュー — ナラティブなガイド: インストール、コンパイル済みモジュールの評価、JSX ランタイムの import map の落とし穴、リソースの遅延ロード、パリティ保証の明示的な制限。

• Wasm のインポート — ビルド時に .wasm モジュールを SSR ルートへインポートするという、別の無関係な機能。

• シンタックスハイライト — このパッケージの fancy-regex バックエンドと比較するための、ネイティブ zfb の syntect のセットアップ。