@symbiote-native/components 0.5.0 → 2.0.0

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;

package/build/behaviors/image-background.js

@@ -0,0 +1,139 @@
+// ImageBackground's host behavior: the composition and the prop split the wrapper component did,
+// moved below the framework so the primitive can be a bare tag.
+//
+// THE TWO-NODE SHAPE IS RN'S. `ImageBackground.js:74-103` opens a `<View>` carrying the app's
+// `style`, puts an absolutely-filled `<Image>` inside it, and lays the app's `{children}` AFTER
+// that image so they paint on top. The lowered form is the same two nodes — `image-background`
+// (an RCTView, the tag an app writes) with an RCTImageView built under it.
+//
+// WHY THE SLOT TAKES NO CHILDREN, which is the one thing this primitive needed that ScrollView,
+// ActivityIndicator and Button did not. `childHost` answers two questions at once — which node an
+// owner prop redirects onto, and which node the app's children go under — and those had the same
+// answer for every primitive until this one. Here they differ: the image takes `imageStyle` and the
+// whole `...props` spread, while the children belong beside it. `slotTakesNoChildren` is what
+// splits them (`IHostBehavior`, and it is not a JSX nicety upstream could have collapsed — an
+// Android `<Image>` is an `ImageView`, not a `ViewGroup`).
+//
+// WHERE THE APP'S PROPS GO. RN destructures `children, style, imageStyle, imageRef,
+// importantForAccessibility, ...props` and spreads `...props` onto the Image
+// (`ImageBackground.js:62-81`), so the set that moves is OPEN — every event, every accessibility
+// prop, `testID`, `id`, whatever an app writes next — and only a complement can express it.
+// `IMAGE_BACKGROUND_HOST_PROPS` is the short list that stays behind, and it is shorter than RN's:
+// `importantForAccessibility` rides to the image alone, which is what all five wrappers did, so
+// the tag and the component it replaces commit the same payload. The divergence from RN predates
+// lowering and is unchanged by it.
+//
+// WHAT THE IMAGE'S FOLD OWES. Everything on the image arrives as a real prop write, so its payload
+// is built by the shared `foldImagePayload` like any other `image`. Two things cannot arrive that
+// way and are folded here: the style, which is DERIVED from the owner's own `style` (RN proxies the
+// wrapper's width/height onto the image so it fills the box rather than collapsing to the source's
+// intrinsic size), and `id`, whose rename to `nativeID` is applied per adapter on the tag THEY
+// create and so never reaches a node a behavior built.
+import { appendChild, createElement, flattenStyle, registerHostBehavior, } from '@symbiote-native/engine';
+import { descriptorFor } from '../component-names';
+import { foldImagePayload, IMAGE_TAG } from './image.js';
+export const IMAGE_BACKGROUND_TAG = 'image-background';
+// The inner Image's positioning: absolute-fill behind the box's children.
+const ABSOLUTE_FILL = {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
+};
+// The props RN keeps on the wrapper View (`ImageBackground.js:74-78`), plus the two spellings of a
+// class name — `routeProp`'s slot redirect runs above its own class branch, so an unlisted `class`
+// would style the image instead of the box.
+const IMAGE_BACKGROUND_HOST_PROPS = ['style', 'class', 'className'];
+// The owner props the image's payload is derived from. Only `style`, because a class name is
+// published INTO `node.props.style` by `pushClassStyle` — so a `class` write arrives here spelled
+// `style` and the proxied width/height follow a class-declared box as well as an inline one.
+const IMAGE_BACKGROUND_SLOT_DERIVED = ['style'];
+// `imageStyle` is the wrapper's own name for the image's `style`. A bare class NAME is a legal
+// value for it — every adapter's wrapper resolved one — and `routeProp` routes a string landing on
+// `style` as `class` instead, so the registry resolves it on the image with nothing needed here.
+const IMAGE_BACKGROUND_SLOT_PROPS = { imageStyle: 'style' };
+// A StyleProp is an object, an array of them, or a registered class array — all of which
+// `flattenStyle` already handles one layer down. The only thing to exclude is a scalar.
+function styleOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return { ...value };
+}
+// RN opts the wrapper out of iOS's Smart Invert for its whole subtree (`ImageBackground.js:75`) —
+// a photograph inverted by accessibility settings is the case that prop exists for. None of the
+// five wrappers ever wrote it, so this closes a standing gap rather than reproducing one.
+const hostFold = props => ({
+    ...props,
+    accessibilityIgnoresInvertColors: true,
+});
+// Read one explicit dimension off the (already-flattened) box style. A dp number or a percentage
+// string is a valid IDimensionValue; anything else (auto / undefined) yields undefined.
+function readDimension(style, key) {
+    const value = Object.hasOwn(style, key) ? Reflect.get(style, key) : undefined;
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    return undefined;
+}
+function imageFold(owner) {
+    return props => {
+        // RN's own workaround, and its comment is worth reading before "simplifying" this
+        // (`ImageBackground.js:86-96`): an RN Image overwrites its own width/height from the source's
+        // intrinsic size, which fights the box's explicit dimensions, so they are proxied back on.
+        // Reads the OWNER's live style — a class name lands there too, published by `pushClassStyle`.
+        const box = flattenStyle(styleOf(owner.props.style));
+        const next = {
+            ...props,
+            // `imageStyle` last, so a caller still wins over the fill and the proxy.
+            style: [
+                ABSOLUTE_FILL,
+                {
+                    width: readDimension(box, 'width'),
+                    height: readDimension(box, 'height'),
+                },
+                styleOf(props.style),
+            ],
+        };
+        // Unconditional priority when both are set, matching RN (`View.js:77-79`) and `foldHostBag`.
+        // A raw `id` is a key no ViewConfig declares, so Fabric drops it and the nativeID is lost.
+        if (Object.hasOwn(next, 'id')) {
+            next.nativeID = next.id;
+            delete next.id;
+        }
+        return foldImagePayload(next);
+    };
+}
+// Returns the image, so `slotProps` / `slotPropsExcept` / `slotDerived` all point at it — and the
+// app's children stay on the owner because of `slotTakesNoChildren`, not because of what this
+// returns. The image is appended FIRST and nothing else is ever placed in front of it, which is
+// what makes the children paint over it.
+//
+// Built WITHOUT handing `IMAGE_TAG` to `createElement`, deliberately: that would attach Image's own
+// behavior and set `payloadFold` to `foldImagePayload` alone, and this node's style has to be
+// derived from the owner. `payloadFold` is a single slot, so the composition is spelled here — and
+// it still calls the one shared mapping rather than restating it.
+function buildBackgroundImage(node) {
+    const descriptor = descriptorFor(IMAGE_TAG);
+    const image = createElement(descriptor.component, descriptor.isText);
+    image.payloadFold = imageFold(node);
+    appendChild(node, image);
+    return image;
+}
+const imageBackgroundBehavior = {
+    slotProps: IMAGE_BACKGROUND_SLOT_PROPS,
+    slotPropsExcept: IMAGE_BACKGROUND_HOST_PROPS,
+    slotDerived: IMAGE_BACKGROUND_SLOT_DERIVED,
+    slotTakesNoChildren: true,
+    buildStructure: buildBackgroundImage,
+    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() { },
+};
+export function registerImageBackgroundBehavior() {
+    registerHostBehavior(IMAGE_BACKGROUND_TAG, imageBackgroundBehavior);
+}

