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

package/dist/reanimated-compat/props.js

@@ -0,0 +1,111 @@
+// `useAnimatedProps`: the same trick as `useAnimatedStyle`, applied to props
+// instead of to a style.
+//
+// The mapper returns ordinary values every frame. On the first run each
+// NUMERIC leaf is replaced by an animated node and the mapping is remembered;
+// later runs push new values into those nodes, so a running animation costs
+// zero React renders. `createAnimatedComponent` spreads the result onto the
+// wrapped component without resolving it, and the component subscribes.
+//
+// WHY THIS IS ALMOST FREE HERE, and what it is actually for. The SVG shapes
+// already accept `number | AnimatedNode` on every numeric geometry and paint
+// prop and drive their own invalidation from it — `src/components/svg/
+// animated-support.ts` subscribes and rebuilds the path descriptor straight
+// into `queueDraw`. So an animated `r`, `strokeWidth` or `strokeDashoffset`
+// reaches GTK through a channel that has been there since the SVG epic, and
+// this file only has to hand it a node instead of a number. That is the whole
+// mechanism: `useAnimatedProps` is not a second write path, it is the first
+// one addressed by prop name rather than by style key.
+//
+// A NON-numeric prop is not driveable, for the same reason a colour is not
+// driveable in a style: nothing downstream subscribes to it, so it can only
+// land on the next React render. It says so once, by name, rather than being
+// dropped silently — and it ASKS FOR that render rather than waiting for one
+// that may never come.
+//
+// The asking is not a refinement. `react-native-drawer-layout`'s `Overlay`
+// (measured in the gallery's upstream-libraries section) is a full-screen `Animated.View`
+// whose `pointerEvents` is `"none"` until the drawer starts opening and
+// `"auto"` after; nothing else in that component re-renders, so a value only
+// applied "on the next render" was applied on no render at all. The overlay
+// went permanently targetable the first time the drawer opened and swallowed
+// every press in the app underneath it — the silent failure this package
+// refuses everywhere else. One React render per CHANGE (not per frame: the
+// value has to actually differ) is the honest cost, and the warning is what
+// makes it visible.
+import { createStyleNode } from "./style";
+// One warning per prop name per session, matching the style path's policy.
+const warned = new Set();
+const warnUndriveableProp = (property) => {
+    if (warned.has(property)) {
+        return;
+    }
+    warned.add(property);
+    const isProduction = typeof process !== "undefined" && process.env.NODE_ENV === "production";
+    if (!isProduction) {
+        console.warn(`react-native-reanimated: useAnimatedProps changed \`${property}\`, which is not a number, so nothing ` +
+            "downstream subscribes to it — only numeric props are driven at frame rate here (the SVG geometry " +
+            "and paint numbers). The new value is applied by a React render instead, one per change. " +
+            "See docs/api.md.");
+    }
+};
+/** @internal Test seam: the warning is once per session by design. */
+export const resetUndriveablePropWarnings = () => {
+    warned.clear();
+};
+// Only top-level numbers. Not a simplification: a prop is driveable exactly
+// when its receiver duck-types an animated node in that position, and the
+// components that do (the SVG shapes) take `number | AnimatedNode` — never a
+// nested object.
+const numericKeysOf = (source) => Object.keys(source).filter((key) => typeof source[key] === "number");
+export const createAnimatedProps = (source, reuse) => {
+    const numeric = numericKeysOf(source);
+    const signature = numeric.join("|");
+    const nodes = new Map();
+    for (const key of numeric) {
+        const existing = reuse?.get(key);
+        if (existing) {
+            existing.__push(source[key]);
+            nodes.set(key, existing);
+        }
+        else {
+            nodes.set(key, createStyleNode(source[key]));
+        }
+    }
+    const props = { ...source };
+    for (const [key, node] of nodes) {
+        props[key] = node;
+    }
+    // The last values seen for everything that is NOT node-backed, so a change
+    // can be reported rather than silently dropped.
+    let staticSnapshot = source;
+    return {
+        props,
+        nodes,
+        apply(next) {
+            if (numericKeysOf(next).join("|") !== signature) {
+                return false;
+            }
+            for (const [key, node] of nodes) {
+                node.__push(next[key]);
+            }
+            let needsRender = false;
+            for (const key of Object.keys(next)) {
+                if (nodes.has(key)) {
+                    continue;
+                }
+                if (!Object.is(next[key], staticSnapshot[key])) {
+                    warnUndriveableProp(key);
+                    props[key] = next[key];
+                    // The caller rebuilds and re-renders on false, which is the only
+                    // channel a non-node prop has. Mutating `props` alone left the new
+                    // value sitting in an object React had already committed.
+                    needsRender = true;
+                }
+            }
+            staticSnapshot = next;
+            return !needsRender;
+        },
+    };
+};
+//# sourceMappingURL=props.js.map

