@quiesco/agent 0.0.0-stage → 0.1.1

package/src/fiber-adapter/traverse.ts

@@ -0,0 +1,260 @@
+/**
+ * Build the renderer-independent HostNode tree from fiber roots.
+ * Rules (docs/spikes/07-web-fiber-query.md "查询规则"):
+ * - Only HostComponent fibers become nodes; composite fibers are transparent.
+ * - Text = HostText fibers + `memoizedProps.children` (string/number) of hosts WITHOUT child fibers
+ *   (react-dom's shouldSetTextContent case; reading it only when there are no child fibers avoids
+ *   double counting on Fabric).
+ * - HostSingleton (html/head/body) is transparent; HostHoistable (<title>, <link>, ...) is skipped.
+ */
+import type { Rect } from '@quiesco/protocol';
+
+import type { Fiber } from './fiber';
+import { WorkTag, isObject, walkSiblings } from './fiber';
+import type { HostPlatform } from './host';
+import type { CompositeNode, HandlerRef, HostNode, InstanceRef, PropsRef } from './types';
+
+class Node implements HostNode {
+  readonly type: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly testID: string | undefined;
+  readonly label: string | undefined;
+  readonly role: string | undefined;
+  readonly hiddenByStyle: boolean;
+  readonly clipsContent: boolean;
+  readonly renderedWithParent: boolean;
+  readonly children: Node[] = [];
+  text = '';
+  ownText = '';
+
+  constructor(
+    private readonly fiber: Fiber,
+    private readonly platform: HostPlatform,
+    readonly parent: Node | null,
+    viaComponent: boolean,
+  ) {
+    const props = isObject(fiber.memoizedProps) ? fiber.memoizedProps : {};
+    this.type = typeof fiber.type === 'string' ? fiber.type : String(fiber.type);
+    this.props = props;
+    this.testID = platform.testID(props);
+    this.label = platform.label(props);
+    this.role = platform.role(props);
+    this.hiddenByStyle = platform.hiddenByStyle(fiber, props);
+    this.clipsContent = platform.clipsContent(this.type, fiber, props);
+    this.renderedWithParent = parent !== null && !viaComponent;
+  }
+
+  ownerNames(): readonly string[] {
+    const out: string[] = [];
+    for (let f = this.fiber.return; f !== null && !isHostBoundary(f); f = f.return) {
+      const name = componentName(f.type);
+      if (name !== null && !out.includes(name)) out.push(name);
+    }
+    return out;
+  }
+
+  isFocused(): boolean {
+    return this.platform.isFocused(this.fiber);
+  }
+
+  focus(): boolean {
+    return this.platform.focus(this.fiber);
+  }
+
+  inputValue(): string | undefined {
+    return this.platform.inputValue(this.type, this.fiber, this.props as Record<string, unknown>);
+  }
+
+  measure(): Rect | null {
+    return this.platform.measure(this.fiber);
+  }
+
+  nativeTag(): number | null {
+    return this.platform.nativeTag(this.fiber);
+  }
+
+  isSameElement(other: HostNode): boolean {
+    if (other === this) return true;
+    if (!(other instanceof Node)) return false;
+    const a = this.fiber.stateNode;
+    return (a !== null && a !== undefined && a === other.fiber.stateNode) || this.fiber === other.fiber;
+  }
+
+  ownerProps(): Readonly<Record<string, unknown>> {
+    const out: Record<string, unknown> = {};
+    for (let f = this.fiber.return; f !== null && !isHostBoundary(f); f = f.return) {
+      if (f.tag === WorkTag.HostText || !isObject(f.memoizedProps)) continue;
+      for (const [k, v] of Object.entries(f.memoizedProps)) if (!(k in out)) out[k] = v;
+    }
+    return out;
+  }
+
+  findHandler(name: string): HandlerRef | null {
+    for (let f: Fiber | null = this.fiber; f !== null && f.tag !== WorkTag.HostRoot; f = f.return) {
+      const p = f.memoizedProps;
+      if (isObject(p) && typeof p[name] === 'function') return { fn: p[name] as HandlerRef['fn'], props: p };
+    }
+    return null;
+  }
+
+  findProps(test: (props: Readonly<Record<string, unknown>>) => boolean, maxDepth = DEFAULT_PROPS_DEPTH): PropsRef | null {
+    return findPropsFrom(this.fiber, test, maxDepth);
+  }
+
+  findInstance(method: string): InstanceRef | null {
+    for (let f = this.fiber.return; f !== null && f.tag !== WorkTag.HostRoot; f = f.return) {
+      const inst = f.stateNode;
+      if (f.tag !== WorkTag.ClassComponent || !isObject(inst) || typeof inst[method] !== 'function') continue;
+      const owner = f;
+      const platform = this.platform;
+      return {
+        call: (...args) => (inst[method] as (...a: unknown[]) => unknown).apply(inst, args),
+        hostNodes: () => buildHostTree(owner, platform),
+        raw: () => inst,
+      };
+    }
+    return null;
+  }
+}
+
+/** How far up `findProps` looks by default: the components wrapping a control, not the whole screen. */
+const DEFAULT_PROPS_DEPTH = 12;
+
+function findPropsFrom(start: Fiber, test: (props: Readonly<Record<string, unknown>>) => boolean, maxDepth: number): PropsRef | null {
+  let depth = 0;
+  for (let f: Fiber | null = start; f !== null && f.tag !== WorkTag.HostRoot && depth <= maxDepth; f = f.return, depth++) {
+    if (f.tag === WorkTag.HostText || !isObject(f.memoizedProps)) continue;
+    if (test(f.memoizedProps)) return { props: f.memoizedProps, name: COMPONENT_TAGS.has(f.tag) ? componentName(f.type) : null };
+  }
+  return null;
+}
+
+class Composite implements CompositeNode {
+  readonly name: string | null;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly testID: string | undefined;
+  readonly rendersHost: boolean;
+
+  constructor(private readonly fiber: Fiber) {
+    this.name = componentName(fiber.type);
+    this.props = isObject(fiber.memoizedProps) ? fiber.memoizedProps : {};
+    this.testID = typeof this.props['testID'] === 'string' ? this.props['testID'] : undefined;
+    this.rendersHost = hasHost(fiber.child);
+  }
+
+  findProps(test: (props: Readonly<Record<string, unknown>>) => boolean, maxDepth = DEFAULT_PROPS_DEPTH): PropsRef | null {
+    return findPropsFrom(this.fiber, test, maxDepth);
+  }
+}
+
+function hasHost(first: Fiber | null): boolean {
+  for (const f of walkSiblings(first)) if (f.tag === WorkTag.HostComponent || f.tag === WorkTag.HostText) return true;
+  return false;
+}
+
+/**
+ * Component fibers under `fiber` (pre-order) that render no host element and satisfy `test`. A match's
+ * descendants are not searched: a wrapper passing its testID down to an inner component is one target.
+ */
+export function findHostlessComposites(fiber: Fiber, test: (c: CompositeNode) => boolean): CompositeNode[] {
+  const out: CompositeNode[] = [];
+  const stack: Fiber[] = [];
+  let f: Fiber | null = fiber.child;
+  while (f !== null || stack.length > 0) {
+    if (f === null) f = stack.pop() ?? null;
+    if (f === null) break;
+    if (f.sibling !== null) stack.push(f.sibling);
+    if (COMPONENT_TAGS.has(f.tag) && !hasHost(f.child)) {
+      const c = new Composite(f);
+      if (test(c)) {
+        out.push(c);
+        f = null;
+        continue;
+      }
+    }
+    f = f.child;
+  }
+  return out;
+}
+
+/** Display name of a component type: function / class, forwardRef, memo. Null for anonymous ones. */
+function componentName(type: unknown): string | null {
+  const named = (t: unknown): string | null => {
+    if (typeof t !== 'function' && !isObject(t)) return null;
+    const o = t as { displayName?: unknown; name?: unknown };
+    if (typeof o.displayName === 'string' && o.displayName !== '') return o.displayName;
+    return typeof t === 'function' && typeof o.name === 'string' && o.name !== '' ? o.name : null;
+  };
+  const direct = named(type);
+  if (direct !== null || !isObject(type)) return direct;
+  return named(type['render']) ?? named(type['type']);
+}
+
+const COMPONENT_TAGS: ReadonlySet<number> = new Set([
+  WorkTag.FunctionComponent,
+  WorkTag.ClassComponent,
+  WorkTag.ForwardRef,
+  WorkTag.MemoComponent,
+  WorkTag.SimpleMemoComponent,
+]);
+
+function isHostBoundary(f: Fiber): boolean {
+  return f.tag === WorkTag.HostComponent || f.tag === WorkTag.HostRoot || f.tag === WorkTag.HostPortal;
+}
+
+function stringChildren(fiber: Fiber): string {
+  if (fiber.child !== null || !isObject(fiber.memoizedProps)) return '';
+  const c = fiber.memoizedProps['children'];
+  return typeof c === 'string' || typeof c === 'number' ? String(c) : '';
+}
+
+/**
+ * Collect host nodes under `first` and its siblings into `out` (children of `parent`).
+ * `viaComponent`: a component fiber lies between `parent` and `first`.
+ * Returns [all text, text not inside a child host], both in render order.
+ */
+function collect(first: Fiber | null, parent: Node | null, platform: HostPlatform, out: Node[], viaComponent = false): [string, string] {
+  let text = '';
+  let own = '';
+  for (let f = first; f !== null; f = f.sibling) {
+    switch (f.tag) {
+      case WorkTag.HostComponent: {
+        const node = new Node(f, platform, parent, viaComponent);
+        const [childText, childOwn] = collect(f.child, node, platform, node.children);
+        const mine = stringChildren(f);
+        node.text = mine + childText;
+        node.ownText = mine + childOwn;
+        out.push(node);
+        text += node.text;
+        break;
+      }
+      case WorkTag.HostText:
+        if (typeof f.memoizedProps === 'string' || typeof f.memoizedProps === 'number') {
+          text += String(f.memoizedProps);
+          own += String(f.memoizedProps);
+        }
+        break;
+      case WorkTag.HostHoistable:
+        break;
+      default: {
+        const [t, o] = collect(f.child, parent, platform, out, viaComponent || COMPONENT_TAGS.has(f.tag));
+        text += t;
+        own += o;
+      }
+    }
+  }
+  return [text, own];
+}
+
+/** Host nodes directly below `fiber` (the fiber itself is not included). */
+export function buildHostTree(fiber: Fiber, platform: HostPlatform): HostNode[] {
+  const out: Node[] = [];
+  collect(fiber.child, null, platform, out);
+  return out;
+}
+
+/** First fiber (pre-order) whose component type is `type`. */
+export function findFiberByType(start: Fiber, type: unknown): Fiber | null {
+  for (const f of walkSiblings(start)) if (f.type === type) return f;
+  return null;
+}

