@unrulysystems/native-motion-core 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @unrulysystems/native-motion-core
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Initial alpha prerelease: the M3-era public surface (layout, presence, drag, gestures, variants,
+  orchestration, value types) with the cross-engine conformance suite published alongside the
+  runtime packages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unruly Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @unrulysystems/native-motion-core
+
+The host-agnostic heart of the system (SPEC-CORE): a deterministic motion graph plus every pure
+animation subsystem, with **zero host dependencies** — nothing here may import react,
+react-native, reanimated, gesture-handler, or motion. That law is structural: an oxlint
+`no-restricted-imports` rule over `src/**` (root `.oxlintrc.json`, run by `nub run lint`) fails on
+ANY non-relative import in non-test source (REQ-CORE-003). The native runtime, the web shim, and the conformance harness all consume this
+one module.
+
+## Surface map (`src/index.ts`)
+
+| Area                      | Role                                                                                                                          | Key files                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| graph / clock / scheduler | The deterministic motion graph: injectable clock + scheduler, motion values with clock-timestamped velocity                   | `graph.ts`, `clock.ts`, `types.ts`, `motion-value.ts` (internal) |
+| spring                    | Analytic closed-form scalar spring solver                                                                                     | `spring.ts`                                                      |
+| transition                | User transition config → concrete physics; the retarget/interruption seam (`retargetSpring` seeds from live state)            | `transition.ts`                                                  |
+| timing                    | Duration + easing tween generator                                                                                             | `timing.ts`                                                      |
+| value-types               | Typed parsers + gamma-aware mixers (numeric/unit, color, complex), unified `mix()`                                            | `value-types/`                                                   |
+| subset                    | The frozen universal-subset registry — the single source of truth every engine's prop surface derives from                    | `subset/`                                                        |
+| component                 | The declarative public API contract: `Target`/`Transition` (seconds), loud-fail `validateTarget`, pure `resolveTarget`        | `component/`                                                     |
+| driver                    | The host-agnostic `Driver` seam + pure per-frame `stepProp`, reference driver, prop tiers                                     | `driver/`                                                        |
+| presence                  | Exit-lifecycle state machine + controller (present → exiting → removed, settle-coupled)                                       | `presence/`                                                      |
+| gesture                   | Pure gesture math (projection, snap, elastic, velocity normalization) + the begin→active→end/cancel session                   | `gesture/`                                                       |
+| layout                    | Pure FLIP projection (`invert`/`projectAtProgress`, top-left anchored Transform) + measurement lifecycle + projection session | `layout/`                                                        |
+
+Naming note: `src/transition.ts` (spring-config resolution, `resolveSpring`) and
+`src/component/transition.ts` (public seconds→ms boundary, `toSpringConfig`) are different
+seams that share a basename — read the directory.
+
+## Verification
+
+- 460 colocated unit tests (39 files, `src/**` plus the `scripts/**` gate suites), all
+  deterministic under `ManualClock`/`ManualScheduler`; green under Vitest.
+- Golden files under `src/__goldens__/` pin the pinned-motion oracle's outputs; they are
+  GENERATED by `packages/conformance/scripts/gen-*-goldens.mjs` (core itself must never import
+  motion-dom) and regenerated only on an intentional oracle bump.
+- Worklet tagging is manifest-driven (`scripts/worklet-tagging-manifest.mjs`, the single source):
+  `scripts/tag-worklet-dist.mjs` post-build tags the four FILE-level crossing modules
+  (`transition`, `spring`, `timing`, `driver/step`), 19 FUNCTION-level directives on the dual-use
+  modules (`value-types/color`, `layout/*`), and the tagged `worklet-layout/` runtime copies —
+  an un-tagged crossing fails only live on device (0.5.x SIGSEGV / 0.10.x Remote-Function throw),
+  so the lists are closed over transitive callees and verified fail-closed by
+  `scripts/check-worklet-banners.mjs` (in `nub run check`) and per-artifact by
+  `scripts/check-bundle-worklets.mjs` (run by `apps/mobile/scripts/proof-build.sh`).
+
+```bash
+cd packages/core && bunx vitest run
+```

