@symbiote-native/angular 0.1.0

package/src/components/activity-indicator/shared.ts

@@ -0,0 +1,206 @@
+import { Directive, ElementRef, EventEmitter, inject, Input, Output } from '@angular/core';
+import {
+  renderActivityIndicator,
+  resolveAccessibilityProps,
+  type IAccessibilityProps,
+  type IAccessibilityStateValue,
+  type IActivityIndicatorPlatform,
+  type IActivityIndicatorProps,
+  type IActivityIndicatorSize,
+  type IAriaProps,
+} from '@symbiote-native/components';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type { IDescriptor } from '@symbiote-native/components';
+import { anchorHostStyle } from '../../primitives';
+
+export type { IActivityIndicatorProps, IActivityIndicatorSize } from '@symbiote-native/components';
+
+// Narrows anchorHostStyle's `unknown` (it reads an opaque engine prop bag) to the shape
+// IActivityIndicatorProps['style'] actually declares, the same runtime guard image/shared.ts's
+// asStyle() uses for the identical reason — a style value is structurally opaque at the type
+// level, so this only rules out non-objects, never validates individual style keys.
+function asStyle(value: unknown): IActivityIndicatorProps['style'] {
+  return typeof value === 'object' && value !== null ? value : undefined;
+}
+
+// What the component itself takes as plain @Input()s: the full shared, cross-adapter
+// IActivityIndicatorProps surface minus onLayout and the accessibility callbacks, which it
+// exposes as real @Output() EventEmitters instead (see the class below), mirroring Pressable's
+// IAngularPressableInputs split.
+export type IActivityIndicatorInputs = Omit<
+  IActivityIndicatorProps,
+  | 'onLayout'
+  | 'onAccessibilityAction'
+  | 'onAccessibilityTap'
+  | 'onMagicTap'
+  | 'onAccessibilityEscape'
+>;
+
+@Directive()
+export abstract class ActivityIndicatorBase implements IActivityIndicatorInputs {
+  @Input() animating?: boolean;
+  @Input() color?: string;
+  @Input() hidesWhenStopped?: boolean;
+  @Input() nativeID?: string;
+  @Input() size?: IActivityIndicatorSize;
+  @Input() style?: IActivityIndicatorProps['style'];
+  @Input() testID?: string;
+  // Real @Output()s. This component renders through DescriptorOutlet (`symbiote-descriptor-
+  // outlet`), not a hand-written template: emitterHandler() below wraps each EventEmitter into a
+  // plain callback under the SAME onX key the shared, cross-adapter IActivityIndicatorProps
+  // expects, so the Descriptor's props bag still carries a function the engine's routeProp
+  // recognizes and routes to setEventListener — the outlet's renderer.setProperty call never
+  // sees an EventEmitter, only the wrapper.
+  @Output() readonly layout = new EventEmitter<ISymbioteEvent>();
+
+  @Input() accessible?: boolean;
+  @Input() accessibilityLabel?: string;
+  @Input() accessibilityHint?: string;
+  @Input() accessibilityRole?: IAccessibilityProps['accessibilityRole'];
+  @Input() accessibilityState?: IAccessibilityStateValue;
+  @Input() accessibilityValue?: IAccessibilityProps['accessibilityValue'];
+  @Input() accessibilityActions?: IAccessibilityProps['accessibilityActions'];
+  @Input() accessibilityLabelledBy?: string | string[];
+  @Input() importantForAccessibility?: IAccessibilityProps['importantForAccessibility'];
+  @Input() accessibilityLiveRegion?: IAccessibilityProps['accessibilityLiveRegion'];
+  @Input() screenReaderFocusable?: boolean;
+  @Input() accessibilityViewIsModal?: boolean;
+  @Input() accessibilityElementsHidden?: boolean;
+  @Input() accessibilityIgnoresInvertColors?: boolean;
+  @Input() accessibilityLanguage?: string;
+  @Input() accessibilityRespondsToUserInteraction?: boolean;
+  @Input() accessibilityShowsLargeContentViewer?: boolean;
+  @Input() accessibilityLargeContentTitle?: string;
+  @Output() readonly accessibilityAction = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  @Input() role?: IAriaProps['role'];
+  @Input('aria-label') ariaLabel?: string;
+  @Input('aria-labelledby') ariaLabelledBy?: string;
+  @Input('aria-live') ariaLive?: IAriaProps['aria-live'];
+  @Input('aria-hidden') ariaHidden?: boolean;
+  @Input('aria-busy') ariaBusy?: boolean;
+  @Input('aria-checked') ariaChecked?: boolean | 'mixed';
+  @Input('aria-disabled') ariaDisabled?: boolean;
+  @Input('aria-expanded') ariaExpanded?: boolean;
+  @Input('aria-selected') ariaSelected?: boolean;
+  @Input('aria-modal') ariaModal?: boolean;
+  @Input('aria-valuemax') ariaValueMax?: number;
+  @Input('aria-valuemin') ariaValueMin?: number;
+  @Input('aria-valuenow') ariaValueNow?: number;
+  @Input('aria-valuetext') ariaValueText?: string;
+
+  protected abstract readonly defaultColor: string | null;
+  protected readonly nativeExtras: Readonly<Record<string, unknown>> = {};
+
+  // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
+  // onto (see anchorHostStyle's doc comment) — NOT the descriptor-outlet-rendered wrapper the
+  // `descriptor` getter below builds. Merged FIRST so an explicit `style` @Input still wins
+  // (flattenStyle's later-wins collapse), mirroring every other composed component's anchor merge.
+  private readonly elementRef = inject(ElementRef);
+
+  // Stable bound wrappers (created ONCE, not per `descriptor` access) fed to emitterHandler below.
+  // jsonEqual (core/engine/src/commit.ts) falls through to Object.is for a function leaf, so a
+  // fresh closure built inside the `descriptor` getter would never equal the previous frame's
+  // closure even when nothing changed — every CD pass would read as "props changed" and force a
+  // real Fabric re-clone cascading up every ancestor to the root (the same hazard
+  // AnimatedComponentBase.reconcile() and ScrollViewStickyHeader's onHostLayout guard against).
+  private readonly onLayoutHandler = (event: ISymbioteEvent): void => this.layout.emit(event);
+  private readonly onAccessibilityActionHandler = (event: ISymbioteEvent): void =>
+    this.accessibilityAction.emit(event);
+  private readonly onAccessibilityTapHandler = (event: ISymbioteEvent): void =>
+    this.accessibilityTap.emit(event);
+  private readonly onMagicTapHandler = (event: ISymbioteEvent): void => this.magicTap.emit(event);
+  private readonly onAccessibilityEscapeHandler = (event: ISymbioteEvent): void =>
+    this.accessibilityEscape.emit(event);
+
+  get descriptor(): IDescriptor {
+    const props = resolveAccessibilityProps<IActivityIndicatorProps>({
+      animating: this.animating,
+      color: this.color,
+      hidesWhenStopped: this.hidesWhenStopped,
+      nativeID: this.nativeID,
+      size: this.size,
+      style: [asStyle(anchorHostStyle(this.elementRef)), this.style],
+      testID: this.testID,
+      onLayout: this.emitterHandler(this.layout, this.onLayoutHandler),
+      accessible: this.accessible,
+      accessibilityLabel: this.accessibilityLabel,
+      accessibilityHint: this.accessibilityHint,
+      accessibilityRole: this.accessibilityRole,
+      accessibilityState: this.accessibilityState,
+      accessibilityValue: this.accessibilityValue,
+      accessibilityActions: this.accessibilityActions,
+      accessibilityLabelledBy: this.accessibilityLabelledBy,
+      importantForAccessibility: this.importantForAccessibility,
+      accessibilityLiveRegion: this.accessibilityLiveRegion,
+      screenReaderFocusable: this.screenReaderFocusable,
+      accessibilityViewIsModal: this.accessibilityViewIsModal,
+      accessibilityElementsHidden: this.accessibilityElementsHidden,
+      accessibilityIgnoresInvertColors: this.accessibilityIgnoresInvertColors,
+      accessibilityLanguage: this.accessibilityLanguage,
+      accessibilityRespondsToUserInteraction: this.accessibilityRespondsToUserInteraction,
+      accessibilityShowsLargeContentViewer: this.accessibilityShowsLargeContentViewer,
+      accessibilityLargeContentTitle: this.accessibilityLargeContentTitle,
+      onAccessibilityAction: this.emitterHandler(
+        this.accessibilityAction,
+        this.onAccessibilityActionHandler,
+      ),
+      onAccessibilityTap: this.emitterHandler(
+        this.accessibilityTap,
+        this.onAccessibilityTapHandler,
+      ),
+      onMagicTap: this.emitterHandler(this.magicTap, this.onMagicTapHandler),
+      onAccessibilityEscape: this.emitterHandler(
+        this.accessibilityEscape,
+        this.onAccessibilityEscapeHandler,
+      ),
+      role: this.role,
+      'aria-label': this.ariaLabel,
+      'aria-labelledby': this.ariaLabelledBy,
+      'aria-live': this.ariaLive,
+      'aria-hidden': this.ariaHidden,
+      'aria-busy': this.ariaBusy,
+      'aria-checked': this.ariaChecked,
+      'aria-disabled': this.ariaDisabled,
+      'aria-expanded': this.ariaExpanded,
+      'aria-selected': this.ariaSelected,
+      'aria-modal': this.ariaModal,
+      'aria-valuemax': this.ariaValueMax,
+      'aria-valuemin': this.ariaValueMin,
+      'aria-valuenow': this.ariaValueNow,
+      'aria-valuetext': this.ariaValueText,
+    });
+
+    const { animating, color, hidesWhenStopped, size, style, ...passthrough } = props;
+    return renderActivityIndicator(
+      {
+        animating: animating !== false,
+        color,
+        hidesWhenStopped: hidesWhenStopped !== false,
+        size: size ?? 'small',
+        style,
+        passthrough,
+      },
+      this.platform,
+    );
+  }
+
+  private get platform(): IActivityIndicatorPlatform {
+    return { defaultColor: this.defaultColor, nativeExtras: this.nativeExtras };
+  }
+
+  // Gates a STABLE bound handler behind `observed`, so an unbound event still resolves to
+  // `undefined` in the descriptor's props bag — the same "undefined means nobody cares" contract
+  // the old @Input() callback had, letting resolveAccessibilityProps drop the key entirely instead
+  // of handing the engine a no-op function. `handler` must be one of the readonly bound fields
+  // above, never a closure built here — see their doc comment for why.
+  private emitterHandler(
+    emitter: EventEmitter<ISymbioteEvent>,
+    handler: (event: ISymbioteEvent) => void,
+  ): ((event: ISymbioteEvent) => void) | undefined {
+    return emitter.observed ? handler : undefined;
+  }
+}

