@symbiote-native/components 3.1.1 → 3.1.3

package/build/behaviors/text-input.js

@@ -1,28 +1,13 @@
-// 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, it composes a small press machine so a
-// tap focuses the input (`TextInput.js`'s own `usePressability` — FOUND MISSING 2026-09-20, since
-// nothing here wired ANY press listener at all), 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 tag 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, focusTextInput, Platform, propOf, propsOf, registerHostBehavior, requestCommitFor, setBehaviorListener, setInputBlurred, setInputFocused, setProp, } from '@symbiote-native/engine';
-import { attachPressMachine, detachPressMachine, } from './pressable.js';
+// TextInput's machine, on the engine node instead of inside a framework component. It holds three
+// native-state mirrors (event count, last native text, focus), commands text back down on
+// divergence, fires focus once at mount for autoFocus, composes a press machine for tap-to-focus.
+// Needed a new engine hook where Pressable did not: the controlled handshake is driven by a PROP
+// (`value`), and a tag has no render to re-run the divergence check, so afterCommit is the beat.
+// The order of the two commit hooks is load-bearing, pinned by a test: attachAfterCommit seeds
+// lastNativeText from mount-time props, afterCommit compares against that seed. Reversed, the
+// first beat would see an empty mirror and command a redundant write on every input.
+import { appListenerFor, blurTextInput, dispatchViewCommand, dlog, focusTextInput, Platform, propOf, propsOf, registerHostBehavior, requestCommitFor, setInputBlurred, setInputFocused, setNodeDispatch, setProp, } from '@symbiote-native/engine';
+import { attachPressMachine, detachPressMachine, PRESS_DISPATCH, } from './pressable.js';
 import { eventCountFromChange, foldText, INITIAL_EVENT_COUNT, SELECTION_NONE, shouldCommandText, textFromChange, } from '../state/text-input.js';
 // Both spellings, because `multiline` picks between two Fabric views and the TAG is what decides.
 // The behavior is registered for both so it does not care which one the app wrote.
