@quiesco/agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quiesco contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @quiesco/agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The in-app agent of Quiesco: element queries, synchronization trackers (network, timers, React,
+animations), actions, soft reset and backdoors. It connects to the test run from inside the e2e build of
+your app; without `EXPO_PUBLIC_QUIESCO=1` it is replaced by a no-op stub.
+
+```sh
+npm i @quiesco/agent @quiesco/native
+```
+
+- `metro.config.js`: `module.exports = withQuiesco(getDefaultConfig(__dirname))` with
+  `const { withQuiesco } = require('@quiesco/agent/metro')`.
+- Import `@quiesco/agent` first in the entry file and wrap the root in `<QuiescoRoot>`.
+
+`npx quiesco init` sets up Metro and the entry file. In-app API (`quiesco.backdoor`, `quiesco.onReset`, …):
+[API reference](https://shift-14cc7601.mintlify.site/api).
+
+Peer dependencies: `react` >= 19.2, `react-native` >= 0.83 (New Architecture). Supported: Expo SDK 58.
+
+Part of [Quiesco](https://github.com/h2nology/quiesco): gray-box end-to-end testing for Expo apps on iOS, Android and the web. Setup: `npx quiesco init` ([quick start](https://github.com/h2nology/quiesco#quick-start-web-about-10-minutes)).
+
+## License
+
+MIT

package/metro.cjs

@@ -0,0 +1,144 @@
+// @ts-check
+/**
+ * Metro integration (docs/spikes/06-prod-strip.md, approach B).
+ *
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withQuiesco } = require('@quiesco/agent/metro');
+ *   module.exports = withQuiesco(getDefaultConfig(__dirname));
+ *
+ * - Not an e2e build (`EXPO_PUBLIC_QUIESCO !== '1'`): `@quiesco/agent` resolves to the stub, so no agent
+ *   code reaches the bundle. A guard inside node_modules would not work: babel-preset-expo does not
+ *   inline EXPO_PUBLIC_* there.
+ * - e2e build: the agent's `build-config` module is replaced by a generated file carrying the fallback
+ *   port / session (`EXPO_PUBLIC_QUIESCO_PORT`, `EXPO_PUBLIC_QUIESCO_SESSION`), used when no launch
+ *   parameters are available (JS-only mode).
+ * - e2e build: the agent's early module (`src/early.ts`: React DevTools hook + scheduler patch) is put
+ *   first in `serializer.getModulesRunBeforeMainModule`. React Native 0.88 loads its renderer from
+ *   `setup-env`, which Metro runs before the app entry; a hook installed later is never seen by the
+ *   renderer in release builds (no React DevTools hook there).
+ *
+ * - e2e build: `expo/fetch` imported by the app or a library resolves to `src/expo-fetch.js`, which
+ *   re-exports it with a tracked `fetch` (Phase 6.10: the real module's exports are non-configurable
+ *   getters, so the network tracker cannot patch them at runtime). Expo's own code reaches its fetch
+ *   through relative paths and is not affected; the global fetch is tracked separately.
+ *
+ * - Always: the artifacts directory (`options.artifactsDir`, default `artifacts`, relative to the project
+ *   root; `false` for none) is added to `resolver.blockList` (Phase 6.12).
+ *   Metro sends every connected app an HMR update for any watched file that changes, even one outside
+ *   the bundle; the dev client then shows its "Refreshing..." window over the app, and a touch from
+ *   another parallel worker lands on that window. Screenshots and JSON written there would do that.
+ *   `.expo/devices.json` is blocked for the same reason: Expo's dev server rewrites it on every manifest
+ *   request, i.e. every time a dev client app starts (`ManifestMiddleware.saveDevicesAsync`).
+ *
+ * Plain CommonJS on purpose: Node loads metro.config.js without a TypeScript step.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const AGENT = '@quiesco/agent';
+const AGENT_SRC = path.join(__dirname, 'src');
+const STUB = path.join(AGENT_SRC, 'stub.ts');
+const EARLY = path.join(AGENT_SRC, 'early.ts');
+const EXPO_FETCH = path.join(AGENT_SRC, 'expo-fetch.js');
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+function isE2E(env) {
+  return env.EXPO_PUBLIC_QUIESCO === '1';
+}
+
+/**
+ * Write the build-time connection fallback and return its path.
+ * @param {string} projectRoot
+ * @param {NodeJS.ProcessEnv} env
+ */
+function writeBuildConfig(projectRoot, env) {
+  const port = Number.parseInt(env.EXPO_PUBLIC_QUIESCO_PORT ?? '', 10);
+  const config = { port: Number.isInteger(port) ? port : null, session: env.EXPO_PUBLIC_QUIESCO_SESSION ?? null };
+  const dir = path.join(projectRoot, '.expo', 'quiesco');
+  const file = path.join(dir, 'build-config.js');
+  const source = `// Generated by @quiesco/agent/metro. Do not edit.\nexport const buildConfig = ${JSON.stringify(config)};\n`;
+  fs.mkdirSync(dir, { recursive: true });
+  if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== source) fs.writeFileSync(file, source);
+  return file;
+}
+
+/** @param {string} p absolute path */
+const escapePath = (p) => path.resolve(p).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * `blockList` (a RegExp, a list of them, or unset) plus the given files and directories (with everything
+ * under them).
+ * @param {RegExp | RegExp[] | undefined | null} blockList
+ * @param {{ files: string[]; dirs: string[] }} paths absolute paths
+ * @returns {RegExp[]}
+ */
+function blockPaths(blockList, { files, dirs }) {
+  const existing = blockList === undefined || blockList === null ? [] : Array.isArray(blockList) ? blockList : [blockList];
+  return [
+    ...existing,
+    ...files.map((f) => new RegExp(`^${escapePath(f)}$`)),
+    ...dirs.map((d) => new RegExp(`^${escapePath(d)}(?:[\\\\/].*)?$`)),
+  ];
+}
+
+/**
+ * @template {{ projectRoot?: string; resolver?: { resolveRequest?: Function | null; blockList?: RegExp | RegExp[] | null }; serializer?: { getModulesRunBeforeMainModule?: (entryFilePath: string) => string[] } }} T
+ * @param {T} config Metro config (e.g. from expo/metro-config)
+ * @param {{ enabled?: boolean; env?: NodeJS.ProcessEnv; projectRoot?: string; artifactsDir?: string | false }} [options]
+ * @returns {T}
+ */
+function withQuiesco(config, options = {}) {
+  const env = options.env ?? process.env;
+  const enabled = options.enabled ?? isE2E(env);
+  const projectRoot = options.projectRoot ?? config.projectRoot ?? process.cwd();
+  const buildConfigFile = enabled ? writeBuildConfig(projectRoot, env) : null;
+  const upstream = config.resolver?.resolveRequest ?? null;
+  const artifactsDir = options.artifactsDir ?? 'artifacts';
+  const blockList = blockPaths(config.resolver?.blockList, {
+    files: [path.join(projectRoot, '.expo', 'devices.json')],
+    dirs: artifactsDir === false ? [] : [path.resolve(projectRoot, artifactsDir)],
+  });
+
+  /**
+   * @param {{ originModulePath: string; resolveRequest: Function }} context
+   * @param {string} moduleName
+   * @param {string | null} platform
+   */
+  function resolveRequest(context, moduleName, platform) {
+    if (!enabled && moduleName === AGENT) return { type: 'sourceFile', filePath: STUB };
+    if (buildConfigFile !== null && moduleName === './build-config' && path.dirname(context.originModulePath) === AGENT_SRC) {
+      return { type: 'sourceFile', filePath: buildConfigFile };
+    }
+    if (enabled && moduleName === 'expo/fetch' && path.resolve(context.originModulePath) !== EXPO_FETCH) {
+      return { type: 'sourceFile', filePath: EXPO_FETCH };
+    }
+    return upstream !== null ? upstream(context, moduleName, platform) : context.resolveRequest(context, moduleName, platform);
+  }
+
+  const resolver = { ...config.resolver, resolveRequest, blockList };
+  if (!enabled) return { ...config, resolver };
+
+  // Metro compares these paths with the (real) paths of modules in the graph.
+  const early = fs.realpathSync(EARLY);
+  const upstreamBefore = config.serializer?.getModulesRunBeforeMainModule;
+  /** @param {string} entryFilePath */
+  function getModulesRunBeforeMainModule(entryFilePath) {
+    const rest = typeof upstreamBefore === 'function' ? upstreamBefore(entryFilePath) : [];
+    return [early, ...rest.filter((p) => p !== early)];
+  }
+  // Expo's serializer (withExpoSerializers) captured the original `config.serializer` object in
+  // getDefaultConfig() and reads getModulesRunBeforeMainModule from it when exporting (release
+  // bundles); the dev server reads the returned config. Set it on both.
+  if (config.serializer !== undefined && config.serializer !== null) config.serializer.getModulesRunBeforeMainModule = getModulesRunBeforeMainModule;
+  return {
+    ...config,
+    resolver,
+    serializer: { ...config.serializer, getModulesRunBeforeMainModule },
+  };
+}
+
+module.exports = { withQuiesco, isE2E };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@quiesco/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Quiesco in-app agent (React Native / Expo, iOS / Android / Web)",
+  "license": "MIT",
+  "author": "h2nology",
+  "keywords": [
+    "quiesco",
+    "e2e",
+    "testing",
+    "expo",
+    "react-native",
+    "agent",
+    "metro"
+  ],
+  "homepage": "https://github.com/h2nology/quiesco/tree/main/packages/agent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h2nology/quiesco.git",
+    "directory": "packages/agent"
+  },
+  "bugs": {
+    "url": "https://github.com/h2nology/quiesco/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "react-native": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./stub": "./src/stub.ts",
+    "./metro": "./metro.cjs"
+  },
+  "files": [
+    "src",
+    "metro.cjs"
+  ],
+  "dependencies": {
+    "@quiesco/protocol": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.2",
+    "react-native": ">=0.83"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
 }

