create-ailk 0.21.0 → 0.22.0

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

@@ -0,0 +1,89 @@
+"use client"; // Reads sessionStorage (a browser API) once on mount — a server page cannot.
+
+/**
+ * AccountInviteLink — the /thanks page's "Track this in your account" link
+ * (#8771 D6). The magnet walk writes one `sessionStorage` item,
+ * `ailk:account-invite`, before it navigates here; this shows the link only
+ * for the thank-you page that walk was headed to, and only if the stored href
+ * is a same-site sign-in path. It reads the item once and removes it, so the
+ * email in the href does not stay in the tab. A refresh shows no link (the
+ * invite email still carries it).
+ *
+ * Base tree: it imports nothing from `flows/**`, so a build without the walk
+ * still compiles this page.
+ */
+import { Button, Container, Link } from "@working-theory/ui";
+import type { ReactElement } from "react";
+import { useEffect, useState } from "react";
+
+/** Must equal `ACCOUNT_INVITE_STORAGE_KEY` in the walk's `FlowStepperClient`. */
+const STORAGE_KEY = "ailk:account-invite";
+/** A reserved name that never resolves: only used to test an href stays on-site. */
+const PLACEHOLDER_ORIGIN = "https://placeholder.invalid";
+const HUB_SIGN_IN_PATH = "/api/hub-session/sign-in";
+
+interface Props {
+  /** The route's `[slug]` — the hand-off must have been written for this page. */
+  thanksSlug: string;
+  /** `contact.trackInAccount`, read on the server. */
+  label: string;
+}
+
+/** The stored href when it is a same-site sign-in path, else `null`. */
+function safeSignInHref(raw: unknown, thanks: unknown, thanksSlug: string): string | null {
+  if (typeof raw !== "string" || thanks !== thanksSlug) return null;
+  let url: URL;
+  try {
+    url = new URL(raw, PLACEHOLDER_ORIGIN);
+  } catch {
+    return null;
+  }
+  if (url.origin !== PLACEHOLDER_ORIGIN) return null;
+  if (url.pathname !== HUB_SIGN_IN_PATH && !url.pathname.endsWith("/sign-in")) {
+    return null;
+  }
+  return raw;
+}
+
+/** Read the hand-off once, remove it, and answer the link to show (or `null`). */
+function takeHandOff(thanksSlug: string): string | null {
+  try {
+    const stored = window.sessionStorage.getItem(STORAGE_KEY);
+    if (stored === null) return null;
+    window.sessionStorage.removeItem(STORAGE_KEY);
+    const parsed: unknown = JSON.parse(stored);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const { thanks, href } = parsed as { thanks?: unknown; href?: unknown };
+    return safeSignInHref(href, thanks, thanksSlug);
+  } catch {
+    return null;
+  }
+}
+
+export function AccountInviteLink({ thanksSlug, label }: Props): ReactElement | null {
+  const [href, setHref] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Only ever sets the link: React's development double-mount runs this
+    // twice, and the second run finds the item already removed.
+    const found = takeHandOff(thanksSlug);
+    if (found !== null) setHref(found);
+  }, [thanksSlug]);
+
+  if (href === null) return null;
+  return (
+    // Session Replay records the DOM, so the link (it carries the email) is
+    // blocked from it; `Link` does not forward an undeclared data-* attribute.
+    // The page shell sets no gutters, so the link sits in its own Container,
+    // lined up with the thank-you content above it.
+    <Container className="pb-section">
+      <div data-sentry-block>
+        <Button asChild variant="outline" className="min-h-11">
+          <Link href={href} variant="bare" data-testid="thanks-account-invite">
+            {label}
+          </Link>
+        </Button>
+      </div>
+    </Container>
+  );
+}

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

