@symbiote-native/components 0.4.0 → 1.0.0

package/build/behaviors/pressable.js

@@ -0,0 +1,310 @@
+// 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, rippleProps, } from '../state/pressable.js';
+import { buildPressableListeners, resolveDisabledAccessibilityState, } from '../view/render-pressable/index.js';
+export const PRESSABLE_TAG = 'symbiote-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;
+}
+// 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',
+    '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) {
+    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;
+    return out;
+}
+// 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),
+        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) {
+    const handlers = createPressHandlers(configFor(node), state.runtime, state.host);
+    state.isBuilt = true;
+    state.listeners = buildPressableListeners(handlers, {
+        disabled: node.props.disabled === true ? true : undefined,
+        cancelable: typeof node.props.cancelable === 'boolean'
+            ? node.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 attach(node) {
+    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,
+        timers,
+        listeners: {},
+        isBuilt: false,
+    };
+    states.set(node, state);
+    installListeners(node, state);
+}
+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');
+}
+// 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,
+        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',
+        ],
+    });
+}

package/build/behaviors/switch.d.ts

@@ -0,0 +1,2 @@
+export declare const SWITCH_TAG = "symbiote-switch";
+export declare function registerSwitchBehavior(): void;

package/build/behaviors/switch.js

@@ -0,0 +1,182 @@
+// Switch's machine, on the engine node instead of inside a framework component — the second
+// STATEFUL primitive after TextInput (`.claude/rules/host-primitive-tier.md`, "cheapest: tag
+// exists, no handle. lastNativeReport -> dispatchViewCommand").
+//
+// WHAT A `Switch` COMPONENT ACTUALLY DOES, and why none of it needs a framework. It mirrors the
+// value native LAST REPORTED (not the value the app authors), and when the two disagree — the app
+// rejected the toggle, or its handler is a no-op — it commands native back down with the
+// platform's snap-back command (Switch.js:221-225: iOS `setValue`, Android `setNativeValue`). The
+// TEMPLATE reads none of it.
+//
+// WHY THE DIVERGENCE CHECK IS DEFERRED A MICROTASK, NOT RUN SYNCHRONOUSLY INSIDE `onChange`. The
+// obvious place to compare "what native just reported" against "what the app currently authors" is
+// right where the report arrives. It is wrong: an ACCEPTED toggle updates the app's own state, and
+// that state reaches `node.props.value` only once the app's OWN reconciliation runs — which, for
+// every adapter here, happens strictly after `onChange` returns, never during it. Checking
+// synchronously would read the STALE pre-accept value and send a spurious snap-back on every
+// accepted toggle. The wrapper avoids this by running its own check from an effect that fires AFTER
+// the app's state update has flowed into a new render (`useLayoutEffect`, `$effect`, a post-flush
+// `watch`); Angular's OWN switch component (`adapters/angular/src/components/switch/shared.ts`,
+// `snapBackIfNeeded`) already solves the identical problem for a node with no render the same way —
+// `queueMicrotask` then a plain read of the current value — and this mirrors it rather than routing
+// through `IHostBehavior.afterCommit`.
+//
+// `afterCommit` was the first design and it does NOT work here: it requires a commit that actually
+// changes something to reach `runDeferredAttaches` at all (`commit.ts`'s `!result.changed` early
+// return — the same gate `text-input.test.ts` documents), and this check on its own writes no prop.
+// Pairing it with `requestCommitFor` — which schedules a commit but writes nothing either — hits
+// exactly that early return and never fires; proven wrong by this file's own test before it shipped.
+// `queueMicrotask` sidesteps the whole question: it needs no commit, only a later turn of the
+// microtask queue, and `dispatchViewCommand` is an imperative call to native independent of Fabric's
+// prop-commit pipeline anyway.
+//
+// The residual gap this leaves, and it is why `afterCommit` is STILL registered below: a check
+// scheduled only from `onChange` never re-runs for a prop change with no preceding native event —
+// e.g. the app moves `value` on its own initiative while a PAST toggle's disagreement is still
+// unresolved. `afterCommit` costs nothing extra (it fires only on a commit that already changed
+// something) and closes that one case; the microtask path is what the no-op-handler case actually
+// needs.
+import { appListenerFor, dispatchViewCommand, dlog, Platform, registerHostBehavior, setBehaviorListener, } from '@symbiote-native/engine';
+import { createInitialSwitchState, shouldSnapBack, switchReducer, valueFromChange, } from '../state/switch.js';
+// The LOWERED tag — NOT the wrapper's `symbiote-switch-managed` (`render-switch.ts`). One owner
+// per node: the wrapper already runs this same machine in its own lifecycle, so registering here
+// under the tag it emits would attach a second, redundant copy.
+export const SWITCH_TAG = 'symbiote-switch';
+const states = new WeakMap();
+function stateOf(node) {
+    return states.get(node);
+}
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function booleanOf(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+// `{ false?, true? }` narrowed at runtime — an authored object arriving through an untyped bag
+// cannot be trusted to the type system without reading it field by field, the same idiom
+// `text-input.ts`'s `selectionOf` uses for `{ start, end? }`.
+function trackColorOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const bag = { ...value };
+    const falseColor = stringOf(bag.false);
+    const trueColor = stringOf(bag.true);
+    if (falseColor === undefined && trueColor === undefined)
+        return undefined;
+    return { false: falseColor, true: trueColor };
+}
+// The wrapper-body prop fold this primitive owes its lowered form: `trackColor` / `thumbColor` /
+// `ios_backgroundColor` are AUTHORED names, none of them a real Fabric prop — RN's Switch view
+// declares `onTintColor`/`tintColor` (iOS) or `trackColorFor*`/`trackTintColor` (Android), plus
+// `thumbTintColor`. `render-switch.ts` folds them for the wrapper path via an adapter-supplied
+// `ISwitchPlatform`; a lowered node has no adapter to supply one, so this reads `Platform.OS`
+// directly — the same fact every adapter's own index.ios.ts/index.android.ts already encodes as a
+// literal, just read once here instead of five times.
+function trackColorPropsFor(value, trackColor) {
+    if (Platform.OS === 'android') {
+        return {
+            trackColorForFalse: trackColor?.false,
+            trackColorForTrue: trackColor?.true,
+            trackTintColor: value ? trackColor?.true : trackColor?.false,
+        };
+    }
+    return {
+        onTintColor: trackColor?.true,
+        tintColor: trackColor?.false,
+    };
+}
+// RN rounds the iOS background pill to this radius when `ios_backgroundColor` is set — the same
+// constant `render-switch.ts` uses, kept independent rather than exported+imported for one
+// primitive-local literal (see that file for the upstream fact it encodes).
+const IOS_BACKGROUND_BORDER_RADIUS = 16;
+// The platform-specific imperative command RN's own Switch sends to correct a rejected toggle
+// (Switch.js:221-225) — read off Platform.OS for the same reason `trackColorPropsFor` is.
+function snapBackCommand() {
+    return Platform.OS === 'android' ? 'setNativeValue' : 'setValue';
+}
+function foldPayload(props) {
+    const value = props.value === true;
+    const trackColor = trackColorOf(props.trackColor);
+    const iosBackground = stringOf(props.ios_backgroundColor);
+    const out = {
+        ...props,
+        value,
+        disabled: booleanOf(props.disabled),
+        ...trackColorPropsFor(value, trackColor),
+        thumbTintColor: stringOf(props.thumbColor),
+        style: iosBackground === undefined
+            ? props.style
+            : [
+                props.style,
+                {
+                    backgroundColor: iosBackground,
+                    borderRadius: IOS_BACKGROUND_BORDER_RADIUS,
+                },
+            ],
+    };
+    // The authored names themselves must NOT ride along: none is a Fabric prop, and leaving them in
+    // the payload is how a reader concludes the fold ran when it did not.
+    delete out.trackColor;
+    delete out.thumbColor;
+    delete out.ios_backgroundColor;
+    return out;
+}
+// Shared by both triggers — see the module header for why there are two.
+function evaluateSnapBack(node) {
+    const state = stateOf(node);
+    if (state === undefined)
+        return; // detached before this ran
+    const fabricValue = node.props.value === true;
+    if (!shouldSnapBack(state, fabricValue)) {
+        dlog(`Switch behavior snap-back no-op reported=${String(state.lastNativeReport)} value=${fabricValue}`);
+        return;
+    }
+    dlog(`Switch behavior ${snapBackCommand()} snap-back reported=${String(state.lastNativeReport)} value=${fabricValue}`);
+    dispatchViewCommand(node, snapBackCommand(), [fabricValue]);
+}
+function onChange(node, event) {
+    const state = stateOf(node);
+    if (state === undefined)
+        return;
+    const value = valueFromChange(event);
+    if (value === undefined)
+        return;
+    dlog(`Switch behavior onChange value=${String(value)} eventCount=${String(event.nativeEvent.eventCount)}`);
+    states.set(node, switchReducer(state, { type: 'native-reported', value }));
+    // `onValueChange` is not a Fabric event — it is a fold the component wrapper does over the raw
+    // `change` payload (same class as TextInput's `onValueChange`, `text-input.ts`'s
+    // `callValueChange`), so it lands in `node.props` as a plain function key rather than through
+    // `ownedListeners`.
+    const listener = node.props.onValueChange;
+    if (typeof listener === 'function')
+        listener(value, event);
+    // A raw `change` listener authored directly on the bare tag — not part of any adapter's public
+    // surface today, but `change` is the name this behavior's own dispatcher owns
+    // (`ownedListeners` below), so one is stashed rather than silently evicting the machine.
+    const rawListener = appListenerFor(node, 'change');
+    if (typeof rawListener === 'function')
+        rawListener(event);
+    // See the module header: deferred so an ACCEPTING app's own state update has a turn of the
+    // microtask queue to reach `node.props.value` first.
+    queueMicrotask(() => evaluateSnapBack(node));
+}
+function attach(node) {
+    states.set(node, createInitialSwitchState());
+    setBehaviorListener(node, 'change', event => onChange(node, event));
+}
+function detach(node) {
+    states.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 registerSwitchBehavior() {
+    registerHostBehavior(SWITCH_TAG, {
+        attach,
+        // See the module header: closes the residual case a microtask scheduled only from `onChange`
+        // cannot — a prop change with no preceding native event.
+        afterCommit: evaluateSnapBack,
+        detach,
+        foldPayload,
+        ownedListeners: ['change'],
+    });
+}

package/build/behaviors/text-input.d.ts

@@ -0,0 +1,14 @@
+import { type ISymbioteNode } from '@symbiote-native/engine';
+import { type ITextInputHandle } from '../state/text-input';
+export declare const TEXT_INPUT_TAG = "symbiote-text-input";
+export declare const TEXT_INPUT_MULTILINE_TAG = "symbiote-text-input-multiline";
+/**
+ * The imperative API RN exposes on a TextInput ref, built over the engine node. Reached through
+ * each adapter's own `host-instance` accessor — the capability, not a shape
+ * (`.claude/rules/adapter-parity-audit.md`).
+ *
+ * `focus`/`blur` are native view commands; `clear` and `setSelection` reuse `setTextAndSelection`,
+ * the same stale-safe path a controlled write takes, so they cannot race a keystroke either.
+ */
+export declare function buildTextInputHandle(node: ISymbioteNode): ITextInputHandle;
+export declare function registerTextInputBehavior(): void;