@symbiote-native/engine 0.3.0 → 0.5.0

package/README.md

@@ -97,8 +97,14 @@ before a tag is guaranteed to exist.
 - **Runtime modules**, framework-agnostic, re-exported by every adapter: `Platform`,
   `StyleSheet` (+ `computeHairlineWidth`), `Dimensions`, `PixelRatio`, `Appearance`, `AppState`,
   `Keyboard`, `AccessibilityInfo`, `BackHandler`, `PermissionsAndroid`, `LayoutAnimation`,
-  `InteractionManager`, `PanResponder`, and the imperative modules `Alert`, `Share`,
+  `InteractionManager`, `PanResponder`, `StatusBar`, and the imperative modules `Alert`, `Share`,
   `ActionSheetIOS`, `Linking`, `Vibration`, `ToastAndroid`, `Settings`, `I18nManager`.
+- **Host behaviors** (`registerHostBehavior` / `IHostBehavior` / `hasHostBehaviors` /
+  `clearHostBehaviors` / `appListenerFor` / `setBehaviorListener` / `requestCommitFor`) — the
+  registry that lets a primitive's state machine live directly on the engine node instead of
+  inside a framework component, so a `Pressable`/`Switch`/`TextInput`/`Image` can compile to a
+  bare intrinsic tag ("host-primitive lowering"). `@symbiote-native/components` registers its
+  behaviors against this seam; the engine never imports them back.
 - **`Animated`** — both the JS and native driver (`timing` / `spring` / `decay` / `loop` /
   `ValueXY` / tracking / `diffClamp` / `Easing`), including the native-event attachment path
   (`attachNativeEvent`, `AnimatedEvent`).

package/build/accessibility-props.d.ts

@@ -0,0 +1,20 @@
+export declare const ARIA_ALIAS_KEYS: readonly string[];
+/**
+ * Whether one key is an alias this fold consumes. `startsWith` rather than a Set lookup: this runs
+ * on `setProp`, the hottest write path in the engine (32 001 writes on one benchmark create), and
+ * it is guarded by the node's sticky flag so it is reached at most once per node per key. The
+ * `role` comparison comes first because it is the one alias with no prefix.
+ */
+export declare function isAriaAliasKey(key: string): boolean;
+/**
+ * Fold the web-alias `aria-*` / `role` props into RN's canonical `accessibility*` props.
+ *
+ * Returns the input BY IDENTITY when no alias is present — the fast path that keeps this off the
+ * hot path for the ~99% of nodes carrying none, and the property idempotence rests on: pass 1
+ * blanks every alias, so a second pass finds nothing and returns by identity again.
+ *
+ * The alias keys are blanked to `undefined` rather than deleted. That is not laziness: `setProp`
+ * treats an `undefined` write as a delete and `fabricProps` skips undefined, so a blanked alias
+ * cannot reach Fabric, while a `delete` would deoptimise the object's shape on every folded node.
+ */
+export declare function foldAriaProps(props: Record<string, unknown>): Record<string, unknown>;

package/build/accessibility-props.js

