@specific.dev/spectest 0.66.0 → 0.68.0

package/dist/page-snapshot.js

@@ -0,0 +1,149 @@
+// The page's structure at the moment a browser step failed, as text an agent
+// can read.
+//
+// A failed browser test is the one failure where the CLI reader has nothing to
+// look at. The message says what did not happen, the timeline says what ran,
+// and the page itself — the thing that would answer the question — is only on
+// the dashboard, inside an rrweb replay. `screenshot()` is no help either: it
+// throws inside a test run, and an image is not something every reader can
+// read.
+//
+// So a failed browser/mobile step captures its page as an **accessibility
+// tree** (`page.ariaSnapshot()`), the same data locators resolve against. It is
+// small (a form page is under 1 KB; a 200-row table is 38 KB, 4 KB gzipped), it
+// is text, and every name in it is directly usable as
+// `getByRole(role, { name })`. It rides out on the step's own recorded event,
+// which is what keeps this entirely inside the SDK: no new daemon method, no
+// side channel, no supervisor involvement. The control plane lifts it into a
+// `case-page` artifact the same way it already lifts an eval screenshot's
+// bytes, so the failure block can hand the reader one command that prints the
+// page they could not see.
+//
+// Riding the event has a second, load-bearing effect: `ctx.poll` truncates the
+// events of every superseded attempt, so a poll whose predicate fails ten
+// times keeps exactly one capture — the attempt the timeline kept — with no
+// bookkeeping here.
+//
+// Two deliberate choices about the format:
+//
+//   * **Default mode, not `mode: "ai"`.** The ai mode adds `[ref=e12]`
+//     handles, and a ref is only resolvable in the live page it came from —
+//     in a downloaded file it is an invitation to write a locator that cannot
+//     work. Iframe content, which ai mode adds and the default mode leaves as
+//     a bare `- iframe`, is recovered by snapshotting each frame instead.
+//   * **No timestamps.** A guest's wall clock resumes frozen at the snapshot
+//     it was restored from, so a time captured here would be a plausible lie.
+//     The artifact row carries a host-side `created_at`.
+/** The document is a debugging aid, and a pathological page must not grow the
+ *  `/run` reply (the vm-agent caps a proxied daemon response at 16 MB). Real
+ *  pages are far below this: the biggest thing measured while building it was
+ *  38 KB. */
+export const MAX_DOCUMENT_BYTES = 256 * 1024;
+/** How many child frames are worth walking. An ad-heavy page can carry
+ *  dozens; the ones a test drives are at the front. */
+const MAX_FRAMES = 10;
+/** Per-call deadline. The page has just failed a step, and it may be wedged; a
+ *  diagnostic must not add to the damage. */
+const CAPTURE_TIMEOUT_MS = 3_000;
+function withTimeout(work, fallback) {
+    let timer;
+    return Promise.race([
+        work.catch(() => fallback),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(fallback), CAPTURE_TIMEOUT_MS);
+        }),
+    ]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+async function frameStructure(frame) {
+    // A frame's tree comes from its own body: `page.ariaSnapshot()` stops at
+    // `- iframe` and never descends into it.
+    const tree = await withTimeout(frame.locator("body").ariaSnapshot(), "");
+    if (!tree.trim())
+        return undefined;
+    return { name: frame.name(), url: frame.url(), tree };
+}
+/**
+ * Capture the page behind a failed step, or `undefined` when there is nothing
+ * to show.
+ *
+ * Everything here is best-effort: a page that is closed, navigating or wedged
+ * yields a partial record rather than an error, because the caller is already
+ * reporting a failure and must not report this one instead.
+ */
+export async function capturePageStructure(page, meta) {
+    const tree = await withTimeout(page.ariaSnapshot(), "");
+    const title = await withTimeout(page.title(), "");
+    let url = "";
+    try {
+        url = page.url();
+    }
+    catch {
+        /* The page is gone; the tree, if we got one, is still worth keeping. */
+    }
+    const frames = [];
+    try {
+        const children = page.frames().filter((f) => f !== page.mainFrame());
+        for (const f of children.slice(0, MAX_FRAMES)) {
+            const s = await frameStructure(f);
+            if (s)
+                frames.push(s);
+        }
+    }
+    catch {
+        /* Frames are a bonus; the main tree is the point. */
+    }
+    if (!tree.trim() && frames.length === 0)
+        return undefined;
+    return formatPageStructure({ ...meta, url, title, tree, frames });
+}
+/** The header that tells a reader what they are looking at. Worth its lines:
+ *  the file is read by someone who did not choose its format, hours later,
+ *  with nothing around it. */
+const LEGEND = [
+    "# Page structure at the moment this step failed.",
+    "#",
+    '# One line per accessibility node: `role "accessible name" [state]: own text`,',
+    "# children indented, properties as `/`-prefixed children (/url, /placeholder).",
+    "# The names here are exactly what `getByRole(role, { name })` matches on.",
+    "# Elements hidden from assistive technology are absent, as they are from locators.",
+];
+function quote(s) {
+    return JSON.stringify(s);
+}
+function sessionHeading(s) {
+    const name = s.session === "" ? "(default)" : quote(s.session);
+    const parts = [`## ${s.kind} session ${name}`];
+    if (s.url)
+        parts.push(`url: ${s.url}`);
+    if (s.title)
+        parts.push(`title: ${quote(s.title)}`);
+    return parts.join(" — ");
+}
+/** Render the document. Pure, so its shape is testable without a browser. */
+export function formatPageStructure(s) {
+    const lines = [...LEGEND, "#", `# failed step: ${s.action}`];
+    if (s.error) {
+        // The first line only: the near-miss block under a locator failure is
+        // already in the CLI output, and this file exists to add to it.
+        lines.push(`# failure: ${s.error.split("\n")[0]}`);
+    }
+    lines.push("", sessionHeading(s), s.tree.trimEnd());
+    for (const f of s.frames) {
+        const name = f.name === "" ? "" : ` ${quote(f.name)}`;
+        lines.push("", `### iframe${name} — url: ${f.url}`, f.tree.trimEnd());
+    }
+    return truncate(`${lines.join("\n")}\n`);
+}
+/** Cut the document to {@link MAX_DOCUMENT_BYTES}, on a line boundary, and say
+ *  so — a silently short tree reads as a page that ends there. */
+export function truncate(doc) {
+    const bytes = Buffer.byteLength(doc, "utf8");
+    if (bytes <= MAX_DOCUMENT_BYTES)
+        return doc;
+    const text = Buffer.from(doc, "utf8").subarray(0, MAX_DOCUMENT_BYTES).toString("utf8");
+    const cut = text.slice(0, text.lastIndexOf("\n") + 1);
+    return `${cut}# … truncated at ${MAX_DOCUMENT_BYTES} bytes (${bytes} bytes captured)\n`;
+}

