@mentra/engine 0.1.0-beta.0

package/build/utils/display/scene/degrade.js

@@ -0,0 +1,64 @@
+/**
+ * Degrade — compile a scene for devices that can't position elements
+ * (`canPosition: false`: G1, Z100). Output is a LEGACY layout that rides the
+ * existing display path — DisplayProcessor wraps it there, exactly as today,
+ * which is what keeps sugar byte-identical on old hardware (spec §2/§5:
+ * degrade output must be UNWRAPPED; wrapping twice breaks the goldens).
+ *
+ * Rules (design doc §3.4.8): content-preserving, never-erroring,
+ * honestly-reported. Text collapses in reading order (y, then x) joined by
+ * blank lines; EXACTLY two text elements sharing a y-range with disjoint
+ * x-ranges become a double_text_wall (ColumnComposer path downstream); rects
+ * drop silently (decoration); images drop + report.
+ */
+function yOverlap(a, b) {
+    return a.box.y < b.box.y + b.box.h && b.box.y < a.box.y + a.box.h;
+}
+function xDisjoint(a, b) {
+    return a.box.x + a.box.w <= b.box.x || b.box.x + b.box.w <= a.box.x;
+}
+export function degradeScene(input) {
+    const dropped = [];
+    let degraded = false;
+    const texts = [];
+    input.forEach((el, index) => {
+        if (!el || typeof el !== "object" || !el.box) {
+            // Malformed element — report it like the positioning pipeline does
+            // instead of silently pretending the render was clean.
+            dropped.push(el?.id ?? `element[${index}]`);
+            degraded = true;
+            return;
+        }
+        if (el.type === "text") {
+            texts.push(el);
+        }
+        else if (el.type === "image") {
+            dropped.push(el.id ?? `image[${index}]`);
+            degraded = true;
+        }
+        // rects: silent drop — pure decoration on a text wall.
+    });
+    if (texts.length === 0) {
+        return { layout: null, degraded, dropped };
+    }
+    // Row exception: exactly 2 columns with clean separation — the shipped
+    // double_text_wall mechanism (scope guard: nothing fancier; this is NOT a
+    // layout engine).
+    if (texts.length === 2 && yOverlap(texts[0], texts[1]) && xDisjoint(texts[0], texts[1])) {
+        const [left, right] = texts[0].box.x <= texts[1].box.x ? [texts[0], texts[1]] : [texts[1], texts[0]];
+        return {
+            layout: { layoutType: "double_text_wall", topText: left.text ?? "", bottomText: right.text ?? "" },
+            degraded,
+            dropped,
+        };
+    }
+    // Reading order: y, then x; join with blank lines. Downstream wrap clips
+    // overflow per the device profile.
+    const ordered = [...texts].sort((a, b) => a.box.y - b.box.y || a.box.x - b.box.x);
+    const text = ordered
+        .map((t) => t.text ?? "")
+        .filter((t) => t.length > 0)
+        .join("\n\n");
+    return { layout: { layoutType: "text_wall", text }, degraded, dropped };
+}
+//# sourceMappingURL=degrade.js.map

package/build/utils/display/scene/degrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degrade.js","sourceRoot":"","sources":["../../../../src/utils/display/scene/degrade.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Degrade — compile a scene for devices that can't position elements\n * (`canPosition: false`: G1, Z100). Output is a LEGACY layout that rides the\n * existing display path — DisplayProcessor wraps it there, exactly as today,\n * which is what keeps sugar byte-identical on old hardware (spec §2/§5:\n * degrade output must be UNWRAPPED; wrapping twice breaks the goldens).\n *\n * Rules (design doc §3.4.8): content-preserving, never-erroring,\n * honestly-reported. Text collapses in reading order (y, then x) joined by\n * blank lines; EXACTLY two text elements sharing a y-range with disjoint\n * x-ranges become a double_text_wall (ColumnComposer path downstream); rects\n * drop silently (decoration); images drop + report.\n */\n\nimport type {SceneElementInput} from \"./types\"\n\nexport interface DegradedScene {\n  /** Legacy layout for the existing display path, or null for an empty scene (caller clears). */\n  layout: {layoutType: string; [key: string]: unknown} | null\n  degraded: boolean\n  dropped: string[]\n}\n\ntype TextEl = Extract<SceneElementInput, {type: \"text\"}>\n\nfunction yOverlap(a: TextEl, b: TextEl): boolean {\n  return a.box.y < b.box.y + b.box.h && b.box.y < a.box.y + a.box.h\n}\n\nfunction xDisjoint(a: TextEl, b: TextEl): boolean {\n  return a.box.x + a.box.w <= b.box.x || b.box.x + b.box.w <= a.box.x\n}\n\nexport function degradeScene(input: readonly SceneElementInput[]): DegradedScene {\n  const dropped: string[] = []\n  let degraded = false\n\n  const texts: TextEl[] = []\n  input.forEach((el, index) => {\n    if (!el || typeof el !== \"object\" || !el.box) {\n      // Malformed element — report it like the positioning pipeline does\n      // instead of silently pretending the render was clean.\n      dropped.push((el as {id?: string} | null)?.id ?? `element[${index}]`)\n      degraded = true\n      return\n    }\n    if (el.type === \"text\") {\n      texts.push(el)\n    } else if (el.type === \"image\") {\n      dropped.push(el.id ?? `image[${index}]`)\n      degraded = true\n    }\n    // rects: silent drop — pure decoration on a text wall.\n  })\n\n  if (texts.length === 0) {\n    return {layout: null, degraded, dropped}\n  }\n\n  // Row exception: exactly 2 columns with clean separation — the shipped\n  // double_text_wall mechanism (scope guard: nothing fancier; this is NOT a\n  // layout engine).\n  if (texts.length === 2 && yOverlap(texts[0], texts[1]) && xDisjoint(texts[0], texts[1])) {\n    const [left, right] = texts[0].box.x <= texts[1].box.x ? [texts[0], texts[1]] : [texts[1], texts[0]]\n    return {\n      layout: {layoutType: \"double_text_wall\", topText: left.text ?? \"\", bottomText: right.text ?? \"\"},\n      degraded,\n      dropped,\n    }\n  }\n\n  // Reading order: y, then x; join with blank lines. Downstream wrap clips\n  // overflow per the device profile.\n  const ordered = [...texts].sort((a, b) => a.box.y - b.box.y || a.box.x - b.box.x)\n  const text = ordered\n    .map((t) => t.text ?? \"\")\n    .filter((t) => t.length > 0)\n    .join(\"\\n\\n\")\n  return {layout: {layoutType: \"text_wall\", text}, degraded, dropped}\n}\n"]}