package/dist/clock.cjs

@@ -0,0 +1,71 @@
+"use strict";
+// Deterministic clock + scheduler for the injectable time seam (REQ-CLOCK-001, REQ-VERIFY-001).
+// These are real implementations, not stubs: the whole graph is made deterministic under test by
+// advancing time in explicit increments and pumping frames. Exported so the conformance runner
+// (M1b) and any consumer's tests reuse them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManualScheduler = exports.ManualClock = void 0;
+/** A clock whose time only moves when `advance` is called. */
+class ManualClock {
+    #t;
+    constructor(start = 0) {
+        this.#t = start;
+    }
+    now() {
+        return this.#t;
+    }
+    /** Move time forward by `ms`. Negative deltas are a programming error. */
+    advance(ms) {
+        if (ms < 0)
+            throw new Error(`ManualClock.advance: negative delta ${ms}`);
+        this.#t += ms;
+    }
+}
+exports.ManualClock = ManualClock;
+/**
+ * A scheduler whose frames only fire when `frame` is called. Advancing the clock and running the
+ * registered per-frame steps are coupled here so a test drives wall-time and frames in one call,
+ * keeping the sampled trajectory reproducible.
+ */
+class ManualScheduler {
+    #clock;
+    #steps = new Set();
+    // Command-edge-grown reusable snapshot (REQ-DRIVER-021, packet §6 ordinary local-JS repair):
+    // capacity extends at the registration edge (onFrame); frame() refills it by indexed writes and
+    // drains by index — no fresh Array.from snapshot per local frame.
+    #stepSnapshot = [];
+    #snapshotCount = 0;
+    constructor(clock) {
+        this.#clock = clock;
+    }
+    onFrame(step) {
+        this.#steps.add(step);
+        // Registration edge: grow the reusable snapshot's capacity here, never mid-frame.
+        if (this.#stepSnapshot.length < this.#steps.size)
+            this.#stepSnapshot.length = this.#steps.size;
+        return () => {
+            this.#steps.delete(step);
+        };
+    }
+    /** Advance the clock by `dtMs` and run one frame step for every registered listener. */
+    frame(dtMs) {
+        this.#clock.advance(dtMs);
+        // Snapshot into the reusable buffer so a step that unregisters mid-frame does not perturb
+        // this iteration. forEach walks the Set's internal slots — no iterator object per frame.
+        this.#snapshotCount = 0;
+        this.#steps.forEach(this.#collectStep);
+        const count = this.#snapshotCount;
+        for (let i = 0; i < count; i++)
+            this.#stepSnapshot[i](dtMs);
+    }
+    #collectStep = (step) => {
+        this.#stepSnapshot[this.#snapshotCount] = step;
+        this.#snapshotCount += 1;
+    };
+    /** Convenience: run `count` frames of `dtMs` each. */
+    frames(count, dtMs) {
+        for (let i = 0; i < count; i++)
+            this.frame(dtMs);
+    }
+}
+exports.ManualScheduler = ManualScheduler;

package/dist/clock.d.cts

@@ -0,0 +1,23 @@
+import type { Clock, Scheduler } from "./types.cjs";
+/** A clock whose time only moves when `advance` is called. */
+export declare class ManualClock implements Clock {
+    #private;
+    constructor(start?: number);
+    now(): number;
+    /** Move time forward by `ms`. Negative deltas are a programming error. */
+    advance(ms: number): void;
+}
+/**
+ * A scheduler whose frames only fire when `frame` is called. Advancing the clock and running the
+ * registered per-frame steps are coupled here so a test drives wall-time and frames in one call,
+ * keeping the sampled trajectory reproducible.
+ */
+export declare class ManualScheduler implements Scheduler {
+    #private;
+    constructor(clock: ManualClock);
+    onFrame(step: (dtMs: number) => void): () => void;
+    /** Advance the clock by `dtMs` and run one frame step for every registered listener. */
+    frame(dtMs: number): void;
+    /** Convenience: run `count` frames of `dtMs` each. */
+    frames(count: number, dtMs: number): void;
+}

package/dist/clock.d.ts