package/dist/reanimated-compat/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","sourceRoot":"","sources":["../../src/reanimated-compat/props.ts"],"names":[],"mappings":"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","sourcesContent":["// `useAnimatedProps`: the same trick as `useAnimatedStyle`, applied to props\n// instead of to a style.\n//\n// The mapper returns ordinary values every frame. On the first run each\n// NUMERIC leaf is replaced by an animated node and the mapping is remembered;\n// later runs push new values into those nodes, so a running animation costs\n// zero React renders. `createAnimatedComponent` spreads the result onto the\n// wrapped component without resolving it, and the component subscribes.\n//\n// WHY THIS IS ALMOST FREE HERE, and what it is actually for. The SVG shapes\n// already accept `number | AnimatedNode` on every numeric geometry and paint\n// prop and drive their own invalidation from it — `src/components/svg/\n// animated-support.ts` subscribes and rebuilds the path descriptor straight\n// into `queueDraw`. So an animated `r`, `strokeWidth` or `strokeDashoffset`\n// reaches GTK through a channel that has been there since the SVG epic, and\n// this file only has to hand it a node instead of a number. That is the whole\n// mechanism: `useAnimatedProps` is not a second write path, it is the first\n// one addressed by prop name rather than by style key.\n//\n// A NON-numeric prop is not driveable, for the same reason a colour is not\n// driveable in a style: nothing downstream subscribes to it, so it can only\n// land on the next React render. It says so once, by name, rather than being\n// dropped silently — and it ASKS FOR that render rather than waiting for one\n// that may never come.\n//\n// The asking is not a refinement. `react-native-drawer-layout`'s `Overlay`\n// (measured in the gallery's upstream-libraries section) is a full-screen `Animated.View`\n// whose `pointerEvents` is `\"none\"` until the drawer starts opening and\n// `\"auto\"` after; nothing else in that component re-renders, so a value only\n// applied \"on the next render\" was applied on no render at all. The overlay\n// went permanently targetable the first time the drawer opened and swallowed\n// every press in the app underneath it — the silent failure this package\n// refuses everywhere else. One React render per CHANGE (not per frame: the\n// value has to actually differ) is the honest cost, and the warning is what\n// makes it visible.\nimport { createStyleNode, type StyleNode } from \"./style\"\n\nexport type PropsObject = Record<string, unknown>\n\n// One warning per prop name per session, matching the style path's policy.\nconst warned = new Set<string>()\n\nconst warnUndriveableProp = (property: string): void => {\n  if (warned.has(property)) {\n    return\n  }\n  warned.add(property)\n  const isProduction =\n    typeof process !== \"undefined\" && process.env.NODE_ENV === \"production\"\n  if (!isProduction) {\n    console.warn(\n      `react-native-reanimated: useAnimatedProps changed \\`${property}\\`, which is not a number, so nothing ` +\n        \"downstream subscribes to it — only numeric props are driven at frame rate here (the SVG geometry \" +\n        \"and paint numbers). The new value is applied by a React render instead, one per change. \" +\n        \"See docs/api.md.\",\n    )\n  }\n}\n\n/** @internal Test seam: the warning is once per session by design. */\nexport const resetUndriveablePropWarnings = (): void => {\n  warned.clear()\n}\n\n// Only top-level numbers. Not a simplification: a prop is driveable exactly\n// when its receiver duck-types an animated node in that position, and the\n// components that do (the SVG shapes) take `number | AnimatedNode` — never a\n// nested object.\nconst numericKeysOf = (source: PropsObject): string[] =>\n  Object.keys(source).filter((key) => typeof source[key] === \"number\")\n\nexport type AnimatedPropsObject = {\n  /** Stable object spread onto the component; never replaced in place. */\n  readonly props: PropsObject\n  /** The nodes behind it, reusable when the props have to be rebuilt. */\n  readonly nodes: ReadonlyMap<string, StyleNode>\n  /**\n   * Publishes a fresh updater result. Returns false when the SHAPE changed\n   * (a prop became numeric, stopped being numeric, or appeared) and the\n   * caller must rebuild — the nodes the component subscribed to no longer\n   * describe these props.\n   */\n  apply(next: PropsObject): boolean\n}\n\nexport const createAnimatedProps = (\n  source: PropsObject,\n  reuse?: ReadonlyMap<string, StyleNode>,\n): AnimatedPropsObject => {\n  const numeric = numericKeysOf(source)\n  const signature = numeric.join(\"|\")\n\n  const nodes = new Map<string, StyleNode>()\n  for (const key of numeric) {\n    const existing = reuse?.get(key)\n    if (existing) {\n      existing.__push(source[key] as number)\n      nodes.set(key, existing)\n    } else {\n      nodes.set(key, createStyleNode(source[key] as number))\n    }\n  }\n\n  const props: PropsObject = { ...source }\n  for (const [key, node] of nodes) {\n    props[key] = node\n  }\n\n  // The last values seen for everything that is NOT node-backed, so a change\n  // can be reported rather than silently dropped.\n  let staticSnapshot = source\n\n  return {\n    props,\n    nodes,\n    apply(next) {\n      if (numericKeysOf(next).join(\"|\") !== signature) {\n        return false\n      }\n      for (const [key, node] of nodes) {\n        node.__push(next[key] as number)\n      }\n      let needsRender = false\n      for (const key of Object.keys(next)) {\n        if (nodes.has(key)) {\n          continue\n        }\n        if (!Object.is(next[key], staticSnapshot[key])) {\n          warnUndriveableProp(key)\n          props[key] = next[key]\n          // The caller rebuilds and re-renders on false, which is the only\n          // channel a non-node prop has. Mutating `props` alone left the new\n          // value sitting in an object React had already committed.\n          needsRender = true\n        }\n      }\n      staticSnapshot = next\n      return !needsRender\n    },\n  }\n}\n"]}

package/dist/reanimated-compat/scroll-handler.d.ts