package/build/utils/display/scene/differ.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Scene differ — matches elements between the last frame sent to the device and
+ * the next scene, and classifies each element's change. Pure set arithmetic:
+ * nothing in here is device-specific (spec §1).
+ *
+ * Matching rules (design doc §3.4.1, in order):
+ *   1. same explicit `id` + same `type`  ⇒ same element
+ *   2. no id: same `type` + identical box ⇒ same element
+ *   3. no id: same `type`, by order among the still-unmatched
+ *   4. anything unmatched in prev ⇒ removed; unmatched in next ⇒ created
+ *
+ * Matched no-id elements INHERIT the previous element's assigned id so the
+ * device-side id⇒firmware-component mapping stays stable; fresh elements get a
+ * synthesized id from the caller (SceneStore counter). Synthesized ids are
+ * prefixed "~" so they can never collide with app-supplied ids.
+ */
+import type { FrameElement, SceneBox, SceneElementType } from "./types";
+/** A processed (clamped/wrapped) element, pre-diff: id optional, no annotation yet. */
+export interface DiffableElement {
+    id?: string;
+    type: SceneElementType;
+    box: SceneBox;
+    text?: string;
+    data?: string;
+    style?: FrameElement["style"];
+    contentHash: string;
+}
+export interface DiffResult {
+    elements: FrameElement[];
+    removed: string[];
+}
+/**
+ * Diff `next` against `prev` (the last frame sent for this app/view/device;
+ * empty array for a fresh scene). `nextSyntheticId` mints ids for elements the
+ * app didn't name — must be stable per (app, view) across calls (SceneStore).
+ */
+export declare function diffScene(prev: readonly FrameElement[], next: readonly DiffableElement[], nextSyntheticId: () => string): DiffResult;
+//# sourceMappingURL=differ.d.ts.map

package/build/utils/display/scene/differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../../../src/utils/display/scene/differ.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAE,QAAQ,EAAe,gBAAgB,EAAC,MAAM,SAAS,CAAA;AAGlF,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,gBAAgB,CAAA;IACtB,GAAG,EAAE,QAAQ,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAyBD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,IAAI,EAAE,SAAS,eAAe,EAAE,EAChC,eAAe,EAAE,MAAM,MAAM,GAC5B,UAAU,CA2DZ"}

package/build/utils/display/scene/differ.js

@@ -0,0 +1,107 @@
+/**
+ * Scene differ — matches elements between the last frame sent to the device and
+ * the next scene, and classifies each element's change. Pure set arithmetic:
+ * nothing in here is device-specific (spec §1).
+ *
+ * Matching rules (design doc §3.4.1, in order):
+ *   1. same explicit `id` + same `type`  ⇒ same element
+ *   2. no id: same `type` + identical box ⇒ same element
+ *   3. no id: same `type`, by order among the still-unmatched
+ *   4. anything unmatched in prev ⇒ removed; unmatched in next ⇒ created
+ *
+ * Matched no-id elements INHERIT the previous element's assigned id so the
+ * device-side id⇒firmware-component mapping stays stable; fresh elements get a
+ * synthesized id from the caller (SceneStore counter). Synthesized ids are
+ * prefixed "~" so they can never collide with app-supplied ids.
+ */
+import { boxesEqual } from "./types";
+function classify(prev, next) {
+    if (!boxesEqual(prev.box, next.box))
+        return "moved";
+    if (prev.contentHash !== next.contentHash)
+        return "updated";
+    return "unchanged";
+}
+/**
+ * Assemble the annotated FrameElement, OMITTING optional fields that are
+ * undefined. A present key with an `undefined` value cannot cross the Expo
+ * Android bridge — its `Map<String, Any>` converter rejects it ("Value is
+ * undefined, expected an Object"), which surfaces as ERR_UNEXPECTED from
+ * displayEvent. (iOS's `[String: Any]` bridge silently drops nils, so the
+ * defect was invisible there.) Keeping the keys absent — not undefined —
+ * matches the optional-field contract in types.ts.
+ */
+function buildFrameElement(el, id, change) {
+    const out = { id, type: el.type, box: el.box, contentHash: el.contentHash, change };
+    if (el.text !== undefined)
+        out.text = el.text;
+    if (el.data !== undefined)
+        out.data = el.data;
+    if (el.style !== undefined)
+        out.style = el.style;
+    return out;
+}
+/**
+ * Diff `next` against `prev` (the last frame sent for this app/view/device;
+ * empty array for a fresh scene). `nextSyntheticId` mints ids for elements the
+ * app didn't name — must be stable per (app, view) across calls (SceneStore).
+ */
+export function diffScene(prev, next, nextSyntheticId) {
+    const prevUnmatched = new Set(prev.map((_, i) => i));
+    const prevByExplicitId = new Map();
+    prev.forEach((el, i) => {
+        if (!el.id.startsWith("~"))
+            prevByExplicitId.set(`${el.type}:${el.id}`, i);
+    });
+    // matches[nextIndex] = prevIndex | undefined
+    const matches = new Array(next.length).fill(undefined);
+    // Pass 1: explicit id + type.
+    next.forEach((el, i) => {
+        if (!el.id)
+            return;
+        const j = prevByExplicitId.get(`${el.type}:${el.id}`);
+        if (j !== undefined && prevUnmatched.has(j)) {
+            matches[i] = j;
+            prevUnmatched.delete(j);
+        }
+    });
+    // Pass 2: no-id elements match a no-id prev element of the same type with an
+    // identical box.
+    next.forEach((el, i) => {
+        if (el.id || matches[i] !== undefined)
+            return;
+        for (const j of prevUnmatched) {
+            const p = prev[j];
+            if (p.id.startsWith("~") && p.type === el.type && boxesEqual(p.box, el.box)) {
+                matches[i] = j;
+                prevUnmatched.delete(j);
+                break;
+            }
+        }
+    });
+    // Pass 3: remaining no-id elements match remaining no-id prev of the same
+    // type in order (k-th unmatched text ↔ k-th unmatched text).
+    next.forEach((el, i) => {
+        if (el.id || matches[i] !== undefined)
+            return;
+        for (const j of prevUnmatched) {
+            const p = prev[j];
+            if (p.id.startsWith("~") && p.type === el.type) {
+                matches[i] = j;
+                prevUnmatched.delete(j);
+                break;
+            }
+        }
+    });
+    const elements = next.map((el, i) => {
+        const j = matches[i];
+        if (j !== undefined) {
+            const p = prev[j];
+            return buildFrameElement(el, el.id ?? p.id, classify(p, el));
+        }
+        return buildFrameElement(el, el.id ?? nextSyntheticId(), "created");
+    });
+    const removed = [...prevUnmatched].map((j) => prev[j].id);
+    return { elements, removed };
+}
+//# sourceMappingURL=differ.js.map

