@quiesco/agent 0.0.0-stage → 0.1.1

package/src/query/matcher.ts

@@ -0,0 +1,121 @@
+/**
+ * Matcher evaluation over the HostNode tree (requirements.md §6.1).
+ *
+ * - `id` / `label` / `role` compare the host's own props; `id` / `text` / `label` accept a regex.
+ * - `type` is a semantic type, a host type or the name of a component rendering the host (semantic.ts).
+ * - `has`: some descendant matches. `not`: the node itself does not match.
+ * - `text` compares the concatenated text of the node's subtree. Because a container's text includes
+ *   its children's text, only the DEEPEST matching nodes are returned: a node is dropped when one of
+ *   its descendants also satisfies the whole matcher (e.g. `{ text: 'Login' }` returns the RCTText,
+ *   not every View wrapping it).
+ * - `within` restricts the search to descendants of the single element it matches.
+ * - Results are in render (pre-order) order; `index` picks one of them.
+ */
+import type { ElementSummary, Matcher, TextMatch } from '@quiesco/protocol';
+
+import { QuiescoError } from '../errors';
+import type { HostNode } from '../fiber-adapter';
+import { matchesType, widgetLabel } from './semantic';
+
+export function toRegExp(m: TextMatch): RegExp | string {
+  return typeof m === 'string' ? m : new RegExp(m.regex.source, m.regex.flags);
+}
+
+function textMatches(value: string | undefined, pattern: TextMatch): boolean {
+  if (value === undefined) return false;
+  const p = toRegExp(pattern);
+  if (typeof p === 'string') return value === p;
+  p.lastIndex = 0;
+  return p.test(value);
+}
+
+/**
+ * Whether `node` itself satisfies the matcher: its own fields, `has` and `not` (`within` / `index`
+ * select among nodes and are not considered here).
+ */
+export function matchesSelf(node: HostNode, m: Matcher): boolean {
+  if (m.id !== undefined && !textMatches(node.testID, m.id)) return false;
+  if (m.role !== undefined && node.role !== m.role) return false;
+  if (m.label !== undefined && !textMatches(widgetLabel(node), m.label)) return false;
+  if (m.text !== undefined && !textMatches(node.text, m.text)) return false;
+  if (m.type !== undefined && !matchesType(node, m.type)) return false;
+  if (m.has !== undefined && !hasMatchingDescendant(node, m.has)) return false;
+  if (m.not !== undefined && matchesSelf(node, m.not)) return false;
+  return true;
+}
+
+function* preorder(nodes: readonly HostNode[]): Generator<HostNode> {
+  const stack = [...nodes].reverse();
+  while (stack.length > 0) {
+    const n = stack.pop() as HostNode;
+    yield n;
+    for (let i = n.children.length - 1; i >= 0; i--) stack.push(n.children[i] as HostNode);
+  }
+}
+
+function hasMatchingDescendant(node: HostNode, m: Matcher): boolean {
+  for (const d of preorder(node.children)) if (matchesSelf(d, m)) return true;
+  return false;
+}
+
+/** All nodes matching `m` (ignoring `index`) under `roots`. Throws if `within` is missing or ambiguous. */
+export function findAllIgnoringIndex(roots: readonly HostNode[], m: Matcher): HostNode[] {
+  let scope = roots;
+  if (m.within !== undefined) scope = resolveOne(roots, m.within).children;
+  const out: HostNode[] = [];
+  for (const n of preorder(scope)) {
+    if (!matchesSelf(n, m)) continue;
+    if (m.text !== undefined && hasMatchingDescendant(n, m)) continue;
+    out.push(n);
+  }
+  return out;
+}
+
+/**
+ * Elements for `m`. With `index`, at most one element (empty if out of range).
+ * Assertions use this directly and apply their own semantics to the count.
+ */
+export function findAll(roots: readonly HostNode[], m: Matcher): HostNode[] {
+  const all = findAllIgnoringIndex(roots, m);
+  if (m.index === undefined) return all;
+  const picked = all[m.index];
+  return picked === undefined ? [] : [picked];
+}
+
+export type Summarizer = (node: HostNode) => ElementSummary;
+
+/**
+ * Exactly one element, for actions and `within`: ELEMENT_NOT_FOUND / MULTIPLE_MATCHES otherwise.
+ * `summarize` is used to list the candidates in MULTIPLE_MATCHES.
+ */
+export function resolveOne(roots: readonly HostNode[], m: Matcher, summarize?: Summarizer): HostNode {
+  const found = findAll(roots, m);
+  if (found.length === 0) throw new QuiescoError('ELEMENT_NOT_FOUND', `No element matches ${describeMatcher(m)}`, { matcher: m });
+  if (found.length > 1) {
+    throw new QuiescoError(
+      'MULTIPLE_MATCHES',
+      `${found.length} elements match ${describeMatcher(m)}; add \`index\` or a more specific matcher`,
+      { matcher: m, matches: summarize === undefined ? [] : found.map(summarize) },
+    );
+  }
+  return found[0] as HostNode;
+}
+
+function fmt(t: TextMatch): string {
+  return typeof t === 'string' ? JSON.stringify(t) : `/${t.regex.source}/${t.regex.flags}`;
+}
+
+/** Human-readable matcher, e.g. `{ id: "submit", within: { id: "form" } }`. */
+export function describeMatcher(m: Matcher): string {
+  const parts: string[] = [];
+  if (m.id !== undefined) parts.push(`id: ${fmt(m.id)}`);
+  if (m.text !== undefined) parts.push(`text: ${fmt(m.text)}`);
+  if (m.label !== undefined) parts.push(`label: ${fmt(m.label)}`);
+  if (m.role !== undefined) parts.push(`role: ${JSON.stringify(m.role)}`);
+  if (m.type !== undefined) parts.push(`type: ${JSON.stringify(m.type)}`);
+  if (m.has !== undefined) parts.push(`has: ${describeMatcher(m.has)}`);
+  if (m.not !== undefined) parts.push(`not: ${describeMatcher(m.not)}`);
+  if (m.within !== undefined) parts.push(`within: ${describeMatcher(m.within)}`);
+  if (m.index !== undefined) parts.push(`index: ${m.index}`);
+  return `{ ${parts.join(', ')} }`;
+}