@@ -0,0 +1,119 @@
+import type { ScrollEvent } from "../components/scroll-view";
+import type { DependencyList } from "./hooks";
+/**
+ * The event a scroll handler receives — Reanimated's shape, which is RN's
+ * native scroll payload FLATTENED (`event.contentOffset`, not
+ * `event.nativeEvent.contentOffset`) plus the event name.
+ *
+ * It carries exactly the three measurements this platform can report, which
+ * are the three {@link ScrollEvent} already carries. RN's payload also has
+ * `contentInset`, `velocity` and `zoomScale`; none has a source in a
+ * `GtkScrolledWindow`, and inventing zeros for them would be a number a
+ * caller could not tell from a measurement.
+ */
+export type AnimatedScrollEvent = ScrollEvent["nativeEvent"] & {
+    eventName: string;
+};
+export type ScrollHandlerCallback<Context extends Record<string, unknown>> = (event: AnimatedScrollEvent, context: Context) => void;
+export type ScrollHandlers<Context extends Record<string, unknown>> = {
+    onScroll?: ScrollHandlerCallback<Context>;
+    /** The user-driven scroll session began — native for touchpad, grouped for wheel. */
+    onBeginDrag?: ScrollHandlerCallback<Context>;
+    /** That session ended. A wheel gets no momentum pair afterwards. */
+    onEndDrag?: ScrollHandlerCallback<Context>;
+    /** The scroller kept moving on its own after the sequence ended. */
+    onMomentumBegin?: ScrollHandlerCallback<Context>;
+    /** That movement came to rest. */
+    onMomentumEnd?: ScrollHandlerCallback<Context>;
+};
+/**
+ * @internal The hook without the hook: the translation from a
+ * {@link ScrollEvent} to a handler call, plus the one context object every
+ * call shares. Split out because this repo's unit project has no React
+ * renderer — the hook below is two refs around this.
+ *
+ * `latest` is read per event rather than captured, so a re-render that
+ * changed the handlers is picked up without changing the returned function.
+ */
+export declare const createScrollHandler: <Context extends Record<string, unknown> = Record<string, unknown>>(latest: () => ScrollHandlers<Context> | ScrollHandlerCallback<Context> | undefined, sharedContext?: Context) => ((event: ScrollEvent) => void);
+/**
+ * Returns a scroll handler to pass as a scrollable's `onScroll`. The identity
+ * is stable across renders — a scrollable that re-attached its signal handler
+ * on every render would be a worse deal than the render this hook exists to
+ * avoid.
+ */
+export declare const useAnimatedScrollHandler: <Context extends Record<string, unknown> = Record<string, unknown>>(handlers: ScrollHandlers<Context> | ScrollHandlerCallback<Context> | undefined, dependencies?: DependencyList) => ((event: ScrollEvent) => void);
+/** Upstream's return shape. Both fields mean something here. */
+export type UseHandlerContext<Context extends Record<string, unknown>> = {
+    context: Context;
+    doDependenciesDiffer: boolean;
+    useWeb: boolean;
+};
+/**
+ * The context object a hand-built handler shares across its calls, plus the
+ * two questions upstream answers alongside it.
+ *
+ * `doDependenciesDiffer` is **always false**, and that is a statement rather
+ * than a stub: upstream needs it because a worklet is a by-value snapshot
+ * that goes stale, so a changed dependency has to force a REBUILD of the
+ * handler on the UI runtime. Here a handler is an ordinary closure read out
+ * of a ref at call time, so it is never stale and there is never anything to
+ * rebuild. A caller that feeds this into `useEvent`'s `rebuild` argument
+ * therefore never rebuilds, which is correct.
+ *
+ * `useWeb` is upstream's `SHOULD_BE_USE_WEB`, and it is true for the same
+ * reason it is true for react-native-windows: one runtime, no worklet
+ * boundary, events delivered as ordinary props (docs/research/reanimated.md).
+ */
+export declare const useHandler: <Event extends object, Context extends Record<string, unknown> = Record<string, unknown>>(handlers: Record<string, ((event: Event, context: Context) => void) | undefined>, dependencies?: DependencyList) => UseHandlerContext<Context>;
+/**
+ * Runs `handler` for each of `eventNames` the platform can report. The
+ * returned value goes on a scrollable's `onScroll`, exactly as the result of
+ * {@link useAnimatedScrollHandler} does — and it is the same object underneath:
+ * one callable carrying the phase sink for whichever phase names were asked
+ * for, so a `ScrollView` given a handler that asked for none installs no phase
+ * machinery.
+ *
+ * `rebuild` is accepted and ignored, for the reason `doDependenciesDiffer` is
+ * always false: nothing here goes stale, so there is nothing to rebuild.
+ *
+ * **Scroll event names only.** A name outside that set throws where it is
+ * asked for, naming itself: `onGestureHandlerStateChange` and the touch names
+ * belong to systems this platform implements elsewhere and would not reach a
+ * handler registered here, and a subscription that can never fire is the
+ * failure mode this package refuses everywhere else.
+ */
+export declare const useEvent: <Event extends object>(handler: (event: Event & {
+    eventName: string;
+}) => void, eventNames?: readonly string[], rebuild?: boolean) => ((event: ScrollEvent) => void);
+/** Anything `scrollTo` can be pointed at: RN's scroll methods live on the ref. */
+type ScrollableHandle = {
+    scrollTo?: (options: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }) => void;
+};
+type ScrollableRef = (() => ScrollableHandle | null) | {
+    current: ScrollableHandle | null;
+} | null | undefined;
+/**
+ * Scrolls the view an `useAnimatedRef` points at — the other half of the pair
+ * above, and the reason it is in this file: a list that reads its own offset
+ * through the handler almost always writes one back, and
+ * `react-native-reanimated-dnd`'s `useSortableList` does exactly that inside
+ * a `useAnimatedReaction`.
+ *
+ * Upstream is a worklet reaching the shadow tree directly. Here it is the
+ * ordinary imperative `scrollTo` every RN scrollable already exposes, called
+ * synchronously, for the same reason the handler needs no event system: this
+ * IS the thread that owns the widget. The argument order is upstream's
+ * (`x` then `y`, not RN's options object), so library call sites are
+ * unchanged, and `animated` carries through to `ScrollView`, which ignores it.
+ *
+ * A ref that is not (yet) pointing at a scrollable is ignored rather than
+ * throwing: upstream does the same, and the first frames of a list whose ref
+ * has not been attached are a normal state, not an error.
+ */
+export declare const scrollTo: (animatedRef: ScrollableRef, x: number, y: number, animated: boolean) => void;
+export {};

package/dist/reanimated-compat/scroll-handler.js

