@symbiote-native/angular 0.1.0

package/src/render.ts

@@ -0,0 +1,224 @@
+// Mount an Angular app onto a Fabric surface. The native host hands us a rootTag; we
+// create a surface and bootstrap a standalone Angular component WITHOUT platform-browser
+// (no DOM) — createEnvironmentInjector + createComponent over @angular/core only, with our
+// SymbioteRendererFactory provided so Angular drives the engine, which commits into
+// nativeFabricUIManager; RN's own renderer never in the path. Angular twin of
+// adapters/vue/src/render.ts. See the `angular-adapter` skill (§2 bootstrap).
+
+import {
+  createElement as createEngineElement,
+  createSurface,
+  disposeRoot,
+  dlog,
+  toPublicInstance,
+  type ISymbioteNode,
+  type IRootTag,
+  type SymbioteSurface,
+} from '@symbiote-native/engine';
+import { descriptorFor } from '@symbiote-native/components';
+import {
+  ApplicationRef,
+  createComponent,
+  createEnvironmentInjector,
+  DOCUMENT,
+  RendererFactory2,
+  ɵINJECTOR_SCOPE as INJECTOR_SCOPE,
+  ɵprovideZonelessChangeDetectionInternal as provideZonelessChangeDetectionInternal,
+  type ComponentRef,
+  type EnvironmentInjector,
+  type Type,
+} from '@angular/core';
+import { SymbioteRendererFactory } from './renderer';
+import { ColorSchemeService, WindowDimensionsService } from './services';
+
+// The two FFI-edge casts of this adapter, both confined here to bootstrap. Angular's core
+// types model a browser: the injector parent is a non-null EnvironmentInjector, the host is
+// a DOM Element. Our root has neither shape — a null parent IS a root injector, and the host
+// is a SymbioteSurface (or, for a wrapped AppRegistry root, a plain engine node) the
+// SymbioteRenderer (not the DOM) consumes. These are the sanctioned I/O-edge casts where our
+// objects cross into Angular's web-typed API; revisit if Angular ever exposes a cast-free
+// host. Nothing else in the adapter casts.
+function rootInjectorParent(): EnvironmentInjector {
+  return null as unknown as EnvironmentInjector;
+}
+function asAngularHost(hostNode: SymbioteSurface | ISymbioteNode): Element {
+  // Angular's locateHostElement reads hostElement.tagName even when a concrete hostElement
+  // is supplied. The host container is given Angular the tiny DOM-shaped field it probes
+  // without changing the renderer target.
+  Object.defineProperty(hostNode, 'tagName', {
+    configurable: true,
+    value: 'symbiote-root',
+  });
+  return hostNode as unknown as Element;
+}
+
+// A bare `symbiote-view` node, created directly through the engine (bypassing Angular's own
+// createElement, which only resolves KNOWN symbiote primitives, never an arbitrary component's
+// selector — see SymbioteRenderer.createElement). Used as the AppRegistry root's host when a
+// wrapperComponentProvider is set: Angular has no hostElement-less bootstrap for our renderer
+// (it would try `renderer.createElement(rootComponent.selector)`, which throws for anything
+// that isn't one of our primitives), so the root needs an explicit host too, one we then hand
+// to the wrapper as projectable content.
+function createDetachedViewHost(): ISymbioteNode {
+  const descriptor = descriptorFor('View');
+  return toPublicInstance(createEngineElement(descriptor.component, descriptor.isText));
+}
+
+interface IMountedApp {
+  cmpRef: ComponentRef<unknown>;
+  rootRef: ComponentRef<unknown> | undefined;
+  injector: EnvironmentInjector;
+}
+
+// AppRegistry's `wrapperComponentProvider` support: the root renders detached (Angular gives
+// it its own host node via our renderer, not yet attached anywhere), and the wrapper — the
+// component actually attached to the surface — receives that host node as a projected child.
+// `<ng-content>` in the wrapper's template is the Angular idiom for "render my children", the
+// direct twin of React's `createElement(Wrapper, null, rootElement)`.
+export interface IMountOptions {
+  initialProps?: object;
+  wrapperComponent?: Type<unknown>;
+}
+
+function applyInputs(cmpRef: ComponentRef<unknown>, initialProps: object | undefined): void {
+  if (initialProps === undefined) return;
+  for (const [key, value] of Object.entries(initialProps)) {
+    cmpRef.setInput(key, value);
+  }
+}
+
+// One Angular app per surface, so a surface can be torn down (unmount) or cleanly
+// re-mounted on the same rootTag: the bridgeless host stops and restarts a surface on Fast
+// Refresh and on lifecycle/focus changes, reusing the rootTag.
+const apps = new Map<IRootTag, IMountedApp>();
+
+function teardown(rootTag: IRootTag): void {
+  const app = apps.get(rootTag);
+  if (app === undefined) return;
+  app.rootRef?.destroy();
+  app.cmpRef.destroy();
+  app.injector.destroy();
+  apps.delete(rootTag);
+  disposeRoot(rootTag);
+}
+
+export function mount(
+  rootTag: IRootTag,
+  rootComponent: Type<unknown>,
+  options?: IMountOptions,
+): SymbioteSurface {
+  // A re-mount on a live rootTag starts clean; otherwise the stale app double-drives the surface.
+  teardown(rootTag);
+
+  const surface = createSurface(rootTag);
+  const injector = createEnvironmentInjector(
+    [
+      {
+        provide: RendererFactory2,
+        useValue: new SymbioteRendererFactory(surface),
+      },
+      { provide: DOCUMENT, useValue: { head: surface, body: surface } },
+      // createEnvironmentInjector with a null parent gives this injector scope
+      // {'environment'} only (see EnvironmentNgModuleRefAdapter), so providedIn:'root'
+      // tokens — ApplicationRef included — never resolve on their own (R3Injector.get
+      // walks up looking for an injector whose `scopes` contains 'root', and a null
+      // parent means that search always dead-ends in NullInjector). platform-browser's
+      // BROWSER_MODULE_PROVIDERS solves this the same way for real DOM apps: it hands
+      // { provide: INJECTOR_SCOPE, useValue: 'root' } to its OWN app-level providers, and
+      // R3Injector's constructor reads that provider and self-tags this.scopes with
+      // 'root'. We do the same here — no PlatformRef, no DOM, just this one provider.
+      { provide: INJECTOR_SCOPE, useValue: 'root' },
+      // Supplies the real ChangeDetectionSchedulerImpl (microtask-batched, self-scheduling
+      // via ApplicationRef.afterTick) + NoopNgZone + ZONELESS_ENABLED: true — the exact
+      // bundle internalCreateApplication() uses. With ApplicationRef reachable (see above),
+      // there is no more reason for a hand-rolled scheduler: it replaces our old
+      // unconditional `rootView.detectChanges(); cmpView.detectChanges()` (which force-ran
+      // BOTH root views on every tick regardless of cause) with Angular's own tick(), which
+      // only enters an attached view when something actually marked it (RefreshView / Dirty
+      // consumer / HasChildViewsToRefresh). NOTE: this does NOT stop the root's own template
+      // from re-running on a plain press or `ChangeDetectorRef.markForCheck()` anywhere in
+      // the tree — `markViewDirty` (which both native (event) bindings and `markForCheck()`
+      // go through, see SymbioteHostPropsDirective) unconditionally sets RefreshView on
+      // EVERY ancestor up to the root; that is fundamental, unavoidable Angular zoneless
+      // behavior, true in every Angular app, not something this swap changes. What DOES
+      // still protect a sibling branch from an unrelated press is a genuine child
+      // `@Component` boundary — SignalView-compiled children are skip-eligible regardless of
+      // this scheduler (see the `angular-adapter` skill §20 for the full investigation,
+      // including the test that disproved the stronger claim before it shipped).
+      ...provideZonelessChangeDetectionInternal(),
+      ColorSchemeService,
+      WindowDimensionsService,
+    ],
+    rootInjectorParent(),
+  );
+
+  // hostElement = the surface: the component's template content commits straight into the
+  // surface with no wrapper view, the engine wrapping surface.children in its synthetic flex
+  // root — the Angular equivalent of Vue's `app.mount(surface)`.
+  let cmpRef: ComponentRef<unknown>;
+  let rootRef: ComponentRef<unknown> | undefined;
+  if (options?.wrapperComponent === undefined) {
+    cmpRef = createComponent<unknown>(rootComponent, {
+      environmentInjector: injector,
+      hostElement: asAngularHost(surface),
+    });
+    applyInputs(cmpRef, options?.initialProps);
+  } else {
+    // The root gets its own host node from the renderer (createComponent without a
+    // hostElement) but is not attached to the surface directly; it is handed to the
+    // wrapper as projectable content instead, so only the wrapper needs a real host.
+    const rootHost = asAngularHost(createDetachedViewHost());
+    rootRef = createComponent<unknown>(rootComponent, {
+      environmentInjector: injector,
+      hostElement: rootHost,
+    });
+    applyInputs(rootRef, options.initialProps);
+    cmpRef = createComponent<unknown>(options.wrapperComponent, {
+      environmentInjector: injector,
+      hostElement: asAngularHost(surface),
+      projectableNodes: [[rootHost]],
+    });
+  }
+
+  // Attach both root views to ApplicationRef so its own tick() (via the real
+  // ChangeDetectionSchedulerImpl provided above) drives them from here on — no manual
+  // ChangeDetectorRef juggling needed. markForCheck anywhere in the tree now notifies
+  // the real scheduler, which batches a microtask and calls appRef.tick() itself.
+  const appRef = injector.get(ApplicationRef);
+  appRef.attachView(cmpRef.hostView);
+  if (rootRef !== undefined) {
+    appRef.attachView(rootRef.hostView);
+  }
+
+  dlog(`angular mount root=${rootTag}`);
+  appRef.tick(); // first paint
+  surface.requestCommit();
+
+  apps.set(rootTag, { cmpRef, rootRef, injector });
+  return surface;
+}
+
+// Tear down a surface by rootTag: the public pair of `mount`, and the JS half of the
+// bridgeless `RN$stopSurface` contract (see installStopSurfaceGlobal).
+export function unmount(rootTag: IRootTag): void {
+  dlog(`angular unmount root=${rootTag}`);
+  teardown(rootTag);
+}
+
+// `global.RN$stopSurface` is the JSI hook C++ AppRegistryBinding::stopSurface calls to stop a
+// Fabric surface. RN installs it from its own renderer; symbiote REPLACES that renderer, so
+// without this the binding throws "Global was not installed" on every surface stop (Fast
+// Refresh, focus/lifecycle) and the screen goes blank. Same contract as the React/Vue
+// adapters: an app uses one adapter, so exactly one installer runs.
+declare global {
+  var RN$stopSurface: ((surfaceId: number) => void) | undefined;
+}
+
+function installStopSurfaceGlobal(): void {
+  globalThis.RN$stopSurface = (surfaceId: number): void => {
+    unmount(surfaceId);
+  };
+  dlog('installed global.RN$stopSurface');
+}
+
+installStopSurfaceGlobal();