@@ -0,0 +1,104 @@
+/**
+ * #8771 AC-5 — /thanks shows only its own hand-off: the walk's sessionStorage
+ * item, for this page's slug, when its href is a same-site sign-in path.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+import React, { StrictMode } from "react";
+
+import { AccountInviteLink } from "../AccountInviteLink";
+
+const KEY = "ailk:account-invite";
+const LABEL = "Track this in your account";
+const SITE_HREF = "/sign-in?next=%2Faccount&email=jane%40example.com";
+const HUB_HREF = "/api/hub-session/sign-in?next=%2Faccount&email=x%40y.example";
+const WALK = join(__dirname, "..", "..", "..", "flows", "[slug]", "FlowStepperClient.tsx");
+// A Free scaffold ships no magnet walk, and the scaffold matrix runs this suite
+// inside one (#8799), so the key check skips where the walk does not exist.
+const itWithWalk = existsSync(WALK) ? it : it.skip;
+
+function store(value: unknown): void {
+  window.sessionStorage.setItem(KEY, typeof value === "string" ? value : JSON.stringify(value));
+}
+
+function show(slug = "flow-thanks") {
+  return render(<AccountInviteLink thanksSlug={slug} label={LABEL} />);
+}
+
+beforeEach(() => window.sessionStorage.clear());
+
+describe("AccountInviteLink", () => {
+  it("renders the stored link for its own slug, blocked from Replay, and removes the item", () => {
+    store({ thanks: "flow-thanks", href: SITE_HREF });
+
+    show();
+
+    const link = screen.getByTestId("thanks-account-invite");
+    expect(link).toHaveAttribute("href", SITE_HREF);
+    expect(link).toHaveTextContent(LABEL);
+    expect(link.closest("[data-sentry-block]")).not.toBeNull();
+    expect(window.sessionStorage.getItem(KEY)).toBeNull();
+  });
+
+  it("renders a hub spoke's sign-in path under the matching slug", () => {
+    store({ thanks: "flow-thanks", href: HUB_HREF });
+    show();
+    expect(screen.getByTestId("thanks-account-invite")).toHaveAttribute("href", HUB_HREF);
+  });
+
+  it("renders a locale-prefixed site sign-in path", () => {
+    store({ thanks: "flow-thanks", href: "/fr/sign-in?email=a%40b.example" });
+    show();
+    expect(screen.getByTestId("thanks-account-invite")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["another slug", { thanks: "other", href: SITE_HREF }, "flow-thanks"],
+    ["an off-site href", { thanks: "flow-thanks", href: "https://evil.example/sign-in" }, "flow-thanks"],
+    ["a protocol-relative href", { thanks: "flow-thanks", href: "//evil.example/sign-in" }, "flow-thanks"],
+    ["a non-sign-in path", { thanks: "flow-thanks", href: "/account" }, "flow-thanks"],
+    ["a hub href under another thanks", { thanks: "flow-thanks-qualified", href: HUB_HREF }, "flow-thanks"],
+    ["a value that is not JSON", "not json", "flow-thanks"],
+    ["a JSON null", "null", "flow-thanks"],
+  ])("renders nothing for %s", (_name, value, slug) => {
+    store(value);
+    show(slug);
+    expect(screen.queryByTestId("thanks-account-invite")).toBeNull();
+  });
+
+  it("renders nothing when sessionStorage throws", () => {
+    const spy = jest.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("denied");
+    });
+    show();
+    expect(screen.queryByTestId("thanks-account-invite")).toBeNull();
+    spy.mockRestore();
+  });
+
+  it("shows the link once: a fresh mount after it (a refresh) renders nothing", () => {
+    store({ thanks: "flow-thanks", href: SITE_HREF });
+    const first = show();
+    expect(screen.getByTestId("thanks-account-invite")).toBeInTheDocument();
+    first.unmount();
+
+    show();
+    expect(screen.queryByTestId("thanks-account-invite")).toBeNull();
+  });
+
+  it("keeps the link under React.StrictMode's double effect", () => {
+    store({ thanks: "flow-thanks", href: SITE_HREF });
+    render(
+      <StrictMode>
+        <AccountInviteLink thanksSlug="flow-thanks" label={LABEL} />
+      </StrictMode>,
+    );
+    expect(screen.getByTestId("thanks-account-invite")).toBeInTheDocument();
+  });
+
+  itWithWalk("reads the same storage key the walk writes (the two constants are tied only by this test)", () => {
+    const walk = readFileSync(WALK, "utf8");
+    expect(walk).toContain(`ACCOUNT_INVITE_STORAGE_KEY = "${KEY}"`);
+  });
+});

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

@@ -37,6 +37,23 @@ jest.mock("@working-theory/ui", () => ({
     }),
 }));
 
+// #8771 D6 — the page reads the link label on the server and renders the client
+// component that owns the hand-off; this file asserts only that wiring.
+jest.mock("next-intl/server", () => ({
+  getTranslations: jest.fn().mockResolvedValue((key: string) => `label:${key}`),
+}));
+// eslint-disable-next-line no-restricted-syntax -- the page's wiring is the unit under test; the component has its own suite
+jest.mock("../AccountInviteLink", () => ({
+  AccountInviteLink: ({ thanksSlug, label }: { thanksSlug: string; label: string }) =>
+    React.createElement("div", {
+      "data-testid": "account-invite-link",
+      "data-slug": thanksSlug,
+      "data-label": label,
+    }),
+}));
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { notFound } from "next/navigation";
 import ThankYouSlugPage from "../page";
 
@@ -93,4 +110,25 @@ describe("ThankYouSlugPage — detail route", () => {
     ).rejects.toThrow("NEXT_NOT_FOUND");
     expect(mockNotFound).toHaveBeenCalled();
   });
+
+  it("renders AccountInviteLink with the route's slug and the contact label (#8771)", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue(makeThankYouSource("flow-thanks"));
+
+    const element = await ThankYouSlugPage({
+      params: Promise.resolve({ locale: "en", slug: "flow-thanks" }),
+      getMdxSource,
+    });
+    const { container } = render(element);
+
+    const link = container.querySelector('[data-testid="account-invite-link"]');
+    // Inside the page's own <main>, not after it (#8771 design review).
+    expect(link?.closest("main")).not.toBeNull();
+    expect(link).toHaveAttribute("data-slug", "flow-thanks");
+    expect(link).toHaveAttribute("data-label", "label:trackInAccount");
+  });
+
+  it("stays a server page: the module has no client directive (#8771)", () => {
+    const source = readFileSync(join(__dirname, "..", "page.tsx"), "utf8");
+    expect(source).not.toMatch(/["']use client["']/);
+  });
 });

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

@@ -7,8 +7,11 @@
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
 import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
 
+import { AccountInviteLink } from "./AccountInviteLink";
+
 interface Props {
   params: Promise<{ locale: string; slug: string }>;
   getMdxSource?: typeof defaultGetMdxSource;
@@ -26,11 +29,17 @@ export default async function Page({
   getMdxSource,
 }: Props): Promise<ReactElement> {
   const { locale, slug } = await params;
+  // #8771 D6 — the magnet walk's "Track this in your account" hand-off. The
+  // page stays a server page; the client component decides if it has a link.
+  // It renders through `trailing`, inside the page's own <main>, so it keeps
+  // the page's landmark and layout rather than sitting after `</main>`.
+  const t = await getTranslations({ locale, namespace: "contact" });
   return renderPage({
     type: "ThankYouPage",
     slug,
     locale,
     populatedDescriptionTestId: "thank-you-description",
+    trailing: <AccountInviteLink thanksSlug={slug} label={t("trackInAccount")} />,
     ...(getMdxSource !== undefined && { getMdxSource }),
   });
 }

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

@@ -62,7 +62,7 @@ describe("whitepapers/[slug] — snapshot regression", () => {
     });
     const { container } = render(element);
     expect(container.innerHTML).toMatchInlineSnapshot(`
-     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"AILK AEO Strategy 2026","description":"In-depth research on answer engine optimization for AILK products.","mainEntity":{"@context":"https://schema.org","@type":"Article","headline":"AILK AEO Strategy 2026","description":"In-depth research on answer engine optimization for AILK products."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Whitepapers","item":"http://localhost:3000/en/whitepapers"},{"@type":"ListItem","position":3,"name":"AILK AEO Strategy 2026","item":"http://localhost:3000/en/whitepapers/ailk-aeo-strategy-2026"}]}]}</script><main id="main"><div class="mx-auto w-full max-w-container-xl px-4 md:px-6 lg:px-8 py-section"><h1 class="text-heading-1 lg:text-display-sm font-display text-fg hero-type-display">AILK AEO Strategy 2026</h1><p data-testid="whitepaper-description" class="mt-block-tight text-lead">In-depth research on answer engine optimization for AILK products.</p><div data-testid="markdown-view-toggle" class="ailk-markdown-view-toggle mt-block-loose"><div class="flex justify-end mb-3"><div role="radiogroup" aria-label="Page view" data-testid="markdown-view-toggle" class="inline-flex items-center gap-0.5 rounded-lg p-1 bg-(--color-surface-secondary)"><button class="inline-flex items-center justify-center gap-2 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) hover:bg-(--color-surface-secondary) active:bg-gray-200 rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) bg-(--color-bg) text-(--color-fg) shadow-sm" type="button" role="radio" aria-checked="true" aria-label="Rendered" tabindex="0" data-testid="markdown-view-toggle-rendered">Rendered</button><button class="inline-flex items-center justify-center gap-2 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) hover:bg-(--color-surface-secondary) active:bg-gray-200 rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) text-(--color-text-muted) hover:text-(--color-fg)" type="button" role="radio" aria-checked="false" aria-label="Markdown" tabindex="-1" data-testid="markdown-view-toggle-markdown">Markdown</button></div></div><div role="status" aria-live="polite" aria-atomic="true" class="sr-only" data-testid="markdown-view-toggle-status">Showing Rendered view</div><div data-testid="markdown-view-rendered"><article data-testid="mdx-body"><div class="ailk-prose max-w-none text-(--color-text-muted) text-body-sm leading-relaxed [&amp;>*:first-child]:mt-0 [&amp;_h2]:mt-block-loose [&amp;_h2]:scroll-mt-24 [&amp;_h2]:text-heading-3 [&amp;_h2]:font-display [&amp;_h2]:text-(--color-fg) [&amp;_h3]:mt-block-loose [&amp;_h3]:scroll-mt-24 [&amp;_h3]:text-heading-4 [&amp;_h3]:font-display [&amp;_h3]:text-(--color-fg) [&amp;_h4]:mt-block-tight [&amp;_h4]:scroll-mt-24 [&amp;_h4]:text-heading-4 [&amp;_h4]:font-display [&amp;_h4]:text-(--color-fg) [&amp;_h5]:mt-block-tight [&amp;_h5]:scroll-mt-24 [&amp;_h5]:text-heading-4 [&amp;_h5]:font-display [&amp;_h5]:text-(--color-fg) [&amp;_h6]:mt-block-tight [&amp;_h6]:scroll-mt-24 [&amp;_h6]:text-heading-4 [&amp;_h6]:font-display [&amp;_h6]:text-(--color-fg) [&amp;_p]:mt-paragraph [&amp;_strong]:font-semibold [&amp;_strong]:text-(--color-fg) [&amp;_em]:italic [&amp;_ul]:mt-paragraph [&amp;_ul]:list-disc [&amp;_ul]:ps-6 [&amp;_ol]:mt-paragraph [&amp;_ol]:list-decimal [&amp;_ol]:ps-6 [&amp;_li]:mt-1 [&amp;_li]:ps-1 [&amp;_li]:marker:text-(--color-text-muted) [&amp;_li>ul]:mt-1 [&amp;_li>ol]:mt-1 [&amp;_blockquote]:mt-paragraph [&amp;_blockquote]:border-s-4 [&amp;_blockquote]:border-(--color-border-strong) [&amp;_blockquote]:ps-4 [&amp;_blockquote]:italic [&amp;_blockquote]:text-(--color-text-muted) [&amp;_hr]:my-block-loose [&amp;_hr]:border-(--color-border) [&amp;_a]:text-(--color-accent) [&amp;_a]:underline [&amp;_a]:underline-offset-4 [&amp;_:not(pre)>code]:rounded [&amp;_:not(pre)>code]:bg-(--color-surface-secondary) [&amp;_:not(pre)>code]:px-1.5 [&amp;_:not(pre)>code]:py-0.5 [&amp;_:not(pre)>code]:text-code [&amp;_:not(pre)>code]:font-mono [&amp;_:not(pre)>code]:text-(--color-fg) [&amp;_pre]:mt-paragraph [&amp;_pre]:overflow-auto [&amp;_pre]:rounded-md [&amp;_pre]:border-hairline [&amp;_pre]:border-(--color-border) [&amp;_pre]:bg-(--color-bg) [&amp;_pre]:p-4 [&amp;_pre]:font-mono [&amp;_pre]:text-body-sm [&amp;_img]:mt-paragraph [&amp;_img]:h-auto [&amp;_img]:max-w-full [&amp;_img]:rounded-lg [&amp;_table]:mt-paragraph [&amp;_table]:w-full [&amp;_table]:border-collapse [&amp;_table]:text-body-sm [&amp;_th]:border-b [&amp;_th]:border-(--color-border) [&amp;_th]:bg-(--color-surface-secondary) [&amp;_th]:px-3 [&amp;_th]:py-2 [&amp;_th]:text-start [&amp;_th]:font-semibold [&amp;_th]:text-(--color-fg) [&amp;_td]:border-b [&amp;_td]:border-(--color-border) [&amp;_td]:px-3 [&amp;_td]:py-2 [&amp;_kbd]:rounded [&amp;_kbd]:border-hairline [&amp;_kbd]:border-(--color-border) [&amp;_kbd]:bg-(--color-surface-secondary) [&amp;_kbd]:px-1.5 [&amp;_kbd]:py-0.5 [&amp;_kbd]:text-caption [&amp;_kbd]:font-mono" data-testid="mdx-content"><div data-testid="mdx-rendered">## Executive Summary
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"AILK AEO Strategy 2026","description":"In-depth research on answer engine optimization for AILK products.","mainEntity":{"@context":"https://schema.org","@type":"Article","headline":"AILK AEO Strategy 2026","description":"In-depth research on answer engine optimization for AILK products."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Whitepapers","item":"http://localhost:3000/en/whitepapers"},{"@type":"ListItem","position":3,"name":"AILK AEO Strategy 2026","item":"http://localhost:3000/en/whitepapers/ailk-aeo-strategy-2026"}]}]}</script><main id="main"><div class="mx-auto w-full max-w-container-xl px-4 md:px-6 lg:px-8 py-section"><h1 class="text-heading-1 lg:text-display-sm font-display text-fg hero-type-display">AILK AEO Strategy 2026</h1><p data-testid="whitepaper-description" class="mt-block-tight text-lead">In-depth research on answer engine optimization for AILK products.</p><div data-testid="markdown-view-toggle" class="ailk-markdown-view-toggle mt-block-loose"><div class="flex justify-end mb-3"><div role="radiogroup" aria-label="Page view" data-testid="markdown-view-toggle" class="inline-flex items-center gap-0.5 rounded-lg p-1 bg-(--color-surface-secondary)"><button class="inline-flex items-center justify-center gap-2 font-medium motion-safe:transition motion-safe:duration-(--button-hover-duration) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) not-disabled:hover:bg-(--button-hover-quiet-bg) not-disabled:hover:text-(--button-hover-quiet-fg) not-disabled:hover:opacity-(--button-hover-opacity) not-disabled:hover:transform-(--button-hover-transform) not-disabled:hover:shadow-(--button-hover-shadow) not-disabled:active:bg-gray-200 not-disabled:active:text-(--color-fg) rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) bg-(--color-bg) text-(--color-fg) shadow-sm" type="button" role="radio" aria-checked="true" aria-label="Rendered" tabindex="0" data-testid="markdown-view-toggle-rendered">Rendered</button><button class="inline-flex items-center justify-center gap-2 font-medium motion-safe:transition motion-safe:duration-(--button-hover-duration) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) not-disabled:hover:bg-(--button-hover-quiet-bg) not-disabled:hover:text-(--button-hover-quiet-fg) not-disabled:hover:opacity-(--button-hover-opacity) not-disabled:hover:transform-(--button-hover-transform) not-disabled:hover:shadow-(--button-hover-shadow) not-disabled:active:bg-gray-200 not-disabled:active:text-(--color-fg) rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) text-(--color-text-muted) hover:text-(--color-fg)" type="button" role="radio" aria-checked="false" aria-label="Markdown" tabindex="-1" data-testid="markdown-view-toggle-markdown">Markdown</button></div></div><div role="status" aria-live="polite" aria-atomic="true" class="sr-only" data-testid="markdown-view-toggle-status">Showing Rendered view</div><div data-testid="markdown-view-rendered"><article data-testid="mdx-body"><div class="ailk-prose max-w-none text-(--color-text-muted) text-body-sm leading-relaxed [&amp;>*:first-child]:mt-0 [&amp;_h2]:mt-block-loose [&amp;_h2]:scroll-mt-24 [&amp;_h2]:text-heading-3 [&amp;_h2]:font-display [&amp;_h2]:text-(--color-fg) [&amp;_h3]:mt-block-loose [&amp;_h3]:scroll-mt-24 [&amp;_h3]:text-heading-4 [&amp;_h3]:font-display [&amp;_h3]:text-(--color-fg) [&amp;_h4]:mt-block-tight [&amp;_h4]:scroll-mt-24 [&amp;_h4]:text-heading-4 [&amp;_h4]:font-display [&amp;_h4]:text-(--color-fg) [&amp;_h5]:mt-block-tight [&amp;_h5]:scroll-mt-24 [&amp;_h5]:text-heading-4 [&amp;_h5]:font-display [&amp;_h5]:text-(--color-fg) [&amp;_h6]:mt-block-tight [&amp;_h6]:scroll-mt-24 [&amp;_h6]:text-heading-4 [&amp;_h6]:font-display [&amp;_h6]:text-(--color-fg) [&amp;_p]:mt-paragraph [&amp;_strong]:font-semibold [&amp;_strong]:text-(--color-fg) [&amp;_em]:italic [&amp;_ul]:mt-paragraph [&amp;_ul]:list-disc [&amp;_ul]:ps-6 [&amp;_ol]:mt-paragraph [&amp;_ol]:list-decimal [&amp;_ol]:ps-6 [&amp;_li]:mt-1 [&amp;_li]:ps-1 [&amp;_li]:marker:text-(--color-text-muted) [&amp;_li>ul]:mt-1 [&amp;_li>ol]:mt-1 [&amp;_blockquote]:mt-paragraph [&amp;_blockquote]:border-s-4 [&amp;_blockquote]:border-(--color-border-strong) [&amp;_blockquote]:ps-4 [&amp;_blockquote]:italic [&amp;_blockquote]:text-(--color-text-muted) [&amp;_hr]:my-block-loose [&amp;_hr]:border-(--color-border) [&amp;_a]:text-(--color-accent) [&amp;_a]:underline [&amp;_a]:underline-offset-4 [&amp;_:not(pre)>code]:rounded [&amp;_:not(pre)>code]:bg-(--color-surface-secondary) [&amp;_:not(pre)>code]:px-1.5 [&amp;_:not(pre)>code]:py-0.5 [&amp;_:not(pre)>code]:text-code [&amp;_:not(pre)>code]:font-mono [&amp;_:not(pre)>code]:text-(--color-fg) [&amp;_pre]:mt-paragraph [&amp;_pre]:overflow-auto [&amp;_pre]:rounded-md [&amp;_pre]:border-hairline [&amp;_pre]:border-(--color-border) [&amp;_pre]:bg-(--color-bg) [&amp;_pre]:p-4 [&amp;_pre]:font-mono [&amp;_pre]:text-body-sm [&amp;_img]:mt-paragraph [&amp;_img]:h-auto [&amp;_img]:max-w-full [&amp;_img]:rounded-lg [&amp;_table]:mt-paragraph [&amp;_table]:w-full [&amp;_table]:border-collapse [&amp;_table]:text-body-sm [&amp;_th]:border-b [&amp;_th]:border-(--color-border) [&amp;_th]:bg-(--color-surface-secondary) [&amp;_th]:px-3 [&amp;_th]:py-2 [&amp;_th]:text-start [&amp;_th]:font-semibold [&amp;_th]:text-(--color-fg) [&amp;_td]:border-b [&amp;_td]:border-(--color-border) [&amp;_td]:px-3 [&amp;_td]:py-2 [&amp;_kbd]:rounded [&amp;_kbd]:border-hairline [&amp;_kbd]:border-(--color-border) [&amp;_kbd]:bg-(--color-surface-secondary) [&amp;_kbd]:px-1.5 [&amp;_kbd]:py-0.5 [&amp;_kbd]:text-caption [&amp;_kbd]:font-mono" data-testid="mdx-content"><div data-testid="mdx-rendered">## Executive Summary
 
      Body content.</div></div></article></div></div></div></main>"
     `);

package/templates/apps/web/app/api/auth/hub/authorize/__tests__/route.test.ts

@@ -10,6 +10,10 @@
  * are the two external boundaries; both are mocked. The route's own decisions
  * are what is under test: which query it accepts, who it sends to sign in,
  * where a minted code goes, and what it refuses to redirect to.
+ *
+ * #8757 D9 (AC-6): an optional `login_hint` reaches the sign-in page as
+ * `email` on the no-session branch only; it never enters the continuation ref
+ * or the code redirect, and a repeated one is a 400 like any repeated key.
  */
 
 // --- Mocks set up BEFORE imports ---
