@specific.dev/spectest 0.64.0 → 0.67.0

package/dist/browser.js

@@ -34,6 +34,7 @@ import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
+import { capturePageStructure } from "./page-snapshot.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
@@ -1122,6 +1123,37 @@ function buildBackend(holder, recorder, buildOpts) {
     // when rrweb's load-deferred full snapshot is most likely to be
     // missing from the chunk we're about to drain (see `drainExpr`).
     let lastDrainUrl = null;
+    // Failed steps that captured their page. Bounded per session per case: a
+    // test that catches its own locator errors in a loop must not pay for a
+    // capture on each one, and three pages is already more than a reader will
+    // open. `ctx.poll` needs no bookkeeping here — it truncates the events of
+    // every superseded attempt, and each capture rides its own event.
+    let pageCaptures = 0;
+    const PAGE_CAPTURE_LIMIT = 3;
+    /** The page behind a failed step, for its event (see page-snapshot.ts).
+     *  Best-effort and quiet: this runs while an error is already on its way
+     *  up, and must never become the failure the author sees. */
+    async function failedPageStructure(action, error) {
+        // No recorder means nothing is recording this op (an eval, a library
+        // caller), so there is no event for the capture to ride out on.
+        if (!recorder || recordingEnded || viewClosed)
+            return undefined;
+        if (pageCaptures >= PAGE_CAPTURE_LIMIT)
+            return undefined;
+        pageCaptures += 1;
+        try {
+            return await capturePageStructure(holder.page, {
+                session: recorder.sessionName ?? "",
+                // A desktop view has no device preset; a phone-emulated one does.
+                kind: holder.device ? "mobile" : "browser",
+                action,
+                error,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Session provenance stamped on every recorded op: which replay player
      *  the step belongs to, which named browser it acted on, and where in
      *  the player to seek (`endT`, in rrweb's clock). */
@@ -1203,12 +1235,17 @@ function buildBackend(holder, recorder, buildOpts) {
         catch (err) {
             const e = err;
             const endT = Date.now();
+            const error = e?.message ?? String(err);
+            // Captured after the clock stops, so the diagnostic is not billed to
+            // the step, and before the event is recorded, so it rides it.
+            const pageStructure = await failedPageStructure(action, error);
             recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: endT - t,
-                error: e?.message ?? String(err),
+                error,
+                ...(pageStructure ? { pageStructure } : {}),
             }, resv);
             // Still try to drain — the failure itself may have produced
             // useful rrweb events (mutations from a half-loaded page, etc.).
@@ -1536,12 +1573,16 @@ function buildBackend(holder, recorder, buildOpts) {
             // where the matcher started polling, since that's what `tOffsetMs` means
             // everywhere else (the ops that reserve up front stamp their start).
             const endT = Date.now();
+            // A matcher that ran out of budget is the other half of a failed
+            // browser step, and the page it settled on is the same evidence.
+            const pageStructure = error ? await failedPageStructure(action, error) : undefined;
             const seq = recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
+                ...(pageStructure ? { pageStructure } : {}),
             }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.

package/dist/components/supabase.js

@@ -698,6 +698,14 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
 /** One isolate per function, reused across requests (the runtime pools by
  *  servicePath). The idle timeout is a day, not upstream's five minutes: a
  *  test environment is a snapshot lineage whose forks inherit these
@@ -708,32 +716,268 @@ function workerFor(name: string) {
   return EdgeRuntime.userWorkers.create({
     servicePath: FUNCTIONS_DIR + "/" + name,
     memoryLimitMb: 256,
-    workerTimeoutMs: 24 * 60 * 60 * 1000,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
     noModuleCache: false,
     importMapPath: null,
     envVars: Object.entries(Deno.env.toObject()),
   });
 }
 
-/** Boot every function's isolate now, without calling it. Creating the
- *  worker loads the module graph and runs the module's top level — for a
- *  function that is its \`Deno.serve(handler)\` registration, no business
- *  logic. Called once at environment setup, before the warm snapshot, so
- *  the isolates are shared, clean pages of the snapshot rather than a boot
- *  in every test that first touches a function. */
-async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, string> }> {
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
   const names: string[] = [];
   for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
     if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// There is deliberately no opt-out: it stands in wherever it can be exact,
+// and where it cannot the per-function isolates are used. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
     try {
-      await Deno.stat(FUNCTIONS_DIR + "/" + entry.name + "/index.ts");
-      names.push(entry.name);
-    } catch {
-      // not a function directory
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
     }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
   }
-  // All at once: a project can have dozens of functions, and each boot is
-  // mostly module loading — the isolates come up concurrently.
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
+  }
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
   const results = await Promise.allSettled(names.map((name) => workerFor(name)));
   const warmed: string[] = [];
   const failed: Record<string, string> = {};
@@ -741,7 +985,7 @@ async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, str
     if (r.status === "fulfilled") warmed.push(names[i]);
     else failed[names[i]] = String(r.reason);
   });
-  return { warmed: warmed.sort(), failed };
+  return { mode: "per-function", warmed: warmed.sort(), failed };
 }
 
 Deno.serve(async (req: Request) => {
@@ -766,7 +1010,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await workerFor(name);
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1521,13 +1765,16 @@ export function supabase(opts = {}) {
                     // fork of it. Warm, the isolates are clean shared pages of the
                     // snapshot and a test's diff is what its requests mutate.
                     setup: async () => {
+                        const t0 = Date.now();
                         const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
                         if (!res.ok) {
                             console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
                             return;
                         }
-                        const { warmed, failed } = (await res.json());
-                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"}${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+                        const { mode, warmed, failed } = (await res.json());
+                        const secs = ((Date.now() - t0) / 1000).toFixed(1);
+                        const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
                         for (const [name, err] of Object.entries(failed)) {
                             console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
                         }

package/dist/daemon.js

@@ -42,7 +42,7 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
-import { InterceptRegistry, runChain, } from "./harness/intercept.js";
+import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -2301,35 +2301,61 @@ function ingressClaimsHostname(hostname) {
     }
     return false;
 }
-/** Record one request an interceptor saw, nested under its `intercept` step. */
+/** Record one request an interceptor saw, nested under its `intercept` step.
+ *
+ * A forced 503 is the step doing exactly what its description says, so it is
+ * **not** marked failed — reddening the outcome the test asked for trains the
+ * reader to ignore the colour. Only a handler that threw is marked, because
+ * that 500 is a bug in the middleware rather than the outage it stands for. */
 function recordInterceptedRequest(it, rec, durationMs) {
     const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
     if (parentSeq === undefined || !isRecording())
         return;
-    const by = rec.answeredBy === "handler"
-        ? "answered by the interceptor"
-        : rec.answeredBy === "modified"
-            ? "upstream answer replaced by the interceptor"
-            : "passed through to the upstream";
+    const by = rec.threw
+        ? "the interceptor threw — 500 from spectest, not from your handler"
+        : rec.answeredBy === "handler"
+            ? "answered by the interceptor"
+            : rec.answeredBy === "modified"
+                ? "upstream answer replaced by the interceptor"
+                : "passed through to the upstream";
     recordStep({
         kind: "intercept-request",
         parentSeq,
         title: `${rec.method} ${rec.path} → ${rec.status}`,
-        status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+        status: rec.threw ? "failed" : "passed",
+        // Method, path and status are already the title; the one thing the row
+        // cannot say for itself is who produced that status.
         blocks: [
-            {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: it.hostname },
-                    { label: "Request", value: `${rec.method} ${rec.path}` },
-                    { label: "Status", value: String(rec.status) },
-                    { label: "Answered", value: by },
-                ],
-            },
+            { type: "kv", rows: [{ label: "Answered", value: by, error: rec.threw === true }] },
         ],
         durationMs,
     });
 }
+/** The handler's own source, which is what the interceptor actually does.
+ *
+ * Free and impossible to let rot: Bun runs the project's TypeScript
+ * directly, so `toString()` is the text the author wrote. It is the step's
+ * body, under the description — a mechanism the reader can check against
+ * the intent the description claims. A handler long enough to be a wall of
+ * code folds into a disclosure instead of pushing the requests off screen.
+ */
+function handlerBlocks(handler) {
+    let src;
+    try {
+        src = String(handler);
+    }
+    catch {
+        return [];
+    }
+    const code = { type: "code", lang: "ts", label: "Handler", code: src };
+    return src.split("\n").length > HANDLER_FOLD_LINES
+        ? [{ type: "details", summary: "Handler", blocks: [code] }]
+        : [code];
+}
+/** Past this many lines the handler source is folded away. Chosen so the
+ *  shapes this feature is for — a one-line forced status, a short
+ *  fail-twice-then-pass — always show, and only a real program hides. */
+const HANDLER_FOLD_LINES = 15;
 /**
  * Put middleware in front of a hostname the ingress serves — the
  * implementation behind `ctx.intercept`.
@@ -2338,15 +2364,19 @@ function recordInterceptedRequest(it, rec, durationMs) {
  * the daemon (DNS does not point here), so the interceptor could only be
  * silent — and silence is the failure mode this whole layer is designed
  * against. The message names the two ways to get a route.
+ *
+ * The `description` is required because it is the step's whole title in the
+ * timeline and in the CLI's failure detail: it is what tells a reader why
+ * the UI under test went to its error state. The handler source says how;
+ * only the author can say what it means.
  */
-function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
-    const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
-    const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
-    if (typeof hostname !== "string" || hostname.length === 0) {
-        throw new Error("ctx.intercept: a hostname is required");
-    }
-    const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    if (!handler) {
+function registerInterceptor(target, description, handler) {
+    const { hostname: host, path } = parseTarget(target);
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new Error(`ctx.intercept(${JSON.stringify(target)}): a description is required — what the ` +
+            `environment now does, as the timeline reads it, e.g. "the sync endpoint returns 503".`);
+    }
+    if (typeof handler !== "function") {
         throw new Error("ctx.intercept: a handler (req, next) => Response is required");
     }
     if (!ingressClaimsHostname(host)) {
@@ -2357,19 +2387,41 @@ function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
     }
     const resv = reserveEvent();
     const it = INTERCEPTORS.register(host, path, handler);
+    const where = `${host}${it.path === "/" ? "" : it.path}`;
     const seq = recordStep({
         kind: "intercept",
-        title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+        // The description alone. The pill already says INTERCEPT, and the
+        // target is in the panel — a row that repeats both spends its width
+        // on what the reader can already see and none of it on the one thing
+        // only the author knows.
+        title: description.trim(),
         blocks: [
+            ...handlerBlocks(handler),
             {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: host },
-                    { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+                // The target IS the summary line, so the closed disclosure still
+                // says where the interceptor sits — a generic "Target" label
+                // would spend the one visible line saying nothing.
+                type: "details",
+                summary: where,
+                blocks: [
+                    {
+                        type: "kv",
+                        rows: [
+                            {
+                                label: "Matches",
+                                value: it.path === "/" ? "every path on this host" : `${it.path} and below`,
+                            },
+                            {
+                                label: "Until",
+                                value: it.scope === undefined ? "remove()" : "the end of this test",
+                            },
+                        ],
+                    },
                 ],
             },
         ],
-        durationMs: 0,
+        // No duration: this is a marker for the moment the interceptor went
+        // up, and "(0 ms)" reads as a step that did nothing.
     }, resv);
     if (seq !== undefined)
         INTERCEPT_STEP_SEQ.set(it.id, seq);

package/dist/harness/intercept.d.ts

@@ -48,6 +48,12 @@ export interface InterceptedRequest {
      *  upstream via `next()` untouched (`upstream`), or the upstream's answer
      *  replaced by the interceptor after `next()` (`modified`). */
     answeredBy: "handler" | "upstream" | "modified";
+    /** The handler threw (or returned something that is not a `Response`), so
+     *  the 500 below is a bug in the test's own middleware rather than the
+     *  outage it was asked to produce. The distinction cannot be recovered
+     *  from the status: a deliberate 500 and a crashed handler are the same
+     *  number, and only this tells the timeline which one to mark as wrong. */
+    threw?: boolean;
 }
 export interface Interceptor {
     id: number;
@@ -61,6 +67,22 @@ export interface Interceptor {
     calls: number;
     requests: InterceptedRequest[];
 }
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export declare function parseTarget(target: string): {
+    hostname: string;
+    path: string;
+};
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export declare function pathMounts(mount: string, pathname: string): boolean;

package/dist/harness/intercept.js

@@ -33,6 +33,34 @@
  * plain `Request`/`Response` objects.
  */
 import { isWildcard, wildcardSuffix } from "./hostmatch";
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export function parseTarget(target) {
+    if (typeof target !== "string" || target.trim() === "") {
+        throw new Error("intercept: a target hostname is required, e.g. \"app.test\" or \"app.test/api\"");
+    }
+    const bare = target.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    const slash = bare.indexOf("/");
+    const hostname = slash === -1 ? bare : bare.slice(0, slash);
+    const rest = slash === -1 ? undefined : bare.slice(slash);
+    if (hostname === "") {
+        throw new Error(`intercept: target ${JSON.stringify(target)} names no hostname — write it as "app.test/api", not "/api"`);
+    }
+    if (hostname.includes("?") || hostname.includes("#")) {
+        throw new Error(`intercept: target ${JSON.stringify(target)} cannot carry a query or fragment`);
+    }
+    return { hostname, path: normalizeMount(rest) };
+}
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export function pathMounts(mount, pathname) {
@@ -159,6 +187,7 @@ export async function runChain(chain, req, upstream, observe) {
             res = new Response(`spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
             record.answeredBy = "handler";
             record.status = 500;
+            record.threw = true;
             it.calls++;
             it.requests.push(record);
             observe?.(it, record, Date.now() - started);