@symbiote-native/components 1.0.0 → 2.0.0

package/README.md

@@ -30,8 +30,7 @@ supplies only the third:
    bridges the `Descriptor` to `React.createElement`; Vue wires it through `ref`/`watch` and
    bridges to `h()`. This is the ONLY part a new adapter has to write.
 
-`Switch` is the canonical reference for a full three-layer component; `ActivityIndicator` is the
-canonical render-only reference (no state machine needed).
+`Switch` is the canonical reference for a full three-layer component.
 
 ### Install
 
@@ -86,8 +85,8 @@ host node untouched — the render function never names a framework type.
   canonical `accessibility*` transform, shared so every adapter folds identically.
 - **Components with a full state + render split** — `Switch`, `Modal` (its reducer gates the iOS
   keep-alive frame).
-- **Render-only components** (no state machine) — `ActivityIndicator`, `Image`,
-  `ImageBackground`, `InputAccessoryView`.
+- **Render-only components** (no state machine) — `Image`, `ImageBackground`,
+  `InputAccessoryView`.
 - **Pure logic/plumbing without a full `Descriptor`** — `Pressable`'s press state machine
   (`createPressHandlers` / `createPressRuntime` in `state/pressable`) plus its render-decision
   helpers (`buildPressableListeners`, `resolveDisabledAccessibilityState`, `shouldClaimResponder`,

package/build/behaviors/activity-indicator/index.android.d.ts

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

package/build/behaviors/activity-indicator/index.android.js

@@ -0,0 +1,16 @@
+// ActivityIndicator's behavior on Android, where the spinner is `AndroidProgressBar` and needs two
+// props RN's iOS branch never sends (`ActivityIndicator.js:106`, spread only at `:118`):
+//
+//   styleAttr      drives ProgressBar.setStyle(); without it the view throws "setStyle() not called"
+//   indeterminate  the spinner has no determinate mode here
+//
+// and where the default colour is the THEME — expressed as null so the fold omits the key entirely
+// rather than handing Fabric's colour parser a null it rejects.
+import { registerActivityIndicatorBehaviors } from './shared.js';
+const ANDROID_STYLE_ATTR = 'Normal';
+export function registerActivityIndicatorBehavior() {
+    registerActivityIndicatorBehaviors({
+        defaultColor: null,
+        nativeExtras: { styleAttr: ANDROID_STYLE_ATTR, indeterminate: true },
+    });
+}

package/build/behaviors/activity-indicator/index.d.ts

@@ -0,0 +1,3 @@
+export { registerActivityIndicatorBehavior } from './index.ios';
+export { ACTIVITY_INDICATOR_SPINNER_TAG, ACTIVITY_INDICATOR_TAG, } from './shared';
+export type { IActivityIndicatorProps, IActivityIndicatorSize } from './shared';

package/build/behaviors/activity-indicator/index.ios.d.ts

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

package/build/behaviors/activity-indicator/index.ios.js

@@ -0,0 +1,14 @@
+// ActivityIndicator's behavior on iOS: `ActivityIndicatorView` takes the size enum and a GRAY
+// default colour, and needs no extra native props. That is the entire platform half.
+//
+// This file is also the base the folder's `index.ts` re-exports for headless, matching every other
+// platform-split module in this tree.
+import { registerActivityIndicatorBehaviors } from './shared.js';
+// RN's iOS default spinner colour (`ActivityIndicator.js:25`, GRAY).
+const IOS_DEFAULT_COLOR = '#999999';
+export function registerActivityIndicatorBehavior() {
+    registerActivityIndicatorBehaviors({
+        defaultColor: IOS_DEFAULT_COLOR,
+        nativeExtras: {},
+    });
+}

package/build/behaviors/activity-indicator/index.js

@@ -0,0 +1,5 @@
+// The base of the folder-as-module group: Metro picks `index.ios` / `index.android` per platform,
+// and everything else (tsx, vitest, headless) lands here. iOS is the default, matching every other
+// platform-split module in this tree.
+export { registerActivityIndicatorBehavior } from './index.ios.js';
+export { ACTIVITY_INDICATOR_SPINNER_TAG, ACTIVITY_INDICATOR_TAG, } from './shared.js';

package/build/behaviors/activity-indicator/shared.d.ts

@@ -0,0 +1,18 @@
+import { type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps } from '../../accessibility-props';
+export declare const ACTIVITY_INDICATOR_TAG = "activity-indicator";
+export declare const ACTIVITY_INDICATOR_SPINNER_TAG = "activity-indicator-spinner";
+export type IActivityIndicatorSize = 'small' | 'large' | number;
+export interface IActivityIndicatorProps extends IAccessibilityProps, IAriaProps {
+    animating?: boolean;
+    color?: string;
+    size?: IActivityIndicatorSize;
+    hidesWhenStopped?: boolean;
+    style?: IStyleProp<IViewStyle>;
+    onLayout?: (event: ISymbioteEvent) => void;
+}
+export type IActivityIndicatorPlatform = {
+    defaultColor: string | null;
+    nativeExtras: Readonly<Record<string, unknown>>;
+};
+export declare function registerActivityIndicatorBehaviors(platform: IActivityIndicatorPlatform): void;

package/build/behaviors/activity-indicator/shared.js

@@ -0,0 +1,149 @@
+// ActivityIndicator's host behavior: the composition and the prop fold, below the framework, so the
+// primitive is a bare `activity-indicator` tag and not five wrapper components.
+//
+// THE TWO-NODE SHAPE IS RN'S, not ours to collapse. `ActivityIndicator.js:112` opens a centering
+// `<View>` around the native spinner, so the tag is that View and `buildStructure` builds
+// `activity-indicator-spinner` under it. The container cannot be folded INTO the spinner either: it
+// carries `alignItems`/`justifyContent`, which centre the spinner inside the space it was given,
+// and moved onto the spinner they would centre its children, of which it has none.
+//
+// THE PLATFORM HALF IS THE SPINNER'S DEFAULTS AND NOTHING ELSE. iOS defaults the colour to RN's GRAY
+// and needs no extra native props; Android's default is the theme, which means OMITTING the key
+// rather than sending null (Fabric's colour parser rejects a null), plus `styleAttr` and
+// `indeterminate` — without the first, AndroidProgressBar throws "setStyle() not called".
+// `index.ios` / `index.android` supply them, the same file split `behaviors/scroll-view` uses.
+//
+// WHERE THE APP'S PROPS GO. `slotPropsExcept` is the COMPLEMENT of a rename map: everything an app
+// writes on the tag routes to the spinner under its own name except `ACTIVITY_INDICATOR_HOST_PROPS`,
+// which is RN's own split (`ActivityIndicator.js:99` spreads `...restProps` onto the spinner; `:113`
+// keeps `onLayout` and `style` on the View). The set that moves is OPEN — every aria alias, every
+// accessibility prop, whatever an app writes next — so a name map cannot express it.
+//
+// THE SIZE TRANSLATION IS PLATFORM-INVARIANT and lives here beside the fold that applies it: RN maps
+// 'small'/'large' to a native size enum AND a fixed box style, while a NUMBER never reaches native
+// at all (it sizes the spinner through style alone).
+//
+// Registered by all five adapters since 2026-09-09, in the same commit that deleted the five
+// wrappers — the registry is keyed by TAG, so registering while a wrapper still painted its own
+// spinner would have given every indicator two.
+import { appendChild, createElement, registerHostBehavior, } from '@symbiote-native/engine';
+import { descriptorFor } from '../../component-names';
+export const ACTIVITY_INDICATOR_TAG = 'activity-indicator';
+// The NATIVE spinner — `ActivityIndicatorView` on iOS, `AndroidProgressBar` on Android. Built by
+// `buildStructure` below and by nothing else; no app writes it.
+export const ACTIVITY_INDICATOR_SPINNER_TAG = 'activity-indicator-spinner';
+// Fixed pixel boxes RN gives the two named sizes (styles.sizeSmall/sizeLarge).
+const SIZE_SMALL_PX = 20;
+const SIZE_LARGE_PX = 36;
+// RN's own default when the app writes no `size` (ActivityIndicator.js:72).
+const DEFAULT_SIZE = 'small';
+// Centering wrapper RN puts around the spinner (styles.container).
+const CONTAINER_STYLE = {
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+// The props that stay on the centering host instead of travelling to the spinner: RN's own two
+// (`ActivityIndicator.js:113`) plus the spellings the ENGINE resolves against a node's own style.
+const ACTIVITY_INDICATOR_HOST_PROPS = [
+    // A layout callback measures the box the spinner is centred IN, which is this node.
+    'onLayout',
+    // The composed `StyleSheet.compose(styles.container, style)` array (`:114`).
+    'style',
+    // A class NAME resolves to a style (`routeProp`'s class branch), so a class written on the tag has
+    // to reach the centering view — the node `style` lands on — or the app's rule paints a spinner it
+    // was never written for.
+    'class',
+    'className',
+];
+function resolveSize(size) {
+    if (size === 'small') {
+        return {
+            sizeStyle: { width: SIZE_SMALL_PX, height: SIZE_SMALL_PX },
+            sizeProp: 'small',
+        };
+    }
+    if (size === 'large') {
+        return {
+            sizeStyle: { width: SIZE_LARGE_PX, height: SIZE_LARGE_PX },
+            sizeProp: 'large',
+        };
+    }
+    return { sizeStyle: { width: size, height: size } };
+}
+// The HOST's fold: RN's `StyleSheet.compose(styles.container, style)` (ActivityIndicator.js:114).
+// Base first, so an app style still wins.
+const hostFold = props => ({
+    ...props,
+    style: [CONTAINER_STYLE, props.style],
+});
+function isActivityIndicatorSize(value) {
+    return value === 'small' || value === 'large' || typeof value === 'number';
+}
+// The SPINNER's fold — RN's own body (`ActivityIndicator.js:99-118`) applied to the node the app
+// never names.
+function spinnerFold(platform) {
+    return props => {
+        const size = isActivityIndicatorSize(props.size)
+            ? props.size
+            : DEFAULT_SIZE;
+        const { sizeStyle, sizeProp } = resolveSize(size);
+        const next = {
+            ...props,
+            // RN defaults both to true and every wrapper spelled that `!== false`. A tag has no
+            // destructuring default, so the fold is where the default has to live.
+            animating: props.animating !== false,
+            hidesWhenStopped: props.hidesWhenStopped !== false,
+            style: sizeStyle,
+        };
+        // A NUMBER never reaches native: it sizes the spinner through style alone, and the native enum
+        // takes 'small'/'large' only. So the key has to leave, not merely go unwritten.
+        if (sizeProp === undefined)
+            delete next.size;
+        else
+            next.size = sizeProp;
+        const color = typeof props.color === 'string' ? props.color : platform.defaultColor;
+        // Omitted rather than sent as null — Android's theme default is null and Fabric's colour parser
+        // rejects one.
+        if (color === null)
+            delete next.color;
+        else
+            next.color = color;
+        return next;
+    };
+}
+// The composition. Returns the spinner as the slot because the prop redirect is gated on
+// `childHost` being set — the redirect is what this slot is FOR, and NOT where children go: RN's
+// ActivityIndicator renders only the spinner (`ActivityIndicator.js:112-118`) and takes no children
+// at all. Hence `slotTakesNoChildren` below; without it a stray child would mount INSIDE the native
+// spinner, which on Android is a `ProgressBar` and not a `ViewGroup` — the `addView` crash
+// `IHostBehavior.slotTakesNoChildren` records for ImageBackground's Image.
+function buildSpinner(platform) {
+    return (node) => {
+        const descriptor = descriptorFor(ACTIVITY_INDICATOR_SPINNER_TAG);
+        const spinner = createElement(descriptor.component, descriptor.isText, ACTIVITY_INDICATOR_SPINNER_TAG);
+        // Constants of the platform, never a function of a prop, so they are seeded at build time the
+        // way ScrollView seeds `collapsable: false` — empty on iOS, AndroidProgressBar's two
+        // requirements on Android.
+        spinner.props = { ...platform.nativeExtras };
+        spinner.payloadFold = spinnerFold(platform);
+        appendChild(node, spinner);
+        return spinner;
+    };
+}
+function activityIndicatorBehavior(platform) {
+    return {
+        slotPropsExcept: ACTIVITY_INDICATOR_HOST_PROPS,
+        slotTakesNoChildren: true,
+        buildStructure: buildSpinner(platform),
+        foldPayload: hostFold,
+        // Required by the interface and deliberately empty: this primitive owns no timer, no listener
+        // and no native handshake. Written out rather than shared with a `noop` so the emptiness reads
+        // as a decision.
+        attach() { },
+        detach() { },
+    };
+}
+// Called by the platform files; nothing else should.
+export function registerActivityIndicatorBehaviors(platform) {
+    registerHostBehavior(ACTIVITY_INDICATOR_TAG, activityIndicatorBehavior(platform));
+}

package/build/behaviors/button.d.ts

@@ -0,0 +1,2 @@
+export declare const BUTTON_TAG = "button";
+export declare function registerButtonBehavior(): void;

package/build/behaviors/button.js

@@ -0,0 +1,328 @@
+// Button as an ENGINE-NODE behavior, so RN's one batteries-included control can be an intrinsic
+// tag instead of five framework components (`.claude/rules/host-primitive-tier.md`, tier 2).
+//
+// THE WHOLE PRIMITIVE IS COMPOSITION. RN's Button is a touchable wrapping a View wrapping a Text
+// (Button.js:363-388) and takes NO children — `title` is a string prop. So `buildStructure` owns
+// the entire subtree, and the nodes below it are a PROJECTION of three owner props.
+//
+// AND THE TOUCHABLE IS NOT THE SAME ONE ON BOTH PLATFORMS (Button.js:281-284), which is why the
+// two trees have different HEIGHTS. TouchableOpacity WRAPS — it renders its own `<Animated.View>`
+// and puts the child inside it (TouchableOpacity.js:302,344). TouchableNativeFeedback RENDERS
+// NOTHING and clones its props onto the child instead (TouchableNativeFeedback.js:339), so on
+// Android Button's own `<View style={buttonStyles}>` IS the responder:
+//
+//   iOS      button   RCTView      TouchableOpacity's Animated.View — the responder + the fade
+//            └ view   RCTView      resolveButtonViewStyle(color, disabled) — `{}` here
+//              └ text RCTText      resolveButtonTextStyle(color, disabled) + RN's Text defaults
+//                └ raw RCTRawText  resolveButtonTitle(title)                       FOUR nodes
+//
+//   Android  button   RCTView      the styled button view, CLONED onto: the responder, the ripple
+//            │                     background, the whole a11y fold. No fade, no wrapper.
+//            └ text   RCTText
+//              └ raw  RCTRawText   UPPERCASED (Button.js:352-353)                 THREE nodes
+//
+// EVERY FOLD IS ALREADY WRITTEN AND TESTED in `../view/render-button`; nothing here re-derives one.
+// What is new is only WHERE they run: on engine nodes, instead of in a component body.
+//
+// ---------------------------------------------------------------------------------------------
+// HOW THE PROJECTION REACHES ITS NODES, given that each `payloadFold` MUST be pure:
+//
+//   title    a REDIRECT. The raw text is the slot, and `slotProps` renames `title` -> `text` on it,
+//            so the app's write lands on the label through the label's own `routeProp` and marks
+//            it. `resolveButtonTitle`'s uppercase is then the label's own fold over its OWN props —
+//            no owner to read, and `isEmptyRawText` still sees the real title, so an empty one is
+//            dropped by the commit walk exactly as it was before.
+//   color    a per-node FOLD over the owner, on the text and — on iOS — on the view (the shape
+//   disabled `behaviors/scroll-view/shared.ts` uses). `slotDerived` marks the slot, and
+//            `addDerivedNode` extends that mark to the nodes past it. On Android the second
+//            consumer is the OWNER itself, which `setProp` already dirties.
+//
+// So no node writes to another and no follow-up commit is needed. Two seams that do NOT work here,
+// measured against the real commit path, so neither is tried again:
+//
+//   slotDerived alone     marks `node.childHost` and nothing else — ONE node, where a colour change
+//                         moves two. `addDerivedNode` is the hop past it.
+//   afterCommit           UNREACHABLE for exactly the props that matter. `title` and `color` never
+//                         reach the host payload, so a write to either produces a byte-identical
+//                         payload and `commitContainer` returns on a no-op ABOVE
+//                         `runDeferredAttaches`. Recorded at `IHostBehavior.afterCommit`.
+//
+// WHY THE OWNER'S FOLD IS BOUND IN `buildStructure` rather than declared as `behavior.foldPayload`.
+// It needs two things that are not in the bag it is handed: `onPress` lives in the listener STASH
+// (`ownedListeners` diverts it, so `props.onPress` is always undefined), and `focusable` is a
+// function of it. `scroll-view/index.android.ts` assigns `owner.payloadFold` from `onWrapChange`
+// for the same reason; `attachHostBehavior` sets the field one line BEFORE it calls
+// `buildStructure`, so the binding here is what stands.
+// ---------------------------------------------------------------------------------------------
+// KNOWN DIVERGENCES, stated rather than left to be discovered on a device:
+//
+// 1. CLOSED 2026-09-09, and it closed by DELETION rather than by a fix. The gap was that all five
+//    wrappers rendered TouchableOpacity unconditionally where RN swaps in TouchableNativeFeedback
+//    (Button.js:280-283), so a Button faded on Android and committed four nodes where RN ripples
+//    and commits three. There is no wrapper left to diverge: `button` is a tag, registered by all
+//    five adapters, and the swap above is the only implementation.
+//
+//    THE ORDER MATTERED AND IS THE REUSABLE HALF. The registry is keyed by TAG, so registering
+//    while a wrapper still built its own view and text would have given every Button a SECOND copy
+//    of the subtree — the hazard `behaviors/scroll-view/shared.ts` records. Entry, registration and
+//    the five deletions are one change, which is also what `touchable-native-feedback` did hours
+//    earlier and for the same reason.
+//
+//    WHAT AN APP SEES, stated because it is a behaviour change and not a refactor: on Android a
+//    Button now ripples instead of fading and commits three nodes instead of four. That is the RN
+//    parity this whole line of work was for.
+//
+// 2. CLOSED 2026-09-09, kept for the seam rather than the gap. `aria-disabled` — and an authored
+//    `accessibilityState.disabled` — now suppress the press, not just grey the label.
+//
+//    THE RESOLUTION IS BUTTON'S, NOT THE MACHINE'S, and that asymmetry is the finding. RN hands
+//    Pressability the RAW prop (Pressable.js:266), so on a bare `pressable` `aria-disabled` changes
+//    only what is ANNOUNCED and the press still fires; resolving it down there would be a new
+//    divergence pointing the other way. Button is the outlier (Button.js:337), so it hands the
+//    touchable an `IDisabledResolver` (`./pressable`) and `rebuild` calls it at every gesture start.
+//
+//    A RESOLVER RATHER THAN A WRITE, because writing the answer into `node.props.disabled` LATCHES:
+//    `resolveButtonDisabled` short-circuits on `disabled !== undefined`, so the injected value would
+//    answer the next resolution as the app's own and the button could never re-enable. Reading per
+//    gesture also means a flip needs no commit to reach the machine.
+//
+//    AND THE PRESS WAS ONLY HALF OF IT. `./touchable-opacity`'s `afterCommit` re-settles the fade
+//    when `disabled` moves, and it read the RAW prop — so for an hour after the press half closed, a
+//    Button disabled by `aria-disabled` mid-press stayed at its ACTIVE opacity while already
+//    refusing the press. It reads through the same resolver now. The general shape: one prop
+//    resolved in two places, and closing the first makes the second look done.
+//
+// 3. CLOSED 2026-09-09, repo-wide, and kept here for the finding rather than the gap. `focusable`
+//    was emitted by NOTHING in `core/components` — not a wrapper, not the press behavior — so a
+//    keyboard or TV host could focus a disabled button, on every adapter and both paths. RN carries
+//    two formulas (`Pressable.js:258` vs the four `Touchable*`, which also require a press handler
+//    and a non-disabled state); both now live in `../view/render-pressable` and every behavior and
+//    surviving wrapper calls them.
+// ---------------------------------------------------------------------------------------------
+//
+// 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 view and text under this tag, registering would have given
+// every Button a second copy of the subtree.
+import { addDerivedNode, appendChild, appListenerFor, createElement, createRawText, markPropsDirty, Platform, registerHostBehavior, requestCommitFor, } from '@symbiote-native/engine';
+import { descriptorFor } from '../component-names';
+import { resolveTextProps } from '../text-props.js';
+import { BUTTON_ACCESSIBILITY_ROLE, resolveButtonDisabled, resolveButtonImportantForAccessibility, resolveButtonTextStyle, resolveButtonTitle, resolveButtonViewStyle, } from '../view/render-button.js';
+import { backgroundProps, selectableBackground, } from '../view/render-touchable-native-feedback.js';
+import { resolveTouchableFocusable } from '../view/render-pressable/index.js';
+import { booleanOr, createPressBehavior, } from './pressable.js';
+import { nativeFeedbackRefinement } from './touchable-native-feedback.js';
+import { createTouchableOpacityBehavior } from './touchable-opacity.js';
+export const BUTTON_TAG = 'button';
+// Read once, like `render-button`'s own module-level `buttonViewStyle`: the platform cannot change
+// under a running app, and every test that needs the other branch already has to mock `Platform`
+// for `render-button` regardless — which is why this is a branch rather than a `button/` folder
+// split. A file split would move the behavior and leave its style half still reading `Platform`.
+const IS_ANDROID = Platform.OS === 'android';
+// The owner props the derived nodes' styles are derived from. A name missing here is a node frozen
+// at its mount value, which is the whole failure mode this list has. `title` is NOT one of them: it
+// is redirected by `SLOT_PROPS` and never reaches `setProp` on the owner, so listing it would be
+// dead.
+const SLOT_DERIVED = [
+    'color',
+    'disabled',
+    'aria-disabled',
+    'accessibilityState',
+];
+// Button.js:386 renders `<Text>{title}</Text>`; the raw text is where that string lives.
+const SLOT_PROPS = { title: 'text' };
+function stringOr(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+// `accessibilityState` arrives as `unknown` off `node.props`, and only `disabled` decides anything
+// here. Narrowed field by field rather than cast, the idiom `./pressable` uses for the same bag.
+function accessibilityDisabled(value) {
+    if (typeof value !== 'object' || value === null)
+        return {};
+    const disabled = Reflect.get(value, 'disabled');
+    return typeof disabled === 'boolean' ? { disabled } : {};
+}
+// Takes the PROP BAG rather than the node, so the owner's own fold — which is handed a bag and not
+// a node — resolves the same projection its derived children do.
+function projectionOf(props) {
+    return {
+        color: stringOr(props.color),
+        // Button.js:337 — `disabled` may be decided by `aria-disabled` or by an authored
+        // `accessibilityState.disabled`. The engine folds both into the COMMITTED accessibilityState
+        // already; this is the half a payload fold cannot do, which is greying the label.
+        disabled: resolveButtonDisabled(booleanOr(props.disabled), booleanOr(props['aria-disabled']), accessibilityDisabled(props.accessibilityState)),
+    };
+}
+// What the press machine reads instead of the raw prop — see KNOWN DIVERGENCES 2. Pure: the
+// projection is derived per call and nothing is written back.
+const buttonDisabled = props => projectionOf(props).disabled;
+/**
+ * NO MEMO, and the earlier version's memo is deliberately gone. It guarded `setProp`'s `Object.is`,
+ * which a FRESH style object per call can never satisfy — so pushing unconditionally would have
+ * dirtied a node on every commit and re-committed forever
+ * (`.claude/rules/list-geometry-feedback-loop.md`). A payload fold does not go through `setProp`:
+ * its result reaches `reconcile`, which compares against the mirror with a recursive `propsEqual`
+ * (commit.ts) and reuses the committed handle when nothing moved. An equal-but-fresh style is
+ * therefore not a change, and there is nothing to feed back.
+ */
+function viewFold(owner) {
+    return props => {
+        const { color, disabled } = projectionOf(owner.props);
+        return { ...props, style: resolveButtonViewStyle(color, disabled) };
+    };
+}
+function textFold(owner) {
+    return props => {
+        const { color, disabled } = projectionOf(owner.props);
+        return {
+            ...props,
+            style: resolveButtonTextStyle(color, disabled),
+            // RN puts `disabled` on the Text as well (Button.js:386) — a real RCTText prop read by
+            // Android's accessibility layer, and not the same thing as the greyed colour above.
+            disabled,
+        };
+    };
+}
+// Reads its OWN `text`, which `SLOT_PROPS` redirected the app's `title` into — no owner closure, so
+// the fold is shared by every button. `fabricProps` reads only `.text` off a raw-text fold.
+const labelFold = props => ({
+    text: resolveButtonTitle(stringOr(props.text) ?? ''),
+});
+// ---- the Android touchable -------------------------------------------------------------------
+// Button.js:281-284. Not two variants of one component: see the tree diagram at the top for what
+// wrapping instead of cloning costs. The Android arm composes the bare press machine, so no
+// opacity value is opened and no fade runs — the ripple IS the feedback there.
+//
+// The refinement is TNF's own and now lives with TNF (`./touchable-native-feedback`). This file
+// held a private copy while the `touchable-native-feedback` TAG did not exist and its wrappers
+// still wrapped where RN clones; the tag landed, the responder node was already a parameter, and
+// one caller became two.
+const touchable = IS_ANDROID
+    ? createPressBehavior(nativeFeedbackRefinement, buttonDisabled)
+    : createTouchableOpacityBehavior(buttonDisabled);
+// ---- the owner's own payload -------------------------------------------------------------------
+/**
+ * The wrapper-body folds, over the touchable's own. What is deliberately NOT here:
+ *
+ *   accessible          the touchable's fold already applies `accessible !== false`, which is
+ *                       exactly RN's split — Button forwards the caller's value RAW (Button.js:365)
+ *                       and the touchable one level down defaults it (TouchableOpacity.js:303).
+ *   accessibilityState  the engine's aria fold gives `ariaDisabled ?? state.disabled` and the press
+ *                       fold then merges `props.disabled` over it, which composes to RN's
+ *                       `props.disabled ?? aria ?? state.disabled` — the same value, with
+ *                       busy/checked/expanded/selected preserved, without a Button-specific fold.
+ */
+function ownerFold(node) {
+    return props => {
+        const next = {
+            ...(touchable.foldPayload === undefined
+                ? props
+                : touchable.foldPayload(props)),
+        };
+        next.accessibilityRole = BUTTON_ACCESSIBILITY_ROLE;
+        // 'no' is the only value the resolver moves (Button.js:356), so checking for it IS the
+        // narrowing this bag needs — the shared resolver still owns what 'no' becomes.
+        if (next.importantForAccessibility === 'no')
+            next.importantForAccessibility =
+                resolveButtonImportantForAccessibility('no');
+        // Re-mapped, so the raw name must not also reach Fabric. Where the wrappers put it too — the
+        // pressable owns sound suppression (Button.js:377 hands `touchSoundDisabled` to the touchable).
+        if (Object.hasOwn(next, 'touchSoundDisabled')) {
+            next.android_disableSound = next.touchSoundDisabled;
+            delete next.touchSoundDisabled;
+        }
+        const { color, disabled } = projectionOf(props);
+        // TouchableOpacity.js:336 and TouchableNativeFeedback.js:369 — the SAME expression, so the tag
+        // owes it on both platforms. `onPress` is an owned name, so it is in the stash and never in
+        // `props`; a flip of it dirties nothing by itself, which `onOwnedListenerChange` answers.
+        next.focusable = resolveTouchableFocusable(booleanOr(props.focusable), appListenerFor(node, 'press') !== undefined, disabled);
+        if (IS_ANDROID) {
+            // TNF renders no view, it CLONES onto Button's `<View style={buttonStyles}>`
+            // (TouchableNativeFeedback.js:339), so this host IS that view. Overwritten rather than merged
+            // because RN's Button declares no `style` prop at all — there is nothing to compose with.
+            next.style = resolveButtonViewStyle(color, disabled);
+            // Button passes no `background` and no `useForeground`, so TNF resolves the theme's
+            // selectable background onto the background slot (TouchableNativeFeedback.js:343-348,
+            // :402). The dicts are the shared factories', never restated here.
+            Object.assign(next, backgroundProps(selectableBackground(), false));
+        }
+        // Read by the folds above and declared by no ViewConfig. A key Fabric does not know throws
+        // nothing, logs nothing and paints nothing, so the strip has to be here or it is never noticed.
+        // `title` needs none — `SLOT_PROPS` redirects it before it can land on this node.
+        delete next.color;
+        return next;
+    };
+}
+/**
+ * Builds the whole subtree, once, at `attachHostBehavior`.
+ *
+ * RETURNS THE RAW TEXT. RN's Button declares no `children` prop and renders none, so the slot is
+ * not where the app's children go — it is where its `title` goes, which is what `SLOT_PROPS`
+ * redirects onto it. `childHost` is also the GATE on both engine seams this behavior uses:
+ * `slotDerived`'s mark and the prop redirect are both skipped unless it is set (node.ts), so
+ * returning `undefined` would leave the whole subtree frozen at its mount values.
+ */
+function buildStructure(node) {
+    const textDescriptor = descriptorFor('text');
+    const text = createElement(textDescriptor.component, textDescriptor.isText, 'text');
+    // RN's Text.js applies these to every non-virtual Text on its way to native, and a hand-written
+    // host tag inherits nothing a `<Text>` component did — Svelte's Button clipped long labels
+    // mid-word for exactly this reason (`.claude/rules/host-primitive-tier.md`, "The THIRD path").
+    // Constants, because the app cannot reach this node to override them.
+    text.props = resolveTextProps({});
+    // Empty until the redirected `title` arrives. The commit walk drops an empty raw text
+    // (`isEmptyRawText`, node.ts), so no Fabric node exists for it until it has a label — and that
+    // check reads `props.text`, which the redirect writes, not the fold's uppercased output.
+    const label = createRawText('');
+    text.payloadFold = textFold(node);
+    label.payloadFold = labelFold;
+    // The hop `slotDerived` alone does not make: it marks the slot (the label), and this is past it.
+    addDerivedNode(node, text);
+    appendChild(text, label);
+    if (IS_ANDROID) {
+        // No fourth node: TNF clones onto the styled view, so the host IS it and the label's parent
+        // hangs straight off it.
+        appendChild(node, text);
+    }
+    else {
+        const viewDescriptor = descriptorFor('view');
+        const view = createElement(viewDescriptor.component, viewDescriptor.isText, 'view');
+        view.payloadFold = viewFold(node);
+        addDerivedNode(node, view);
+        appendChild(view, text);
+        // Lands on the owner, because `node.childHost` is still undefined here — the engine assigns it
+        // from what this returns. That ordering is why `buildStructure` RETURNS the slot instead of
+        // setting the field itself.
+        appendChild(node, view);
+    }
+    // See the header: the owner's fold needs its own node, and this runs after
+    // `attachHostBehavior` has already written `behavior.foldPayload` into the field.
+    node.payloadFold = ownerFold(node);
+    return label;
+}
+// `focusable` is a function of a LISTENER, and a listener flip changes no payload by itself — so
+// the commit after it is a no-op and no fold re-runs (`IHostBehavior.onOwnedListenerChange`).
+function onOwnedListenerChange(node, name) {
+    if (name !== 'press')
+        return;
+    markPropsDirty(node);
+    requestCommitFor(node);
+}
+// Idempotent: an adapter entry may be imported more than once in a bundle.
+export function registerButtonBehavior() {
+    // `attach`/`detach` come from the touchable unwrapped: the internal nodes are ordinary children
+    // that leave with the sweep, and each carries only a pure fold, so this behavior owns no per-node
+    // runtime of its own to release.
+    //
+    // No `foldPayload` here on purpose — `buildStructure` binds the owner's fold to its node.
+    const behavior = {
+        ...touchable,
+        foldPayload: undefined,
+        buildStructure,
+        onOwnedListenerChange,
+        slotProps: SLOT_PROPS,
+        slotDerived: SLOT_DERIVED,
+    };
+    registerHostBehavior(BUTTON_TAG, behavior);
+}

package/build/behaviors/image-background.d.ts

@@ -0,0 +1,2 @@
+export declare const IMAGE_BACKGROUND_TAG = "image-background";
+export declare function registerImageBackgroundBehavior(): void;