justerm-wasm-decode 0.6.0

package/README.md

@@ -0,0 +1,131 @@
+# justerm-wasm-decode
+
+The **canonical web decoder** for [justerm](https://github.com/kihyun1998/justerm)'s binary wire
+format — the engine's native `decode` compiled to WASM, so a web consumer shares *one* decoder with
+the native backend instead of hand-writing (and re-syncing) a TypeScript mirror.
+
+Typical data path: the native engine `encode`s a damage frame in your backend, the bytes cross your
+IPC (e.g. a Tauri Channel), and in the webview this package decodes them into renderer-ready columns.
+
+The decoder owns the **fixed formats and standards** (the wire records, the colour-ref encoding, the
+flag bit positions, the xterm 16–255 colour formula). *Theme values* (your 16 ANSI colours + default
+fg/bg) and *render policy* (inverse/dim/bold→bright, the font atlas, the cursor) stay yours. See
+[ADR-0008](https://github.com/kihyun1998/justerm/blob/master/docs/adr/0008-wasm-decode-binding-separate-crate.md).
+
+> Version-locked to the `justerm` crate: this package's version equals the engine version, so pinning
+> one `justerm` version gives you a matching encoder (native) + decoder (this). `wireVersion()` lets
+> you assert agreement at load.
+
+## Install
+
+```sh
+npm install justerm-wasm-decode
+```
+
+## Usage
+
+```js
+import { decodeFrame, buildPalette, flags, wireVersion } from "justerm-wasm-decode";
+import { resolveRgb, decodeColorRef, FG, BG } from "justerm-wasm-decode/colors.js";
+
+// Bundler target (Vite/webpack): the above imports work directly.
+// Web target (no bundler): `import init, { ... } from "justerm-wasm-decode"; await init();` first.
+
+console.assert(wireVersion() === 2); // optional: assert the backend encoder agrees
+
+// --- once at startup / on theme change ---
+// buildPalette fills 0..15 from your scheme's ANSI colours and 16..255 from the
+// fixed xterm cube/grayscale. Keep your default fg/bg alongside (they are the
+// `Default` colour ref, resolved by role — not part of the 256).
+const palette = {
+  colors: buildPalette(Uint32Array.from(scheme.ansi16)), // 16 × 0xRRGGBB
+  defaultFg: scheme.defaultFg, // 0xRRGGBB
+  defaultBg: scheme.defaultBg,
+};
+const F = flags(); // bit constants, read once
+
+// --- per frame (e.g. an IPC message) ---
+const frame = decodeFrame(wireBytes); // throws on a malformed buffer
+// Structure-of-arrays columns (zero-copy views) + the span directory.
+const { codepoints, fg, bg, extra, link, spans } = frame;
+const flagBits = frame.flags; // note: the column; `flags()` above is the constants
+
+for (let s = 0; s < spans.length; s += 5) {
+  const line = spans[s], left = spans[s + 1], offset = spans[s + 3], count = spans[s + 4];
+  for (let k = 0; k < count; k++) {
+    const i = offset + k;
+    const col = left + k;
+
+    const fgRgb = resolveRgb(fg[i], palette, FG); // 0xRRGGBB
+    const bgRgb = resolveRgb(bg[i], palette, BG);
+    const bold = (flagBits[i] & F.bold) !== 0;
+    if (flagBits[i] & F.wide_char_spacer) continue; // trailing half of a wide glyph
+
+    // your adapter: map codepoints[i] -> atlas glyph, apply bold/inverse/dim,
+    // resolve extra[i]/link[i] via sideTable/linkTable, place at (line, col).
+  }
+}
+
+frame.free(); // release the column views — or scope with `using frame = decodeFrame(...)`
+```
+
+### Lifetime of the columns
+
+`codepoints` / `fg` / `bg` / `flags` / `extra` / `link` / `spans` are **zero-copy views** into WASM
+linear memory — the bulk data reaches JS with no per-cell boundary crossing. A view is invalidated
+when WASM memory grows, which the **next** `decodeFrame` call can trigger. Read or copy what you need
+from one frame before decoding the next, and `free()` the frame (or scope it with `using`) when done.
+The `palette` from `buildPalette` is an owned copy, so it is safe to keep across frames.
+
+## What the columns hold
+
+One entry per cell, in span order. `spans` is a flat directory: 5 `u32`s per span —
+`line, left, right, cell_offset, cell_count` — where cell `k` of a span is column index
+`cell_offset + k`.
+
+| Column | Type | Meaning |
+|--------|------|---------|
+| `codepoints` | `Uint32Array` | base Unicode codepoint (not an atlas glyph id) |
+| `fg` / `bg` | `Uint32Array` | colour references — pass to `resolveRgb` |
+| `flags` | `Uint16Array` | attribute + layout bits — test with `flags()` constants |
+| `extra` | `Uint16Array` | 1-based `sideTable` index for a grapheme cluster (`0` = none) |
+| `link` | `Uint16Array` | 1-based `linkTable` index for an OSC 8 hyperlink (`0` = none) |
+
+`frame.sideTable` (`string[]`) and `frame.linkTable` (`string[]`) carry the referenced clusters/URIs.
+
+## Cursor
+
+The frame also carries the engine's cursor as scalar getters (screen coordinates, 0-based):
+
+| Getter | Type | Meaning |
+|--------|------|---------|
+| `cursorRow` / `cursorCol` | `number` | cursor cell position |
+| `cursorVisible` | `boolean` | `false` when the engine hides the cursor (DECTCEM `?25l`) |
+
+justerm **reports** the cursor; *drawing* it is your adapter's job. beamterm has no cursor primitive,
+so draw the caret by inverting `fg`/`bg` on the cell at `(cursorRow, cursorCol)` (or an overlay quad).
+A pure cursor move is included in the frame's damage spans (the old **and** new cells), so an
+incremental cell-invert renderer clears the previous caret and inks the new one without ghosting.
+
+## Colour helpers
+
+- **`resolveRgb(ref, palette, role) → 0xRRGGBB`** — resolves a `fg[i]`/`bg[i]` ref: `Default` → the
+  role's default (`FG`/`BG`), `Indexed` → `palette.colors[i]`, `Rgb` → passthrough. Alloc-free; call
+  it per cell. It does **not** apply inverse/dim/hidden/bold→bright — that is your render policy.
+- **`buildPalette(ansi16) → Uint32Array(256)`** — the 256-colour table (0..15 your ANSI, 16..255 the
+  fixed xterm standard). Build once per scheme.
+- **`decodeColorRef(ref)`** — `{ kind: "default" } | { kind: "indexed", index } | { kind: "rgb", r,
+  g, b }`. For inspection; allocates, so prefer `resolveRgb` in the hot loop.
+
+## Flag constants (`flags()`)
+
+`bold`, `dim`, `italic`, `underline`, `blink`, `inverse`, `hidden`, `strikethrough`, `wide_char`,
+`wide_char_spacer`, `wrapline` — each the bit to AND against a `flags[i]` value. How to act on them
+(skip the spacer, bold→bright, dim) is your render policy. `wrapline` is engine reflow/copy metadata,
+usually ignored by a renderer.
+
+## License
+
+Dual-licensed under [MIT](https://github.com/kihyun1998/justerm/blob/master/LICENSE-MIT) or
+[Apache-2.0](https://github.com/kihyun1998/justerm/blob/master/LICENSE-APACHE), at your option —
+same as the `justerm` crate.

package/colors.d.ts

@@ -0,0 +1,27 @@
+// Types for the justerm-wasm-decode colour helpers (#36). See colors.js.
+
+/** Role for `Default` resolution: foreground. */
+export const FG: 0;
+/** Role for `Default` resolution: background. */
+export const BG: 1;
+export type Role = typeof FG | typeof BG;
+
+/** A resolved palette: 256 packed-RGB indices + the theme's default fg/bg. */
+export interface Palette {
+  /** `0..15` the theme's ANSI colours, `16..255` the xterm cube/grayscale. */
+  colors: Uint32Array;
+  defaultFg: number;
+  defaultBg: number;
+}
+
+/** A decoded colour reference. */
+export type ColorRef =
+  | { kind: "default" }
+  | { kind: "indexed"; index: number }
+  | { kind: "rgb"; r: number; g: number; b: number };
+
+/** Resolve a colour ref to a packed `0xRRGGBB` number (alloc-free; per cell). */
+export function resolveRgb(ref: number, palette: Palette, role: Role): number;
+
+/** Unpack a colour ref into a tagged object (inspection; not the hot loop). */
+export function decodeColorRef(ref: number): ColorRef;

package/colors.js

@@ -0,0 +1,48 @@
+// Colour helpers for the justerm-wasm-decode decoder (#36, ADR-0008).
+//
+// The single hand-written JS mirror in the package: these decode justerm's
+// tagged-u32 colour-ref encoding (high byte = tag — 0 Default, 1 Indexed, 2 Rgb;
+// low 24 bits = payload). They live in JS, not WASM, because `resolveRgb` runs
+// per cell and a WASM call per cell would defeat the zero-copy design (#34 AC3).
+// Kept in lockstep with Rust `encode_color` by a parity test (wasm-pack --node).
+
+/** Role for `Default` resolution: foreground. */
+export const FG = 0;
+/** Role for `Default` resolution: background. */
+export const BG = 1;
+
+/**
+ * Resolve a colour reference to a packed `0xRRGGBB` number. Alloc-free — call it
+ * per cell. `palette` is `{ colors: Uint32Array(256), defaultFg, defaultBg }`
+ * (build `colors` once per scheme with `buildPalette`); `role` is `FG` or `BG`,
+ * selecting which default a `Default` ref resolves to.
+ *
+ * Does NOT apply inverse/dim/hidden/bold→bright — those are render policy the
+ * caller applies afterward.
+ */
+export function resolveRgb(ref, palette, role) {
+  switch (ref >>> 24) {
+    case 0:
+      return role === FG ? palette.defaultFg : palette.defaultBg;
+    case 1:
+      return palette.colors[ref & 0xff];
+    default:
+      return ref & 0xffffff;
+  }
+}
+
+/**
+ * Unpack a colour reference into a tagged object — `{ kind: 'default' }`,
+ * `{ kind: 'indexed', index }`, or `{ kind: 'rgb', r, g, b }`. For inspection,
+ * not the hot loop (it allocates an object); use `resolveRgb` there.
+ */
+export function decodeColorRef(ref) {
+  switch (ref >>> 24) {
+    case 0:
+      return { kind: "default" };
+    case 1:
+      return { kind: "indexed", index: ref & 0xff };
+    default:
+      return { kind: "rgb", r: (ref >>> 16) & 0xff, g: (ref >>> 8) & 0xff, b: ref & 0xff };
+  }
+}

package/justerm_wasm_decode.d.ts

@@ -0,0 +1,159 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A decoded damage frame, presented for a web renderer.
+ *
+ * Scalars come via getters; cells are exposed as **structure-of-arrays** — one
+ * zero-copy typed-array column per field (`codepoints`/`fg`/`bg`/`flags`/
+ * `extra`/`link`) plus the `spans` directory — so a consumer reads `frame.fg[i]`
+ * with no byte-offset knowledge and no per-cell boundary crossing (#34/#35).
+ */
+export class DecodedFrame {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Per-cell background colour references (tagged `u32`s, as [`DecodedFrame::fg`]).
+     */
+    readonly bg: Uint32Array;
+    /**
+     * Per-cell base codepoints (`cell.c` as `u32`), in span order — one of the
+     * structure-of-arrays cell columns (#35). Zero-copy view into WASM memory;
+     * the bulk data reaches JS with no per-cell boundary crossing (#34 AC3).
+     *
+     * # Lifetime (applies to every column + `spans`)
+     * The returned array views WASM memory directly; it is invalidated if that
+     * memory grows (e.g. the next `decodeFrame` call allocates). Read it before
+     * the next decode.
+     */
+    readonly codepoints: Uint32Array;
+    readonly cols: number;
+    /**
+     * Whether the caret blinks (att610 `?12`). The engine reports the mode; the
+     * renderer does the animation (#81).
+     */
+    readonly cursorBlink: boolean;
+    /**
+     * Cursor column (screen coords, 0-based).
+     */
+    readonly cursorCol: number;
+    /**
+     * Cursor row (screen coords, 0-based). The consumer draws the caret here by
+     * cell-invert / overlay — justerm only reports where it is (#38).
+     */
+    readonly cursorRow: number;
+    /**
+     * Caret shape: `0` = Block, `1` = Underline, `2` = Bar (DECSCUSR #89). The
+     * consumer draws the shape; the engine only reports it (#81).
+     */
+    readonly cursorShape: number;
+    /**
+     * Whether the engine shows the cursor (DECTCEM `?25`). When `false` the
+     * consumer stops drawing the caret.
+     */
+    readonly cursorVisible: boolean;
+    /**
+     * Per-cell frame-local grapheme side-table index (`0` = none; else
+     * `sideTable[extra - 1]`).
+     */
+    readonly extra: Uint16Array;
+    /**
+     * Per-cell foreground colour references as tagged `u32`s (high byte = tag
+     * `Default|Indexed|Rgb`, low 24 = payload). Resolve with `resolveRgb`.
+     */
+    readonly fg: Uint32Array;
+    /**
+     * Per-cell `CellFlags` bits. Test with the constants from `flags()`.
+     */
+    readonly flags: Uint16Array;
+    readonly hasScroll: boolean;
+    /**
+     * `0` = Full (every row present), `1` = Partial (only the listed spans).
+     */
+    readonly kind: number;
+    /**
+     * Per-cell frame-local hyperlink index (`0` = none; else `linkTable[link - 1]`).
+     */
+    readonly link: Uint16Array;
+    /**
+     * This frame's OSC 8 hyperlink URIs, indexed by a cell's `link` field
+     * (1-based; index 0 means none). Small and rare, so copied to a JS array.
+     */
+    readonly linkTable: string[];
+    readonly rows: number;
+    readonly scrollBottom: number;
+    readonly scrollCount: number;
+    readonly scrollTop: number;
+    /**
+     * This frame's grapheme clusters, each joined into a string, indexed by a
+     * cell's `extra` field (1-based; index 0 means none). Small and rare, so
+     * copied to a JS array rather than viewed.
+     */
+    readonly sideTable: string[];
+    /**
+     * Span directory: 5 `u32`s per span — `line, left, right, cell_offset,
+     * cell_count` — where `cell_offset` indexes the cell columns (cell k of a
+     * span is column index `cell_offset + k`). JS walks this directory, never per
+     * cell (#34 AC3). Same zero-copy view lifetime as the columns.
+     */
+    readonly spans: Uint32Array;
+}
+
+/**
+ * The `CellFlags` bit positions, exported so a consumer tests `flags[i] & F.bold`
+ * without hard-coding bit values (#36). The values come straight from Rust
+ * `CellFlags`, so there is no JS mirror to drift. Read once and cache (e.g.
+ * destructure the result): the bits never change within a build.
+ */
+export class Flags {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    blink: number;
+    bold: number;
+    dim: number;
+    hidden: number;
+    inverse: number;
+    italic: number;
+    strikethrough: number;
+    underline: number;
+    wide_char_spacer: number;
+    wide_char: number;
+    wrapline: number;
+}
+
+/**
+ * Resolve a 16-colour ANSI scheme into the full xterm 256-colour table (#36).
+ *
+ * Slots `0..16` are the supplied ANSI colours (the theme's values); `16..256`
+ * are the fixed xterm 6×6×6 cube + grayscale ramp, computed here so a consumer
+ * never re-implements that standard. Returns an **owned** copy (built per scheme;
+ * it outlives many `decodeFrame` calls). `ansi` is expected to have 16 entries
+ * (extras ignored, missing treated as `0`). The default fg/bg are *not* part of
+ * the 256 — the consumer keeps them and passes them to `resolveRgb`.
+ */
+export function buildPalette(ansi: Uint32Array): Uint32Array;
+
+/**
+ * Decode a justerm wire buffer (ADR-0005) into a [`DecodedFrame`].
+ *
+ * On a malformed buffer this throws a JS `Error` carrying the `DecodeError`
+ * variant name — the validation a hand-written TS decoder would otherwise have
+ * to re-implement (and fuzz). Identical bytes yield a frame identical to the
+ * native `justerm_core::decode` (the build-parity test, #34 AC2).
+ */
+export function decodeFrame(bytes: Uint8Array): DecodedFrame;
+
+/**
+ * The `CellFlags` bit constants (see [`Flags`]).
+ */
+export function flags(): Flags;
+
+/**
+ * The wire-format version this decoder understands (the `VERSION` byte gating
+ * ADR-0005). A consumer can read it at load time to assert the WASM decoder and
+ * the backend encoder agree before any frame flows; `decodeFrame` also returns a
+ * `BadVersion` error on mismatch, so a stale artifact fails loudly.
+ */
+export function wireVersion(): number;

package/justerm_wasm_decode.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./justerm_wasm_decode.d.ts" */
+import * as wasm from "./justerm_wasm_decode_bg.wasm";
+import { __wbg_set_wasm } from "./justerm_wasm_decode_bg.js";
+
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    DecodedFrame, Flags, buildPalette, decodeFrame, flags, wireVersion
+} from "./justerm_wasm_decode_bg.js";

package/justerm_wasm_decode_bg.js

@@ -0,0 +1,575 @@
+/**
+ * A decoded damage frame, presented for a web renderer.
+ *
+ * Scalars come via getters; cells are exposed as **structure-of-arrays** — one
+ * zero-copy typed-array column per field (`codepoints`/`fg`/`bg`/`flags`/
+ * `extra`/`link`) plus the `spans` directory — so a consumer reads `frame.fg[i]`
+ * with no byte-offset knowledge and no per-cell boundary crossing (#34/#35).
+ */
+export class DecodedFrame {
+    static __wrap(ptr) {
+        const obj = Object.create(DecodedFrame.prototype);
+        obj.__wbg_ptr = ptr;
+        DecodedFrameFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        DecodedFrameFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_decodedframe_free(ptr, 0);
+    }
+    /**
+     * Per-cell background colour references (tagged `u32`s, as [`DecodedFrame::fg`]).
+     * @returns {Uint32Array}
+     */
+    get bg() {
+        const ret = wasm.decodedframe_bg(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Per-cell base codepoints (`cell.c` as `u32`), in span order — one of the
+     * structure-of-arrays cell columns (#35). Zero-copy view into WASM memory;
+     * the bulk data reaches JS with no per-cell boundary crossing (#34 AC3).
+     *
+     * # Lifetime (applies to every column + `spans`)
+     * The returned array views WASM memory directly; it is invalidated if that
+     * memory grows (e.g. the next `decodeFrame` call allocates). Read it before
+     * the next decode.
+     * @returns {Uint32Array}
+     */
+    get codepoints() {
+        const ret = wasm.decodedframe_codepoints(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get cols() {
+        const ret = wasm.decodedframe_cols(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Whether the caret blinks (att610 `?12`). The engine reports the mode; the
+     * renderer does the animation (#81).
+     * @returns {boolean}
+     */
+    get cursorBlink() {
+        const ret = wasm.decodedframe_cursorBlink(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Cursor column (screen coords, 0-based).
+     * @returns {number}
+     */
+    get cursorCol() {
+        const ret = wasm.decodedframe_cursorCol(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Cursor row (screen coords, 0-based). The consumer draws the caret here by
+     * cell-invert / overlay — justerm only reports where it is (#38).
+     * @returns {number}
+     */
+    get cursorRow() {
+        const ret = wasm.decodedframe_cursorRow(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Caret shape: `0` = Block, `1` = Underline, `2` = Bar (DECSCUSR #89). The
+     * consumer draws the shape; the engine only reports it (#81).
+     * @returns {number}
+     */
+    get cursorShape() {
+        const ret = wasm.decodedframe_cursorShape(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Whether the engine shows the cursor (DECTCEM `?25`). When `false` the
+     * consumer stops drawing the caret.
+     * @returns {boolean}
+     */
+    get cursorVisible() {
+        const ret = wasm.decodedframe_cursorVisible(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Per-cell frame-local grapheme side-table index (`0` = none; else
+     * `sideTable[extra - 1]`).
+     * @returns {Uint16Array}
+     */
+    get extra() {
+        const ret = wasm.decodedframe_extra(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Per-cell foreground colour references as tagged `u32`s (high byte = tag
+     * `Default|Indexed|Rgb`, low 24 = payload). Resolve with `resolveRgb`.
+     * @returns {Uint32Array}
+     */
+    get fg() {
+        const ret = wasm.decodedframe_fg(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Per-cell `CellFlags` bits. Test with the constants from `flags()`.
+     * @returns {Uint16Array}
+     */
+    get flags() {
+        const ret = wasm.decodedframe_flags(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {boolean}
+     */
+    get hasScroll() {
+        const ret = wasm.decodedframe_hasScroll(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * `0` = Full (every row present), `1` = Partial (only the listed spans).
+     * @returns {number}
+     */
+    get kind() {
+        const ret = wasm.decodedframe_kind(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Per-cell frame-local hyperlink index (`0` = none; else `linkTable[link - 1]`).
+     * @returns {Uint16Array}
+     */
+    get link() {
+        const ret = wasm.decodedframe_link(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * This frame's OSC 8 hyperlink URIs, indexed by a cell's `link` field
+     * (1-based; index 0 means none). Small and rare, so copied to a JS array.
+     * @returns {string[]}
+     */
+    get linkTable() {
+        const ret = wasm.decodedframe_linkTable(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @returns {number}
+     */
+    get rows() {
+        const ret = wasm.decodedframe_rows(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get scrollBottom() {
+        const ret = wasm.decodedframe_scrollBottom(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get scrollCount() {
+        const ret = wasm.decodedframe_scrollCount(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get scrollTop() {
+        const ret = wasm.decodedframe_scrollTop(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * This frame's grapheme clusters, each joined into a string, indexed by a
+     * cell's `extra` field (1-based; index 0 means none). Small and rare, so
+     * copied to a JS array rather than viewed.
+     * @returns {string[]}
+     */
+    get sideTable() {
+        const ret = wasm.decodedframe_sideTable(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * Span directory: 5 `u32`s per span — `line, left, right, cell_offset,
+     * cell_count` — where `cell_offset` indexes the cell columns (cell k of a
+     * span is column index `cell_offset + k`). JS walks this directory, never per
+     * cell (#34 AC3). Same zero-copy view lifetime as the columns.
+     * @returns {Uint32Array}
+     */
+    get spans() {
+        const ret = wasm.decodedframe_spans(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose) DecodedFrame.prototype[Symbol.dispose] = DecodedFrame.prototype.free;
+
+/**
+ * The `CellFlags` bit positions, exported so a consumer tests `flags[i] & F.bold`
+ * without hard-coding bit values (#36). The values come straight from Rust
+ * `CellFlags`, so there is no JS mirror to drift. Read once and cache (e.g.
+ * destructure the result): the bits never change within a build.
+ */
+export class Flags {
+    static __wrap(ptr) {
+        const obj = Object.create(Flags.prototype);
+        obj.__wbg_ptr = ptr;
+        FlagsFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        FlagsFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_flags_free(ptr, 0);
+    }
+    /**
+     * @returns {number}
+     */
+    get blink() {
+        const ret = wasm.__wbg_get_flags_blink(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get bold() {
+        const ret = wasm.__wbg_get_flags_bold(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get dim() {
+        const ret = wasm.__wbg_get_flags_dim(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get hidden() {
+        const ret = wasm.__wbg_get_flags_hidden(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get inverse() {
+        const ret = wasm.__wbg_get_flags_inverse(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get italic() {
+        const ret = wasm.__wbg_get_flags_italic(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get strikethrough() {
+        const ret = wasm.__wbg_get_flags_strikethrough(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get underline() {
+        const ret = wasm.__wbg_get_flags_underline(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get wide_char_spacer() {
+        const ret = wasm.__wbg_get_flags_wide_char_spacer(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get wide_char() {
+        const ret = wasm.__wbg_get_flags_wide_char(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get wrapline() {
+        const ret = wasm.__wbg_get_flags_wrapline(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @param {number} arg0
+     */
+    set blink(arg0) {
+        wasm.__wbg_set_flags_blink(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set bold(arg0) {
+        wasm.__wbg_set_flags_bold(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set dim(arg0) {
+        wasm.__wbg_set_flags_dim(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set hidden(arg0) {
+        wasm.__wbg_set_flags_hidden(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set inverse(arg0) {
+        wasm.__wbg_set_flags_inverse(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set italic(arg0) {
+        wasm.__wbg_set_flags_italic(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set strikethrough(arg0) {
+        wasm.__wbg_set_flags_strikethrough(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set underline(arg0) {
+        wasm.__wbg_set_flags_underline(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set wide_char_spacer(arg0) {
+        wasm.__wbg_set_flags_wide_char_spacer(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set wide_char(arg0) {
+        wasm.__wbg_set_flags_wide_char(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @param {number} arg0
+     */
+    set wrapline(arg0) {
+        wasm.__wbg_set_flags_wrapline(this.__wbg_ptr, arg0);
+    }
+}
+if (Symbol.dispose) Flags.prototype[Symbol.dispose] = Flags.prototype.free;
+
+/**
+ * Resolve a 16-colour ANSI scheme into the full xterm 256-colour table (#36).
+ *
+ * Slots `0..16` are the supplied ANSI colours (the theme's values); `16..256`
+ * are the fixed xterm 6×6×6 cube + grayscale ramp, computed here so a consumer
+ * never re-implements that standard. Returns an **owned** copy (built per scheme;
+ * it outlives many `decodeFrame` calls). `ansi` is expected to have 16 entries
+ * (extras ignored, missing treated as `0`). The default fg/bg are *not* part of
+ * the 256 — the consumer keeps them and passes them to `resolveRgb`.
+ * @param {Uint32Array} ansi
+ * @returns {Uint32Array}
+ */
+export function buildPalette(ansi) {
+    const ptr0 = passArray32ToWasm0(ansi, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.buildPalette(ptr0, len0);
+    var v2 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v2;
+}
+
+/**
+ * Decode a justerm wire buffer (ADR-0005) into a [`DecodedFrame`].
+ *
+ * On a malformed buffer this throws a JS `Error` carrying the `DecodeError`
+ * variant name — the validation a hand-written TS decoder would otherwise have
+ * to re-implement (and fuzz). Identical bytes yield a frame identical to the
+ * native `justerm_core::decode` (the build-parity test, #34 AC2).
+ * @param {Uint8Array} bytes
+ * @returns {DecodedFrame}
+ */
+export function decodeFrame(bytes) {
+    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.decodeFrame(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return DecodedFrame.__wrap(ret[0]);
+}
+
+/**
+ * The `CellFlags` bit constants (see [`Flags`]).
+ * @returns {Flags}
+ */
+export function flags() {
+    const ret = wasm.flags();
+    return Flags.__wrap(ret);
+}
+
+/**
+ * The wire-format version this decoder understands (the `VERSION` byte gating
+ * ADR-0005). A consumer can read it at load time to assert the WASM decoder and
+ * the backend encoder agree before any frame flows; `decodeFrame` also returns a
+ * `BadVersion` error on mismatch, so a stale artifact fails loudly.
+ * @returns {number}
+ */
+export function wireVersion() {
+    const ret = wasm.wireVersion();
+    return ret;
+}
+export function __wbg___wbindgen_throw_ea4887a5f8f9a9db(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+}
+export function __wbindgen_cast_0000000000000001(arg0, arg1) {
+    // Cast intrinsic for `Ref(Slice(U16)) -> NamedExternref("Uint16Array")`.
+    const ret = getArrayU16FromWasm0(arg0, arg1);
+    return ret;
+}
+export function __wbindgen_cast_0000000000000002(arg0, arg1) {
+    // Cast intrinsic for `Ref(Slice(U32)) -> NamedExternref("Uint32Array")`.
+    const ret = getArrayU32FromWasm0(arg0, arg1);
+    return ret;
+}
+export function __wbindgen_cast_0000000000000003(arg0, arg1) {
+    // Cast intrinsic for `Ref(String) -> Externref`.
+    const ret = getStringFromWasm0(arg0, arg1);
+    return ret;
+}
+export function __wbindgen_init_externref_table() {
+    const table = wasm.__wbindgen_externrefs;
+    const offset = table.grow(4);
+    table.set(0, undefined);
+    table.set(offset + 0, undefined);
+    table.set(offset + 1, null);
+    table.set(offset + 2, true);
+    table.set(offset + 3, false);
+}
+const DecodedFrameFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_decodedframe_free(ptr, 1));
+const FlagsFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_flags_free(ptr, 1));
+
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
+function getArrayU16FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint16ArrayMemory0().subarray(ptr / 2, ptr / 2 + len);
+}
+
+function getArrayU32FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint16ArrayMemory0 = null;
+function getUint16ArrayMemory0() {
+    if (cachedUint16ArrayMemory0 === null || cachedUint16ArrayMemory0.byteLength === 0) {
+        cachedUint16ArrayMemory0 = new Uint16Array(wasm.memory.buffer);
+    }
+    return cachedUint16ArrayMemory0;
+}
+
+let cachedUint32ArrayMemory0 = null;
+function getUint32ArrayMemory0() {
+    if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
+        cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
+    }
+    return cachedUint32ArrayMemory0;
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passArray32ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 4, 4) >>> 0;
+    getUint32ArrayMemory0().set(arg, ptr / 4);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+let WASM_VECTOR_LEN = 0;
+
+
+let wasm;
+export function __wbg_set_wasm(val) {
+    wasm = val;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "justerm-wasm-decode",
+  "type": "module",
+  "description": "WASM decoder for justerm's wire format: structure-of-arrays cell columns + format-owned colour/flag helpers. See ADR-0008.",
+  "version": "0.6.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kihyun1998/justerm"
+  },
+  "files": [
+    "justerm_wasm_decode_bg.wasm",
+    "justerm_wasm_decode.js",
+    "justerm_wasm_decode_bg.js",
+    "justerm_wasm_decode.d.ts",
+    "colors.js",
+    "colors.d.ts"
+  ],
+  "main": "justerm_wasm_decode.js",
+  "types": "justerm_wasm_decode.d.ts",
+  "sideEffects": [
+    "./justerm_wasm_decode.js",
+    "./snippets/*"
+  ]
+}