@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/anonymous-access-multitenant/src/feature.ts

@@ -0,0 +1,65 @@
+// Multi-Tenant Anonymous Access — Subdomain-Resolver Pattern
+//
+// Use case: SaaS deployment where every customer gets `<tenant>.shop.com`.
+// Anonymous visitors land on the right tenant via the host header. The
+// recipe shows the three pieces an app needs:
+//
+//  1. tenantResolver — parses the Host header, looks up the tenantId in
+//     a small cache + DB. Returns null on misses (404 to the visitor).
+//  2. tenantExists   — guards header/cookie-supplied ids the same cache.
+//  3. setTenantCookie — once the resolver decided, persist on the visitor
+//     so subsequent requests skip the parse + DB lookup.
+//
+// The product/order entities are minimal — the focus of this recipe is
+// the resolution chain, not the domain logic. Pair this with the
+// single-tenant recipe (samples/recipes/anonymous-access/) for
+// comparison.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const productEntity = createEntity({
+  table: "mt_products",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+export const productTable = buildEntityTable("product", productEntity);
+
+export const multiTenantShopFeature = defineFeature("mtshop", (r) => {
+  r.entity("product", productEntity);
+
+  // Public listing — every tenant has its own products, scoped by tenantId
+  // automatically via the framework's tenant-isolation. Anonymous visitors
+  // see only the tenant they landed on.
+  r.queryHandler(
+    "product:list",
+    z.object({}),
+    async (_event, ctx) => ctx.db.selectMany(productTable),
+    {
+      access: { roles: [...access.anonymous, "User", "Admin"] },
+      rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    },
+  );
+
+  // Admin-only — proves role-gating still works on top of the multi-tenant
+  // anonymous resolution.
+  r.writeHandler(
+    "product:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const exec = createEventStoreExecutor(productTable, productEntity, {
+        entityName: "product",
+      });
+      return exec.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});

package/samples/recipes/anonymous-access-multitenant/src/subdomain-resolver.ts