@@ -0,0 +1,274 @@
+// `useAnimatedScrollHandler` — Reanimated's "react to a scroll without
+// rendering".
+//
+// On mobile it is the sharpest edge of the whole architecture: the scroll
+// event is delivered to the UI runtime by native code, so the handler runs on
+// the UI thread at 60/120Hz and the JS thread never hears about it. That is
+// what `useEvent` and the whole event-name subscription machinery underneath
+// this hook exist to arrange.
+//
+// Here the arrangement is already the case, and it has been since the
+// ScrollView shipped. `emitScroll` in src/components/scroll-view.tsx runs
+// from a `GtkAdjustment::value-changed` handler — a C callback on the GTK
+// main loop, which is this JS thread — and calls the `onScroll` prop
+// directly. Nothing about that path goes through React: no state is set, no
+// render is scheduled, and the windowed list core already relies on exactly
+// this to re-window during a scroll. A handler that writes a shared value
+// from there gets what Reanimated promises, by the same reasoning
+// docs/research/reanimated.md gives for the rest of this surface.
+//
+// So the hook is a translation, not an implementation of an event system:
+// it returns a plain function to hand to a scrollable's `onScroll`, and the
+// scrollable calls it. That is also how Reanimated's own web path resolves —
+// `SHOULD_BE_USE_WEB` routes `useEvent` to a JS listener attached as an
+// ordinary prop.
+//
+// THE FOUR PHASE HANDLERS are called now, and what they mean is the input
+// device's rather than the platform's. Measured on GTK 4.22.4 under a real
+// pointer (docs/research/scroll-phases.md):
+//
+//   - a MOUSE WHEEL gives GTK no sequence — one `::scroll` per detent and
+//     nothing around it. This platform groups a burst into a desktop scroll
+//     SESSION and reports begin/end (never momentum), which is what lets a
+//     phase-aware consumer capture state before its first detent. This is an
+//     intentional desktop extension: RN has no wheel to define here.
+//   - a TOUCHPAD GLIDE produces all four. The sequence has a real beginning
+//     and end, and the scrolled window's own kinetic animation carries the
+//     content on afterwards.
+//
+// The one approximation: `onBeginDrag` is the scroll SEQUENCE beginning, not
+// a finger landing on the content. A touchpad never touches the content, so
+// "the user started driving this scroller" is the closest true statement —
+// and it is the statement consumers act on.
+//
+// The routing is the other half. Upstream hands ONE value to `onScroll` and
+// the native side delivers five event names into it; `@gorhom/bottom-sheet`
+// relies on exactly that and passes no phase prop at all. Here the handler
+// carries a phase SINK (src/components/scroll-phase.ts) that `ScrollView`
+// delivers into, so a library call site is unchanged. The sink is attached
+// only while a phase handler is actually present, which is what lets a
+// `ScrollView` given a plain `onScroll`-only handler install nothing.
+import { useRef, useState } from "react";
+import { setScrollPhaseSink, } from "../components/scroll-phase";
+/** Upstream's event name for each phase, carried on the flattened event. */
+const EVENT_NAME_OF_PHASE = {
+    beginDrag: "onScrollBeginDrag",
+    endDrag: "onScrollEndDrag",
+    momentumBegin: "onMomentumScrollBegin",
+    momentumEnd: "onMomentumScrollEnd",
+};
+const PHASE_KEY_OF_PHASE = {
+    beginDrag: "onBeginDrag",
+    endDrag: "onEndDrag",
+    momentumBegin: "onMomentumBegin",
+    momentumEnd: "onMomentumEnd",
+};
+/**
+ * Whether `handlers` asks for any phase at all. The answer decides whether a
+ * `ScrollView` installs its phase machinery, so it is asked of the CURRENT
+ * handlers on every render rather than once: a component that grows a phase
+ * handler later gets one, and one that never has any never pays for one.
+ */
+const wantsPhase = (handlers, phase) => {
+    if (typeof handlers !== "object" || handlers === null) {
+        return false;
+    }
+    if (phase !== undefined) {
+        return (typeof handlers[PHASE_KEY_OF_PHASE[phase]] === "function");
+    }
+    return Object.values(PHASE_KEY_OF_PHASE).some((key) => typeof handlers[key] === "function");
+};
+/**
+ * @internal The hook without the hook: the translation from a
+ * {@link ScrollEvent} to a handler call, plus the one context object every
+ * call shares. Split out because this repo's unit project has no React
+ * renderer — the hook below is two refs around this.
+ *
+ * `latest` is read per event rather than captured, so a re-render that
+ * changed the handlers is picked up without changing the returned function.
+ */
+export const createScrollHandler = (latest, 
+// The context object, when the caller already owns one — `useHandler`
+// hands out its own and a handler built from it has to share it.
+sharedContext) => {
+    // Upstream's `useHandler` gives every handler call the SAME mutable object
+    // across the whole scroll, and `@gorhom/bottom-sheet` uses it to carry the
+    // offset a drag started at. One object per handler is that contract.
+    const context = sharedContext ?? {};
+    const handle = (event) => {
+        const current = latest();
+        const onScroll = typeof current === "function" ? current : current?.onScroll;
+        onScroll?.({ ...event.nativeEvent, eventName: "onScroll" }, context);
+    };
+    // The phase sink shares that same context object, which is the whole
+    // reason gorhom's lock works: `onBeginDrag` writes the offset the drag
+    // started at into it and `onScroll` reads it back on the next frame.
+    setScrollPhaseSink(handle, {
+        wants: (phase) => wantsPhase(latest(), phase),
+        deliver: (phase, event) => {
+            const current = latest();
+            if (typeof current !== "object" || current === null) {
+                return;
+            }
+            const callback = current[PHASE_KEY_OF_PHASE[phase]];
+            callback?.({ ...event.nativeEvent, eventName: EVENT_NAME_OF_PHASE[phase] }, context);
+        },
+    });
+    return handle;
+};
+/**
+ * Returns a scroll handler to pass as a scrollable's `onScroll`. The identity
+ * is stable across renders — a scrollable that re-attached its signal handler
+ * on every render would be a worse deal than the render this hook exists to
+ * avoid.
+ */
+export const useAnimatedScrollHandler = (handlers, 
+// Accepted for source parity and unused, for the reason the rest of this
+// surface gives: nothing here is captured by a Babel plugin, so a handler
+// read out of a ref is always the current one and there is no stale
+// closure for a dependency array to refresh.
+dependencies) => {
+    void dependencies;
+    // The "latest ref" pattern, and the two disables below are what it costs.
+    // Upstream rebuilds the handler OBJECT on every render and the returned
+    // function has to call the current one; keeping it in a ref is the only
+    // way to do that without a new function each time, which is the whole
+    // point of the hook. Nothing reads the ref during render — the read
+    // happens inside the scroll callback, which runs from a GTK signal long
+    // after the commit. `useState` holds the function itself for the same
+    // reason `useAnimatedRef` reaches for it: that value IS the return value,
+    // and a ref there really would be a render-time read.
+    const latest = useRef(handlers);
+    // eslint-disable-next-line react-hooks/refs
+    latest.current = handlers;
+    // eslint-disable-next-line react-hooks/refs
+    const [stable] = useState(() => createScrollHandler(() => latest.current));
+    return stable;
+};
+/**
+ * The context object a hand-built handler shares across its calls, plus the
+ * two questions upstream answers alongside it.
+ *
+ * `doDependenciesDiffer` is **always false**, and that is a statement rather
+ * than a stub: upstream needs it because a worklet is a by-value snapshot
+ * that goes stale, so a changed dependency has to force a REBUILD of the
+ * handler on the UI runtime. Here a handler is an ordinary closure read out
+ * of a ref at call time, so it is never stale and there is never anything to
+ * rebuild. A caller that feeds this into `useEvent`'s `rebuild` argument
+ * therefore never rebuilds, which is correct.
+ *
+ * `useWeb` is upstream's `SHOULD_BE_USE_WEB`, and it is true for the same
+ * reason it is true for react-native-windows: one runtime, no worklet
+ * boundary, events delivered as ordinary props (docs/research/reanimated.md).
+ */
+export const useHandler = (handlers, dependencies) => {
+    void handlers;
+    void dependencies;
+    const [context] = useState(() => ({}));
+    return { context, doDependenciesDiffer: false, useWeb: true };
+};
+/**
+ * The event names this platform has a source for. Everything a scroll can
+ * report, and nothing else — there is no native event registry here to
+ * subscribe an arbitrary name against, so a name outside this set is refused
+ * by name rather than accepted and never fired.
+ */
+const SCROLL_EVENT_NAMES = new Set([
+    "onScroll",
+    ...Object.values(EVENT_NAME_OF_PHASE),
+]);
+const PHASE_OF_EVENT_NAME = new Map(Object.keys(EVENT_NAME_OF_PHASE).map((phase) => [
+    EVENT_NAME_OF_PHASE[phase],
+    phase,
+]));
+/**
+ * Runs `handler` for each of `eventNames` the platform can report. The
+ * returned value goes on a scrollable's `onScroll`, exactly as the result of
+ * {@link useAnimatedScrollHandler} does — and it is the same object underneath:
+ * one callable carrying the phase sink for whichever phase names were asked
+ * for, so a `ScrollView` given a handler that asked for none installs no phase
+ * machinery.
+ *
+ * `rebuild` is accepted and ignored, for the reason `doDependenciesDiffer` is
+ * always false: nothing here goes stale, so there is nothing to rebuild.
+ *
+ * **Scroll event names only.** A name outside that set throws where it is
+ * asked for, naming itself: `onGestureHandlerStateChange` and the touch names
+ * belong to systems this platform implements elsewhere and would not reach a
+ * handler registered here, and a subscription that can never fire is the
+ * failure mode this package refuses everywhere else.
+ */
+export const useEvent = (handler, eventNames = [], rebuild = false) => {
+    void rebuild;
+    for (const name of eventNames) {
+        if (!SCROLL_EVENT_NAMES.has(name)) {
+            throw new Error(`[react-native-gtkx] useEvent("${name}") is not supported. ` +
+                `This platform delivers scroll events only — ${[...SCROLL_EVENT_NAMES].join(", ")} — ` +
+                "because a GtkAdjustment is the one event source there is to subscribe to. " +
+                "See docs/api.md for the gesture and touch surfaces, which are their own systems.");
+        }
+    }
+    const latest = useRef(handler);
+    // eslint-disable-next-line react-hooks/refs
+    latest.current = handler;
+    const names = useRef(eventNames);
+    // eslint-disable-next-line react-hooks/refs
+    names.current = eventNames;
+    // eslint-disable-next-line react-hooks/refs
+    const [stable] = useState(() => {
+        const call = (nativeEvent, eventName) => {
+            if (names.current.includes(eventName)) {
+                latest.current({ ...nativeEvent, eventName });
+            }
+        };
+        const emit = (event) => {
+            call(event.nativeEvent, "onScroll");
+        };
+        setScrollPhaseSink(emit, {
+            wants: () => names.current.some((name) => PHASE_OF_EVENT_NAME.has(name)),
+            deliver: (phase, event) => {
+                call(event.nativeEvent, EVENT_NAME_OF_PHASE[phase]);
+            },
+        });
+        // Upstream's return value carries this, and `useScrollOffset` reaches
+        // through it to register a view TAG with the native event registry. There
+        // is no such registry here and no tag to give it, so reaching for it
+        // fails where it is reached for rather than silently doing nothing.
+        Object.defineProperty(emit, "workletEventHandler", {
+            get() {
+                throw new Error("[react-native-gtkx] useEvent(...).workletEventHandler is not supported. " +
+                    "It registers a native view tag with Reanimated's event registry, and this " +
+                    "platform has neither. Hand the value useEvent returns to a scrollable's " +
+                    "`onScroll` prop instead — that IS the subscription here.");
+            },
+        });
+        return emit;
+    });
+    return stable;
+};
+/**
+ * Scrolls the view an `useAnimatedRef` points at — the other half of the pair
+ * above, and the reason it is in this file: a list that reads its own offset
+ * through the handler almost always writes one back, and
+ * `react-native-reanimated-dnd`'s `useSortableList` does exactly that inside
+ * a `useAnimatedReaction`.
+ *
+ * Upstream is a worklet reaching the shadow tree directly. Here it is the
+ * ordinary imperative `scrollTo` every RN scrollable already exposes, called
+ * synchronously, for the same reason the handler needs no event system: this
+ * IS the thread that owns the widget. The argument order is upstream's
+ * (`x` then `y`, not RN's options object), so library call sites are
+ * unchanged, and `animated` carries through to `ScrollView`, which ignores it.
+ *
+ * A ref that is not (yet) pointing at a scrollable is ignored rather than
+ * throwing: upstream does the same, and the first frames of a list whose ref
+ * has not been attached are a normal state, not an error.
+ */
+export const scrollTo = (animatedRef, x, y, animated) => {
+    if (!animatedRef) {
+        return;
+    }
+    const handle = typeof animatedRef === "function" ? animatedRef() : animatedRef.current;
+    handle?.scrollTo?.({ x, y, animated });
+};
+//# sourceMappingURL=scroll-handler.js.map

