@synap-core/sdk 1.1.0 → 1.3.0

package/src/templates.ts

@@ -0,0 +1,122 @@
+/**
+ * ensureTemplate — an app asks the pod whether the template it runs on is
+ * installed, and (optionally) asks for it to be installed.
+ *
+ * TEMPLATE-LIFECYCLE Contract B. ONE door: tRPC `workspaces.ensureTemplate`
+ * (Hub REST mirror `POST /api/hub/workspaces/ensure-template`). The pod
+ * resolves the definition from the catalog and installs through its governed
+ * install door — an app NEVER sends a definition. "Installed" means an ACTIVE
+ * workspace whose `settings.packageSlug` is the slug.
+ *
+ * The result union below is HAND-WRITTEN from the contract
+ * (`TEMPLATE-LIFECYCLE/DESIGN.md`, Contract B) because the published
+ * `@synap-core/api-types` does not carry the procedure until the next regen.
+ * Once it does, `EnsureTemplateResult` should become
+ * `RouterOutputs["workspaces"]["ensureTemplate"]`.
+ *
+ * A failed call REJECTS. It is never folded into `missing`: "the pod said the
+ * template is not installed" and "we could not ask the pod" are different
+ * facts, and only the first may offer an install.
+ */
+
+export interface EnsureTemplateInput {
+  slug: string;
+  /** Ask the pod to install it when missing. */
+  install?: boolean;
+  /** One plain sentence: why the app needs it (shown on the install request). */
+  reason?: string;
+}
+
+export interface EnsureTemplateMissingTemplate {
+  slug: string;
+  name: string;
+  description: string | null;
+  icon: string | null;
+}
+
+export type EnsureTemplateResult =
+  /** Installed: an ACTIVE workspace carries the template. */
+  | { status: "installed"; workspaceId: string; version: string | null; drifted: boolean }
+  /** Not installed, and no install was asked. */
+  | { status: "missing"; template: EnsureTemplateMissingTemplate }
+  /** Install asked by an agent or app key: the governed install filed a proposal. */
+  | { status: "proposed"; proposalId: string; reviewUrl: string }
+  /** Install asked by a person: it is being installed now. */
+  | { status: "installing"; workspaceId: string }
+  /**
+   * Another live space already holds this template's domain (one space per
+   * domain), so the pod will not install a twin. The person decides what to
+   * do with that space; `guidance` is the pod's own sentence.
+   */
+  | { status: "exists"; workspaceId: string; workspaceName: string; guidance: string }
+  /** The catalog retired the template; `replacedBy` is its successor, if any. */
+  | { status: "retired"; replacedBy: string | null }
+  /** A COMPLETE catalog sync does not list the slug. */
+  | { status: "not_in_catalog" }
+  /** The pod cannot tell yet (catalog cache cold or last sync incomplete). */
+  | { status: "unknown" };
+
+export type EnsureTemplateStatus = EnsureTemplateResult["status"];
+
+/**
+ * The slice of the tRPC client this helper needs. Structural on purpose: it
+ * accepts `createSynapClient(...)` and a React `trpc.useUtils().client` alike,
+ * and keeps compiling before the procedure lands in the generated types.
+ */
+export interface EnsureTemplateClient {
+  workspaces: {
+    ensureTemplate: {
+      mutate(input: EnsureTemplateInput): Promise<unknown>;
+    };
+  };
+}
+
+export interface EnsureTemplateOptions {
+  install?: boolean;
+  reason?: string;
+}
+
+const STATUSES: ReadonlySet<string> = new Set<EnsureTemplateStatus>([
+  "installed",
+  "missing",
+  "proposed",
+  "installing",
+  "exists",
+  "retired",
+  "not_in_catalog",
+  "unknown",
+]);
+
+/**
+ * Narrow the wire answer. An answer whose `status` is not one the contract
+ * names is a protocol error and throws: guessing "missing" would offer an
+ * install the pod never said was needed.
+ */
+export function parseEnsureTemplateResult(raw: unknown): EnsureTemplateResult {
+  const status =
+    raw && typeof raw === "object" ? (raw as { status?: unknown }).status : undefined;
+  if (typeof status !== "string" || !STATUSES.has(status)) {
+    throw new Error(
+      `ensureTemplate: the pod answered with an unknown status (${String(status)}).`,
+    );
+  }
+  return raw as EnsureTemplateResult;
+}
+
+export async function ensureTemplate(
+  client: EnsureTemplateClient,
+  slug: string,
+  opts: EnsureTemplateOptions = {},
+): Promise<EnsureTemplateResult> {
+  const input: EnsureTemplateInput = { slug };
+  if (opts.install) input.install = true;
+  if (opts.reason) input.reason = opts.reason;
+  return parseEnsureTemplateResult(await client.workspaces.ensureTemplate.mutate(input));
+}
+
+/** The workspace the template lives in, when the answer names one. */
+export function ensuredWorkspaceId(result: EnsureTemplateResult): string | null {
+  return result.status === "installed" || result.status === "installing"
+    ? result.workspaceId
+    : null;
+}