@@ -0,0 +1,105 @@
+// Subdomain-based tenantResolver + tenantExists wired against an LRU cache.
+// Apps drop this into anonymousAccess: { tenantResolver, tenantExists, … }.
+//
+// Cache strategy: 5-minute TTL is the sweet spot — it absorbs traffic
+// bursts (a Reddit hug peaks for ~10 minutes; cache means one DB lookup
+// for the entire wave) without holding stale data so long that a freshly
+// disabled tenant keeps serving content. Apps with stricter SLA can drop
+// the TTL or call invalidateTenantCache(slug) from their disable-tenant
+// handler.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type TenantLookup = (subdomain: string) => Promise<TenantId | null>;
+export type TenantExistsLookup = (tenantId: TenantId) => Promise<boolean>;
+
+export type SubdomainResolverOptions = {
+  // Subdomain → tenantId. Typically queries the tenants table for an
+  // active row matching the slug (acme.shop.com → "acme"). Returning null
+  // is the legitimate "no such tenant" answer — throw only on infra
+  // failures.
+  readonly lookupBySubdomain: TenantLookup;
+  // tenantId → exists?. Called when a visitor presents an X-Tenant header
+  // or kumiko_tenant cookie (so a cookie that survives a server restart
+  // still re-validates against the DB on first use). Apps usually wrap
+  // the same tenants table — keep the implementation symmetric to
+  // lookupBySubdomain.
+  readonly existsById: TenantExistsLookup;
+  // Apex / non-tenant hosts that should NOT be resolved. Common pattern:
+  // `shop.com` is the marketing site, `app.shop.com` is the admin app —
+  // anonymous traffic to those should 404 rather than land on a default.
+  readonly reservedSubdomains?: readonly string[];
+  // TTL in seconds. Default 300s (5min) — see top-of-file rationale.
+  readonly cacheTtlSeconds?: number;
+};
+
+type CacheEntry<T> = { value: T; expiresAt: number };
+
+// Builds resolver + tenantExists that share independent caches by lookup
+// key (subdomain vs tenantId), so the two callbacks each amortise their
+// own DB load. Apps drop the returned object into
+// `anonymousAccess: { tenantResolver: r.tenantResolver, tenantExists: r.tenantExists }`.
+export function createSubdomainResolver(opts: SubdomainResolverOptions): {
+  tenantResolver: (c: {
+    req: { url: string; header: (name: string) => string | undefined };
+  }) => Promise<TenantId | null>;
+  tenantExists: (id: TenantId) => Promise<boolean>;
+  invalidate: (subdomainOrTenantId: string) => void;
+  invalidateAll: () => void;
+} {
+  const ttlMs = (opts.cacheTtlSeconds ?? 300) * 1000;
+  const reserved = new Set(opts.reservedSubdomains ?? ["www", "app", "api", "admin"]);
+  const subdomainCache = new Map<string, CacheEntry<TenantId | null>>();
+  const existsCache = new Map<TenantId, CacheEntry<boolean>>();
+
+  async function lookupBySubdomainCached(subdomain: string): Promise<TenantId | null> {
+    const now = Date.now();
+    const cached = subdomainCache.get(subdomain);
+    if (cached && cached.expiresAt > now) return cached.value;
+
+    const tenantId = await opts.lookupBySubdomain(subdomain);
+    subdomainCache.set(subdomain, { value: tenantId, expiresAt: now + ttlMs });
+    return tenantId;
+  }
+
+  async function existsByIdCached(tenantId: TenantId): Promise<boolean> {
+    const now = Date.now();
+    const cached = existsCache.get(tenantId);
+    if (cached && cached.expiresAt > now) return cached.value;
+
+    const exists = await opts.existsById(tenantId);
+    existsCache.set(tenantId, { value: exists, expiresAt: now + ttlMs });
+    return exists;
+  }
+
+  return {
+    tenantResolver: async (c) => {
+      const host = c.req.header("Host");
+      if (!host) return null;
+      const subdomain = extractSubdomain(host);
+      if (subdomain === null) return null;
+      if (reserved.has(subdomain)) return null;
+      return lookupBySubdomainCached(subdomain);
+    },
+    tenantExists: existsByIdCached,
+    invalidate: (key) => {
+      subdomainCache.delete(key);
+      existsCache.delete(key as TenantId);
+    },
+    invalidateAll: () => {
+      subdomainCache.clear();
+      existsCache.clear();
+    },
+  };
+}
+
+// Extracts the leftmost DNS label, dropping the port and assuming the
+// host has at least 3 labels (subdomain.domain.tld). Bare hosts like
+// "localhost" or "shop.com" return null so the caller falls through to
+// the "no tenant" branch.
+export function extractSubdomain(host: string): string | null {
+  const noPort = host.split(":")[0] ?? host;
+  const labels = noPort.split(".");
+  if (labels.length < 3) return null;
+  return labels[0] ?? null;
+}

package/samples/recipes/apex-landing/README.md

