zfb-md-wasm

@takazudo/zfb-md-wasm のリファレンス — zfb の markdown/MDX パイプラインの WebAssembly ビルド。エクスポート、async のシグネチャ、オプション / 結果の型（ZfbMdWasmOptions、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 は両方を受け取りますが黙って無視するため、1 つのオプションオブジェクトでどちらの呼び出しにも使えます。

renderHtml(source, options?)

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

Markdown → mdast → ビジター → hast → HTML 文字列。SWC を完全にスキップします。options のデフォルトは {} です。

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 のコンテンツが含まれる場合だけです。

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

2 つのサブパスエクスポート。どちらも同じクレートからコンパイルされますが、異なる wasm アーティファクトを提供します:

各サブパスの 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 を確認してください — バージョン番号はリリースごとに変わります。

関連項目

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

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

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