@symbiote-native/components 0.5.0 → 2.0.0

package/build/behaviors/input-accessory-view.js

@@ -0,0 +1,70 @@
+// InputAccessoryView's host behavior — a prop fold and nothing else. No listeners, no timers, no
+// commit hook: the wrapper's whole body was prop mapping, so its lowered form owes exactly that.
+//
+// The fold is NOT written here. `mapInputAccessoryViewProps` in
+// `../view/render-input-accessory-view` is the one implementation and this file only narrows a flat
+// bag into the typed view it takes, the `stringOf` / `styleOf` guard idiom `behaviors/image.ts`
+// uses. Counted before starting, which is step one of the fold-only recipe: unlike Image, which had
+// THREE implementations, all five adapters already call the shared render fn and Svelte's
+// `input-accessory-view-props.ts` is a type declaration rather than a second mapping. So there was
+// one implementation to extract, not three to collapse.
+//
+// SHARES THE WRAPPER'S TAG, no `-managed` twin. The two questions the recipe separates both answer
+// no: the fold is idempotent (there is no aliasing at all — every consumed name leaves under the
+// same name, so a second pass rewrites the same values), and the behavior carries no machine, so
+// nothing can end up with two owners on one node. Idempotence is asserted rather than reasoned.
+//
+// PLATFORM. This is the only primitive in its group that is not platform-invariant in what it
+// COMMITS TO: `input-accessory-view` resolves to `RCTInputAccessoryView` on iOS and to a
+// plain `RCTView` on Android. The fold itself is platform-invariant on purpose — it reproduces the
+// wrapper's mapping exactly, on both platforms, so the lowered and wrapped paths cannot diverge
+// per-platform. What it does NOT do is fix the pre-existing Android divergence underneath it:
+// upstream RN renders NOTHING there (`InputAccessoryView.js` — `console.warn('<InputAccessoryView>
+// is only supported on iOS.'); return null`), while we commit an RCTView, and `backgroundColor` is
+// a declared prop of the iOS view but a style key on RCTView. Both predate this behavior and are
+// identical on both paths; neither is in scope here, and a fold that "fixed" one silently would
+// make the two paths disagree.
+import { registerHostBehavior, } from '@symbiote-native/engine';
+import { INPUT_ACCESSORY_VIEW_PROP_NAMES, mapInputAccessoryViewProps, } from '../view/render-input-accessory-view.js';
+export const INPUT_ACCESSORY_VIEW_TAG = 'input-accessory-view';
+const CONSUMED = new Set(INPUT_ACCESSORY_VIEW_PROP_NAMES);
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+// A StyleProp is an object, an array of them, or a registered class array — all shapes
+// `flattenStyle` already handles. Only a scalar has to be excluded.
+function styleOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return { ...value };
+}
+export function foldInputAccessoryViewPayload(props) {
+    const passthrough = {};
+    for (const key of Object.keys(props)) {
+        if (!CONSUMED.has(key))
+            passthrough[key] = props[key];
+    }
+    return mapInputAccessoryViewProps({
+        nativeID: stringOf(props.nativeID),
+        backgroundColor: stringOf(props.backgroundColor),
+        style: styleOf(props.style),
+        passthrough,
+    });
+}
+// Required by IHostBehavior and deliberately empty: this primitive owns no per-node runtime.
+// Written out rather than shared with a `noop` so the emptiness reads as a decision.
+function attach(_node) {
+    // nothing to set up
+}
+function detach(_node) {
+    // nothing to release
+}
+export function registerInputAccessoryViewBehavior() {
+    registerHostBehavior(INPUT_ACCESSORY_VIEW_TAG, {
+        attach,
+        detach,
+        foldPayload: foldInputAccessoryViewPayload,
+    });
+}

package/build/behaviors/pressable.d.ts

