animader 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "animader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "JS glue for animader.wasm, the deterministic runtime",
+  "license": "CC0-1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./log": "./src/log.js",
+    "./route": "./src/route.js",
+    "./session": "./src/session.js",
+    "./piece": "./src/piece.js",
+    "./wasm": "./wasm/animader.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "wasm",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/index.js

@@ -0,0 +1,482 @@
+// animader - JS glue around animader.wasm.
+//
+// The log tier is a pure function of a session document and its 'ANEV'
+// blob. This file mirrors src/wasm_entry.zig's zone convention byte for
+// byte: the host writes the text or the blob into
+// `exports.anm_log_inPtr()`, calls one of the six exports with the byte
+// length, and reads `anm_log_outLen()` bytes from `anm_log_outPtr()`.
+// 'ANEV' itself (src/Abi.zig) is:
+//
+//   [magic u32]['ANEV'][version u32][count u32][strtab_len u32]
+//   count x 32-byte records
+//   strtab_len bytes: NUL-separated strings referenced by index
+//
+// Return convention, mirrored from the entry header: a call answers a
+// byte length (>= 0) or a negative status, never data:
+//
+//   -1  diagnostics; `LogError.code` is the first EventLog code
+//   -2  bad call (over a zone cap, malformed blob, no cached session)
+//   -3  out of memory
+//   -4  output over its zone
+//   -5  a component over its cap
+//
+// Session state: 'ANEV' carries no `(session ...)` header, so the wasm
+// module caches the session from the last clean parse; `encode` renders
+// that session with the blob's records. `parse` must therefore run before
+// `encode` in the same instance.
+//
+// `pointerState` decodes the boundary's 64-byte little-endian
+// PointerState wire (the field-by-field layout is in src/wasm_entry.zig's
+// header) into the same field object the native fold produces.
+//
+// Memory views are re-taken from `exports.memory.buffer` on every call
+// (the pacer discipline): a view taken before a grow would detach. This
+// module's zones never grow, but the glue does not rely on that.
+
+const MAGIC = 0x56454e41; // 'ANEV' read little-endian
+const VERSION = 1;
+const HEADER_LEN = 20;
+const RECORD_LEN = 32;
+const MAX_EVENTS = 1 << 20;
+const MAX_STRTAB = 1 << 16;
+const NO_CODE = 0xffff;
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+const POINTER_STATE_LEN = 64;
+
+const STATUS_DIAGNOSTICS = -1;
+const STATUS_BAD_CALL = -2;
+const STATUS_OOM = -3;
+const STATUS_OUTPUT_TOO_SMALL = -4;
+const STATUS_COMPONENT_TOO_LARGE = -5;
+
+/** Kind ordinals, append-only on the wire (`EventLog.Kind`). */
+export const KINDS = [
+  "resize",
+  "down",
+  "move",
+  "up",
+  "wheel",
+  "key",
+  "custom",
+  "input-write",
+  "mark",
+  "adjust",
+  "reset",
+  "cancel",
+  "derived",
+];
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+// SJON's executable-plugin dispatch import (`env.sjon_host_invoke_plugin`).
+// The session schema declares no executable plugins, so it is never
+// called; returning 0 maps to a clean SJON diagnostic rather than a trap.
+// Every instantiation must provide it.
+export const IMPORTS = { env: { sjon_host_invoke_plugin: () => 0 } };
+
+/** A boundary failure or a malformed 'ANEV' blob. */
+export class LogError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ status?: number | null, code?: number | null }} [details]
+   *   `status` is the boundary's negative return (null for a JS-side
+   *   defect); `code` is the first EventLog diagnostic code for a
+   *   diagnosed parse.
+   */
+  constructor(message, { status = null, code = null } = {}) {
+    super(message);
+    this.name = "LogError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** The status semantics, so a caller does not have to know the integers. */
+export const STATUS = {
+  DIAGNOSTICS: STATUS_DIAGNOSTICS,
+  BAD_CALL: STATUS_BAD_CALL,
+  OOM: STATUS_OOM,
+  OUTPUT_TOO_SMALL: STATUS_OUTPUT_TOO_SMALL,
+  COMPONENT_TOO_LARGE: STATUS_COMPONENT_TOO_LARGE,
+};
+
+const describeStatus = (status) => {
+  switch (status) {
+    case STATUS_DIAGNOSTICS:
+      return "the session has diagnostics";
+    case STATUS_BAD_CALL:
+      return "bad call";
+    case STATUS_OOM:
+      return "out of memory";
+    case STATUS_OUTPUT_TOO_SMALL:
+      return "the output would not fit its zone";
+    case STATUS_COMPONENT_TOO_LARGE:
+      return "a session component is over its cap";
+    default:
+      return `unknown status ${status}`;
+  }
+};
+
+function toBytes(blob) {
+  if (blob instanceof Uint8Array) return blob;
+  if (blob instanceof ArrayBuffer) return new Uint8Array(blob);
+  if (ArrayBuffer.isView(blob)) return new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);
+  throw new TypeError("animader: expected an ArrayBuffer or a typed array");
+}
+
+function micros(value, what) {
+  if (!Number.isSafeInteger(value)) {
+    throw new LogError(`animader: ${what} must be a safe integer (microseconds), got ${value}`, {
+      status: STATUS_BAD_CALL,
+    });
+  }
+  return value;
+}
+
+/** The decoded string table: one entry per NUL-separated name. */
+function decodeStrings(bytes) {
+  const out = [];
+  let pos = 0;
+  while (pos < bytes.length) {
+    const end = bytes.indexOf(0, pos);
+    if (end === -1) {
+      out.push(decoder.decode(bytes.subarray(pos)));
+      break;
+    }
+    out.push(decoder.decode(bytes.subarray(pos, end)));
+    pos = end + 1;
+  }
+  return out;
+}
+
+/** The loaded boundary artifact and the JS-side 'ANEV' decode. */
+export class Log {
+  #e;
+
+  /**
+   * Instantiate the artifact synchronously (node, tests). `bytes` is the
+   * built animader.wasm, e.g. from `readFileSync`.
+   * @param {BufferSource} bytes
+   * @returns {Log}
+   */
+  static loadSync(bytes) {
+    return new Log(new WebAssembly.Instance(new WebAssembly.Module(bytes), IMPORTS));
+  }
+
+  /**
+   * Instantiate the artifact from bytes or a compiled module (browser).
+   * @param {BufferSource | WebAssembly.Module} source
+   * @returns {Promise<Log>}
+   */
+  static async load(source) {
+    const instance =
+      source instanceof WebAssembly.Module
+        ? await WebAssembly.instantiate(source, IMPORTS)
+        : (await WebAssembly.instantiate(source, IMPORTS)).instance;
+    return new Log(instance);
+  }
+
+  /** @param {WebAssembly.Instance} instance */
+  constructor(instance) {
+    this.#e = instance.exports;
+    if (typeof this.#e.animader_abiVersion !== "function" || this.#e.animader_abiVersion() !== 1) {
+      throw new LogError("animader: unsupported or missing ABI version 1");
+    }
+    for (const name of [
+      "anm_log_inPtr",
+      "anm_log_inCap",
+      "anm_log_outPtr",
+      "anm_log_outLen",
+      "anm_log_diagCode",
+      "anm_log_parse",
+      "anm_log_encode",
+      "anm_log_window",
+      "anm_log_pointer",
+      "anm_log_pointerState",
+      "anm_log_recognise",
+      "memory",
+    ]) {
+      if (this.#e[name] === undefined) throw new LogError(`animader: missing export ${name}`);
+    }
+  }
+
+  /** The boundary ABI version (1). */
+  get abiVersion() {
+    return this.#e.animader_abiVersion();
+  }
+
+  #writeInput(bytes) {
+    const e = this.#e;
+    const cap = e.anm_log_inCap();
+    if (bytes.byteLength > cap) {
+      throw new LogError(
+        `animader: input is ${bytes.byteLength} bytes, over the ${cap}-byte input zone`,
+        { status: STATUS_BAD_CALL },
+      );
+    }
+    new Uint8Array(e.memory.buffer, e.anm_log_inPtr(), bytes.byteLength).set(bytes);
+  }
+
+  #output(len) {
+    return new Uint8Array(this.#e.memory.buffer, this.#e.anm_log_outPtr(), len).slice();
+  }
+
+  #check(status, what) {
+    if (status < 0) {
+      const message = status === STATUS_DIAGNOSTICS ? `${what}: the session has diagnostics` : `${what}: ${describeStatus(status)}`;
+      throw new LogError(`animader: ${message} (status ${status})`, { status });
+    }
+    return status;
+  }
+
+  /**
+   * Canonical session text in, 'ANEV' blob out. A clean parse caches the
+   * session the wasm module renders back in `encode`.
+   * @param {string} text
+   * @returns {Uint8Array}
+   */
+  parse(text) {
+    const bytes = encoder.encode(text);
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_parse(bytes.byteLength);
+    if (status === STATUS_DIAGNOSTICS) {
+      const raw = this.#e.anm_log_diagCode();
+      const code = raw === NO_CODE ? null : raw;
+      throw new LogError(
+        `animader: the session has diagnostics${code === null ? "" : ` (event-log code ${code})`}`,
+        { status, code },
+      );
+    }
+    this.#check(status, "parse");
+    return this.#output(status);
+  }
+
+  /**
+   * 'ANEV' blob in, the canonical text out, byte for byte, rendering the
+   * session cached by the last clean `parse`.
+   * @param {Uint8Array} blob
+   * @returns {string}
+   */
+  encode(blob) {
+    const bytes = toBytes(blob);
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_encode(bytes.byteLength);
+    this.#check(status, "encode");
+    return decoder.decode(this.#output(status));
+  }
+
+  /**
+   * 'ANEV' blob plus the half-open window [t0, t1) in, the window's blob
+   * out. The full original string table rides along.
+   * @param {Uint8Array} blob
+   * @param {number} t0
+   * @param {number} t1
+   * @returns {Uint8Array}
+   */
+  window(blob, t0, t1) {
+    const bytes = toBytes(blob);
+    const from = micros(t0, "t0");
+    const to = micros(t1, "t1");
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_window(bytes.byteLength, BigInt(from), BigInt(to));
+    this.#check(status, "window");
+    return this.#output(status);
+  }
+
+  /**
+   * 'ANEV' blob plus t / t_prev / a pointer id in, the twelve pngine
+   * lanes out (x, y, clickX, clickY, dx, dy, buttons, pressure,
+   * modifiers, scrollX, scrollY, pad).
+   * @param {Uint8Array} blob
+   * @param {number} t
+   * @param {number} tPrev
+   * @param {number} [ptr]
+   * @returns {Float32Array}
+   */
+  pointer(blob, t, tPrev, ptr = 0) {
+    const bytes = toBytes(blob);
+    const now = micros(t, "t");
+    const prev = micros(tPrev, "t_prev");
+    if (!Number.isInteger(ptr) || ptr < 0 || ptr > 255) {
+      throw new LogError(`animader: pointer id must be an integer 0..255, got ${ptr}`, {
+        status: STATUS_BAD_CALL,
+      });
+    }
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_pointer(bytes.byteLength, BigInt(now), BigInt(prev), ptr);
+    if (status !== 48) {
+      this.#check(status, "pointer");
+      throw new LogError(`animader: pointer answered ${status} bytes, expected 48`, {
+        status,
+      });
+    }
+    const out = this.#output(status);
+    return new Float32Array(out.buffer, out.byteOffset, 12);
+  }
+
+  /**
+   * 'ANEV' blob plus t / t_prev / a pointer id in, the pointer's folded
+   * state out: the `EventLog.PointerState` fields in declaration order,
+   * decoded from the boundary's 64-byte wire. `downAt` is null before the
+   * pointer's first down; `dx`/`dy` and the wheel and scroll sums are
+   * against `tPrev`. A pointer with no records in a blob that has records
+   * is the fresh state (present false, every lane zero), not an error.
+   * @param {Uint8Array} blob
+   * @param {number} t
+   * @param {number} tPrev
+   * @param {number} [ptr]
+   * @returns {{
+   *   ptr: number, present: boolean, down: boolean, x: number, y: number,
+   *   buttons: number, pressure: number, mods: number,
+   *   downAt: number | null, downX: number, downY: number,
+   *   clickTouched: boolean, dx: number, dy: number,
+   *   wheelX: number, wheelY: number, scrollX: number, scrollY: number,
+   * }}
+   */
+  pointerState(blob, t, tPrev, ptr = 0) {
+    const bytes = toBytes(blob);
+    const now = micros(t, "t");
+    const prev = micros(tPrev, "t_prev");
+    if (!Number.isInteger(ptr) || ptr < 0 || ptr > 255) {
+      throw new LogError(`animader: pointer id must be an integer 0..255, got ${ptr}`, {
+        status: STATUS_BAD_CALL,
+      });
+    }
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_pointerState(bytes.byteLength, BigInt(now), BigInt(prev), ptr);
+    this.#check(status, "pointerState");
+    if (status !== POINTER_STATE_LEN) {
+      throw new LogError(
+        `animader: pointerState answered ${status} bytes, expected ${POINTER_STATE_LEN}`,
+        { status },
+      );
+    }
+    const out = this.#output(status);
+    // The offsets of the wire, pinned in src/wasm_entry.zig's header:
+    // 0 ptr, 1 present, 2 down, 4 x, 6 y, 8 buttons, 10 pressure,
+    // 12 mods, 13 down-at present, 16 down-at, 24 down-x, 26 down-y,
+    // 28 click-touched, 32 dx, 36 dy, 40 wheel-x, 48 wheel-y,
+    // 56 scroll-x, 60 scroll-y; 64 bytes total.
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    return {
+      ptr: view.getUint8(0),
+      present: view.getUint8(1) !== 0,
+      down: view.getUint8(2) !== 0,
+      x: view.getUint16(4, true),
+      y: view.getUint16(6, true),
+      buttons: view.getUint8(8),
+      pressure: view.getUint16(10, true),
+      mods: view.getUint8(12),
+      downAt: view.getUint8(13) === 0 ? null : Number(view.getBigInt64(16, true)),
+      downX: view.getUint16(24, true),
+      downY: view.getUint16(26, true),
+      clickTouched: view.getUint8(28) !== 0,
+      dx: view.getInt32(32, true),
+      dy: view.getInt32(36, true),
+      wheelX: Number(view.getBigInt64(40, true)),
+      wheelY: Number(view.getBigInt64(48, true)),
+      scrollX: view.getInt32(56, true),
+      scrollY: view.getInt32(60, true),
+    };
+  }
+
+  /**
+   * 'ANEV' blob plus a pointer id in, the gestures the recognisers fold
+   * out of its records as an 'ANEV' blob out (derived records, never
+   * canonical text; `encode` refuses them). The output keeps the input's
+   * full string table, so a key press's `:code` index stays valid. A
+   * malformed blob, a blob with no records, or a pointer id above 255 is
+   * a bad call (status -2), never data.
+   * @param {Uint8Array} blob
+   * @param {number} [ptr]
+   * @returns {Uint8Array}
+   */
+  recognise(blob, ptr = 0) {
+    const bytes = toBytes(blob);
+    if (!Number.isInteger(ptr) || ptr < 0 || ptr > 255) {
+      throw new LogError(`animader: pointer id must be an integer 0..255, got ${ptr}`, {
+        status: STATUS_BAD_CALL,
+      });
+    }
+    this.#writeInput(bytes);
+    const status = this.#e.anm_log_recognise(bytes.byteLength, ptr);
+    this.#check(status, "recognise");
+    return this.#output(status);
+  }
+
+  /**
+   * Decode an 'ANEV' blob in JS. The record shape is the wire's:
+   * `{ at, kind, ptr, buttons, mods, x, y, p, str, v }`, with `kind` the
+   * string name, `str` the decoded string or null, and `v` three lanes.
+   * @param {Uint8Array} blob
+   * @returns {{ records: Array<object>, strings: string[] }}
+   */
+  decode(blob) {
+    const bytes = toBytes(blob);
+    if (bytes.byteLength < HEADER_LEN) {
+      throw new LogError(`animader: 'ANEV' blob is ${bytes.byteLength} bytes, under the 20-byte header`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== MAGIC) throw new LogError("animader: 'ANEV' magic is missing");
+    if (view.getUint32(4, true) !== VERSION) {
+      throw new LogError(`animader: 'ANEV' version ${view.getUint32(4, true)} is not ${VERSION}`);
+    }
+    const count = view.getUint32(8, true);
+    const strtabLen = view.getUint32(12, true);
+    if (count > MAX_EVENTS) throw new LogError(`animader: 'ANEV' count ${count} over the ceiling`);
+    if (strtabLen > MAX_STRTAB) throw new LogError(`animader: 'ANEV' strtab ${strtabLen} over the ceiling`);
+    if (HEADER_LEN + count * RECORD_LEN + strtabLen !== bytes.byteLength) {
+      throw new LogError("animader: 'ANEV' length does not match its header");
+    }
+
+    const strings = decodeStrings(
+      bytes.subarray(HEADER_LEN + count * RECORD_LEN, bytes.byteLength),
+    );
+    const records = [];
+    for (let i = 0; i < count; i++) {
+      const o = HEADER_LEN + i * RECORD_LEN;
+      const kind = KINDS[view.getUint8(o + 8)];
+      if (kind === undefined) throw new LogError(`animader: 'ANEV' record kind ${view.getUint8(o + 8)} is not a Kind`);
+      const at = view.getBigInt64(o, true);
+      if (at < 0n || at > BigInt(MAX_SAFE)) {
+        throw new LogError(`animader: 'ANEV' record :at ${at} is outside the writer's 0..2^53-1 domain`);
+      }
+      const strRaw = view.getUint16(o + 18, true);
+      if (strRaw !== NO_CODE && strRaw >= strings.length) {
+        throw new LogError(`animader: 'ANEV' record string index ${strRaw} has no table entry`);
+      }
+      records.push({
+        at: Number(at),
+        kind,
+        ptr: view.getUint8(o + 9),
+        buttons: view.getUint8(o + 10),
+        mods: view.getUint8(o + 11),
+        x: view.getUint16(o + 12, true),
+        y: view.getUint16(o + 14, true),
+        p: view.getUint16(o + 16, true),
+        str: strRaw === NO_CODE ? null : strings[strRaw],
+        v: [view.getInt32(o + 20, true), view.getInt32(o + 24, true), view.getInt32(o + 28, true)],
+      });
+    }
+    return { records, strings };
+  }
+}
+
+// The machine tier (plan 02, phase 6): `Machine` over the machine exports,
+// its decoders and its error type.
+export {
+  Machine,
+  MachineError,
+  MACHINE_CODES,
+  decodeSnapshot,
+  decodeMeta,
+  decodeOutputs,
+  decodeDiags,
+  decodeEmits,
+} from "./machine.js";
+
+// The composed session tier (plan 03, phase 4): `Session` over one
+// instance's machine and bridge exports, with the score and the consumer
+// seams.
+export { Session, SessionError, encodeTargets } from "./session.js";