create-ailk 0.27.0 → 0.28.1

package/templates/apps/web/app/[locale]/flows/[slug]/results/[payload]/page.tsx

@@ -0,0 +1,264 @@
+// oss: false
+/**
+ * /[locale]/flows/[slug]/results/[payload] — the cold-load results route
+ * (#4770).
+ *
+ * Server-fetches the flow config exactly as `flows/[slug]/page.tsx` does
+ * (`flows.get(slug)`, always dynamically rendered — the config is DB-backed
+ * live data).
+ * Decodes the versioned, answers-only permalink (`decodePermalink`,
+ * `@working-theory/validation`) and `redirect()`s to `/[locale]/flows/[slug]`
+ * — step 1, never an error page — on ANY of: an invalid payload (FR6), a
+ * stale-version payload (FR6), a payload whose own `flowSlug` does not match
+ * this route's `[slug]` (D2/FR6), or a served flow that is not a
+ * recommending register (D8 — `mode !== "recommending" || !offers`, checked
+ * against the field `recommend()` is about to be handed rather than
+ * inferring the compiler's five-keys-travel-together guarantee).
+ *
+ * On a valid payload against a recommending flow, renders `ResultsClient`,
+ * which runs the already-shipped pure `recommend()` in the browser and
+ * renders the returned fits through the existing `RecommendationCard`
+ * (D10 — a minimal render; Epic #4759 recomposes it against the LOCKED
+ * DESIGN.md).
+ *
+ * `?checkout=success|cancelled` (#4842 FR7/D6) is read only after every
+ * guard above and rendered by `ResultsClient` as a one-line status over the
+ * identical recommendation.
+ *
+ * #9071 D3 — the recommender's landing. A flow with an offer carrying a
+ * string `lookupKey` (an Offerings recommender) never renders here: after
+ * the recommending guard the page redirects to `/<locale>/pricing?plan=<plan>`
+ * when the first fit's lookup key is in the current shown set — read from
+ * `offerings.shown()`, the endpoint `/pricing` renders from, through this
+ * page's own read shared per instance for 15 seconds — and to `/<locale>/pricing` with no badge otherwise (no fit, a
+ * key no longer shown, any failed read). The URL is built only from an
+ * allowlisted locale and a `parseLookupKey` plan. A flow with no such offer,
+ * or whose first fit carries none, renders as before with no read.
+ */
+import { flows, offerings } from "@working-theory/api-client";
+import {
+  decodePermalink,
+  type FlowConfig,
+  parseLookupKey,
+  recommend,
+  resolveLocalizedString,
+  shownOfferingsAnswerSchema,
+  type WaitlistAnswers,
+  type WorkspaceShownSetWire,
+} from "@working-theory/validation";
+import type { Metadata } from "next";
+import { redirect } from "next/navigation";
+import type { ReactElement } from "react";
+
+import { browserApiOrigin } from "../../../../../../lib/api-origin.generated";
+
+import type { ResultsReturnState } from "./ResultsClient";
+import { ResultsClient } from "./ResultsClient";
+
+export const dynamic = "force-dynamic";
+
+interface Props {
+  params: Promise<{ locale: string; slug: string; payload: string }>;
+  /** FR7 (#4842) — `?checkout=success|cancelled` after Stripe's hosted page. */
+  searchParams?: Promise<Record<string, string | string[] | undefined>>;
+}
+
+/**
+ * D6 (#4842) — the return micro-state, validated against the two literals;
+ * anything else (absent, an array, an unknown value) renders no status line.
+ */
+function resolveReturnState(
+  value: string | string[] | undefined,
+): ResultsReturnState | undefined {
+  return value === "success" || value === "cancelled" ? value : undefined;
+}
+
+// Mirrors `ResultsClient.tsx` — a path is built only from an enabled locale.
+const DEFAULT_LOCALE = "en";
+const ENABLED_LOCALES = (
+  process.env.NEXT_PUBLIC_ENABLED_LOCALES ?? DEFAULT_LOCALE
+).split(",");
+
+/** #9071 D3a — `/pricing`'s and the buy route's window. */
+const SHOWN_READ_TTL_MS = 15_000;
+/** #9071 NFR-4 — no landing read holds a visitor longer than this. */
+const SHOWN_READ_TIMEOUT_MS = 5_000;
+
+let shownRead:
+  | { at: number; read: Promise<WorkspaceShownSetWire | null> }
+  | undefined;
+
+/**
+ * The three names `getApiBase()` reads, the browser-facing one through the
+ * topology seam (#7874 D12), which a spoke renders with no env read (#9480):
+ * the browser-facing name set on a spoke at runtime counts as no origin.
+ */
+function apiOriginConfigured(): boolean {
+  return Boolean(
+    process.env.AILK_API_URL ||
+    browserApiOrigin() ||
+    process.env.NEXT_PUBLIC_API_URL,
+  );
+}
+
+/**
+ * #9071 D3a — the current shown set, or `null` for "nothing shown": no API
+ * origin in production (no call), `unconnected`, `empty`, an expired set, a
+ * non-2xx, a body the schema refuses, a throw, or no answer within 5 s.
+ * Concurrent and failed reads are shared like a good one.
+ */
+function readCurrentShownSet(): Promise<WorkspaceShownSetWire | null> {
+  if (process.env.NODE_ENV === "production" && !apiOriginConfigured()) {
+    return Promise.resolve(null);
+  }
+  const now = Date.now();
+  if (shownRead && now - shownRead.at < SHOWN_READ_TTL_MS) return shownRead.read;
+  const read = (async (): Promise<WorkspaceShownSetWire | null> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const timeout = new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), SHOWN_READ_TIMEOUT_MS);
+      });
+      const res = await Promise.race([offerings.shown(), timeout]);
+      if (res === null || !res.ok) return null;
+      const parsed = shownOfferingsAnswerSchema.safeParse(res.body);
+      if (!parsed.success || parsed.data.status !== "shown") return null;
+      return parsed.data.shownSet.state === "current" ? parsed.data.shownSet : null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  })();
+  shownRead = { at: now, read };
+  return read;
+}
+
+function isOfferingsOffer(offer: unknown): boolean {
+  return (
+    typeof offer === "object" &&
+    offer !== null &&
+    typeof (offer as { lookupKey?: unknown }).lookupKey === "string"
+  );
+}
+
+/**
+ * #9071 D3 — where a completed Offerings recommender lands, or `null` to
+ * render the results page as before. The served config is not re-parsed
+ * here, so every read of it is shape-checked and any throw is `null`.
+ */
+async function recommenderLanding(
+  config: FlowConfig,
+  answers: WaitlistAnswers,
+  locale: string,
+): Promise<string | null> {
+  try {
+    const offers: unknown = config.offers;
+    if (!Array.isArray(offers) || !offers.some(isOfferingsOffer)) return null;
+
+    let fitKey: string | undefined;
+    try {
+      fitKey = recommend(
+        {
+          key: config.experiment?.key ?? config.slug,
+          offers: config.offers,
+          pairings: config.pairings,
+          rateTable: config.rateTable,
+          scoring: config.scoring,
+        },
+        answers,
+      ).fits[0]?.offerKey;
+    } catch {
+      fitKey = undefined;
+    }
+    const fit: unknown =
+      fitKey === undefined
+        ? undefined
+        : offers.find(
+            (o: unknown) =>
+              typeof o === "object" && o !== null && (o as { key?: unknown }).key === fitKey,
+          );
+    if (fit !== undefined && !isOfferingsOffer(fit)) return null;
+
+    const safeLocale = ENABLED_LOCALES.includes(locale) ? locale : DEFAULT_LOCALE;
+    const base = `/${safeLocale}/pricing`;
+    if (fit === undefined) return base;
+    const lookupKey = (fit as { lookupKey: string }).lookupKey;
+    const parsed = parseLookupKey(lookupKey);
+    if (parsed === null) return base;
+
+    const shown = await readCurrentShownSet();
+    const isShown =
+      shown?.offerings.some((o) => o.prices.some((p) => p.lookupKey === lookupKey)) ??
+      false;
+    return isShown ? `${base}?plan=${parsed.plan}` : base;
+  } catch {
+    return null;
+  }
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale, slug, payload } = await params;
+
+  const decoded = decodePermalink(payload);
+  if (!decoded.ok || decoded.value.flowSlug !== slug) return {};
+
+  const res = await flows.get(slug);
+  if (!res.ok) return {};
+
+  const { recommendation } = res.body;
+  if (!recommendation) return {};
+
+  return {
+    title: resolveLocalizedString(
+      recommendation.copy.title,
+      locale,
+      res.body.defaultLocale,
+    ),
+  };
+}
+
+export default async function Page({
+  params,
+  searchParams,
+}: Props): Promise<ReactElement> {
+  const { locale, slug, payload } = await params;
+
+  const decoded = decodePermalink(payload);
+  if (!decoded.ok) {
+    redirect(`/${locale}/flows/${slug}`);
+  }
+  if (decoded.value.flowSlug !== slug) {
+    redirect(`/${locale}/flows/${slug}`);
+  }
+
+  const res = await flows.get(slug);
+  if (!res.ok) {
+    redirect(`/${locale}/flows/${slug}`);
+  }
+  if (res.body.mode !== "recommending" || res.body.offers === undefined) {
+    redirect(`/${locale}/flows/${slug}`);
+  }
+
+  const landing = await recommenderLanding(
+    res.body,
+    decoded.value.answers,
+    locale,
+  );
+  if (landing !== null) redirect(landing);
+
+  // FR7 — read AFTER every redirect guard above, so a return param never
+  // changes which guard fires or where it sends the visitor.
+  const returnState = resolveReturnState((await searchParams)?.checkout);
+
+  return (
+    <ResultsClient
+      config={res.body}
+      locale={locale}
+      answers={decoded.value.answers}
+      slug={slug}
+      payload={payload}
+      {...(returnState !== undefined ? { returnState } : {})}
+    />
+  );
+}

