animader 0.0.0-stage → 0.1.1

package/src/log.js

@@ -0,0 +1,304 @@
+// animader/log - the session writer and the replay walk (plan 01,
+// phase 5a).
+//
+// The writer's job is to produce what a DOM produces: pointer, wheel, key
+// and resize events become the core records a recording contains, with
+// the lanes taken from pngine's `attachPointerTracking`
+// (npm/pngine/src/init-core.js:98-150):
+//
+//   - position is the canvas-normalised coordinate, clamped to 0..1 and
+//     quantised to u16 by round(v * 65535); 0 is the left/top edge, 65535
+//     the right/bottom.
+//   - buttons are the DOM `MouseEvent.buttons` bitmask, modifiers the
+//     four pngine bits (1 shift, 2 ctrl, 4 alt, 8 meta). pngine's
+//     `init-core.js` also carries a Space bit at 16; it is outside the
+//     log's `:mods` domain (the four bits above), so the writer drops it
+//     and `mini.js:271` already omits it.
+//   - pressure is pngine's rule: `e.pressure || 0.5` on a down, and
+//     `e.pressure || (e.buttons ? 0.5 : 0)` on a move, quantised to u16.
+//   - the wheel's `:dx`/`:dy` are 24.8 device-pixel deltas:
+//     round(e.delta * 256 * the deltaMode factor), clamped to i32.
+//     `WheelEvent.deltaMode` 0 is device pixels; 1 is lines at the
+//     writer's `WHEEL_LINE_PX` (16) and 2 is pages at `WHEEL_PAGE_PX`
+//     (800), because the DOM carries counts, not pixels, in those modes
+//     and no browser-independent pixel value exists. The folds read only
+//     the sign of these lanes (src/EventLog.zig), so the conversion is
+//     about the recorded text's unit, not a fold input.
+//   - a release follows the phase 3 rule: buttons and pressure zero, the
+//     position and modifiers held from before it.
+//
+// The writer never emits a verb and no line formats a float: every line
+// is a template string over the integers just stamped. A `pointermove`
+// while no button is down is not recorded: the log's sequence rule has no
+// move-while-up, and the player's hover deltas have no record (the one
+// place the recorded stream cannot be the live struct; the folds read the
+// stream).
+//
+// `:at` is `Math.round(clock())`, required to be a safe integer in
+// 0..2^53-1 (the schema's `at-usec` domain); a clock outside it throws
+// rather than writing a line the parser must refuse.
+
+const SJON_ESCAPES = {
+  "\0": "\\0",
+  '"': '\\"',
+  "\\": "\\\\",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+/** The SJON string escape set (SJON/src/StringEscape.zig) for one value. */
+const quote = (value) =>
+  '"' + String(value).replace(/[\0"\\\n\r\t]/g, (c) => SJON_ESCAPES[c]) + '"';
+
+const clamp01 = (v) => {
+  if (!Number.isFinite(v)) return 0;
+  if (v < 0) return 0;
+  if (v > 1) return 1;
+  return v;
+};
+
+const q16 = (v) => Math.round(clamp01(v) * 65535);
+
+const clampI32 = (v) => {
+  if (!Number.isFinite(v)) return 0;
+  if (v < -2147483648) return -2147483648;
+  if (v > 2147483647) return 2147483647;
+  return Math.round(v);
+};
+
+/**
+ * The writer's line and page wheel factors, in device pixels. The DOM's
+ * `WheelEvent.deltaMode` 1 and 2 carry counts, not pixels, and no
+ * browser-independent pixel value exists, so the writer pins these: 16
+ * is a default CSS line box, 800 a nominal page. The values are pinned
+ * by the three-mode red in test/log.test.js.
+ */
+const WHEEL_LINE_PX = 16;
+const WHEEL_PAGE_PX = 800;
+
+/** `WheelEvent.deltaMode` -> the device-pixel factor of its counts. */
+const wheelFactor = (mode) => (mode === 1 ? WHEEL_LINE_PX : mode === 2 ? WHEEL_PAGE_PX : 1);
+
+const modsOf = (e) =>
+  (e.shiftKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.altKey ? 4 : 0) | (e.metaKey ? 8 : 0);
+
+const ptrOf = (e) => (Number.isInteger(e.pointerId) ? e.pointerId : 0) & 0xff;
+
+const requireDim = (value, what) => {
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new RangeError(`attachLog: ${what} must be an integer 1..65535, got ${value}`);
+  }
+  return value;
+};
+
+const EMPTY_V = () => [0, 0, 0];
+
+/**
+ * Record pointer, wheel, key and resize events on a canvas-like
+ * EventTarget.
+ *
+ * @param {object} canvas an EventTarget with `width`/`height` and
+ *   `getBoundingClientRect()` (the canvas element, or a test double).
+ * @param {() => number} clock session microseconds; `:at` is
+ *   `Math.round(clock())`, required inside 0..2^53-1.
+ * @returns {{ drain: () => object[], text: () => string, detach: () => void }}
+ *   `drain()` hands the records appended since the last call, `text()`
+ *   the canonical session text so far (deterministic: the same handle
+ *   answers the same string), `detach()` removes every listener through
+ *   one AbortController.
+ */
+export function attachLog(canvas, clock) {
+  const sessionW = requireDim(canvas.width, "canvas.width");
+  const sessionH = requireDim(canvas.height, "canvas.height");
+  const sessionLine = `(session :version 1 :canvas [${sessionW} ${sessionH}])`;
+
+  const ac = new AbortController();
+  const signal = ac.signal;
+  const records = [];
+  const lines = [];
+  let drained = 0;
+  /** Pointer ids currently down: the log's `down (move)* (up|cancel)`. */
+  const down = new Set();
+  /** The held u16 position and modifier bits a release carries. */
+  let lastX = 0;
+  let lastY = 0;
+  let lastMods = 0;
+
+  const stamp = () => {
+    const raw = clock();
+    const t = Math.round(raw);
+    if (!Number.isSafeInteger(t) || t < 0) {
+      throw new RangeError(`attachLog: clock() must answer microseconds in 0..2^53-1, got ${raw}`);
+    }
+    return t;
+  };
+
+  const emit = (record, line) => {
+    records.push(record);
+    lines.push(line);
+  };
+
+  const unitOf = (e) => {
+    const rect = canvas.getBoundingClientRect();
+    const nx = rect.width > 0 ? (e.clientX - rect.left) / rect.width : 0;
+    const ny = rect.height > 0 ? (e.clientY - rect.top) / rect.height : 0;
+    return { x: q16(nx), y: q16(ny), mods: modsOf(e) };
+  };
+
+  canvas.addEventListener(
+    "pointerdown",
+    (e) => {
+      const at = stamp();
+      const id = ptrOf(e);
+      const { x, y, mods } = unitOf(e);
+      const buttons = (e.buttons ?? 0) & 0xff;
+      const p = q16(e.pressure || 0.5);
+      lastX = x;
+      lastY = y;
+      lastMods = mods;
+      down.add(id);
+      emit(
+        { at, kind: "down", ptr: id, buttons, mods, x, y, p, str: null, v: EMPTY_V() },
+        `(down :at ${at} :ptr ${id} :x ${x} :y ${y} :b ${buttons} :p ${p} :mods ${mods})`,
+      );
+    },
+    { signal },
+  );
+
+  canvas.addEventListener(
+    "pointermove",
+    (e) => {
+      const id = ptrOf(e);
+      if (!down.has(id)) return;
+      const at = stamp();
+      const { x, y, mods } = unitOf(e);
+      const buttons = (e.buttons ?? 0) & 0xff;
+      const p = q16(e.pressure || (e.buttons ? 0.5 : 0));
+      lastX = x;
+      lastY = y;
+      lastMods = mods;
+      emit(
+        { at, kind: "move", ptr: id, buttons, mods, x, y, p, str: null, v: EMPTY_V() },
+        `(move :at ${at} :ptr ${id} :x ${x} :y ${y} :b ${buttons} :p ${p} :mods ${mods})`,
+      );
+    },
+    { passive: true, signal },
+  );
+
+  canvas.addEventListener(
+    "pointerup",
+    (e) => {
+      const id = ptrOf(e);
+      if (!down.has(id)) return;
+      down.delete(id);
+      const at = stamp();
+      emit(
+        { at, kind: "up", ptr: id, buttons: 0, mods: lastMods, x: lastX, y: lastY, p: 0, str: null, v: EMPTY_V() },
+        `(up :at ${at} :ptr ${id} :x ${lastX} :y ${lastY} :b 0 :p 0 :mods ${lastMods})`,
+      );
+    },
+    { signal },
+  );
+
+  canvas.addEventListener(
+    "pointercancel",
+    (e) => {
+      const id = ptrOf(e);
+      if (!down.has(id)) return;
+      down.delete(id);
+      const at = stamp();
+      emit(
+        { at, kind: "cancel", ptr: id, buttons: 0, mods: 0, x: 0, y: 0, p: 0, str: null, v: EMPTY_V() },
+        `(cancel :at ${at} :ptr ${id})`,
+      );
+    },
+    { signal },
+  );
+
+  canvas.addEventListener(
+    "wheel",
+    (e) => {
+      const at = stamp();
+      const id = ptrOf(e);
+      const factor = wheelFactor(e.deltaMode);
+      const dx = clampI32(e.deltaX * factor * 256);
+      const dy = clampI32(e.deltaY * factor * 256);
+      const mods = modsOf(e);
+      lastMods = mods;
+      emit(
+        { at, kind: "wheel", ptr: id, buttons: 0, mods, x: lastX, y: lastY, p: 0, str: null, v: [dx, dy, 0] },
+        `(wheel :at ${at} :ptr ${id} :x ${lastX} :y ${lastY} :dx ${dx} :dy ${dy} :mods ${mods})`,
+      );
+    },
+    { passive: false, signal },
+  );
+
+  const key = (isDown) => (e) => {
+    const at = stamp();
+    const code = e.code ?? "";
+    const mods = modsOf(e);
+    const buttons = isDown ? 1 : 0;
+    emit(
+      { at, kind: "key", ptr: 0, buttons, mods, x: 0, y: 0, p: 0, str: code, v: EMPTY_V() },
+      `(key :at ${at} :code ${quote(code)} :down ${buttons} :mods ${mods})`,
+    );
+  };
+  document.addEventListener("keydown", key(true), { signal });
+  document.addEventListener("keyup", key(false), { signal });
+
+  canvas.addEventListener(
+    "resize",
+    () => {
+      const at = stamp();
+      const w = requireDim(canvas.width, "canvas.width");
+      const h = requireDim(canvas.height, "canvas.height");
+      emit(
+        { at, kind: "resize", ptr: 0, buttons: 0, mods: 0, x: 0, y: 0, p: 0, str: null, v: [w, h, 0] },
+        `(resize :at ${at} :v [${w} ${h}])`,
+      );
+    },
+    { signal },
+  );
+
+  return {
+    drain() {
+      const out = records.slice(drained);
+      drained = records.length;
+      return out;
+    },
+    text() {
+      return [sessionLine, ...lines].join("\n") + "\n";
+    },
+    detach() {
+      ac.abort();
+    },
+  };
+}
+
+/**
+ * Parse a session text through the artifact and deliver records to `sink`
+ * as `clock()` passes their `:at`. The parse is the wasm one, so verbs
+ * expand to the records a recording would have contained.
+ *
+ * @param {import("./index.js").Log} log the loaded boundary artifact.
+ * @param {string} text the session document.
+ * @param {(record: object) => void} sink one call per record, in `:at`
+ *   order; a sink may block (the clock is what paces delivery).
+ * @param {() => number} clock session microseconds.
+ * @returns {Promise<void>}
+ */
+export async function replay(log, text, sink, clock) {
+  const { records } = log.decode(log.parse(text));
+  for (const record of records) {
+    for (;;) {
+      const now = Math.round(clock());
+      if (!Number.isSafeInteger(now)) {
+        throw new RangeError(`replay: clock() must answer a safe integer, got ${now}`);
+      }
+      if (now >= record.at) break;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    sink(record);
+  }
+}