@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/examples/purchasing/src/routes.ts

@@ -0,0 +1,53 @@
+import { ContractError, type Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import confirmOrder from "../generated/procedures/confirm-order.js";
+import { handlers } from "./handlers.js";
+import { requestsPage } from "./requests-page.js";
+import { signInPage } from "./sign-in.js";
+
+const MAX_BODY = 64 * 1024, MAX_SKEW_SECONDS = 300;
+
+/**
+ * App-owned routes, tried before Admin, MCP and REST. Return undefined to fall through.
+ * GET /sign-in: member sign-in (src/sign-in.ts). GET /requests: the employee's page (src/requests-page.ts).
+ * POST /callbacks/supplier: the supplier confirms an order. The signature is checked over the RAW body before parsing.
+ * AGENT: match the real supplier's signature scheme (header names, what is signed, encoding).
+ */
+export async function appRoutes(request: Request, env: Env, context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
+  const path = new URL(request.url).pathname;
+  if (path === "/sign-in" && request.method === "GET") return signInPage();
+  if (path === "/requests" && request.method === "GET") return requestsPage(request, env, await context.caller());
+  if (path !== "/callbacks/supplier") return undefined;
+  if (request.method !== "POST") return new Response(null, { status: 405, headers: { allow: "POST" } });
+  if (Number(request.headers.get("content-length") ?? MAX_BODY + 1) > MAX_BODY) return new Response(null, { status: 413 });
+  const raw = await request.arrayBuffer();
+  const timestamp = request.headers.get("x-supplier-timestamp") ?? "";
+  if (!(await verified(env.SUPPLIER_WEBHOOK_SECRET, timestamp, raw, request.headers.get("x-supplier-signature") ?? "")))
+    return new Response(null, { status: 401 });
+
+  let body: { reference?: unknown; orderId?: unknown };
+  try { body = JSON.parse(new TextDecoder().decode(raw)); } catch { return new Response(null, { status: 400 }); }
+  if (typeof body.reference !== "string" || typeof body.orderId !== "string") return new Response(null, { status: 400 });
+  // Trusted path: a system caller, after the signature proved the sender.
+  const system: Caller = { kind: "system", reason: "supplier callback" };
+  try {
+    await confirmOrder(env.DB, system, { id: body.reference, supplierOrderId: body.orderId });
+  } catch (error) {
+    if (!(error instanceof ContractError && error.code === "CONFLICT")) throw error;
+    // A replay of a callback already applied succeeds again, so the supplier stops retrying.
+    const current = await store(env.DB, system, { handlers }).collection("requests").findById(body.reference);
+    if (current?.requeststatus === "confirmed" && current.supplierorderid === body.orderId) return new Response(null, { status: 204 });
+    return new Response(null, { status: 409 }); // unknown request, another order id, or not approved/ordered
+  }
+  return new Response(null, { status: 204 });
+}
+
+/** HMAC-SHA256 over `${timestamp}.${raw body}`, hex encoded; crypto.subtle.verify compares in constant time. */
+async function verified(secret: string, timestamp: string, raw: ArrayBuffer, signature: string) {
+  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > MAX_SKEW_SECONDS) return false;
+  if (!/^[0-9a-f]{64}$/.test(signature)) return false;
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+  const signed = new Uint8Array([...new TextEncoder().encode(`${timestamp}.`), ...new Uint8Array(raw)]);
+  const bytes = new Uint8Array(signature.match(/../g)!.map(pair => parseInt(pair, 16)));
+  return crypto.subtle.verify("HMAC", key, bytes, signed);
+}

package/docs/examples/purchasing/src/schedule.ts