package/build/behaviors/image.d.ts

@@ -0,0 +1,3 @@
+export declare const IMAGE_TAG = "image";
+export declare function foldImagePayload(props: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function registerImageBehavior(): void;

package/build/behaviors/image.js

@@ -0,0 +1,123 @@
+// Image's host behavior, and it carries NOTHING but a prop fold — no listeners, no timers, no
+// commit hook. That is what a "fold-only" primitive means: the wrapper's whole body was prop
+// mapping, so its lowered form owes exactly that and nothing else.
+//
+// The fold itself is not written here. `mapImageProps` in `../view/render-image` is the one
+// implementation, and this file only narrows a flat prop bag into the typed view it takes — the
+// same shape `behaviors/text-input.ts` uses (`stringOf` / `booleanOf` guards, then hand the shared
+// resolver a typed object). A second copy of the mapping is the exact drift this primitive has
+// already paid for once: `adapters/svelte/src/components/image/image-logic.ts` reproduces it by
+// hand and says so in its own header, because nothing was exported to call.
+//
+// WHY THIS MAY SHARE THE WRAPPER'S TAG, where TextInput needed `-managed`. A behavior fold is keyed
+// on the tag, and `renderImage` emits `image` too — so on a wrapper-built node this fold
+// runs on ALREADY-FOLDED props. That is safe here and only here, because the mapping is idempotent:
+// every alias it consumes (`src`, `srcSet`, `alt`, `width`, `height`, …) is absent from its own
+// output, `source` comes back in the array shape `normalizeSource` guarantees, and
+// `loadingIndicatorSource` leaves under a DIFFERENT name (`loadingIndicatorSrc`), so a second pass
+// finds nothing left to fold. Idempotence is asserted in `image.test.ts` rather than assumed — the
+// audit rule's point is that a double fold is invisible precisely when it happens to be harmless,
+// so the property has to be pinned or it is an accident waiting to be broken.
+import { registerHostBehavior, } from '@symbiote-native/engine';
+import { IMAGE_VIEW_PROP_NAMES, mapImageProps, } from '../view/render-image/index.js';
+export const IMAGE_TAG = 'image';
+const RESIZE_MODES = new Set([
+    'cover',
+    'contain',
+    'stretch',
+    'repeat',
+    'center',
+]);
+const CROSS_ORIGINS = new Set([
+    'anonymous',
+    'use-credentials',
+]);
+const CONSUMED = new Set(IMAGE_VIEW_PROP_NAMES);
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberOf(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+function resizeModeOf(value) {
+    if (typeof value !== 'string' || !RESIZE_MODES.has(value))
+        return undefined;
+    // Narrowed by the set membership above, then re-stated as the union through a switch rather than
+    // a cast: the set and the type are two declarations of one list, and only this makes them agree.
+    switch (value) {
+        case 'cover':
+        case 'contain':
+        case 'stretch':
+        case 'repeat':
+        case 'center':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function crossOriginOf(value) {
+    if (typeof value !== 'string' || !CROSS_ORIGINS.has(value))
+        return undefined;
+    return value === 'anonymous' ? 'anonymous' : 'use-credentials';
+}
+// A source is an asset id (number), a `{uri}` object, or an array of those. Anything else cannot be
+// resolved and is dropped rather than forwarded — a malformed source reaching Fabric paints nothing
+// and reports nothing, which is worse than an image that is simply absent.
+function sourceOf(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    if (typeof Reflect.get(value, 'uri') === 'string')
+        return { ...value };
+    return undefined;
+}
+// A StyleProp is an object, an array of them, or a registered class array — all of which
+// `flattenStyle` already handles. The only thing to exclude is a scalar.
+function styleOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return { ...value };
+}
+export function foldImagePayload(props) {
+    const passthrough = {};
+    for (const key of Object.keys(props)) {
+        if (!CONSUMED.has(key))
+            passthrough[key] = props[key];
+    }
+    return mapImageProps({
+        source: sourceOf(props.source),
+        defaultSource: sourceOf(props.defaultSource),
+        loadingIndicatorSource: sourceOf(props.loadingIndicatorSource),
+        style: styleOf(props.style),
+        resizeMode: resizeModeOf(props.resizeMode),
+        tintColor: stringOf(props.tintColor),
+        src: stringOf(props.src),
+        srcSet: stringOf(props.srcSet),
+        alt: stringOf(props.alt),
+        width: numberOf(props.width),
+        height: numberOf(props.height),
+        crossOrigin: crossOriginOf(props.crossOrigin),
+        referrerPolicy: stringOf(props.referrerPolicy),
+        passthrough,
+    });
+}
+// Required by IHostBehavior and deliberately empty: Image owns no per-node runtime. Written out
+// rather than shared with a `noop` helper so the emptiness reads as a decision.
+function attach(_node) {
+    // nothing to set up
+}
+function detach(_node) {
+    // nothing to release
+}
+export function registerImageBehavior() {
+    registerHostBehavior(IMAGE_TAG, {
+        attach,
+        detach,
+        foldPayload: foldImagePayload,
+    });
+}

package/build/behaviors/input-accessory-view.d.ts

@@ -0,0 +1,3 @@
+export declare const INPUT_ACCESSORY_VIEW_TAG = "input-accessory-view";
+export declare function foldInputAccessoryViewPayload(props: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function registerInputAccessoryViewBehavior(): void;