@flighthq/snapshot 0.1.0

package/dist/captureSnapshot.d.ts

@@ -0,0 +1,14 @@
+import type { Snapshot } from '@flighthq/types';
+/** Capture `source` into an immutable snapshot: a deep clone of the plain state, deep-frozen so
+ *  nothing can mutate it afterward.
+ *
+ *  The clone means the returned snapshot does not alias `source` — mutating `source` later never
+ *  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`.
+ */
+export declare function captureSnapshot<T>(source: Readonly<T>): Snapshot<T>;
+//# sourceMappingURL=captureSnapshot.d.ts.map

package/dist/captureSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureSnapshot.d.ts","sourceRoot":"","sources":["../src/captureSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAInE"}

package/dist/captureSnapshot.js

@@ -0,0 +1,34 @@
+/** Capture `source` into an immutable snapshot: a deep clone of the plain state, deep-frozen so
+ *  nothing can mutate it afterward.
+ *
+ *  The clone means the returned snapshot does not alias `source` — mutating `source` later never
+ *  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`.
+ */
+export function captureSnapshot(source) {
+    const clone = structuredClone(source);
+    freezeSnapshotDeep(clone);
+    return clone;
+}
+// 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.
+function freezeSnapshotDeep(value) {
+    if (value === null || typeof value !== 'object') {
+        return;
+    }
+    Object.freeze(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            freezeSnapshotDeep(value[index]);
+        }
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        freezeSnapshotDeep(value[key]);
+    }
+}
+//# sourceMappingURL=captureSnapshot.js.map

package/dist/captureSnapshot.js.map

@@ -0,0 +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"}

package/dist/equalsSnapshot.d.ts

@@ -0,0 +1,10 @@
+import type { Snapshot } from '@flighthq/types';
+/** Deep structural equality between two snapshots: `true` when they have the same shape and every
+ *  leaf value is strictly equal.
+ *
+ *  Objects must have the same own keys; arrays must have the same length with element-wise equal
+ *  entries. Leaves are compared with `===`, so `NaN` never equals itself and `-0`/`+0` are equal.
+ *  Used to detect whether state actually changed before pushing an undo entry or sending a frame.
+ */
+export declare function equalsSnapshot<T>(a: Snapshot<T>, b: Snapshot<T>): boolean;
+//# sourceMappingURL=equalsSnapshot.d.ts.map

package/dist/equalsSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equalsSnapshot.d.ts","sourceRoot":"","sources":["../src/equalsSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAEzE"}

package/dist/equalsSnapshot.js

