create-ailk 0.21.0 → 0.23.0

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

@@ -4,32 +4,73 @@
  * `?t=` token never leaks through a Referer header off this page (D17,
  * SEC-8438-9).
  *
- * RSC: reads `?t=` and renders the heading, the lead and the one
+ * RSC: reads `?t=` and renders the heading, the line and the one
  * interactive piece (`UnsubscribeButton`, "use client") that posts
  * `unsubscribeAction(token)` ON CLICK — never on this GET, so a mail
- * scanner's prefetch writes nothing. The island gets the token and nothing
- * else: it reads its own strings, because anything callable handed across
- * this server→client edge fails Flight serialization (the scaffold matrix's
- * `GET /unsubscribe -> 500`; `__tests__/unsubscribe-rsc-boundary.test.tsx`).
+ * scanner's prefetch writes nothing. The island gets the token and three
+ * strings: anything callable handed across this server→client edge fails
+ * Flight serialization (the scaffold matrix's `GET /unsubscribe -> 500`;
+ * `__tests__/unsubscribe-rsc-boundary.test.tsx`).
+ *
+ * #8847 D12 — the title, line, button and done message come from the
+ * newsletter magnet's `unsubscribe` block (`readServedMagnet`, shared like
+ * /contact's read), else the seeded `newsletterFlowConfig`'s. The token states
+ * (already, invalid, unavailable) keep their catalog lines: they describe
+ * the link, not the newsletter. The frame is /contact's `column` look. The
+ * page renders on every request.
  */
 
+import { SectionFrame } from "@working-theory/ui";
 import { Heading, Text } from "@working-theory/ui/primitives";
+import {
+  NEWSLETTER_FLOW_SLUG,
+  newsletterFlowConfig,
+  resolveLocalizedString,
+  type FlowUnsubscribeCopy,
+} from "@working-theory/validation";
 import type { Metadata } from "next";
-import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
 
+import { readServedMagnet } from "../../../lib/in-page-magnet";
+
 import { UnsubscribeButton } from "./unsubscribe-button";
 
+export const dynamic = "force-dynamic";
+
 interface Props {
   params: Promise<{ locale: string }>;
   searchParams: Promise<{ t?: string }>;
 }
 
+interface UnsubscribeCopy {
+  title: string;
+  body?: string;
+  cta: string;
+  doneHeadline: string;
+  doneBody?: string;
+}
+
+/** The newsletter magnet's unsubscribe copy, else the seeded config's. */
+async function unsubscribeCopy(locale: string): Promise<UnsubscribeCopy> {
+  const served = await readServedMagnet(NEWSLETTER_FLOW_SLUG);
+  const config = served?.unsubscribe ? served : newsletterFlowConfig;
+  const block = config.unsubscribe as FlowUnsubscribeCopy;
+  const resolve = (value: Record<string, string>): string =>
+    resolveLocalizedString(value, locale, config.defaultLocale);
+  return {
+    title: resolve(block.title),
+    ...(block.body !== undefined && { body: resolve(block.body) }),
+    cta: resolve(block.cta),
+    doneHeadline: resolve(block.done.headline),
+    ...(block.done.body !== undefined && { doneBody: resolve(block.done.body) }),
+  };
+}
+
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { locale } = await params;
-  const t = await getTranslations({ locale, namespace: "unsubscribe" });
+  const copy = await unsubscribeCopy(locale);
   return {
-    title: t("title"),
+    title: copy.title,
     robots: { index: false, follow: true },
     referrer: "no-referrer",
   };
@@ -38,17 +79,28 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 export default async function UnsubscribePage({ params, searchParams }: Props): Promise<ReactElement> {
   const { locale } = await params;
   const { t: token } = await searchParams;
-  const t = await getTranslations({ locale, namespace: "unsubscribe" });
+  const copy = await unsubscribeCopy(locale);
 
   return (
-    <div className="mx-auto flex max-w-md flex-col gap-4 px-4 py-16" data-testid="unsubscribe-page">
-      <Heading level={1} visual={2}>
-        {t("title")}
-      </Heading>
-      <Text as="p" variant="body">
-        {t("lead")}
-      </Text>
-      <UnsubscribeButton token={token ?? null} />
-    </div>
+    <SectionFrame sectionId="unsubscribe" className="ailk-contact-frame" data-testid="unsubscribe-page">
+      <div className="ailk-contact-column text-center">
+        <Heading level={1} visual="display" className="ailk-contact-heading text-center">
+          {copy.title}
+        </Heading>
+        {copy.body !== undefined && (
+          <Text as="p" tone="muted" className="mx-auto mt-block-tight ailk-contact-measure text-balance">
+            {copy.body}
+          </Text>
+        )}
+        <div className="ailk-contact-slot mx-auto mt-block-loose flex w-full ailk-contact-measure flex-col items-center">
+          <UnsubscribeButton
+            token={token ?? null}
+            cta={copy.cta}
+            doneHeadline={copy.doneHeadline}
+            {...(copy.doneBody !== undefined && { doneBody: copy.doneBody })}
+          />
+        </div>
+      </div>
+    </SectionFrame>
   );
 }

