@symbiote-native/components 0.5.0 → 2.0.0

package/build/behaviors/switch.js

@@ -0,0 +1,186 @@
+// 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 `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 = '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`. ONE argument, `value` carried on the event (`ISwitchChangeEvent`) — same
+    // reason as TextInput: Svelte's compiler forces an individual `on*` attribute through a native
+    // listener wrapper that calls with exactly one argument, always a real object.
+    const listener = node.props.onValueChange;
+    if (typeof listener === 'function') {
+        const changeEvent = Object.assign(event, { value });
+        listener(changeEvent);
+    }
+    // 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 = "text-input";
+export declare const TEXT_INPUT_MULTILINE_TAG = "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;

package/build/behaviors/text-input.js

@@ -0,0 +1,319 @@
+// TextInput's machine, on the engine node instead of inside a framework component — the tier-2
+// half of `.claude/rules/host-primitive-tier.md` for the second primitive to get one.
+//
+// WHAT A `TextInput` COMPONENT ACTUALLY DOES, and why none of it needs a framework. It holds three
+// mirrors of native state (the acknowledged event count, the last text native reported, whether the
+// input is focused), it commands text back down when the app's `value` diverges from that mirror,
+// it fires `focus` once at mount when `autoFocus` is set, and it exposes five imperative methods.
+// The TEMPLATE reads none of it — which is the whole tier-2 test. Every framework was paying an
+// instance for a machine that only ever needed a per-node home.
+//
+// WHY IT NEEDED A NEW ENGINE HOOK AND `Pressable` DID NOT. A press machine is driven entirely by
+// events, which arrive long after commit. The controlled handshake is driven by a PROP: `value`
+// changing is what must re-run the divergence check, and in a component the render is what does
+// that. A lowered element has no render, so `IHostBehavior.afterCommit` is the equivalent beat —
+// see that interface for why it is not a hook on `setProp`.
+//
+// THE ORDER OF THE TWO COMMIT HOOKS IS LOAD-BEARING HERE, which is why the engine pins it with a
+// test: `attachAfterCommit` seeds `lastNativeText` from the mount-time props, and `afterCommit`
+// compares against that seed. Reversed, the very first beat would see an empty mirror, decide the
+// app's value had diverged, and command a redundant `setTextAndSelection` down to native on every
+// input in the tree.
+import { appListenerFor, blurTextInput, dispatchViewCommand, dlog, registerHostBehavior, requestCommitFor, setBehaviorListener, setInputBlurred, setInputFocused, setProp, } from '@symbiote-native/engine';
+import { eventCountFromChange, foldText, INITIAL_EVENT_COUNT, SELECTION_NONE, resolveTextInputProps, shouldCommandText, textFromChange, } from '../state/text-input.js';
+// Both spellings, because `multiline` picks between two Fabric views and a lowering transform
+// resolves that statically. The behavior is registered for both so it does not care which one the
+// transform emitted.
+export const TEXT_INPUT_TAG = 'text-input';
+export const TEXT_INPUT_MULTILINE_TAG = 'text-input-multiline';
+const states = new WeakMap();
+function stateOf(node) {
+    return states.get(node);
+}
+function stringProp(node, key) {
+    const value = node.props[key];
+    return typeof value === 'string' ? value : undefined;
+}
+// `{ start, end? }` narrowed at runtime. `end` defaults to `start` — a caret, RN's own reading when
+// only one bound is given — and both fall back to SELECTION_NONE when the prop is absent.
+function selectionOf(value) {
+    if (typeof value !== 'object' || value === null) {
+        return { start: SELECTION_NONE, end: SELECTION_NONE };
+    }
+    const bag = { ...value };
+    const start = typeof bag.start === 'number' ? bag.start : SELECTION_NONE;
+    const end = typeof bag.end === 'number' ? bag.end : start;
+    return { start, end };
+}
+// The app's own callback for an owned event name, read from the STASH rather than from
+// `node.props`: every name below is in `ownedListeners`, so `routeProp` parks the app's handler
+// beside the machine's instead of overwriting it.
+function callAppListener(node, name, event) {
+    const listener = appListenerFor(node, name);
+    if (typeof listener === 'function')
+        listener(event);
+}
+// `onValueChange(event)` is NOT a Fabric event — it is a fold the component wrapper used to do
+// over the raw `change` payload, so it lives in `node.props` as a plain function key and
+// `fabricProps` drops it on the way to native. A lowered element has no wrapper to run that fold, so
+// before this the callback was simply never called: the field echoed keystrokes natively (native
+// owns its own text) while every value the app derived from it stayed frozen. Device-found
+// 2026-08-31 in examples/solid's canary — the greeting never left "Hello, stranger".
+//
+// Same class as `value -> text` (`core/engine/src/fabric-props.ts`) and the same repair: below the
+// fork, where all five adapters inherit it. Refusing to lower an element carrying the prop was the
+// other candidate and is strictly worse — it makes the optimisation opt out of the idiom the
+// ecosystem actually writes, to avoid a fold the runtime can do in three lines.
+//
+// The listener takes ONE argument, `text` carried on the event itself (`ITextInputChangeEvent`),
+// not `(text, event)` — Svelte's compiler forces every individual `on*` attribute through a native
+// listener wrapper that calls with exactly one argument, always a real object, so a second
+// argument is silently dropped and a bare string as the sole argument crashes.
+function callValueChange(node, text, event) {
+    const listener = node.props.onValueChange;
+    if (typeof listener !== 'function')
+        return;
+    const changeEvent = Object.assign(event, { text });
+    listener(changeEvent);
+}
+// The W3C/legacy alias fold the WRAPPER runs in its component body — `inputMode` -> `keyboardType`,
+// `enterKeyHint` -> `returnKeyType`, `readOnly` -> inverted `editable`, `blurOnSubmit` ->
+// `submitBehavior`, plus the `underlineColorAndroid: 'transparent'` default that hides the Material
+// bar. A lowered element has no body, so before this every one of them was dropped: the raw alias
+// reached Fabric as a key no ViewConfig declares, which throws nothing and renders nothing, so
+// `inputMode="numeric"` simply produced the default keyboard on a device while the whole headless
+// suite stayed green.
+//
+// Found by the wrapper-vs-behavior import audit rather than by hand
+// (`.claude/rules/adapter-parity-audit.md`) — the same audit that found Pressable's two.
+const ALIAS_ONLY_KEYS = [
+    'inputMode',
+    'enterKeyHint',
+    'readOnly',
+    'blurOnSubmit',
+];
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function booleanOf(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+// `multiline` picks between TWO Fabric views, so the TAG decides it and no later prop write moves a
+// node between them. Two of the three paths that build the node resolve it before the engine ever
+// sees the prop — the wrapper CONSUMES it to pick its intrinsic, a lowering transform reads a
+// literal at compile time — and the third, an author writing the tag by hand, has neither. That
+// leaves two silent, device-only divergences, measured on the committed payload:
+//
+//   <text-input-multiline value="a" />   RCTMultilineTextInputView, folded as SINGLE-line:
+//                                        submitBehavior 'blurAndSubmit', so Return blurs instead
+//                                        of inserting a newline
+//   <text-input multiline value="b" />   RCTSinglelineTextInputView carrying the multiline fold
+//
+// So the tag is the authority here, and a prop that contradicts it throws rather than being
+// quietly overridden — an ignored `multiline` is a wrong native view with nothing to read.
+// Found on Solid, fixed here because all five adapters produce the same two divergences: a
+// decision the wrapper used to make by CONSUMING a prop has no owner once the author writes the
+// tag directly.
+// The COMPLAINT cannot live here, only the correction. `foldPayload` runs inside the commit, so a
+// throw from it surfaces as an uncaught exception a tick after the author's write with no frame
+// naming the call site — measured: a test awaiting the mount sees `nothing committed` instead of
+// the error. Refusing a contradicting prop therefore stays in each adapter's own prop-write path,
+// where the author's stack still exists (Solid's `renderer.ts` is the reference); this file only
+// guarantees that whatever the props say, the payload matches the TAG.
+function foldPayload(props, isMultilineTag) {
+    const folded = resolveTextInputProps({
+        inputMode: stringOf(props.inputMode),
+        keyboardType: stringOf(props.keyboardType),
+        enterKeyHint: stringOf(props.enterKeyHint),
+        returnKeyType: stringOf(props.returnKeyType),
+        readOnly: booleanOf(props.readOnly),
+        editable: booleanOf(props.editable),
+        submitBehavior: stringOf(props.submitBehavior),
+        blurOnSubmit: booleanOf(props.blurOnSubmit),
+        multiline: isMultilineTag,
+        cursorColor: stringOf(props.cursorColor),
+        selectionColor: stringOf(props.selectionColor),
+        selectionHandleColor: stringOf(props.selectionHandleColor),
+        autoComplete: stringOf(props.autoComplete),
+        textContentType: stringOf(props.textContentType),
+        showSoftInputOnFocus: booleanOf(props.showSoftInputOnFocus),
+        underlineColorAndroid: stringOf(props.underlineColorAndroid),
+    });
+    const out = { ...props, ...folded };
+    // The aliases themselves must NOT ride along: they are inert at native, and leaving them in the
+    // payload is how a reader concludes the fold ran when it did not.
+    for (const key of ALIAS_ONLY_KEYS)
+        delete out[key];
+    return out;
+}
+function onChange(node, event) {
+    const state = stateOf(node);
+    if (state === undefined)
+        return;
+    const text = textFromChange(event);
+    if (text !== undefined) {
+        // Ordering matches the component path exactly: record the mirror, then hand the app its text.
+        state.lastNativeText = text;
+        callValueChange(node, text, event);
+    }
+    // Ordering: record the text first, then the count, so the acknowledged count never runs ahead of
+    // the text it stands for. A count without its text makes the next controlled write echo an
+    // acknowledgement native has not actually given.
+    const count = eventCountFromChange(event);
+    if (count !== undefined) {
+        state.mostRecentEventCount = count;
+        // Native READS this prop, so the mirror is not enough — it has to reach the payload. Same shape
+        // as the press machine's `setNodePressed` + `requestCommitFor`: a behavior writing a prop owes
+        // the commit, because nothing else is going to ask for one.
+        setProp(node, 'mostRecentEventCount', count);
+        requestCommitFor(node);
+    }
+    callAppListener(node, 'change', event);
+}
+function onFocus(node, event) {
+    const state = stateOf(node);
+    if (state !== undefined)
+        state.isFocused = true;
+    // App-wide, so `Keyboard.dismiss()` can blur this input without holding a ref to it.
+    setInputFocused(node);
+    callAppListener(node, 'focus', event);
+}
+function onBlur(node, event) {
+    const state = stateOf(node);
+    if (state !== undefined)
+        state.isFocused = false;
+    setInputBlurred(node);
+    callAppListener(node, 'blur', event);
+}
+function attach(node) {
+    states.set(node, {
+        mostRecentEventCount: INITIAL_EVENT_COUNT,
+        lastNativeText: undefined,
+        isFocused: false,
+    });
+    // The mirror's seed has to reach the PAYLOAD too, not just this state object. Every wrapper hands
+    // the count to `renderTextInput` on every render, so a component-path input commits the key at
+    // create; the behavior used to write it only inside the change handshake, so a lowered input
+    // carried no such key until the user typed. Found independently by three adapters' equivalence
+    // arms, 2026-09-01 — a divergence between the two paths of ONE adapter, not between adapters.
+    //
+    // No `requestCommitFor` here: at create the renderer commits anyway, and on a re-attach the key is
+    // already standing at this same value, so `setProp`'s identity guard makes the write a no-op.
+    setProp(node, 'mostRecentEventCount', INITIAL_EVENT_COUNT);
+    setBehaviorListener(node, 'change', event => onChange(node, event));
+    setBehaviorListener(node, 'focus', event => onFocus(node, event));
+    setBehaviorListener(node, 'blur', event => onBlur(node, event));
+}
+// The first commit is the earliest point where the node has BOTH its props and a Fabric tag. The
+// mirror needs the first, `autoFocus` needs the second.
+function attachAfterCommit(node) {
+    const state = stateOf(node);
+    if (state === undefined)
+        return;
+    state.lastNativeText = foldText(stringProp(node, 'value'), stringProp(node, 'defaultValue'));
+    if (node.props.autoFocus !== true)
+        return;
+    // Driven in JS rather than as a native prop, exactly as RN does it
+    // (TextInput.js:538 -> TextInputState.focusInput). The native command is idempotent if the input
+    // is already focused.
+    dlog('TextInput behavior: autoFocus -> focus command');
+    dispatchViewCommand(node, 'focus', []);
+}
+// The controlled handshake. A plain prop re-push would race the user's keystrokes — native may have
+// text JS has not seen yet — so the command carrying the acknowledged count is the only stale-safe
+// path, and `shouldCommandText` is what keeps it a no-op unless the value genuinely diverged.
+function afterCommit(node) {
+    const state = stateOf(node);
+    if (state === undefined)
+        return;
+    const value = stringProp(node, 'value');
+    if (!shouldCommandText(state.lastNativeText, value))
+        return;
+    // `selection` is `{ start, end? }` when present. SELECTION_NONE (-1) is RN's "leave the cursor
+    // where native put it" sentinel, so an absent selection must not be read as position 0 — that
+    // would jump the caret to the front of the field on every controlled write.
+    const { start, end } = selectionOf(node.props.selection);
+    dlog(`TextInput behavior: setTextAndSelection count=${state.mostRecentEventCount} ` +
+        `text=${JSON.stringify(value)}`);
+    dispatchViewCommand(node, 'setTextAndSelection', [
+        state.mostRecentEventCount,
+        value,
+        start,
+        end,
+    ]);
+    state.lastNativeText = value;
+}
+function detach(node) {
+    states.delete(node);
+}
+/**
+ * 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 function buildTextInputHandle(node) {
+    return {
+        // Forwarded, not re-implemented: these are the engine node's own prototype methods, and a
+        // TextInput ref that lacks them is poorer than every other host ref for no reason. See
+        // `ITextInputHandle` for why the handle is a UNION rather than the five below.
+        measure: callback => node.measure(callback),
+        measureInWindow: callback => node.measureInWindow(callback),
+        measureLayout: (relativeTo, onSuccess, onFail) => node.measureLayout(relativeTo, onSuccess, onFail),
+        setNativeProps: nativeProps => node.setNativeProps(nativeProps),
+        focus: () => dispatchViewCommand(node, 'focus', []),
+        // Through TextInputState, NOT a raw command — the same route the component path takes
+        // (`react/.../text-input/index.ts`, "so the app-wide focus tracking clears too"). The native
+        // `blur` event also clears the tracking via this behavior's own listener, so a raw command
+        // looks equivalent and is not: the event is the NATIVE side's, and it does not arrive when the
+        // input was already blurred. `Keyboard.dismiss()` reads `currentlyFocusedInput()`, so a stale
+        // entry there aims a blur at a node that no longer holds focus.
+        blur: () => blurTextInput(node),
+        isFocused: () => stateOf(node)?.isFocused === true,
+        clear: () => {
+            const state = stateOf(node);
+            if (state === undefined)
+                return;
+            dispatchViewCommand(node, 'setTextAndSelection', [
+                state.mostRecentEventCount,
+                '',
+                0,
+                0,
+            ]);
+            state.lastNativeText = '';
+        },
+        setSelection: (start, end) => {
+            const state = stateOf(node);
+            if (state === undefined)
+                return;
+            // The CURRENT text, not the app's `value`: a selection move must not also rewrite the text,
+            // and native discards a command whose text disagrees with what it holds.
+            dispatchViewCommand(node, 'setTextAndSelection', [
+                state.mostRecentEventCount,
+                state.lastNativeText,
+                start,
+                end,
+            ]);
+        },
+    };
+}
+// 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 registerTextInputBehavior() {
+    const behaviorFor = (isMultilineTag) => ({
+        attach,
+        attachAfterCommit,
+        afterCommit,
+        detach,
+        // The one thing the two registrations do NOT share: the tag is what answers `multiline`, so
+        // each closes over its own answer. Everything else is the same machine.
+        foldPayload: (props) => foldPayload(props, isMultilineTag),
+        // The three the machine needs as INPUTS. Without the stash the app's own `onChange` would
+        // evict the machine from the very event the controlled handshake runs on.
+        ownedListeners: ['change', 'focus', 'blur'],
+    });
+    registerHostBehavior(TEXT_INPUT_TAG, behaviorFor(false));
+    registerHostBehavior(TEXT_INPUT_MULTILINE_TAG, behaviorFor(true));
+}

package/build/behaviors/touchable-highlight.d.ts

@@ -0,0 +1,9 @@
+import { type IHostBehavior } from '@symbiote-native/engine';
+import { type IDisabledResolver } from './pressable';
+export declare const TOUCHABLE_HIGHLIGHT_TAG = "touchable-highlight";
+/**
+ * The behavior as PARTS, mirroring `./touchable-opacity`'s shape — a tag that is a
+ * TouchableHighlight plus something composes this instead of re-implementing the underlay.
+ */
+export declare function createTouchableHighlightBehavior(disabledOf?: IDisabledResolver): IHostBehavior;
+export declare function registerTouchableHighlightBehavior(): void;