package/dist/recorder.d.ts

@@ -433,6 +433,22 @@ export interface BrowserEvent extends BaseEvent {
     attempts?: number;
     durationMs: number;
     error?: string;
+    /**
+     * The page's accessibility tree at the moment this step failed — set only
+     * on a failed browser/mobile step (see `page-snapshot.ts`). It rides the
+     * event because that is the only channel out of the harness the SDK owns
+     * end to end, and because `ctx.poll` truncates a superseded attempt's
+     * events, which drops its capture with it.
+     *
+     * **The control plane lifts this out**: it stores the text as a
+     * `case-page` artifact and replaces the field with `pageArtifactId`,
+     * exactly as it does for an eval screenshot's inline bytes. So a
+     * persisted event carries the id, never the document.
+     */
+    pageStructure?: string;
+    /** The `art_0…` the control plane stored {@link pageStructure} as. Never
+     *  set by the SDK. */
+    pageArtifactId?: string;
     /**
      * Session this op belonged to. Set whenever the Browser was opened
      * with a `BrowserSessionRecorder` attached (the daemon always does).

package/dist/text-match.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Playwright's whitespace normalization, character for character
+ * (`normalizeWhiteSpace`, playwright-core): drop zero-width spaces and soft
+ * hyphens, trim, then collapse every run of whitespace to one space. `\s`
+ * covers U+00A0 and the rest of the Unicode space characters, which is what
+ * makes a typed space match a no-break one.
+ */
+export declare function normalizeWhiteSpace(text: string): string;
+export interface TextMatchOptions {
+    /** Compare without regard to letter case. On a RegExp this adds the `i`
+     *  flag, as playwright's own `ignoreCase` does. */
+    ignoreCase?: boolean;
+}
+/** The element's text equals `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export declare function matchesText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
+/** The element's text contains `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export declare function containsText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
+/** `" "` for an invisible character, the character itself otherwise.
+ *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
+ *  valid JSON string literal. */
+export declare function escapeInvisible(s: string): string;
+/**
+ * A sentence to append to a failed string comparison when the two strings
+ * print the same, or differ only in letter case — the failure a reader cannot
+ * see. Returns `""` for every other case, so a caller can concatenate it
+ * unconditionally.
+ *
+ * `mode` is how the two were compared: `"equal"` for the equality matchers,
+ * `"contains"` for the substring ones.
+ */
+export declare function textDifferenceNote(actual: unknown, expected: unknown, mode: "equal" | "contains"): string;
+/** Every element's text equals the item at its position, and there are
+ *  exactly as many elements as items. */
+export declare function matchesTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;
+/** The elements' texts contain every item, in order. Extra elements between
+ *  the matches are allowed. */
+export declare function containsTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;

package/dist/text-match.js

@@ -0,0 +1,239 @@
+// Text comparison for the web-first matchers, and readable notes for the
+// failures that invisible characters cause.
+//
+// Two rules, and they are deliberately different:
+//
+//   * **Matching is Playwright's.** `expect(locator).toHaveText(...)` and
+//     `toContainText(...)` normalize whitespace on BOTH sides exactly as
+//     playwright's own text engine does (`normalizeWhiteSpace` in
+//     playwright-core). Without this the SDK disagreed with itself: the same
+//     string matched through `getByText("15 000 kr")` (playwright's engine,
+//     which normalizes) and failed through `toContainText("15 000 kr")`
+//     (ours, which did a raw `includes`). The case that reported it is
+//     Swedish number formatting — `Intl.NumberFormat("sv-SE")` groups
+//     thousands with U+00A0 NO-BREAK SPACE, and JavaScript's `\s` covers
+//     U+00A0, so normalization makes a typed space match it.
+//
+//   * **Diagnostics are wider.** A value the author compares themselves
+//     (`expect(body).toContain(...)`, `toHaveValue`) is still exact, as it
+//     must be — so when such a comparison fails on characters that print the
+//     same, the message has to say so. `textDifferenceNote` reports the
+//     invisible or look-alike characters that are the whole difference, and
+//     `escapeInvisible` makes the two printed strings differ on screen.
+/** Characters that are invisible on screen (or print as an ordinary space)
+ *  and their Unicode names, for a message a reader can act on. */
+const INVISIBLE_NAMES = {
+    0x0009: "TAB",
+    0x000a: "LINE FEED",
+    0x000b: "LINE TABULATION",
+    0x000c: "FORM FEED",
+    0x000d: "CARRIAGE RETURN",
+    0x00a0: "NO-BREAK SPACE",
+    0x00ad: "SOFT HYPHEN",
+    0x1680: "OGHAM SPACE MARK",
+    0x2000: "EN QUAD",
+    0x2001: "EM QUAD",
+    0x2002: "EN SPACE",
+    0x2003: "EM SPACE",
+    0x2004: "THREE-PER-EM SPACE",
+    0x2005: "FOUR-PER-EM SPACE",
+    0x2006: "SIX-PER-EM SPACE",
+    0x2007: "FIGURE SPACE",
+    0x2008: "PUNCTUATION SPACE",
+    0x2009: "THIN SPACE",
+    0x200a: "HAIR SPACE",
+    0x200b: "ZERO WIDTH SPACE",
+    0x200c: "ZERO WIDTH NON-JOINER",
+    0x200d: "ZERO WIDTH JOINER",
+    0x200e: "LEFT-TO-RIGHT MARK",
+    0x200f: "RIGHT-TO-LEFT MARK",
+    0x2028: "LINE SEPARATOR",
+    0x2029: "PARAGRAPH SEPARATOR",
+    0x202f: "NARROW NO-BREAK SPACE",
+    0x205f: "MEDIUM MATHEMATICAL SPACE",
+    0x2060: "WORD JOINER",
+    0x3000: "IDEOGRAPHIC SPACE",
+    0xfeff: "ZERO WIDTH NO-BREAK SPACE",
+};
+/** Visible characters an author reaches for on the keyboard, and the
+ *  typographic look-alikes a CMS, a text editor or `Intl` substitutes for
+ *  them. Reported, never matched through — two strings that differ by an em
+ *  dash really are different strings. */
+const LOOKALIKES = {
+    0x2010: { ascii: "-", name: "HYPHEN" },
+    0x2011: { ascii: "-", name: "NON-BREAKING HYPHEN" },
+    0x2012: { ascii: "-", name: "FIGURE DASH" },
+    0x2013: { ascii: "-", name: "EN DASH" },
+    0x2014: { ascii: "-", name: "EM DASH" },
+    0x2212: { ascii: "-", name: "MINUS SIGN" },
+    0x2018: { ascii: "'", name: "LEFT SINGLE QUOTATION MARK" },
+    0x2019: { ascii: "'", name: "RIGHT SINGLE QUOTATION MARK" },
+    0x201c: { ascii: '"', name: "LEFT DOUBLE QUOTATION MARK" },
+    0x201d: { ascii: '"', name: "RIGHT DOUBLE QUOTATION MARK" },
+    0x2026: { ascii: "...", name: "HORIZONTAL ELLIPSIS" },
+};
+/**
+ * Playwright's whitespace normalization, character for character
+ * (`normalizeWhiteSpace`, playwright-core): drop zero-width spaces and soft
+ * hyphens, trim, then collapse every run of whitespace to one space. `\s`
+ * covers U+00A0 and the rest of the Unicode space characters, which is what
+ * makes a typed space match a no-break one.
+ */
+export function normalizeWhiteSpace(text) {
+    return text.replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ");
+}
+function caseFold(s, opts) {
+    return opts?.ignoreCase ? s.toLowerCase() : s;
+}
+function withIgnoreCase(re, opts) {
+    if (!opts?.ignoreCase || re.flags.includes("i"))
+        return re;
+    return new RegExp(re.source, `${re.flags}i`);
+}
+/** The element's text equals `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export function matchesText(actual, expected, opts) {
+    const a = normalizeWhiteSpace(actual);
+    if (expected instanceof RegExp)
+        return withIgnoreCase(expected, opts).test(a);
+    return caseFold(a, opts) === caseFold(normalizeWhiteSpace(expected), opts);
+}
+/** The element's text contains `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export function containsText(actual, expected, opts) {
+    const a = normalizeWhiteSpace(actual);
+    if (expected instanceof RegExp)
+        return withIgnoreCase(expected, opts).test(a);
+    return caseFold(a, opts).includes(caseFold(normalizeWhiteSpace(expected), opts));
+}
+// ── Diagnostics ───────────────────────────────────────────────────────────
+/** `" "` for an invisible character, the character itself otherwise.
+ *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
+ *  valid JSON string literal. */
+export function escapeInvisible(s) {
+    let out = "";
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        // Control characters are already escaped by JSON.stringify; what is left
+        // is the invisible-but-not-control set, which prints as nothing (or as an
+        // ordinary space) and so must be spelled out.
+        out += code > 0x1f && code in INVISIBLE_NAMES
+            ? `\\u${code.toString(16).padStart(4, "0")}`
+            : ch;
+    }
+    return out;
+}
+/** The name of a character worth reporting, or `undefined` when it is an
+ *  ordinary one. */
+function suspectName(code) {
+    if (code === 0x20)
+        return undefined;
+    return INVISIBLE_NAMES[code] ?? LOOKALIKES[code]?.name;
+}
+/** Map a character onto the plain one it prints as, so two strings that only
+ *  *look* the same can be told apart from two that really differ. */
+function foldChar(ch) {
+    const code = ch.codePointAt(0);
+    if (code in LOOKALIKES)
+        return LOOKALIKES[code].ascii;
+    if (code in INVISIBLE_NAMES) {
+        // Zero-width characters print as nothing; the rest print as a space.
+        return code === 0x200b ||
+            code === 0x200c ||
+            code === 0x200d ||
+            code === 0x200e ||
+            code === 0x200f ||
+            code === 0x00ad ||
+            code === 0x2060 ||
+            code === 0xfeff
+            ? ""
+            : " ";
+    }
+    return ch;
+}
+/** The string as it appears on screen: every look-alike replaced by the plain
+ *  character it resembles, every zero-width one dropped, whitespace collapsed. */
+function fold(s) {
+    let out = "";
+    for (const ch of s)
+        out += foldChar(ch);
+    return out.trim().replace(/ +/g, " ");
+}
+/** Every reportable character in `s`, first occurrence only, in order. */
+function suspects(s) {
+    const seen = new Set();
+    const out = [];
+    let index = 0;
+    for (const ch of s) {
+        const name = suspectName(ch.codePointAt(0));
+        if (name && !seen.has(name)) {
+            seen.add(name);
+            out.push({ name, index });
+        }
+        index += ch.length;
+    }
+    return out;
+}
+function listSuspects(items) {
+    return items
+        .slice(0, 3)
+        .map((s) => `${s.name} at index ${s.index}`)
+        .join(", ");
+}
+/**
+ * A sentence to append to a failed string comparison when the two strings
+ * print the same, or differ only in letter case — the failure a reader cannot
+ * see. Returns `""` for every other case, so a caller can concatenate it
+ * unconditionally.
+ *
+ * `mode` is how the two were compared: `"equal"` for the equality matchers,
+ * `"contains"` for the substring ones.
+ */
+export function textDifferenceNote(actual, expected, mode) {
+    if (typeof actual !== "string" || typeof expected !== "string")
+        return "";
+    const matched = (a, e) => mode === "equal" ? a === e : a.includes(e);
+    if (matched(actual, expected))
+        return "";
+    const fa = fold(actual);
+    const fe = fold(expected);
+    if (matched(fa, fe)) {
+        const inActual = suspects(actual);
+        const inExpected = suspects(expected);
+        const where = inActual.length
+            ? `the actual text has ${listSuspects(inActual)}`
+            : `the expected string has ${listSuspects(inExpected)}`;
+        return ` — the two print the same: they differ only in invisible or look-alike characters (${where})`;
+    }
+    if (matched(fa.toLowerCase(), fe.toLowerCase())) {
+        return " — they differ only in letter case";
+    }
+    return "";
+}
+// ── Array forms (`toHaveText([...])` / `toContainText([...])`) ────────────
+//
+// Playwright's own rule, from its injected script: the expected items are
+// matched against the received texts **greedily, in order**, and the lengths
+// must agree for `toHaveText` but not for `toContainText`. So
+// `toContainText(["Two", "Four"])` passes against a four-row list, while
+// `toHaveText(["Two", "Four"])` does not.
+function matchesInOrder(actual, expected, item) {
+    let want = 0;
+    for (let i = 0; i < actual.length && want < expected.length; i++) {
+        if (item(actual[i], expected[want]))
+            want++;
+    }
+    return want === expected.length;
+}
+/** Every element's text equals the item at its position, and there are
+ *  exactly as many elements as items. */
+export function matchesTextArray(actual, expected, opts) {
+    if (actual.length !== expected.length)
+        return false;
+    return matchesInOrder(actual, expected, (a, e) => matchesText(a, e, opts));
+}
+/** The elements' texts contain every item, in order. Extra elements between
+ *  the matches are allowed. */
+export function containsTextArray(actual, expected, opts) {
+    return matchesInOrder(actual, expected, (a, e) => containsText(a, e, opts));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -37,6 +37,7 @@ import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
+import { capturePageStructure } from "./page-snapshot.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import {
   attachBrowserCoverage,
@@ -1616,6 +1617,38 @@ function buildBackend(
   // 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: string | null = 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: BrowserAction,
+    error: string,
+  ): Promise<string | undefined> {
+    // 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
@@ -1699,12 +1732,17 @@ function buildBackend(
     } catch (err) {
       const e = err as Error;
       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.).
@@ -2078,12 +2116,16 @@ function buildBackend(
       // 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/src/components/supabase.ts

@@ -235,18 +235,6 @@ export interface SupabaseOptions {
   storage?: boolean;
   /** Include Realtime (`<name>-realtime`). Default `true`. */
   realtime?: boolean;
-  /**
-   * Edge functions. `isolation` picks how they run on the edge runtime:
-   * `"shared"` (default) loads every function into **one** isolate, so a
-   * shared module graph (`_shared/`, npm packages) is loaded once rather than
-   * once per function — measured on a 51-function project as 230 MB against
-   * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
-   * that differs is module-level state: a singleton in `_shared` is one
-   * object for all functions here, one per function there. `"per-function"`
-   * runs it the hosted way. Either way the runtime, the request each
-   * function sees and the per-function `verify_jwt` are the same.
-   */
-  functions?: { isolation?: "shared" | "per-function" };
 
   /**
    * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
@@ -1055,9 +1043,6 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
-/** How the functions run: every function in one isolate (the default), or
- *  one isolate per function as hosted Supabase does — see sharedWorker. */
-const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
 /** 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
@@ -1137,7 +1122,8 @@ async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
 // what differs from hosted Supabase is that module-level state is one
 // object for every function rather than one per function.
 //
-// It stands in only where it can be exact. A function with its own
+// 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
@@ -1286,7 +1272,6 @@ async function writeShared(names: string[]): Promise<string | 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 (ISOLATION !== "shared") return null;
   if (!sharedSpec) {
     sharedSpec = (async () => {
       const names = await functionNames();
@@ -2242,9 +2227,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             JWT_SECRET: jwtSecret,
             // Where the router looks for `<name>/`, inside the repo mount.
             FUNCTIONS_DIR: fnServePath,
-            // One isolate for all functions (default) or one each — see the
-            // `functions` option and the router's shared-isolate notes.
-            FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
             // The default a function inherits when the config says nothing:
             // reject an unauthenticated call, as hosted Supabase does.
             VERIFY_JWT: "true",