@flighthq/snapshot 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/captureSnapshot.d.ts

@@ -6,9 +6,21 @@ import type { Snapshot } from '@flighthq/types/contract';
  *  affects the snapshot, and vice versa. The freeze makes it a fixed point-in-time value safe to
  *  store in an undo stack, send over the wire, or interpolate toward.
  *
- *  `source` must be plain, structured-cloneable data (numbers, strings, booleans, arrays, nested
- *  objects). Passing a class instance, function, or other non-cloneable value is programmer error and
- *  throws via `structuredClone`.
+ *  `source` must be plain, **acyclic**, structured-cloneable data (numbers, strings, booleans, arrays,
+ *  nested objects). Passing a class instance, function, or other non-cloneable value is programmer
+ *  error and throws via `structuredClone`.
+ *
+ *  Acyclic is a narrower contract than structured-cloneable, and deliberately so. `structuredClone`
+ *  itself handles cycles, and capture handles them too — but `equalsSnapshot`, `interpolateSnapshots`,
+ *  and `restoreSnapshot` walk a snapshot without tracking what they have visited, and giving them a
+ *  visited set would tax every acyclic walk in the common per-frame netcode path to serve a shape
+ *  almost no game state has. So a cycle is programmer error here, not a supported input. Import
+ *  `enableSnapshotGuards` to have it reported at capture time, where it is diagnosable, rather than as
+ *  a stack overflow several frames later.
  */
 export declare function captureSnapshot<T>(source: Readonly<T>): Snapshot<T>;
+/** Installs the capture-time guard, or clears it with `null`. The seam exists so the message and the
+ *  `@flighthq/log` dependency live in the separately-importable guard module rather than here; not
+ *  importing that module costs production nothing. Called by `enableSnapshotGuards`, not directly. */
+export declare function setSnapshotCaptureGuard(guard: ((source: unknown) => void) | null): void;
 //# sourceMappingURL=captureSnapshot.d.ts.map

