react-native-gtkx 0.2.0-alpha.2 → 0.3.0-alpha.1

package/dist/reanimated-compat/updater-animations.js

@@ -0,0 +1,273 @@
+import { animationSignature, buildAnimation, isAnimationSpec, targetOf, } from "./animation";
+// How far behind its own animation a property this platform will not drive at
+// frame rate is allowed to fall.
+//
+// The settle alone is not an answer, and `@gorhom/bottom-sheet` MOUNTING is
+// the measurement that says so. Its content mask is bounded by an animated
+// `height` whose target is derived from the sheet's own POSITION, so every
+// frame of the opening spring re-aims it — 37 re-aims over 673 ms, each
+// cancelling the last, so not one of them a settle — and then a further
+// 677 ms for the final spring to converge. Measured on the gallery's
+// `upstream-bottom-sheet` screen: the seed was 95.9 px (gorhom's
+// `animatedContentHeightMax` was still 0 on the mapper run that first
+// produced a `height` at all, and the real 832 px arrived 27 ms later, by
+// which time the key already had an entry and a moving target is an animation
+// rather than a seed), and `height` reached Yoga exactly TWICE in the whole
+// mount: 95.9 px at once, 954.6 px 1378 ms later. For 1.38 s the mask was a
+// tenth of its size, the list inside it had no bounded parent, and it mounted
+// zero of its 18 rows. Correct by the settle rule and plainly wrong to
+// anybody opening the screen.
+//
+// So the value lands on a cadence as well. 100 ms because that is the bound
+// under which a change still reads as immediate, and because it bounds the
+// cost by the CLOCK rather than by the animation: at most ten renders a
+// second per animated key, against sixty frames. The same mount now lands the
+// mask at 266 → 546 → 649 → 731 → 792 → 832 → 896 → 939 → 951 → 954 px before
+// settling at 954.6 — the shape the animation has, at a tenth of its rate —
+// with the first at ~100 ms rather than 1.38 s.
+//
+// What it costs, both halves measured in one `spike/core-exports` run on the
+// same machine: 4 settles and 4 renders against 290 refused-property frames
+// before, 4 settles + 38 landings and 42 renders against 294 after. Still an
+// order of magnitude under the per-frame layout write the refusal exists to
+// avoid, and no longer a promise that may never come due.
+// docs/research/animated-size.md §10.
+const LANDING_INTERVAL_MS = 100;
+// A landing that cannot move a widget is a render for nothing: GTK allocates
+// whole pixels, so a sub-pixel step changes no committed geometry. It is what
+// keeps a long animation over a short distance from spending ten renders a
+// second to travel one pixel — gorhom's `paddingBottom` crosses 26 px over the
+// same 1.38 s and lands 8 times, not 13.
+const LANDING_EPSILON = 1;
+/**
+ * @param publish Receives the updater's object with every animated key
+ *   replaced by a number. Called once per mapper run and once per animation
+ *   frame.
+ * @param onSettled Called when an animation on `key` reaches its target on its
+ *   own (never when it is cancelled or replaced). The style layer uses it for
+ *   the properties it refuses to drive at frame rate, whose contract is that
+ *   the value lands on the next React render — without it, that promise is
+ *   only kept when something else happens to re-render.
+ * @param onLanding Called when `key`'s current value has to reach React
+ *   without its animation having reached a target. Two occasions: while an
+ *   animation runs, at most once per `LANDING_INTERVAL_MS` and only when the
+ *   value has moved far enough to change a committed layout (the cadence); and
+ *   when a plain number REPLACES a running animation, where upstream cancels
+ *   and snaps and a refused property cannot snap without a render. The snap is
+ *   deliberately not rate-limited — it is a state change rather than a step of
+ *   one, it happens once per mapper run that flips the key rather than once per
+ *   frame, and upstream pushes exactly the same number of `updateProps` for it.
+ *   Same job as `onSettled` and the same handling at the call site; it is a
+ *   separate callback because a settle and a value that has merely got to be
+ *   published are different claims, and only the first one is a promise kept.
+ *   Omit it and both cost nothing at all — a caller with no refused properties
+ *   (`useAnimatedProps`) does.
+ */
+export const createUpdaterAnimations = (engine, publish, onSettled, onLanding) => {
+    const entries = new Map();
+    // The clock the animations themselves run on, never `Date` — the whole
+    // layer is driven by one injected scheduler so a test can take it
+    // (components/frame-scheduler.ts). A driver that only has frame stamps and
+    // no off-frame `now` cannot have a cadence, and falls back to the settle.
+    const hasClock = engine.scheduler.now !== undefined;
+    const now = () => engine.scheduler.now?.() ?? 0;
+    let lastSource = null;
+    // A frame of one key's animation republishes the WHOLE object, which
+    // re-enters `resolve`. The guard keeps that from restarting anything: the
+    // run in progress publishes the final state itself.
+    let resolving = false;
+    /**
+     * @param replacement The plain value that took the key over, or `undefined`
+     *   when the key left the updater's result altogether.
+     *
+     *   A number here owes the caller a render, and `landedValue` is what decides
+     *   it: that field is this module's whole model of what REACT holds for the
+     *   key, and everything since the last landing or settle went to the widget
+     *   without passing through React. So a plain number that differs from it has
+     *   to be published or it never arrives — on a refused property the snap IS
+     *   a render, and neither the cadence nor a settle is ever going to come for
+     *   it. Compared without the cadence's one-pixel epsilon and for the same
+     *   reason a settle ignores it: this is a resting value rather than a step
+     *   towards one, and there is nothing after it to correct a skipped render.
+     *
+     *   Not asked for otherwise. A key that VANISHED, or one replaced by a
+     *   percentage or a colour, changes the style's SHAPE, and the caller already
+     *   pays exactly one render for that (hooks.ts); a value equal to the one
+     *   React already has is a render for nothing.
+     */
+    const drop = (key, replacement) => {
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        entries.delete(key);
+        entry.running?.stop();
+        entry.driver.removeListener(entry.listenerId);
+        if (typeof replacement === "number" &&
+            !Object.is(replacement, entry.landedValue)) {
+            onLanding?.(key);
+        }
+    };
+    const republish = () => {
+        if (resolving || lastSource === null) {
+            return;
+        }
+        // No previous result on a frame: nothing can START an animation here — the
+        // source has not changed — so there is nothing to look a starting point up
+        // for.
+        publish(resolve(lastSource, null));
+    };
+    /**
+     * Records that `key`'s current value is the one React now holds. Called
+     * wherever a render is asked for, so the cadence is measured from the last
+     * value React was actually given rather than from the last frame.
+     */
+    const markLanded = (entry) => {
+        entry.landedValue = entry.driver.__getValue();
+        entry.landedAt = now();
+    };
+    /** The cadence: see LANDING_INTERVAL_MS. */
+    const considerLanding = (key, value) => {
+        if (onLanding === undefined || !hasClock) {
+            return;
+        }
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        if (now() - entry.landedAt < LANDING_INTERVAL_MS) {
+            return;
+        }
+        if (Math.abs(value - entry.landedValue) < LANDING_EPSILON) {
+            return;
+        }
+        markLanded(entry);
+        onLanding(key);
+    };
+    /** Aims `entry`'s driver at `spec`, replacing whatever it was running. */
+    const start = (key, entry, spec, signature) => {
+        entry.signature = signature;
+        entry.running?.stop();
+        const animation = buildAnimation(engine, entry.driver, spec);
+        entry.running = animation;
+        animation.start((result) => {
+            if (entry.running === animation) {
+                entry.running = null;
+            }
+            // `finished` only: a restart stops the previous animation, and reporting
+            // that as a settle would publish through React on every frame the target
+            // moves, which is the cost the refusal exists to avoid. A restart is
+            // still covered — the cadence above is what carries a target that keeps
+            // moving, and it does not care whose animation the frames belong to.
+            if (result.finished) {
+                markLanded(entry);
+                onSettled?.(key);
+            }
+        });
+        return entry;
+    };
+    /**
+     * Where an animation that is starting has to start FROM, for a key that was
+     * not animating a moment ago: the value the PREVIOUS updater result held for
+     * it, and only when that is a real number.
+     *
+     * This is `prepareAnimation(…, oldValues[key])` and nothing more —
+     * `oldValues` is `state.last`, upstream's copy of the whole previous updater
+     * result — so the second of the header's three rules costs no bookkeeping at
+     * all. The previous result is an object this module was already holding for
+     * `republish`; reading one key out of it is the entire mechanism, and the
+     * entry does not have to carry a value across runs or outlive its animation.
+     *
+     * Numbers only, and `undefined` for everything else, which lines up with
+     * upstream at both ends: a key that was absent has no starting point (its
+     * `oldValues[key]` is `undefined`, and the animation's own `current` — the
+     * target — stands), and a percentage string or a colour is not something the
+     * numeric drivers here can start at.
+     */
+    const startingPoint = (previous, key) => {
+        const value = previous?.[key];
+        return typeof value === "number" && Number.isFinite(value)
+            ? value
+            : undefined;
+    };
+    const ensure = (key, spec, previous) => {
+        const signature = animationSignature(spec);
+        const existing = entries.get(key);
+        if (existing !== undefined) {
+            return existing.signature === signature
+                ? existing
+                : start(key, existing, spec, signature);
+        }
+        const from = startingPoint(previous, key);
+        // The driver is seeded before anything is built on purpose: a spring reads
+        // its origin off the value it is given (animation.ts), so this IS where
+        // "animate from the old number" happens.
+        const driver = new engine.api.Value(from ?? targetOf(spec) ?? 0);
+        const entry = {
+            driver,
+            listenerId: driver.addListener(({ value }) => {
+                republish();
+                considerLanding(key, value);
+            }),
+            signature,
+            running: null,
+            // Whichever branch follows, React's copy of this key is the value the
+            // driver starts at: a seed changes the style's SHAPE and the caller
+            // already pays one render for that (hooks.ts), and a starting point that
+            // came out of the previous result is a number React was already handed.
+            // So the cadence starts here either way.
+            landedValue: driver.__getValue(),
+            landedAt: now(),
+        };
+        entries.set(key, entry);
+        // Nothing to animate from: seeded at the target and not started at all,
+        // which is the first of the header's three rules.
+        return from === undefined ? entry : start(key, entry, spec, signature);
+    };
+    const resolve = (source, previous) => {
+        resolving = true;
+        try {
+            let resolved = null;
+            for (const key of Object.keys(source)) {
+                const value = source[key];
+                if (!isAnimationSpec(value)) {
+                    // A plain value replacing an animation cancels it and snaps, exactly
+                    // as an assignment to a shared value does and exactly as upstream's
+                    // `delete animations[key]` + `updateProps` in the same run does. The
+                    // number itself is published below, by identity.
+                    drop(key, value);
+                    continue;
+                }
+                resolved ??= { ...source };
+                resolved[key] = ensure(key, value, previous).driver.__getValue();
+            }
+            for (const key of [...entries.keys()]) {
+                if (!(key in source)) {
+                    drop(key, undefined);
+                }
+            }
+            return resolved ?? source;
+        }
+        finally {
+            resolving = false;
+        }
+    };
+    return {
+        run(source) {
+            // `state.last`, upstream's name for it: the result this run's animations
+            // measure themselves against. Held for one run only, and it was already
+            // being held.
+            const previous = lastSource;
+            lastSource = source;
+            publish(resolve(source, previous));
+        },
+        dispose() {
+            for (const key of [...entries.keys()]) {
+                // Nothing is owed a render: the component is going away.
+                drop(key, undefined);
+            }
+            lastSource = null;
+        },
+    };
+};
+//# sourceMappingURL=updater-animations.js.map