@@ -0,0 +1,23 @@
+import type { Clock, Scheduler } from "./types.js";
+/** A clock whose time only moves when `advance` is called. */
+export declare class ManualClock implements Clock {
+    #private;
+    constructor(start?: number);
+    now(): number;
+    /** Move time forward by `ms`. Negative deltas are a programming error. */
+    advance(ms: number): void;
+}
+/**
+ * A scheduler whose frames only fire when `frame` is called. Advancing the clock and running the
+ * registered per-frame steps are coupled here so a test drives wall-time and frames in one call,
+ * keeping the sampled trajectory reproducible.
+ */
+export declare class ManualScheduler implements Scheduler {
+    #private;
+    constructor(clock: ManualClock);
+    onFrame(step: (dtMs: number) => void): () => void;
+    /** Advance the clock by `dtMs` and run one frame step for every registered listener. */
+    frame(dtMs: number): void;
+    /** Convenience: run `count` frames of `dtMs` each. */
+    frames(count: number, dtMs: number): void;
+}

package/dist/clock.js

@@ -0,0 +1,66 @@
+// Deterministic clock + scheduler for the injectable time seam (REQ-CLOCK-001, REQ-VERIFY-001).
+// These are real implementations, not stubs: the whole graph is made deterministic under test by
+// advancing time in explicit increments and pumping frames. Exported so the conformance runner
+// (M1b) and any consumer's tests reuse them.
+/** A clock whose time only moves when `advance` is called. */
+export class ManualClock {
+    #t;
+    constructor(start = 0) {
+        this.#t = start;
+    }
+    now() {
+        return this.#t;
+    }
+    /** Move time forward by `ms`. Negative deltas are a programming error. */
+    advance(ms) {
+        if (ms < 0)
+            throw new Error(`ManualClock.advance: negative delta ${ms}`);
+        this.#t += ms;
+    }
+}
+/**
+ * A scheduler whose frames only fire when `frame` is called. Advancing the clock and running the
+ * registered per-frame steps are coupled here so a test drives wall-time and frames in one call,
+ * keeping the sampled trajectory reproducible.
+ */
+export class ManualScheduler {
+    #clock;
+    #steps = new Set();
+    // Command-edge-grown reusable snapshot (REQ-DRIVER-021, packet §6 ordinary local-JS repair):
+    // capacity extends at the registration edge (onFrame); frame() refills it by indexed writes and
+    // drains by index — no fresh Array.from snapshot per local frame.
+    #stepSnapshot = [];
+    #snapshotCount = 0;
+    constructor(clock) {
+        this.#clock = clock;
+    }
+    onFrame(step) {
+        this.#steps.add(step);
+        // Registration edge: grow the reusable snapshot's capacity here, never mid-frame.
+        if (this.#stepSnapshot.length < this.#steps.size)
+            this.#stepSnapshot.length = this.#steps.size;
+        return () => {
+            this.#steps.delete(step);
+        };
+    }
+    /** Advance the clock by `dtMs` and run one frame step for every registered listener. */
+    frame(dtMs) {
+        this.#clock.advance(dtMs);
+        // Snapshot into the reusable buffer so a step that unregisters mid-frame does not perturb
+        // this iteration. forEach walks the Set's internal slots — no iterator object per frame.
+        this.#snapshotCount = 0;
+        this.#steps.forEach(this.#collectStep);
+        const count = this.#snapshotCount;
+        for (let i = 0; i < count; i++)
+            this.#stepSnapshot[i](dtMs);
+    }
+    #collectStep = (step) => {
+        this.#stepSnapshot[this.#snapshotCount] = step;
+        this.#snapshotCount += 1;
+    };
+    /** Convenience: run `count` frames of `dtMs` each. */
+    frames(count, dtMs) {
+        for (let i = 0; i < count; i++)
+            this.frame(dtMs);
+    }
+}

package/dist/collect-reads.cjs