package/dist/captureSnapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"captureSnapshot.d.ts","sourceRoot":"","sources":["../src/captureSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAInE"}
+{"version":3,"file":"captureSnapshot.d.ts","sourceRoot":"","sources":["../src/captureSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAKnE;AAED;;sGAEsG;AACtG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAEvF"}

package/dist/captureSnapshot.js

@@ -5,19 +5,40 @@
  *  affects the snapshot, and vice versa. The freeze makes it a fixed point-in-time value safe to
  *  store in an undo stack, send over the wire, or interpolate toward.
  *
- *  `source` must be plain, structured-cloneable data (numbers, strings, booleans, arrays, nested
- *  objects). Passing a class instance, function, or other non-cloneable value is programmer error and
- *  throws via `structuredClone`.
+ *  `source` must be plain, **acyclic**, structured-cloneable data (numbers, strings, booleans, arrays,
+ *  nested objects). Passing a class instance, function, or other non-cloneable value is programmer
+ *  error and throws via `structuredClone`.
+ *
+ *  Acyclic is a narrower contract than structured-cloneable, and deliberately so. `structuredClone`
+ *  itself handles cycles, and capture handles them too — but `equalsSnapshot`, `interpolateSnapshots`,
+ *  and `restoreSnapshot` walk a snapshot without tracking what they have visited, and giving them a
+ *  visited set would tax every acyclic walk in the common per-frame netcode path to serve a shape
+ *  almost no game state has. So a cycle is programmer error here, not a supported input. Import
+ *  `enableSnapshotGuards` to have it reported at capture time, where it is diagnosable, rather than as
+ *  a stack overflow several frames later.
  */
 export function captureSnapshot(source) {
+    _captureGuard?.(source);
     const clone = structuredClone(source);
     freezeSnapshotDeep(clone);
     return clone;
 }
+/** Installs the capture-time guard, or clears it with `null`. The seam exists so the message and the
+ *  `@flighthq/log` dependency live in the separately-importable guard module rather than here; not
+ *  importing that module costs production nothing. Called by `enableSnapshotGuards`, not directly. */
+export function setSnapshotCaptureGuard(guard) {
+    _captureGuard = guard;
+}
+let _captureGuard = null;
 // Recursively `Object.freeze`s every object and array reachable from `value`, so the whole tree is
 // immutable — not just the top level. Primitives and `null` are already immutable and skipped.
+//
+// `Object.isFrozen` doubles as the visited check. structuredClone preserves cycles and shared
+// references, so without it a cyclic clone recurses until the stack overflows, and a diamond is walked
+// once per path. Freezing before descending means an already-frozen node has been seen, which makes
+// the walk terminate on cycles and linear on shared subtrees, with no side table to allocate.
 function freezeSnapshotDeep(value) {
-    if (value === null || typeof value !== 'object') {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
         return;
     }
     Object.freeze(value);

package/dist/captureSnapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"captureSnapshot.js","sourceRoot":"","sources":["../src/captureSnapshot.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAI,MAAmB;IACpD,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAM,CAAC;IAC3C,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1B,OAAO,KAAoB,CAAC;AAC9B,CAAC;AAED,mGAAmG;AACnG,+FAA+F;AAC/F,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO;IACT,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,OAAO;IACT,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,EAAE,CAAC;QAChE,kBAAkB,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"captureSnapshot.js","sourceRoot":"","sources":["../src/captureSnapshot.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAI,MAAmB;IACpD,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAM,CAAC;IAC3C,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1B,OAAO,KAAoB,CAAC;AAC9B,CAAC;AAED;;sGAEsG;AACtG,MAAM,UAAU,uBAAuB,CAAC,KAAyC;IAC/E,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,IAAI,aAAa,GAAuC,IAAI,CAAC;AAE7D,mGAAmG;AACnG,+FAA+F;AAC/F,EAAE;AACF,8FAA8F;AAC9F,uGAAuG;AACvG,oGAAoG;AACpG,8FAA8F;AAC9F,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,OAAO;IACT,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,OAAO;IACT,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,EAAE,CAAC;QAChE,kBAAkB,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/contract.d.ts

@@ -1,4 +1,5 @@
 export * from './captureSnapshot';
+export * from './enableSnapshotGuards';
 export * from './equalsSnapshot';
 export * from './interpolateSnapshots';
 export * from './restoreSnapshot';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}

package/dist/contract.js

@@ -1,4 +1,5 @@
 export * from './captureSnapshot';
+export * from './enableSnapshotGuards';
 export * from './equalsSnapshot';
 export * from './interpolateSnapshots';
 export * from './restoreSnapshot';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}

package/dist/enableSnapshotGuards.d.ts

@@ -0,0 +1,28 @@
+/** Uninstalls the guard installed by `enableSnapshotGuards`. */
+export declare function disableSnapshotGuards(): void;
+/**
+ * Installs the caller-facing snapshot guard (opt-in, dev-only). It inspects each `captureSnapshot`
+ * source and warns once — through `@flighthq/log` — about the two shapes that pass `structuredClone`
+ * but then break the guarantees the rest of the package is built on.
+ *
+ * **Non-plain values.** `Map`, `Set`, `Date`, and typed arrays clone successfully, so capture appears
+ * to work, but neither of the package's two contracts survives: `Object.freeze` on a `Map` leaves
+ * `set`/`delete` fully functional, so the snapshot is not immutable, and `equalsSnapshot` compares
+ * leaves with `===`, so two `Map`s holding identical entries — or two `Date`s at the same instant —
+ * are reported unequal. State that looks unchanged then pushes a fresh undo entry every frame.
+ *
+ * **Cycles.** The package contract is acyclic plain data, narrower than structured-cloneable on
+ * purpose: `structuredClone` supports cycles and `captureSnapshot` handles them, but `equalsSnapshot`,
+ * `interpolateSnapshots`, and `restoreSnapshot` all recurse without tracking what they have visited,
+ * and adding a visited set would tax every acyclic walk in the per-frame path. So a cycle is programmer
+ * error, and this is where it becomes diagnosable rather than a stack overflow several frames later. `restoreSnapshot`
+ * is the one that hides: the first restore into a fresh target clones and succeeds, and only the
+ * second — once the target itself holds the cycle — recurses forever. A `RangeError` with no Flight
+ * frame in the stack is the least diagnosable failure in the package, which is why it is worth a
+ * message at the point the cyclic state is captured rather than several frames later.
+ *
+ * Not importing this module costs production nothing: the messages and the `@flighthq/log` dependency
+ * live only here.
+ */
+export declare function enableSnapshotGuards(): void;
+//# sourceMappingURL=enableSnapshotGuards.d.ts.map

package/dist/enableSnapshotGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableSnapshotGuards.d.ts","sourceRoot":"","sources":["../src/enableSnapshotGuards.ts"],"names":[],"mappings":"AAKA,gEAAgE;AAChE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/enableSnapshotGuards.js

@@ -0,0 +1,99 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setSnapshotCaptureGuard } from './captureSnapshot';
+/** Uninstalls the guard installed by `enableSnapshotGuards`. */
+export function disableSnapshotGuards() {
+    setSnapshotCaptureGuard(null);
+}
+/**
+ * Installs the caller-facing snapshot guard (opt-in, dev-only). It inspects each `captureSnapshot`
+ * source and warns once — through `@flighthq/log` — about the two shapes that pass `structuredClone`
+ * but then break the guarantees the rest of the package is built on.
+ *
+ * **Non-plain values.** `Map`, `Set`, `Date`, and typed arrays clone successfully, so capture appears
+ * to work, but neither of the package's two contracts survives: `Object.freeze` on a `Map` leaves
+ * `set`/`delete` fully functional, so the snapshot is not immutable, and `equalsSnapshot` compares
+ * leaves with `===`, so two `Map`s holding identical entries — or two `Date`s at the same instant —
+ * are reported unequal. State that looks unchanged then pushes a fresh undo entry every frame.
+ *
+ * **Cycles.** The package contract is acyclic plain data, narrower than structured-cloneable on
+ * purpose: `structuredClone` supports cycles and `captureSnapshot` handles them, but `equalsSnapshot`,
+ * `interpolateSnapshots`, and `restoreSnapshot` all recurse without tracking what they have visited,
+ * and adding a visited set would tax every acyclic walk in the per-frame path. So a cycle is programmer
+ * error, and this is where it becomes diagnosable rather than a stack overflow several frames later. `restoreSnapshot`
+ * is the one that hides: the first restore into a fresh target clones and succeeds, and only the
+ * second — once the target itself holds the cycle — recurses forever. A `RangeError` with no Flight
+ * frame in the stack is the least diagnosable failure in the package, which is why it is worth a
+ * message at the point the cyclic state is captured rather than several frames later.
+ *
+ * Not importing this module costs production nothing: the messages and the `@flighthq/log` dependency
+ * live only here.
+ */
+export function enableSnapshotGuards() {
+    setSnapshotCaptureGuard(warnOnUnsupportedSnapshotSource);
+}
+// Walks the source once, reporting the first occurrence of each problem kind. Tracks visited objects
+// so the walk itself terminates on the very cycles it is looking for.
+function warnOnUnsupportedSnapshotSource(source) {
+    const seen = new Set();
+    const nonPlain = new Set();
+    let cyclic = false;
+    const visit = (value) => {
+        if (value === null || typeof value !== 'object')
+            return;
+        if (seen.has(value)) {
+            cyclic = true;
+            return;
+        }
+        seen.add(value);
+        const kind = nonPlainSnapshotKind(value);
+        if (kind !== null) {
+            nonPlain.add(kind);
+            // A non-plain container's contents are not part of the plain-data tree; naming the container is
+            // the actionable half, and descending into a Map's entries would only repeat it.
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                visit(entry);
+            return;
+        }
+        for (const key of Object.keys(value)) {
+            visit(value[key]);
+        }
+    };
+    visit(source);
+    if (nonPlain.size > 0) {
+        logOnce('snapshot:non-plain-source', LogLevel.Warn, {
+            message: `captureSnapshot: source contains non-plain value(s) (${Array.from(nonPlain).sort().join(', ')}). ` +
+                'They clone, but a frozen Map/Set stays mutable and equalsSnapshot compares them by reference, ' +
+                'so the snapshot is neither immutable nor comparable. Convert to plain arrays/objects first.',
+        }, 'snapshot');
+    }
+    if (cyclic) {
+        logOnce('snapshot:cyclic-source', LogLevel.Warn, {
+            message: 'captureSnapshot: source contains a cycle. Capture handles it, but equalsSnapshot, ' +
+                'interpolateSnapshots, and restoreSnapshot recurse without cycle tracking and will overflow ' +
+                'the stack — restoreSnapshot only on the second restore into the same target.',
+        }, 'snapshot');
+    }
+}
+// Names the non-plain built-ins that structuredClone accepts, so the warning can say which one was
+// found. Anything structuredClone rejects outright (functions, class instances) already throws at the
+// capture call and needs no guard.
+function nonPlainSnapshotKind(value) {
+    if (value instanceof Map)
+        return 'Map';
+    if (value instanceof Set)
+        return 'Set';
+    if (value instanceof Date)
+        return 'Date';
+    if (value instanceof RegExp)
+        return 'RegExp';
+    if (ArrayBuffer.isView(value))
+        return 'TypedArray';
+    if (value instanceof ArrayBuffer)
+        return 'ArrayBuffer';
+    return null;
+}
+//# sourceMappingURL=enableSnapshotGuards.js.map

