@ccheever/exact-renderer 0.1.0

package/src/types.ts

@@ -0,0 +1,1175 @@
+/**
+ * Exact Renderer Type Definitions
+ *
+ * This module defines the core types used throughout the renderer.
+ * Types are organized into categories:
+ * - Style types (layout, spacing, appearance, typography)
+ * - Prop types (component-specific props)
+ * - Internal types (reconciler and protocol internals)
+ *
+ * Design Principles:
+ * - Web semantics are primary (CSS flexbox defaults)
+ * - React Native compatibility is achieved through aliases
+ * - All types are strictly typed for safety
+ */
+
+import type { ReactNode } from 'react';
+
+import type { AssetRef } from '@exact/core/assets-fonts-state';
+import type {
+  KeyboardState,
+  SafeAreaInsets,
+  SafeAreaRegionInsets,
+  SafeAreaRegionName,
+} from '@exact/core/window-types';
+
+// =============================================================================
+// JSX Intrinsic Elements
+// =============================================================================
+
+// Forward-declare ToggleProps for JSX.IntrinsicElements
+// The actual interface is defined below
+interface _TogglePropsForJSX {
+  style?: ViewStyle;
+  value?: boolean;
+  defaultValue?: boolean;
+  onValueChange?: (value: boolean) => void;
+  glassEffect?: boolean;
+  tintColor?: string;
+  label?: string;
+  children?: ReactNode;
+  disabled?: boolean;
+}
+
+/**
+ * Extend JSX intrinsic elements with Exact custom elements.
+ * This allows using lowercase elements like <toggle> in JSX.
+ */
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      /** Native toggle/switch element with iOS liquid glass effect support */
+      toggle: _TogglePropsForJSX;
+    }
+  }
+}
+
+// =============================================================================
+// RGBA Color Type
+// =============================================================================
+
+// Defined in @exact/core (LLP 0157 F0 relocation); re-exported here for
+// back-compat with existing renderer consumers.
+import type { RGBAColor } from '@exact/core/style/color';
+
+export type { RGBAColor };
+
+// =============================================================================
+// Dimension Types
+// =============================================================================
+
+/**
+ * Dimension type for sizes that can be auto, points, or percent.
+ */
+export type DimensionValue =
+  | { readonly type: 'auto' }
+  | { readonly type: 'points'; readonly value: number }
+  | { readonly type: 'percent'; readonly value: number };
+
+/**
+ * Dimension input - can be a number (interpreted as points) or explicit.
+ */
+export type DimensionInput = number | string | DimensionValue;
+
+// =============================================================================
+// Flexbox Types (CSS Standard)
+// =============================================================================
+
+export type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+export type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+export type JustifyContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+export type AlignItems = 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+export type AlignSelf = 'auto' | 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+export type AlignContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'stretch';
+export type Direction = 'ltr' | 'rtl' | 'auto';
+export type ResolvedDirection = 'ltr' | 'rtl';
+export type WritingMode = 'horizontal-tb' | 'vertical-rl' | 'vertical-lr';
+
+// =============================================================================
+// Position Types
+// =============================================================================
+
+export type PositionType = 'relative' | 'absolute';
+export type Overflow = 'visible' | 'hidden' | 'scroll';
+export type Display = 'flex' | 'grid' | 'none';
+export type AccessibilityCheckedState = boolean | 'mixed';
+export type AccessibilityLiveMode = 'off' | 'polite' | 'assertive' | string;
+export interface AccessibilityActionDescriptor {
+  readonly name: string;
+  readonly label?: string;
+}
+export type FocusScopeMode = boolean | 'contain' | 'restore' | 'containRestore' | string;
+export type SafeAreaEdge = 'top' | 'right' | 'bottom' | 'left';
+export type SafeAreaEdgeMode = 'additive' | 'maximum' | 'off';
+export type SafeAreaRegionSet =
+  | 'container'
+  | 'keyboard'
+  | 'all'
+  | 'none'
+  | SafeAreaRegionName[]
+  | readonly SafeAreaRegionName[];
+export type SafeAreaProp =
+  | 'none'
+  | {
+      regions?: SafeAreaRegionSet;
+      top?: SafeAreaEdgeMode;
+      right?: SafeAreaEdgeMode;
+      bottom?: SafeAreaEdgeMode;
+      left?: SafeAreaEdgeMode;
+    };
+
+export interface SafeAreaInsetProp {
+  edge: SafeAreaEdge;
+  size: number;
+}
+
+// =============================================================================
+// Typography Types
+// =============================================================================
+
+export type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number;
+export type FontStyle = 'normal' | 'italic';
+export type TextAlign = 'auto' | 'left' | 'right' | 'center' | 'justify';
+export type TextDecorationLine = 'none' | 'underline' | 'line-through' | 'underline line-through';
+export type EllipsizeMode = 'head' | 'middle' | 'tail' | 'clip';
+
+// =============================================================================
+// Image Types
+// =============================================================================
+
+export type ResizeMode = 'cover' | 'contain' | 'stretch' | 'center';
+export type ImageObjectFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+export type ImageLoading = 'auto' | 'eager' | 'lazy';
+
+export interface ImageCandidate {
+  uri: string;
+  headers?: Record<string, string>;
+  cacheKey?: string;
+  width?: number;
+  height?: number;
+  pixelDensity?: number;
+  type?: string;
+}
+
+export type ImageColorScheme = 'light' | 'dark';
+export type ImageThemeTreatment = 'none' | 'invert-in-dark' | 'invert-in-light';
+
+export interface ColorSchemeImageSource {
+  light?: ImageSource;
+  dark?: ImageSource;
+  fallback?: ImageSource;
+}
+
+/**
+ * Image source - either a URI or a local asset reference.
+ */
+export type ImageSource =
+  | string
+  | AssetRef
+  | { uri: string; headers?: Record<string, string>; cacheKey?: string }
+  | { thumbhash: string }
+  | ColorSchemeImageSource
+  | readonly ImageCandidate[]
+  | number;
+
+export interface SvgUriSource {
+  uri: string;
+  headers?: Record<string, string>;
+  cacheKey?: string;
+}
+
+export type SvgSource =
+  | string
+  | AssetRef
+  | SvgUriSource;
+
+export type ImagePlaceholder =
+  | string
+  | AssetRef
+  | { thumbhash: string }
+  | { color: string }
+  | ImageSource;
+
+export type SelectableMode = boolean | 'contain' | 'all';
+export type NativeViewSelectionTier = 'atomic' | 'structured' | 'delegated';
+export type NativeViewSelectionGesturePolicy = 'external' | 'internal';
+
+// =============================================================================
+// Style Interfaces
+// =============================================================================
+
+/**
+ * Flexbox layout properties.
+ */
+export interface FlexStyle {
+  flex?: number;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: DimensionInput;
+  flexDirection?: FlexDirection;
+  flexWrap?: FlexWrap;
+  justifyContent?: JustifyContent;
+  alignItems?: AlignItems;
+  alignSelf?: AlignSelf;
+  alignContent?: AlignContent;
+  direction?: Direction;
+  gap?: number;
+  rowGap?: number;
+  columnGap?: number;
+}
+
+/**
+ * Dimension and sizing properties.
+ */
+export interface LayoutStyle {
+  width?: DimensionInput;
+  height?: DimensionInput;
+  minWidth?: DimensionInput;
+  minHeight?: DimensionInput;
+  maxWidth?: DimensionInput;
+  maxHeight?: DimensionInput;
+  aspectRatio?: number;
+}
+
+/**
+ * Padding and margin properties.
+ */
+export interface SpacingStyle {
+  padding?: DimensionInput;
+  paddingTop?: DimensionInput;
+  paddingRight?: DimensionInput;
+  paddingBottom?: DimensionInput;
+  paddingLeft?: DimensionInput;
+  paddingHorizontal?: DimensionInput;
+  paddingVertical?: DimensionInput;
+  paddingStart?: DimensionInput;
+  paddingEnd?: DimensionInput;
+  paddingInlineStart?: DimensionInput;
+  paddingInlineEnd?: DimensionInput;
+  margin?: DimensionInput;
+  marginTop?: DimensionInput;
+  marginRight?: DimensionInput;
+  marginBottom?: DimensionInput;
+  marginLeft?: DimensionInput;
+  marginHorizontal?: DimensionInput;
+  marginVertical?: DimensionInput;
+  marginStart?: DimensionInput;
+  marginEnd?: DimensionInput;
+  marginInlineStart?: DimensionInput;
+  marginInlineEnd?: DimensionInput;
+}
+
+/**
+ * Position properties.
+ */
+export interface PositionStyle {
+  position?: PositionType;
+  top?: DimensionInput;
+  right?: DimensionInput;
+  bottom?: DimensionInput;
+  left?: DimensionInput;
+  start?: DimensionInput;
+  end?: DimensionInput;
+  insetInlineStart?: DimensionInput;
+  insetInlineEnd?: DimensionInput;
+  zIndex?: number;
+}
+
+/**
+ * Visual appearance properties.
+ */
+export interface AppearanceStyle {
+  display?: Display;
+  backgroundColor?: string;
+  opacity?: number;
+  borderRadius?: number;
+  borderTopLeftRadius?: number;
+  borderTopRightRadius?: number;
+  borderBottomLeftRadius?: number;
+  borderBottomRightRadius?: number;
+  borderWidth?: number;
+  borderColor?: string;
+  // Per-side borders (ENG-22085).
+  borderTopWidth?: number;
+  borderRightWidth?: number;
+  borderBottomWidth?: number;
+  borderLeftWidth?: number;
+  borderTopColor?: string;
+  borderRightColor?: string;
+  borderBottomColor?: string;
+  borderLeftColor?: string;
+  shadowColor?: string;
+  shadowOffset?: {
+    width: number;
+    height: number;
+  };
+  shadowRadius?: number;
+  shadowOpacity?: number;
+  boxShadow?: string;
+  backdropBlur?: number;
+  overflow?: Overflow;
+}
+
+/**
+ * Transform properties for animations.
+ */
+export interface TransformStyle {
+  transform?: Array<
+    | { translateX: number }
+    | { translateY: number }
+    | { scale: number }
+    | { scaleX: number }
+    | { scaleY: number }
+    | { rotate: string }
+  >;
+}
+
+// =============================================================================
+// Transition Types
+// =============================================================================
+
+// Defined in @exact/core (LLP 0157 F0 relocation) so framework-neutral
+// packages can describe motion; re-exported here for back-compat.
+import type {
+  CubicBezierEasing,
+  NoneTransition,
+  SpringTransition,
+  StyleTransition,
+  TimingTransition,
+  TransitionConfig,
+  TransitionEasing,
+  TransitionEasingName,
+  TransitionMap,
+  TransitionPhase,
+  TransitionPropertyName,
+} from '@exact/core/style/transitions';
+
+export type {
+  CubicBezierEasing,
+  NoneTransition,
+  SpringTransition,
+  StyleTransition,
+  TimingTransition,
+  TransitionConfig,
+  TransitionEasing,
+  TransitionEasingName,
+  TransitionMap,
+  TransitionPhase,
+  TransitionPropertyName,
+};
+
+export interface TransitionStyle {
+  transition?: StyleTransition;
+}
+
+/**
+ * Typography properties for text elements.
+ */
+export interface TextStyle {
+  color?: string;
+  fontFamily?: string | readonly string[];
+  fontSize?: number;
+  fontWeight?: FontWeight;
+  fontStyle?: FontStyle;
+  fontVariantNumeric?: string;
+  textAlign?: TextAlign;
+  writingMode?: WritingMode;
+  lineHeight?: number;
+  letterSpacing?: number;
+  textDecorationLine?: TextDecorationLine;
+  numberOfLines?: number;
+  ellipsizeMode?: EllipsizeMode;
+}
+
+/**
+ * Combined view style (all non-text styles).
+ */
+export type ViewStyle = FlexStyle & LayoutStyle & SpacingStyle & PositionStyle & AppearanceStyle & TransformStyle & TransitionStyle;
+
+/**
+ * Full style including text properties.
+ */
+export type FullStyle = ViewStyle & TextStyle;
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/**
+ * Press event payload from native.
+ */
+export interface PressEvent {
+  nativeEvent: {
+    locationX: number;
+    locationY: number;
+    timestamp: number;
+  };
+}
+
+/**
+ * Scroll event payload.
+ */
+export interface ScrollEvent {
+  nativeEvent: {
+    contentOffset: {
+      x: number;
+      y: number;
+    };
+    contentSize: {
+      width: number;
+      height: number;
+    };
+    layoutMeasurement: {
+      width: number;
+      height: number;
+    };
+    timestamp: number;
+  };
+}
+
+/**
+ * Change event for inputs.
+ */
+export interface ChangeEvent {
+  nativeEvent: {
+    text: string;
+    selection?: TextInputSelection;
+    textChanged?: boolean;
+    isComposing?: boolean;
+    compositionRange?: TextInputSelection;
+    textRevision?: number;
+    classification?: string;
+  };
+}
+
+export interface TextInputSelection {
+  start: number;
+  end: number;
+}
+
+export interface SelectionChangeEvent {
+  nativeEvent: {
+    selection: TextInputSelection;
+    text?: string;
+    isComposing?: boolean;
+    compositionRange?: TextInputSelection;
+    textRevision?: number;
+    classification?: string;
+  };
+}
+
+/**
+ * Transition completion event payload.
+ */
+export interface TransitionEndEvent {
+  propertyName: TransitionPropertyName;
+  finished: boolean;
+  phase?: TransitionPhase;
+}
+
+/**
+ * Focus event payload from native or the web wrapper layer.
+ */
+export interface FocusChangeEvent {
+  nativeEvent: {
+    timestamp: number;
+    relatedTarget?: number | null;
+  };
+}
+
+/**
+ * Keyboard event payload from native or the web wrapper layer.
+ */
+export interface KeyEvent {
+  nativeEvent: {
+    key: string;
+    code?: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    repeat: boolean;
+    timestamp: number;
+  };
+  preventDefault?: () => void;
+  defaultPrevented?: boolean;
+}
+
+// =============================================================================
+// Component Props Interfaces
+// =============================================================================
+
+export type AgentSemanticScalar = string | number | boolean | null;
+
+export interface AgentSemanticOption {
+  value: AgentSemanticScalar;
+  label?: string;
+}
+
+/**
+ * Renderer-local agent metadata. This never goes into the binary protocol; it
+ * only exists so the authenticated / agent-facing projections can preserve the
+ * author's semantic intent instead of inferring everything heuristically.
+ */
+export interface AgentSemantics {
+  kind: string;
+  label?: string;
+  value?: AgentSemanticScalar | readonly AgentSemanticScalar[];
+  intent?: "default" | "primary" | "destructive" | "success" | "warning" | "info";
+  to?: string;
+  disabledReason?: string;
+  hint?: string;
+  options?: readonly (AgentSemanticScalar | AgentSemanticOption)[];
+  confirmation?: string;
+}
+
+/**
+ * Base props shared by all elements.
+ */
+/**
+ * Liquid Glass material variant. `regular` is the default adaptive glass;
+ * `clear` is the more transparent variant Apple uses over media-rich content.
+ */
+export type GlassVariant = 'regular' | 'clear';
+
+export interface BaseProps {
+  key?: string | number;
+  className?: string;
+  testID?: string;
+  testId?: string;
+  /**
+   * Declarative safe-area participation. The renderer consumes this locally and
+   * resolves it into concrete padding/content-inset style before protocol
+   * encoding, which keeps the cross-platform payload simple.
+   */
+  safeArea?: SafeAreaProp;
+  /**
+   * Fixed sibling safe-area expansion. This is the v1 explicit-size form of
+   * `safeAreaInset(edge:)`.
+   */
+  safeAreaInset?: SafeAreaInsetProp;
+  /**
+   * Tier-2-only agent hint used by the authenticated agent surface.
+   *
+   * This is metadata rather than visual UI. The public markdown path must not
+   * consume it, so read-only agent requests do not see anything richer than the
+   * corresponding HTML page already exposes.
+   */
+  agentSummary?: string;
+  agentId?: string;
+  agentSemantics?: AgentSemantics;
+  selectable?: SelectableMode;
+  selectionCopyText?: string;
+  disabledReason?: string;
+  /**
+   * Liquid Glass (Apple iOS 26 / macOS 26). `glassEffect` enables the effect on
+   * any container surface; the modifiers refine it. The renderer composes these
+   * into a single `glassEffect` spec string before protocol encoding and falls
+   * back to a translucent blur on web and pre-26 OSes.
+   */
+  glassEffect?: boolean;
+  glassVariant?: GlassVariant;
+  glassTint?: string;
+  glassInteractive?: boolean;
+  focusScope?: FocusScopeMode;
+  inert?: boolean;
+  scrollLocked?: boolean;
+  portalTarget?: string;
+  accessibilityLabel?: string;
+  accessibilityRole?: string;
+  accessibilityHint?: string;
+  accessibilityModal?: boolean;
+  accessibilityExpanded?: boolean;
+  accessibilitySelected?: boolean;
+  accessibilityChecked?: AccessibilityCheckedState;
+  accessibilityDisabled?: boolean;
+  accessibilityLive?: AccessibilityLiveMode;
+  accessibilityValueNow?: number;
+  accessibilityValueMin?: number;
+  accessibilityValueMax?: number;
+  accessibilityValueText?: string;
+  focusable?: boolean;
+  tabIndex?: number;
+  nativeID?: string;
+  accessibilityFor?: string;
+  accessibilityLabelledBy?: string;
+  accessibilityDescribedBy?: string;
+  accessibilityBusy?: boolean;
+  accessibilityActions?: readonly AccessibilityActionDescriptor[];
+  accessibilityElementsHidden?: boolean;
+  accessibilityOrder?: readonly string[];
+  accessibilityHeadingLevel?: number;
+  /**
+   * Internal-only flag used by `<AccessibilityChildren>` to keep synthetic
+   * semantics nodes out of the visual surface.
+   */
+  accessibilitySynthetic?: boolean;
+  allowFontScaling?: boolean;
+  maxFontSizeMultiplier?: number;
+  minimumFontSize?: number;
+  lang?: string;
+  onFocus?: (event: FocusChangeEvent) => void;
+  onBlur?: (event: FocusChangeEvent) => void;
+  onKeyDown?: (event: KeyEvent) => void;
+  onKeyUp?: (event: KeyEvent) => void;
+  onFocusIn?: (event: FocusChangeEvent) => void;
+  onFocusOut?: (event: FocusChangeEvent) => void;
+  onAccessibilityAction?: (event: { nativeEvent: { actionName: string } }) => void;
+  onTransitionEnd?: (event: TransitionEndEvent) => void;
+  __exactPresencePhase?: string;
+  __exactPortalLevel?: string;
+  __exactPortalPresentation?: string;
+  __exactDismissableLayer?: boolean;
+  __exactDismissAction?: string;
+  __exactFocusRestore?: boolean;
+  __exactAnchorTarget?: string;
+  __exactAnchorPlacement?: string;
+  __exactAnchorStrategy?: string;
+  __exactAnchorOffset?: number;
+  __exactComponentName?: string;
+  __exactComponentSlot?: string;
+  __exactSourceFilePath?: string;
+  __exactVariantProps?: string;
+  __exactInteractionState?: string;
+  __exactRenderMode?: string;
+  /**
+   * Internal performance hint for fixed-size text surfaces whose content changes
+   * must not affect layout.
+   */
+  __exactTextLayoutStable?: boolean;
+}
+
+/**
+ * Props for container elements (div, View).
+ */
+export interface ContainerProps extends BaseProps {
+  style?: ViewStyle;
+  children?: ReactNode;
+}
+
+/**
+ * Props for text elements.
+ */
+export interface TextElementProps extends BaseProps {
+  style?: FullStyle;
+  children?: ReactNode;
+  textContent?: string;
+  numberOfLines?: number;
+  ellipsizeMode?: EllipsizeMode;
+}
+
+/**
+ * Props for pressable/touchable elements.
+ */
+export interface PressableElementProps extends ContainerProps {
+  onPress?: (event: PressEvent) => void;
+  onPressIn?: (event: PressEvent) => void;
+  onPressOut?: (event: PressEvent) => void;
+  onLongPress?: (event: PressEvent) => void;
+  disabled?: boolean;
+  delayLongPress?: number;
+}
+
+/**
+ * Props for web-style image (img).
+ */
+export interface ImageElementProps extends BaseProps {
+  style?: ViewStyle;
+  src: string;
+  lightSrc?: string;
+  darkSrc?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  objectFit?: ImageObjectFit;
+  objectPosition?: string;
+  loading?: 'eager' | 'lazy';
+  themeTreatment?: ImageThemeTreatment;
+}
+
+/**
+ * Props for RN-style image (Image).
+ */
+export interface RNImageProps extends BaseProps {
+  style?: ViewStyle;
+  source: ImageSource;
+  lightSrc?: string;
+  darkSrc?: string;
+  resizeMode?: ResizeMode;
+  objectFit?: ImageObjectFit;
+  objectPosition?: string;
+  alt?: string;
+  decorative?: boolean;
+  longDescription?: string;
+  placeholder?: ImagePlaceholder;
+  loading?: ImageLoading;
+  themeTreatment?: ImageThemeTreatment;
+  onLoadStart?: () => void;
+  onLoad?: (event: {
+    source: { uri: string; width: number; height: number };
+    cacheType: 'none' | 'disk' | 'memory';
+  }) => void;
+  onError?: (event: { error: string }) => void;
+  onDisplay?: () => void;
+}
+
+export interface SvgProps extends BaseProps {
+  style?: ViewStyle;
+  source: SvgSource;
+  objectFit?: ImageObjectFit;
+  objectPosition?: string;
+  alt?: string;
+  decorative?: boolean;
+  tintColor?: string;
+  colors?: Record<string, string>;
+  pixelDensity?: number;
+}
+
+/**
+ * Props for scroll containers.
+ */
+export interface ScrollContainerProps extends ContainerProps {
+  horizontal?: boolean;
+  showsVerticalScrollIndicator?: boolean;
+  showsHorizontalScrollIndicator?: boolean;
+  scrollEventThrottle?: number;
+  onScroll?: (event: ScrollEvent) => void;
+  contentContainerStyle?: ViewStyle;
+}
+
+/**
+ * Props for text input elements.
+ */
+export interface TextInputProps extends BaseProps {
+  style?: FullStyle;
+  value?: string;
+  defaultValue?: string;
+  selection?: TextInputSelection;
+  placeholder?: string;
+  placeholderTextColor?: string;
+  multiline?: boolean;
+  numberOfLines?: number;
+  maxLength?: number;
+  editable?: boolean;
+  autoFocus?: boolean;
+  secureTextEntry?: boolean;
+  keyboardType?: 'default' | 'numeric' | 'email-address' | 'phone-pad';
+  returnKeyType?: 'done' | 'go' | 'next' | 'search' | 'send';
+  onChangeText?: (text: string) => void;
+  onChange?: (event: ChangeEvent) => void;
+  onSelectionChange?: (event: SelectionChangeEvent) => void;
+  onSubmitEditing?: () => void;
+}
+
+/**
+ * Toggle value change event.
+ */
+export interface ToggleChangeEvent {
+  nativeEvent: {
+    value: boolean;
+  };
+}
+
+/**
+ * Props for toggle/switch elements.
+ */
+export interface ToggleProps extends BaseProps {
+  style?: ViewStyle;
+  /** Current value of the toggle (controlled) */
+  value?: boolean;
+  /** Default value for uncontrolled usage */
+  defaultValue?: boolean;
+  /** Callback when value changes */
+  onValueChange?: (value: boolean) => void;
+  /** Enable iOS 26+ liquid glass effect */
+  glassEffect?: boolean;
+  /** Tint color for the toggle when on */
+  tintColor?: string;
+  /** Label text (rendered natively on iOS) */
+  label?: string;
+  /** Alternative to label prop - children text content */
+  children?: ReactNode;
+  /** Whether the toggle is disabled */
+  disabled?: boolean;
+}
+
+// =============================================================================
+// Internal Types (for reconciler and protocol)
+// =============================================================================
+
+/**
+ * Canonical internal style representation after normalization.
+ * All values are in their final form ready for protocol encoding.
+ */
+export interface CanonicalStyle {
+  display?: Display;
+  // Dimensions
+  width?: DimensionValue;
+  height?: DimensionValue;
+  minWidth?: DimensionValue;
+  minHeight?: DimensionValue;
+  maxWidth?: DimensionValue;
+  maxHeight?: DimensionValue;
+
+  // Padding
+  paddingTop?: DimensionValue;
+  paddingRight?: DimensionValue;
+  paddingBottom?: DimensionValue;
+  paddingLeft?: DimensionValue;
+
+  // Margin
+  marginTop?: DimensionValue;
+  marginRight?: DimensionValue;
+  marginBottom?: DimensionValue;
+  marginLeft?: DimensionValue;
+
+  // Flexbox
+  direction?: ResolvedDirection;
+  flexDirection?: FlexDirection;
+  flexWrap?: FlexWrap;
+  justifyContent?: JustifyContent;
+  alignItems?: AlignItems;
+  alignSelf?: AlignSelf;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: DimensionValue;
+  rowGap?: number;
+  columnGap?: number;
+
+  // Position
+  positionType?: PositionType;
+  top?: DimensionValue;
+  right?: DimensionValue;
+  bottom?: DimensionValue;
+  left?: DimensionValue;
+  zIndex?: number;
+
+  // Transform
+  transformX?: number;
+  transformY?: number;
+  transformScale?: number;
+  transformRotate?: number;
+
+  // Appearance
+  backgroundColor?: RGBAColor;
+  opacity?: number;
+  borderRadius?: number;
+  borderTopLeftRadius?: number;
+  borderTopRightRadius?: number;
+  borderBottomLeftRadius?: number;
+  borderBottomRightRadius?: number;
+  borderWidth?: number;
+  borderColor?: RGBAColor;
+  // Per-side borders (ENG-22085).
+  borderTopWidth?: number;
+  borderRightWidth?: number;
+  borderBottomWidth?: number;
+  borderLeftWidth?: number;
+  borderTopColor?: RGBAColor;
+  borderRightColor?: RGBAColor;
+  borderBottomColor?: RGBAColor;
+  borderLeftColor?: RGBAColor;
+  shadowColor?: RGBAColor;
+  shadowOffsetX?: number;
+  shadowOffsetY?: number;
+  shadowRadius?: number;
+  shadowOpacity?: number;
+  backdropBlur?: number;
+  overflow?: Overflow;
+  aspectRatio?: number;
+  resizeMode?: ResizeMode;
+
+  // Typography
+  fontFamily?: number;
+  fontSize?: number;
+  textColor?: RGBAColor;
+  fontWeight?: number;
+  fontStyle?: FontStyle;
+  fontVariantNumeric?: number;
+  textAlign?: TextAlign;
+  writingMode?: WritingMode;
+  lineHeight?: number;
+  letterSpacing?: number;
+  textDecorationLine?: TextDecorationLine;
+  numberOfLines?: number;
+  ellipsizeMode?: EllipsizeMode;
+}
+
+export type CanonicalTransitionProperty = TransitionPropertyName;
+export type CanonicalTransitionEasing = TransitionEasing;
+
+export interface CanonicalTimingTransition {
+  readonly type: 'timing';
+  readonly duration: number;
+  readonly delay: number;
+  readonly easing: CanonicalTransitionEasing;
+  readonly respectsReducedMotion: boolean;
+}
+
+export interface CanonicalSpringTransition {
+  readonly type: 'spring';
+  readonly duration?: number;
+  readonly delay: number;
+  readonly damping: number;
+  readonly stiffness: number;
+  readonly mass: number;
+  readonly velocity: number;
+  readonly respectsReducedMotion: boolean;
+}
+
+export type CanonicalTransitionConfig = CanonicalTimingTransition | CanonicalSpringTransition;
+export type CanonicalTransitionMap = Partial<Record<CanonicalTransitionProperty, CanonicalTransitionConfig>>;
+
+export interface SafeAreaEdgeModes {
+  top: SafeAreaEdgeMode;
+  right: SafeAreaEdgeMode;
+  bottom: SafeAreaEdgeMode;
+  left: SafeAreaEdgeMode;
+}
+
+export type SafeAreaStrategy = 'framePadding' | 'contentInset';
+
+/**
+ * Resolved safe-area declaration for a node.
+ *
+ * The renderer keeps this separate from `CanonicalProps` because it is not a
+ * protocol concept. It influences padding/content inset derivation and feeds
+ * the inspector/diagnostics surfaces.
+ */
+export interface ResolvedSafeAreaConfig {
+  explicit: boolean;
+  regions: SafeAreaRegionName[];
+  edges: SafeAreaEdgeModes;
+  strategy: SafeAreaStrategy;
+}
+
+/**
+ * Safe-area context propagated from parent to child. Edge-anchored regions are
+ * tracked as "remaining" insets, while keyboard stays rect-based so floating
+ * and split keyboards do not get flattened too early.
+ */
+export interface SafeAreaPropagationState {
+  rootId: number;
+  regions: Readonly<SafeAreaRegionInsets>;
+  keyboard: Readonly<KeyboardState>;
+}
+
+/**
+ * Inspector-facing breakdown of what safe-area logic actually applied to a
+ * node during style resolution.
+ */
+export interface ResolvedSafeAreaState {
+  config: ResolvedSafeAreaConfig;
+  strategy: SafeAreaStrategy;
+  sourceRegions: Readonly<SafeAreaRegionInsets>;
+  siblingExpansion: Readonly<SafeAreaInsets>;
+  availableInsets: Readonly<SafeAreaInsets>;
+  keyboardOverlap: Readonly<SafeAreaInsets>;
+  appliedInsets: Readonly<SafeAreaInsets>;
+  remainingRegions: Readonly<SafeAreaRegionInsets>;
+  keyboardState: Readonly<KeyboardState>;
+}
+
+/**
+ * Canonical internal props representation after normalization.
+ */
+export interface CanonicalProps {
+  // Text content
+  textContent?: string;
+  selectable?: SelectableMode;
+  selectionCopyText?: string;
+  selectionStart?: number;
+  selectionEnd?: number;
+  agentSummary?: string;
+  agentId?: string;
+  agentSemantics?: string;
+
+  // Image properties
+  imageSource?: string;
+  resizeMode?: ResizeMode;
+  svgSource?: string;
+  svgColors?: string;
+  svgObjectPosition?: string;
+  svgPixelDensity?: string;
+  videoPlayerId?: string;
+  videoViewConfig?: string;
+  nativeViewModuleName?: string;
+  nativeViewProps?: string;
+  nativeViewSelectionTier?: NativeViewSelectionTier;
+  nativeViewGesturePolicy?: NativeViewSelectionGesturePolicy;
+
+  // Accessibility
+  accessibilityLabel?: string;
+  lang?: string;
+  focusScope?: FocusScopeMode;
+  inert?: boolean;
+  scrollLocked?: boolean;
+  portalTarget?: string;
+  accessibilityRole?: string;
+  accessibilityHint?: string;
+  accessibilityModal?: boolean;
+  accessibilityExpanded?: boolean;
+  accessibilitySelected?: boolean;
+  accessibilityChecked?: AccessibilityCheckedState;
+  accessibilityDisabled?: boolean;
+  accessibilityLive?: AccessibilityLiveMode;
+  accessibilityValueNow?: number;
+  accessibilityValueMin?: number;
+  accessibilityValueMax?: number;
+  accessibilityValueText?: string;
+  focusable?: boolean;
+  tabIndex?: number;
+  testId?: string;
+  nativeID?: string;
+  /** In-document anchor/URL for link pressables (e.g. a footnote ref's `#fn-1`).
+   * Encoded to native so the host can resolve in-page anchor scrolls. */
+  href?: string;
+  accessibilityLabelledBy?: string;
+  accessibilityDescribedBy?: string;
+  accessibilityBusy?: boolean;
+  accessibilityActions?: string;
+  accessibilityElementsHidden?: boolean;
+  accessibilityOrder?: string;
+  accessibilityHeadingLevel?: number;
+  accessibilitySynthetic?: boolean;
+  allowFontScaling?: boolean;
+  maxFontSizeMultiplier?: number;
+  minimumFontSize?: number;
+  disabledReason?: string;
+  __exactPresencePhase?: string;
+  __exactPortalLevel?: string;
+  __exactPortalPresentation?: string;
+  __exactDismissableLayer?: boolean;
+  __exactDismissAction?: string;
+  __exactFocusRestore?: boolean;
+  __exactAnchorTarget?: string;
+  __exactAnchorPlacement?: string;
+  __exactAnchorStrategy?: string;
+  __exactAnchorOffset?: number;
+  __exactComponentName?: string;
+  __exactComponentSlot?: string;
+  __exactSourceFilePath?: string;
+  __exactVariantProps?: string;
+  __exactInteractionState?: string;
+  __exactRenderMode?: string;
+
+  // Input properties
+  placeholder?: string;
+  value?: string;
+  editable?: boolean;
+  multiline?: boolean;
+  maxLength?: number;
+  secureTextEntry?: boolean;
+
+  // Scroll properties
+  horizontal?: boolean;
+  showsScrollIndicator?: boolean;
+
+  // Toggle properties
+  toggleValue?: boolean;
+  /**
+   * Liquid Glass spec. For toggles this is a boolean (`true` enables the
+   * control glass). For container surfaces the renderer composes the `glass*`
+   * inputs into a spec string — `"true" | "regular" | "clear"` optionally
+   * followed by `;tint=<color>` and/or `;interactive` — which the native host
+   * parses (see ExactEngine glass spec read). The encoder stringifies it onto
+   * the existing `PropId.GlassEffect` wire prop, so no new protocol id is
+   * needed; the legacy `"true"` value stays truthy for the toggle path.
+   */
+  glassEffect?: boolean | string;
+  tintColor?: string;
+  disabled?: boolean;
+}
+
+/**
+ * Event handler registration.
+ */
+export interface EventBinding {
+  handlerId: number;
+  handler: Function;
+}
+
+// =============================================================================
+// Tag Types
+// =============================================================================
+
+/**
+ * Internal tag type used by the renderer.
+ * All user-facing tags (web and RN) are resolved to these canonical types.
+ */
+export type CanonicalTagType =
+  | 'view'      // Generic container
+  | 'text'      // Text content
+  | 'image'     // Image
+  | 'svg'       // SVG image
+  | 'video'     // Video view
+  | 'nativeView' // Generic module-backed native view
+  | 'scroll'    // Scroll container
+  | 'list'      // Host-owned virtual list container
+  | 'input'     // Text input
+  | 'pressable' // Touchable wrapper
+  | 'toggle'    // Toggle/switch
+  ;
+
+/**
+ * Web element tags supported by the renderer.
+ */
+export type WebTagType =
+  | 'div'
+  | 'span'
+  | 'text'
+  | 'img'
+  | 'input'
+  | 'button'
+  | 'toggle'
+  | 'p'
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'h6'
+  | 'section'
+  | 'main'
+  | 'article'
+  | 'nav'
+  | 'aside'
+  | 'header'
+  | 'footer'
+  | 'form'
+  | 'label'
+  | 'textarea'
+  | 'a'
+  | 'svg';
+
+/**
+ * React Native component tags supported by the renderer.
+ */
+export type RNTagType =
+  | 'View'
+  | 'Text'
+  | 'Image'
+  | 'Svg'
+  | 'VideoView'
+  | 'ScrollView'
+  | 'List'
+  | 'TextInput'
+  | 'Pressable'
+  | 'Toggle'
+  | 'Switch';
+
+/**
+ * All supported tag types.
+ */
+export type TagType = WebTagType | RNTagType;