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

package/dist/presence/controller.cjs

@@ -0,0 +1,657 @@
+"use strict";
+// SPEC-PRESENCE §2/§3 — the presence controller: mount authority, exit-target resolution, retention, settle
+// integration, cancellation continuity, and mode ordering. Diffs the child set each commit; retains a
+// dropped child with an exit until its exit resolves; makes every in-flight exit visible to the graph's
+// settle ledger; cancels an exit on key re-entry with value/velocity continuity; and orders enters vs exits
+// per `mode`. The exit is driven off the injected MotionGraph (`graph.animate` over the child's transition)
+// — the controller forks no animation math and imports no driver/React (SPEC-PRESENCE §1). Host-agnostic
+// (REQ-CORE-003): relative imports only.
+//
+// Modeling decision (deterministic interior): the controller owns ONE scalar EXIT-PROGRESS value per exiting
+// child (0 = fully present, 1 = fully exited), driven by the graph. This is a well-defined completion +
+// continuity signal for retention + settle; the per-property exit VALUES a child renders from the resolved
+// exit target are the child/component's concern (SPEC-PRESENCE §1 non-scope).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnimplementedPresenceModeError = void 0;
+exports.createPresenceController = createPresenceController;
+const component_1 = require("../component/index.cjs");
+const transition_1 = require("../component/transition.cjs");
+const timing_1 = require("../timing.cjs");
+const transition_2 = require("../transition.cjs");
+const subset_1 = require("../subset/index.cjs");
+const color_1 = require("../value-types/color.cjs");
+const machine_1 = require("./machine.cjs");
+// Default exit transition when a child declares none: a deterministic 300ms tween. Config, not a magic
+// literal in-line (Motion's own default is transition-dependent; the first spike pins this — refinable).
+// The ease is SPELLED rather than left to injection. Its value is the pin's NON-TRANSFORM per-key
+// default ease `[0.25, 0.1, 0.35, 1]` (motion-dom@12.42.2 utils/default-transitions.ts:35-48) —
+// NOT the `animateMotionValue` easeOut base, which the pin applies only to an AUTHORED transition.
+// (This constant is a flat tween for EVERY key, so it is only an approximation of the pin's
+// genuinely per-key default, which is a 500/25 spring for transform keys — see the
+// transition-dependent caveat above. The ease spelled here is correct for the non-transform case
+// this retention clock actually serves.) Leaving it unspelled made the curve depend on which
+// config builder happened to read it, and routing the exit lane through `toTimingLaneConfig`
+// (transition-default-selection F1) duly injected easeOut into the fallback.
+const DEFAULT_EXIT_TRANSITION = {
+    type: 'tween',
+    duration: 0.3,
+    ease: [0.25, 0.1, 0.35, 1],
+};
+// A transition with at least one DEFINED option (review major 62): an EMPTY `{}` (and one whose every
+// value is explicitly `undefined`) is NOT a transition — the property driver treats it as absent and
+// rides the count-aware default, so presence must too, else a `transition:{}` exit runs a default spring
+// while the property runs the pinned 800ms keyframes default (retention outlives the actual exit).
+function hasDefinedExitTransition(transition) {
+    if (transition === undefined)
+        return false;
+    return Reflect.ownKeys(transition).some((key) => typeof key === 'string' && transition[key] !== undefined);
+}
+function exitTransitionForProperty(transition, key) {
+    return transition === undefined ? undefined : (0, transition_1.resolveTransitionForKey)(transition, key);
+}
+// The keyframes generator's default duration when the transition carries none (`keyframes({duration=300})`
+// in pinned Motion). A tween's own default is the same; the presence progress is a 2-keyframe scalar.
+const DEFAULT_KEYFRAMES_MS = 300;
+// A COLOR keyframe array drives a [0,100] numeric PROGRESS spline (REQ-SPRING-013 / REQ-API-033): the RGBA
+// sequence is projected THROUGH that progress, so a color exit settles over the progress range, never the
+// color strings. Single-sourced with the driver's progress convention.
+const COLOR_PROGRESS_END = 100;
+// The exit-progress GeneratorFactory (review majors 57/62/65/4f7ac2b/fc0a71): the scalar 0→1 progress
+// completes exactly when the child's LONGEST exit property truly settles — driven off the property driver's
+// OWN generators, never a bounded settle probe (a pathological/underdamped spring runs past any frame cap,
+// and a probe that returns its cap as "settled" unmounts the child early — fails OPEN). A single property
+// rides its own 0→1 factory; multiple compose into a generator that is `done` only when EVERY sub-generator
+// is, tracking the least-advanced value so re-entry continuity still reads a real position.
+function exitProgressFactory(exit, childTransition, liveValues, resolvedExits) {
+    const subFactories = Object.entries(exit ?? {})
+        // transitionEnd is a settle-JUMP sub-target, not an animated property (T23 B3): it
+        // contributes no exit duration and never enters the progress composition.
+        .filter(([key]) => key !== 'transitionEnd')
+        .map(([key, value]) => propertyProgressFactory(key, value, childTransition, liveValues, resolvedExits));
+    if (subFactories.length === 0) {
+        // An empty/absent exit selects the transition's default/root consumer before falling back to
+        // the base default. A map must never cross into progressFactory unresolved.
+        const selectedTransition = childTransition === undefined ? undefined : (0, transition_1.resolveTransitionForKey)(childTransition, '');
+        return progressFactory(hasDefinedExitTransition(selectedTransition) ? selectedTransition : DEFAULT_EXIT_TRANSITION, 1);
+    }
+    if (subFactories.length === 1)
+        return subFactories[0];
+    return (seed) => {
+        const generators = subFactories.map((factory) => factory(seed));
+        const sample = { value: 0, velocity: 0, done: false }; // owned + reused (REQ-DRIVER-015)
+        return {
+            sample(elapsedMs) {
+                let minValue = Number.POSITIVE_INFINITY;
+                let velocityAtMin = 0;
+                let allDone = true;
+                for (const generator of generators) {
+                    const next = generator.sample(elapsedMs);
+                    if (!next.done)
+                        allDone = false;
+                    if (next.value < minValue) {
+                        minValue = next.value;
+                        velocityAtMin = next.velocity;
+                    }
+                }
+                sample.value = minValue;
+                sample.velocity = velocityAtMin;
+                sample.done = allDone;
+                return sample;
+            },
+        };
+    };
+}
+// One exit property's 0→1 progress GeneratorFactory. An ARRAY routes through the property driver's OWN
+// generator selection: an explicit / 2-keyframe-transform-default SPRING runs keyframes[0]→keyframes[last]
+// with the ABSOLUTE `restSpeed`, NORMALIZED to 0→1 so the progress is `done` WHEN the property is (over the
+// REAL distance, past any frame cap); everything else is the keyframes generator's config duration as a
+// bounded 0→1 tween. A null-first array receives its actual drop-time committed origin through the
+// host-supplied snapshot (REQ-PRESENCE-020); presence never reads a driver or substitutes a declaration.
+function propertyProgressFactory(key, value, childTransition, liveValues, resolvedExits) {
+    const propertyTransition = exitTransitionForProperty(childTransition, key);
+    const defined = hasDefinedExitTransition(propertyTransition);
+    if (Array.isArray(value)) {
+        const t = defined
+            ? propertyTransition
+            : (0, transition_2.getDefaultTransition)(key, value);
+        if (t.type === 'spring') {
+            const [from, to] = arraySpringEndpoints(key, value, liveValues?.[key], resolvedExits?.[key]);
+            const config = (0, component_1.toSpringConfig)(t);
+            const restSpeed = 'restSpeed' in t && t.restSpeed !== undefined ? t.restSpeed : undefined;
+            return normalizedFactory((0, transition_2.resolveSpringGenerator)(to, restSpeed !== undefined ? { ...config, restSpeed } : config), from, to);
+        }
+        const ms = (0, component_1.toKeyframesConfig)(t).duration ?? DEFAULT_KEYFRAMES_MS;
+        return (0, timing_1.timingGenerator)(1, { duration: ms });
+    }
+    // A SCALAR measure-length exit under an explicit spring (review 7ae34b29f081): a 0→1 unit
+    // progress spring is terminal-frame divergent from the property lane's measured px flight —
+    // measure the SAME host-resolved px endpoints (drop-time committed from, resolved to). An
+    // authored restDelta/restSpeed never reaches here — the exit lane refuses them loud (U7c /
+    // REQ-SPRING-014, the velocity precedent: value-units thresholds have no meaning on a
+    // normalized progress factory). A scalar ANGLE
+    // exit (review 4f95f4f8076a) resolves in degrees — from the committed snapshot to the parsed
+    // target, exact without a host.
+    if (typeof value === 'string' && !(0, color_1.isColor)(value) && defined) {
+        const t = propertyTransition;
+        if (t.type === 'spring') {
+            if (subset_1.UNIVERSAL_SUBSET.get(key)?.valueType === 'angle') {
+                const committedAngle = liveValues?.[key];
+                if (typeof committedAngle !== 'number') {
+                    throw new Error(`presence scalar angle exit '${key}' requires a numeric drop-time live committed value ` +
+                        `(received ${typeof committedAngle}; REQ-PRESENCE-020).`);
+                }
+                const to = angleExitEndpoint(key, value, undefined);
+                return normalizedFactory((0, transition_2.resolveSpringGenerator)(to, (0, component_1.toSpringConfig)(t)), committedAngle, to);
+            }
+            const endpoints = resolvedExits?.[key];
+            if (endpoints === undefined ||
+                endpoints.length !== 2 ||
+                !Number.isFinite(endpoints[0]) ||
+                !Number.isFinite(endpoints[1])) {
+                throw resolvedExitsRefusal(key);
+            }
+            return normalizedFactory((0, transition_2.resolveSpringGenerator)(endpoints[1], (0, component_1.toSpringConfig)(t)), endpoints[0], endpoints[1]);
+        }
+    }
+    // Scalar targets use the same count-aware per-property fallback as a two-keyframe property
+    // command. An empty selected bag is still a selected consumer, but it carries no executable
+    // option, so the property lane's default owns the retention clock (review fj96pq major 1).
+    const scalarTransition = defined
+        ? propertyTransition
+        : typeof value === 'number'
+            ? (0, transition_2.getDefaultTransition)(key, [0, value])
+            : DEFAULT_EXIT_TRANSITION;
+    if (typeof value === 'number' && scalarTransition.type === 'spring') {
+        const committed = liveValues?.[key];
+        if (typeof committed === 'number') {
+            return normalizedFactory((0, transition_2.resolveSpringGenerator)(value, (0, component_1.toSpringConfig)(scalarTransition)), committed, value);
+        }
+    }
+    return progressFactory(scalarTransition, 1);
+}
+// The (from,to) distance a 2-keyframe array spring covers, so the normalized progress settles WHEN the
+// property does (review major 7c54a3b). A COLOR array (its string elements parse as colors) drives a
+// [0,100] progress spline — measured over the progress range, never the RGBA strings (which have no
+// numeric distance). An ANGLE array (review 4f95f4f8076a, classified by the registry value type) is
+// NOT a length: angles resolve in their own unit, so same-unit DEGREE magnitudes are exact without a
+// host layout context (the subset normalizer converts rad → degrees). A measure-resolved LENGTH array
+// (reviews 02e2f855bfd5 + 2f3a8e6c1d90) is NOT a color array, and presence is context-free
+// (SPEC-PRESENCE §1) — so it measures the SAME resolved px endpoints the property lane flies, supplied
+// by the host at the removal boundary (the absolute restSpeed/restDelta thresholds make unit-magnitude
+// estimates terminal-frame-divergent). A NUMERIC array runs keyframes[0]→keyframes[last]; every
+// null-FIRST element (from-current, R8-F2) anchors at the HOST'S immutable removal-boundary snapshot
+// (REQ-PRESENCE-020), never a declared endpoint.
+function arraySpringEndpoints(key, value, committed, resolved) {
+    assertNullFirstLiveOriginKind(key, value, committed);
+    if (value.some((element) => typeof element === 'string' && (0, color_1.isColor)(element))) {
+        return [0, COLOR_PROGRESS_END];
+    }
+    if (subset_1.UNIVERSAL_SUBSET.get(key)?.valueType === 'angle') {
+        return [
+            angleExitEndpoint(key, value[0], committed),
+            angleExitEndpoint(key, value[value.length - 1], committed),
+        ];
+    }
+    if (value.some((element) => typeof element === 'string')) {
+        // The sync preflight proves the host's resolved endpoints before any mutation; this backstop
+        // keeps the same law on the factory path.
+        if (resolved === undefined)
+            throw resolvedExitsRefusal(key);
+        // Bounded ≥2 elements with null only at index 0 are proven by the preflight shape check.
+        const from = resolved[0] === null ? committed : resolved[0];
+        const to = resolved[resolved.length - 1];
+        if (typeof from !== 'number' || typeof to !== 'number')
+            throw resolvedExitsRefusal(key);
+        return [from, to];
+    }
+    const first = value[0];
+    const last = value[value.length - 1];
+    let from;
+    if (typeof first === 'number') {
+        from = first;
+    }
+    else {
+        if (typeof committed !== 'number') {
+            throw new Error(`presence null-first numeric exit '${key}' requires a numeric drop-time live committed value ` +
+                `(received ${typeof committed}; REQ-PRESENCE-020).`);
+        }
+        from = committed;
+    }
+    const to = typeof last === 'number' ? last : from;
+    return [from, to];
+}
+// One ANGLE exit endpoint in degrees (review 4f95f4f8076a): a number is itself (already degrees —
+// the engine-native angle encoding); a null from-current reads the committed degrees snapshot; a
+// deg/rad string normalizes through the ONE subset normalizer (rad → degrees). Angles need no host
+// layout context — same-unit degree magnitudes are exact, unlike measure-resolved lengths.
+function angleExitEndpoint(key, element, committed) {
+    if (typeof element === 'number')
+        return element;
+    if (element === null) {
+        if (typeof committed !== 'number') {
+            throw new Error(`presence null-first angle exit '${key}' requires a numeric drop-time live committed value ` +
+                `(received ${typeof committed}; REQ-PRESENCE-020).`);
+        }
+        return committed;
+    }
+    const entry = subset_1.UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        throw new Error(`presence angle exit '${key}' is not a universal-subset property (the boundary validation ` +
+            'should have refused it first).');
+    }
+    const normalized = (0, subset_1.normalizeCapability)(entry, element);
+    if (typeof normalized !== 'number') {
+        throw new Error(`presence angle exit '${key}' normalized to a non-numeric value (the registry classifies ` +
+            'it as angle; the boundary validation should have refused a non-angle string first).');
+    }
+    return normalized;
+}
+// The host-contract refusal for a measure-length exit missing its resolved px endpoints (review
+// 2f3a8e6c1d90) — one message shared by the sync preflight and the factory backstop.
+function resolvedExitsRefusal(property, childKey) {
+    const location = childKey === undefined ? '' : ` on '${childKey}'`;
+    return new Error(`presence length exit '${property}'${location} requires host-resolved px endpoints ` +
+        '(REQ-PRESENCE-020); the host must resolve measure-length exit arrays against the live ' +
+        'layout context at the removal boundary.');
+}
+// Validate one host-resolved endpoint array against its authored exit array (review 2f3a8e6c1d90):
+// same keyframe count, `null` only at index 0 (the from-current marker presence anchors at the
+// committed snapshot), finite numbers elsewhere.
+function assertResolvedExitEndpoints(property, authored, resolved, childKey) {
+    if (resolved === undefined ||
+        resolved.length !== authored.length ||
+        resolved.length < 2 ||
+        resolved.some((element, index) => (element === null && index !== 0) || (element !== null && !Number.isFinite(element)))) {
+        throw resolvedExitsRefusal(property, childKey);
+    }
+}
+// Validate the host snapshot as one atomic removal precondition. PresenceLiveValues is structurally
+// scalar (number|string), so existence alone cannot prove that the host value can seed this sequence.
+// The authored keyframes are already homogeneously validated at the supplying boundary; their scalar
+// member therefore defines the one legal live-origin kind.
+function assertNullFirstLiveOriginKind(property, value, committed, childKey) {
+    if (value[0] !== null)
+        return;
+    const location = childKey === undefined ? '' : ` on '${childKey}'`;
+    if (committed === undefined) {
+        throw new Error(`presence null-first exit '${property}'${location} has no drop-time live committed value ` +
+            '(REQ-PRESENCE-020); refusing to substitute a declared endpoint or zero.');
+    }
+    const expectedKind = value.some((element) => typeof element === 'string' && (0, color_1.isColor)(element))
+        ? 'string'
+        : 'number';
+    if (typeof committed !== expectedKind) {
+        const expected = expectedKind === 'number' ? 'numeric' : 'string';
+        throw new Error(`presence null-first ${expected} exit '${property}'${location} requires a ${expected} ` +
+            `drop-time live committed value (received ${typeof committed}; REQ-PRESENCE-020).`);
+    }
+}
+// Wrap a property generator (running `propFrom`→`propTo`) so its value/velocity read as a 0→1 PROGRESS, and
+// its `done` — the property's real settle — becomes the progress's. The seed carries the progress position
+// (0 fresh exit; the live value+velocity on cancel), mapped back into property space for continuity. A
+// zero-distance array is already at target — a 0ms tween settles it immediately.
+function normalizedFactory(propertyFactory, propFrom, propTo) {
+    const distance = propTo - propFrom;
+    if (distance === 0)
+        return (0, timing_1.timingGenerator)(1, { duration: 0 });
+    return (seed) => {
+        const generator = propertyFactory({
+            from: propFrom + seed.from * distance,
+            velocity: seed.velocity * distance,
+        });
+        const sample = { value: 0, velocity: 0, done: false }; // owned + reused
+        return {
+            sample(elapsedMs) {
+                const next = generator.sample(elapsedMs);
+                sample.value = (next.value - propFrom) / distance;
+                sample.velocity = next.velocity / distance;
+                sample.done = next.done;
+                return sample;
+            },
+        };
+    };
+}
+// Model a Target as a plain resolved-value record for the pure resolve/merge functions (mirrors COMPONENT).
+// Spreading `undefined` in an object literal is a safe no-op, so no `?? {}` fallback is needed.
+// transitionEnd is a settle-JUMP sub-target, never an animated value (T23 B3) — it must not enter
+// the presence value model.
+function asValues(target) {
+    const { transitionEnd: _transitionEnd, ...values } = { ...target };
+    return values;
+}
+// A progress factory driving the scalar exit-progress toward `target` (1 = exit, 0 = re-enter/cancel), over
+// the child's transition. Reuses the built SPRING/TIMING generators via the COMPONENT converters — no fork.
+// The graph seeds `from`/`velocity` from the live value on (re)animate, so a cancel is continuous.
+function progressFactory(transition, target) {
+    const t = transition ?? DEFAULT_EXIT_TRANSITION;
+    // transition-default-selection F1: the exit tween reads the ONE timing-lane config — the pin's
+    // `animateMotionValue` `ease: "easeOut"` base applies to presence exits too
+    // (motion-dom@12.42.2 motion-value.ts:45-49), so an exit tween with no authored ease runs
+    // [0, 0, 0.58, 1], never the generator default.
+    if (t.type === 'tween')
+        return (0, timing_1.timingGenerator)(target, (0, transition_1.toTimingLaneConfig)(t));
+    if (t.type === 'keyframes') {
+        // A count-aware keyframes default normalizes to a tween (a 2-keyframe scalar progress has one segment).
+        return (0, timing_1.timingGenerator)(target, {
+            duration: t.duration * 1000,
+            ...(t.ease !== undefined ? { ease: t.ease } : {}),
+        });
+    }
+    // A spring DefaultTransition carries `restSpeed` the public Transition cannot — thread it into the
+    // settle threshold (review major 65) so the progress quiesces WHEN the property spring does.
+    const config = (0, component_1.toSpringConfig)(t);
+    const restSpeed = 'restSpeed' in t && t.restSpeed !== undefined ? t.restSpeed : undefined;
+    return (0, transition_2.resolveSpringGenerator)(target, restSpeed !== undefined ? { ...config, restSpeed } : config);
+}
+// Re-entry is a scalar graph animation, but its transition is still authored per property. Resolve each
+// previously exiting property before constructing a generator; a map cannot cross this flat consumer. When
+// several properties are exiting, the progress remains until every reverse generator settles, mirroring the
+// exit-side composition above (the greatest remaining progress is authoritative on the way to 0).
+function reentryProgressFactory(childTransition, propertyKeys) {
+    if (propertyKeys.length === 0) {
+        const selected = childTransition === undefined ? undefined : (0, transition_1.resolveTransitionForKey)(childTransition, '');
+        return progressFactory(hasDefinedExitTransition(selected) ? selected : undefined, 0);
+    }
+    const factories = propertyKeys.map((key) => {
+        const selected = exitTransitionForProperty(childTransition, key);
+        return progressFactory(hasDefinedExitTransition(selected) ? selected : undefined, 0);
+    });
+    if (factories.length === 1)
+        return factories[0];
+    return (seed) => {
+        const generators = factories.map((factory) => factory(seed));
+        const sample = { value: seed.from, velocity: seed.velocity, done: false };
+        return {
+            sample(elapsedMs) {
+                let maxValue = Number.NEGATIVE_INFINITY;
+                let velocityAtMax = 0;
+                let allDone = true;
+                for (const generator of generators) {
+                    const next = generator.sample(elapsedMs);
+                    if (!next.done)
+                        allDone = false;
+                    if (next.value > maxValue) {
+                        maxValue = next.value;
+                        velocityAtMax = next.velocity;
+                    }
+                }
+                sample.value = maxValue;
+                sample.velocity = velocityAtMax;
+                sample.done = allDone;
+                return sample;
+            },
+        };
+    };
+}
+// Legacy typed error retained for public-surface compatibility. The former popLayout construction
+// refusal was removed in T24 P; the native presence layer now owns its layout composition.
+class UnimplementedPresenceModeError extends Error {
+    mode;
+    constructor(mode) {
+        super(`presence mode '${mode}' is not yet implemented (it depends on the layout subsystem); it fails loud rather than degrading.`);
+        this.name = 'UnimplementedPresenceModeError';
+        this.mode = mode;
+    }
+}
+exports.UnimplementedPresenceModeError = UnimplementedPresenceModeError;
+function createPresenceController(options) {
+    const { graph } = options;
+    const mode = options.mode ?? 'sync';
+    const initial = options.initial ?? true;
+    const onExitComplete = options.onExitComplete;
+    const ledger = (0, machine_1.createPresenceLedger)();
+    const tracked = new Map();
+    // 'wait' mode: entering children buffered until every exit resolves (REQ-PRESENCE-015).
+    const pendingEnters = new Map();
+    let firstCommitDone = false;
+    function exitingKeys() {
+        return ledger.trackedKeys().filter((k) => ledger.stateOf(k) === 'exiting');
+    }
+    // Commit the deferred ('wait' mode) entering children — called AFTER onExitComplete so enters land strictly
+    // after the exit callback (§3 Callback exactness / REQ-PRESENCE-015).
+    function flushPendingEnters() {
+        for (const [key, child] of pendingEnters) {
+            ledger.track(key);
+            tracked.set(key, { child });
+        }
+        pendingEnters.clear();
+    }
+    // The exiting set just emptied: fire onExitComplete exactly once, then commit any deferred enters.
+    function onExitingEmptied() {
+        onExitComplete?.();
+        flushPendingEnters();
+    }
+    // Resolve any exiting key whose exit animation has completed: exiting → removed, drop its record. Pull
+    // model — every query reconciles against the graph's advanced state. An OPEN manual authority (drop-time
+    // `deferred` or a mid-exit adoption) blocks resolution outright: a deferred exit has no animation and an
+    // adopted one must not resolve on animation completion alone — safeToRemove owns that leg
+    // (REQ-PRESENCE-001/014).
+    function reconcile() {
+        const before = exitingKeys();
+        if (before.length === 0)
+            return;
+        let anyResolved = false;
+        for (const key of before) {
+            const rec = tracked.get(key);
+            if (rec?.activity !== undefined)
+                continue;
+            if (rec?.animation?.done === true) {
+                ledger.send(key, 'resolve');
+                tracked.delete(key);
+                anyResolved = true;
+            }
+        }
+        if (anyResolved && exitingKeys().length === 0)
+            onExitingEmptied();
+    }
+    function beginExit(key, child, liveValues, resolvedExits) {
+        // Resolve the authored exit target ONCE at drop, held immutable for the exit's duration (§3).
+        // Live values seed only from-current origins/retention; they do not manufacture authored hold keys.
+        const resolvedExit = (0, component_1.resolveTarget)(asValues(child.animate), asValues(child.exit));
+        const progress = graph.motionValue(0);
+        // The progress completes when the child's LONGEST exit property truly settles — driven off the property
+        // driver's own generators (major 57: an omitted >2-keyframe exit rides its 800ms keyframes default, not
+        // the 300ms scalar default; fc0a71: a pathological spring runs to its real settle, never a probe cap;
+        // 7c54a3b: a null-FIRST numeric exit seeds its from-current distance from the committed `base` value;
+        // 2f3a8e6c1d90: a measure-length exit measures the host's RESOLVED px endpoints).
+        const animation = graph.animate(progress, exitProgressFactory(child.exit, child.transition, liveValues, resolvedExits));
+        tracked.set(key, { child, progress, animation, resolvedExit });
+        ledger.send(key, 'drop-with-exit');
+    }
+    function enterPresent(child) {
+        // First-commit enter suppression under initial={false} (REQ-PRESENCE-016). Presence owns the suppression
+        // DECISION; the enter transition itself is the component's concern (§1 non-scope), so no animation here.
+        const enterSuppressed = !firstCommitDone && initial === false;
+        ledger.track(child.key);
+        tracked.set(child.key, { child, enterSuppressed });
+    }
+    return {
+        syncChildren(children, liveValuesByKey, resolvedExitsByKey) {
+            const incoming = new Set(children.map((c) => c.key));
+            // Validate every outgoing null-first origin and length-exit endpoint supply before mutating
+            // any lifecycle record. A missing host snapshot/endpoints refuses the whole commit rather
+            // than partially dropping siblings (REQ-PRESENCE-020, review 2f3a8e6c1d90).
+            for (const key of ledger.trackedKeys()) {
+                if (incoming.has(key) || ledger.stateOf(key) !== 'present')
+                    continue;
+                const child = tracked.get(key)?.child;
+                // Family-6 major 370652a15b84: deferred + authored exit still begins the exit animation
+                // (consumer ∧ animation conjunction) — validate endpoints the same as the non-deferred path.
+                // Deferred without an exit target stays no-animation and needs no endpoint supply.
+                if (child?.exit === undefined)
+                    continue;
+                for (const [property, value] of Object.entries(child.exit)) {
+                    if (!Array.isArray(value)) {
+                        // A SCALAR measure-length exit under an explicit spring measures the host's resolved
+                        // px endpoints (review 7ae34b29f081); a scalar ANGLE exit measures its committed
+                        // degrees origin + parsed target instead (review 4f95f4f8076a). Bounded-duration
+                        // lanes need neither.
+                        if (typeof value === 'string' &&
+                            !(0, color_1.isColor)(value) &&
+                            exitTransitionForProperty(child.transition, property)?.type === 'spring') {
+                            if (subset_1.UNIVERSAL_SUBSET.get(property)?.valueType === 'angle') {
+                                const committedAngle = liveValuesByKey?.get(key)?.[property];
+                                if (typeof committedAngle !== 'number') {
+                                    throw new Error(`presence scalar angle exit '${property}' on '${key}' requires a numeric ` +
+                                        `drop-time live committed value (received ${typeof committedAngle}; ` +
+                                        'REQ-PRESENCE-020).');
+                                }
+                                continue;
+                            }
+                            const resolved = resolvedExitsByKey?.get(key)?.[property];
+                            if (resolved === undefined ||
+                                resolved.length !== 2 ||
+                                !Number.isFinite(resolved[0]) ||
+                                !Number.isFinite(resolved[1])) {
+                                throw resolvedExitsRefusal(property, key);
+                            }
+                        }
+                        continue;
+                    }
+                    if (value[0] === null) {
+                        assertNullFirstLiveOriginKind(property, value, liveValuesByKey?.get(key)?.[property], key);
+                    }
+                    if (value.some((element) => typeof element === 'string' && !(0, color_1.isColor)(element)) &&
+                        subset_1.UNIVERSAL_SUBSET.get(property)?.valueType !== 'angle') {
+                        assertResolvedExitEndpoints(property, value, resolvedExitsByKey?.get(key)?.[property], key);
+                    }
+                }
+            }
+            // 1) Drops first — so `mode:'wait'` enter-buffering below sees the exits started this commit.
+            for (const key of ledger.trackedKeys()) {
+                if (incoming.has(key))
+                    continue;
+                if (ledger.stateOf(key) !== 'present')
+                    continue; // already exiting/held → do NOT re-resolve (§3)
+                const child = tracked.get(key)?.child;
+                if (child?.deferred === true) {
+                    // Manual deferral (REQ-PRESENCE-014): retained until safeToRemove. Hold an open activity
+                    // handle so the graph stays unsettled while the manual exit is pending (REQ-PRESENCE-013).
+                    // Family-6 major 370652a15b84: when an authored exit is also present, start the exit
+                    // animation too — safeToRemove ∧ animation-complete is the retention conjunction
+                    // (same as mid-exit adoption). Deferred with no exit stays no-animation.
+                    if (child.exit !== undefined) {
+                        beginExit(key, child, liveValuesByKey?.get(key), resolvedExitsByKey?.get(key));
+                        const rec = tracked.get(key);
+                        if (rec !== undefined && rec.activity === undefined) {
+                            rec.activity = graph.registerActivity();
+                        }
+                    }
+                    else {
+                        tracked.set(key, { child, activity: graph.registerActivity() });
+                        ledger.send(key, 'drop-with-exit');
+                    }
+                }
+                else if (child?.exit !== undefined) {
+                    beginExit(key, child, liveValuesByKey?.get(key), resolvedExitsByKey?.get(key));
+                }
+                else {
+                    ledger.send(key, 'drop-immediate'); // no exit + no deferral → removed this commit (REQ-PRESENCE-011)
+                    tracked.delete(key);
+                }
+            }
+            // 2) Enters / cancels.
+            for (const child of children) {
+                const state = ledger.stateOf(child.key);
+                if (state === 'exiting') {
+                    // Re-entry cancels the exit (REQ-PRESENCE-012): retarget the live progress back toward present (0).
+                    // graph.animate reseeds from the live value+velocity (REQ-CORE-002/REQ-API-003) — continuity, no
+                    // jump, motion-value identity preserved. A deferred exit has no progress; just release + return.
+                    const prev = tracked.get(child.key);
+                    if (prev?.progress !== undefined) {
+                        // Install the re-entry animation BEFORE releasing an adopted manual hold (r7 finding
+                        // 4e1c3a8f72bd): when the scalar exit already completed under the hold, releasing
+                        // first crosses the graph into settled and resolves pending whenSettled() — a false
+                        // completion edge between the release and the re-animate (REQ-PRESENCE-012/-013).
+                        const enterAnim = graph.animate(prev.progress, reentryProgressFactory(child.transition, [
+                            ...new Set([...Object.keys(child.animate ?? {}), ...Object.keys(child.exit ?? {})]),
+                        ]));
+                        prev.activity?.release();
+                        tracked.set(child.key, { child, progress: prev.progress, animation: enterAnim });
+                    }
+                    else {
+                        prev?.activity?.release();
+                        tracked.set(child.key, { child });
+                    }
+                    ledger.send(child.key, 'cancel');
+                }
+                else if (state === 'present') {
+                    const rec = tracked.get(child.key);
+                    if (rec !== undefined)
+                        rec.child = child; // refresh last-seen props
+                }
+                else if (pendingEnters.has(child.key)) {
+                    pendingEnters.set(child.key, child); // already deferred — refresh
+                }
+                else if (mode === 'wait' && exitingKeys().length > 0) {
+                    pendingEnters.set(child.key, child); // defer until exits resolve (REQ-PRESENCE-015)
+                }
+                else {
+                    enterPresent(child);
+                }
+            }
+            firstCommitDone = true;
+            reconcile();
+        },
+        mountedKeys() {
+            reconcile();
+            return ledger.trackedKeys(); // ledger holds only present + retained-exiting keys (pending enters excluded)
+        },
+        stateOf(key) {
+            reconcile();
+            return ledger.stateOf(key);
+        },
+        isPresent(key) {
+            reconcile();
+            return ledger.stateOf(key) === 'present';
+        },
+        safeToRemove(key) {
+            // Resolve a manual (deferred) exit; idempotent — a no-op once the key has resolved or re-entered.
+            reconcile();
+            if (ledger.stateOf(key) !== 'exiting')
+                return;
+            const rec = tracked.get(key);
+            if (rec !== undefined) {
+                const heldAuthority = rec.activity !== undefined;
+                rec.activity?.release(); // release the manual authority handle
+                delete rec.activity;
+                // A mid-exit adoption composes with the exit animation as a CONJUNCTION (REQ-PRESENCE-001):
+                // with the manual authority now released, a still-running animation keeps the key retained
+                // and reconcile resolves it at completion. Without adopted authority this call stays the
+                // external override it has always been (immediate resolve), and a no-animation deferral has
+                // nothing else to await.
+                if (heldAuthority && rec.animation !== undefined && rec.animation.done !== true)
+                    return;
+            }
+            ledger.send(key, 'resolve');
+            tracked.delete(key);
+            if (exitingKeys().length === 0)
+                onExitingEmptied();
+        },
+        deferExit(key) {
+            // Mid-exit manual-authority adoption (see types.ts): the consumer registered only after the
+            // drop commit, so the `deferred` flag could not have carried its authority into this record.
+            reconcile();
+            if (ledger.stateOf(key) !== 'exiting')
+                return;
+            const rec = tracked.get(key);
+            // Idempotent: a record already holding authority (drop-time deferral or a prior adoption)
+            // must not stack a second unreleasable handle.
+            if (rec === undefined || rec.activity !== undefined)
+                return;
+            rec.activity = graph.registerActivity();
+        },
+        resolvedExitTarget(key) {
+            return tracked.get(key)?.resolvedExit;
+        },
+        enterSuppressed(key) {
+            return tracked.get(key)?.enterSuppressed ?? false;
+        },
+        exitProgress(key) {
+            return tracked.get(key)?.progress?.get();
+        },
+        exitVelocity(key) {
+            return tracked.get(key)?.progress?.getVelocity();
+        },
+    };
+}

package/dist/presence/controller.d.cts

@@ -0,0 +1,6 @@
+import type { PresenceController, PresenceControllerOptions, PresenceMode } from "./types.cjs";
+export declare class UnimplementedPresenceModeError extends Error {
+    readonly mode: PresenceMode;
+    constructor(mode: PresenceMode);
+}
+export declare function createPresenceController(options: PresenceControllerOptions): PresenceController;