@@ -0,0 +1,60 @@
+import { type IHostBehavior, type ISymbioteNode } from '@symbiote-native/engine';
+import { type IPressMachineConfig } from '../state/pressable';
+import type { IAccessibilityStateValue } from '../accessibility-props';
+export declare const PRESSABLE_TAG = "pressable";
+/**
+ * A last look at the machine's config before its handlers are built, for a tag that IS a pressable
+ * plus something — TouchableOpacity, whose fade has to run between the machine and the app's own
+ * `onPressIn`.
+ *
+ * Called from `rebuild`, so once per gesture rather than once per mount: it sees the config the
+ * props actually hold by the time a finger lands, and anything it captures is discarded with the
+ * gesture. Per-node state that must OUTLIVE a gesture belongs on the caller's own WeakMap.
+ */
+export type IPressConfigRefinement = (node: ISymbioteNode, config: IPressMachineConfig) => IPressMachineConfig;
+/**
+ * What the machine reads as `disabled`, for a tag whose spelling of it is not the raw prop.
+ *
+ * There is no resolver by default because RN's Pressable hands Pressability the RAW prop
+ * (`Pressable.js:266`) — `aria-disabled` there changes only what is ANNOUNCED. Button is the one
+ * primitive that differs: it resolves `disabled ?? aria-disabled ?? accessibilityState.disabled` in
+ * the component and passes the ANSWER down as the touchable's own prop (`Button.js:337` -> `:386`),
+ * which a single tag has no second node to pass to.
+ *
+ * Reads the bag and returns the answer; it must never write one back. `resolveButtonDisabled`
+ * short-circuits on an authored `disabled`, so a resolved value stored in `node.props.disabled`
+ * would answer the NEXT resolution as if the app had written it and the tag could never re-enable.
+ */
+export type IDisabledResolver = (props: Readonly<Record<string, unknown>>) => boolean | undefined;
+export declare function booleanOr(value: unknown): boolean | undefined;
+export declare function asAccessibilityState(value: unknown): IAccessibilityStateValue | undefined;
+export declare function accessibleUnlessOptedOut(props: Readonly<Record<string, unknown>>): boolean;
+/**
+ * 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 declare function attachPressMachine(node: ISymbioteNode, options?: {
+    readonly refine?: IPressConfigRefinement;
+    readonly disabledOf?: IDisabledResolver;
+    readonly source?: ISymbioteNode;
+}): void;
+/** See `attachPressMachine`: the same teardown `createPressBehavior` registers as its `detach`. */
+export declare function detachPressMachine(node: ISymbioteNode): void;
+/**
+ * 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 declare function createPressBehavior(refine?: IPressConfigRefinement, disabledOf?: IDisabledResolver): Pick<IHostBehavior, 'attach' | 'detach' | 'foldPayload' | 'ownedListeners'>;
+export declare function registerPressableBehavior(): void;

package/build/behaviors/pressable.js

@@ -0,0 +1,385 @@
+// The press machine as an ENGINE-NODE behavior, so a pressable can be an intrinsic tag instead of
+// a framework component (`.claude/rules/host-primitive-tier.md`, tier 2). Written once; every
+// adapter inherits it by registering, and none re-implements it.
+//
+// The machine itself is unchanged and still shared with the component path — `createPressRuntime`
+// / `createPressHandlers` in `../state/pressable`. What is new is only WHERE its lifecycle lives:
+// on the engine node rather than in a component instance.
+//
+// REGISTRATION IS THE HAZARD, not the machine. Metro enables `inlineRequires` in production only,
+// moving a `require` to the first place its binding is used as a VALUE, and a barrel's
+// `export { X } from './x'` compiles to a lazy getter. A module whose only job is a side effect is
+// never named as a value, so re-exporting it means it NEVER RUNS in a release build — dev perfect,
+// release silently pressless. Each adapter therefore keeps its own `src/register.ts` calling
+// `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, DEFAULT_MIN_PRESS_DURATION_MS, rippleProps, } from '../state/pressable.js';
+import { buildPressableListeners, resolveDisabledAccessibilityState, resolvePressableFocusable, } 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);
+}
+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.
+function asRectOffset(value) {
+    if (typeof value === 'number')
+        return value;
+    if (!isRecord(value))
+        return undefined;
+    const rect = {};
+    if (typeof value.top === 'number')
+        rect.top = value.top;
+    if (typeof value.left === 'number')
+        rect.left = value.left;
+    if (typeof value.bottom === 'number')
+        rect.bottom = value.bottom;
+    if (typeof value.right === 'number')
+        rect.right = value.right;
+    return rect;
+}
+// A predicate rather than a bare `typeof`: `typeof x === 'function'` narrows to `Function`, which
+// carries no call signature and cannot satisfy IPressHandler. Guard, never cast. Also used for the
+// listener bag, whose values are `unknown` for the same reason.
+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',
+    'minPressDuration',
+    '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`) — 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 = {};
+    if (typeof value.disabled === 'boolean')
+        state.disabled = value.disabled;
+    if (typeof value.selected === 'boolean')
+        state.selected = value.selected;
+    if (value.checked === 'mixed' || typeof value.checked === 'boolean')
+        state.checked = value.checked;
+    if (typeof value.busy === 'boolean')
+        state.busy = value.busy;
+    if (typeof value.expanded === 'boolean')
+        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.
+//
+// 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;
+    out.accessible = accessibleUnlessOptedOut(props);
+    // Pressable.js:258 — the plain form, with no press-handler or disabled leg. A Touchable composing
+    // this tag has already resolved its own three-leg formula and passed the answer in as `focusable`,
+    // which `!== false` leaves alone.
+    out.focusable = resolvePressableFocusable(booleanOr(props.focusable));
+    return out;
+}
+// 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, on either path, so a Pressable reached a screen
+// reader as a plain view unless the app wrote the prop. Landing it in the fold above alone reddens
+// four equivalence arms — correctly, since those compare the wrapper against the lowered path — so
+// the behavior and every adapter's wrapper have to move in ONE change. Exported for the wrappers
+// that need to say it themselves, and for the tags whose behavior is their only path.
+export function accessibleUnlessOptedOut(props) {
+    return props.accessible !== false;
+}
+// From the STASH, not from `node.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:
+// 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
+// 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.
+function configFor(node) {
+    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),
+        // 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(node.props.minPressDuration, DEFAULT_MIN_PRESS_DURATION_MS),
+        hitSlop: asRectOffset(node.props.hitSlop),
+        pressRetentionOffset: asRectOffset(node.props.pressRetentionOffset),
+    };
+}
+// 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
+// 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) {
+    // `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 disabled = state.disabledOf === undefined
+        ? source.props.disabled
+        : state.disabledOf(source.props);
+    state.listeners = buildPressableListeners(handlers, {
+        disabled: disabled === true ? true : undefined,
+        cancelable: typeof source.props.cancelable === 'boolean'
+            ? source.props.cancelable
+            : 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
+// gesture. Rebuilding only on the responder claim therefore handed the first `pressIn` an empty
+// listener bag — the press-in half of every press was dropped, the pressed style never reached
+// Fabric, and `onPress` still fired because by then the machine existed. That is exactly the
+// device report: the callback works, the button does not light up.
+//
+// So the trigger is a FLAG, not a name: build if this gesture has not built yet, and clear it when
+// the gesture ends. Order-independent, and it survives the engine reordering its own events.
+//
+// A key `buildPressableListeners` omitted — every one of them when `disabled` is true — resolves to
+// undefined here and the dispatcher returns undefined, which is what an absent listener would do.
+const GESTURE_END_KEYS = new Set([
+    'onPressOut',
+    'onResponderTerminationRequest',
+]);
+function dispatch(node, state, key, args) {
+    if (!state.isBuilt)
+        rebuild(node, state);
+    const listener = state.listeners[key];
+    const result = isPressHandler(listener)
+        ? Reflect.apply(listener, undefined, args)
+        : undefined;
+    // AFTER the handler, not before: `handlePressOut` is what settles the machine, and clearing the
+    // flag first would let a re-entrant dispatch rebuild mid-gesture.
+    if (GESTURE_END_KEYS.has(key))
+        state.isBuilt = false;
+    return result;
+}
+// Installed straight into the listener slot rather than through `routeProp`: the behavior OWNS
+// these names, and `setEventListener` diverts an owned name into the app stash — routing its own
+// dispatcher through there would stash it and leave the slot empty.
+//
+// The engine event names, not the `onX` prop spellings. `buildPressableListeners` speaks the prop
+// spelling, so the two are mapped here rather than guessed at either end.
+const KEY_BY_EVENT = new Map([
+    ['press', 'onPress'],
+    ['pressIn', 'onPressIn'],
+    ['pressOut', 'onPressOut'],
+    ['startShouldSetResponder', 'onStartShouldSetResponder'],
+    ['responderMove', 'onResponderMove'],
+    ['responderTerminationRequest', 'onResponderTerminationRequest'],
+]);
+function installListeners(node, state) {
+    for (const [event, key] of KEY_BY_EVENT) {
+        setBehaviorListener(node, event, symbioteEvent => dispatch(node, state, key, [symbioteEvent]));
+    }
+}
+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 = {
+        // The whole reason this tier is possible: the pressed state resolves BELOW the framework,
+        // through the style registry's `:active` variant, and never crosses into it.
+        setPressed: pressed => {
+            setNodePressed(node, pressed);
+            // Dirtying is not publishing. A press arrives from a native event, outside every renderer
+            // mutation path, so nothing schedules a commit — `native-events.ts` requests none, and no
+            // adapter does either. `setNodeHidden`'s React twin never hit this because the reconciler is
+            // already in its commit phase when it calls.
+            requestCommitFor(node);
+        },
+        // `measure` needs a committed Fabric tag, which a node has by the time a human can touch it.
+        // Returning undefined before then makes the machine fall back to its radius test rather than
+        // throwing, which is the behaviour the component path already relies on.
+        getMeasureFn: () => callback => node.measure(callback),
+        // Tracked so `detach` can cancel them. An un-cancelled long-press timer outlives the tree that
+        // owned it, and `removeChild` visits only a subtree ROOT — a pressable is normally nested.
+        schedule: (callback, ms) => {
+            const id = setTimeout(() => {
+                timers.delete(id);
+                callback();
+            }, ms);
+            timers.add(id);
+            return () => {
+                clearTimeout(id);
+                timers.delete(id);
+            };
+        },
+        now: Date.now,
+    };
+    const state = {
+        runtime,
+        host,
+        refine: options.refine,
+        disabledOf: options.disabledOf,
+        source: options.source ?? node,
+        timers,
+        listeners: {},
+        isBuilt: false,
+    };
+    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)
+        return;
+    // The machine's own teardown, which every wrapper calls from its destroy hook. Not load-bearing
+    // here and no test can make it so: `host.schedule` puts every timer the machine arms into
+    // `state.timers` — the 130ms floor's deferred `pressOut` included — so the loop below already
+    // cancels them. Kept as the contract, and for a timer armed by some future route.
+    disposePressRuntime(state.runtime);
+    for (const id of state.timers)
+        clearTimeout(id);
+    state.timers.clear();
+    states.delete(node);
+    dlog('pressable behavior detached');
+}
+/**
+ * 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.
+        ownedListeners: [
+            'press',
+            'pressIn',
+            'pressOut',
+            'pressMove',
+            'longPress',
+            'startShouldSetResponder',
+            'responderMove',
+            'responderTerminationRequest',
+        ],
+    };
+}
+// 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,83 @@
+// 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, } 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();
+// 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 = node.props.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,52 @@
+// 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.
+//
+// The two folds below are what neither node can work out alone: the wrapper is the APP's node, so
+// it carries whatever the app wrote on `<RefreshControl>` and knows nothing about the scroll view's
+// style. RN reaches the same place through `cloneElement`, which likewise OVERRIDES the refresh
+// control's own `style` — so replacing it here is parity, not a liberty.
+import {} from '@symbiote-native/engine';
+import { splitScrollViewStyle } from '../../scroll-view-commands.js';
+import { ownerFold, registerScrollViewBehaviors, } from './shared.js';
+// The owner under a wrap: the ordinary fold with the VISUAL half of its own style in place of the
+// composed one. Delegating rather than restating is what keeps `decelerationRate`, `horizontal` and
+// `nestedScrollEnabled` in ONE place — none of the three has anything to do with the wrap, and the
+// hand-written copy this replaced had already lost the first of them.
+function wrappedOwnerFold(base, horizontal) {
+    const plain = ownerFold(base, horizontal);
+    return props => ({
+        ...plain(props),
+        style: splitScrollViewStyle(base, props.style).inner,
+    });
+}
+// The wrapper: the LAYOUT half of the OWNER's style, read off the owner because that is where the
+// app wrote it. Kept in step by `slotDerived` naming `style`, which marks the wrapper dirty on an
+// owner style write.
+function wrapperFold(owner, base) {
+    return props => ({
+        ...props,
+        style: splitScrollViewStyle(base, owner.props.style).outer,
+    });
+}
+const android = {
+    claimMode: 'wrap',
+    slotDerived: ['style'],
+    onWrapChange: (base, horizontal) => (owner, wrapper) => {
+        // Back to the ordinary composition, not to `undefined` — the plain fold carries the axis and
+        // the gesture props, which have nothing to do with the wrap.
+        owner.payloadFold =
+            wrapper === undefined
+                ? ownerFold(base, horizontal)
+                : wrappedOwnerFold(base, horizontal);
+        if (wrapper !== undefined)
+            wrapper.payloadFold = wrapperFold(owner, base);
+    },
+};
+export function registerScrollViewBehavior() {
+    registerScrollViewBehaviors(android);
+}