package/src/fiber-adapter/types.ts

@@ -0,0 +1,142 @@
+import type { Rect } from '@quiesco/protocol';
+
+/**
+ * Renderer-independent element model. This is the ONLY shape the rest of the agent sees;
+ * Fiber objects never leave `fiber-adapter/` (requirements.md §3-3).
+ */
+export interface HostNode {
+  /** Host component type: `RCTView`, `RCTText`, `div`, ... */
+  readonly type: string;
+  /** Raw React props of the host fiber (read-only view; may contain functions / elements). */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** `testID` (native) or `data-testid` (react-native-web). */
+  readonly testID: string | undefined;
+  /** `accessibilityLabel` / `aria-label`. */
+  readonly label: string | undefined;
+  /** `accessibilityRole` / `role`. */
+  readonly role: string | undefined;
+  /** Concatenated text of this node's subtree, in render order. */
+  readonly text: string;
+  /** Text directly inside this node, excluding text of child host nodes (e.g. an RCTText's own string). */
+  readonly ownText: string;
+  /** `display: none` or `opacity: 0` on this node itself (ancestors are not considered). */
+  readonly hiddenByStyle: boolean;
+  /**
+   * Whether this host clips its descendants to its own bounds: scroll views, and `overflow` other
+   * than `visible` (style on native, computed style on the web).
+   */
+  readonly clipsContent: boolean;
+  /**
+   * True when no component (function / class / forwardRef / memo) sits between this host and its
+   * parent host: it was created in the same render as the parent, e.g. the `<input>` inside
+   * react-native-web's Switch root `<div>`. Structural, so it survives minification.
+   */
+  readonly renderedWithParent: boolean;
+  readonly parent: HostNode | null;
+  readonly children: readonly HostNode[];
+  /** Window coordinates in logical units (dp / pt / CSS px), or null if the node cannot be measured. */
+  measure(): Rect | null;
+  /** React view tag of the underlying native view (Fabric), or null (web, unmounted). */
+  nativeTag(): number | null;
+  /**
+   * Whether `other` is the same rendered element. HostNode objects are rebuilt on every tree walk, so
+   * identity is the underlying host instance (Fabric instance / DOM element), not the object.
+   */
+  isSameElement(other: HostNode): boolean;
+  /**
+   * Merged props of the composite components that render this host directly (between it and the
+   * nearest ancestor host), nearest first. E.g. a Pressable's `disabled`, a TextInput's `value`.
+   */
+  ownerProps(): Readonly<Record<string, unknown>>;
+  /**
+   * Names of the composite components that render this host directly (between it and the nearest
+   * ancestor host), nearest first. Only named components appear; release builds minify function
+   * names, so only explicit `displayName`s (Pressable, TextInput, ...) are reliable there.
+   */
+  ownerNames(): readonly string[];
+  /**
+   * Current text of a text input (native: the `text` prop TextInput passes to its host, i.e. the value
+   * or the last typed text; web: the DOM element's live `value`). Undefined for other elements.
+   */
+  inputValue(): string | undefined;
+  /**
+   * Give the element the input focus (text inputs). Web: DOM `focus()` and the caret moved to the end;
+   * native: the host instance's `focus()`. False when the element cannot be focused this way.
+   */
+  focus(): boolean;
+  /** Whether the element has the input focus (focused text input; `document.activeElement` on the web). */
+  isFocused(): boolean;
+  /** Nearest component (this host or an ancestor, up to the root) with a function prop `name`. */
+  findHandler(name: string): HandlerRef | null;
+  /**
+   * Nearest fiber (this host, then its ancestors, at most `maxDepth` fibers up) whose props satisfy
+   * `test`, with the name of its component (null for hosts and anonymous components). Used to find the
+   * component behind a control (Slider, Picker, ...) by the shape of its props.
+   */
+  findProps(test: (props: Readonly<Record<string, unknown>>) => boolean, maxDepth?: number): PropsRef | null;
+  /** Nearest ancestor class component instance with a method `name` (e.g. ScrollView's `scrollTo`). */
+  findInstance(method: string): InstanceRef | null;
+}
+
+export interface HandlerRef {
+  fn: (...args: unknown[]) => unknown;
+  /** All props of the component that owns the handler (for `disabled`, sibling handlers, ...). */
+  props: Readonly<Record<string, unknown>>;
+}
+
+export interface PropsRef {
+  props: Readonly<Record<string, unknown>>;
+  name: string | null;
+}
+
+/**
+ * A component that renders no host element of its own (e.g. Android's DateTimePicker, which opens a
+ * system dialog imperatively and renders null). Only value actions can target it (Phase 6.3).
+ */
+export interface CompositeNode {
+  readonly name: string | null;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly testID: string | undefined;
+  /** Whether it renders any host element. */
+  readonly rendersHost: boolean;
+  findProps(test: (props: Readonly<Record<string, unknown>>) => boolean, maxDepth?: number): PropsRef | null;
+}
+
+export interface InstanceRef {
+  /** Call the method on the instance. */
+  call(...args: unknown[]): unknown;
+  /** Top-level host nodes rendered by the component (e.g. the native scroll view). */
+  hostNodes(): HostNode[];
+  /** The component instance itself, for reading documented-but-internal state (e.g. list metrics). */
+  raw(): Record<string, unknown>;
+}
+
+export type RendererKind = 'native' | 'web';
+
+export interface RendererInfo {
+  id: number;
+  packageName: string;
+  version: string;
+  /** 0 = production, 1 = development (React DevTools convention). */
+  bundleType: number;
+  kind: RendererKind;
+  supported: boolean;
+}
+
+export interface AdapterDiagnostics {
+  /** `existing`: wrapped a hook installed by React DevTools; `installed`: we installed a minimal hook. */
+  hookSource: 'existing' | 'installed' | 'none';
+  schedulerPatched: boolean;
+  renderers: RendererInfo[];
+  rootCount: number;
+  /** Problems the user must fix (e.g. the agent was imported after React Native's renderer). */
+  problems: string[];
+  /** Non-fatal notices (e.g. untested renderer version). */
+  warnings: string[];
+}
+
+/** Window size in the same units as `HostNode.measure()`. */
+export interface Viewport {
+  width: number;
+  height: number;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// Keep this import first: it installs the DevTools hook, the scheduler patch and the trackers.
+import './install';
+
+export { QuiescoRoot } from './root/QuiescoRoot';
+export type { QuiescoRootProps } from './root/QuiescoRoot';
+export { quiesco } from './api';
+export type { Backdoor, QuiescoApi, StorageAdapter } from './api-types';

package/src/install.ts

@@ -0,0 +1,6 @@
+// Side-effect module: must be evaluated before React Native's renderer and before the app's code
+// (docs/spikes/01 §1, 02 §2). `@quiesco/agent` imports it first; keep it that way.
+import './early';
+import { getRuntime } from './singleton';
+
+getRuntime();

package/src/json-check.ts

@@ -0,0 +1,43 @@
+/**
+ * Strict JSON check for backdoor results (requirements.md §6.6): reports the first value that would not
+ * survive JSON.stringify / JSON.parse unchanged, as a path like `$.items[2].createdAt`.
+ */
+export function findNonJson(value: unknown, path = '$', seen: Set<object> = new Set()): { path: string; reason: string } | null {
+  switch (typeof value) {
+    case 'string':
+    case 'boolean':
+      return null;
+    case 'number':
+      return Number.isFinite(value) ? null : { path, reason: String(value) };
+    case 'undefined':
+      return { path, reason: 'undefined' };
+    case 'function':
+    case 'symbol':
+    case 'bigint':
+      return { path, reason: typeof value };
+  }
+  if (value === null) return null;
+  const obj = value as object;
+  if (seen.has(obj)) return { path, reason: 'circular reference' };
+  if (Array.isArray(obj)) {
+    seen.add(obj);
+    for (let i = 0; i < obj.length; i++) {
+      const bad = findNonJson(obj[i], `${path}[${i}]`, seen);
+      if (bad !== null) return bad;
+    }
+    seen.delete(obj);
+    return null;
+  }
+  const proto = Object.getPrototypeOf(obj) as unknown;
+  if (proto !== Object.prototype && proto !== null) {
+    const name = (obj as { constructor?: { name?: string } }).constructor?.name ?? 'object';
+    return { path, reason: `${name} instance (only plain objects and arrays)` };
+  }
+  seen.add(obj);
+  for (const [k, v] of Object.entries(obj)) {
+    const bad = findNonJson(v, /^[A-Za-z_$][\w$]*$/.test(k) ? `${path}.${k}` : `${path}[${JSON.stringify(k)}]`, seen);
+    if (bad !== null) return bad;
+  }
+  seen.delete(obj);
+  return null;
+}

package/src/platform.ts

@@ -0,0 +1,155 @@
+/**
+ * Public React Native APIs the agent needs at runtime, loaded lazily (never at agent import time:
+ * that would load React Native before the DevTools hook is installed). Injected for unit tests.
+ * On web, `react-native` is aliased to react-native-web, which provides the same APIs.
+ */
+import type { AppStateName, Platform, Rect } from '@quiesco/protocol';
+
+import type { NativeBridge } from './actions/native';
+import type { InteractionManagerLike } from './sync';
+
+declare const require: (id: string) => unknown;
+
+export interface SocketLike {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: (() => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+
+export interface AppDeps {
+  platform(): Platform;
+  dismissKeyboard(): void;
+  /** The software keyboard's frame in screen coordinates while it is shown, else null. */
+  keyboardFrame(): Rect | null;
+  /** @quiesco/native when it is installed and its native code is linked, else null. */
+  nativeModule(): NativeModuleLike | null;
+  createSocket(url: string): SocketLike;
+  /** Legacy InteractionManager (RN < 0.88), or null. */
+  interactionManager(): InteractionManagerLike | null;
+  /** React Native's AppState (react-native-web: from the page visibility). */
+  appState(): AppStateName;
+  /**
+   * Calls `listener` on every AppState change; returns the unsubscribe. Events still arrive while Android
+   * pauses the JS timers (another activity on top, e.g. a permission dialog).
+   */
+  onAppStateChange?(listener: () => void): () => void;
+  /** The window in logical units and physical pixels per unit. */
+  windowInfo(): { width: number; height: number; pixelRatio: number };
+  /** What the app sees of the device settings (Phase 6.6 read-backs). */
+  settings(): { colorScheme: 'light' | 'dark' | null; fontScale: number; locale: string };
+}
+
+/** What the agent uses of @quiesco/native besides the action bridge. */
+export type NativeModuleLike = NativeBridge & {
+  /** `args`: base64 of the launch arguments' JSON (Phase 6.5); missing in older native builds. */
+  getLaunchParams(): { port: string | null; session: string | null; args?: string | null };
+  /** iOS: leave for the home screen. Missing on Android and in older native builds. */
+  suspend?(): Promise<boolean>;
+  /** iOS: rotate the window scene; resolves with an error message, or '' when requested (Phase 6.6). */
+  setOrientation?(landscape: boolean): Promise<string>;
+  /** Android: post a notification as the app (Phase 6.7). */
+  postNotification?(title: string, body: string, data: Record<string, string>): Promise<{ enabled: boolean }>;
+  /** The clipboard's text ('' when it holds none), read inside the app (Phase 6.6). */
+  getClipboard?(): Promise<string>;
+  setClipboard?(text: string): Promise<void>;
+  /** The WebView inside a view (Phase 6.8): its rect in the window and load state. */
+  webviewInfo?(tag: number): Promise<{ found: boolean; x?: number; y?: number; width?: number; height?: number; insetTop?: number; insetLeft?: number; loading?: boolean }>;
+  /** Evaluate a string-valued expression in the WebView's main frame. */
+  webviewEval?(tag: number, script: string): Promise<string>;
+  /** Run `source` at document start of the WebView's later loads; false where the WebView cannot. */
+  webviewAddStartScript?(tag: number, source: string): Promise<boolean>;
+  /** Show / hide a scroll view's indicators (Phase 6.9 full-page screenshots); what they were: 1 shown, 0 hidden, -1 not found. */
+  setScrollIndicators?(tag: number, visible: boolean): Promise<number>;
+};
+
+interface RN {
+  Platform: { OS: string };
+  Keyboard: {
+    dismiss(): void;
+    // React Native ≥ 0.70; react-native-web has neither (no software keyboard to track).
+    isVisible?(): boolean;
+    metrics?(): { screenX: number; screenY: number; width: number; height: number } | null | undefined;
+  };
+  InteractionManager?: InteractionManagerLike;
+  AppState: { currentState: string | null | undefined; addEventListener(type: 'change', listener: () => void): { remove(): void } };
+  Dimensions: { get(dim: 'window'): { width: number; height: number } };
+  PixelRatio: { get(): number; getFontScale(): number };
+  Appearance: { getColorScheme(): string | null | undefined };
+}
+
+const rn = (): RN => require('react-native') as RN;
+
+type MatchMedia = (query: string) => { matches: boolean };
+
+/**
+ * The color scheme the app sees, read without disturbing it. Where `matchMedia` exists (the web), a
+ * fresh MediaQueryList is asked: reading `matches` on react-native-web's own list (Appearance) updates
+ * its remembered state, and Chromium then dispatches no change event to the app's listeners
+ * (useColorScheme never updates; found in Phase 6.6). Native: React Native's Appearance.
+ */
+export function readColorScheme(matchMedia: MatchMedia | undefined, appearance: () => string | null | undefined): 'light' | 'dark' | null {
+  if (typeof matchMedia === 'function') return matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  const s = appearance();
+  return s === 'light' || s === 'dark' ? s : null;
+}
+
+export const defaultAppDeps: AppDeps = {
+  platform() {
+    const os = rn().Platform.OS;
+    return os === 'ios' || os === 'android' ? os : 'web';
+  },
+  dismissKeyboard() {
+    rn().Keyboard.dismiss();
+  },
+  keyboardFrame() {
+    const k = rn().Keyboard;
+    if (k.isVisible?.() !== true) return null;
+    const m = k.metrics?.();
+    return m === null || m === undefined ? null : { x: m.screenX, y: m.screenY, width: m.width, height: m.height };
+  },
+  nativeModule() {
+    // Optional dependency: Metro bundles apps without @quiesco/native when the require sits directly
+    // in a try block (transformer.allowOptionalDependencies, on by default).
+    try {
+      const mod = require('@quiesco/native') as { QuiescoNative?: ReturnType<AppDeps['nativeModule']> };
+      return mod.QuiescoNative ?? null;
+    } catch {
+      return null;
+    }
+  },
+  createSocket(url) {
+    const WS = (globalThis as unknown as { WebSocket: new (url: string) => SocketLike }).WebSocket;
+    return new WS(url);
+  },
+  appState() {
+    const s = rn().AppState.currentState;
+    return s === 'active' || s === 'background' || s === 'inactive' ? s : 'unknown';
+  },
+  onAppStateChange(listener) {
+    const sub = rn().AppState.addEventListener('change', listener);
+    return () => sub.remove();
+  },
+  windowInfo() {
+    const { width, height } = rn().Dimensions.get('window');
+    return { width, height, pixelRatio: rn().PixelRatio.get() };
+  },
+  settings() {
+    const mm = (globalThis as { matchMedia?: MatchMedia }).matchMedia;
+    return {
+      colorScheme: readColorScheme(mm?.bind(globalThis), () => rn().Appearance.getColorScheme()),
+      fontScale: rn().PixelRatio.getFontScale(),
+      locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    };
+  },
+  interactionManager() {
+    try {
+      // RN 0.88 replaced it with a getter that throws in __DEV__ (removed from core).
+      return rn().InteractionManager ?? null;
+    } catch {
+      return null;
+    }
+  },
+};

package/src/query/index.ts

@@ -0,0 +1,5 @@
+export { describeMatcher, findAll, findAllIgnoringIndex, matchesSelf, resolveOne, toRegExp } from './matcher';
+export type { Summarizer } from './matcher';
+export { getTree, serializableProps, structureLines, summarize, toJsonValue, toTreeNode } from './tree';
+export { hiddenByAncestorStyle, intersectsViewport, isVisible, visiblePart, visibleRatio } from './visibility';
+export { checkedState, elementValue, isEnabled, isFocusedWidget, isWidgetPart, matchesType, semanticType, widgetParts } from './semantic';