create-ailk 0.22.0 → 0.24.0

package/templates/apps/web/lib/in-page-magnet.ts

@@ -0,0 +1,416 @@
+/**
+ * in-page-magnet.ts — the in-page form shape (#8847 D6, D15).
+ *
+ * A contact, quote or newsletter magnet renders from its hub record inside a
+ * chrome-on page: the page holds layout only, and every visible fact on the
+ * form (heading, sentence, fields, consent, button, ending) comes from the
+ * magnet's served config. /contact, /newsletter, /unsubscribe and the
+ * footer signup all read through here.
+ *
+ * - `sharedHubRead` shares a hub read across requests for HUB_READ_TTL_MS
+ *   (#8731, moved here from /contact): a visitor view carries no forwarding
+ *   headers, so on a spoke every view would otherwise count against the
+ *   spoke server's one per-IP limit at the hub. An Admin edit shows within
+ *   that window.
+ * - `readServedMagnet(slug)` is the public flow read; any throw or non-2xx
+ *   (absent, draft, a Free build with no flow route) is `null`.
+ * - `inPageView(config, locale, form)` maps a config's one field step. The
+ *   form kind comes from the CALLER, never the config or the slug (C1): a
+ *   served config carries no `kind`.
+ * - `framedSources` makes the page's first `contact-form` section carry the
+ *   magnet's title and body, and — when that section leads the page — the
+ *   frontmatter title too, so `renderPage`'s title carve-out gives the
+ *   section the `<h1>` and `renderPageMetadata` gives `<title>` the same text.
+ * - `renderInPageMagnet` is the slotted surface for a slug (D15): the form
+ *   bound to its action, or `ContactFallback` when capture is off.
+ *
+ * Pure apart from the two reads; no React state.
+ */
+import { flows, leads } from "@working-theory/api-client";
+import type {
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections,
+} from "@working-theory/page-renderer";
+import {
+  ContactFallback,
+  LeadCaptureForm,
+  type LeadCaptureFormText,
+  localeHref,
+  NewsletterFormInline,
+} from "@working-theory/ui";
+import {
+  flowLeadSource,
+  flowSitePathSchema,
+  resolveLocalizedString,
+  type FlowConfig,
+} from "@working-theory/validation";
+import { createElement, type ReactElement } from "react";
+
+import {
+  contactFormFromConfig,
+  type ContactFormView,
+} from "../app/[locale]/contact/contact-form-magnet";
+import { captureLeadAction } from "../app/[locale]/contact/contact.actions";
+
+import { consentPoliciesFor } from "./consent-policies";
+import { subscribeNewsletterAction } from "./newsletter.actions";
+
+
+export { fillEndingName } from "@working-theory/validation";
+
+// ─── Shared hub reads (#8731) ──────────────────────────────────────────────────
+
+/**
+ * How long a hub read is shared across requests (#8731). Short, so an Admin
+ * edit to the magnet shows within seconds; long enough that a burst of views
+ * makes one read of each, not one per view.
+ */
+export const HUB_READ_TTL_MS = 15_000;
+
+const hubReads = new Map<string, { at: number; read: Promise<unknown> }>();
+
+/**
+ * How long a page waits on one hub read before treating it as failed. The
+ * root layout reads the newsletter magnet for the footer on every page, so a
+ * hub that accepts the connection and stalls must not hold the site.
+ */
+export const HUB_READ_DEADLINE_MS = 2_000;
+
+/** `read`'s result, or `fallback` once HUB_READ_DEADLINE_MS has passed. */
+function withDeadline<T>(read: Promise<T>, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(fallback), HUB_READ_DEADLINE_MS);
+  });
+  return Promise.race([read, late]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * `read()`'s result, shared per instance for HUB_READ_TTL_MS. Concurrent calls
+ * share one in-flight read. A read that settles to `null` (any failed read,
+ * see the readers below) is shared the same way, so a burst against an
+ * unreachable hub is not a burst of retries.
+ */
+export function sharedHubRead<T>(key: string, read: () => Promise<T>): Promise<T> {
+  const now = Date.now();
+  const hit = hubReads.get(key);
+  if (hit && now - hit.at < HUB_READ_TTL_MS) return hit.read as Promise<T>;
+  const fresh = read();
+  hubReads.set(key, { at: now, read: fresh });
+  return fresh;
+}
+
+export type CaptureStatus = Extract<
+  Awaited<ReturnType<typeof leads.captureStatus>>,
+  { ok: true }
+>["body"]["data"];
+
+/** The API's capture status, or `null` for any failed read. */
+export function readCaptureStatus(): Promise<CaptureStatus | null> {
+  return sharedHubRead("capture-status", () =>
+    withDeadline(
+      (async () => {
+        try {
+          const res = await leads.captureStatus();
+          return res.ok && res.body.ok === true ? res.body.data : null;
+        } catch {
+          return null;
+        }
+      })(),
+      null,
+    ),
+  );
+}
+
+/**
+ * The served magnet's config at `slug`, or `null` for any failed read: a
+ * non-2xx (absent, draft, a build with no flow route), a throw, or no answer
+ * within HUB_READ_DEADLINE_MS. The
+ * property access sits inside the `try`, so a client with no `flows` is a
+ * failed read too.
+ */
+export function readServedMagnet(slug: string): Promise<FlowConfig | null> {
+  return sharedHubRead(`magnet:${slug}`, () =>
+    withDeadline(
+      (async () => {
+        try {
+          const res = await flows.get(slug);
+          return res.ok ? res.body : null;
+        } catch {
+          return null;
+        }
+      })(),
+      null,
+    ),
+  );
+}
+
+// ─── The view ──────────────────────────────────────────────────────────────────
+
+/** Which form a caller asks for (C1). */
+export type InPageForm = "contact" | "newsletter";
+
+/** The magnet's `ending.default`, resolved and localized (#8841 D1 shape). */
+export type InPageEnding =
+  | {
+      kind: "screen";
+      headline: string;
+      body?: string;
+      ctas?: { label: string; href: string }[];
+    }
+  | { kind: "redirect"; href: string };
+
+/** A newsletter magnet's one step, as `NewsletterFormInline` renders it. */
+export interface NewsletterFormView {
+  kind: "newsletter";
+  /** The `email` field's name — the key the step submit sends the address under. */
+  emailField: string;
+  label: string;
+  placeholder?: string;
+  /** The step's first consent field: its name, purposes, statement and help line. */
+  consent?: { field: string; purposes: string[]; statement: string; help?: string };
+  submitLabel?: string;
+}
+
+export interface InPageView {
+  stepKey: string;
+  title: string;
+  body?: string;
+  /** Absent when the config has no `ending` and the caller gave no fallback line. */
+  ending?: InPageEnding;
+  form: ContactFormView | NewsletterFormView;
+}
+
+type FieldStep = Extract<FlowConfig["steps"][number], { type: "field" }>;
+
+/** The field types a visitor types or picks a value into. */
+const ENTRY_TYPES = new Set(["text", "email", "tel", "url", "textarea", "select", "address"]);
+
+function newsletterForm(
+  step: FieldStep,
+  resolve: (value: Record<string, string>) => string,
+): NewsletterFormView | null {
+  const email = step.fields.find((f) => f.inputType === "email" && f.mapsTo === "email");
+  if (email === undefined) return null;
+  // Any other field a visitor fills in is not a one-field signup.
+  if (step.fields.some((f) => f !== email && ENTRY_TYPES.has(f.inputType))) return null;
+  const consent = step.fields.find((f) => f.inputType === "consent");
+  return {
+    kind: "newsletter",
+    emailField: email.name,
+    label: resolve(email.copy.label),
+    ...(email.copy.placeholder !== undefined && { placeholder: resolve(email.copy.placeholder) }),
+    ...(consent !== undefined && {
+      consent: {
+        field: consent.name,
+        purposes: consent.purposes ?? [],
+        statement: resolve(consent.copy.label),
+        ...(consent.copy.help !== undefined && { help: resolve(consent.copy.help) }),
+      },
+    }),
+    ...(step.copy.cta !== undefined && { submitLabel: resolve(step.copy.cta) }),
+  };
+}
+
+/**
+ * A config's one field step as an in-page form of the kind the caller names,
+ * or `null` when it is not one: its first step is not a `field` step, a
+ * newsletter config has more than one step or a field other than its email
+ * and consent, or a contact config lacks `name` and `email`. A config with no
+ * `ending` ends on `fallbackHeadline` (the page's catalog success line), or
+ * has no `ending` when the caller gives none, so the form keeps its own.
+ */
+export function inPageView(
+  config: FlowConfig,
+  locale: string,
+  form: InPageForm,
+  fallbackHeadline?: string,
+): InPageView | null {
+  const step = config.steps[0];
+  if (step?.type !== "field") return null;
+  const resolve = (value: Record<string, string>): string =>
+    resolveLocalizedString(value, locale, config.defaultLocale);
+
+  let view: ContactFormView | NewsletterFormView | null;
+  if (form === "newsletter") {
+    view = config.steps.length === 1 ? newsletterForm(step, resolve) : null;
+  } else {
+    view = contactFormFromConfig(config, locale);
+  }
+  if (view === null) return null;
+
+  // Every destination is re-checked against the site-path grammar before it
+  // is rendered or navigated to, as the walk does (#8840): a stored row that
+  // bypassed the write-side check never becomes an off-site link.
+  const onSite = (href: string): boolean => flowSitePathSchema.safeParse(href).success;
+  const outcome = config.ending?.default;
+  const fallback: InPageEnding | undefined =
+    fallbackHeadline === undefined ? undefined : { kind: "screen", headline: fallbackHeadline };
+  let ending: InPageEnding | undefined;
+  if (outcome === undefined) {
+    ending = fallback;
+  } else if (outcome.kind === "redirect") {
+    ending = onSite(outcome.href) ? { kind: "redirect", href: localeHref(locale, outcome.href) } : fallback;
+  } else {
+    const ctas = (outcome.ctas ?? []).filter((cta) => onSite(cta.href));
+    ending = {
+      kind: "screen",
+      headline: resolve(outcome.headline),
+      ...(outcome.body !== undefined && { body: resolve(outcome.body) }),
+      ...(ctas.length > 0 && {
+        ctas: ctas.map((cta) => ({
+          label: resolve(cta.label),
+          href: localeHref(locale, cta.href),
+        })),
+      }),
+    };
+  }
+
+  return {
+    stepKey: step.key,
+    title: resolve(step.copy.title),
+    ...(step.copy.body !== undefined && { body: resolve(step.copy.body) }),
+    ...(ending !== undefined && { ending }),
+    form: view,
+  };
+}
+
+// ─── The page frame ────────────────────────────────────────────────────────────
+
+type Loaders = {
+  getMdxSource: typeof defaultGetMdxSource;
+  getPageSections: typeof defaultGetPageSections;
+};
+type Section = Awaited<ReturnType<typeof defaultGetPageSections>>[number];
+
+/**
+ * The page's first `contact-form` section takes `headline = view.title` and
+ * `description = view.body` (deleted when there is none). When that section
+ * is the first non-alert section, the frontmatter `title` is `view.title`
+ * too. With no `contact-form` section, both loaders pass through unchanged.
+ */
+export function framedSources({
+  getMdxSource,
+  getPageSections,
+  view,
+}: Loaders & { view: Pick<InPageView, "title" | "body"> }): Loaders {
+  const framedSections = async (frontmatter: unknown): Promise<Section[]> => {
+    const sections = await getPageSections(frontmatter);
+    const at = sections.findIndex((s) => s.type === "contact-form");
+    if (at < 0) return sections;
+    return sections.map((section, i) => {
+      if (i !== at || section.type !== "contact-form") return section;
+      const data = { ...section.data, headline: view.title };
+      if (view.body !== undefined) data.description = view.body;
+      else delete data.description;
+      return { ...section, data };
+    });
+  };
+  const framedSource: typeof defaultGetMdxSource = async (type, slug, locale) => {
+    const source = await getMdxSource(type, slug, locale);
+    if (source === null) return source;
+    const sections = await getPageSections(source.frontmatter);
+    const leading = sections.find((s) => s.type !== "alert");
+    if (leading?.type !== "contact-form") return source;
+    return { ...source, frontmatter: { ...source.frontmatter, title: view.title } };
+  };
+  return { getMdxSource: framedSource, getPageSections: framedSections };
+}
+
+// ─── The slotted surface (D15) ─────────────────────────────────────────────────
+
+export interface NewsletterSignupOptions {
+  locale: string;
+  fallbackEmail?: string;
+  /** The footer's compact form: stacked, the label `sr-only`, the placeholder naming the field. */
+  compact?: boolean;
+  className?: string;
+}
+
+/**
+ * The newsletter magnet's signup: the standard `NewsletterFormInline` bound to
+ * `subscribeNewsletterAction`, every word from the view. On /newsletter the
+ * email label is visible and the field and Subscribe share a row from `md`;
+ * the footer's compact form stacks, with the label `sr-only`.
+ */
+export function newsletterSignup(
+  view: InPageView & { form: NewsletterFormView },
+  { locale, fallbackEmail, compact = false, className }: NewsletterSignupOptions,
+): ReactElement {
+  const { form, ending } = view;
+  const placeholder = form.placeholder ?? (compact ? form.label : undefined);
+  return createElement(NewsletterFormInline, {
+    formAction: subscribeNewsletterAction,
+    emailLabel: form.label,
+    ...(compact ? { layout: "stacked" as const } : { label: form.label }),
+    ...(placeholder !== undefined && { placeholder }),
+    ...(form.consent !== undefined && {
+      consentStatement: form.consent.statement,
+      policies: consentPoliciesFor(locale),
+      ...(form.consent.help !== undefined && { helpText: form.consent.help }),
+    }),
+    ...(form.submitLabel !== undefined && { submitLabel: form.submitLabel }),
+    // A redirect ending has no in-place form; the block's own success line stands.
+    ...(ending?.kind === "screen" && {
+      ending: { headline: ending.headline, ...(ending.body !== undefined && { body: ending.body }) },
+    }),
+    ...(fallbackEmail !== undefined && { fallbackEmail }),
+    ...(className !== undefined && { className }),
+  });
+}
+
+export interface RenderInPageMagnetInput {
+  slug: string;
+  locale: string;
+  /** The page's view of the magnet (`inPageView`), mapped for the caller's form. */
+  view: InPageView;
+  /** The `contact` catalog's form copy (`contactFormText`). */
+  text: LeadCaptureFormText;
+  accepting: boolean;
+  fallbackEmail?: string;
+}
+
+/**
+ * The surface a page slots for an in-page magnet: the form bound to its
+ * action, or `ContactFallback` when capture is off. A `contact` form posts
+ * through `captureLeadAction` stamped `flowLeadSource(slug)`; the action keeps
+ * only the contact sources (`CONTACT_LEAD_SOURCES`), so a quote magnet's post
+ * lands as `contact-form` until that list admits its slug. A `newsletter`
+ * form posts through `subscribeNewsletterAction`.
+ */
+export function renderInPageMagnet({
+  slug,
+  locale,
+  view,
+  text,
+  accepting,
+  fallbackEmail,
+}: RenderInPageMagnetInput): ReactElement {
+  if (!accepting) {
+    return createElement(ContactFallback, {
+      email: fallbackEmail,
+      text: {
+        heading: text.unavailableHeading,
+        body: text.unavailableBody,
+        noEmail: text.unavailableNoEmail,
+      },
+    });
+  }
+  const form = view.form;
+  if ("kind" in form) {
+    return newsletterSignup({ ...view, form }, { locale, ...(fallbackEmail !== undefined && { fallbackEmail }) });
+  }
+  return createElement(LeadCaptureForm, {
+    action: captureLeadAction,
+    text: form.consentStatement ? { ...text, consentStatement: form.consentStatement } : text,
+    termsHref: localeHref(locale, "/terms"),
+    policies: consentPoliciesFor(locale),
+    fallbackEmail,
+    fields: form.fields,
+    submitLabel: form.submitLabel,
+    ending: view.ending,
+    source: flowLeadSource(slug),
+    look: "column",
+    consentGate: "on-submit",
+  });
+}

package/templates/apps/web/lib/magnet-routes.ts

@@ -0,0 +1,44 @@
+/**
+ * The magnet walk's path predicate (#8840 D10, spec
+ * docs/specs/8840-a-default-full-screen-magnet-spec.md).
+ *
+ * A magnet's walk renders full-screen: `app/[locale]/layout.tsx` drops the
+ * Nav and the Footer for it, as it does for the auth and account paths, and
+ * keeps the cookie consent banner (a visitor can arrive straight at a walk).
+ * A walk is `/<magnet>/start` — any path whose last segment is `start` — or
+ * one of the two careers apply walks, `/careers/apply` and
+ * `/careers/<posting>/apply`, each bare or under an enabled-locale prefix
+ * (the `auth-routes.ts` rule). #8843's meeting pages add their paths here
+ * rather than writing a second predicate. #8848 D9 adds every page under
+ * `/reports/<slug>` — a gated landing, an ungated reader and the grant
+ * reader alike, since the path cannot tell them apart; `/reports` itself
+ * keeps its chrome. #9287 DD10 adds `/trial/request`, the trial magnet's
+ * walk; `/trial`, its landing, keeps its chrome.
+ *
+ * Fail-safe direction, as `isAuthPath()`: an absent or empty pathname
+ * answers `false`, so a missing `x-pathname` never strips a page's chrome.
+ *
+ * Core, not a module slice: the layout every scaffold carries imports it, and
+ * it names no paid code. No Next.js import — a pure function.
+ */
+export function isMagnetWalkPath(
+  pathname: string | undefined | null,
+  locales: readonly string[],
+): boolean {
+  if (!pathname) return false;
+  const path = pathname.split(/[?#]/)[0] ?? "";
+  const bare =
+    locales.length > 0
+      ? path.replace(new RegExp(`^/(${locales.join("|")})(?=/|$)`), "")
+      : path;
+  const segments = bare.split("/").filter((segment) => segment.length > 0);
+  if (segments.length === 0) return false;
+  if (segments[segments.length - 1] === "start") return true;
+  if (segments[0] === "reports" && segments.length === 2) return true;
+  if (segments.length === 2 && segments[0] === "trial" && segments[1] === "request") return true;
+  return (
+    segments[0] === "careers" &&
+    segments[segments.length - 1] === "apply" &&
+    (segments.length === 2 || segments.length === 3)
+  );
+}

package/templates/apps/web/lib/modules.generated.ts

@@ -0,0 +1,9 @@
+// modules.generated.ts — which module pages this site carries.
+//
+// GENERATED by create-ailk from this app's package.json dependencies (#8843).
+// Do not edit: every scaffold, `create-ailk add-module` and
+// `create-ailk update` rewrites it. It imports nothing, so edge code may
+// read it as well as the locale layout.
+
+/** The scheduling module's booking pages (/meet, /private) exist. */
+export const SCHEDULING_PAGES: boolean = false;

package/templates/apps/web/lib/newsletter.actions.ts

@@ -0,0 +1,205 @@
+"use server";
+
+/**
+ * subscribeNewsletterAction — Server Action paired with the
+ * `ailkSubscribeNewsletter` MCP tool (#6730 D9).
+ *
+ * `/newsletter` and the footer render the newsletter magnet's
+ * `NewsletterFormInline` bound to this action. Validates the address with
+ * its own `newsletterFormSchema` (the form's one field is the page's, not a
+ * wire contract — the `subscribe_newsletter` MCP tool takes the route body
+ * since #7172), calls `POST /v1/leads/subscribe` through
+ * `@working-theory/api-client`, and maps the outcome the same way
+ * `captureLeadAction` does: the API's 503 `lead_capture_not_configured` →
+ * `unavailable`; any other non-2xx or thrown error → the generic `error`;
+ * only a 2xx is `success`.
+ *
+ * Visitor forwarding (#7394): forwards the visitor exactly as
+ * `captureLeadAction` does, through `visitorForwardHeaders` and the
+ * server-only `AILK_VISITOR_FORWARD_KEY`; without them the call is made
+ * with one argument, as before.
+ *
+ * Through the magnet (#8847 D11): /newsletter, /unsubscribe's sibling footer
+ * signup and the page itself all render the workspace's `newsletter`
+ * magnet, so a signup goes through it. The action re-reads the magnet; a post
+ * without `consent=true` while that magnet has a consent field (or, with no
+ * magnet, ever) answers a `consent` field error and nothing is sent. When the
+ * magnet maps, the
+ * address and the consent go to `POST /v1/flows/newsletter/steps` — the step
+ * key, the email field's name and the consent field's purposes all come from
+ * the server's own read, never the post (SEC-8847-A) — which writes the lead,
+ * the consent ledger row and the magnet's welcome email. A 2xx that completes
+ * is success; a 503 `lead_capture_not_configured` or an unreachable API
+ * (status 0, 502, 504) is `unavailable`. Otherwise (a Free build has no flow
+ * route) it posts `leads.subscribe`, as before.
+ */
+
+import { flows, leads, visitorForwardHeaders } from "@working-theory/api-client";
+import { LEAD_CAPTURE_HONEYPOT, type LeadCaptureFormState } from "@working-theory/ui";
+import { NEWSLETTER_FLOW_SLUG } from "@working-theory/validation";
+import { cookies, headers } from "next/headers";
+import { getLocale } from "next-intl/server";
+import { z } from "zod";
+
+import { checkRateLimit, clientIpFromHeaders } from "../src/lib/rate-limit";
+
+import { consentVisitorHeader, readConsentVisitor } from "./consent-visitor";
+import { inPageView, readServedMagnet } from "./in-page-magnet";
+
+const GENERIC_ERROR = "Something went wrong, please try again.";
+const CONSENT_REQUIRED = "Please accept the terms to subscribe.";
+const RATE_LIMITED = "Too many signups from here. Please try again in a few minutes.";
+// #8847 (security review) — the contact action's per-visitor budget: the hub
+// sees this site's egress address on the step route, so one visitor must not
+// spend the bucket every visitor shares.
+const RATE_LIMIT_MAX_CALLS = 30;
+const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+
+/** The form's one field; zod's default message is the field error shown. */
+const newsletterFormSchema = z.object({ email: z.string().email() });
+
+/** The API's 503 for a deployment with nowhere to keep a lead. */
+function isNotConfigured(res: { status: number; body: unknown }): boolean {
+  return (
+    res.status === 503 &&
+    typeof res.body === "object" &&
+    res.body !== null &&
+    (res.body as { error?: unknown }).error === "lead_capture_not_configured"
+  );
+}
+
+/** An API that could not be reached: a thrown call (0), a 502 or a 504. */
+function isApiUnreachable(res: { status: number }): boolean {
+  return res.status === 0 || res.status === 502 || res.status === 504;
+}
+
+/**
+ * The signup through the served newsletter magnet, or `null` when it does not
+ * map (absent, draft, a Free build with no flow route, or not a one-field
+ * signup) — the caller then posts `leads.subscribe`.
+ */
+async function submitThroughMagnet(
+  email: string,
+  consented: boolean,
+  init: { headers: Record<string, string> } | undefined,
+): Promise<LeadCaptureFormState | null> {
+  const magnet = await readServedMagnet(NEWSLETTER_FLOW_SLUG);
+  let locale = "en";
+  try {
+    locale = await getLocale();
+  } catch {
+    // No request-scoped locale — the default locale.
+  }
+  const view = magnet ? inPageView(magnet, locale, "newsletter") : null;
+  if (view === null || !("kind" in view.form)) return null;
+  const { emailField, consent } = view.form;
+  // A magnet without a consent field (a wizard-built newsletter) asks for none.
+  if (consent !== undefined && !consented) {
+    return { kind: "error", fieldErrors: { consent: CONSENT_REQUIRED } };
+  }
+  const values: Record<string, unknown> = { [emailField]: email };
+  if (consent !== undefined) {
+    for (const purpose of consent.purposes) values[`${consent.field}.${purpose}`] = true;
+  }
+  const payload = { stepKey: view.stepKey, values, locale };
+  try {
+    const res = init
+      ? await flows.submitStep(NEWSLETTER_FLOW_SLUG, payload, init)
+      : await flows.submitStep(NEWSLETTER_FLOW_SLUG, payload);
+    if (res.ok) return res.body.completed ? { kind: "success" } : { kind: "error", message: GENERIC_ERROR };
+    if (isNotConfigured(res) || isApiUnreachable(res)) return { kind: "unavailable" };
+    return { kind: "error", message: GENERIC_ERROR };
+  } catch (err) {
+    // The api-client never attaches the request payload to a thrown error.
+    console.error("[subscribeNewsletterAction]", err);
+    return { kind: "unavailable" };
+  }
+}
+
+export async function subscribeNewsletterAction(
+  _prevState: LeadCaptureFormState,
+  formData: FormData,
+): Promise<LeadCaptureFormState> {
+  // Honeypot: a bot that fills the hidden field gets a person's answer, and
+  // nothing is sent.
+  const honeypot = formData.get(LEAD_CAPTURE_HONEYPOT);
+  if (typeof honeypot === "string" && honeypot !== "") return { kind: "success" };
+
+  const parsed = newsletterFormSchema.safeParse({
+    email: formData.get("email"),
+  });
+  if (!parsed.success) {
+    return {
+      kind: "error",
+      fieldErrors: { email: parsed.error.issues[0]?.message ?? "Invalid email" },
+    };
+  }
+
+  let requestHeaders: Awaited<ReturnType<typeof headers>> | undefined;
+  try {
+    requestHeaders = await headers();
+  } catch {
+    // No request scope to read — no forwarding, and the visitor is "unknown".
+  }
+
+  // No readable address: skip the per-visitor limit rather than put every
+  // visitor in one shared bucket (the contact action's rule).
+  const visitor = requestHeaders ? clientIpFromHeaders(requestHeaders) : "unknown";
+  if (
+    visitor !== "unknown" &&
+    !checkRateLimit(`newsletter:${visitor}`, RATE_LIMIT_MAX_CALLS, RATE_LIMIT_WINDOW_MS)
+  ) {
+    return { kind: "error", message: RATE_LIMITED };
+  }
+
+  let init: { headers: Record<string, string> } | undefined;
+  if (requestHeaders) {
+    const forwarded = visitorForwardHeaders(requestHeaders, process.env.AILK_VISITOR_FORWARD_KEY);
+    if (forwarded) init = { headers: forwarded };
+  }
+
+  // #8438 D12 — the banner's visitor id, so a later subscribe links its
+  // cookie choices to the client record. Absent or invalid → no header.
+  try {
+    const visitorId = readConsentVisitor(await cookies());
+    if (visitorId) init = { headers: { ...(init?.headers ?? {}), ...consentVisitorHeader(visitorId) } };
+  } catch {
+    // No request scope to read — subscribe with no visitor-link header.
+  }
+
+  const consented = formData.get("consent") === "true";
+  // The step route keys its limit on the forwarded address, as the walk's
+  // action sends it (flow.actions.ts).
+  const stepInit =
+    visitor !== "unknown"
+      ? { headers: { "x-forwarded-for": visitor, ...(init?.headers ?? {}) } }
+      : init;
+  const viaMagnet = await submitThroughMagnet(parsed.data.email, consented, stepInit);
+  if (viaMagnet !== null) return viaMagnet;
+  // The Free path renders the seeded config, whose consent box gates the post.
+  if (!consented) return { kind: "error", fieldErrors: { consent: CONSENT_REQUIRED } };
+
+  const siteId = process.env.AILK_SITE_ID ?? "default";
+  const body = { siteId, source: "newsletter", email: parsed.data.email };
+  try {
+    const res = init
+      ? await leads.subscribe(body, init)
+      : await leads.subscribe(body);
+    if (!res.ok) {
+      const error =
+        typeof res.body === "object" && res.body !== null
+          ? (res.body as { error?: unknown }).error
+          : undefined;
+      if (res.status === 503 && error === "lead_capture_not_configured") {
+        return { kind: "unavailable" };
+      }
+      return { kind: "error", message: GENERIC_ERROR };
+    }
+    return { kind: "success" };
+  } catch (err) {
+    // The api-client never attaches the request payload to a thrown error,
+    // so logging `err` carries no subscriber address.
+    console.error("[subscribeNewsletterAction]", err);
+    return { kind: "error", message: GENERIC_ERROR };
+  }
+}