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

package/dist/layout/tree.js

@@ -0,0 +1,823 @@
+// @frame-path — executes inside the UI-runtime frame step when hosted by native; allocation-gated there.
+// SPEC-LAYOUT §4a — a host-agnostic projection-node tree. The layoutId registry deliberately owns
+// shared-holder roles; this tree owns component ancestry and accumulated geometry only. Every Motion
+// component can register, but only a node with a target or an explicit projection contributes output.
+import { IDENTITY_TRANSFORM, projectAtProgress } from "./projection.js";
+// The stale-report ring's CONTAINED bound: the dedupe set already collapses per-id spam, so the
+// ring only ever holds distinct-episode reports — a contained flood past the cap is itself the
+// signal (formalized as the delivered projection-report-overflow record). Lifecycle-edge only;
+// the per-frame fast path never touches it.
+const MAX_STALE_REPORTS = 32;
+// The ring's ESCALATED bound (seal r10, F1): escalations are PRESERVED, never evicted — a
+// wrong-forest publish, malformed live input, undefined scale geometry, or the overflow record
+// itself is a script-bug/fail-loud signal that must reach the severity channel. 256 matches the
+// escalated dedupe window: exceeding it needs 256 DISTINCT undrained escalations in one
+// inter-drain window (the driver drains every frame — a catastrophic storm), and past it the
+// overflow record aggregates every dropped id with its count rather than losing one silently.
+const MAX_STALE_ESCALATED_REPORTS = 256;
+// The overflow record's named-id bound (seal r12, F4): the first distinct dropped ids per class
+// are named with their counts in the record's detail; everything past this cap aggregates as an
+// honest "+N more" count. Without it, a callback-only session (no drain) grew the loss maps
+// with every distinct dropped id and rebuilt a string over ALL of them per drop — the
+// reviewer's 1,200-id probe produced a 12,631-character detail. Truth stays exact: the total
+// count is always precise; only the NAMING is capped (the detail's length stays bounded for
+// realistic id lengths).
+const MAX_OVERFLOW_NAMED_IDS = 32;
+// The dedupe sets' own bound (iOS AUTO SIGABRT F2): an unbounded set grows with every distinct
+// stale id a session ever sees AND pins each id's suppression forever — a long session both leaks
+// and loses the signal of a genuinely new episode on an ancient id. Insertion-ordered eviction
+// (a Set iterates in insertion order): past the cap the oldest entry drops, so an evicted id
+// reports again while an in-window id stays deduped. No refresh-on-hit — a hot stale id must not
+// pin itself inside the window forever. The cap applies to EACH of the two class-partitioned
+// sets (seal r9, F2), so the total stays bounded at 2× this value.
+const MAX_STALE_IDS = 256;
+// The known-id ledger's bound (seal r7, F4 — see the ledger comment inside createProjectionTree).
+// Eviction misclassifies an ancient KNOWN id toward the severe 'projection-unregistered-node'
+// code; that direction is deliberate — a publish still landing for a component registered more
+// than this many mounts ago means a lane is holding a long-dead id, itself the script-bug class
+// the severe code exists to surface.
+const MAX_KNOWN_IDS = 4096;
+// The shared empty-drain constant: a quiet frame (the overwhelming common case) allocates nothing.
+const EMPTY_STALE_REPORTS = Object.freeze([]);
+// The identity output for a stale read: shared and frozen, never a per-call allocation.
+const STALE_IDENTITY_OUTPUT = Object.freeze({
+    ...IDENTITY_TRANSFORM,
+    borderRadius: null,
+    targetDeltaScaleX: 1,
+    targetDeltaScaleY: 1,
+    treeScaleX: 1,
+    treeScaleY: 1,
+});
+// The per-frame path writes into the node's persistent cell; allocating a fresh radius pair per
+// frame is exactly what REQ-DRIVER-021 forbids.
+// Pure correction math (REQ-LAYOUT-013: scale × corrected == radius). Callers gate scale
+// validity at the boundary — project()'s report-and-skip above — so this module never throws on
+// a UI-executed path: an operating error is reported at the call boundary (seal r2, F3).
+function writeCorrectedRadius(cell, radius, scaleX, scaleY) {
+    cell.x = radius / scaleX;
+    cell.y = radius / scaleY;
+}
+// Finite-fields probe for setProjection's pre-mutation validation (seal r11, F2a): position may
+// be any finite number; the dimensions carry their own sign rules at the call site (target must
+// be positive — the divisor inside invert; source may be zero — a collapsed host).
+function isFiniteRectGeometry(rect) {
+    return (Number.isFinite(rect.x) &&
+        Number.isFinite(rect.y) &&
+        Number.isFinite(rect.width) &&
+        Number.isFinite(rect.height));
+}
+// The internal-invariant refusals that STAY loud (registration-time, never a UI frame path):
+// a parent-change after registration and a path cycle (refreshPathsAndStableSortAtRegistration).
+// Every frame/update-path refusal converted to report+skip in Phase 1.5 (iOS AUTO SIGABRT campaign).
+// The severity-class partition behind the dedupe law (seal r9, F2) and the ring's delivery
+// reserve (seal r9, F3): escalated codes name script bugs on live nodes — a wrong-forest or
+// mistyped publish, malformed live input, undefined scale geometry, and the ring-overflow
+// record itself; contained codes name routine teardown races and operating conditions.
+function isEscalatedProjectionStaleCode(code) {
+    return (code === 'projection-unregistered-node' ||
+        code === 'projection-invalid-frame-input' ||
+        code === 'projection-non-finite-output' ||
+        code === 'projection-report-overflow');
+}
+function resetOutput(node) {
+    node.output.translateX = 0;
+    node.output.translateY = 0;
+    node.output.scaleX = 1;
+    node.output.scaleY = 1;
+    node.output.borderRadius = null;
+    node.output.targetDeltaScaleX = 1;
+    node.output.targetDeltaScaleY = 1;
+    node.output.treeScaleX = 1;
+    node.output.treeScaleY = 1;
+}
+// alloc-ok: lifecycle-edge — runs only inside register(); the path array is built once per node.
+function updateDepth(node, parent) {
+    node.depth = parent === undefined ? 0 : parent.depth + 1;
+    node.path = parent === undefined ? [node.componentId] : [...parent.path, node.componentId];
+}
+// Hoisted module-level comparator: the registration-edge stable sort allocates no closure.
+function compareByDepth(left, right) {
+    return left.depth - right.depth;
+}
+/**
+ * Creates a stable, depth-sorted component tree. `project()` deliberately walks parents before
+ * children: a non-projecting intermediate has identity output but preserves its ancestor's scale
+ * in `treeScale`, which is precisely the muggle-through capability required by REQ-LAYOUT-012.
+ *
+ * iOS AUTO SIGABRT campaign: every frame/update path is NON-FATAL on a stale id, an orphaned
+ * path, or torn-down frame input — expected teardown races report once per id per episode into a
+ * bounded ring (drained by the host's severity channel); they never throw on the UI runtime.
+ */
+// alloc-ok: construction — one tree per driver; the per-frame surface is project(), which
+// mutates persistent node cells only.
+export function createProjectionTree(options) {
+    // Config-time invariant, loud JS-side like the register/sort-at-registration asserts below
+    // (seal r8, F2): the delivery surface is MANDATORY — a bare tree's escalated reports would
+    // accumulate silently. Untyped JS callers get the same law at runtime.
+    const opts = options;
+    const onStaleProjectionNode = opts !== undefined && 'onStaleProjectionNode' in opts ? opts.onStaleProjectionNode : undefined;
+    const drainDeclared = opts !== undefined && 'delivery' in opts && opts.delivery === 'drain';
+    if (onStaleProjectionNode === undefined && !drainDeclared) {
+        throw new Error('projection tree: createProjectionTree requires a stale-report delivery surface — install ' +
+            "onStaleProjectionNode (JS hosts) or pass { delivery: 'drain' } (the UI driver's " +
+            'frame-edge drain); a bare tree silently accumulates reports in an undrained ring ' +
+            '(seal r8, F2).');
+    }
+    const nodes = new Map();
+    // Depth-sorted once per register() by refreshPathsAndStableSortAtRegistration (packet §6
+    // projection repair): project() reads this list with NO orderDirty/reorder/sort edge in-frame.
+    // unregister() removes by index (order-preserving), so the invariant holds across teardown too.
+    const ordered = [];
+    // The bounded stale-report ring and its per-episode dedupe sets — partitioned by escalation
+    // class (seal r9, F2): a CONTAINED report must never suppress a later ESCALATED report for
+    // the same id (the severity channel would lose the deferred dev throw / production error),
+    // while same-class repeats still dedupe once per episode. Re-registration clears the id from
+    // BOTH sets, so a genuinely new teardown of the same id reports again.
+    const staleReports = [];
+    // Ring accounting (seal r10, F1): contained and escalated entries carry SEPARATE bounds — an
+    // escalation never competes with contained reports for ring space. A dropped report (past its
+    // class cap) is aggregated per id into the overflow record's detail, which names every dropped
+    // id and count; the whole window's accounting resets on drain.
+    let containedInRing = 0;
+    let escalatedInRing = 0;
+    let overflowPending = false;
+    let overflowRecordIndex = -1;
+    const droppedContainedCounts = new Map();
+    const droppedEscalatedCounts = new Map();
+    // The counts-only remainder past MAX_OVERFLOW_NAMED_IDS (seal r12, F4): drops of ids beyond
+    // the named set aggregate here, so the loss accounting AND the rebuilt detail stay bounded in
+    // a drain-free session.
+    let extraContainedDrops = 0;
+    let extraEscalatedDrops = 0;
+    const reportedContainedIds = new Set();
+    const reportedEscalatedIds = new Set();
+    // The known-id ledger behind the stale-vs-never-registered distinction (seal r7, F4): it only
+    // GROWS here at register() — an id that registered and later tore down stays known, so its
+    // teardown race keeps the contained 'projection-stale-node' code, while a never-registered id
+    // escalates to 'projection-unregistered-node'. Lifecycle-edge only; the frame path reads it.
+    const knownIds = new Set();
+    // alloc-ok: lifecycle-edge — the first stale hit per (class, id) per episode allocates the
+    // report record, the detail string (built ONLY here, after the dedupe gate), and the dedupe
+    // entry; the deduped fast path (every later frame) allocates nothing.
+    function reportStaleNode(code, componentId, subject, reason) {
+        const dedupeSet = isEscalatedProjectionStaleCode(code)
+            ? reportedEscalatedIds
+            : reportedContainedIds;
+        if (dedupeSet.has(componentId))
+            return;
+        dedupeSet.add(componentId);
+        if (dedupeSet.size > MAX_STALE_IDS) {
+            // The size check makes the first value blatantly present; iteration is insertion-ordered,
+            // so this evicts the oldest episode (see MAX_STALE_IDS above).
+            dedupeSet.delete(dedupeSet.values().next().value);
+        }
+        const detail = code === 'projection-orphaned-path'
+            ? `'${componentId}' orphaned: parent '${subject}' ${reason}.`
+            : code === 'projection-invalid-radius-correction'
+                ? `borderRadius correction skipped on '${componentId}' (${reason}; the last valid radius is preserved).`
+                : code === 'projection-invalid-frame-input'
+                    ? `${subject} ${reason} on '${componentId}' (malformed input on a live node; update refused).`
+                    : code === 'projection-unregistered-node'
+                        ? `${subject} refused on '${componentId}': the id was never registered in this projection tree (a wrong-forest or mistyped publish — a script bug, not a teardown race).`
+                        : code === 'projection-non-finite-output'
+                            ? `${subject} ${reason} on '${componentId}' (undefined geometry on a live node; output frozen at the last valid finite state).`
+                            : `${subject} ${reason} (teardown race — the host detached before this update).`;
+        const report = { source: 'projection-tree', code, detail };
+        pushStaleReport(report, isEscalatedProjectionStaleCode(code), componentId);
+        onStaleProjectionNode?.(report);
+    }
+    // The ring's fail-loud law (seal r9, F3; seal r10, F1): each class keeps its own bound — an
+    // ESCALATED report never competes with contained entries and is PRESERVED up to
+    // MAX_STALE_ESCALATED_REPORTS (nothing evicts an escalation to make room). A report dropped
+    // past its class cap is never silent: exactly one projection-report-overflow record per
+    // inter-drain window marks the loss, and its detail aggregates EVERY dropped id with its
+    // count, per class — the text always matches what was actually lost.
+    // alloc-ok: lifecycle-edge — drops happen only past a class cap (a teardown storm); the
+    // deduped fast path (a quiet frame) allocates nothing.
+    function pushStaleReport(report, escalated, componentId) {
+        if (escalated) {
+            if (escalatedInRing < MAX_STALE_ESCALATED_REPORTS) {
+                escalatedInRing += 1;
+                staleReports.push(report);
+            }
+            else {
+                recordDroppedReport(componentId, true);
+            }
+            return;
+        }
+        if (containedInRing < MAX_STALE_REPORTS) {
+            containedInRing += 1;
+            staleReports.push(report);
+            return;
+        }
+        recordDroppedReport(componentId, false);
+    }
+    // alloc-ok: lifecycle-edge — one bounded map write per dropped report (already past a class
+    // cap); past the named-id bound a counter increments instead (seal r12, F4).
+    function recordDroppedReport(componentId, escalated) {
+        const counts = escalated ? droppedEscalatedCounts : droppedContainedCounts;
+        const existing = counts.get(componentId);
+        if (existing !== undefined) {
+            counts.set(componentId, existing + 1);
+        }
+        else if (counts.size < MAX_OVERFLOW_NAMED_IDS) {
+            counts.set(componentId, 1);
+        }
+        else if (escalated) {
+            extraEscalatedDrops += 1;
+        }
+        else {
+            extraContainedDrops += 1;
+        }
+        markReportOverflow();
+    }
+    // alloc-ok: lifecycle-edge — detail text built only on an overflow (re)mark, over at most
+    // MAX_OVERFLOW_NAMED_IDS named entries plus the counts-only remainder (bounded, seal r12, F4).
+    function formatDroppedCounts(counts, extra) {
+        let total = extra;
+        let list = '';
+        for (const [id, count] of counts) {
+            total += count;
+            list += `${list === '' ? '' : ', '}${id}×${count}`;
+        }
+        if (extra > 0)
+            list += `${list === '' ? '' : ', '}+${extra} more`;
+        return `${total} [${list}]`;
+    }
+    // alloc-ok: lifecycle-edge — one record per inter-drain window (overflowPending dedupes);
+    // later drops in the same window REPLACE the in-ring record's detail so the drained record
+    // names every dropped id and count.
+    function markReportOverflow() {
+        const lossParts = [];
+        if (droppedContainedCounts.size > 0 || extraContainedDrops > 0)
+            lossParts.push(`dropped ${formatDroppedCounts(droppedContainedCounts, extraContainedDrops)} contained report(s)`);
+        if (droppedEscalatedCounts.size > 0 || extraEscalatedDrops > 0)
+            lossParts.push(`dropped ${formatDroppedCounts(droppedEscalatedCounts, extraEscalatedDrops)} escalated report(s)`);
+        if (droppedContainedCounts.size === 0 && extraContainedDrops === 0)
+            lossParts.push('no contained reports were dropped');
+        if (droppedEscalatedCounts.size === 0 && extraEscalatedDrops === 0)
+            lossParts.push('every escalated report was delivered');
+        const detail = `projection stale-report ring overflowed: ${lossParts.join('; ')} ` +
+            `(caps: ${MAX_STALE_REPORTS} contained, ${MAX_STALE_ESCALATED_REPORTS} escalated; seal r10, F1).`;
+        if (overflowPending) {
+            staleReports[overflowRecordIndex] = {
+                source: 'projection-tree',
+                code: 'projection-report-overflow',
+                detail,
+            };
+            return;
+        }
+        overflowPending = true;
+        overflowRecordIndex = staleReports.length;
+        const report = {
+            source: 'projection-tree',
+            code: 'projection-report-overflow',
+            detail,
+        };
+        staleReports.push(report);
+        onStaleProjectionNode?.(report);
+    }
+    // The idempotent no-op path of every stale mutator/reader below: static subject/reason parts
+    // only — nothing is built at the call site (REQ-DRIVER-021). Seal r7, F4: the code
+    // branches on the known-id ledger — a never-registered id is a wrong-forest/mistyped publish
+    // (escalated), a known-then-torn-down id is the contained Phase-1.5 teardown race.
+    function staleNode(componentId, operation) {
+        if (knownIds.has(componentId)) {
+            reportStaleNode('projection-stale-node', componentId, operation, 'on an unregistered id');
+        }
+        else {
+            reportStaleNode('projection-unregistered-node', componentId, operation, '');
+        }
+        return undefined;
+    }
+    // alloc-ok: lifecycle-edge — React mounts passive effects child-first. Resolve the complete
+    // component forest after each attach so a descendant may enter before its parent without
+    // weakening the frame-path's parent-before-child invariant, then perform the stable depth sort
+    // SYNCHRONOUSLY here (packet §6 registration-edge repair): project() never sorts in-frame.
+    // A stable sort retains sibling mount order, which keeps the traversal deterministic without
+    // encoding host tags.
+    function refreshPathsAndStableSortAtRegistration() {
+        const resolving = new Set();
+        const resolved = new Set();
+        function resolve(node) {
+            if (resolved.has(node.componentId))
+                return;
+            if (resolving.has(node.componentId)) {
+                throw new Error(`projection tree: parent cycle reaches '${node.componentId}'; a Motion component cannot be its own projection ancestor.`);
+            }
+            resolving.add(node.componentId);
+            const parent = node.parentId === null ? undefined : nodes.get(node.parentId);
+            if (parent !== undefined)
+                resolve(parent);
+            updateDepth(node, parent);
+            resolving.delete(node.componentId);
+            resolved.add(node.componentId);
+        }
+        for (const node of nodes.values())
+            resolve(node);
+        ordered.sort(compareByDepth);
+    }
+    // alloc-ok: lifecycle-edge — runs only inside unregister()/prune teardown turns.
+    function hasRegisteredDescendant(componentId) {
+        for (const candidate of nodes.values()) {
+            if (candidate.parentId === componentId)
+                return true;
+        }
+        return false;
+    }
+    // alloc-ok: lifecycle-edge — runs only inside unregister()'s teardown turn.
+    function removeNode(node) {
+        nodes.delete(node.componentId);
+        const index = ordered.indexOf(node);
+        if (index >= 0)
+            ordered.splice(index, 1);
+    }
+    // Passive-effect cleanup is parent-first. A parent is therefore retained as an inert ancestry
+    // record until its descendants have detached, then compacted in the same lifecycle turn.
+    // alloc-ok: lifecycle-edge — runs only inside unregister()'s teardown turn.
+    function prunePendingUnregisters() {
+        let pruned = true;
+        while (pruned) {
+            pruned = false;
+            for (const node of nodes.values()) {
+                if (node.pendingUnregister && !hasRegisteredDescendant(node.componentId)) {
+                    removeNode(node);
+                    pruned = true;
+                    break;
+                }
+            }
+        }
+    }
+    return {
+        // alloc-ok: lifecycle-edge — host mount; builds the node record once, never per frame.
+        register(componentId, parentId, projectionParticipant = false) {
+            // A re-registered id opens a NEW episode in BOTH dedupe classes: its next teardown race
+            // (contained) and its next script-bug report (escalated) both fire again (Phase 1.5; r9 F2).
+            reportedContainedIds.delete(componentId);
+            reportedEscalatedIds.delete(componentId);
+            // The known-id ledger (seal r7, F4) only grows: once registered, an id's later teardown
+            // race stays the contained 'projection-stale-node' class forever (bounded above).
+            if (!knownIds.has(componentId)) {
+                knownIds.add(componentId);
+                if (knownIds.size > MAX_KNOWN_IDS)
+                    knownIds.delete(knownIds.values().next().value);
+            }
+            const existing = nodes.get(componentId);
+            if (existing !== undefined) {
+                if (existing.parentId !== parentId) {
+                    throw new Error(`projection tree: '${componentId}' changed parent from '${existing.parentId}' to '${parentId}' after registration; remount is required to preserve a coherent projection path.`);
+                }
+                // A re-registered node is ALIVE (seal r14, F1): the pending teardown belonged to its
+                // previous life — an unregister retained it as inert ancestry only because a descendant
+                // still lived, and this re-registration is the host returning. Leaving the flag set
+                // would let the next prune (when the last descendant later detaches) remove the LIVE
+                // node: its next update would then misreport a stale teardown and freeze at identity.
+                // Its later teardown is evaluated fresh by the next unregister.
+                existing.pendingUnregister = false;
+                if (existing.projectionParticipant !== projectionParticipant) {
+                    existing.projectionParticipant = projectionParticipant;
+                    // `layout`/active `layoutId` can be removed on a later render. Retaining either leg
+                    // would keep a stale transform painted after the host has returned to ordinary layout.
+                    if (!projectionParticipant) {
+                        existing.target = null;
+                        existing.delta = null;
+                        existing.hasHostFrame = false;
+                        existing.projectionPaintedByHost = false;
+                        existing.treeScaleX = 1;
+                        existing.treeScaleY = 1;
+                        existing.treeTranslateX = 0;
+                        existing.treeTranslateY = 0;
+                        existing.frameTreeCenterOffsetX = 0;
+                        existing.frameTreeCenterOffsetY = 0;
+                        existing.committedInHostFrame = false;
+                        resetOutput(existing);
+                    }
+                }
+                return; // Same-state React rerender: never reset a live projection.
+            }
+            const node = {
+                componentId,
+                parentId,
+                depth: 0,
+                path: [],
+                target: null,
+                targetCell: { x: 0, y: 0, width: 0, height: 0 },
+                layoutCell: { x: 0, y: 0, width: 0, height: 0 },
+                hasHostFrame: false,
+                projectionParticipant,
+                projectionPaintedByHost: false,
+                pendingUnregister: false,
+                delta: null,
+                deltaCell: { ...IDENTITY_TRANSFORM },
+                borderRadius: null,
+                // alloc-ok: lifecycle-edge — one persistent radius cell per registered node, mutated per frame.
+                radiusCell: { x: 0, y: 0 },
+                radiusCorrected: false,
+                treeScaleX: 1,
+                treeScaleY: 1,
+                treeTranslateX: 0,
+                treeTranslateY: 0,
+                frameTreeCenterOffsetX: 0,
+                frameTreeCenterOffsetY: 0,
+                committedInHostFrame: false,
+                output: {
+                    ...IDENTITY_TRANSFORM,
+                    borderRadius: null,
+                    targetDeltaScaleX: 1,
+                    targetDeltaScaleY: 1,
+                    treeScaleX: 1,
+                    treeScaleY: 1,
+                },
+            };
+            nodes.set(componentId, node);
+            ordered.push(node);
+            refreshPathsAndStableSortAtRegistration();
+        },
+        // alloc-ok: lifecycle-edge — host unmount (React passive cleanup is parent-first).
+        unregister(componentId) {
+            const node = nodes.get(componentId);
+            // Double-teardown is a routine race (parent-first cleanup can detach a node twice across
+            // overlapping lanes): an unknown id is an idempotent no-op, never a throw (Phase 1.5).
+            if (node === undefined)
+                return;
+            if (hasRegisteredDescendant(componentId)) {
+                node.pendingUnregister = true;
+                return;
+            }
+            removeNode(node);
+            prunePendingUnregisters();
+        },
+        setTarget(componentId, target) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'setTarget');
+            if (node === undefined)
+                return;
+            node.target = target;
+            if (target !== null)
+                node.projectionParticipant = true;
+        },
+        setProjection(componentId, source, target, progress) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'setProjection');
+            if (node === undefined)
+                return;
+            if (!Number.isFinite(progress) || progress < 0 || progress > 1) {
+                reportStaleNode('projection-invalid-frame-input', componentId, 'setProjection', 'progress outside [0, 1]');
+                return;
+            }
+            // Seal r11, F2a: validate BOTH rects BEFORE any mutation. A zero/negative/non-finite
+            // TARGET dimension divides by zero inside projectAtProgress's invert (its assertMeasurable
+            // throws — a UI throw through an imported callee the tree scan could not see, the review's
+            // probe), and non-finite or negative SOURCE fields poison the delta. Refuse through the
+            // escalated malformed-live-input channel: no mutation, no throw, the node keeps its last
+            // valid projection state. A zero SOURCE dimension stays legal (a collapsed host is a
+            // legal measurement — the finite-zero delta publishes, seal r9, F1).
+            if (!isFiniteRectGeometry(source) ||
+                !isFiniteRectGeometry(target) ||
+                source.width < 0 ||
+                source.height < 0 ||
+                target.width <= 0 ||
+                target.height <= 0) {
+                reportStaleNode('projection-invalid-frame-input', componentId, 'setProjection', 'non-finite rect fields or non-positive target dimensions');
+                return;
+            }
+            node.target = target;
+            node.projectionParticipant = true;
+            node.hasHostFrame = false;
+            node.projectionPaintedByHost = false;
+            node.delta = projectAtProgress(source, target, progress);
+        },
+        setDirectProjection(componentId, translateX, translateY, scaleX, scaleY) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'setDirectProjection');
+            if (node === undefined)
+                return;
+            if (!Number.isFinite(translateX) ||
+                !Number.isFinite(translateY) ||
+                !Number.isFinite(scaleX) ||
+                !Number.isFinite(scaleY) ||
+                scaleX <= 0 ||
+                scaleY <= 0) {
+                reportStaleNode('projection-invalid-frame-input', componentId, 'setDirectProjection', 'non-finite/non-positive translation or scale');
+                return;
+            }
+            node.projectionParticipant = true;
+            node.hasHostFrame = false;
+            node.projectionPaintedByHost = true;
+            node.deltaCell.translateX = translateX;
+            node.deltaCell.translateY = translateY;
+            node.deltaCell.scaleX = scaleX;
+            node.deltaCell.scaleY = scaleY;
+            node.delta = node.deltaCell;
+        },
+        // @frame-path — host layout animations report their current rect on every UI frame. Mutate
+        // persistent cells rather than constructing Rect/Transform records: the worklet frame path
+        // is allocation-gated, while targetless descendants consume this exact delta in the same step.
+        setHostFrame(componentId, currentX, currentY, currentWidth, currentHeight, targetX, targetY, targetWidth, targetHeight) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'setHostFrame');
+            if (node === undefined)
+                return;
+            // Negative dimensions are nonsense geometry, not a collapsed host (seal r12, F3): they
+            // used to sail through and publish NEGATIVE scales into the descendant projection math
+            // (the reviewer's scaleX: -1 probe). Current dims may be zero (legal collapse — the
+            // whole-node freeze owns that path, seal r9 F1); target dims divide, so they must be
+            // positive (seal r11, F2a's law). Refuse BEFORE any mutation.
+            if (!Number.isFinite(currentX) ||
+                !Number.isFinite(currentY) ||
+                !Number.isFinite(currentWidth) ||
+                !Number.isFinite(currentHeight) ||
+                !Number.isFinite(targetX) ||
+                !Number.isFinite(targetY) ||
+                !Number.isFinite(targetWidth) ||
+                !Number.isFinite(targetHeight) ||
+                currentWidth < 0 ||
+                currentHeight < 0 ||
+                targetWidth <= 0 ||
+                targetHeight <= 0) {
+                reportStaleNode('projection-invalid-frame-input', componentId, 'setHostFrame', 'non-finite rect, negative current dimension, or non-positive target dimension');
+                return;
+            }
+            node.layoutCell.x = currentX;
+            node.layoutCell.y = currentY;
+            node.layoutCell.width = currentWidth;
+            node.layoutCell.height = currentHeight;
+            node.targetCell.x = targetX;
+            node.targetCell.y = targetY;
+            node.targetCell.width = targetWidth;
+            node.targetCell.height = targetHeight;
+            node.target = node.targetCell;
+            node.projectionParticipant = true;
+            node.hasHostFrame = true;
+            node.projectionPaintedByHost = false;
+            node.deltaCell.translateX = currentX - targetX;
+            node.deltaCell.translateY = currentY - targetY;
+            node.deltaCell.scaleX = currentWidth / targetWidth;
+            node.deltaCell.scaleY = currentHeight / targetHeight;
+            node.delta = node.deltaCell;
+        },
+        clearProjection(componentId) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'clearProjection');
+            if (node === undefined)
+                return;
+            node.delta = null;
+            node.hasHostFrame = false;
+            node.projectionPaintedByHost = false;
+        },
+        setBorderRadius(componentId, radius) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'setBorderRadius');
+            if (node === undefined)
+                return;
+            if (radius !== null && (!Number.isFinite(radius) || radius < 0)) {
+                reportStaleNode('projection-invalid-frame-input', componentId, 'setBorderRadius', 'not a finite non-negative number');
+                return;
+            }
+            if (node.borderRadius !== radius) {
+                // A CHANGED authored radius invalidates the stale correction (read-current ownership,
+                // REQ-LAYOUT-013 — seal r7, F5): the cell answers the new input, so publish the null
+                // sentinel until a valid correction exists for it — never the obsolete pair.
+                node.radiusCorrected = false;
+            }
+            node.borderRadius = radius;
+        },
+        project(visitor) {
+            // No orderDirty/reorder/sort edge here (packet §6): register() already performed the stable
+            // depth sort; unregister() removes by index, preserving the order.
+            // Index loop: for..of allocates an iterator per frame on Hermes (REQ-DRIVER-021).
+            for (let index = 0; index < ordered.length; index += 1) {
+                const node = ordered[index];
+                const parent = node.parentId === null ? undefined : nodes.get(node.parentId);
+                if (node.parentId !== null && parent === undefined) {
+                    // React passive cleanup is parent-first, so a child outliving its parent mid-teardown
+                    // is routine: skip the orphaned node for THIS frame (its output stays frozen at the
+                    // last valid value, and descendants keep the frozen inherited tree* values) and record
+                    // one orphaned-path report per id per episode — never a UI-thread throw (Phase 1.5).
+                    reportStaleNode('projection-orphaned-path', node.componentId, node.parentId, 'unregistered mid-teardown');
+                    continue;
+                }
+                const inheritedScaleX = parent?.treeScaleX ?? 1;
+                const inheritedScaleY = parent?.treeScaleY ?? 1;
+                const inheritedTranslateX = parent?.treeTranslateX ?? 0;
+                const inheritedTranslateY = parent?.treeTranslateY ?? 0;
+                const inheritedFrameCenterOffsetX = parent?.frameTreeCenterOffsetX ?? 0;
+                const inheritedFrameCenterOffsetY = parent?.frameTreeCenterOffsetY ?? 0;
+                const ownDelta = node.delta;
+                // Seal r9, F1: refuse undefined geometry BEFORE any division. A zero/non-finite
+                // inherited (accumulated) scale, a zero/non-finite current host-frame dimension, or a
+                // non-finite delta makes this node's output divisions undefined — at HEAD those
+                // produced Infinity/NaN outputs and published them into native shared transform values
+                // with no report (the review's zero-width-parent and nested-zero-current probes). The
+                // whole node freezes at its last valid finite state for this frame (skip the reset AND
+                // the recompute; descendants inherit the frozen — finite — tree* values) and records
+                // one escalated report per id per episode: every node here is registered and live by
+                // construction, so this is malformed live geometry, never a teardown race. A FINITE
+                // zero delta scale still publishes (a collapsed host is a legal measurement) — the
+                // descendant's inherited-zero check is what refuses it.
+                if (!Number.isFinite(inheritedScaleX) ||
+                    inheritedScaleX === 0 ||
+                    !Number.isFinite(inheritedScaleY) ||
+                    inheritedScaleY === 0 ||
+                    (node.hasHostFrame &&
+                        (!Number.isFinite(node.layoutCell.width) ||
+                            node.layoutCell.width === 0 ||
+                            !Number.isFinite(node.layoutCell.height) ||
+                            node.layoutCell.height === 0)) ||
+                    (ownDelta !== null &&
+                        (!Number.isFinite(ownDelta.translateX) ||
+                            !Number.isFinite(ownDelta.translateY) ||
+                            !Number.isFinite(ownDelta.scaleX) ||
+                            !Number.isFinite(ownDelta.scaleY)))) {
+                    reportStaleNode('projection-non-finite-output', node.componentId, 'project', 'zero/non-finite scale geometry');
+                    // The freeze preserves the TRANSFORM at its last valid state, but the radius publish
+                    // still follows read-current ownership (seal r7, F5): the cell answers only the
+                    // CURRENT authored radius — a changed or removed radius publishes the null sentinel
+                    // even on a frozen frame, never the obsolete corrected pair.
+                    node.output.borderRadius =
+                        node.borderRadius !== null && node.radiusCorrected ? node.radiusCell : null;
+                    continue;
+                }
+                // Outside host frames, radius is painted inside the raw projection transform before this
+                // node's correction is composed. Preserve that scale separately: `treeScale*output.scale` below is the
+                // effective scale inherited by descendants, whereas the radius must cancel the scale
+                // Reanimated actually applies to this host's border paint.
+                const rawTreeScaleX = node.projectionPaintedByHost
+                    ? (ownDelta?.scaleX ?? 1)
+                    : inheritedScaleX * (ownDelta?.scaleX ?? 1);
+                const rawTreeScaleY = node.projectionPaintedByHost
+                    ? (ownDelta?.scaleY ?? 1)
+                    : inheritedScaleY * (ownDelta?.scaleY ?? 1);
+                resetOutput(node);
+                if (node.hasHostFrame) {
+                    const target = node.target;
+                    if (target === null) {
+                        // ui-throw-ok: internal invariant — setHostFrame is the ONLY production writer of
+                        // hasHostFrame and it always assigns the target cell in the same edge; setTarget has
+                        // no production caller. A null target here is tree corruption (a programmer error),
+                        // never an operating error — the audited assert stays loud.
+                        throw new Error(`projection tree: '${node.componentId}' has a host frame without a target rect; host-frame projection requires coherent geometry.`);
+                    }
+                    // Reanimated's layout lane already paints `layoutCell` — the host's real current box,
+                    // parent-relative — for roots and nested hosts, which is the pin's nested layout box
+                    // (relativeTarget = mix(relativeTargetOrigin, relativeLayout, p)). The tree never
+                    // replays this host's FLIP or rescales its lane: the host keeps its painted size.
+                    // The one correction is positional, when the lane's own parent was committed by Yoga at
+                    // its final place inside a flying frame: the lane then rides that misplaced parent, so
+                    // the host is re-centred on its target centre in the ancestor's painted frame.
+                    if (parent?.committedInHostFrame === true) {
+                        node.output.translateX =
+                            target.x +
+                                target.width / 2 +
+                                inheritedFrameCenterOffsetX -
+                                (node.layoutCell.x + node.layoutCell.width / 2);
+                        node.output.translateY =
+                            target.y +
+                                target.height / 2 +
+                                inheritedFrameCenterOffsetY -
+                                (node.layoutCell.y + node.layoutCell.height / 2);
+                    }
+                }
+                else if (ownDelta !== null && node.projectionPaintedByHost) {
+                    // layoutId already paints its own FLIP transform in the host style. The tree's output
+                    // cancels only ancestor geometry; `tree*` below still publishes the live direct delta
+                    // to targetless descendants through every muggle node.
+                    node.output.translateX = -inheritedTranslateX / inheritedScaleX;
+                    node.output.translateY = -inheritedTranslateY / inheritedScaleY;
+                    node.output.scaleX = 1 / inheritedScaleX;
+                    node.output.scaleY = 1 / inheritedScaleY;
+                }
+                else if (ownDelta !== null) {
+                    // Deltas are expressed in viewport coordinates, but a nested host's transform runs
+                    // inside its parent's already-projected coordinate system. Convert every leg through
+                    // that parent frame: scale-only cancellation makes a targetless child drift by the
+                    // ancestor translation (the M3.5 two-leg registration failure).
+                    node.output.translateX = (ownDelta.translateX - inheritedTranslateX) / inheritedScaleX;
+                    node.output.translateY = (ownDelta.translateY - inheritedTranslateY) / inheritedScaleY;
+                    // A projecting child still renders inside its parent's transformed projection frame.
+                    // Cancel that inherited scale before applying the child's own box delta, exactly as a
+                    // targetless child does below. Without this, a child FLIP of 0.8 under a parent scale of
+                    // 0.5 renders at 0.4 and passes that distortion on to every descendant.
+                    node.output.scaleX = ownDelta.scaleX / inheritedScaleX;
+                    node.output.scaleY = ownDelta.scaleY / inheritedScaleY;
+                }
+                else if (node.projectionParticipant) {
+                    // A targetless node has no independently measured box delta. Under pure FLIP
+                    // (frameTreeCenterOffset == 0) its host Yoga position is already parent-relative, so
+                    // only counter-scale is faithful — replaying ancestor FLIP translation displaces the
+                    // flex centre (the M3.5 two-leg registration failure). Under native host-layout frames
+                    // the ancestor is paint-relative identity and half-size centre movement is carried in
+                    // `frameTreeCenterOffset`: Yoga still commits children against the TARGET box, so a
+                    // targetless (or non-interpolating) descendant freezes at the final centre unless it
+                    // receives that offset (Android residual ≈ (targetSize − currentSize)/2).
+                    node.output.scaleX = 1 / inheritedScaleX;
+                    node.output.scaleY = 1 / inheritedScaleY;
+                    node.output.translateX = inheritedFrameCenterOffsetX / inheritedScaleX;
+                    node.output.translateY = inheritedFrameCenterOffsetY / inheritedScaleY;
+                }
+                // Descendants inherit the transform that is actually rendered, not this node's raw box
+                // delta. A projecting child therefore carries its own scale forward after cancelling its
+                // ancestor's scale; an ordinary Motion intermediary remains an exact identity conduit.
+                node.treeScaleX = node.projectionPaintedByHost
+                    ? (ownDelta?.scaleX ?? 1)
+                    : inheritedScaleX * node.output.scaleX;
+                node.treeScaleY = node.projectionPaintedByHost
+                    ? (ownDelta?.scaleY ?? 1)
+                    : inheritedScaleY * node.output.scaleY;
+                node.treeTranslateX = node.projectionPaintedByHost
+                    ? (ownDelta?.translateX ?? 0)
+                    : inheritedTranslateX + inheritedScaleX * node.output.translateX;
+                node.treeTranslateY = node.projectionPaintedByHost
+                    ? (ownDelta?.translateY ?? 0)
+                    : inheritedTranslateY + inheritedScaleY * node.output.translateY;
+                if (node.hasHostFrame) {
+                    const target = node.target;
+                    if (target === null) {
+                        // ui-throw-ok: internal invariant — identical to the same guard earlier in this walk:
+                        // hasHostFrame implies an assigned target by construction (setHostFrame writes both
+                        // in one edge), so a null target here is a tree-corruption assert, never an
+                        // operating error.
+                        throw new Error(`projection tree: '${node.componentId}' lost its target rect during host-frame projection.`);
+                    }
+                    // Yoga commits this host's children against its TARGET box while the lane paints its
+                    // current box; the half-size change shifts a child's target centre into the painted
+                    // frame (500 → 324 yields -88), so an already-centred child remains centred. Ancestor
+                    // offsets are not added: this host's painted frame (lane plus output) already carries
+                    // them to everything inside it.
+                    node.frameTreeCenterOffsetX = (node.layoutCell.width - target.width) / 2;
+                    node.frameTreeCenterOffsetY = (node.layoutCell.height - target.height) / 2;
+                    node.committedInHostFrame = false;
+                }
+                else {
+                    // A muggle node carries ancestor centre movement untouched. Nodes without measured
+                    // host geometry remain on the targetless path above, but host-framed descendants still
+                    // correct through any number of ordinary Motion intermediaries.
+                    node.frameTreeCenterOffsetX = inheritedFrameCenterOffsetX;
+                    node.frameTreeCenterOffsetY = inheritedFrameCenterOffsetY;
+                    node.committedInHostFrame =
+                        parent !== undefined && (parent.hasHostFrame || parent.committedInHostFrame);
+                }
+                if (node.borderRadius !== null) {
+                    // The radius cancels the scale painted on this host so the on-screen corner stays the
+                    // authored circle (pin scale-border-radius.ts). A host frame is painted by Reanimated's
+                    // layout lane at its real current size, so its own box delta is NOT a painted scale:
+                    // only the inherited paint and this node's output transform are.
+                    const radiusScaleX = node.hasHostFrame
+                        ? inheritedScaleX * node.output.scaleX
+                        : rawTreeScaleX;
+                    const radiusScaleY = node.hasHostFrame
+                        ? inheritedScaleY * node.output.scaleY
+                        : rawTreeScaleY;
+                    if (!Number.isFinite(radiusScaleX) ||
+                        !Number.isFinite(radiusScaleY) ||
+                        radiusScaleX === 0 ||
+                        radiusScaleY === 0) {
+                        // A zero/non-finite accumulated scale makes the correction undefined — an OPERATING
+                        // condition (setHostFrame accepts a zero current width; only target dims are
+                        // validated), never an invariant. Report once per id per episode through the
+                        // stale-report channel and skip the correction, preserving the last valid radius —
+                        // a throw here escapes the UI frame (iOS AUTO SIGABRT seal r2, F3).
+                        reportStaleNode('projection-invalid-radius-correction', node.componentId, '', 'zero/non-finite accumulated tree scale');
+                    }
+                    else {
+                        writeCorrectedRadius(node.radiusCell, node.borderRadius, radiusScaleX, radiusScaleY);
+                        node.radiusCorrected = true;
+                    }
+                    // The sentinel law: publish the cell only once a valid correction exists — null
+                    // otherwise (authored radius retained); a skipped frame keeps the last valid state.
+                    node.output.borderRadius = node.radiusCorrected ? node.radiusCell : null;
+                }
+                const targetDeltaScaleX = ownDelta?.scaleX ?? 1;
+                const targetDeltaScaleY = ownDelta?.scaleY ?? 1;
+                node.output.targetDeltaScaleX = targetDeltaScaleX;
+                node.output.targetDeltaScaleY = targetDeltaScaleY;
+                node.output.treeScaleX =
+                    targetDeltaScaleX === 0 ? rawTreeScaleX : rawTreeScaleX / targetDeltaScaleX;
+                node.output.treeScaleY =
+                    targetDeltaScaleY === 0 ? rawTreeScaleY : rawTreeScaleY / targetDeltaScaleY;
+                visitor?.(node);
+            }
+        },
+        output(componentId) {
+            const node = nodes.get(componentId) ?? staleNode(componentId, 'output');
+            // A stale read returns the shared frozen identity output (last safe visual state), never a
+            // per-call allocation and never a throw (Phase 1.5).
+            if (node === undefined)
+                return STALE_IDENTITY_OUTPUT;
+            return node.output;
+        },
+        // alloc-ok: lifecycle-edge — a quiet frame returns the shared frozen empty array; draining
+        // actual reports is a bounded per-episode operation, never per-frame work.
+        drainStaleReports() {
+            if (staleReports.length === 0)
+                return EMPTY_STALE_REPORTS;
+            const drained = staleReports.slice();
+            staleReports.length = 0;
+            // The inter-drain window rolls (seal r10, F1): class counters, the overflow marker, and
+            // the per-id loss ledger all reset.
+            containedInRing = 0;
+            escalatedInRing = 0;
+            overflowPending = false;
+            overflowRecordIndex = -1;
+            droppedContainedCounts.clear();
+            droppedEscalatedCounts.clear();
+            extraContainedDrops = 0;
+            extraEscalatedDrops = 0;
+            return drained;
+        },
+    };
+}