package/src/components/button.ts

@@ -0,0 +1,193 @@
+// Button for Angular. The minimal cross-platform button in RN's iOS shape (Button.js): a
+// TouchableOpacity wrapping a Text. The base text style, the role constant, and the color fold are
+// shared in @symbiote-native/components/view; here Angular only composes its TouchableOpacity + a
+// symbiote-text child and re-maps the few Button-owned props. The Angular twin of the React/Vue
+// adapter's Button. No JS-side platform branch, so this stays a flat single file (ADR 0026).
+//
+// RN's Button fixes accessibilityRole="button", marks the root accessible, and propagates `disabled`
+// into the accessibility state; those three win over any caller value. `title` becomes the Text
+// child; disabled forwards straight; touchSoundDisabled maps to the pressable's android_disableSound.
+// Every OTHER field of the shared IButtonProps (title, color, disabled, touchSoundDisabled, testID,
+// TV-focus, accessibility state) is agnostic and stays RE-EXPORTED from @symbiote-native/components verbatim
+// (<prop_types_split_agnostic_vs_per_adapter>). onPress and the four accessibility callbacks are the
+// exceptions: each is a real @Output() here (`press`, `accessibilityAction`, `accessibilityTap`,
+// `magicTap`, `accessibilityEscape`), mirroring the Vue adapter's Button, which forks the SAME onPress
+// field the same way (`Omit<ICoreButtonProps, 'onPress'>` + a `press` emit) — not a new precedent, the
+// existing one extended to accessibility.
+
+import {
+  CUSTOM_ELEMENTS_SCHEMA,
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  EventEmitter,
+  inject,
+  Input,
+  Output,
+} from '@angular/core';
+import {
+  BUTTON_ACCESSIBILITY_ROLE,
+  resolveButtonTextStyle,
+  type IAccessibilityProps,
+  type IAccessibilityStateValue,
+  type IAriaProps,
+  type IButtonProps as ICoreButtonProps,
+} from '@symbiote-native/components';
+import type { ISymbioteEvent, ITextStyle, IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import { anchorStyleProp, TextHost } from '../primitives';
+import { TouchableOpacity } from './touchable';
+
+export type IButtonProps = Omit<
+  ICoreButtonProps,
+  | 'onPress'
+  | 'onAccessibilityAction'
+  | 'onAccessibilityTap'
+  | 'onMagicTap'
+  | 'onAccessibilityEscape'
+>;
+
+@Component({
+  selector: 'Button',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  imports: [TouchableOpacity, TextHost],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <TouchableOpacity
+      [style]="anchorStyle"
+      (press)="press.emit($event)"
+      [disabled]="disabled"
+      [android_disableSound]="touchSoundDisabled"
+      [accessibilityRole]="buttonRole"
+      [accessible]="true"
+      [accessibilityState]="{ disabled }"
+      [testID]="testID"
+      [nativeID]="nativeID"
+      [hasTVPreferredFocus]="hasTVPreferredFocus"
+      [nextFocusDown]="nextFocusDown"
+      [nextFocusForward]="nextFocusForward"
+      [nextFocusLeft]="nextFocusLeft"
+      [nextFocusRight]="nextFocusRight"
+      [nextFocusUp]="nextFocusUp"
+      [accessibilityLabel]="accessibilityLabel"
+      [accessibilityHint]="accessibilityHint"
+      [accessibilityValue]="accessibilityValue"
+      [accessibilityActions]="accessibilityActions"
+      [accessibilityLabelledBy]="accessibilityLabelledBy"
+      [importantForAccessibility]="importantForAccessibility"
+      [accessibilityLiveRegion]="accessibilityLiveRegion"
+      [screenReaderFocusable]="screenReaderFocusable"
+      [accessibilityViewIsModal]="accessibilityViewIsModal"
+      [accessibilityElementsHidden]="accessibilityElementsHidden"
+      [accessibilityIgnoresInvertColors]="accessibilityIgnoresInvertColors"
+      [accessibilityLanguage]="accessibilityLanguage"
+      [accessibilityRespondsToUserInteraction]="accessibilityRespondsToUserInteraction"
+      [accessibilityShowsLargeContentViewer]="accessibilityShowsLargeContentViewer"
+      [accessibilityLargeContentTitle]="accessibilityLargeContentTitle"
+      (accessibilityAction)="accessibilityAction.emit($event)"
+      (accessibilityTap)="accessibilityTap.emit($event)"
+      (magicTap)="magicTap.emit($event)"
+      (accessibilityEscape)="accessibilityEscape.emit($event)"
+      [ariaLabel]="ariaLabel"
+      [ariaBusy]="ariaBusy"
+      [ariaChecked]="ariaChecked"
+      [ariaDisabled]="ariaDisabled"
+      [ariaExpanded]="ariaExpanded"
+      [ariaHidden]="ariaHidden"
+      [ariaLabelledBy]="ariaLabelledBy"
+      [ariaLive]="ariaLive"
+      [ariaSelected]="ariaSelected"
+      [ariaModal]="ariaModal"
+      [ariaValueMax]="ariaValueMax"
+      [ariaValueMin]="ariaValueMin"
+      [ariaValueNow]="ariaValueNow"
+      [ariaValueText]="ariaValueText"
+      [role]="role"
+    >
+      <symbiote-text [style]="textStyle">{{ title }}</symbiote-text>
+    </TouchableOpacity>
+  `,
+})
+export class Button implements IButtonProps {
+  // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
+  // onto (see anchorHostStyle's doc comment in primitives/shared.ts) — NOT the inner
+  // TouchableOpacity/Pressable one level down. RN's real Button takes no `style` prop, so this
+  // is the only style source forwarded.
+  private readonly elementRef = inject(ElementRef);
+
+  @Output() readonly press = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly accessibilityAction = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
+  @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // Button-owned props: title is the Text child, color/disabled fold into the label style, and
+  // touchSoundDisabled re-maps onto TouchableOpacity.
+  @Input() title = '';
+  @Input() color?: string;
+  @Input() disabled?: boolean;
+  @Input() touchSoundDisabled?: boolean;
+  @Input() testID?: string;
+
+  // TV-focus props (Button.js): inert on a phone host, forwarded through TouchableOpacity.
+  @Input() hasTVPreferredFocus?: boolean;
+  @Input() nextFocusDown?: number;
+  @Input() nextFocusForward?: number;
+  @Input() nextFocusLeft?: number;
+  @Input() nextFocusRight?: number;
+  @Input() nextFocusUp?: number;
+
+  // Accessibility surface (IAccessibilityProps). accessibilityRole, accessible, and
+  // accessibilityState are declared for surface completeness but Button forces its own
+  // (button / true / { disabled }); the caller value is ignored, mirroring RN's Button.js.
+  @Input() nativeID?: string;
+  @Input() accessible?: boolean;
+  @Input() accessibilityLabel?: string;
+  @Input() accessibilityHint?: string;
+  @Input() accessibilityRole?: IAccessibilityProps['accessibilityRole'];
+  @Input() accessibilityState?: IAccessibilityStateValue;
+  @Input() accessibilityValue?: IAccessibilityProps['accessibilityValue'];
+  @Input() accessibilityActions?: IAccessibilityProps['accessibilityActions'];
+  @Input() accessibilityLabelledBy?: string | string[];
+  @Input() importantForAccessibility?: IAccessibilityProps['importantForAccessibility'];
+  @Input() accessibilityLiveRegion?: IAccessibilityProps['accessibilityLiveRegion'];
+  @Input() screenReaderFocusable?: boolean;
+  @Input() accessibilityViewIsModal?: boolean;
+  @Input() accessibilityElementsHidden?: boolean;
+  @Input() accessibilityIgnoresInvertColors?: boolean;
+  @Input() accessibilityLanguage?: string;
+  @Input() accessibilityRespondsToUserInteraction?: boolean;
+  @Input() accessibilityShowsLargeContentViewer?: boolean;
+  @Input() accessibilityLargeContentTitle?: string;
+
+  // Web-alias a11y surface (IAriaProps). External dashed aliases are exposed as Angular inputs and
+  // forwarded to TouchableOpacity's camelCase aria inputs.
+  @Input() role?: IAriaProps['role'];
+  @Input('aria-label') ariaLabel?: string;
+  @Input('aria-labelledby') ariaLabelledBy?: string;
+  @Input('aria-live') ariaLive?: IAriaProps['aria-live'];
+  @Input('aria-hidden') ariaHidden?: boolean;
+  @Input('aria-busy') ariaBusy?: boolean;
+  @Input('aria-checked') ariaChecked?: boolean | 'mixed';
+  @Input('aria-disabled') ariaDisabled?: boolean;
+  @Input('aria-expanded') ariaExpanded?: boolean;
+  @Input('aria-selected') ariaSelected?: boolean;
+  @Input('aria-modal') ariaModal?: boolean;
+  @Input('aria-valuemax') ariaValueMax?: number;
+  @Input('aria-valuemin') ariaValueMin?: number;
+  @Input('aria-valuenow') ariaValueNow?: number;
+  @Input('aria-valuetext') ariaValueText?: string;
+
+  // RN's Button is always accessibilityRole="button"; the shared role constant, not a literal.
+  readonly buttonRole = BUTTON_ACCESSIBILITY_ROLE;
+
+  // The label style with the caller color tinted in and `disabled` greying it out (disabled wins),
+  // computed by the shared fold so every adapter paints the identical button.
+  get textStyle(): ITextStyle {
+    return resolveButtonTextStyle(this.color, this.disabled);
+  }
+
+  get anchorStyle(): IStyleProp<IViewStyle> | undefined {
+    return anchorStyleProp<IViewStyle>(this.elementRef);
+  }
+}

package/src/components/flat-list/column-wrapper-style-class.test.ts

@@ -0,0 +1,116 @@
+// Regression guard: columnWrapperStyle previously accepted ONLY a JS style object/array. It now
+// also resolves a class-name string through the shared style registry, merged onto the same
+// flex-row wrapper as an object/array value (see index.ts's ngOnChanges). Mirrors the Vue twin
+// (column-wrapper-style-class.test.ts) and flat-list.test.ts's row-packing shape.
+import '@angular/compiler';
+import { Component } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { clearGlobalStyles, registerStyles } from '@symbiote-native/engine';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+
+import { mount, unmount } from '../../render';
+import { FlatList } from './index';
+import { VListItemDirective } from '../virtualized-list/directives';
+
+const ROOT_TAG = 953;
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+interface IRow {
+  id: string;
+  label: string;
+}
+
+const rows: IRow[] = Array.from({ length: 4 }, (_unused, index) => ({
+  id: `r-${index}`,
+  label: `row-${index}`,
+}));
+
+function walk(nodes: IFakeNode[], visit: (node: IFakeNode) => void): void {
+  for (const node of nodes) {
+    visit(node);
+    walk(node.children, visit);
+  }
+}
+
+function rowsWithFlexDirection(): IFakeNode[] {
+  const found: IFakeNode[] = [];
+  walk(fabric.committed, node => {
+    if (node.viewName === 'RCTView' && node.props.flexDirection === 'row') found.push(node);
+  });
+  return found;
+}
+
+@Component({
+  selector: 'symbiote-flatlist-column-style-class-host',
+  standalone: true,
+  imports: [FlatList, VListItemDirective],
+  template: `
+    <FlatList
+      [data]="rows"
+      [numColumns]="2"
+      [keyExtractor]="keyExtractor"
+      [columnWrapperStyle]="'gap8'"
+    >
+      <ng-template vListItem let-item>
+        <symbiote-text [testID]="item.id">{{ item.label }}</symbiote-text>
+      </ng-template>
+    </FlatList>
+  `,
+})
+class FlatListColumnStyleClassHost {
+  rows = rows;
+  keyExtractor = (item: IRow): string => item.id;
+}
+
+@Component({
+  selector: 'symbiote-flatlist-column-style-object-host',
+  standalone: true,
+  imports: [FlatList, VListItemDirective],
+  template: `
+    <FlatList
+      [data]="rows"
+      [numColumns]="2"
+      [keyExtractor]="keyExtractor"
+      [columnWrapperStyle]="{ gap: 4 }"
+    >
+      <ng-template vListItem let-item>
+        <symbiote-text [testID]="item.id">{{ item.label }}</symbiote-text>
+      </ng-template>
+    </FlatList>
+  `,
+})
+class FlatListColumnStyleObjectHost {
+  rows = rows;
+  keyExtractor = (item: IRow): string => item.id;
+}
+
+beforeEach(() => {
+  fabric.reset();
+  registerStyles({ gap8: { gap: 8 } });
+});
+afterEach(() => {
+  unmount(ROOT_TAG);
+  clearGlobalStyles();
+});
+
+describe('FlatList columnWrapperStyle class-name support', () => {
+  it('resolves a class-name string onto the row wrapper alongside flexDirection', async () => {
+    mount(ROOT_TAG, FlatListColumnStyleClassHost);
+    await tick();
+    await tick();
+
+    const found = rowsWithFlexDirection();
+    expect(found.length, 'two flex-row rows for 4 items in 2 columns').toBe(2);
+    expect(found[0].props.gap).toBe(8);
+  });
+
+  it('still accepts an ordinary style object unchanged', async () => {
+    mount(ROOT_TAG, FlatListColumnStyleObjectHost);
+    await tick();
+    await tick();
+
+    const found = rowsWithFlexDirection();
+    expect(found[0].props.gap).toBe(4);
+  });
+});

package/src/components/flat-list/flat-list-array-style.test.ts

@@ -0,0 +1,131 @@
+import '@angular/compiler';
+import { Component } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import { flattenStyle } from '@symbiote-native/engine';
+
+import { mount, unmount } from '../../render';
+import { FlatList } from './index';
+import { VListItemDirective } from '../virtualized-list/directives';
+
+const ROOT_TAG = 905;
+const fabric = installFabric();
+
+interface IChip {
+  id: string;
+  n: number;
+}
+
+const chips: IChip[] = Array.from({ length: 24 }, (_unused, index) => ({
+  id: `c-${index}`,
+  n: index,
+}));
+
+// Regression coverage for a real device bug: Angular compiles a literal `[style]="…"` binding to
+// the built-in ɵɵstyleMap instruction (NOT a regular @Input() property write), regardless of the
+// target's declared type — it only understands a flat style object, never an array. RN's own
+// `style={[base, override]}` composition idiom (used by examples/angular/App.ts's "FlatList · 24
+// chips" demo for the per-item computed backgroundColor) crashed deep inside Angular's own styling
+// engine (`prop.indexOf is not a function`), and the crash landed inside a zoneless
+// SymbioteChangeDetectionScheduler tick with no catch around it — so the retry kept re-firing
+// forever (RAM climbing, constant re-render log spam on device) while the item never painted its
+// style. Fixed by flattening any array-composed style with the engine's own `flattenStyle` before
+// it reaches a `[style]=` binding — required of app authors (see App.ts) AND of every adapter
+// component that forwards its own `style` @Input() onward (see the `resolvedStyle` getters/fields
+// in virtualized-list, section-list, virtualized-section-list — flat-list's own `rowStyle` had the
+// identical landmine, always assigning an array). See the angular-adapter skill for the full story.
+@Component({
+  selector: 'symbiote-chip-list-host',
+  standalone: true,
+  imports: [FlatList, VListItemDirective],
+  template: `
+    <FlatList
+      testID="chips-list"
+      [data]="chips"
+      [horizontal]="true"
+      [keyExtractor]="keyExtractor"
+      [getItemLayout]="getItemLayout"
+      [style]="{ height: 84 }"
+    >
+      <ng-template vListItem let-item>
+        <symbiote-view
+          [testID]="'chip-' + item.n"
+          [style]="flattenStyle([{ height: 72, width: 64 }, { backgroundColor: chipColor(item) }])"
+        >
+          <symbiote-text>{{ item.n }}</symbiote-text>
+        </symbiote-view>
+      </ng-template>
+    </FlatList>
+  `,
+})
+class ChipListHost {
+  chips = chips;
+  flattenStyle = flattenStyle;
+  keyExtractor = (item: IChip): string => item.id;
+  getItemLayout = (
+    _data: unknown,
+    index: number,
+  ): { length: number; offset: number; index: number } => ({
+    length: 64,
+    offset: 64 * index,
+    index,
+  });
+  chipColor(item: IChip): string {
+    return `hsl(${(item.n * 47) % 360}, 70%, 50%)`;
+  }
+}
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function findCommitted(
+  nodes: typeof fabric.committed,
+  predicate: (n: (typeof nodes)[number]) => boolean,
+): (typeof nodes)[number] | undefined {
+  for (const node of nodes) {
+    if (predicate(node)) return node;
+    const found = findCommitted(node.children, predicate);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+describe('FlatList array-composed item style', () => {
+  it('flattens to a plain object instead of crashing ɵɵstyleMap, and commits it', async () => {
+    mount(ROOT_TAG, ChipListHost);
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+
+    const chip0 = findCommitted(fabric.committed, node => node.props.testID === 'chip-0');
+    expect(chip0?.props).toMatchObject({
+      height: 72,
+      width: 64,
+      backgroundColor: 'hsl(0, 70%, 50%)',
+    });
+  });
+
+  it('does not free-run change detection once the window settles', async () => {
+    mount(ROOT_TAG, ChipListHost);
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+
+    const scroll = fabric.find(node => node.viewName === 'RCTScrollView');
+    if (scroll !== undefined) {
+      fabric.fireEvent(scroll.instanceHandle, 'topLayout', {
+        layout: { x: 0, y: 0, width: 360, height: 84 },
+      });
+    }
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+
+    let previous = fabric.counts.completeRoot;
+    let stillGrowing = false;
+    for (let tick = 0; tick < 10; tick += 1) {
+      await new Promise<void>(resolve => setTimeout(resolve, 0));
+      const current = fabric.counts.completeRoot;
+      if (current > previous) stillGrowing = true;
+      previous = current;
+    }
+    expect(stillGrowing).toBe(false);
+  });
+});