package/build/utils/display/scene/differ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.js","sourceRoot":"","sources":["../../../../src/utils/display/scene/differ.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Scene differ — matches elements between the last frame sent to the device and\n * the next scene, and classifies each element's change. Pure set arithmetic:\n * nothing in here is device-specific (spec §1).\n *\n * Matching rules (design doc §3.4.1, in order):\n *   1. same explicit `id` + same `type`  ⇒ same element\n *   2. no id: same `type` + identical box ⇒ same element\n *   3. no id: same `type`, by order among the still-unmatched\n *   4. anything unmatched in prev ⇒ removed; unmatched in next ⇒ created\n *\n * Matched no-id elements INHERIT the previous element's assigned id so the\n * device-side id⇒firmware-component mapping stays stable; fresh elements get a\n * synthesized id from the caller (SceneStore counter). Synthesized ids are\n * prefixed \"~\" so they can never collide with app-supplied ids.\n */\n\nimport type {FrameElement, SceneBox, SceneChange, SceneElementType} from \"./types\"\nimport {boxesEqual} from \"./types\"\n\n/** A processed (clamped/wrapped) element, pre-diff: id optional, no annotation yet. */\nexport interface DiffableElement {\n  id?: string\n  type: SceneElementType\n  box: SceneBox\n  text?: string\n  data?: string\n  style?: FrameElement[\"style\"]\n  contentHash: string\n}\n\nexport interface DiffResult {\n  elements: FrameElement[]\n  removed: string[]\n}\n\nfunction classify(prev: FrameElement, next: DiffableElement): SceneChange {\n  if (!boxesEqual(prev.box, next.box)) return \"moved\"\n  if (prev.contentHash !== next.contentHash) return \"updated\"\n  return \"unchanged\"\n}\n\n/**\n * Assemble the annotated FrameElement, OMITTING optional fields that are\n * undefined. A present key with an `undefined` value cannot cross the Expo\n * Android bridge — its `Map<String, Any>` converter rejects it (\"Value is\n * undefined, expected an Object\"), which surfaces as ERR_UNEXPECTED from\n * displayEvent. (iOS's `[String: Any]` bridge silently drops nils, so the\n * defect was invisible there.) Keeping the keys absent — not undefined —\n * matches the optional-field contract in types.ts.\n */\nfunction buildFrameElement(el: DiffableElement, id: string, change: SceneChange): FrameElement {\n  const out: FrameElement = {id, type: el.type, box: el.box, contentHash: el.contentHash, change}\n  if (el.text !== undefined) out.text = el.text\n  if (el.data !== undefined) out.data = el.data\n  if (el.style !== undefined) out.style = el.style\n  return out\n}\n\n/**\n * Diff `next` against `prev` (the last frame sent for this app/view/device;\n * empty array for a fresh scene). `nextSyntheticId` mints ids for elements the\n * app didn't name — must be stable per (app, view) across calls (SceneStore).\n */\nexport function diffScene(\n  prev: readonly FrameElement[],\n  next: readonly DiffableElement[],\n  nextSyntheticId: () => string,\n): DiffResult {\n  const prevUnmatched = new Set(prev.map((_, i) => i))\n  const prevByExplicitId = new Map<string, number>()\n  prev.forEach((el, i) => {\n    if (!el.id.startsWith(\"~\")) prevByExplicitId.set(`${el.type}:${el.id}`, i)\n  })\n\n  // matches[nextIndex] = prevIndex | undefined\n  const matches: (number | undefined)[] = new Array(next.length).fill(undefined)\n\n  // Pass 1: explicit id + type.\n  next.forEach((el, i) => {\n    if (!el.id) return\n    const j = prevByExplicitId.get(`${el.type}:${el.id}`)\n    if (j !== undefined && prevUnmatched.has(j)) {\n      matches[i] = j\n      prevUnmatched.delete(j)\n    }\n  })\n\n  // Pass 2: no-id elements match a no-id prev element of the same type with an\n  // identical box.\n  next.forEach((el, i) => {\n    if (el.id || matches[i] !== undefined) return\n    for (const j of prevUnmatched) {\n      const p = prev[j]\n      if (p.id.startsWith(\"~\") && p.type === el.type && boxesEqual(p.box, el.box)) {\n        matches[i] = j\n        prevUnmatched.delete(j)\n        break\n      }\n    }\n  })\n\n  // Pass 3: remaining no-id elements match remaining no-id prev of the same\n  // type in order (k-th unmatched text ↔ k-th unmatched text).\n  next.forEach((el, i) => {\n    if (el.id || matches[i] !== undefined) return\n    for (const j of prevUnmatched) {\n      const p = prev[j]\n      if (p.id.startsWith(\"~\") && p.type === el.type) {\n        matches[i] = j\n        prevUnmatched.delete(j)\n        break\n      }\n    }\n  })\n\n  const elements: FrameElement[] = next.map((el, i) => {\n    const j = matches[i]\n    if (j !== undefined) {\n      const p = prev[j]\n      return buildFrameElement(el, el.id ?? p.id, classify(p, el))\n    }\n    return buildFrameElement(el, el.id ?? nextSyntheticId(), \"created\")\n  })\n\n  const removed = [...prevUnmatched].map((j) => prev[j].id)\n  return {elements, removed}\n}\n"]}

