@specific.dev/spectest 0.67.0 → 0.69.0

package/src/harness/wrapper-rules.ts

@@ -0,0 +1,547 @@
+// Blocking typecheck rules: control flow that a provenance wrapper makes
+// constant.
+//
+// `sdk/src/inspect.ts` returns every primitive leaf of a recorded op as a
+// `Carrier` — an object holding the value, with coercion sinks so template
+// interpolation, arithmetic, `==` and `JSON.stringify` all behave. Two things
+// a carrier cannot rescue, because JavaScript exposes no hook for either:
+//
+//   if (row.written)      // an object is ALWAYS truthy, even around `false`
+//   measured.rows === 2   // an object is NEVER === a primitive
+//
+// Both are constant, and both are silent. The first is the more expensive: a
+// `ctx.poll` predicate that collapses a wrapped `false` to `true` reports
+// success on attempt 1 and the suite runs on against data that never arrived
+// (reported 2026-08-30). `tsc` catches the second as TS2367 and says nothing
+// about the first — a truthiness test on an object type is legal TypeScript.
+//
+// WHY THESE MAY BLOCK A RUN WHEN `tsc`'s OWN DIAGNOSTICS MAY NOT
+// ---------------------------------------------------------------
+// The typecheck report is advisory because a `tsc` verdict is about the
+// DECLARED TYPES, and those can disagree with the program that actually runs,
+// in both directions:
+//
+//   - the types go stale: the global `fetch` is patched at runtime to record
+//     but keeps its raw `Response` type, so correct code is flagged;
+//   - narrowing is unsound: TypeScript does not reset a narrowed `let` across
+//     a callback, so `phase === "end"` after `[1,2].forEach(() => phase = "end")`
+//     is reported as having no overlap when at runtime it matches.
+//
+// The second is why TS2367 cannot gate a run even though it is exactly the
+// diagnostic that would have caught the reported bug.
+//
+// These rules ask a different question — *is this value a `Carrier`* — which
+// is a fact about the runtime representation, not an inference. Wrapping is
+// unconditional (see inspect.ts), so a value typed `Carrier<T>` IS an object
+// when the line executes. Narrowing cannot turn a carrier into a number, so
+// there is no unsoundness to inherit.
+//
+// {@link CODE_EQUALITY} is true of the run outright. {@link CODE_TRUTHY} is a
+// convention on top of it — read its note for why that still earns a gate, and
+// for the line neither rule crosses.
+//
+// SOUNDNESS CONDITIONS, both load-bearing:
+//
+//   1. `strictNullChecks` must be on. With it off, an optional leaf
+//      (`row.opt?: Carrier<string>`) reports as `Carrier<string>` rather than
+//      `Carrier<string> | undefined`, and `if (row.opt)` — a legitimate
+//      presence test, since `wrapChild` returns nullish RAW — would be flagged
+//      as a bug. The driver refuses to run rather than guess.
+//   2. A union carrying `null`/`undefined` is never flagged, for the same
+//      reason: that condition distinguishes present from absent and is correct.
+//
+// The type is identified from its printed form rather than from its symbol:
+// one round trip instead of several, and the whole decision stays a pure
+// function over a string, which is what the tests below drive. A user type
+// that happens to be called `Carrier<T>` would also be flagged — and would
+// also be an object at runtime, so the finding stays true.
+
+/** A finding, shaped like the `TypecheckError` the report already carries. */
+export interface WrapperDiagnostic {
+  /** Path relative to the app dir, matching the advisory diagnostics. */
+  file: string;
+  line: number;
+  column: number;
+  code: string;
+  message: string;
+  /**
+   * Whether this finding may fail the run. Only a rule that is true of the
+   * RUN, not merely of the declared types, may block — see the header and the
+   * note on {@link CODE_TRUTHY}.
+   */
+  blocking: boolean;
+}
+
+/**
+ * A condition on a wrapped value — always true. **Blocking**, but on different
+ * grounds from {@link CODE_EQUALITY}, and the difference is worth knowing.
+ *
+ * This rule is NOT a proof. Two things can hide a runtime nullish from the
+ * compiler: a row generic that overstates a column
+ * (`client<{ names: string }>` over a `string_agg` that returns NULL) and
+ * TypeScript's deliberately unsound array indexing (`rows[0]` is typed
+ * non-optional even when the array is empty). A nullish leaf comes back RAW
+ * from `wrapChild`, so in those shapes `if (rows[0]?.names)` really does tell
+ * present from absent, and "always true" is false about it — measured against
+ * a real suite on 2026-08-30 (`journal-note.ts:200`).
+ *
+ * It blocks anyway, as a CONVENTION rather than a verdict: *unwrap before
+ * branching on a wrapped value*, the same discipline the docs already teach
+ * for `===`. What makes that acceptable is that the fix is safe in every case
+ * — `?.unwrap()` short-circuits, so it never throws and never changes code
+ * that was already correct; it only removes the accident. And the accident is
+ * the worst failure this SDK has: a `ctx.poll` predicate that collapses a
+ * wrapped `false` to `true` passes on attempt 1, the suite runs on against
+ * data that never arrived, and neither the compiler nor the runtime says a
+ * word (reported 2026-08-30).
+ *
+ * The line this does not cross: a rule may demand more of the user's own code,
+ * but it may never fail a run over OUR stale types (the patched global
+ * `fetch`) or over the compiler's own bad inference (TS2367 across a
+ * callback). Those cost the user a fix they cannot make.
+ */
+export const CODE_TRUTHY = "SPECTEST2001";
+/**
+ * `===`/`!==` between a wrapped value and a plain one — always false/true.
+ * **Blocking.** Sound even when a row generic understates nullability: if the
+ * leaf is a carrier the comparison is false because an object never equals a
+ * primitive, and if it is raw nullish it is false because nullish does not
+ * equal the literal either. A nullish literal on the other side is excluded —
+ * see {@link equalityIsConstant}.
+ */
+export const CODE_EQUALITY = "SPECTEST2002";
+
+/**
+ * Split a printed type on its TOP-LEVEL `|`, leaving nested unions alone
+ * (`Carrier<A | B> | undefined` → [`Carrier<A | B>`, `undefined`]). Depth is
+ * tracked across every bracket kind because a printed type can hold object
+ * literals (`{ a: 1 | 2 }`), tuples and parenthesised function types.
+ */
+export function splitUnion(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (c === "<" || c === "(" || c === "[" || c === "{") depth += 1;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth -= 1;
+    else if (c === "|" && depth === 0) {
+      parts.push(text.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start).trim());
+  return parts.filter((p) => p.length > 0);
+}
+
+/** One union member that is the primitive carrier. Object/array/response
+ *  wrappers are deliberately NOT included: they are objects whether or not we
+ *  wrap them, so a condition on one is not made constant by the wrapper. */
+export function isCarrierMember(member: string): boolean {
+  return /^Carrier<[\s\S]*>$/.test(member.trim());
+}
+
+export type TypeVerdict =
+  /** Every member is a carrier and none is nullish — constant at runtime. */
+  | "carrier"
+  /** A carrier that may also be absent — a real presence test, leave alone. */
+  | "nullable-carrier"
+  /** Not a wrapper. */
+  | "plain";
+
+/**
+ * Classify a printed type for the rules. `unknown`/`any`/an error type read as
+ * `plain`: the checker could not say what the value is, and a rule that blocks
+ * a run must not guess.
+ */
+export function classifyType(text: string | undefined): TypeVerdict {
+  if (!text) return "plain";
+  const members = splitUnion(text);
+  const nullish = members.filter((m) => m === "null" || m === "undefined");
+  const rest = members.filter((m) => m !== "null" && m !== "undefined");
+  if (rest.length === 0) return "plain";
+  // A union mixing a carrier with a non-nullish plain type is not a shape the
+  // SDK produces. Blocking a run needs certainty, so an unrecognised shape
+  // reads as plain rather than as a finding.
+  if (!rest.every((m) => isCarrierMember(m))) return "plain";
+  return nullish.length > 0 ? "nullable-carrier" : "carrier";
+}
+
+/** Source text that denotes a nullish literal. */
+export function isNullishLiteral(exprText: string): boolean {
+  const t = exprText.trim();
+  return t === "null" || t === "undefined" || /^void\s+0$/.test(t);
+}
+
+/**
+ * Verdict for a strict `===`/`!==`. Blocking only when exactly one side is a
+ * definite carrier: two carriers compare object identity, which is a different
+ * mistake and not one this rule can prove constant.
+ *
+ * A comparison against a NULLISH LITERAL is never constant, whatever the type
+ * says. `wrapChild` hands a `null`/`undefined` leaf back RAW, so
+ * `row.setting === null` is the correct way to ask whether a column is null —
+ * and it answers correctly in both directions. The declared type cannot show
+ * this, because a row generic is the caller's own assertion
+ * (`client<{ setting: unknown }>`) and routinely understates nullability.
+ * Found in a real suite on 2026-08-30 (`document-export-settings.ts:64`),
+ * where flagging it would have blocked a passing test.
+ */
+export function equalityIsConstant(
+  left: string | undefined,
+  right: string | undefined,
+  leftExpr = "",
+  rightExpr = "",
+): boolean {
+  if (isNullishLiteral(leftExpr) || isNullishLiteral(rightExpr)) return false;
+  const l = classifyType(left);
+  const r = classifyType(right);
+  return (l === "carrier") !== (r === "carrier");
+}
+
+/**
+ * The real start of a node. A TypeScript node's `pos` is the end of the
+ * PREVIOUS node, so it includes the leading whitespace and comments; `tsc`
+ * reports the first meaningful character. Without this every column is a few
+ * places to the left and a finding above a comment points at the comment.
+ */
+export function startOfNode(text: string, pos: number): number {
+  let i = Math.max(0, Math.min(pos, text.length));
+  while (i < text.length) {
+    const c = text[i];
+    if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+      i += 1;
+    } else if (c === "/" && text[i + 1] === "/") {
+      const nl = text.indexOf("\n", i);
+      i = nl === -1 ? text.length : nl + 1;
+    } else if (c === "/" && text[i + 1] === "*") {
+      const close = text.indexOf("*/", i + 2);
+      i = close === -1 ? text.length : close + 2;
+    } else {
+      break;
+    }
+  }
+  return i;
+}
+
+/** 1-indexed line/column for a character offset, matching `tsc` output. */
+export function lineColumnAt(text: string, pos: number): { line: number; column: number } {
+  const clamped = Math.max(0, Math.min(pos, text.length));
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < clamped; i += 1) {
+    if (text.charCodeAt(i) === 10) {
+      line += 1;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: clamped - lineStart + 1 };
+}
+
+/** Trim a source snippet for a message: one line, bounded. */
+export function snippet(text: string, pos: number, end: number): string {
+  const raw = text.slice(Math.max(0, pos), Math.max(0, end)).trim();
+  const oneLine = raw.split("\n")[0]?.trim() ?? "";
+  return oneLine.length > 60 ? `${oneLine.slice(0, 57)}…` : oneLine;
+}
+
+export function truthyMessage(expr: string, typeText: string): string {
+  const subject = expr ? `\`${expr}\`` : "This value";
+  return (
+    `${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+    `runtime, so this condition is always true. A wrapped \`false\`, \`0\` or ` +
+    `\`""\` reads as truthy. Call \`.unwrap()\` before testing it.`
+  );
+}
+
+export function equalityMessage(expr: string, typeText: string, negated: boolean): string {
+  const subject = expr ? `\`${expr}\`` : "This value";
+  const verdict = negated ? "always true" : "always false";
+  return (
+    `${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+    `runtime and can never be strictly equal to a plain value, so this ` +
+    `comparison is ${verdict}. Call \`.unwrap()\` first, or assert with ` +
+    `\`expect(...)\`, which unwraps for you.`
+  );
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Driver
+//
+// Runs against the BAKED TypeScript, never the project's own. The advisory
+// pass deliberately prefers an app-local `typescript` (the project's choice of
+// compiler is its own), but the gate cannot: 7 of the 12 projects measured on
+// 2026-08-30 pin TypeScript 5.x, which has no checker API at all, so keying
+// the rules off the project's compiler would silently switch the gate off for
+// exactly the projects most likely to need it — including the one that
+// reported the bug. The baked compiler is ours and is always present.
+//
+// Everything here is best-effort. The API is `typescript/unstable/*` and can
+// break on a version bump; a throw, a timeout or a missing install yields
+// `skipped`/`failed` and NO diagnostics, so a run proceeds exactly as it does
+// today. Only a definite finding can block, which is what makes an unstable
+// dependency acceptable underneath a gate.
+// ───────────────────────────────────────────────────────────────────────────
+
+/** Minimal shape of the bits of the TS 7 API this uses. */
+interface TsNode {
+  kind: number;
+  pos: number;
+  end: number;
+  [k: string]: unknown;
+}
+interface TsType {
+  flags: number;
+}
+interface TsProject {
+  compilerOptions: Record<string, unknown>;
+  program: {
+    getSourceFileNames(): Promise<readonly string[]> | readonly string[];
+    getSourceFile(f: string): Promise<{ statements: TsNode[] } | undefined>;
+  };
+  checker: {
+    getTypeAtLocation(nodes: readonly TsNode[]): Promise<(TsType | undefined)[]>;
+    typeToString(t: TsType): Promise<string>;
+  };
+}
+
+export interface WrapperRuleRun {
+  status: "ok" | "skipped" | "failed";
+  diagnostics: WrapperDiagnostic[];
+  detail?: string;
+  durationMs: number;
+}
+
+/** `TypeFlags.Object | TypeFlags.Union` — the only shapes a carrier can wear.
+ *  Filtering on the flags the batch call already returned keeps the printed
+ *  name (one round trip each) off every ordinary `boolean` condition. */
+const OBJECT_OR_UNION = (1 << 19) | (1 << 20);
+
+/** Candidate positions, and what each one means if the operand is a carrier. */
+interface Candidate {
+  node: TsNode;
+  kind: "truthy" | "equality";
+  /** For an equality, the other side, whose type decides with this one. */
+  other?: TsNode;
+  negated?: boolean;
+}
+
+const SYNTAX = {
+  If: "IfStatement",
+  While: "WhileStatement",
+  DoWhile: "DoStatement",
+  For: "ForStatement",
+  Conditional: "ConditionalExpression",
+  Prefix: "PrefixUnaryExpression",
+  Binary: "BinaryExpression",
+} as const;
+
+/**
+ * Collect the positions worth asking about in one file. Kept separate from the
+ * checker so the walk can be reasoned about (and extended) on its own.
+ */
+export function collectCandidates(
+  statements: readonly TsNode[],
+  kindName: (n: TsNode) => string,
+  walk: (n: TsNode, visit: (c: TsNode) => void) => void,
+): Candidate[] {
+  const all: TsNode[] = [];
+  const push = (n: TsNode): void => {
+    all.push(n);
+    walk(n, push);
+  };
+  for (const s of statements) push(s);
+
+  const out: Candidate[] = [];
+  for (const n of all) {
+    const k = kindName(n);
+    if (k === SYNTAX.If || k === SYNTAX.While || k === SYNTAX.DoWhile) {
+      const e = n.expression as TsNode | undefined;
+      if (e) out.push({ node: e, kind: "truthy" });
+    } else if (k === SYNTAX.For || k === SYNTAX.Conditional) {
+      const e = n.condition as TsNode | undefined;
+      if (e) out.push({ node: e, kind: "truthy" });
+    } else if (k === SYNTAX.Prefix) {
+      // `!x` — TypeScript's own always-truthy check misses this shape, which
+      // is why the rule cannot lean on TS2774.
+      if (kindName({ kind: n.operator as number } as TsNode) === "ExclamationToken") {
+        const e = n.operand as TsNode | undefined;
+        if (e) out.push({ node: e, kind: "truthy" });
+      }
+    } else if (k === SYNTAX.Binary) {
+      const op = kindName({ kind: (n.operatorToken as TsNode)?.kind } as TsNode);
+      const left = n.left as TsNode | undefined;
+      const right = n.right as TsNode | undefined;
+      if (!left || !right) continue;
+      if (op === "AmpersandAmpersandToken" || op === "BarBarToken") {
+        out.push({ node: left, kind: "truthy" });
+      } else if (op === "EqualsEqualsEqualsToken") {
+        out.push({ node: left, kind: "equality", other: right, negated: false });
+      } else if (op === "ExclamationEqualsEqualsToken") {
+        out.push({ node: left, kind: "equality", other: right, negated: true });
+      }
+    }
+  }
+  return out;
+}
+
+export async function runWrapperRules(opts: {
+  /** Directory of the baked `typescript` package. */
+  typescriptDir: string;
+  /** Absolute path of the tsconfig to open. */
+  configFile: string;
+  /** Only files under here produce diagnostics. */
+  appDir: string;
+  readFile: (p: string) => Promise<string>;
+  relative: (from: string, to: string) => string;
+  join: (...parts: string[]) => string;
+  dirname: (p: string) => string;
+}): Promise<WrapperRuleRun> {
+  const started = Date.now();
+  const done = (r: Omit<WrapperRuleRun, "durationMs">): WrapperRuleRun => ({
+    ...r,
+    durationMs: Date.now() - started,
+  });
+
+  let api: { close(): void } | undefined;
+  try {
+    const base = opts.join(opts.typescriptDir, "dist");
+    const apiMod = (await import(opts.join(base, "api", "async", "api.js"))) as {
+      API: new (o: { cwd: string }) => {
+        close(): void;
+        updateSnapshot(p: {
+          openProjects: string[];
+        }): Promise<{ getProjects(): Promise<readonly TsProject[]> }>;
+      };
+    };
+    const utils = (await import(opts.join(base, "ast", "utils.js"))) as {
+      formatSyntaxKind(k: number): string;
+    };
+    const visitor = (await import(opts.join(base, "ast", "visitor.js"))) as {
+      visitEachChild(n: unknown, cb: (c: unknown) => unknown, ctx: unknown): unknown;
+    };
+
+    const inst = new apiMod.API({ cwd: opts.dirname(opts.configFile) });
+    api = inst;
+    const snapshot = await inst.updateSnapshot({ openProjects: [opts.configFile] });
+    const project = (await snapshot.getProjects())[0];
+    if (!project) return done({ status: "failed", diagnostics: [], detail: "no project" });
+
+    // Soundness condition 1 — see the header. Without strictNullChecks an
+    // optional carrier loses its `| undefined` and every presence test in the
+    // suite becomes a finding, so refuse rather than guess.
+    // `compilerOptions` is the file's raw options, not the resolved ones, so
+    // the `strict` family has to be folded by hand: an explicit
+    // `strictNullChecks` wins, otherwise `strict` supplies it.
+    const strictNullChecks =
+      (project.compilerOptions.strictNullChecks as boolean | undefined) ??
+      (project.compilerOptions.strict as boolean | undefined) ??
+      false;
+    if (strictNullChecks !== true) {
+      return done({
+        status: "skipped",
+        diagnostics: [],
+        detail:
+          "strictNullChecks is off; a wrapped optional cannot be told from a wrapped value",
+      });
+    }
+
+    const kindName = (n: TsNode): string =>
+      typeof n?.kind === "number" ? utils.formatSyntaxKind(n.kind) : "";
+    const walk = (n: TsNode, visit: (c: TsNode) => void): void => {
+      try {
+        visitor.visitEachChild(
+          n,
+          (c) => {
+            visit(c as TsNode);
+            return c;
+          },
+          undefined,
+        );
+      } catch {
+        /* a node shape the walker cannot descend — its children are skipped */
+      }
+    };
+
+    const names = await project.program.getSourceFileNames();
+    const files = names.filter(
+      (f) =>
+        f.startsWith(`${opts.appDir}/`) && !f.includes("/node_modules/") && !f.endsWith(".d.ts"),
+    );
+
+    const diagnostics: WrapperDiagnostic[] = [];
+    for (const file of files) {
+      const sf = await project.program.getSourceFile(file);
+      if (!sf) continue;
+      const candidates = collectCandidates(sf.statements, kindName, walk);
+      if (candidates.length === 0) continue;
+
+      // One batched checker call per file, then a printed name only for the
+      // types that could be a wrapper at all.
+      const nodes = candidates.flatMap((c) => (c.other ? [c.node, c.other] : [c.node]));
+      const types = await project.checker.getTypeAtLocation(nodes);
+      const printed = new Map<number, string>();
+      for (let i = 0; i < nodes.length; i += 1) {
+        const t = types[i];
+        if (t && (t.flags & OBJECT_OR_UNION) !== 0) {
+          printed.set(i, await project.checker.typeToString(t));
+        }
+      }
+
+      const text = await opts.readFile(file);
+      const rel = opts.relative(opts.appDir, file);
+      let idx = 0;
+      for (const c of candidates) {
+        const leftText = printed.get(idx);
+        idx += 1;
+        const rightText = c.other ? printed.get(idx) : undefined;
+        if (c.other) idx += 1;
+
+        const start = startOfNode(text, c.node.pos);
+        const where = lineColumnAt(text, start);
+        const expr = snippet(text, start, c.node.end);
+        if (c.kind === "truthy") {
+          if (classifyType(leftText) !== "carrier") continue;
+          diagnostics.push({
+            file: rel,
+            ...where,
+            code: CODE_TRUTHY,
+            message: truthyMessage(expr, leftText as string),
+            blocking: true,
+          });
+          continue;
+        }
+        const otherStart = startOfNode(text, (c.other as TsNode).pos);
+        const otherExpr = snippet(text, otherStart, (c.other as TsNode).end);
+        if (!equalityIsConstant(leftText, rightText, expr, otherExpr)) continue;
+        const carrierIsLeft = classifyType(leftText) === "carrier";
+        const node = carrierIsLeft ? c.node : (c.other as TsNode);
+        const at = carrierIsLeft ? start : otherStart;
+        diagnostics.push({
+          file: rel,
+          ...lineColumnAt(text, at),
+          code: CODE_EQUALITY,
+          message: equalityMessage(
+            snippet(text, at, node.end),
+            (carrierIsLeft ? leftText : rightText) as string,
+            c.negated === true,
+          ),
+          blocking: true,
+        });
+      }
+    }
+    return done({ status: "ok", diagnostics });
+  } catch (err) {
+    return done({
+      status: "failed",
+      diagnostics: [],
+      detail: (err as Error)?.message ?? String(err),
+    });
+  } finally {
+    try {
+      api?.close();
+    } catch {
+      /* the session is already gone */
+    }
+  }
+}

package/src/index.ts

@@ -2900,7 +2900,7 @@ function buildLocatorMatchers(
     // The last error a probe threw, kept for the failure message: a matcher
     // whose read waits for the element (textContent, inputValue, isEnabled …)
     // reports a missing element as a playwright timeout, and that — not
-    // "got <error: Timeout 5000ms exceeded …>" — is the sentence to fail with.
+    // "got <error: Timeout 10000ms exceeded …>" — is the sentence to fail with.
     let probeError: unknown;
     for (;;) {
       let satisfied: boolean;
@@ -2939,8 +2939,8 @@ function buildLocatorMatchers(
       }
       if (Date.now() >= deadline) {
         // The deadline, not the stopwatch: every one of these polled until it
-        // ran out, and "(waited 5s)" is both what the author set and the same
-        // number twice in a row — a measured 4_987ms is neither.
+        // ran out, and "(waited 10s)" is both what the author set and the same
+        // number twice in a row — a measured 9_987ms is neither.
         const msg = (await elementFailure(probeError)) ??
           `${describe(actual)} (waited ${formatWaited(budget)})`;
         const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);

package/src/locator-errors.ts

@@ -1,7 +1,7 @@
 // Readable failures for locator steps.
 //
 // Playwright reports every unmet actionability wait the same way: a
-// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// `TimeoutError` whose message is "Timeout 10000ms exceeded." with the real
 // story — did the element exist at all? was it disabled? did something cover
 // it? — buried in a call log below it. A test that clicks a button that is not
 // on the page therefore fails with a sentence about OUR deadline, which reads

package/src/locator.ts

@@ -32,11 +32,16 @@ import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 
 /** Default deadline for a locator action/read's target to become actionable.
- *  Playwright's own default is 30s — far too slow-failing for tests; 5s
- *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
- *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
-export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+ *  Playwright's own default is 30s — far too slow-failing for tests. This was
+ *  5s (the pre-Playwright behavior) until 2026-09-03, and 5s turned out to be
+ *  about one page load: a real app under a full VM fan-out took 1.8-2.0s for a
+ *  full navigation plus its client data chain on a quiet box, and 4x that on
+ *  the tail, so a step that was correct and merely late failed. 10s still
+ *  fails fast enough to be useful and leaves room for the tail. A per-call
+ *  `{ timeout }` overrides it; `undefined` falls through to the context
+ *  default (also set to this in browser.ts's `newViewContext`). Navigations
+ *  keep a longer deadline. */
+export const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 
 // Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
 // them (locators are never serialized) while runtime code can still detect a
@@ -656,7 +661,7 @@ export interface Locator {
   /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
   nth(index: number): Locator;
 
-  // ── Actions (auto-wait; default 5s, `{ timeout }` overrides) ──────────
+  // ── Actions (auto-wait; default 10s, `{ timeout }` overrides) ─────────
   click(opts?: ClickOptions): Promise<void>;
   dblclick(opts?: ClickOptions): Promise<void>;
   /** Touch-tap (mobile sessions only; throws on desktop). `duration`
@@ -761,7 +766,7 @@ export function makeLocator(
   };
 
   // Every terminal op runs through this: playwright's actionability timeouts
-  // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+  // say "Timeout 10000ms exceeded" and hide what actually went wrong in a call
   // log, so they are rewritten into a sentence naming the element and its
   // state (see locator-errors.ts), and a failure that found NO element asks
   // the page what it does hold. Applied INSIDE `pageOp`, so the recorded step

package/src/terminal.ts

@@ -32,6 +32,9 @@ import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
 import type { EventReservation } from "./recorder.js";
 import type { TerminalStepAction } from "./recorder.js";
 import { wrap } from "./inspect.js";
+// One default deadline for "wait until the app shows it", whichever surface
+// the author is watching — see the constant for why it is what it is.
+import { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
 import type { Wrapped } from "./inspect.js";
 
 export interface TerminalOpts {
@@ -614,7 +617,7 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
       matcher: string | RegExp | ((screen: string, output: string) => unknown),
       waitOpts?: { timeoutMs?: number; intervalMs?: number },
     ) {
-      const timeoutMs = waitOpts?.timeoutMs ?? 5_000;
+      const timeoutMs = waitOpts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
       const intervalMs = waitOpts?.intervalMs ?? 100;
       const t = Date.now();
       const resv = reserveEvent();