create-rindle 0.1.6

package/templates/minimal/README.md

@@ -0,0 +1,72 @@
+# __PROJECT_NAME__
+
+A SQL-first [Rindle](https://github.com/rindle-sh/rindle) app on [TanStack Start](https://tanstack.com/start),
+generated by `create-rindle`. It's a tiny forum-of-rooms: each room shows a **live message count**
+that the in-process incremental-view engine keeps exact on every write — no polling.
+
+## The shape
+
+Three tiers, same as the Rindle flagship examples:
+
+- **Browser** — a TanStack Start SPA whose data layer *is* Rindle. The wasm IVM engine runs
+  in-process: reads resolve locally and instantly, writes apply optimistically and reconcile on
+  confirmation. Views are co-located Relay-style fragments (`src/components/*.queries.ts`).
+- **API authority** (`server/app-api.ts`) — resolves named queries to ASTs, runs the authoritative SQL
+  mutators, and enforces policy: reads are public, writes require an identity, and a `"spam"` name/body
+  is rejected (you'll see the optimistic write snap back + a toast). It's host-agnostic: the browser
+  reaches it through TanStack Start **server routes** (`src/routes/api.rindle.{query,read,mutate}.tsx`,
+  via `server/rindle-http.ts`) that run in the same server as the app, and SSR calls the very same
+  factory **in-process** (no network hop).
+- **Daemon** (`rindled`) — owns the SQLite data + live IVM and streams normalized deltas to subscribers.
+
+## SQL is the source of truth
+
+The schema lives in `migrations/*.sql`. The `@rindle/client` table schema is **generated** from it
+into `shared/schema.gen.ts` (re-exported by `shared/app-def.ts`, which layers on the relationships,
+normalization, and mutators) — so the TypeScript can't drift from the DDL. To change the schema, edit
+or add a `migrations/*.sql`; `pnpm dev` re-applies it and regenerates `shared/schema.gen.ts` on every
+change.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` (`server/dev.ts`) is one command: it boots the daemon (`rindle up` supervising `rindled` —
+prebuilt binaries from `@rindle/cli`, no Rust toolchain needed), applies the migrations, regenerates
+`shared/schema.gen.ts`, starts Vite (which serves both the app and the `/api/rindle` route), and seeds
+a little data. Open two browser windows
+to watch writes sync live. Post a message and watch the room's count update on the home page. Try a
+room name or message containing "spam" to see the rejection path.
+
+> Requires Node ≥ 22.18 (runs the `.ts` server files via Node's built-in type stripping). The TanStack
+> route tree (`src/routeTree.gen.ts`) is a generated artifact — `pnpm dev` and `pnpm generate-routes`
+> produce it; `pnpm typecheck` runs `tsr generate` first.
+
+## Devtools
+
+In development a floating **🌊 Rindle** devtools pane is mounted (`src/devtools.tsx`): a live view of the
+**mutation timeline** (the optimistic fork/rebase loop, with a snap-back highlight when a prediction
+diverges from the server), the **queries inspector**, and the raw **delta stream**. It's wired up in
+`src/devtools.tsx` (the panel) and `src/rindle-client.ts` (`attachDevtools`), both behind
+`import.meta.env.DEV` — so `@rindle/devtools` and `@rindle/react-devtools` are tree-shaken entirely out
+of `vite build` and never ship to production.
+
+## Layout
+
+| path | what |
+|---|---|
+| `migrations/*.sql` | the schema — **source of truth** |
+| `shared/schema.gen.ts` | generated `@rindle/client` schema (don't edit by hand) |
+| `shared/app-def.ts` | the contract root: schema re-export, relationships, mutators |
+| `shared/auth.ts` | the identity seam (`AuthProvider`) |
+| `server/dev.ts` | one-command dev orchestrator |
+| `server/app-api.ts` | the authority: query resolution, SQL mutators, policy (host-agnostic) |
+| `server/rindle-http.ts` | adapts the authority to a Web Request (the Start API routes call it) |
+| `src/routes/api.rindle.*.tsx` | the three API endpoints as Start server routes (the browser's API) |
+| `src/ssr.ts` | first-paint preload — calls the authority in-process |
+| `src/components/*.queries.ts` | co-located queries + fragments |
+| `src/routes/*` | TanStack routes |
+| `src/devtools.tsx` | dev-only in-browser devtools pane (tree-shaken from prod) |

package/templates/minimal/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.rindled
+*.db
+*.db-*
+.DS_Store
+*.log

package/templates/minimal/migrations/0001_init.sql

@@ -0,0 +1,21 @@
+-- 0001_init — the app's two normalized tables.
+--
+-- This SQL is the SINGLE SOURCE OF TRUTH for the schema. It is applied to the daemon on demand through
+-- the `/migrate` endpoint (run by `rindle migrate apply`, which `pnpm dev` drives for you), and the
+-- @rindle/client TypeScript schema is GENERATED from the daemon's introspected result into
+-- shared/schema.gen.ts — so the TS can't drift from the DDL.
+--
+-- To change the schema: add or edit a file in migrations/. `pnpm dev --watch` re-applies it and
+-- regenerates shared/schema.gen.ts automatically; `pnpm migrate` does the same for a one-shot run.
+--
+-- Column kinds map to the client schema like so: TEXT → string(), INTEGER/REAL → number(), a column
+-- declared BOOLEAN/BOOL → boolean(), JSON → json(). Column ORDER matters — the IVM engine reads it
+-- back with PRAGMA table_info. `IF NOT EXISTS` keeps re-runs safe.
+
+CREATE TABLE IF NOT EXISTS room (id TEXT, name TEXT, createdAt REAL, PRIMARY KEY (id));
+-- The room list orders newest-first.
+CREATE INDEX IF NOT EXISTS room_created ON room (createdAt DESC, id);
+
+CREATE TABLE IF NOT EXISTS message (id TEXT, roomId TEXT, author TEXT, body TEXT, createdAt REAL, PRIMARY KEY (id));
+-- Forward (a room's messages, oldest-first) AND the reverse the live count uses when a message changes.
+CREATE INDEX IF NOT EXISTS message_room ON message (roomId, createdAt, id);

package/templates/minimal/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A SQL-first Rindle app on TanStack Start — generated by create-rindle.",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "dev": "node server/dev.ts",
+    "migrate": "node server/migrate.ts",
+    "generate-routes": "tsr generate",
+    "build": "vite build",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "seed": "node server/seed.ts"
+  },
+  "dependencies": {
+    "@rindle/api-server": "latest",
+    "@rindle/client": "latest",
+    "@rindle/daemon-client": "latest",
+    "@rindle/optimistic": "latest",
+    "@rindle/react": "latest",
+    "@rindle/wasm": "latest",
+    "@tanstack/react-router": "latest",
+    "@tanstack/react-start": "latest",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@rindle/cli": "latest",
+    "@rindle/devtools": "latest",
+    "@rindle/react-devtools": "latest",
+    "@tanstack/router-cli": "^1.167.17",
+    "@tanstack/router-plugin": "^1.168.18",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^5.7.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/minimal/server/app-api.ts

@@ -0,0 +1,115 @@
+// The app authority, runtime-AGNOSTIC. The serverless-shaped tier's actual logic: it resolves named
+// queries to ASTs (the daemon mints opaque leases), runs the AUTHORITATIVE mutators into approved SQL,
+// enforces policy (identity required to write, a "spam" rejection demo), and talks to the daemon over
+// the private bearer-auth'd control plane.
+//
+// It is deliberately free of any host: server/rindle-http.ts adapts it to a Web Request for the Start
+// API routes (src/routes/api.rindle.*.tsx) the browser calls, and the SSR loader (src/ssr.ts) calls the
+// SAME factory in-process. The only per-host inputs are the daemon's control-plane URL + token and the
+// AuthProvider.
+
+import { createRindleApiServer, defineApiMutators, registerQueries } from "@rindle/api-server";
+import type { ApiMutators, MutationContext, RindleApiServer, SqlMutationTx } from "@rindle/api-server";
+import { HttpRindleDaemonClient } from "@rindle/daemon-client";
+import type { FetchLike } from "@rindle/daemon-client";
+
+import { createRoomArgs, normalizeBody, normalizeName, normalizeSubject, postMessageArgs } from "../shared/app-def.ts";
+import type { Identity } from "../shared/auth.ts";
+import { roomsQuery } from "../src/components/RoomCard.queries.ts";
+import { roomDetailQuery } from "../src/components/RoomView.queries.ts";
+
+/** The authority's principal is the verified identity (or undefined when anonymous). */
+export type User = Identity | undefined;
+
+// The authority's query surface is just the list of co-located client queries. Each `defineQuery`
+// re-runs its validator on the UNTRUSTED wire args before building the AST, so a malformed client
+// can't smuggle a garbage arg in.
+const apiQueries = registerQueries<User>([roomsQuery, roomDetailQuery]);
+
+const apiMutators = defineApiMutators<User, ApiMutators<User>>({
+  createRoom: (tx: SqlMutationTx, raw: unknown, ctx: MutationContext<User>) => {
+    const a = createRoomArgs.parse(raw);
+    requireUser(ctx.user);
+    const name = cleanName(a.name);
+    tx.exec("INSERT OR IGNORE INTO room (id, name, createdAt) VALUES (?, ?, ?)", [a.id, name, a.createdAt]);
+  },
+  postMessage: (tx: SqlMutationTx, raw: unknown, ctx: MutationContext<User>) => {
+    const a = postMessageArgs.parse(raw);
+    const who = requireUser(ctx.user);
+    const body = cleanBody(a.body);
+    // Insert only into a room that exists — a racing client can't post into a deleted room. `author`
+    // is the VERIFIED subject, never the wire arg.
+    tx.exec(
+      `INSERT INTO message (id, roomId, author, body, createdAt)
+       SELECT ?, ?, ?, ?, ? WHERE EXISTS (SELECT 1 FROM room WHERE id = ?)`,
+      [a.id, a.roomId, who.subject, body, a.createdAt, a.roomId],
+    );
+  },
+});
+
+/** A bearer-auth'd daemon control-plane target. */
+export interface AppApiOptions {
+  /** The daemon control-plane base URL — bearer-auth'd. */
+  daemonUrl: string;
+  /** The shared bearer token for {@link daemonUrl} (daemon ↔ this tier ONLY — never reaches the browser). */
+  daemonToken: string;
+  /** Override the daemon HTTP transport (defaults to global `fetch`). */
+  fetch?: FetchLike;
+}
+
+/** Build the configured API server. Stateless: safe to construct per-request or once per process.
+ *  Reads are PUBLIC; writes require a verified identity. */
+export function createAppApi(opts: AppApiOptions): RindleApiServer<User> {
+  const daemon = new HttpRindleDaemonClient({
+    baseUrl: opts.daemonUrl,
+    headers: { authorization: `Bearer ${opts.daemonToken}` },
+    fetch: opts.fetch,
+  });
+  return createRindleApiServer<User>({
+    daemon,
+    queries: apiQueries,
+    mutators: apiMutators,
+    authorizeQuery: () => true, // public reads
+    authorizeMutation: ({ user }) => !!user && user.subject.length > 0, // must be signed in
+  });
+}
+
+/** Resolve the daemon wiring from an environment bag, shared by both host shells. */
+export function resolveDaemon(
+  env: Record<string, string | undefined>,
+  defaults: { daemonUrl: string; daemonToken: string },
+): Pick<AppApiOptions, "daemonUrl" | "daemonToken"> {
+  return {
+    daemonUrl: env.RINDLE_DAEMON_URL ?? defaults.daemonUrl,
+    daemonToken: env.RINDLE_DAEMON_TOKEN ?? defaults.daemonToken,
+  };
+}
+
+/** Map an error thrown out of the API server (or body parsing) to an HTTP status + message. */
+export function httpErrorOf(err: unknown): { status: number; message: string } {
+  const status = typeof err === "object" && err !== null ? (err as { status?: unknown }).status : undefined;
+  return {
+    status: typeof status === "number" ? status : 500,
+    message: String(err instanceof Error ? err.message : err),
+  };
+}
+
+/** A room name policy that also exercises the REJECTION path end to end (toast in the UI). */
+function cleanName(name: string): string {
+  const out = normalizeName(name);
+  if (out.length === 0) throw new Error("a room name is required");
+  if (/\bspam\b/i.test(out)) throw new Error('the word "spam" is not allowed');
+  return out;
+}
+
+function cleanBody(body: string): string {
+  const out = normalizeBody(body);
+  if (out.length === 0) throw new Error("a message can't be empty");
+  if (/\bspam\b/i.test(out)) throw new Error('the word "spam" is not allowed');
+  return out;
+}
+
+function requireUser(user: User): Identity {
+  if (!user || user.subject.length === 0) throw new Error("you must be signed in");
+  return { subject: normalizeSubject(user.subject) };
+}

package/templates/minimal/server/auth-dev.ts

@@ -0,0 +1,22 @@
+// The DEV identity provider — resolves the `x-rindle-user` header to an Identity: no passwords, no
+// auth service, so the example runs standalone. The browser persists a handle per tab
+// (src/rindle-client.ts) and sends it on every `/api/rindle/*` call; SSR uses a fixed viewer (reads
+// are public). Swap this for a real provider (e.g. JWT-against-JWKS) without touching the API server.
+
+import { normalizeSubject } from "../shared/app-def.ts";
+import type { AuthProvider, Identity } from "../shared/auth.ts";
+
+/** Resolve a handle to a dev identity, or null when blank. */
+export function identityFromHandle(handle: string | null | undefined): Identity | null {
+  if (!handle) return null;
+  const subject = normalizeSubject(handle);
+  if (!subject || subject === "anon") return null;
+  return { subject };
+}
+
+/** The dev AuthProvider: the principal rides the `x-rindle-user` header. */
+export const devAuth: AuthProvider = {
+  verify(req: Request): Promise<Identity | null> {
+    return Promise.resolve(identityFromHandle(req.headers.get("x-rindle-user")));
+  },
+};

package/templates/minimal/server/dev.ts

@@ -0,0 +1,148 @@
+// One-command dev: boots the daemon (the Rust `rindled`, supervised by `rindle up`) and the Vite dev
+// server — which also serves the app's API as a Start server route — and tears them down together.
+//
+//   pnpm dev          # boots everything: daemon + migrations + schema gen + seed + Vite (+ API route)
+//
+// The DATABASE tier is one command: `rindle up --migrate --gen --watch` supervises `rindled` (respawn
+// on exit / migrate-at-bounce), applies the migrations/ DDL once it's ready, generates the
+// @rindle/client schema TS from the introspected result (shared/schema.gen.ts), and re-runs both on
+// every *.sql change. The schema is SQL-first: migrations/*.sql is the source of truth and
+// shared/schema.gen.ts is generated from it. Seeding is app code, so it stays here: once the schema is
+// live we run the idempotent seed. The rest is the web tier (Vite), which also serves the API route.
+//
+// The `rindle` + `rindled` binaries come from @rindle/cli (prebuilt, per-platform) — no Rust toolchain
+// needed. Working inside the Rindle monorepo? Set RINDLE_BIN_DIR=target/release (after a cargo build)
+// to use locally built binaries instead.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { rindleBinaryPath, rindledBinaryPath } from "@rindle/cli";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const appRoot = resolve(here, "..");
+
+const DAEMON_TOKEN = "dev-daemon-token";
+const DAEMON_URL = "http://127.0.0.1:7600"; // the daemon's control plane (httpPort below)
+const WS_URL = "ws://127.0.0.1:7601"; // rindled serves subscriptions on their own port
+
+const children: ChildProcess[] = []; // app tiers (seed) — share our process group
+let supervisor: ChildProcess | undefined; // `rindle up` — its own group; it owns the rindled child
+let shuttingDown = false;
+const stop = () => {
+  shuttingDown = true;
+  // `rindle up` runs detached in its own process group and owns `rindled`, so group-kill it to take
+  // both down; the app tiers share our group and are killed individually.
+  if (supervisor?.pid) {
+    try {
+      process.kill(-supervisor.pid, "SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }
+  for (const child of children) child.kill("SIGKILL");
+  process.exit(0);
+};
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+
+function node(script: string, env: NodeJS.ProcessEnv = {}): ChildProcess {
+  const child = spawn(process.execPath, [join(appRoot, script)], {
+    stdio: "inherit",
+    env: { ...process.env, RINDLE_DAEMON_TOKEN: DAEMON_TOKEN, ...env },
+  });
+  children.push(child);
+  return child;
+}
+
+// Poll the control plane until `rindle up --migrate` has applied the schema (tables appear) and the
+// daemon is serving — a real readiness gate that also rides through the migrate-at-bounce restart.
+async function waitForSchema(timeoutMs = 60_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${DAEMON_URL}/schema`, { headers: { authorization: `Bearer ${DAEMON_TOKEN}` } });
+      if (res.ok) {
+        const body = (await res.json()) as { tables?: unknown[] };
+        if (Array.isArray(body.tables) && body.tables.length > 0) return true;
+      }
+    } catch {
+      /* not up yet, or mid-bounce — retry */
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+
+// Resolve the prebuilt binaries (from @rindle/cli, or RINDLE_BIN_DIR in the monorepo). They must be
+// co-located so `rindle up` finds `rindled` as a sibling — @rindle/cli ships them that way.
+const rindleBin = rindleBinaryPath();
+const rindledBin = rindledBinaryPath();
+
+// The daemon config `rindle up` runs against: loopback, the dev token, no `tables` (the schema is
+// applied from migrations/ on demand and introspected — never created at boot).
+const dataDir = join(appRoot, ".rindled");
+mkdirSync(dataDir, { recursive: true });
+const daemonJson = join(dataDir, "daemon.json");
+writeFileSync(
+  daemonJson,
+  JSON.stringify({
+    db: join(dataDir, "app.db"),
+    httpPort: 7600,
+    wsPort: 7601,
+    authToken: DAEMON_TOKEN,
+    nWorkers: 4,
+    tables: [],
+  }),
+);
+
+// The database tier, one command: supervise `rindled`, apply migrations/ on boot, regenerate the
+// client schema (`--gen` → shared/schema.gen.ts), and re-run both on every *.sql change (`--watch`).
+// Detached into its own process group so `stop()` can group-kill it together with the `rindled` child.
+const migrationsDir = join(appRoot, "migrations");
+const schemaGen = join(appRoot, "shared/schema.gen.ts"); // SQL-first: generated from migrations/*.sql
+supervisor = spawn(
+  rindleBin,
+  ["up", "--config", daemonJson, "--daemon-bin", rindledBin, "--migrate", "--gen", schemaGen, "--watch", "--dir", migrationsDir],
+  {
+    stdio: ["ignore", "inherit", "inherit"],
+    detached: true,
+    env: { ...process.env, RINDLE_DAEMON_TOKEN: DAEMON_TOKEN, RINDLE_DAEMON_URL: DAEMON_URL },
+  },
+);
+supervisor.on("exit", (code, signal) => {
+  if (shuttingDown) return;
+  console.error(`[dev] rindle up exited (code ${code}, signal ${signal}) — shutting down`);
+  stop();
+});
+
+// Wait until the schema is live (migrations applied, daemon re-introspected), then the API tier and
+// the idempotent seed (a fresh DB shows an empty app until the seed lands; re-running is a no-op).
+if (!(await waitForSchema())) {
+  console.error("[dev] daemon did not come up with a schema in time — check migrations/");
+  if (supervisor.pid) {
+    try {
+      process.kill(-supervisor.pid, "SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }
+  process.exit(1);
+}
+node("server/seed.ts", { RINDLE_DAEMON_URL: DAEMON_URL });
+
+// The web tier: Vite programmatically. The app's API tier is a set of Start SERVER ROUTES
+// (src/routes/api.rindle.*.tsx) served by this same dev server — no proxy, no standalone API process.
+// Those routes AND the SSR loader read the daemon IN-PROCESS (in this Vite process), so point this
+// process's own env at the daemon control plane (URL + token); the client bundle gets the PUBLIC ws url.
+process.env.RINDLE_DAEMON_URL = DAEMON_URL;
+process.env.RINDLE_DAEMON_TOKEN = DAEMON_TOKEN;
+process.env.VITE_DAEMON_WS = WS_URL;
+const { createServer } = await import("vite");
+const vite = await createServer({ root: appRoot });
+await vite.listen();
+vite.printUrls();
+console.log("[dev] migrations + shared/schema.gen.ts auto-apply/regenerate on boot + on every migrations/ change.");
+console.log("[dev] open two browser windows to watch writes sync live.");

package/templates/minimal/server/migrate.ts

@@ -0,0 +1,47 @@
+// `pnpm migrate` — apply the schema migrations via the `rindle` CLI, then seed. The CLI is the real
+// operator tool (the prebuilt binary shipped by @rindle/cli); migrations are applied by
+// `rindle migrate apply`, NOT a TS library. Idempotent throughout: the daemon dedups migrations by
+// `id`, and the seed carries a durable idempotency key — re-running is a no-op.
+//
+//   pnpm migrate                       # apply (daemon self-restarts to re-introspect) → seed
+//   node server/migrate.ts --deploy    # CI/prod: apply only (caller seeds separately)
+
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { rindleBinaryPath } from "@rindle/cli";
+
+import { seed } from "./seed.ts";
+
+const appRoot = resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+const migrationsDir = join(appRoot, "migrations");
+
+const DAEMON_URL = process.env.RINDLE_DAEMON_URL ?? "http://127.0.0.1:7600";
+const DAEMON_TOKEN = process.env.RINDLE_DAEMON_TOKEN ?? "dev-daemon-token";
+const deploy = process.argv.includes("--deploy");
+
+function run(cmd: string, args: string[]): void {
+  const r = spawnSync(cmd, args, { stdio: "inherit" });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error(`\`${cmd} ${args.join(" ")}\` exited with ${r.status ?? r.signal}`);
+}
+
+async function main(): Promise<void> {
+  const rindle = rindleBinaryPath();
+  // Apply pending *.sql through the daemon's /migrate. Idempotent (dedup by id), additive-DDL-linted,
+  // and it waits out a dev daemon's migrate-at-bounce self-restart.
+  run(rindle, ["migrate", "apply", "--dir", migrationsDir, "--url", DAEMON_URL, "--token", DAEMON_TOKEN]);
+
+  if (deploy) {
+    console.log("[migrate] --deploy: applied; the caller seeds next.");
+    return;
+  }
+  console.log("[migrate] seeding…");
+  await seed({ url: DAEMON_URL, token: DAEMON_TOKEN });
+}
+
+main().catch((err) => {
+  console.error(`[migrate] ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/templates/minimal/server/rindle-http.ts

@@ -0,0 +1,38 @@
+// The HTTP host for the app authority: it adapts a Web `Request` to the runtime-agnostic factory in
+// app-api.ts and dispatches the three Rindle endpoints. The TanStack Start server routes in
+// src/routes/api.rindle.*.tsx import this from INSIDE their handlers (a dynamic import), so this module
+// and its daemon/SQL deps never reach the client bundle. SSR reads skip this and call the authority
+// in-process instead (src/ssr.ts) — no network hop.
+
+import type { ApiContext } from "@rindle/api-server";
+
+import { createAppApi, httpErrorOf, resolveDaemon } from "./app-api.ts";
+import type { User } from "./app-api.ts";
+import { devAuth } from "./auth-dev.ts";
+
+/** Which Rindle endpoint a request targets. */
+export type RindleRouteKind = "query" | "read" | "mutate";
+
+/** Run one `/api/rindle/{query,read,mutate}` request through the authority. Stateless: the authority is
+ *  built per request (cheap), so this is safe in a fresh-per-request serverless host too. */
+export async function handleRindleJson(kind: RindleRouteKind, request: Request): Promise<Response> {
+  try {
+    const daemon = resolveDaemon(process.env, {
+      daemonUrl: "http://127.0.0.1:7600",
+      daemonToken: "dev-daemon-token",
+    });
+    const api = createAppApi(daemon);
+    const body = await request.json().catch(() => ({}));
+    const context: ApiContext<User> = { user: (await devAuth.verify(request)) ?? undefined, request };
+    const out =
+      kind === "query"
+        ? await api.handleQueryJson(body, context)
+        : kind === "read"
+          ? await api.handleReadJson(body, context)
+          : await api.handleMutateJson(body, context);
+    return Response.json(out);
+  } catch (err) {
+    const { status, message } = httpErrorOf(err);
+    return Response.json({ error: message }, { status });
+  }
+}

package/templates/minimal/server/seed.ts

@@ -0,0 +1,70 @@
+// Seed the daemon with a little starter data — a couple of rooms and some messages — pushed through
+// the private control plane as ONE foreign SqlTxn carrying an idempotency key: the file-backed daemon
+// (`rindled`) won't re-seed across restarts (the key is durable). Retries until the daemon answers, so
+// dev.ts can fire-and-forget it during startup.
+
+import { HttpRindleDaemonClient } from "@rindle/daemon-client";
+import type { SqlStatement, WireValue } from "@rindle/daemon-client";
+
+const DAEMON_URL = process.env.RINDLE_DAEMON_URL ?? "http://127.0.0.1:7600";
+const DAEMON_TOKEN = process.env.RINDLE_DAEMON_TOKEN ?? "dev-daemon-token";
+
+const ROOMS = [
+  { id: "room-welcome", name: "Welcome" },
+  { id: "room-random", name: "Random" },
+];
+
+const MESSAGES = [
+  { roomId: "room-welcome", author: "ada", body: "Welcome! This whole board is a Rindle app — the room counts are live incremental views." },
+  { roomId: "room-welcome", author: "grace", body: "Post a message and watch the count on the home page update with no polling." },
+  { roomId: "room-random", author: "alan", body: "Open two browser windows side by side to see writes sync." },
+];
+
+const at = (n: number): number => 1717000000000 + n * 60_000; // deterministic timestamps
+
+function valuesClause(rowCount: number, colCount: number): string {
+  const tuple = `(${Array(colCount).fill("?").join(", ")})`;
+  return Array(rowCount).fill(tuple).join(", ");
+}
+
+export function seedStatements(): SqlStatement[] {
+  const statements: SqlStatement[] = [];
+
+  statements.push({
+    sql: `INSERT INTO room (id, name, createdAt) VALUES ${valuesClause(ROOMS.length, 3)}`,
+    params: ROOMS.flatMap((r, i) => [r.id, r.name, at(i)]) as WireValue[],
+  });
+
+  statements.push({
+    sql: `INSERT INTO message (id, roomId, author, body, createdAt) VALUES ${valuesClause(MESSAGES.length, 5)}`,
+    params: MESSAGES.flatMap((m, i) => [`msg-${i}`, m.roomId, m.author, m.body, at(i + ROOMS.length)]) as WireValue[],
+  });
+
+  return statements;
+}
+
+export interface SeedOptions {
+  url?: string;
+  token?: string;
+}
+
+export async function seed({ url = DAEMON_URL, token = DAEMON_TOKEN }: SeedOptions = {}): Promise<void> {
+  const daemon = new HttpRindleDaemonClient({ baseUrl: url, headers: { authorization: `Bearer ${token}` } });
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const out = await daemon.executeSqlTxn({ idempotencyKey: "seed-v1", statements: seedStatements() });
+      console.log(
+        out.applied
+          ? `[seed] seeded ${ROOMS.length} rooms + ${MESSAGES.length} messages (cv ${out.cv})`
+          : `[seed] already seeded (idempotency key absorbed the replay)`,
+      );
+      return;
+    } catch (err) {
+      if (attempt >= 20) throw err;
+      await new Promise((r) => setTimeout(r, 500)); // daemon still booting — retry
+    }
+  }
+}
+
+// Allow `node server/seed.ts` standalone.
+if (import.meta.url === `file://${process.argv[1]}`) await seed();