@@ -0,0 +1,68 @@
+"use strict";
+// Dependency collection for reactive derived computes (REQ-API-027's `useTransform(() => expr)`
+// form — the same actual-reads trick the pinned oracle uses). A collection frame records every
+// MotionValue whose `get()` runs inside `compute`; outside a frame the report is a single null
+// check, so the hot read path stays allocation- and branch-cheap. Frames nest (the previous
+// collector is restored on exit) and always close, even when the compute throws — a stuck
+// collector would silently attribute unrelated reads to the wrong derived.
+//
+// Frame-path repair (REQ-DRIVER-021, packet §6 ordinary local-JS bookkeeping): an active
+// collector dedupes into prefilled indexed slots — no Set growth per read in-frame. The public
+// ReadonlySet view is materialized once when the collection closes (a command/render edge),
+// never per read.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActiveMotionValueReadCollector = void 0;
+exports.reportMotionValueRead = reportMotionValueRead;
+exports.collectMotionValueReads = collectMotionValueReads;
+/**
+ * The active collection frame. Reads dedupe by an indexed scan of the prefilled slot list —
+ * the read count per compute is tiny, so the linear membership check beats a Set's per-add
+ * growth on the frame path.
+ */
+class ActiveMotionValueReadCollector {
+    // Prefilled-slot list: capacity grows only to the compute's read high-water mark (below), then
+    // is reused — never a fresh array per read.
+    #slots = [];
+    #count = 0;
+    /** @internal Record one read, deduping into the prefilled slots. Called only via reportMotionValueRead. */
+    recordUniqueIntoPrefilledSlots(value) {
+        const slots = this.#slots;
+        const count = this.#count;
+        for (let i = 0; i < count; i++) {
+            if (slots[i] === value)
+                return;
+        }
+        if (count === slots.length)
+            slots.length = count === 0 ? 8 : count * 2;
+        slots[count] = value;
+        this.#count = count + 1;
+    }
+    /**
+     * Materialize the public ReadonlySet view ONCE at collection close (the command/render edge
+     * that opened the frame) — the repair moves every per-read Set.add off the read path.
+     */
+    sealReads() {
+        const reads = new Set();
+        for (let i = 0; i < this.#count; i++)
+            reads.add(this.#slots[i]);
+        return reads;
+    }
+}
+exports.ActiveMotionValueReadCollector = ActiveMotionValueReadCollector;
+let activeCollector = null;
+/** @internal Called by MotionValue implementations from `get()`. */
+function reportMotionValueRead(value) {
+    if (activeCollector !== null)
+        activeCollector.recordUniqueIntoPrefilledSlots(value);
+}
+function collectMotionValueReads(compute) {
+    const previous = activeCollector;
+    const collector = new ActiveMotionValueReadCollector();
+    activeCollector = collector;
+    try {
+        return { result: compute(), reads: collector.sealReads() };
+    }
+    finally {
+        activeCollector = previous;
+    }
+}

package/dist/collect-reads.d.cts

@@ -0,0 +1,23 @@
+import type { MotionValue } from "./types.cjs";
+/**
+ * The active collection frame. Reads dedupe by an indexed scan of the prefilled slot list —
+ * the read count per compute is tiny, so the linear membership check beats a Set's per-add
+ * growth on the frame path.
+ */
+export declare class ActiveMotionValueReadCollector {
+    #private;
+    /** @internal Record one read, deduping into the prefilled slots. Called only via reportMotionValueRead. */
+    recordUniqueIntoPrefilledSlots(value: MotionValue<unknown>): void;
+    /**
+     * Materialize the public ReadonlySet view ONCE at collection close (the command/render edge
+     * that opened the frame) — the repair moves every per-read Set.add off the read path.
+     */
+    sealReads(): ReadonlySet<MotionValue<unknown>>;
+}
+/** @internal Called by MotionValue implementations from `get()`. */
+export declare function reportMotionValueRead(value: MotionValue<unknown>): void;
+export interface CollectedReads<T> {
+    readonly result: T;
+    readonly reads: ReadonlySet<MotionValue<unknown>>;
+}
+export declare function collectMotionValueReads<T>(compute: () => T): CollectedReads<T>;

package/dist/collect-reads.d.ts

@@ -0,0 +1,23 @@
+import type { MotionValue } from "./types.js";
+/**
+ * The active collection frame. Reads dedupe by an indexed scan of the prefilled slot list —
+ * the read count per compute is tiny, so the linear membership check beats a Set's per-add
+ * growth on the frame path.
+ */
+export declare class ActiveMotionValueReadCollector {
+    #private;
+    /** @internal Record one read, deduping into the prefilled slots. Called only via reportMotionValueRead. */
+    recordUniqueIntoPrefilledSlots(value: MotionValue<unknown>): void;
+    /**
+     * Materialize the public ReadonlySet view ONCE at collection close (the command/render edge
+     * that opened the frame) — the repair moves every per-read Set.add off the read path.
+     */
+    sealReads(): ReadonlySet<MotionValue<unknown>>;
+}
+/** @internal Called by MotionValue implementations from `get()`. */
+export declare function reportMotionValueRead(value: MotionValue<unknown>): void;
+export interface CollectedReads<T> {
+    readonly result: T;
+    readonly reads: ReadonlySet<MotionValue<unknown>>;
+}
+export declare function collectMotionValueReads<T>(compute: () => T): CollectedReads<T>;

package/dist/collect-reads.js

@@ -0,0 +1,62 @@
+// Dependency collection for reactive derived computes (REQ-API-027's `useTransform(() => expr)`
+// form — the same actual-reads trick the pinned oracle uses). A collection frame records every
+// MotionValue whose `get()` runs inside `compute`; outside a frame the report is a single null
+// check, so the hot read path stays allocation- and branch-cheap. Frames nest (the previous
+// collector is restored on exit) and always close, even when the compute throws — a stuck
+// collector would silently attribute unrelated reads to the wrong derived.
+//
+// Frame-path repair (REQ-DRIVER-021, packet §6 ordinary local-JS bookkeeping): an active
+// collector dedupes into prefilled indexed slots — no Set growth per read in-frame. The public
+// ReadonlySet view is materialized once when the collection closes (a command/render edge),
+// never per read.
+/**
+ * The active collection frame. Reads dedupe by an indexed scan of the prefilled slot list —
+ * the read count per compute is tiny, so the linear membership check beats a Set's per-add
+ * growth on the frame path.
+ */
+export class ActiveMotionValueReadCollector {
+    // Prefilled-slot list: capacity grows only to the compute's read high-water mark (below), then
+    // is reused — never a fresh array per read.
+    #slots = [];
+    #count = 0;
+    /** @internal Record one read, deduping into the prefilled slots. Called only via reportMotionValueRead. */
+    recordUniqueIntoPrefilledSlots(value) {
+        const slots = this.#slots;
+        const count = this.#count;
+        for (let i = 0; i < count; i++) {
+            if (slots[i] === value)
+                return;
+        }
+        if (count === slots.length)
+            slots.length = count === 0 ? 8 : count * 2;
+        slots[count] = value;
+        this.#count = count + 1;
+    }
+    /**
+     * Materialize the public ReadonlySet view ONCE at collection close (the command/render edge
+     * that opened the frame) — the repair moves every per-read Set.add off the read path.
+     */
+    sealReads() {
+        const reads = new Set();
+        for (let i = 0; i < this.#count; i++)
+            reads.add(this.#slots[i]);
+        return reads;
+    }
+}
+let activeCollector = null;
+/** @internal Called by MotionValue implementations from `get()`. */
+export function reportMotionValueRead(value) {
+    if (activeCollector !== null)
+        activeCollector.recordUniqueIntoPrefilledSlots(value);
+}
+export function collectMotionValueReads(compute) {
+    const previous = activeCollector;
+    const collector = new ActiveMotionValueReadCollector();
+    activeCollector = collector;
+    try {
+        return { result: compute(), reads: collector.sealReads() };
+    }
+    finally {
+        activeCollector = previous;
+    }
+}

package/dist/component/boundedArray.cjs

@@ -0,0 +1,74 @@
+"use strict";
+// A hostile array can lie about `length`, grow during iterator traversal, or expose a length that
+// JavaScript cannot allocate. Every public/supplying boundary therefore captures the cardinality ONCE
+// before it allocates or reads an index. Sparse slots stay sparse so the owning schema can name them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CAPTURED_ARRAY_LENGTH = void 0;
+exports.capturedArrayDescription = capturedArrayDescription;
+exports.captureBoundedArray = captureBoundedArray;
+exports.captureBoundedCubicBezier = captureBoundedCubicBezier;
+exports.MAX_CAPTURED_ARRAY_LENGTH = 100_000;
+function hasSafeArrayLength(value) {
+    return (typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= exports.MAX_CAPTURED_ARRAY_LENGTH);
+}
+/** A safe error value that never retains a hostile array/proxy for a formatter to reread. */
+function capturedArrayDescription(capture) {
+    if (capture.kind === 'not-array')
+        return 'a non-array value';
+    if (capture.kind === 'invalid-length') {
+        const { length } = capture;
+        const rendered = length === null ||
+            typeof length === 'undefined' ||
+            typeof length === 'boolean' ||
+            typeof length === 'number' ||
+            typeof length === 'bigint' ||
+            typeof length === 'string' ||
+            typeof length === 'symbol'
+            ? String(length)
+            : `a ${typeof length} value`;
+        return `an array reporting length ${rendered}`;
+    }
+    return `an array (length ${capture.values.length})`;
+}
+/**
+ * Capture a real array's bounded shape without iteration. Length is read exactly once, then each OWN
+ * member is read exactly once. Dependency faults from `length`, `hasOwn`, or an index are intentionally
+ * unguarded so their identity survives; malformed cardinality is represented safely for the caller's
+ * typed refusal channel.
+ */
+function captureBoundedArray(value) {
+    if (!Array.isArray(value))
+        return { kind: 'not-array' };
+    const length = value.length;
+    if (!hasSafeArrayLength(length))
+        return { kind: 'invalid-length', length };
+    const captured = [];
+    captured.length = length;
+    for (let index = 0; index < length; index++) {
+        if (Object.hasOwn(value, index))
+            captured[index] = value[index];
+    }
+    return { kind: 'captured', values: Object.freeze(captured) };
+}
+/**
+ * Capture the only nested timing-array shape the legal schema admits: a four-coordinate
+ * cubic-bezier tuple. Its cardinality is checked before reading any member, so malformed
+ * nested arrays cannot turn an outer easing list into quadratic work.
+ */
+function captureBoundedCubicBezier(value) {
+    if (!Array.isArray(value))
+        return { kind: 'not-array' };
+    const length = value.length;
+    if (!hasSafeArrayLength(length) || length !== 4)
+        return { kind: 'invalid-length', length };
+    const captured = [];
+    captured.length = 4;
+    for (let index = 0; index < 4; index++) {
+        if (Object.hasOwn(value, index))
+            captured[index] = value[index];
+    }
+    return { kind: 'captured', values: Object.freeze(captured) };
+}

package/dist/component/boundedArray.d.cts

@@ -0,0 +1,25 @@
+export declare const MAX_CAPTURED_ARRAY_LENGTH = 100000;
+export type BoundedArrayCapture = {
+    readonly kind: 'not-array';
+} | {
+    readonly kind: 'invalid-length';
+    readonly length: unknown;
+} | {
+    readonly kind: 'captured';
+    readonly values: readonly unknown[];
+};
+/** A safe error value that never retains a hostile array/proxy for a formatter to reread. */
+export declare function capturedArrayDescription(capture: BoundedArrayCapture): string;
+/**
+ * Capture a real array's bounded shape without iteration. Length is read exactly once, then each OWN
+ * member is read exactly once. Dependency faults from `length`, `hasOwn`, or an index are intentionally
+ * unguarded so their identity survives; malformed cardinality is represented safely for the caller's
+ * typed refusal channel.
+ */
+export declare function captureBoundedArray(value: unknown): BoundedArrayCapture;
+/**
+ * Capture the only nested timing-array shape the legal schema admits: a four-coordinate
+ * cubic-bezier tuple. Its cardinality is checked before reading any member, so malformed
+ * nested arrays cannot turn an outer easing list into quadratic work.
+ */
+export declare function captureBoundedCubicBezier(value: unknown): BoundedArrayCapture;

package/dist/component/boundedArray.d.ts

@@ -0,0 +1,25 @@
+export declare const MAX_CAPTURED_ARRAY_LENGTH = 100000;
+export type BoundedArrayCapture = {
+    readonly kind: 'not-array';
+} | {
+    readonly kind: 'invalid-length';
+    readonly length: unknown;
+} | {
+    readonly kind: 'captured';
+    readonly values: readonly unknown[];
+};
+/** A safe error value that never retains a hostile array/proxy for a formatter to reread. */
+export declare function capturedArrayDescription(capture: BoundedArrayCapture): string;
+/**
+ * Capture a real array's bounded shape without iteration. Length is read exactly once, then each OWN
+ * member is read exactly once. Dependency faults from `length`, `hasOwn`, or an index are intentionally
+ * unguarded so their identity survives; malformed cardinality is represented safely for the caller's
+ * typed refusal channel.
+ */
+export declare function captureBoundedArray(value: unknown): BoundedArrayCapture;
+/**
+ * Capture the only nested timing-array shape the legal schema admits: a four-coordinate
+ * cubic-bezier tuple. Its cardinality is checked before reading any member, so malformed
+ * nested arrays cannot turn an outer easing list into quadratic work.
+ */
+export declare function captureBoundedCubicBezier(value: unknown): BoundedArrayCapture;

package/dist/component/boundedArray.js

@@ -0,0 +1,68 @@
+// A hostile array can lie about `length`, grow during iterator traversal, or expose a length that
+// JavaScript cannot allocate. Every public/supplying boundary therefore captures the cardinality ONCE
+// before it allocates or reads an index. Sparse slots stay sparse so the owning schema can name them.
+export const MAX_CAPTURED_ARRAY_LENGTH = 100_000;
+function hasSafeArrayLength(value) {
+    return (typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= MAX_CAPTURED_ARRAY_LENGTH);
+}
+/** A safe error value that never retains a hostile array/proxy for a formatter to reread. */
+export function capturedArrayDescription(capture) {
+    if (capture.kind === 'not-array')
+        return 'a non-array value';
+    if (capture.kind === 'invalid-length') {
+        const { length } = capture;
+        const rendered = length === null ||
+            typeof length === 'undefined' ||
+            typeof length === 'boolean' ||
+            typeof length === 'number' ||
+            typeof length === 'bigint' ||
+            typeof length === 'string' ||
+            typeof length === 'symbol'
+            ? String(length)
+            : `a ${typeof length} value`;
+        return `an array reporting length ${rendered}`;
+    }
+    return `an array (length ${capture.values.length})`;
+}
+/**
+ * Capture a real array's bounded shape without iteration. Length is read exactly once, then each OWN
+ * member is read exactly once. Dependency faults from `length`, `hasOwn`, or an index are intentionally
+ * unguarded so their identity survives; malformed cardinality is represented safely for the caller's
+ * typed refusal channel.
+ */
+export function captureBoundedArray(value) {
+    if (!Array.isArray(value))
+        return { kind: 'not-array' };
+    const length = value.length;
+    if (!hasSafeArrayLength(length))
+        return { kind: 'invalid-length', length };
+    const captured = [];
+    captured.length = length;
+    for (let index = 0; index < length; index++) {
+        if (Object.hasOwn(value, index))
+            captured[index] = value[index];
+    }
+    return { kind: 'captured', values: Object.freeze(captured) };
+}
+/**
+ * Capture the only nested timing-array shape the legal schema admits: a four-coordinate
+ * cubic-bezier tuple. Its cardinality is checked before reading any member, so malformed
+ * nested arrays cannot turn an outer easing list into quadratic work.
+ */
+export function captureBoundedCubicBezier(value) {
+    if (!Array.isArray(value))
+        return { kind: 'not-array' };
+    const length = value.length;
+    if (!hasSafeArrayLength(length) || length !== 4)
+        return { kind: 'invalid-length', length };
+    const captured = [];
+    captured.length = 4;
+    for (let index = 0; index < 4; index++) {
+        if (Object.hasOwn(value, index))
+            captured[index] = value[index];
+    }
+    return { kind: 'captured', values: Object.freeze(captured) };
+}