@symbiote-native/components 0.4.0 → 1.0.0

package/build/behaviors/text-input.js

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

package/build/bootstrap/index.js

@@ -4,7 +4,7 @@
 // startup. Lives OUTSIDE the package's main barrel (see package.json's separate "./bootstrap"
 // export): react-native's own source is Flow syntax Vitest's transform can't parse, so anything
 // importing it directly must stay unreachable from the tested main index.ts.
-import { processColor, DeviceEventEmitter, Image } from 'react-native';
+import { processColor, DeviceEventEmitter, Image, } from 'react-native';
 import { setColorProcessor, setDeviceEventSource, setImageSourceResolver, setNativeViewConfigSource, } from '@symbiote-native/engine';
 // @ts-expect-error react-native ships no types for this internal path (plain .js) - the
 // try/catch below is what actually proves the shape, not TS.

package/build/component-names/index.android.js

@@ -2,9 +2,10 @@
 // Each name is the ViewManager's REACT_CLASS in react-native/ReactAndroid/.../views/**.
 // device-verify-pending: source-confirmed from RN's Android ViewManagers, proven on a
 // real host by the absence of a "Can't find ViewManager '<name>'" red box.
-import { buildDescriptors, makeDescriptorFor } from './shared.js';
+import { buildDescriptors, makeDescriptorFor, } from './shared.js';
 const ANDROID_NAMES = {
     'symbiote-view': 'RCTView',
+    'symbiote-pressable': 'RCTView',
     'symbiote-text': 'RCTText',
     'symbiote-image': 'RCTImageView',
     'symbiote-scroll-view': 'RCTScrollView',
@@ -19,8 +20,29 @@ const ANDROID_NAMES = {
     // Android has one text-input ViewManager for both single- and multiline.
     'symbiote-text-input': 'AndroidTextInput',
     'symbiote-text-input-multiline': 'AndroidTextInput',
+    // The component path's pair — same native views, a tag the behavior registry does not
+    // carry. See `shared.ts` for why the wrapper may not share the lowered tag.
+    'symbiote-text-input-managed': 'AndroidTextInput',
+    'symbiote-text-input-multiline-managed': 'AndroidTextInput',
     'symbiote-switch': 'AndroidSwitch',
+    // The wrapper's tag — same native view, a tag the behavior registry does not carry. See
+    // `shared.ts` for why the wrapper may not share the lowered tag.
+    'symbiote-switch-managed': 'AndroidSwitch',
     'symbiote-activity-indicator': 'AndroidProgressBar',
+    // KNOWN DIVERGENCE FROM REACT NATIVE, and it is in our favour — recorded 2026-09-01 because it
+    // was arrived at by accident, not decided. Upstream `SafeAreaView.js` is
+    // `Platform.select({ ios: RCTSafeAreaViewNativeComponent, default: View })`, so RN's own JS
+    // renders a plain View on Android and applies NO insets. `RCTSafeAreaView` does exist and is
+    // registered (`ReactSafeAreaViewManager.REACT_CLASS`, wired in `MainReactPackage.kt:149`) and
+    // does real window-inset math — so we inset where RN does not, and an app ported from RN gets
+    // different Android layout with nothing to explain why.
+    //
+    // This table's rule is "the name is the ViewManager's REACT_CLASS", and by that rule the entry is
+    // correct. What nobody checked is whether RN's JS ROUTES there. Left as-is deliberately: insetting
+    // is the better behaviour and RN has deprecated its own component in favour of
+    // react-native-safe-area-context. Invisible to every audit we have, because both of our paths
+    // agree with each other and only disagree with RN — the boundary
+    // `.claude/rules/adapter-parity-audit.md` states about itself.
     'symbiote-safe-area-view': 'RCTSafeAreaView',
     'symbiote-modal': 'RCTModalHostView',
     'symbiote-refresh-control': 'AndroidSwipeRefreshLayout',

package/build/component-names/index.ios.js

@@ -2,9 +2,10 @@
 // (component-names.ts re-exports it) for headless tsx / tsc / web fallback.
 // Fabric names are the codegen spec's registered name (the new-arch name), not the legacy
 // paperComponentName (RCTSwitch, …).
-import { buildDescriptors, makeDescriptorFor } from './shared.js';
+import { buildDescriptors, makeDescriptorFor, } from './shared.js';
 const IOS_NAMES = {
     'symbiote-view': 'RCTView',
+    'symbiote-pressable': 'RCTView',
     'symbiote-text': 'RCTText',
     'symbiote-image': 'RCTImageView',
     'symbiote-scroll-view': 'RCTScrollView',
@@ -15,7 +16,14 @@ const IOS_NAMES = {
     'symbiote-horizontal-scroll-content': 'RCTScrollContentView',
     'symbiote-text-input': 'RCTSinglelineTextInputView',
     'symbiote-text-input-multiline': 'RCTMultilineTextInputView',
+    // The component path's pair — same native views, a tag the behavior registry does not
+    // carry. See `shared.ts` for why the wrapper may not share the lowered tag.
+    'symbiote-text-input-managed': 'RCTSinglelineTextInputView',
+    'symbiote-text-input-multiline-managed': 'RCTMultilineTextInputView',
     'symbiote-switch': 'Switch',
+    // The wrapper's tag — same native view, a tag the behavior registry does not carry. See
+    // `shared.ts` for why the wrapper may not share the lowered tag.
+    'symbiote-switch-managed': 'Switch',
     'symbiote-activity-indicator': 'ActivityIndicatorView',
     'symbiote-safe-area-view': 'SafeAreaView',
     'symbiote-modal': 'ModalHostView',

package/build/component-names/shared.d.ts

@@ -1,4 +1,4 @@
-export type ISymbioteIntrinsic = 'symbiote-view' | 'symbiote-text' | 'symbiote-image' | 'symbiote-scroll-view' | 'symbiote-scroll-content' | 'symbiote-horizontal-scroll-view' | 'symbiote-horizontal-scroll-content' | 'symbiote-text-input' | 'symbiote-text-input-multiline' | 'symbiote-switch' | 'symbiote-activity-indicator' | 'symbiote-safe-area-view' | 'symbiote-modal' | 'symbiote-refresh-control' | 'symbiote-input-accessory-view';
+export type ISymbioteIntrinsic = 'symbiote-view' | 'symbiote-pressable' | 'symbiote-text' | 'symbiote-image' | 'symbiote-scroll-view' | 'symbiote-scroll-content' | 'symbiote-horizontal-scroll-view' | 'symbiote-horizontal-scroll-content' | 'symbiote-text-input' | 'symbiote-text-input-multiline' | 'symbiote-text-input-managed' | 'symbiote-text-input-multiline-managed' | 'symbiote-switch' | 'symbiote-switch-managed' | 'symbiote-activity-indicator' | 'symbiote-safe-area-view' | 'symbiote-modal' | 'symbiote-refresh-control' | 'symbiote-input-accessory-view';
 export interface IComponentDescriptor {
     component: string;
     isText: boolean;

package/build/component-names/shared.js

@@ -13,7 +13,10 @@ const TEXT_INTRINSICS = new Set(['symbiote-text']);
 export function buildDescriptors(names) {
     const descriptors = {};
     for (const [intrinsic, component] of Object.entries(names)) {
-        descriptors[intrinsic] = { component, isText: TEXT_INTRINSICS.has(intrinsic) };
+        descriptors[intrinsic] = {
+            component,
+            isText: TEXT_INTRINSICS.has(intrinsic),
+        };
     }
     return descriptors;
 }
@@ -24,6 +27,7 @@ export function buildDescriptors(names) {
 // is a raw Fabric view name from a library's codegen component and flows through untouched
 // (the engine derives its events/processors from the view's ViewConfig, no per-library glue).
 export function makeDescriptorFor(descriptors) {
+    const unrewritten = publicNamesThatAreNotViewNames(descriptors);
     return type => {
         const descriptor = descriptors[type];
         if (descriptor !== undefined)
@@ -31,6 +35,41 @@ export function makeDescriptorFor(descriptors) {
         if (type.startsWith('symbiote-')) {
             throw new Error(`Unknown symbiote component type: ${type}`);
         }
+        if (unrewritten.has(type)) {
+            throw new Error(`"${type}" is a primitive's PUBLIC name, not a Fabric view name — a rewrite was missed. ` +
+                `Expected the intrinsic tag (e.g. "symbiote-view"). Falling through would have committed ` +
+                `a Fabric view literally named "${type}", which fails on device only.`);
+        }
         return { component: type, isText: false };
     };
 }
+// A primitive's public name reaching here means an adapter's rewrite missed a call site. Without
+// this the name falls through as a raw Fabric view name and commits a view literally called `View`
+// — no error at any layer, wrong only on a device.
+//
+// Both halves are DERIVED, because a hand-written list of either would be wrong within a release.
+// The names come from the intrinsic union (kebab -> Pascal); the exclusions come from the platform's
+// own table, and deriving them is not tidiness — two public names ARE real Fabric view names, so a
+// hand-written block list would break an adapter's thin wrapper over a third-party native view,
+// which resolves by view name through this same function.
+//
+// AND THE EXCLUSION IS PER PLATFORM, which is why it must be computed from the table rather than
+// stated. `Switch` and `SafeAreaView` are iOS view names; Android spells them `AndroidSwitch` and
+// `RCTSafeAreaView`, so the same public name is EXCLUDED on iOS and BLOCKED on Android. That
+// asymmetry is correct — nothing legitimate resolves by the bare name on Android — but a reader who
+// takes "these two are real view names" as platform-invariant will conclude the guard is broken on
+// one side or the other.
+function publicNamesThatAreNotViewNames(descriptors) {
+    const viewNames = new Set(Object.values(descriptors).map(descriptor => descriptor.component));
+    const names = new Set();
+    for (const intrinsic of Object.keys(descriptors)) {
+        const publicName = intrinsic
+            .slice('symbiote-'.length)
+            .split('-')
+            .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+        if (!viewNames.has(publicName))
+            names.add(publicName);
+    }
+    return names;
+}

package/build/descriptor.d.ts

@@ -9,3 +9,11 @@ export type IDescriptor = {
 };
 export declare function el(type: IDescriptorType, props?: IDescriptorProps, children?: IDescriptorChild[], key?: string): IDescriptor;
 export declare function txt(props?: IDescriptorProps, children?: IDescriptorChild[]): IDescriptor;
+export type IDescriptorShapeGuard = {
+    error(detail: string): Error;
+    assertType(expected: IDescriptorType, actual: IDescriptorType): void;
+    assertChildCount(expected: number, actual: number): void;
+    asText(child: IDescriptorChild): string;
+    asElement(child: IDescriptorChild): IDescriptor;
+};
+export declare function createDescriptorShapeGuard(bridge: string): IDescriptorShapeGuard;

package/build/descriptor.js

@@ -13,3 +13,30 @@ export function el(type, props = {}, children = [], key) {
 export function txt(props = {}, children = []) {
     return { type: 'symbiote-text', props, children };
 }
+// `bridge` names the caller (`descriptorToSolid`, `descriptorToSvelte`) so a device log says which
+// one tripped without a stack to read.
+export function createDescriptorShapeGuard(bridge) {
+    const error = (detail) => new Error(`${bridge}: Descriptor shape changed between renders (${detail}) — a render-*.ts fn must ` +
+        `produce a CONSTANT tree shape; only prop values may vary between calls.`);
+    return {
+        error,
+        assertType(expected, actual) {
+            if (expected !== actual)
+                throw error(`${expected} -> ${actual}`);
+        },
+        assertChildCount(expected, actual) {
+            if (expected !== actual)
+                throw error(`child count ${expected} -> ${actual}`);
+        },
+        asText(child) {
+            if (typeof child !== 'string')
+                throw error(`text -> ${child.type}`);
+            return child;
+        },
+        asElement(child) {
+            if (typeof child === 'string')
+                throw error('element -> text');
+            return child;
+        },
+    };
+}

package/build/fold-host-bag.d.ts

@@ -0,0 +1,15 @@
+import { type IFoldOp } from '../host-primitives.cjs';
+export type IHostBag = Record<string, unknown>;
+interface IFoldPlan {
+    readonly aliases: ReadonlyArray<readonly [string, string]>;
+    readonly defaults: ReadonlyArray<readonly [string, IFoldOp]>;
+}
+export declare const FOLD_PLAN_BY_TAG: ReadonlyMap<string, IFoldPlan>;
+/**
+ * Apply a primitive's aliases and defaults to a bag, copy-on-write.
+ *
+ * Never mutates the input: the bag belongs to whoever built it, and a framework may hand the same
+ * object back on a re-render, so writing into it would leak a fold into the author's own state.
+ */
+export declare function foldHostBag(tagName: string, bag: IHostBag): IHostBag;
+export {};

package/build/fold-host-bag.js

@@ -0,0 +1,99 @@
+// The RUNTIME half of `HOST_PRIMITIVES` — RN's prop folds applied to a props bag on its way into
+// the engine, keyed by intrinsic tag.
+//
+// Why it exists at all. A primitive's host node is produced by THREE paths, and the compile-time
+// fold in a lowering transform covers exactly one of them:
+//
+//   lowered `<View>`         the transform folded it     covered by the transform
+//   `<View>` it refused      the wrapper folds it        covered by the wrapper
+//   a hand-authored tag      nobody folds it             covered by NOTHING
+//
+// The third path is not hypothetical: Svelte's `components/button.svelte` writes `<symbiote-text>`
+// directly rather than composing `Text.svelte`, so its title reached Fabric with no
+// `ellipsizeMode` and clipped mid-word where every other adapter ellipsised (2026-08-31). Angular
+// shipped the identical defect from the identical cause, and both fixed it the same way — a seed
+// in the layer every path crosses.
+//
+// Why it is SHARED rather than one copy per adapter: an adapter that lowers has a transform doing
+// this at compile time, an adapter that does not has only this, and a primitive with no wrapper at
+// all (a bare intrinsic tag) has only this everywhere. Three producers of one answer is the shape
+// `<adapters_stay_thin>` exists to stop. Both halves read the same spec, so they cannot drift into
+// two different answers — only into one answer applied twice, which every operation here is
+// idempotent under (`(x ?? 'tail') ?? 'tail'`, `(x !== false) !== false`).
+import { HOST_PRIMITIVES, } from '../host-primitives.cjs';
+const planFor = (primitive) => ({
+    aliases: Object.entries(primitive.aliases),
+    defaults: Object.entries(primitive.defaults),
+});
+// The wrapper's spelling of a tag whose behavior must attach to the LOWERED path only
+// (`component-names/shared.ts`). A suffix rather than a spec field because it cannot go stale: the
+// next primitive to grow a `-managed` twin is covered the day it is named, with no edit here.
+// `managed-tags-fold.test.ts` pins the convention against the platform tables, so a twin named some
+// other way fails rather than silently losing its folds.
+const managedSpellingOf = (tag) => `${tag}-managed`;
+// EVERY spelling a primitive commits under, and the two axes are independent.
+//
+// `intrinsicWhen` lets one primitive commit two different tags (`TextInput` ->
+// `symbiote-text-input` / `…-multiline`). `-managed` is the wrapper's twin of each of those. A map
+// keyed on the lowered spellings alone folds the lowered path and silently skips the component one
+// — which is exactly what shipped: TextInput and Switch committed a raw `id`, a key no ViewConfig
+// declares, so Fabric dropped it and the nativeID was lost on device with nothing red. Found by
+// Svelte's equivalence arm, 2026-09-01, and it is the two paths of ONE adapter disagreeing.
+//
+// Folding a bag the wrapper already folded is a no-op — an alias deletes its source key, so the
+// second pass finds nothing to rename — which is what makes covering both paths from one plan safe.
+function tagsOf(primitive) {
+    const alternate = primitive.intrinsicWhen?.intrinsic;
+    const lowered = alternate === undefined
+        ? [primitive.intrinsic]
+        : [primitive.intrinsic, alternate];
+    return [...lowered, ...lowered.map(managedSpellingOf)];
+}
+export const FOLD_PLAN_BY_TAG = new Map(Object.values(HOST_PRIMITIVES).flatMap(primitive => {
+    const plan = planFor(primitive);
+    return tagsOf(primitive).map((tag) => [tag, plan]);
+}));
+// The runtime twin of a transform's `foldExpression`, which emits these same two operations as
+// SOURCE. `notFalse` is RN's own encoding (`allowFontScaling !== false`): an explicit `undefined`
+// reads as "not set" and only a literal `false` opts out, which is why it is not a `??`.
+function fold(op, authored) {
+    return op.op === 'notFalse' ? authored !== false : (authored ?? op.value);
+}
+/**
+ * Apply a primitive's aliases and defaults to a bag, copy-on-write.
+ *
+ * Never mutates the input: the bag belongs to whoever built it, and a framework may hand the same
+ * object back on a re-render, so writing into it would leak a fold into the author's own state.
+ */
+export function foldHostBag(tagName, bag) {
+    const plan = FOLD_PLAN_BY_TAG.get(tagName);
+    if (plan === undefined)
+        return bag;
+    let next = bag;
+    for (const [from, to] of plan.aliases) {
+        if (!(from in next))
+            continue;
+        if (next === bag)
+            next = { ...bag };
+        // RN gives the alias unconditional priority when both are set (View.js:77-79,
+        // `processedProps.nativeID = id`), and the raw key must not survive — no ViewConfig declares
+        // `id`, so Fabric would drop it silently.
+        next[to] = next[from];
+        delete next[from];
+    }
+    // Seeded whether or not the key was authored: a default that only applies to a key already
+    // present is not a default.
+    //
+    // A bag a transform already folded takes the `continue` on every key and never reaches the copy —
+    // which is what keeps the compile-time fold worth having once this one exists. It is no longer
+    // the mechanism, but it does keep the hot path allocation-free.
+    for (const [key, op] of plan.defaults) {
+        const folded = fold(op, next[key]);
+        if (key in next && Object.is(next[key], folded))
+            continue;
+        if (next === bag)
+            next = { ...bag };
+        next[key] = folded;
+    }
+    return next;
+}