@symbiote-native/components 1.0.0 → 3.0.0

package/build/behaviors/pressable.js

@@ -14,10 +14,10 @@
 // `registerPressableBehavior()`, and its entry does a bare `import './register';` that the barrel
 // does NOT re-export. A bare `import './register';` sitting NEXT TO such a re-export does not work
 // either: Babel merges the two imports of one specifier and the merged dependency stays lazy.
-import { appListenerFor, dlog, registerHostBehavior, requestCommitFor, setBehaviorListener, setNodePressed, } from '@symbiote-native/engine';
-import { createPressHandlers, createPressRuntime, disposePressRuntime, DEFAULT_DELAY_LONG_PRESS_MS, rippleProps, } from '../state/pressable.js';
-import { buildPressableListeners, resolveDisabledAccessibilityState, } from '../view/render-pressable/index.js';
-export const PRESSABLE_TAG = 'symbiote-pressable';
+import { appListenerFor, dlog, propOf, registerHostBehavior, requestCommitFor, setBehaviorListener, setNodePressed, propsOf, } from '@symbiote-native/engine';
+import { createPressHandlers, createPressRuntime, disposePressRuntime, DEFAULT_DELAY_LONG_PRESS_MS, DEFAULT_MIN_PRESS_DURATION_MS, } from '../state/pressable.js';
+import { buildPressableListeners } from '../view/render-pressable/index.js';
+export const PRESSABLE_TAG = 'pressable';
 const states = new WeakMap();
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -25,6 +25,12 @@ function isRecord(value) {
 function numberOr(value, fallback) {
     return typeof value === 'number' ? value : fallback;
 }
+// The bag arrives as `unknown` off `node.props`; every RN default below is written against
+// `boolean | undefined`. Exported to the sibling behaviors folding the same bag, and deliberately
+// NOT to the shared barrel — same reasoning as `asAccessibilityState`.
+export function booleanOr(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
 // A scalar offset or the per-edge object; anything else reads as "no offset", which the machine
 // turns into RN's defaults. Same narrowing the component path does — kept here rather than shared
 // because the component's version narrows Vue attrs, and this one narrows engine props.
@@ -50,27 +56,11 @@ function asRectOffset(value) {
 function isPressHandler(value) {
     return typeof value === 'function';
 }
-// The props the MACHINE consumes and the host must never see. The wrapper drops them by
-// destructuring — they go into `createPressHandlers` / `buildPressableListeners` and are simply
-// absent from the object it spreads onto its View. A lowered element has no destructure, so every
-// one of them rode into the payload as a key no ViewConfig declares.
-const MACHINE_ONLY_KEYS = [
-    // Consumed below and replaced by the resolved `nativeBackgroundAndroid` /
-    // `nativeForegroundAndroid`; the raw config is not a native prop.
-    'android_ripple',
-    'disabled',
-    'cancelable',
-    'delayLongPress',
-    'unstable_pressDelay',
-    'pressRetentionOffset',
-    'delayHoverIn',
-    'delayHoverOut',
-];
-// Narrowed field by field rather than cast: the bag arrives as `unknown` off `node.props`. A local
-// twin of the guard each adapter keeps for its own attrs (Vue's `asAccessibilityState`) — not
-// hoisted to the shared barrel, because every adapter re-exports that barrel wholesale and a
-// narrowing helper is not API anyone should be able to import.
-function asAccessibilityState(value) {
+// Narrowed field by field rather than cast: the bag arrives as `unknown` off `propOf`. A local
+// twin of the guard each adapter keeps for its own attrs (Vue's `asAccessibilityState`) — exported
+// to the sibling behaviors that fold the same bag, and deliberately NOT to the shared barrel, which
+// every adapter re-exports wholesale: a narrowing helper is not API anyone should be able to import.
+export function asAccessibilityState(value) {
     if (!isRecord(value))
         return undefined;
     const state = {};
@@ -86,99 +76,118 @@ function asAccessibilityState(value) {
         state.expanded = value.expanded;
     return state;
 }
-// Narrowed field by field, same reason as the accessibility guard above: the config arrives as
-// `unknown` off `node.props`.
-function asRippleConfig(value) {
-    if (!isRecord(value))
-        return undefined;
-    const config = {};
-    if (typeof value.color === 'string')
-        config.color = value.color;
-    if (typeof value.borderless === 'boolean')
-        config.borderless = value.borderless;
-    if (typeof value.radius === 'number')
-        config.radius = value.radius;
-    if (typeof value.foreground === 'boolean')
-        config.foreground = value.foreground;
-    return config;
-}
-// `disabled` reaches a screen reader ONLY as `accessibilityState.disabled` — it is not a native
-// View prop, so the wrapper folds it (`resolveDisabledAccessibilityState`, called by all five) and
-// forwards the composite. Lowering dropped that fold: press suppression still worked, because the
-// machine reads `node.props.disabled` directly, so the button behaved correctly and announced
-// itself as enabled. An accessibility regression with no visual tell and no failing test.
+// THE PAYLOAD FOLD MOVED TO THE ENGINE — `foldPressableProps` in `SymbioteFabricProps.cpp`, and
+// its contract is `core/engine/cpp/tests/js/pressable-payload.itest.ts`. It is not re-implemented
+// here in any form, which is the point: `disabled` -> `accessibilityState`, `accessible`/`focusable`
+// defaulting on, the Android ripple config, and the nine machine-only keys being kept out of the
+// payload are all functions of the TAG alone. That is user-agent behavior — RN does it for every
+// Pressable in every app — and it belongs beside the tree, like a browser's `<button>`.
+//
+// It cost a trip: a `payloadFold` marshals the whole bag out and the whole bag back, ~17 us per
+// pressable per commit, and a benchmark row carries two.
+//
+// What is still here is the MACHINE, which is where a browser keeps it too: timers, the responder
+// claim, hit-slop retention, and the callbacks into app code.
 //
-// Found by the wrapper-vs-behavior import audit (`.claude/rules/adapter-parity-audit.md`).
-function foldPayload(props) {
-    const resolved = resolveDisabledAccessibilityState(asAccessibilityState(props.accessibilityState), typeof props.disabled === 'boolean' ? props.disabled : undefined);
-    // The Android ripple. Our WRAPPER paints it through a dedicated inner View, mirroring
-    // TouchableNativeFeedback — and that reading is what made this look unfixable for a lowered
-    // element, which has no child to put it on. RN's own `Pressable` does NOT do that: it spreads
-    // `useAndroidRippleForView`'s `viewProps` onto its own View (`Pressable.js:251`), so the ripple
-    // background is an ordinary prop of the responder itself and a single node carries it fine.
-    //
-    // `rippleProps` returns undefined off Android, so this whole branch is inert on iOS.
-    //
-    // STILL MISSING ON BOTH PATHS, and lowering did not cause it: RN also dispatches
-    // `Commands.hotspotUpdate(x, y)` on pressIn/pressMove and `Commands.setPressed` on
-    // pressIn/pressOut, which is what makes the ripple originate at the touch point. Neither our
-    // wrapper nor this behavior sends them — grep for `hotspotUpdate` returns nothing in the tree.
-    const rippleConfig = asRippleConfig(props.android_ripple);
-    const ripple = rippleConfig !== undefined ? rippleProps(rippleConfig) : undefined;
-    const out = { ...props };
-    for (const key of MACHINE_ONLY_KEYS)
-        delete out[key];
-    if (ripple !== undefined)
-        Object.assign(out, ripple);
-    // Written only when the fold produced something: an unconditional assignment would put an
-    // `accessibilityState: undefined` key on every lowered Pressable in the tree, and `fabricProps`
-    // skipping undefined is a coincidence to lean on, not a contract to rely on here.
-    if (resolved !== undefined)
-        out.accessibilityState = resolved;
-    return out;
+// The one thing that did NOT move with it is `hitSlop`, and that is deliberate — it is a real
+// native View prop, so it never was part of the fold.
+// RN makes every pressable accessible unless the app opts OUT — `Pressable.js:252`
+// (`accessible: accessible !== false`), and the whole Touchable family repeats it verbatim
+// (`TouchableOpacity.js:303`, `TouchableHighlight.js:337`). `!== false` rather than `?? true`, so
+// only a literal `false` opts out and an explicit `undefined` still reads as accessible.
+//
+// Nothing in this repo did it until 2026-09-09, so a Pressable reached a screen reader as a plain
+// view unless the app wrote the prop. Exported so anything composing this tag can say it too.
+export function accessibleUnlessOptedOut(props) {
+    return props.accessible !== false;
 }
-// From the STASH, not from `node.props`. Every name below is in `ownedListeners`, so `routeProp`
+// From the STASH, not from the props. Every name below is in `ownedListeners`, so `routeProp`
 // diverts the app's `onPress` away from `node.listeners` (where it would evict the behavior's own
 // dispatcher) and into the stash — which makes the stash the only place it exists. Reading
-// `node.props` here returns undefined for every callback and every press silently does nothing:
+// `propOf` here returns undefined for every callback and every press silently does nothing:
 // the behavior runs, the machine runs, and it calls nobody.
 function callbackAt(node, event) {
     const value = appListenerFor(node, event);
     return isPressHandler(value) ? value : undefined;
 }
-// Callbacks come from `callbackAt` (the stash), scalars from `node.props`. The split is not
+// Callbacks come from `callbackAt` (the stash), scalars from `propOf`. The split is not
 // cosmetic: `delayLongPress` and `hitSlop` are ordinary props that `fabricProps` drops as unknown
-// keys, while `onPress` and friends are OWNED event names that never reach `node.props` at all.
+// keys, while `onPress` and friends are OWNED event names that never reach the props at all.
 function configFor(node) {
+    const unstablePressDelay = numberOr(propOf(node, 'unstable_pressDelay'), 0);
     return {
         onPress: callbackAt(node, 'press'),
         onPressIn: callbackAt(node, 'pressIn'),
         onPressOut: callbackAt(node, 'pressOut'),
         onPressMove: callbackAt(node, 'pressMove'),
         onLongPress: callbackAt(node, 'longPress'),
-        delayLongPress: numberOr(node.props.delayLongPress, DEFAULT_DELAY_LONG_PRESS_MS),
-        unstable_pressDelay: numberOr(node.props.unstable_pressDelay, 0),
-        hitSlop: asRectOffset(node.props.hitSlop),
-        pressRetentionOffset: asRectOffset(node.props.pressRetentionOffset),
+        // Pressability.js:471-474 — `normalizeDelay(authored, 10, DEFAULT_LONG_PRESS_DELAY_MS -
+        // delayPressIn)`. The subtraction applies only to the FALLBACK, never to an authored value —
+        // it exists so the long-press threshold, timed from the grant that also arms
+        // `unstable_pressDelay`, lands at a constant 500ms from touch-down by default, not
+        // 500ms + unstable_pressDelay. See `createPressHandlers`'s `handlePressIn` for the other half
+        // (the timer must be ARMED at grant, not after the pressDelay fires, or this compensation
+        // does nothing).
+        delayLongPress: Math.max(10, numberOr(propOf(node, 'delayLongPress'), DEFAULT_DELAY_LONG_PRESS_MS - unstablePressDelay)),
+        unstable_pressDelay: unstablePressDelay,
+        // RN's Touchables own the deactivation floor in their OWN machine and hand Pressability
+        // `minPressDuration: 0` (TouchableOpacity.js:195). While they were wrappers they passed it as
+        // an internal input; on the tag there is nowhere else to say it, so the floor has to be a
+        // readable prop or every Touchable holds its fade for the machine's 130 ms default.
+        minPressDuration: numberOr(propOf(node, 'minPressDuration'), DEFAULT_MIN_PRESS_DURATION_MS),
+        hitSlop: asRectOffset(propOf(node, 'hitSlop')),
+        pressRetentionOffset: asRectOffset(propOf(node, 'pressRetentionOffset')),
+        // Pressable.js's own name is `android_disableSound`; every composed touchable (Highlight,
+        // NativeFeedback, WithoutFeedback, Button) instead forwards vendor's `touchSoundDisabled` to
+        // this same config field (`TouchableHighlight.js:205`, `TouchableWithoutFeedback.js:199`,
+        // `TouchableNativeFeedback.js:228`). `node` here is whichever tag AUTHORS the prop — itself for
+        // a plain pressable/highlight/button, the owner for a clone-onto-child touchable, since
+        // `configFor` is always called with that source — so reading both names off it resolves
+        // correctly for every composition without a per-tag override.
+        android_disableSound: booleanOr(propOf(node, 'android_disableSound')) ??
+            booleanOr(propOf(node, 'touchSoundDisabled')),
     };
 }
 // Rebuilding at GESTURE START is the whole reason for the dispatcher indirection, and skipping it
 // is a bug that looks like working code. `attach` runs inside `createElement`, before a single
-// prop has been routed — `node.props` is literally `{}` there — so a machine built at attach would
+// prop has been routed — the node holds nothing at all there — so a machine built at attach would
 // capture no `onPress` at all and every press would silently do nothing. `createPressHandlers`
 // destructures its config eagerly, so it cannot be handed a live view either; it has to be re-made
 // once the props exist. A gesture is one interaction, so a handful of closures per press is
 // invisible — unlike doing it per prop write, which is the cost this whole tier exists to remove.
 function rebuild(node, state) {
-    const handlers = createPressHandlers(configFor(node), state.runtime, state.host);
+    // `state.source` for everything READ, `node` for the refinement, which acts on the responder
+    // (dispatching a view command needs the committed node, not the one holding the props).
+    const source = state.source;
+    const base = configFor(source);
+    const handlers = createPressHandlers(state.refine === undefined ? base : state.refine(node, base), state.runtime, state.host);
     state.isBuilt = true;
+    // Re-read every gesture, so a tag whose resolver looks past `disabled` — `./button`, at
+    // `aria-disabled` — re-enables on the next touch instead of latching at its first answer.
+    const sourceProps = propsOf(source);
+    const disabled = state.disabledOf === undefined
+        ? sourceProps.disabled
+        : state.disabledOf(sourceProps);
     state.listeners = buildPressableListeners(handlers, {
-        disabled: node.props.disabled === true ? true : undefined,
-        cancelable: typeof node.props.cancelable === 'boolean'
-            ? node.props.cancelable
-            : undefined,
+        disabled: disabled === true ? true : undefined,
+        cancelable: resolveCancelable(source),
+        blockNativeResponder: propOf(source, 'blockNativeResponder') === true,
     });
 }
+// Pressable is the only member of the family with a `cancelable` prop of its own (`Pressable.js:41`).
+// TouchableOpacity/TouchableHighlight/TouchableNativeFeedback instead expose `rejectResponderTermination`
+// and derive `cancelable: !this.props.rejectResponderTermination` internally
+// (`TouchableOpacity.js:186`, `TouchableHighlight.js:194`, `TouchableNativeFeedback.js:217`) — every
+// composed touchable shares this `rebuild()`, so without this the authored name never reached the
+// machine and every Touchable silently kept the RN native default (yield the responder) regardless of
+// what the app asked for. An explicit `cancelable` still wins, matching Pressable's own precedence.
+function resolveCancelable(source) {
+    const cancelable = propOf(source, 'cancelable');
+    if (typeof cancelable === 'boolean')
+        return cancelable;
+    const reject = propOf(source, 'rejectResponderTermination');
+    return typeof reject === 'boolean' ? !reject : undefined;
+}
 // WHICHEVER EVENT OPENS THE GESTURE REBUILDS, and pinning that to one name was a real bug.
 // `onStartShouldSetResponder` looks like the opener and is not: `core/engine/src/events/index.ts`
 // bubbles PRESS_IN and only THEN calls `negotiateResponder`, so `pressIn` arrives FIRST on every
@@ -222,13 +231,31 @@ const KEY_BY_EVENT = new Map([
     ['startShouldSetResponder', 'onStartShouldSetResponder'],
     ['responderMove', 'onResponderMove'],
     ['responderTerminationRequest', 'onResponderTerminationRequest'],
+    ['responderGrant', 'onResponderGrant'],
 ]);
 function installListeners(node, state) {
     for (const [event, key] of KEY_BY_EVENT) {
         setBehaviorListener(node, event, symbioteEvent => dispatch(node, state, key, [symbioteEvent]));
     }
 }
-function attach(node) {
+function attachWith(refine, disabledOf) {
+    return node => attach(node, { refine, disabledOf });
+}
+/**
+ * The machine on `node`, reading its props and the app's callbacks off `options.source` when that
+ * is a different node.
+ *
+ * Exported for a behavior whose responder is not its own node — `./touchable-native-feedback`,
+ * whose tag commits nothing and adopts the app's single child as the responder. Every other caller
+ * goes through `createPressBehavior`, where source and node are the same.
+ *
+ * Re-callable on the same node: a second call replaces the state and the dispatchers, which is what
+ * a re-arm after `detachPressMachine` needs.
+ */
+export function attachPressMachine(node, options = {}) {
+    attach(node, options);
+}
+function attach(node, options) {
     const timers = new Set();
     const runtime = createPressRuntime();
     const host = {
@@ -264,6 +291,9 @@ function attach(node) {
     const state = {
         runtime,
         host,
+        refine: options.refine,
+        disabledOf: options.disabledOf,
+        source: options.source ?? node,
         timers,
         listeners: {},
         isBuilt: false,
@@ -271,6 +301,10 @@ function attach(node) {
     states.set(node, state);
     installListeners(node, state);
 }
+/** See `attachPressMachine`: the same teardown `createPressBehavior` registers as its `detach`. */
+export function detachPressMachine(node) {
+    detach(node);
+}
 function detach(node) {
     const state = states.get(node);
     if (state === undefined)
@@ -286,13 +320,19 @@ function detach(node) {
     states.delete(node);
     dlog('pressable behavior detached');
 }
-// Idempotent: an adapter entry may be imported more than once in a bundle, and re-registering the
-// same tag with an equivalent behavior must not double-install anything.
-export function registerPressableBehavior() {
-    registerHostBehavior(PRESSABLE_TAG, {
-        attach,
+/**
+ * The press machine as behavior parts, so a tag that is a pressable PLUS something can compose it
+ * instead of re-implementing it.
+ *
+ * Spread into the caller's own behavior and wrap `attach`/`detach` around these — the touchable
+ * family needs a per-node Animated value opened before the machine and closed after it. The
+ * WeakMap holding the machine's own state is keyed by node, so one node may hold exactly one of
+ * these; a tag composing it therefore must not also register the plain `pressable` behavior.
+ */
+export function createPressBehavior(refine, disabledOf) {
+    return {
+        attach: attachWith(refine, disabledOf),
         detach,
-        foldPayload,
         // Every name the machine needs as an INPUT. The responder pair is not optional — it is how a
         // gesture starts at all, and `RESPONDER_EVENTS` makes those listeners on any node regardless
         // of ViewConfig, so they collide exactly like `press` does.
@@ -305,6 +345,12 @@ export function registerPressableBehavior() {
             'startShouldSetResponder',
             'responderMove',
             'responderTerminationRequest',
+            'responderGrant',
         ],
-    });
+    };
+}
+// Idempotent: an adapter entry may be imported more than once in a bundle, and re-registering the
+// same tag with an equivalent behavior must not double-install anything.
+export function registerPressableBehavior() {
+    registerHostBehavior(PRESSABLE_TAG, createPressBehavior());
 }

package/build/behaviors/refresh-control.d.ts

@@ -0,0 +1,2 @@
+export declare const REFRESH_CONTROL_TAG = "refresh-control";
+export declare function registerRefreshControlBehavior(): void;

package/build/behaviors/refresh-control.js

@@ -0,0 +1,96 @@
+// RefreshControl's machine, on the engine node instead of inside a framework component.
+//
+// WHAT THE FIVE WRAPPERS ACTUALLY DO, counted before writing this — the audit rule's instruction to
+// grep the fold's OUTPUT rather than trust one wrapper. Four of the five (react, vue, solid,
+// svelte) fold exactly `resolveAccessibilityProps` and forward, and that fold ALREADY runs in the
+// engine at `fabricProps` on every path (the aria fold `SafeAreaView`'s spec entry cites). So there
+// is nothing left for a `foldPayload` here to do, and this behavior deliberately declares none.
+//
+// The fifth is Angular, and it is the whole reason this file exists: it alone reproduces RN's
+// CONTROLLED handshake (`RefreshControl.js:145-166`) — mirror what native last reported, and when
+// the app's `refreshing` disagrees, command native back with `setNativeRefreshing`. React, Vue,
+// Solid and Svelte have never had it, so a pull whose handler leaves `refreshing` false spins
+// forever on four of five adapters. Moving it here closes that as a P0 parity gap rather than
+// porting it four more times.
+//
+// ONE COMMAND NAME ON BOTH PLATFORMS — no `Platform.OS` branch, unlike Switch's snap-back
+// (`setValue` / `setNativeValue`). RN sends `setNativeRefreshing` through both
+// `PullToRefreshCommands` and `AndroidSwipeRefreshLayoutCommands` (`RefreshControl.js:152,157`).
+//
+// PLACEMENT IS NOT THIS FILE'S PROBLEM, though the tier audit once filed the primitive as
+// impossible over it. iOS puts the control BESIDE the scroll view's content and Android makes it
+// the scroll view's PARENT, and that decision belongs to the ScrollView, which now states it as
+// data — `claimedChildren: { [REFRESH_CONTROL]: platform.claimMode }` in
+// `behaviors/scroll-view/shared.ts`, honoured by the engine's `appendChild`. A claim is keyed on
+// the child's FABRIC name and needs nothing from the child's own behavior, so the two are
+// independent; `refresh-control-placement.test.ts` pins that both ways round.
+//
+// WHY THE DIVERGENCE CHECK IS DEFERRED A MICROTASK, and why `afterCommit` alone is not enough:
+// `behaviors/switch.ts`'s module header, verbatim. Same shape, same two triggers, same reasons —
+// an ACCEPTING app's state reaches `node.props` only after its own reconciliation, and a REJECTING
+// app writes no prop at all, so the commit that `afterCommit` waits for never comes.
+import { appListenerFor, dispatchViewCommand, dlog, registerHostBehavior, setBehaviorListener, propOf, } from '@symbiote-native/engine';
+export const REFRESH_CONTROL_TAG = 'refresh-control';
+// RN's own name for the command, sent to whichever of the two native views the platform resolved.
+const SET_NATIVE_REFRESHING = 'setNativeRefreshing';
+// What native LAST reported, absent until it has reported at all. Absent is not `false`: native is
+// optimistic — it spins on the gesture before JS approves — so only a report can make the mirror
+// authoritative, and an app that drives `refreshing` on its own initiative must never be corrected
+// against a value native never claimed.
+const reported = new WeakMap();
+// TODO(rn-parity, low priority, efficiency not correctness): vendor's `componentDidUpdate`
+// (`RefreshControl.js:139-158`) sends `setNativeRefreshing` only when `refreshing` did NOT change
+// between renders, trusting the ordinary prop diff to carry a real change to native. Ours has no
+// such guard — `evaluateSnapBack` fires the command on any disagreement with `reported`, even when
+// this same commit already carries the authored `refreshing` change (accept-then-finish: app agrees
+// on the gesture, then sets `refreshing: false` to end it — vendor sends zero commands, we send one
+// extra). Both settle on the same native value, so this is a harmless redundant call, not a bug —
+// and NOT a candidate for the same fix as the "repairs a snap-back the app contradicts on a later
+// commit" test below, which relies on this exact unconditional re-check for a genuine cross-
+// framework microtask race. A real fix needs tracking the last-seen authored value alongside
+// `reported`, so a same-commit authored change can be told apart from native drifting on its own —
+// not attempted here.
+//
+// Shared by both triggers — see the module header for why there are two.
+function evaluateSnapBack(node) {
+    const lastNativeReport = reported.get(node);
+    if (lastNativeReport === undefined)
+        return; // no report yet, nothing to disagree with
+    const refreshing = propOf(node, 'refreshing') === true;
+    if (lastNativeReport === refreshing) {
+        dlog(`RefreshControl behavior snap-back no-op refreshing=${refreshing}`);
+        return;
+    }
+    dlog(`RefreshControl behavior ${SET_NATIVE_REFRESHING} reported=${lastNativeReport} refreshing=${refreshing}`);
+    dispatchViewCommand(node, SET_NATIVE_REFRESHING, [refreshing]);
+    reported.set(node, refreshing);
+}
+function onRefresh(node, event) {
+    // Native has already started spinning by the time this arrives (RefreshControl.js:180), so the
+    // mirror moves BEFORE the app's handler runs — a handler that flips `refreshing` to true then
+    // agrees with it, and one that does nothing is what the deferred check corrects.
+    reported.set(node, true);
+    const listener = appListenerFor(node, 'refresh');
+    if (typeof listener === 'function')
+        listener(event);
+    queueMicrotask(() => evaluateSnapBack(node));
+}
+function attach(node) {
+    setBehaviorListener(node, 'refresh', event => onRefresh(node, event));
+}
+function detach(node) {
+    reported.delete(node);
+}
+// Idempotent: an adapter entry may be imported more than once in a bundle, and re-registering the
+// same tag with an equivalent behavior must not double-install anything.
+export function registerRefreshControlBehavior() {
+    registerHostBehavior(REFRESH_CONTROL_TAG, {
+        attach,
+        // Closes the case a microtask scheduled from `onRefresh` cannot: the app moves `refreshing` on
+        // its own while a past report is still unresolved. Costs nothing extra — it fires only on a
+        // commit that already changed something.
+        afterCommit: evaluateSnapBack,
+        detach,
+        ownedListeners: ['refresh'],
+    });
+}

package/build/behaviors/scroll-view/index.android.d.ts

@@ -0,0 +1 @@
+export declare function registerScrollViewBehavior(): void;

package/build/behaviors/scroll-view/index.android.js

@@ -0,0 +1,40 @@
+// ScrollView's behavior on Android, where a RefreshControl is not a child at all.
+//
+// An Android ScrollView holds exactly ONE child, so a sibling refresh control is an `addViewAt`
+// crash rather than a layout mistake. RN inverts the tree instead: `AndroidSwipeRefreshLayout`
+// WRAPS the scroll view, and the scroll view's style is split across the two boxes — layout on the
+// wrapper's frame, visual on the scroller (`ScrollView.js:1856`). `nestedScrollEnabled` goes on the
+// inner view so it consumes the gesture before the refresh parent sees it.
+//
+// THIS FILE IS A CLAIM MODE AND NOTHING ELSE NOW (2026-09-18). It carried two `payloadFold`s until
+// then — the last two folds in ScrollView and the last structural blocker in the behavior
+// migration — and both are `SymbioteFabricProps.cpp` now: `foldScrollViewProps` takes the visual
+// half when its parent is a refresh control, and `foldRefreshWrapperProps` takes the layout half of
+// the child it wraps.
+//
+// WHY THEY RESISTED THREE ITERATIONS, and what changed. Every seam the engine had read UP —
+// `ownerProps`, `IOwner.tagName`, `IAncestorLookup` — and the wrapper is the scroll view's PARENT
+// asking for the scroll view's style, the one direction none of them go. `IFirstChild` is that
+// direction, and it is the same argument `ownerProps` already made rather than a new one: the tree
+// lives in C++, so reading another node is a pointer hop, and RN itself builds this parent FROM its
+// child (`cloneElement(refreshControl, {style: outer}, scrollView)`).
+//
+// `slotDerived: ['style']` STAYS AND IS NOW LOAD-BEARING FOR THE ENGINE'S RULE. A rule re-runs when
+// ITS node is dirty; the wrapper derives from a node that is not itself, so an owner style write
+// must mark it (`routeProp`'s `node.wrapper` branch). Without this entry the wrapper freezes at its
+// mount frame while the scroller visibly restyles inside it —
+// `core/engine/cpp/tests/js/scroll-view-wrap-payload.itest.ts` is the case that says so.
+//
+// AND NOTHING HERE IS `#ifdef ANDROID` OR `Platform.OS`, on either side: the engine's rules are
+// gated on TOPOLOGY. iOS claims the refresh control BESIDE the content, so a scroll view is never
+// one's child there and neither branch can fire. That is strictly better than a compile-time split
+// for the reason `Switch`/`AndroidSwitch` already showed — and it is why the wrap's payload fixture
+// runs on the ORDINARY test host rather than needing the Android arm.
+import { registerScrollViewBehaviors } from './shared.js';
+const android = {
+    claimMode: 'wrap',
+    slotDerived: ['style'],
+};
+export function registerScrollViewBehavior() {
+    registerScrollViewBehaviors(android);
+}

package/build/behaviors/scroll-view/index.d.ts

@@ -0,0 +1,3 @@
+export { registerScrollViewBehavior } from './index.ios';
+export { HORIZONTAL_SCROLL_VIEW_TAG, REFRESH_CONTROL, SCROLL_VIEW_TAG, } from './shared';
+export { STICKY_HEADER_TAG } from './sticky';

package/build/behaviors/scroll-view/index.ios.d.ts

@@ -0,0 +1 @@
+export declare function registerScrollViewBehavior(): void;

package/build/behaviors/scroll-view/index.ios.js

@@ -0,0 +1,10 @@
+// ScrollView's behavior on iOS: a RefreshControl is a SIBLING of the content view, rendered before
+// it (`ScrollView.js:1844`). That is the whole platform half — a claim in `beside` mode, and the
+// engine's placement rule already puts a claimed child before the slot.
+//
+// This file is also the base the folder's `index.ts` re-exports for headless, matching
+// `render-scroll-view`'s own choice to make iOS the default for anything platform-branched.
+import { registerScrollViewBehaviors } from './shared.js';
+export function registerScrollViewBehavior() {
+    registerScrollViewBehaviors({ claimMode: 'beside' });
+}

package/build/behaviors/scroll-view/index.js

@@ -0,0 +1,8 @@
+// The base of the folder-as-module group: Metro picks `index.ios` / `index.android` per platform,
+// and everything else (tsx, vitest, headless) lands here. iOS is the default for the same reason
+// `render-scroll-view`'s own `Platform.select` defaults to it.
+export { registerScrollViewBehavior } from './index.ios.js';
+export { HORIZONTAL_SCROLL_VIEW_TAG, REFRESH_CONTROL, SCROLL_VIEW_TAG, } from './shared.js';
+// The tag, so a test can locate a committed sticky wrapper by what the engine was TOLD rather than
+// by a key its tag rule writes — see `ILiveNode.tagName`.
+export { STICKY_HEADER_TAG } from './sticky.js';

package/build/behaviors/scroll-view/responder.d.ts

@@ -0,0 +1,4 @@
+import { type ISymbioteNode } from '@symbiote-native/engine';
+export declare function markScrollObserved(owner: ISymbioteNode): void;
+export declare const RESPONDER_OWNED_LISTENERS: readonly string[];
+export declare function installResponderPredicates(owner: ISymbioteNode): void;