Skip to content
sdlc

WASM/TypeScript consumption surface

Status: open/planned · Kind: adapter · Audience: system

Summary

Section titled “Summary”
  • One wasm-bindgen build with generated TypeScript types is the sole boundary between the Rust core and every TS consumer — browser and Node served by packaging, not by parallel bindings or reimplementations.
  • Reads speak mdast-compatible JSON (unist position semantics); edits are structured edit descriptions applied CST-side.
  • The TS markdown-contract package becomes a strongly-typed wrapper over this surface once parity holds; TS reimplementation of core logic is frozen.

Statement

Section titled “Statement”

The fleet’s TS consumers — polish UI, sdlc tooling, determined apps, doc sites — must share one implementation of parsing, validation, and editing. The boundary is one binding crate: wasm-bindgen bindings, tsify-generated types, conditional main/browser/exports packaging with an environment-detecting loader — the shape oxc and biome converged on after abandoning dual wasm+native bindings. Findings, typed models, and mdast views cross as JSON with frozen interchange shapes; napi-rs is admitted later only under demonstrated performance need for large-vault batch work.

What it provides

Section titled “What it provides”
  • @-scoped npm package(s): WASM artifact + typed wrapper, dual node/browser entry, sync Node init and async browser init.
  • Generated .d.ts from the Rust type layer — no hand-maintained type mirrors (the 1709-line lint-rule table is the cautionary example).
  • mdast-compatible read view so unified/remark ecosystem intuitions and tooling transfer.
  • Stable interchange shapes: Finding, typed document model, edit descriptions.
  • Feature-gated builds from the one binding crate (lite read-only through full vault) — separate wasm packages don’t share binary payload, so cut points are deliberate.
  • Standalone per-tier packages only on proven external demand (the B-MDU7 promotion bar applied to npm); the vault plane stays exposable because vault-kernel’s storage backend is a trait.

Underlying implementation

Section titled “Underlying implementation”

Precedent: markdown-contract PR #249 (WASM spike, GO — 404 KiB brotli, JSON boundary, sync/async init findings reusable directly). Built by M-F4RZ-wasm-ts-distribution. Packaging lesson source: oxc’s retrospective on abandoning dual bindings; biome’s @biomejs/js-api loader shim.

← Back to Capabilities