@@ -0,0 +1,32 @@
+## Screenshot renderer
+
+`bun run screenshot` renders the sample page and shoots a full-page PNG via
+Playwright (`page.setContent` — no server, because the renderer is pure). The
+spec also paints a product-board mock (`hero-app.png`), uses it in the hero
+`.shot-frame`, then writes `lightbox.png` with the overlay open. Docs embed
+`screenshots/landing.png` and `screenshots/apex/lightbox.png`.
+
+## GEO/AEO: schema.org JSON-LD
+
+`buildLandingPage`'s `head.schemaJson` combines `organizationSchema` +
+`webPageSchema` (from the `seo` feature) into one `@graph` block — Organization
++ WebPage nodes in a single `<script type="application/ld+json">`, which
+`renderApexPage` already knows how to emit. This is the seam an app extends
+with `faqPageSchema` for an FAQ section, or its own custom schema.org type.
+
+## Site discovery: sitemap.xml / llms.txt
+
+The recipe itself has no server (`renderApexPage` is a pure function — nothing
+to boot), but `src/__tests__/seo-routes.integration.test.ts` shows how an app
+mounts `createSeoFeature` alongside the thin `GET /` route that serves
+`renderLanding(...)`, and exercises `/sitemap.xml` + `/llms.txt` as real HTTP
+requests via `setupTestStack`.
+
+## Run
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test            # pure-function seams + the seo-mounted integration test
+bun run screenshot  # → screenshots/landing.png + lightbox.png
+```

package/samples/recipes/apex-landing/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-apex-landing",
+  "description": "Apex landing page composed from other features — hero copy from template-resolver, prices and caps from tier-engine — rendered to one static HTML string.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "screenshot": "bun x playwright test --config=playwright.config.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-headless": "workspace:*"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1"
+  }
+}

package/samples/recipes/apex-landing/playwright.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// No webServer: the Apex renderer is a pure function, so the runner feeds its
+// HTML straight into the page via setContent — nothing to boot.
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env["CI"],
+  retries: 0,
+  workers: 1,
+  reporter: [["list"]],
+  timeout: 60_000,
+  use: {
+    viewport: { width: 1920, height: 1080 },
+    deviceScaleFactor: 2,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"], viewport: { width: 1920, height: 1080 } },
+    },
+  ],
+});

package/samples/recipes/apex-landing/src/constants.ts

@@ -0,0 +1,7 @@
+/** Product UI mock in the hero `.shot-frame` — not the full-page docs shot. */
+export const HERO_SCREENSHOT = {
+  src: "/screenshots/hero-app.png",
+  alt: "Tasklane planning board — click to enlarge",
+  width: 720,
+  height: 480,
+} as const;

package/samples/recipes/apex-landing/src/feature.ts

@@ -0,0 +1,307 @@
+// Apex landing page — composed from OTHER features' data.
+//
+// `renderApexPage(page)` is a pure function: a typed `ApexPage` in, one HTML
+// string out. The interesting part is where that page's CONTENT comes from. An
+// app does not hard-code its landing copy or prices — it pulls them from the
+// features it already runs, so the marketing page can never drift from the
+// product:
+//
+//   • hero headline / tagline  ← template-resolver (kind `text-block`, keyed by slug)
+//   • prices and plan caps     ← tier-engine   (the app's plan config)
+//
+// `buildLandingPage` below shows both seams. It takes the data those features
+// expose and assembles an `ApexPage`; the app serves `renderApexPage(page)` as
+// one static, cacheable response.
+
+import { organizationSchema, webPageSchema } from "@cosmicdrift/kumiko-bundled-features/seo";
+import {
+  type ApexPage,
+  type ApexPricingTier,
+  renderApexPage,
+} from "@cosmicdrift/kumiko-headless/apex";
+import { HERO_SCREENSHOT } from "./constants";
+
+// --- Inputs: shapes the surrounding features hand you -----------------------
+
+/** Editable copy as the `template-resolver` feature projects it: a content string
+ *  per stable slug. A real app fills this Map from the template-resolver read model. */
+export type ContentBlocks = ReadonlyMap<string, string>;
+
+/** One plan as the app's `tier-engine` config exposes it. */
+export type PlanInfo = {
+  readonly key: string;
+  readonly name: string;
+  readonly tagline: string;
+  /** `null` = free or on-request; the renderer just shows the `amount` text. */
+  readonly monthlyEur: number | null;
+  /** Usage cap from the tier config; `Infinity` = unlimited. */
+  readonly maxProjects: number;
+  readonly benefits: readonly string[];
+  readonly featured?: boolean;
+};
+
+export type LandingInput = {
+  /** From `template-resolver`. Omit a slug and the baked-in fallback is used, so the
+   *  page renders fully even before anything is seeded. */
+  readonly blocks?: ContentBlocks;
+  /** From `tier-engine`. */
+  readonly plans: readonly PlanInfo[];
+  /** Override hero `.shot-frame` src — screenshot runner passes a data: URL. */
+  readonly heroScreenshot?: typeof HERO_SCREENSHOT;
+};
+
+// --- The two feature seams --------------------------------------------------
+
+/** template-resolver seam: block content if seeded, else the fallback baked in here. */
+function block(blocks: ContentBlocks | undefined, slug: string, fallback: string): string {
+  return blocks?.get(slug) ?? fallback;
+}
+
+function formatEuro(n: number): string {
+  return `${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })} €`;
+}
+
+function planAmount(plan: PlanInfo): string {
+  if (plan.monthlyEur === null) return plan.key === "enterprise" ? "Let's talk" : "0 €";
+  return formatEuro(plan.monthlyEur);
+}
+
+function planCap(plan: PlanInfo): string {
+  return Number.isFinite(plan.maxProjects)
+    ? `${plan.maxProjects.toLocaleString("en-US")} projects`
+    : "Unlimited projects";
+}
+
+/** tier-engine seam: one plan from the config → one Apex pricing card. */
+function toPricingTier(plan: PlanInfo): ApexPricingTier {
+  const paid = plan.monthlyEur !== null;
+  return {
+    name: plan.name,
+    tagline: plan.tagline,
+    amount: planAmount(plan),
+    priceSuffix: paid ? "/month" : undefined,
+    featured: plan.featured,
+    badge: plan.featured ? "Popular" : undefined,
+    capLine: planCap(plan),
+    benefits: plan.benefits,
+    cta: {
+      label: plan.key === "enterprise" ? "Contact us" : `Choose ${plan.name}`,
+      href: plan.key === "enterprise" ? "/contact" : "/signup",
+      variant: plan.featured ? "primary" : "secondary",
+    },
+  };
+}
+
+// --- Assembly ---------------------------------------------------------------
+
+const FEATURE_ICON = {
+  bolt: '<path d="M13 2 4 14h6l-1 8 9-12h-6z"/>',
+  shield: '<path d="M12 3 5 6v6c0 4 3 7 7 9 4-2 7-5 7-9V6z"/><path d="m9 12 2 2 4-4"/>',
+  layers: '<path d="m12 3 9 5-9 5-9-5z"/><path d="m3 13 9 5 9-5"/>',
+} as const;
+
+const BRAND_TOKENS = `:root{
+  --bg:#ffffff; --bg-card:#ffffff; --bg-muted:#f6f7f9;
+  --border:#e6e8ec; --fg:#0f1729; --fg-muted:#475067; --fg-subtle:#6b7280;
+  --primary:#4f46e5; --primary-hover:#4338ca; --primary-fg:#ffffff;
+  --accent:#4f46e5; --accent-fg:#ffffff; --accent-hover:#6366f1;
+  --status-ok:#16a34a; --shadow:0 12px 30px -12px rgba(15,23,42,.25);
+  --footer-cols:3;
+  --font-body:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  --font-mono:ui-monospace,SFMono-Regular,"SF Mono",Menlo,monospace;
+}`;
+
+export function buildLandingPage(input: LandingInput): ApexPage {
+  return {
+    theme: "light",
+    brand: { tokensCss: BRAND_TOKENS },
+    head: {
+      lang: "en",
+      title: block(input.blocks, "index:meta.title", "Tasklane — ship your roadmap"),
+      description: block(
+        input.blocks,
+        "index:meta.description",
+        "Plan, track and ship product work in one place. Free to start, no credit card.",
+      ),
+      canonicalUrl: "https://tasklane.example/",
+      // GEO/AEO seam: schema.org JSON-LD via the seo feature's pure builders
+      // (organizationSchema/webPageSchema), fed straight into ApexHead —
+      // renderApexPage already emits the <script type="application/ld+json">
+      // block, this recipe only supplies the data. Two node types share one
+      // block via @graph (a single schemaJson can't hold two top-level @type
+      // values). Site-discovery (sitemap.xml/llms.txt) for an app that also
+      // mounts managed-pages/legal-pages is demonstrated separately in
+      // samples/apps/use-all-bundled's createSeoFeature wiring — this recipe
+      // has no server/feature of its own to attach routes to.
+      schemaJson: {
+        "@context": "https://schema.org",
+        "@graph": [
+          organizationSchema({ name: "Tasklane", url: "https://tasklane.example/" }),
+          webPageSchema({
+            name: block(input.blocks, "index:meta.title", "Tasklane — ship your roadmap"),
+            url: "https://tasklane.example/",
+            description: block(
+              input.blocks,
+              "index:meta.description",
+              "Plan, track and ship product work in one place. Free to start, no credit card.",
+            ),
+          }),
+        ],
+      },
+    },
+    header: {
+      brand: { href: "/", label: "Tasklane" },
+      // A dropdown nav entry (kind:"menu") renders an icon/title/desc panel on
+      // hover + keyboard focus; plain links sit beside it. One typed shape, no
+      // app CSS — the renderer ships the dropdown styling.
+      navLinks: [
+        {
+          kind: "menu",
+          label: "Product",
+          items: [
+            {
+              icon: FEATURE_ICON.bolt,
+              title: "Live planning",
+              desc: "Reorder, estimate and assign as you type.",
+              href: "#features",
+            },
+            {
+              icon: FEATURE_ICON.layers,
+              title: "Portfolio view",
+              desc: "Every project on one screen, at a glance.",
+              href: "#features",
+            },
+            {
+              icon: FEATURE_ICON.shield,
+              title: "Your data, yours",
+              desc: "EU-hosted, no tracking, export any time.",
+              href: "#features",
+            },
+          ],
+          footer: { label: "See all features", href: "#features" },
+        },
+        { label: "Pricing", href: "#pricing" },
+      ],
+      actions: [{ label: "Sign in", href: "/login", variant: "link" }],
+    },
+    sections: [
+      {
+        kind: "hero",
+        title: block(input.blocks, "index:hero.title", "Ship your roadmap, not your spreadsheet"),
+        tagline: block(
+          input.blocks,
+          "index:hero.tagline",
+          "Plan, track and ship product work in one place — free to start, no credit card.",
+        ),
+        ctas: [
+          { label: "Start free", href: "/signup", variant: "primary" },
+          { label: "See pricing", href: "#pricing", variant: "secondary" },
+        ],
+        metaHtml: "<strong>Free forever plan.</strong> No credit card required.",
+        screenshot: input.heroScreenshot ?? HERO_SCREENSHOT,
+      },
+      {
+        kind: "feature-grid",
+        id: "features",
+        eyebrow: "Features",
+        heading: "Everything your team needs to ship",
+        sub: "From a single backlog to the whole portfolio — without tab-juggling.",
+        items: [
+          {
+            icon: FEATURE_ICON.bolt,
+            title: "Live planning",
+            desc: "Reorder, estimate and assign in one board that updates as you type.",
+          },
+          {
+            icon: FEATURE_ICON.layers,
+            title: "Portfolio view",
+            desc: "Every project on one screen: progress, owners and ship dates at a glance.",
+          },
+          {
+            icon: FEATURE_ICON.shield,
+            title: "Your data, yours",
+            desc: "EU-hosted, no tracking, export any time. Privacy is the baseline, not a tier.",
+          },
+        ],
+      },
+      {
+        kind: "pricing-grid",
+        id: "pricing",
+        eyebrow: "Pricing",
+        heading: "Fair prices, clear limits",
+        sub: "Start free. Upgrade when your portfolio grows. Cancel any time.",
+        tiers: input.plans.map(toPricingTier),
+      },
+      {
+        kind: "final-cta",
+        heading: "Your first board in two minutes",
+        sub: "Start free — no credit card, no install.",
+        cta: { label: "Start free", href: "/signup", variant: "primary" },
+      },
+    ],
+    footer: {
+      brand: { label: "Tasklane" },
+      tagline: "Ship your roadmap.",
+      columns: [
+        {
+          heading: "Product",
+          links: [
+            { label: "Features", href: "#features" },
+            { label: "Pricing", href: "#pricing" },
+          ],
+        },
+        {
+          heading: "Company",
+          links: [
+            { label: "About", href: "/about" },
+            { label: "Contact", href: "/contact" },
+          ],
+        },
+        {
+          heading: "Legal",
+          links: [
+            { label: "Privacy", href: "/legal/privacy" },
+            { label: "Imprint", href: "/legal/imprint" },
+          ],
+        },
+      ],
+      bottomLeft: "© 2026 Tasklane",
+      bottomRight: "Made with Kumiko",
+    },
+  };
+}
+
+/** Convenience: input → final HTML string an app serves as its landing page. */
+export function renderLanding(input: LandingInput): string {
+  return renderApexPage(buildLandingPage(input));
+}
+
+/** Sample plan config, as a `tier-engine`-backed app would expose it.
+ *  Used by the test and the screenshot runner. */
+export const SAMPLE_PLANS: readonly PlanInfo[] = [
+  {
+    key: "free",
+    name: "Free",
+    tagline: "For your first project",
+    monthlyEur: null,
+    maxProjects: 3,
+    benefits: ["Live planning board", "Up to 5 collaborators", "CSV export"],
+  },
+  {
+    key: "pro",
+    name: "Pro",
+    tagline: "For a growing team",
+    monthlyEur: 12,
+    maxProjects: 50,
+    benefits: ["Everything in Free", "Portfolio view", "Custom fields", "Priority support"],
+    featured: true,
+  },
+  {
+    key: "enterprise",
+    name: "Enterprise",
+    tagline: "For the whole org",
+    monthlyEur: null,
+    maxProjects: Number.POSITIVE_INFINITY,
+    benefits: ["Everything in Pro", "SSO & SCIM", "Dedicated instance", "SLA"],
+  },
+];

package/samples/recipes/apex-surface-auth/README.md

@@ -0,0 +1,114 @@
+# apex-surface-auth
+
+The **standard pattern for public apex auth**: login, signup, forgot-password,
+and account-deletion on your marketing surface — schema-less, anonymously
+reachable, without leaking admin nav or internal topology.
+
+A typical app has two mounts sharing locale and primitives:
+
+- **Admin UI** → `createKumikoApp` (loads the full schema after login via
+  the authenticated `GET /api/schema`)
+- **Apex** → `createPublicSurface` (no schema, ever)
+
+## What it shows
+
+- **Four public routes** — `/login`, `/signup`, `/forgot-password`,
+  `/delete-account` (+ confirm) using bundled auth screens.
+- **`createPublicSurface`** — stacks `clientFeatures` providers and i18n only,
+  **not** their gates (an `AuthGate` would lock the public surface).
+- **`AuthShellProvider`** — auth card inside marketing chrome instead of
+  fullscreen (optional; default fullscreen still works).
+- **`composeApexAccountApp()`** — server feature list for all four flows.
+- **Anonymous deletion** — email-verified magic-link flow when the user cannot
+  log in (GDPR Art. 17 lockout case).
+- **`anonymousAccess`** — lets unauthenticated `/api/write` hit anonymous
+  handlers on the apex host tenant.
+
+## Client: `createPublicSurface` + `AuthShell`
+
+```tsx illustration
+import {
+  ForgotPasswordScreen, SignupScreen, createLoginRoute,
+  AuthShellProvider, emailPasswordClient,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import {
+  RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
+} from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
+import { createPublicSurface } from "@cosmicdrift/kumiko-renderer-web";
+
+// createLoginRoute, not a raw LoginScreen render — it owns the challenge-
+// swap for a second factor, so mounting auth-mfa later doesn't need this
+// route touched again. Pass `mfaVerifyScreen: MfaVerifyScreen` (from
+// `.../auth-mfa/web`) once the app mounts auth-mfa.
+const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
+
+createPublicSurface({
+  clientFeatures: [emailPasswordClient()],   // SessionProvider + i18n
+  shell: ({ children }) => (
+    <MarketingChrome>
+      <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
+        {children}
+      </AuthShellProvider>
+    </MarketingChrome>
+  ),
+  routes: [
+    { path: "/login",           component: <LoginRoute /> },
+    { path: "/signup",          component: <SignupScreen loginHref="/login" /> },
+    { path: "/forgot-password", component: <ForgotPasswordScreen loginHref="/login" /> },
+    { path: "/delete-account",         component: <RequestAccountDeletionScreen /> },
+    { path: "/delete-account/confirm", component: <ConfirmAccountDeletionScreen /> },
+  ],
+  fallback: <LoginRoute />,
+});
+```
+
+## Server: composition + `anonymousAccess`
+
+`composeApexAccountApp()` (see `src/feature.ts`) mounts features for all four
+flows. Login/signup/password reset come from `auth-email-password`; the
+anonymous **email-verified** deletion flow from `user-data-rights`:
+
+- `request-deletion-by-email` (anonymous, enumeration-safe) → magic link
+- `confirm-deletion-by-token` (anonymous) → starts grace period
+
+```ts illustration
+runProdApp({
+  features: composeApexAccountApp({
+    deletionTokenSecret: process.env.DELETION_TOKEN_SECRET!,
+    deletionVerifyUrl: "https://app.example.com/delete-account/confirm",
+    sendDeletionVerificationEmail: async ({ email, verifyUrl }) => {
+      // Must be non-blocking (enqueue) — synchronous send enables timing oracle.
+      await delivery.notify("account.deletion.verify", { email, verifyUrl });
+    },
+  }),
+  anonymousAccess: { defaultTenantId: APEX_TENANT_ID },
+});
+```
+
+## Why deletion is anonymous
+
+GDPR Art. 17 applies when the user **cannot log in** (lockout). The flow is
+email-verified (magic link), not login-gated. The HMAC token carries `userId`
++ expiry (no DB table); purpose `"deletion-request"` blocks replay on other
+token endpoints. Second confirm is idempotent (`user_not_in_active_state`).
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Proves end-to-end over real `/api/write` without auth:
+
+1. `request-deletion-by-email` → verification email enqueued
+2. `confirm-deletion-by-token` → user status `DeletionRequested`
+3. Unknown email → same 200 response, no mail (enumeration-safe)
+
+## Related samples
+
+- [user-profile](/en/samples/recipes-user-profile/) — logged-in self-service
+  profile (password, email, deletion while authenticated).
+- [session-revocation](/en/samples/recipes-session-revocation/) — wire
+  `createSessionCallbacks()` so logout invalidates JWTs server-side.