package/build/utils/display/scene/index.d.ts

@@ -0,0 +1,10 @@
+export type { FrameElement, SceneBox, SceneBreakMode, SceneChange, SceneDisplayCapabilities, SceneElementInput, SceneElementType, SceneFrame, SceneProcessResult, SceneRectStyle, SceneTextStyle, } from "./types";
+export { boxesEqual, contentHash, elementContentHash } from "./types";
+export type { DiffResult, DiffableElement } from "./differ";
+export { diffScene } from "./differ";
+export type { ProcessedScene } from "./process";
+export { processScene, profileLineHeightPx } from "./process";
+export type { DegradedScene } from "./degrade";
+export { degradeScene } from "./degrade";
+export { SceneStore } from "./store";
+//# sourceMappingURL=index.d.ts.map

package/build/utils/display/scene/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/display/scene/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,WAAW,EACX,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAA;AAChB,OAAO,EAAC,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAA;AACnE,YAAY,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,UAAU,CAAA;AACzD,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAA;AAClC,YAAY,EAAC,cAAc,EAAC,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAC,YAAY,EAAE,mBAAmB,EAAC,MAAM,WAAW,CAAA;AAC3D,YAAY,EAAC,aAAa,EAAC,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AACtC,OAAO,EAAC,UAAU,EAAC,MAAM,SAAS,CAAA"}

package/build/utils/display/scene/index.js

@@ -0,0 +1,6 @@
+export { boxesEqual, contentHash, elementContentHash } from "./types";
+export { diffScene } from "./differ";
+export { processScene, profileLineHeightPx } from "./process";
+export { degradeScene } from "./degrade";
+export { SceneStore } from "./store";
+//# sourceMappingURL=index.js.map

package/build/utils/display/scene/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/display/scene/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAA;AAEnE,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAA;AAElC,OAAO,EAAC,YAAY,EAAE,mBAAmB,EAAC,MAAM,WAAW,CAAA;AAE3D,OAAO,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AACtC,OAAO,EAAC,UAAU,EAAC,MAAM,SAAS,CAAA","sourcesContent":["export type {\n  FrameElement,\n  SceneBox,\n  SceneBreakMode,\n  SceneChange,\n  SceneDisplayCapabilities,\n  SceneElementInput,\n  SceneElementType,\n  SceneFrame,\n  SceneProcessResult,\n  SceneRectStyle,\n  SceneTextStyle,\n} from \"./types\"\nexport {boxesEqual, contentHash, elementContentHash} from \"./types\"\nexport type {DiffResult, DiffableElement} from \"./differ\"\nexport {diffScene} from \"./differ\"\nexport type {ProcessedScene} from \"./process\"\nexport {processScene, profileLineHeightPx} from \"./process\"\nexport type {DegradedScene} from \"./degrade\"\nexport {degradeScene} from \"./degrade\"\nexport {SceneStore} from \"./store\"\n"]}