@@ -345,3 +349,113 @@ describe("a signed-in person", () => {
     },
   );
 });
+
+describe("the login_hint (#8757 D9)", () => {
+  const HINT = "a@b.example";
+
+  /** The `next` value of the 303, and the ref inside it. */
+  function continuationOf(res: Response): { next: string; ref: string } {
+    const location = res.headers.get("location") ?? "";
+    const next = new URL(location, HUB).searchParams.get("next") ?? "";
+    return { next, ref: next.slice(`${CONTINUE}/`.length) };
+  }
+
+  it("no session + a valid login_hint: 303 to /sign-in?next=<continue path>&email=a%40b.example; the ref opens to the six-key canonical query alone", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const canonical = query();
+
+    const res = await GET(
+      request(`${canonical}&login_hint=${encodeURIComponent(HINT)}`),
+    );
+
+    expect(res.status).toBe(303);
+    const { next, ref } = continuationOf(res);
+    expect(res.headers.get("location")).toBe(
+      `/sign-in?next=${encodeURIComponent(`${CONTINUE}/${ref}`)}&email=a%40b.example`,
+    );
+    expect(next).toBe(`${CONTINUE}/${ref}`);
+    const opened = openContinuation(ref, mockSecret);
+    expect(opened).toBe(canonical);
+    expect(opened).not.toContain("login_hint");
+    expect(opened).not.toContain("email");
+    expect(mockCreateCode).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["an invalid login_hint", "nope"],
+    ["a login_hint carrying a separator", "a@b.example&next=/x"],
+    ["an over-long login_hint", `${"a".repeat(250)}@b.example`],
+  ])(
+    "no session + %s: dropped — the 303 carries no email",
+    async (_name, hint) => {
+      mockGetSession.mockResolvedValue(null);
+      const canonical = query();
+
+      const res = await GET(
+        request(`${canonical}&login_hint=${encodeURIComponent(hint)}`),
+      );
+
+      expect(res.status).toBe(303);
+      const { ref } = continuationOf(res);
+      expect(res.headers.get("location")).toBe(
+        `/sign-in?next=${encodeURIComponent(`${CONTINUE}/${ref}`)}`,
+      );
+      expect(openContinuation(ref, mockSecret)).toBe(canonical);
+    },
+  );
+
+  it.each([
+    ["no session", null],
+    ["a session", { user: { id: "u1" } }],
+  ])(
+    "a repeated login_hint is a 400 invalid_request (%s)",
+    async (_name, session) => {
+      mockGetSession.mockResolvedValue(session);
+
+      const res = await GET(
+        request(`${query()}&login_hint=a%40b.example&login_hint=c%40d.example`),
+      );
+
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      expect(await res.json()).toEqual({ error: "invalid_request" });
+      expect(mockCreateCode).not.toHaveBeenCalled();
+      expect(mockGetSession).not.toHaveBeenCalled();
+    },
+  );
+
+  it("with a session: the code redirect is unchanged and carries no hint", async () => {
+    mockGetSession.mockResolvedValue({ user: { id: "u1" } });
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    const withHint = await GET(
+      request(`${query()}&login_hint=${encodeURIComponent(HINT)}`, {
+        cookie: "better-auth.session_token=tok",
+      }),
+    );
+    const without = await GET(
+      request(query(), { cookie: "better-auth.session_token=tok" }),
+    );
+
+    expect(withHint.status).toBe(303);
+    const location = withHint.headers.get("location") ?? "";
+    expect(location).toBe(without.headers.get("location"));
+    expect(location).toBe(`${SPOKE_CALLBACK}?code=${CODE}&state=${STATE}`);
+    expect(location).not.toContain("login_hint");
+    expect(location).not.toContain("email");
+    expect(location).not.toContain("b.example");
+    // The hint is never handed to the API either.
+    expect(mockCreateCode).toHaveBeenNthCalledWith(
+      1,
+      {
+        clientId: "spoke_abc",
+        redirectUri: SPOKE_CALLBACK,
+        codeChallenge: CHALLENGE,
+      },
+      { headers: { cookie: "better-auth.session_token=tok", origin: HUB } },
+    );
+  });
+});