package/templates/apps/web/app/[locale]/flows/[slug]/save.actions.ts

@@ -0,0 +1,75 @@
+// oss: false
+"use server";
+
+/**
+ * save.actions.ts — "Email me this plan" (#4842 D7): validates with
+ * `flowSaveInputSchema`, calls `flows.save`, returns the lead id. A sibling of
+ * `flow.actions.ts` (ADR 0013 `*.actions.ts`).
+ *
+ * Split out of `checkout.actions.ts` by #6786: saving a recommendation is the
+ * results page's own job, so it ships with the page (the `flows` surface,
+ * signal-collectors), while `startCheckoutAction` stays commerce's. The shared
+ * validation, IP-forwarding and status → kind helpers are `email-moment.ts`.
+ */
+
+import { flows } from "@working-theory/api-client";
+import type { FlowSaveInput } from "@working-theory/validation";
+import {
+  flowSaveInputSchema,
+  flowSlugSchema,
+} from "@working-theory/validation";
+
+import { runBotCheck } from "../../../../lib/bot-check";
+
+import type { EmailMomentFailure } from "./email-moment";
+import {
+  emailMomentFields,
+  errorName,
+  failureFor,
+  resolveVisitorIpInit,
+} from "./email-moment";
+
+export type SaveActionResult =
+  { ok: true; leadId: string } | EmailMomentFailure;
+
+export async function saveRecommendationAction(
+  slug: string,
+  body: FlowSaveInput,
+): Promise<SaveActionResult> {
+  const parsedSlug = flowSlugSchema.safeParse(slug);
+  if (!parsedSlug.success) return { ok: false, kind: "invalid_input" };
+
+  const parsed = flowSaveInputSchema.safeParse(body);
+  if (!parsed.success) return { ok: false, kind: "invalid_input" };
+
+  const payload = emailMomentFields(parsed.data);
+
+  // #9255 D4 — the spoke edge's bot check, after the input checks and before
+  // the write.
+  const botCheck = await runBotCheck({
+    source: "bot-check",
+    target: "saveRecommendationAction",
+    scope: "write",
+  });
+  if (botCheck !== "pass") return { ok: false, kind: "unavailable" };
+
+  try {
+    const visitorIpInit = await resolveVisitorIpInit();
+    const res = visitorIpInit
+      ? await flows.save(parsedSlug.data, payload, visitorIpInit)
+      : await flows.save(parsedSlug.data, payload);
+    if (!res.ok) {
+      const failure = failureFor(res);
+      console.error(
+        `[saveRecommendationAction] slug=${parsedSlug.data} kind=${failure.kind} status=${res.status}`,
+      );
+      return failure;
+    }
+    return { ok: true, leadId: res.body.leadId };
+  } catch (err) {
+    console.error(
+      `[saveRecommendationAction] slug=${parsedSlug.data} kind=network errName=${errorName(err)}`,
+    );
+    return { ok: false, kind: "network" };
+  }
+}

