@symbiote-native/angular 0.6.2 → 0.8.0

package/src/diagnostics.ts

@@ -0,0 +1,138 @@
+// Per-window counters for the Angular adapter, the twin of the engine's readCommitProfile().
+// The engine's number answers "what did the commit walk cost"; these answer the question one layer
+// up, which is the one Angular keeps losing: HOW MANY TIMES did anything run at all.
+//
+// Angular is the only adapter whose update model can free-run. A change-detection pass that writes
+// a fresh reference into a downstream @Input marks a view dirty, the zoneless scheduler books
+// another pass, and it never settles - the hazard `stableAnchorStyle` and VirtualizedList's
+// `lastRecompute` gate each guard one instance of. A guard that stops holding is INVISIBLE from the
+// outside: the screen paints correctly, only the frame rate collapses. `cdPasses` at rest is what
+// makes it visible, and every other counter here narrows the same window to a suspect.
+//
+// Deliberately NOT gated behind isDebug(): an integer increment is noise next to the work it
+// counts, and the numbers are only meaningful from a RELEASE build (dev-mode Angular runs its own
+// checks and drowns the signal). The per-name detail map IS gated, since it allocates.
+
+export interface IAngularProfile {
+  // Change-detection passes: RendererFactory2.end() runs once per ApplicationRef.tick().
+  cdPasses: number;
+  // Primitive host views (symbiote-view / symbiote-text / ...) Angular actually walked. Divided by
+  // cdPasses this is the SIZE OF THE TREE one tick touches - the number that separates "the list is
+  // expensive" from "every mounted screen is re-checked because a list scrolled". The primitives are
+  // CheckAlways, and a Global tick refreshes every CheckAlways view in the application.
+  viewsChecked: number;
+  // Prop/style/class/text writes that reached the engine. At rest this must be 0: a nonzero idle
+  // value means change detection is rewriting props nothing asked to change.
+  rendererWrites: number;
+  nodesCreated: number;
+  nodesInserted: number;
+  nodesRemoved: number;
+  // The `class` poll every COMPOSED component runs per check (SymbioteStyleInputDirective: Pressable,
+  // ScrollView, Image, the lists...; the raw primitives are counted by `viewsChecked` instead).
+  // `styleMarks` is how often the poll actually found a change and dirtied the view - the ratio is
+  // how much of the polling is wasted, and a nonzero idle `styleMarks` is a free-run engine.
+  styleChecks: number;
+  styleMarks: number;
+  // VirtualizedList: checks vs the ones that got past the `lastRecompute` dedup gate. Recomputes
+  // climbing with checks means the gate is not holding, which is the free-run bug itself.
+  listChecks: number;
+  listRecomputes: number;
+  listMarks: number;
+  // Scroll events the list saw. With sticky headers RN pins scrollEventThrottle to 1, so this is
+  // the frame rate of the gesture and the denominator for everything measured during a drag.
+  scrollTicks: number;
+  // Cell views. `outletUpdates` is the cheap path (context patched in place); `outletCreates` past
+  // the first window means cells are being rebuilt instead of reused, which is the cost CDK's
+  // view-recycling strategy exists to avoid.
+  outletCreates: number;
+  outletUpdates: number;
+  outletDestroys: number;
+  // Sticky projection: schedules are cheap (a Set insert), flushes walk every projected record.
+  projectionSchedules: number;
+  projectionFlushes: number;
+  // A sticky wrapper rebuilt loses its measured layout and costs a native round trip; reuse is the
+  // fixed path. Creates climbing during a plain scroll is the regression this pair pins.
+  stickyWrapperCreates: number;
+  stickyWrapperReuses: number;
+}
+
+type IAngularCounter = keyof IAngularProfile;
+
+function createCounters(): IAngularProfile {
+  return {
+    cdPasses: 0,
+    viewsChecked: 0,
+    rendererWrites: 0,
+    nodesCreated: 0,
+    nodesInserted: 0,
+    nodesRemoved: 0,
+    styleChecks: 0,
+    styleMarks: 0,
+    listChecks: 0,
+    listRecomputes: 0,
+    listMarks: 0,
+    scrollTicks: 0,
+    outletCreates: 0,
+    outletUpdates: 0,
+    outletDestroys: 0,
+    projectionSchedules: 0,
+    projectionFlushes: 0,
+    stickyWrapperCreates: 0,
+    stickyWrapperReuses: 0,
+  };
+}
+
+let counters = createCounters();
+
+export function countAngular(counter: IAngularCounter): void {
+  counters[counter] += 1;
+}
+
+// Reading zeroes the counters, so a sampler on an interval gets disjoint windows rather than a
+// growing total - same contract as readCommitProfile().
+export function readAngularProfile(): IAngularProfile {
+  const snapshot = counters;
+  counters = createCounters();
+  return snapshot;
+}
+
+// Which prop names the renderer actually rewrites, and which host tags get created. Off by default
+// because it allocates per write; the probe screen turns it on for one sample. A write nothing
+// asked for is the whole diagnosis, and the prop NAME is what points at the binding responsible.
+let isDetailEnabled = false;
+const writesByProp = new Map<string, number>();
+const createsByTag = new Map<string, number>();
+
+export function setAngularProfileDetail(enabled: boolean): void {
+  isDetailEnabled = enabled;
+  if (!enabled) {
+    writesByProp.clear();
+    createsByTag.clear();
+  }
+}
+
+export function noteAngularWrite(propName: string): void {
+  if (!isDetailEnabled) return;
+  writesByProp.set(propName, (writesByProp.get(propName) ?? 0) + 1);
+}
+
+export function noteAngularCreate(tagName: string): void {
+  if (!isDetailEnabled) return;
+  createsByTag.set(tagName, (createsByTag.get(tagName) ?? 0) + 1);
+}
+
+export interface IAngularProfileDetail {
+  writesByProp: readonly (readonly [string, number])[];
+  createsByTag: readonly (readonly [string, number])[];
+}
+
+// Sorted hottest-first and read-and-cleared, so a sample names its own top offenders.
+export function readAngularProfileDetail(): IAngularProfileDetail {
+  const detail = {
+    writesByProp: [...writesByProp.entries()].sort((a, b) => b[1] - a[1]),
+    createsByTag: [...createsByTag.entries()].sort((a, b) => b[1] - a[1]),
+  };
+  writesByProp.clear();
+  createsByTag.clear();
+  return detail;
+}