package/dist/reanimated-compat/updater-animations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater-animations.js","sourceRoot":"","sources":["../../src/reanimated-compat/updater-animations.ts"],"names":[],"mappings":"AA+EA,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,QAAQ,GAGT,MAAM,aAAa,CAAA;AAKpB,8EAA8E;AAC9E,iCAAiC;AACjC,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,wEAAwE;AACxE,wEAAwE;AACxE,qEAAqE;AACrE,iEAAiE;AACjE,sEAAsE;AACtE,0EAA0E;AAC1E,8EAA8E;AAC9E,4EAA4E;AAC5E,4EAA4E;AAC5E,8EAA8E;AAC9E,uEAAuE;AACvE,8BAA8B;AAC9B,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,wEAAwE;AACxE,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,gDAAgD;AAChD,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,0DAA0D;AAC1D,sCAAsC;AACtC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAE/B,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,yCAAyC;AACzC,MAAM,eAAe,GAAG,CAAC,CAAA;AAwBzB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,MAAuB,EACvB,OAA0C,EAC1C,SAAiC,EACjC,SAAiC,EACd,EAAE;IACrB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAA;IACxC,uEAAuE;IACvE,kEAAkE;IAClE,2EAA2E;IAC3E,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,SAAS,CAAA;IACnD,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAA;IACvD,IAAI,UAAU,GAAyB,IAAI,CAAA;IAC3C,qEAAqE;IACrE,0EAA0E;IAC1E,oDAAoD;IACpD,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,WAAoB,EAAQ,EAAE;QACvD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAM;QACR,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACnB,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAA;QACrB,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QAC7C,IACE,OAAO,WAAW,KAAK,QAAQ;YAC/B,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,EAC1C,CAAC;YACD,SAAS,EAAE,CAAC,GAAG,CAAC,CAAA;QAClB,CAAC;IACH,CAAC,CAAA;IAED,MAAM,SAAS,GAAG,GAAS,EAAE;QAC3B,IAAI,SAAS,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACrC,OAAM;QACR,CAAC;QACD,2EAA2E;QAC3E,2EAA2E;QAC3E,OAAO;QACP,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAA;IACpC,CAAC,CAAA;IAED;;;;OAIG;IACH,MAAM,UAAU,GAAG,CAAC,KAAY,EAAQ,EAAE;QACxC,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;QAC7C,KAAK,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAA;IACxB,CAAC,CAAA;IAED,4CAA4C;IAC5C,MAAM,eAAe,GAAG,CAAC,GAAW,EAAE,KAAa,EAAQ,EAAE;QAC3D,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,OAAM;QACR,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAM;QACR,CAAC;QACD,IAAI,GAAG,EAAE,GAAG,KAAK,CAAC,QAAQ,GAAG,mBAAmB,EAAE,CAAC;YACjD,OAAM;QACR,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,eAAe,EAAE,CAAC;YAC1D,OAAM;QACR,CAAC;QACD,UAAU,CAAC,KAAK,CAAC,CAAA;QACjB,SAAS,CAAC,GAAG,CAAC,CAAA;IAChB,CAAC,CAAA;IAED,0EAA0E;IAC1E,MAAM,KAAK,GAAG,CACZ,GAAW,EACX,KAAY,EACZ,IAAmB,EACnB,SAAiB,EACV,EAAE;QACT,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;QAC3B,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAA;QACrB,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAC5D,KAAK,CAAC,OAAO,GAAG,SAAS,CAAA;QACzB,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE;YACzB,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAChC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;YACtB,CAAC;YACD,yEAAyE;YACzE,yEAAyE;YACzE,qEAAqE;YACrE,wEAAwE;YACxE,qEAAqE;YACrE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,UAAU,CAAC,KAAK,CAAC,CAAA;gBACjB,SAAS,EAAE,CAAC,GAAG,CAAC,CAAA;YAClB,CAAC;QACH,CAAC,CAAC,CAAA;QACF,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,aAAa,GAAG,CACpB,QAA8B,EAC9B,GAAW,EACS,EAAE;QACtB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAA;QAC7B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YACxD,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,SAAS,CAAA;IACf,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,CACb,GAAW,EACX,IAAmB,EACnB,QAA8B,EACvB,EAAE;QACT,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACjC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC,SAAS,KAAK,SAAS;gBACrC,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;QAC3C,CAAC;QACD,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;QACzC,2EAA2E;QAC3E,wEAAwE;QACxE,yCAAyC;QACzC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QAChE,MAAM,KAAK,GAAU;YACnB,MAAM;YACN,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;gBAC3C,SAAS,EAAE,CAAA;gBACX,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC7B,CAAC,CAAC;YACF,SAAS;YACT,OAAO,EAAE,IAAI;YACb,sEAAsE;YACtE,oEAAoE;YACpE,yEAAyE;YACzE,wEAAwE;YACxE,yCAAyC;YACzC,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE;YAChC,QAAQ,EAAE,GAAG,EAAE;SAChB,CAAA;QACD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACvB,wEAAwE;QACxE,kDAAkD;QAClD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IACxE,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,CACd,MAAqB,EACrB,QAA8B,EACf,EAAE;QACjB,SAAS,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC;YACH,IAAI,QAAQ,GAAyB,IAAI,CAAA;YACzC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;gBACzB,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC5B,qEAAqE;oBACrE,oEAAoE;oBACpE,qEAAqE;oBACrE,iDAAiD;oBACjD,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;oBAChB,SAAQ;gBACV,CAAC;gBACD,QAAQ,KAAK,EAAE,GAAG,MAAM,EAAE,CAAA;gBAC1B,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;YAClE,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;oBACrB,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;gBACtB,CAAC;YACH,CAAC;YACD,OAAO,QAAQ,IAAI,MAAM,CAAA;QAC3B,CAAC;gBAAS,CAAC;YACT,SAAS,GAAG,KAAK,CAAA;QACnB,CAAC;IACH,CAAC,CAAA;IAED,OAAO;QACL,GAAG,CAAC,MAAM;YACR,yEAAyE;YACzE,wEAAwE;YACxE,cAAc;YACd,MAAM,QAAQ,GAAG,UAAU,CAAA;YAC3B,UAAU,GAAG,MAAM,CAAA;YACnB,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;QACpC,CAAC;QACD,OAAO;YACL,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACtC,yDAAyD;gBACzD,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;YACtB,CAAC;YACD,UAAU,GAAG,IAAI,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC,CAAA","sourcesContent":["// An animation returned FROM a style or props updater, which is the shape the\n// documentation of `useAnimatedStyle` is written in:\n//\n//   const style = useAnimatedStyle(() => ({\n//     height: withSpring(open.value ? 320 : 0),\n//   }))\n//\n// Assigning an animation to a shared value has always worked here\n// (mutable.ts). Returning one from an updater did not, and it failed the way\n// this repo likes least: silently. `with*` builders return a MARKED DESCRIPTOR\n// outside the initial run (animation.ts), the style layer's leaf test is\n// `typeof value === \"number\"`, and a descriptor is an object — so the property\n// was neither driven nor written nor warned about. It simply sat in the style\n// as `{kind: \"spring\", toValue: 543.4, …}`.\n//\n// Found by `spike/core-exports`, not by reading: `@gorhom/bottom-sheet` bounds\n// its scrollable with `height: animate({point: …})` from `useAnimatedStyle`,\n// and the probe's report that the height \"is not reaching the Yoga node\" was\n// true for a reason one layer earlier than layout — the height was never a\n// number on this platform at all. docs/research/animated-size.md §9.\n//\n// WHAT THIS MODULE IS. One running animation per key, on the platform's own\n// `Animated.Value` and the platform's one frame scheduler — the same\n// `buildAnimation` a shared value uses, so `withTiming`, `withSpring`,\n// `withDelay`, `withSequence`, `withRepeat`, `withDecay` and `withClamp` all\n// arrive here already implemented. The updater's object is republished with\n// each animated key replaced by the number its animation is currently at, and\n// a frame of a running animation costs no React render — it goes down exactly\n// the path a shared value written every frame goes down.\n//\n// THREE RULES, and all three are upstream's — every one of them read out of\n// `hook/useAnimatedStyle.ts`'s `styleUpdater`/`prepareAnimation` rather than\n// inferred from behaviour:\n//\n//  - A key APPEARING for the first time is seeded at the animation's target\n//    rather than animated to it. There is nothing to animate from, and it is\n//    the same collapse `initialUpdaterRun` performs on the updater's first\n//    run. Upstream reaches the same place from the other direction: its\n//    `prepareAnimation` starts at `oldValues[key]`, which for a key that was\n//    not in the last result is `undefined` and leaves the animation's own\n//    `current` — its target — standing.\n//  - A key whose previous result held a PLAIN NUMBER animates from that\n//    number. `oldValues` is `state.last`, the whole previous updater result\n//    kept raw, and `prepareAnimation`'s last branch is one line with the\n//    comment already on it: `// previously it was a plain value, just set it\n//    as starting point`. So `height: open.value ? withTiming(200) : 100` runs\n//    100 → 200, and the idiom people actually write — snap shut, open\n//    smoothly — animates. It did not here: the key was dropped when it held a\n//    number and re-seeded when it next held an animation, so the seed went\n//    straight to 200 and the animation never played at all. Silently, which\n//    is the failure this repo ranks worst.\n//  - A re-run that produces an EQUIVALENT animation does not restart it. A\n//    mapper re-runs whenever anything it read changed, which for a real app is\n//    many times a second, and rebuilding the spring each time would leave it\n//    crawling. Equivalence is the descriptor's target and shape\n//    (`animationSignature`), not object identity — every run builds a fresh\n//    object.\n//\n// AND THE REVERSE DIRECTION, animation → plain number, which is upstream's\n// too and is not the mirror image of the second rule: `styleUpdater`'s\n// non-animated branch does `delete animations[key]` and pushes the value\n// through `updateProps` in the SAME run, so the animation is cancelled — no\n// callback, no settle — and the number lands at once. It does not ease back.\n// The only thing this platform has to add is the render a refused property\n// needs to land at all, because \"at once\" through React is still a render (see\n// `onLanding`).\n//\n// WHERE THIS DIFFERS FROM UPSTREAM, said out loud: a restart picks the\n// animation up at the value it is currently at, with the velocity the new\n// descriptor asks for, where upstream also carries the previous animation's\n// VELOCITY across. For a target that moves once that is the same animation;\n// for a target that moves every frame ours is slightly more damped.\n//\n// AND THE CADENCE, the one rule here that is ours rather than upstream's — see\n// LANDING_INTERVAL_MS. It exists because none of the above is enough for a\n// property whose frames this platform refuses to write: for those, the value\n// only exists on screen at whatever the last React render committed, and \"the\n// render at the settle\" turned out to be arbitrarily far away.\nimport type { AnimatedValue, CompositeAnimation } from \"../animated/index\"\nimport {\n  animationSignature,\n  buildAnimation,\n  isAnimationSpec,\n  targetOf,\n  type AnimationEngine,\n  type AnimationSpec,\n} from \"./animation\"\n\n/** What an updater returns: a style object, or a props object. */\nexport type UpdaterObject = Record<string, unknown>\n\n// How far behind its own animation a property this platform will not drive at\n// frame rate is allowed to fall.\n//\n// The settle alone is not an answer, and `@gorhom/bottom-sheet` MOUNTING is\n// the measurement that says so. Its content mask is bounded by an animated\n// `height` whose target is derived from the sheet's own POSITION, so every\n// frame of the opening spring re-aims it — 37 re-aims over 673 ms, each\n// cancelling the last, so not one of them a settle — and then a further\n// 677 ms for the final spring to converge. Measured on the gallery's\n// `upstream-bottom-sheet` screen: the seed was 95.9 px (gorhom's\n// `animatedContentHeightMax` was still 0 on the mapper run that first\n// produced a `height` at all, and the real 832 px arrived 27 ms later, by\n// which time the key already had an entry and a moving target is an animation\n// rather than a seed), and `height` reached Yoga exactly TWICE in the whole\n// mount: 95.9 px at once, 954.6 px 1378 ms later. For 1.38 s the mask was a\n// tenth of its size, the list inside it had no bounded parent, and it mounted\n// zero of its 18 rows. Correct by the settle rule and plainly wrong to\n// anybody opening the screen.\n//\n// So the value lands on a cadence as well. 100 ms because that is the bound\n// under which a change still reads as immediate, and because it bounds the\n// cost by the CLOCK rather than by the animation: at most ten renders a\n// second per animated key, against sixty frames. The same mount now lands the\n// mask at 266 → 546 → 649 → 731 → 792 → 832 → 896 → 939 → 951 → 954 px before\n// settling at 954.6 — the shape the animation has, at a tenth of its rate —\n// with the first at ~100 ms rather than 1.38 s.\n//\n// What it costs, both halves measured in one `spike/core-exports` run on the\n// same machine: 4 settles and 4 renders against 290 refused-property frames\n// before, 4 settles + 38 landings and 42 renders against 294 after. Still an\n// order of magnitude under the per-frame layout write the refusal exists to\n// avoid, and no longer a promise that may never come due.\n// docs/research/animated-size.md §10.\nconst LANDING_INTERVAL_MS = 100\n\n// A landing that cannot move a widget is a render for nothing: GTK allocates\n// whole pixels, so a sub-pixel step changes no committed geometry. It is what\n// keeps a long animation over a short distance from spending ten renders a\n// second to travel one pixel — gorhom's `paddingBottom` crosses 26 px over the\n// same 1.38 s and lands 8 times, not 13.\nconst LANDING_EPSILON = 1\n\ntype Entry = {\n  driver: AnimatedValue\n  listenerId: string\n  signature: string\n  running: CompositeAnimation | null\n  // The value React was last given for this key, and the moment it was given\n  // — the two the cadence is measured against. They survive a restart on\n  // purpose: what matters is how stale REACT's copy is, not how far the\n  // animation currently in flight has come.\n  landedValue: number\n  landedAt: number\n}\n\nexport type UpdaterAnimations = {\n  /**\n   * Resolves `source`'s animations and publishes the result. Called from the\n   * mapper, so `source` is a fresh object every time.\n   */\n  run(source: UpdaterObject): void\n  dispose(): void\n}\n\n/**\n * @param publish Receives the updater's object with every animated key\n *   replaced by a number. Called once per mapper run and once per animation\n *   frame.\n * @param onSettled Called when an animation on `key` reaches its target on its\n *   own (never when it is cancelled or replaced). The style layer uses it for\n *   the properties it refuses to drive at frame rate, whose contract is that\n *   the value lands on the next React render — without it, that promise is\n *   only kept when something else happens to re-render.\n * @param onLanding Called when `key`'s current value has to reach React\n *   without its animation having reached a target. Two occasions: while an\n *   animation runs, at most once per `LANDING_INTERVAL_MS` and only when the\n *   value has moved far enough to change a committed layout (the cadence); and\n *   when a plain number REPLACES a running animation, where upstream cancels\n *   and snaps and a refused property cannot snap without a render. The snap is\n *   deliberately not rate-limited — it is a state change rather than a step of\n *   one, it happens once per mapper run that flips the key rather than once per\n *   frame, and upstream pushes exactly the same number of `updateProps` for it.\n *   Same job as `onSettled` and the same handling at the call site; it is a\n *   separate callback because a settle and a value that has merely got to be\n *   published are different claims, and only the first one is a promise kept.\n *   Omit it and both cost nothing at all — a caller with no refused properties\n *   (`useAnimatedProps`) does.\n */\nexport const createUpdaterAnimations = (\n  engine: AnimationEngine,\n  publish: (resolved: UpdaterObject) => void,\n  onSettled?: (key: string) => void,\n  onLanding?: (key: string) => void,\n): UpdaterAnimations => {\n  const entries = new Map<string, Entry>()\n  // The clock the animations themselves run on, never `Date` — the whole\n  // layer is driven by one injected scheduler so a test can take it\n  // (components/frame-scheduler.ts). A driver that only has frame stamps and\n  // no off-frame `now` cannot have a cadence, and falls back to the settle.\n  const hasClock = engine.scheduler.now !== undefined\n  const now = (): number => engine.scheduler.now?.() ?? 0\n  let lastSource: UpdaterObject | null = null\n  // A frame of one key's animation republishes the WHOLE object, which\n  // re-enters `resolve`. The guard keeps that from restarting anything: the\n  // run in progress publishes the final state itself.\n  let resolving = false\n\n  /**\n   * @param replacement The plain value that took the key over, or `undefined`\n   *   when the key left the updater's result altogether.\n   *\n   *   A number here owes the caller a render, and `landedValue` is what decides\n   *   it: that field is this module's whole model of what REACT holds for the\n   *   key, and everything since the last landing or settle went to the widget\n   *   without passing through React. So a plain number that differs from it has\n   *   to be published or it never arrives — on a refused property the snap IS\n   *   a render, and neither the cadence nor a settle is ever going to come for\n   *   it. Compared without the cadence's one-pixel epsilon and for the same\n   *   reason a settle ignores it: this is a resting value rather than a step\n   *   towards one, and there is nothing after it to correct a skipped render.\n   *\n   *   Not asked for otherwise. A key that VANISHED, or one replaced by a\n   *   percentage or a colour, changes the style's SHAPE, and the caller already\n   *   pays exactly one render for that (hooks.ts); a value equal to the one\n   *   React already has is a render for nothing.\n   */\n  const drop = (key: string, replacement: unknown): void => {\n    const entry = entries.get(key)\n    if (entry === undefined) {\n      return\n    }\n    entries.delete(key)\n    entry.running?.stop()\n    entry.driver.removeListener(entry.listenerId)\n    if (\n      typeof replacement === \"number\" &&\n      !Object.is(replacement, entry.landedValue)\n    ) {\n      onLanding?.(key)\n    }\n  }\n\n  const republish = (): void => {\n    if (resolving || lastSource === null) {\n      return\n    }\n    // No previous result on a frame: nothing can START an animation here — the\n    // source has not changed — so there is nothing to look a starting point up\n    // for.\n    publish(resolve(lastSource, null))\n  }\n\n  /**\n   * Records that `key`'s current value is the one React now holds. Called\n   * wherever a render is asked for, so the cadence is measured from the last\n   * value React was actually given rather than from the last frame.\n   */\n  const markLanded = (entry: Entry): void => {\n    entry.landedValue = entry.driver.__getValue()\n    entry.landedAt = now()\n  }\n\n  /** The cadence: see LANDING_INTERVAL_MS. */\n  const considerLanding = (key: string, value: number): void => {\n    if (onLanding === undefined || !hasClock) {\n      return\n    }\n    const entry = entries.get(key)\n    if (entry === undefined) {\n      return\n    }\n    if (now() - entry.landedAt < LANDING_INTERVAL_MS) {\n      return\n    }\n    if (Math.abs(value - entry.landedValue) < LANDING_EPSILON) {\n      return\n    }\n    markLanded(entry)\n    onLanding(key)\n  }\n\n  /** Aims `entry`'s driver at `spec`, replacing whatever it was running. */\n  const start = (\n    key: string,\n    entry: Entry,\n    spec: AnimationSpec,\n    signature: string,\n  ): Entry => {\n    entry.signature = signature\n    entry.running?.stop()\n    const animation = buildAnimation(engine, entry.driver, spec)\n    entry.running = animation\n    animation.start((result) => {\n      if (entry.running === animation) {\n        entry.running = null\n      }\n      // `finished` only: a restart stops the previous animation, and reporting\n      // that as a settle would publish through React on every frame the target\n      // moves, which is the cost the refusal exists to avoid. A restart is\n      // still covered — the cadence above is what carries a target that keeps\n      // moving, and it does not care whose animation the frames belong to.\n      if (result.finished) {\n        markLanded(entry)\n        onSettled?.(key)\n      }\n    })\n    return entry\n  }\n\n  /**\n   * Where an animation that is starting has to start FROM, for a key that was\n   * not animating a moment ago: the value the PREVIOUS updater result held for\n   * it, and only when that is a real number.\n   *\n   * This is `prepareAnimation(…, oldValues[key])` and nothing more —\n   * `oldValues` is `state.last`, upstream's copy of the whole previous updater\n   * result — so the second of the header's three rules costs no bookkeeping at\n   * all. The previous result is an object this module was already holding for\n   * `republish`; reading one key out of it is the entire mechanism, and the\n   * entry does not have to carry a value across runs or outlive its animation.\n   *\n   * Numbers only, and `undefined` for everything else, which lines up with\n   * upstream at both ends: a key that was absent has no starting point (its\n   * `oldValues[key]` is `undefined`, and the animation's own `current` — the\n   * target — stands), and a percentage string or a colour is not something the\n   * numeric drivers here can start at.\n   */\n  const startingPoint = (\n    previous: UpdaterObject | null,\n    key: string,\n  ): number | undefined => {\n    const value = previous?.[key]\n    return typeof value === \"number\" && Number.isFinite(value)\n      ? value\n      : undefined\n  }\n\n  const ensure = (\n    key: string,\n    spec: AnimationSpec,\n    previous: UpdaterObject | null,\n  ): Entry => {\n    const signature = animationSignature(spec)\n    const existing = entries.get(key)\n    if (existing !== undefined) {\n      return existing.signature === signature\n        ? existing\n        : start(key, existing, spec, signature)\n    }\n    const from = startingPoint(previous, key)\n    // The driver is seeded before anything is built on purpose: a spring reads\n    // its origin off the value it is given (animation.ts), so this IS where\n    // \"animate from the old number\" happens.\n    const driver = new engine.api.Value(from ?? targetOf(spec) ?? 0)\n    const entry: Entry = {\n      driver,\n      listenerId: driver.addListener(({ value }) => {\n        republish()\n        considerLanding(key, value)\n      }),\n      signature,\n      running: null,\n      // Whichever branch follows, React's copy of this key is the value the\n      // driver starts at: a seed changes the style's SHAPE and the caller\n      // already pays one render for that (hooks.ts), and a starting point that\n      // came out of the previous result is a number React was already handed.\n      // So the cadence starts here either way.\n      landedValue: driver.__getValue(),\n      landedAt: now(),\n    }\n    entries.set(key, entry)\n    // Nothing to animate from: seeded at the target and not started at all,\n    // which is the first of the header's three rules.\n    return from === undefined ? entry : start(key, entry, spec, signature)\n  }\n\n  const resolve = (\n    source: UpdaterObject,\n    previous: UpdaterObject | null,\n  ): UpdaterObject => {\n    resolving = true\n    try {\n      let resolved: UpdaterObject | null = null\n      for (const key of Object.keys(source)) {\n        const value = source[key]\n        if (!isAnimationSpec(value)) {\n          // A plain value replacing an animation cancels it and snaps, exactly\n          // as an assignment to a shared value does and exactly as upstream's\n          // `delete animations[key]` + `updateProps` in the same run does. The\n          // number itself is published below, by identity.\n          drop(key, value)\n          continue\n        }\n        resolved ??= { ...source }\n        resolved[key] = ensure(key, value, previous).driver.__getValue()\n      }\n      for (const key of [...entries.keys()]) {\n        if (!(key in source)) {\n          drop(key, undefined)\n        }\n      }\n      return resolved ?? source\n    } finally {\n      resolving = false\n    }\n  }\n\n  return {\n    run(source) {\n      // `state.last`, upstream's name for it: the result this run's animations\n      // measure themselves against. Held for one run only, and it was already\n      // being held.\n      const previous = lastSource\n      lastSource = source\n      publish(resolve(source, previous))\n    },\n    dispose() {\n      for (const key of [...entries.keys()]) {\n        // Nothing is owed a render: the component is going away.\n        drop(key, undefined)\n      }\n      lastSource = null\n    },\n  }\n}\n"]}