package/src/actions/hit-test.ts

@@ -0,0 +1,42 @@
+/** Geometry shared by the action performers: centers, hit testing, element descriptions. */
+import type { Rect } from '@quiesco/protocol';
+
+import type { HostNode } from '../fiber-adapter';
+
+export function center(r: Rect): { x: number; y: number } {
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}
+
+export function contains(r: Rect, p: { x: number; y: number }): boolean {
+  return p.x >= r.x && p.x < r.x + r.width && p.y >= r.y && p.y < r.y + r.height;
+}
+
+/** Whether `a` is `b` or one of its ancestors (compared as rendered elements, not objects). */
+export function isAncestor(a: HostNode, b: HostNode): boolean {
+  for (let n: HostNode | null = b; n !== null; n = n.parent) if (a.isSameElement(n)) return true;
+  return false;
+}
+
+export function describe(n: HostNode): string {
+  const id = n.testID !== undefined ? ` testID="${n.testID}"` : '';
+  const text = n.text !== '' ? ` text="${n.text.slice(0, 40)}"` : '';
+  return `<${n.type}${id}${text}>`;
+}
+
+/**
+ * Topmost host node whose rect contains `p` (later in render order = drawn on top; zIndex / elevation
+ * are not considered). `pointerEvents: none` removes a subtree, `box-none` only the node itself.
+ */
+export function hitTest(roots: readonly HostNode[], p: { x: number; y: number }): HostNode | null {
+  let top: HostNode | null = null;
+  const visit = (n: HostNode): void => {
+    if (n.hiddenByStyle) return;
+    const pe = n.props['pointerEvents'];
+    if (pe === 'none') return;
+    const r = n.measure();
+    if (pe !== 'box-none' && r !== null && r.width > 0 && r.height > 0 && contains(r, p)) top = n;
+    for (const c of n.children) visit(c);
+  };
+  for (const r of roots) visit(r);
+  return top;
+}