package/dist/enableSnapshotGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableSnapshotGuards.js","sourceRoot":"","sources":["../src/enableSnapshotGuards.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { captureSnapshot, equalsSnapshot, interpolateSnapshots, restoreSnapshot } from './contract';
+export { captureSnapshot, disableSnapshotGuards, enableSnapshotGuards, equalsSnapshot, interpolateSnapshots, restoreSnapshot, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { captureSnapshot, equalsSnapshot, interpolateSnapshots, restoreSnapshot } from './contract';
+export { captureSnapshot, disableSnapshotGuards, enableSnapshotGuards, equalsSnapshot, interpolateSnapshots, restoreSnapshot, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/interpolateSnapshots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interpolateSnapshots.d.ts","sourceRoot":"","sources":["../src/interpolateSnapshots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EACd,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EACd,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,CAAC,EACN,MAAM,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,GAChC,IAAI,CAYN"}
+{"version":3,"file":"interpolateSnapshots.d.ts","sourceRoot":"","sources":["../src/interpolateSnapshots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EACd,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EACd,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,CAAC,EACN,MAAM,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,GAChC,IAAI,CAiBN"}

package/dist/interpolateSnapshots.js

@@ -24,11 +24,16 @@ export function interpolateSnapshots(a, b, t, out, schema) {
         typeof out !== 'object') {
         return;
     }
-    interpolateSnapshotsInto(out, a, b, clamp(t, 0, 1), schema, '');
+    // The schema is compiled to a Set once per call rather than scanned per leaf: SnapshotSchema is a
+    // readonly string[], so the old per-leaf `includes` was linear in the schema on every numeric field.
+    // `undefined` (no schema, every numeric leaf interpolates) stays distinct from an empty Set (a schema
+    // that lists nothing, so nothing interpolates) — collapsing those two inverts the caller's intent.
+    const paths = schema === undefined ? undefined : new Set(schema);
+    interpolateSnapshotsInto(out, a, b, clamp(t, 0, 1), paths, '');
 }
 // Walks `b` (the destination shape) key by key, writing each interpolated or snapped field into
 // `out`, reading the matching value from `a`. `prefix` is the dotted path to the current container.
-function interpolateSnapshotsInto(out, a, b, t, schema, prefix) {
+function interpolateSnapshotsInto(out, a, b, t, paths, prefix) {
     const outRecord = out;
     const aRecord = a;
     const bRecord = b;
@@ -36,11 +41,12 @@ function interpolateSnapshotsInto(out, a, b, t, schema, prefix) {
         out.length = b.length;
     }
     for (const key of Object.keys(bRecord)) {
-        const path = prefix === '' ? key : `${prefix}.${key}`;
         const aValue = aRecord[key];
         const bValue = bRecord[key];
         if (typeof aValue === 'number' && typeof bValue === 'number') {
-            outRecord[key] = isSnapshotPathInterpolated(schema, path) ? lerp(aValue, bValue, t) : bValue;
+            // With no schema every numeric leaf interpolates, so the dotted path is never consulted — and
+            // building it was the walk's main per-leaf allocation. Only pay for it when a schema exists.
+            outRecord[key] = paths === undefined || paths.has(snapshotPath(prefix, key)) ? lerp(aValue, bValue, t) : bValue;
             continue;
         }
         if (aValue !== null &&
@@ -50,15 +56,15 @@ function interpolateSnapshotsInto(out, a, b, t, schema, prefix) {
             Array.isArray(aValue) === Array.isArray(bValue)) {
             const container = ensureSnapshotContainer(outRecord[key], Array.isArray(bValue));
             outRecord[key] = container;
-            interpolateSnapshotsInto(container, aValue, bValue, t, schema, path);
+            interpolateSnapshotsInto(container, aValue, bValue, t, paths, paths === undefined ? '' : snapshotPath(prefix, key));
             continue;
         }
         outRecord[key] = cloneSnapshotValue(bValue);
     }
 }
-// A numeric leaf interpolates when there is no schema, or when its path is listed in the schema.
-function isSnapshotPathInterpolated(schema, path) {
-    return schema === undefined || schema.includes(path);
+// Joins a container prefix and key into the dotted path a schema lists.
+function snapshotPath(prefix, key) {
+    return prefix === '' ? key : `${prefix}.${key}`;
 }
 // Reuses `existing` when it is already a mutable container of the needed kind, else allocates a fresh
 // empty one, so the walk can recurse into `out` even when `out` did not mirror the snapshot's shape.

package/dist/interpolateSnapshots.js.map

@@ -1 +1 @@
-{"version":3,"file":"interpolateSnapshots.js","sourceRoot":"","sources":["../src/interpolateSnapshots.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"interpolateSnapshots.js","sourceRoot":"","sources":["../src/interpolateSnapshots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAGtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAClC,CAAc,EACd,CAAc,EACd,CAAS,EACT,GAAM,EACN,MAAiC;IAEjC,IACE,CAAC,KAAK,IAAI;QACV,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,OAAO,CAAC,KAAK,QAAQ;QACrB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ,EACvB,CAAC;QACD,OAAO;IACT,CAAC;IACD,kGAAkG;IAClG,qGAAqG;IACrG,sGAAsG;IACtG,mGAAmG;IACnG,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACjE,wBAAwB,CAAC,GAAa,EAAE,CAAW,EAAE,CAAW,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED,gGAAgG;AAChG,oGAAoG;AACpG,SAAS,wBAAwB,CAC/B,GAAW,EACX,CAAS,EACT,CAAS,EACT,CAAS,EACT,KAAsC,EACtC,MAAc;IAEd,MAAM,SAAS,GAAG,GAA8B,CAAC;IACjD,MAAM,OAAO,GAAG,CAA4B,CAAC;IAC7C,MAAM,OAAO,GAAG,CAA4B,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,GAAiB,CAAC,MAAM,GAAI,CAAe,CAAC,MAAM,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7D,8FAA8F;YAC9F,6FAA6F;YAC7F,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAChH,SAAS;QACX,CAAC;QACD,IACE,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAC/C,CAAC;YACD,MAAM,SAAS,GAAG,uBAAuB,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACjF,SAAS,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;YAC3B,wBAAwB,CACtB,SAAS,EACT,MAAM,EACN,MAAM,EACN,CAAC,EACD,KAAK,EACL,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,CACrD,CAAC;YACF,SAAS;QACX,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,SAAS,YAAY,CAAC,MAAc,EAAE,GAAW;IAC/C,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC;AAClD,CAAC;AAED,sGAAsG;AACtG,qGAAqG;AACrG,SAAS,uBAAuB,CAAC,QAAiB,EAAE,OAAgB;IAClE,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,EAAE,CAAC;QAC7F,OAAO,QAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3B,CAAC;AAED,qGAAqG;AACrG,gFAAgF;AAChF,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/snapshot",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.1-next.209.43ef1bc",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,8 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/math": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.1-next.209.43ef1bc",
+    "@flighthq/math": "0.3.1-next.209.43ef1bc",
+    "@flighthq/types": "0.3.1-next.209.43ef1bc"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/captureSnapshot.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { captureSnapshot } from './captureSnapshot';
+import { captureSnapshot, setSnapshotCaptureGuard } from './captureSnapshot';
 
 describe('captureSnapshot', () => {
   it('returns a deep-equal copy of the source', () => {
@@ -48,3 +48,76 @@ describe('captureSnapshot', () => {
     expect(snapshot.c).toBe(1);
   });
 });
+
+describe('captureSnapshot cyclic and shared structure', () => {
+  // The package contract is acyclic, so these are not a supported input — they cover incidental
+  // robustness, not a guarantee. Object.isFrozen doubles as the freeze walk's visited mark at no cost,
+  // so capture survives a cycle rather than overflowing; the downstream walks deliberately do not, and
+  // enableSnapshotGuards reports a cyclic source at capture time.
+  it('captures a self-referencing object without overflowing the stack', () => {
+    const node: Record<string, unknown> = { name: 'root' };
+    node['self'] = node;
+
+    const snapshot = captureSnapshot(node) as Record<string, unknown>;
+
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(snapshot['self']).toBe(snapshot);
+  });
+
+  it('captures a mutually-referencing pair', () => {
+    const a: Record<string, unknown> = { tag: 'a' };
+    const b: Record<string, unknown> = { tag: 'b', a };
+    a['b'] = b;
+
+    const snapshot = captureSnapshot(a) as Record<string, Record<string, unknown>>;
+
+    expect(Object.isFrozen(snapshot['b'])).toBe(true);
+    expect(snapshot['b']!['a']).toBe(snapshot);
+  });
+
+  // A diamond is not a cycle, but shares the visited path: structuredClone keeps the sharing, and the
+  // freeze walk must still freeze the shared node rather than skip it.
+  it('freezes a shared subtree reached by two paths', () => {
+    const shared = { v: 1 };
+
+    const snapshot = captureSnapshot({ left: shared, right: shared }) as { left: object; right: object };
+
+    expect(snapshot.left).toBe(snapshot.right);
+    expect(Object.isFrozen(snapshot.left)).toBe(true);
+  });
+});
+
+describe('setSnapshotCaptureGuard', () => {
+  afterEach(() => setSnapshotCaptureGuard(null));
+
+  // The seam exists so the warning text and the @flighthq/log dependency stay in the separately
+  // importable guard module; the core path only calls whatever is installed.
+  it('passes the capture source to the installed guard', () => {
+    const seen: unknown[] = [];
+    setSnapshotCaptureGuard((source) => seen.push(source));
+    const source = { hp: 1 };
+
+    captureSnapshot(source);
+
+    expect(seen).toEqual([source]);
+  });
+
+  it('runs the guard against the source rather than the frozen clone', () => {
+    let wasFrozen = true;
+    setSnapshotCaptureGuard((source) => (wasFrozen = Object.isFrozen(source)));
+
+    captureSnapshot({ hp: 1 });
+
+    expect(wasFrozen).toBe(false);
+  });
+
+  it('stops calling the guard once cleared with null', () => {
+    let calls = 0;
+    setSnapshotCaptureGuard(() => (calls += 1));
+    captureSnapshot({ a: 1 });
+    setSnapshotCaptureGuard(null);
+    captureSnapshot({ a: 2 });
+
+    expect(calls).toBe(1);
+  });
+});

package/src/enableSnapshotGuards.test.ts

@@ -0,0 +1,62 @@
+import { setLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+
+import { captureSnapshot } from './captureSnapshot';
+import { disableSnapshotGuards, enableSnapshotGuards } from './enableSnapshotGuards';
+
+let entries: LogEntry[];
+
+beforeEach(() => {
+  entries = [];
+  setLogSink((entry) => entries.push(entry));
+});
+
+afterEach(() => {
+  disableSnapshotGuards();
+  setLogSink(null);
+});
+
+function messages(): string[] {
+  return entries.map((e) => String((e.data as { message?: unknown } | undefined)?.message ?? ''));
+}
+
+describe('disableSnapshotGuards', () => {
+  it('stops the guard from inspecting later captures', () => {
+    enableSnapshotGuards();
+    disableSnapshotGuards();
+    captureSnapshot({ when: new Date(0) });
+    expect(messages()).toEqual([]);
+  });
+});
+
+describe('enableSnapshotGuards', () => {
+  it('says nothing for a plain acyclic source', () => {
+    enableSnapshotGuards();
+    captureSnapshot({ hp: 1, items: [{ id: 'a' }], nested: { deep: { ok: true } } });
+    expect(messages()).toEqual([]);
+  });
+
+  it('warns about a Map, which clones but is neither frozen nor comparable', () => {
+    enableSnapshotGuards();
+    captureSnapshot({ byId: new Map([['a', 1]]) });
+    expect(messages().join('\n')).toContain('Map');
+  });
+
+  it('warns about a cycle, naming the operations that cannot walk it', () => {
+    enableSnapshotGuards();
+    const node: Record<string, unknown> = { name: 'root' };
+    node['self'] = node;
+    captureSnapshot(node);
+    expect(messages().join('\n')).toContain('cycle');
+  });
+
+  // The guard walks the same shape it is warning about, so it has to survive it — a cycle guard that
+  // overflows the stack before it can report the cycle would be worse than no guard.
+  it('terminates on the cyclic source it is reporting', () => {
+    enableSnapshotGuards();
+    const a: Record<string, unknown> = {};
+    const b: Record<string, unknown> = { a };
+    a['b'] = b;
+    expect(() => captureSnapshot(a)).not.toThrow();
+  });
+});

package/src/equalsSnapshot.test.ts

@@ -56,3 +56,15 @@ describe('equalsSnapshot', () => {
     expect(equalsSnapshot(a, b)).toBe(false);
   });
 });
+
+describe('equalsSnapshot documented leaf semantics', () => {
+  // Leaves are compared with ===, which the doc comment calls out precisely because both of these
+  // surprise people. Pinned so the comparison cannot quietly become Object.is.
+  it('reports two NaN leaves as unequal, since === says so', () => {
+    expect(equalsSnapshot(captureSnapshot({ v: NaN }), captureSnapshot({ v: NaN }))).toBe(false);
+  });
+
+  it('reports -0 and +0 as equal, since === says so', () => {
+    expect(equalsSnapshot(captureSnapshot({ v: -0 }), captureSnapshot({ v: 0 }))).toBe(true);
+  });
+});

package/src/interpolateSnapshots.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import { captureSnapshot } from './captureSnapshot';
 import { interpolateSnapshots } from './interpolateSnapshots';
+import { restoreSnapshot } from './restoreSnapshot';
 
 describe('interpolateSnapshots', () => {
   it('lerps numerics and snaps the string at t=0.5', () => {
@@ -95,3 +96,58 @@ describe('interpolateSnapshots', () => {
     expect(out.tag).toBeNull();
   });
 });
+
+describe('interpolateSnapshots schema paths', () => {
+  // A schema listing an array-indexed path is the case the dotted-path walk exists for: array
+  // elements are addressed by index, so 'players.0.health' interpolates while 'players.1.health' —
+  // absent from the schema — snaps to b.
+  it('interpolates only the array-indexed path listed in the schema', () => {
+    const a = captureSnapshot({ players: [{ health: 0 }, { health: 0 }] });
+    const b = captureSnapshot({ players: [{ health: 100 }, { health: 100 }] });
+    const out = { players: [{ health: 0 }, { health: 0 }] };
+
+    interpolateSnapshots(a, b, 0.5, out, ['players.0.health']);
+
+    expect(out.players[0]!.health).toBe(50);
+    expect(out.players[1]!.health).toBe(100);
+  });
+
+  // An empty schema is not the same as no schema: it lists nothing, so nothing interpolates and every
+  // numeric leaf snaps to b. Collapsing the two would silently invert the caller's intent.
+  it('treats an empty schema as "interpolate nothing", not "interpolate everything"', () => {
+    const a = captureSnapshot({ hp: 0 });
+    const b = captureSnapshot({ hp: 100 });
+    const out = { hp: 0 };
+
+    interpolateSnapshots(a, b, 0.5, out, []);
+
+    expect(out.hp).toBe(100);
+  });
+
+  it('interpolates every numeric leaf when no schema is given', () => {
+    const a = captureSnapshot({ hp: 0, mp: 0 });
+    const b = captureSnapshot({ hp: 100, mp: 50 });
+    const out = { hp: 0, mp: 0 };
+
+    interpolateSnapshots(a, b, 0.5, out);
+
+    expect(out.hp).toBe(50);
+    expect(out.mp).toBe(25);
+  });
+
+  // The documented use: out is the caller's live render-state object, interpolated each frame and
+  // later restored from a snapshot. The two operations must not fight over the same object.
+  it('interpolates into an out object that is later restored into', () => {
+    const a = captureSnapshot({ pos: { x: 0, y: 0 }, tag: 'a' });
+    const b = captureSnapshot({ pos: { x: 10, y: 20 }, tag: 'b' });
+    const live = { pos: { x: 0, y: 0 }, tag: 'a' };
+
+    interpolateSnapshots(a, b, 0.5, live);
+    expect(live.pos).toEqual({ x: 5, y: 10 });
+    expect(live.tag).toBe('b');
+
+    restoreSnapshot(a, live);
+    expect(live.pos).toEqual({ x: 0, y: 0 });
+    expect(live.tag).toBe('a');
+  });
+});

package/src/restoreSnapshot.test.ts

@@ -84,3 +84,40 @@ describe('restoreSnapshot', () => {
     expect(target.items).toEqual([1, 2]);
   });
 });
+
+describe('restoreSnapshot array resizing', () => {
+  // Shrink and grow are separate paths through the same length assignment, and a restore loop that
+  // only ever grows would never notice a shrink that leaves stale trailing entries behind.
+  it('shrinks a nested array to the snapshot length', () => {
+    const snapshot = captureSnapshot({ items: [{ id: 'a' }] });
+    const live = { items: [{ id: 'x' }, { id: 'y' }, { id: 'z' }] };
+
+    restoreSnapshot(snapshot, live);
+
+    expect(live.items).toEqual([{ id: 'a' }]);
+  });
+
+  it('grows a nested array to the snapshot length', () => {
+    const snapshot = captureSnapshot({ items: [{ id: 'a' }, { id: 'b' }, { id: 'c' }] });
+    const live = { items: [{ id: 'x' }] };
+
+    restoreSnapshot(snapshot, live);
+
+    expect(live.items).toEqual([{ id: 'a' }, { id: 'b' }, { id: 'c' }]);
+  });
+
+  // Round trip through a mutation: capture, mutate the live object freely, restore, and the live
+  // object is back to the captured state without aliasing the frozen snapshot.
+  it('round-trips capture, mutate, restore without aliasing the snapshot', () => {
+    const live = { hp: 10, items: [{ id: 'a' }] };
+    const snapshot = captureSnapshot(live);
+
+    live.hp = 99;
+    live.items.push({ id: 'b' });
+    restoreSnapshot(snapshot, live);
+
+    expect(live).toEqual({ hp: 10, items: [{ id: 'a' }] });
+    live.items[0]!.id = 'mutated';
+    expect(snapshot.items[0]!.id).toBe('a');
+  });
+});