package/templates/apps/web/app/[locale]/unsubscribe/unsubscribe-button.tsx

@@ -5,12 +5,13 @@
  * D17). Posts `unsubscribeAction(token)` on click only — never on render,
  * so a mail scanner's GET prefetch of the page writes nothing.
  *
- * Reads its own strings through `useTranslations` (the island idiom
- * `FlowStepperClient` uses) rather than taking them as props: the done line
- * needs the purpose's description formatted in, and a formatting FUNCTION
- * handed across from the page (a Server Component) cannot be serialized
- * into the Flight payload — the scaffold matrix's `GET /unsubscribe -> 500`
- * (`unsubscribe-rsc-boundary.test.tsx` holds the regression).
+ * The button label and the done message are the newsletter magnet's
+ * (#8847 D12), passed as STRINGS: a formatting FUNCTION handed across from the
+ * page (a Server Component) cannot be serialized into the Flight payload —
+ * the scaffold matrix's `GET /unsubscribe -> 500`
+ * (`unsubscribe-rsc-boundary.test.tsx` holds the regression). The token
+ * states (invalid, already, unavailable) read their own catalog lines
+ * through `useTranslations`.
  */
 
 import { Button, InlineMessage } from "@working-theory/ui/primitives";
@@ -19,7 +20,21 @@ import { useState, useTransition, type ReactElement } from "react";
 
 import { unsubscribeAction, type UnsubscribeResult } from "./unsubscribe.actions";
 
-export function UnsubscribeButton({ token }: { token: string | null }): ReactElement {
+interface UnsubscribeButtonProps {
+  token: string | null;
+  /** The button label (the magnet's `unsubscribe.cta`). */
+  cta: string;
+  /** The done message (the magnet's `unsubscribe.done`). */
+  doneHeadline: string;
+  doneBody?: string;
+}
+
+export function UnsubscribeButton({
+  token,
+  cta,
+  doneHeadline,
+  doneBody,
+}: UnsubscribeButtonProps): ReactElement {
   const t = useTranslations("unsubscribe");
   const [result, setResult] = useState<UnsubscribeResult | null>(null);
   const [pending, startTransition] = useTransition();
@@ -35,7 +50,13 @@ export function UnsubscribeButton({ token }: { token: string | null }): ReactEle
   if (result?.kind === "done") {
     return (
       <InlineMessage variant="success" role="status" data-testid="unsubscribe-done">
-        {t("done", { description: result.description })}
+        {/* Headline over body, as the /contact ending stacks them (#8847 D12). */}
+        <span className="flex flex-col">
+          <span className="font-semibold" data-testid="unsubscribe-done-headline">
+            {doneHeadline}
+          </span>
+          {doneBody !== undefined && <span className="mt-1">{doneBody}</span>}
+        </span>
       </InlineMessage>
     );
   }
@@ -67,7 +88,7 @@ export function UnsubscribeButton({ token }: { token: string | null }): ReactEle
       }}
       data-testid="unsubscribe-button"
     >
-      {t("button")}
+      {cta}
     </Button>
   );
 }

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/hub-session/__tests__/routes.test.ts

@@ -13,6 +13,9 @@
  * a callback that BURNS a code it cannot complete (AC-5), and a sign-out that
  * refuses a cross-site request and revokes nothing (AC-5). Each route is a 404
  * unless the web seam's `SIGN_IN_PROVIDER` is `"hub"` (AC-9).
+ *
+ * #8757 D9 (AC-6): a valid single `?email=` on the sign-in route becomes the
+ * authorize URL's `login_hint`; the sealed flow cookie never carries it.
  */
 
 import { createHash } from "node:crypto";
@@ -36,7 +39,7 @@ jest.mock("../../../../lib/topology.generated", () => ({
   },
 }));
 
-import { seal } from "../../../../lib/hub-session/seal";
+import { seal, unseal } from "../../../../lib/hub-session/seal";
 import { GET as callback } from "../callback/route";
 import { GET as signIn } from "../sign-in/route";
 import { POST as signOut } from "../sign-out/route";
@@ -161,6 +164,46 @@ describe("GET /api/hub-session/sign-in", () => {
   });
 });
 