package/templates/apps/web/app/api/auth/hub/authorize/route.ts

@@ -11,6 +11,7 @@
  *   GET /api/auth/hub/authorize
  *       ?response_type=code&client_id=…&redirect_uri=…&state=…
  *       &code_challenge=…&code_challenge_method=S256
+ *       [&login_hint=<email>]   (optional, #8757 D9 — see below)
  *
  *   - a malformed query is a 400 and NEVER a redirect;
  *   - no Better Auth session: the six validated keys are sealed into a short
@@ -32,6 +33,14 @@
  *   - any other refusal is a 400 with `{ "error": "invalid_request" }` and no
  *     visitor copy: only a misconfigured client reaches it.
  *
+ * `login_hint` (#8757 D9) is optional and read beside the six keys with
+ * `accountEmailHintSchema` (`hubAuthorizeQuerySchema` is unchanged): repeated
+ * → 400 like any repeated key; refused → dropped. It acts only on the
+ * no-session branch, as the sign-in page's `email`, so the form opens with the
+ * address typed. It never enters the ref, a code or a cookie — the continue
+ * route rebuilds the query from the ref, so the hint is gone after sign-in —
+ * and with a session it is ignored.
+ *
  * `BETTER_AUTH_URL` pins the `Origin` sent with the cookie-authenticated write
  * (Node's `fetch` sets none). Unset, the step answers 503: it needs a pinned
  * origin, exactly as the emailed link does.
@@ -42,7 +51,10 @@
  * state, a challenge or a cookie.
  */
 import { hubSignIn } from "@working-theory/api-client";
-import { hubAuthorizeQuerySchema } from "@working-theory/validation";
+import {
+  accountEmailHintSchema,
+  hubAuthorizeQuerySchema,
+} from "@working-theory/validation";
 
 import { auth, resolveSecret } from "../../../../../auth";
 import {
@@ -109,9 +121,13 @@ export async function GET(request: Request): Promise<Response> {
     if (values.length > 1) return json(400, "invalid_request");
     raw[key] = values[0];
   }
+  // #8757 D9 — the optional hint: the same once-only rule; refused → dropped.
+  const hints = url.searchParams.getAll("login_hint");
+  if (hints.length > 1) return json(400, "invalid_request");
   const parsed = hubAuthorizeQuerySchema.safeParse(raw);
   if (!parsed.success) return json(400, "invalid_request");
   const query = parsed.data;
+  const hint = accountEmailHintSchema.safeParse(hints[0]);
 
   const session = await auth.api.getSession({ headers: request.headers });
   if (!session) {
@@ -121,8 +137,9 @@ export async function GET(request: Request): Promise<Response> {
     for (const key of QUERY_KEYS) canonical.set(key, query[key]);
     const ref = mintContinuation(canonical.toString(), resolveSecret());
     if (ref.length > CONTINUATION_REF_MAX) return json(400, "invalid_request");
-    const next = `${CONTINUE_PATH}/${ref}`;
-    return see(`/sign-in?next=${encodeURIComponent(next)}`);
+    const signIn = new URLSearchParams({ next: `${CONTINUE_PATH}/${ref}` });
+    if (hint.success) signIn.set("email", hint.data);
+    return see(`/sign-in?${signIn.toString()}`);
   }
 
   const origin = pinnedOrigin();

package/templates/apps/web/app/api/checkout/[offering]/route.ts

@@ -0,0 +1,48 @@
+// The buy route — the standard spoke checkout (#8748), kept current by
+// `create-ailk update`: do not edit it. Every guarantee lives in the
+// spoke-checkout package and arrives by a package bump. This site's offerings
+// are data in lib/checkout-config.ts, the one file to edit. It answers 404 on
+// any build that is not a spoke.
+//
+// A buyer who is signed in when checkout starts returns to /account; everyone
+// else returns to the thank-you page with Stripe's session id (#8757 D12). The
+// session is read through the site's generated seam: Better Auth on a site,
+// the sealed hub session on a hub-sign-in spoke, none without sign-in.
+import { createSpokeCheckout } from "@working-theory/spoke-checkout";
+
+import {
+  checkoutNotServed,
+  checkoutServed,
+  spokeCheckoutConfig,
+} from "../../../../lib/checkout";
+import { readSession } from "../../../../lib/topology.generated";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type BuyRoute = ReturnType<typeof createSpokeCheckout>["buy"];
+type BuyContext = Parameters<BuyRoute["GET"]>[1];
+
+let buy: BuyRoute | undefined;
+
+/** `/account` for a request with a session, else `null` (the thank-you page). */
+async function successPath(request: Request): Promise<string | null> {
+  return (await readSession(request.headers)) ? "/account" : null;
+}
+
+/** Built on the first served request and kept, so the package's rate limiters persist. */
+function buyRoute(): BuyRoute {
+  buy ??= createSpokeCheckout(spokeCheckoutConfig, { successPath }).buy;
+  return buy;
+}
+
+// platform-decisions-waiver: api-versioning — a browser buy link that redirects to Stripe Checkout, not a versioned API contract (spec 8748 §7)
+export async function GET(request: Request, ctx: BuyContext): Promise<Response> {
+  if (!checkoutServed()) return checkoutNotServed();
+  return buyRoute().GET(request, ctx);
+}
+
+export async function POST(request: Request, ctx: BuyContext): Promise<Response> {
+  if (!checkoutServed()) return checkoutNotServed();
+  return buyRoute().POST(request, ctx);
+}

package/templates/apps/web/app/api/checkout/__tests__/route.test.ts

@@ -0,0 +1,120 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The standard buy route (#8748 D1, D11; spec
+ * docs/specs/8748-a-standard-spoke-checkout-route-spec.md AC-2, AC-4).
+ *
+ * The checkout package is mocked: every guarantee is its own, proven by its
+ * own suites. These cases prove the route is wiring only — built once from
+ * `spokeCheckoutConfig`, serving the package's `buy` handlers on a spoke and
+ * a 404 anywhere else — and that it declares no offering and no Stripe
+ * client of its own.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mockBuyGet = jest.fn();
+const mockBuyPost = jest.fn();
+const mockCreateSpokeCheckout = jest.fn((_config: unknown) => ({
+  buy: { GET: mockBuyGet, POST: mockBuyPost },
+}));
+// `virtual`: CI runs this suite before the package's dist is built, so it
+// may not resolve at all — the factory stands in either way.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown) => mockCreateSpokeCheckout(config),
+  }),
+  { virtual: true },
+);
+
+const mockTopology: { value: "hub" | "spoke" } = { value: "spoke" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  get TOPOLOGY() {
+    return mockTopology.value;
+  },
+}));
+
+import { checkoutConfig } from "../../../../lib/checkout-config";
+import { spokeCheckoutConfig } from "../../../../lib/checkout";
+import { GET, POST } from "../[offering]/route";
+
+const ROUTE_SOURCE = readFileSync(
+  join(__dirname, "..", "[offering]", "route.ts"),
+  "utf8",
+);
+
+function ctxFor(offering: string) {
+  return { params: Promise.resolve({ offering }) };
+}
+
+function request(method: "GET" | "POST"): Request {
+  return new Request("https://acme.example.com/api/checkout/example", {
+    method,
+  });
+}
+
+describe("the standard buy route (#8748 AC-2)", () => {
+  beforeEach(() => {
+    mockBuyGet.mockReset();
+    mockBuyPost.mockReset();
+  });
+
+  it("answers 404 with no-store on a hub, and never builds the package's handlers (D11)", async () => {
+    mockTopology.value = "hub";
+    for (const res of [
+      await GET(request("GET"), ctxFor("example")),
+      await POST(request("POST"), ctxFor("example")),
+    ]) {
+      expect(res.status).toBe(404);
+      expect(res.headers.get("cache-control")).toBe("no-store");
+    }
+    expect(mockCreateSpokeCheckout).not.toHaveBeenCalled();
+    expect(mockBuyGet).not.toHaveBeenCalled();
+    expect(mockBuyPost).not.toHaveBeenCalled();
+  });
+
+  it("serves the package's buy handlers on a spoke, built once from spokeCheckoutConfig", async () => {
+    mockTopology.value = "spoke";
+    const fromGet = new Response(null, { status: 303 });
+    const fromPost = new Response(null, { status: 303 });
+    mockBuyGet.mockResolvedValue(fromGet);
+    mockBuyPost.mockResolvedValue(fromPost);
+
+    const getRequest = request("GET");
+    const getCtx = ctxFor("example");
+    expect(await GET(getRequest, getCtx)).toBe(fromGet);
+    expect(mockBuyGet).toHaveBeenCalledWith(getRequest, getCtx);
+
+    const postRequest = request("POST");
+    const postCtx = ctxFor("example");
+    expect(await POST(postRequest, postCtx)).toBe(fromPost);
+    expect(mockBuyPost).toHaveBeenCalledWith(postRequest, postCtx);
+
+    expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+    const [config] = mockCreateSpokeCheckout.mock.calls[0] as [
+      typeof spokeCheckoutConfig,
+    ];
+    expect(config).toBe(spokeCheckoutConfig);
+    expect(config.offerings).toBe(checkoutConfig.offerings);
+  });
+
+  it("names no offering of the site's own", () => {
+    for (const slug of Object.keys(checkoutConfig.offerings)) {
+      const quoted = new RegExp(`["'\`]${slug}["'\`]`);
+      const property = new RegExp(`\\b${slug}\\s*:`);
+      expect(ROUTE_SOURCE).not.toMatch(quoted);
+      expect(ROUTE_SOURCE).not.toMatch(property);
+    }
+  });
+
+  it("reads no Stripe setting and imports no Stripe client (AC-4)", () => {
+    expect(ROUTE_SOURCE).not.toContain("STRIPE_");
+    expect(ROUTE_SOURCE).not.toContain("stripe-client");
+  });
+});