package/build/utils/display/scene/process.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Scene processing — validate → clamp → budget → wrap. Everything here is
+ * generic; device variation enters only through the capabilities block and the
+ * display profile (data, not code). Spec §5.
+ *
+ * Never rejects a frame: offending elements are dropped per-element and
+ * reported via `dropped` / `degraded` (design doc §3.4.6; spec §4 refines the
+ * design doc's image "reject" to per-element drop).
+ */
+import type { DisplayProfile } from "../profiles/types";
+import type { DiffableElement } from "./differ";
+import type { SceneDisplayCapabilities, SceneElementInput } from "./types";
+export interface ProcessedScene {
+    elements: DiffableElement[];
+    degraded: boolean;
+    dropped: string[];
+}
+/**
+ * Line height for box-height→line-count math — ONLY when the profile declares
+ * a calibrated `lineHeightPx`. Deriving one from full-canvas numbers proved
+ * wrong on hardware (288/8=36px clipped the G2 nav instruction to one line;
+ * the real container line height is smaller). Without calibration we return
+ * null and the wrap step skips host-side height clipping entirely — text wraps
+ * to the box WIDTH and the firmware clips vertically in-box, which is exactly
+ * the legacy behavior.
+ */
+export declare function profileLineHeightPx(profile: DisplayProfile, _canvasHeight: number): number | null;
+/**
+ * Process a raw scene against a device's capabilities + profile. Output is
+ * diff-ready (text pre-wrapped, boxes clamped, content hashed) and reflects
+ * exactly what will be sent — the diff baseline is post-processed by design
+ * (spec §4).
+ */
+export declare function processScene(input: readonly SceneElementInput[], caps: SceneDisplayCapabilities, profile: DisplayProfile): ProcessedScene;
+//# sourceMappingURL=process.d.ts.map

package/build/utils/display/scene/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../../src/utils/display/scene/process.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,UAAU,CAAA;AAC7C,OAAO,KAAK,EAAW,wBAAwB,EAAE,iBAAiB,EAAiB,MAAM,SAAS,CAAA;AAGlG,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjG;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,cAAc,GACtB,cAAc,CAgJhB"}

package/build/utils/display/scene/process.js

@@ -0,0 +1,187 @@
+/**
+ * Scene processing — validate → clamp → budget → wrap. Everything here is
+ * generic; device variation enters only through the capabilities block and the
+ * display profile (data, not code). Spec §5.
+ *
+ * Never rejects a frame: offending elements are dropped per-element and
+ * reported via `dropped` / `degraded` (design doc §3.4.6; spec §4 refines the
+ * design doc's image "reject" to per-element drop).
+ */
+import { TextMeasurer } from "../measurer/TextMeasurer";
+import { TextWrapper } from "../wrapper/TextWrapper";
+import { elementContentHash } from "./types";
+/** Reporting id for an element the app may not have named. */
+function reportId(el, index) {
+    return el.id ?? `${el.type}[${index}]`;
+}
+function clampBox(box, width, height) {
+    const x1 = Math.max(0, Math.floor(box.x));
+    const y1 = Math.max(0, Math.floor(box.y));
+    const x2 = Math.min(width, Math.floor(box.x) + Math.max(0, Math.floor(box.w)));
+    const y2 = Math.min(height, Math.floor(box.y) + Math.max(0, Math.floor(box.h)));
+    if (x2 <= x1 || y2 <= y1)
+        return null;
+    return { x: x1, y: y1, w: x2 - x1, h: y2 - y1 };
+}
+function boxShrunk(orig, clamped) {
+    return (clamped.x !== Math.floor(orig.x) ||
+        clamped.y !== Math.floor(orig.y) ||
+        clamped.w !== Math.floor(orig.w) ||
+        clamped.h !== Math.floor(orig.h));
+}
+/**
+ * Line height for box-height→line-count math — ONLY when the profile declares
+ * a calibrated `lineHeightPx`. Deriving one from full-canvas numbers proved
+ * wrong on hardware (288/8=36px clipped the G2 nav instruction to one line;
+ * the real container line height is smaller). Without calibration we return
+ * null and the wrap step skips host-side height clipping entirely — text wraps
+ * to the box WIDTH and the firmware clips vertically in-box, which is exactly
+ * the legacy behavior.
+ */
+export function profileLineHeightPx(profile, _canvasHeight) {
+    return profile.lineHeightPx ?? null;
+}
+/**
+ * Process a raw scene against a device's capabilities + profile. Output is
+ * diff-ready (text pre-wrapped, boxes clamped, content hashed) and reflects
+ * exactly what will be sent — the diff baseline is post-processed by design
+ * (spec §4).
+ */
+export function processScene(input, caps, profile) {
+    const dropped = [];
+    let degraded = false;
+    const measurer = new TextMeasurer(profile);
+    const wrapper = new TextWrapper(measurer);
+    const lineHeight = profileLineHeightPx(profile, caps.height);
+    // Validate + dedupe explicit ids (first occurrence wins; dupes are dev error).
+    const seenIds = new Set();
+    const valid = [];
+    input.forEach((raw, index) => {
+        if (!raw || typeof raw !== "object" || !raw.box) {
+            dropped.push(reportId(raw ?? { type: "text" }, index));
+            degraded = true;
+            return;
+        }
+        // Non-finite box numbers (NaN/±Infinity/non-number) would survive the
+        // Math.* clamp below and poison the frame all the way to native ints.
+        const b = raw.box;
+        if (![b.x, b.y, b.w, b.h].every((n) => typeof n === "number" && Number.isFinite(n))) {
+            dropped.push(reportId(raw, index));
+            degraded = true;
+            return;
+        }
+        // Leading "~" is the differ's synthetic-id namespace — an app id there
+        // would never match across frames (re-created every push). Normalize by
+        // stripping; the rewrite is deterministic, so diffing stays stable.
+        const el = raw.id?.startsWith("~") ? { ...raw, id: raw.id.replace(/^~+/, "") || undefined } : raw;
+        if (el.id) {
+            const key = `${el.type}:${el.id}`;
+            if (seenIds.has(key)) {
+                dropped.push(reportId(el, index));
+                degraded = true;
+                return;
+            }
+            seenIds.add(key);
+        }
+        valid.push({ el, index });
+    });
+    // Clamp + per-type limits, then budget in array order.
+    let textBudget = caps.maxTextElements;
+    let imageBudget = caps.maxImageElements;
+    const out = [];
+    for (const { el, index } of valid) {
+        const clamped = clampBox(el.box, caps.width, caps.height);
+        if (!clamped) {
+            dropped.push(reportId(el, index));
+            degraded = true;
+            continue;
+        }
+        const shrunk = boxShrunk(el.box, clamped);
+        if (shrunk)
+            degraded = true;
+        if (el.type === "image") {
+            // Images: a shrunk box can't be honored (we don't crop pixels host-side)
+            // and per-image device limits are box-level (the firmware allocates the
+            // component from the box). SGCs scale pixels to the box (phone-side
+            // scaling — never on glasses).
+            if (shrunk) {
+                dropped.push(reportId(el, index));
+                continue;
+            }
+            if (caps.maxImagePx && (clamped.w > caps.maxImagePx.width || clamped.h > caps.maxImagePx.height)) {
+                dropped.push(reportId(el, index));
+                degraded = true;
+                continue;
+            }
+            if (imageBudget <= 0) {
+                dropped.push(reportId(el, index));
+                degraded = true;
+                continue;
+            }
+            imageBudget--;
+            out.push({
+                id: el.id,
+                type: "image",
+                box: clamped,
+                data: el.data,
+                contentHash: elementContentHash({ type: "image", data: el.data }),
+            });
+            continue;
+        }
+        // text + rect share the text-container budget (design doc §3.4.6).
+        if (textBudget <= 0) {
+            dropped.push(reportId(el, index));
+            degraded = true;
+            continue;
+        }
+        textBudget--;
+        if (el.type === "rect") {
+            out.push({
+                id: el.id,
+                type: "rect",
+                box: clamped,
+                style: el.style,
+                contentHash: elementContentHash({ type: "rect", style: el.style }),
+            });
+            continue;
+        }
+        // Text: wrap on the phone into the (clamped) box. The box then carries
+        // pre-wrapped text; firmware in-box wrap is a fallback, not the mechanism.
+        // Height clipping only applies with a CALIBRATED line height — otherwise
+        // the firmware clips vertically in-box (legacy behavior).
+        const style = el.style ?? {};
+        const maxLines = lineHeight ? Math.max(1, Math.floor(clamped.h / lineHeight)) : profile.maxLines;
+        const result = wrapper.wrap(el.text ?? "", {
+            maxWidthPx: clamped.w,
+            maxLines,
+            ...(style.breakMode ? { breakMode: style.breakMode } : {}),
+        });
+        let lines = result.lines;
+        if (result.truncated) {
+            degraded = true;
+            if (style.overflow === "ellipsis" && lines.length > 0) {
+                // Trim the last line until it fits WITH the ellipsis appended —
+                // otherwise the extra glyph can overflow the clamped box width.
+                let last = lines[lines.length - 1];
+                while (last.length > 0 && !measurer.fitsInWidth(`${last}…`, clamped.w)) {
+                    last = last.slice(0, -1);
+                }
+                // A box narrower than the ellipsis glyph itself gets an empty line —
+                // never emit a line wider than the clamped box.
+                const ellipsized = last.length > 0 || measurer.fitsInWidth("…", clamped.w) ? `${last}…` : "";
+                lines = [...lines.slice(0, -1), ellipsized];
+            }
+        }
+        const wrappedText = lines.join("\n");
+        out.push({
+            id: el.id,
+            type: "text",
+            box: clamped,
+            text: wrappedText,
+            style: el.style,
+            contentHash: elementContentHash({ type: "text", text: wrappedText, style: el.style }),
+        });
+    }
+    return { elements: out, degraded, dropped };
+}
+//# sourceMappingURL=process.js.map

package/build/utils/display/scene/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../../src/utils/display/scene/process.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Scene processing — validate → clamp → budget → wrap. Everything here is\n * generic; device variation enters only through the capabilities block and the\n * display profile (data, not code). Spec §5.\n *\n * Never rejects a frame: offending elements are dropped per-element and\n * reported via `dropped` / `degraded` (design doc §3.4.6; spec §4 refines the\n * design doc's image \"reject\" to per-element drop).\n */\n\nimport {TextMeasurer} from \"../measurer/TextMeasurer\"\nimport {TextWrapper} from \"../wrapper/TextWrapper\"\nimport type {DisplayProfile} from \"../profiles/types\"\nimport type {DiffableElement} from \"./differ\"\nimport type {SceneBox, SceneDisplayCapabilities, SceneElementInput, SceneTextStyle} from \"./types\"\nimport {elementContentHash} from \"./types\"\n\nexport interface ProcessedScene {\n  elements: DiffableElement[]\n  degraded: boolean\n  dropped: string[]\n}\n\n/** Reporting id for an element the app may not have named. */\nfunction reportId(el: SceneElementInput, index: number): string {\n  return el.id ?? `${el.type}[${index}]`\n}\n\nfunction clampBox(box: SceneBox, width: number, height: number): SceneBox | null {\n  const x1 = Math.max(0, Math.floor(box.x))\n  const y1 = Math.max(0, Math.floor(box.y))\n  const x2 = Math.min(width, Math.floor(box.x) + Math.max(0, Math.floor(box.w)))\n  const y2 = Math.min(height, Math.floor(box.y) + Math.max(0, Math.floor(box.h)))\n  if (x2 <= x1 || y2 <= y1) return null\n  return {x: x1, y: y1, w: x2 - x1, h: y2 - y1}\n}\n\nfunction boxShrunk(orig: SceneBox, clamped: SceneBox): boolean {\n  return (\n    clamped.x !== Math.floor(orig.x) ||\n    clamped.y !== Math.floor(orig.y) ||\n    clamped.w !== Math.floor(orig.w) ||\n    clamped.h !== Math.floor(orig.h)\n  )\n}\n\n/**\n * Line height for box-height→line-count math — ONLY when the profile declares\n * a calibrated `lineHeightPx`. Deriving one from full-canvas numbers proved\n * wrong on hardware (288/8=36px clipped the G2 nav instruction to one line;\n * the real container line height is smaller). Without calibration we return\n * null and the wrap step skips host-side height clipping entirely — text wraps\n * to the box WIDTH and the firmware clips vertically in-box, which is exactly\n * the legacy behavior.\n */\nexport function profileLineHeightPx(profile: DisplayProfile, _canvasHeight: number): number | null {\n  return profile.lineHeightPx ?? null\n}\n\n/**\n * Process a raw scene against a device's capabilities + profile. Output is\n * diff-ready (text pre-wrapped, boxes clamped, content hashed) and reflects\n * exactly what will be sent — the diff baseline is post-processed by design\n * (spec §4).\n */\nexport function processScene(\n  input: readonly SceneElementInput[],\n  caps: SceneDisplayCapabilities,\n  profile: DisplayProfile,\n): ProcessedScene {\n  const dropped: string[] = []\n  let degraded = false\n\n  const measurer = new TextMeasurer(profile)\n  const wrapper = new TextWrapper(measurer)\n  const lineHeight = profileLineHeightPx(profile, caps.height)\n\n  // Validate + dedupe explicit ids (first occurrence wins; dupes are dev error).\n  const seenIds = new Set<string>()\n  const valid: {el: SceneElementInput; index: number}[] = []\n  input.forEach((raw, index) => {\n    if (!raw || typeof raw !== \"object\" || !raw.box) {\n      dropped.push(reportId(raw ?? ({type: \"text\"} as SceneElementInput), index))\n      degraded = true\n      return\n    }\n    // Non-finite box numbers (NaN/±Infinity/non-number) would survive the\n    // Math.* clamp below and poison the frame all the way to native ints.\n    const b = raw.box\n    if (![b.x, b.y, b.w, b.h].every((n) => typeof n === \"number\" && Number.isFinite(n))) {\n      dropped.push(reportId(raw, index))\n      degraded = true\n      return\n    }\n    // Leading \"~\" is the differ's synthetic-id namespace — an app id there\n    // would never match across frames (re-created every push). Normalize by\n    // stripping; the rewrite is deterministic, so diffing stays stable.\n    const el = raw.id?.startsWith(\"~\") ? {...raw, id: raw.id.replace(/^~+/, \"\") || undefined} : raw\n    if (el.id) {\n      const key = `${el.type}:${el.id}`\n      if (seenIds.has(key)) {\n        dropped.push(reportId(el, index))\n        degraded = true\n        return\n      }\n      seenIds.add(key)\n    }\n    valid.push({el, index})\n  })\n\n  // Clamp + per-type limits, then budget in array order.\n  let textBudget = caps.maxTextElements\n  let imageBudget = caps.maxImageElements\n  const out: DiffableElement[] = []\n\n  for (const {el, index} of valid) {\n    const clamped = clampBox(el.box, caps.width, caps.height)\n    if (!clamped) {\n      dropped.push(reportId(el, index))\n      degraded = true\n      continue\n    }\n    const shrunk = boxShrunk(el.box, clamped)\n    if (shrunk) degraded = true\n\n    if (el.type === \"image\") {\n      // Images: a shrunk box can't be honored (we don't crop pixels host-side)\n      // and per-image device limits are box-level (the firmware allocates the\n      // component from the box). SGCs scale pixels to the box (phone-side\n      // scaling — never on glasses).\n      if (shrunk) {\n        dropped.push(reportId(el, index))\n        continue\n      }\n      if (caps.maxImagePx && (clamped.w > caps.maxImagePx.width || clamped.h > caps.maxImagePx.height)) {\n        dropped.push(reportId(el, index))\n        degraded = true\n        continue\n      }\n      if (imageBudget <= 0) {\n        dropped.push(reportId(el, index))\n        degraded = true\n        continue\n      }\n      imageBudget--\n      out.push({\n        id: el.id,\n        type: \"image\",\n        box: clamped,\n        data: el.data,\n        contentHash: elementContentHash({type: \"image\", data: el.data}),\n      })\n      continue\n    }\n\n    // text + rect share the text-container budget (design doc §3.4.6).\n    if (textBudget <= 0) {\n      dropped.push(reportId(el, index))\n      degraded = true\n      continue\n    }\n    textBudget--\n\n    if (el.type === \"rect\") {\n      out.push({\n        id: el.id,\n        type: \"rect\",\n        box: clamped,\n        style: el.style,\n        contentHash: elementContentHash({type: \"rect\", style: el.style}),\n      })\n      continue\n    }\n\n    // Text: wrap on the phone into the (clamped) box. The box then carries\n    // pre-wrapped text; firmware in-box wrap is a fallback, not the mechanism.\n    // Height clipping only applies with a CALIBRATED line height — otherwise\n    // the firmware clips vertically in-box (legacy behavior).\n    const style: SceneTextStyle = el.style ?? {}\n    const maxLines = lineHeight ? Math.max(1, Math.floor(clamped.h / lineHeight)) : profile.maxLines\n    const result = wrapper.wrap(el.text ?? \"\", {\n      maxWidthPx: clamped.w,\n      maxLines,\n      ...(style.breakMode ? {breakMode: style.breakMode} : {}),\n    })\n    let lines = result.lines\n    if (result.truncated) {\n      degraded = true\n      if (style.overflow === \"ellipsis\" && lines.length > 0) {\n        // Trim the last line until it fits WITH the ellipsis appended —\n        // otherwise the extra glyph can overflow the clamped box width.\n        let last = lines[lines.length - 1]\n        while (last.length > 0 && !measurer.fitsInWidth(`${last}…`, clamped.w)) {\n          last = last.slice(0, -1)\n        }\n        // A box narrower than the ellipsis glyph itself gets an empty line —\n        // never emit a line wider than the clamped box.\n        const ellipsized = last.length > 0 || measurer.fitsInWidth(\"…\", clamped.w) ? `${last}…` : \"\"\n        lines = [...lines.slice(0, -1), ellipsized]\n      }\n    }\n    const wrappedText = lines.join(\"\\n\")\n    out.push({\n      id: el.id,\n      type: \"text\",\n      box: clamped,\n      text: wrappedText,\n      style: el.style,\n      contentHash: elementContentHash({type: \"text\", text: wrappedText, style: el.style}),\n    })\n  }\n\n  return {elements: out, degraded, dropped}\n}\n"]}

package/build/utils/display/scene/store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SceneStore — the host's retained scene state, keyed (appId, view). Holds the
+ * last POST-PROCESSED frame sent to the device (the diff baseline), the scene
+ * epoch, and the synthetic-id counter. Recovery = replay from here; the device
+ * never needs an app's cooperation to rebuild (design doc §3.4.7).
+ *
+ * Duration/expiry stays in LocalDisplayManager (it already owns those timers);
+ * this store is pure retained state.
+ */
+import type { FrameElement, SceneFrame } from "./types";
+export declare class SceneStore {
+    private entries;
+    private key;
+    private entry;
+    /** The last frame sent for (app, view), or [] if none. */
+    lastFrame(appId: string, view: string): FrameElement[];
+    hasScene(appId: string, view: string): boolean;
+    /** Mint a synthetic element id — "~" prefix keeps it out of the app-id namespace. */
+    nextSyntheticId(appId: string, view: string): () => string;
+    /** Record the frame that was actually sent (post-processing, post-diff). */
+    commit(appId: string, view: string, elements: FrameElement[]): void;
+    /** True when the retained frame is a replay source only — not a diff baseline. */
+    isBaselineStale(appId: string, view: string): boolean;
+    /**
+     * The glasses view was cleared (durationMs expiry, unmount fallback, boot
+     * expiry): every app's retained frame for that view is now replay-only.
+     * Frames are kept — restore-as-replay repaints create-based and doesn't
+     * consult the baseline.
+     */
+    markViewStale(view: string): void;
+    currentEpoch(appId: string, view: string): number;
+    /**
+     * Bump the epoch — device switch, reconnect, app switch, scene↔legacy
+     * transition. A bumped epoch bypasses native dedup and tells the device the
+     * next frame rebuilds from scratch, so the diff baseline resets too.
+     */
+    bumpEpoch(appId: string, view: string): number;
+    /**
+     * Build a replay frame from retained state: the whole scene, all elements
+     * "created" (replay is always create-based — updates to dead firmware ids
+     * drop silently on the wire; spec §4). Returns null if nothing is retained.
+     */
+    buildReplayFrame(appId: string, view: "main" | "dashboard"): SceneFrame | null;
+    /** Forget an app's scene (app stop / clear). */
+    clear(appId: string, view?: string): void;
+    clearAll(): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/build/utils/display/scene/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/utils/display/scene/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAE,UAAU,EAAC,MAAM,SAAS,CAAA;AAerD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAA2B;IAE1C,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,KAAK;IAUb,0DAA0D;IAC1D,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE;IAItD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAK9C,qFAAqF;IACrF,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM;IAK1D,4EAA4E;IAC5E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAMnE,kFAAkF;IAClF,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAIrD;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOjC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAIjD;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAO9C;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI;IAe9E,gDAAgD;IAChD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAUzC,QAAQ,IAAI,IAAI;CAGjB"}

package/build/utils/display/scene/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/utils/display/scene/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * SceneStore — the host's retained scene state, keyed (appId, view). Holds the\n * last POST-PROCESSED frame sent to the device (the diff baseline), the scene\n * epoch, and the synthetic-id counter. Recovery = replay from here; the device\n * never needs an app's cooperation to rebuild (design doc §3.4.7).\n *\n * Duration/expiry stays in LocalDisplayManager (it already owns those timers);\n * this store is pure retained state.\n */\n\nimport type {FrameElement, SceneFrame} from \"./types\"\n\ninterface Entry {\n  lastFrame: FrameElement[] | null\n  epoch: number\n  idCounter: number\n  /**\n   * The glasses no longer show `lastFrame` (a system clear wiped the view) but\n   * the frame is retained as the replay source. The next incremental diff must\n   * run against an EMPTY baseline — otherwise \"unchanged\" elements are skipped\n   * and never repainted onto the blank screen.\n   */\n  baselineStale: boolean\n}\n\nexport class SceneStore {\n  private entries = new Map<string, Entry>()\n\n  private key(appId: string, view: string): string {\n    return `${appId}\u0000${view}`\n  }\n\n  private entry(appId: string, view: string): Entry {\n    const k = this.key(appId, view)\n    let e = this.entries.get(k)\n    if (!e) {\n      e = {lastFrame: null, epoch: 0, idCounter: 0, baselineStale: false}\n      this.entries.set(k, e)\n    }\n    return e\n  }\n\n  /** The last frame sent for (app, view), or [] if none. */\n  lastFrame(appId: string, view: string): FrameElement[] {\n    return this.entry(appId, view).lastFrame ?? []\n  }\n\n  hasScene(appId: string, view: string): boolean {\n    const e = this.entries.get(this.key(appId, view))\n    return !!e?.lastFrame && e.lastFrame.length > 0\n  }\n\n  /** Mint a synthetic element id — \"~\" prefix keeps it out of the app-id namespace. */\n  nextSyntheticId(appId: string, view: string): () => string {\n    const e = this.entry(appId, view)\n    return () => `~${++e.idCounter}`\n  }\n\n  /** Record the frame that was actually sent (post-processing, post-diff). */\n  commit(appId: string, view: string, elements: FrameElement[]): void {\n    const e = this.entry(appId, view)\n    e.lastFrame = elements\n    e.baselineStale = false\n  }\n\n  /** True when the retained frame is a replay source only — not a diff baseline. */\n  isBaselineStale(appId: string, view: string): boolean {\n    return this.entries.get(this.key(appId, view))?.baselineStale ?? false\n  }\n\n  /**\n   * The glasses view was cleared (durationMs expiry, unmount fallback, boot\n   * expiry): every app's retained frame for that view is now replay-only.\n   * Frames are kept — restore-as-replay repaints create-based and doesn't\n   * consult the baseline.\n   */\n  markViewStale(view: string): void {\n    // Key separator is NUL (see key()) — invisible in dumps, so match explicitly.\n    for (const [k, e] of this.entries) {\n      if (k.endsWith(`\\u0000${view}`)) e.baselineStale = true\n    }\n  }\n\n  currentEpoch(appId: string, view: string): number {\n    return this.entry(appId, view).epoch\n  }\n\n  /**\n   * Bump the epoch — device switch, reconnect, app switch, scene↔legacy\n   * transition. A bumped epoch bypasses native dedup and tells the device the\n   * next frame rebuilds from scratch, so the diff baseline resets too.\n   */\n  bumpEpoch(appId: string, view: string): number {\n    const e = this.entry(appId, view)\n    e.epoch++\n    e.lastFrame = null\n    return e.epoch\n  }\n\n  /**\n   * Build a replay frame from retained state: the whole scene, all elements\n   * \"created\" (replay is always create-based — updates to dead firmware ids\n   * drop silently on the wire; spec §4). Returns null if nothing is retained.\n   */\n  buildReplayFrame(appId: string, view: \"main\" | \"dashboard\"): SceneFrame | null {\n    const e = this.entries.get(this.key(appId, view))\n    if (!e?.lastFrame || e.lastFrame.length === 0) return null\n    const elements = e.lastFrame.map((el) => ({...el, change: \"created\" as const}))\n    e.epoch++\n    return {\n      appId,\n      view,\n      sceneEpoch: e.epoch,\n      replay: true,\n      elements,\n      removed: [],\n    }\n  }\n\n  /** Forget an app's scene (app stop / clear). */\n  clear(appId: string, view?: string): void {\n    if (view !== undefined) {\n      this.entries.delete(this.key(appId, view))\n      return\n    }\n    for (const k of [...this.entries.keys()]) {\n      if (k.startsWith(`${appId}\u0000`)) this.entries.delete(k)\n    }\n  }\n\n  clearAll(): void {\n    this.entries.clear()\n  }\n}\n"]}