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

package/dist/layout/identity.js

@@ -0,0 +1,698 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Layout identity registry (specs/L2-BUILD-PACKET.md) — the ratified shared layout-identity seam
+// (BRIEF Decisions 2026-07-06). Pairs LAYOUT geometry with PRESENCE-owned lifetimes without owning
+// either: per `layoutId` a HOLDER STACK in mount order plus ONE shared flight (the existing
+// projection session — reused, not reimplemented), which every holder reads RELATIVE TO ITS OWN
+// layout rect (both elements coincide visually mid-flight; no reparenting anywhere,
+// REQ-LAYOUT-015). Host-agnostic and deterministic under the fake clock; within-screen only
+// (REQ-LAYOUT-003).
+//
+// Modeling notes:
+// - The flight is a per-id `createProjectionSession`; holders derive their transforms from the
+//   SHARED visual rect via `invert(visual, ownLayout)` — the lead's math and the trailing's math
+//   are the same function over different layout rects, so coincidence holds by construction.
+// - The crossfade rides ONE scalar on the [0, 100] internal progress convention (REQ-SPRING-013,
+//   the same convention L1 colors use), driven through the same graph and spring config as the
+//   rect flight: lead opacity = clamp01(s / 100), the flight's departure partner = 1 − that.
+//   Opacity CLAMPS on read (spring overshoot past 100 must not produce out-of-range opacity).
+// - Per-id settle derives from the flight channels + scalar against the layout epsilons —
+//   `graph.isSettled()` is GLOBAL (any other animation on the shared graph would leak into it),
+//   so the registry never uses it for per-id state.
+import { resolveSpringGenerator } from "../transition.js";
+import { timingGenerator } from "../timing.js";
+import { EPSILON_POS, EPSILON_VEL } from "./constants.js";
+import { createProjectionSession } from "./session.js";
+// Frames of exclusive-remount grace after a measured sole leave. Covers deferred host onLayout
+// attach after React unmount/mount; far longer delays must not invent flights from forgotten rects.
+const EXCLUSIVE_HANDOFF_GRACE_FRAMES = 8;
+// The crossfade scalar's internal progress span (REQ-SPRING-013 convention, shared with L1 colors).
+const SCALAR_END = 100;
+// One edge authors at most ONE flight mode — the host resolver is single-outcome (T22 L1);
+// both present is an authoring contradiction the registry refuses loud (severity law: the
+// host maps this to dev-throw / prod-report at its boundary).
+function assertSingleFlightMode(options) {
+    if (options?.timing !== undefined && options?.spring !== undefined) {
+        throw new Error('layout identity: flight options carry BOTH spring and timing — one edge executes exactly one mode; author one.');
+    }
+}
+// Spring-config identity for session reuse (beside timingEqual): null session-spring pairs
+// with an undefined request (both mean the registry default); otherwise field-wise over the
+// engine SpringConfig surface.
+function springEqual(a, b) {
+    if (a === null || b === undefined)
+        return a === null && b === undefined;
+    return (a.stiffness === b.stiffness &&
+        a.damping === b.damping &&
+        a.mass === b.mass &&
+        a.duration === b.duration &&
+        a.bounce === b.bounce &&
+        a.visualDuration === b.visualDuration &&
+        a.velocity === b.velocity &&
+        a.restSpeed === b.restSpeed &&
+        a.restDelta === b.restDelta);
+}
+function timingEqual(a, b) {
+    if (b === undefined)
+        return a === null;
+    if (a === null)
+        return false;
+    if (a.duration !== b.duration)
+        return false;
+    const ae = a.ease;
+    const be = b.ease;
+    if (ae === be)
+        return true;
+    if (ae === undefined || be === undefined)
+        return ae === be;
+    if (typeof ae === 'string' || typeof be === 'string')
+        return ae === be;
+    if (!Array.isArray(ae) || !Array.isArray(be) || ae.length !== be.length)
+        return false;
+    for (let i = 0; i < ae.length; i++) {
+        if (ae[i] !== be[i])
+            return false;
+    }
+    return true;
+}
+function requireFiniteRect(id, operation, rect) {
+    if (!Number.isFinite(rect.x) ||
+        !Number.isFinite(rect.y) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height) ||
+        rect.width <= 0 ||
+        rect.height <= 0) {
+        throw new Error(`layout identity '${id}': ${operation} received a malformed rect ` +
+            `(${JSON.stringify(rect)}) — non-finite fields never fabricate a flight (packet §semantics 6).`);
+    }
+}
+function requireRegistryRect(id, operation, rect) {
+    requireFiniteRect(id, operation, rect);
+    return rect;
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+// alloc-ok: construction — one registry per driver; the per-frame surface is readInto/holds/
+// isSettled/releasable + the sessions' in-place reads, which allocate nothing.
+export function createLayoutIdentityRegistry(options) {
+  'worklet';
+    if (options.graph === undefined) {
+        throw new Error('createLayoutIdentityRegistry: a MotionGraph is required.');
+    }
+    const { graph } = options;
+    // Handle provenance + resolution (round-8 major 6, round-9 major 7): the private mint map.
+    // One WeakMap.get per readInto does BOTH the membership check (by the handle object's
+    // reference identity — clones/forgeries/foreign handles miss) and the internals lookup (the
+    // data lives here, not on the handle, so mutating a minted handle redirects nothing). Weakly
+    // held — a departed holder's handle is GC-able the moment the engine drops it.
+    const handleData = new WeakMap();
+    // One spring drives the flight AND the crossfade scalar (packet §Design); the default matches
+    // the session's own LAYOUT_PROJECTION_SPRING.
+    const flightSpring = options.spring ?? { stiffness: 550, damping: 45 };
+    const entries = new Map();
+    // One-shot exclusive-remount handoffs: measured sole leave → next enter within frame grace is
+    // lead-from-snapshot. Parallel id list avoids Map iterators on the frame-path tick.
+    const exclusiveHandoffs = new Map();
+    const exclusiveHandoffFrames = new Map();
+    const exclusiveHandoffIds = [];
+    function seedExclusiveHandoff(id, rect) {
+        if (!exclusiveHandoffs.has(id))
+            exclusiveHandoffIds.push(id);
+        exclusiveHandoffs.set(id, rect);
+        exclusiveHandoffFrames.set(id, EXCLUSIVE_HANDOFF_GRACE_FRAMES);
+    }
+    function clearExclusiveHandoff(id) {
+        if (!exclusiveHandoffs.has(id))
+            return;
+        exclusiveHandoffs.delete(id);
+        exclusiveHandoffFrames.delete(id);
+        for (let i = 0; i < exclusiveHandoffIds.length; i++) {
+            if (exclusiveHandoffIds[i] === id) {
+                exclusiveHandoffIds[i] = exclusiveHandoffIds[exclusiveHandoffIds.length - 1];
+                exclusiveHandoffIds.length -= 1;
+                break;
+            }
+        }
+    }
+    function entryOf(id, operation) {
+        const entry = entries.get(id);
+        if (entry === undefined) {
+            throw new Error(`layout identity '${id}': no holders are registered (${operation}).`);
+        }
+        return entry;
+    }
+    function holderIn(list, token) {
+        // Indexed lookup: this runs per painted holder per frame through readInto/releasable —
+        // Array.find allocates its callback closure per call (REQ-DRIVER-015, review round 6).
+        for (let i = 0; i < list.length; i++) {
+            const h = list[i];
+            if (h.token === token)
+                return h;
+        }
+        return undefined;
+    }
+    function requireHolder(entry, id, token, operation) {
+        const holder = holderIn(entry.holders, token) ?? holderIn(entry.exiting, token);
+        if (holder === undefined) {
+            throw new Error(`layout identity '${id}': '${String(token)}' does not hold this id (${operation}).`);
+        }
+        return holder;
+    }
+    function lead(entry) {
+        return entry.holders[entry.holders.length - 1];
+    }
+    // Ensure a projection session matches the requested flight mode (spring vs duration tween)
+    // AND config (per-flight spring vs registry default). Mode or config changes dispose and
+    // rebuild — never retarget across modes or spring configs (T22 L2).
+    // alloc-ok: lifecycle-edge — pairing only, never per frame.
+    function ensureSession(entry, timing, spring) {
+        if (entry.session !== null &&
+            timingEqual(entry.sessionTiming, timing) &&
+            springEqual(entry.sessionSpring, spring)) {
+            return;
+        }
+        entry.session?.dispose();
+        if (timing !== undefined) {
+            entry.session = createProjectionSession({ graph, timing });
+            entry.sessionTiming = timing;
+            entry.sessionSpring = null;
+        }
+        else {
+            entry.session = createProjectionSession({ graph, spring: spring ?? flightSpring });
+            entry.sessionTiming = null;
+            entry.sessionSpring = spring ?? null;
+        }
+    }
+    function animateScalarToEnd(entry, timing, spring) {
+        if (entry.scalar === null)
+            return;
+        if (timing !== undefined) {
+            graph.animate(entry.scalar, timingGenerator(SCALAR_END, timing));
+        }
+        else {
+            graph.animate(entry.scalar, resolveSpringGenerator(SCALAR_END, spring ?? flightSpring));
+        }
+    }
+    // Restart the crossfade scalar at 0 (a fresh fade for a fresh pairing; the READ mapping —
+    // who is lead, who fades — carries visual continuity across re-pairings). It ANIMATES only
+    // when the flight it rides actually exists: a pairing made before the lead measured holds at
+    // 0 (lead invisible, predecessor opaque) until the first commit begins the real flight.
+    // `instant` jumps straight to SCALAR_END (pin type:false — no multi-frame crossfade).
+    function restartScalar(entry, animate, instant = false, timing, spring) {
+        if (entry.scalar === null)
+            entry.scalar = graph.motionValue(0);
+        else
+            entry.scalar.jump(0);
+        if (instant) {
+            entry.scalar.jump(SCALAR_END);
+            entry.scalarPending = false;
+            return;
+        }
+        if (animate) {
+            animateScalarToEnd(entry, timing, spring);
+            entry.scalarPending = false;
+        }
+        else {
+            entry.scalarPending = true;
+        }
+    }
+    // Instant settle of rect + crossfade (REQ-API-035 layout lane under MotionConfig policy).
+    // Jump visual to target, scalar to end, release every exiting rider — no multi-frame flight.
+    // alloc-ok: lifecycle-edge — enter/commitRect/leave only; never per frame.
+    function settleInstant(entry, target, fadingFrom) {
+        // Retain the live spring config (a spring-mode session needs no rebuild just to settle);
+        // a timing session still collapses to the default spring, as before.
+        ensureSession(entry, undefined, entry.sessionSpring ?? undefined);
+        entry.session.settleAt(target);
+        entry.target = target;
+        entry.pendingBefore = null;
+        entry.fadingFrom = fadingFrom;
+        restartScalar(entry, false, true);
+        // Crossfade already complete: every exiting rider is releasable (no flight left to await).
+        // Indexed loop: for..of iterator allocation is banned on frame-path modules (REQ-DRIVER-021).
+        for (let i = 0; i < entry.exiting.length; i++) {
+            entry.exiting[i].released = true;
+        }
+    }
+    // Begin (or re-pair) the shared flight from `before` toward the lead's rect. Uses retarget when
+    // a measured flight is live (C0/C1 via the session's own semantics); begin otherwise.
+    // alloc-ok: lifecycle-edge — pairing/retarget resolution at enter/leave edges, never per frame.
+    function fly(entry, id, before, fadingFrom, options) {
+        const instant = options?.instant === true;
+        // Read-current tri-state on the enter/leave edges (review r2 major 1 — the commitRect
+        // 7htzcf law verbatim): options===undefined keeps the live mode (internal paths and
+        // callers that do not restate policy); an options object without timing/spring clears to
+        // the registry default; a config sets.
+        const timing = options === undefined ? (entry.sessionTiming ?? undefined) : options.timing;
+        const spring = options === undefined ? (entry.sessionSpring ?? undefined) : options.spring;
+        const target = lead(entry)?.rect ?? null;
+        if (instant && target !== null) {
+            settleInstant(entry, target, fadingFrom);
+            return;
+        }
+        if (entry.session !== null &&
+            timingEqual(entry.sessionTiming, timing) &&
+            springEqual(entry.sessionSpring, spring) &&
+            entry.session.state() === 'projecting' &&
+            entry.session.measured() &&
+            target !== null) {
+            entry.session.retarget(target);
+        }
+        else if (before !== null) {
+            ensureSession(entry, timing, spring);
+            entry.session.begin(id, before, target);
+            if (target === null)
+                entry.pendingBefore = before;
+        }
+        else {
+            // No visible departure exists anywhere in the stack (nothing ever measured): the flight
+            // is impossible. Degrade to a plain crossfade at natural spots and never park a
+            // fail-closed session — an unmeasurable wait would hold the graph's settle ledger open
+            // (review cycle 4 major 9).
+            entry.session?.dispose();
+            entry.session = null;
+            entry.sessionTiming = null;
+            entry.sessionSpring = null;
+            entry.pendingBefore = null;
+        }
+        // A new pairing supersedes every exiting fade it does not itself carry: a superseded
+        // exiting holder paints 0 from now on and is owed nothing — release it rather than strand
+        // it behind the new flight's settle (review cycle 7 major 12). The incoming fadingFrom may
+        // itself be an exiting holder (the leave path) — that one still rides.
+        for (const ex of entry.exiting) {
+            if (ex.token !== fadingFrom)
+                ex.released = true;
+        }
+        entry.target = target;
+        entry.fadingFrom = fadingFrom;
+        restartScalar(entry, target !== null, false, timing, spring);
+    }
+    function flightSettled(entry) {
+        // The rect leg: no session means no rect flight is pending (never flown, a reverted
+        // pairing, or a degraded plain fade) — settled rect-wise, but NEVER settled overall while
+        // the crossfade below is still live (review cycle 5 major 10: a degraded fade is active
+        // graph work; per-id settle must not lie and read() must render the fade, not snap it).
+        // Allocation-free (REQ-DRIVER-015): the session compares its live channels in place —
+        // this runs per active id per frame, so visualRect()/velocity() record-building is banned.
+        if (entry.session !== null) {
+            if (entry.target === null)
+                return false; // unmeasured target: fail-closed, never settled
+            if (!entry.session.settledAgainst(entry.target, EPSILON_POS, EPSILON_VEL))
+                return false;
+        }
+        const s = entry.scalar;
+        if (s === null)
+            return true;
+        return Math.abs(s.get() - SCALAR_END) < EPSILON_POS && Math.abs(s.getVelocity()) < EPSILON_VEL;
+    }
+    // The registry's one per-frame scratch rect: readHolderInto runs per painted holder per frame,
+    // so the visual rect is written in place here instead of allocated per read (REQ-DRIVER-015).
+    const scratchVisual = { x: 0, y: 0, width: 0, height: 0 };
+    // Single source of truth for read() and readInto(): a RESOLVED entry+holder in, ONE settle
+    // evaluation (read+zLifted as separate calls evaluated flightSettled twice), written field-wise
+    // into the caller-owned record. read() resolves by token (js-thread); readInto() dereferences
+    // its enter()-minted handle O(1) (the per-frame path, round-7 major 4).
+    function writeHolderView(entry, h, out) {
+        const holder = h.token;
+        const settled = flightSettled(entry);
+        const isLead = lead(entry)?.token === holder;
+        // Opacity: the lead fades in with the scalar; the flight's departure partner fades out;
+        // everyone else (older stack members, exiting holders no longer paired) sits at 0. Exact
+        // endpoints at settle — no epsilon residue on what the substrate paints. With no scalar
+        // (no pairing ever, or a reverted one) the identity sits with the LEAD alone — two
+        // holders both painting opaque is never a valid state (review cycle 6 major 11).
+        if (entry.scalar === null)
+            out.opacity = isLead ? 1 : 0;
+        else if (isLead)
+            out.opacity = settled ? 1 : clamp01(entry.scalar.get() / SCALAR_END);
+        else if (entry.fadingFrom === holder) {
+            out.opacity = settled ? 0 : 1 - clamp01(entry.scalar.get() / SCALAR_END);
+        }
+        else
+            out.opacity = 0;
+        // Transform: the shared visual rect relative to this holder's OWN layout rect. Identity
+        // while no flight exists, the holder is unmeasured, or the flight is unmeasured
+        // (fail-closed — never a fabricated delta, REQ-LAYOUT-011). The invert is written field-wise
+        // (projection.invert allocates its Transform — banned per frame); the divisions are safe by
+        // construction: every stored holder rect passed requireRegistryRect's width/height > 0 gate.
+        if (entry.session === null ||
+            !entry.session.writeVisualInto(scratchVisual) ||
+            h.rect === null) {
+            out.translateX = 0;
+            out.translateY = 0;
+            out.scaleX = 1;
+            out.scaleY = 1;
+        }
+        else {
+            out.translateX = scratchVisual.x - h.rect.x;
+            out.translateY = scratchVisual.y - h.rect.y;
+            out.scaleX = scratchVisual.width / h.rect.width;
+            out.scaleY = scratchVisual.height / h.rect.height;
+        }
+        // zLifted()'s exact definition, folded in so the hot path is one call, not three.
+        out.zLifted = isLead && !settled;
+    }
+    return {
+        // alloc-ok: lifecycle-edge — holder mount (React commit); builds the entry/holder records once.
+        enter(id, holder, rect, options) {
+            assertSingleFlightMode(options);
+            const registryRect = rect === null ? null : requireRegistryRect(id, 'enter', rect);
+            let entry = entries.get(id);
+            if (entry === undefined) {
+                entry = {
+                    holders: [],
+                    exiting: [],
+                    session: null,
+                    sessionTiming: null,
+                    sessionSpring: null,
+                    target: null,
+                    pendingBefore: null,
+                    fadingFrom: null,
+                    scalar: null,
+                    scalarPending: false,
+                };
+                entries.set(id, entry);
+            }
+            if (holderIn(entry.holders, holder) !== undefined ||
+                holderIn(entry.exiting, holder) !== undefined) {
+                throw new Error(`layout identity '${id}': token '${String(holder)}' already holds this id (enter).`);
+            }
+            const predecessor = lead(entry);
+            const h = { token: holder, rect: registryRect };
+            entry.holders.push(h);
+            // Frozen field-less token: nothing to mutate, nothing to leak (round-9 major 7).
+            const handle = Object.freeze({
+                __identityHolderHandle: true,
+            });
+            handleData.set(handle, { id, entry, holder: h });
+            if (predecessor === undefined) {
+                // Exclusive remount handoff: measured sole leave left a one-shot departure rect.
+                const handoff = exclusiveHandoffs.get(id);
+                clearExclusiveHandoff(id);
+                if (handoff !== undefined && handoff.width > 0 && handoff.height > 0) {
+                    fly(entry, id, handoff, null, options);
+                    return { role: 'lead', handle };
+                }
+                return { role: 'sole', handle };
+            }
+            // Live concurrent predecessor wins over any stale exclusive handoff.
+            clearExclusiveHandoff(id);
+            // The flight departs from — and the crossfade fades out — the last VISIBLE identity, not
+            // blindly the immediate predecessor: an unmeasured pending lead was never painted and can
+            // be neither the departure rect nor the fade-out partner (review cycle 4 major 9). A live
+            // flight's visual rect wins (C0 on rapid re-pairing); otherwise the nearest MEASURED
+            // holder down the stack; an all-unmeasured stack degrades to a plain crossfade in fly().
+            const liveVisual = entry.session?.visualRect() ?? null;
+            const nearestMeasured = [...entry.holders]
+                .reverse()
+                .find((c) => c.token !== holder && c.rect !== null);
+            const before = liveVisual ?? nearestMeasured?.rect ?? null;
+            const fadingFrom = predecessor.rect !== null
+                ? predecessor.token
+                : (entry.fadingFrom ?? nearestMeasured?.token ?? predecessor.token);
+            fly(entry, id, before, fadingFrom, options);
+            return { role: 'lead', handle };
+        },
+        commitRect(id, holder, rect, options) {
+            assertSingleFlightMode(options);
+            const instant = options?.instant === true;
+            const registryRect = requireRegistryRect(id, 'commitRect', rect);
+            const entry = entryOf(id, 'commitRect');
+            const h = requireHolder(entry, id, holder, 'commitRect');
+            h.rect = registryRect;
+            const currentLead = lead(entry);
+            if (currentLead?.token !== holder)
+                return;
+            // A LEAD commit (re)targets the shared flight — host layout stays authoritative
+            // (REQ-LAYOUT-002). A pairing made before the lead measured departs from the recorded
+            // predecessor rect now that a target exists. A degraded pairing (no session — nothing in
+            // the stack ever measured) skips the flight but still starts its deferred crossfade below.
+            if (instant) {
+                settleInstant(entry, registryRect, entry.fadingFrom);
+                return;
+            }
+            // Read-current flight mode (7htzcf): when this edge carries options, timing/spring
+            // absence means the default spring (clear prior mode/config). options===undefined keeps
+            // the live mode (internal paths that do not restate policy).
+            const priorTiming = entry.sessionTiming;
+            const priorSpring = entry.sessionSpring;
+            const flightTiming = options === undefined ? (entry.sessionTiming ?? undefined) : options.timing;
+            const flightSpringConfig = options === undefined ? (entry.sessionSpring ?? undefined) : options.spring;
+            if (entry.session === null) {
+                // fall through to the deferred-crossfade start
+            }
+            else if (entry.pendingBefore !== null) {
+                const before = entry.pendingBefore;
+                entry.pendingBefore = null;
+                ensureSession(entry, flightTiming, flightSpringConfig);
+                entry.session.begin(id, before, registryRect);
+                entry.target = registryRect;
+            }
+            else if (timingEqual(entry.sessionTiming, flightTiming) &&
+                springEqual(entry.sessionSpring, flightSpringConfig) &&
+                entry.session.state() === 'projecting' &&
+                entry.session.measured()) {
+                entry.session.retarget(registryRect);
+                entry.target = registryRect;
+            }
+            else {
+                const before = entry.session.visualRect() ?? entry.target;
+                if (before === null) {
+                    // No departure rect can ever exist (the predecessor never measured): the flight is
+                    // impossible. CLOSE the rect leg instead of parking the session in a wait that can
+                    // never resolve (review cycle 3 major 6) — the deferred crossfade below still hands
+                    // the identity over as a plain fade; geometry stays fail-closed at identity.
+                    entry.session.dispose();
+                    entry.session = null;
+                    entry.sessionTiming = null;
+                    entry.sessionSpring = null;
+                    entry.target = null;
+                    entry.pendingBefore = null;
+                }
+                else {
+                    ensureSession(entry, flightTiming, flightSpringConfig);
+                    entry.session.begin(id, before, registryRect);
+                    entry.target = registryRect;
+                }
+            }
+            if (entry.scalarPending && entry.scalar !== null) {
+                // The deferred crossfade starts with the REAL flight — or degrades to a plain fade when
+                // the predecessor never measured (geometry stays fail-closed, but a lead stranded
+                // invisible would be a silent severity-law violation).
+                entry.scalar.jump(0);
+                animateScalarToEnd(entry, flightTiming, flightSpringConfig);
+                entry.scalarPending = false;
+            }
+            else if (
+            // Live scalar must share read-current config with geometry (2vqwp8 5d2c7f9a8e41):
+            // session rebuild alone left a prior duration tween finishing for hundreds of frames.
+            entry.scalar !== null &&
+                options !== undefined &&
+                (!timingEqual(priorTiming, flightTiming) || !springEqual(priorSpring, flightSpringConfig))) {
+                animateScalarToEnd(entry, flightTiming, flightSpringConfig);
+            }
+        },
+        // alloc-ok: lifecycle-edge — holder unmount (React commit); exiting-fade bookkeeping.
+        leave(id, holder, options) {
+            assertSingleFlightMode(options);
+            const entry = entryOf(id, 'leave');
+            const exitingHolder = holderIn(entry.exiting, holder);
+            if (exitingHolder !== undefined) {
+                // A former lead being released (post-crossfade removal path).
+                entry.exiting.splice(entry.exiting.indexOf(exitingHolder), 1);
+                exitingHolder.departed = true; // handle validity ends with registry membership
+            }
+            else {
+                const h = requireHolder(entry, id, holder, 'leave');
+                const wasLead = lead(entry)?.token === holder;
+                entry.holders.splice(entry.holders.indexOf(h), 1);
+                if (wasLead && entry.holders.length > 0) {
+                    const before = entry.session?.visualRect() ?? h.rect;
+                    if (before === null) {
+                        h.departed = true; // dropped outright — no exit ride, handle validity ends here
+                        // The leaver never became visible (unmeasured, no live flight): it drops outright —
+                        // immediately releasable, no exit ride, no crossfade owed (review cycle 2 major 4).
+                        // What remains is decided by what sits beneath it (review cycle 6 major 11):
+                        const resumed = lead(entry);
+                        const resumedSource = resumed === undefined
+                            ? undefined
+                            : [...entry.holders]
+                                .reverse()
+                                .find((c) => c.token !== resumed.token && c.rect !== null);
+                        if (resumed !== undefined &&
+                            resumed.rect === null &&
+                            (resumedSource !== undefined || entry.fadingFrom !== null)) {
+                            // An older PENDING pairing survives beneath the leaver (an unmeasured resumed
+                            // lead over a visible identity): RE-ESTABLISH it — the resumed lead's first
+                            // commit must still run the original shared flight + crossfade, never snap in.
+                            fly(entry, id, resumedSource?.rect ?? null, entry.fadingFrom ?? resumedSource?.token ?? null, options);
+                        }
+                        else {
+                            // Nothing pending underneath (measured resumed lead, or nothing visible
+                            // anywhere): the entry returns to its at-rest state. dispose() releases the
+                            // session's waiting-for-measurement activity — an abandoned session must not
+                            // hold the graph's settle ledger open (review cycle 3 major 6).
+                            entry.session?.dispose();
+                            entry.session = null;
+                            entry.sessionTiming = null;
+                            entry.sessionSpring = null;
+                            entry.target = null;
+                            entry.pendingBefore = null;
+                            entry.fadingFrom = null;
+                            entry.scalar = null;
+                            entry.scalarPending = false;
+                        }
+                    }
+                    else {
+                        // The lead leaving hands lead back and REVERSES the flight; the leaver rides as
+                        // exiting-trailing (fade-out) until settle, then `releasable` (packet §Design) —
+                        // its handle stays valid for the ride.
+                        entry.exiting.push(h);
+                        fly(entry, id, before, holder, options);
+                    }
+                }
+                else {
+                    // A trailing/non-lead holder (or the last holder) leaving gets no exit ride: its
+                    // handle's validity ends with its registry membership. Presence-retained followers
+                    // must not take this leave while the successor's forward flight is live
+                    // (REQ-PRESENCE-024): beginExit skip-detaches; unmount still leaves.
+                    h.departed = true;
+                    // Exclusive remount: last measured holder seeds a short-lived handoff for the successor
+                    // that React mounts in the same commit (catalog Shared-layout-reparenting).
+                    if (entry.holders.length === 0 && entry.exiting.length === 0 && h.rect !== null) {
+                        seedExclusiveHandoff(id, h.rect);
+                    }
+                    if (entry.fadingFrom === holder) {
+                        // The fade-out partner left mid-crossfade: nothing remains to fade against — the lead
+                        // paints fully opaque immediately (a half-faded lead with no visible counterpart is a
+                        // continuity dip, review cycle 2 minor 5). jump() itself ends the live scalar spring
+                        // (the pinned notify-then-stop contract, r17) — no pre-stop, which would reverse the
+                        // cancellation/change order. The rect flight continues unaffected.
+                        entry.fadingFrom = null;
+                        if (entry.scalar !== null) {
+                            entry.scalar.jump(SCALAR_END);
+                            entry.scalarPending = false;
+                        }
+                    }
+                }
+            }
+            if (entry.holders.length === 0 && entry.exiting.length === 0) {
+                // GC (packet §Design): the last holder leaving drops the id. A measured sole leave may
+                // have seeded exclusiveHandoffs above — that snapshot is independent of the entry GC.
+                // dispose() closes out the session with the entry: a fail-closed wait releases its
+                // activity, a live flight's springs stop (nothing reads them anymore) — either way the
+                // graph's settle ledger is left clean (review cycle 3 major 6).
+                entry.session?.dispose();
+                entries.delete(id);
+            }
+        },
+        // alloc-ok: js-thread — record-building read for JS-side callers; the UI frame path uses
+        // readInto's caller-owned record.
+        read(id, holder) {
+            // Delegates to the same single-source computation the hot path uses; this record-building
+            // shape stays for JS-side callers (checks, e2e) — the per-frame path is readInto().
+            const out = {
+                translateX: 0,
+                translateY: 0,
+                scaleX: 1,
+                scaleY: 1,
+                opacity: 0,
+                zLifted: false,
+            };
+            const entry = entryOf(id, 'read');
+            const h = requireHolder(entry, id, holder, 'read');
+            writeHolderView(entry, h, out);
+            return {
+                transform: {
+                    translateX: out.translateX,
+                    translateY: out.translateY,
+                    scaleX: out.scaleX,
+                    scaleY: out.scaleY,
+                },
+                opacity: out.opacity,
+            };
+        },
+        readInto(handle, out) {
+            // O(1) handle resolution (round-7 major 4) with the by-token discipline's fail-loud
+            // posture intact: ONE WeakMap.get is both the provenance check and the lookup (rounds
+            // 8–9) — forged objects, spread-clones, foreign-registry handles, and mutated real
+            // handles all miss THIS registry's private map or resolve to the untouched internals;
+            // only then is liveness checked. WeakMap.get on a primitive returns undefined, so the
+            // single miss branch covers malformed values too.
+            const hi = handleData.get(handle);
+            if (hi === undefined) {
+                throw new Error('layout identity: readInto received a value that is not an enter()-minted ' +
+                    'IdentityHolderHandle of this registry (forged and cross-registry handles never dereference).');
+            }
+            if (hi.holder.departed === true) {
+                throw new Error(`layout identity '${hi.id}': this handle's holder ('${String(hi.holder.token)}') no longer holds the id (readInto).`);
+            }
+            writeHolderView(hi.entry, hi.holder, out);
+        },
+        releasable(id, holder) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return true; // the id was dropped — nothing holds the element
+            const exitingHolder = holderIn(entry.exiting, holder);
+            if (exitingHolder !== undefined) {
+                // Sticky latch (review cycle 7 major 12): once the fade this holder rides has settled
+                // (or a new pairing superseded it in fly()), the release is permanent — a later
+                // unrelated flight must never flip it back.
+                if (exitingHolder.released === true)
+                    return true;
+                if (flightSettled(entry)) {
+                    exitingHolder.released = true;
+                    return true;
+                }
+                return false;
+            }
+            // Still holding → not releasable; not tracked at all → the registry is done with it
+            // (e.g. a reverted pending pairing dropped the leaver without an exit ride — review
+            // cycle 2 major 4: a coupled safeToRemove must still fire for it).
+            return holderIn(entry.holders, holder) === undefined;
+        },
+        zLifted(id, holder) {
+            const entry = entryOf(id, 'zLifted');
+            requireHolder(entry, id, holder, 'zLifted');
+            return lead(entry)?.token === holder && !flightSettled(entry);
+        },
+        isSettled(id) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return true;
+            return flightSettled(entry);
+        },
+        holds(id, holder) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return false; // the id was dropped — nothing is tracked
+            return (holderIn(entry.holders, holder) !== undefined ||
+                holderIn(entry.exiting, holder) !== undefined);
+        },
+        isLead(id, holder) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return false;
+            return lead(entry)?.token === holder;
+        },
+        // Once per UI frame from the layout engine step (REQ-DRIVER-015: indexed, no Map iterators).
+        tickExclusiveHandoffs() {
+            for (let i = 0; i < exclusiveHandoffIds.length;) {
+                const id = exclusiveHandoffIds[i];
+                const remaining = exclusiveHandoffFrames.get(id);
+                if (remaining === undefined || remaining <= 1) {
+                    exclusiveHandoffs.delete(id);
+                    exclusiveHandoffFrames.delete(id);
+                    exclusiveHandoffIds[i] = exclusiveHandoffIds[exclusiveHandoffIds.length - 1];
+                    exclusiveHandoffIds.length -= 1;
+                    continue;
+                }
+                exclusiveHandoffFrames.set(id, remaining - 1);
+                i += 1;
+            }
+        },
+        hasPendingExclusiveHandoffs() {
+            return exclusiveHandoffIds.length > 0;
+        },
+    };
+}