@@ -0,0 +1,51 @@
+/** Deep structural equality between two snapshots: `true` when they have the same shape and every
+ *  leaf value is strictly equal.
+ *
+ *  Objects must have the same own keys; arrays must have the same length with element-wise equal
+ *  entries. Leaves are compared with `===`, so `NaN` never equals itself and `-0`/`+0` are equal.
+ *  Used to detect whether state actually changed before pushing an undo entry or sending a frame.
+ */
+export function equalsSnapshot(a, b) {
+    return snapshotValuesEqual(a, b);
+}
+function snapshotValuesEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aIsArray = Array.isArray(a);
+    if (aIsArray !== Array.isArray(b)) {
+        return false;
+    }
+    if (aIsArray) {
+        const aArray = a;
+        const bArray = b;
+        if (aArray.length !== bArray.length) {
+            return false;
+        }
+        for (let index = 0; index < aArray.length; index += 1) {
+            if (!snapshotValuesEqual(aArray[index], bArray[index])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    const aObject = a;
+    const bObject = b;
+    const aKeys = Object.keys(aObject);
+    if (aKeys.length !== Object.keys(bObject).length) {
+        return false;
+    }
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(bObject, key)) {
+            return false;
+        }
+        if (!snapshotValuesEqual(aObject[key], bObject[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=equalsSnapshot.js.map

package/dist/equalsSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"equalsSnapshot.js","sourceRoot":"","sources":["../src/equalsSnapshot.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAI,CAAc,EAAE,CAAc;IAC9D,OAAO,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAU,EAAE,CAAU;IACjD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,CAAc,CAAC;QAC9B,MAAM,MAAM,GAAG,CAAc,CAAC;QAC9B,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBACvD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,CAA4B,CAAC;IAC7C,MAAM,OAAO,GAAG,CAA4B,CAAC;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YACxD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACrD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './captureSnapshot';
+export * from './equalsSnapshot';
+export * from './interpolateSnapshots';
+export * from './restoreSnapshot';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './captureSnapshot';
+export * from './equalsSnapshot';
+export * from './interpolateSnapshots';
+export * from './restoreSnapshot';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/interpolateSnapshots.d.ts

@@ -0,0 +1,19 @@
+import type { Snapshot, SnapshotSchema } from '@flighthq/types';
+/** Interpolate between two snapshots into a live mutable `out`, the "tween over instances" for smooth
+ *  netcode/replay rendering between two fixed frames.
+ *
+ *  `t` is clamped to `[0, 1]`. For each numeric leaf present as a number in both `a` and `b`, `out`
+ *  receives `lerp(a, b, t)`. Every non-numeric leaf — strings, booleans, `null`/`undefined`, or a
+ *  slot that is a number in only one snapshot — snaps to the destination value from `b` (cloned so
+ *  `out` stays mutable and unaliased). Nested objects and arrays are walked recursively; arrays are
+ *  resized to `b`'s length and interpolated positionally.
+ *
+ *  With a `schema` (dot-separated paths from the root, array elements by index), only numeric leaves
+ *  whose path is listed interpolate; every other numeric leaf snaps to `b` — how a numeric id or
+ *  discrete count is kept from blending. Without a schema, all numeric leaves interpolate.
+ *
+ *  `out` may be a separate live object; it is read from `a`/`b` and written field by field, so it can
+ *  safely be the caller's render-state object.
+ */
+export declare function interpolateSnapshots<T>(a: Snapshot<T>, b: Snapshot<T>, t: number, out: T, schema?: Readonly<SnapshotSchema>): void;
+//# sourceMappingURL=interpolateSnapshots.d.ts.map

package/dist/interpolateSnapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolateSnapshots.d.ts","sourceRoot":"","sources":["../src/interpolateSnapshots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;;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"}

package/dist/interpolateSnapshots.js

@@ -0,0 +1,79 @@
+import { clamp, lerp } from '@flighthq/math';
+/** Interpolate between two snapshots into a live mutable `out`, the "tween over instances" for smooth
+ *  netcode/replay rendering between two fixed frames.
+ *
+ *  `t` is clamped to `[0, 1]`. For each numeric leaf present as a number in both `a` and `b`, `out`
+ *  receives `lerp(a, b, t)`. Every non-numeric leaf — strings, booleans, `null`/`undefined`, or a
+ *  slot that is a number in only one snapshot — snaps to the destination value from `b` (cloned so
+ *  `out` stays mutable and unaliased). Nested objects and arrays are walked recursively; arrays are
+ *  resized to `b`'s length and interpolated positionally.
+ *
+ *  With a `schema` (dot-separated paths from the root, array elements by index), only numeric leaves
+ *  whose path is listed interpolate; every other numeric leaf snaps to `b` — how a numeric id or
+ *  discrete count is kept from blending. Without a schema, all numeric leaves interpolate.
+ *
+ *  `out` may be a separate live object; it is read from `a`/`b` and written field by field, so it can
+ *  safely be the caller's render-state object.
+ */
+export function interpolateSnapshots(a, b, t, out, schema) {
+    if (a === null ||
+        typeof a !== 'object' ||
+        b === null ||
+        typeof b !== 'object' ||
+        out === null ||
+        typeof out !== 'object') {
+        return;
+    }
+    interpolateSnapshotsInto(out, a, b, clamp(t, 0, 1), schema, '');
+}
+// 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) {
+    const outRecord = out;
+    const aRecord = a;
+    const bRecord = b;
+    if (Array.isArray(b)) {
+        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;
+            continue;
+        }
+        if (aValue !== null &&
+            typeof aValue === 'object' &&
+            bValue !== null &&
+            typeof bValue === 'object' &&
+            Array.isArray(aValue) === Array.isArray(bValue)) {
+            const container = ensureSnapshotContainer(outRecord[key], Array.isArray(bValue));
+            outRecord[key] = container;
+            interpolateSnapshotsInto(container, aValue, bValue, t, schema, path);
+            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);
+}
+// 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.
+function ensureSnapshotContainer(existing, isArray) {
+    if (existing !== null && typeof existing === 'object' && Array.isArray(existing) === isArray) {
+        return existing;
+    }
+    return isArray ? [] : {};
+}
+// Snaps a non-interpolated value into `out`: primitives pass through; an object/array is deep-cloned
+// so `out` holds a fresh mutable copy rather than aliasing the frozen snapshot.
+function cloneSnapshotValue(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    return structuredClone(value);
+}
+//# sourceMappingURL=interpolateSnapshots.js.map

package/dist/interpolateSnapshots.js.map

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

package/dist/restoreSnapshot.d.ts

@@ -0,0 +1,16 @@
+import type { Snapshot } from '@flighthq/types';
+/** Restore `snapshot` back into the live mutable `target`, deep-assigning every field in place.
+ *
+ *  `target` keeps its own object identity — this mutates the caller's live state rather than
+ *  replacing it. Where `target` already holds a compatible nested object or array, that container is
+ *  reused and mutated in place (preserving its identity too); otherwise a fresh mutable clone of the
+ *  snapshot's subtree is assigned, so the restored state never aliases the frozen snapshot and stays
+ *  freely mutable.
+ *
+ *  Array handling: a target array is resized to the snapshot array's length — extra tail elements are
+ *  dropped, missing elements are added — then each element is restored positionally.
+ *
+ *  A top-level primitive snapshot has nothing to assign into a live reference and is a no-op.
+ */
+export declare function restoreSnapshot<T>(snapshot: Snapshot<T>, target: T): void;
+//# sourceMappingURL=restoreSnapshot.d.ts.map

package/dist/restoreSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restoreSnapshot.d.ts","sourceRoot":"","sources":["../src/restoreSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAKzE"}

package/dist/restoreSnapshot.js

@@ -0,0 +1,51 @@
+/** Restore `snapshot` back into the live mutable `target`, deep-assigning every field in place.
+ *
+ *  `target` keeps its own object identity — this mutates the caller's live state rather than
+ *  replacing it. Where `target` already holds a compatible nested object or array, that container is
+ *  reused and mutated in place (preserving its identity too); otherwise a fresh mutable clone of the
+ *  snapshot's subtree is assigned, so the restored state never aliases the frozen snapshot and stays
+ *  freely mutable.
+ *
+ *  Array handling: a target array is resized to the snapshot array's length — extra tail elements are
+ *  dropped, missing elements are added — then each element is restored positionally.
+ *
+ *  A top-level primitive snapshot has nothing to assign into a live reference and is a no-op.
+ */
+export function restoreSnapshot(snapshot, target) {
+    if (snapshot === null || typeof snapshot !== 'object' || target === null || typeof target !== 'object') {
+        return;
+    }
+    restoreSnapshotInto(target, snapshot);
+}
+// Deep-assigns every own key of `source` into `target`, recursing through compatible nested
+// containers and resizing arrays to match. Both are known to be objects/arrays here.
+function restoreSnapshotInto(target, source) {
+    if (Array.isArray(source)) {
+        const targetArray = target;
+        const sourceArray = source;
+        targetArray.length = sourceArray.length;
+        for (let index = 0; index < sourceArray.length; index += 1) {
+            targetArray[index] = restoreSnapshotValue(targetArray[index], sourceArray[index]);
+        }
+        return;
+    }
+    const targetObject = target;
+    const sourceObject = source;
+    for (const key of Object.keys(sourceObject)) {
+        targetObject[key] = restoreSnapshotValue(targetObject[key], sourceObject[key]);
+    }
+}
+// Resolves the value to store for one field: primitives pass through; an object/array reuses a
+// compatible mutable container in `targetValue` (mutated in place) or is cloned fresh and mutable.
+function restoreSnapshotValue(targetValue, sourceValue) {
+    if (sourceValue === null || typeof sourceValue !== 'object') {
+        return sourceValue;
+    }
+    const sourceIsArray = Array.isArray(sourceValue);
+    if (targetValue !== null && typeof targetValue === 'object' && Array.isArray(targetValue) === sourceIsArray) {
+        restoreSnapshotInto(targetValue, sourceValue);
+        return targetValue;
+    }
+    return structuredClone(sourceValue);
+}
+//# sourceMappingURL=restoreSnapshot.js.map

package/dist/restoreSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restoreSnapshot.js","sourceRoot":"","sources":["../src/restoreSnapshot.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAI,QAAqB,EAAE,MAAS;IACjE,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACvG,OAAO;IACT,CAAC;IACD,mBAAmB,CAAC,MAAgB,EAAE,QAAkB,CAAC,CAAC;AAC5D,CAAC;AAED,4FAA4F;AAC5F,qFAAqF;AACrF,SAAS,mBAAmB,CAAC,MAAc,EAAE,MAAc;IACzD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,WAAW,GAAG,MAAmB,CAAC;QACxC,MAAM,WAAW,GAAG,MAAmB,CAAC;QACxC,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;QACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC3D,WAAW,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO;IACT,CAAC;IACD,MAAM,YAAY,GAAG,MAAiC,CAAC;IACvD,MAAM,YAAY,GAAG,MAAiC,CAAC;IACvD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5C,YAAY,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,+FAA+F;AAC/F,mGAAmG;AACnG,SAAS,oBAAoB,CAAC,WAAoB,EAAE,WAAoB;IACtE,IAAI,WAAW,KAAK,IAAI,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC5D,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,WAAW,KAAK,IAAI,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,aAAa,EAAE,CAAC;QAC5G,mBAAmB,CAAC,WAAqB,EAAE,WAAqB,CAAC,CAAC;QAClE,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,eAAe,CAAC,WAAW,CAAC,CAAC;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/snapshot",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/math": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Immutable recoverable-state captures over plain data — captureSnapshot deep-clones and deep-freezes a state object, restoreSnapshot deep-assigns a snapshot back into live mutable state, interpolateSnapshots schema-aware lerps numeric leaves between two snapshots, and snapshotsEqual deep-compares; the primitive under save/undo/netcode/replay, deps types + math only",
+  "sideEffects": false
+}

package/src/captureSnapshot.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { captureSnapshot } from './captureSnapshot';
+
+describe('captureSnapshot', () => {
+  it('returns a deep-equal copy of the source', () => {
+    const source = { x: 1, nested: { y: 2 }, items: [3, 4] };
+    const snapshot = captureSnapshot(source);
+    expect(snapshot).toEqual(source);
+  });
+
+  it('deep-freezes every nested object and array', () => {
+    const snapshot = captureSnapshot({ x: 1, nested: { y: 2, points: [{ z: 3 }] } });
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.nested)).toBe(true);
+    expect(Object.isFrozen(snapshot.nested.points)).toBe(true);
+    expect(Object.isFrozen(snapshot.nested.points[0])).toBe(true);
+  });
+
+  it('is unaffected by mutating the source after capture', () => {
+    const source = { x: 1, nested: { y: 2 }, items: [3, 4] };
+    const snapshot = captureSnapshot(source);
+    source.x = 99;
+    source.nested.y = 99;
+    source.items.push(5);
+    expect(snapshot.x).toBe(1);
+    expect(snapshot.nested.y).toBe(2);
+    expect(snapshot.items).toEqual([3, 4]);
+  });
+
+  it('copies nested arrays rather than sharing the reference', () => {
+    const source = { items: [1, 2, 3] };
+    const snapshot = captureSnapshot(source);
+    expect(snapshot.items).not.toBe(source.items);
+    expect(snapshot.items).toEqual([1, 2, 3]);
+  });
+
+  it('captures an empty object', () => {
+    const snapshot = captureSnapshot({});
+    expect(snapshot).toEqual({});
+    expect(Object.isFrozen(snapshot)).toBe(true);
+  });
+
+  it('captures null and undefined leaf fields', () => {
+    const snapshot = captureSnapshot({ a: null, b: undefined, c: 1 });
+    expect(snapshot.a).toBeNull();
+    expect(snapshot.b).toBeUndefined();
+    expect(snapshot.c).toBe(1);
+  });
+});

package/src/equalsSnapshot.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { captureSnapshot } from './captureSnapshot';
+import { equalsSnapshot } from './equalsSnapshot';
+
+describe('equalsSnapshot', () => {
+  it('is true for deep-equal snapshots', () => {
+    const a = captureSnapshot({ x: 1, nested: { y: 2 }, items: [3, 4] });
+    const b = captureSnapshot({ x: 1, nested: { y: 2 }, items: [3, 4] });
+    expect(equalsSnapshot(a, b)).toBe(true);
+  });
+
+  it('is false for a differing leaf value', () => {
+    const a = captureSnapshot({ x: 1, nested: { y: 2 } });
+    const b = captureSnapshot({ x: 1, nested: { y: 3 } });
+    expect(equalsSnapshot(a, b)).toBe(false);
+  });
+
+  it('is false for a differing shape', () => {
+    const a = captureSnapshot({ x: 1 } as Record<string, number>);
+    const b = captureSnapshot({ x: 1, y: 2 } as Record<string, number>);
+    expect(equalsSnapshot(a, b)).toBe(false);
+  });
+
+  it('is false for arrays of differing length', () => {
+    const a = captureSnapshot({ items: [1, 2] });
+    const b = captureSnapshot({ items: [1, 2, 3] });
+    expect(equalsSnapshot(a, b)).toBe(false);
+  });
+
+  it('is true for two empty objects', () => {
+    expect(equalsSnapshot(captureSnapshot({}), captureSnapshot({}))).toBe(true);
+  });
+
+  it('distinguishes null from a value at the same key', () => {
+    const a = captureSnapshot({ tag: null as number | null });
+    const b = captureSnapshot({ tag: 0 as number | null });
+    expect(equalsSnapshot(a, b)).toBe(false);
+  });
+});

package/src/interpolateSnapshots.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { captureSnapshot } from './captureSnapshot';
+import { interpolateSnapshots } from './interpolateSnapshots';
+
+describe('interpolateSnapshots', () => {
+  it('lerps numerics and snaps the string at t=0.5', () => {
+    const a = captureSnapshot({ x: 0, y: 10, name: 'a' });
+    const b = captureSnapshot({ x: 10, y: 0, name: 'b' });
+    const out = { x: 0, y: 0, name: '' };
+    interpolateSnapshots(a, b, 0.5, out);
+    expect(out).toEqual({ x: 5, y: 5, name: 'b' });
+  });
+
+  it('returns a numerics at t=0 and b numerics at t=1', () => {
+    const a = captureSnapshot({ x: 0, y: 10 });
+    const b = captureSnapshot({ x: 10, y: 0 });
+    const atStart = { x: -1, y: -1 };
+    const atEnd = { x: -1, y: -1 };
+    interpolateSnapshots(a, b, 0, atStart);
+    interpolateSnapshots(a, b, 1, atEnd);
+    expect(atStart).toEqual({ x: 0, y: 10 });
+    expect(atEnd).toEqual({ x: 10, y: 0 });
+  });
+
+  it('interpolates only schema-listed paths and snaps the rest to b', () => {
+    const a = captureSnapshot({ x: 0, y: 10 });
+    const b = captureSnapshot({ x: 10, y: 0 });
+    const out = { x: 0, y: 0 };
+    interpolateSnapshots(a, b, 0.5, out, ['x']);
+    expect(out).toEqual({ x: 5, y: 0 });
+  });
+
+  it('lerps nested numeric fields', () => {
+    const a = captureSnapshot({ pos: { x: 0, y: 0 } });
+    const b = captureSnapshot({ pos: { x: 100, y: 40 } });
+    const out = { pos: { x: 0, y: 0 } };
+    interpolateSnapshots(a, b, 0.25, out);
+    expect(out.pos).toEqual({ x: 25, y: 10 });
+  });
+
+  it('clamps t below 0 and above 1', () => {
+    const a = captureSnapshot({ x: 0 });
+    const b = captureSnapshot({ x: 10 });
+    const under = { x: -1 };
+    const over = { x: -1 };
+    interpolateSnapshots(a, b, -5, under);
+    interpolateSnapshots(a, b, 5, over);
+    expect(under.x).toBe(0);
+    expect(over.x).toBe(10);
+  });
+
+  it('lerps arrays of numbers element-wise', () => {
+    const a = captureSnapshot({ points: [0, 100] });
+    const b = captureSnapshot({ points: [10, 0] });
+    const out = { points: [0, 0] };
+    interpolateSnapshots(a, b, 0.5, out);
+    expect(out.points).toEqual([5, 50]);
+  });
+
+  it('snaps a null field to b', () => {
+    const a = captureSnapshot({ value: 1, tag: null as number | null });
+    const b = captureSnapshot({ value: 3, tag: null as number | null });
+    const out = { value: 0, tag: 7 as number | null };
+    interpolateSnapshots(a, b, 0.5, out);
+    expect(out.value).toBe(2);
+    expect(out.tag).toBeNull();
+  });
+});

package/src/restoreSnapshot.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { captureSnapshot } from './captureSnapshot';
+import { restoreSnapshot } from './restoreSnapshot';
+
+describe('restoreSnapshot', () => {
+  it('writes a snapshot back into a live target', () => {
+    const snapshot = captureSnapshot({ x: 1, y: 2 });
+    const target = { x: 0, y: 0 };
+    restoreSnapshot(snapshot, target);
+    expect(target).toEqual({ x: 1, y: 2 });
+  });
+
+  it('restores nested objects and arrays', () => {
+    const snapshot = captureSnapshot({ nested: { a: 1 }, items: [1, 2, 3] });
+    const target = { nested: { a: 0 }, items: [0] };
+    restoreSnapshot(snapshot, target);
+    expect(target.nested).toEqual({ a: 1 });
+    expect(target.items).toEqual([1, 2, 3]);
+  });
+
+  it('keeps the target object identity, mutating in place', () => {
+    const snapshot = captureSnapshot({ x: 1 });
+    const target = { x: 0 };
+    const before = target;
+    restoreSnapshot(snapshot, target);
+    expect(target).toBe(before);
+  });
+
+  it('reuses a compatible nested container rather than replacing it', () => {
+    const snapshot = captureSnapshot({ nested: { a: 1 } });
+    const target = { nested: { a: 0 } };
+    const nestedBefore = target.nested;
+    restoreSnapshot(snapshot, target);
+    expect(target.nested).toBe(nestedBefore);
+    expect(target.nested.a).toBe(1);
+  });
+
+  it('leaves the restored target mutable and unaliased from the frozen snapshot', () => {
+    const snapshot = captureSnapshot({ nested: { a: 1 } });
+    const target = { nested: { a: 0 } } as { nested: { a: number } };
+    restoreSnapshot(snapshot, target);
+    target.nested.a = 42;
+    expect(target.nested.a).toBe(42);
+    expect(snapshot.nested.a).toBe(1);
+  });
+
+  it('resizes the target array to the snapshot array length', () => {
+    const snapshot = captureSnapshot({ items: [1, 2] });
+    const target = { items: [9, 9, 9, 9] };
+    restoreSnapshot(snapshot, target);
+    expect(target.items).toEqual([1, 2]);
+  });
+});