@@ -0,0 +1,31 @@
+import { toCloudflareCron } from "@aotter/mantle/cron";
+import type { Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import approvedRequests from "../generated/views/approved-requests.js";
+import staleRequests from "../generated/views/stale-requests.js";
+import { handlers } from "./handlers.js";
+import { adminEmails, notify } from "./notify.js";
+import { placeOrder } from "./supplier.js";
+
+/** Daily 09:00 UTC; list the same expression in wrangler.jsonc `triggers.crons`. */
+export const DAILY = toCloudflareCron("0 9 * * *");
+/** Remind about requests still 'submitted' after this many days. */
+const PENDING_DAYS = 3;
+
+export async function scheduled(controller: ScheduledController, env: Env): Promise<void> {
+  if (controller.cron !== DAILY) throw new Error(`No application schedule runs on '${controller.cron}'`);
+  const system: Caller = { kind: "system", reason: "daily purchasing cron" };
+
+  // 1. Retry supplier orders that failed right after approval.
+  const data = store(env.DB, system, { handlers });
+  for (const { id, title, amount } of await approvedRequests(env.DB, system, {}))
+    await placeOrder(data, { id: String(id), title: String(title), amount: Number(amount) }); // View rows are typed loosely
+
+  // 2. Remind admins about requests waiting too long.
+  const before = new Date(controller.scheduledTime - PENDING_DAYS * 86_400_000).toISOString();
+  const stale = await staleRequests(env.DB, system, { before });
+  if (stale.length === 0) return;
+  const text = `${stale.length} purchase request(s) have waited more than ${PENDING_DAYS} days:\n` +
+    stale.map(r => `- ${r.title} (${r.department}, ${r.amount})`).join("\n");
+  for (const to of await adminEmails()) await notify(to, "Purchase requests waiting for approval", text, "purchasing.reminder");
+}

package/docs/examples/purchasing/src/signup.ts

@@ -0,0 +1,5 @@
+/** Employees only: an email may create an account only on the company's domain (ADMIN_EMAIL always signs in). */
+export async function allowSignUp(env: Env, email: string): Promise<boolean> {
+  // AGENT: set EMPLOYEE_DOMAIN in wrangler.jsonc vars; for a per-person list, see the club-events example.
+  return email.toLowerCase().endsWith(`@${env.EMPLOYEE_DOMAIN.toLowerCase()}`);
+}

package/docs/examples/purchasing/src/supplier.ts

@@ -0,0 +1,32 @@
+import { env } from "cloudflare:workers";
+import { ContractError } from "@aotter/mantle/contracts";
+import type { HandlerContext } from "../generated/generated.js";
+
+/**
+ * Orders an approved request from the supplier, then marks it 'ordered'. Returns false when the supplier could not be
+ * reached; the request stays 'approved' and the daily cron (src/schedule.ts) retries it.
+ * AGENT: use the supplier's real API, auth and payload.
+ */
+export async function placeOrder(store: HandlerContext["store"], request: { id: string; title: string; amount: number }) {
+  let orderId: string;
+  try {
+    const response = await fetch(env.SUPPLIER_API_URL, {
+      method: "POST",
+      // The request id as idempotency key: a retry after a lost response does not order twice.
+      headers: { "content-type": "application/json", "idempotency-key": request.id },
+      body: JSON.stringify({ reference: request.id, item: request.title, amount: request.amount }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) throw new Error(`supplier answered ${response.status}`);
+    ({ orderId } = await response.json() as { orderId: string });
+  } catch (error) {
+    console.error(`[purchasing] supplier order for ${request.id} failed; it stays approved for the retry`, error);
+    return false;
+  }
+  try { await store.procedures["mark-ordered"]({ id: request.id, supplierOrderId: orderId }); }
+  catch (error) {
+    // The supplier's callback already confirmed it (it can arrive before this write).
+    if (!(error instanceof ContractError && error.code === "CONFLICT")) throw error;
+  }
+  return true;
+}

package/docs/examples/purchasing/wrangler.jsonc

@@ -0,0 +1,69 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-app",
+  "main": "dist/worker/index.js",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "global_fetch_strictly_public"
+  ],
+  "vars": {
+    "EMPLOYEE_DOMAIN": "example.com"
+  },
+  "secrets": {
+    "required": [
+      "BETTER_AUTH_SECRET",
+      "PUBLIC_ORIGIN",
+      "ADMIN_EMAIL",
+      "SUPPLIER_API_URL",
+      "SUPPLIER_WEBHOOK_SECRET"
+    ]
+  },
+  "observability": {
+    "enabled": true,
+    "logs": {
+      "enabled": true,
+      "head_sampling_rate": 1
+    },
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.01
+    }
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-app"
+    }
+  ],
+  "assets": {
+    "directory": "dist/client",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": [
+      "0 9 * * *"
+    ]
+  },
+  "no_bundle": true,
+  "find_additional_modules": true,
+  "base_dir": "dist/worker",
+  "build": {
+    "command": "mantle bundle src/index.ts dist",
+    "watch_dir": [
+      "src",
+      "generated"
+    ]
+  },
+  "rules": [
+    {
+      "type": "ESModule",
+      "globs": [
+        "**/*.js"
+      ],
+      "fallthrough": true
+    }
+  ]
+}

package/docs/examples/recipes/README.md