@@ -55,20 +40,11 @@ function callAppListener(node, name, event) {
     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 on the node as a plain prop key and
-// `fabricProps` drops it on the way to native. A tag 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.
-//
-// 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.
+// `onValueChange(event)` is NOT a Fabric event — it lives on the node as a plain prop key, and
+// fabricProps drops it on the way to native.
+// The listener takes ONE argument, `text` carried on the event itself, not `(text, event)` —
+// Svelte's compiler forces every `on*` attribute through a wrapper that calls with exactly one
+// argument, always a real object, so a bare string as the sole argument crashes.
 function callValueChange(node, text, event) {
     const listener = propOf(node, 'onValueChange');
     if (typeof listener !== 'function')
@@ -76,67 +52,28 @@ function callValueChange(node, text, event) {
     const changeEvent = Object.assign(event, { text });
     listener(changeEvent);
 }
-// The alias list and its two narrowing helpers went with the fold. They existed only to feed
-// `resolveTextInputProps`, and that resolution is `foldTextInputAliases` in
-// `SymbioteFabricProps.cpp` now — keeping a copy of the names here would be a second statement of
-// the same rule, which is the thing the move was for.
-// `multiline` picks between TWO Fabric views, so the TAG decides it and no later prop write moves a
-// node between them. The wrapper that used to stand here CONSUMED the prop to pick its intrinsic;
-// an author writing the tag can spell the two apart, which 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.
-// THE FOLD IS GONE — the rule lives in the engine now, `foldTextInputAliases` in
-// `core/engine/cpp/SymbioteFabricProps.cpp`, beside the tree it writes into.
-//
-// It is UA behavior in the browser sense: mapping the web-facing spelling (`inputMode`,
-// `enterKeyHint`, `readOnly`, the W3C `autoComplete` token) onto React Native's own is a property of
-// the PLATFORM, not of any app, framework or component instance. Blink resolves `<input>`'s
-// attributes in the engine and every framework on top pays nothing for it; this is the same move.
-//
-// And it had a price. A `payloadFold` is a JS closure the C++ walk calls per node per commit, which
-// means converting the whole props bag to a `jsi::Value` and the result back again — ~17 us apiece,
-// and the entire gap between React's walk (24-27 ms, no folds) and every other adapter's (41-44 ms,
-// `foldsFound=1000`) on a byte-identical benchmark tree.
-//
-// There is deliberately NO TypeScript twin. `core/engine/cpp/tests/js/text-input-payload.itest.ts`
-// is the contract, and it reads the payload the commit actually sent rather than a second copy of
-// the rule.
-//
-// What stays here is the MACHINE: the controlled-value handshake, the event-count acknowledgement,
-// autofocus. Those run at gesture and lifecycle rate and call back into app code — which is exactly
-// what a browser keeps above the engine too.
+// `multiline` picks between TWO Fabric views, so the TAG decides it and no later prop write moves
+// a node between them. An author writing the tag can still spell a contradicting `multiline`
+// prop, which silently commits the wrong view with nothing to read.
+// So the tag is the authority: a contradicting prop throws rather than being quietly overridden.
+// The throw stays in each adapter's own prop-write path, not here, since a throw from foldPayload
+// inside the commit surfaces a tick later with no frame naming the call site.
+// The alias/fold rule lives in the engine now (foldTextInputAliases in SymbioteFabricProps.cpp),
+// UA behavior mapping the web-facing spelling onto RN's own — a property of the platform, paid
+// once, not per app or framework. No TypeScript twin: the itest reads the payload directly.
+// What stays here is the MACHINE: the controlled-value handshake, event-count acknowledgement,
+// autofocus — running at gesture/lifecycle rate and calling back into app code.
 function onChange(node, event) {
     const state = stateOf(node);
     if (state === undefined)
         return;
-    // TextInput.js:502-518's `_onChange` — `onChange` first, THEN `onChangeText`, UNCONDITIONALLY on
-    // every native change, and only THEN the mirrors ("This must happen last", vendor's own comment
-    // on the count). Ours used to run backwards: the mirror first, then `onChangeText`, with the real
-    // `onChange` called dead last — an app with side effects observable across `onChange` and
-    // `onChangeText` saw them in the opposite order from a real device.
+    // Mirrors vendor's own ordering: `onChange` first, then `onChangeText`, unconditionally on
+    // every native change, and only THEN the mirrors update.
     callAppListener(node, 'change', event);
     const text = textFromChange(event);
     if (text !== undefined) {
-        // TextInput.js:506 — fired right alongside `onChange`, off the same event, `text` riding on it
-        // as a field for the same reason `onValueChange` does. Read directly rather than owned/stashed:
-        // like `onValueChange`, it is not a Fabric event name, so nothing routes it and nothing native
-        // could overwrite it.
+        // Read directly, not owned/stashed: like onValueChange, onChangeText isn't a Fabric event
+        // name, so nothing routes it and nothing native could overwrite it.
         const onChangeText = propOf(node, 'onChangeText');
         if (typeof onChangeText === 'function') {
             onChangeText(Object.assign(event, { text }));
@@ -175,11 +112,9 @@ function onBlur(node, event) {
     setInputBlurred(node);
     callAppListener(node, 'blur', event);
 }
-// The out-of-commit half of the same check `afterCommit` runs on every commit: given the mirror
-// already updated from a real native report, send the authored `selection` back down if it still
-// disagrees. Kept separate from `afterCommit`'s own combined text+selection dispatch rather than
-// shared with it — this path has no `freshlySeeded`/text-divergence concept, and folding the two
-// would risk a double command on a commit where both diverge at once.
+// The out-of-commit half of the check afterCommit runs on every commit: given the mirror already
+// updated from a real native report, send the authored `selection` back down if it still
+// disagrees. Kept separate from afterCommit's own dispatch to avoid a double command.
 function correctSelectionIfNeeded(node, state) {
     const props = propsOf(node);
     const { start, end } = selectionOf(props.selection);
@@ -199,12 +134,8 @@ function correctSelectionIfNeeded(node, state) {
     ]);
     state.lastNativeSelection = { start, end };
 }
-// TextInput.js:522-533 — `_onSelectionChange` forwards to the app FIRST, then folds the REAL native
-// position into `lastNativeSelection`, whichever way the caret moved (a controlled write we sent
-// ourselves, or the user dragging it). That update alone is what schedules React's next render,
-// which is what re-runs the divergence check with the freshly-updated mirror. We have no render to
-// ride, so `correctSelectionIfNeeded` is called directly, right after the mirror moves — same shape
-// as `refresh-control.ts`'s own re-check after a native report.
+// Forwards to the app FIRST, then folds the real native position into lastNativeSelection. With
+// no render to ride the mirror update, correctSelectionIfNeeded is called directly right after.
 function onSelectionChange(node, event) {
     callAppListener(node, 'selectionChange', event);
     const state = stateOf(node);
@@ -216,12 +147,9 @@ function onSelectionChange(node, event) {
     state.lastNativeSelection = native;
     correctSelectionIfNeeded(node, state);
 }
-// `TextInput.js`'s own `usePressability(config)` — the same Pressability class every Touchable
-// uses, wired for exactly one reason: `onPress` calls `inputRef.current.focus()` when
-// `editable !== false`, so a tap landing inside an authored `hitSlop` but outside the native
-// view's own focus zone still focuses the input. `onPressIn`/`onPressOut` need NO wrapping here —
-// `configFor`'s defaults already forward them raw, which is exactly what upstream does
-// (`onPressIn, onPressOut` destructured straight into the config with no wrapper function).
+// The same Pressability class every Touchable uses, wired so a tap inside an authored `hitSlop`
+// but outside the native view's own focus zone still focuses the input. onPressIn/onPressOut need
+// no wrapping — configFor's defaults already forward them raw.
 const focusOnPress = (node, config) => ({
     ...config,
     onPress(event) {
@@ -253,23 +181,34 @@ function attach(node) {
         isMirrorFreshlySeeded: false,
         lastNativeSelection: { start: SELECTION_NONE, end: SELECTION_NONE },
     });
-    // The mirror's seed has to reach the PAYLOAD too, not just this state object. The wrappers handed
-    // the count over on every render, so an input committed the key at create; the behavior used to
-    // write it only inside the change handshake, so the tag carried no such key until the user typed.
-    // Found independently by three adapters, 2026-09-01.
-    //
-    // 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.
+    // The mirror's seed must reach the PAYLOAD too, not just this state object — otherwise the tag
+    // carries no `mostRecentEventCount` key until the user types.
+    // No `requestCommitFor` here: at create the renderer commits anyway, and on a re-attach the key
+    // is already at this 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));
-    setBehaviorListener(node, 'selectionChange', event => onSelectionChange(node, event));
     attachPressMachine(node, {
         refine: focusOnPress,
         cancelableOf: textInputCancelable,
     });
+    // AFTER the machine, which points the node at its own: a node holds exactly one dispatch, and
+    // `TEXT_INPUT_DISPATCH` is the union that delegates the machine's seven back to it
+    setNodeDispatch(node, TEXT_INPUT_DISPATCH);
 }
+const OWN_HANDLERS = new Map([
+    ['change', onChange],
+    ['focus', onFocus],
+    ['blur', onBlur],
+    ['selectionChange', onSelectionChange],
+]);
+const TEXT_INPUT_DISPATCH = {
+    names: new Set([...OWN_HANDLERS.keys(), ...PRESS_DISPATCH.names]),
+    deliver(node, name, event) {
+        const own = OWN_HANDLERS.get(name);
+        if (own !== undefined)
+            return own(node, event);
+        return PRESS_DISPATCH.deliver(node, name, event);
+    },
+};
 // TextInput.js:597 with its `rejectResponderTermination = true` default (:905): iOS keeps the
 // gesture unless the app opts in; Android hands Pressability `null`, i.e. its own default (yield).
 function textInputCancelable(source) {
@@ -284,20 +223,15 @@ function attachAfterCommit(node) {
     const state = stateOf(node);
     if (state === undefined)
         return;
-    // ONE question, not three. `propOf` crosses the host boundary per call — `flushOps()` plus a JSI
-    // read — and this runs once per input on the commit that lands it, so three reads of the same
-    // bag were three crossings per `<text-input>` on every create. `propsOf` fetches it whole and
-    // hands back the host's own object when nothing is stashed, which is every node here.
+    // ONE question, not three: propOf crosses the host boundary per call, so propsOf fetches the
+    // whole bag instead, handing back the host's own object when nothing is stashed.
     const props = propsOf(node);
     state.lastNativeText = foldText(stringFrom(props.value), stringFrom(props.defaultValue));
     state.isMirrorFreshlySeeded = true;
     if (props.autoFocus !== true)
         return;
-    // Driven in JS rather than as a native `autoFocus` prop (RN's own ViewConfigs DO declare one —
-    // `RCTTextInputViewConfig.js`/`AndroidTextInputNativeComponent.js` — but we don't forward it, so
-    // this is the one mechanism that focuses the input). Routed through `focusTextInput`, not a raw
-    // command, so an autoFocused input also updates the app-wide tracker `Keyboard.dismiss()` reads —
-    // a raw command left it unset until the native focus event round-tripped back.
+    // Driven in JS, not a native `autoFocus` prop (RN declares one but we don't forward it). Routed
+    // through focusTextInput, not a raw command, so it also updates the app-wide focus tracker.
     dlog('TextInput behavior: autoFocus -> focus command');
     focusTextInput(node);
 }
@@ -308,10 +242,9 @@ function afterCommit(node) {
     const state = stateOf(node);
     if (state === undefined)
         return;
-    // The seed ran on this same commit, so the TEXT comparison below is already decided — see
-    // `isMirrorFreshlySeeded`. SELECTION is not seeded by anything, so it is checked regardless: an
-    // authored `selection` must move the caret on this very commit, matching `TextInput.js`'s own
-    // sentinel-seeded `lastNativeSelection`.
+    // The seed ran on this same commit, so the TEXT comparison below is already decided. SELECTION
+    // is not seeded by anything, so it's checked regardless — an authored `selection` must move the
+    // caret on this very commit.
     const freshlySeeded = state.isMirrorFreshlySeeded;
     if (freshlySeeded)
         state.isMirrorFreshlySeeded = false;
@@ -320,11 +253,8 @@ function afterCommit(node) {
     const props = propsOf(node);
     const value = stringFrom(props.value);
     const textDiverged = !freshlySeeded && shouldCommandText(state.lastNativeText, value);
-    // `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. `lastNativeSelection`
-    // is seeded at the same sentinel, so a real selection always "diverges" from it until this behavior
-    // has actually sent one.
+    // SELECTION_NONE (-1) is RN's "leave the cursor where native put it" sentinel, so an absent
+    // selection must not read as position 0, or every controlled write would jump the caret to front.
     const { start, end } = selectionOf(props.selection);
     const selectionAuthored = start !== SELECTION_NONE || end !== SELECTION_NONE;
     const selectionDiverged = selectionAuthored &&
@@ -356,14 +286,8 @@ function detach(node) {
     states.delete(node);
     detachPressMachine(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.
- */
+// The imperative API RN exposes on a TextInput ref, built over the engine node. `clear` and
+// `setSelection` reuse setTextAndSelection, the same stale-safe path a controlled write takes.
 export function buildTextInputHandle(node) {
     return {
         // Forwarded, not re-implemented: these are the engine node's own prototype methods, and a
@@ -373,16 +297,11 @@ export function buildTextInputHandle(node) {
         measureInWindow: callback => node.measureInWindow(callback),
         measureLayout: (relativeTo, onSuccess, onFail) => node.measureLayout(relativeTo, onSuccess, onFail),
         setNativeProps: nativeProps => node.setNativeProps(nativeProps),
-        // Through TextInputState, NOT a raw command — RN's `ReactNativeElement.focus()` routes a text
-        // input through `TextInputState.focusTextInput` for the same reason blur below does: app-wide
-        // tracking, plus the already-focused/`editable: false` no-op RN's own guard carries.
+        // Through TextInputState, NOT a raw command: app-wide tracking, plus the
+        // already-focused/editable:false no-op RN's own guard carries.
         focus: () => focusTextInput(node),
-        // 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.
+        // Through TextInputState, NOT a raw command: a raw command looks equivalent and isn't, since
+        // Keyboard.dismiss() reads currentlyFocusedInput() and a stale entry blurs the wrong node.
         blur: () => blurTextInput(node),
         isFocused: () => stateOf(node)?.isFocused === true,
         clear: () => {
@@ -415,12 +334,8 @@ export function buildTextInputHandle(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 registerTextInputBehavior() {
-    // THE TWO TAGS NOW SHARE ONE BEHAVIOR OBJECT, and that is the port showing up in the shape of the
-    // code. `multiline` was the only thing the two registrations did not share: each closed over its
-    // own answer to feed `foldPayload`. With the fold gone the machine is identical for both, and the
-    // engine answers `multiline` from the component name it already holds
-    // (`foldTextInputAliases`'s `isMultiline` argument, `SymbioteFabricProps.cpp`) — which is the
-    // better place for it anyway, since the component name is what Fabric actually keys the view on.
+    // The two tags share one behavior object: with the fold gone the machine is identical for both,
+    // and the engine answers `multiline` from the component name it already holds.
     const behavior = {
         attach,
         attachAfterCommit,

package/build/behaviors/touchable-highlight.js

@@ -1,33 +1,9 @@
-// TouchableHighlight as an ENGINE-NODE behavior, so it can be an intrinsic tag instead of a
-// framework component (`.claude/rules/host-primitive-tier.md`, tier 2).
-//
-// ONE NODE, THE SAME SIMPLIFICATION EVERY WRAPPER ALREADY SHIPPED. RN's own TouchableHighlight
-// renders a container View (the responder, the underlay backgroundColor, the whole accessibility
-// fold) and CLONES an extra opacity style onto its single child (TouchableHighlight.js:281-320,
-// `_createExtraStyles` + `cloneElement`). This tag folds both onto the ONE node instead, in
-// `foldTouchableHighlightUnderlay` (`SymbioteFabricProps.cpp`) now — see that rule's own header.
-//
-// KNOWN GAP, and it predates both this port and the fix it reverts. Composing `opacity` onto the
-// SAME node as the underlay's `backgroundColor` fades the underlay itself, so `underlayColor:
-// 'black'` paints grey rather than black — every adapter's wrapper shipped this, and the rule's own
-// header above says so on purpose ("The port keeps that, it does not reopen it"). A 2026-09-15 fix
-// (fd39750b) closed it pointwise, in JS, on this one tag; this revert returns to the shared
-// (buggy) behavior every adapter already had, which is correct for THIS merge — a merge that also
-// changes behavior is unattributable.
-//
-// The reason the old header gave for not splitting it — "needs a child to target and a framework
-// component holding an opaque children slot cannot reach one safely" — no longer holds: that was
-// true of JS wrappers, not of the engine. The DESCENDANT seam this needs already exists: a rule
-// keyed on `IOwner.tagName`, the same shape `foldCloneOntoChild` uses to reach a
-// TouchableNativeFeedback child's own `fabricProps()` call and write onto ITS payload — the write
-// `IFirstChild` cannot do, since that seam only reads a child, from the PARENT's own call.
-//
-// TODO: what actually blocks it is one missing field. `IOwner` carries `{ props, tagName,
-// hasPressListener }`; the child would need the owner's `underlayShown` too (currently only on
-// `ISelf`, the node's own state) to decide whether to paint at all. Closing this is a new
-// descendant-keyed rule plus that one field on `IOwner`, not a `foldTouchableHighlightUnderlay`
-// rewrite.
-//
+// TouchableHighlight as an ENGINE-NODE behavior: RN's own version renders a container View plus
+// clones an opacity style onto its child (TouchableHighlight.js:281-320); this tag folds both
+// onto the ONE node instead (`foldTouchableHighlightUnderlay` in `SymbioteFabricProps.cpp`).
+// KNOWN GAP: composing `opacity` onto the SAME node as the underlay's `backgroundColor` fades the
+// underlay itself, so `underlayColor: 'black'` paints grey, not black. TODO: needs a
+// descendant-keyed rule plus `underlayShown` added to `IOwner`.
 // WHAT IS SHARED AND WHAT IS NEW. The underlay show/hide state machine
 // (createHighlightUnderlayHandlers/createHighlightUnderlayRuntime, `../state/touchable`) is already
 // framework-agnostic — every wrapper already calls it. New here is only WHERE `shown` lives (a
@@ -133,30 +109,14 @@ const refine = (node, config) => {
         },
     };
 };
-// THE UNDERLAY FOLD LEFT THIS FILE ON 2026-09-18, and with it the last `payloadFold` on this tag —
-// this behavior now costs ZERO trips into JS per commit, down from one on every commit it was dirty
-// in (which for a touchable is FIVE at mount alone, because the opacity settle re-commits it).
-//
-// THE NOTE IT REPLACES SAID THE UNDERLAY WAS "the genuine unportable article" BECAUSE IT IS BUILT
-// FROM LIVE PRESS STATE. Half right, and the half it got wrong is the reusable part: `shown` really
-// does flip mid-gesture and really is JS's, but the RULE was never made of it. Of four inputs, three
-// were already portable — `underlayColor` and `activeOpacity` are ordinary props (ones the engine
-// ALREADY strips), and `_hasPressHandler` is listener EXISTENCE, which has crossed since
-// `OP_SET_OWNED_LISTENER`. The fourth is one bit. "JS holds it" was never the same claim as "only JS
-// can compute it", and this is the third time that distinction has moved a rule.
-//
-// WHAT CROSSES AND WHAT DOES NOT. `setNodeUnderlayShown` sends the bit on a flip — twice a tap. The
-// hold timer, the `press`-then-`pressOut` ordering, the re-arm on a second tap and the
-// `onShowUnderlay` / `onHideUnderlay` callbacks all stay here, where Pressability is, because they
-// run at gesture rate and call into app code. That is the browser's line too: a UA paints `:active`,
-// the page decides what a click means.
-//
-// `focusable` left earlier the same day and carried a bug out with it — it read `props.disabled` off
-// the BAG, which the engine's pressable rule strips, so every DISABLED highlight stayed in the focus
-// order. One rule serves both touchable tags now (`foldPressableProps`), so there is no second copy
-// to drift; pinned in `core/engine/cpp/tests/js/touchable-focusable-payload.itest.ts`.
-//
-// The underlay's own contract: `core/engine/cpp/tests/js/touchable-highlight-underlay.itest.ts`.
+// This behavior binds NO payload fold: `underlayColor`/`activeOpacity` are ordinary props the
+// engine already strips, listener existence crosses via `OP_SET_OWNED_LISTENER`, and the one
+// live bit crosses via `setNodeUnderlayShown` on a flip — twice a tap.
+// What stays in JS: the hold timer, press-then-pressOut ordering, the re-arm on a second tap, and
+// the `onShowUnderlay`/`onHideUnderlay` callbacks — they run at gesture rate and call app code.
+// `focusable` is `foldPressableProps` now, shared with the other touchable tag so there is no
+// second copy to drift — pinned in `touchable-focusable-payload.itest.ts`. Underlay's own
+// contract: `touchable-highlight-underlay.itest.ts`.
 // A listener flip changes no payload by itself, so the commit after it is a no-op and no fold
 // re-runs (`IHostBehavior.onOwnedListenerChange`) — same reason `./touchable-opacity` carries this.
 function onOwnedListenerChange(node, name) {

package/build/behaviors/touchable-native-feedback.js

@@ -49,11 +49,9 @@
 // 3. `style` is NOT cloned, matching RN — its clone list (:342-390) is closed, and a `style` on a
 //    TNF stays on a node that never commits. RN's TNF declares no style prop either.
 //
-// REGISTRATION IS THE HAZARD, not the machine — see `./pressable` for why each adapter entry does a
-// bare `import './register';` that the barrel does not re-export. Registered by ALL FIVE adapters
-// since 2026-09-09, in the same commit that deleted the five wrappers, which is what makes it safe:
-// while a wrapper still built its own Pressable + feedback View, registering would have left every
-// TouchableNativeFeedback with two responders.
+// REGISTRATION IS THE HAZARD, not the machine — see `./pressable` for why each adapter entry does
+// a bare `import './register';`. Registering while a wrapper still built its own Pressable +
+// feedback View would leave every TouchableNativeFeedback with two responders.
 import { SLOT_DERIVED_ALL, appListenerFor, markPropsDirty, Platform, registerHostBehavior, requestCommitFor, setBehaviorListener, } from '@symbiote-native/engine';
 import { resolveButtonDisabled } from '../view/render-button.js';
 import { asAccessibilityState, attachPressMachine, booleanOr, detachPressMachine, withNativeFeedbackCommands, } from './pressable.js';
@@ -66,19 +64,9 @@ export const TOUCHABLE_NATIVE_FEEDBACK_TAG = 'touchable-native-feedback';
 const touchableNativeFeedbackDisabled = props => resolveButtonDisabled(booleanOr(props.disabled), booleanOr(props['aria-disabled']), asAccessibilityState(props.accessibilityState));
 // Read once, like `./button`'s: the platform cannot change under a running app.
 const IS_ANDROID = Platform.OS === 'android';
-// WHAT THE OWNER'S WRITES DIRTY, and it is EVERY name rather than a list of thirty.
-//
-// RN's clone list (`TouchableNativeFeedback.js:349-390`) lived here until 2026-09-18 as
-// `CLONED_PROPS` + `DERIVED_FROM` + `ARIA_ALIAS_KEYS`, feeding `slotDerived`. The clone itself is
-// `foldCloneOntoChild` in `SymbioteFabricProps.cpp`, so the list had stopped being the rule and
-// become a MIRROR of `kNativeFeedbackClonedKeys` — two lists that must agree, failing silently (the
-// clone goes stale on the one prop a list forgot) when they drift.
-//
-// `SLOT_DERIVED_ALL` is both the honest spelling and the cheaper one to keep: a `cloneElement` owner
-// re-clones on every render whatever changed, so it never derived its slot from a NAMED set in the
-// first place. The cost is a false dirty on an owner prop the clone does not carry, and for this tag
-// that is nearly empty — its owner is an anchor whose props reach Fabric nowhere else, so every name
-// it holds is either cloned or consumed by the press machine.
+// Dirties EVERY owner prop rather than a named list: `cloneElement` re-clones whatever changed
+// each render, so the C++ fold never worked from a fixed set either. The cost is a false dirty on
+// an uncloned prop — negligible, since this owner's props reach Fabric only via the clone.
 const SLOT_DERIVED = [SLOT_DERIVED_ALL];
 // The two RN clones as EVENTS rather than props (:386-387). Owned, so the app's callback stashes on
 // the owner and a trampoline installed on the child reads it at dispatch time — which keeps a fresh
@@ -101,11 +89,6 @@ const PRESS_LISTENERS = [
     'responderMove',
     'responderTerminationRequest',
 ];
-// `asFeedbackBackground` went with the fold, and `backgroundProps` — the slot pick it fed — followed
-// on 2026-09-18 as the orphan it had become. The first narrowed the app's `background` dict on its
-// discriminant; the C++ rule asks only whether the value is an OBJECT and copies it into the slot,
-// because the four factories that produce it (`render-touchable-native-feedback.ts`) are ours and
-// the payload is not a place to re-validate what a typed factory already built.
 /**
  * TNF's own Pressability config, applied to whatever node carries the responder.
  *
@@ -126,15 +109,9 @@ export const nativeFeedbackRefinement = (node, config) => {
     const floorless = { ...config, minPressDuration: 0 };
     return IS_ANDROID ? withNativeFeedbackCommands(node, floorless) : floorless;
 };
-// `cloneFold` LEFT THIS FILE ON 2026-09-18 — it is `foldCloneOntoChild` in
-// `SymbioteFabricProps.cpp`, and the seam it needed is the first rule keyed on the PARENT'S tag
-// rather than on the node's own (`IOwner`). The child of a TNF is whatever the app wrote, usually a
-// plain `<view>` with no tag at all, so nothing self-keyed could ever have reached it.
-//
-// What it cost to have had here: one JSI round trip per touchable per commit over an eighteen-key
-// bag, and `tag-rule-cost.itest.ts` prices a fold by what it MARSHALS rather than by what it does.
-//
-// Contract: `core/engine/cpp/tests/js/clone-onto-child-payload.itest.ts`.
+// The clone runs in C++ (`foldCloneOntoChild`, `SymbioteFabricProps.cpp`), keyed on the PARENT'S
+// tag rather than the node's own — the child is whatever the app wrote, usually untagged, so
+// nothing self-keyed could ever reach it. Contract: `clone-onto-child-payload.itest.ts`.
 // Not RN's own list: RN drops these by never cloning them, and a tag has no clone to omit
 // them from — they would ride into the child's payload as keys no ViewConfig declares. Same strip
 // `./pressable`'s fold does for the machine-only half, applied to the owner's bag instead.

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

@@ -1,12 +1,5 @@
 import { type IHostBehavior } from '@symbiote-native/engine';
 import { type IDisabledResolver } from './pressable';
 export declare const TOUCHABLE_OPACITY_TAG = "touchable-opacity";
-/**
- * The behavior as PARTS, so a tag that is a TouchableOpacity plus something — `button`, which RN
- * builds as exactly that (Button.js:283) — composes the fade instead of re-implementing it.
- *
- * Safe to hand to two tags: every piece of runtime is keyed by NODE (`states`), and `press` is
- * itself already shared that way.
- */
 export declare function createTouchableOpacityBehavior(disabledOf?: IDisabledResolver): IHostBehavior;
 export declare function registerTouchableOpacityBehavior(): void;