package/src/renderer.test.ts

@@ -0,0 +1,179 @@
+// Co-located headless test for the Angular renderer seam (ADR 0025). Drives SymbioteRenderer
+// directly — no Angular runtime, no compiler — against the shared fake Fabric slot, proving
+// each Renderer2 method maps onto the engine mutation API and commits a correct Fabric tree.
+// The bootstrap (mount → createComponent) is validated separately on a real host / the AOT
+// example; this isolates the seam, which is the deterministic, framework-free half.
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  clearGlobalStyles,
+  createSurface,
+  disposeRoot,
+  isSymbioteNode,
+  registerStyles,
+} from '@symbiote-native/engine';
+import { installFabric } from '@symbiote-native/test-utils';
+import { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
+
+const ROOT_TAG = 707;
+const PROBE_ID = 'probe';
+
+const fabric = installFabric();
+
+// A macrotask boundary drains the engine's coalesced (requestCommit) commit before asserting.
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+function setup(): { surface: ReturnType<typeof createSurface>; renderer: SymbioteRenderer } {
+  const surface = createSurface(ROOT_TAG);
+  const renderer = new SymbioteRendererFactory(surface).createRenderer(null, null);
+  if (!(renderer instanceof SymbioteRenderer))
+    throw new Error('unreachable: factory built the renderer');
+  return { surface, renderer };
+}
+
+beforeEach(() => fabric.reset());
+afterEach(() => {
+  disposeRoot(ROOT_TAG);
+  clearGlobalStyles();
+});
+
+describe('Angular SymbioteRenderer drives the engine', () => {
+  it('maps createElement / createText / appendChild into a committed Fabric tree', async () => {
+    const { surface, renderer } = setup();
+    const view = renderer.createElement('symbiote-view');
+    const text = renderer.createElement('symbiote-text');
+    const raw = renderer.createText('Hello');
+    renderer.appendChild(text, raw);
+    renderer.appendChild(view, text);
+    renderer.appendChild(surface, view);
+    await tick();
+
+    // The engine wraps surface.children in the synthetic box-none AppContainer root.
+    const root = fabric.appRoot();
+    expect(fabric.serialize(root.children)).toBe('RCTView(RCTText(RCTRawText "Hello"))');
+  });
+
+  it('maps additional symbiote intrinsics through the shared descriptor table', async () => {
+    const { surface, renderer } = setup();
+    const spinner = renderer.createElement('symbiote-activity-indicator');
+    renderer.setProperty(spinner, 'testID', 'spinner');
+    renderer.setProperty(spinner, 'animating', true);
+    const image = renderer.createElement('symbiote-image');
+    renderer.setProperty(image, 'testID', 'image');
+    renderer.setProperty(image, 'source', { uri: 'https://example.invalid/image.png' });
+    renderer.appendChild(surface, spinner);
+    renderer.appendChild(surface, image);
+    await tick();
+
+    const committed = fabric.find(node => node.props.testID === 'spinner');
+    expect(committed?.viewName).toBe('ActivityIndicatorView');
+    expect(committed?.props.animating).toBe(true);
+    const committedImage = fabric.find(node => node.props.testID === 'image');
+    expect(committedImage?.viewName).toBe('RCTImageView');
+    expect(committedImage?.props.source).toEqual({ uri: 'https://example.invalid/image.png' });
+  });
+
+  it('commits setProperty and merges per-key setStyle into one style prop', async () => {
+    const { surface, renderer } = setup();
+    const view = renderer.createElement('symbiote-view');
+    renderer.setProperty(view, 'nativeID', PROBE_ID);
+    renderer.setStyle(view, 'padding', 24);
+    renderer.setStyle(view, 'opacity', 0.5);
+    renderer.appendChild(surface, view);
+    await tick();
+
+    const committed = fabric.find(node => node.props.nativeID === PROBE_ID);
+    expect(committed, 'the probed RCTView committed').toBeDefined();
+    // Angular emits a [style] binding as per-key setStyle; the seam folds them into one style
+    // object, then the engine HOISTS style keys to top-level Fabric props (RN's flat C++ props
+    // contract — style is never a nested key on a committed node).
+    expect(committed?.props).toMatchObject({ nativeID: PROBE_ID, padding: 24, opacity: 0.5 });
+  });
+
+  it('resolves addClass tokens through the shared style registry and lets explicit style win', async () => {
+    registerStyles({ card: { padding: 10, backgroundColor: 'red' } });
+    const { surface, renderer } = setup();
+    const view = renderer.createElement('symbiote-view');
+    renderer.setProperty(view, 'nativeID', PROBE_ID);
+    // Ivy compiles class="card highlight" to one addClass call per token, never a single string.
+    renderer.addClass(view, 'card');
+    renderer.addClass(view, 'highlight');
+    renderer.setStyle(view, 'backgroundColor', 'blue');
+    renderer.appendChild(surface, view);
+    await tick();
+
+    const committed = fabric.find(node => node.props.nativeID === PROBE_ID);
+    // padding comes from the class; backgroundColor is explicit style, so it wins over the
+    // class-derived red — same precedence Vue's class="..."/:style="..." merge guarantees.
+    expect(committed?.props).toMatchObject({ padding: 10, backgroundColor: 'blue' });
+  });
+
+  it('removeClass drops a token and recomputes the resolved style', async () => {
+    registerStyles({ card: { padding: 10 }, highlight: { opacity: 0.5 } });
+    const { surface, renderer } = setup();
+    const view = renderer.createElement('symbiote-view');
+    renderer.setProperty(view, 'nativeID', PROBE_ID);
+    renderer.addClass(view, 'card');
+    renderer.addClass(view, 'highlight');
+    renderer.removeClass(view, 'highlight');
+    renderer.appendChild(surface, view);
+    await tick();
+
+    const committed = fabric.find(node => node.props.nativeID === PROBE_ID);
+    expect(committed?.props.padding).toBe(10);
+    expect(committed?.props.opacity).toBeUndefined();
+  });
+
+  it('removeChild detaches a node from the next commit', async () => {
+    const { surface, renderer } = setup();
+    const keep = renderer.createElement('symbiote-view');
+    const drop = renderer.createElement('symbiote-view');
+    renderer.setProperty(drop, 'nativeID', PROBE_ID);
+    renderer.appendChild(surface, keep);
+    renderer.appendChild(surface, drop);
+    await tick();
+    expect(
+      fabric.find(node => node.props.nativeID === PROBE_ID),
+      'present before remove',
+    ).toBeDefined();
+
+    fabric.reset();
+    renderer.removeChild(surface, drop);
+    await tick();
+    expect(
+      fabric.find(node => node.props.nativeID === PROBE_ID),
+      'gone after remove',
+    ).toBeUndefined();
+  });
+
+  it('createComment yields an anchor the commit walk skips but flattens its children', async () => {
+    const { surface, renderer } = setup();
+    const anchor = renderer.createComment();
+    renderer.appendChild(anchor, renderer.createElement('symbiote-view'));
+    renderer.appendChild(surface, anchor);
+    renderer.appendChild(surface, renderer.createElement('symbiote-text'));
+    await tick();
+
+    // The anchor never reaches Fabric; its child keeps the same sibling position. Angular
+    // composed components use this to make their framework host element disappear.
+    const root = fabric.appRoot();
+    expect(fabric.serialize(root.children)).toBe('RCTViewRCTText');
+  });
+
+  it('listen attaches an explicit event listener and the unlisten fn removes it', () => {
+    const { renderer } = setup();
+    const view = renderer.createElement('symbiote-view');
+    expect(isSymbioteNode(view)).toBe(true);
+    if (!isSymbioteNode(view)) throw new Error('unreachable: createElement returns a node');
+
+    const unlisten = renderer.listen(view, 'press', () => {});
+    expect(view.listeners?.has('press'), 'listener attached under the explicit name').toBe(true);
+    unlisten();
+    expect(view.listeners?.has('press'), 'unlisten removed it').toBe(false);
+  });
+
+  it('listen on a global target (window/document) is an inert no-op', () => {
+    const { renderer } = setup();
+    expect(() => renderer.listen('window', 'resize', () => {})()).not.toThrow();
+  });
+});