package/templates/apps/web/app/[locale]/for/__tests__/hub-children.test.tsx

@@ -0,0 +1,32 @@
+/**
+ * Hub child cards (#10121) for /for. The shared cases live in
+ * `lib/__tests__/hub-children.fixtures.ts`; this file sits beside the route so
+ * a scaffold without /for drops it with the route (#10157).
+ */
+const mockRenderPage = jest.fn(async (..._args: unknown[]) => "<rendered/>");
+
+jest.mock("@working-theory/page-renderer", () => ({
+  __esModule: true,
+  renderPage: (...args: unknown[]) => mockRenderPage(...args),
+  renderPageMetadata: jest.fn(),
+  // Never reached — every call in this suite passes its loaders via DI.
+  getMdxSlugs: jest.fn(),
+  getMdxSource: jest.fn(),
+  getPageSections: jest.fn(),
+}));
+
+jest.mock("@working-theory/ui/sections", () => ({
+  __esModule: true,
+  SectionRenderer: () => null,
+}));
+
+import ForPage from "../page";
+import {
+  describeHub,
+  type HubPage,
+} from "../../../../lib/__tests__/hub-children.fixtures";
+
+describeHub(
+  ["for", ForPage as HubPage, "UseCasesList", "UseCase", "composed"],
+  mockRenderPage,
+);

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