package/src/testing/auth-server.ts

@@ -0,0 +1,380 @@
+/**
+ * A mock pod for pod-app sign-in: its OAuth authorization server (RFC 8414
+ * metadata, /authorize as a function standing in for the consent screen,
+ * /token, /revoke) and a few Hub REST doors behind the Bearer token. Inject
+ * `fetch` into the REAL `@synap-core/sdk/connect` (`createPodAppAuth({ fetch })`)
+ * so everything above the wire is the production path. No network.
+ *
+ * Wire behaviour mirrors synap-backend `routers/oauth/routes.ts` for a CIMD
+ * client: `iss` on every authorization answer (RFC 9207), PKCE S256 checked at
+ * /token, single-use codes bound to client_id + redirect_uri + resource, the
+ * token response's `synap_grant` / `synap_user`. Refresh mirrors PB3
+ * (`routers/oauth/refresh.ts`): rotating and single-use, 30 days from issue;
+ * a token presented AGAIN after its use is a reuse that revokes its whole
+ * family AND the live access key; a new code ends the client's older
+ * families; /revoke with a refresh token kills its family and access key.
+ * `refresh: false` is a pod before PB3 (no refresh_token at all).
+ *
+ *   mock.authorize(authorizeUrl)                  → the callback URL (approved)
+ *   mock.authorize(authorizeUrl, { deny: true })  → error=access_denied
+ *   mock.authorize(authorizeUrl, { iss: "https://evil.example" })  → a mix-up attempt
+ *   mock.loseNextRefreshRace()                    → the next redeem is a concurrent loser (refused, no revoke)
+ *   mock.consumeRefreshToken(t)                   → the token was used elsewhere (presenting it is a reuse)
+ *   mock.revokeAll()                              → the person removed the app in their pod
+ */
+import { pkceChallenge, randomToken } from "../connect/encoding";
+import type { PodGrant, PodUser } from "../connect/types";
+
+/** A placeholder pod origin; never contacted. */
+export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
+
+export const MOCK_GRANT: PodGrant[] = [
+  { permission: "entity.post.read", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
+  { permission: "entity.post.create", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
+];
+
+export const MOCK_USER: PodUser = { id: "user_mock_ada", name: "Ada Lovelace" };
+
+export type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
+
+export interface MockAuthServerOptions {
+  issuer?: string;
+  /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+  refresh?: boolean;
+  /** Default 3600 (the pod's 1 h). */
+  accessTtlSec?: number;
+  /** Default 30 days. */
+  refreshIdleSec?: number;
+  /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
+  advertiseRefreshExpiry?: boolean;
+  grant?: PodGrant[];
+  user?: PodUser;
+  /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
+  metadata?: Record<string, unknown>;
+  /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+  writeMode?: "proposed" | "applied";
+  /** Hub paths (after /api/hub) that answer one failure. */
+  failures?: Record<string, MockHubFailure>;
+  now?: () => number;
+}
+
+export interface MockAuthRequest {
+  method: string;
+  url: string;
+  /** Lower-cased header names. */
+  headers: Record<string, string>;
+  /** The form body of a /token or /revoke call. */
+  form: Record<string, string> | null;
+}
+
+export interface AuthorizeDecision {
+  /** The person said no. */
+  deny?: boolean;
+  /** Override `iss` on the answer (null = omit it): a mix-up attack. */
+  iss?: string | null;
+  /** Override `state` on the answer: a forged answer. */
+  state?: string;
+}
+
+export interface MockAuthServer {
+  issuer: string;
+  fetch: typeof fetch;
+  requests: MockAuthRequest[];
+  /** Hub writes seen, in order. */
+  writes: Array<{ method: string; path: string; body: unknown }>;
+  /** Stand-in for the consent screen: validates the request like /authorize, returns where the pod redirects. */
+  authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
+  /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
+  consumeRefreshToken(token: string): void;
+  /** The next refresh redeem loses a concurrent race: invalid_grant, nothing revoked. */
+  loseNextRefreshRace(): void;
+  /** Refresh-token redeems that were reuses (each revoked a family). */
+  reuses: number;
+  /** The person revoked the app: every token stops working. */
+  revokeAll(): void;
+  /** Live (unrevoked) refresh tokens. */
+  liveRefreshTokens(): string[];
+  reset(): void;
+}
+
+interface CodeRow {
+  clientId: string;
+  redirectUri: string;
+  challenge: string;
+  resource: string | null;
+  scope: string[];
+}
+
+interface AccessRow {
+  expiresAt: number;
+  revoked: boolean;
+  family: string | null;
+}
+
+interface RefreshRow {
+  clientId: string;
+  family: string;
+  idleUntil: number;
+  used: boolean;
+  revoked: boolean;
+  scope: string[];
+}
+
+function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers },
+  });
+}
+
+function oauthError(error: string, description: string, status = 400): Response {
+  return json(status, { error, error_description: description });
+}
+
+export function createMockAuthServer(options: MockAuthServerOptions = {}): MockAuthServer {
+  const issuer = options.issuer ?? MOCK_AUTH_ISSUER;
+  const now = options.now ?? Date.now;
+  const refresh = options.refresh ?? true;
+  const accessTtl = options.accessTtlSec ?? 3600;
+  const refreshIdle = options.refreshIdleSec ?? 30 * 24 * 3600;
+  const grant = options.grant ?? MOCK_GRANT;
+  const user = options.user ?? MOCK_USER;
+  const codes = new Map<string, CodeRow>();
+  const access = new Map<string, AccessRow>();
+  const refreshTokens = new Map<string, RefreshRow>();
+  const requests: MockAuthRequest[] = [];
+  const writes: Array<{ method: string; path: string; body: unknown }> = [];
+  let proposalSeq = 0;
+
+  const metadata = (): Record<string, unknown> => {
+    const base: Record<string, unknown> = {
+      issuer,
+      authorization_endpoint: `${issuer}/authorize`,
+      token_endpoint: `${issuer}/token`,
+      registration_endpoint: `${issuer}/register`,
+      revocation_endpoint: `${issuer}/revoke`,
+      revocation_endpoint_auth_methods_supported: ["none"],
+      response_types_supported: ["code"],
+      grant_types_supported: refresh ? ["authorization_code", "refresh_token"] : ["authorization_code"],
+      code_challenge_methods_supported: ["S256"],
+      token_endpoint_auth_methods_supported: ["none"],
+      authorization_response_iss_parameter_supported: true,
+      client_id_metadata_document_supported: true,
+    };
+    for (const [k, v] of Object.entries(options.metadata ?? {})) {
+      if (v === undefined) delete base[k];
+      else base[k] = v;
+    }
+    return base;
+  };
+
+  let loseNextRace = false;
+  let reuses = 0;
+  const revokeFamily = (family: string) => {
+    for (const r of refreshTokens.values()) if (r.family === family) r.revoked = true;
+    for (const a of access.values()) if (a.family === family) a.revoked = true;
+  };
+
+  const tokenBody = (scope: string[], clientId: string, family: string) => {
+    const accessToken = `synap_hub_mock_${randomToken()}`;
+    access.set(accessToken, { expiresAt: now() + accessTtl * 1000, revoked: false, family: refresh ? family : null });
+    const body: Record<string, unknown> = {
+      access_token: accessToken,
+      token_type: "Bearer",
+      expires_in: accessTtl,
+      scope: scope.join(" "),
+      synap_grant: grant.filter((g) => scope.includes(g.permission)),
+      synap_user: user,
+    };
+    if (refresh) {
+      const refreshToken = randomToken();
+      refreshTokens.set(refreshToken, { clientId, family, idleUntil: now() + refreshIdle * 1000, used: false, revoked: false, scope });
+      body.refresh_token = refreshToken;
+      if (options.advertiseRefreshExpiry) body.refresh_token_expires_in = refreshIdle;
+    }
+    return body;
+  };
+
+  async function token(form: Record<string, string>): Promise<Response> {
+    if (form.grant_type === "authorization_code") {
+      const row = form.code ? codes.get(form.code) : undefined;
+      if (form.code) codes.delete(form.code); // claim first: a failed exchange burns the code
+      if (!row) return oauthError("invalid_grant", "Invalid, expired, or already-redeemed authorization code");
+      if (row.clientId !== form.client_id) return oauthError("invalid_grant", "client_id does not match the code");
+      if (row.redirectUri !== form.redirect_uri) return oauthError("invalid_grant", "redirect_uri mismatch");
+      if (!form.code_verifier || (await pkceChallenge(form.code_verifier)) !== row.challenge) {
+        return oauthError("invalid_grant", "PKCE verification failed");
+      }
+      if (form.resource !== undefined && row.resource && form.resource !== row.resource) {
+        return oauthError("invalid_target", "resource does not match the authorization request");
+      }
+      // The latest connect wins: a new code ends this client's older families.
+      for (const r of refreshTokens.values()) if (r.clientId === row.clientId) revokeFamily(r.family);
+      return json(200, tokenBody(row.scope, row.clientId, randomToken()));
+    }
+    if (form.grant_type === "refresh_token") {
+      if (!refresh) return oauthError("unsupported_grant_type", 'Only grant_type "authorization_code" is supported');
+      if (!form.refresh_token || !form.client_id) return oauthError("invalid_request", "refresh_token and client_id are required");
+      const row = refreshTokens.get(form.refresh_token);
+      if (!row || row.clientId !== form.client_id || row.revoked) {
+        return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      }
+      if (row.used) {
+        reuses++;
+        revokeFamily(row.family);
+        return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      }
+      if (row.idleUntil <= now()) return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      if (loseNextRace) {
+        loseNextRace = false;
+        return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      }
+      row.used = true;
+      return json(200, tokenBody(row.scope, row.clientId, row.family));
+    }
+    return oauthError("unsupported_grant_type", "Unsupported grant_type");
+  }
+
+  function hub(method: string, path: string, headers: Record<string, string>, body: unknown): Response | "reject" {
+    const failure = options.failures?.[path];
+    if (failure === "unreachable") return "reject";
+    const bearer = /^Bearer (.+)$/.exec(headers.authorization ?? "")?.[1];
+    const row = bearer ? access.get(bearer) : undefined;
+    if (!row || row.revoked || row.expiresAt <= now()) return json(401, { error: "Unauthorized" });
+    switch (failure) {
+      case "rate_limited":
+        return json(429, { error: "Too many requests" }, { "Retry-After": "30" });
+      case "forbidden":
+        return json(403, { error: "Forbidden" });
+      case "door_unsupported":
+        return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
+      case "server":
+        return json(500, { error: "Internal error" });
+      case "unavailable":
+        return json(503, { error: "Unavailable" });
+    }
+    // The grant fence (spec 17 §5): aggregate reads are refused to a scoped token.
+    if (path.startsWith("/knowledge/") || path === "/entities/retrieve" || path === "/memory/search") {
+      return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
+    }
+    if (method === "GET" && path === "/users/me") return json(200, user);
+    if (method === "GET" && path === "/entities") return json(200, { entities: [], total: 0 });
+    if (method !== "GET") {
+      writes.push({ method, path, body });
+      if ((options.writeMode ?? "proposed") === "proposed") {
+        const proposalId = `prop_mock_${++proposalSeq}`;
+        return json(200, {
+          status: "proposed",
+          message: "Sent for review",
+          proposalId,
+          reviewUrl: `${issuer}/open/${proposalId}`,
+        });
+      }
+      return json(200, { status: "created", id: `ent_mock_${writes.length}` });
+    }
+    return json(404, { error: "Not found" });
+  }
+
+  const mockFetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const request = typeof input === "object" && "method" in input ? input : null;
+    const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers ?? request?.headers).forEach((value, name) => {
+      headers[name.toLowerCase()] = value;
+    });
+    const rawBody = typeof init?.body === "string" ? init.body : request ? await request.clone().text() : "";
+    const isForm = (headers["content-type"] ?? "").includes("application/x-www-form-urlencoded");
+    const form = isForm ? Object.fromEntries(new URLSearchParams(rawBody)) : null;
+    requests.push({ method, url: url.href, headers, form });
+
+    if (url.origin !== new URL(issuer).origin) throw new TypeError(`Failed to fetch: ${url.origin} is not the mock pod`);
+    const path = url.pathname;
+    if (method === "GET" && path === "/.well-known/oauth-authorization-server") return json(200, metadata());
+    if (method === "POST" && path === "/token") return token(form ?? {});
+    if (method === "POST" && path === "/revoke") {
+      const t = form?.token ?? "";
+      const r = refreshTokens.get(t);
+      if (r && form?.client_id && form.client_id !== r.clientId) {
+        return oauthError("unauthorized_client", "The token was not issued to this client");
+      }
+      if (r) revokeFamily(r.family);
+      const a = access.get(t);
+      if (a) a.revoked = true;
+      return new Response(null, { status: 200 });
+    }
+    const hubPath = /^\/api\/hub(\/.*)$/.exec(path)?.[1];
+    if (hubPath) {
+      let body: unknown = undefined;
+      try {
+        body = rawBody ? JSON.parse(rawBody) : undefined;
+      } catch {
+        body = rawBody;
+      }
+      const res = hub(method, hubPath, headers, body);
+      if (res === "reject") throw new TypeError("Failed to fetch: mock pod unreachable");
+      return res;
+    }
+    return json(404, { error: "Not found" });
+  };
+
+  return {
+    issuer,
+    fetch: mockFetch as typeof fetch,
+    requests,
+    writes,
+    authorize(authorizeUrl, decision = {}) {
+      const url = new URL(authorizeUrl);
+      if (`${url.origin}${url.pathname}` !== `${issuer}/authorize`) throw new Error(`Not this pod's /authorize: ${authorizeUrl}`);
+      const q = url.searchParams;
+      const redirectUri = q.get("redirect_uri");
+      const clientId = q.get("client_id");
+      // Phase 1 (shown, never redirected): no verified redirect yet.
+      if (!clientId || !redirectUri) throw new Error("Authorization request rejected: client_id and redirect_uri are required");
+      const answer = new URL(redirectUri);
+      const state = decision.state ?? q.get("state");
+      const finish = (fields: Record<string, string>) => {
+        for (const [k, v] of Object.entries(fields)) answer.searchParams.set(k, v);
+        if (state !== null) answer.searchParams.set("state", state);
+        const iss = decision.iss === undefined ? issuer : decision.iss;
+        if (iss !== null) answer.searchParams.set("iss", iss);
+        return answer.href;
+      };
+      if (q.get("response_type") !== "code") return finish({ error: "unsupported_response_type" });
+      if (q.get("code_challenge_method") !== "S256" || !q.get("code_challenge")) {
+        return finish({ error: "invalid_request", error_description: "PKCE S256 is required" });
+      }
+      const resource = q.get("resource");
+      if (resource !== null && resource !== `${issuer}/api/hub` && resource !== `${issuer}/mcp`) {
+        return finish({ error: "invalid_target" });
+      }
+      const scope = (q.get("scope") ?? "").split(/\s+/).filter(Boolean);
+      if (scope.length === 0) return finish({ error: "invalid_scope" });
+      if (decision.deny) return finish({ error: "access_denied" });
+      const code = randomToken();
+      codes.set(code, { clientId, redirectUri, challenge: q.get("code_challenge")!, resource, scope });
+      return finish({ code });
+    },
+    consumeRefreshToken(t) {
+      const row = refreshTokens.get(t);
+      if (row) row.used = true;
+    },
+    loseNextRefreshRace() {
+      loseNextRace = true;
+    },
+    get reuses() {
+      return reuses;
+    },
+    revokeAll() {
+      for (const row of access.values()) row.revoked = true;
+      for (const row of refreshTokens.values()) row.revoked = true;
+    },
+    liveRefreshTokens() {
+      return [...refreshTokens].filter(([, r]) => !r.used && !r.revoked).map(([t]) => t);
+    },
+    reset() {
+      requests.length = 0;
+      writes.length = 0;
+    },
+  };
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,132 @@
+/**
+ * Demo data for the mock pod. Shapes are the `@synap-core/sdk/public` wire
+ * types, so a fixture that drifts from the contract fails to compile.
+ */
+import type { PublicForm, PublicRecord, PublicShare } from "../public/client";
+
+export const MOCK_FORM: PublicForm = {
+  title: "Get in touch",
+  fields: [
+    { key: "name", label: "Name", type: "text", required: true, constraints: { maxLength: 120 } },
+    { key: "email", label: "Email", type: "email", required: true },
+    {
+      key: "topic",
+      label: "Topic",
+      type: "enum",
+      constraints: { enum: ["Sales", "Support", "Partnership"] },
+    },
+    { key: "message", label: "Message", type: "richtext", help: "A few lines is plenty." },
+  ],
+  successMessage: "Thanks — we received your message.",
+  honeypotField: "hp",
+  ticket: "mock-ticket",
+  minSubmitMs: 0,
+  captcha: { required: false },
+};
+
+export const MOCK_SHARE: PublicShare = {
+  resourceType: "entity",
+  title: "Launch notes",
+  properties: { status: "open", owner: "Ada", featured: true },
+  body: {
+    format: "markdown",
+    content: [
+      "# Launch notes",
+      "",
+      "This page is a **published snapshot** from a Synap pod.",
+      "",
+      "- Read the [Synap docs](https://synap.live)",
+      "- Links other than http, https and mailto render as plain text: [bad](javascript:alert(1))",
+      "",
+      "<script>raw HTML is shown as text, never run</script>",
+    ].join("\n"),
+  },
+  publishedOn: "2026-09-27",
+};
+
+/** One collection of a mock site: its door config and its live records. */
+export interface MockCollection {
+  /** Default sort keys (`-` = descending); also the sort keys the door accepts. */
+  sort: string[];
+  pageSize: number;
+  addressing: "slug" | "publicId";
+  records: PublicRecord[];
+}
+
+/** A mock published site. The manifest is derived from it (counts included). */
+export interface MockSite {
+  title?: string;
+  description?: string;
+  publishedOn: string;
+  collections: Record<string, MockCollection>;
+}
+
+/** A public id of the door's shape (`p_` + 16 base62), deterministic. */
+function publicId(prefix: string, n: number): string {
+  return `p_${prefix}${String(n).padStart(16 - prefix.length, "0")}`;
+}
+
+function slugify(s: string): string {
+  return s
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96);
+}
+
+const PAPER_TITLES = [
+  "Sparse graphs at scale",
+  "Learning to rank, revisited",
+  "A note on causal tracing",
+  "Small models, long contexts",
+  "Evaluating retrieval honestly",
+  "Robust tokenisation",
+  "Graphs that forget",
+  "Calibration under shift",
+  "Latent space cartography",
+  "Proofs as programs, again",
+  "Cheap uncertainty",
+  "Résumé of a decade",
+];
+const VENUES = ["NeurIPS", "ICML", "ACL", "ICLR"];
+
+const PAPERS: PublicRecord[] = PAPER_TITLES.map((title, i) => ({
+  collection: "paper",
+  publicId: publicId("paper", i + 1),
+  slug: slugify(title),
+  title,
+  properties: {
+    year: 2026 - (i % 5),
+    venue: VENUES[i % VENUES.length],
+    open: i % 3 !== 0,
+  },
+  publishedOn: `2026-09-${String(28 - i).padStart(2, "0")}`,
+  body: i % 4 === 3 ? null : { format: "markdown", content: `# ${title}\n\nAbstract of **${title}**.` },
+}));
+
+const PEOPLE: PublicRecord[] = ["Ada Lovelace", "Alan Turing", "Grace Hopper"].map((name, i) => ({
+  collection: "person",
+  publicId: publicId("person", i + 1),
+  slug: null,
+  title: name,
+  properties: { name, role: i === 0 ? "Lead" : "Researcher" },
+  publishedOn: "2026-09-01",
+  body: null,
+}));
+
+/**
+ * The demo site: `paper` (12 records, 5 per page, by slug: pagination),
+ * `person` (by public id), `event` (nothing published: the empty state).
+ */
+export const MOCK_SITE: MockSite = {
+  title: "Demo lab",
+  description: "What the lab publishes",
+  publishedOn: "2026-09-01",
+  collections: {
+    paper: { sort: ["-year"], pageSize: 5, addressing: "slug", records: PAPERS },
+    person: { sort: ["name"], pageSize: 20, addressing: "publicId", records: PEOPLE },
+    event: { sort: [], pageSize: 10, addressing: "slug", records: [] },
+  },
+};