package/dist/reanimated-compat/scroll-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-handler.js","sourceRoot":"","sources":["../../src/reanimated-compat/scroll-handler.ts"],"names":[],"mappings":"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","sourcesContent":["// `useAnimatedScrollHandler` — Reanimated's \"react to a scroll without\n// rendering\".\n//\n// On mobile it is the sharpest edge of the whole architecture: the scroll\n// event is delivered to the UI runtime by native code, so the handler runs on\n// the UI thread at 60/120Hz and the JS thread never hears about it. That is\n// what `useEvent` and the whole event-name subscription machinery underneath\n// this hook exist to arrange.\n//\n// Here the arrangement is already the case, and it has been since the\n// ScrollView shipped. `emitScroll` in src/components/scroll-view.tsx runs\n// from a `GtkAdjustment::value-changed` handler — a C callback on the GTK\n// main loop, which is this JS thread — and calls the `onScroll` prop\n// directly. Nothing about that path goes through React: no state is set, no\n// render is scheduled, and the windowed list core already relies on exactly\n// this to re-window during a scroll. A handler that writes a shared value\n// from there gets what Reanimated promises, by the same reasoning\n// docs/research/reanimated.md gives for the rest of this surface.\n//\n// So the hook is a translation, not an implementation of an event system:\n// it returns a plain function to hand to a scrollable's `onScroll`, and the\n// scrollable calls it. That is also how Reanimated's own web path resolves —\n// `SHOULD_BE_USE_WEB` routes `useEvent` to a JS listener attached as an\n// ordinary prop.\n//\n// THE FOUR PHASE HANDLERS are called now, and what they mean is the input\n// device's rather than the platform's. Measured on GTK 4.22.4 under a real\n// pointer (docs/research/scroll-phases.md):\n//\n//   - a MOUSE WHEEL gives GTK no sequence — one `::scroll` per detent and\n//     nothing around it. This platform groups a burst into a desktop scroll\n//     SESSION and reports begin/end (never momentum), which is what lets a\n//     phase-aware consumer capture state before its first detent. This is an\n//     intentional desktop extension: RN has no wheel to define here.\n//   - a TOUCHPAD GLIDE produces all four. The sequence has a real beginning\n//     and end, and the scrolled window's own kinetic animation carries the\n//     content on afterwards.\n//\n// The one approximation: `onBeginDrag` is the scroll SEQUENCE beginning, not\n// a finger landing on the content. A touchpad never touches the content, so\n// \"the user started driving this scroller\" is the closest true statement —\n// and it is the statement consumers act on.\n//\n// The routing is the other half. Upstream hands ONE value to `onScroll` and\n// the native side delivers five event names into it; `@gorhom/bottom-sheet`\n// relies on exactly that and passes no phase prop at all. Here the handler\n// carries a phase SINK (src/components/scroll-phase.ts) that `ScrollView`\n// delivers into, so a library call site is unchanged. The sink is attached\n// only while a phase handler is actually present, which is what lets a\n// `ScrollView` given a plain `onScroll`-only handler install nothing.\nimport { useRef, useState } from \"react\"\nimport {\n  setScrollPhaseSink,\n  type ScrollPhase,\n} from \"../components/scroll-phase\"\nimport type { ScrollEvent } from \"../components/scroll-view\"\nimport type { DependencyList } from \"./hooks\"\n\n/**\n * The event a scroll handler receives — Reanimated's shape, which is RN's\n * native scroll payload FLATTENED (`event.contentOffset`, not\n * `event.nativeEvent.contentOffset`) plus the event name.\n *\n * It carries exactly the three measurements this platform can report, which\n * are the three {@link ScrollEvent} already carries. RN's payload also has\n * `contentInset`, `velocity` and `zoomScale`; none has a source in a\n * `GtkScrolledWindow`, and inventing zeros for them would be a number a\n * caller could not tell from a measurement.\n */\nexport type AnimatedScrollEvent = ScrollEvent[\"nativeEvent\"] & {\n  eventName: string\n}\n\nexport type ScrollHandlerCallback<Context extends Record<string, unknown>> = (\n  event: AnimatedScrollEvent,\n  context: Context,\n) => void\n\nexport type ScrollHandlers<Context extends Record<string, unknown>> = {\n  onScroll?: ScrollHandlerCallback<Context>\n  /** The user-driven scroll session began — native for touchpad, grouped for wheel. */\n  onBeginDrag?: ScrollHandlerCallback<Context>\n  /** That session ended. A wheel gets no momentum pair afterwards. */\n  onEndDrag?: ScrollHandlerCallback<Context>\n  /** The scroller kept moving on its own after the sequence ended. */\n  onMomentumBegin?: ScrollHandlerCallback<Context>\n  /** That movement came to rest. */\n  onMomentumEnd?: ScrollHandlerCallback<Context>\n}\n\n/** Upstream's event name for each phase, carried on the flattened event. */\nconst EVENT_NAME_OF_PHASE: Record<ScrollPhase, string> = {\n  beginDrag: \"onScrollBeginDrag\",\n  endDrag: \"onScrollEndDrag\",\n  momentumBegin: \"onMomentumScrollBegin\",\n  momentumEnd: \"onMomentumScrollEnd\",\n}\n\nconst PHASE_KEY_OF_PHASE = {\n  beginDrag: \"onBeginDrag\",\n  endDrag: \"onEndDrag\",\n  momentumBegin: \"onMomentumBegin\",\n  momentumEnd: \"onMomentumEnd\",\n} as const satisfies Record<ScrollPhase, string>\n\n/**\n * Whether `handlers` asks for any phase at all. The answer decides whether a\n * `ScrollView` installs its phase machinery, so it is asked of the CURRENT\n * handlers on every render rather than once: a component that grows a phase\n * handler later gets one, and one that never has any never pays for one.\n */\nconst wantsPhase = (handlers: unknown, phase?: ScrollPhase): boolean => {\n  if (typeof handlers !== \"object\" || handlers === null) {\n    return false\n  }\n  if (phase !== undefined) {\n    return (\n      typeof (handlers as Record<string, unknown>)[\n        PHASE_KEY_OF_PHASE[phase]\n      ] === \"function\"\n    )\n  }\n  return Object.values(PHASE_KEY_OF_PHASE).some(\n    (key) => typeof (handlers as Record<string, unknown>)[key] === \"function\",\n  )\n}\n\n/**\n * @internal The hook without the hook: the translation from a\n * {@link ScrollEvent} to a handler call, plus the one context object every\n * call shares. Split out because this repo's unit project has no React\n * renderer — the hook below is two refs around this.\n *\n * `latest` is read per event rather than captured, so a re-render that\n * changed the handlers is picked up without changing the returned function.\n */\nexport const createScrollHandler = <\n  Context extends Record<string, unknown> = Record<string, unknown>,\n>(\n  latest: () =>\n    ScrollHandlers<Context> | ScrollHandlerCallback<Context> | undefined,\n  // The context object, when the caller already owns one — `useHandler`\n  // hands out its own and a handler built from it has to share it.\n  sharedContext?: Context,\n): ((event: ScrollEvent) => void) => {\n  // Upstream's `useHandler` gives every handler call the SAME mutable object\n  // across the whole scroll, and `@gorhom/bottom-sheet` uses it to carry the\n  // offset a drag started at. One object per handler is that contract.\n  const context = sharedContext ?? ({} as Context)\n  const handle = (event: ScrollEvent): void => {\n    const current = latest()\n    const onScroll = typeof current === \"function\" ? current : current?.onScroll\n    onScroll?.({ ...event.nativeEvent, eventName: \"onScroll\" }, context)\n  }\n  // The phase sink shares that same context object, which is the whole\n  // reason gorhom's lock works: `onBeginDrag` writes the offset the drag\n  // started at into it and `onScroll` reads it back on the next frame.\n  setScrollPhaseSink(handle, {\n    wants: (phase) => wantsPhase(latest(), phase),\n    deliver: (phase, event) => {\n      const current = latest()\n      if (typeof current !== \"object\" || current === null) {\n        return\n      }\n      const callback = current[PHASE_KEY_OF_PHASE[phase]] as\n        ScrollHandlerCallback<Context> | undefined\n      callback?.(\n        { ...event.nativeEvent, eventName: EVENT_NAME_OF_PHASE[phase] },\n        context,\n      )\n    },\n  })\n  return handle\n}\n\n/**\n * Returns a scroll handler to pass as a scrollable's `onScroll`. The identity\n * is stable across renders — a scrollable that re-attached its signal handler\n * on every render would be a worse deal than the render this hook exists to\n * avoid.\n */\nexport const useAnimatedScrollHandler = <\n  Context extends Record<string, unknown> = Record<string, unknown>,\n>(\n  handlers:\n    ScrollHandlers<Context> | ScrollHandlerCallback<Context> | undefined,\n  // Accepted for source parity and unused, for the reason the rest of this\n  // surface gives: nothing here is captured by a Babel plugin, so a handler\n  // read out of a ref is always the current one and there is no stale\n  // closure for a dependency array to refresh.\n  dependencies?: DependencyList,\n): ((event: ScrollEvent) => void) => {\n  void dependencies\n  // The \"latest ref\" pattern, and the two disables below are what it costs.\n  // Upstream rebuilds the handler OBJECT on every render and the returned\n  // function has to call the current one; keeping it in a ref is the only\n  // way to do that without a new function each time, which is the whole\n  // point of the hook. Nothing reads the ref during render — the read\n  // happens inside the scroll callback, which runs from a GTK signal long\n  // after the commit. `useState` holds the function itself for the same\n  // reason `useAnimatedRef` reaches for it: that value IS the return value,\n  // and a ref there really would be a render-time read.\n  const latest = useRef(handlers)\n  // eslint-disable-next-line react-hooks/refs\n  latest.current = handlers\n  // eslint-disable-next-line react-hooks/refs\n  const [stable] = useState(() =>\n    createScrollHandler<Context>(() => latest.current),\n  )\n  return stable\n}\n\n// --- the primitives the hook above is built on --------------------------\n//\n// `useHandler` and `useEvent` are what upstream builds every scroll handler\n// out of, and libraries reach for them directly to build their own. Both are\n// implementable over this seam, and neither needs the event system they exist\n// to arrange on mobile — for the reason at the top of this file.\n\n/** Upstream's return shape. Both fields mean something here. */\nexport type UseHandlerContext<Context extends Record<string, unknown>> = {\n  context: Context\n  doDependenciesDiffer: boolean\n  useWeb: boolean\n}\n\n/**\n * The context object a hand-built handler shares across its calls, plus the\n * two questions upstream answers alongside it.\n *\n * `doDependenciesDiffer` is **always false**, and that is a statement rather\n * than a stub: upstream needs it because a worklet is a by-value snapshot\n * that goes stale, so a changed dependency has to force a REBUILD of the\n * handler on the UI runtime. Here a handler is an ordinary closure read out\n * of a ref at call time, so it is never stale and there is never anything to\n * rebuild. A caller that feeds this into `useEvent`'s `rebuild` argument\n * therefore never rebuilds, which is correct.\n *\n * `useWeb` is upstream's `SHOULD_BE_USE_WEB`, and it is true for the same\n * reason it is true for react-native-windows: one runtime, no worklet\n * boundary, events delivered as ordinary props (docs/research/reanimated.md).\n */\nexport const useHandler = <\n  Event extends object,\n  Context extends Record<string, unknown> = Record<string, unknown>,\n>(\n  handlers: Record<\n    string,\n    ((event: Event, context: Context) => void) | undefined\n  >,\n  dependencies?: DependencyList,\n): UseHandlerContext<Context> => {\n  void handlers\n  void dependencies\n  const [context] = useState(() => ({}) as Context)\n  return { context, doDependenciesDiffer: false, useWeb: true }\n}\n\n/**\n * The event names this platform has a source for. Everything a scroll can\n * report, and nothing else — there is no native event registry here to\n * subscribe an arbitrary name against, so a name outside this set is refused\n * by name rather than accepted and never fired.\n */\nconst SCROLL_EVENT_NAMES = new Set<string>([\n  \"onScroll\",\n  ...Object.values(EVENT_NAME_OF_PHASE),\n])\n\nconst PHASE_OF_EVENT_NAME = new Map<string, ScrollPhase>(\n  (Object.keys(EVENT_NAME_OF_PHASE) as ScrollPhase[]).map((phase) => [\n    EVENT_NAME_OF_PHASE[phase],\n    phase,\n  ]),\n)\n\n/**\n * Runs `handler` for each of `eventNames` the platform can report. The\n * returned value goes on a scrollable's `onScroll`, exactly as the result of\n * {@link useAnimatedScrollHandler} does — and it is the same object underneath:\n * one callable carrying the phase sink for whichever phase names were asked\n * for, so a `ScrollView` given a handler that asked for none installs no phase\n * machinery.\n *\n * `rebuild` is accepted and ignored, for the reason `doDependenciesDiffer` is\n * always false: nothing here goes stale, so there is nothing to rebuild.\n *\n * **Scroll event names only.** A name outside that set throws where it is\n * asked for, naming itself: `onGestureHandlerStateChange` and the touch names\n * belong to systems this platform implements elsewhere and would not reach a\n * handler registered here, and a subscription that can never fire is the\n * failure mode this package refuses everywhere else.\n */\nexport const useEvent = <Event extends object>(\n  handler: (event: Event & { eventName: string }) => void,\n  eventNames: readonly string[] = [],\n  rebuild = false,\n): ((event: ScrollEvent) => void) => {\n  void rebuild\n  for (const name of eventNames) {\n    if (!SCROLL_EVENT_NAMES.has(name)) {\n      throw new Error(\n        `[react-native-gtkx] useEvent(\"${name}\") is not supported. ` +\n          `This platform delivers scroll events only — ${[...SCROLL_EVENT_NAMES].join(\", \")} — ` +\n          \"because a GtkAdjustment is the one event source there is to subscribe to. \" +\n          \"See docs/api.md for the gesture and touch surfaces, which are their own systems.\",\n      )\n    }\n  }\n  const latest = useRef(handler)\n  // eslint-disable-next-line react-hooks/refs\n  latest.current = handler\n  const names = useRef(eventNames)\n  // eslint-disable-next-line react-hooks/refs\n  names.current = eventNames\n  // eslint-disable-next-line react-hooks/refs\n  const [stable] = useState(() => {\n    const call = (nativeEvent: object, eventName: string): void => {\n      if (names.current.includes(eventName)) {\n        latest.current({ ...nativeEvent, eventName } as Event & {\n          eventName: string\n        })\n      }\n    }\n    const emit = (event: ScrollEvent): void => {\n      call(event.nativeEvent, \"onScroll\")\n    }\n    setScrollPhaseSink(emit, {\n      wants: () => names.current.some((name) => PHASE_OF_EVENT_NAME.has(name)),\n      deliver: (phase, event) => {\n        call(event.nativeEvent, EVENT_NAME_OF_PHASE[phase])\n      },\n    })\n    // Upstream's return value carries this, and `useScrollOffset` reaches\n    // through it to register a view TAG with the native event registry. There\n    // is no such registry here and no tag to give it, so reaching for it\n    // fails where it is reached for rather than silently doing nothing.\n    Object.defineProperty(emit, \"workletEventHandler\", {\n      get() {\n        throw new Error(\n          \"[react-native-gtkx] useEvent(...).workletEventHandler is not supported. \" +\n            \"It registers a native view tag with Reanimated's event registry, and this \" +\n            \"platform has neither. Hand the value useEvent returns to a scrollable's \" +\n            \"`onScroll` prop instead — that IS the subscription here.\",\n        )\n      },\n    })\n    return emit\n  })\n  return stable\n}\n\n/** Anything `scrollTo` can be pointed at: RN's scroll methods live on the ref. */\ntype ScrollableHandle = {\n  scrollTo?: (options: { x?: number; y?: number; animated?: boolean }) => void\n}\n\ntype ScrollableRef =\n  | (() => ScrollableHandle | null)\n  | { current: ScrollableHandle | null }\n  | null\n  | undefined\n\n/**\n * Scrolls the view an `useAnimatedRef` points at — the other half of the pair\n * above, and the reason it is in this file: a list that reads its own offset\n * through the handler almost always writes one back, and\n * `react-native-reanimated-dnd`'s `useSortableList` does exactly that inside\n * a `useAnimatedReaction`.\n *\n * Upstream is a worklet reaching the shadow tree directly. Here it is the\n * ordinary imperative `scrollTo` every RN scrollable already exposes, called\n * synchronously, for the same reason the handler needs no event system: this\n * IS the thread that owns the widget. The argument order is upstream's\n * (`x` then `y`, not RN's options object), so library call sites are\n * unchanged, and `animated` carries through to `ScrollView`, which ignores it.\n *\n * A ref that is not (yet) pointing at a scrollable is ignored rather than\n * throwing: upstream does the same, and the first frames of a list whose ref\n * has not been attached are a normal state, not an error.\n */\nexport const scrollTo = (\n  animatedRef: ScrollableRef,\n  x: number,\n  y: number,\n  animated: boolean,\n): void => {\n  if (!animatedRef) {\n    return\n  }\n  const handle =\n    typeof animatedRef === \"function\" ? animatedRef() : animatedRef.current\n  handle?.scrollTo?.({ x, y, animated })\n}\n"]}

package/dist/reanimated-compat/scroll-offset.d.ts

@@ -0,0 +1,12 @@
+import type { SharedValue } from "./mutable";
+type MakeMutable = <T>(initial: T) => SharedValue<T>;
+/** Either spelling of a ref, as everything else on this surface accepts. */
+type ScrollableRef = (() => unknown) | {
+    current: unknown;
+} | null | undefined;
+export declare const createScrollOffsetHooks: (makeMutable: MakeMutable) => {
+    useScrollOffset: (animatedRef: ScrollableRef, providedOffset?: SharedValue<number>) => SharedValue<number>;
+    /** Upstream's own deprecated alias, kept so library call sites are unchanged. */
+    useScrollViewOffset: (animatedRef: ScrollableRef, providedOffset?: SharedValue<number>) => SharedValue<number>;
+};
+export {};