@symbiote-native/angular 0.3.3 → 0.5.0

package/src/components/pressable/index.ts

@@ -14,9 +14,12 @@ import {
   createPressHandlers,
   createPressRuntime,
   DEFAULT_DELAY_LONG_PRESS_MS,
+  isTerminationAllowed,
   resolveAccessibilityProps,
   resolveDisabledAccessibilityState,
   rippleProps,
+  shouldClaimResponder,
+  shouldSuppressPress,
   type IAccessibilityProps,
   type IAccessibilityStateValue,
   type IAriaProps,
@@ -43,7 +46,7 @@ export type { IPressState, IPressableAndroidRippleConfig } from '@symbiote-nativ
 
 // The full logical Pressable surface, callback-shaped press/hover events included. Touchable* and
 // TouchableNativeFeedback still take their OWN onPress/onPressIn/... as @Input() callbacks (that is
-// a separate, not-yet-converted decision) and derive their public prop types from this — so it keeps
+// a separate, not-yet-converted decision) and derive their public prop types from this - so it keeps
 // the callback fields even though the Pressable component below no longer implements them directly.
 export interface IAngularPressableProps extends IAccessibilityProps, IAriaProps {
   onPress?: IPressHandler;
@@ -76,7 +79,7 @@ export interface IAngularPressableProps extends IAccessibilityProps, IAriaProps
 
 // What the Pressable component itself takes as plain @Input()s: the full surface minus the press/
 // hover events and the four accessibility callbacks, all of which it exposes as real @Output()
-// EventEmitters instead (see the class below) — the one place in the family where the
+// EventEmitters instead (see the class below) - the one place in the family where the
 // callback-vs-EventEmitter tradeoff is actually fixed.
 export type IAngularPressableInputs = Omit<
   IAngularPressableProps,
@@ -131,7 +134,7 @@ function asSymbioteEvent(event: unknown): ISymbioteEvent | undefined {
 export class Pressable implements IAngularPressableInputs {
   // The press/hover lifecycle as real Angular events: `(press)="onTap($event)"`, not
   // `[onPress]="onTap"`. createPressHandlers still wants plain IPressHandler callbacks, so
-  // emitterHandler() below adapts each EventEmitter into one — only while something is actually
+  // emitterHandler() below adapts each EventEmitter into one - only while something is actually
   // subscribed (`.observed`), so an unbound onLongPress still skips arming the timer, exactly as
   // the old @Input()-absent case did.
   @Output() readonly press = new EventEmitter<ISymbioteEvent>();
@@ -223,8 +226,8 @@ export class Pressable implements IAngularPressableInputs {
   };
 
   private readonly changeDetector = inject(ChangeDetectorRef);
-  // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
-  // onto (see anchorHostStyle's doc comment) — NOT `hostElement` above, which targets the real
+  // This component's OWN host - the non-painting anchor `class="..."` at the use site resolves
+  // onto (see anchorHostStyle's doc comment) - NOT `hostElement` above, which targets the real
   // inner `symbiote-view` one level down.
   private readonly elementRef = inject(ElementRef);
 
@@ -275,8 +278,7 @@ export class Pressable implements IAngularPressableInputs {
     return this.android_ripple === undefined ? undefined : rippleProps(this.android_ripple);
   }
 
-  // Assembles the SAME resolved values the template used to bind one-by-one into a single
-  // flat bag for `[symbioteHostProps]` (Renderer2.setProperty per key) — see primitives/shared.ts.
+  // Flat bag for `[symbioteHostProps]` (Renderer2.setProperty per key) - see primitives/shared.ts.
   get hostProps(): Record<string, unknown> {
     return {
       testID: this.testID,
@@ -298,34 +300,34 @@ export class Pressable implements IAngularPressableInputs {
 
   handlePressIn(event: unknown): void {
     const symbioteEvent = asSymbioteEvent(event);
-    if (this.disabled === true || symbioteEvent === undefined) return;
+    if (shouldSuppressPress(this.disabled) || symbioteEvent === undefined) return;
     this.handlers.handlePressIn(symbioteEvent);
   }
 
   handlePressOut(event: unknown): void {
     const symbioteEvent = asSymbioteEvent(event);
-    if (this.disabled === true || symbioteEvent === undefined) return;
+    if (shouldSuppressPress(this.disabled) || symbioteEvent === undefined) return;
     this.handlers.handlePressOut(symbioteEvent);
   }
 
   handlePress(event: unknown): void {
     const symbioteEvent = asSymbioteEvent(event);
-    if (this.disabled === true || symbioteEvent === undefined) return;
+    if (shouldSuppressPress(this.disabled) || symbioteEvent === undefined) return;
     this.handlers.handlePress(symbioteEvent);
   }
 
   handleResponderMove(event: unknown): void {
     const symbioteEvent = asSymbioteEvent(event);
-    if (this.disabled === true || symbioteEvent === undefined) return;
+    if (shouldSuppressPress(this.disabled) || symbioteEvent === undefined) return;
     this.handlers.handleResponderMove(symbioteEvent);
   }
 
   claimResponder(): boolean {
-    return this.disabled !== true;
+    return shouldClaimResponder(this.disabled);
   }
 
   allowTermination(): boolean {
-    return this.cancelable !== false;
+    return isTerminationAllowed(this.cancelable);
   }
 
   emit(emitter: EventEmitter<ISymbioteEvent>, event: unknown): void {
@@ -342,8 +344,8 @@ export class Pressable implements IAngularPressableInputs {
   }
 
   // Wraps an @Output() as an IPressHandler only while it has a subscriber, so an unbound
-  // (longPress) still skips arming the timer — the same "undefined means nobody cares" contract
-  // createPressHandlers had with the old @Input() callbacks.
+  // (longPress) still skips arming the timer, matching createPressHandlers' "undefined means
+  // nobody cares" contract.
   private emitterHandler(emitter: EventEmitter<ISymbioteEvent>): IPressHandler | undefined {
     return emitter.observed ? event => emitter.emit(event) : undefined;
   }

package/src/components/{refresh-control.ts → refresh-control/index.ts}

@@ -36,23 +36,18 @@ import {
 import {
   dispatchViewCommand,
   dlog,
+  isSymbioteEvent,
   isSymbioteNode,
   type IStyleProp,
   type ISymbioteEvent,
   type IViewStyle,
 } from '@symbiote-native/engine';
-import { anchorHostStyle, RefreshControlHost, SymbioteHostPropsDirective } from '../primitives';
+import { anchorHostStyle, RefreshControlHost, SymbioteHostPropsDirective } from '../../primitives';
 
 // Record<string, unknown> already tolerates `style` holding the [anchorHostStyle, this.style]
 // array anchorHostStyle's merge produces (see hostProps below) — no widening needed.
 type IHostProps = Record<string, unknown>;
 
-// Angular infers an `(event)` binding's $event as the DOM Event for a custom-schema element,
-// so each handler enters as `unknown` and is narrowed here before reaching a typed callback.
-function isSymbioteEvent(value: unknown): value is ISymbioteEvent {
-  return typeof value === 'object' && value !== null && 'nativeEvent' in value;
-}
-
 // Mirrors React's IRefreshControlProps minus children (Angular takes the Android-wrapped scroll view
 // via <ng-content>), declared per-adapter over the shared accessibility base since the framework-specific
 // children slot keeps it from being fully shared across adapters. Read the React reference for the

package/src/components/{refresh-control.test.ts → refresh-control/refresh-control.test.ts}

@@ -4,8 +4,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { clearGlobalStyles, registerStyles } from '@symbiote-native/engine';
 import { installFabric } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from '../render';
-import { RefreshControl } from './refresh-control';
+import { mount, unmount } from '../../render';
+import { RefreshControl } from './index';
 
 const ROOT_TAG = 914;
 const fabric = installFabric();

package/src/components/{safe-area-view.ts → safe-area-view/index.ts}

@@ -22,14 +22,13 @@ import {
   type IAccessibilityStateValue,
   type IAriaProps,
 } from '@symbiote-native/components';
-import type { IStyleProp, ISymbioteEvent, IViewStyle } from '@symbiote-native/engine';
-import { anchorHostStyle, SafeAreaViewHost, SymbioteHostPropsDirective } from '../primitives';
-
-// Angular infers an `(event)` binding's $event as the DOM Event for a custom-schema element,
-// so each handler enters as `unknown` and is narrowed here before reaching a typed callback.
-function isSymbioteEvent(value: unknown): value is ISymbioteEvent {
-  return typeof value === 'object' && value !== null && 'nativeEvent' in value;
-}
+import {
+  isSymbioteEvent,
+  type IStyleProp,
+  type ISymbioteEvent,
+  type IViewStyle,
+} from '@symbiote-native/engine';
+import { anchorHostStyle, SafeAreaViewHost, SymbioteHostPropsDirective } from '../../primitives';
 
 // Mirrors React's ISafeAreaViewProps minus children (Angular takes children via <ng-content>),
 // declared per-adapter over the shared accessibility base since the framework-specific children

package/src/components/{safe-area-view.test.ts → safe-area-view/safe-area-view.test.ts}

@@ -4,8 +4,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { clearGlobalStyles, registerStyles } from '@symbiote-native/engine';
 import { installFabric } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from '../render';
-import { SafeAreaView } from './safe-area-view';
+import { mount, unmount } from '../../render';
+import { SafeAreaView } from './index';
 
 const ROOT_TAG = 910;
 const fabric = installFabric();

package/src/components/text-input.ts

@@ -65,6 +65,7 @@ import {
   blurTextInput,
   dispatchViewCommand,
   dlog,
+  isSymbioteEvent,
   isSymbioteNode,
   setInputBlurred,
   setInputFocused,
@@ -83,12 +84,6 @@ import {
 
 export type { ITextInputHandle, ITextInputSelection, IInputMode, IEnterKeyHint, ISubmitBehavior };
 
-// Angular infers an (event) binding's $event as the DOM Event for a custom-schema element, so
-// each handler enters as `unknown` and is narrowed here before reaching a typed callback.
-function isSymbioteEvent(value: unknown): value is ISymbioteEvent {
-  return typeof value === 'object' && value !== null && 'nativeEvent' in value;
-}
-
 // Mirrors React's ITextInputProps minus nothing (TextInput has no children) — declared
 // per-adapter over the shared accessibility base because Angular's input surface aliases the
 // aria-* keys to camelCase @Inputs, unlike the plain agnostic fields shared across adapters.

package/src/components/{touchable.ts → touchable/index.ts}

@@ -55,9 +55,9 @@ import {
   type IStyleProp,
   type IViewStyle,
 } from '@symbiote-native/engine';
-import { anchorHostStyle, anchorStyleProp } from '../primitives';
-import { Pressable, type IAngularPressableInputs } from './pressable';
-import { Animated, AnimatedView } from '../modules/animated';
+import { anchorHostStyle, anchorStyleProp } from '../../primitives';
+import { Pressable, type IAngularPressableInputs } from '../pressable';
+import { Animated, AnimatedView } from '../../modules/animated';
 
 // The shared field base for all three: the Pressable INPUT surface (minus style, which each
 // Touchable routes differently, and minus the press/hover events, which each Touchable declares as

package/src/components/{touchable.test.ts → touchable/touchable.test.ts}

@@ -9,8 +9,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { clearGlobalStyles, registerStyles } from '@symbiote-native/engine';
 import { installFabric } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from '../render';
-import { TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback } from './touchable';
+import { mount, unmount } from '../../render';
+import { TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback } from './index';
 
 const ROOT_TAG = 940;
 const fabric = installFabric();

package/src/components/{touchable-native-feedback.ts → touchable-native-feedback/index.ts}

@@ -44,9 +44,9 @@ import {
   type IPressableAndroidRippleConfig,
   type IRectOffset,
 } from '@symbiote-native/components';
-import { dlog, type ISymbioteEvent } from '@symbiote-native/engine';
-import { anchorHostStyle, SymbioteHostPropsDirective, ViewHost } from '../primitives';
-import { Pressable, type IAngularPressableInputs } from './pressable';
+import { dlog, isSymbioteEvent, type ISymbioteEvent } from '@symbiote-native/engine';
+import { anchorHostStyle, SymbioteHostPropsDirective, ViewHost } from '../../primitives';
+import { Pressable, type IAngularPressableInputs } from '../pressable';
 
 export type {
   INativeFeedbackBackground,
@@ -63,12 +63,6 @@ export type IAngularTouchableNativeFeedbackProps = Omit<IAngularPressableInputs,
   useForeground?: boolean;
 };
 
-// Angular infers an `(event)` binding's $event as the DOM Event for a custom-schema element,
-// so each handler enters as `unknown` and is narrowed here before reaching a typed callback.
-function isSymbioteEvent(value: unknown): value is ISymbioteEvent {
-  return typeof value === 'object' && value !== null && 'nativeEvent' in value;
-}
-
 @Component({
   selector: 'TouchableNativeFeedback',
   standalone: true,

package/src/components/{touchable-native-feedback.test.ts → touchable-native-feedback/touchable-native-feedback.test.ts}

@@ -10,8 +10,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { clearGlobalStyles, registerStyles } from '@symbiote-native/engine';
 import { installFabric } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from '../render';
-import { TouchableNativeFeedback } from './touchable-native-feedback';
+import { mount, unmount } from '../../render';
+import { TouchableNativeFeedback } from './index';
 
 const ROOT_TAG = 941;
 const fabric = installFabric();

package/src/{create-portal.test.ts → create-portal/create-portal.test.ts}

@@ -8,9 +8,9 @@ import { Component, signal } from '@angular/core';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from './render';
-import { ViewHost, TextHost } from './primitives';
-import { PortalDirective, PortalOutletDirective } from './create-portal';
+import { mount, unmount } from '../render';
+import { ViewHost, TextHost } from '../primitives';
+import { PortalDirective, PortalOutletDirective } from './index';
 
 const ROOT_TAG = 930;
 

package/src/{create-tunnel.test.ts → create-tunnel/create-tunnel.test.ts}

@@ -8,9 +8,9 @@ import { Component } from '@angular/core';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
 
-import { mount, unmount } from './render';
-import { ViewHost, TextHost } from './primitives';
-import { createTunnel, TunnelInDirective, TunnelOut } from './create-tunnel';
+import { mount, unmount } from '../render';
+import { ViewHost, TextHost } from '../primitives';
+import { createTunnel, TunnelInDirective, TunnelOut } from './index';
 
 const SOURCE_TAG = 920;
 const TARGET_TAG = 921;

package/src/index.ts

@@ -135,7 +135,7 @@ export { DescriptorOutlet } from './descriptor-to-angular';
 // call.
 export { PortalDirective, PortalOutletDirective } from './create-portal';
 export { createTunnel, TunnelInDirective, TunnelOut, type ITunnelStore } from './create-tunnel';
-export { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
+export { registerComposedComponent, SymbioteRenderer, SymbioteRendererFactory } from './renderer';
 export { findNodeHandle } from './host-instance';
 export type { IHostInstance } from './host-instance';
 export { StatusBar } from './modules/status-bar';

package/src/modules/animated/animated-leaf-binder/animated-leaf-binder.test.ts

@@ -0,0 +1,116 @@
+// Unit tests for AnimatedLeafBinder in isolation — no Angular involved. Both
+// AnimatedComponentBase and AnimatedImage delegate their leaf-lifecycle (build a leaf,
+// bind it to the committed Fabric node, swap leaves on re-render, tear down) to this Pure
+// Fabrication; these tests exercise the binder directly against a real engine node
+// (SymbioteSurface + the fake Fabric backend), so a break here isolates to the shared
+// orchestration rather than either owning component.
+import { beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import {
+  AnimatedValue,
+  createElement,
+  createSurface,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+import { AnimatedLeafBinder } from './index';
+
+const fabric = installFabric();
+let nextRootTag = 9001;
+
+beforeEach(() => fabric.reset());
+
+// A node that has already gone through a commit — whenCommitted fires synchronously.
+function committedNode(): ISymbioteNode {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  surface.commit();
+  return node;
+}
+
+// A node that is attached to a surface but has NOT been committed yet — whenCommitted
+// must defer until the caller commits the surface.
+function uncommittedNode(): { node: ISymbioteNode; commit: () => void } {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  return { node, commit: () => surface.commit() };
+}
+
+// `appRoot()` unwraps RN's synthetic box-none AppContainer, which is ALSO an RCTView, so a
+// plain `fabric.find(viewName === 'RCTView')` would match it instead of the node under test.
+// Each test appends exactly one child, so the container's first (only) child is the real node.
+function fakeView(): ReturnType<typeof fabric.find> {
+  return fabric.appRoot().children[0];
+}
+
+describe('AnimatedLeafBinder', () => {
+  it('creates and attaches an AnimatedProps leaf, wiring value changes onto the host node', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    // The leaf itself never pushes the INITIAL value — that first paint comes from the
+    // owning component's own reduceProps template binding (out of scope here). The leaf
+    // only drives value CHANGES after it is bound.
+    binder.reconcile({ style: { opacity } }, false);
+
+    opacity.setValue(0.4);
+    expect(fakeView()?.props.opacity).toBe(0.4);
+  });
+
+  it('binds to the host node via whenCommitted, deferring until the node is actually committed', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    // Not committed yet: the value graph exists, but no Fabric node to flush onto.
+    opacity.setValue(0.5);
+    expect(fabric.created).toHaveLength(0);
+
+    commit();
+    // whenCommitted's post-commit retry binds the leaf now; a subsequent change flushes.
+    opacity.setValue(0.7);
+    expect(fakeView()?.props.opacity).toBe(0.7);
+  });
+
+  it('attaches the new leaf before detaching the old one on a second reconcile', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const shared = new AnimatedValue(1);
+    const order: string[] = [];
+    const originalAddChild = shared.__addChild.bind(shared);
+    const originalRemoveChild = shared.__removeChild.bind(shared);
+    shared.__addChild = child => {
+      order.push('add');
+      originalAddChild(child);
+    };
+    shared.__removeChild = child => {
+      order.push('remove');
+      originalRemoveChild(child);
+    };
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+    order.length = 0; // only care about the SECOND reconcile's swap order
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+
+    expect(order).toEqual(['add', 'remove']);
+  });
+
+  it('detaches the leaf and cancels any pending bind on destroy', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    binder.destroy();
+    commit();
+
+    // The pending whenCommitted bind was cancelled by destroy, so committing afterward
+    // must not retroactively bind the (already-detached) leaf.
+    opacity.setValue(0.9);
+    expect(fakeView()?.props.opacity).toBeUndefined();
+  });
+});

package/src/modules/animated/animated-leaf-binder/index.ts

@@ -0,0 +1,101 @@
+// Pure Fabrication (GRASP): the leaf-lifecycle orchestration shared by every Animated*
+// wrapper, extracted out of AnimatedComponentBase so AnimatedImage — which cannot extend
+// AnimatedComponentBase, since it must extend ImageBase for TS's-native image handling —
+// gets the SAME logic via composition instead of copy-pasting it. Framework-thin on
+// purpose: it knows nothing about Angular (@ViewChild, DI, change detection), only the
+// engine's Animated leaf + commit primitives, so it stays testable without any Angular
+// bootstrap. NOTE: react/vue drive this same dance through their own runtime HOC
+// (createAnimatedComponent) rather than a class, so there is no cross-adapter dedup
+// opportunity here yet — this Pure Fabrication is local to the angular adapter.
+import {
+  AnimatedProps,
+  attachNativeEventHandler,
+  dlog,
+  whenCommitted,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+
+export class AnimatedLeafBinder {
+  // The leaf currently wired into the value graph. Null until the first reconcile.
+  private attached: AnimatedProps | null = null;
+  // The whenCommitted waiter for the current leaf's node binding, cancelled before the next.
+  private cancelBind: (() => void) | undefined;
+  // Detachers for any Animated.event prop bound natively to the committed node (JS path: none).
+  private eventDetachers: Array<() => void> = [];
+
+  // `resolveNode` stays a caller-supplied resolver (not a constructor-captured node) so this
+  // class never needs to know HOW the host node is found — AnimatedComponentBase and
+  // AnimatedImage both resolve it the same way (resolveHostNode + isSymbioteNode over their
+  // own @ViewChild), but that's Angular DI state this binder has no business touching.
+  // `label` is purely diagnostic (dlog), mirroring the constructor.name the pre-extraction
+  // dlog call used.
+  constructor(
+    private readonly resolveNode: () => ISymbioteNode | null,
+    private readonly label: string,
+  ) {}
+
+  // Build a fresh AnimatedProps leaf from the current props (the React/Vue per-render
+  // useMemo(rest)), wire it into the graph, and swap the previous one out. Attach the NEW leaf
+  // BEFORE detaching the OLD one: a shared Value self-detaches (dropping its native node) the
+  // instant its child count hits zero, so detaching first would kill a running native animation
+  // on any unrelated re-render (mirrors RN's AnimatedComponent._attachProps). Then bind the
+  // committed node, go native if wanted, and rebind native events.
+  reconcile(props: Record<string, unknown>, wantsNative: boolean): void {
+    dlog(`${this.label} reconcile`);
+    const newLeaf = new AnimatedProps(props);
+    newLeaf.__attach();
+    if (this.attached !== null && this.attached !== newLeaf) this.attached.__detach();
+    this.attached = newLeaf;
+
+    this.bindNode(newLeaf, props, wantsNative);
+  }
+
+  // Bind the leaf to the host's Fabric node THROUGH whenCommitted: under Angular's zoneless
+  // batched change detection the inner host's tag does not exist yet at ngAfterViewInit time
+  // (the same async-commit gotcha Vue documents), so binding eagerly would no-op. whenCommitted
+  // runs the action now if already committed, else after the commit that assigns the tag.
+  private bindNode(
+    leaf: AnimatedProps,
+    props: Record<string, unknown>,
+    wantsNative: boolean,
+  ): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    const node = this.resolveNode();
+    if (node === null) return;
+    this.cancelBind = whenCommitted(node, () => {
+      leaf.setNativeView(node);
+      if (wantsNative) leaf.__makeNative();
+      this.attachEvents(node, props);
+    });
+  }
+
+  // Native-attach any Animated.event prop (e.g. onScroll={Animated.event(…,{useNativeDriver:true})})
+  // to the committed node. attachNativeEventHandler no-ops (returns undefined) unless the prop is a
+  // native event handler with a committed tag, so the JS path stays the fallback. Rebound each
+  // reconcile so a new inline event re-attaches; detached first to avoid leaking the prior binding.
+  private attachEvents(node: ISymbioteNode, props: Record<string, unknown>): void {
+    this.detachEvents();
+    for (const key of Object.keys(props)) {
+      const attachment = attachNativeEventHandler(node, key, props[key]);
+      if (attachment !== undefined) this.eventDetachers.push(attachment.detach);
+    }
+  }
+
+  private detachEvents(): void {
+    for (const detach of this.eventDetachers) detach();
+    this.eventDetachers = [];
+  }
+
+  // Tear down everything: cancel a still-pending bind, drop native event listeners, detach the
+  // current leaf from the value graph. Safe to call even if reconcile() was never called.
+  destroy(): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    this.detachEvents();
+    if (this.attached !== null) {
+      this.attached.__detach();
+      this.attached = null;
+    }
+  }
+}

package/src/modules/animated/animated-leaf-binder.test.ts

@@ -0,0 +1,116 @@
+// Unit tests for AnimatedLeafBinder in isolation — no Angular involved. Both
+// AnimatedComponentBase and AnimatedImage delegate their leaf-lifecycle (build a leaf,
+// bind it to the committed Fabric node, swap leaves on re-render, tear down) to this Pure
+// Fabrication; these tests exercise the binder directly against a real engine node
+// (SymbioteSurface + the fake Fabric backend), so a break here isolates to the shared
+// orchestration rather than either owning component.
+import { beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import {
+  AnimatedValue,
+  createElement,
+  createSurface,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+import { AnimatedLeafBinder } from './animated-leaf-binder';
+
+const fabric = installFabric();
+let nextRootTag = 9001;
+
+beforeEach(() => fabric.reset());
+
+// A node that has already gone through a commit — whenCommitted fires synchronously.
+function committedNode(): ISymbioteNode {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  surface.commit();
+  return node;
+}
+
+// A node that is attached to a surface but has NOT been committed yet — whenCommitted
+// must defer until the caller commits the surface.
+function uncommittedNode(): { node: ISymbioteNode; commit: () => void } {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  return { node, commit: () => surface.commit() };
+}
+
+// `appRoot()` unwraps RN's synthetic box-none AppContainer, which is ALSO an RCTView, so a
+// plain `fabric.find(viewName === 'RCTView')` would match it instead of the node under test.
+// Each test appends exactly one child, so the container's first (only) child is the real node.
+function fakeView(): ReturnType<typeof fabric.find> {
+  return fabric.appRoot().children[0];
+}
+
+describe('AnimatedLeafBinder', () => {
+  it('creates and attaches an AnimatedProps leaf, wiring value changes onto the host node', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    // The leaf itself never pushes the INITIAL value — that first paint comes from the
+    // owning component's own reduceProps template binding (out of scope here). The leaf
+    // only drives value CHANGES after it is bound.
+    binder.reconcile({ style: { opacity } }, false);
+
+    opacity.setValue(0.4);
+    expect(fakeView()?.props.opacity).toBe(0.4);
+  });
+
+  it('binds to the host node via whenCommitted, deferring until the node is actually committed', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    // Not committed yet: the value graph exists, but no Fabric node to flush onto.
+    opacity.setValue(0.5);
+    expect(fabric.created).toHaveLength(0);
+
+    commit();
+    // whenCommitted's post-commit retry binds the leaf now; a subsequent change flushes.
+    opacity.setValue(0.7);
+    expect(fakeView()?.props.opacity).toBe(0.7);
+  });
+
+  it('attaches the new leaf before detaching the old one on a second reconcile', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const shared = new AnimatedValue(1);
+    const order: string[] = [];
+    const originalAddChild = shared.__addChild.bind(shared);
+    const originalRemoveChild = shared.__removeChild.bind(shared);
+    shared.__addChild = child => {
+      order.push('add');
+      originalAddChild(child);
+    };
+    shared.__removeChild = child => {
+      order.push('remove');
+      originalRemoveChild(child);
+    };
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+    order.length = 0; // only care about the SECOND reconcile's swap order
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+
+    expect(order).toEqual(['add', 'remove']);
+  });
+
+  it('detaches the leaf and cancels any pending bind on destroy', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    binder.destroy();
+    commit();
+
+    // The pending whenCommitted bind was cancelled by destroy, so committing afterward
+    // must not retroactively bind the (already-detached) leaf.
+    opacity.setValue(0.9);
+    expect(fakeView()?.props.opacity).toBeUndefined();
+  });
+});