package/src/actions/host.ts

@@ -0,0 +1,194 @@
+/**
+ * `native` action mode without @quiesco/native: the host injects real input (web: Playwright mouse,
+ * touchscreen, keyboard, wheel). The agent picks the point and runs the same checks as the in-app
+ * native mode (stable position, nothing on top), then returns the HostInput; the host injects it and
+ * waits for idle. Nothing here depends on the platform: a provider that cannot inject a kind of input
+ * rejects it with a clear error.
+ */
+import type { Direction, HostInput, Matcher, Point, Rect, Speed } from '@quiesco/protocol';
+
+import { QuiescoError } from '../errors';
+import type { HostNode, Viewport } from '../fiber-adapter';
+import { summarize } from '../query';
+import type { Clock } from '../sync';
+import { center, describe, hitTest, isAncestor } from './hit-test';
+import type { ActionPerformer } from './performer';
+import type { FingerPath } from './multitouch';
+import { framesForSequence, pinchGestures, rotateGesture } from './multitouch';
+import * as value from './value';
+
+export interface HostContext {
+  clock: Clock;
+  roots: () => readonly HostNode[];
+  viewport: () => Viewport | null;
+  matcher: Matcher;
+  deadline: number;
+}
+
+const LONG_PRESS_MS = 800;
+const STABLE_POLL_MS = 16;
+const SCROLL_FRACTION = 0.8;
+
+export function hostPerformer(ctx: HostContext): ActionPerformer {
+  const sleep = (ms: number): Promise<void> =>
+    new Promise((r) => {
+      ctx.clock.setTimeout(r, ms);
+    });
+
+  /** The node's rect once it stops moving, after checking nothing covers the touch point (default: center). */
+  const ready = async (node: HostNode, point?: Point): Promise<Rect> => {
+    let prev: Rect | null = null;
+    for (;;) {
+      const rect = node.measure();
+      if (rect === null) throw new QuiescoError('ELEMENT_NOT_FOUND', 'The element cannot be measured (unmounted?)', { matcher: ctx.matcher });
+      const same = prev !== null && Math.abs(prev.x - rect.x) < 0.5 && Math.abs(prev.y - rect.y) < 0.5 && Math.abs(prev.width - rect.width) < 0.5;
+      if (same || ctx.clock.now() >= ctx.deadline) {
+        const top = hitTest(ctx.roots(), point === undefined ? center(rect) : { x: rect.x + point.x, y: rect.y + point.y });
+        if (top !== null && !isAncestor(node, top)) {
+          throw new QuiescoError('ELEMENT_OBSCURED', `${describe(node)} is covered by ${describe(top)}; a real click would not reach it`, {
+            matcher: ctx.matcher,
+            element: summarize(node, ctx.viewport()),
+            obscuredBy: describe(top),
+          });
+        }
+        return rect;
+      }
+      prev = rect;
+      await sleep(STABLE_POLL_MS);
+    }
+  };
+
+  const tapAt = async (node: HostNode, extra: { count?: number; holdMs?: number; point?: Point } = {}): Promise<HostInput> => {
+    const rect = await ready(node, extra.point);
+    const c = extra.point === undefined ? center(rect) : { x: rect.x + extra.point.x, y: rect.y + extra.point.y };
+    const input: HostInput = { kind: 'tap', x: c.x, y: c.y };
+    if (extra.count !== undefined) input.count = extra.count;
+    if (extra.holdMs !== undefined) input.holdMs = extra.holdMs;
+    return input;
+  };
+
+  const typeAt = async (node: HostNode, text: string, clearFirst: boolean): Promise<HostInput> => {
+    const c = center(await ready(node));
+    return { kind: 'type', x: c.x, y: c.y, text, clearFirst };
+  };
+
+  /** Wheel over the element (at `from`, normalized, when given); `down` reveals content below. */
+  const wheel = async (node: HostNode, content: Direction, distance?: number, from?: Point): Promise<HostInput> => {
+    const rect = await ready(node);
+    const at = from === undefined ? center(rect) : { x: rect.x + from.x * rect.width, y: rect.y + from.y * rect.height };
+    const vertical = content === 'up' || content === 'down';
+    const d = distance ?? (vertical ? rect.height : rect.width) * SCROLL_FRACTION;
+    const sign = content === 'down' || content === 'right' ? 1 : -1;
+    return { kind: 'wheel', x: at.x, y: at.y, dx: vertical ? 0 : sign * d, dy: vertical ? sign * d : 0 };
+  };
+
+  const contentFor = (finger: Direction): Direction => ({ up: 'down', down: 'up', left: 'right', right: 'left' } as const)[finger];
+
+  return {
+    viaHost: true,
+    tap: (node, point) => tapAt(node, point === undefined ? {} : { point }),
+    longPress: (node, durationMs, point) => tapAt(node, { holdMs: durationMs ?? LONG_PRESS_MS, ...(point === undefined ? {} : { point }) }),
+    multiTap: (node, count) => tapAt(node, { count }),
+    type: (node, text) => typeAt(node, text, false),
+    replaceText: (node, text) => typeAt(node, text, true),
+    clear: (node) => typeAt(node, '', true),
+    async pressKey(node, key) {
+      // The key goes to the focused element; focusing puts the caret at the end of the text.
+      if (!node.focus()) throw new QuiescoError('ACTION_NOT_SUPPORTED', `${describe(node)} cannot take the keyboard focus`, { action: 'pressKey', platform: 'web' });
+      return { kind: 'key', key: key === 'enter' ? 'Enter' : 'Backspace' };
+    },
+    scroll: (node, direction, distance, from) => wheel(node, direction, distance, from),
+    // A wheel moves content the way the finger swipe would (speed has no wheel equivalent).
+    swipe: (node, direction, _speed?: Speed, distance?: number, from?: Point) => wheel(node, contentFor(direction), distance, from),
+    async drag(node, to, holdMs, durationMs) {
+      const from = center(await ready(node));
+      return { kind: 'drag', from, to, durationMs, holdMs };
+    },
+    tapAt: async (point, holdMs) => ({ kind: 'tap', x: point.x, y: point.y, ...(holdMs === undefined ? {} : { holdMs }) }),
+
+    /**
+     * Real browser input where the DOM has it: `<select>` → selectOption, date / time inputs → fill,
+     * a switch / checkbox → click (when it must change), a segment → click. Sliders, and components
+     * that are not DOM form controls, are set through their callbacks (docs/api.mdx, value controls).
+     */
+    async setValue(control, v) {
+      const node = control.node;
+      if (node === null || value.isDisabledControl(control)) return value.jsSetValue(control, v, 'web');
+      if (node.type === 'select' && (control.kind === 'picker' || control.kind === 'select')) {
+        const i = value.pickerIndex(control, v, 'web');
+        const c = center(await ready(node));
+        return { kind: 'select', x: c.x, y: c.y, value: String((value.pickerItems(control)[i] as value.PickerItem).value) };
+      }
+      const inputType = node.type === 'input' ? String(node.props['type'] ?? 'text') : '';
+      if (control.dom === 'input' && inputType !== 'range') {
+        const c = center(await ready(node));
+        return { kind: 'fill', x: c.x, y: c.y, value: value.inputString(inputType, v, 'web') };
+      }
+      if (control.kind === 'switch' || control.kind === 'checkbox') {
+        if (typeof v !== 'boolean' || value.switchState(control) === v) return value.jsSetValue(control, v, 'web');
+        return tapAt(node);
+      }
+      if (control.kind === 'segmented') {
+        const i = value.segmentIndex(control, v, 'web');
+        const n = value.segmentValues(control).length;
+        const r = node.measure();
+        if (i === control.props['selectedIndex'] || r === null || n === 0) return value.jsSetValue(control, v, 'web');
+        return tapAt(node, { point: { x: ((i + 0.5) * r.width) / n, y: r.height / 2 } });
+      }
+      return value.jsSetValue(control, v, 'web');
+    },
+
+    /**
+     * Mouse drag of the thumb. The thumb is the square child of the slider (react-native-community
+     * slider's web implementation insets its track by half a thumb); the host injects the drag, so the
+     * result is not read back here (the step's assertion does that).
+     */
+    async adjustSlider(node, control, position) {
+      const rect = await ready(node);
+      const thumb = findThumb(node, rect);
+      const t = thumb?.width ?? 0;
+      const lo = rect.x + t / 2;
+      const hi = rect.x + rect.width - t / 2;
+      const range = value.sliderRange(control.props);
+      const current = typeof control.props['value'] === 'number' && range.max > range.min ? (control.props['value'] - range.min) / (range.max - range.min) : 0;
+      const y = thumb === null ? rect.y + rect.height / 2 : thumb.y + thumb.height / 2;
+      const from = thumb === null ? { x: lo + current * (hi - lo), y } : { x: thumb.x + thumb.width / 2, y };
+      return { kind: 'drag', from, to: { x: lo + position * (hi - lo), y }, durationMs: 300, holdMs: 0 };
+    },
+
+    // The DOM has no accessibility actions (react-native-web drops accessibilityActions): callbacks.
+    accessibilityAction: async (target, name) => value.jsAccessibilityAction(target, name, 'web'),
+
+    // Touch events with several touch points; the host rejects them on viewports without touch.
+    async pinch(node, scale, angle, speed, slop) {
+      const rect = await ready(node);
+      let gestures: FingerPath[][];
+      try {
+        gestures = pinchGestures(rect, scale, angle, speed, ctx.viewport(), slop);
+      } catch (e) {
+        throw new QuiescoError('ACTION_NOT_SUPPORTED', e instanceof Error ? e.message : String(e), { action: 'pinch', platform: 'web' });
+      }
+      return touches(gestures);
+    },
+    rotate: async (node, radians, speed, slop) => touches([rotateGesture(await ready(node), radians, speed, slop)]),
+    async multiTouch(node, fingers) {
+      if (node !== null) await ready(node);
+      return touches([fingers]);
+    },
+  };
+}
+
+function touches(gestures: FingerPath[][]): HostInput {
+  return { kind: 'touches', fingers: Math.max(...gestures.map((g) => g.length)), frames: framesForSequence(gestures) };
+}
+
+/** A square descendant narrower than half the slider: the thumb. */
+function findThumb(node: HostNode, rect: Rect): Rect | null {
+  for (const c of node.children) {
+    const r = c.measure();
+    if (r !== null && r.width > 4 && Math.abs(r.width - r.height) < 1 && r.width < rect.width / 2) return r;
+    const deeper = findThumb(c, rect);
+    if (deeper !== null) return deeper;
+  }
+  return null;
+}