@iterant/site-runtime 3.6.0 → 3.7.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.7.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -81,6 +81,7 @@ _Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.0._
 | `tw-animate-css`           | 1.4.0   | the animation utilities Tailwind v4 dropped           |
 | `github-slugger`           | 2.0.0   | heading and anchor slugs                              |
 | `micromark`                | 4.0.2   | the CommonMark compiler markdown wrappers render with |
+| `micromark-extension-gfm`  | 3.0.0   | tables, task lists and strikethrough on top of it     |
 
 <!-- /generated -->
 
@@ -351,6 +352,48 @@ is what puts the component in the client bundle siblings hydrate from. The
 bespoke-sibling gate enforces both on every non-draft bespoke page, after the
 build.
 
+## Forms (3.7.0)
+
+A capturing form posts to the platform, never to a backend of its own. The
+authored convention (an action-less `<form data-iterant-form="<key>">`, the
+`_hp` honeypot, a hidden `data-iterant-form-success` sibling) is what the
+injected runtime and the edge's native fallback act on, and `IterantForm`
+renders exactly that markup so a page stops hand-writing it. Rendered
+statically it behaves as the authored markup does: the runtime intercepts the
+submit and reveals the success element. Hydrated (`client:load`, or inside a
+bespoke page) it owns the submit: it marks the form `data-iterant-form-managed`
+on mount, which is how the runtime knows to stand down, posts the same body to
+the same endpoint, disables the submit button with `aria-busy` while in flight,
+shows the success or the error message, resets the fields on success and never
+navigates. `name` is required and is the form key the submissions dashboard
+aggregates on. `successMessage` and `errorMessage` take a wrapped text value or
+a plain string, so a section passes its entry copy straight through, and an
+absent value falls back to the package default. It ships no utility classes:
+the page styles the form through `className`, the state through
+`data-iterant-form-state` (`idle`, `pending`, `success`, `error`) and the two
+message elements through their attributes.
+
+```tsx
+import { readText } from "@iterant/site-runtime/content-values";
+import { IterantForm } from "@iterant/site-runtime/forms";
+
+<IterantForm name={readText(data.formKey)} successMessage={data.successCopy}>
+  <label htmlFor="email">{readText(data.emailLabel)}</label>
+  <input id="email" name="email" type="email" required />
+  <button type="submit">{readText(data.submitLabel)}</button>
+</IterantForm>;
+```
+
+`submitForm(name, fields)` is the same post without the component, for a
+multi-step form or a custom handler. It resolves to `{ ok: true }` or
+`{ ok: false, error }` and never throws, whether the platform accepted,
+refused (`rate_limited`, `turnstile_failed`) or was unreachable (`network`).
+Values are strings only: a `File` is refused as `unsupported_field:<name>`, and
+`readFormFields` turns a form's `FormData` into the record it takes. Pass one
+`idempotencyKey` across retries of a submission and the platform collapses them
+to one row. Submissions are captured on a published site; the dev server has no
+endpoint, so a preview submit settles as an error and captures nothing.
+
 ## Structured data is derived, never authored
 
 Every indexable page emits a schema.org graph (Organization, WebSite, the page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {
@@ -49,6 +49,7 @@
     "./sitemap": "./src/lib/sitemap/index.ts",
     "./seo": "./src/components/seo.tsx",
     "./seo-json": "./src/components/seo-json.tsx",
+    "./forms": "./src/components/forms.tsx",
     "./layout": "./src/layouts/LayoutCore.astro",
     "./layout-core": "./src/layouts/layout-core.ts",
     "./layout-contract": "./src/layouts/layout-contract.ts",
@@ -81,7 +82,8 @@
       "class-variance-authority",
       "tw-animate-css",
       "github-slugger",
-      "micromark"
+      "micromark",
+      "micromark-extension-gfm"
     ]
   },
   "dependencies": {
@@ -98,6 +100,7 @@
     "github-slugger": "2.0.0",
     "lucide-react": "1.31.0",
     "micromark": "4.0.2",
+    "micromark-extension-gfm": "3.0.0",
     "motion": "13.0.0",
     "radix-ui": "1.6.7",
     "react": "19.2.8",
@@ -114,6 +117,7 @@
     "@types/node": "24.3.1",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
+    "jsdom": "^26.0.0",
     "typescript": "5.9.2",
     "vitest": "^4.0.13",
     "wrangler": "^4.107.0"

package/scripts/scan-bespoke-siblings.mjs

@@ -19,12 +19,29 @@
  *      the shape the catch-all's pickPageExport (src/lib/bespoke-pages.ts)
  *      resolves.
  *
- * For every NON-DRAFT bespoke base entry, this asserts (1) against the built
- * manifest and (2) by importing the built client entry itself. Draft bespoke
- * pages are exempt: drafts never publish, their siblings are never advertised
- * (hreflang/sitemap), and the stock `not-found` page is a draft that
- * deliberately lives outside the `<base>/page.tsx` convention (404.astro
- * renders it). Publishing a bespoke page puts it in scope on the next verify.
+ * For every NON-DRAFT bespoke base entry THAT HAS a locale sibling file
+ * (`<base>.<locale>.json`, draft or not: a draft sibling still renders in a
+ * preview), this asserts (1) against the built manifest and (2) by importing
+ * the built client entry itself. Draft bespoke pages are exempt: drafts never
+ * publish, their siblings are never advertised (hreflang/sitemap), and the
+ * stock `not-found` page is a draft that deliberately lives outside the
+ * `<base>/page.tsx` convention (404.astro renders it). Publishing a bespoke
+ * page puts it in scope on the next verify.
+ *
+ * Scoping to bases-with-siblings (3.6.1) loses nothing: the hazard cannot
+ * materialize without a sibling, a sibling only comes into existence through
+ * a save, and every save runs this gate, so a base picks up the full check
+ * the moment its first sibling lands. Before that, a pre-convention bespoke
+ * page (every pre-3.6 blog) must not block a same-major runtime bump over a
+ * feature the repo does not use.
+ *
+ * A base whose sibling route is SHADOWED is also out of scope (3.6.1): when
+ * `src/pages/[locale]/<base>.astro` exists (`index.astro` for the `home`
+ * base), Astro's route priority sends `/es` to that explicit route, never to
+ * the catch-all, so the catch-all hydration contract this gate asserts does
+ * not serve the sibling at all. Replica-era repos localize exactly this way.
+ * The shadowing route's own hydration is `astro build`'s concern, like every
+ * other explicit route.
  *
  * It also pins the Astro runtime contract the catch-all relies on: the island
  * renderer must keep accepting `client:component-path` /
@@ -37,7 +54,7 @@
  * weaken this script.
  */
 
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { exit } from "node:process";
@@ -51,41 +68,34 @@ const CONVENTIONS =
 /** @type {string[]} */
 const problems = [];
 
-// ---- SF-pin: the Astro runtime directive contract --------------------------
-
-const hydrationJs = join(
-  process.cwd(),
-  "node_modules/astro/dist/runtime/server/hydration.js",
-);
-const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
-for (const directive of ["client:component-path", "client:component-export"]) {
-  if (!hydrationSrc.includes(`case "${directive}"`)) {
-    problems.push(
-      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
-        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
-        `exactly that escape hatch (src/pages/[...slug].astro) — re-verify ` +
-        `sibling hydration against this Astro version before shipping.`,
-    );
-  }
-}
-
-// ---- SF1+SF2: every non-draft bespoke base ---------------------------------
+// ---- SF1+SF2: every non-draft bespoke base with a sibling ------------------
 
-/** Non-draft bespoke base entry ids (`home`), never locale siblings. */
-async function bespokeBases() {
+/**
+ * Non-draft bespoke base entry ids (`home`), never locale siblings, plus the
+ * set of base ids that have at least one sibling file. Sibling presence
+ * counts by filename alone (`home.es.json` -> `home`): a sibling's own draft
+ * flag or parse failure does not excuse its base, because the sibling still
+ * renders in a preview.
+ */
+async function bespokeInventory() {
   const pagesDir = join(process.cwd(), "src/content/pages");
   /** @type {string[]} */
   const bases = [];
+  /** @type {Set<string>} */
+  const siblingBases = new Set();
   /** @type {string[]} */
   let names = [];
   try {
     names = await readdir(pagesDir);
   } catch {
-    return bases; // no pages dir — astro check owns that failure
+    return { bases, siblingBases }; // no pages dir: astro check owns that failure
   }
   for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
     const id = name.replace(/\.json$/, "");
-    if (id.includes(".")) continue; // locale sibling — guarded via its base
+    if (id.includes(".")) {
+      siblingBases.add(id.slice(0, id.indexOf(".")));
+      continue; // locale sibling: guarded via its base
+    }
     /** @type {{ mode?: string; draft?: boolean }} */
     let entry;
     try {
@@ -95,7 +105,21 @@ async function bespokeBases() {
     }
     if (entry.mode === "bespoke" && entry.draft !== true) bases.push(id);
   }
-  return bases;
+  return { bases, siblingBases };
+}
+
+/**
+ * Whether an explicit locale route shadows this base's siblings. Astro sends
+ * `/es` (and `/es/<base>`) to `src/pages/[locale]/index.astro` (respectively
+ * `[locale]/<base>.astro`) before any rest-param catch-all, so when that file
+ * exists the sibling never renders through the catch-all this gate asserts.
+ */
+async function siblingRouteShadowed(base) {
+  const file = base === "home" ? "index.astro" : `${base}.astro`;
+  return stat(join(process.cwd(), "src/pages/[locale]", file)).then(
+    (s) => s.isFile(),
+    () => false,
+  );
 }
 
 /**
@@ -133,8 +157,37 @@ async function builtEntryModules() {
   return null;
 }
 
-const bases = await bespokeBases();
-if (bases.length > 0 && problems.length === 0) {
+const inventory = await bespokeInventory();
+/** @type {string[]} */
+const bases = [];
+for (const base of inventory.bases) {
+  if (!inventory.siblingBases.has(base)) continue;
+  if (await siblingRouteShadowed(base)) continue;
+  bases.push(base);
+}
+// Nothing can hydrate through the escape hatch: the first sibling arrives via
+// a save, and every save re-runs this gate, so exiting here defers nothing.
+if (bases.length === 0) exit(0);
+
+// ---- SF-pin: the Astro runtime directive contract --------------------------
+
+const hydrationJs = join(
+  process.cwd(),
+  "node_modules/astro/dist/runtime/server/hydration.js",
+);
+const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
+for (const directive of ["client:component-path", "client:component-export"]) {
+  if (!hydrationSrc.includes(`case "${directive}"`)) {
+    problems.push(
+      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
+        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
+        `exactly that escape hatch (src/pages/[...slug].astro): re-verify ` +
+        `sibling hydration against this Astro version before shipping.`,
+    );
+  }
+}
+
+if (problems.length === 0) {
   const entryModules = await builtEntryModules();
   if (!entryModules) {
     problems.push(

package/src/components/forms.tsx

@@ -0,0 +1,155 @@
+import {
+  type FormEvent,
+  type ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { type ContentLeaf, readText } from "../lib/content-values";
+import {
+  FORM_HONEYPOT_FIELD,
+  mintIdempotencyKey,
+  readFormFields,
+  submitForm,
+} from "../lib/submit-form";
+
+export { readFormFields, submitForm } from "../lib/submit-form";
+export type { SubmitFormOptions, SubmitFormResult } from "../lib/submit-form";
+
+export const DEFAULT_SUCCESS_MESSAGE = "Thanks for your submission!";
+export const DEFAULT_ERROR_MESSAGE = "Something went wrong. Please try again.";
+
+export interface IterantFormProps {
+  /** The form key: `data-iterant-form`, and what the submissions dashboard
+   *  aggregates on. */
+  name: string;
+  /** A wrapped text value or a plain string; anything else, or an empty one,
+   *  falls back to the default. */
+  successMessage?: ContentLeaf;
+  errorMessage?: ContentLeaf;
+  className?: string;
+  children?: ReactNode;
+  onSuccess?(): void;
+}
+
+type FormState = "idle" | "pending" | "success" | "error";
+
+// The capturing form of the forms convention (an action-less
+// `data-iterant-form`, the `_hp` honeypot, a hidden success sibling), rendered
+// once so pages stop hand-writing it. Rendered statically it IS that markup and
+// the injected runtime submits it. Hydrated, it owns the submit: same body,
+// same endpoint, its own pending, success and error states, no navigation.
+export function IterantForm({
+  name,
+  successMessage,
+  errorMessage,
+  className,
+  children,
+  onSuccess,
+}: IterantFormProps) {
+  const [state, setState] = useState<FormState>("idle");
+  // Set after mount, never in the static render: the mark is what tells the
+  // injected runtime this form's submit has an owner and to stand down.
+  const [managed, setManaged] = useState(false);
+  useEffect(() => {
+    setManaged(true);
+  }, []);
+  const inFlight = useRef(false);
+  // One key per submission, reused on retry so the platform collapses a
+  // retried post to one row, and dropped once the submission is accepted.
+  const idempotencyKey = useRef<string | null>(null);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    // A runtime from before the managed mark took this submit in its
+    // capture-phase listener and posts it itself.
+    if (event.isDefaultPrevented()) return;
+    event.preventDefault();
+    if (inFlight.current) return;
+    const form = event.currentTarget;
+    // A runtime from before the managed mark may have posted this form while
+    // the page was still static and be waiting on the edge: its in-flight mark
+    // stands down this submit, and its key is the one a retry reuses, so the
+    // platform collapses both posts to one row.
+    if (form.dataset.iterantSubmitting === "1") return;
+    inFlight.current = true;
+    const release = markBusy(form);
+    setState("pending");
+    idempotencyKey.current ??= form.dataset.iterantIk || mintIdempotencyKey();
+    const result = await submitForm(name, readFormFields(form), {
+      idempotencyKey: idempotencyKey.current,
+    });
+    release();
+    inFlight.current = false;
+    if (!result.ok) {
+      setState("error");
+      return;
+    }
+    idempotencyKey.current = null;
+    form.reset();
+    setState("success");
+    onSuccess?.();
+  }
+
+  return (
+    <div>
+      <form
+        data-iterant-form={name}
+        data-iterant-form-managed={managed ? "" : undefined}
+        data-iterant-form-state={state}
+        className={className}
+        onSubmit={handleSubmit}
+      >
+        <input
+          type="text"
+          name={FORM_HONEYPOT_FIELD}
+          tabIndex={-1}
+          autoComplete="off"
+          aria-hidden="true"
+          style={{ position: "absolute", left: "-9999px" }}
+        />
+        {children}
+      </form>
+      <p
+        data-iterant-form-success=""
+        role="status"
+        hidden={state !== "success"}
+      >
+        {readText(successMessage) || DEFAULT_SUCCESS_MESSAGE}
+      </p>
+      <p data-iterant-form-error="" role="alert" hidden={state !== "error"}>
+        {readText(errorMessage) || DEFAULT_ERROR_MESSAGE}
+      </p>
+    </div>
+  );
+}
+
+// The submit controls are the caller's children, so the pending state goes on
+// the live elements: `aria-busy` for assistive tech and the page's styles,
+// `disabled` so a second click cannot start a second submission.
+function markBusy(form: HTMLFormElement): () => void {
+  const restore = Array.from(form.elements)
+    .filter(isSubmitControl)
+    .map((control) => {
+      const wasDisabled = control.disabled;
+      control.disabled = true;
+      control.setAttribute("aria-busy", "true");
+      return () => {
+        control.disabled = wasDisabled;
+        control.removeAttribute("aria-busy");
+      };
+    });
+  return () => {
+    for (const fn of restore) fn();
+  };
+}
+
+function isSubmitControl(
+  element: Element,
+): element is HTMLButtonElement | HTMLInputElement {
+  return (
+    (element instanceof HTMLButtonElement ||
+      element instanceof HTMLInputElement) &&
+    element.type === "submit"
+  );
+}

package/src/lib/markdown.ts

@@ -1,4 +1,5 @@
 import { micromark } from "micromark";
+import { gfm, gfmHtml } from "micromark-extension-gfm";
 
 // The one compiler for {type:"markdown"} content values (content-values.ts).
 // Runs at build time inside Astro's static render, so the browser ships HTML,
@@ -8,10 +9,18 @@ import { micromark } from "micromark";
 // tags up front, and this default is the backstop for anything that predates
 // or evades the schema. Do not pass allowDangerousHtml here, ever.
 //
+// GFM is on because the dashboard's body toolbar emits it: tables and task
+// lists are buttons a customer can press, and CommonMark alone would render
+// what they wrote as pipe soup. It adds syntax only; the escaping contract
+// above is untouched, and gfmHtml writes task checkboxes disabled.
+//
 // Headings: a markdown body renders inside a section, below the page's own
 // h1, so authors start at `##`. The compiler does not rewrite heading levels;
 // a body that opens with `#` is an authoring error the review pass catches,
 // not something to silently demote.
 export function renderMarkdown(value: string): string {
-  return micromark(value);
+  return micromark(value, {
+    extensions: [gfm()],
+    htmlExtensions: [gfmHtml()],
+  });
 }

package/src/lib/submit-form.ts

@@ -0,0 +1,123 @@
+// The page-side half of platform form capture. A submission posts to the same
+// endpoint, in the same body, that the injected runtime and the edge-rewritten
+// native form already use (apps/site-dispatch, iterant-endpoints.ts). There is
+// one protocol: this module reuses its field names and never adds one.
+
+/** The endpoint's own control fields. Everything else in a body is visitor data. */
+export const FORM_HONEYPOT_FIELD = "_hp";
+const FORM_IDEMPOTENCY_FIELD = "_ik";
+const FORM_SID_FIELD = "_sid";
+
+/** The opaque form-key grammar the endpoint routes on; a key outside it is a 404 there. */
+export const FORM_KEY_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+// The direct-origin base. A page served through the platform edge carries the
+// prefix-resolved base in the injected config, which wins.
+const DEFAULT_FORMS_BASE = "/_iterant/forms";
+
+export type SubmitFormResult = { ok: true } | { ok: false; error: string };
+
+export interface SubmitFormOptions {
+  /** Reuse one key across retries of one submission and the platform collapses
+   *  them to a single row. Minted per call when absent. */
+  idempotencyKey?: string;
+}
+
+// What the injected runtime leaves on the window: its config, and the session
+// id it minted, so a lead submitted from page code still joins the visitor's
+// journey without this package learning where the id is stored.
+type SignalsWindow = {
+  __ITERANT_SIGNALS__?: { formsBase?: string };
+  iterantSignals?: { sid?(): string };
+};
+
+function signals(): SignalsWindow {
+  return typeof window === "undefined"
+    ? {}
+    : (window as unknown as SignalsWindow);
+}
+
+function formsBase(): string {
+  return signals().__ITERANT_SIGNALS__?.formsBase || DEFAULT_FORMS_BASE;
+}
+
+function readSid(): string {
+  try {
+    return signals().iterantSignals?.sid?.() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+export function mintIdempotencyKey(): string {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `ik-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+/** A form's fields as the record `submitForm` takes: strings only, so a file
+ *  input contributes nothing, the same read the injected runtime performs. */
+export function readFormFields(form: HTMLFormElement): Record<string, string> {
+  const fields: Record<string, string> = {};
+  new FormData(form).forEach((value, name) => {
+    if (typeof value === "string") fields[name] = value;
+  });
+  return fields;
+}
+
+/** Post one submission for the form key `name`. Resolves to `{ ok: true }` on
+ *  a durable accept and `{ ok: false, error }` otherwise, and never throws:
+ *  `error` is the endpoint's own token (`rate_limited`, `turnstile_failed`,
+ *  `drain_failed`), `http_<status>` for an answer without one, `network` when
+ *  nothing answered, `invalid_name` for a key the endpoint would not route and
+ *  `unsupported_field:<name>` for a value that is not a string. */
+export async function submitForm(
+  name: string,
+  fields: Record<string, string>,
+  options: SubmitFormOptions = {},
+): Promise<SubmitFormResult> {
+  if (!FORM_KEY_PATTERN.test(name)) return { ok: false, error: "invalid_name" };
+  const body: Record<string, string> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    // File inputs are unsupported: only string values are captured.
+    if (typeof value !== "string") {
+      return { ok: false, error: `unsupported_field:${key}` };
+    }
+    body[key] = value;
+  }
+  body[FORM_IDEMPOTENCY_FIELD] = options.idempotencyKey ?? mintIdempotencyKey();
+  const sid = readSid();
+  if (sid) body[FORM_SID_FIELD] = sid;
+
+  let response: Response;
+  try {
+    response = await fetch(`${formsBase()}/${encodeURIComponent(name)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      credentials: "omit",
+    });
+  } catch {
+    return { ok: false, error: "network" };
+  }
+  if (response.ok) return { ok: true };
+  return {
+    ok: false,
+    error: (await errorToken(response)) ?? `http_${response.status}`,
+  };
+}
+
+// The endpoint refuses with a JSON envelope carrying a token. Anything else
+// (a dev server's HTML 404, a proxy's error page) has no token to read.
+async function errorToken(response: Response): Promise<string | null> {
+  try {
+    const parsed: unknown = await response.json();
+    if (parsed && typeof parsed === "object") {
+      const error = (parsed as { error?: unknown }).error;
+      if (typeof error === "string" && error !== "") return error;
+    }
+  } catch {
+    // not the endpoint's envelope
+  }
+  return null;
+}