satteri 0.9.4 → 0.10.0

package/dist/op-stream.d.ts

@@ -5,21 +5,14 @@
  * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
  * values in generated/wire-constants.ts) — the only structural encoding for
  * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
- * char codes when short ASCII, `encodeInto` otherwise).
+ * char codes when short ASCII, `encodeInto` otherwise). `CommandBuffer`
+ * extends this class so payloads are emitted directly into the command
+ * bytes, with no intermediate opstream buffer or copy.
  */
 import { ByteWriter } from "./byte-writer.js";
-export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
 export declare class OpWriter extends ByteWriter {
-    #private;
-    constructor();
-    /**
-     * Start a compile on this (shared, module-level) writer. Encoding evaluates
-     * plugin-supplied getters and `toJSON`; if one of those calls a context
-     * mutation, the nested compile would reset the stream under the outer one
-     * and corrupt it silently — throw instead. Pair with `end` in a `finally`.
-     */
-    begin(): void;
-    end(): void;
+    constructor(initialSize?: number);
     open(type: number): void;
     close(): void;
     str(field: number, s: string): void;

package/dist/op-stream.js

@@ -5,32 +5,17 @@
  * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
  * values in generated/wire-constants.ts) — the only structural encoding for
  * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
- * char codes when short ASCII, `encodeInto` otherwise).
+ * char codes when short ASCII, `encodeInto` otherwise). `CommandBuffer`
+ * extends this class so payloads are emitted directly into the command
+ * bytes, with no intermediate opstream buffer or copy.
  */
 import { ByteWriter } from "./byte-writer.js";
 import { OP_OPEN, OP_CLOSE, OP_REF, OP_KEEP_CHILDREN, OP_STR, OP_U8, OP_U32, OP_BOOL, OP_DATA, OP_PROP, OP_ALIGN, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
 // Re-exported so visitors/readers keep importing wire constants from here.
-export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
 export class OpWriter extends ByteWriter {
-    #encoding = false;
-    constructor() {
-        super(512);
-    }
-    /**
-     * Start a compile on this (shared, module-level) writer. Encoding evaluates
-     * plugin-supplied getters and `toJSON`; if one of those calls a context
-     * mutation, the nested compile would reset the stream under the outer one
-     * and corrupt it silently — throw instead. Pair with `end` in a `finally`.
-     */
-    begin() {
-        if (this.#encoding) {
-            throw new Error("reentrant op-stream compile: a node getter or toJSON invoked a context mutation while its node was being encoded");
-        }
-        this.#encoding = true;
-        this.reset();
-    }
-    end() {
-        this.#encoding = false;
+    constructor(initialSize = 512) {
+        super(initialSize);
     }
     open(type) {
         this.ensure(2);

package/dist/plugin.d.ts

@@ -1,20 +1,46 @@
 import type { MdastPluginInstance } from "./mdast/mdast-visitor.js";
 import type { HastVisitorInstance } from "./hast/hast-visitor.js";
+import type { Data, SourceFormat } from "./types.js";
+/**
+ * What a plugin factory is told about the document, before it is parsed.
+ *
+ * Return `null`, `undefined` or `false` from the factory to leave the plugin
+ * out of the pipeline for this document.
+ */
+export interface PluginFactoryContext {
+    /** The `fileURL` compile option, or `undefined` when none was given. */
+    readonly fileURL: URL | undefined;
+    /** Which kind of document is being compiled. */
+    readonly sourceFormat: SourceFormat;
+    /** The unparsed source, minus a leading BOM as the parser sees it. Intended
+     *  for cheap checks, not for parsing Markdown. */
+    readonly source: string;
+    /** The document-level data bag, before any plugin has run. */
+    readonly data: Data;
+}
 export type MdastPluginDefinition = MdastPluginInstance & {
     name: string;
 };
 export type HastPluginDefinition = HastVisitorInstance & {
     name: string;
 };
-/**
- * Entry accepted by `mdastPlugins`: a definition reused across documents,
- * or a factory called once per compile so closures reset per document.
- */
-export type MdastPluginInput = MdastPluginDefinition | (() => MdastPluginDefinition);
-/**
- * Entry accepted by `hastPlugins`: a definition reused across documents,
- * or a factory called once per compile so closures reset per document.
- */
-export type HastPluginInput = HastPluginDefinition | (() => HastPluginDefinition);
+type PluginEntry<D> = D | ((ctx: PluginFactoryContext) => PluginEntry<D>) | readonly PluginEntry<D>[] | null | undefined | false;
+/** Entry accepted by `mdastPlugins`. */
+export type MdastPluginEntry = PluginEntry<MdastPluginDefinition>;
+/** Entry accepted by `hastPlugins`. */
+export type HastPluginEntry = PluginEntry<HastPluginDefinition>;
+/** Value accepted by the `mdastPlugins` option. */
+export type MdastPluginList = readonly MdastPluginEntry[];
+/** Value accepted by the `hastPlugins` option. */
+export type HastPluginList = readonly HastPluginEntry[];
+/** Older name for {@link MdastPluginEntry}. */
+export type MdastPluginInput = MdastPluginEntry;
+/** Older name for {@link HastPluginEntry}. */
+export type HastPluginInput = HastPluginEntry;
+/** The one place a plugin option becomes the definition array the pipeline
+ *  runs. Factories resolve here and nowhere else, so each is called once per
+ *  compile no matter how deeply it is nested. */
+export declare function normalizePlugins<D>(entries: readonly PluginEntry<D>[], option: string, source: string, fileURL: URL | undefined, sourceFormat: SourceFormat, data: Data): D[];
 export declare function defineMdastPlugin<P extends MdastPluginDefinition>(definition: P): P;
 export declare function defineHastPlugin<P extends HastPluginDefinition>(definition: P): P;
+export {};

package/dist/plugin.js

@@ -1,6 +1,54 @@
+/** Bounds factory-in-factory nesting. Real presets nest one level; anything
+ *  deeper is a factory that leads back to itself, which would otherwise recurse
+ *  until the stack overflows. */
+const MAX_FACTORY_DEPTH = 10;
+/** The one place a plugin option becomes the definition array the pipeline
+ *  runs. Factories resolve here and nowhere else, so each is called once per
+ *  compile no matter how deeply it is nested. */
+export function normalizePlugins(entries, option, source, fileURL, sourceFormat, data) {
+    const out = [];
+    // Built lazily so a list with no factories allocates no context.
+    let ctx;
+    const walk = (entry, factoryDepth) => {
+        if (entry === null || entry === undefined || entry === false)
+            return;
+        if (Array.isArray(entry)) {
+            for (const item of entry)
+                walk(item, factoryDepth);
+            return;
+        }
+        if (typeof entry === "function") {
+            if (factoryDepth === 0) {
+                throw new Error(`${option}: plugin factory nesting is too deep. A factory most likely returns itself. ` +
+                    `A factory may return a plugin or a list of plugins, but that list must not lead back to the same factory.`);
+            }
+            // `data` stays mutable on purpose: it is the live bag the visitors share.
+            ctx ??= Object.freeze({
+                fileURL,
+                sourceFormat,
+                // The parser drops a leading BOM, so `ctx.source` in a visitor lacks it too.
+                source: source.startsWith("\uFEFF") ? source.slice(1) : source,
+                data,
+            });
+            walk(entry(ctx), factoryDepth - 1);
+            return;
+        }
+        if (typeof entry !== "object") {
+            throw new Error(`${option}: expected a plugin, a factory, a list, or null/undefined/false`);
+        }
+        if (typeof entry.then === "function") {
+            throw new Error(`${option}: a Promise is not a plugin. Plugin factories must be synchronous; ` +
+                `await the value first and pass the plugin itself.`);
+        }
+        out.push(entry);
+    };
+    for (const entry of entries)
+        walk(entry, MAX_FACTORY_DEPTH);
+    return out;
+}
 // Generic so the inferred plugin type preserves each visitor's *actual* return
-// type. That lets call sites of `markdownToHtml`/`mdxToJs` distinguish sync
-// plugins from async ones in their conditional return type.
+// type. That lets the compile entry points distinguish sync plugins from async
+// ones in their conditional return type.
 export function defineMdastPlugin(definition) {
     if (!definition.name) {
         throw new Error("Plugin definition must have a name");

package/dist/string-pool.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Byte-offset to UTF-16-offset remap for a wire string pool holding multibyte
+ * sequences, so the once-decoded pool can still be sliced with `substring`
+ * instead of a `TextDecoder` call per string.
+ */
+export declare class PoolOffsets {
+    #private;
+    /** `extraBytes` is the pool's byte length minus its UTF-16 length, which
+     *  bounds the multibyte character count: each one costs at least one byte. */
+    constructor(bytes: Uint8Array, extraBytes: number);
+    /** Both ends of a string ref sit on character boundaries, so the remap is exact. */
+    slice(text: string, offset: number, len: number): string;
+}

package/dist/string-pool.js

@@ -0,0 +1,91 @@
+const NO_WORDS = new Uint32Array(0);
+/**
+ * Byte-offset to UTF-16-offset remap for a wire string pool holding multibyte
+ * sequences, so the once-decoded pool can still be sliced with `substring`
+ * instead of a `TextDecoder` call per string.
+ */
+export class PoolOffsets {
+    #starts;
+    #shifts;
+    #count;
+    #hint = 0;
+    /** `extraBytes` is the pool's byte length minus its UTF-16 length, which
+     *  bounds the multibyte character count: each one costs at least one byte. */
+    constructor(bytes, extraBytes) {
+        const starts = new Uint32Array(extraBytes);
+        const shifts = new Uint32Array(extraBytes);
+        const n = bytes.length;
+        const pad = (4 - (bytes.byteOffset & 3)) & 3;
+        const wordCount = n > pad ? (n - pad) >> 2 : 0;
+        // A pool shorter than its alignment padding would put the view past the buffer.
+        const words = wordCount === 0 ? NO_WORDS : new Uint32Array(bytes.buffer, bytes.byteOffset + pad, wordCount);
+        let count = 0;
+        let shift = 0;
+        let i = 0;
+        for (;;) {
+            // `i` is always at a character boundary, so a word with no high bits set
+            // cannot hide the start of one and the whole word is skippable.
+            if (i >= pad && ((i - pad) & 3) === 0) {
+                let w = (i - pad) >> 2;
+                while (w < wordCount && ((words[w] ?? 0) & 0x80808080) === 0)
+                    w++;
+                i = pad + (w << 2);
+            }
+            if (i >= n)
+                break;
+            const lead = bytes[i] ?? 0;
+            if (lead < 0x80) {
+                i++;
+                continue;
+            }
+            starts[count] = i;
+            if (lead < 0xe0) {
+                shift += 1;
+                i += 2;
+            }
+            else if (lead < 0xf0) {
+                shift += 2;
+                i += 3;
+            }
+            else {
+                shift += 2;
+                i += 4;
+            }
+            shifts[count] = shift;
+            count++;
+        }
+        this.#starts = starts;
+        this.#shifts = shifts;
+        this.#count = count;
+    }
+    /** How many multibyte characters start strictly before `byteOffset`. */
+    #seek(byteOffset) {
+        const starts = this.#starts;
+        const count = this.#count;
+        const hint = this.#hint;
+        if ((hint === count || (starts[hint] ?? 0) >= byteOffset) &&
+            (hint === 0 || (starts[hint - 1] ?? 0) < byteOffset)) {
+            return hint;
+        }
+        let lo = 0;
+        let hi = count;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if ((starts[mid] ?? 0) < byteOffset)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        this.#hint = lo;
+        return lo;
+    }
+    #shiftAt(index) {
+        return index === 0 ? 0 : (this.#shifts[index - 1] ?? 0);
+    }
+    /** Both ends of a string ref sit on character boundaries, so the remap is exact. */
+    slice(text, offset, len) {
+        const start = offset - this.#shiftAt(this.#seek(offset));
+        const endByte = offset + len;
+        return text.substring(start, endByte - this.#shiftAt(this.#seek(endByte)));
+    }
+}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { Position } from "unist";
-import type { Literal as MdastLiteral, Nodes as MdastStdNodes, Parent as MdastParent, PhrasingContent } from "mdast";
+import type { Data as MdastData, Literal as MdastLiteral, Nodes as MdastStdNodes, Parent as MdastParent, PhrasingContent, BlockContent } from "mdast";
 import type { Literal as HastLiteral, Nodes as HastStdNodes } from "hast";
 export type { Position, Point } from "unist";
 export type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute as MdxJsxAttributeNode, MdxJsxExpressionAttribute as MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpression as MdxJsxAttributeValueExpressionNode, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./mdx-types.js";
@@ -24,6 +24,40 @@ export interface Subscript extends MdastParent {
     type: "subscript";
     children: PhrasingContent[];
 }
+export interface DescriptionList extends MdastParent {
+    type: "descriptionList";
+    children: (DescriptionTerm | DescriptionDetails)[];
+}
+export interface DescriptionTerm extends MdastParent {
+    type: "descriptionTerm";
+    children: PhrasingContent[];
+}
+export interface DescriptionDetails extends MdastParent {
+    type: "descriptionDetails";
+    children: BlockContent[];
+    /** Loose definitions wrap their content in a `<p>`; tight ones don't. */
+    spread?: boolean;
+}
+/**
+ * A user-defined mdast node. `type` is an arbitrary string the plugin chooses
+ * (e.g. `"section"`); it round-trips and is surfaced back as `node.type`. Pass
+ * one to `ctx.replaceNode` / `insertBefore` / `appendChild`, etc.
+ *
+ * Works as either shape:
+ * - a **parent** with `children` renders to an element through `data.hName`
+ *   (default `<div>`), merges `data.hProperties`, and renders its children;
+ * - a **leaf** with a non-empty `value` (and no `children` or `data.h*`)
+ *   renders to an HTML text node.
+ *
+ * Only these fields survive the round trip; put anything else in `data`.
+ */
+export interface Custom {
+    type: string;
+    children?: (MdastNode | Custom)[];
+    value?: string;
+    data?: MdastData;
+    position?: Position;
+}
 declare module "mdast" {
     interface FrontmatterContentMap {
         toml: Toml;
@@ -34,6 +68,9 @@ declare module "mdast" {
         inlineMath: InlineMath;
         superscript: Superscript;
         subscript: Subscript;
+        descriptionList: DescriptionList;
+        descriptionTerm: DescriptionTerm;
+        descriptionDetails: DescriptionDetails;
     }
     interface PhrasingContentMap {
         inlineMath: InlineMath;
@@ -86,6 +123,12 @@ export interface DataMap {
  * string key holding any value, plus the typed keys registered in {@link DataMap}.
  */
 export type Data = Record<string, unknown> & Partial<DataMap>;
+/**
+ * The source format a plugin is running against, surfaced as `ctx.sourceFormat`:
+ * `"markdown"` for a plain Markdown compile, `"mdx"` for an MDX one. Lets a
+ * plugin shared between both pipelines branch on which it is handling.
+ */
+export type SourceFormat = "markdown" | "mdx";
 export interface StringRefRaw {
     offset: number;
     len: number;

package/dist/visitor-shared.d.ts

@@ -5,19 +5,42 @@
  * it polymorphic.
  */
 import type { CommandBuffer } from "./command-buffer.js";
+/** Plugin-level configuration, set via `options` on a plugin definition. */
+export interface PluginOptions {
+    /**
+     * Set to `true` if any visitor reads `node.position`. When no plugin in the
+     * pipeline opts in, source-position tracking is skipped during parsing
+     * (~15% faster parse), and `node.position` is `undefined`.
+     */
+    position?: boolean;
+}
+export declare const ROOT_NODE_ID = 0;
+export declare function rootReplacementError(content: unknown): Error;
+/** Hooks subscribe to node 0 by node type, so a document left headed by anything
+ *  but a `root` silently stops firing them, in this phase and every later one. */
+export declare function requireRootReplacement<T>(content: T): T;
 export declare function asArray<T>(value: T | T[]): T[];
 /** Thrown when declarative replacement content can't be compiled to the
  *  structural op-stream — an unsupported node type (e.g. a bare `root`/`doctype`
  *  handed in as content) or an out-of-range numeric field. The op-stream is the
  *  only structural encoding, so this is a hard error rather than a fallback. */
 export declare function unencodableContentError(content: unknown): Error;
+/** Per handle, so membership alone proves ownership and the read path needs no marker of its own. */
+export type NodeRefs = WeakMap<object, number>;
+/** Separates "belongs to another tree" from "never had an id"; arena ids are never negative. */
+export declare const FOREIGN_REF = -1;
+/** `_refs` rides on the prototype, surviving neither a spread copy nor an object literal. */
+export declare function crossPipelineForeign(node: object): number | undefined;
 /**
  * Arena id for a node passed to a context method, via a per-kind `nid` lookup
- * (closure keeps each kind's call site monomorphic). Plugin-built nodes have
- * no id; without this check the id would coerce to 0 in the command buffer
- * and the mutation would silently target the document root.
+ * (closure keeps each kind's call site monomorphic) resolved against the
+ * edited tree's own refs. Plugin-built nodes have no id; without this check
+ * the id would coerce to 0 in the command buffer and the mutation would
+ * silently target the document root. A node read from another tree has an id
+ * that is meaningless here, and one that happens to be in range would edit an
+ * unrelated node.
  */
-export declare function makeRequireNid<TNode>(nid: (node: TNode) => number | undefined): (node: TNode, method: string) => number;
+export declare function makeRequireNid<TNode>(nid: (node: TNode, refs: NodeRefs) => number | undefined): (node: TNode, method: string, refs: NodeRefs) => number;
 /** Concatenate the return-value and context command buffers for one pass,
  *  resetting both for reuse. */
 export declare function mergeAndReset(returnBuffer: CommandBuffer, ctx: {

package/dist/visitor-shared.js

@@ -5,6 +5,19 @@
  * it polymorphic.
  */
 const EMPTY_BYTES = new Uint8Array(0);
+export const ROOT_NODE_ID = 0;
+export function rootReplacementError(content) {
+    const type = content?.type;
+    return new Error(`satteri: replaceNode on the document root takes a \`root\`${typeof type === "string" ? `, not "${type}"` : ""}. Pass { type: "root", children: [...] } to swap the document, ` +
+        'or setProperty(root, "children", [...]) to swap only its children.');
+}
+/** Hooks subscribe to node 0 by node type, so a document left headed by anything
+ *  but a `root` silently stops firing them, in this phase and every later one. */
+export function requireRootReplacement(content) {
+    if (content?.type === "root")
+        return content;
+    throw rootReplacementError(content);
+}
 export function asArray(value) {
     return Array.isArray(value) ? value : [value];
 }
@@ -17,20 +30,33 @@ export function unencodableContentError(content) {
     return new Error(`satteri: cannot encode replacement content${typeof type === "string" ? ` of type "${type}"` : ""} ` +
         "into the structural op-stream — unsupported node type or out-of-range numeric field.");
 }
+/** Separates "belongs to another tree" from "never had an id"; arena ids are never negative. */
+export const FOREIGN_REF = -1;
+/** `_refs` rides on the prototype, surviving neither a spread copy nor an object literal. */
+export function crossPipelineForeign(node) {
+    // Probed before the own-property call: plugin-built content misses here, and that is the hot case.
+    if (node._refs === undefined)
+        return undefined;
+    return Object.hasOwn(node, "_refs") ? undefined : FOREIGN_REF;
+}
 /**
  * Arena id for a node passed to a context method, via a per-kind `nid` lookup
- * (closure keeps each kind's call site monomorphic). Plugin-built nodes have
- * no id; without this check the id would coerce to 0 in the command buffer
- * and the mutation would silently target the document root.
+ * (closure keeps each kind's call site monomorphic) resolved against the
+ * edited tree's own refs. Plugin-built nodes have no id; without this check
+ * the id would coerce to 0 in the command buffer and the mutation would
+ * silently target the document root. A node read from another tree has an id
+ * that is meaningless here, and one that happens to be in range would edit an
+ * unrelated node.
  */
 export function makeRequireNid(nid) {
-    return (node, method) => {
-        const id = nid(node);
-        if (id === undefined) {
-            throw new Error(`${method}: node has no arena id — it was built in JS, not read from this tree. ` +
-                `Pass plugin-built nodes as new content (e.g. the second argument of insertAfter).`);
-        }
-        return id;
+    return (node, method, refs) => {
+        const id = nid(node, refs);
+        if (id !== undefined && id !== FOREIGN_REF)
+            return id;
+        throw new Error(`${method}: invalid node id — this node has no id in the tree being edited. Either it was ` +
+            `built in JS, in which case pass it as new content (e.g. the second argument of ` +
+            `insertAfter), or it was read from another tree (a different document, the mdast phase of ` +
+            `this one, or an earlier compile), in which case match it again in this pass.`);
     };
 }
 /** Concatenate the return-value and context command buffers for one pass,

package/dist/wire-read.js

@@ -3,7 +3,9 @@
  * the hand-written decoders and the generated layout decoder so both interpret
  * the bytes identically.
  */
-const textDecoder = new TextDecoder("utf-8");
+// `ignoreBOM` keeps a value-initial U+FEFF: each string is decoded from its
+// own byte range, so the default BOM strip would eat it as content.
+const textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
 /** Read a u16 (LE) at `off`. */
 export function ru16(view, off) {
     return view.getUint16(off, true);