create-ailk 0.12.1 → 0.14.0

package/templates/apps/web/lib/__tests__/profile-back-link.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Tests for the profile back-link rule (#7744 D7).
+ *
+ * On a deck home, a team profile's back arrow returns to the home's people
+ * slide (`#slide-people`, #7740's anchor for the section id `people`);
+ * everywhere else it goes home. Covers bare and locale-prefixed profiles, the
+ * `/team` index, near misses, a non-deck home and the absent-header fail-safe.
+ */
+
+import {
+  backLinkHref,
+  isTeamProfilePath,
+  PEOPLE_SLIDE_ANCHOR,
+} from "../profile-back-link";
+
+const LOCALES = ["en", "fr"];
+
+describe("isTeamProfilePath", () => {
+  it.each(["/team/first-member", "/fr/team/first-member", "/en/team/a"])(
+    "is true for the profile path %s",
+    (pathname) => {
+      expect(isTeamProfilePath(pathname, LOCALES)).toBe(true);
+    },
+  );
+
+  it.each([
+    "/team",
+    "/team/",
+    "/fr/team",
+    "/team/a/b",
+    "/teams/x",
+    "/about",
+    "/",
+    "",
+  ])("is false for %s", (pathname) => {
+    expect(isTeamProfilePath(pathname, LOCALES)).toBe(false);
+  });
+
+  it("treats a prefix that is not an enabled locale as the first segment", () => {
+    expect(isTeamProfilePath("/xx/team/a", ["en"])).toBe(false);
+  });
+
+  it("answers false for an absent pathname", () => {
+    expect(isTeamProfilePath(null, LOCALES)).toBe(false);
+    expect(isTeamProfilePath(undefined, LOCALES)).toBe(false);
+  });
+});
+
+describe("backLinkHref", () => {
+  it("names the people-slide anchor", () => {
+    expect(PEOPLE_SLIDE_ANCHOR).toBe("slide-people");
+  });
+
+  it("returns /#slide-people for a profile on a deck home", () => {
+    expect(
+      backLinkHref({
+        pathname: "/team/first-member",
+        homePath: "/",
+        home: "deck",
+        locales: LOCALES,
+      }),
+    ).toBe("/#slide-people");
+  });
+
+  it("keeps the /fr prefix on a non-default locale", () => {
+    expect(
+      backLinkHref({
+        pathname: "/fr/team/first-member",
+        homePath: "/fr",
+        home: "deck",
+        locales: LOCALES,
+      }),
+    ).toBe("/fr#slide-people");
+  });
+
+  it.each(["/team", "/team/a/b", "/about", "/teams/x", null, undefined])(
+    "returns the home for %s on a deck home",
+    (pathname) => {
+      expect(
+        backLinkHref({ pathname, homePath: "/", home: "deck", locales: LOCALES }),
+      ).toBe("/");
+    },
+  );
+
+  it("returns the home for a profile when the home is not a deck", () => {
+    expect(
+      backLinkHref({
+        pathname: "/team/first-member",
+        homePath: "/",
+        home: "default",
+        locales: LOCALES,
+      }),
+    ).toBe("/");
+  });
+});

package/templates/apps/web/lib/__tests__/relay.test.ts

@@ -0,0 +1,515 @@
+/**
+ * @jest-environment node
+ */
+// The same-origin relay (#7644): the site serves the root-relative /v1 paths
+// its own browser forms post to and forwards each, server-side, to the hub.
+//
+// Drives `handleRelay` with real `Request` objects through the real
+// `relayToApi` (jest maps @working-theory/api-client to source), with the
+// global `fetch` — the hub — stubbed.
+//
+// Spec: docs/specs/7644-the-browser-talks-only-to-spec.md §5.1 AC-1 to AC-4.
+
+import { handleRelay, RELAY_ROUTES } from "../relay";
+
+const HUB = "https://hub.example";
+const SITE = "https://spoke.example";
+const K1 = "K1";
+const FORWARD_KEY = "FWD";
+const BODY = '{"siteId":"x","email":"a@b.example"}';
+const QUERY = "?calLink=acme/intro&start=2026-10-05";
+
+const ENV_KEYS = [
+  "AILK_API_URL",
+  "NEXT_PUBLIC_AILK_API_URL",
+  "NEXT_PUBLIC_API_URL",
+  "AILK_SPOKE_KEY",
+  "AILK_VISITOR_FORWARD_KEY",
+] as const;
+const priorEnv = new Map<string, string | undefined>(
+  ENV_KEYS.map((name) => [name, process.env[name]]),
+);
+
+function hubAnswer(
+  status = 201,
+  body = '{"id":"lead_1","persisted":"db"}',
+  headers: Record<string, string> = { "content-type": "application/json" },
+): Response {
+  return new Response(body, { status, headers });
+}
+
+const fetchMock = jest.fn(async (_url: string, _init: RequestInit) =>
+  hubAnswer(),
+);
+const priorFetch = global.fetch;
+
+/** The `(url, init)` of the one hub call. */
+function sent(): { url: string; init: RequestInit; headers: Headers } {
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+  const call = fetchMock.mock.calls[0];
+  if (!call) throw new Error("the hub was not called");
+  const [url, init] = call;
+  return { url, init, headers: new Headers(init.headers) };
+}
+
+const SAME_ORIGIN = {
+  origin: SITE,
+  "sec-fetch-site": "same-origin",
+};
+
+/**
+ * A request to the relay at `path`. A same-origin browser POST by default:
+ * `host: spoke.example`, its own `Origin`, `Sec-Fetch-Site: same-origin`
+ * and a JSON body. `headers` overrides; a `null` value removes the header.
+ */
+function relayRequest(
+  path: string,
+  {
+    method = "POST",
+    headers = {},
+    body = BODY,
+  }: {
+    method?: string;
+    headers?: Record<string, string | null>;
+    body?: string;
+  } = {},
+): Request {
+  const merged: Record<string, string | null> = {
+    host: "spoke.example",
+    ...SAME_ORIGIN,
+    ...(method === "POST" ? { "content-type": "application/json" } : {}),
+    ...headers,
+  };
+  const init: RequestInit = {
+    method,
+    headers: Object.fromEntries(
+      Object.entries(merged).filter(
+        (entry): entry is [string, string] => entry[1] !== null,
+      ),
+    ),
+  };
+  if (method === "POST") init.body = body;
+  return new Request(`${SITE}${path}`, init);
+}
+
+async function errorCode(res: Response): Promise<string | undefined> {
+  const json = (await res.json()) as { ok?: boolean; error?: { code?: string } };
+  expect(json.ok).toBe(false);
+  return json.error?.code;
+}
+
+const ENTRIES: ReadonlyArray<{ method: "GET" | "POST"; path: string }> = [
+  { method: "POST", path: "/v1/leads/submit" },
+  { method: "POST", path: "/v1/leads/subscribe" },
+  { method: "POST", path: "/v1/leads/callback" },
+  { method: "GET", path: "/v1/schedule/availability" },
+  { method: "POST", path: "/v1/schedule/book" },
+  { method: "POST", path: "/v1/commerce/invoices" },
+];
+const VISITOR_ENTRIES = ENTRIES.filter(
+  (e) => e.path !== "/v1/commerce/invoices",
+);
+
+/** The relay request for one D2 entry, with the GET's query string. */
+function entryRequest(
+  entry: { method: string; path: string },
+  headers: Record<string, string | null> = {},
+): Request {
+  return relayRequest(
+    entry.method === "GET" ? `${entry.path}${QUERY}` : entry.path,
+    { method: entry.method, headers },
+  );
+}
+
+let errorSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  fetchMock.mockClear();
+  fetchMock.mockImplementation(async () => hubAnswer());
+  global.fetch = fetchMock as jest.Mock;
+  for (const name of ENV_KEYS) delete process.env[name];
+  process.env.AILK_API_URL = HUB;
+  process.env.AILK_SPOKE_KEY = K1;
+  errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  errorSpy.mockRestore();
+});
+
+afterAll(() => {
+  global.fetch = priorFetch;
+  for (const [name, value] of priorEnv) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+describe("AC-1 — forwarding, one entry each", () => {
+  it.each(ENTRIES)(
+    "$method $path is forwarded once, unchanged, and its answer passed back",
+    async (entry) => {
+      const res = await handleRelay(entryRequest(entry));
+
+      const { url, init } = sent();
+      expect(url).toBe(
+        `${HUB}${entry.path}${entry.method === "GET" ? QUERY : ""}`,
+      );
+      expect(init.method).toBe(entry.method);
+      if (entry.method === "POST") expect(init.body).toBe(BODY);
+      else expect(init.body).toBeUndefined();
+
+      expect(res.status).toBe(201);
+      expect(await res.text()).toBe('{"id":"lead_1","persisted":"db"}');
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(res.headers.get("cache-control")).toBe("no-store");
+    },
+  );
+
+  it("forwards the body byte-for-byte, never re-serialised", async () => {
+    const body = '{ "b":1,\n  "a" : [2, 1] }';
+    await handleRelay(relayRequest("/v1/leads/submit", { body }));
+    expect(sent().init.body).toBe(body);
+  });
+
+  it("drops a query string on a POST entry", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit?x=1"));
+    expect(sent().url).toBe(`${HUB}/v1/leads/submit`);
+  });
+
+  it("passes the hub's 429 and retry-after through", async () => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(429, '{"ok":false}', {
+        "content-type": "application/json",
+        "retry-after": "30",
+      }),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(429);
+    expect(res.headers.get("retry-after")).toBe("30");
+    expect(await res.text()).toBe('{"ok":false}');
+  });
+
+  it("answers 502 relay_unreachable when the hub cannot be reached", async () => {
+    fetchMock.mockImplementation(async () => {
+      throw new TypeError("fetch failed");
+    });
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(502);
+    expect(await errorCode(res)).toBe("relay_unreachable");
+  });
+});
+
+describe("AC-2 — only the list", () => {
+  it.each([
+    ["POST", "/v1/workspaces"],
+    ["GET", "/v1/schedule/meeting-types"],
+    ["POST", "/v1/flows/x/steps"],
+    ["GET", "/v1/leads/submit"],
+    ["POST", "/v1/leads/submit/"],
+    ["POST", "/v1/leads/submit/extra"],
+    ["POST", "/v1/Leads/submit"],
+  ])("%s %s answers 404 not_found and calls no hub", async (method, path) => {
+    const res = await handleRelay(relayRequest(path, { method }));
+    expect(res.status).toBe(404);
+    expect(await errorCode(res)).toBe("not_found");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("RELAY_ROUTES is exactly the six D2 pairs, and frozen", () => {
+    expect(RELAY_ROUTES).toEqual(ENTRIES);
+    expect(Object.isFrozen(RELAY_ROUTES)).toBe(true);
+    for (const route of RELAY_ROUTES) expect(Object.isFrozen(route)).toBe(true);
+  });
+});
+
+describe("AC-3 — the key, and only the site's key", () => {
+  it.each(ENTRIES)(
+    "$method $path carries the site's key and refuses redirects",
+    async (entry) => {
+      await handleRelay(entryRequest(entry));
+      const { init, headers } = sent();
+      expect(headers.get("x-ailk-spoke-key")).toBe(K1);
+      expect(init.redirect).toBe("error");
+    },
+  );
+
+  it.each(ENTRIES)(
+    "$method $path without a site key carries none and still works (the single-site path)",
+    async (entry) => {
+      delete process.env.AILK_SPOKE_KEY;
+      const res = await handleRelay(entryRequest(entry));
+      const { init, headers } = sent();
+      expect(headers.get("x-ailk-spoke-key")).toBeNull();
+      expect(init.redirect).toBe("error");
+      expect(res.status).toBe(201);
+    },
+  );
+
+  const CLIENT_SENT = {
+    "x-ailk-spoke-key": "EVIL",
+    "x-ailk-visitor-forward-key": "EVIL",
+    "x-ailk-workspace-id": "wksp_x",
+    authorization: "Bearer t",
+  };
+
+  it("a client-sent key, forward key, workspace header and authorization never reach the hub", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit", { headers: CLIENT_SENT }));
+    const { headers } = sent();
+    expect(headers.get("x-ailk-spoke-key")).toBe(K1);
+    expect(headers.get("x-ailk-visitor-forward-key")).toBeNull();
+    expect(headers.get("x-ailk-workspace-id")).toBeNull();
+    expect(headers.get("authorization")).toBeNull();
+  });
+
+  it("with no site key, a client-sent key still never reaches the hub", async () => {
+    delete process.env.AILK_SPOKE_KEY;
+    await handleRelay(relayRequest("/v1/leads/submit", { headers: CLIENT_SENT }));
+    expect(sent().headers.get("x-ailk-spoke-key")).toBeNull();
+  });
+});
+
+describe("AC-4 — the visitor, unchanged; a cross-site post, refused", () => {
+  it("forwards x-forwarded-for and user-agent exactly as received", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: {
+          "x-forwarded-for": "203.0.113.5, 10.0.0.1",
+          "user-agent": "UA/1",
+        },
+      }),
+    );
+    const { headers } = sent();
+    expect(headers.get("x-forwarded-for")).toBe("203.0.113.5, 10.0.0.1");
+    expect(headers.get("user-agent")).toBe("UA/1");
+  });
+
+  it("sends x-real-ip as x-forwarded-for when that is all it has", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "x-real-ip": "203.0.113.9" },
+      }),
+    );
+    expect(sent().headers.get("x-forwarded-for")).toBe("203.0.113.9");
+  });
+
+  it("sends no x-forwarded-for when it has neither", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(sent().headers.get("x-forwarded-for")).toBeNull();
+  });
+
+  it.each(VISITOR_ENTRIES)(
+    "$method $path carries the keyed visitor IP when the site has a forward key",
+    async (entry) => {
+      process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+      await handleRelay(
+        entryRequest(entry, { "x-forwarded-for": "203.0.113.5, 10.0.0.1" }),
+      );
+      const { headers } = sent();
+      expect(headers.get("x-ailk-visitor-ip")).toBe("203.0.113.5");
+      expect(headers.get("x-ailk-visitor-forward-key")).toBe(FORWARD_KEY);
+    },
+  );
+
+  it("POST /v1/commerce/invoices carries no keyed visitor IP", async () => {
+    process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+    await handleRelay(
+      relayRequest("/v1/commerce/invoices", {
+        headers: { "x-forwarded-for": "203.0.113.5" },
+      }),
+    );
+    const { headers } = sent();
+    expect(headers.get("x-ailk-visitor-ip")).toBeNull();
+    expect(headers.get("x-ailk-visitor-forward-key")).toBeNull();
+  });
+
+  it("forwards cookie and origin on /v1/commerce/invoices", async () => {
+    await handleRelay(
+      relayRequest("/v1/commerce/invoices", { headers: { cookie: "s=1" } }),
+    );
+    const { headers } = sent();
+    expect(headers.get("cookie")).toBe("s=1");
+    expect(headers.get("origin")).toBe(SITE);
+  });
+
+  it.each(VISITOR_ENTRIES)(
+    "$method $path forwards neither cookie nor origin",
+    async (entry) => {
+      await handleRelay(entryRequest(entry, { cookie: "s=1" }));
+      const { headers } = sent();
+      expect(headers.get("cookie")).toBeNull();
+      expect(headers.get("origin")).toBeNull();
+    },
+  );
+
+  it.each<[string, Record<string, string | null>]>([
+    ["a foreign origin", { origin: "https://evil.example" }],
+    ["origin: null", { origin: "null" }],
+    ["the same host on another port", { origin: "https://spoke.example:8443" }],
+    [
+      "sec-fetch-site: cross-site with a same-host origin",
+      { "sec-fetch-site": "cross-site" },
+    ],
+    ["sec-fetch-site: same-site", { "sec-fetch-site": "same-site" }],
+  ])("%s answers 403 cross_site and calls no hub", async (_label, headers) => {
+    const res = await handleRelay(relayRequest("/v1/leads/submit", { headers }));
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("cross_site");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("admits an origin that matches the forwarded host behind a proxy", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: {
+          host: "internal:3000",
+          "x-forwarded-host": "spoke.example, proxy",
+        },
+      }),
+    );
+    expect(res.status).toBe(201);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("admits a JSON POST that carries neither origin nor sec-fetch-site (a non-browser caller)", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { origin: null, "sec-fetch-site": null },
+      }),
+    );
+    expect(res.status).toBe(201);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("the forwarded host wins over a matching host header", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { host: "spoke.example", "x-forwarded-host": "proxy.example" },
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("cross_site");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("a POST that is not JSON answers 415", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "content-type": "text/plain" },
+      }),
+    );
+    expect(res.status).toBe(415);
+    expect(await errorCode(res)).toBe("unsupported_media_type");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("admits a JSON content-type with parameters, in any case", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "content-type": "Application/JSON; charset=utf-8" },
+      }),
+    );
+    expect(res.status).toBe(201);
+  });
+
+  it("a body over 1 MiB answers 413", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { body: "x".repeat(1_048_577) }),
+    );
+    expect(res.status).toBe(413);
+    expect(await errorCode(res)).toBe("payload_too_large");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("a body of exactly 1 MiB is forwarded", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { body: "x".repeat(1_048_576) }),
+    );
+    expect(res.status).toBe(201);
+  });
+
+  it("a request already relayed answers 508 relay_loop", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { headers: { "x-ailk-relayed": "1" } }),
+    );
+    expect(res.status).toBe(508);
+    expect(await errorCode(res)).toBe("relay_loop");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("marks every forwarded call so a self-pointing hub address cannot loop", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(sent().headers.get("x-ailk-relayed")).toBe("1");
+  });
+
+  it("forwards nothing outside its allow-list", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "x-custom": "1", "accept-language": "en" },
+      }),
+    );
+    const names = [...sent().headers.keys()].sort();
+    expect(names).toEqual(["content-type", "x-ailk-relayed", "x-ailk-spoke-key"]);
+  });
+});
+
+describe("hardening — what the site serves, and a missing hub address", () => {
+  const mediaType = (res: Response) =>
+    res.headers.get("content-type")?.split(";")[0]?.trim();
+
+  it("passes a JSON content-type through as the hub sent it", async () => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(201, "{}", { "content-type": "application/json; charset=utf-8" }),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.headers.get("content-type")).toBe(
+      "application/json; charset=utf-8",
+    );
+  });
+
+  it.each([
+    ["an HTML error page", { "content-type": "text/html" }],
+    ["no content-type at all", {}],
+  ])("serves %s from the hub as text/plain, never as markup", async (_label, headers) => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(502, "<p>bad gateway</p>", headers),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(502);
+    expect(mediaType(res)).toBe("text/plain");
+    expect(await res.text()).toBe("<p>bad gateway</p>");
+  });
+
+  it("marks every relayed answer and every refusal nosniff", async () => {
+    const relayed = await handleRelay(relayRequest("/v1/leads/submit"));
+    const refused = await handleRelay(relayRequest("/v1/nope"));
+    expect(relayed.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(refused.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(mediaType(refused)).toBe("application/json");
+  });
+
+  describe("in production", () => {
+    const env = process.env as Record<string, string | undefined>;
+    const priorNodeEnv = env.NODE_ENV;
+    beforeEach(() => {
+      env.NODE_ENV = "production";
+    });
+    afterEach(() => {
+      env.NODE_ENV = priorNodeEnv;
+    });
+
+    it("answers 502 relay_unreachable and calls nothing when no hub address is set", async () => {
+      delete process.env.AILK_API_URL;
+      const res = await handleRelay(relayRequest("/v1/leads/submit"));
+      expect(res.status).toBe(502);
+      expect(await errorCode(res)).toBe("relay_unreachable");
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it("forwards as usual when a hub address is set", async () => {
+      const res = await handleRelay(relayRequest("/v1/leads/submit"));
+      expect(res.status).toBe(201);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/templates/apps/web/lib/__tests__/site-theme-head.test.ts

@@ -0,0 +1,70 @@
+/**
+ * `siteThemeHead` (#7742 D6 / AC-4) — the one helper behind the locale
+ * layout's `<style data-ailk="theme-vars">` and `<html>` class and the minimal
+ * 404's. Pinned against the expressions the layout computed inline before the
+ * extraction, so moving them into the helper changed no byte of the `<style>`
+ * text; `layout.test.tsx` and `site-fonts.test.tsx` pin the layout's own
+ * emitted text over it.
+ */
+import { applyDesignFonts, themeToCssVarsBothModes } from "@working-theory/theme";
+
+import type { SiteFonts } from "../site-fonts";
+
+const mockSiteFonts: SiteFonts = { className: "", families: {} };
+// eslint-disable-next-line no-restricted-syntax -- #507: `site-fonts.ts` is a generated data module with no external boundary to mock instead; this is the seam the helper reads.
+jest.mock("../site-fonts", () => ({
+  __esModule: true,
+  siteFonts: mockSiteFonts,
+}));
+
+const mockLoadSiteBrandTokens = jest.fn();
+const mockLoadSiteShapeCss = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- #507: the helper's one seam onto `_site.mdx`; the overlay is the test's to set.
+jest.mock("../site-theme", () => ({
+  __esModule: true,
+  loadSiteBrandTokens: (...args: unknown[]) => mockLoadSiteBrandTokens(...args),
+  loadSiteShapeCss: (...args: unknown[]) => mockLoadSiteShapeCss(...args),
+}));
+
+import { siteThemeHead } from "../site-theme-head";
+
+/** The locale layout's pre-#7742 inline computation, verbatim. */
+function layoutStyleText(): { css: string; className: string | undefined } {
+  const designFonts = applyDesignFonts(mockLoadSiteBrandTokens(), mockSiteFonts);
+  return {
+    css:
+      themeToCssVarsBothModes(designFonts.tokens ? { brand: designFonts.tokens } : {}) +
+      mockLoadSiteShapeCss(),
+    className: designFonts.className || undefined,
+  };
+}
+
+beforeEach(() => {
+  Object.assign(mockSiteFonts, { className: "", families: {} });
+  mockLoadSiteBrandTokens.mockReset().mockReturnValue(undefined);
+  mockLoadSiteShapeCss.mockReset().mockReturnValue("");
+});
+
+describe("siteThemeHead (#7742 D6)", () => {
+  it("no theme and no faces: today's CSS and no class", () => {
+    const head = siteThemeHead();
+    expect(head.css).toBe(themeToCssVarsBothModes({}));
+    expect(head.css).toBe(layoutStyleText().css);
+    expect(head.fontClassName).toBeUndefined();
+  });
+
+  it("a brand overlay, shape CSS and design faces: the layout's exact text and class", () => {
+    mockLoadSiteBrandTokens.mockReturnValue({ font: { body: "Brand" } });
+    mockLoadSiteShapeCss.mockReturnValue(":root{--radius-control:0}");
+    Object.assign(mockSiteFonts, {
+      className: "f1 f2",
+      families: { display: "var(--font-design-display), Georgia, serif" },
+    });
+    const head = siteThemeHead();
+    const expected = layoutStyleText();
+    expect(head.css).toBe(expected.css);
+    expect(head.css).toContain("--font-body: Brand;");
+    expect(head.css.endsWith(":root{--radius-control:0}")).toBe(true);
+    expect(head.fontClassName).toBe(expected.className);
+  });
+});