@@ -54,6 +54,8 @@ describe("ForPage — snapshot regression", () => {
   it("empty state renders deterministic HTML", async () => {
     const element = await ForPage({
       params: Promise.resolve({ locale: "en" }),
+      // No child pages: this snapshot pins the hub's own render (#10121).
+      getMdxSlugs: async () => [],
       getMdxSource: getMdxSourceEmpty,
     });
     const { container } = render(element);
@@ -76,11 +78,13 @@ describe("ForPage — snapshot regression", () => {
 
     const element = await ForPage({
       params: Promise.resolve({ locale: "en" }),
+      // No child pages: this snapshot pins the hub's own render (#10121).
+      getMdxSlugs: async () => [],
       getMdxSource: getMdxSourcePopulated,
     });
     const { container } = render(element);
     expect(container.innerHTML).toMatchInlineSnapshot(
-      `"<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Use Cases","description":"How teams use our platform.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Article"}]}}</script><main id="main"><div><h1>Use Cases</h1><p data-testid="for-description" class="mt-block-tight text-lead">How teams use our platform.</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 data-testid="mdx-remote" data-source=""></div></article></div></div></div></main>"`,
+      `"<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Use Cases","description":"How teams use our platform.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Article"}]}}</script><main id="main"><div><div data-testid="markdown-view-toggle" class="ailk-markdown-view-toggle"><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 data-testid="mdx-remote" data-source=""></div></article></div></div></div></main>"`,
     );
   });
 });

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

@@ -1,53 +1,51 @@
 // Customers (/for) hub page (#6878 D2 — renamed from /use-cases). Reads
 // UseCasesList MDX via the content adapter and emits a JSON-LD CollectionPage
-// via the dispatcher. List-only — no detail route.
+// via the dispatcher. Sections when the frontmatter carries `sections[]` (the
+// Free template's hub, operator ruling 2026-09-23), the MDX body otherwise.
+// It lists every UseCase page through one generated card section (#10121,
+// apps/web/lib/hub-children.tsx — the /alternatives and /templates shape).
 import type {
+  getMdxSlugs as defaultGetMdxSlugs,
   getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections,
 } from "@working-theory/page-renderer";
-import {
-  getMdxSource as loadMdxSource,
-  renderPage,
-  renderPageMetadata,
-} from "@working-theory/page-renderer";
+import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
 import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
+import { type HubConfig, hubPageInput } from "../../../lib/hub-children";
+
 interface Props {
   params: Promise<{ locale: string }>;
   getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+  getMdxSlugs?: typeof defaultGetMdxSlugs;
 }
 
+const HUB: HubConfig = {
+  listType: "UseCasesList",
+  slug: "for",
+  childType: "UseCase",
+  linkLabel: "Read the use case",
+  sectionId: "use-case-cards",
+  body: "composed",
+};
+
 export async function generateMetadata({
   params,
 }: Pick<Props, "params">): Promise<Metadata> {
   const { locale } = await params;
-  return renderPageMetadata({
-    type: "UseCasesList",
-    slug: "for",
-    locale,
-  });
+  return renderPageMetadata({ type: "UseCasesList", slug: "for", locale });
 }
 
 export default async function Page({
   params,
-  getMdxSource,
+  ...loaders
 }: Props): Promise<ReactElement> {
   const { locale } = await params;
-  // A UseCasesList page that composes `sections[]` (the Free template's
-  // /for hub, operator ruling 2026-09-23) renders them; a prose-only page
-  // keeps the MDX-body render. The CollectionPage JSON-LD is built from the
-  // sections either way (buildUseCasesList).
-  const source = await (getMdxSource ?? loadMdxSource)("UseCasesList", "for", locale);
-  const composed =
-    source !== null &&
-    Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&
-    ((source.frontmatter as { sections?: unknown[] }).sections?.length ?? 0) > 0;
   return renderPage({
     type: "UseCasesList",
     slug: "for",
-    locale,
-    translationsNamespace: "for",
-    ...(composed ? {} : { bodyMode: "mdx-body" as const }),
-    ...(getMdxSource !== undefined && { getMdxSource }),
+    ...(await hubPageInput(HUB, locale, loaders)),
   });
 }

package/templates/apps/web/app/[locale]/how-to/[slug]/page.tsx

@@ -1,7 +1,11 @@
 // HowTo detail page. Reads the HowTo MDX for the given slug, renders via
 // @working-theory/page-renderer, and emits a JSON-LD <script>. Unknown slugs trigger 404.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
-import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import {
+  getMdxSource as loadMdxSource,
+  renderPage,
+  renderPageMetadata,
+} from "@working-theory/page-renderer";
 import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
@@ -22,12 +26,25 @@ export default async function Page({
   getMdxSource,
 }: Props): Promise<ReactElement> {
   const { locale, slug } = await params;
+  // A page that composes `sections[]` renders them (JSON-LD is built from
+  // the same sections); a prose page renders its MDX body — the rule
+  // /vs/[slug] applies (#10122).
+  const source = await (getMdxSource ?? loadMdxSource)("HowTo", slug, locale);
+  const composed =
+    source !== null &&
+    Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&
+    ((source.frontmatter as { sections?: unknown[] }).sections?.length ?? 0) >
+      0;
   return renderPage({
     type: "HowTo",
     slug,
     locale,
-    bodyMode: "mdx-body",
-    populatedDescriptionTestId: "how-to-description",
+    ...(composed
+      ? {}
+      : {
+          bodyMode: "mdx-body" as const,
+          populatedDescriptionTestId: "how-to-description",
+        }),
     ...(getMdxSource !== undefined && { getMdxSource }),
   });
 }

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

@@ -58,7 +58,7 @@ describe("how-to/[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":"Deploy AILK to Vercel","description":"Step-by-step guide to deploying AI Launch Kit on Vercel.","mainEntity":{"@context":"https://schema.org","@type":"HowTo","name":"Deploy AILK to Vercel","description":"Step-by-step guide to deploying AI Launch Kit on Vercel."}},{"@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":"How-To Guides","item":"http://localhost:3000/en/how-to"},{"@type":"ListItem","position":3,"name":"Deploy AILK to Vercel","item":"http://localhost:3000/en/how-to/deploy-ailk-vercel"}]}]}</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">Deploy AILK to Vercel</h1><p data-testid="how-to-description" class="mt-block-tight text-lead">Step-by-step guide to deploying AI Launch Kit on Vercel.</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">## Steps
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"Deploy AILK to Vercel","description":"Step-by-step guide to deploying AI Launch Kit on Vercel.","mainEntity":{"@context":"https://schema.org","@type":"HowTo","name":"Deploy AILK to Vercel","description":"Step-by-step guide to deploying AI Launch Kit on Vercel."}},{"@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":"How-To Guides","item":"http://localhost:3000/en/how-to"},{"@type":"ListItem","position":3,"name":"Deploy AILK to Vercel","item":"http://localhost:3000/en/how-to/deploy-ailk-vercel"}]}]}</script><main id="main"><div class="mx-auto w-full max-w-container-xl px-4 md:px-6 lg:px-8 py-section"><div data-testid="markdown-view-toggle" class="ailk-markdown-view-toggle"><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">## Steps
 
      Body content.</div></div></article></div></div></div></main>"
     `);

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

@@ -1,7 +1,11 @@
 // Integration detail page. Reads the Integration MDX for the given slug, renders
-// via next-mdx-remote/rsc, and emits a JSON-LD <script>. Unknown slugs 404 through renderPage.
+// via @working-theory/page-renderer, and emits a JSON-LD <script>. Unknown slugs 404 through renderPage.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
-import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import {
+  getMdxSource as loadMdxSource,
+  renderPage,
+  renderPageMetadata,
+} from "@working-theory/page-renderer";
 import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
@@ -22,12 +26,29 @@ export default async function Page({
   getMdxSource,
 }: Props): Promise<ReactElement> {
   const { locale, slug } = await params;
+  // A page that composes `sections[]` renders them (JSON-LD is built from
+  // the same sections); a prose page renders its MDX body — the rule
+  // /vs/[slug] applies (#10122).
+  const source = await (getMdxSource ?? loadMdxSource)(
+    "Integration",
+    slug,
+    locale,
+  );
+  const composed =
+    source !== null &&
+    Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&
+    ((source.frontmatter as { sections?: unknown[] }).sections?.length ?? 0) >
+      0;
   return renderPage({
     type: "Integration",
     slug,
     locale,
-    bodyMode: "mdx-body",
-    populatedDescriptionTestId: "integration-description",
+    ...(composed
+      ? {}
+      : {
+          bodyMode: "mdx-body" as const,
+          populatedDescriptionTestId: "integration-description",
+        }),
     ...(getMdxSource !== undefined && { getMdxSource }),
   });
 }

package/templates/apps/web/app/[locale]/integrations/__tests__/hub-children.test.tsx

@@ -0,0 +1,38 @@
+/**
+ * Hub child cards (#10121) for /integrations. The shared cases live in
+ * `lib/__tests__/hub-children.fixtures.ts`; this file sits beside the route so
+ * a scaffold without /integrations drops it with the route (#10157).
+ */
+const mockRenderPage = jest.fn(async (..._args: unknown[]) => "<rendered/>");
+
+jest.mock("@working-theory/page-renderer", () => ({
+  __esModule: true,
+  renderPage: (...args: unknown[]) => mockRenderPage(...args),
+  renderPageMetadata: jest.fn(),
+  // Never reached — every call in this suite passes its loaders via DI.
+  getMdxSlugs: jest.fn(),
+  getMdxSource: jest.fn(),
+  getPageSections: jest.fn(),
+}));
+
+jest.mock("@working-theory/ui/sections", () => ({
+  __esModule: true,
+  SectionRenderer: () => null,
+}));
+
+import IntegrationsPage from "../page";
+import {
+  describeHub,
+  type HubPage,
+} from "../../../../lib/__tests__/hub-children.fixtures";
+
+describeHub(
+  [
+    "integrations",
+    IntegrationsPage as HubPage,
+    "IntegrationsList",
+    "Integration",
+    "mdx-body",
+  ],
+  mockRenderPage,
+);