@symbiote-native/angular 0.0.0-canary-20260724081123

package/src/modules/animated/create-animated-component.ts

@@ -0,0 +1,365 @@
+// createAnimatedComponent for @symbiote-native/angular: the Angular twin of the React/Vue
+// wrapper. React/Vue have a runtime HOC (`createAnimatedComponent(Component)` builds a
+// fresh wrapped component on the fly). Angular has NO such idiom AND it cannot have one:
+// the AOT-under-Metro build compiles every @Component at build
+// time and ships NO JIT compiler to Hermes, so a runtime `Component({...})(class)` would
+// throw. The idiomatic, AOT-safe equivalent is therefore an EXPLICIT set of standalone
+// components — AnimatedView / AnimatedText / AnimatedImage / AnimatedScrollView — each a
+// thin @Component over the matching host primitive, all sharing one abstract lifecycle
+// base. The mechanism (build an AnimatedProps leaf, reduce animated props to current
+// values for the first paint, bind the leaf to the committed host node, swap leaves on
+// re-render, tear down on destroy) lives once in AnimatedComponentBase; only the per-host
+// template differs.
+//
+// The framework-agnostic half (reduceProps / readPassthroughStyle / resolveHostNode /
+// AnimatedProps / attachNativeEventHandler / isNativeAnimatedAvailable) comes from
+// @symbiote-native/engine, shared verbatim with React and Vue. Angular supplies
+// only the lifecycle wiring. The per-frame path NEVER goes through Angular change
+// detection: value.setValue / animation -> flushValue -> AnimatedProps.update() ->
+// setNativeProps(node), exactly as on the other adapters.
+
+import {
+  ChangeDetectionStrategy,
+  Component,
+  CUSTOM_ELEMENTS_SCHEMA,
+  Directive,
+  ElementRef,
+  inject,
+  ViewChild,
+  type AfterViewInit,
+  type OnChanges,
+  type OnDestroy,
+  type Type,
+} from '@angular/core';
+import {
+  isNativeAnimatedAvailable,
+  isSymbioteNode,
+  reduceProps,
+  readPassthroughStyle,
+  resolveHostNode,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+import { selectScrollIntrinsics } from '@symbiote-native/components';
+import { Image, ScrollView, Text, View } from '../../components';
+import {
+  anchorHostStyle,
+  ViewHost,
+  TextHost,
+  ImageHost,
+  ScrollViewHost,
+  SymbioteHostPropsDirective,
+} from '../../primitives';
+import { FlatList } from '../../components/flat-list';
+import {
+  IMAGE_INPUTS,
+  IMAGE_OUTPUTS,
+  ImageBase,
+  resolveImageProps,
+} from '../../components/image/shared';
+import { SectionList } from '../../components/section-list';
+import { AnimatedLeafBinder } from './animated-leaf-binder';
+
+// RN's prop carrying explicit (already-rasterized) values that override the animated prop in
+// the COMMITTED props (sticky-header passthrough). Named once so the directive input and the
+// reconcile agree.
+const PASSTHROUGH_PROP = 'passthroughAnimatedPropExplicitValues';
+
+// The inputs every animated wrapper accepts. `style` is the (possibly animated) style — the
+// common path (TouchableOpacity passes `[style, { opacity }]`). `animatedProps` is the generic
+// escape hatch for any OTHER prop that may hold an AnimatedNode or an Animated.event handler,
+// plus static host props to forward (the React/Vue `rest`). The passthrough drives native.
+// Each concrete @Component re-lists these (Angular's inputs-on-base convention, mirroring
+// Switch/Image), so they are inherited consistently.
+export const ANIMATED_INPUTS = ['style', 'animatedProps', PASSTHROUGH_PROP];
+export const ANIMATED_IMAGE_INPUTS = [...IMAGE_INPUTS, 'animatedProps', PASSTHROUGH_PROP];
+
+// The shared lifecycle for every animated wrapper. Concrete subclasses add ONLY a @Component
+// decorator (selector + the host-primitive template) — no behavior. Plain fields (no @Input
+// here): the inputs are declared on each concrete via ANIMATED_INPUTS, the adapter convention.
+// @Directive() (no selector) is the Angular-sanctioned decorator for an abstract base that
+// declares lifecycle hooks — without it ngtsc rejects the inherited hooks (NG2007).
+@Directive()
+export abstract class AnimatedComponentBase implements AfterViewInit, OnChanges, OnDestroy {
+  style: unknown;
+  animatedProps: Record<string, unknown> | undefined;
+  passthroughAnimatedPropExplicitValues: unknown;
+
+  // This component's OWN host — every Animated* wrapper is a non-painting ANCHOR
+  // (ANCHOR_HOST_COMPONENTS in renderer.ts), so a `class="..."` at the use site resolves onto
+  // THIS element, never the real inner host primitive one level down (see anchorHostStyle's doc
+  // comment in primitives/shared.ts — the same reason ScrollView's own scrollProps merges it in).
+  private readonly elementRef = inject(ElementRef);
+
+  // The directive sitting on the inner host primitive; its `node` is the committed SymbioteNode
+  // the leaf binds to. Inherited by the decorated subclass (Angular collects base-class queries).
+  @ViewChild(SymbioteHostPropsDirective) private hostDirective?: SymbioteHostPropsDirective;
+
+  // The leaf-lifecycle orchestration (build/attach/swap/bind/detach an AnimatedProps leaf) is a
+  // Pure Fabrication shared with AnimatedImage, which cannot extend this class (it must extend
+  // ImageBase — see the file header). `resolveNode` stays a resolver, not a captured node: the
+  // committed node only exists after `hostDirective` is populated post-view-init.
+  private readonly leafBinder = new AnimatedLeafBinder(
+    () => this.hostNode(),
+    this.constructor.name,
+  );
+  // Set once the view (and the inner host directive) exists; ngOnChanges before then is a no-op.
+  private viewReady = false;
+
+  // The concrete props for the host element each change-detection pass: animated entries reduced
+  // to their current value, then the passthrough style layered on top (last wins via the style
+  // array, which the commit layer flattens) so the ShadowTree carries the current transform.
+  get reducedProps(): Record<string, unknown> {
+    const reduced = reduceProps(this.mergedProps());
+    const passthroughStyle = readPassthroughStyle(this.passthroughAnimatedPropExplicitValues);
+    if (passthroughStyle !== undefined) {
+      reduced['style'] =
+        reduced['style'] === undefined ? passthroughStyle : [reduced['style'], passthroughStyle];
+    }
+    reduced['style'] = [anchorHostStyle(this.elementRef), reduced['style']];
+    return reduced;
+  }
+
+  ngAfterViewInit(): void {
+    this.viewReady = true;
+    this.reconcile();
+  }
+
+  ngOnChanges(): void {
+    this.reconcile();
+  }
+
+  ngOnDestroy(): void {
+    this.leafBinder.destroy();
+  }
+
+  // A non-stable [animatedProps]/[style] input (a fresh object literal in the template) pushes
+  // a new reference on every change-detection pass of the HOST view, re-triggering this on every
+  // unrelated interaction elsewhere in the app — DEBUG=1 turns this into a visible tick count in
+  // AnimatedLeafBinder.reconcile, so an unexpectedly high rate for a component nobody is
+  // animating is the tell (see AnimatedScrollView's stable-reference fix in examples/angular/App.ts).
+  private reconcile(): void {
+    if (!this.viewReady) return;
+    const props = this.mergedProps();
+    const hasPassthroughAnimatedValues =
+      this.passthroughAnimatedPropExplicitValues !== null &&
+      this.passthroughAnimatedPropExplicitValues !== undefined;
+    const wantsNative = hasPassthroughAnimatedValues && isNativeAnimatedAvailable();
+    this.leafBinder.reconcile(props, wantsNative);
+  }
+
+  // Merge the dedicated `style` input over the generic `animatedProps` bag into one props map —
+  // the equivalent of React/Vue `rest`. `style` wins so `[style]` and `[animatedProps].style`
+  // never disagree.
+  private mergedProps(): Record<string, unknown> {
+    const base = this.animatedProps ?? {};
+    return this.style === undefined ? { ...base } : { ...base, style: this.style };
+  }
+
+  // The committed host node held by IDENTITY. resolveHostNode unwraps an imperative scroll
+  // handle to the underlying SymbioteNode (View / Text already hand back the node directly);
+  // the isSymbioteNode guard keeps us off a cast.
+  private hostNode(): ISymbioteNode | null {
+    const resolved = resolveHostNode(this.hostDirective?.node);
+    return isSymbioteNode(resolved) ? resolved : null;
+  }
+}
+
+@Component({
+  selector: 'AnimatedView, symbiote-animated-view',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  imports: [SymbioteHostPropsDirective, ViewHost],
+  inputs: ANIMATED_INPUTS,
+  template: `
+    <symbiote-view [symbioteHostProps]="reducedProps">
+      <ng-content></ng-content>
+    </symbiote-view>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AnimatedView extends AnimatedComponentBase {}
+
+@Component({
+  selector: 'AnimatedText, symbiote-animated-text',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  imports: [SymbioteHostPropsDirective, TextHost],
+  inputs: ANIMATED_INPUTS,
+  template: `
+    <symbiote-text [symbioteHostProps]="reducedProps">
+      <ng-content></ng-content>
+    </symbiote-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AnimatedText extends AnimatedComponentBase {}
+
+@Component({
+  selector: 'AnimatedImage, symbiote-animated-image',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  imports: [SymbioteHostPropsDirective, ImageHost],
+  inputs: ANIMATED_IMAGE_INPUTS,
+  outputs: IMAGE_OUTPUTS,
+  template: `
+    <symbiote-image
+      [symbioteHostProps]="animatedImageProps"
+      (accessibilityAction)="handleAccessibilityAction($event)"
+      (accessibilityTap)="handleAccessibilityTap($event)"
+      (magicTap)="handleMagicTap($event)"
+      (accessibilityEscape)="handleAccessibilityEscape($event)"
+      (loadStart)="handleLoadStart($event)"
+      (load)="handleLoad($event)"
+      (loadEnd)="handleLoadEnd($event)"
+      (error)="handleError($event)"
+      (progress)="handleProgress($event)"
+      (partialLoad)="handlePartialLoad($event)"
+    >
+      <ng-content></ng-content>
+    </symbiote-image>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AnimatedImage extends ImageBase implements AfterViewInit, OnChanges, OnDestroy {
+  animatedProps: Record<string, unknown> | undefined;
+  passthroughAnimatedPropExplicitValues: unknown;
+
+  // AnimatedImage is a non-painting ANCHOR too (ANCHOR_HOST_COMPONENTS) — see the matching
+  // comment on AnimatedComponentBase.elementRef.
+  private readonly elementRef = inject(ElementRef);
+
+  @ViewChild(SymbioteHostPropsDirective) private hostDirective?: SymbioteHostPropsDirective;
+
+  // Same Pure Fabrication AnimatedComponentBase holds — see its matching comment. AnimatedImage
+  // can't extend AnimatedComponentBase (it must extend ImageBase, see the file header), so it
+  // gets the leaf-lifecycle via composition instead of duplicating it.
+  private readonly leafBinder = new AnimatedLeafBinder(
+    () => this.hostNode(),
+    this.constructor.name,
+  );
+  private viewReady = false;
+
+  get animatedImageProps(): Record<string, unknown> {
+    const reduced = reduceProps(this.mergedProps());
+    const passthroughStyle = readPassthroughStyle(this.passthroughAnimatedPropExplicitValues);
+    if (passthroughStyle !== undefined) {
+      reduced['style'] =
+        reduced['style'] === undefined ? passthroughStyle : [reduced['style'], passthroughStyle];
+    }
+    const resolved = resolveImageProps(reduced);
+    resolved['style'] = [anchorHostStyle(this.elementRef), resolved['style']];
+    return resolved;
+  }
+
+  ngAfterViewInit(): void {
+    this.viewReady = true;
+    this.reconcile();
+  }
+
+  ngOnChanges(): void {
+    this.reconcile();
+  }
+
+  ngOnDestroy(): void {
+    this.leafBinder.destroy();
+  }
+
+  private reconcile(): void {
+    if (!this.viewReady) return;
+    const props = this.mergedProps();
+    const hasPassthroughAnimatedValues =
+      this.passthroughAnimatedPropExplicitValues !== null &&
+      this.passthroughAnimatedPropExplicitValues !== undefined;
+    const wantsNative = hasPassthroughAnimatedValues && isNativeAnimatedAvailable();
+    this.leafBinder.reconcile(props, wantsNative);
+  }
+
+  private mergedProps(): Record<string, unknown> {
+    const props: Record<string, unknown> = { ...(this.animatedProps ?? {}) };
+    for (const [key, value] of Object.entries(this.imageInputProps)) {
+      if (value !== undefined) props[key] = value;
+    }
+    return props;
+  }
+
+  private hostNode(): ISymbioteNode | null {
+    const resolved = resolveHostNode(this.hostDirective?.node);
+    return isSymbioteNode(resolved) ? resolved : null;
+  }
+}
+
+@Component({
+  selector: 'AnimatedScrollView, symbiote-animated-scroll-view',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  imports: [SymbioteHostPropsDirective, ScrollViewHost],
+  inputs: ANIMATED_INPUTS,
+  template: `
+    <symbiote-scroll-view [symbioteHostProps]="reducedProps">
+      <symbiote-scroll-content [symbioteHostProps]="contentProps">
+        <ng-content></ng-content>
+      </symbiote-scroll-content>
+    </symbiote-scroll-view>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AnimatedScrollView extends AnimatedComponentBase {
+  // RN defaults nested scrolling ON (ScrollView.js `nestedScrollEnabled ?? true`) — Android
+  // needs it explicit or a ScrollView nested inside another scrollable container never
+  // receives touch (swallowed by the outer scroll view; iOS doesn't gate on this). The real
+  // ScrollView component already defaults this (scroll-view/shared.ts), but AnimatedScrollView
+  // talks to the raw primitive directly and has no such defaulting, so it must apply it too.
+  //
+  // scrollViewBaseStyle (overflow: 'scroll' + the per-axis flexDirection) is the OTHER thing
+  // the real ScrollView applies that this bespoke template used to skip entirely — without it,
+  // iOS Fabric never clips the scroll view's content to its own frame (Android's native
+  // ViewGroup clips regardless of the style prop, which is why this was invisible there). This
+  // wrapper has no dedicated `horizontal` input (only the generic `animatedProps`/`style`
+  // surface), and its template is hardcoded to the vertical intrinsics
+  // (symbiote-scroll-view/symbiote-scroll-content, not the horizontal variants), so
+  // selectScrollIntrinsics is always called with isHorizontal=false here — matching what the
+  // template can actually render.
+  override get reducedProps(): Record<string, unknown> {
+    const reduced = super.reducedProps;
+    const { scrollViewBaseStyle } = selectScrollIntrinsics(false, undefined);
+    const withScrollBase: Record<string, unknown> = {
+      ...reduced,
+      style: [scrollViewBaseStyle, reduced.style],
+    };
+    return withScrollBase.nestedScrollEnabled === undefined
+      ? { ...withScrollBase, nestedScrollEnabled: true }
+      : withScrollBase;
+  }
+
+  // The content (inner) view's props: contentStyle from the same intrinsics selection, plus
+  // `collapsable: false` (the Android multi-child fix this file's tests already cover) — mirrors
+  // the real ScrollView's own `contentProps` getter (scroll-view/shared.ts).
+  get contentProps(): Record<string, unknown> {
+    const { contentStyle } = selectScrollIntrinsics(false, undefined);
+    return { style: contentStyle, collapsable: false };
+  }
+}
+
+// List components are already explicit AOT-compiled Angular components with their own full input
+// surface and inner ScrollView composition. Expose them in the Animated namespace without runtime
+// synthesis; app code passes animated style/onScroll through the existing list inputs.
+export const AnimatedFlatList = FlatList;
+export const AnimatedSectionList = SectionList;
+
+// Surface-parity shim for the React/Vue `createAnimatedComponent(Component)`. Angular cannot
+// synthesize a component at runtime (no JIT under AOT/Metro — see the file header), so this maps
+// the built-in primitives to their pre-authored wrappers and refuses anything else with a
+// pointer to the real Angular idiom: author a standalone @Component extending
+// AnimatedComponentBase.
+export function createAnimatedComponent(base: unknown): Type<unknown> {
+  if (base === View) return AnimatedView;
+  if (base === Text) return AnimatedText;
+  if (base === Image) return AnimatedImage;
+  if (base === ScrollView) return AnimatedScrollView;
+  throw new Error(
+    'createAnimatedComponent: Angular cannot synthesize a component at runtime (no JIT compiler ' +
+      'under AOT/Metro). Author an explicit standalone @Component extending AnimatedComponentBase ' +
+      'instead. The built-in primitives View / Text / Image / ScrollView map to ' +
+      'AnimatedView / AnimatedText / AnimatedImage / AnimatedScrollView.',
+  );
+}

package/src/modules/animated/index.ts

@@ -0,0 +1,105 @@
+// The Animated namespace for @symbiote-native/angular: the Angular twin of adapters/vue/src/modules/
+// animated/index.ts. The animated COMPONENTS (View / Text / Image / ScrollView) are explicit
+// standalone components (Angular has no runtime HOC — see create-animated-component.ts); the
+// value graph, easing and imperative drivers come from @symbiote-native/engine (framework-agnostic,
+// JS-driven), spread in verbatim. Both halves meet here so the familiar surface,
+// `Animated.timing(new Animated.Value(0), …).start()`, works against the Angular-driven engine.
+
+import {
+  AnimatedValue,
+  AnimatedValueXY,
+  AnimatedColor,
+  AnimatedMock,
+  Easing,
+  Platform,
+  timing,
+  spring,
+  decay,
+  parallel,
+  sequence,
+  stagger,
+  loop,
+  delay,
+  add,
+  subtract,
+  multiply,
+  divide,
+  modulo,
+  diffClamp,
+  event,
+  forkEvent,
+  unforkEvent,
+} from '@symbiote-native/engine';
+import {
+  AnimatedFlatList,
+  AnimatedImage,
+  AnimatedScrollView,
+  AnimatedSectionList,
+  AnimatedText,
+  AnimatedView,
+  createAnimatedComponent,
+} from './create-animated-component';
+
+export {
+  AnimatedComponentBase,
+  AnimatedFlatList,
+  AnimatedImage,
+  AnimatedScrollView,
+  AnimatedSectionList,
+  AnimatedText,
+  AnimatedView,
+  createAnimatedComponent,
+} from './create-animated-component';
+
+// ScrollView is exposed DIRECTLY, not behind the lazy getter the React/Vue modules use: that
+// getter only exists to defer a RUNTIME createAnimatedComponent(ScrollView) past module init so
+// it cannot read ScrollView inside its own TDZ during an import cycle. AnimatedScrollView here is
+// a statically-declared component that never reads the ScrollView class at init (it targets the
+// `symbiote-scroll-view` host by string), so there is no cycle to defer.
+//
+// FlatList / SectionList are exposed as explicit AOT-safe list entries now that the Angular list
+// components exist. Angular still cannot synthesize arbitrary animated wrappers at runtime; custom
+// animated components remain explicit standalone components over AnimatedComponentBase.
+
+// The live, JS-driven driver namespace (real frames). RN's AnimatedImplementation.
+const liveDrivers = {
+  Value: AnimatedValue,
+  ValueXY: AnimatedValueXY,
+  Color: AnimatedColor,
+  Easing,
+  timing,
+  spring,
+  decay,
+  parallel,
+  sequence,
+  stagger,
+  loop,
+  delay,
+  add,
+  subtract,
+  multiply,
+  divide,
+  modulo,
+  diffClamp,
+  event,
+  forkEvent,
+  unforkEvent,
+};
+
+// RN swaps the WHOLE driver namespace for the mock when the host reports isDisableAnimations
+// (reduced motion / test env): the mock keeps the same surface but jumps each animation to its
+// final value synchronously, no frames. The animated COMPONENTS are live in both branches; only
+// the drivers/value/operators/events half is swapped, exactly like RN spreading `...Animated`
+// (impl or mock) over the same components.
+const drivers = Platform.isDisableAnimations ? AnimatedMock : liveDrivers;
+
+export const Animated = {
+  View: AnimatedView,
+  Text: AnimatedText,
+  Image: AnimatedImage,
+  ScrollView: AnimatedScrollView,
+  FlatList: AnimatedFlatList,
+  SectionList: AnimatedSectionList,
+  createAnimatedComponent,
+  ...drivers,
+};

package/src/modules/app-registry/app-registry.test.ts

@@ -0,0 +1,106 @@
+// Co-located Angular-driven test, Angular twin of adapters/react/src/modules/
+// app-registry/app-registry.test.tsx. Proves the AppRegistry entry point:
+// `registerComponent(appKey, () => App)` stores a runnable that calls `mount` (driving
+// @symbiote-native/engine) AND bridges it to the host registrar (RN's own AppRegistry, injected via
+// `setHostRegistrar`) so native can find it by key. Also proves the Angular-specific
+// `setWrapperComponentProvider` seam: a pre-authored standalone wrapper receives the root's
+// host node as projected `<ng-content>`, the AOT-safe twin of React's
+// createElement(Wrapper, null, rootElement).
+
+import '@angular/compiler';
+import { Component, Input, type Type } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import { AppRegistry, setHostRegistrar, type IAppParameters, type IRunnable } from '../..';
+import { unmount } from '../../render';
+
+const APP_KEY = 'canary';
+const ROOT_TAG = 212;
+const WRAPPED_APP_KEY = 'canary-wrapped';
+const WRAPPED_ROOT_TAG = 213;
+
+// Angular's mount() batches change detection on a microtask, so a committed native tag isn't
+// available synchronously — assertions on the committed tree need one tick, same as Vue.
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+class TestText {}
+Component({
+  selector: 'symbiote-text',
+  standalone: true,
+  template: '<ng-content></ng-content>',
+})(TestText);
+
+class SmokeComponent {}
+Component({
+  selector: 'symbiote-app-registry-smoke',
+  standalone: true,
+  imports: [TestText],
+  template: '<symbiote-text>hi</symbiote-text>',
+})(SmokeComponent);
+
+class WrapperComponent {
+  @Input() label = '';
+}
+Component({
+  selector: 'symbiote-app-registry-wrapper',
+  standalone: true,
+  imports: [TestText],
+  template: '<symbiote-text>{{ label }}</symbiote-text><ng-content></ng-content>',
+})(WrapperComponent);
+
+const fabric = installFabric();
+
+// The host registrar the native side drives (RN's AppRegistry stand-in).
+const hostRunnables = new Map<string, IRunnable>();
+
+beforeEach(() => {
+  fabric.reset();
+  hostRunnables.clear();
+  setHostRegistrar({
+    registerRunnable: (appKey: string, run: IRunnable): string => {
+      hostRunnables.set(appKey, run);
+      return appKey;
+    },
+  });
+  AppRegistry.registerComponent(APP_KEY, () => SmokeComponent);
+});
+afterEach(() => {
+  unmount(ROOT_TAG);
+  unmount(WRAPPED_ROOT_TAG);
+});
+
+describe('AppRegistry', () => {
+  it('exposes the app key and bridges the runnable to the host registrar', () => {
+    expect(AppRegistry.getAppKeys()).toContain(APP_KEY);
+    expect(hostRunnables.get(APP_KEY)).toBeDefined();
+  });
+
+  it('mounts the tree when the host invokes the runnable with a rootTag', async () => {
+    const hostRun = hostRunnables.get(APP_KEY);
+    expect(hostRun).toBeDefined();
+
+    const nativeParams: IAppParameters = { rootTag: ROOT_TAG };
+    hostRun!(nativeParams);
+    await tick();
+
+    expect(fabric.find(n => n.viewName === 'RCTText')).toBeDefined();
+  });
+
+  it('runApplication drives the same runnable locally', async () => {
+    AppRegistry.runApplication(APP_KEY, { rootTag: ROOT_TAG });
+    await tick();
+
+    expect(fabric.find(n => n.viewName === 'RCTText')).toBeDefined();
+  });
+
+  it('projects the root component into a registered wrapper via <ng-content>', async () => {
+    AppRegistry.setWrapperComponentProvider(() => WrapperComponent as Type<unknown>);
+    AppRegistry.registerComponent(WRAPPED_APP_KEY, () => SmokeComponent);
+
+    AppRegistry.runApplication(WRAPPED_APP_KEY, { rootTag: WRAPPED_ROOT_TAG });
+    await tick();
+
+    const texts = fabric.appRoot().children.flatMap(n => fabric.serialize([n]));
+    expect(texts.join('')).toContain('hi');
+  });
+});

package/src/modules/app-registry/index.ts

@@ -0,0 +1,60 @@
+// AppRegistry: the JS entry point RN apps already use:
+//   AppRegistry.registerComponent(appKey, () => App)
+// The registry bookkeeping (sections, host-registrar bridge, headless tasks) is
+// framework-agnostic and lives in @symbiote-native/engine's createAppRegistry; this file supplies
+// only the one Angular-specific seam — building a runnable from a component provider via
+// `mount`'s wrapper/initialProps support (render.ts) — so examples/angular's own
+// registerRunnable + mount call can move onto the same entry point React/Vue already have.
+
+import type { Type } from '@angular/core';
+import {
+  createAppRegistry,
+  dlog,
+  type IAppParameters,
+  type IRunnable,
+} from '@symbiote-native/engine';
+import { mount } from '../../render';
+
+// RN's IComponentProvider: a thunk returning the root component (lazy so the module
+// graph stays cheap until the app actually runs).
+export type IComponentProvider = () => Type<unknown>;
+
+// RN's IWrapperComponentProvider: given the surface's parameters, returns a
+// component to wrap the app root in (e.g. a context provider). Optional. Angular has no
+// runtime template synthesis (no JIT under AOT/Metro — see create-animated-component.ts),
+// so the wrapper must be a pre-authored standalone @Component whose template renders
+// `<ng-content>` — the Angular idiom for "render my children" (mount() projects the root's
+// host node into it, the twin of React's createElement(Wrapper, null, rootElement)).
+export type IWrapperComponentProvider = (appParameters: IAppParameters) => Type<unknown>;
+
+function runnableFor(
+  componentProvider: IComponentProvider,
+  getWrapperComponentProvider: () => IWrapperComponentProvider | undefined,
+): IRunnable {
+  return appParameters => {
+    dlog(`AppRegistry: mounting on rootTag ${String(appParameters.rootTag)}`);
+    // Read live (not at registration time) so setWrapperComponentProvider affects every
+    // runnable's next run, not just future ones.
+    mount(appParameters.rootTag, componentProvider(), {
+      initialProps: appParameters.initialProps,
+      wrapperComponent: getWrapperComponentProvider()?.(appParameters),
+    });
+  };
+}
+
+const { AppRegistry, setHostRegistrar } = createAppRegistry<
+  IComponentProvider,
+  IWrapperComponentProvider
+>(runnableFor);
+
+export { AppRegistry, setHostRegistrar };
+export type {
+  IAppParameters,
+  IRunnable,
+  IHostRegistrar,
+  IRegistry,
+  IHeadlessTask,
+  ITaskProvider,
+  ITaskCanceller,
+  ITaskCancelProvider,
+} from '@symbiote-native/engine';