package/dist/responder/system.d.ts

@@ -2,18 +2,49 @@ import type { NativeTouch } from "../components/press-event";
 import type { ResponderProps } from "./types";
 /** An opaque platform handle. A Gtk.Widget in practice; never treated as one. */
 export type ResponderHost = object;
+/**
+ * Why the responder was taken away by something that is not a pointer event.
+ *
+ * react-native-web's list is longer — cancel-ish events, context menu,
+ * window blur, ancestor scroll, selection change — and measuring GTK
+ * collapsed most of it. GTK cancels a single-button gesture the instant a
+ * second button goes down, and a widget that steals a sequence (a
+ * selectable label, a `GtkDragSource` attached through `Controllers`)
+ * cancels it too, so "context menu" and "selection change" both arrive as
+ * an ordinary `::cancel` on the event source and need no trigger of their
+ * own. What is left needs asking for:
+ *
+ * - `"blur"`: the toplevel stopped being the active window. Not a question,
+ *   in RN or here — the window is gone either way.
+ * - `"scroll"`: an ancestor scroller moved under the gesture. The one
+ *   termination a holder may refuse, and therefore the only place
+ *   `onResponderTerminationRequest` is consulted outside a transfer (PRD
+ *   crux 2: GTK's `CLAIMED` is irrevocable, so anything GTK has already
+ *   taken cannot be given back no matter what the holder answers).
+ */
+export type TerminationReason = "blur" | "scroll";
 export type ResponderSystemOptions = {
     /** The platform's parent link. Returning null ends the path. */
     parentOf: (host: ResponderHost) => ResponderHost | null;
     /**
-     * Fired after a node is granted the responder — where the platform makes
-     * its GTK `CLAIMED` declaration. One-way by construction: GTK has no way
-     * to hand a claimed sequence back, so this is only ever called once JS has
-     * already decided (docs/research/gestures.md, "no voluntary release").
+     * Fired at most ONCE per interaction, the first time any node is granted
+     * the responder — where the platform makes its GTK `CLAIMED` declaration.
+     *
+     * Its argument is the node whose event source is carrying the interaction,
+     * NOT the node that won the responder. Those differ whenever an ancestor
+     * claims (the common `onMoveShouldSetPanResponder` shape), and claiming on
+     * the ancestor is actively wrong: GTK denies the sequence on every gesture
+     * below the one that claims, which kills the very source the interaction
+     * is arriving through. What GTK is being told is "this interaction belongs
+     * to React Native, native widgets keep off" — a statement about the
+     * island, not about which view inside it currently holds the lock, which
+     * is a JS matter GTK has no way to represent.
+     *
+     * One-way by construction: GTK has no way to hand a claimed sequence back,
+     * so this only ever runs once JS has already decided (see
+     * docs/research/gestures.md, "no voluntary release").
      */
-    onGrant?: (host: ResponderHost) => void;
-    /** Fired when the responder is released or terminated. */
-    onRelease?: (host: ResponderHost) => void;
+    onClaim?: (source: ResponderHost) => void;
 };
 export type ResponderSystem = {
     register(host: ResponderHost, getProps: () => ResponderProps): () => void;
@@ -21,7 +52,49 @@ export type ResponderSystem = {
     touchMove(host: ResponderHost, touch: NativeTouch): void;
     touchEnd(host: ResponderHost, touch: NativeTouch): void;
     touchCancel(host: ResponderHost, touch: NativeTouch): void;
+    /**
+     * Something that is not a pointer event took the interaction. Returns
+     * whether the responder was actually given up — `false` means either
+     * nothing held it or the holder refused a reason that allows refusal.
+     */
+    terminate(reason: TerminationReason): boolean;
+    /**
+     * THE OUT-OF-EVENT GRANT CHANNEL. A registered node asks for the responder
+     * between touch events, and the ordinary negotiation runs against a
+     * synthesized event at the last known pointer position.
+     *
+     * RN negotiates inside touch events only, so a recognizer that changes its
+     * mind on a TIMER has no way to take the interaction until the pointer next
+     * moves. `activateAfterLongPress` is exactly that recognizer: the press
+     * matures while the pointer is still, and waiting for the next move puts
+     * the "lifted" visual one frame late — or, for a press-and-hold that never
+     * moves again, never.
+     *
+     * The precedent is react-native-web, which added
+     * `onScrollShouldSetResponder` and `onSelectionChangeShouldSetResponder`
+     * for its own platform's realities; extending the model where the platform
+     * demands it is recorded as acceptable in docs/research/gestures.md, and
+     * this channel is documented there with its reason.
+     *
+     * Deliberately NOT a new prop and not a new grant path: it reuses
+     * `negotiateAndTransfer` unchanged, so capture still beats bubble, the LCA
+     * pruning still applies, and an ancestor that wants the interaction still
+     * wins it. The only thing that is new is WHEN the question gets asked. The
+     * synthesized event is the same one `terminate()` already builds from
+     * `session.lastTouch`, for the same reason.
+     *
+     * No `onResponderMove` is dispatched afterwards: the pointer did not move,
+     * and inventing a move to announce a grant would put a fabricated
+     * coordinate into every consumer's translation arithmetic.
+     *
+     * Returns whether `host` holds the responder once the negotiation is over
+     * — `false` when there is no interaction, when `host` is not on the path
+     * the interaction is travelling, or when somebody else won.
+     */
+    requestResponder(host: ResponderHost): boolean;
     /** The node currently holding the responder, or null. */
     getResponder(): ResponderHost | null;
+    /** The node whose event source is carrying the interaction, or null. */
+    getSource(): ResponderHost | null;
 };
 export declare const createResponderSystem: (options: ResponderSystemOptions) => ResponderSystem;