@quiesco/agent 0.0.0-stage → 0.1.1

package/src/fiber-adapter/hook.ts

@@ -0,0 +1,154 @@
+/**
+ * `__REACT_DEVTOOLS_GLOBAL_HOOK__` integration (docs/spikes/01-fiber-query.md §1).
+ *
+ * - A hook already exists (debug builds: react-devtools-core installs it in InitializeCore; Expo web dev):
+ *   WRAP its methods and call the originals, so React DevTools keeps working.
+ * - No hook (release builds, web production): install a minimal one.
+ *
+ * Renderers look the hook up once, at module init. React Native 0.88 loads its renderer from
+ * `setup-env` (run by Metro before the app entry), so `withQuiesco()` makes Metro run the agent's
+ * early module (`src/early.ts`) before that. When the renderer is already registered on an existing
+ * hook anyway, its roots are taken over from `getFiberRoots`; only roots rendered before the agent
+ * (app code that ran first) are reported as a problem.
+ */
+import type { DevToolsHook, FiberRoot, RendererInternals } from './fiber';
+import { isObject } from './fiber';
+import type { RendererInfo, RendererKind } from './types';
+
+export const HOOK_KEY = '__REACT_DEVTOOLS_GLOBAL_HOOK__';
+const MARK = '__quiescoWrapped';
+
+const SUPPORTED: Record<string, RendererKind> = {
+  'react-native-renderer': 'native',
+  'react-dom': 'web',
+};
+const SUPPORTED_MAJOR = 19;
+
+export type CommitListener = (rendererID: number, root: FiberRoot) => void;
+
+export interface HookState {
+  source: 'existing' | 'installed';
+  renderers: Map<number, RendererInfo>;
+  roots: Map<number, Set<FiberRoot>>;
+  /** Renderers that had already rendered roots when we installed (state set up before may be missed). */
+  lateRenderers: RendererInfo[];
+  commitListeners: Set<CommitListener>;
+}
+
+export function describeRenderer(id: number, internals: RendererInternals): RendererInfo {
+  const packageName = internals.rendererPackageName ?? 'unknown';
+  const version = internals.version ?? internals.reconcilerVersion ?? 'unknown';
+  const kind = SUPPORTED[packageName];
+  const major = Number.parseInt(version, 10);
+  return {
+    id,
+    packageName,
+    version,
+    bundleType: internals.bundleType ?? 0,
+    kind: kind ?? 'native',
+    supported: kind !== undefined && major === SUPPORTED_MAJOR,
+  };
+}
+
+function addRoot(state: HookState, rendererID: unknown, root: unknown): void {
+  if (typeof rendererID !== 'number' || !isObject(root) || !('current' in root)) return;
+  let set = state.roots.get(rendererID);
+  if (set === undefined) state.roots.set(rendererID, (set = new Set()));
+  set.add(root as unknown as FiberRoot);
+}
+
+function onCommit(state: HookState, rendererID: unknown, root: unknown): void {
+  addRoot(state, rendererID, root);
+  if (typeof rendererID !== 'number' || !isObject(root)) return;
+  for (const l of state.commitListeners) {
+    try {
+      l(rendererID, root as unknown as FiberRoot);
+    } catch {
+      // A listener must never break the app's commit.
+    }
+  }
+}
+
+type HookMethod = (this: unknown, ...args: unknown[]) => unknown;
+
+function wrapMethod(hook: DevToolsHook, name: string, before: (args: unknown[]) => void): void {
+  const original = hook[name] as HookMethod | undefined;
+  hook[name] = function (this: unknown, ...args: unknown[]) {
+    try {
+      before(args);
+    } catch {
+      // never break the app
+    }
+    return typeof original === 'function' ? original.apply(this, args) : undefined;
+  };
+}
+
+/**
+ * Install (or wrap) the DevTools hook on `target`. Idempotent per target: a second call returns the
+ * state created by the first one (Fast Refresh re-evaluates modules).
+ */
+export function installHook(target: Record<string, unknown>): HookState {
+  const existing = target[HOOK_KEY];
+  if (isObject(existing) && isObject(existing[MARK])) return existing[MARK] as unknown as HookState;
+
+  const state: HookState = {
+    source: 'installed',
+    renderers: new Map(),
+    roots: new Map(),
+    lateRenderers: [],
+    commitListeners: new Set(),
+  };
+
+  if (isObject(existing) && typeof existing['inject'] === 'function') {
+    const hook = existing as DevToolsHook;
+    state.source = 'existing';
+    const originalInject = hook.inject;
+    hook.inject = function (this: unknown, internals: RendererInternals) {
+      const id = originalInject.call(this, internals);
+      state.renderers.set(id, describeRenderer(id, internals));
+      return id;
+    };
+    if (hook.renderers instanceof Map) {
+      for (const [id, internals] of hook.renderers) {
+        const info = describeRenderer(id, internals);
+        state.renderers.set(id, info);
+        const roots = typeof hook.getFiberRoots === 'function' ? hook.getFiberRoots(id) : undefined;
+        if (roots !== undefined && roots.size > 0) {
+          for (const root of roots) addRoot(state, id, root);
+          state.lateRenderers.push(info);
+        }
+      }
+    }
+    wrapMethod(hook, 'onScheduleFiberRoot', (a) => addRoot(state, a[0], a[1]));
+    wrapMethod(hook, 'onCommitFiberRoot', (a) => onCommit(state, a[0], a[1]));
+    hook[MARK] = state;
+    return state;
+  }
+
+  let nextID = 1;
+  const renderers = new Map<number, RendererInternals>();
+  const hook: DevToolsHook = {
+    supportsFiber: true,
+    isDisabled: false,
+    renderers,
+    inject(internals) {
+      const id = nextID++;
+      renderers.set(id, internals);
+      state.renderers.set(id, describeRenderer(id, internals));
+      return id;
+    },
+    onScheduleFiberRoot(id, root) {
+      addRoot(state, id, root);
+    },
+    onCommitFiberRoot(id, root) {
+      onCommit(state, id, root);
+    },
+    onPostCommitFiberRoot() {},
+    onCommitFiberUnmount() {},
+    setStrictMode() {},
+    checkDCE() {},
+    [MARK]: state,
+  };
+  target[HOOK_KEY] = hook;
+  return state;
+}