package/src/query/semantic.ts

@@ -0,0 +1,266 @@
+/**
+ * Platform-independent element kinds and states (Phase 6.1).
+ *
+ * The semantic type comes from, in order:
+ * 1. the accessibility role (`accessibilityRole` / `role`), which the app states explicitly;
+ * 2. a scroll host rendered by a virtualized list (its owner has a `renderItem` prop) → `list`;
+ * 3. the host component type (`RCTText`, `AndroidSwitch`, `input`, ...). Host type strings are not
+ *    minified, so this works in release builds;
+ * 4. the display name of a component rendering the host (`Pressable`, `TouchableOpacity`, ...);
+ *    only components with an explicit displayName are reliable in release builds;
+ * 5. a host whose owner has an `onPress` handler → `button`.
+ *
+ * Host names are React Native 0.88's (findings.md "6.1 源码确认") plus common community components.
+ *
+ * Widgets made of several hosts: a host rendered directly by its parent host's component
+ * (`renderedWithParent`) with the same semantic type as the parent is a PART of the parent widget,
+ * e.g. react-native-web's Switch = root `<div>` (testID, typed via the Switch displayName) + an
+ * `<input role="switch">` holding `checked` / `disabled`. Parts do not match `type` on their own,
+ * and the widget reads its state (checked, value, enabled, focus) from its parts.
+ */
+import type { JsonValue, SemanticType } from '@quiesco/protocol';
+
+import type { HostNode } from '../fiber-adapter';
+
+const ROLES: Readonly<Record<string, SemanticType>> = {
+  button: 'button',
+  togglebutton: 'button',
+  imagebutton: 'button',
+  link: 'link',
+  header: 'header',
+  heading: 'header',
+  text: 'text',
+  image: 'image',
+  img: 'image',
+  switch: 'switch',
+  checkbox: 'checkbox',
+  radio: 'radio',
+  adjustable: 'slider',
+  slider: 'slider',
+  search: 'input',
+  searchbox: 'input',
+  textbox: 'input',
+  progressbar: 'progress',
+  combobox: 'picker',
+  spinbutton: 'picker',
+  list: 'list',
+};
+
+const HOSTS: Readonly<Record<string, SemanticType>> = {
+  // React Native 0.88
+  RCTText: 'text',
+  RCTVirtualText: 'text',
+  RCTSelectableText: 'text',
+  RCTSinglelineTextInputView: 'input',
+  RCTMultilineTextInputView: 'input',
+  AndroidTextInput: 'input',
+  RCTImageView: 'image',
+  Switch: 'switch',
+  RCTSwitch: 'switch',
+  AndroidSwitch: 'switch',
+  ActivityIndicatorView: 'progress',
+  AndroidProgressBar: 'progress',
+  RCTScrollView: 'scroll',
+  AndroidHorizontalScrollView: 'scroll',
+  // Community components
+  RNCSlider: 'slider',
+  RNCPicker: 'picker',
+  RNCAndroidDialogPicker: 'picker',
+  RNCAndroidDropdownPicker: 'picker',
+  RNDateTimePicker: 'picker',
+  ExpoImage: 'image',
+  // DOM (react-native-web)
+  textarea: 'input',
+  img: 'image',
+  select: 'picker',
+  a: 'link',
+  button: 'button',
+  progress: 'progress',
+  h1: 'header',
+  h2: 'header',
+  h3: 'header',
+  h4: 'header',
+  h5: 'header',
+  h6: 'header',
+};
+
+const DOM_INPUT_TYPES: Readonly<Record<string, SemanticType>> = {
+  checkbox: 'checkbox',
+  radio: 'radio',
+  range: 'slider',
+  button: 'button',
+  submit: 'button',
+  reset: 'button',
+  image: 'button',
+};
+
+/** Components with an explicit displayName (or stable name) that identify the element's kind. */
+const OWNERS: Readonly<Record<string, SemanticType>> = {
+  Text: 'text',
+  TextInput: 'input',
+  Image: 'image',
+  ImageBackground: 'image',
+  ScrollView: 'scroll',
+  ActivityIndicator: 'progress',
+  Switch: 'switch',
+  Slider: 'slider',
+  Picker: 'picker',
+  Checkbox: 'checkbox',
+  CheckBox: 'checkbox',
+  Pressable: 'button',
+  TouchableOpacity: 'button',
+  TouchableHighlight: 'button',
+  TouchableNativeFeedback: 'button',
+  Button: 'button',
+};
+
+function isFunction(v: unknown): boolean {
+  return typeof v === 'function';
+}
+
+export function semanticType(node: HostNode): SemanticType | undefined {
+  if (node.role !== undefined) {
+    const r = ROLES[node.role.toLowerCase()];
+    if (r !== undefined) return r;
+  }
+  const host = node.type === 'input' ? (DOM_INPUT_TYPES[String(node.props['type'] ?? '')] ?? 'input') : HOSTS[node.type];
+  const owner = node.ownerProps();
+  if ((host === 'scroll' || node.clipsContent) && isFunction(owner['renderItem'])) return 'list';
+  if (host !== undefined) return host;
+  for (const name of node.ownerNames()) {
+    const o = OWNERS[name];
+    if (o !== undefined) return o;
+  }
+  return isFunction(owner['onPress']) ? 'button' : undefined;
+}
+
+/** Whether `node` is a part of its parent's widget (see the module comment). */
+export function isWidgetPart(node: HostNode, type: SemanticType | undefined = semanticType(node)): boolean {
+  return type !== undefined && node.renderedWithParent && node.parent !== null && semanticType(node.parent) === type;
+}
+
+/** The parts of `node`'s widget (direct children rendered with it, of the same semantic type). */
+export function widgetParts(node: HostNode, type: SemanticType | undefined = semanticType(node)): HostNode[] {
+  if (type === undefined) return [];
+  return node.children.filter((c) => c.renderedWithParent && semanticType(c) === type);
+}
+
+/** Whether `type` (from a matcher) names this element: semantic type, host type or a component name. */
+export function matchesType(node: HostNode, type: string): boolean {
+  if (node.type === type || node.ownerNames().includes(type)) return true;
+  const kind = semanticType(node);
+  return kind === type && !isWidgetPart(node, kind);
+}
+
+/** The element's accessibility label, or its widget part's (RNW puts a Switch's aria-label on the inner input). */
+export function widgetLabel(node: HostNode): string | undefined {
+  if (node.label !== undefined) return node.label;
+  for (const part of widgetParts(node)) if (part.label !== undefined) return part.label;
+  return undefined;
+}
+
+/** Focused, or one of its widget parts is (the focusable `<input>` of a web Switch). */
+export function isFocusedWidget(node: HostNode): boolean {
+  return node.isFocused() || widgetParts(node).some((p) => p.isFocused());
+}
+
+/** Props as the app wrote them: host props first, then the owning composites (Pressable `disabled`, ...). */
+function propOf(node: HostNode, name: string): unknown {
+  const own = node.props[name];
+  return own !== undefined ? own : node.ownerProps()[name];
+}
+
+function accessibilityState(node: HostNode): Record<string, unknown> {
+  const s = propOf(node, 'accessibilityState');
+  return typeof s === 'object' && s !== null ? (s as Record<string, unknown>) : {};
+}
+
+function isTrue(v: unknown): boolean {
+  return v === true || v === 'true';
+}
+
+function selfDisabled(node: HostNode): boolean {
+  return (
+    isTrue(propOf(node, 'disabled')) ||
+    isTrue(accessibilityState(node)['disabled']) ||
+    isTrue(propOf(node, 'aria-disabled')) ||
+    propOf(node, 'editable') === false
+  );
+}
+
+/**
+ * False when the element, an ancestor (a disabled Pressable disables its label too) or one of its
+ * widget parts is disabled.
+ */
+export function isEnabled(node: HostNode): boolean {
+  for (let n: HostNode | null = node; n !== null; n = n.parent) if (selfDisabled(n)) return false;
+  return !widgetParts(node).some(selfDisabled);
+}
+
+function toChecked(v: unknown): boolean | 'mixed' | undefined {
+  if (v === true || v === 'true') return true;
+  if (v === false || v === 'false') return false;
+  if (v === 'mixed') return 'mixed';
+  return undefined;
+}
+
+/** Checked state: accessibilityState / aria-checked, a DOM checkbox, a Switch's `value`, or a widget part's. */
+export function checkedState(node: HostNode, type: SemanticType | undefined = semanticType(node)): boolean | 'mixed' | undefined {
+  const own = ownChecked(node, type);
+  if (own !== undefined) return own;
+  for (const part of widgetParts(node, type)) {
+    const c = ownChecked(part, type);
+    if (c !== undefined) return c;
+  }
+  return undefined;
+}
+
+function ownChecked(node: HostNode, type: SemanticType | undefined): boolean | 'mixed' | undefined {
+  const fromA11y = toChecked(accessibilityState(node)['checked']) ?? toChecked(propOf(node, 'aria-checked'));
+  if (fromA11y !== undefined) return fromA11y;
+  if (type === 'switch' || type === 'checkbox' || type === 'radio') {
+    return toChecked(propOf(node, 'checked')) ?? toChecked(propOf(node, 'value'));
+  }
+  return undefined;
+}
+
+function jsonScalar(v: unknown): JsonValue | undefined {
+  if (typeof v === 'string' || typeof v === 'boolean') return v;
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  return undefined;
+}
+
+/** The element's value: input text, switch state, slider / picker value, accessibilityValue, or a widget part's. */
+export function elementValue(node: HostNode, type: SemanticType | undefined = semanticType(node)): JsonValue | undefined {
+  const own = ownValue(node, type);
+  if (own !== undefined) return own;
+  for (const part of widgetParts(node, type)) {
+    const v = ownValue(part, type);
+    if (v !== undefined) return v;
+  }
+  return undefined;
+}
+
+function ownValue(node: HostNode, type: SemanticType | undefined): JsonValue | undefined {
+  const text = node.inputValue();
+  if (text !== undefined) return text;
+  if (type === 'switch' || type === 'checkbox' || type === 'radio') {
+    const c = ownChecked(node, type);
+    if (typeof c === 'boolean') return c;
+  }
+  if (type === 'picker') {
+    const v = jsonScalar(propOf(node, 'selectedValue')) ?? jsonScalar(propOf(node, 'value'));
+    if (v !== undefined) return v;
+  }
+  if (type === 'slider' || type === 'progress') {
+    const v = jsonScalar(propOf(node, 'value'));
+    if (v !== undefined) return v;
+  }
+  const a11y = propOf(node, 'accessibilityValue');
+  if (typeof a11y === 'object' && a11y !== null) {
+    const o = a11y as Record<string, unknown>;
+    const v = jsonScalar(o['text']) ?? jsonScalar(o['now']);
+    if (v !== undefined) return v;
+  }
+  return jsonScalar(propOf(node, 'aria-valuetext')) ?? jsonScalar(propOf(node, 'aria-valuenow'));
+}