+describe("GET /api/hub-session/sign-in — the hinted email (#8757 D9)", () => {
+  function startWith(query: string): { authorize: URL; payload: Record<string, unknown> } {
+    const res = signIn(new Request(`${SITE}/api/hub-session/sign-in?${query}`));
+    expect(res.status).toBe(303);
+    const flow = cookieValue(res, "ailk-hub-flow");
+    if (flow === undefined) throw new Error("no flow cookie");
+    const payload = unseal(flow, SESSION_SECRET, "flow", "ailk-hub-flow");
+    if (payload === null || typeof payload !== "object") throw new Error("flow did not open");
+    return {
+      authorize: new URL(res.headers.get("location") ?? ""),
+      payload: payload as Record<string, unknown>,
+    };
+  }
+
+  it("?next=/account&email=a%40b.example → the authorize URL carries login_hint; the flow cookie does not", () => {
+    const { authorize, payload } = startWith("next=/account&email=a%40b.example");
+    expect(authorize.searchParams.get("login_hint")).toBe("a@b.example");
+    expect(authorize.search).toContain("login_hint=a%40b.example");
+    // The six keys are untouched beside it.
+    expect(authorize.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(authorize.searchParams.getAll("login_hint")).toHaveLength(1);
+    expect(payload.next).toBe("/account");
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+    expect(JSON.stringify(payload)).not.toContain("a@b.example");
+  });
+
+  it.each([
+    ["an invalid value", "next=/account&email=bad"],
+    ["a repeated value", "next=/account&email=a%40b.example&email=c%40d.example"],
+    ["a value carrying a separator", "next=/account&email=a%40b.example%26x%3D1"],
+    ["no value", "next=/account"],
+  ])("%s → no login_hint", (_label, query) => {
+    const { authorize, payload } = startWith(query);
+    expect(authorize.searchParams.has("login_hint")).toBe(false);
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+  });
+});
+
 describe("GET /api/hub-session/callback", () => {
   function exchangeOk(): void {
     mockExchange.mockResolvedValue({

package/templates/apps/web/app/api/hub-session/sign-in/route.ts

@@ -10,10 +10,17 @@
  *   - not a hub-mode spoke (`SIGN_IN_PROVIDER` is not `"hub"`): 404;
  *   - hub mode but not configured: 303 to `/account`, whose gate says so.
  *
+ * Hinted email (#8757 D9): a single `?email=` that `accountEmailHintSchema`
+ * accepts rides to the hub as `login_hint`, so its sign-in form opens with
+ * the address typed. A refused or repeated value is dropped. The hint goes on
+ * the authorize URL only — never into the sealed flow cookie.
+ *
  * Nothing here logs the state, the verifier or the challenge.
  */
 import { createHash, randomBytes } from "node:crypto";
 
+import { accountEmailHintSchema } from "@working-theory/validation";
+
 import { hubSessionConfig } from "../../../../lib/hub-session/config";
 import { seal } from "../../../../lib/hub-session/seal";
 import {
@@ -40,13 +47,22 @@ function see(location: string, setCookie?: string): Response {
   return new Response(null, { status: 303, headers });
 }
 
+/** #8757 D9 — the one `email` the hint schema accepts; repeated or refused → none. */
+function emailHint(params: URLSearchParams): string | undefined {
+  const values = params.getAll("email");
+  if (values.length !== 1) return undefined;
+  const parsed = accountEmailHintSchema.safeParse(values[0]);
+  return parsed.success ? parsed.data : undefined;
+}
+
 // platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
 export function GET(request: Request): Response {
   if (SIGN_IN_PROVIDER !== "hub") return new Response(null, { status: 404 });
   const config = hubSessionConfig();
   if (config === null) return see(HUB_SESSION_FALLBACK_PATH);
 
-  const next = hubNextPath(new URL(request.url).searchParams.get("next"));
+  const params = new URL(request.url).searchParams;
+  const next = hubNextPath(params.get("next"));
   const state = randomBytes(32).toString("base64url");
   const verifier = randomBytes(32).toString("base64url");
   const challenge = createHash("sha256").update(verifier).digest("base64url");
@@ -60,14 +76,17 @@ export function GET(request: Request): Response {
   );
 
   const authorize = new URL(AUTHORIZE_PATH, config.hubOrigin);
-  authorize.search = new URLSearchParams({
+  const query = new URLSearchParams({
     response_type: "code",
     client_id: config.clientId,
     redirect_uri: config.redirectUri,
     state,
     code_challenge: challenge,
     code_challenge_method: "S256",
-  }).toString();
+  });
+  const loginHint = emailHint(params);
+  if (loginHint !== undefined) query.set("login_hint", loginHint);
+  authorize.search = query.toString();
 
   return see(
     authorize.toString(),