package/src/fiber-adapter/host.ts

@@ -0,0 +1,210 @@
+/**
+ * Renderer-specific details. These are the only three differences between Fabric and
+ * react-dom + react-native-web that the query layer needs (docs/spikes/07-web-fiber-query.md),
+ * plus style-based hiding and the viewport size.
+ */
+import type { Rect } from '@quiesco/protocol';
+
+import type { Fiber } from './fiber';
+import { isObject } from './fiber';
+import type { RendererKind, Viewport } from './types';
+
+export interface HostPlatform {
+  kind: RendererKind;
+  testID(props: Record<string, unknown>): string | undefined;
+  label(props: Record<string, unknown>): string | undefined;
+  role(props: Record<string, unknown>): string | undefined;
+  hiddenByStyle(fiber: Fiber, props: Record<string, unknown>): boolean;
+  /** Whether the host clips its descendants (scroll views, `overflow` other than `visible`). */
+  clipsContent(type: string, fiber: Fiber, props: Record<string, unknown>): boolean;
+  /** Whether the host has the input focus. */
+  isFocused(fiber: Fiber): boolean;
+  /** Focus the host (text inputs); false when it has no way to be focused. */
+  focus(fiber: Fiber): boolean;
+  /** Live text of a text input host, undefined for other hosts. */
+  inputValue(type: string, fiber: Fiber, props: Record<string, unknown>): string | undefined;
+  measure(fiber: Fiber): Rect | null;
+  /** React view tag of the native view (Fabric), for native touch injection. Null on web. */
+  nativeTag(fiber: Fiber): number | null;
+  viewport(): Viewport | null;
+}
+
+/** Lazily loaded platform modules. Injected so the adapter can be unit-tested without React Native. */
+export interface PlatformDeps {
+  /**
+   * Fabric's `getPublicInstanceFromInternalInstanceHandle`, from
+   * `react-native/Libraries/Renderer/shims/ReactFabric` (private path; docs/spikes/01 §3).
+   */
+  getPublicInstance?: () => ((fiber: Fiber) => unknown) | null;
+  /** `Dimensions.get('window')` on native; `{ innerWidth, innerHeight }` on web. */
+  viewport?: () => Viewport | null;
+  /** `window.getComputedStyle` on web. */
+  getComputedStyle?: (el: unknown) => ComputedStyleLike | null;
+  /** The focused element: `TextInput.State.currentlyFocusedInput()` on native, `document.activeElement` on web. */
+  focusedElement?: () => unknown;
+}
+
+export interface ComputedStyleLike {
+  display?: string;
+  opacity?: string;
+  overflowX?: string;
+  overflowY?: string;
+}
+
+/** Native host types that scroll (and therefore clip) their content. RN 0.88 host names. */
+const NATIVE_SCROLL_HOSTS = new Set(['RCTScrollView', 'AndroidHorizontalScrollView']);
+/** Native text input hosts (RN 0.88). TextInput passes its current text as the `text` prop. */
+const NATIVE_TEXT_INPUTS = new Set(['RCTSinglelineTextInputView', 'RCTMultilineTextInputView', 'AndroidTextInput']);
+const WEB_TEXT_INPUTS = new Set(['input', 'textarea', 'select']);
+const WEB_NON_TEXT_INPUT_TYPES = new Set(['checkbox', 'radio', 'button', 'submit', 'reset', 'image', 'file', 'range', 'color', 'hidden']);
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function toRect(r: unknown): Rect | null {
+  if (!isObject(r)) return null;
+  const { x, y, width, height } = r;
+  if (typeof x !== 'number' || typeof y !== 'number' || typeof width !== 'number' || typeof height !== 'number') return null;
+  return { x, y, width, height };
+}
+
+function callRect(el: unknown): Rect | null {
+  if (!isObject(el) || typeof el['getBoundingClientRect'] !== 'function') return null;
+  try {
+    return toRect((el['getBoundingClientRect'] as () => unknown).call(el));
+  } catch {
+    return null;
+  }
+}
+
+/** Flatten an RN style prop (object, nested arrays, falsy entries). Registered numeric styles are ignored. */
+export function flattenStyle(style: unknown): Record<string, unknown> {
+  if (Array.isArray(style)) {
+    const out: Record<string, unknown> = {};
+    for (const s of style) Object.assign(out, flattenStyle(s));
+    return out;
+  }
+  return isObject(style) ? { ...style } : {};
+}
+
+function hiddenStyle(display: unknown, opacity: unknown): boolean {
+  return display === 'none' || opacity === 0 || opacity === '0';
+}
+
+function clips(overflow: unknown): boolean {
+  return typeof overflow === 'string' && overflow !== '' && overflow !== 'visible';
+}
+
+function focusedElement(deps: PlatformDeps): unknown {
+  try {
+    return deps.focusedElement?.() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function nativePlatform(deps: PlatformDeps): HostPlatform {
+  let getPublic: ((fiber: Fiber) => unknown) | null | undefined;
+  return {
+    kind: 'native',
+    testID: (p) => str(p['testID']),
+    label: (p) => str(p['accessibilityLabel']) ?? str(p['aria-label']),
+    role: (p) => str(p['accessibilityRole']) ?? str(p['role']),
+    hiddenByStyle: (_fiber, p) => {
+      const s = flattenStyle(p['style']);
+      return hiddenStyle(s['display'], s['opacity']);
+    },
+    clipsContent: (type, _fiber, p) => NATIVE_SCROLL_HOSTS.has(type) || clips(flattenStyle(p['style'])['overflow']),
+    isFocused(fiber) {
+      const focused = focusedElement(deps);
+      return focused !== null && focused !== undefined && focused === publicInstance(fiber);
+    },
+    focus(fiber) {
+      const el = publicInstance(fiber);
+      if (!isObject(el) || typeof el['focus'] !== 'function') return false;
+      (el['focus'] as () => void).call(el);
+      return true;
+    },
+    inputValue(type, _fiber, p) {
+      if (!NATIVE_TEXT_INPUTS.has(type)) return undefined;
+      return str(p['text']) ?? str(p['value']) ?? str(p['defaultValue']) ?? '';
+    },
+    measure(fiber) {
+      return callRect(publicInstance(fiber));
+    },
+    nativeTag(fiber) {
+      const el = publicInstance(fiber);
+      const tag = isObject(el) ? el['__nativeTag'] : undefined;
+      return typeof tag === 'number' ? tag : null;
+    },
+    viewport: () => deps.viewport?.() ?? null,
+  };
+
+  function publicInstance(fiber: Fiber): unknown {
+    if (getPublic === undefined) {
+      try {
+        getPublic = deps.getPublicInstance?.() ?? null;
+      } catch {
+        getPublic = null;
+      }
+    }
+    if (getPublic === null) return null;
+    try {
+      return getPublic(fiber);
+    } catch {
+      return null;
+    }
+  }
+}
+
+export function webPlatform(deps: PlatformDeps): HostPlatform {
+  return {
+    kind: 'web',
+    // react-native-web forwards testID to the DOM element as data-testid; testID itself stays on the RNW composite.
+    testID: (p) => str(p['data-testid']) ?? str(p['testID']),
+    label: (p) => str(p['aria-label']) ?? str(p['accessibilityLabel']),
+    role: (p) => str(p['role']) ?? str(p['accessibilityRole']),
+    hiddenByStyle(fiber, p) {
+      // RNW compiles StyleSheet styles to class names, so the computed style is the reliable source.
+      const computed = deps.getComputedStyle?.(fiber.stateNode) ?? null;
+      if (computed !== null) return hiddenStyle(computed.display, computed.opacity);
+      const s = flattenStyle(p['style']);
+      return hiddenStyle(s['display'], s['opacity']);
+    },
+    clipsContent(_type, fiber, p) {
+      const computed = deps.getComputedStyle?.(fiber.stateNode) ?? null;
+      if (computed !== null) return clips(computed.overflowX) || clips(computed.overflowY);
+      return clips(flattenStyle(p['style'])['overflow']);
+    },
+    isFocused(fiber) {
+      const focused = focusedElement(deps);
+      return focused !== null && focused !== undefined && focused === fiber.stateNode;
+    },
+    focus(fiber) {
+      const el = fiber.stateNode;
+      if (!isObject(el) || typeof el['focus'] !== 'function') return false;
+      (el['focus'] as () => void).call(el);
+      // Keys act at the end of the text, like after a user tapped into the field.
+      const value = el['value'];
+      if (typeof value === 'string' && typeof el['setSelectionRange'] === 'function') {
+        try {
+          (el['setSelectionRange'] as (a: number, b: number) => void).call(el, value.length, value.length);
+        } catch {
+          // Inputs like type="email" do not support selection.
+        }
+      }
+      return true;
+    },
+    inputValue(type, fiber, p) {
+      if (!WEB_TEXT_INPUTS.has(type)) return undefined;
+      if (type === 'input' && WEB_NON_TEXT_INPUT_TYPES.has(String(p['type'] ?? ''))) return undefined;
+      const el = fiber.stateNode;
+      const live = isObject(el) ? el['value'] : undefined;
+      return str(live) ?? str(p['value']) ?? str(p['defaultValue']) ?? '';
+    },
+    measure: (fiber) => callRect(fiber.stateNode),
+    nativeTag: () => null,
+    viewport: () => deps.viewport?.() ?? null,
+  };
+}

package/src/fiber-adapter/index.ts

@@ -0,0 +1,221 @@
+/**
+ * The only module allowed to touch React internals (requirements.md §3-3, §12).
+ * Everything above it works with `HostNode` and plain strings.
+ */
+import { defaultPlatformDeps, loadScheduler } from './default-deps';
+import type { Fiber, FiberRoot } from './fiber';
+import type { HookState } from './hook';
+import { installHook } from './hook';
+import type { HostPlatform, PlatformDeps } from './host';
+import { nativePlatform, webPlatform } from './host';
+import type { SchedulerState } from './scheduler';
+import { patchScheduler } from './scheduler';
+import { buildHostTree, findFiberByType, findHostlessComposites } from './traverse';
+import type { AdapterDiagnostics, CompositeNode, HostNode, RendererKind, Viewport } from './types';
+
+export type { AdapterDiagnostics, CompositeNode, HandlerRef, HostNode, InstanceRef, PropsRef, RendererInfo, RendererKind, Viewport } from './types';
+export { flattenStyle } from './host';
+
+/** React Native's `noTimeout` / react-dom's `noTimeout`: no pending suspended-commit timeout. */
+const NO_TIMEOUT = -1;
+
+export interface FiberAdapterOptions {
+  /** Where `__REACT_DEVTOOLS_GLOBAL_HOOK__` lives. Default: `globalThis`. */
+  target?: Record<string, unknown>;
+  /** Returns the `scheduler` module object. Default: `require('scheduler')`. */
+  loadScheduler?: () => unknown;
+  platformDeps?: PlatformDeps;
+  now?: () => number;
+}
+
+/**
+ * Install the DevTools hook and patch the scheduler on `target`, before any renderer loads. Run by
+ * `src/early.ts`, which `withQuiesco()` makes Metro execute ahead of React Native's own setup.
+ * Idempotent: FiberAdapter.install() later picks up the same hook and scheduler state.
+ */
+export function installEarly(target: Record<string, unknown> = globalThis as unknown as Record<string, unknown>, load: () => unknown = loadScheduler): void {
+  installHook(target);
+  try {
+    patchScheduler(load());
+  } catch {
+    // FiberAdapter.install() reports scheduler problems.
+  }
+}
+
+export class FiberAdapter {
+  private hook: HookState | null = null;
+  private scheduler: SchedulerState | null = null;
+  private schedulerError: string | null = null;
+  private scopeType: unknown = null;
+  private readonly platforms = new Map<RendererKind, HostPlatform>();
+  private readonly now: () => number;
+
+  constructor(private readonly options: FiberAdapterOptions = {}) {
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Install the DevTools hook and patch the scheduler. Must run before the renderer module loads,
+   * i.e. from the first import of the app entry (docs/spikes/01 §1, 02 §2). Idempotent.
+   */
+  install(): void {
+    if (this.hook !== null) return;
+    this.hook = installHook(this.options.target ?? (globalThis as unknown as Record<string, unknown>));
+    try {
+      this.scheduler = patchScheduler((this.options.loadScheduler ?? loadScheduler)(), this.now);
+      if (!this.scheduler.patched) this.schedulerError = 'scheduler module has no unstable_scheduleCallback';
+    } catch (e) {
+      this.schedulerError = `cannot load scheduler: ${String(e)}`;
+    }
+  }
+
+  /**
+   * Restrict queries to the subtree of the first fiber whose component type is `componentType`
+   * (e.g. `QuiescoRoot`), excluding dev-client overlays (docs/spikes/01 §2). `null` = whole app.
+   */
+  setScope(componentType: unknown): void {
+    this.scopeType = componentType;
+  }
+
+  /** Top-level host nodes within the scope, across all roots. Built fresh on every call. */
+  getHostRoots(): HostNode[] {
+    const out: HostNode[] = [];
+    const hook = this.requireHook();
+    for (const [rendererID, roots] of hook.roots) {
+      const platform = this.platformFor(rendererID);
+      for (const root of roots) {
+        let start = root.current;
+        if (this.scopeType !== null) {
+          const scoped = findFiberByType(start, this.scopeType);
+          if (scoped === null) continue;
+          start = scoped;
+        }
+        out.push(...buildHostTree(start, platform));
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Components within the scope that render no host element and satisfy `test` (value actions on e.g.
+   * Android's DateTimePicker, which renders null and opens a system dialog).
+   */
+  findHostlessComposites(test: (c: CompositeNode) => boolean): CompositeNode[] {
+    const out: CompositeNode[] = [];
+    for (const start of this.scopedStarts()) out.push(...findHostlessComposites(start, test));
+    return out;
+  }
+
+  /** Window size of the (first) renderer in use, in the same units as `HostNode.measure()`. */
+  viewport(): Viewport | null {
+    const first = this.requireHook().roots.keys().next();
+    return first.done === true ? null : this.platformFor(first.value).viewport();
+  }
+
+  /** Detector A (docs/spikes/02): pending work recorded on FiberRoot fields. Empty = idle. */
+  pendingRootWork(): string[] {
+    const busy: string[] = [];
+    for (const root of this.allRoots()) {
+      if (root.pendingLanes !== 0) busy.push(`pendingLanes=0b${root.pendingLanes.toString(2)}`);
+      if (root.callbackNode != null) busy.push('callbackNode');
+      if (root.cancelPendingCommit != null) busy.push('cancelPendingCommit');
+      if (root.timeoutHandle !== NO_TIMEOUT && root.timeoutHandle !== undefined) busy.push(`timeoutHandle=${String(root.timeoutHandle)}`);
+    }
+    return busy;
+  }
+
+  /** Detector B (docs/spikes/02): scheduler tasks not yet finished. Empty = idle. */
+  pendingSchedulerTasks(): string[] {
+    const out: string[] = [];
+    if (this.scheduler === null) return out;
+    const t = this.now();
+    for (const task of this.scheduler.pending.values()) {
+      out.push(`task#${task.id} p${task.priority} ${t - task.since}ms${task.continued > 0 ? ` (continued ×${task.continued})` : ''}`);
+    }
+    return out;
+  }
+
+  /** Called after every commit of any root. Returns an unsubscribe function. */
+  onCommit(listener: () => void): () => void {
+    const hook = this.requireHook();
+    const l = (): void => listener();
+    hook.commitListeners.add(l);
+    return () => hook.commitListeners.delete(l);
+  }
+
+  diagnostics(): AdapterDiagnostics {
+    const hook = this.hook;
+    const problems: string[] = [];
+    const warnings: string[] = [];
+    if (hook === null) {
+      problems.push('fiber adapter not installed');
+      return { hookSource: 'none', schedulerPatched: false, renderers: [], rootCount: 0, problems, warnings };
+    }
+    const renderers = [...hook.renderers.values()];
+    if (hook.lateRenderers.length > 0) {
+      problems.push(
+        `The app rendered before @quiesco/agent was installed (${hook.lateRenderers.map((r) => r.packageName).join(', ')}); ` +
+          'work started before that is not tracked. Import @quiesco/agent on the first line of the app entry file.',
+      );
+    }
+    if (this.schedulerError !== null) problems.push(this.schedulerError);
+    for (const r of renderers) {
+      if (!r.supported) warnings.push(`untested renderer ${r.packageName}@${r.version}; queries may not work`);
+    }
+    return {
+      hookSource: hook.source,
+      schedulerPatched: this.scheduler?.patched ?? false,
+      renderers,
+      rootCount: this.allRoots().length,
+      problems,
+      warnings,
+    };
+  }
+
+  /**
+   * Call once the app has rendered (e.g. when QuiescoRoot mounts). If no renderer was injected by
+   * then, the renderer loaded before the hook existed and never saw it.
+   */
+  checkRendererSeen(): string | null {
+    const hook = this.requireHook();
+    if (hook.renderers.size > 0) return null;
+    return (
+      'No React renderer registered with the Quiesco DevTools hook: the renderer loaded before the hook existed. ' +
+      'Wrap metro.config.js with withQuiesco() from @quiesco/agent/metro (it runs the hook before React Native ' +
+      'starts) and import @quiesco/agent on the first line of the app entry file.'
+    );
+  }
+
+  private scopedStarts(): Fiber[] {
+    const out: Fiber[] = [];
+    for (const roots of this.requireHook().roots.values()) {
+      for (const root of roots) {
+        const start = this.scopeType === null ? root.current : findFiberByType(root.current, this.scopeType);
+        if (start !== null) out.push(start);
+      }
+    }
+    return out;
+  }
+
+  private allRoots(): FiberRoot[] {
+    const out: FiberRoot[] = [];
+    for (const set of this.requireHook().roots.values()) out.push(...set);
+    return out;
+  }
+
+  private platformFor(rendererID: number): HostPlatform {
+    const kind = this.hook?.renderers.get(rendererID)?.kind ?? 'native';
+    let p = this.platforms.get(kind);
+    if (p === undefined) {
+      const deps = this.options.platformDeps ?? defaultPlatformDeps;
+      p = kind === 'web' ? webPlatform(deps) : nativePlatform(deps);
+      this.platforms.set(kind, p);
+    }
+    return p;
+  }
+
+  private requireHook(): HookState {
+    if (this.hook === null) throw new Error('FiberAdapter.install() has not been called');
+    return this.hook;
+  }
+}

package/src/fiber-adapter/scheduler.ts

@@ -0,0 +1,70 @@
+/**
+ * Track pending React scheduler tasks (docs/spikes/02-react-idle.md §2, detector B).
+ *
+ * The renderer reads `unstable_scheduleCallback` / `unstable_cancelCallback` from the `scheduler`
+ * module object at its own module init, so the exports must be replaced BEFORE the renderer loads.
+ * Render work and `flushPassiveEffects` are both queued through it.
+ */
+import { isObject } from './fiber';
+
+const MARK = '__quiescoSchedulerState';
+
+export interface PendingTask {
+  id: number;
+  priority: number;
+  since: number;
+  /** Number of continuations returned so far (a continuation keeps the task pending). */
+  continued: number;
+}
+
+export interface SchedulerState {
+  patched: boolean;
+  pending: Map<unknown, PendingTask>;
+  scheduledTotal: number;
+}
+
+type Callback = (this: unknown, didTimeout: boolean) => unknown;
+type ScheduleFn = (this: unknown, priority: number, callback: Callback, options?: unknown) => unknown;
+type CancelFn = (this: unknown, task: unknown) => unknown;
+
+/** Patch a `scheduler` module object in place. Idempotent per module object. */
+export function patchScheduler(scheduler: unknown, now: () => number = Date.now): SchedulerState {
+  if (!isObject(scheduler)) return { patched: false, pending: new Map(), scheduledTotal: 0 };
+  const existing = scheduler[MARK];
+  if (isObject(existing)) return existing as unknown as SchedulerState;
+
+  const origSchedule = scheduler['unstable_scheduleCallback'] as ScheduleFn | undefined;
+  const origCancel = scheduler['unstable_cancelCallback'] as CancelFn | undefined;
+  const state: SchedulerState = { patched: false, pending: new Map(), scheduledTotal: 0 };
+  if (typeof origSchedule !== 'function' || typeof origCancel !== 'function') return state;
+
+  let nextId = 1;
+  scheduler['unstable_scheduleCallback'] = function (this: unknown, priority: number, callback: Callback, options?: unknown) {
+    const info: PendingTask = { id: nextId++, priority, since: now(), continued: 0 };
+    const wrap = (cb: Callback): Callback =>
+      function (this: unknown, didTimeout: boolean) {
+        let result: unknown;
+        try {
+          result = cb.call(this, didTimeout);
+        } finally {
+          if (typeof result !== 'function') state.pending.delete(task);
+        }
+        if (typeof result === 'function') {
+          info.continued++;
+          return wrap(result as Callback);
+        }
+        return result;
+      };
+    const task: unknown = origSchedule.call(this, priority, wrap(callback), options);
+    state.pending.set(task, info);
+    state.scheduledTotal++;
+    return task;
+  };
+  scheduler['unstable_cancelCallback'] = function (this: unknown, task: unknown) {
+    state.pending.delete(task);
+    return origCancel.call(this, task);
+  };
+  scheduler[MARK] = state;
+  state.patched = true;
+  return state;
+}