@quiesco/agent 0.0.0-stage → 0.1.1

package/src/connection/client.ts

@@ -0,0 +1,196 @@
+/**
+ * WebSocket JSON-RPC client of the agent (requirements.md §7).
+ * - On open: send `hello`; the host answers with the session id and the agent config, or closes the
+ *   socket with a 4xxx code (session / protocol mismatch, replaced by a newer connection).
+ * - Host → agent requests are dispatched to `handle` and answered with `result` or `error`.
+ * - Agent → host events are notifications; they are buffered until the handshake completes.
+ * - Reconnects with backoff after unexpected closes (Metro reload, host restart, network blip).
+ */
+import { CloseCode, JsonRpcErrorCode, PROTOCOL_VERSION } from '@quiesco/protocol';
+import type {
+  AgentConfig,
+  AgentEventName,
+  AgentEvents,
+  HostMethods,
+  JsonRpcFailure,
+  JsonRpcRequest,
+  JsonRpcSuccess,
+  ParamsOf,
+  ResultOf,
+} from '@quiesco/protocol';
+
+import { QuiescoError } from '../errors';
+import type { SocketLike } from '../platform';
+import type { Clock } from '../sync';
+import type { ConnectionParams } from './params';
+
+export type HelloInfo = Omit<ParamsOf<HostMethods['hello']>, 'sessionId' | 'protocolVersion'>;
+export type RequestHandler = (method: string, params: unknown) => Promise<unknown>;
+export type ClientState = 'idle' | 'connecting' | 'handshaking' | 'ready' | 'rejected' | 'stopped';
+
+export interface AgentClientOptions {
+  params: ConnectionParams;
+  hello: HelloInfo;
+  createSocket: (url: string) => SocketLike;
+  handle: RequestHandler;
+  onReady?: (config: AgentConfig) => void;
+  clock: Clock;
+  /** Diagnostics sink (defaults to nothing; the runtime wires it to the original console). */
+  log?: (message: string) => void;
+}
+
+const HELLO_ID = 'hello';
+const BACKOFF_MS = [250, 500, 1000, 2000];
+const MAX_BUFFERED_EVENTS = 100;
+/** Close codes after which reconnecting is pointless. */
+const FINAL_CODES: ReadonlySet<number> = new Set([CloseCode.SESSION_MISMATCH, CloseCode.PROTOCOL_MISMATCH, CloseCode.REPLACED]);
+
+type Incoming = Partial<JsonRpcRequest & JsonRpcSuccess & JsonRpcFailure>;
+
+export class AgentClient {
+  private socket: SocketLike | null = null;
+  private _state: ClientState = 'idle';
+  private attempt = 0;
+  private retryTimer: unknown = null;
+  private readonly buffer: string[] = [];
+
+  constructor(private readonly options: AgentClientOptions) {}
+
+  get state(): ClientState {
+    return this._state;
+  }
+
+  get url(): string {
+    return `ws://localhost:${this.options.params.port}`;
+  }
+
+  start(): void {
+    if (this._state !== 'idle' && this._state !== 'stopped') return;
+    this.connect();
+  }
+
+  stop(): void {
+    this._state = 'stopped';
+    if (this.retryTimer !== null) this.options.clock.clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+    const s = this.socket;
+    this.socket = null;
+    s?.close(CloseCode.NORMAL, 'agent stopped');
+  }
+
+  notify<E extends AgentEventName>(event: E, params: AgentEvents[E]): void {
+    const msg = JSON.stringify({ jsonrpc: '2.0', method: event, params });
+    if (this._state === 'ready' && this.socket !== null) {
+      this.socket.send(msg);
+      return;
+    }
+    this.buffer.push(msg);
+    if (this.buffer.length > MAX_BUFFERED_EVENTS) this.buffer.shift();
+  }
+
+  private connect(): void {
+    this._state = 'connecting';
+    let socket: SocketLike;
+    try {
+      socket = this.options.createSocket(this.url);
+    } catch (e) {
+      this.options.log?.(`cannot create WebSocket to ${this.url}: ${String(e)}`);
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    socket.onopen = () => {
+      if (this.socket !== socket) return;
+      this._state = 'handshaking';
+      const params: ParamsOf<HostMethods['hello']> = {
+        ...this.options.hello,
+        sessionId: this.options.params.session,
+        protocolVersion: PROTOCOL_VERSION,
+      };
+      socket.send(JSON.stringify({ jsonrpc: '2.0', id: HELLO_ID, method: 'hello', params }));
+    };
+    socket.onmessage = (ev) => {
+      if (this.socket === socket) this.onMessage(socket, ev.data);
+    };
+    socket.onerror = () => {
+      // onclose follows; nothing to do here.
+    };
+    socket.onclose = (ev) => {
+      if (this.socket !== socket) return;
+      this.socket = null;
+      if (this._state === 'stopped') return;
+      if (FINAL_CODES.has(ev.code)) {
+        this._state = 'rejected';
+        this.options.log?.(`host closed the connection (${ev.code}${ev.reason ? `: ${ev.reason}` : ''}); not reconnecting`);
+        return;
+      }
+      this.scheduleReconnect();
+    };
+  }
+
+  private scheduleReconnect(): void {
+    this._state = 'connecting';
+    const delay = BACKOFF_MS[Math.min(this.attempt, BACKOFF_MS.length - 1)] as number;
+    this.attempt++;
+    this.retryTimer = this.options.clock.setTimeout(() => {
+      this.retryTimer = null;
+      if (this._state !== 'stopped') this.connect();
+    }, delay);
+  }
+
+  private onMessage(socket: SocketLike, data: unknown): void {
+    let msg: Incoming;
+    try {
+      msg = JSON.parse(String(data)) as Incoming;
+    } catch {
+      this.send(socket, { jsonrpc: '2.0', id: null, error: { code: JsonRpcErrorCode.PARSE_ERROR, message: 'invalid JSON' } });
+      return;
+    }
+    if (msg.id === HELLO_ID && msg.method === undefined) {
+      this.onHelloResponse(socket, msg);
+      return;
+    }
+    if (typeof msg.method === 'string' && msg.id !== undefined) {
+      void this.onRequest(socket, msg.id, msg.method, msg.params);
+    }
+    // Notifications from the host are not used yet.
+  }
+
+  private onHelloResponse(socket: SocketLike, msg: Incoming): void {
+    if (msg.error !== undefined) {
+      this.options.log?.(`hello rejected: ${msg.error.message}`);
+      return; // the host closes the socket with a final code
+    }
+    const result = msg.result as ResultOf<HostMethods['hello']>;
+    this._state = 'ready';
+    this.attempt = 0;
+    this.options.onReady?.(result.config);
+    for (const m of this.buffer.splice(0)) socket.send(m);
+  }
+
+  private async onRequest(socket: SocketLike, id: string | number, method: string, params: unknown): Promise<void> {
+    try {
+      const result = await this.options.handle(method, params);
+      this.send(socket, { jsonrpc: '2.0', id, result: result ?? null });
+    } catch (e) {
+      this.send(socket, { jsonrpc: '2.0', id, error: toErrorObject(e) });
+    }
+  }
+
+  private send(socket: SocketLike, msg: object): void {
+    if (this.socket === socket) socket.send(JSON.stringify(msg));
+  }
+}
+
+export class MethodNotFound extends Error {
+  constructor(readonly method: string) {
+    super(`unknown method ${method}`);
+  }
+}
+
+function toErrorObject(e: unknown): JsonRpcFailure['error'] {
+  if (e instanceof QuiescoError) return e.toJSON();
+  if (e instanceof MethodNotFound) return { code: JsonRpcErrorCode.METHOD_NOT_FOUND, message: e.message };
+  const err = e instanceof Error ? e : new Error(String(e));
+  return { code: JsonRpcErrorCode.INTERNAL_ERROR, message: `agent error: ${err.message}`, data: { stack: err.stack ?? '' } };
+}

package/src/connection/params.ts

@@ -0,0 +1,63 @@
+/**
+ * Where to connect (docs/spikes/05-connection-params.md). Priority:
+ * 1. Native launch parameters (iOS process args / Android intent extras), via @quiesco/native.
+ * 2. Web: `window.__QUIESCO__` injected by Playwright's addInitScript.
+ * 3. Build-time fallback generated by withQuiesco (`EXPO_PUBLIC_QUIESCO_PORT`).
+ * 4. DEFAULT_PORT with no session (JS-only mode, single device).
+ */
+import { DEFAULT_PORT, WEB_PARAMS_GLOBAL } from '@quiesco/protocol';
+import type { JsonValue } from '@quiesco/protocol';
+
+export interface ConnectionParams {
+  port: number;
+  session: string | null;
+  source: 'native' | 'web-global' | 'build' | 'default';
+}
+
+export interface ParamSources {
+  native: { port?: string; session?: string } | null;
+  global: Record<string, unknown>;
+  build: { port: number | null; session: string | null };
+}
+
+function toPort(v: unknown): number | null {
+  const n = typeof v === 'number' ? v : typeof v === 'string' ? Number.parseInt(v, 10) : Number.NaN;
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+}
+
+export function resolveParams(src: ParamSources): ConnectionParams {
+  const nativePort = toPort(src.native?.port);
+  if (nativePort !== null) return { port: nativePort, session: src.native?.session ?? null, source: 'native' };
+
+  const web = src.global[WEB_PARAMS_GLOBAL] as { port?: unknown; session?: unknown } | undefined;
+  const webPort = toPort(web?.port);
+  if (webPort !== null) return { port: webPort, session: typeof web?.session === 'string' ? web.session : null, source: 'web-global' };
+
+  const buildPort = toPort(src.build.port);
+  if (buildPort !== null) return { port: buildPort, session: src.build.session, source: 'build' };
+
+  return { port: DEFAULT_PORT, session: null, source: 'default' };
+}
+
+/**
+ * Test launch arguments (Phase 6.5). Native: base64 of an ASCII-only JSON object (LAUNCH_PARAM_ARGS);
+ * web: the object in `window.__QUIESCO__.args`. Anything else → no arguments, with the reason.
+ */
+export function decodeLaunchArgs(
+  native: string | null | undefined,
+  global: Record<string, unknown>,
+  decodeBase64: (b64: string) => string,
+): { args: Record<string, JsonValue>; problem: string | null } {
+  const isObject = (v: unknown): v is Record<string, JsonValue> => typeof v === 'object' && v !== null && !Array.isArray(v);
+  if (typeof native === 'string' && native !== '') {
+    try {
+      const v: unknown = JSON.parse(decodeBase64(native));
+      return isObject(v) ? { args: v, problem: null } : { args: {}, problem: 'launch arguments are not a JSON object' };
+    } catch (e) {
+      return { args: {}, problem: `cannot decode launch arguments (${(e as Error).message})` };
+    }
+  }
+  const web = global[WEB_PARAMS_GLOBAL] as { args?: unknown } | undefined;
+  if (web?.args !== undefined) return isObject(web.args) ? { args: web.args, problem: null } : { args: {}, problem: 'launch arguments are not a JSON object' };
+  return { args: {}, problem: null };
+}

package/src/early.ts

@@ -0,0 +1,10 @@
+/**
+ * Earliest agent code (docs/spikes/01 §1, 02 §2): installs the React DevTools hook and the scheduler
+ * patch. React Native 0.88 loads its renderer from `setup-env`, which Metro runs before the app entry,
+ * so `withQuiesco()` (metro.cjs) puts this module first in `getModulesRunBeforeMainModule`.
+ * `install.ts` imports it too, which keeps it in the bundle (and covers setups without that hook).
+ * It must not import react-native or react.
+ */
+import { installEarly } from './fiber-adapter';
+
+installEarly();

package/src/errors.ts

@@ -0,0 +1,23 @@
+import { ErrorCode } from '@quiesco/protocol';
+import type { ErrorDataMap, ErrorName, QuiescoErrorObject } from '@quiesco/protocol';
+
+/** Error thrown inside the agent; serialized to a JSON-RPC error object by the connection layer. */
+export class QuiescoError<N extends ErrorName = ErrorName> extends Error {
+  readonly errorName: N;
+  readonly data: ErrorDataMap[N];
+
+  constructor(name: N, message: string, data: ErrorDataMap[N]) {
+    super(message);
+    this.name = 'QuiescoError';
+    this.errorName = name;
+    this.data = data;
+  }
+
+  get code(): (typeof ErrorCode)[N] {
+    return ErrorCode[this.errorName];
+  }
+
+  toJSON(): QuiescoErrorObject<N> {
+    return { code: this.code, message: this.message, data: { name: this.errorName, ...this.data } };
+  }
+}

package/src/events.ts

@@ -0,0 +1,136 @@
+/**
+ * App → host events (requirements.md §7): console output as `log`, uncaught errors as `error`
+ * (the current step fails immediately on the host).
+ * - React Native: wraps `ErrorUtils.setGlobalHandler` (fatal → `redbox`, otherwise `uncaught`).
+ * - Browsers: `error` / `unhandledrejection` window events.
+ * Both are feature-detected; nothing here branches on the platform name.
+ * Native unhandled promise rejections are only reported by RN in __DEV__ (as LogBox warnings) and are
+ * not forwarded yet.
+ */
+import type { AgentEvents, LogLevel } from '@quiesco/protocol';
+
+type Notify = <E extends keyof AgentEvents>(event: E, params: AgentEvents[E]) => void;
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const CONSOLE_METHODS: Record<string, LogLevel> = { debug: 'debug', log: 'info', info: 'info', warn: 'warn', error: 'error' };
+
+interface ErrorUtilsLike {
+  getGlobalHandler(): (error: unknown, isFatal?: boolean) => void;
+  setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
+}
+interface EventTargetLike {
+  addEventListener(type: string, listener: (ev: unknown) => void): void;
+  removeEventListener(type: string, listener: (ev: unknown) => void): void;
+}
+
+export interface EventForwarderOptions {
+  notify: Notify;
+  target?: Record<string, unknown>;
+  now?: () => number;
+}
+
+function formatArg(a: unknown): string {
+  if (typeof a === 'string') return a;
+  if (a instanceof Error) return a.stack ?? `${a.name}: ${a.message}`;
+  try {
+    return JSON.stringify(a) ?? String(a);
+  } catch {
+    return String(a);
+  }
+}
+
+function errorParts(e: unknown): { message: string; stack?: string } {
+  if (e instanceof Error) return e.stack === undefined ? { message: e.message } : { message: e.message, stack: e.stack };
+  return { message: formatArg(e) };
+}
+
+export class EventForwarder {
+  private minLevel = LEVELS.warn;
+  private readonly restores: (() => void)[] = [];
+  private readonly target: Record<string, unknown>;
+  private readonly now: () => number;
+  private forwarding = false;
+
+  constructor(private readonly options: EventForwarderOptions) {
+    this.target = options.target ?? (globalThis as unknown as Record<string, unknown>);
+    this.now = options.now ?? Date.now;
+  }
+
+  setLevel(level: LogLevel | 'off'): void {
+    this.minLevel = level === 'off' ? Number.POSITIVE_INFINITY : LEVELS[level];
+  }
+
+  install(): void {
+    if (this.restores.length > 0) return;
+    this.installConsole();
+    this.installErrorUtils();
+    this.installWindowEvents();
+  }
+
+  uninstall(): void {
+    while (this.restores.length > 0) this.restores.pop()?.();
+  }
+
+  private send: Notify = (event, params) => {
+    // Guard against recursion when sending itself logs (e.g. a failing socket warns).
+    if (this.forwarding) return;
+    this.forwarding = true;
+    try {
+      this.options.notify(event, params);
+    } catch {
+      // never break the app's console
+    } finally {
+      this.forwarding = false;
+    }
+  };
+
+  private installConsole(): void {
+    const c = this.target['console'] as Record<string, unknown> | undefined;
+    if (c === undefined) return;
+    for (const [method, level] of Object.entries(CONSOLE_METHODS)) {
+      const original = c[method];
+      if (typeof original !== 'function') continue;
+      const self = this;
+      const wrapped = function (this: unknown, ...args: unknown[]) {
+        if (LEVELS[level] >= self.minLevel) self.send('log', { level, message: args.map(formatArg).join(' '), timestamp: self.now() });
+        return (original as (...a: unknown[]) => unknown).apply(this, args);
+      };
+      c[method] = wrapped;
+      this.restores.push(() => {
+        if (c[method] === wrapped) c[method] = original;
+      });
+    }
+  }
+
+  private installErrorUtils(): void {
+    const eu = this.target['ErrorUtils'] as ErrorUtilsLike | undefined;
+    if (eu === undefined || typeof eu.setGlobalHandler !== 'function') return;
+    const previous = eu.getGlobalHandler();
+    const handler = (error: unknown, isFatal?: boolean): void => {
+      this.send('error', { kind: isFatal === true ? 'redbox' : 'uncaught', ...errorParts(error), timestamp: this.now() });
+      previous(error, isFatal);
+    };
+    eu.setGlobalHandler(handler);
+    this.restores.push(() => {
+      if (eu.getGlobalHandler() === handler) eu.setGlobalHandler(previous);
+    });
+  }
+
+  private installWindowEvents(): void {
+    const w = this.target['window'] as EventTargetLike | undefined;
+    if (w === undefined || typeof w.addEventListener !== 'function') return;
+    const onError = (ev: unknown): void => {
+      const e = ev as { error?: unknown; message?: string };
+      this.send('error', { kind: 'uncaught', ...errorParts(e.error ?? e.message), timestamp: this.now() });
+    };
+    const onRejection = (ev: unknown): void => {
+      this.send('error', { kind: 'unhandledRejection', ...errorParts((ev as { reason?: unknown }).reason), timestamp: this.now() });
+    };
+    w.addEventListener('error', onError);
+    w.addEventListener('unhandledrejection', onRejection);
+    this.restores.push(() => {
+      w.removeEventListener('error', onError);
+      w.removeEventListener('unhandledrejection', onRejection);
+    });
+  }
+}

package/src/expo-fetch.js

@@ -0,0 +1,13 @@
+// `expo/fetch` as the app sees it in e2e builds (Phase 6.10). withQuiesco() (metro.cjs) resolves the
+// app's and libraries' `expo/fetch` imports here; this module's own import goes to the real one. The
+// real module's exports are non-configurable getters, so they cannot be patched at runtime.
+//
+// The exported `fetch` is tracked like the global one (busy until the response and its body are read)
+// and honors the simulated offline mode. Everything else is re-exported unchanged.
+import { fetch as expoFetch } from 'expo/fetch';
+
+import { getRuntime } from './singleton';
+
+export * from 'expo/fetch';
+
+export const fetch = getRuntime().wrapFetch(expoFetch);

package/src/fiber-adapter/default-deps.native.ts

@@ -0,0 +1,36 @@
+/**
+ * Platform modules for iOS / Android (Metro picks this file over default-deps.ts for native platforms).
+ * Everything is loaded lazily: requiring the renderer shim at agent install time would load the
+ * renderer BEFORE the DevTools hook and scheduler patch are in place.
+ */
+import type { PlatformDeps } from './host';
+import type { Fiber } from './fiber';
+import type { Viewport } from './types';
+
+declare const require: (id: string) => unknown;
+
+interface FabricShim {
+  getPublicInstanceFromInternalInstanceHandle?: (fiber: Fiber) => unknown;
+}
+
+export const defaultPlatformDeps: PlatformDeps = {
+  getPublicInstance() {
+    // Private RN path (docs/spikes/01 §3). RN 0.88 warns about deep imports; isolated here on purpose.
+    const mod = require('react-native/Libraries/Renderer/shims/ReactFabric') as { default?: FabricShim } & FabricShim;
+    const shim = mod.default ?? mod;
+    return shim.getPublicInstanceFromInternalInstanceHandle ?? null;
+  },
+  focusedElement() {
+    const rn = require('react-native') as { TextInput?: { State?: { currentlyFocusedInput?: () => unknown } } };
+    return rn.TextInput?.State?.currentlyFocusedInput?.() ?? null;
+  },
+  viewport() {
+    const rn = require('react-native') as { Dimensions: { get(dim: 'window'): Viewport } };
+    const { width, height } = rn.Dimensions.get('window');
+    return { width, height };
+  },
+};
+
+export function loadScheduler(): unknown {
+  return require('scheduler');
+}

package/src/fiber-adapter/default-deps.ts

@@ -0,0 +1,38 @@
+/**
+ * Platform modules for web (react-dom + react-native-web). Metro uses default-deps.native.ts on iOS / Android.
+ */
+import type { PlatformDeps } from './host';
+
+declare const require: (id: string) => unknown;
+
+interface WindowLike {
+  innerWidth: number;
+  innerHeight: number;
+  getComputedStyle(el: Element): CSSStyleDeclaration;
+}
+
+function win(): WindowLike | null {
+  const w = (globalThis as { window?: WindowLike }).window;
+  return w !== undefined && typeof w.getComputedStyle === 'function' ? w : null;
+}
+
+export const defaultPlatformDeps: PlatformDeps = {
+  viewport() {
+    const w = win();
+    return w === null ? null : { width: w.innerWidth, height: w.innerHeight };
+  },
+  focusedElement() {
+    const doc = (globalThis as { document?: { activeElement?: unknown } }).document;
+    return doc?.activeElement ?? null;
+  },
+  getComputedStyle(el) {
+    const w = win();
+    if (w === null || typeof Element === 'undefined' || !(el instanceof Element)) return null;
+    const s = w.getComputedStyle(el);
+    return { display: s.display, opacity: s.opacity, overflowX: s.overflowX, overflowY: s.overflowY };
+  },
+};
+
+export function loadScheduler(): unknown {
+  return require('scheduler');
+}

package/src/fiber-adapter/fiber.ts

@@ -0,0 +1,81 @@
+/**
+ * Minimal shapes of React's internal objects. Private to fiber-adapter.
+ * Field names follow React 19 (ReactInternalTypes.js / ReactFiberRoot.js); verified on React 19.3.0
+ * with react-native-renderer (Fabric) and react-dom (docs/spikes/01, 02, 07).
+ */
+
+/** WorkTag values from ReactWorkTags.js. */
+export const WorkTag = {
+  FunctionComponent: 0,
+  ClassComponent: 1,
+  HostRoot: 3,
+  HostPortal: 4,
+  HostComponent: 5,
+  HostText: 6,
+  ForwardRef: 11,
+  MemoComponent: 14,
+  SimpleMemoComponent: 15,
+  /** react-dom only: <title>, <link>, ... hoisted into <head>. Not queryable; children are walked. */
+  HostHoistable: 26,
+  /** react-dom only: <html>, <head>, <body>. Not queryable; children are walked. */
+  HostSingleton: 27,
+} as const;
+
+export interface Fiber {
+  tag: number;
+  type: unknown;
+  key: string | null;
+  memoizedProps: unknown;
+  stateNode: unknown;
+  child: Fiber | null;
+  sibling: Fiber | null;
+  return: Fiber | null;
+}
+
+export interface FiberRoot {
+  current: Fiber;
+  pendingLanes: number;
+  callbackNode: unknown;
+  cancelPendingCommit: unknown;
+  timeoutHandle: unknown;
+}
+
+/** Object passed by a renderer to `hook.inject()`. */
+export interface RendererInternals {
+  bundleType?: number;
+  version?: string;
+  rendererPackageName?: string;
+  reconcilerVersion?: string;
+}
+
+/** The subset of `__REACT_DEVTOOLS_GLOBAL_HOOK__` that renderers call. */
+export interface DevToolsHook {
+  supportsFiber?: boolean;
+  isDisabled?: boolean;
+  renderers?: Map<number, RendererInternals>;
+  inject: (internals: RendererInternals) => number;
+  onScheduleFiberRoot?: (rendererID: number, root: FiberRoot, children: unknown) => void;
+  onCommitFiberRoot?: (rendererID: number, root: FiberRoot, priority: unknown, didError: unknown) => void;
+  onPostCommitFiberRoot?: (rendererID: number, root: FiberRoot) => void;
+  onCommitFiberUnmount?: (rendererID: number, fiber: Fiber) => void;
+  /** react-devtools-core: the roots it has seen for a renderer. */
+  getFiberRoots?: (rendererID: number) => Set<FiberRoot>;
+  [key: string]: unknown;
+}
+
+export function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/** Depth-first walk over `fiber` and its siblings (pre-order). Iterative: fiber trees can be deep. */
+export function* walkSiblings(fiber: Fiber | null): Generator<Fiber> {
+  const stack: Fiber[] = [];
+  let node = fiber;
+  while (node !== null || stack.length > 0) {
+    if (node === null) node = stack.pop() ?? null;
+    if (node === null) break;
+    yield node;
+    if (node.sibling !== null) stack.push(node.sibling);
+    node = node.child;
+  }
+}