package/src/query/tree.ts

@@ -0,0 +1,116 @@
+/**
+ * Serialization of HostNodes: element summaries (query / assert results), the compact diagnostic
+ * tree (`getTree`), and the structure hash used by the frame-stable tracker.
+ */
+import type { ElementSummary, JsonValue, Rect, TreeNode } from '@quiesco/protocol';
+
+import type { HostNode, Viewport } from '../fiber-adapter';
+import { checkedState, elementValue, isEnabled, isFocusedWidget, semanticType, widgetLabel } from './semantic';
+import { visibleRatio } from './visibility';
+
+/** Props never worth sending: structural, or huge and useless for assertions. */
+// `ref`: React 19 passes it as a prop; a DOM ref holds the element and its fiber (huge, circular).
+const SKIPPED_PROPS = new Set(['children', 'style', 'collapsable', 'collapsableChildren', 'ref']);
+const MAX_DEPTH = 4;
+
+function isReactElement(v: object): boolean {
+  return '$$typeof' in v;
+}
+
+/** JSON-safe copy: drops functions, symbols, React elements and cycles; bounds depth. */
+export function toJsonValue(v: unknown, depth = 0, seen: Set<object> = new Set()): JsonValue | undefined {
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return v;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (typeof v !== 'object' || depth >= MAX_DEPTH || seen.has(v) || isReactElement(v)) return undefined;
+  seen.add(v);
+  try {
+    if (Array.isArray(v)) return v.map((x) => toJsonValue(x, depth + 1, seen) ?? null);
+    const out: Record<string, JsonValue> = {};
+    for (const [k, x] of Object.entries(v)) {
+      const j = toJsonValue(x, depth + 1, seen);
+      if (j !== undefined) out[k] = j;
+    }
+    return out;
+  } finally {
+    seen.delete(v);
+  }
+}
+
+export function serializableProps(props: Readonly<Record<string, unknown>>): Record<string, JsonValue> {
+  const out: Record<string, JsonValue> = {};
+  for (const [k, v] of Object.entries(props)) {
+    if (SKIPPED_PROPS.has(k)) continue;
+    const j = toJsonValue(v);
+    if (j !== undefined) out[k] = j;
+  }
+  return out;
+}
+
+export function summarize(node: HostNode, viewport: Viewport | null): ElementSummary {
+  const rect = node.measure();
+  const ratio = visibleRatio(node, viewport, rect);
+  const kind = semanticType(node);
+  const s: ElementSummary = {
+    type: node.type,
+    text: node.text,
+    rect,
+    visible: ratio > 0,
+    visibleRatio: Math.round(ratio * 1000) / 1000,
+    focused: isFocusedWidget(node),
+    enabled: isEnabled(node),
+    props: serializableProps(node.props),
+  };
+  if (node.testID !== undefined) s.testID = node.testID;
+  if (node.role !== undefined) s.role = node.role;
+  const label = widgetLabel(node);
+  if (label !== undefined) s.label = label;
+  if (kind !== undefined) s.semanticType = kind;
+  const checked = checkedState(node, kind);
+  if (checked !== undefined) s.checked = checked;
+  const value = elementValue(node, kind);
+  if (value !== undefined) s.value = value;
+  return s;
+}
+
+function roundRect(r: Rect): Rect {
+  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+}
+
+export function toTreeNode(node: HostNode): TreeNode {
+  const t: TreeNode = { type: node.type, children: node.children.map(toTreeNode) };
+  if (node.testID !== undefined) t.testID = node.testID;
+  const text = node.ownText;
+  if (text !== '') t.text = text;
+  if (node.role !== undefined) t.role = node.role;
+  const kind = semanticType(node);
+  if (kind !== undefined) t.semanticType = kind;
+  const rect = node.measure();
+  if (rect !== null) t.rect = roundRect(rect);
+  return t;
+}
+
+/** `getTree` result. Several top-level hosts are wrapped in a synthetic `root` node. */
+export function getTree(roots: readonly HostNode[]): TreeNode | null {
+  if (roots.length === 0) return null;
+  if (roots.length === 1) return toTreeNode(roots[0] as HostNode);
+  return { type: 'root', children: roots.map(toTreeNode) };
+}
+
+/**
+ * Structure snapshot for the frame-stable tracker (requirements.md §6.2-5): one line per host node in
+ * tree order with its type, testID, text, rounded rect and child count. Two frames are stable when the
+ * lines are equal; the lines also say which node changed when the tree never settles.
+ */
+export function structureLines(roots: readonly HostNode[], skip?: ReadonlySet<HostNode>): string[] {
+  const lines: string[] = [];
+  const stack = [...roots].reverse();
+  while (stack.length > 0) {
+    const n = stack.pop() as HostNode;
+    if (skip?.has(n) === true) continue; // and its subtree
+    const r = n.measure();
+    const rect = r === null ? '-' : `${Math.round(r.x)},${Math.round(r.y)} ${Math.round(r.width)}x${Math.round(r.height)}`;
+    lines.push(`${n.type}${n.testID === undefined ? '' : `#${n.testID}`}${n.ownText === '' ? '' : ` ${JSON.stringify(n.ownText)}`} @${rect} children=${n.children.length}`);
+    for (let i = n.children.length - 1; i >= 0; i--) stack.push(n.children[i] as HostNode);
+  }
+  return lines;
+}

package/src/query/visibility.ts

@@ -0,0 +1,60 @@
+/**
+ * Visibility rules (requirements.md §6.1; clipping added in Phase 6.1). The visible part of an
+ * element is its rect intersected with:
+ * - the viewport (window), when its size is known;
+ * - every ancestor that clips its content: scroll views and `overflow` other than `visible`.
+ *
+ * `visibleRatio` = visible area / element area. An element is visible when the ratio is > 0 and
+ * neither it nor an ancestor is hidden by style (`display: none` / `opacity: 0`).
+ *
+ * Not considered (documented limitations): being covered by another element (actions check that
+ * separately, ELEMENT_OBSCURED), and transforms not reflected in the measured rect.
+ */
+import type { Rect } from '@quiesco/protocol';
+
+import type { HostNode, Viewport } from '../fiber-adapter';
+
+export function hiddenByAncestorStyle(node: HostNode): boolean {
+  for (let n: HostNode | null = node; n !== null; n = n.parent) if (n.hiddenByStyle) return true;
+  return false;
+}
+
+function intersect(a: Rect, b: Rect): Rect | null {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const w = Math.min(a.x + a.width, b.x + b.width) - x;
+  const h = Math.min(a.y + a.height, b.y + b.height) - y;
+  return w > 0 && h > 0 ? { x, y, width: w, height: h } : null;
+}
+
+export function intersectsViewport(rect: Rect, viewport: Viewport): boolean {
+  return intersect(rect, { x: 0, y: 0, width: viewport.width, height: viewport.height }) !== null;
+}
+
+/**
+ * The part of `rect` not clipped by the viewport or by clipping ancestors of `node`, or null when
+ * nothing is left. Ancestors that cannot be measured do not clip.
+ */
+export function visiblePart(node: HostNode, viewport: Viewport | null, rect: Rect): Rect | null {
+  let part: Rect | null = rect;
+  if (viewport !== null) part = intersect(part, { x: 0, y: 0, width: viewport.width, height: viewport.height });
+  for (let a = node.parent; a !== null && part !== null; a = a.parent) {
+    if (!a.clipsContent) continue;
+    const clip = a.measure();
+    if (clip !== null) part = intersect(part, clip);
+  }
+  return part;
+}
+
+/** Visible fraction of the element's area, 0–1. */
+export function visibleRatio(node: HostNode, viewport: Viewport | null, rect: Rect | null = node.measure()): number {
+  if (hiddenByAncestorStyle(node)) return 0;
+  if (rect === null || rect.width <= 0 || rect.height <= 0) return 0;
+  const part = visiblePart(node, viewport, rect);
+  if (part === null) return 0;
+  return Math.min(1, (part.width * part.height) / (rect.width * rect.height));
+}
+
+export function isVisible(node: HostNode, viewport: Viewport | null, rect: Rect | null = node.measure()): boolean {
+  return visibleRatio(node, viewport, rect) > 0;
+}

package/src/reset/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Soft reset (requirements.md §6.5):
+ * 1. clear persistent storage (built-in adapters for the platform + adapters registered by the app),
+ * 2. run the app's onReset hooks (in registration order),
+ * 3. remount the whole app by changing QuiescoRoot's key,
+ * 4. (the runtime then waits for idle).
+ * A failing step aborts the reset with RESET_FAILED naming the step.
+ */
+import type { StorageAdapter } from '../api-types';
+import { QuiescoError } from '../errors';
+
+export class ResetManager {
+  private readonly hooks: (() => void | Promise<void>)[] = [];
+  private readonly storages: StorageAdapter[] = [];
+
+  constructor(private readonly builtInStorage: () => StorageAdapter[]) {}
+
+  onReset(hook: () => void | Promise<void>): () => void {
+    if (typeof hook !== 'function') throw new TypeError('quiesco.onReset(hook): hook must be a function');
+    this.hooks.push(hook);
+    return () => {
+      const i = this.hooks.indexOf(hook);
+      if (i >= 0) this.hooks.splice(i, 1);
+    };
+  }
+
+  registerStorage(adapter: StorageAdapter): () => void {
+    if (adapter == null || typeof adapter.clear !== 'function') throw new TypeError('quiesco.registerStorage(adapter): adapter.clear must be a function');
+    this.storages.push(adapter);
+    return () => {
+      const i = this.storages.indexOf(adapter);
+      if (i >= 0) this.storages.splice(i, 1);
+    };
+  }
+
+  /** Steps 1–3. `remount` is null when QuiescoRoot is not mounted. */
+  async run(remount: (() => void) | null): Promise<void> {
+    for (const s of [...this.builtInStorage(), ...this.storages]) {
+      await step(`storage:${s.name}`, () => s.clear());
+    }
+    let i = 0;
+    for (const hook of [...this.hooks]) {
+      await step(`onReset#${i++}`, hook);
+    }
+    if (remount === null) {
+      throw new QuiescoError('RESET_FAILED', 'Soft reset failed at remount: QuiescoRoot is not mounted', { step: 'remount', message: 'QuiescoRoot is not mounted' });
+    }
+    await step('remount', remount);
+  }
+}
+
+async function step(name: string, fn: () => void | Promise<void>): Promise<void> {
+  try {
+    await fn();
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new QuiescoError('RESET_FAILED', `Soft reset failed at ${name}: ${message}`, { step: name, message });
+  }
+}

package/src/reset/storage-defaults.native.ts

@@ -0,0 +1,26 @@
+/**
+ * Built-in stores cleared on soft reset, iOS / Android (Metro picks this over storage-defaults.ts).
+ * AsyncStorage is optional: Metro treats a `require` directly inside a `try` block as an optional
+ * dependency (transformer.allowOptionalDependencies, on by default), so apps without it still bundle.
+ * Only the default (legacy) store is cleared; stores from `createAsyncStorage(name)` need an adapter.
+ */
+import type { StorageAdapter } from '../api-types';
+
+declare const require: (id: string) => unknown;
+
+interface AsyncStorageLike {
+  clear(): Promise<void>;
+}
+
+export function defaultStorageAdapters(): StorageAdapter[] {
+  let asyncStorage: AsyncStorageLike | undefined;
+  try {
+    const mod = require('@react-native-async-storage/async-storage') as { default?: AsyncStorageLike } & Partial<AsyncStorageLike>;
+    asyncStorage = mod.default ?? (mod as AsyncStorageLike);
+  } catch {
+    asyncStorage = undefined;
+  }
+  if (asyncStorage === undefined || typeof asyncStorage.clear !== 'function') return [];
+  const s = asyncStorage;
+  return [{ name: 'AsyncStorage', clear: () => s.clear() }];
+}