create-ailk 0.30.0 → 0.32.0

package/templates/apps/web/app/[locale]/pricing/[slug]/__tests__/page.test.tsx

@@ -32,6 +32,9 @@ jest.mock("next/navigation", () => ({
 
 import OfferingPricingPage, { dynamic, generateMetadata } from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const SLUG = "website-rebuild";
 const SITE_EMAIL = "hello@example.com";
 

package/templates/apps/web/app/[locale]/pricing/__tests__/offerings.test.tsx

@@ -27,6 +27,9 @@ import {
 
 import PricingPage, { generateMetadata } from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const SITE_EMAIL = "hello@example.com";
 const HOSTILE = "</script><script>alert(1)</script>";
 

package/templates/apps/web/app/[locale]/pricing/__tests__/page.test.tsx

@@ -15,6 +15,9 @@ import { act, render, screen, within } from "@testing-library/react";
 
 import PricingPage from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const PLANS = [
   {
     key: "basic",

package/templates/apps/web/app/[locale]/pricing/__tests__/unconnected.test.tsx

@@ -27,6 +27,9 @@ import { TOPOLOGY } from "../../../../lib/topology.generated";
 import * as pricingPage from "../page";
 import PricingPage, { generateMetadata } from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const PLANS = [
   {
     key: "basic",

package/templates/apps/web/app/[locale]/projects/__tests__/page-renderer-migration.test.tsx

@@ -51,6 +51,9 @@ import { notFound } from "next/navigation";
 import ProjectsPage from "../page";
 import ProjectSlugPage from "../[slug]/page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
 // ── Shared stub helpers ────────────────────────────────────────────────────────

package/templates/apps/web/app/[locale]/services/__tests__/page-renderer-migration.test.tsx

@@ -31,6 +31,9 @@ import ServicesPage from "../page";
 import ServiceSlugPage from "../[slug]/page";
 import * as pageRenderer from "@working-theory/page-renderer";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
 // ── Shared stub helpers ────────────────────────────────────────────────────────

package/templates/apps/web/app/[locale]/team/__tests__/team-routes.test.tsx

@@ -31,6 +31,9 @@ import TeamPage from "../page";
 import TeamMemberPage from "../[slug]/page";
 import * as pageRenderer from "@working-theory/page-renderer";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 type JsonLd = Record<string, unknown>;
 
 function jsonLdScripts(container: HTMLElement): JsonLd[] {

package/templates/apps/web/app/[locale]/thanks/[slug]/__tests__/page.test.tsx

@@ -52,10 +52,10 @@ jest.mock("../AccountInviteLink", () => ({
     }),
 }));
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { notFound } from "next/navigation";
-import ThankYouSlugPage from "../page";
+import ThankYouSlugPage, { generateMetadata } from "../page";
 
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
@@ -132,3 +132,22 @@ describe("ThankYouSlugPage — detail route", () => {
     expect(source).not.toMatch(/["']use client["']/);
   });
 });
+
+// #10617 AC-1 — the route's own metadata, read from the real seed, carries
+// the noindex directive the page-renderer gives every ThankYouPage.
+// The scaffold matrix runs this suite inside a scaffold that ships no
+// flow-thanks seed (#10763), so the test skips where the seed does not exist.
+const SEED = join(
+  __dirname, "..", "..", "..", "..", "..", "..", "..",
+  "content", "en", "ThankYouPage", "flow-thanks.mdx",
+);
+const itWithSeed = existsSync(SEED) ? it : it.skip;
+
+describe("ThankYouSlugPage — generateMetadata (#10617)", () => {
+  itWithSeed("carries robots noindex, follow", async () => {
+    const metadata = await generateMetadata({
+      params: Promise.resolve({ locale: "en", slug: "flow-thanks" }),
+    });
+    expect(metadata.robots).toEqual({ index: false, follow: true });
+  });
+});

package/templates/apps/web/app/[locale]/thanks/[slug]/page.tsx

@@ -4,6 +4,7 @@
 // header says why there is no static-params export (#7379). Unknown slugs 404
 // via renderPage's own detail-route branch (no translationsNamespace passed
 // — renderPage calls notFound() itself when getMdxSource resolves null).
+// `renderPageMetadata` makes every ThankYouPage `noindex, follow` (#10617).
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
 import type { Metadata } from "next";

package/templates/apps/web/app/llms.txt/route.ts

@@ -25,6 +25,9 @@
  * the docs path; otherwise those rows are skipped (the MDX docs route never
  * serves them) and the docs directory is listed (`getDocsPages`, default
  * `listDocsPages`).
+ *
+ * Blog (#10644 D1): under the database adapter the adapter's `BlogList` /
+ * `BlogPosting` rows are the blog, and `getBlogPages` is not called.
  */
 
 import { siteDiscoverable } from "@working-theory/api-client";
@@ -59,6 +62,8 @@ export interface LlmsHandlerDeps {
    * Blog pages getter. Defaults to none — Free has no blog (D-46, #5365 D9).
    * The docs + blog module's own copy of this route reads `blogSource`.
    * Override in tests to inject stub pages.
+   * Not called under the database adapter, whose `BlogList` / `BlogPosting`
+   * rows are the blog (#10644 D1).
    */
   getBlogPages?: () => Array<{ url: string; data: { title: string; description?: string } }>;
   /** The docs pages (#10041). Defaults to `listDocsPages` over this app's docs directory. */
@@ -97,10 +102,10 @@ export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
       types.map((type) => adapter.listPages(type, defaultLocale)),
     );
 
-    const databaseDocs = resolvedAdapterKind() === "database";
+    const databaseCorpus = resolvedAdapterKind() === "database";
     for (const pages of pageLists) {
       for (const page of pages) {
-        if (isDocsType(page.type) && !databaseDocs) continue;
+        if (isDocsType(page.type) && !databaseCorpus) continue;
         const path = isDocsType(page.type)
           ? adapterDocsUrl(page.type, page.slug)
           : pagePathFor(page);
@@ -118,18 +123,20 @@ export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
     // blogSource.getPages() returns pages ordered by Fumadocs; the index page
     // (/blog) sorts first naturally because its slug array is empty.
     lines.push("");
-    for (const page of resolveBlogPages()) {
-      lines.push(`- Title: ${page.data.title}`);
-      lines.push(`  URL: ${baseUrl}${page.url}`);
-      if (page.data.description) {
-        lines.push(`  Description: ${page.data.description}`);
+    if (!databaseCorpus) {
+      for (const page of resolveBlogPages()) {
+        lines.push(`- Title: ${page.data.title}`);
+        lines.push(`  URL: ${baseUrl}${page.url}`);
+        if (page.data.description) {
+          lines.push(`  Description: ${page.data.description}`);
+        }
+        lines.push("");
       }
-      lines.push("");
     }
 
     // The docs directory (#10041 D8) — not under the database adapter, whose
     // docs rows are listed above.
-    if (!databaseDocs) {
+    if (!databaseCorpus) {
       for (const doc of resolveDocsPages()) {
         lines.push(`- Title: ${doc.title}`);
         lines.push(`  URL: ${baseUrl}${doc.url}`);

package/templates/apps/web/app/sitemap.xml/route.ts

@@ -152,6 +152,9 @@ export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
           }
           continue;
         }
+        // #10617 — a flow's completion target renders `robots: noindex`
+        // (`renderPageMetadata`), so it is never listed, in any locale.
+        if (page.type === "ThankYouPage") continue;
         const path = pagePathFor(page);
         const lastmod = page.publishedAt ?? today;
 

package/templates/apps/web/jest.config.cjs

@@ -1,5 +1,50 @@
 // Mirrors apps/api's ts-jest setup (CONVENTIONS.md mentions Vitest aspirationally,
 // but no Vitest is installed anywhere yet). JSDOM env so RTL can mount components.
+/**
+ * #10699 D4: lib/runtime-source.ts derives the toc through
+ * fumadocs-core/content/toc, whose remark closure ships ESM only. These are
+ * pnpm-store name prefixes (the `tools/jest/mdxeditor-esm.cjs` shape, inlined
+ * because a scaffold's copy of this file has no `tools/`): `mdast-util-`
+ * covers every `mdast-util-*` package, `remark` covers `remark-gfm` /
+ * `remark-parse`, `vfile` covers `vfile-message`. Re-derive from the
+ * installed tree when the lockfile moves; the runtime-source suites loading
+ * is the proof.
+ */
+const REMARK_TOC_ESM = [
+  "bail",
+  "ccount",
+  "character-",
+  "decode-named-character-reference",
+  "devlop",
+  "escape-string-regexp",
+  "estree-util-",
+  "github-slugger",
+  "is-plain-obj",
+  "longest-streak",
+  "markdown-table",
+  "mdast-util-",
+  "micromark",
+  "remark",
+  "trough",
+  "unified",
+  "unist-util-",
+  "vfile",
+  "zwitch",
+];
+
+/**
+ * Admit REMARK_TOC_ESM beside whatever a carve-out already admits, leaving
+ * the carve-out's own literal untouched — create-ailk's template build and the
+ * docs-blog `jest-config` patch both find it by exact string.
+ */
+function admitRemarkToc(pattern) {
+  const head = "/node_modules/(?!(\\.pnpm/)?";
+  return pattern.replace(
+    head,
+    `${head}(?:${REMARK_TOC_ESM.join("|")})|(\\.pnpm/)?`,
+  );
+}
+
 module.exports = {
   preset: "ts-jest",
   globalSetup: require.resolve("../../tools/jest/pin-timezone.cjs"),
@@ -17,7 +62,7 @@ module.exports = {
   // Mirrors the canonical jose carve-out used in apps/api, apps/mcp, and apps-paid/license-issuer.
   // Added: issue #1077
   transformIgnorePatterns: [
-    "/node_modules/(?!(\\.pnpm/)?@working-theory(?:\\+[^/]*?@?[^/]*?|/[^/]+)(/|$))",
+    admitRemarkToc("/node_modules/(?!(\\.pnpm/)?@working-theory(?:\\+[^/]*?@?[^/]*?|/[^/]+)(/|$))"),
   ],
   moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json"],
   // Workspace packages publish ESM in dist/, but ts-jest runs in CommonJS.

package/templates/apps/web/lib/__tests__/bot-check.test.ts

@@ -14,6 +14,13 @@ jest.mock("botid/server", () => ({
   checkBotId: (...args: unknown[]) => checkBotIdMock(...args),
 }));
 
+// The request's headers (#10715): every case decides them here, a direct
+// request with no proxy marker unless the case says otherwise.
+const headersMock = jest.fn();
+jest.mock("next/headers", () => ({
+  headers: (...args: unknown[]) => headersMock(...args),
+}));
+
 const BOT = {
   isHuman: false,
   isBot: true,
@@ -42,6 +49,8 @@ let warnSpy: jest.SpyInstance;
 
 beforeEach(() => {
   checkBotIdMock.mockReset();
+  headersMock.mockReset();
+  headersMock.mockResolvedValue(new Headers({ host: "spoke.example" }));
   for (const name of ENV_KEYS) delete process.env[name];
   process.env.VERCEL = "1";
   errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
@@ -78,10 +87,13 @@ describe("AC-1 — runBotCheck's verdict (#9889 D3, one rule for every write)",
       checkBotIdMock.mockResolvedValue(verdict);
       expect(await runBotCheck(CHECK)).toBe("bot");
       expect(warnSpy).toHaveBeenCalledTimes(1);
-      expect(warnSpy).toHaveBeenCalledWith("[bot-check] bot refused", {
-        path: "testAction",
-        outcome: "bot-detected",
-      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[bot-check] bot refused",
+        expect.objectContaining({
+          path: "testAction",
+          outcome: "bot-detected",
+        }),
+      );
     },
   );
 
@@ -252,3 +264,234 @@ describe("AC-4 — the switches and BotID's client list", () => {
     expect(compileBotIdPath(entry?.path ?? "").test(pathname)).toBe(true);
   });
 });
+
+describe("#10715 — a refusal names its cause", () => {
+  const DIRECT = { host: "spoke.example" };
+  const PROXIED = {
+    host: "spoke.example",
+    "x-forwarded-host": "www.spoke.example",
+    "cf-ray": "8f2b-CLE",
+    cookie: "session=secret",
+    "x-is-human": "challenge-token",
+  };
+  const VERDICT = {
+    ...BOT,
+    verifiedBotName: undefined,
+    verifiedBotCategory: undefined,
+    classificationReason: "integrity-check-failed",
+  };
+  const FIX =
+    "Serve the site direct to Vercel: set its Cloudflare DNS record to DNS-only (no orange cloud), never behind a reverse proxy (#10715).";
+
+  /** Runs `run` in a fresh copy of the module, so its once-per-process flag starts unset. */
+  async function inFreshModule(
+    run: (fresh: typeof import("../bot-check")) => Promise<void>,
+  ): Promise<void> {
+    await jest.isolateModulesAsync(async () => {
+      await run(await import("../bot-check"));
+    });
+  }
+
+  it("a direct refusal logs the full shape: the verdict's detail, both hosts and proxied false", async () => {
+    headersMock.mockResolvedValue(new Headers(DIRECT));
+    checkBotIdMock.mockResolvedValue(VERDICT);
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("bot");
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]).toStrictEqual([
+      "[bot-check] bot refused",
+      {
+        path: "testAction",
+        outcome: "bot-detected",
+        classificationReason: "integrity-check-failed",
+        bypassed: false,
+        isVerifiedBot: false,
+        host: "spoke.example",
+        forwardedHost: null,
+        proxied: false,
+      },
+    ]);
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it("a proxied refusal logs proxied true and no header value but the two hosts", async () => {
+    headersMock.mockResolvedValue(new Headers(PROXIED));
+    checkBotIdMock.mockResolvedValue({ ...VERDICT, isVerifiedBot: true });
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("bot");
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]).toStrictEqual([
+      "[bot-check] bot refused",
+      {
+        path: "testAction",
+        outcome: "bot-detected",
+        classificationReason: "integrity-check-failed",
+        bypassed: false,
+        isVerifiedBot: true,
+        host: "spoke.example",
+        forwardedHost: "www.spoke.example",
+        proxied: true,
+      },
+    ]);
+    const logged = JSON.stringify([warnSpy.mock.calls, errorSpy.mock.calls]);
+    for (const secret of ["8f2b-CLE", "session=secret", "challenge-token"]) {
+      expect(logged).not.toContain(secret);
+    }
+  });
+
+  it("a verdict with no reason logs classificationReason null", async () => {
+    checkBotIdMock.mockResolvedValue(BOT);
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("bot");
+    });
+    expect(warnSpy.mock.calls[0]?.[1]).toMatchObject({
+      classificationReason: null,
+      proxied: false,
+    });
+  });
+
+  it("headers it cannot read log null hosts and proxied false, and still refuse", async () => {
+    headersMock.mockImplementation(() => {
+      throw new Error("outside a request scope");
+    });
+    checkBotIdMock.mockResolvedValue(BOT);
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("bot");
+    });
+    expect(warnSpy.mock.calls[0]?.[1]).toMatchObject({
+      host: null,
+      forwardedHost: null,
+      proxied: false,
+    });
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a human", HUMAN, "pass"],
+    ["a bot", BOT, "bot"],
+  ] as const)(
+    "the first proxied check (%s) logs the reverse-proxy error once per process, naming the fix",
+    async (_label, verdict, outcome) => {
+      headersMock.mockResolvedValue(new Headers(PROXIED));
+      checkBotIdMock.mockResolvedValue(verdict);
+      await inFreshModule(async (fresh) => {
+        for (let i = 0; i < 3; i++) {
+          expect(await fresh.runBotCheck(CHECK)).toBe(outcome);
+        }
+      });
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0]).toStrictEqual([
+        "[bot-check] reverse proxy detected",
+        {
+          path: "testAction",
+          outcome: "proxied",
+          host: "spoke.example",
+          forwardedHost: "www.spoke.example",
+          fix: FIX,
+        },
+      ]);
+    },
+  );
+
+  it("a proxied check that throws still logs the reverse-proxy error, then the failure", async () => {
+    headersMock.mockResolvedValue(new Headers(PROXIED));
+    checkBotIdMock.mockRejectedValue(new Error("token abc"));
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("unavailable");
+    });
+    expect(errorSpy.mock.calls.map(([message]) => message)).toEqual([
+      "[bot-check] reverse proxy detected",
+      "[bot-check] bot check failed",
+    ]);
+  });
+
+  it("a direct check never logs the reverse-proxy error", async () => {
+    headersMock.mockResolvedValue(new Headers(DIRECT));
+    checkBotIdMock.mockResolvedValue(HUMAN);
+    await inFreshModule(async (fresh) => {
+      expect(await fresh.runBotCheck(CHECK)).toBe("pass");
+    });
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("proxied changes no verdict: a proxied human passes, a proxied bot refuses", async () => {
+    headersMock.mockResolvedValue(new Headers(PROXIED));
+    await inFreshModule(async (fresh) => {
+      checkBotIdMock.mockResolvedValue(HUMAN);
+      expect(await fresh.runBotCheck(CHECK)).toBe("pass");
+      checkBotIdMock.mockResolvedValue(BOT);
+      expect(await fresh.runBotCheck(CHECK)).toBe("bot");
+    });
+  });
+});
+
+describe("#10715 — AILK_BOT_CHECK=observe runs the check and never refuses", () => {
+  it.each(["observe", " OBSERVE ", "Observe"])(
+    "AILK_BOT_CHECK=%j leaves the check on for both scopes",
+    (value) => {
+      process.env.AILK_BOT_CHECK = value;
+      expect(botCheckOn("write")).toBe(true);
+      expect(botCheckOn("booking")).toBe(true);
+    },
+  );
+
+  it.each([
+    ["a bot", BOT, true],
+    ["a human", HUMAN, false],
+  ] as const)(
+    "%s passes for every scope, logging the facts and isBot as observed",
+    async (_label, verdict, isBot) => {
+      process.env.AILK_BOT_CHECK = " Observe ";
+      headersMock.mockResolvedValue(new Headers({ host: "spoke.example" }));
+      checkBotIdMock.mockResolvedValue({
+        ...verdict,
+        classificationReason: "reason-x",
+      });
+      for (const scope of ["write", "booking"] as const) {
+        expect(await runBotCheck({ ...CHECK, scope })).toBe("pass");
+      }
+      expect(checkBotIdMock).toHaveBeenCalledTimes(2);
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+      expect(warnSpy.mock.calls[0]).toStrictEqual([
+        "[bot-check] bot check observed",
+        {
+          path: "testAction",
+          outcome: "observed",
+          isBot,
+          classificationReason: "reason-x",
+          bypassed: false,
+          isVerifiedBot: false,
+          host: "spoke.example",
+          forwardedHost: null,
+          proxied: false,
+        },
+      ]);
+      expect(errorSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  it("a check that throws logs the failure and passes", async () => {
+    process.env.AILK_BOT_CHECK = "observe";
+    checkBotIdMock.mockRejectedValue(new Error("token abc"));
+    expect(await runBotCheck(CHECK)).toBe("pass");
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy).toHaveBeenCalledWith("[bot-check] bot check failed", {
+      path: "testAction",
+      outcome: "bot-check-failed",
+      error: "Error",
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("AILK_BOOKING_BOT_CHECK=off still passes the booking without asking BotID", async () => {
+    process.env.AILK_BOT_CHECK = "observe";
+    process.env.AILK_BOOKING_BOT_CHECK = "off";
+    checkBotIdMock.mockResolvedValue(BOT);
+    expect(await runBotCheck({ ...CHECK, scope: "booking" })).toBe("pass");
+    expect(checkBotIdMock).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/web/lib/__tests__/in-page-magnet-self-request.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @jest-environment node
+ */
+// #10553 — with AILK_API_URL unset the API client falls back to
+// localhost:3001; a site server bound to 3001 then fetched its own
+// /v1/flows/newsletter, whose render (the footer reads the magnet on every
+// page) fetched it again, without end. The page's flow read now makes no
+// request to its own address and renders without the magnet, and a hub that
+// does not answer is asked once however many renders read it.
+//
+// Through the real `@working-theory/api-client` (jest maps it to source) with
+// the global `fetch` stubbed; the Server Action modules are stubbed as in
+// in-page-magnet.test.ts.
+
+export {};
+
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: a "use server" boundary the module only binds
+jest.mock("../../app/[locale]/contact/contact.actions", () => ({
+  captureLeadAction: jest.fn(),
+}));
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: a "use server" boundary the module only binds
+jest.mock("../newsletter.actions", () => ({
+  subscribeNewsletterAction: jest.fn(),
+}));
+
+const ENV_KEYS = [
+  "AILK_API_URL",
+  "NEXT_PUBLIC_AILK_API_URL",
+  "NEXT_PUBLIC_API_URL",
+  "AILK_SPOKE_KEY",
+  "__NEXT_PRIVATE_ORIGIN",
+] as const;
+const priorEnv = new Map<string, string | undefined>(
+  ENV_KEYS.map((name) => [name, process.env[name]]),
+);
+const priorFetch = global.fetch;
+const fetchMock = jest.fn(async (_url: string) => {
+  throw new TypeError("fetch failed");
+});
+
+/** A fresh `in-page-magnet` module, so the shared read starts empty. */
+function freshModule(): typeof import("../in-page-magnet") {
+  let mod: typeof import("../in-page-magnet") | undefined;
+  jest.isolateModules(() => {
+    mod = jest.requireActual("../in-page-magnet");
+  });
+  if (mod === undefined) throw new Error("in-page-magnet did not load");
+  return mod;
+}
+
+beforeEach(() => {
+  for (const name of ENV_KEYS) delete process.env[name];
+  fetchMock.mockClear();
+  global.fetch = fetchMock as jest.Mock;
+});
+
+afterAll(() => {
+  global.fetch = priorFetch;
+  for (const [name, value] of priorEnv) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+describe("the flow read with AILK_API_URL unset (#10553)", () => {
+  it("on a server bound to the fallback's port, makes no request to its own /v1 and renders without the magnet", async () => {
+    process.env.__NEXT_PRIVATE_ORIGIN = "http://localhost:3001";
+    const { readServedMagnet } = freshModule();
+
+    const renders = await Promise.all(
+      Array.from({ length: 20 }, () => readServedMagnet("newsletter")),
+    );
+
+    expect(renders.every((config) => config === null)).toBe(true);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("on any other port, asks the unanswering fallback once for the flow and renders without it", async () => {
+    process.env.__NEXT_PRIVATE_ORIGIN = "http://localhost:3000";
+    const { readServedMagnet } = freshModule();
+
+    const first = await readServedMagnet("newsletter");
+    const again = await Promise.all(
+      Array.from({ length: 20 }, () => readServedMagnet("newsletter")),
+    );
+
+    expect(first).toBeNull();
+    expect(again.every((config) => config === null)).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("http://localhost:3001/v1/flows/newsletter");
+  });
+});