@symbiote-native/angular 0.8.0 → 1.0.0

package/src/components/section-list/index.ts

@@ -100,6 +100,13 @@ export {
   VListHeaderDirective,
   VListSeparatorDirective,
 } from '../virtualized-list';
+import {
+  gateWanted,
+  injectGateDemandAbove,
+  provideGateDemand,
+  type IGateDemand,
+  type IGatedAccessibilityEvent,
+} from '../../gate-demand';
 
 // SectionList's public surface is exactly VirtualizedSectionList's (RN layers them one-for-one), so
 // the prop type is shared verbatim — no SectionList-only field exists.
@@ -123,6 +130,7 @@ export type ISectionListInputs<ItemT> = Omit<
 @Component({
   selector: 'SectionList',
   standalone: true,
+  viewProviders: [provideGateDemand(() => SectionList)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -381,6 +389,16 @@ export class SectionList<ItemT = unknown>
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   @Input() role?: IAriaProps['role'];
   @Input() ariaLabel?: string;
   @Input() ariaLabelledBy?: string;

package/src/components/switch/index.android.ts

@@ -10,7 +10,7 @@ import {
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import {
   anchorHostStyle,
-  SwitchHost,
+  ManagedSwitchHost,
   SymbioteHostPropsDirective,
   SymbioteStyleInputDirective,
 } from '../../primitives';
@@ -24,7 +24,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  imports: [SwitchHost, SymbioteHostPropsDirective],
+  imports: [ManagedSwitchHost, SymbioteHostPropsDirective],
   providers: [
     {
       provide: NG_VALUE_ACCESSOR,
@@ -54,7 +54,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
   ],
   outputs: ['valueChange', 'change'],
   template: `
-    <symbiote-switch
+    <symbiote-switch-managed
       #nativeSwitch="symbioteHost"
       [symbioteHostProps]="hostProps()"
       (change)="handleChange($event, nativeSwitch)"
@@ -63,7 +63,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
 })
 export class Switch extends SwitchBase implements DoCheck {
   // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
-  // onto (see anchorHostStyle's doc comment) — NOT the <symbiote-switch> leaf one level down.
+  // onto (see anchorHostStyle's doc comment) — NOT the <symbiote-switch-managed> leaf one level down.
   private readonly elementRef = inject(ElementRef);
 
   protected readonly platform = {

package/src/components/switch/index.ios.ts

@@ -10,7 +10,7 @@ import {
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import {
   anchorHostStyle,
-  SwitchHost,
+  ManagedSwitchHost,
   SymbioteHostPropsDirective,
   SymbioteStyleInputDirective,
 } from '../../primitives';
@@ -24,7 +24,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  imports: [SwitchHost, SymbioteHostPropsDirective],
+  imports: [ManagedSwitchHost, SymbioteHostPropsDirective],
   providers: [
     {
       provide: NG_VALUE_ACCESSOR,
@@ -54,7 +54,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
   ],
   outputs: ['valueChange', 'change'],
   template: `
-    <symbiote-switch
+    <symbiote-switch-managed
       #nativeSwitch="symbioteHost"
       [symbioteHostProps]="hostProps()"
       (change)="handleChange($event, nativeSwitch)"
@@ -63,7 +63,7 @@ export type { ISwitchProps, ISwitchTrackColor } from './shared';
 })
 export class Switch extends SwitchBase implements DoCheck {
   // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
-  // onto (see anchorHostStyle's doc comment) — NOT the <symbiote-switch> leaf one level down.
+  // onto (see anchorHostStyle's doc comment) — NOT the <symbiote-switch-managed> leaf one level down.
   private readonly elementRef = inject(ElementRef);
 
   protected readonly platform = {

package/src/components/text-input.ts

@@ -2,7 +2,7 @@
 // and the controlled-write predicate live in @symbiote-native/components/state, the render (intrinsic
 // + native-prop mapping) in @symbiote-native/components/view, both shared verbatim with the React and
 // Vue adapters. Here Angular supplies only the lifecycle: renderTextInput picks ONE of two host
-// intrinsics at runtime (symbiote-text-input / symbiote-text-input-multiline) via `@if`/`@else`,
+// intrinsics at runtime (symbiote-text-input-managed / …-multiline-managed) via `@if`/`@else`,
 // each wired through the shared `SymbioteHostPropsDirective` (`[symbioteHostProps]="hostProps"`,
 // `../primitives/shared.ts`) so the flat resolved prop bag doesn't need enumerating as individual
 // `[prop]` bindings; a @ViewChild reading that directive (by its `#host` template ref, across
@@ -73,6 +73,9 @@ import {
   setInputBlurred,
   setInputFocused,
   whenCommitted,
+  type IMeasureInWindowOnSuccess,
+  type IMeasureLayoutOnSuccess,
+  type IMeasureOnSuccess,
   type IStyleProp,
   type ISymbioteEvent,
   type ISymbioteNode,
@@ -80,11 +83,16 @@ import {
 } from '@symbiote-native/engine';
 import {
   anchorHostStyle,
-  MultilineTextInputHost,
+  ManagedMultilineTextInputHost,
   SymbioteHostPropsDirective,
   SymbioteStyleInputDirective,
-  TextInputHost,
+  ManagedTextInputHost,
 } from '../primitives';
+import {
+  gateWanted,
+  injectGateDemand,
+  type IGatedAccessibilityEvent,
+} from '../gate-demand';
 
 export type {
   ITextInputHandle,
@@ -169,7 +177,11 @@ export type IAngularTextInputInputs = Omit<
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  imports: [SymbioteHostPropsDirective, TextInputHost, MultilineTextInputHost],
+  imports: [
+    SymbioteHostPropsDirective,
+    ManagedTextInputHost,
+    ManagedMultilineTextInputHost,
+  ],
   changeDetection: ChangeDetectionStrategy.OnPush,
   providers: [
     {
@@ -180,7 +192,7 @@ export type IAngularTextInputInputs = Omit<
   ],
   template: `
     @if (isMultiline) {
-      <symbiote-text-input-multiline
+      <symbiote-text-input-multiline-managed
         #host
         [symbioteHostProps]="hostProps"
         (change)="handleChange($event)"
@@ -191,13 +203,9 @@ export type IAngularTextInputInputs = Omit<
         (keyPress)="emit(keyPress, $event)"
         (endEditing)="emit(endEditing, $event)"
         (contentSizeChange)="emit(contentSizeChange, $event)"
-        (accessibilityAction)="emit(accessibilityAction, $event)"
-        (accessibilityTap)="emit(accessibilityTap, $event)"
-        (magicTap)="emit(magicTap, $event)"
-        (accessibilityEscape)="emit(accessibilityEscape, $event)"
-      ></symbiote-text-input-multiline>
+      ></symbiote-text-input-multiline-managed>
     } @else {
-      <symbiote-text-input
+      <symbiote-text-input-managed
         #host
         [symbioteHostProps]="hostProps"
         (change)="handleChange($event)"
@@ -208,11 +216,7 @@ export type IAngularTextInputInputs = Omit<
         (keyPress)="emit(keyPress, $event)"
         (endEditing)="emit(endEditing, $event)"
         (contentSizeChange)="emit(contentSizeChange, $event)"
-        (accessibilityAction)="emit(accessibilityAction, $event)"
-        (accessibilityTap)="emit(accessibilityTap, $event)"
-        (magicTap)="emit(magicTap, $event)"
-        (accessibilityEscape)="emit(accessibilityEscape, $event)"
-      ></symbiote-text-input>
+      ></symbiote-text-input-managed>
     }
   `,
 })
@@ -282,6 +286,9 @@ export class TextInput
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
 
+  // Null unless a wrapper renders this TextInput in its own template. See `../gate-demand.ts`.
+  private readonly gateDemand = injectGateDemand();
+
   @Input() accessible?: boolean;
   @Input() accessibilityLabel?: string;
   @Input() accessibilityHint?: string;
@@ -318,7 +325,7 @@ export class TextInput
 
   // This component's OWN host — the non-painting anchor `class="..."` at the use site resolves
   // onto (see anchorHostStyle's doc comment) — NOT `hostRef` above, which targets the real inner
-  // symbiote-text-input(-multiline) one level down.
+  // symbiote-text-input-managed(-multiline-managed) one level down.
   private readonly elementRef = inject(ElementRef);
   // Only setDisabledState() needs this: it mutates `editable` from OUTSIDE Angular's own binding
   // path (@angular/forms calling in directly), which doesn't itself schedule a tick under zoneless CD.
@@ -458,6 +465,41 @@ export class TextInput
     if (isSymbioteEvent(event)) emitter.emit(event);
   }
 
+  // `undefined` means `setEventListener` never sees a function, so the gate stays dark. A demand
+  // from above overrides `.observed` for the same reason it does on Pressable: a wrapper's binding
+  // is not a subscriber (`../gate-demand.ts`).
+  private gatedAccessibilityHandler(
+    name: IGatedAccessibilityEvent,
+  ): ((event: unknown) => void) | undefined {
+    const emitter = this[name];
+    return gateWanted(this.gateDemand, name, emitter)
+      ? event => this.emit(emitter, event)
+      : undefined;
+  }
+
+  // Forwarded from the engine node so a TextInput ref is not poorer than any other host ref — an
+  // instance exposing only the five methods below CLOSES the node off (see ITextInputHandle's own
+  // comment). No Angular-specific state to add: these four pass straight through.
+  measure(callback: IMeasureOnSuccess): void {
+    this.hostNode?.measure(callback);
+  }
+
+  measureInWindow(callback: IMeasureInWindowOnSuccess): void {
+    this.hostNode?.measureInWindow(callback);
+  }
+
+  measureLayout(
+    relativeToNativeNode: ISymbioteNode | number,
+    onSuccess: IMeasureLayoutOnSuccess,
+    onFail?: () => void,
+  ): void {
+    this.hostNode?.measureLayout(relativeToNativeNode, onSuccess, onFail);
+  }
+
+  setNativeProps(nativeProps: Record<string, unknown>): void {
+    this.hostNode?.setNativeProps(nativeProps);
+  }
+
   // The imperative API RN exposes on a TextInput ref; in Angular the component instance IS the
   // handle (a parent reads it via @ViewChild(TextInput) and calls these). focus/blur drive native
   // view commands; clear and setSelection reuse setTextAndSelection (the same stale-safe path as a
@@ -531,6 +573,20 @@ export class TextInput
     return {
       ...this.foldedAccessibility,
       accessible: this.accessible,
+      // NOT template bindings, unlike every other event on this component's two host tags. These
+      // four are `on*`-GATED Fabric events (`.claude/rules/fabric-boolean-event-gates.md`): native
+      // fires them only when the committed payload carries a FUNCTION at that key, and a template
+      // `(accessibilityAction)="..."` binding is present unconditionally — so it lit all four gates
+      // on every TextInput in every app whether or not anything listened. Routed through the flat
+      // bag instead, the same shape Pressable uses.
+      onAccessibilityAction: this.gatedAccessibilityHandler(
+        'accessibilityAction',
+      ),
+      onAccessibilityTap: this.gatedAccessibilityHandler('accessibilityTap'),
+      onMagicTap: this.gatedAccessibilityHandler('magicTap'),
+      onAccessibilityEscape: this.gatedAccessibilityHandler(
+        'accessibilityEscape',
+      ),
       testID: this.testID,
       nativeID: this.nativeID,
       placeholder: this.placeholder,

package/src/components/touchable/index.ts

@@ -72,6 +72,13 @@ import {
 } from '../../primitives';
 import { Pressable, type IAngularPressableInputs } from '../pressable';
 import { Animated, AnimatedView } from '../../modules/animated';
+import {
+  gateWanted,
+  injectGateDemandAbove,
+  provideGateDemand,
+  type IGateDemand,
+  type IGatedAccessibilityEvent,
+} from '../../gate-demand';
 
 // The shared field base for all three: the Pressable INPUT surface (minus style, which each
 // Touchable routes differently, and minus the press/hover events, which each Touchable declares as
@@ -128,6 +135,7 @@ function createTimerScheduler(): ITimerScheduler {
 @Component({
   selector: 'TouchableOpacity',
   standalone: true,
+  viewProviders: [provideGateDemand(() => TouchableOpacity)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -136,6 +144,7 @@ function createTimerScheduler(): ITimerScheduler {
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
     <Pressable
+      [__minPressDuration]="0"
       (press)="press.emit($event)"
       (pressIn)="handlePressIn($event)"
       (pressOut)="handlePressOut($event)"
@@ -224,6 +233,16 @@ export class TouchableOpacity
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   @Input() activeOpacity?: number;
   @Input() delayPressIn?: number;
   @Input() delayPressOut?: number;
@@ -417,6 +436,7 @@ export class TouchableOpacity
 @Component({
   selector: 'TouchableHighlight',
   standalone: true,
+  viewProviders: [provideGateDemand(() => TouchableHighlight)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -424,6 +444,7 @@ export class TouchableOpacity
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
     <Pressable
+      [__minPressDuration]="0"
       [style]="containerStyle()"
       (press)="handlePress($event)"
       (pressIn)="handlePressIn($event)"
@@ -511,6 +532,16 @@ export class TouchableHighlight
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   // RN's onShowUnderlay / onHideUnderlay — fired on a real transition only, never on a repeat.
   @Output() readonly showUnderlay = new EventEmitter<void>();
   @Output() readonly hideUnderlay = new EventEmitter<void>();
@@ -693,6 +724,7 @@ export class TouchableHighlight
 @Component({
   selector: 'TouchableWithoutFeedback',
   standalone: true,
+  viewProviders: [provideGateDemand(() => TouchableWithoutFeedback)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -700,6 +732,7 @@ export class TouchableHighlight
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
     <Pressable
+      [__minPressDuration]="0"
       [style]="mergedStyle"
       (press)="press.emit($event)"
       (pressIn)="handlePressIn($event)"
@@ -791,6 +824,16 @@ export class TouchableWithoutFeedback
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   @Input() delayPressIn?: number;
   @Input() delayPressOut?: number;
   @Input() minPressDuration?: number;

package/src/components/touchable-native-feedback/index.ts

@@ -82,6 +82,7 @@ export type IAngularTouchableNativeFeedbackProps = Omit<
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
     <Pressable
+      [__minPressDuration]="0"
       (press)="press.emit($event)"
       (pressIn)="pressIn.emit($event)"
       (pressOut)="pressOut.emit($event)"
@@ -100,13 +101,7 @@ export type IAngularTouchableNativeFeedbackProps = Omit<
       [android_ripple]="android_ripple"
       [android_disableSound]="android_disableSound"
     >
-      <symbiote-view
-        [symbioteHostProps]="hostProps()"
-        (accessibilityAction)="emit(accessibilityAction, $event)"
-        (accessibilityTap)="emit(accessibilityTap, $event)"
-        (magicTap)="emit(magicTap, $event)"
-        (accessibilityEscape)="emit(accessibilityEscape, $event)"
-      >
+      <symbiote-view [symbioteHostProps]="hostProps()">
         <ng-content></ng-content>
       </symbiote-view>
     </Pressable>
@@ -262,14 +257,29 @@ export class TouchableNativeFeedback
       nativeID: this.nativeID,
       accessible: this.accessible,
       ...this.folded,
+      onAccessibilityAction: this.eventEmitterHandler(this.accessibilityAction),
+      onAccessibilityTap: this.eventEmitterHandler(this.accessibilityTap),
+      onMagicTap: this.eventEmitterHandler(this.magicTap),
+      onAccessibilityEscape: this.eventEmitterHandler(this.accessibilityEscape),
     };
   });
 
   // Forward an engine event to the matching @Output(), narrowing the template's untyped $event.
-  emit(emitter: EventEmitter<ISymbioteEvent>, event: unknown): void {
+  private emit(emitter: EventEmitter<ISymbioteEvent>, event: unknown): void {
     if (isSymbioteEvent(event)) emitter.emit(event);
   }
 
+  // The four accessibility events are boolean-GATED Fabric events
+  // (`.claude/rules/fabric-boolean-event-gates.md`): native fires them only when the committed
+  // payload carries a FUNCTION at that key, so a template binding here lit the gate on every
+  // instance whether or not an app ever subscribed. `.observed`-gated, mirroring Pressable's
+  // `accessibilityEmitterHandler`.
+  private eventEmitterHandler(
+    emitter: EventEmitter<ISymbioteEvent>,
+  ): ((event: unknown) => void) | undefined {
+    return emitter.observed ? event => this.emit(emitter, event) : undefined;
+  }
+
   // Fold the web aria-*/role aliases into the canonical accessibility* props once per render, so the
   // host never sees an aria-* key (native ignores them), and merge `disabled` into the a11y state
   // (resolveDisabledAccessibilityState) the same way Pressable does for its own host.

package/src/components/virtualized-list/index.ts

@@ -127,6 +127,13 @@ export {
   VListItemDirective,
   VListSeparatorDirective,
 } from './directives';
+import {
+  gateWanted,
+  injectGateDemandAbove,
+  provideGateDemand,
+  type IGateDemand,
+  type IGatedAccessibilityEvent,
+} from '../../gate-demand';
 export type { IVListItemContext, IVListSeparatorContext } from './directives';
 
 // The Angular VirtualizedList prop surface. Mirrors React/Vue's IVirtualizedListProps MINUS the
@@ -213,6 +220,7 @@ interface IWindowCell<ItemT> {
 @Component({
   selector: 'VirtualizedList',
   standalone: true,
+  viewProviders: [provideGateDemand(() => VirtualizedList)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -381,6 +389,16 @@ export class VirtualizedList<ItemT = unknown>
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   @Input({ required: true }) data!: unknown;
   @Input({ required: true }) getItem!: (data: unknown, index: number) => ItemT;
   @Input({ required: true }) getItemCount!: (data: unknown) => number;

package/src/components/virtualized-section-list/index.ts

@@ -88,6 +88,13 @@ export {
   VSectionItemDirective,
   VSectionSeparatorDirective,
 } from './directives';
+import {
+  gateWanted,
+  injectGateDemandAbove,
+  provideGateDemand,
+  type IGateDemand,
+  type IGatedAccessibilityEvent,
+} from '../../gate-demand';
 export type { IVSectionContext, IVSectionItemContext } from './directives';
 
 // The Angular VirtualizedSectionList prop surface. Mirrors React/Vue's IVirtualizedSectionListProps
@@ -160,6 +167,7 @@ export type IVirtualizedSectionListInputs<ItemT> = Omit<
 @Component({
   selector: 'VirtualizedSectionList',
   standalone: true,
+  viewProviders: [provideGateDemand(() => VirtualizedSectionList)],
   hostDirectives: [
     { directive: SymbioteStyleInputDirective, inputs: ['style'] },
   ],
@@ -416,6 +424,16 @@ export class VirtualizedSectionList<ItemT = unknown>
   @Output() readonly accessibilityTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly magicTap = new EventEmitter<ISymbioteEvent>();
   @Output() readonly accessibilityEscape = new EventEmitter<ISymbioteEvent>();
+
+  // This wrapper binds the four gated accessibility events on the component it renders, which
+  // Angular forces to be unconditional and which would light that component's gates on every
+  // instance. It answers for them instead — see `gate-demand.ts`.
+  private readonly gateDemandAbove = injectGateDemandAbove();
+
+  wantsGate(name: IGatedAccessibilityEvent): boolean {
+    return gateWanted(this.gateDemandAbove, name, this[name]);
+  }
+
   @Input() role?: IAriaProps['role'];
   @Input() ariaLabel?: string;
   @Input() ariaLabelledBy?: string;

package/src/components.ts

@@ -130,6 +130,8 @@ export {
   HorizontalScrollContentView,
   TextInputHost,
   MultilineTextInputHost,
+  ManagedTextInputHost,
+  ManagedMultilineTextInputHost,
   SwitchHost,
   ActivityIndicatorHost,
   SafeAreaViewHost,

package/src/create-portal/index.ts

@@ -20,16 +20,23 @@
 //
 // The safe, fully-public-API mechanism: create the embedded view DIRECTLY inside a
 // ViewContainerRef anchored at the destination, so there is nothing to move at all. That
-// ViewContainerRef comes from `PortalOutletDirective`, a marker placed on the target host
-// (`<View portalOutlet #overlayHost="portalOutlet">`) purely to expose its ViewContainerRef, the
-// same export-as-template-variable idiom `#form="ngForm"` uses. This also replaces the
-// `isSymbioteNode` runtime guard React/Vue need (there `to` is an arbitrary JS value until
-// validated): here `to` is typed as `PortalOutletDirective` — the only way to construct one is
-// Angular's own template compiler resolving a template reference variable, so `strictTemplates`
-// rejects anything else at compile time and there is nothing left to guard at runtime.
+// ViewContainerRef comes from `PortalOutletDirective`, exported to a template variable with the
+// same idiom `#form="ngForm"` uses. This also replaces the `isSymbioteNode` runtime guard
+// React/Vue need (there `to` is an arbitrary JS value until validated): here `to` is typed as
+// `PortalOutletDirective` — the only way to construct one is Angular's own template compiler
+// resolving a template reference variable, so `strictTemplates` rejects anything else at compile
+// time and there is nothing left to guard at runtime.
+//
+// THE MARKER GOES ON AN `<ng-container>` INSIDE THE TARGET, never on the target element. A
+// ViewContainerRef anchors AT its host and `createEmbeddedView` inserts after that anchor, so
+// `<View portalOutlet>` delivers a SIBLING where React's `createPortal(node, host)` and Vue's
+// `<Teleport to>` deliver a child. Device-reported 2026-09-02: a card portaled into an absolutely
+// positioned overlay laid out in the scroll flow, since the overlay cannot centre a node that is
+// not in it.
 
 import {
   Directive,
+  ElementRef,
   inject,
   Input,
   TemplateRef,
@@ -38,10 +45,19 @@ import {
   type OnChanges,
   type OnDestroy,
 } from '@angular/core';
+import { isAnchor, isSymbioteNode } from '@symbiote-native/engine';
 
 /** Marks the destination for `*portal` — place it on whichever already-mounted host should
- *  paint the portaled content (e.g. a persistent overlay-host View near the app root), then
- *  export it to a template variable and pass that variable as `*portal`'s target. */
+ *  paint the portaled content — on an `<ng-container>` INSIDE that host, never on the host
+ *  element itself (see the file header) — then export it to a template variable and pass that
+ *  variable as `*portal`'s target:
+ *
+ *  ```html
+ *  <View class="overlay-host">
+ *    <ng-container portalOutlet #overlayHost="portalOutlet"></ng-container>
+ *  </View>
+ *  ```
+ */
 @Directive({
   selector: '[portalOutlet]',
   standalone: true,
@@ -49,6 +65,20 @@ import {
 })
 export class PortalOutletDirective {
   readonly viewContainerRef = inject(ViewContainerRef);
+
+  constructor() {
+    // The wrong placement commits a valid tree that simply differs from React's, so nothing
+    // downstream can catch it. It has to fail where it is written.
+    const host: unknown = inject(ElementRef).nativeElement;
+    if (!isSymbioteNode(host) || !isAnchor(host)) {
+      throw new Error(
+        'portalOutlet must sit on an <ng-container> inside the target host, not on the host ' +
+          'element: a ViewContainerRef anchored at an element inserts AFTER it, so the ported ' +
+          'content would become the host\'s sibling. Write <View class="…">' +
+          '<ng-container portalOutlet #x="portalOutlet"></ng-container></View>.',
+      );
+    }
+  }
 }
 
 /** `*portal="overlayHost"` — renders the host element into whichever `PortalOutletDirective`