package/src/host-instance/index.ts

@@ -13,14 +13,19 @@
 // An uncommitted or unknown input surfaces as null.
 
 import { ElementRef } from '@angular/core';
-import { getNativeTag, isSymbioteNode, type ISymbioteNode } from '@symbiote-native/engine';
+import {
+  getNativeTag,
+  isSymbioteNode,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
 
 export type { IHostInstance } from '@symbiote-native/engine';
 
 function resolveHostNode(candidate: unknown): ISymbioteNode | null {
   if (candidate === null || candidate === undefined) return null;
   if (isSymbioteNode(candidate)) return candidate;
-  if (candidate instanceof ElementRef) return resolveHostNode(candidate.nativeElement);
+  if (candidate instanceof ElementRef)
+    return resolveHostNode(candidate.nativeElement);
   const maybeHost = candidate as { nativeElement?: unknown };
   if (typeof maybeHost.nativeElement !== 'undefined') {
     return resolveHostNode(maybeHost.nativeElement);
@@ -29,7 +34,8 @@ function resolveHostNode(candidate: unknown): ISymbioteNode | null {
 }
 
 export function findNodeHandle(componentOrHandle: unknown): number | null {
-  if (componentOrHandle === null || componentOrHandle === undefined) return null;
+  if (componentOrHandle === null || componentOrHandle === undefined)
+    return null;
   if (typeof componentOrHandle === 'number') return componentOrHandle;
   const node = resolveHostNode(componentOrHandle);
   return node ? (getNativeTag(node) ?? null) : null;

package/src/index.ts

@@ -27,6 +27,7 @@ export {
   stableAnchorStyle,
   Switch,
   SymbioteHostPropsDirective,
+  SymbioteStyleInputDirective,
   Text,
   TextInput,
   TouchableHighlight,
@@ -60,6 +61,16 @@ export {
   AnimatedText,
   AnimatedView,
 } from './modules/animated';
+// Exported even though Angular's version maps only the four primitives (View/Text/Image/
+// ScrollView) onto the pre-authored wrappers above and THROWS on anything else — there is no JIT
+// under AOT/Metro, so it cannot synthesize a wrapper at runtime the way the other four adapters
+// do. It ships anyway because portable code (`createAnimatedComponent(View)`) then compiles and
+// runs identically on all five adapters, and the one case Angular cannot serve fails with a
+// message naming the fix (author a standalone @Component over AnimatedComponentBase) instead of
+// failing as a missing export, which names nothing. Found by the barrel audit in
+// `.claude/rules/adapter-parity-audit.md`: it was implemented and tested here all along and simply
+// never reached this file, so `@symbiote-native/angular` consumers could not reach it at all.
+export { createAnimatedComponent } from './modules/animated';
 export type {
   IActivityIndicatorProps,
   IAngularImageBackgroundProps,
@@ -134,7 +145,12 @@ export { DescriptorOutlet } from './descriptor-to-angular';
 // idiom) parameterized by an `@Input()`, rather than a factory returning fresh components per
 // call.
 export { PortalDirective, PortalOutletDirective } from './create-portal';
-export { createTunnel, TunnelInDirective, TunnelOut, type ITunnelStore } from './create-tunnel';
+export {
+  createTunnel,
+  TunnelInDirective,
+  TunnelOut,
+  type ITunnelStore,
+} from './create-tunnel';
 export { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
 // registerComposedComponent lives in the dependency-free leaf ./anchor-host-registry, NOT in the
 // require-cyclic ./renderer — see the leaf header. The babel-register-composed plugin injects the
@@ -249,7 +265,6 @@ export type {
 } from '@symbiote-native/engine';
 export {
   dlog,
-  flattenStyle,
   isDebug,
   Platform,
   processColor,
@@ -258,4 +273,47 @@ export {
   setNativeViewConfigSource,
   StyleSheet,
 } from '@symbiote-native/engine';
-export type { IRootTag, ISymbioteEvent, ISymbioteNode } from '@symbiote-native/engine';
+export type {
+  IRootTag,
+  ISymbioteEvent,
+  ISymbioteNode,
+} from '@symbiote-native/engine';
+// The agnostic style / platform / view-config types behind the values above. Angular takes its
+// component props as @Input()s and exports no per-component prop type, but an app still needs
+// these to type a style object or a Platform.select spec.
+export type {
+  IViewStyle,
+  ITextStyle,
+  IFlexAlign,
+  IFlexJustify,
+  IPlatformStatic,
+  IPlatformOSType,
+  IPlatformConstantsIOS,
+  IPlatformConstantsAndroid,
+  IPlatformSelectSpec,
+  INativeViewConfig,
+  INativeViewConfigSource,
+} from '@symbiote-native/engine';
+export type {
+  IAccessibilityProps,
+  IAriaProps,
+  IAccessibilityRole,
+  IRole,
+  IAccessibilityStateValue,
+  IAccessibilityValue,
+  IAccessibilityActionInfo,
+  IResponderProps,
+  IPressState,
+  IPressableAndroidRippleConfig,
+  IImageStatics,
+} from '@symbiote-native/components';
+
+// Diagnostics: per-window Angular-side counters (change-detection passes, renderer writes, list
+// recomputes, cell views). The engine's readCommitProfile() prices the commit; these say how many
+// times anything ran at all - the number that exposes a change-detection free-run.
+export {
+  readAngularProfile,
+  readAngularProfileDetail,
+  setAngularProfileDetail,
+} from './diagnostics';
+export type { IAngularProfile, IAngularProfileDetail } from './diagnostics';

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

@@ -1,101 +1,52 @@
-// 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.
+// Angular's binding of the shared AnimatedProps leaf lifecycle (core/engine's
+// createAnimatedLeafLifecycle). The POLICY - when to rebuild, when to skip, attach-new-before-
+// detach-old, native event rebinding - lives in the engine and is identical for every adapter;
+// this class supplies only the two things that are genuinely Angular's: how the host node is
+// resolved (a @ViewChild directive, not a ref), and the whenCommitted deferral its batched
+// change detection forces.
+//
+// Pure Fabrication (GRASP): kept as its own class rather than folded into AnimatedComponentBase so
+// AnimatedImage - which must extend ImageBase instead - gets the same wiring by composition rather
+// than copy-paste.
 import {
-  AnimatedProps,
-  attachNativeEventHandler,
-  dlog,
+  createAnimatedLeafLifecycle,
   whenCommitted,
+  type IAnimatedLeafLifecycle,
   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> = [];
+  private readonly lifecycle: IAnimatedLeafLifecycle;
 
   // `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
+  // 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);
+    label: string,
+  ) {
+    this.lifecycle = createAnimatedLeafLifecycle(label);
   }
 
-  // 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;
+  // Only the NATIVE half is deferred through whenCommitted (which runs it NOW when the node is
+  // already committed - the steady state, and the only path a scroll frame takes). The leaf itself
+  // always joins the value graph synchronously: deferring THAT too put the build behind a
+  // canceller the next reconcile drops, so a component reconciling faster than it commits never
+  // attached anything and a sticky header's rebuilt interpolation never reached the graph.
+  // Regression-covered in leaf-attach-before-commit.test.ts.
+  reconcile(props: Record<string, unknown>, wantsNative: boolean): void {
     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 = [];
+    this.lifecycle.reconcile(props, node, wantsNative, bind =>
+      node === null ? undefined : whenCommitted(node, bind),
+    );
   }
 
   // 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;
-    }
+    this.lifecycle.teardown();
   }
 }