@@ -0,0 +1,213 @@
+// RN's `aria-*` / `role` -> `accessibility*` fold, at the layer every path goes through.
+//
+// WHY IT IS HERE AND NOT IN A WRAPPER. It used to run inside each primitive's COMPONENT, which is
+// exactly the layer host-primitive lowering removes. A per-attribute element path cannot do it —
+// `aria-checked` has to be folded against a sibling `accessibilityState` — so the four lowering
+// transforms REFUSED any element carrying `role` or an `aria-*` attribute
+// (`REFUSAL_CATEGORIES.bagFold`). Accessibility props are ordinary in real code, so that refusal
+// cost lowering coverage on every primitive, including the three already lowered. Moving the fold
+// down deletes the refusal instead of teaching four transforms a bag operation they cannot express.
+//
+// IT IS A MOVE, NOT A REWRITE, AND THAT IS DELIBERATE. The function carries TWO CONTRADICTORY
+// PRECEDENCE RULES: for the scalars an explicit `accessibility*` WINS and the alias only fills a
+// hole (`if (next.X === undefined)`), while INSIDE the `accessibilityState` / `accessibilityValue`
+// composites the ALIAS wins per field (`ariaBusy ?? existing?.busy`). Both mirror RN's View.js.
+// Anyone "cleaning this up" collapses them into one rule, and every component test stays green
+// while real accessibility silently changes. `core/components/src/accessibility-props.test.ts`
+// pins both directions; read it before touching the branches below.
+//
+// Record-level rather than typed, because the engine's caller has a raw `node.props` bag and an
+// interface is not assignable to `Record<string, unknown>` (no index signature). The typed
+// `resolveAccessibilityProps<T>` in `core/components` stays where adapters already import it and
+// delegates here, keeping its own typed gate so the fast path allocates nothing.
+import { dlog } from './debug.js';
+// Copied line for line from the wrapper this replaces. The first copy silently dropped five
+// entries (`button`, `grid`, `link`, `list`, `listitem`) — a role that falls through simply passes
+// unmapped, so `role="listitem"` would have reached Fabric as `listitem` instead of `list` with
+// nothing red anywhere. Diff this against RN's View.js rather than reading it for plausibility.
+const ROLE_TO_ACCESSIBILITY_ROLE = {
+    alert: 'alert',
+    button: 'button',
+    checkbox: 'checkbox',
+    combobox: 'combobox',
+    grid: 'grid',
+    heading: 'header',
+    img: 'image',
+    link: 'link',
+    list: 'list',
+    listitem: 'list',
+    menu: 'menu',
+    menubar: 'menubar',
+    menuitem: 'menuitem',
+    none: 'none',
+    presentation: 'none',
+    progressbar: 'progressbar',
+    radio: 'radio',
+    radiogroup: 'radiogroup',
+    scrollbar: 'scrollbar',
+    searchbox: 'search',
+    slider: 'adjustable',
+    spinbutton: 'spinbutton',
+    summary: 'summary',
+    switch: 'switch',
+    tab: 'tab',
+    tablist: 'tablist',
+    timer: 'timer',
+    toolbar: 'toolbar',
+};
+// Exported so a behavior that folds a DIFFERENT node's bag can name them without restating the
+// list. `slotDerived` (host-behavior.ts) takes prop NAMES, so a primitive whose payload derives
+// from an owner's aria props has to enumerate them — and a second hand-written copy is exactly what
+// `.claude/rules/adapter-parity-audit.md` records going stale one member at a time.
+export const ARIA_ALIAS_KEYS = [
+    'role',
+    'aria-label',
+    'aria-labelledby',
+    'aria-live',
+    'aria-hidden',
+    'aria-busy',
+    'aria-checked',
+    'aria-disabled',
+    'aria-expanded',
+    'aria-selected',
+    'aria-modal',
+    'aria-valuemax',
+    'aria-valuemin',
+    'aria-valuenow',
+    'aria-valuetext',
+];
+// An indexed loop rather than `.some(key => …)`: the callback captures `props`, so a closure is
+// allocated per call, and this is the gate on a path that runs once per node.
+function hasAnyAriaKey(props) {
+    for (let index = 0; index < ARIA_ALIAS_KEYS.length; index += 1) {
+        if (props[ARIA_ALIAS_KEYS[index]] !== undefined)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether one key is an alias this fold consumes. `startsWith` rather than a Set lookup: this runs
+ * on `setProp`, the hottest write path in the engine (32 001 writes on one benchmark create), and
+ * it is guarded by the node's sticky flag so it is reached at most once per node per key. The
+ * `role` comparison comes first because it is the one alias with no prefix.
+ */
+export function isAriaAliasKey(key) {
+    return key === 'role' || key.startsWith('aria-');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function fieldOf(source, field) {
+    return isRecord(source) ? source[field] : undefined;
+}
+/**
+ * Fold the web-alias `aria-*` / `role` props into RN's canonical `accessibility*` props.
+ *
+ * Returns the input BY IDENTITY when no alias is present — the fast path that keeps this off the
+ * hot path for the ~99% of nodes carrying none, and the property idempotence rests on: pass 1
+ * blanks every alias, so a second pass finds nothing and returns by identity again.
+ *
+ * The alias keys are blanked to `undefined` rather than deleted. That is not laziness: `setProp`
+ * treats an `undefined` write as a delete and `fabricProps` skips undefined, so a blanked alias
+ * cannot reach Fabric, while a `delete` would deoptimise the object's shape on every folded node.
+ */
+export function foldAriaProps(props) {
+    if (!hasAnyAriaKey(props))
+        return props;
+    const bag = { ...props };
+    dlog('foldAriaProps: folding aria/role aliases into accessibility* props');
+    const role = bag.role;
+    const ariaLabel = bag['aria-label'];
+    const ariaLabelledBy = bag['aria-labelledby'];
+    const ariaLive = bag['aria-live'];
+    const ariaHidden = bag['aria-hidden'];
+    const ariaBusy = bag['aria-busy'];
+    const ariaChecked = bag['aria-checked'];
+    const ariaDisabled = bag['aria-disabled'];
+    const ariaExpanded = bag['aria-expanded'];
+    const ariaSelected = bag['aria-selected'];
+    const ariaModal = bag['aria-modal'];
+    const ariaValueMax = bag['aria-valuemax'];
+    const ariaValueMin = bag['aria-valuemin'];
+    const ariaValueNow = bag['aria-valuenow'];
+    const ariaValueText = bag['aria-valuetext'];
+    for (let index = 0; index < ARIA_ALIAS_KEYS.length; index += 1) {
+        bag[ARIA_ALIAS_KEYS[index]] = undefined;
+    }
+    // RULE ONE, for every scalar: the explicit prop WINS, the alias only fills a hole.
+    if (typeof ariaLabelledBy === 'string' &&
+        bag.accessibilityLabelledBy === undefined) {
+        bag.accessibilityLabelledBy = ariaLabelledBy.split(/\s*,\s*/g);
+    }
+    if (ariaLabel !== undefined && bag.accessibilityLabel === undefined) {
+        bag.accessibilityLabel = ariaLabel;
+    }
+    if (ariaLive !== undefined && bag.accessibilityLiveRegion === undefined) {
+        bag.accessibilityLiveRegion = ariaLive === 'off' ? 'none' : ariaLive;
+    }
+    // One input, TWO outputs, and the second is conditional on the VALUE rather than on presence.
+    if (ariaHidden !== undefined) {
+        if (bag.accessibilityElementsHidden === undefined) {
+            bag.accessibilityElementsHidden = ariaHidden;
+        }
+        if (ariaHidden === true && bag.importantForAccessibility === undefined) {
+            bag.importantForAccessibility = 'no-hide-descendants';
+        }
+    }
+    if (ariaModal !== undefined && bag.accessibilityViewIsModal === undefined) {
+        bag.accessibilityViewIsModal = ariaModal;
+    }
+    if (typeof role === 'string' && bag.accessibilityRole === undefined) {
+        bag.accessibilityRole = ROLE_TO_ACCESSIBILITY_ROLE[role] ?? role;
+    }
+    // RULE TWO, INSIDE the composites: the polarity INVERTS and the ALIAS wins per field. Read from
+    // the ORIGINAL props, not from `bag` — the loop above has already blanked the aliases there.
+    //
+    // UPSTREAM-BUG(react-native): View.js:96 is `checked: ariaChecked ?? accessibilityState?.checked`
+    // — NO type coercion. A template writes `aria-checked="true"` as a STRING in every framework we
+    // support, so `accessibilityState.checked` reaches native as `'true'` where the native side
+    // declares `boolean | 'mixed'`. Ported verbatim for parity; do NOT add a cast without recording
+    // a deliberate divergence. Found by the Svelte session 2026-08-31 and pinned as an ASSERTION in
+    // `adapters/svelte/src/aria-fold-parity.test.ts`, so a future decision to coerce shows up as a
+    // failing test at the point the decision was made rather than as a silent behaviour change.
+    //
+    // A SECOND, SMALLER DIVERGENCE, and this one is ours rather than upstream's — it predates the
+    // move down and is kept only because changing it here would be an undeclared behaviour change:
+    // upstream gates the composite on `!= null` (View.js:87-92) and this gates on `!== undefined`.
+    // So an explicit `aria-busy={null}` builds an all-undefined `accessibilityState` here and builds
+    // nothing upstream. The VALUES agree either way — `??` treats null and undefined alike — so only
+    // the composite's existence differs.
+    //
+    // The composite is REPLACED by a fresh literal listing exactly the known fields, so an unknown
+    // field riding on the incoming object is dropped. Faithful to RN and pinned by a test; it is the
+    // shape of bug that only shows for whoever passes a field RN adds later.
+    const existingState = fieldOf(props, 'accessibilityState');
+    if (existingState !== undefined ||
+        ariaBusy !== undefined ||
+        ariaChecked !== undefined ||
+        ariaDisabled !== undefined ||
+        ariaExpanded !== undefined ||
+        ariaSelected !== undefined) {
+        bag.accessibilityState = {
+            busy: ariaBusy ?? fieldOf(existingState, 'busy'),
+            checked: ariaChecked ?? fieldOf(existingState, 'checked'),
+            disabled: ariaDisabled ?? fieldOf(existingState, 'disabled'),
+            expanded: ariaExpanded ?? fieldOf(existingState, 'expanded'),
+            selected: ariaSelected ?? fieldOf(existingState, 'selected'),
+        };
+    }
+    const existingValue = fieldOf(props, 'accessibilityValue');
+    if (existingValue !== undefined ||
+        ariaValueMax !== undefined ||
+        ariaValueMin !== undefined ||
+        ariaValueNow !== undefined ||
+        ariaValueText !== undefined) {
+        bag.accessibilityValue = {
+            max: ariaValueMax ?? fieldOf(existingValue, 'max'),
+            min: ariaValueMin ?? fieldOf(existingValue, 'min'),
+            now: ariaValueNow ?? fieldOf(existingValue, 'now'),
+            text: ariaValueText ?? fieldOf(existingValue, 'text'),
+        };
+    }
+    return bag;
+}

package/build/animated/graph.d.ts

@@ -3,12 +3,14 @@ import { type IInterpolationConfig } from './interpolation';
 export type IValueListener = (state: {
     value: number | string;
 }) => void;
+export declare function hasAnimatedNodes(): boolean;
 export declare class AnimatedNode {
     private readonly listeners;
     private suspendCallbacks;
     protected isNative: boolean;
     private nativeTag;
     private platformConfig;
+    constructor();
     __attach(): void;
     __detach(): void;
     __isNative(): boolean;

package/build/animated/graph.js

@@ -20,6 +20,17 @@ let nextListenerId = 1;
 // channel. RN tolerates the per-channel flushes and relies on a downstream commit-
 // coalescing layer; symbiote has none here, so it coalesces at the source.
 let flushSuspendDepth = 0;
+// Has this process ever constructed an Animated node at all?
+//
+// `routeProp` has to answer "does this prop hold an animated value" on EVERY prop write - 32 001
+// of them on one benchmark create - and for an app that animates nothing the only cheap answer is
+// that no AnimatedNode exists to find. One boolean read, the discipline `hasHostBehaviors` and
+// `isDebug` already set. Set in the base constructor so every node type raises it, including the
+// operators and interpolations an app never names directly.
+let anyAnimatedNode = false;
+export function hasAnimatedNodes() {
+    return anyAnimatedNode;
+}
 export class AnimatedNode {
     listeners = new Map();
     // While > 0, this node's own __callListeners is a no-op. A composite setter
@@ -39,6 +50,9 @@ export class AnimatedNode {
     // native config at creation (__getNativeTag). Optional: undefined when no caller
     // supplied one, matching today's behavior.
     platformConfig;
+    constructor() {
+        anyAnimatedNode = true;
+    }
     __attach() { }
     __detach() {
         this.removeAllListeners();

package/build/animated/host-binding.d.ts

@@ -0,0 +1,39 @@
+import { type ISymbioteNode } from '../node';
+export declare function hasAnimatedBindings(): boolean;
+/**
+ * Give a node a behavior-owned animated style layer, or drop it by passing `undefined`.
+ *
+ * The seam a lowered `TouchableOpacity` needs: RN runs its press fade from an `Animated.View` whose
+ * style is `[props.style, {opacity: anim}]` (TouchableOpacity.js:302), and a tag has no such
+ * wrapper. The layer is bound to the leaf, never folded into `node.props.style` — so the behavior
+ * can still read the AUTHOR's resting opacity back without seeing its own fade.
+ */
+export declare function setAnimatedBehaviorStyle(node: ISymbioteNode, style: unknown): void;
+/**
+ * Resolve an animated value in a prop, returning what should be published for it.
+ *
+ * Returns its input by IDENTITY when the value holds nothing animated, so `routeProp` can call it
+ * unconditionally and every downstream branch — class, style, activeStyle, `on*`, `setProp` —
+ * keeps seeing a plain value and needs no change.
+ */
+export declare function bindAnimatedValue(node: ISymbioteNode, key: string, value: unknown): unknown;
+/**
+ * Bind a native-driven `Animated.event` handler written as an `on*` prop. A no-op for every other
+ * handler, so `routeProp` calls it for any `on*` name behind the same one-boolean gate.
+ */
+export declare function bindAnimatedEvent(node: ISymbioteNode, propName: string, handler: unknown): void;
+/**
+ * Release a node's animated subscription. Called per node from the commit sweep, which is where a
+ * genuine removal is first distinguishable from a framework spelling a move as remove-then-insert
+ * (host-behavior.ts, `markDetachCandidate`).
+ */
+export declare function detachAnimatedProps(node: ISymbioteNode): void;
+/**
+ * Re-arm a subtree the sweep tore down and the framework put back — Svelte parks LIVE nodes
+ * offscreen across commits and returns them with their props unwritten, so without this the
+ * animation stops with nothing red anywhere.
+ *
+ * A WeakSet miss and no walk at all for every node in a freshly built tree, which is the path that
+ * runs ~9 000 times per benchmark create.
+ */
+export declare function reattachAnimatedProps(node: ISymbioteNode): void;

package/build/animated/host-binding.js

@@ -0,0 +1,263 @@
+// An AnimatedNode written straight into a prop of a HOST NODE — the engine half of what
+// `createAnimatedComponent` used to broker.
+//
+// WHY IT EXISTS. `Animated.View` is `createAnimatedComponent(View)`: a wrapper whose whole job is
+// to keep an `AnimatedProps` leaf alive beside a base COMPONENT. Once a primitive is a bare
+// intrinsic tag there is no component to wrap, so every `Animated.*` built that way loses its
+// base. The two halves the wrapper actually brokered — the value graph and the node's Fabric view
+// tag — are both already engine-side (`animated/props.ts`, `commit.ts`'s `getNativeTag`), so the
+// wrapper was standing between two things that live in the same room. An app writes
+//
+//     <view style={{ opacity: someAnimatedValue }} />
+//
+// and `routeProp` resolves it here: publish the current value so the first paint is concrete,
+// subscribe the leaf so every frame lands as one targeted `setNativeProps` commit, and tear the
+// subscription down when the node leaves the tree for good.
+//
+// THE PRECEDENT IT FOLLOWS is `routeProp`'s own `isStyleCallback` branch: a `style` function is
+// already a value the engine INTERPRETS rather than forwards, resolved at both values of
+// `pressed`. An AnimatedNode is the same shape of problem one step further — the resolution is
+// continuous rather than two-valued, so it needs a subscription instead of a second call.
+//
+// THE CYCLE IS DELIBERATE, and it is the one `node.ts` already carries with `commit.ts`: node.ts
+// imports this module for `routeProp`, and this module reaches back into node.ts for `setProp`.
+// Neither side touches the other at module-evaluation time — only inside a function body — so
+// every loader resolves it. The alternative, a
+// `registerAnimatedResolver` installed from elsewhere, is exactly the load-time-side-effect shape
+// Metro's `inlineRequires` drops in release builds (CLAUDE.md; and see `graph.ts`'s note on why
+// `AnimatedInterpolation` lives next to its base class).
+import { AnimatedNode } from './graph.js';
+import { AnimatedStyle } from './style.js';
+import { attachNativeEventHandler } from './event.js';
+import { createAnimatedLeafLifecycle, } from './leaf-lifecycle.js';
+import { setProp } from '../node.js';
+const bindings = new WeakMap();
+// Nodes the commit sweep tore down, whether or not they carried a binding — the twin of
+// host-behavior.ts's `tornDown`, and marked for every node for the same reason: the node a
+// framework re-inserts is usually a plain container whose DESCENDANT holds the subscription.
+const parked = new WeakSet();
+// The gate, matching `hasHostBehaviors`. `removeChild` and the two inserts read it on every call,
+// so an app that animates nothing must pay one boolean read rather than a WeakMap probe.
+let anyBinding = false;
+export function hasAnimatedBindings() {
+    return anyBinding;
+}
+// Only what `AnimatedProps` can actually bind: a prop that IS a node, or a `style` holding one.
+// Deliberately NOT a general deep walk — an arbitrary prop bag can hold an app object with a
+// cycle in it, and a walk that never terminates would be a hang on the engine's hottest path.
+function styleHoldsAnimated(style) {
+    if (Array.isArray(style))
+        return style.some(styleHoldsAnimated);
+    if (typeof style !== 'object' || style === null)
+        return false;
+    for (const key of Object.keys(style)) {
+        const entry = Reflect.get(style, key);
+        if (entry instanceof AnimatedNode)
+            return true;
+        // `transform: [{ translateX: node }]` — the one nesting `AnimatedTransform` reads.
+        if (key !== 'transform' || !Array.isArray(entry))
+            continue;
+        for (const item of entry) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            for (const inner of Object.keys(item)) {
+                if (Reflect.get(item, inner) instanceof AnimatedNode)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// The value to PUBLISH now, or undefined when there is nothing animated after all. A false
+// positive from the scan above lands here and is turned away, so the raw value still reaches
+// `setProp` unchanged and nothing new can break.
+function rasterize(key, value) {
+    if (value instanceof AnimatedNode)
+        return value.__getValue();
+    if (key !== 'style')
+        return undefined;
+    return AnimatedStyle.from(value)?.__getValue();
+}
+function reconcile(node, binding) {
+    parked.delete(node);
+    if (Object.keys(binding.raw).length > 0) {
+        // `wantsNative: false` — nothing here forces the native driver. A leaf becomes native by
+        // CASCADE, from the value it is a child of (`AnimatedWithChildren.__addChild` /
+        // `__connectNativeChildren`), which is what makes `useNativeDriver` on the animation the only
+        // thing that decides. The wrapper's own `wantsNative` was keyed on
+        // `passthroughAnimatedPropExplicitValues`, a wrapper-ism with no meaning on a bare tag.
+        //
+        // And NO `scheduleNativeBind`, though a prop write always precedes the node's first commit:
+        // nothing the bind does needs a Fabric tag on the spot. `setNativeView` only stores the
+        // target, `connectToView` defers itself through `pendingViewConnects` + the post-commit hook
+        // (`props.ts`), and `attachNativeEventHandler` wraps its own `whenCommitted`. A deferral here
+        // would be unfalsifiable code, so it is not here.
+        binding.lifecycle.reconcile(binding.raw, node, false);
+        return;
+    }
+    binding.lifecycle.teardown();
+    bindings.delete(node);
+    // Fabric may flatten a view again once nothing animates it.
+    setProp(node, 'collapsable', undefined);
+}
+// A style layer a HOST BEHAVIOR owns on its own node, composed OVER the app's style.
+//
+// WHY IT IS NOT AN ORDINARY PROP. TouchableOpacity's press fade is an AnimatedValue that has to
+// beat whatever `opacity` the caller's own style asks for, and `fabricProps` hoists the style slot
+// AFTER every plain prop — so a top-level `opacity` loses to `style={{opacity: 0.6}}`, silently and
+// only for the styled call sites. The layer has to sit INSIDE the style, above the author's.
+//
+// AND IT CANNOT SHARE `raw.style` WITH THE APP. The leaf keys its bound props by name, so the app's
+// next plain `style` write would find `raw.style` holding nothing animated and tear the behavior's
+// binding down. Composing here means that write still sees an animated style — ours — and
+// re-registers the pair instead.
+const behaviorStyles = new WeakMap();
+// The gate, matching `anyBinding`: one boolean read on the style branch of every prop write in an
+// app whose behaviors own no animated layer, which is nearly all of them.
+let anyBehaviorStyle = false;
+function withBehaviorStyle(node, style) {
+    if (!anyBehaviorStyle)
+        return style;
+    const layer = behaviorStyles.get(node);
+    return layer === undefined ? style : [style, layer];
+}
+/**
+ * Give a node a behavior-owned animated style layer, or drop it by passing `undefined`.
+ *
+ * The seam a lowered `TouchableOpacity` needs: RN runs its press fade from an `Animated.View` whose
+ * style is `[props.style, {opacity: anim}]` (TouchableOpacity.js:302), and a tag has no such
+ * wrapper. The layer is bound to the leaf, never folded into `node.props.style` — so the behavior
+ * can still read the AUTHOR's resting opacity back without seeing its own fade.
+ */
+export function setAnimatedBehaviorStyle(node, style) {
+    if (style === undefined)
+        behaviorStyles.delete(node);
+    else {
+        behaviorStyles.set(node, style);
+        anyBehaviorStyle = true;
+    }
+    // Re-register against the style standing right now, so the pair the leaf holds is always
+    // (author, layer) whichever of the two moved last.
+    bindAnimatedValue(node, 'style', node.props.style);
+}
+/**
+ * Resolve an animated value in a prop, returning what should be published for it.
+ *
+ * Returns its input by IDENTITY when the value holds nothing animated, so `routeProp` can call it
+ * unconditionally and every downstream branch — class, style, activeStyle, `on*`, `setProp` —
+ * keeps seeing a plain value and needs no change.
+ */
+export function bindAnimatedValue(node, key, value) {
+    const existing = bindings.get(node);
+    const bound = key === 'style' ? withBehaviorStyle(node, value) : value;
+    const isAnimated = bound instanceof AnimatedNode ||
+        (key === 'style' && styleHoldsAnimated(bound));
+    if (!isAnimated) {
+        // A prop that USED to be animated and no longer is: drop it, or the leaf keeps writing a
+        // stale value over whatever the app just wrote.
+        if (existing !== undefined && Object.hasOwn(existing.raw, key)) {
+            delete existing.raw[key];
+            reconcile(node, existing);
+        }
+        return value;
+    }
+    const binding = existing ?? {
+        raw: {},
+        lifecycle: createAnimatedLeafLifecycle('host'),
+    };
+    if (existing === undefined) {
+        bindings.set(node, binding);
+        anyBinding = true;
+    }
+    binding.raw[key] = bound;
+    // Fabric flattens a view whose props do not require one, and a flattened view has no tag for
+    // the native driver to bind to. RN forces the same flag from `reduceAnimatedProps`.
+    setProp(node, 'collapsable', false);
+    reconcile(node, binding);
+    // The AUTHOR's value, rasterized — never the composed one. A behavior's layer reaches Fabric
+    // through the per-frame `setNativeProps` merge, and folding it in here would publish the fade's
+    // own output as the node's declarative style, which the behavior then reads back as resting.
+    const own = rasterize(key, value);
+    return own === undefined ? value : own;
+}
+const eventBindings = new WeakMap();
+/**
+ * Bind a native-driven `Animated.event` handler written as an `on*` prop. A no-op for every other
+ * handler, so `routeProp` calls it for any `on*` name behind the same one-boolean gate.
+ */
+export function bindAnimatedEvent(node, propName, handler) {
+    const bound = eventBindings.get(node);
+    if (bound !== undefined) {
+        const current = bound.get(propName);
+        if (current !== undefined) {
+            // A framework hands a fresh closure most renders; only a different handler is worth a
+            // detach/attach round trip through the native module.
+            if (current.handler === handler)
+                return;
+            current.attachment.detach();
+            bound.delete(propName);
+        }
+    }
+    // Returns undefined unless this really is a native-driven AnimatedEvent, and defers itself
+    // through `whenCommitted` until the node has a Fabric tag — no second deferral invented here.
+    const attachment = attachNativeEventHandler(node, propName, handler);
+    if (attachment === undefined)
+        return;
+    const map = bound ?? new Map();
+    if (bound === undefined)
+        eventBindings.set(node, map);
+    map.set(propName, { handler, attachment });
+    // The same gate the props half raises: teardown and re-arm are both behind it.
+    anyBinding = true;
+}
+// Re-attach against the tag the node has NOW. The old handles are spent — each detached against
+// the tag it attached with, which is the point — so re-arming is a fresh attach, not a resume, and
+// it goes back through `bindAnimatedEvent` rather than growing a second attach path. Only a node
+// the sweep parked reaches here, and parking always detaches, so clearing without detaching first
+// drops nothing live.
+function reattachAnimatedEvents(node) {
+    const bound = eventBindings.get(node);
+    if (bound === undefined)
+        return;
+    const spent = [...bound];
+    bound.clear();
+    for (const [propName, binding] of spent)
+        bindAnimatedEvent(node, propName, binding.handler);
+}
+/**
+ * Release a node's animated subscription. Called per node from the commit sweep, which is where a
+ * genuine removal is first distinguishable from a framework spelling a move as remove-then-insert
+ * (host-behavior.ts, `markDetachCandidate`).
+ */
+export function detachAnimatedProps(node) {
+    // The sweep runs for host behaviors too, so an app that animates nothing must not pay a WeakSet
+    // insert per removed node to learn it has nothing to release.
+    if (!anyBinding)
+        return;
+    parked.add(node);
+    bindings.get(node)?.lifecycle.teardown();
+    const bound = eventBindings.get(node);
+    if (bound === undefined)
+        return;
+    for (const binding of bound.values())
+        binding.attachment.detach();
+}
+/**
+ * Re-arm a subtree the sweep tore down and the framework put back — Svelte parks LIVE nodes
+ * offscreen across commits and returns them with their props unwritten, so without this the
+ * animation stops with nothing red anywhere.
+ *
+ * A WeakSet miss and no walk at all for every node in a freshly built tree, which is the path that
+ * runs ~9 000 times per benchmark create.
+ */
+export function reattachAnimatedProps(node) {
+    if (!parked.has(node))
+        return;
+    parked.delete(node);
+    const binding = bindings.get(node);
+    if (binding !== undefined)
+        reconcile(node, binding);
+    reattachAnimatedEvents(node);
+    for (const child of node.children)
+        reattachAnimatedProps(child);
+}