@ccheever/exact-renderer 0.1.0

package/src/inspector.ts

@@ -0,0 +1,3570 @@
+import type {
+  AccessibilityNode,
+  AgentCapability,
+  AgentEvent,
+  ElementRef,
+  ElementRefInfo,
+  FindQuery,
+  FindResultData,
+  Frame,
+  HitTestBlocker,
+  LayoutDiagnostic,
+  Point,
+  ResolveTargetData,
+  ResolveTargetOcclusion,
+  ResolveTargetScrollAncestor,
+  ResolvedTarget,
+  RootInfo,
+  SafeAreaNodeSnapshotData,
+  TextPattern,
+  VisibilityState,
+  ViewNode,
+} from '@exact/core/agent/types';
+import {
+  resetAgentStateTracking,
+  subscribeAgentStateEvents,
+} from '@exact/core/agent/state';
+import {
+  recordCommitTimestamp,
+} from '@exact/core/agent/interaction-state';
+import {
+  getFacetComponents,
+  findFloatingPositionByViewId,
+  getThemeSnapshot,
+} from '@exact/core/agent/experience-registry';
+import {
+  EventType,
+} from '@exact/core/protocol/opcodes';
+import {
+  _resetAgentLogState,
+  recordAgentLog,
+} from '@exact/core/runtime/diagnostics/logs';
+import {
+  getRootWindowMetrics,
+} from '@exact/core/window-state';
+import type { CanonicalStyle } from './types.js';
+import type { ElementNode, HostNode, RootNode, TextNode } from './nodes/node.js';
+import { NodeKind } from './nodes/node.js';
+import { getScreenDimensions } from './protocol/index.js';
+import {
+  registerInspectorCommitAnalyzer,
+  registerInspectorResetHook,
+} from './inspector-runtime.js';
+
+type InspectorListener = (event: AgentEvent) => void;
+
+interface SnapshotRecord {
+  snapshotId: string;
+  rootId: number;
+  stateVersion: number;
+  timestamp: number;
+  frameCount: number;
+  refs: Record<ElementRef, ElementRefInfo>;
+  tree?: ViewNode;
+}
+
+interface SerializedSnapshot {
+  root: ViewNode;
+  refs: Record<ElementRef, ElementRefInfo>;
+  frames: Map<number, Frame>;
+}
+
+interface AccessibilitySnapshot {
+  nodes: AccessibilityNode[];
+  refs: Record<ElementRef, ElementRefInfo>;
+}
+
+interface ResolvedElement {
+  root: RootNode;
+  element: ElementNode;
+  frame: Frame;
+}
+
+interface SharedInspectorState {
+  roots: Map<number, RootNode>;
+  listeners: Set<InspectorListener>;
+  snapshots: Map<string, SnapshotRecord>;
+  snapshotOrder: string[];
+  textOverrides: Map<number, string>;
+  toggleOverrides: Map<number, boolean>;
+  valueOverrides: Map<number, unknown>;
+  scrollOffsets: Map<number, Point>;
+  snapshotCounter: number;
+  stateVersion: number;
+  frameCount: number;
+  lastCommitAt: number;
+}
+
+declare global {
+  var __exactRendererInspectorState: SharedInspectorState | undefined;
+  var __exactSetInspectorScrollOffset:
+    | ((viewId: number, offset: Point, rootId?: number) => Point | null)
+    | undefined;
+}
+
+function getSharedInspectorState(): SharedInspectorState {
+  if (globalThis.__exactRendererInspectorState) {
+    return globalThis.__exactRendererInspectorState;
+  }
+
+  const state: SharedInspectorState = {
+    roots: new Map<number, RootNode>(),
+    listeners: new Set<InspectorListener>(),
+    snapshots: new Map<string, SnapshotRecord>(),
+    snapshotOrder: [],
+    textOverrides: new Map<number, string>(),
+    toggleOverrides: new Map<number, boolean>(),
+    valueOverrides: new Map<number, unknown>(),
+    scrollOffsets: new Map<number, Point>(),
+    snapshotCounter: 0,
+    stateVersion: 0,
+    frameCount: 0,
+    lastCommitAt: 0,
+  };
+  globalThis.__exactRendererInspectorState = state;
+  return state;
+}
+
+const sharedState = getSharedInspectorState();
+const roots = sharedState.roots;
+const listeners = sharedState.listeners;
+const snapshots = sharedState.snapshots;
+const snapshotOrder = sharedState.snapshotOrder;
+const textOverrides = sharedState.textOverrides;
+const toggleOverrides = sharedState.toggleOverrides;
+const valueOverrides = sharedState.valueOverrides;
+const scrollOffsets = sharedState.scrollOffsets;
+
+const MAX_SNAPSHOTS = 64;
+const AGENT_CAPABILITIES: AgentCapability[] = [
+  'capabilities',
+  'access',
+  'screenshot',
+  'tree',
+  'layout',
+  'diagnostics',
+  'accessibility',
+  'accessibility-audit',
+  'preferences',
+  'announce',
+  'roots',
+  'snapshot',
+  'find',
+  'resolve-target',
+  'logs',
+  'network',
+  'focus',
+  'action',
+  'navigation',
+  'navigation-graph',
+  'perf',
+  'environment',
+  'state',
+  'tap',
+  'type',
+  'set-value',
+  'scroll',
+  'host-scroll',
+  'event-trace',
+  'native-inspect',
+  'native-hit-test',
+  'native-perform',
+  'native-trace',
+  'native-capture',
+  'native-probe',
+  'protocol-tap',
+  'contract-dataflow',
+  'gesture',
+  'run-js',
+  'wait',
+  'stream',
+  'hit-test',
+  'act',
+  'extract',
+  'observe',
+  'assert-visual',
+  'app-content',
+  'app-affordances',
+  'app-intents',
+  'app-go-back',
+  'floating-positions',
+  'theme',
+  'facet-components',
+  // LLP 0140: additive interface-level capability tokens.
+  'mutation.observe-after',
+  'carrier-discovery',
+];
+
+function emit(event: AgentEvent): void {
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch (error) {
+      console.error('[RendererInspector] listener failed:', error);
+    }
+  }
+}
+
+subscribeAgentStateEvents((event) => {
+  emit(event);
+});
+
+function clearInteractionOverrides(): void {
+  textOverrides.clear();
+  toggleOverrides.clear();
+  valueOverrides.clear();
+  scrollOffsets.clear();
+}
+
+function currentTimestamp(): number {
+  return Date.now();
+}
+
+function findLatestSnapshotRecord(rootId?: number): SnapshotRecord | null {
+  for (let index = snapshotOrder.length - 1; index >= 0; index -= 1) {
+    const snapshotId = snapshotOrder[index]!;
+    const record = snapshots.get(snapshotId);
+    if (!record) {
+      continue;
+    }
+    if (rootId == null || record.rootId === rootId) {
+      return record;
+    }
+  }
+  return null;
+}
+
+function nextSnapshotId(): string {
+  sharedState.snapshotCounter += 1;
+  return `s_${currentTimestamp()}_${sharedState.snapshotCounter}`;
+}
+
+function makeRootInfo(root: RootNode): RootInfo {
+  const { width, height } = getScreenDimensions(root.rootId);
+  return {
+    rootId: root.rootId,
+    label: root.rootId === 0 ? 'Main' : `Root ${root.rootId}`,
+    size: {
+      width,
+      height,
+    },
+  };
+}
+
+function getDefaultDimension(base: number, fallback: number): number {
+  return Number.isFinite(base) && base > 0 ? base : fallback;
+}
+
+function resolveDimension(
+  value: unknown,
+  base: number,
+  fallback: number,
+): number {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    'value' in value &&
+    typeof (value as { value?: unknown }).value === 'number'
+  ) {
+    const dimension = value as { type?: unknown; value: number };
+    if (dimension.type === 'points') {
+      return dimension.value;
+    }
+    if (dimension.type === 'percent') {
+      return base * (dimension.value / 100);
+    }
+  }
+
+  return fallback;
+}
+
+function getStyleDimension(
+  style: CanonicalStyle,
+  key: keyof CanonicalStyle,
+  base: number,
+  fallback: number,
+): number {
+  return resolveDimension(style[key], base, fallback);
+}
+
+function getNodeText(node: ElementNode): string {
+  if (node.props.textContent) {
+    return node.props.textContent;
+  }
+
+  let text = '';
+  for (const child of node.children) {
+    if (child.kind === NodeKind.Text) {
+      text += child.text;
+      continue;
+    }
+    text += getNodeText(child);
+  }
+  return text.trim();
+}
+
+function getTestId(node: ElementNode): string | undefined {
+  const candidate =
+    node.originalProps.testId ??
+    node.originalProps.testID ??
+    node.originalProps['data-testid'] ??
+    node.originalProps['data-test-id'] ??
+    node.originalProps.id;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : undefined;
+}
+
+function getEffectiveTextValue(node: ElementNode): string | undefined {
+  if (textOverrides.has(node.id)) {
+    return textOverrides.get(node.id);
+  }
+  return node.props.value;
+}
+
+function getEffectiveToggleValue(node: ElementNode): boolean | undefined {
+  if (toggleOverrides.has(node.id)) {
+    return toggleOverrides.get(node.id);
+  }
+  return node.props.toggleValue;
+}
+
+function getElementLabel(
+  node: ElementNode,
+  labelledByIndex?: Map<string, string>,
+): string | undefined {
+  if (node.props.accessibilityLabel) {
+    return node.props.accessibilityLabel;
+  }
+
+  if (
+    typeof node.props.accessibilityLabelledBy === 'string' &&
+    labelledByIndex?.has(node.props.accessibilityLabelledBy)
+  ) {
+    return labelledByIndex.get(node.props.accessibilityLabelledBy);
+  }
+
+  if (node.tagType === 'input') {
+    return getEffectiveTextValue(node) ?? node.props.placeholder;
+  }
+
+  if (node.tagType === 'toggle') {
+    return node.props.textContent ?? getNodeText(node);
+  }
+
+  const text = getNodeText(node);
+  return text || undefined;
+}
+
+function getImplicitRole(node: ElementNode): string {
+  switch (node.tagType) {
+    case 'pressable':
+      return 'button';
+    case 'input':
+      return 'textbox';
+    case 'toggle':
+      return 'switch';
+    case 'scroll':
+      return 'scrollview';
+    case 'image':
+      return 'image';
+    case 'text':
+      return 'text';
+    default:
+      return 'none';
+  }
+}
+
+function getRole(node: ElementNode): string {
+  if (typeof node.props.accessibilityRole === 'string' && node.props.accessibilityRole.length > 0) {
+    return node.props.accessibilityRole;
+  }
+
+  return getImplicitRole(node);
+}
+
+function getAccessibilityText(node: ElementNode): string | undefined {
+  const text = getNodeText(node);
+  return text.length > 0 ? text : undefined;
+}
+
+function getAccessibilityValue(node: ElementNode): string | undefined {
+  if (typeof node.props.accessibilityValueText === 'string' && node.props.accessibilityValueText.length > 0) {
+    return node.props.accessibilityValueText;
+  }
+  if (typeof node.props.accessibilityValueNow === 'number' && Number.isFinite(node.props.accessibilityValueNow)) {
+    return String(node.props.accessibilityValueNow);
+  }
+  if (node.tagType === 'toggle') {
+    const toggleValue = getEffectiveToggleValue(node);
+    if (typeof toggleValue === 'boolean') {
+      return toggleValue ? 'true' : 'false';
+    }
+  }
+  return getEffectiveTextValue(node);
+}
+
+function getAccessibilityCheckedState(
+  node: ElementNode,
+): AccessibilityNode['checked'] | undefined {
+  const checked = node.props.accessibilityChecked;
+  if (checked === 'mixed') {
+    return 'mixed';
+  }
+  if (typeof checked === 'boolean') {
+    return checked;
+  }
+  const toggleValue = getEffectiveToggleValue(node);
+  return typeof toggleValue === 'boolean' ? toggleValue : undefined;
+}
+
+function getAccessibilityLiveMode(node: ElementNode): AccessibilityNode['live'] | undefined {
+  const live = node.props.accessibilityLive;
+  if (live === 'polite' || live === 'assertive') {
+    return live;
+  }
+  return 'off';
+}
+
+function getAccessibilityActions(node: ElementNode): AccessibilityNode['actions'] {
+  const rawActions = node.props.accessibilityActions ?? node.originalProps.accessibilityActions;
+  const parsed =
+    typeof rawActions === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(rawActions) as unknown;
+          } catch {
+            return [];
+          }
+        })()
+      : rawActions;
+
+  if (!Array.isArray(parsed)) {
+    return [];
+  }
+
+  return parsed.flatMap((action): AccessibilityNode['actions'] => {
+    if (!action || typeof action !== 'object') {
+      return [];
+    }
+    const candidate = action as { name?: unknown; label?: unknown };
+    if (typeof candidate.name !== 'string' || candidate.name.trim().length === 0) {
+      return [];
+    }
+    const name = candidate.name.trim();
+    const label =
+      typeof candidate.label === 'string' && candidate.label.trim().length > 0
+        ? candidate.label.trim()
+        : name;
+    return [{ name, label }];
+  });
+}
+
+function shouldHideAccessibilityElement(node: ElementNode): boolean {
+  return node.props.inert === true || node.props.accessibilityElementsHidden === true;
+}
+
+function shouldFlattenAccessibilityNode(
+  node: ElementNode,
+  role: string,
+  label: string | undefined,
+  hint: string | undefined,
+  actions: AccessibilityNode['actions'],
+  focusable: boolean,
+  childIds: string[],
+): boolean {
+  return (
+    (role === 'generic' || role === 'none') &&
+    !label &&
+    !hint &&
+    (actions?.length ?? 0) === 0 &&
+    !focusable &&
+    node.props.accessibilityBusy !== true &&
+    node.props.accessibilityModal !== true &&
+    node.props.accessibilityExpanded === undefined &&
+    node.props.accessibilitySelected === undefined &&
+    getAccessibilityCheckedState(node) === undefined &&
+    childIds.length > 0 &&
+    node.tagType !== 'text'
+  );
+}
+
+function parseVariantProps(raw: unknown): Record<string, unknown> | undefined {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseNativeViewProps(raw: unknown): Record<string, unknown> | undefined {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// A single inspector snapshot needs to answer two global interaction questions:
+// which modal, if any, currently owns input focus; and whether a given element
+// is therefore effectively inert even if its own props look enabled. We cache
+// that root-level answer once per tree walk so tree serialization, diagnostics,
+// hit testing, and resolve-target all use the same modal view of the world.
+interface InteractionContext {
+  activeModal: ElementNode | null;
+}
+
+function focusScopeModeFromValue(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+  if (value === true) {
+    return 'contained';
+  }
+  return undefined;
+}
+
+function isActiveModalNode(node: ElementNode): boolean {
+  return (
+    node.props.accessibilityModal === true &&
+    node.props.__exactPresencePhase !== 'exiting'
+  );
+}
+
+function buildInteractionContext(root: RootNode): InteractionContext {
+  let activeModal: ElementNode | null = null;
+
+  const walk = (node: HostNode): void => {
+    if (node.kind === NodeKind.Element && isActiveModalNode(node)) {
+      // Later visible modals replace earlier ones so the foreground overlay is
+      // the one that blocks background interactions in the derived snapshot.
+      activeModal = node;
+    }
+
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+
+  walk(root);
+  return {
+    activeModal,
+  };
+}
+
+function isDescendantOfElement(
+  node: HostNode | null,
+  ancestor: ElementNode,
+): boolean {
+  let current = node;
+  while (current) {
+    if (current.kind === NodeKind.Element && current.id === ancestor.id) {
+      return true;
+    }
+    current = current.parent as HostNode | null;
+  }
+  return false;
+}
+
+function blockingModalForElement(
+  node: ElementNode,
+  interactionContext: InteractionContext,
+): ElementNode | null {
+  const activeModal = interactionContext.activeModal;
+  if (!activeModal) {
+    return null;
+  }
+
+  return isDescendantOfElement(node, activeModal) ? null : activeModal;
+}
+
+function recordBehaviorWarning(
+  message: string,
+  rootId: number,
+  context: Record<string, unknown>,
+): void {
+  recordAgentLog({
+    source: 'runtime',
+    level: 'warn',
+    message,
+    rootId,
+    context: {
+      category: 'behavior',
+      ...context,
+    },
+  });
+}
+
+function recordComponentWarning(
+  message: string,
+  rootId: number,
+  context: Record<string, unknown>,
+): void {
+  recordAgentLog({
+    source: 'runtime',
+    level: 'warn',
+    message,
+    rootId,
+    context: {
+      category: 'component',
+      ...context,
+    },
+  });
+}
+
+function buildNativeIdIndex(elements: ElementNode[]): Map<string, ElementNode> {
+  const nativeIds = new Map<string, ElementNode>();
+
+  for (const element of elements) {
+    if (typeof element.props.nativeID === 'string' && element.props.nativeID.length > 0) {
+      nativeIds.set(element.props.nativeID, element);
+    }
+    const testId = getTestId(element);
+    if (testId) {
+      nativeIds.set(testId, element);
+    }
+  }
+
+  return nativeIds;
+}
+
+function buildLabelledByIndex(elements: ElementNode[]): Map<string, string> {
+  const labels = new Map<string, string>();
+
+  for (const element of elements) {
+    const text = getNodeText(element);
+    const label =
+      typeof element.props.accessibilityLabel === 'string' && element.props.accessibilityLabel.length > 0
+        ? element.props.accessibilityLabel
+        : text.length > 0
+          ? text
+          : undefined;
+    if (!label) {
+      continue;
+    }
+    if (typeof element.props.nativeID === 'string' && element.props.nativeID.length > 0) {
+      labels.set(element.props.nativeID, label);
+    }
+    const testId = getTestId(element);
+    if (testId) {
+      labels.set(testId, label);
+    }
+  }
+
+  return labels;
+}
+
+function hasFocusableDescendants(node: ElementNode): boolean {
+  for (const child of node.children) {
+    if (child.kind !== NodeKind.Element) {
+      continue;
+    }
+
+    if (isElementInteractable(child)) {
+      return true;
+    }
+
+    if (hasFocusableDescendants(child)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function analyzeCommitWarnings(root: RootNode): void {
+  // Retained runtime warnings are emitted at commit time so `/agent/logs`
+  // reflects what the app actually rendered, not just what component authors
+  // intended to wire. That makes the warnings actionable for both humans and
+  // automated doctor-style audits.
+  const elements: ElementNode[] = [];
+  flattenElements(root, elements);
+  const nativeIds = buildNativeIdIndex(elements);
+
+  for (const element of elements) {
+    if (
+      typeof element.props.accessibilityLabelledBy === 'string' &&
+      !nativeIds.has(element.props.accessibilityLabelledBy)
+    ) {
+      recordBehaviorWarning('accessibilityLabelledBy target was not found.', root.rootId, {
+        subcategory: 'labelledBy',
+        viewId: element.id,
+        targetId: element.props.accessibilityLabelledBy,
+      });
+    }
+
+    if (
+      typeof element.props.accessibilityDescribedBy === 'string' &&
+      !nativeIds.has(element.props.accessibilityDescribedBy)
+    ) {
+      recordBehaviorWarning('accessibilityDescribedBy target was not found.', root.rootId, {
+        subcategory: 'describedBy',
+        viewId: element.id,
+        targetId: element.props.accessibilityDescribedBy,
+      });
+    }
+
+    const focusScopeMode = focusScopeModeFromValue(element.props.focusScope);
+    if (focusScopeMode && !hasFocusableDescendants(element)) {
+      recordBehaviorWarning('Focus scope has no focusable descendants.', root.rootId, {
+        subcategory: 'focusScope',
+        viewId: element.id,
+        mode: focusScopeMode,
+      });
+    }
+
+    const componentName = typeof element.props.__exactComponentName === 'string'
+      ? element.props.__exactComponentName.split('.')[0] ?? element.props.__exactComponentName
+      : undefined;
+    const slotName =
+      typeof element.props.__exactComponentSlot === 'string'
+        ? element.props.__exactComponentSlot
+        : undefined;
+
+    if (
+      (componentName === 'Dialog' || componentName === 'AlertDialog' || componentName === 'Sheet') &&
+      slotName === 'content' &&
+      typeof element.props.accessibilityLabelledBy !== 'string'
+    ) {
+      recordComponentWarning('Facet dialog content is missing accessibilityLabelledBy wiring.', root.rootId, {
+        subcategory: 'missing-label',
+        componentName,
+        viewId: element.id,
+      });
+    }
+
+    if (
+      componentName === 'Toast' &&
+      slotName === 'root' &&
+      typeof element.props.accessibilityLive !== 'string'
+    ) {
+      recordComponentWarning('Facet toast root is missing accessibilityLive semantics.', root.rootId, {
+        subcategory: 'missing-live-region',
+        componentName,
+        viewId: element.id,
+      });
+    }
+  }
+}
+
+registerInspectorCommitAnalyzer(analyzeCommitWarnings);
+
+function resetFullInspectorAgentState(): void {
+  _resetAgentLogState();
+  resetAgentStateTracking();
+}
+
+registerInspectorResetHook(resetFullInspectorAgentState);
+
+function buildBehaviorMetadata(node: ElementNode): ViewNode['behaviors'] {
+  const behaviors: NonNullable<ViewNode['behaviors']> = {};
+  const semanticState: NonNullable<NonNullable<ViewNode['behaviors']>['semanticState']> = {};
+
+  if (node.props.focusScope !== undefined) {
+    behaviors.focusScope = node.props.focusScope;
+  }
+  if (node.props.__exactFocusRestore === true) {
+    behaviors.focusRestore = true;
+  }
+  if (node.props.inert === true) {
+    behaviors.inert = true;
+  }
+  if (node.props.scrollLocked === true) {
+    behaviors.scrollLocked = true;
+  }
+  if (node.props.__exactDismissableLayer === true) {
+    behaviors.dismissableLayer = true;
+  }
+  if (typeof node.props.__exactDismissAction === 'string') {
+    behaviors.dismissAction = node.props.__exactDismissAction;
+  }
+  if (typeof node.props.accessibilityRole === 'string') {
+    behaviors.accessibilityRole = node.props.accessibilityRole;
+  }
+  if (typeof node.props.accessibilityModal === 'boolean') {
+    behaviors.accessibilityModal = node.props.accessibilityModal;
+  }
+  if (typeof node.props.accessibilityExpanded === 'boolean') {
+    semanticState.expanded = node.props.accessibilityExpanded;
+  }
+  if (typeof node.props.accessibilitySelected === 'boolean') {
+    semanticState.selected = node.props.accessibilitySelected;
+  }
+  if (
+    typeof node.props.accessibilityChecked === 'boolean' ||
+    node.props.accessibilityChecked === 'mixed'
+  ) {
+    semanticState.checked = node.props.accessibilityChecked;
+  }
+  if (typeof node.props.disabled === 'boolean') {
+    semanticState.disabled = node.props.disabled;
+  } else if (typeof node.props.accessibilityDisabled === 'boolean') {
+    semanticState.disabled = node.props.accessibilityDisabled;
+  }
+  if (typeof node.props.accessibilityValueText === 'string') {
+    semanticState.valueText = node.props.accessibilityValueText;
+  }
+  if (Object.keys(semanticState).length > 0) {
+    behaviors.semanticState = semanticState;
+  }
+
+  return Object.keys(behaviors).length > 0 ? behaviors : undefined;
+}
+
+function buildAnchorMetadata(node: ElementNode): ViewNode['anchor'] {
+  if (typeof node.props.__exactAnchorTarget !== 'string') {
+    return undefined;
+  }
+
+  return {
+    target: node.props.__exactAnchorTarget,
+    placement:
+      typeof node.props.__exactAnchorPlacement === 'string'
+        ? node.props.__exactAnchorPlacement
+        : undefined,
+    strategy:
+      typeof node.props.__exactAnchorStrategy === 'string'
+        ? node.props.__exactAnchorStrategy
+        : undefined,
+    offset:
+      typeof node.props.__exactAnchorOffset === 'number'
+        ? node.props.__exactAnchorOffset
+        : undefined,
+  };
+}
+
+function buildPortalMetadata(node: ElementNode): ViewNode['portal'] {
+  if (
+    node.props.portalTarget === undefined &&
+    node.props.__exactPortalLevel === undefined &&
+    node.props.__exactPortalPresentation === undefined
+  ) {
+    return undefined;
+  }
+
+  return {
+    target: typeof node.props.portalTarget === 'string' ? node.props.portalTarget : undefined,
+    level:
+      typeof node.props.__exactPortalLevel === 'string'
+        ? node.props.__exactPortalLevel
+        : undefined,
+    presentation:
+      typeof node.props.__exactPortalPresentation === 'string'
+        ? node.props.__exactPortalPresentation
+        : undefined,
+  };
+}
+
+function buildDevProvenance(node: ElementNode): ViewNode['devProvenance'] {
+  if (
+    node.props.__exactComponentName === undefined &&
+    node.props.__exactSourceFilePath === undefined
+  ) {
+    return undefined;
+  }
+
+  return {
+    componentName:
+      typeof node.props.__exactComponentName === 'string'
+        ? node.props.__exactComponentName
+        : undefined,
+    slotName:
+      typeof node.props.__exactComponentSlot === 'string'
+        ? node.props.__exactComponentSlot
+        : undefined,
+    sourceFilePath:
+      typeof node.props.__exactSourceFilePath === 'string'
+        ? node.props.__exactSourceFilePath
+        : undefined,
+    variantProps: parseVariantProps(node.props.__exactVariantProps),
+  };
+}
+
+function buildSafeAreaSnapshot(
+  node: ElementNode,
+): SafeAreaNodeSnapshotData | undefined {
+  const safeArea = node.safeAreaState;
+  if (!safeArea) {
+    return undefined;
+  }
+
+  return {
+    strategy: safeArea.strategy,
+    regions: [...safeArea.config.regions],
+    edges: { ...safeArea.config.edges },
+    sourceRegions: {
+      container: { ...safeArea.sourceRegions.container },
+      displayCutout: { ...safeArea.sourceRegions.displayCutout },
+      gestures: { ...safeArea.sourceRegions.gestures },
+    },
+    siblingExpansion: { ...safeArea.siblingExpansion },
+    availableInsets: { ...safeArea.availableInsets },
+    keyboardOverlap: { ...safeArea.keyboardOverlap },
+    appliedInsets: { ...safeArea.appliedInsets },
+    remainingRegions: {
+      container: { ...safeArea.remainingRegions.container },
+      displayCutout: { ...safeArea.remainingRegions.displayCutout },
+      gestures: { ...safeArea.remainingRegions.gestures },
+    },
+    keyboardState: {
+      ...safeArea.keyboardState,
+      occlusion: { ...safeArea.keyboardState.occlusion },
+    },
+  };
+}
+
+function findFacetComponentInfo(node: ElementNode): ViewNode['component'] {
+  const componentName = node.props.__exactComponentName;
+  if (typeof componentName !== 'string' || componentName.length === 0) {
+    return undefined;
+  }
+
+  const baseName = componentName.split('.')[0] ?? componentName;
+  return getFacetComponents().find((entry) => entry.name === baseName);
+}
+
+function computeWhyNotInteractable(
+  node: ElementNode,
+  floating: ViewNode['floating'],
+  presencePhase: ViewNode['presencePhase'],
+  interactionContext: InteractionContext,
+): string | undefined {
+  if (node.props.disabled === true || node.props.accessibilityDisabled === true) {
+    return 'disabled';
+  }
+  if (node.props.inert === true) {
+    return 'inert-explicit';
+  }
+  if (isElementInteractable(node) && blockingModalForElement(node, interactionContext)) {
+    return 'inert-modal';
+  }
+  if (presencePhase === 'exiting') {
+    return 'presence-exiting';
+  }
+  if (floating?.scrolling === true) {
+    return 'floating-scrolling';
+  }
+  if (floating?.state === 'premeasure') {
+    return 'floating-premeasure';
+  }
+  if (
+    floating?.state === 'hidden-anchor-escaped' ||
+    floating?.state === 'hidden-reference-hidden' ||
+    floating?.state === 'hidden-anchor-removed'
+  ) {
+    return 'floating-hidden';
+  }
+  return undefined;
+}
+
+function isElementInteractable(node: ElementNode): boolean {
+  if (node.props.inert || node.props.disabled || node.props.accessibilityDisabled) {
+    return false;
+  }
+
+  return (
+    node.events.has(EventType.Press) ||
+    node.events.has(EventType.PressIn) ||
+    node.events.has(EventType.PressOut) ||
+    node.events.has(EventType.LongPress) ||
+    node.events.has(EventType.Change) ||
+    node.events.has(EventType.Focus) ||
+    node.events.has(EventType.KeyDown) ||
+    node.props.focusable === true ||
+    node.tagType === 'pressable' ||
+    node.tagType === 'input' ||
+    node.tagType === 'toggle' ||
+    node.tagType === 'scroll'
+  );
+}
+
+function getResolvedTarget(node: ElementNode, ref?: ElementRef): ResolvedTarget {
+  return {
+    ref,
+    viewId: node.id,
+    type: node.originalTag,
+    label: getElementLabel(node),
+    testId: getTestId(node),
+  };
+}
+
+function approximateTextFrame(text: string, parentFrame: Frame): Frame {
+  return {
+    x: parentFrame.x,
+    y: parentFrame.y,
+    width: Math.max(0, Math.min(parentFrame.width, text.length * 7)),
+    height: 18,
+  };
+}
+
+function getDefaultNodeSize(
+  node: ElementNode,
+  availableWidth: number,
+  availableHeight: number,
+): { width: number; height: number } {
+  switch (node.tagType) {
+    case 'text':
+      return {
+        width: Math.min(availableWidth, Math.max(32, getNodeText(node).length * 7)),
+        height: 20,
+      };
+    case 'input':
+      return { width: Math.min(availableWidth, 240), height: 44 };
+    case 'toggle':
+      return { width: Math.min(availableWidth, 120), height: 32 };
+    case 'image':
+      return { width: Math.min(availableWidth, 120), height: 120 };
+    case 'pressable':
+      return { width: Math.min(availableWidth, 160), height: 44 };
+    default:
+      return {
+        width: getDefaultDimension(availableWidth, 120),
+        height: Math.min(getDefaultDimension(availableHeight, 120), 120),
+      };
+  }
+}
+
+function resolveOptionalDimension(value: unknown, base: number): number | undefined {
+  const resolved = resolveDimension(value, base, Number.NaN);
+  return Number.isFinite(resolved) ? Math.max(0, resolved) : undefined;
+}
+
+function getStyleNumber(style: CanonicalStyle, key: keyof CanonicalStyle): number | undefined {
+  const value = style[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function constrainSize(
+  style: CanonicalStyle,
+  width: number,
+  height: number,
+  containingWidth: number,
+  containingHeight: number,
+): { width: number; height: number } {
+  const minWidth = resolveOptionalDimension(style.minWidth, containingWidth);
+  const minHeight = resolveOptionalDimension(style.minHeight, containingHeight);
+  const maxWidth = resolveOptionalDimension(style.maxWidth, containingWidth);
+  const maxHeight = resolveOptionalDimension(style.maxHeight, containingHeight);
+
+  let constrainedWidth = width;
+  let constrainedHeight = height;
+
+  if (minWidth !== undefined) constrainedWidth = Math.max(constrainedWidth, minWidth);
+  if (minHeight !== undefined) constrainedHeight = Math.max(constrainedHeight, minHeight);
+  if (maxWidth !== undefined) constrainedWidth = Math.min(constrainedWidth, maxWidth);
+  if (maxHeight !== undefined) constrainedHeight = Math.min(constrainedHeight, maxHeight);
+
+  return {
+    width: Math.max(0, constrainedWidth),
+    height: Math.max(0, constrainedHeight),
+  };
+}
+
+function getMainAxisGap(style: CanonicalStyle, direction: CanonicalStyle['flexDirection']): number {
+  const rawGap = direction === 'row'
+    ? getStyleNumber(style, 'columnGap')
+    : getStyleNumber(style, 'rowGap');
+  return rawGap !== undefined ? Math.max(0, rawGap) : 0;
+}
+
+function getCrossAxisGap(style: CanonicalStyle, direction: CanonicalStyle['flexDirection']): number {
+  const rawGap = direction === 'row'
+    ? getStyleNumber(style, 'rowGap')
+    : getStyleNumber(style, 'columnGap');
+  return rawGap !== undefined ? Math.max(0, rawGap) : 0;
+}
+
+function hasFlexWrap(style: CanonicalStyle): boolean {
+  return style.flexWrap === 'wrap' || style.flexWrap === 'wrap-reverse';
+}
+
+function computeIntrinsicElementSize(
+  node: ElementNode,
+  availableWidth: number,
+  availableHeight: number,
+  depth = 0,
+): { width: number; height: number } {
+  const defaultSize = getDefaultNodeSize(node, availableWidth, availableHeight);
+  const explicitWidth = resolveOptionalDimension(node.style.width, availableWidth);
+  const explicitHeight = resolveOptionalDimension(node.style.height, availableHeight);
+
+  const canUseChildIntrinsicSize =
+    node.tagType === 'view' ||
+    node.tagType === 'scroll' ||
+    (node.tagType === 'pressable' && node.children.length > 0);
+
+  if (depth > 16 || !canUseChildIntrinsicSize) {
+    return constrainSize(
+      node.style,
+      explicitWidth ?? defaultSize.width,
+      explicitHeight ?? defaultSize.height,
+      availableWidth,
+      availableHeight,
+    );
+  }
+
+  const paddingTop = getStyleDimension(node.style, 'paddingTop', availableHeight, 0);
+  const paddingRight = getStyleDimension(node.style, 'paddingRight', availableWidth, 0);
+  const paddingBottom = getStyleDimension(node.style, 'paddingBottom', availableHeight, 0);
+  const paddingLeft = getStyleDimension(node.style, 'paddingLeft', availableWidth, 0);
+  const contentWidth = Math.max(0, availableWidth - paddingLeft - paddingRight);
+  const contentHeight = Math.max(0, availableHeight - paddingTop - paddingBottom);
+  const direction = node.style.flexDirection ?? 'column';
+  const gap = getMainAxisGap(node.style, direction);
+  const crossGap = getCrossAxisGap(node.style, direction);
+  const shouldWrap = direction === 'row' && hasFlexWrap(node.style);
+
+  let mainSize = 0;
+  let crossSize = 0;
+  let normalChildCount = 0;
+  let lineMainSize = 0;
+  let lineCrossSize = 0;
+  let lineCount = 0;
+  let lineChildCount = 0;
+
+  const commitLine = (): void => {
+    if (lineChildCount === 0) {
+      return;
+    }
+    mainSize = Math.max(mainSize, lineMainSize);
+    crossSize += lineCrossSize;
+    lineCount += 1;
+    lineMainSize = 0;
+    lineCrossSize = 0;
+    lineChildCount = 0;
+  };
+
+  for (const child of node.children) {
+    const childSize = child.kind === NodeKind.Text
+      ? approximateTextFrame(child.text, {
+          x: 0,
+          y: 0,
+          width: contentWidth,
+          height: contentHeight,
+        })
+      : computeIntrinsicElementSize(child, contentWidth, contentHeight, depth + 1);
+
+    const style = child.kind === NodeKind.Element ? child.style : ({} as CanonicalStyle);
+    const marginTop = getStyleDimension(style, 'marginTop', contentHeight, 0);
+    const marginRight = getStyleDimension(style, 'marginRight', contentWidth, 0);
+    const marginBottom = getStyleDimension(style, 'marginBottom', contentHeight, 0);
+    const marginLeft = getStyleDimension(style, 'marginLeft', contentWidth, 0);
+
+    if (direction === 'row') {
+      const childMain = childSize.width + marginLeft + marginRight;
+      const childCross = childSize.height + marginTop + marginBottom;
+      if (shouldWrap) {
+        const nextLineMain = lineChildCount > 0
+          ? lineMainSize + gap + childMain
+          : childMain;
+        if (lineChildCount > 0 && nextLineMain > contentWidth + 0.5) {
+          commitLine();
+        }
+        lineMainSize = lineChildCount > 0
+          ? lineMainSize + gap + childMain
+          : childMain;
+        lineCrossSize = Math.max(lineCrossSize, childCross);
+        lineChildCount += 1;
+      } else {
+        mainSize += childMain;
+        crossSize = Math.max(crossSize, childCross);
+      }
+    } else {
+      mainSize += childSize.height + marginTop + marginBottom;
+      crossSize = Math.max(crossSize, childSize.width + marginLeft + marginRight);
+    }
+
+    normalChildCount += 1;
+  }
+
+  if (shouldWrap) {
+    commitLine();
+    if (lineCount > 1) {
+      crossSize += crossGap * (lineCount - 1);
+    }
+  } else if (normalChildCount > 1) {
+    mainSize += gap * (normalChildCount - 1);
+  }
+
+  const intrinsicWidth = direction === 'row'
+    ? mainSize + paddingLeft + paddingRight
+    : crossSize + paddingLeft + paddingRight;
+  const intrinsicHeight = direction === 'row'
+    ? crossSize + paddingTop + paddingBottom
+    : mainSize + paddingTop + paddingBottom;
+
+  return constrainSize(
+    node.style,
+    explicitWidth ?? (intrinsicWidth > 0 ? intrinsicWidth : defaultSize.width),
+    explicitHeight ?? (intrinsicHeight > 0 ? intrinsicHeight : defaultSize.height),
+    availableWidth,
+    availableHeight,
+  );
+}
+
+function getBridge():
+  | {
+      getLayout?: (viewId: number) => Frame | null;
+      getAbsoluteLayout?: (viewId: number) => Frame | null;
+      getLayoutGeneration?: () => number;
+      hitTest?: (x: number, y: number) => number | null;
+    }
+  | null {
+  const bridge = (globalThis as { exact?: unknown }).exact;
+  return typeof bridge === 'object' && bridge !== null
+    ? (bridge as {
+        getLayout?: (viewId: number) => Frame | null;
+        getAbsoluteLayout?: (viewId: number) => Frame | null;
+        getLayoutGeneration?: () => number;
+        hitTest?: (x: number, y: number) => number | null;
+      })
+    : null;
+}
+
+function computeApproximateFrames(root: RootNode): Map<number, Frame> {
+  const frames = new Map<number, Frame>();
+  const viewport = getScreenDimensions(root.rootId);
+  const rootFrame: Frame = {
+    x: 0,
+    y: 0,
+    width: viewport.width,
+    height: viewport.height,
+  };
+
+  frames.set(root.id, rootFrame);
+
+  const layoutChildren = (
+    parent: RootNode | ElementNode,
+    parentFrame: Frame,
+  ): void => {
+    const children = parent.kind === NodeKind.Root ? parent.children : parent.children;
+    const style = parent.kind === NodeKind.Root ? ({} as CanonicalStyle) : parent.style;
+    const paddingTop = parent.kind === NodeKind.Root ? 0 : getStyleDimension(style, 'paddingTop', parentFrame.height, 0);
+    const paddingRight = parent.kind === NodeKind.Root ? 0 : getStyleDimension(style, 'paddingRight', parentFrame.width, 0);
+    const paddingBottom = parent.kind === NodeKind.Root ? 0 : getStyleDimension(style, 'paddingBottom', parentFrame.height, 0);
+    const paddingLeft = parent.kind === NodeKind.Root ? 0 : getStyleDimension(style, 'paddingLeft', parentFrame.width, 0);
+    const contentX = parentFrame.x + paddingLeft;
+    const contentY = parentFrame.y + paddingTop;
+    const contentWidth = Math.max(0, parentFrame.width - paddingLeft - paddingRight);
+    const contentHeight = Math.max(0, parentFrame.height - paddingTop - paddingBottom);
+    const direction = parent.kind === NodeKind.Root ? 'column' : (parent.style.flexDirection ?? 'column');
+    const alignItems = parent.kind === NodeKind.Root ? 'stretch' : (style.alignItems ?? 'stretch');
+    const scrollOffset =
+      parent.kind === NodeKind.Root ||
+      (parent.kind === NodeKind.Element && parent.tagType === 'scroll')
+        ? scrollOffsets.get(parent.id) ?? { x: 0, y: 0 }
+        : { x: 0, y: 0 };
+    const gap = getMainAxisGap(style, direction);
+    const contentMainSize = direction === 'row' ? contentWidth : contentHeight;
+
+    type LayoutEntry = {
+      child: ElementNode | TextNode;
+      width: number;
+      height: number;
+      marginTop: number;
+      marginRight: number;
+      marginBottom: number;
+      marginLeft: number;
+      isAbsolute: boolean;
+      absoluteLeft: number;
+      absoluteTop: number;
+      flexGrow: number;
+    };
+
+    const entries: LayoutEntry[] = [];
+    let normalEntryCount = 0;
+    let occupiedMainSize = 0;
+    let totalFlexGrow = 0;
+
+    for (const child of children) {
+      if (child.kind === NodeKind.Text) {
+        const textFrame = approximateTextFrame(
+          child.text,
+          {
+            x: 0,
+            y: 0,
+            width: contentWidth,
+            height: contentHeight,
+          },
+        );
+        entries.push({
+          child,
+          width: textFrame.width,
+          height: textFrame.height,
+          marginTop: 0,
+          marginRight: 0,
+          marginBottom: 0,
+          marginLeft: 0,
+          isAbsolute: false,
+          absoluteLeft: Number.NaN,
+          absoluteTop: Number.NaN,
+          flexGrow: 0,
+        });
+        normalEntryCount += 1;
+        occupiedMainSize += direction === 'row' ? textFrame.width : textFrame.height;
+        continue;
+      }
+
+      const marginTop = getStyleDimension(child.style, 'marginTop', contentHeight, 0);
+      const marginRight = getStyleDimension(child.style, 'marginRight', contentWidth, 0);
+      const marginBottom = getStyleDimension(child.style, 'marginBottom', contentHeight, 0);
+      const marginLeft = getStyleDimension(child.style, 'marginLeft', contentWidth, 0);
+      const intrinsicSize = computeIntrinsicElementSize(child, contentWidth, contentHeight);
+      const explicitWidth = resolveOptionalDimension(child.style.width, contentWidth);
+      const explicitHeight = resolveOptionalDimension(child.style.height, contentHeight);
+      const flexGrow = Math.max(0, getStyleNumber(child.style, 'flexGrow') ?? 0);
+      const flexBasis = resolveOptionalDimension(child.style.flexBasis, contentMainSize);
+      const isAbsolute = child.style.positionType === 'absolute';
+      const alignSelf = child.style.alignSelf ?? 'auto';
+      const crossAxisAlign = alignSelf === 'auto' ? alignItems : alignSelf;
+
+      let width = explicitWidth ?? (direction === 'row'
+        ? intrinsicSize.width
+        : (!isAbsolute && crossAxisAlign === 'stretch' ? contentWidth : intrinsicSize.width));
+      let height = explicitHeight ?? (direction === 'row' && !isAbsolute && crossAxisAlign === 'stretch' && !hasFlexWrap(style)
+        ? contentHeight
+        : intrinsicSize.height);
+
+      if (direction === 'row' && flexGrow > 0 && explicitWidth === undefined) {
+        width = flexBasis ?? 0;
+      } else if (direction !== 'row' && flexGrow > 0 && explicitHeight === undefined) {
+        height = flexBasis ?? 0;
+      }
+
+      ({ width, height } = constrainSize(
+        child.style,
+        width,
+        height,
+        contentWidth,
+        contentHeight,
+      ));
+
+      const absoluteLeft = resolveDimension(child.style.left, contentWidth, Number.NaN);
+      const absoluteTop = resolveDimension(child.style.top, contentHeight, Number.NaN);
+
+      entries.push({
+        child,
+        width,
+        height,
+        marginTop,
+        marginRight,
+        marginBottom,
+        marginLeft,
+        isAbsolute,
+        absoluteLeft,
+        absoluteTop,
+        flexGrow,
+      });
+
+      if (!isAbsolute) {
+        normalEntryCount += 1;
+        totalFlexGrow += flexGrow;
+        occupiedMainSize += direction === 'row'
+          ? width + marginLeft + marginRight
+          : height + marginTop + marginBottom;
+      }
+    }
+
+    if (normalEntryCount > 1) {
+      occupiedMainSize += gap * (normalEntryCount - 1);
+    }
+
+    const remainingMainSize = Math.max(0, contentMainSize - occupiedMainSize);
+    if (totalFlexGrow > 0 && remainingMainSize > 0) {
+      for (const entry of entries) {
+        if (entry.isAbsolute || entry.flexGrow <= 0) {
+          continue;
+        }
+
+        const delta = remainingMainSize * (entry.flexGrow / totalFlexGrow);
+        if (direction === 'row') {
+          entry.width += delta;
+        } else {
+          entry.height += delta;
+        }
+      }
+    }
+
+    let cursorX = contentX - scrollOffset.x;
+    let cursorY = contentY - scrollOffset.y;
+
+    if (direction === 'row' && hasFlexWrap(style)) {
+      type FlexLine = {
+        entries: LayoutEntry[];
+        mainSize: number;
+        crossSize: number;
+      };
+      const lines: FlexLine[] = [];
+      let currentLine: FlexLine = {
+        entries: [],
+        mainSize: 0,
+        crossSize: 0,
+      };
+      const commitLine = (): void => {
+        if (currentLine.entries.length === 0) {
+          return;
+        }
+        lines.push(currentLine);
+        currentLine = {
+          entries: [],
+          mainSize: 0,
+          crossSize: 0,
+        };
+      };
+
+      for (const entry of entries) {
+        if (entry.isAbsolute) {
+          continue;
+        }
+
+        const entryMain = entry.width + entry.marginLeft + entry.marginRight;
+        const entryCross = entry.height + entry.marginTop + entry.marginBottom;
+        const nextMain = currentLine.entries.length > 0
+          ? currentLine.mainSize + gap + entryMain
+          : entryMain;
+        if (currentLine.entries.length > 0 && nextMain > contentWidth + 0.5) {
+          commitLine();
+        }
+        currentLine.mainSize = currentLine.entries.length > 0
+          ? currentLine.mainSize + gap + entryMain
+          : entryMain;
+        currentLine.crossSize = Math.max(currentLine.crossSize, entryCross);
+        currentLine.entries.push(entry);
+      }
+      commitLine();
+
+      const crossGap = getCrossAxisGap(style, direction);
+      const orderedLines = style.flexWrap === 'wrap-reverse'
+        ? [...lines].reverse()
+        : lines;
+      let lineY = contentY - scrollOffset.y;
+
+      for (let lineIndex = 0; lineIndex < orderedLines.length; lineIndex += 1) {
+        const line = orderedLines[lineIndex]!;
+        let lineX = contentX - scrollOffset.x;
+        for (let entryIndex = 0; entryIndex < line.entries.length; entryIndex += 1) {
+          const entry = line.entries[entryIndex]!;
+          const { child } = entry;
+          const frame: Frame = {
+            x: lineX + entry.marginLeft,
+            y: lineY + entry.marginTop,
+            width: entry.width,
+            height: entry.height,
+          };
+          frames.set(child.id, frame);
+          if (child.kind === NodeKind.Element) {
+            layoutChildren(child, frame);
+          }
+          lineX += entry.width + entry.marginLeft + entry.marginRight +
+            (entryIndex < line.entries.length - 1 ? gap : 0);
+        }
+        lineY += line.crossSize + (lineIndex < orderedLines.length - 1 ? crossGap : 0);
+      }
+
+      for (const entry of entries) {
+        if (!entry.isAbsolute) {
+          continue;
+        }
+        const { child } = entry;
+        const frame: Frame = {
+          x: Number.isFinite(entry.absoluteLeft)
+            ? contentX + entry.absoluteLeft + entry.marginLeft
+            : contentX + entry.marginLeft,
+          y: Number.isFinite(entry.absoluteTop)
+            ? contentY + entry.absoluteTop + entry.marginTop
+            : contentY + entry.marginTop,
+          width: entry.width,
+          height: entry.height,
+        };
+        frames.set(child.id, frame);
+        if (child.kind === NodeKind.Element) {
+          layoutChildren(child, frame);
+        }
+      }
+      return;
+    }
+
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+      const { child } = entry;
+      const x = entry.isAbsolute && Number.isFinite(entry.absoluteLeft)
+        ? contentX + entry.absoluteLeft + entry.marginLeft
+        : cursorX + entry.marginLeft;
+      const y = entry.isAbsolute && Number.isFinite(entry.absoluteTop)
+        ? contentY + entry.absoluteTop + entry.marginTop
+        : cursorY + entry.marginTop;
+
+      const frame: Frame = { x, y, width: entry.width, height: entry.height };
+      frames.set(child.id, frame);
+      if (child.kind === NodeKind.Element) {
+        layoutChildren(child, frame);
+      }
+
+      if (entry.isAbsolute) {
+        continue;
+      }
+
+      if (direction === 'row') {
+        cursorX += entry.width + entry.marginLeft + entry.marginRight + (index < entries.length - 1 ? gap : 0);
+      } else {
+        cursorY += entry.height + entry.marginTop + entry.marginBottom + (index < entries.length - 1 ? gap : 0);
+      }
+    }
+  };
+
+  layoutChildren(root, rootFrame);
+  return frames;
+}
+
+function buildFrameIndex(root: RootNode): Map<number, Frame> {
+  const bridge = getBridge();
+  const approximate = computeApproximateFrames(root);
+  if (!bridge?.getLayout) {
+    applyFloatingPositionFrames(root, approximate);
+    return approximate;
+  }
+
+  const applyKernelFrames = (node: HostNode): void => {
+    const kernelFrame = bridge.getAbsoluteLayout?.(node.id) ?? bridge.getLayout?.(node.id);
+    if (kernelFrame) {
+      approximate.set(node.id, kernelFrame);
+    }
+
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (const child of node.children) {
+        applyKernelFrames(child);
+      }
+    }
+  };
+
+  applyKernelFrames(root);
+  applyFloatingPositionFrames(root, approximate);
+  return approximate;
+}
+
+function isFiniteFrame(frame: Frame): boolean {
+  return (
+    Number.isFinite(frame.x) &&
+    Number.isFinite(frame.y) &&
+    Number.isFinite(frame.width) &&
+    Number.isFinite(frame.height)
+  );
+}
+
+function translateSubtreeFrames(
+  node: HostNode,
+  frames: Map<number, Frame>,
+  dx: number,
+  dy: number,
+): void {
+  if (dx === 0 && dy === 0) {
+    return;
+  }
+
+  const frame = frames.get(node.id);
+  if (frame) {
+    frames.set(node.id, {
+      ...frame,
+      x: frame.x + dx,
+      y: frame.y + dy,
+    });
+  }
+
+  if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+    for (const child of node.children) {
+      translateSubtreeFrames(child, frames, dx, dy);
+    }
+  }
+}
+
+function applyFloatingPositionFrames(
+  root: RootNode,
+  frames: Map<number, Frame>,
+): void {
+  const visit = (node: HostNode): void => {
+    if (node.kind === NodeKind.Element) {
+      const floating = findFloatingPositionByViewId(node.id);
+      if (floating?.positioned === true) {
+        const current = frames.get(node.id);
+        const next: Frame = {
+          x: floating.x,
+          y: floating.y,
+          width: floating.width,
+          height: floating.height,
+        };
+
+        if (current && isFiniteFrame(next)) {
+          translateSubtreeFrames(node, frames, next.x - current.x, next.y - current.y);
+          frames.set(node.id, next);
+        }
+      }
+    }
+
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (const child of node.children) {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+}
+
+function resolveRootAndNodeByViewId(viewId: number): {
+  root: RootNode;
+  node: ElementNode;
+  frames: Map<number, Frame>;
+} | null {
+  for (const root of roots.values()) {
+    const node = findNodeByViewId(root, viewId);
+    if (node?.kind === NodeKind.Element) {
+      return {
+        root,
+        node,
+        frames: buildFrameIndex(root),
+      };
+    }
+  }
+
+  return null;
+}
+
+export function queryClippingAncestorsForViewId(viewId: number): ClipChainEntry[] {
+  const resolved = resolveRootAndNodeByViewId(viewId);
+  if (!resolved) {
+    return [];
+  }
+
+  const entries: ClipChainEntry[] = [];
+  let ancestor: HostNode | null = resolved.node.parent as HostNode | null;
+
+  while (ancestor) {
+    const ancestorFrame = resolved.frames.get(ancestor.id);
+    const clipsDescendants =
+      ancestor.kind === NodeKind.Root ||
+      (ancestor.kind === NodeKind.Element &&
+        (ancestor.tagType === 'scroll' ||
+          ancestor.style.overflow === 'hidden' ||
+          ancestor.style.overflow === 'scroll'));
+
+    if (clipsDescendants && ancestorFrame) {
+      const type =
+        ancestor.kind === NodeKind.Root
+          ? 'Root'
+          : ancestor.kind === NodeKind.Element
+            ? ancestor.originalTag
+            : 'Unknown';
+      entries.push({
+        viewId: ancestor.id,
+        type,
+        frame: ancestorFrame,
+        overflow: ancestor.kind === NodeKind.Element ? ancestor.style.overflow : undefined,
+      });
+    }
+
+    ancestor = ancestor.parent as HostNode | null;
+  }
+
+  return entries;
+}
+
+export function queryClippingBoundaryForViewId(viewId: number): Frame | null {
+  const resolved = resolveRootAndNodeByViewId(viewId);
+  if (!resolved) {
+    return null;
+  }
+
+  const viewport = resolved.frames.get(resolved.root.id) ?? {
+    x: 0,
+    y: 0,
+    width: getScreenDimensions(resolved.root.rootId).width,
+    height: getScreenDimensions(resolved.root.rootId).height,
+  };
+  const ancestors = queryClippingAncestorsForViewId(viewId);
+
+  return ancestors.reduce<Frame>((boundary, entry) => {
+    const nextX = Math.max(boundary.x, entry.frame.x);
+    const nextY = Math.max(boundary.y, entry.frame.y);
+    const nextRight = Math.min(boundary.x + boundary.width, entry.frame.x + entry.frame.width);
+    const nextBottom = Math.min(boundary.y + boundary.height, entry.frame.y + entry.frame.height);
+
+    return {
+      x: nextX,
+      y: nextY,
+      width: Math.max(0, nextRight - nextX),
+      height: Math.max(0, nextBottom - nextY),
+    };
+  }, viewport);
+}
+
+function makeViewNode(
+  node: HostNode,
+  frames: Map<number, Frame>,
+  refs: Record<ElementRef, ElementRefInfo>,
+  depth: number | undefined,
+  refCounter: { value: number },
+  interactionContext: InteractionContext,
+): ViewNode {
+  const frame = frames.get(node.id) ?? { x: 0, y: 0, width: 0, height: 0 };
+  const shouldDescend = depth === undefined || depth > 0;
+  const nextDepth = depth === undefined ? undefined : Math.max(0, depth - 1);
+
+  if (node.kind === NodeKind.Root) {
+    const theme = getThemeSnapshot() ?? undefined;
+    return {
+      viewId: node.id,
+      type: 'View',
+      frame,
+      props: {
+        rootId: node.rootId,
+        layoutGeneration: getBridge()?.getLayoutGeneration?.() ?? 0,
+      },
+      style: {},
+      theme,
+      children: shouldDescend
+        ? node.children.map((child) =>
+            makeViewNode(child, frames, refs, nextDepth, refCounter, interactionContext),
+          )
+        : [],
+    };
+  }
+
+  if (node.kind === NodeKind.Text) {
+    return {
+      viewId: node.id,
+      type: 'Text',
+      frame,
+      text: node.text,
+      props: {},
+      style: {},
+      children: [],
+    };
+  }
+
+  const label = getElementLabel(node);
+  const testId = getTestId(node);
+  const shouldAssignRef = isElementInteractable(node) || typeof testId === 'string';
+  const ref = shouldAssignRef ? (`@e${refCounter.value++}` as ElementRef) : undefined;
+
+  if (ref) {
+    refs[ref] = {
+      ref,
+      viewId: node.id,
+      type: node.originalTag,
+      label,
+      testId,
+      frame,
+    };
+  }
+
+  const props: Record<string, unknown> = {
+    ...node.props,
+    testId,
+  };
+
+  const floating = findFloatingPositionByViewId(node.id) ?? undefined;
+  const behaviors = buildBehaviorMetadata(node);
+  const portal = buildPortalMetadata(node);
+  const anchor = buildAnchorMetadata(node);
+  const presencePhase =
+    typeof node.props.__exactPresencePhase === 'string'
+      ? node.props.__exactPresencePhase
+      : undefined;
+  const component = findFacetComponentInfo(node);
+  const devProvenance = buildDevProvenance(node);
+
+  if (textOverrides.has(node.id)) {
+    props.value = textOverrides.get(node.id);
+  }
+  if (toggleOverrides.has(node.id)) {
+    props.toggleValue = toggleOverrides.get(node.id);
+  }
+  if (valueOverrides.has(node.id)) {
+    const overriddenValue = valueOverrides.get(node.id);
+    props.value = overriddenValue;
+    if (typeof overriddenValue === 'number') {
+      props.accessibilityValueNow = overriddenValue;
+    }
+  }
+  if (scrollOffsets.has(node.id)) {
+    props.contentOffset = scrollOffsets.get(node.id);
+  }
+  if (typeof node.props.__exactRenderMode === 'string') {
+    // `__exactRenderMode` is an implementation detail on the host node, but
+    // agents need a stable public field that answers the RFC 0073 question
+    // directly: is this control taking the native or composed path?
+    props.renderMode = node.props.__exactRenderMode;
+    delete props.__exactRenderMode;
+  }
+  if (node.tagType === 'nativeView') {
+    if (typeof node.props.nativeViewModuleName === 'string') {
+      props.moduleName = node.props.nativeViewModuleName;
+    }
+
+    const moduleProps = parseNativeViewProps(node.props.nativeViewProps);
+    if (moduleProps) {
+      if (valueOverrides.has(node.id)) {
+        moduleProps.value = valueOverrides.get(node.id);
+      }
+      props.moduleProps = moduleProps;
+    }
+
+    // The raw transport fields stay useful internally, but they are noisy in
+    // the public tree. Expose the friendlier `moduleName` / `moduleProps`
+    // projection instead so agents do not need to decode renderer internals.
+    delete props.nativeViewModuleName;
+    delete props.nativeViewProps;
+  }
+  const safeArea = buildSafeAreaSnapshot(node);
+  if (safeArea) {
+    props.safeArea = safeArea;
+  }
+
+  return {
+    viewId: node.id,
+    type: node.originalTag,
+    frame,
+    ref,
+    text: getNodeText(node) || undefined,
+    props,
+    style: { ...node.style },
+    behaviors,
+    portal,
+    anchor,
+    presencePhase,
+    whyNotInteractable: computeWhyNotInteractable(
+      node,
+      floating,
+      presencePhase,
+      interactionContext,
+    ),
+    devProvenance,
+    floating,
+    component,
+    children: shouldDescend
+      ? node.children.map((child) =>
+          makeViewNode(child, frames, refs, nextDepth, refCounter, interactionContext),
+        )
+      : [],
+  };
+}
+
+function flattenElements(node: HostNode, elements: ElementNode[]): void {
+  if (node.kind === NodeKind.Element) {
+    elements.push(node);
+  }
+
+  if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+    for (const child of node.children) {
+      flattenElements(child, elements);
+    }
+  }
+}
+
+function collectSerializedViewIds(node: ViewNode, ids: Set<number>): void {
+  ids.add(node.viewId);
+  for (const child of node.children) {
+    collectSerializedViewIds(child, ids);
+  }
+}
+
+function findNodeByViewId(node: HostNode, viewId: number): HostNode | null {
+  if (node.id === viewId) {
+    return node;
+  }
+
+  if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+    for (const child of node.children) {
+      const match = findNodeByViewId(child, viewId);
+      if (match) {
+        return match;
+      }
+    }
+  }
+
+  return null;
+}
+
+function normalizeLookup(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function pointInFrame(point: Point, frame: Frame): boolean {
+  return (
+    point.x >= frame.x &&
+    point.y >= frame.y &&
+    point.x <= frame.x + frame.width &&
+    point.y <= frame.y + frame.height
+  );
+}
+
+function framesIntersect(left: Frame, right: Frame): boolean {
+  return !(
+    left.x + left.width <= right.x ||
+    right.x + right.width <= left.x ||
+    left.y + left.height <= right.y ||
+    right.y + right.height <= left.y
+  );
+}
+
+function findElementByPoint(
+  root: RootNode,
+  frames: Map<number, Frame>,
+  point: Point,
+): ElementNode | null {
+  const visit = (node: HostNode): ElementNode | null => {
+    const frame = frames.get(node.id);
+    if (!frame || !pointInFrame(point, frame)) {
+      return null;
+    }
+
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (let index = node.children.length - 1; index >= 0; index -= 1) {
+        const child = node.children[index];
+        const match = visit(child);
+        if (match) {
+          return match;
+        }
+      }
+    }
+
+    return node.kind === NodeKind.Element ? node : null;
+  };
+
+  const bridge = getBridge();
+  if (bridge?.hitTest) {
+    const viewId = bridge.hitTest(point.x, point.y);
+    if (typeof viewId === 'number' && viewId >= 0) {
+      const exactMatch = findNodeByViewId(root, viewId);
+      return exactMatch?.kind === NodeKind.Element ? exactMatch : null;
+    }
+  }
+
+  return visit(root);
+}
+
+function nearestActionableElement(node: ElementNode | null): ElementNode | null {
+  let current: HostNode | null = node;
+  while (current) {
+    if (current.kind === NodeKind.Element && isElementInteractable(current)) {
+      return current;
+    }
+    current = current.parent as HostNode | null;
+  }
+  return null;
+}
+
+function resolveRoot(rootId?: number): RootNode | null {
+  if (typeof rootId === 'number') {
+    return roots.get(rootId) ?? null;
+  }
+  return roots.get(0) ?? roots.values().next().value ?? null;
+}
+
+export function registerRoot(root: RootNode): void {
+  roots.set(root.rootId, root);
+  sharedState.stateVersion += 1;
+  emit({
+    type: 'connect',
+    rootId: root.rootId,
+    label: makeRootInfo(root).label,
+    size: makeRootInfo(root).size,
+  });
+}
+
+export function unregisterRoot(rootId: number): void {
+  if (!roots.delete(rootId)) {
+    return;
+  }
+  sharedState.stateVersion += 1;
+  emit({
+    type: 'disconnect',
+    reason: `root:${rootId}:unregistered`,
+    exitCode: null,
+    signal: null,
+  });
+}
+
+export function notifyCommit(
+  root: RootNode,
+  options: {
+    changedViews?: Iterable<number>;
+    analyzeWarnings?: boolean;
+  } = {},
+): void {
+  roots.set(root.rootId, root);
+  sharedState.frameCount += 1;
+  sharedState.stateVersion += 1;
+  sharedState.lastCommitAt = currentTimestamp();
+  recordCommitTimestamp(sharedState.lastCommitAt);
+  if (options.analyzeWarnings !== false) {
+    analyzeCommitWarnings(root);
+  }
+
+  if (listeners.size === 0) {
+    return;
+  }
+
+  const changedViews =
+    options.changedViews !== undefined
+      ? Array.from(options.changedViews)
+      : (() => {
+          const collected: number[] = [];
+          const collect = (node: HostNode): void => {
+            collected.push(node.id);
+            if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+              for (const child of node.children) {
+                collect(child);
+              }
+            }
+          };
+          collect(root);
+          return collected;
+        })();
+
+  emit({
+    type: 'render',
+    frameCount: sharedState.frameCount,
+    changedViews,
+  });
+}
+
+export function emitInspectorError(
+  error: unknown,
+  options: {
+    source?: 'runtime' | 'agent';
+    rootId?: number;
+    componentStack?: string;
+    context?: Record<string, unknown>;
+  } = {},
+): void {
+  const message =
+    error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+  const latestSnapshot = findLatestSnapshotRecord(options.rootId);
+  recordAgentLog({
+    source: options.source ?? 'runtime',
+    level: 'error',
+    message,
+    stack: error instanceof Error ? error.stack : undefined,
+    componentStack: options.componentStack,
+    context: options.context,
+    rootId: latestSnapshot?.rootId,
+    snapshotId: latestSnapshot?.snapshotId,
+  });
+  emit({
+    type: 'error',
+    message,
+    stack: error instanceof Error ? error.stack : undefined,
+  });
+}
+
+export function emitInspectorEvent(event: AgentEvent): void {
+  emit(event);
+}
+
+export function subscribeAgentEvents(listener: InspectorListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function getFrameCount(): number {
+  return sharedState.frameCount;
+}
+
+export function getAgentCapabilities(): AgentCapability[] {
+  return AGENT_CAPABILITIES.slice();
+}
+
+export function getStateVersion(): number {
+  return sharedState.stateVersion;
+}
+
+export function getLastCommitAt(): number {
+  return sharedState.lastCommitAt;
+}
+
+export function getRootsSnapshot(): RootInfo[] {
+  return Array.from(roots.values()).map(makeRootInfo);
+}
+
+export function getRootNode(rootId?: number): RootNode | null {
+  return resolveRoot(rootId);
+}
+
+export function serializeTree(
+  rootId?: number,
+  depth?: number,
+  viewId?: number,
+): SerializedSnapshot {
+  const root = resolveRoot(rootId);
+  if (!root) {
+    throw new Error('No active Exact roots');
+  }
+
+  const frames = buildFrameIndex(root);
+  const refs: Record<ElementRef, ElementRefInfo> = {};
+  const refCounter = { value: 1 };
+  const source = typeof viewId === 'number' ? findNodeByViewId(root, viewId) ?? root : root;
+  const interactionContext = buildInteractionContext(root);
+
+  return {
+    root: makeViewNode(source, frames, refs, depth, refCounter, interactionContext),
+    refs,
+    frames,
+  };
+}
+
+export function serializeLayout(
+  rootId?: number,
+  viewId?: number,
+): { frames: Array<Frame & { viewId: number }>; refs: Record<ElementRef, ElementRefInfo> } {
+  const snapshot = serializeTree(rootId, undefined, viewId);
+  const resolvedRoot = resolveRoot(rootId);
+  const includedViewIds = new Set<number>();
+  collectSerializedViewIds(snapshot.root, includedViewIds);
+  const frames: Array<Frame & { viewId: number }> = [];
+  for (const [id, frame] of snapshot.frames) {
+    if (!includedViewIds.has(id)) {
+      continue;
+    }
+    const node = resolvedRoot ? findNodeByViewId(resolvedRoot, id) : null;
+    const safeArea =
+      node && node.kind === NodeKind.Element
+        ? buildSafeAreaSnapshot(node)
+        : undefined;
+    frames.push({
+      viewId: id,
+      ...frame,
+      ...(safeArea ? { safeArea } : {}),
+    });
+  }
+  frames.sort((left, right) => left.viewId - right.viewId);
+  return {
+    frames,
+    refs: snapshot.refs,
+  };
+}
+
+export function serializeAccessibility(rootId?: number): AccessibilitySnapshot {
+  const root = resolveRoot(rootId);
+  if (!root) {
+    throw new Error('No active Exact roots');
+  }
+
+  const frames = buildFrameIndex(root);
+  const refs: Record<ElementRef, ElementRefInfo> = {};
+  const nodes: AccessibilityNode[] = [];
+  const refCounter = { value: 1 };
+  const elements: ElementNode[] = [];
+  flattenElements(root, elements);
+  const labelledByIndex = buildLabelledByIndex(elements);
+  const visitElement = (element: ElementNode): string[] => {
+    if (shouldHideAccessibilityElement(element)) {
+      return [];
+    }
+
+    const childIds: string[] = [];
+    for (const child of element.children) {
+      if (child.kind === NodeKind.Element) {
+        childIds.push(...visitElement(child));
+      }
+    }
+
+    const role = getRole(element);
+    const implicitRole = getImplicitRole(element);
+    const label = getElementLabel(element, labelledByIndex);
+    const hint =
+      typeof element.props.accessibilityHint === 'string' &&
+      element.props.accessibilityHint.length > 0
+        ? element.props.accessibilityHint
+        : undefined;
+    const actions = getAccessibilityActions(element);
+    const focusable =
+      element.props.focusable === true ||
+      (typeof element.props.tabIndex === 'number' && element.props.tabIndex >= 0) ||
+      isElementInteractable(element);
+
+    if (role === 'presentation') {
+      return [];
+    }
+
+    if (shouldFlattenAccessibilityNode(element, role, label, hint, actions, focusable, childIds)) {
+      return childIds;
+    }
+
+    const frame = frames.get(element.id) ?? { x: 0, y: 0, width: 0, height: 0 };
+    const testId = getTestId(element);
+    const ref = `@e${refCounter.value++}` as ElementRef;
+    const id = `v${element.id}`;
+    refs[ref] = {
+      ref,
+      viewId: element.id,
+      type: element.originalTag,
+      label,
+      testId,
+      frame,
+    };
+
+    nodes.push({
+      id,
+      viewId: element.id,
+      ref,
+      role,
+      implicitRole,
+      explicitRole:
+        typeof element.props.accessibilityRole === 'string' &&
+        element.props.accessibilityRole.length > 0
+          ? element.props.accessibilityRole
+          : undefined,
+      label,
+      name: label ?? element.originalTag,
+      hint,
+      text: getAccessibilityText(element),
+      value: getAccessibilityValue(element),
+      valueNow:
+        typeof element.props.accessibilityValueNow === 'number' &&
+        Number.isFinite(element.props.accessibilityValueNow)
+          ? element.props.accessibilityValueNow
+          : undefined,
+      valueMin:
+        typeof element.props.accessibilityValueMin === 'number' &&
+        Number.isFinite(element.props.accessibilityValueMin)
+          ? element.props.accessibilityValueMin
+          : undefined,
+      valueMax:
+        typeof element.props.accessibilityValueMax === 'number' &&
+        Number.isFinite(element.props.accessibilityValueMax)
+          ? element.props.accessibilityValueMax
+          : undefined,
+      expanded:
+        typeof element.props.accessibilityExpanded === 'boolean'
+          ? element.props.accessibilityExpanded
+          : undefined,
+      selected:
+        typeof element.props.accessibilitySelected === 'boolean'
+          ? element.props.accessibilitySelected
+          : undefined,
+      checked: getAccessibilityCheckedState(element),
+      disabled:
+        element.props.disabled === true || element.props.accessibilityDisabled === true,
+      busy: element.props.accessibilityBusy === true,
+      modal: element.props.accessibilityModal === true,
+      focusable,
+      live: getAccessibilityLiveMode(element),
+      labelledBy:
+        typeof element.props.accessibilityLabelledBy === 'string' &&
+        element.props.accessibilityLabelledBy.length > 0
+          ? element.props.accessibilityLabelledBy
+          : undefined,
+      describedBy:
+        typeof element.props.accessibilityDescribedBy === 'string' &&
+        element.props.accessibilityDescribedBy.length > 0
+          ? element.props.accessibilityDescribedBy
+          : undefined,
+      headingLevel:
+        typeof element.props.accessibilityHeadingLevel === 'number'
+          ? element.props.accessibilityHeadingLevel
+          : undefined,
+      nativeID:
+        typeof element.props.nativeID === 'string' && element.props.nativeID.length > 0
+          ? element.props.nativeID
+          : undefined,
+      testId,
+      tabIndex:
+        typeof element.props.tabIndex === 'number' && Number.isFinite(element.props.tabIndex)
+          ? element.props.tabIndex
+          : undefined,
+      synthetic: element.props.accessibilitySynthetic === true,
+      actions,
+      children: childIds,
+    });
+
+    return [id];
+  };
+
+  for (const child of root.children) {
+    if (child.kind === NodeKind.Element) {
+      visitElement(child);
+    }
+  }
+
+  return { nodes, refs };
+}
+
+export function rememberSnapshot(
+  rootId: number,
+  refs: Record<ElementRef, ElementRefInfo>,
+  tree?: ViewNode,
+): SnapshotRecord {
+  const record: SnapshotRecord = {
+    snapshotId: nextSnapshotId(),
+    rootId,
+    stateVersion: sharedState.stateVersion,
+    timestamp: currentTimestamp(),
+    frameCount: sharedState.frameCount,
+    refs,
+    tree,
+  };
+  snapshots.set(record.snapshotId, record);
+  snapshotOrder.push(record.snapshotId);
+
+  while (snapshotOrder.length > MAX_SNAPSHOTS) {
+    const oldest = snapshotOrder.shift();
+    if (oldest) {
+      snapshots.delete(oldest);
+    }
+  }
+
+  return record;
+}
+
+export function getSnapshot(snapshotId: string): SnapshotRecord | null {
+  return snapshots.get(snapshotId) ?? null;
+}
+
+export function snapshotIsCurrent(snapshotId: string): boolean {
+  const snapshot = getSnapshot(snapshotId);
+  return snapshot !== null && snapshot.stateVersion === sharedState.stateVersion;
+}
+
+export function getLatestSnapshotId(): string | null {
+  return snapshotOrder.length > 0
+    ? snapshotOrder[snapshotOrder.length - 1]!
+    : null;
+}
+
+export function setTextValue(viewId: number, value: string): void {
+  textOverrides.set(viewId, value);
+}
+
+export function setToggleValue(viewId: number, value: boolean): void {
+  toggleOverrides.set(viewId, value);
+}
+
+export function setControlValue(viewId: number, value: unknown): void {
+  valueOverrides.set(viewId, value);
+}
+
+export function applyScrollDelta(viewId: number, dx: number, dy: number): Point {
+  const current = scrollOffsets.get(viewId) ?? { x: 0, y: 0 };
+  const next = {
+    x: current.x + dx,
+    y: current.y + dy,
+  };
+  scrollOffsets.set(viewId, next);
+  return next;
+}
+
+export function setScrollOffset(viewId: number, offset: Point): Point {
+  const next = {
+    x: offset.x,
+    y: offset.y,
+  };
+  scrollOffsets.set(viewId, next);
+  return next;
+}
+
+function normalizeScrollCoordinate(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function syncInspectorScrollOffset(
+  viewId: number,
+  offset: Point,
+  rootId?: number,
+): Point | null {
+  const root = resolveRoot(rootId);
+  if (!root || !findNodeByViewId(root, viewId)) {
+    return null;
+  }
+
+  const next = setScrollOffset(viewId, {
+    x: normalizeScrollCoordinate(offset?.x),
+    y: normalizeScrollCoordinate(offset?.y),
+  });
+  notifyCommit(root);
+  return next;
+}
+
+globalThis.__exactSetInspectorScrollOffset = syncInspectorScrollOffset;
+
+export function getScrollMetrics(
+  viewId: number,
+  rootId?: number,
+): ResolveTargetScrollAncestor | null {
+  const root = resolveRoot(rootId);
+  if (!root) {
+    return null;
+  }
+
+  const node = findNodeByViewId(root, viewId);
+  if (
+    !node ||
+    !(
+      node.kind === NodeKind.Root ||
+      (node.kind === NodeKind.Element && node.tagType === 'scroll')
+    )
+  ) {
+    return null;
+  }
+
+  const snapshot = serializeTree(root.rootId);
+  const refIndex = new Map<number, ElementRef>();
+  for (const [ref, info] of Object.entries(snapshot.refs)) {
+    refIndex.set(info.viewId, ref as ElementRef);
+  }
+
+  return scrollAncestorSnapshot(node, snapshot.frames, refIndex);
+}
+
+export function getTextForView(viewId: number, rootId?: number): string | undefined {
+  const root = resolveRoot(rootId);
+  if (!root) {
+    return undefined;
+  }
+  const node = findNodeByViewId(root, viewId);
+  if (!node || node.kind !== NodeKind.Element) {
+    return undefined;
+  }
+  return (getEffectiveTextValue(node) ?? getNodeText(node)) || undefined;
+}
+
+export function resolveElement(
+  selector: {
+    ref?: ElementRef;
+    snapshotId?: string;
+    testId?: string;
+    nativeID?: string;
+    label?: string;
+    viewId?: number;
+    x?: number;
+    y?: number;
+    rootId?: number;
+  },
+): ResolvedElement | null {
+  if (selector.ref) {
+    if (!selector.snapshotId) {
+      throw new Error('snapshotId is required when using refs');
+    }
+    const snapshot = getSnapshot(selector.snapshotId);
+    if (!snapshot) {
+      throw new Error(`Unknown snapshot ${selector.snapshotId}`);
+    }
+    const root = resolveRoot(snapshot.rootId);
+    if (!root) {
+      return null;
+    }
+    const ref = snapshot.refs[selector.ref];
+    if (!ref) {
+      return null;
+    }
+    const node = findNodeByViewId(root, ref.viewId);
+    if (!node || node.kind !== NodeKind.Element) {
+      return null;
+    }
+    const frames = buildFrameIndex(root);
+    return {
+      root,
+      element: node,
+      frame: frames.get(node.id) ?? ref.frame,
+    };
+  }
+
+  const root = resolveRoot(selector.rootId);
+  if (!root) {
+    return null;
+  }
+
+  const frames = buildFrameIndex(root);
+
+  if (typeof selector.viewId === 'number') {
+    const node = findNodeByViewId(root, selector.viewId);
+    if (node?.kind === NodeKind.Element) {
+      return {
+        root,
+        element: node,
+        frame: frames.get(node.id) ?? { x: 0, y: 0, width: 0, height: 0 },
+      };
+    }
+    return null;
+  }
+
+  if (typeof selector.x === 'number' && typeof selector.y === 'number') {
+    const node = findElementByPoint(root, frames, { x: selector.x, y: selector.y });
+    if (!node) {
+      return null;
+    }
+    return {
+      root,
+      element: node,
+      frame: frames.get(node.id) ?? { x: selector.x, y: selector.y, width: 0, height: 0 },
+    };
+  }
+
+  const elements: ElementNode[] = [];
+  flattenElements(root, elements);
+
+  if (selector.testId) {
+    const matches = elements.filter((element) => getTestId(element) === selector.testId);
+    if (matches.length === 0) {
+      return null;
+    }
+    if (matches.length > 1) {
+      throw new Error(`Ambiguous testId ${selector.testId}`);
+    }
+    return {
+      root,
+      element: matches[0],
+      frame: frames.get(matches[0].id) ?? { x: 0, y: 0, width: 0, height: 0 },
+    };
+  }
+
+  if (selector.nativeID) {
+    const nativeIds = buildNativeIdIndex(elements);
+    const match = nativeIds.get(selector.nativeID);
+    if (!match) {
+      return null;
+    }
+    return {
+      root,
+      element: match,
+      frame: frames.get(match.id) ?? { x: 0, y: 0, width: 0, height: 0 },
+    };
+  }
+
+  if (selector.label) {
+    const normalized = normalizeLookup(selector.label);
+    const matches = elements.filter((element) => normalizeLookup(getElementLabel(element) ?? '') === normalized);
+    if (matches.length === 0) {
+      return null;
+    }
+    if (matches.length > 1) {
+      throw new Error(`Ambiguous label ${selector.label}`);
+    }
+    return {
+      root,
+      element: matches[0],
+      frame: frames.get(matches[0].id) ?? { x: 0, y: 0, width: 0, height: 0 },
+    };
+  }
+
+  return null;
+}
+
+export function resolveActionableElement(
+  selector: Parameters<typeof resolveElement>[0],
+): ResolvedElement | null {
+  const resolved = resolveElement(selector);
+  if (!resolved) {
+    return null;
+  }
+  const actionable = nearestActionableElement(resolved.element);
+  if (!actionable) {
+    return resolved;
+  }
+  const frames = buildFrameIndex(resolved.root);
+  return {
+    root: resolved.root,
+    element: actionable,
+    frame: frames.get(actionable.id) ?? resolved.frame,
+  };
+}
+
+function nearestChangeElement(node: ElementNode | null): ElementNode | null {
+  let current: HostNode | null = node;
+  while (current) {
+    if (current.kind === NodeKind.Element && current.events.has(EventType.Change)) {
+      return current;
+    }
+    current = current.parent as HostNode | null;
+  }
+  return null;
+}
+
+function findDescendantChangeElement(node: ElementNode): ElementNode | null {
+  if (node.events.has(EventType.Change)) {
+    return node;
+  }
+
+  for (const child of node.children) {
+    if (child.kind !== NodeKind.Element) {
+      continue;
+    }
+
+    const match = findDescendantChangeElement(child);
+    if (match) {
+      return match;
+    }
+  }
+
+  return null;
+}
+
+export function resolveChangeElement(
+  selector: Parameters<typeof resolveElement>[0],
+): ResolvedElement | null {
+  const resolved = resolveElement(selector);
+  if (!resolved) {
+    return null;
+  }
+
+  // `exact_set_value` often targets a Facet wrapper by testId while the actual
+  // Change handler lives on an inner native-view leaf. Search upward first so a
+  // hit inside an input/slider resolves to the bound control, then search
+  // downward so wrapper nodes still find their change-capable descendant.
+  const target =
+    nearestChangeElement(resolved.element) ??
+    findDescendantChangeElement(resolved.element);
+  if (!target) {
+    return resolved;
+  }
+
+  const frames = buildFrameIndex(resolved.root);
+  return {
+    root: resolved.root,
+    element: target,
+    frame: frames.get(target.id) ?? resolved.frame,
+  };
+}
+
+export function buildHitTestBlockers(
+  element: ElementNode | null,
+  frame: Frame | null,
+  options: {
+    root?: RootNode | null;
+    point?: Point;
+    interactionContext?: InteractionContext;
+  } = {},
+): HitTestBlocker[] {
+  if (!element || !frame) {
+    return [{ reason: 'offScreen' }];
+  }
+
+  const point = options.point ?? getElementCenter(frame);
+  const blockers: HitTestBlocker[] = [];
+
+  if (frame.width <= 0 || frame.height <= 0) {
+    blockers.push({ reason: 'zeroSize' });
+  }
+
+  if (element.props.disabled) {
+    blockers.push({
+      reason: 'disabled',
+      by: {
+        viewId: element.id,
+        type: element.originalTag,
+        label: getElementLabel(element),
+        frame,
+      },
+    });
+  }
+
+  const root = options.root;
+  if (!root) {
+    return blockers;
+  }
+
+  const frames = buildFrameIndex(root);
+  const interactionContext = options.interactionContext ?? buildInteractionContext(root);
+  const blockingModal = blockingModalForElement(element, interactionContext);
+  if (blockingModal) {
+    blockers.push({
+      reason: 'inert',
+      by: {
+        viewId: blockingModal.id,
+        type: blockingModal.originalTag,
+        label: getElementLabel(blockingModal),
+        frame: frames.get(blockingModal.id) ?? undefined,
+      },
+    });
+  }
+  const floating = findFloatingPositionByViewId(element.id);
+  if (floating?.scrolling === true) {
+    blockers.push({
+      reason: 'scrolling',
+      by: {
+        viewId: element.id,
+        type: element.originalTag,
+        label: getElementLabel(element),
+        frame,
+      },
+    });
+  }
+  const rootFrame = frames.get(root.id);
+  if (rootFrame && !pointInFrame(point, rootFrame)) {
+    blockers.push({ reason: 'offScreen' });
+  }
+
+  let ancestor: HostNode | null = element.parent as HostNode | null;
+  while (ancestor) {
+    if (ancestor.kind === NodeKind.Element) {
+      const ancestorFrame = frames.get(ancestor.id);
+      const clipsDescendants =
+        ancestor.tagType === 'scroll' ||
+        ancestor.style.overflow === 'hidden' ||
+        ancestor.style.overflow === 'scroll';
+      if (
+        clipsDescendants &&
+        ancestorFrame &&
+        (!framesIntersect(frame, ancestorFrame) || !pointInFrame(point, ancestorFrame))
+      ) {
+        blockers.push({
+          reason: 'clipped',
+          by: {
+            viewId: ancestor.id,
+            type: ancestor.originalTag,
+            label: getElementLabel(ancestor),
+            frame: ancestorFrame,
+          },
+        });
+        break;
+      }
+    }
+    ancestor = ancestor.parent as HostNode | null;
+  }
+
+  const target = nearestActionableElement(element) ?? element;
+  const topmost = nearestActionableElement(findElementByPoint(root, frames, point));
+  if (topmost && topmost.id !== target.id) {
+    const topmostFrame = frames.get(topmost.id) ?? null;
+    blockers.push({
+      reason: 'overlapped',
+      by: {
+        viewId: topmost.id,
+        type: topmost.originalTag,
+        label: getElementLabel(topmost),
+        frame: topmostFrame ?? undefined,
+      },
+    });
+  }
+
+  return blockers;
+}
+
+function buildViewIdToRefIndex(
+  refs: Record<ElementRef, ElementRefInfo>,
+): Map<number, ElementRef> {
+  const index = new Map<number, ElementRef>();
+  for (const [ref, info] of Object.entries(refs) as Array<[ElementRef, ElementRefInfo]>) {
+    index.set(info.viewId, ref);
+  }
+  return index;
+}
+
+function intersectFrames(left: Frame, right: Frame): Frame | null {
+  const x = Math.max(left.x, right.x);
+  const y = Math.max(left.y, right.y);
+  const maxX = Math.min(left.x + left.width, right.x + right.width);
+  const maxY = Math.min(left.y + left.height, right.y + right.height);
+  const width = maxX - x;
+  const height = maxY - y;
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+  return { x, y, width, height };
+}
+
+function frameEquals(left: Frame, right: Frame): boolean {
+  return (
+    left.x === right.x &&
+    left.y === right.y &&
+    left.width === right.width &&
+    left.height === right.height
+  );
+}
+
+function unionFrames(left: Frame | null, right: Frame | null): Frame | null {
+  if (!left) {
+    return right ? { ...right } : null;
+  }
+  if (!right) {
+    return { ...left };
+  }
+  const x = Math.min(left.x, right.x);
+  const y = Math.min(left.y, right.y);
+  const maxX = Math.max(left.x + left.width, right.x + right.width);
+  const maxY = Math.max(left.y + left.height, right.y + right.height);
+  return {
+    x,
+    y,
+    width: maxX - x,
+    height: maxY - y,
+  };
+}
+
+function patternMatches(
+  value: string | undefined,
+  pattern: string | TextPattern | undefined,
+): boolean {
+  if (pattern === undefined) {
+    return true;
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    return false;
+  }
+  if (typeof pattern === 'string') {
+    return normalizeLookup(value).includes(normalizeLookup(pattern));
+  }
+  try {
+    return new RegExp(pattern.regex, pattern.flags).test(value);
+  } catch {
+    return false;
+  }
+}
+
+function computeDescendantBounds(
+  node: ElementNode | RootNode,
+  frames: Map<number, Frame>,
+): Frame | null {
+  let bounds: Frame | null = frames.get(node.id) ?? null;
+  for (const child of node.children) {
+    if (child.kind === NodeKind.Element) {
+      bounds = unionFrames(bounds, computeDescendantBounds(child, frames));
+      continue;
+    }
+    bounds = unionFrames(bounds, frames.get(child.id) ?? null);
+  }
+  return bounds;
+}
+
+function scrollAncestorSnapshot(
+  ancestor: ElementNode | RootNode,
+  frames: Map<number, Frame>,
+  refIndex: Map<number, ElementRef>,
+): ResolveTargetScrollAncestor {
+  const frame = frames.get(ancestor.id) ?? { x: 0, y: 0, width: 0, height: 0 };
+  const bounds = computeDescendantBounds(ancestor, frames);
+  const offset = scrollOffsets.get(ancestor.id) ?? { x: 0, y: 0 };
+  const contentWidth = bounds
+    ? Math.max(frame.width, bounds.x + bounds.width - frame.x + offset.x)
+    : frame.width;
+  const contentHeight = bounds
+    ? Math.max(frame.height, bounds.y + bounds.height - frame.y + offset.y)
+    : frame.height;
+
+  return {
+    viewId: ancestor.id,
+    ref: ancestor.kind === NodeKind.Element ? refIndex.get(ancestor.id) : undefined,
+    type: ancestor.kind === NodeKind.Element ? ancestor.originalTag : 'Root',
+    currentOffset: { ...offset },
+    contentSize: {
+      width: contentWidth,
+      height: contentHeight,
+    },
+    viewportSize: {
+      width: frame.width,
+      height: frame.height,
+    },
+  };
+}
+
+function rootScrollAncestorSnapshot(
+  ancestor: RootNode,
+  frames: Map<number, Frame>,
+  refIndex: Map<number, ElementRef>,
+): ResolveTargetScrollAncestor | null {
+  const snapshot = scrollAncestorSnapshot(ancestor, frames, refIndex);
+  const hasOffset =
+    snapshot.currentOffset.x !== 0 || snapshot.currentOffset.y !== 0;
+  const hasScrollableContent =
+    snapshot.contentSize.width > snapshot.viewportSize.width ||
+    snapshot.contentSize.height > snapshot.viewportSize.height;
+  return hasOffset || hasScrollableContent ? snapshot : null;
+}
+
+function occlusionFromBy(
+  by:
+    | {
+        viewId: number;
+        ref?: ElementRef;
+        type: string;
+        label?: string;
+      }
+    | undefined,
+): ResolveTargetOcclusion | undefined {
+  if (!by) {
+    return undefined;
+  }
+  return {
+    viewId: by.viewId,
+    ref: by.ref,
+    type: by.type,
+    label: by.label,
+  };
+}
+
+function computeScrollDeltaForViewport(frame: Frame, viewport: Frame): Point {
+  let x = 0;
+  let y = 0;
+
+  if (frame.x < viewport.x) {
+    x = frame.x - viewport.x;
+  } else if (frame.x + frame.width > viewport.x + viewport.width) {
+    x = frame.x + frame.width - (viewport.x + viewport.width);
+  }
+
+  if (frame.y < viewport.y) {
+    y = frame.y - viewport.y;
+  } else if (frame.y + frame.height > viewport.y + viewport.height) {
+    y = frame.y + frame.height - (viewport.y + viewport.height);
+  }
+
+  return { x, y };
+}
+
+function visibilityStateForRects(frame: Frame, visibleRect: Frame | null): VisibilityState {
+  if (!visibleRect || visibleRect.width <= 0 || visibleRect.height <= 0) {
+    return 'none';
+  }
+  return frameEquals(frame, visibleRect) ? 'full' : 'partial';
+}
+
+function buildResolveTargetDataForElement(
+  root: RootNode,
+  element: ElementNode,
+  frames: Map<number, Frame>,
+  refIndex: Map<number, ElementRef>,
+  explicitRef?: ElementRef,
+  interactionContext: InteractionContext = buildInteractionContext(root),
+): ResolveTargetData {
+  const frame = frames.get(element.id) ?? { x: 0, y: 0, width: 0, height: 0 };
+  let visibleRect: Frame | null = frame.width > 0 && frame.height > 0 ? { ...frame } : null;
+  let clipAncestor: ResolveTargetOcclusion | undefined;
+  let recommendedScrollDelta: ResolveTargetData['recommendedScrollDelta'];
+  const scrollChain: ResolveTargetScrollAncestor[] = [];
+
+  let ancestor: HostNode | null = element.parent as HostNode | null;
+  while (ancestor) {
+    if (ancestor.kind === NodeKind.Element || ancestor.kind === NodeKind.Root) {
+      const ancestorFrame = frames.get(ancestor.id);
+      const scrollAncestor =
+        ancestor.kind === NodeKind.Element && ancestor.tagType === 'scroll'
+          ? scrollAncestorSnapshot(ancestor, frames, refIndex)
+          : ancestor.kind === NodeKind.Root
+            ? rootScrollAncestorSnapshot(ancestor, frames, refIndex)
+            : null;
+      if (scrollAncestor) {
+        scrollChain.push(scrollAncestor);
+      }
+
+      const clipsDescendants =
+        ancestor.kind === NodeKind.Root ||
+        (ancestor.kind === NodeKind.Element &&
+          (ancestor.tagType === 'scroll' ||
+            ancestor.style.overflow === 'hidden' ||
+            ancestor.style.overflow === 'scroll'));
+
+      if (clipsDescendants && ancestorFrame && visibleRect) {
+        const nextVisibleRect = intersectFrames(visibleRect, ancestorFrame);
+        const wasClipped =
+          !nextVisibleRect || !frameEquals(visibleRect, nextVisibleRect);
+
+        if (wasClipped && !clipAncestor) {
+          clipAncestor = {
+            viewId: ancestor.id,
+            ref: ancestor.kind === NodeKind.Element ? refIndex.get(ancestor.id) : undefined,
+            type: ancestor.kind === NodeKind.Element ? ancestor.originalTag : 'Root',
+            label: ancestor.kind === NodeKind.Element ? getElementLabel(ancestor) : undefined,
+          };
+        }
+
+        if (
+          wasClipped &&
+          !recommendedScrollDelta &&
+          scrollAncestor
+        ) {
+          const delta = computeScrollDeltaForViewport(frame, ancestorFrame);
+          if (delta.x !== 0 || delta.y !== 0) {
+            recommendedScrollDelta = {
+              ancestor: {
+                viewId: scrollAncestor.viewId,
+                ref: scrollAncestor.ref,
+                type: scrollAncestor.type,
+              },
+              delta,
+            };
+          }
+        }
+
+        visibleRect = nextVisibleRect;
+      }
+    }
+    ancestor = ancestor.parent as HostNode | null;
+  }
+
+  const visibility = visibilityStateForRects(frame, visibleRect);
+  const tapPoint = visibleRect ? getElementCenter(visibleRect) : null;
+  const blockers = buildHitTestBlockers(element, frame, {
+    root,
+    point: tapPoint ?? getElementCenter(frame),
+    interactionContext,
+  });
+  const occludedBy = blockers
+    .filter((blocker) => blocker.reason === 'overlapped')
+    .map((blocker) => occlusionFromBy(blocker.by))
+    .filter((value): value is ResolveTargetOcclusion => value !== undefined);
+  const interactable =
+    visibility !== 'none' &&
+    elementIsInteractable(element) &&
+    blockers.length === 0;
+
+  return {
+    target: getResolvedTarget(element, explicitRef ?? refIndex.get(element.id)),
+    frame,
+    visibleRect,
+    visibility,
+    occludedBy: occludedBy.length > 0 ? occludedBy : undefined,
+    clipAncestor,
+    scrollChain,
+    interactable,
+    recommendedTapPoint: interactable ? tapPoint : null,
+    recommendedScrollDelta,
+  };
+}
+
+export function resolveTargetDetails(
+  selector: Parameters<typeof resolveElement>[0],
+): ResolveTargetData | null {
+  const resolved =
+    typeof selector.x === 'number' && typeof selector.y === 'number'
+      ? resolveElement(selector)
+      : resolveElement(selector);
+  if (!resolved) {
+    return null;
+  }
+
+  const frames = buildFrameIndex(resolved.root);
+  const snapshot = serializeTree(resolved.root.rootId);
+  const refIndex = buildViewIdToRefIndex(snapshot.refs);
+  const explicitRef =
+    typeof selector.ref === 'string' ? (selector.ref as ElementRef) : undefined;
+  const interactionContext = buildInteractionContext(resolved.root);
+
+  return buildResolveTargetDataForElement(
+    resolved.root,
+    resolved.element,
+    frames,
+    refIndex,
+    explicitRef,
+    interactionContext,
+  );
+}
+
+export function findMatchingElements(query: FindQuery): FindResultData {
+  const root = resolveRoot(query.rootId);
+  if (!root) {
+    return {
+      matches: [],
+      total: 0,
+    };
+  }
+
+  const scopedNode =
+    typeof query.viewId === 'number'
+      ? findNodeByViewId(root, query.viewId) ?? root
+      : root;
+  if (scopedNode.kind !== NodeKind.Element && scopedNode.kind !== NodeKind.Root) {
+    return {
+      matches: [],
+      total: 0,
+    };
+  }
+
+  const frames = buildFrameIndex(root);
+  const snapshot = serializeTree(root.rootId);
+  const refIndex = buildViewIdToRefIndex(snapshot.refs);
+  const interactionContext = buildInteractionContext(root);
+  const elements: ElementNode[] = [];
+  flattenElements(scopedNode, elements);
+
+  const matches = elements
+    .map((element) => {
+      const frame = frames.get(element.id) ?? { x: 0, y: 0, width: 0, height: 0 };
+      const label = getElementLabel(element);
+      const text = (getEffectiveTextValue(element) ?? getNodeText(element)) || undefined;
+      const testId = getTestId(element);
+      const role = getRole(element);
+      const resolved = buildResolveTargetDataForElement(
+        root,
+        element,
+        frames,
+        refIndex,
+        undefined,
+        interactionContext,
+      );
+
+      return {
+        ref: refIndex.get(element.id),
+        viewId: element.id,
+        type: element.originalTag,
+        label,
+        text,
+        testId,
+        role,
+        frame,
+        visible: resolved.visibility !== 'none',
+        interactable: resolved.interactable,
+      };
+    })
+    .filter((match) => {
+      if (query.role && normalizeLookup(match.role ?? '') !== normalizeLookup(query.role)) {
+        return false;
+      }
+      if (query.type && normalizeLookup(match.type) !== normalizeLookup(query.type)) {
+        return false;
+      }
+      if (query.testId && match.testId !== query.testId) {
+        return false;
+      }
+      if (!patternMatches(match.label, query.label)) {
+        return false;
+      }
+      if (!patternMatches(match.text, query.text)) {
+        return false;
+      }
+      if (typeof query.visible === 'boolean' && match.visible !== query.visible) {
+        return false;
+      }
+      if (typeof query.interactable === 'boolean' && match.interactable !== query.interactable) {
+        return false;
+      }
+      return true;
+    })
+    .sort((left, right) => left.viewId - right.viewId);
+
+  const limit = Math.max(0, query.limit ?? 20);
+  return {
+    matches: matches.slice(0, limit),
+    total: matches.length,
+  };
+}
+
+export function describeResolvedElement(
+  resolved: ResolvedElement | null,
+  ref?: ElementRef,
+): ResolvedTarget | undefined {
+  if (!resolved) {
+    return undefined;
+  }
+  return getResolvedTarget(resolved.element, ref);
+}
+
+export function elementIsInteractable(element: ElementNode): boolean {
+  return isElementInteractable(element);
+}
+
+export function dispatchElementEvent(
+  element: ElementNode,
+  eventType: EventType,
+  payload: unknown,
+): boolean {
+  const binding = element.events.get(eventType);
+  if (!binding) {
+    return false;
+  }
+
+  const dispatch = (
+    globalThis as {
+      __exactDispatchEvent?: (handlerId: number, payload: unknown) => void;
+    }
+  ).__exactDispatchEvent;
+
+  if (typeof dispatch === 'function') {
+    dispatch(binding.handlerId, payload);
+  } else {
+    binding.handler(payload);
+  }
+  return true;
+}
+
+export function getElementCenter(frame: Frame): Point {
+  return {
+    x: frame.x + frame.width / 2,
+    y: frame.y + frame.height / 2,
+  };
+}
+
+export function getVisibleInteractiveElements(rootId?: number): Array<{
+  ref: ElementRef;
+  description: string;
+}> {
+  const snapshot = serializeTree(rootId);
+  const entries: Array<{ ref: ElementRef; description: string }> = [];
+
+  for (const ref of Object.keys(snapshot.refs) as ElementRef[]) {
+    const info = snapshot.refs[ref];
+    const description = info.label
+      ? `${info.type} "${info.label}"`
+      : info.testId
+        ? `${info.type} (${info.testId})`
+        : info.type;
+    entries.push({ ref, description });
+  }
+
+  return entries;
+}
+
+export interface ClipChainEntry {
+  viewId: number;
+  type: string;
+  frame: Frame;
+  overflow: string | undefined;
+}
+
+function hasScrollableAncestor(node: ElementNode): boolean {
+  let current: HostNode | null = node.parent as HostNode | null;
+  while (current) {
+    if (current.kind === NodeKind.Element && current.tagType === 'scroll') {
+      return true;
+    }
+    current = current.parent as HostNode | null;
+  }
+  return false;
+}
+
+function hasKeyboardAvoidanceAncestor(node: ElementNode): boolean {
+  let current: HostNode | null = node;
+  while (current) {
+    if (
+      current.kind === NodeKind.Element &&
+      current.safeAreaState?.config.regions.includes('keyboard')
+    ) {
+      return true;
+    }
+    current = current.parent as HostNode | null;
+  }
+  return false;
+}
+
+function nearlyMatches(value: number, expected: number, tolerance = 2): boolean {
+  return Math.abs(value - expected) <= tolerance;
+}
+
+export function computeDiagnostics(rootId?: number, viewId?: number): LayoutDiagnostic[] {
+  const root = resolveRoot(rootId);
+  if (!root) {
+    return [];
+  }
+
+  const frames = buildFrameIndex(root);
+  const interactionContext = buildInteractionContext(root);
+  const windowMetrics = getRootWindowMetrics(root.rootId);
+  const diagnostics: LayoutDiagnostic[] = [];
+  const source =
+    typeof viewId === 'number'
+      ? findNodeByViewId(root, viewId) ?? root
+      : root;
+
+  const walk = (node: HostNode): void => {
+    if (node.kind !== NodeKind.Element && node.kind !== NodeKind.Root) {
+      return;
+    }
+
+    if (node.kind === NodeKind.Element) {
+      const frame = frames.get(node.id);
+      if (frame) {
+        const floating = findFloatingPositionByViewId(node.id);
+        const invisiblePresentReason =
+          node.props.inert === true
+            ? 'inert-explicit'
+            : isElementInteractable(node) && blockingModalForElement(node, interactionContext)
+              ? 'inert-modal'
+            : node.props.__exactPresencePhase === 'exiting'
+              ? 'presence-exiting'
+              : floating?.scrolling === true
+                ? 'floating-scrolling'
+              : floating?.state === 'premeasure'
+                ? 'floating-premeasure'
+                : floating?.state === 'hidden-anchor-escaped' ||
+                    floating?.state === 'hidden-reference-hidden' ||
+                    floating?.state === 'hidden-anchor-removed'
+                  ? 'floating-hidden'
+                  : null;
+
+        if (invisiblePresentReason) {
+          diagnostics.push({
+            severity: 'warning',
+            kind: 'invisible-present',
+            message: `Element is present in the tree but not interactable because ${invisiblePresentReason}`,
+            viewId: node.id,
+            type: node.originalTag,
+            label: getElementLabel(node),
+            frame,
+            details: {
+              reason: invisiblePresentReason,
+              interactable: false,
+              floatingState: floating?.state,
+            },
+          });
+        }
+
+        // Walk the ancestor clip chain to detect clipping
+        let ancestor: HostNode | null = node.parent as HostNode | null;
+        while (ancestor) {
+          if (ancestor.kind === NodeKind.Element || ancestor.kind === NodeKind.Root) {
+            const ancestorFrame = frames.get(ancestor.id);
+            const clipsDescendants = ancestor.kind === NodeKind.Root ||
+              (ancestor.kind === NodeKind.Element && (
+                ancestor.tagType === 'scroll' ||
+                ancestor.style.overflow === 'hidden' ||
+                ancestor.style.overflow === 'scroll'
+              ));
+
+            if (clipsDescendants && ancestorFrame) {
+              // Check if this element extends beyond its clipping ancestor
+              const overflowRight = (frame.x + frame.width) - (ancestorFrame.x + ancestorFrame.width);
+              const overflowBottom = (frame.y + frame.height) - (ancestorFrame.y + ancestorFrame.height);
+              const overflowLeft = ancestorFrame.x - frame.x;
+              const overflowTop = ancestorFrame.y - frame.y;
+
+              if (overflowRight > 1 || overflowBottom > 1 || overflowLeft > 1 || overflowTop > 1) {
+                // Compute the visible rect after clipping
+                const visibleX = Math.max(frame.x, ancestorFrame.x);
+                const visibleY = Math.max(frame.y, ancestorFrame.y);
+                const visibleRight = Math.min(frame.x + frame.width, ancestorFrame.x + ancestorFrame.width);
+                const visibleBottom = Math.min(frame.y + frame.height, ancestorFrame.y + ancestorFrame.height);
+                const visibleWidth = Math.max(0, visibleRight - visibleX);
+                const visibleHeight = Math.max(0, visibleBottom - visibleY);
+                const totalArea = frame.width * frame.height;
+                const visibleArea = visibleWidth * visibleHeight;
+                const clippedPercent = totalArea > 0
+                  ? Math.round((1 - visibleArea / totalArea) * 100)
+                  : 0;
+
+                if (clippedPercent > 5) {
+                  const scrollAncestor =
+                    ancestor.kind === NodeKind.Element && ancestor.tagType === 'scroll'
+                      ? ancestor
+                      : null;
+                  if (scrollAncestor) {
+                    if (isElementInteractable(node)) {
+                      diagnostics.push({
+                        severity: 'info',
+                        kind: 'scrollContentClipped',
+                        message: `${clippedPercent}% of this element is outside the ScrollView viewport; scroll to reveal it`,
+                        viewId: node.id,
+                        type: node.originalTag,
+                        label: getElementLabel(node),
+                        frame,
+                        details: {
+                          clipAncestor: {
+                            viewId: scrollAncestor.id,
+                            type: scrollAncestor.originalTag,
+                            frame: ancestorFrame,
+                            overflow: scrollAncestor.style.overflow,
+                          },
+                          visibleRect: { x: visibleX, y: visibleY, width: visibleWidth, height: visibleHeight },
+                          clippedPercent,
+                        },
+                      });
+                    }
+                    break;
+                  }
+
+                  diagnostics.push({
+                    severity: 'warning',
+                    kind: 'clipped',
+                    message: `${clippedPercent}% of this element is clipped by ancestor ${ancestor.kind === NodeKind.Root ? 'root' : (ancestor as ElementNode).originalTag} (viewId ${ancestor.id})`,
+                    viewId: node.id,
+                    type: node.originalTag,
+                    label: getElementLabel(node),
+                    frame,
+                    details: {
+                      clipAncestor: {
+                        viewId: ancestor.id,
+                        type: ancestor.kind === NodeKind.Root ? 'Root' : (ancestor as ElementNode).originalTag,
+                        frame: ancestorFrame,
+                        overflow: ancestor.kind === NodeKind.Element
+                          ? (ancestor as ElementNode).style.overflow
+                          : undefined,
+                      },
+                      visibleRect: { x: visibleX, y: visibleY, width: visibleWidth, height: visibleHeight },
+                      clippedPercent,
+                    },
+                  });
+                }
+              }
+              break; // Only check the nearest clipping ancestor
+            }
+          }
+          ancestor = ancestor.parent as HostNode | null;
+        }
+
+        // Detect zero-size elements that have children
+        if ((frame.width <= 0 || frame.height <= 0) && node.children.length > 0) {
+          diagnostics.push({
+            severity: 'warning',
+            kind: 'zeroSize',
+            message: `Element has zero ${frame.width <= 0 ? 'width' : 'height'} but contains ${node.children.length} children`,
+            viewId: node.id,
+            type: node.originalTag,
+            label: getElementLabel(node),
+            frame,
+          });
+        }
+
+        const containerInsets = windowMetrics.regions.container;
+        const rootFrame = frames.get(root.id);
+        if (rootFrame && isElementInteractable(node)) {
+          const violatedEdges: string[] = [];
+          if (containerInsets.top > 0 && frame.y < rootFrame.y + containerInsets.top - 1) {
+            violatedEdges.push('top');
+          }
+          if (
+            containerInsets.right > 0 &&
+            frame.x + frame.width > rootFrame.x + rootFrame.width - containerInsets.right + 1
+          ) {
+            violatedEdges.push('right');
+          }
+          if (
+            containerInsets.bottom > 0 &&
+            frame.y + frame.height > rootFrame.y + rootFrame.height - containerInsets.bottom + 1
+          ) {
+            violatedEdges.push('bottom');
+          }
+          if (containerInsets.left > 0 && frame.x < rootFrame.x + containerInsets.left - 1) {
+            violatedEdges.push('left');
+          }
+
+          if (violatedEdges.length > 0) {
+            diagnostics.push({
+              severity: 'warning',
+              kind: 'safeAreaOcclusion',
+              message: `Interactive content extends into the ${violatedEdges.join(', ')} safe area.`,
+              viewId: node.id,
+              type: node.originalTag,
+              label: getElementLabel(node),
+              frame,
+              details: {
+                edges: violatedEdges,
+                containerInsets,
+              },
+            });
+          }
+        }
+
+        const keyboard = windowMetrics.keyboard;
+        if (
+          keyboard.visible &&
+          keyboard.occlusion.width > 0 &&
+          keyboard.occlusion.height > 0 &&
+          framesIntersect(frame, keyboard.occlusion) &&
+          !hasKeyboardAvoidanceAncestor(node) &&
+          (node.tagType === 'input' || isElementInteractable(node))
+        ) {
+          diagnostics.push({
+            severity: 'warning',
+            kind: 'keyboardOcclusion',
+            message: 'Content is intersecting the keyboard without keyboard avoidance.',
+            viewId: node.id,
+            type: node.originalTag,
+            label: getElementLabel(node),
+            frame,
+            details: {
+              keyboard: {
+                ...keyboard,
+                occlusion: { ...keyboard.occlusion },
+              },
+            },
+          });
+        }
+
+        if (
+          node.tagType === 'input' &&
+          !hasScrollableAncestor(node) &&
+          !hasKeyboardAvoidanceAncestor(node)
+        ) {
+          diagnostics.push({
+            severity: 'warning',
+            kind: 'missingKeyboardAvoidance',
+            message: 'Text input lives in a non-scrolling container with no keyboard avoidance.',
+            viewId: node.id,
+            type: node.originalTag,
+            label: getElementLabel(node),
+            frame,
+          });
+        }
+
+        if (!node.safeAreaState) {
+          const paddingTop = getStyleDimension(node.style, 'paddingTop', frame.height, 0);
+          const paddingBottom = getStyleDimension(node.style, 'paddingBottom', frame.height, 0);
+          if (
+            (containerInsets.top > 0 && nearlyMatches(paddingTop, containerInsets.top)) ||
+            (containerInsets.bottom > 0 && nearlyMatches(paddingBottom, containerInsets.bottom))
+          ) {
+            diagnostics.push({
+              severity: 'info',
+              kind: 'duplicateSafeAreaPadding',
+              message: 'Hardcoded padding closely matches the current container safe area.',
+              viewId: node.id,
+              type: node.originalTag,
+              label: getElementLabel(node),
+              frame,
+              details: {
+                paddingTop,
+                paddingBottom,
+                containerInsets,
+              },
+            });
+          }
+        }
+      }
+    }
+
+    // Walk children
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+
+  walk(source);
+  return diagnostics;
+}
+
+export function _resetInspectorState(): void {
+  roots.clear();
+  listeners.clear();
+  snapshots.clear();
+  snapshotOrder.length = 0;
+  _resetAgentLogState();
+  resetAgentStateTracking();
+  clearInteractionOverrides();
+  sharedState.snapshotCounter = 0;
+  sharedState.stateVersion = 0;
+  sharedState.frameCount = 0;
+  sharedState.lastCommitAt = 0;
+}
+
+(globalThis as typeof globalThis & {
+  __exactRendererInspectorTargeting?: Pick<
+    typeof import('./inspector.js'),
+    'resolveElement' | 'resolveTargetDetails' | 'setScrollOffset'
+  >;
+}).__exactRendererInspectorTargeting = {
+  resolveElement,
+  resolveTargetDetails,
+  setScrollOffset,
+};