@@ -0,0 +1,58 @@
+# Recipes
+
+A multilingual recipe site. Admins write recipes in Admin as drafts and publish them; visitors read the published
+recipes in Traditional Chinese (`zh-TW`, the default) and English (`en`) without signing in. The visitor pages are
+plain app-owned HTML with the head tags search and answer engines read, plus Markdown and `llms.txt` for AI agents.
+
+## Capabilities shown
+
+- Publishing lifecycle (draft → publish): `lifecycle: publishing` on both Schemas in `manifests/recipes.yaml`;
+  Admin's publish action runs the generated `recipes.publish` Procedure. Public Views and anonymous Store reads see
+  published rows only.
+- Translations: `recipe_translations` is `localized` and `translates: { parent: recipes, on: slug }`. A translation
+  publishes only while its parent is published, and its reads merge the parent's `total_minutes`, `servings` and
+  `cover_url` (`src/routes.ts` `read`).
+- Visitor pages in `src/routes.ts` (routing, reads) and `src/pages.ts` (rendering), always read as an anonymous caller:
+  - every item of [public pages](../../handbook/guides/public-pages.md): head tags, Open Graph, JSON-LD `Recipe`, the
+    short answer block, hreflang and `x-default`, per-language Markdown alternates, `llms.txt`, sitemap and robots.
+- Cover images on R2: `wrangler.jsonc` (the shell's file plus the `MEDIA` bucket and two vars), `src/site-config.ts`
+  (media purpose `cover`) and `src/media.ts` (`r2MediaStorage`). See "Cover images" below to switch it on.
+
+Search for `AGENT:` for what an app must still provide: layout and styling, cache policy, list paging, the S3 signer.
+
+## Combine with
+
+- Need members to see or edit only their own rows? Add club-events' `restrict: { recipes: "author_id = auth.uid()" }` on a View.
+- Need review before publishing, or an AI that approves? Add purchasing's guarded status transitions and admin MCP.
+
+## Copy
+
+```sh
+cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
+cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/
+cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
+```
+
+Then follow the shell README (`db:init`, `dev`). Sign in at `/admin`, add a recipe, publish it, open `/zh-TW/`.
+Add a translation from the recipe's language tab and publish it to get `/en/`.
+
+## Cover images
+
+The media library needs the generated site module, which the shell does not generate. To switch it on:
+
+1. In `package.json`, add `--site src/site-config.ts` to both the `generate` and `check` commands, then
+   `pnpm generate` (this adds the `site_config`/`media_assets` tables to `generated/schema.sql`).
+2. In `src/service.ts`, import `site` from `../generated/site.js` and `coverStorage` from `./media.js`, and add
+   `site, media: coverStorage(env, signer)` to `adminOptions`. The signer is app-owned (see `src/media.ts`).
+3. Create the bucket, set CORS and the two `vars` in `wrangler.jsonc` (see `docs/handbook/cloudflare/media-r2.md`).
+
+Admin's media library then uploads straight to R2 with presigned URLs; copy a committed image's URL into `cover_url`.
+The smoke does not cover upload: local `wrangler dev` has an R2 binding but no S3 endpoint to presign against.
+
+## `pnpm smoke` proves
+
+- Drafts (zh-TW and en) are absent from detail, `.md`, list and `llms.txt`, even when the request has an admin session.
+- A translation cannot publish before its parent; publishing both through the Admin API makes them visible.
+- Each locale's detail page has title, description, canonical, hreflang (`zh-TW`, `en`, `x-default`) and a switcher link.
+- JSON-LD parses as a `Recipe` with the recipe name; the en page inherits `totalTime` from its parent; the short answer is present.
+- `.md` returns `text/markdown`; `llms.txt` and both locale lists show the published recipe; `/` redirects to `/zh-TW/`.

package/docs/examples/recipes/manifests/recipes.yaml

@@ -0,0 +1,75 @@
+# Recipes. The parent row is the default locale (zh-TW); recipe_translations holds each other locale (en, ...).
+# Both use the publishing lifecycle: Admin creates drafts, publish makes them visible to visitors.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: {name: recipes}
+spec:
+  title: Recipes
+  lifecycle: publishing
+  uniqueIndexes: [[slug]]
+  searchableFields: [title]
+  schema:
+    type: object
+    required: [slug, title, summary, ingredients, steps, total_minutes, servings]
+    properties:
+      slug: {type: string, pattern: "^[a-z0-9-]+$", maxLength: 80}
+      title: {type: string}
+      summary: {type: string, description: "One or two sentences; used as the meta description."}
+      ingredients: {type: string, description: "One ingredient per line."}
+      steps: {type: string, description: "One step per line."}
+      total_minutes: {type: integer, minimum: 1}
+      servings: {type: integer, minimum: 1}
+      cover_url: {type: string, description: "Public URL of a committed cover image from the media library."}
+  uiSchema:
+    fields:
+      summary: {widget: textarea}
+      ingredients: {widget: textarea}
+      steps: {widget: textarea}
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: {name: recipe_translations}
+spec:
+  title: Recipe translations
+  lifecycle: publishing
+  localized: true
+  # Shares `slug` with its parent; reads merge the parent's total_minutes, servings and cover_url.
+  # A translation publishes only while its parent is published.
+  translates: {parent: recipes, on: slug}
+  uniqueIndexes: [[slug, locale]]
+  schema:
+    type: object
+    required: [slug, locale, title, summary, ingredients, steps]
+    properties:
+      slug: {type: string, maxLength: 80}
+      locale: {type: string, description: "BCP 47 tag, e.g. en"}
+      title: {type: string}
+      summary: {type: string}
+      ingredients: {type: string}
+      steps: {type: string}
+  uiSchema:
+    fields:
+      summary: {widget: textarea}
+      ingredients: {widget: textarea}
+      steps: {widget: textarea}
+---
+# Visitor list for the default locale. Public Views return published rows only.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: published_recipes}
+spec:
+  surface: public
+  sql: SELECT id, slug, title, summary FROM recipes ORDER BY id
+---
+# Visitor list for one translated locale; a translation is hidden while its parent is unpublished.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: published_translations}
+spec:
+  surface: public
+  input:
+    type: object
+    required: [locale]
+    additionalProperties: false
+    properties: {locale: {type: string, minLength: 2, maxLength: 35}}
+  sql: SELECT id, slug, title, summary FROM recipe_translations WHERE locale = input.locale ORDER BY id

package/docs/examples/recipes/smoke.mjs

@@ -0,0 +1,102 @@
+// Recipes acceptance: drafts stay hidden, publishing via the Admin API makes both locales visible with SEO, JSON-LD,
+// hreflang, Markdown alternates, llms.txt, sitemap and robots.
+import assert from "node:assert/strict";
+import { smoke } from "./smoke-kit.mjs";
+
+const recipe = {
+  slug: "scallion-pancake", title: "蔥油餅", summary: "外酥內軟的蔥油餅 </script>", total_minutes: 25, servings: 2,
+  ingredients: "中筋麵粉 200 克\n熱水 120 毫升\n青蔥 3 根", steps: "揉麵團並靜置\n擀開撒蔥捲起\n小火煎至金黃",
+};
+const english = {
+  slug: "scallion-pancake", locale: "en", title: "Scallion Pancake", summary: "Crisp outside, soft inside.",
+  ingredients: "200 g all-purpose flour\n120 ml hot water\n3 scallions", steps: "Knead and rest the dough\nRoll, add scallions, coil\nPan-fry until golden",
+};
+const jsonLd = html => JSON.parse(/<script type="application\/ld\+json">(.*?)<\/script>/s.exec(html)[1]);
+
+await smoke(async ({ origin, owner, call, signIn, step }) => {
+  const admin = await signIn(owner);
+  const create = async (collection, data) => {
+    const created = await call("POST", "/admin/api/entries", { cookie: admin, body: { collection, data } });
+    assert.equal(created.status, 200, JSON.stringify(created.body));
+    return created.body.entry;
+  };
+  const publish = (collection, entry) => call("POST", `/admin/api/entries/${entry.id}/publish?collection=${collection}`, { cookie: admin, body: { expectedVersion: entry.version } });
+  const parent = await create("recipes", recipe), translation = await create("recipe_translations", english);
+  step("admin creates a zh-TW recipe and its en translation as drafts");
+
+  for (const path of ["/zh-TW/recipes/scallion-pancake", "/zh-TW/recipes/scallion-pancake.md", "/en/recipes/scallion-pancake"]) {
+    assert.equal((await call("GET", path)).status, 404, path);
+  }
+  // Visitor pages read as anonymous even when the request carries an admin session.
+  assert.equal((await call("GET", "/zh-TW/recipes/scallion-pancake", { cookie: admin })).status, 404);
+  assert.ok(!(await call("GET", "/zh-TW/")).body.includes("scallion-pancake"));
+  assert.ok(!(await call("GET", "/llms.txt")).body.includes("scallion-pancake"));
+  assert.ok(!(await call("GET", "/sitemap.xml")).body.includes("scallion-pancake"));
+  step("drafts are invisible to visitors: detail, Markdown, list, llms.txt and sitemap");
+
+  assert.equal((await publish("recipe_translations", translation)).status, 409);
+  const published = await publish("recipes", parent);
+  assert.equal(published.status, 200, JSON.stringify(published.body));
+  assert.equal((await call("GET", "/en/recipes/scallion-pancake")).status, 404);
+  assert.equal((await publish("recipe_translations", translation)).status, 200);
+  step("a translation cannot publish before its parent; publishing both via the Admin API");
+
+  const zh = await call("GET", "/zh-TW/recipes/scallion-pancake");
+  assert.equal(zh.status, 200);
+  assert.match(zh.headers.get("content-type"), /text\/html/);
+  const html = zh.body;
+  assert.match(html, /<html lang="zh-TW">/);
+  assert.match(html, /<title>蔥油餅 \| 食譜<\/title>/);
+  assert.match(html, /<meta name="description" content="外酥內軟的蔥油餅 &lt;\/script&gt;">/);
+  assert.ok(html.includes(`<link rel="canonical" href="${origin}/zh-TW/recipes/scallion-pancake">`));
+  assert.ok(html.includes(`<link rel="alternate" type="text/markdown" href="${origin}/zh-TW/recipes/scallion-pancake.md">`));
+  step("zh-TW detail has title, description and canonical");
+
+  for (const [lang, path] of [["zh-TW", "/zh-TW"], ["en", "/en"], ["x-default", "/zh-TW"]]) {
+    assert.ok(html.includes(`<link rel="alternate" hreflang="${lang}" href="${origin}${path}/recipes/scallion-pancake">`), lang);
+  }
+  assert.ok(html.includes(`<a href="/en/recipes/scallion-pancake" hreflang="en" lang="en">English</a>`));
+  const en = await call("GET", "/en/recipes/scallion-pancake");
+  assert.equal(en.status, 200);
+  assert.match(en.body, /<html lang="en">/);
+  assert.ok(en.body.includes(`<link rel="canonical" href="${origin}/en/recipes/scallion-pancake">`));
+  assert.ok(en.body.includes(`<link rel="alternate" hreflang="zh-TW" href="${origin}/zh-TW/recipes/scallion-pancake">`));
+  assert.ok(en.body.includes(`<a href="/zh-TW/recipes/scallion-pancake" hreflang="zh-TW" lang="zh-TW">繁體中文</a>`));
+  step("hreflang alternates and the locale switcher link zh-TW and en");
+
+  const zhData = jsonLd(html), enData = jsonLd(en.body);
+  assert.equal(zhData["@type"], "Recipe");
+  assert.equal(zhData.name, "蔥油餅");
+  assert.equal(zhData.description, recipe.summary);
+  assert.deepEqual(zhData.recipeIngredient, ["中筋麵粉 200 克", "熱水 120 毫升", "青蔥 3 根"]);
+  assert.equal(enData.name, "Scallion Pancake");
+  assert.equal(enData.inLanguage, "en");
+  assert.equal(enData.totalTime, "PT25M"); // merged from the parent row
+  assert.match(zhData.datePublished, /^\d{4}-/); assert.match(zhData.dateModified, /^\d{4}-/);
+  assert.ok(en.body.includes(`<meta property="og:url" content="${origin}/en/recipes/scallion-pancake">`));
+  assert.ok(en.body.includes(`<meta property="og:type" content="article">`));
+  assert.ok(en.body.includes(`<meta property="og:locale" content="en">`) && en.body.includes(`<meta property="og:locale:alternate" content="zh_TW">`));
+  assert.match(en.body, /<section id="quick-answer"><h2>How long does it take\?<\/h2><p>About 25 minutes in total; serves 2.<\/p><\/section>/);
+  step("JSON-LD Recipe parses with name and dates; Open Graph url/type/locale; the short answer block is present");
+
+  const md = await call("GET", "/en/recipes/scallion-pancake.md");
+  assert.equal(md.status, 200);
+  assert.match(md.headers.get("content-type"), /^text\/markdown/);
+  assert.ok(md.body.startsWith("# Scallion Pancake\n"));
+  assert.ok(md.body.includes("- 200 g all-purpose flour") && md.body.includes("1. Knead and rest the dough"));
+  step(".md alternate returns Markdown");
+
+  const llms = await call("GET", "/llms.txt");
+  assert.ok(llms.body.includes(`- [蔥油餅](${origin}/zh-TW/recipes/scallion-pancake.md)`));
+  assert.ok(llms.body.includes(`- [Scallion Pancake](${origin}/en/recipes/scallion-pancake.md)`));
+  assert.ok((await call("GET", "/en/")).body.includes(`<a href="/en/recipes/scallion-pancake">Scallion Pancake</a>`));
+  const home = await fetch(`${origin}/`, { redirect: "manual" });
+  assert.equal(home.status, 302);
+  assert.equal(home.headers.get("location"), `${origin}/zh-TW/`);
+  const sitemap = await call("GET", "/sitemap.xml");
+  assert.match(sitemap.headers.get("content-type"), /^application\/xml/);
+  for (const path of ["/zh-TW/", "/en/", "/zh-TW/recipes/scallion-pancake", "/en/recipes/scallion-pancake"]) assert.ok(sitemap.body.includes(`<loc>${origin}${path}</loc>`), path);
+  const robots = await call("GET", "/robots.txt");
+  assert.ok(robots.body.includes("Disallow: /admin/") && robots.body.includes(`Sitemap: ${origin}/sitemap.xml`));
+  step("llms.txt, sitemap (both locales), robots and the locale lists show the published recipe; / redirects to the default locale");
+});

package/docs/examples/recipes/src/media.ts

@@ -0,0 +1,13 @@
+import { r2MediaStorage, type S3Signer } from "@aotter/mantle/media/r2";
+
+/**
+ * Cover-image storage on the MEDIA R2 binding (docs/handbook/cloudflare/media-r2.md). Pass the result as Admin's
+ * `media` option (with `site` from generated/site.ts); the Admin media library then creates an upload, the browser
+ * PUTs the bytes straight to R2 with a presigned URL, and commit copies them under `committed/`.
+ * Copy the committed asset's public URL into a recipe's `cover_url`.
+ * AGENT: supply a SigV4 signer that returns query-signed PUT URLs, e.g. `new AwsClient({ accessKeyId, secretAccessKey })`
+ * from aws4fetch with R2 S3 credentials kept as secrets. Configure bucket CORS for PUT from your origin.
+ */
+export function coverStorage(env: Env, signer: S3Signer) {
+  return r2MediaStorage({ bucket: env.MEDIA, signer, endpoint: env.MEDIA_S3_ENDPOINT, publicBase: env.MEDIA_PUBLIC_BASE });
+}

package/docs/examples/recipes/src/pages.ts

@@ -0,0 +1,99 @@
+/** Dependency-free visitor HTML, Markdown and llms.txt for recipes. */
+export const LOCALES = ["zh-TW", "en"] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = "zh-TW";
+
+export interface Recipe {
+  slug: string; locale: Locale; title: string; summary: string; ingredients: string; steps: string;
+  total_minutes: number; servings: number; cover_url?: string | null; published_at?: string | null; updated_at?: string | null;
+}
+export interface Listed { slug: string; title: string; summary: string }
+
+// AGENT: move UI strings to your translation workflow when you add locales.
+const text = {
+  "zh-TW": { site: "食譜", description: "家常食譜，中英對照。", how: "需要多久？", answer: (m: number, s: number) => `總共約 ${m} 分鐘，可供 ${s} 人份。`, ingredients: "材料", steps: "步驟", all: "所有食譜", name: "繁體中文" },
+  en: { site: "Recipes", description: "Home recipes in Traditional Chinese and English.", how: "How long does it take?", answer: (m: number, s: number) => `About ${m} minutes in total; serves ${s}.`, ingredients: "Ingredients", steps: "Steps", all: "All recipes", name: "English" },
+} satisfies Record<Locale, unknown>;
+
+const escape = (value: unknown) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]!));
+const lines = (value: string) => value.split("\n").map(line => line.trim()).filter(Boolean);
+const recipePath = (locale: Locale, slug: string) => `/${locale}/recipes/${slug}`;
+
+/** hreflang alternates for every locale the page exists in, plus x-default (the default locale). */
+function alternates(origin: string, locales: readonly Locale[], path: (locale: Locale) => string) {
+  return locales.map(l => `<link rel="alternate" hreflang="${l}" href="${origin}${path(l)}">`).join("")
+    + `<link rel="alternate" hreflang="x-default" href="${origin}${path(DEFAULT_LOCALE)}">`;
+}
+
+/** Open Graph: og:locale uses underscores (zh_TW); the other locales the page exists in are alternates. */
+function openGraph(type: "website" | "article", url: string, locale: Locale, locales: readonly Locale[], title: string, description: string) {
+  const og = (property: string, content: string) => `<meta property="og:${property}" content="${escape(content)}">`;
+  return og("type", type) + og("url", url) + og("site_name", text[locale].site) + og("title", title) + og("description", description)
+    + og("locale", locale.replace("-", "_")) + locales.filter(l => l !== locale).map(l => og("locale:alternate", l.replace("-", "_"))).join("");
+}
+
+function documentHtml(locale: Locale, head: string, body: string) {
+  // AGENT: real layout and styling (stylesheet, header, footer, images sizes); keep the head tags.
+  return `<!doctype html><html lang="${locale}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${head}</head><body>${body}</body></html>`;
+}
+
+function switcher(locales: readonly Locale[], path: (locale: Locale) => string, current: Locale) {
+  return `<nav aria-label="Language">${locales.map(l => l === current ? `<strong>${text[l].name}</strong>` : `<a href="${path(l)}" hreflang="${l}" lang="${l}">${text[l].name}</a>`).join(" | ")}</nav>`;
+}
+
+export function listHtml(origin: string, locale: Locale, rows: readonly Listed[]) {
+  const t = text[locale], path = (l: Locale) => `/${l}/`;
+  const head = `<title>${escape(t.site)}</title><meta name="description" content="${escape(t.description)}">`
+    + `<link rel="canonical" href="${origin}${path(locale)}">${alternates(origin, LOCALES, path)}`
+    + openGraph("website", `${origin}${path(locale)}`, locale, LOCALES, t.site, t.description);
+  const items = rows.map(r => `<li><a href="${recipePath(locale, r.slug)}">${escape(r.title)}</a><p>${escape(r.summary)}</p></li>`).join("");
+  return documentHtml(locale, head, `${switcher(LOCALES, path, locale)}<h1>${escape(t.site)}</h1><ul>${items}</ul>`);
+}
+
+export function recipeHtml(origin: string, locale: Locale, r: Recipe, locales: readonly Locale[]) {
+  const t = text[locale], path = (l: Locale) => recipePath(l, r.slug), canonical = `${origin}${path(locale)}`;
+  const jsonLd = {
+    "@context": "https://schema.org", "@type": "Recipe", name: r.title, description: r.summary, inLanguage: locale, url: canonical,
+    ...(r.cover_url ? { image: [r.cover_url] } : {}), ...(r.published_at ? { datePublished: r.published_at } : {}), ...(r.updated_at ? { dateModified: r.updated_at } : {}),
+    totalTime: `PT${r.total_minutes}M`, recipeYield: String(r.servings),
+    recipeIngredient: lines(r.ingredients),
+    recipeInstructions: lines(r.steps).map(step => ({ "@type": "HowToStep", text: step })),
+  };
+  const head = `<title>${escape(r.title)} | ${escape(t.site)}</title><meta name="description" content="${escape(r.summary)}">`
+    + `<link rel="canonical" href="${canonical}">${alternates(origin, locales, path)}`
+    + `<link rel="alternate" type="text/markdown" href="${canonical}.md">`
+    + openGraph("article", canonical, locale, locales, r.title, r.summary)
+    + (r.cover_url ? `<meta property="og:image" content="${escape(r.cover_url)}">` : "")
+    // `<` is escaped so admin-authored text cannot close the script element.
+    + `<script type="application/ld+json">${JSON.stringify(jsonLd).replace(/</g, "\\u003c")}</script>`;
+  const body = `${switcher(locales, path, locale)}<p><a href="/${locale}/">${escape(t.all)}</a></p>`
+    + `<article><h1>${escape(r.title)}</h1><p>${escape(r.summary)}</p>`
+    + (r.cover_url ? `<img src="${escape(r.cover_url)}" alt="${escape(r.title)}">` : "")
+    // Short answer block: one question and a one-sentence answer that search and answer engines can quote.
+    + `<section id="quick-answer"><h2>${escape(t.how)}</h2><p>${escape(t.answer(r.total_minutes, r.servings))}</p></section>`
+    + `<h2>${escape(t.ingredients)}</h2><ul>${lines(r.ingredients).map(i => `<li>${escape(i)}</li>`).join("")}</ul>`
+    + `<h2>${escape(t.steps)}</h2><ol>${lines(r.steps).map(s => `<li>${escape(s)}</li>`).join("")}</ol></article>`;
+  return documentHtml(locale, head, body);
+}
+
+export function recipeMarkdown(r: Recipe) {
+  const t = text[r.locale];
+  return [`# ${r.title}`, "", r.summary, "", `## ${t.how}`, "", t.answer(r.total_minutes, r.servings), "",
+    `## ${t.ingredients}`, "", ...lines(r.ingredients).map(i => `- ${i}`), "",
+    `## ${t.steps}`, "", ...lines(r.steps).map((s, i) => `${i + 1}. ${s}`), ""].join("\n");
+}
+
+/** llms.txt (https://llmstxt.org): one section per locale, each recipe linking to its Markdown alternate. */
+export function llmsTxt(origin: string, lists: readonly (readonly [Locale, readonly Listed[]])[]) {
+  return [`# ${text.en.site}`, "", `> ${text.en.description}`, "",
+    ...lists.flatMap(([locale, rows]) => [`## ${text[locale].name} (${locale})`, "",
+      ...rows.map(r => `- [${r.title}](${origin}${recipePath(locale, r.slug)}.md): ${r.summary.replace(/\s+/g, " ")}`), ""])].join("\n");
+}
+
+/** sitemap.xml: each locale's list page and every published recipe in it (only published rows reach `lists`). */
+export function sitemapXml(origin: string, lists: readonly (readonly [Locale, readonly Listed[]])[]) {
+  const paths = lists.flatMap(([locale, rows]) => [`/${locale}/`, ...rows.map(r => recipePath(locale, r.slug))]);
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${paths.map(path => `<url><loc>${escape(origin + path)}</loc></url>`).join("")}</urlset>\n`;
+}
+
+export const robotsTxt = (origin: string) => `User-agent: *\nDisallow: /admin/\nSitemap: ${origin}/sitemap.xml\n`;

package/docs/examples/recipes/src/routes.ts

@@ -0,0 +1,71 @@
+import type { Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import { translationLocales } from "../generated/translations.js";
+import recipePage from "../generated/paged/views/published_recipes.js";
+import translationPage from "../generated/paged/views/published_translations.js";
+import { DEFAULT_LOCALE, LOCALES, type Locale, type Recipe, listHtml, llmsTxt, recipeHtml, recipeMarkdown, robotsTxt, sitemapXml } from "./pages.js";
+
+// Visitor pages always read as anonymous, even for a signed-in admin, so drafts never reach public HTML.
+const visitor: Caller = { kind: "anonymous" };
+const page = /^\/(zh-TW|en)\/(?:recipes\/([a-z0-9-]+?)(\.md)?)?$/;
+
+/**
+ * Visitor pages, tried before Admin, MCP and REST. Only these paths are matched; everything else falls through.
+ *   /                          -> redirect to /zh-TW/
+ *   /{locale}/                 list (HTML)
+ *   /{locale}/recipes/{slug}   detail (HTML: SEO meta, hreflang, JSON-LD Recipe, short answer)
+ *   /{locale}/recipes/{slug}.md  Markdown alternate
+ *   /llms.txt                  published recipes for AI agents
+ *   /sitemap.xml, /robots.txt  every published URL in every locale; robots keeps crawlers out of /admin/
+ */
+export async function appRoutes(request: Request, env: Env, _context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
+  const url = new URL(request.url), match = page.exec(url.pathname);
+  if (!["/", "/llms.txt", "/sitemap.xml", "/robots.txt"].includes(url.pathname) && !match) return undefined;
+  if (request.method !== "GET" && request.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });
+  // Absolute links use the configured origin, not the request Host.
+  const origin = env.PUBLIC_ORIGIN;
+  if (url.pathname === "/") return Response.redirect(`${origin}/${DEFAULT_LOCALE}/`, 302);
+
+  if (url.pathname === "/robots.txt") return send(request, robotsTxt(origin), "text/plain; charset=utf-8");
+  if (url.pathname === "/llms.txt" || url.pathname === "/sitemap.xml") {
+    const lists = await Promise.all(LOCALES.map(async locale => [locale, await list(env, locale)] as const));
+    return url.pathname === "/llms.txt"
+      ? send(request, llmsTxt(origin, lists), "text/plain; charset=utf-8")
+      : send(request, sitemapXml(origin, lists), "application/xml; charset=utf-8");
+  }
+
+  const locale = match![1] as Locale, slug = match![2], markdown = !!match![3];
+  if (!slug) return send(request, listHtml(origin, locale, await list(env, locale)), "text/html; charset=utf-8");
+  const found = await read(env, slug, locale);
+  if (!found) return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  return markdown
+    ? send(request, recipeMarkdown(found.recipe), "text/markdown; charset=utf-8", { link: `<${origin}/${locale}/recipes/${slug}>; rel="canonical"` })
+    : send(request, recipeHtml(origin, locale, found.recipe, found.locales), "text/html; charset=utf-8");
+}
+
+/** First page of published recipes in one locale. AGENT: page with `nextCursor` once a locale has more than 100 recipes. */
+async function list(env: Env, locale: Locale) {
+  const result = locale === DEFAULT_LOCALE
+    ? await recipePage(env.DB, visitor, {}, { limit: 100 })
+    : await translationPage(env.DB, visitor, { locale }, { limit: 100 });
+  return result.rows.map(row => ({ slug: String(row.slug), title: String(row.title), summary: String(row.summary) }));
+}
+
+/** One published recipe in `locale` plus the locales it is published in (for hreflang). */
+async function read(env: Env, slug: string, locale: Locale): Promise<{ recipe: Recipe; locales: Locale[] } | undefined> {
+  const recipes = store(env.DB, visitor);
+  const parent = await recipes.collection("recipes").first({ where: { slug } });
+  if (!parent) return undefined;
+  const translated = (await translationLocales(env.DB, visitor, "recipes", [parent]))[parent.id] ?? [];
+  const locales = LOCALES.filter(l => l === DEFAULT_LOCALE || translated.includes(l));
+  if (!locales.includes(locale)) return undefined;
+  // A translation read merges the parent's fields (total_minutes, servings, cover_url, ...); the child's own fields win.
+  const row = locale === DEFAULT_LOCALE ? parent : await recipes.collection("recipe_translations").first({ where: { slug, locale } });
+  if (!row) return undefined;
+  return { recipe: { ...row, slug, locale } as Recipe, locales };
+}
+
+function send(request: Request, body: string, type: string, headers: Record<string, string> = {}) {
+  // AGENT: choose a cache policy (and purge on publish) once pages sit behind a CDN.
+  return new Response(request.method === "HEAD" ? null : body, { headers: { "content-type": type, "cache-control": "no-store", ...headers } });
+}

package/docs/examples/recipes/src/site-config.ts

@@ -0,0 +1,12 @@
+import type { SiteDefaults } from "@aotter/mantle/site";
+
+/**
+ * Site defaults for `mantle generate ... --site src/site-config.ts`, which adds the media library tables and
+ * `generated/site.ts`. The shell does not pass `--site`; see README "Cover images" for the two lines to add.
+ */
+export const siteDefaults = {
+  title: "Recipes",
+  description: "Home recipes in Traditional Chinese and English.",
+  locales: ["zh-TW", "en"],
+  media: { purposes: [{ name: "cover", required: ["image/jpeg,image/png,image/webp"], maxBytes: { "image/jpeg": 5_000_000, "image/png": 5_000_000, "image/webp": 5_000_000 } }] },
+} satisfies SiteDefaults;