makersclaw 0.6.0 → 0.7.0

package/src/install.mjs

@@ -2,8 +2,15 @@
 // result and prints nothing: src/cli.mjs says it, as text or as --json.
 //
 // Two files record what an app holds:
-//   makersclaw.json   the template and version it was laid from, and each
-//                     block with the version it came from
+//   makersclaw.json   the template and version it was laid from, each
+//                     block with the version it came from, where its
+//                     tables live (`tables`: "own" or "public") and which
+//                     fixed files it runs on (`mode`: "server" or
+//                     "browser"). The rest of its keys are the app's
+//                     (`brain`: the platform's declaration; `moves`: a
+//                     store package's move map); every command keeps
+//                     them. `tables` is never "moved": that is the
+//                     platform's mode, and no command writes it
 //   check/pins.json   sha256 of every fixed file, the template's and the
 //                     blocks' — `npm run check` refuses one that differs
 // and a third says which package versions it installs:
@@ -21,7 +28,7 @@ import { join } from "node:path";
 import { hashFile, readJson, removeFile, sha256, walk, writeFile, writeJson } from "./fsutil.mjs";
 import { LOCKFILE, LockError, deriveLock, parseLock } from "./lockfile.mjs";
 import { NPM_LOCKFILE, PNPM_VERSION, installDeps } from "./pm.mjs";
-import { BLOCK_DIR, loadBlocks, loadItems, loadTemplate, packageInfo, readmeOf, suggest, templateNames } from "./registry.mjs";
+import { BASE_MODE, BLOCK_DIR, loadBlocks, loadItems, loadTemplate, modeFiles, packageInfo, readmeOf, suggest, templateNames } from "./registry.mjs";
 
 export const MANIFEST = "makersclaw.json";
 export const PINS = "check/pins.json";
@@ -68,6 +75,7 @@ function readState(dir) {
 
 function requireManifest(dir) {
   const state = readState(dir);
+  if (state.manifest?.tables === MOVED) throw movedManifest();
   if (!state.manifest) {
     const hasApp = existsSync(join(dir, "package.json"));
     throw new CliError(
@@ -80,6 +88,142 @@ function requireManifest(dir) {
   return state;
 }
 
+/** Where an app's tables live: "own", its own schema (app_<name>), or
+ *  "public", the workspace schema every app shared before 0.7.0. */
+const TABLES = ["own", "public"];
+
+/**
+ * The platform's third mode (claw's MIGRATE-SPEC M17 and §10): a legacy
+ * app whose tables the workspace's move put in its own schema, while its
+ * code still names public. The platform holds it (the app's blueprint,
+ * claw.app_roles); the app's makersclaw.json keeps "public" (or no key)
+ * until its rebuild writes "own". So no command writes "moved": `init
+ * --tables moved` is refused, and so is every command over a manifest
+ * that says it, rather than write it back.
+ */
+const MOVED = "moved";
+const MOVED_WHY = "moved is the platform's mode, never a manifest's";
+function movedManifest() {
+  return new CliError(
+    `${MANIFEST} says tables "moved": ${MOVED_WHY}`,
+    `set "tables" to "public" (or take the key out, for an app laid before 0.7.0): a moved app's code still names public, and its rebuild sets "own"`,
+  );
+}
+
+/**
+ * A makersclaw.json a lay wrote. Every lay since 0.2.0 records the
+ * `version` it laid, so a manifest without one was written by someone
+ * else first: the platform writes its `brain` declaration into a
+ * work-first app's new manifest before that app's first `init`
+ * (APPS-SPEC 4.2). Such a manifest's keys are kept like any other's, but
+ * it is no record of an app from before 0.7.0.
+ */
+function writtenByLay(manifest) {
+  return Boolean(manifest) && Object.hasOwn(manifest, "version");
+}
+
+/**
+ * The `tables` init writes. It never flips an app: an app's tables move
+ * from public to their own schema only with its workspace (the platform's
+ * move), never because a refresh ran `init --force`. So an app's
+ * makersclaw.json keeps its value — an absent key in a manifest a lay
+ * wrote is an app from before 0.7.0, on public — and a `--tables` that
+ * says otherwise is refused. Where no lay wrote a makersclaw.json (there
+ * is none, or it holds only the platform's keys) and it names no tables,
+ * there is no record to keep: a new app is "own" unless told, and an app
+ * laid before makersclaw kept one is "public" unless told (the platform,
+ * which holds the truth, always tells).
+ */
+function tablesFor(dir, before, asked) {
+  if (asked === MOVED) throw new CliError(`--tables moved: ${MOVED_WHY}`, `leave --tables out: a moved app keeps its makersclaw.json's "public" until its rebuild sets "own"`);
+  if (before.manifest?.tables === MOVED) throw movedManifest();
+  if (asked !== undefined && !TABLES.includes(asked)) {
+    throw new CliError(`--tables takes ${TABLES.join(" or ")}, not "${asked}"`, "own: the app's tables in its own schema (every new app) · public: an app from before 0.7.0");
+  }
+  const named = Boolean(before.manifest) && Object.hasOwn(before.manifest, "tables");
+  if (!named && !writtenByLay(before.manifest)) return asked ?? (existsSync(join(dir, "package.json")) ? "public" : "own");
+  const had = named ? before.manifest.tables : "public";
+  if (!TABLES.includes(had)) {
+    throw new CliError(`${MANIFEST} says tables ${JSON.stringify(had)}; an app's tables are ${TABLES.join(" or ")}`, `set "tables" in ${MANIFEST} to the one the platform holds for this app`);
+  }
+  if (asked !== undefined && asked !== had) {
+    throw new CliError(
+      (named ? `this app's tables are ${had}, not ${asked}` : `${MANIFEST} names no tables, so this app's are public (laid before 0.7.0), not ${asked}`) +
+        (had === "public" ? ": an app's tables move from public to their own schema only with its workspace" : ": an app on its own schema never goes back to public"),
+      `leave --tables out, or pass --tables ${had}` + (named ? "" : `; if its tables are already in its own schema, put "tables": "own" back in ${MANIFEST}`),
+    );
+  }
+  return had;
+}
+
+/** Which fixed files an app runs on: "server", a Next server in the
+ *  workspace (files/ as it is; an absent key, every app before 0.7.0), or
+ *  "browser", code that runs in the member's browser: files the platform
+ *  serves, reading and writing through its data door (template.json
+ *  `modes.browser`). */
+const MODES = [BASE_MODE, "browser"];
+
+/** The app's mode, from its makersclaw.json. Anything but the two is
+ *  refused: which fixed files to lay depends on it. */
+function modeOf(manifest) {
+  const mode = manifest && Object.hasOwn(manifest, "mode") ? manifest.mode : BASE_MODE;
+  if (!MODES.includes(mode)) {
+    throw new CliError(`${MANIFEST} says mode ${JSON.stringify(mode)}; an app's mode is ${MODES.join(" or ")}`, `makersclaw mode <${MODES.join("|")}> sets the one the platform holds for this app`);
+  }
+  return mode;
+}
+
+/**
+ * The `mode` init writes. Like `tables`, init never changes an app's: a
+ * refresh is claw's `init --force` over the app it has, and a flip there
+ * would turn a server app into a browser one whose Server Actions then fail
+ * its export. So a manifest that names a mode keeps it, whoever wrote it,
+ * and so does one a lay wrote (absent: server); a --mode that differs is
+ * refused, and `makersclaw mode` is the one switch. A new manifest takes
+ * --mode's value, and with none no key: an absent mode is server, the
+ * CLI's own default, because outside Makersclaw no door answers a browser
+ * app. { mode, key }: the app's mode, and the value to write (undefined:
+ * the key stays as it is).
+ */
+function modeFor(before, asked) {
+  if (asked !== undefined && !MODES.includes(asked)) {
+    throw new CliError(`--mode takes ${MODES.join(" or ")}, not "${asked}"`, "server: a Next server in the workspace (the default) · browser: its code runs in the member's browser, and every read and write goes through the platform's data door");
+  }
+  const named = Boolean(before.manifest) && Object.hasOwn(before.manifest, "mode");
+  if (!named && !writtenByLay(before.manifest)) return { mode: asked ?? BASE_MODE, key: asked };
+  const had = modeOf(before.manifest);
+  if (asked !== undefined && asked !== had) {
+    throw new CliError(
+      `this app is a ${had} app, not ${asked}: an app changes mode only with makersclaw mode`,
+      `leave --mode out, or run makersclaw mode ${asked}: it lays that mode's fixed files and says what the app's own code must change`,
+    );
+  }
+  return { mode: had, key: undefined };
+}
+
+/** A browser app's tables are its own: the door serves an app's own schema
+ *  and nothing else, so a browser app on public would read nothing. `how`
+ *  says where the pair came from, for the refusal's words. */
+function requireOwnTables(mode, tables, how) {
+  if (mode !== "browser" || tables === "own") return;
+  const why = "a browser app reads and writes only through the platform's data door, which serves an app's own schema and nothing else";
+  if (how === "flags") throw new CliError(`a browser app's tables are own, not ${tables}: ${why}`, "leave --tables out: --mode browser writes tables own");
+  if (how === "switch") {
+    throw new CliError(
+      `${tables === undefined ? `${MANIFEST} names no tables, so this app's are public (laid before 0.7.0)` : `this app's tables are ${tables}`}, not own: ${why}`,
+      "an app's tables move to their own schema only with its workspace (the platform's move); until then it stays a server app",
+    );
+  }
+  throw new CliError(`${MANIFEST} says mode browser and tables ${tables}: ${why}`, `if its tables are in its own schema, set "tables": "own"; if not, makersclaw mode server lays it as a server app`);
+}
+
+/** The files the template lays in this mode (registry modeFiles). */
+function modeFilesOrFail(tpl, mode) {
+  const files = modeFiles(tpl, mode);
+  if (!files) throw new CliError(`template ${tpl.name} has no ${mode} mode in makersclaw ${version()}`, `its modes: ${[BASE_MODE, ...Object.keys(tpl.modes ?? {})].join(", ")}`);
+  return files;
+}
+
 function loadTemplateOrFail(name) {
   const tpl = loadTemplate(name);
   if (!tpl) throw new CliError(`this makersclaw has no template "${name}"`, `templates: ${templateNames().join(", ")}`);
@@ -149,11 +293,12 @@ function writeLock(dir, cut, written) {
 
 const lockSummary = (cut) => (cut ? { covered: cut.covered.length, carried: cut.carried, left: cut.left } : null);
 
-/** Paths a template may remove when a newer version stops shipping them:
- *  its fixed files, the ones it names as retired (middleware.js since
- *  0.6.0: Next 16 fails a build that has it beside proxy.js), and the kit,
- *  parts and block folders. Anything else a pins.json names is left alone
- *  — it is not ours to delete. */
+/** Paths a template may remove when a newer version stops shipping them,
+ *  or the app's mode stops laying them: its fixed files (the base's, so
+ *  the ones a mode drops too), the ones it names as retired (middleware.js
+ *  since 0.6.0: Next 16 fails a build that has it beside proxy.js), and
+ *  the kit, parts and block folders. Anything else a pins.json names is
+ *  left alone — it is not ours to delete. */
 function ownedPath(path, tpl) {
   if (/^components\/(?:ui|parts|blocks)\//.test(path) || /^lib\/[^/]+\.js$/.test(path)) return true;
   if ((tpl.retired ?? []).includes(path)) return true;
@@ -162,12 +307,24 @@ function ownedPath(path, tpl) {
 
 /**
  * Lay a template — and the blocks the app already has — over `dir`: the
- * one routine behind init, init --force and update. Fixed files and docs
- * are replaced; starters are laid only when missing; package.json is
+ * one routine behind init, init --force, update and mode. Fixed files and
+ * docs are replaced; starters are laid only when missing; package.json is
  * merged; blocks come again from this version; what an older version
- * pinned and this one no longer ships is removed.
+ * pinned and this one no longer ships is removed. makersclaw.json is
+ * rewritten over what it held: `template`, `version` and `blocks` are
+ * this lay's, `tables` is init's (tablesFor; update leaves it as it was),
+ * `mode` is a new manifest's init's or `makersclaw mode`'s (modeFor), and
+ * every other key — the platform's `brain` declaration, one a later
+ * version adds — survives a refresh and an update. Until 0.7.0 it was
+ * rewritten as exactly those three, and a declaration was lost.
+ *
+ * The files are the app's mode's (modeFiles): a browser app gets the
+ * browser overlay's copy of a fixed file where there is one, and none of
+ * the files browser mode drops. The pins follow: a file the mode does not
+ * lay is not pinned, and one that was pinned is removed as a retired one
+ * is, so a switch of mode leaves only the new mode's fixed files.
  */
-function lay(dir, tpl, before) {
+function lay(dir, tpl, before, { tables, mode } = {}) {
   const v = version();
   const written = [];
   const kept = [];
@@ -177,7 +334,13 @@ function lay(dir, tpl, before) {
   const pins = {};
   const fresh = !existsSync(join(dir, "package.json"));
 
-  for (const f of tpl.files) {
+  // Decided before a file is written: a refused mode leaves the app as it was.
+  const keys = { ...(tables ? { tables } : {}), ...(mode ? { mode } : {}) };
+  const appMode = modeOf({ ...before.manifest, ...keys });
+  requireOwnTables(appMode, keys.tables ?? before.manifest?.tables ?? "public", "manifest");
+  const files = modeFilesOrFail(tpl, appMode);
+
+  for (const f of files) {
     const to = join(dir, f.path);
     if (f.class === "starter" && existsSync(to)) {
       kept.push(f.path);
@@ -259,12 +422,24 @@ function lay(dir, tpl, before) {
       removed.push(p);
     }
   }
+  // A file the mode leaves out that no pin names is not the template's to
+  // delete (the app wrote it, or a hand laid it), but it is in the way:
+  // under output: "export" Next ignores a proxy.js, and lib/db.js is pg.
+  const laid = new Set(files.map((f) => f.path));
+  for (const f of tpl.files) {
+    if (f.class !== "fixed" || laid.has(f.path) || f.path in before.pins || !existsSync(join(dir, f.path))) continue;
+    notes.push(`${f.path}: ${appMode} mode lays none, and this one is not pinned — left alone; delete it unless the app's own code needs it`);
+  }
 
   writeJson(join(dir, PINS), sortKeys(pins));
-  writeJson(join(dir, MANIFEST), { template: tpl.name, version: v, blocks: sortKeys(blocks) });
+  const manifest = { ...before.manifest, template: tpl.name, version: v, blocks: sortKeys(blocks), ...keys };
+  writeJson(join(dir, MANIFEST), manifest);
   return {
     template: tpl.name,
     version: v,
+    // An absent key is an app from before 0.7.0: its tables are in public.
+    tables: manifest.tables ?? "public",
+    mode: appMode,
     from: before.manifest?.version ?? null,
     written,
     kept,
@@ -278,14 +453,14 @@ function lay(dir, tpl, before) {
   };
 }
 
-/** `init [dir] [-t next] [--force]` */
-export function init(dir, { template = "next", force = false } = {}) {
+/** `init [dir] [-t next] [--force] [--tables own|public] [--mode browser|server]` */
+export function init(dir, { template = "next", force = false, tables, mode: askedMode } = {}) {
   const tpl = loadTemplateOrFail(template);
   const before = readState(dir);
   if (existsSync(join(dir, "package.json")) && !force) {
     throw new CliError(
       `${dir} already holds an app`,
-      before.manifest
+      writtenByLay(before.manifest)
         ? "makersclaw update lays this version over it"
         : "makersclaw init --force lays the template over it: fixed files and docs are replaced, your own files stay",
     );
@@ -293,7 +468,13 @@ export function init(dir, { template = "next", force = false } = {}) {
   if (before.manifest?.template && before.manifest.template !== template) {
     throw new CliError(`this app was laid from template "${before.manifest.template}", not "${template}"`, `makersclaw init --force -t ${before.manifest.template}`);
   }
-  return lay(dir, tpl, before);
+  // Decided before a file is written: a refused --tables or --mode leaves
+  // the app as it was. A new browser app's tables are own unless --tables
+  // says otherwise, and then it is refused.
+  const m = modeFor(before, askedMode);
+  const t = tablesFor(dir, before, tables ?? (m.key === "browser" ? "own" : undefined));
+  if (tables !== undefined) requireOwnTables(m.mode, t, "flags");
+  return lay(dir, tpl, before, { tables: t, mode: m.key });
 }
 
 /** `update [--major] [--adopt]` — this version's fixed files, docs and
@@ -330,6 +511,57 @@ export function update(dir, { major = false, adopt = false } = {}) {
   return lay(dir, tpl, before);
 }
 
+/** What an app's own code must change when it moves to a mode. The
+ *  template lays the fixed files; the surfaces are the app's, and move in
+ *  the same build (claw's STATIC-SPEC §3, "What the Builder is told"). */
+export const MODE_CHANGES = {
+  browser: [
+    'every surface a client component ("use client") that reads through the lib/data hooks (useRows, useRow, useCount, useCountBy, useActivity) and writes through lib/actions; a hook compares its options on every render (a time in filter or since to the minute), so anything else worked out per render (a Date.now() number) is worked out once, with useMemo',
+    "view state (?row=) from useSearchParams(): a browser app's page is a file built once and has no request, so a surface gets no searchParams",
+    "a write of more than one row is a function in the app's schema ((args jsonb) returns jsonb), called with runAction and named in references/actions.md",
+    'no server code of its own: no "use server" module, no route.js under app/, no proxy.js or middleware.js, no import of next/headers, next/cache, next/server, pg or lib/db',
+    "no export const dynamic, revalidate, fetchCache, runtime or dynamicParams in the app's own files",
+    "no process.env in the app's own code but CLAW_BASE_PATH, CLAW_PRODUCT and NEXT_PUBLIC_*: a prerendered page prints what it reads into a file anyone who opens the app can fetch",
+  ],
+  server: [
+    "lib/data.js is the server's again (pg, next/headers): a client surface takes its hooks from lib/door.js, or becomes a server component that calls loadRows",
+    "lib/actions.js is Server Actions again: a client surface calls them as it did",
+    "server code the app needs (a route handler, a Server Action of its own) may come back",
+  ],
+};
+
+/**
+ * `mode <browser|server>` — the one switch of an app's mode. It sets
+ * `mode` in makersclaw.json, lays that mode's fixed files, removes the
+ * other mode's (as update removes a retired file), and says what the
+ * app's own code must change. Browser needs `tables: "own"`: the door
+ * serves only an app's own schema. The app must be on this version, as
+ * for add: the switch lays this version's fixed files.
+ */
+export function mode(dir, to) {
+  if (to === undefined) throw new CliError("name a mode: browser or server", "makersclaw mode browser · makersclaw mode server");
+  if (!MODES.includes(to)) throw new CliError(`an app's mode is ${MODES.join(" or ")}, not "${to}"`, "server: a Next server in the workspace · browser: its code runs in the member's browser, and every read and write goes through the platform's data door");
+  const before = requireManifest(dir);
+  const { manifest } = before;
+  const v = version();
+  if (manifest.version !== v) {
+    throw new CliError(
+      `this app is on makersclaw ${manifest.version}; this is ${v}, and a switch of mode lays this version's fixed files`,
+      newer(manifest.version, v)
+        ? `npx makersclaw@${manifest.version} mode ${to}`
+        : compatible(manifest.version, v)
+          ? `makersclaw update first (${manifest.version} → ${v} is compatible), then mode ${to}`
+          : `makersclaw update --major first (makersclaw diff shows what changes), then mode ${to}`,
+    );
+  }
+  const tpl = loadTemplateOrFail(manifest.template);
+  // Not checked: a mode this CLI cannot read is what the switch mends.
+  const was = Object.hasOwn(manifest, "mode") ? manifest.mode : BASE_MODE;
+  requireOwnTables(to, manifest.tables, "switch");
+  const r = lay(dir, tpl, before, { mode: to });
+  return { ...r, was, changed: was !== to, change: MODE_CHANGES[to] };
+}
+
 function importFor(item) {
   if (item.type === "block") {
     const names = item.exports?.length ? item.exports.join(", ") : "…";
@@ -356,6 +588,9 @@ export function add(dir, names) {
   }
   const tpl = loadTemplateOrFail(manifest.template);
   const items = loadItems(tpl);
+  // A kit component is restored from the app's mode's copy of its file.
+  const appMode = modeOf(manifest);
+  const laid = new Map(modeFilesOrFail(tpl, appMode).map((f) => [f.path, f.from]));
   const order = [];
   const seen = new Set();
   const visit = (name, by) => {
@@ -380,7 +615,9 @@ export function add(dir, names) {
     const files = [];
     let changed = 0;
     for (const f of item.files) {
-      const bytes = readFileSync(f.from);
+      const from = item.type === "block" ? f.from : laid.get(f.to);
+      if (!from) throw new CliError(`${item.name}: ${f.to} is not laid in ${appMode} mode`);
+      const bytes = readFileSync(from);
       const hash = sha256(bytes);
       if (hashFile(join(dir, f.to)) !== hash) {
         writeFile(join(dir, f.to), bytes);
@@ -490,6 +727,8 @@ export function diff(dir) {
   const { manifest, pins } = requireManifest(dir);
   const tpl = loadTemplateOrFail(manifest.template);
   const v = version();
+  const appMode = modeOf(manifest);
+  const files = modeFilesOrFail(tpl, appMode);
   const entries = [];
   const statusOf = (path, have, want, pinned) => {
     if (have === want) return null;
@@ -498,12 +737,14 @@ export function diff(dir) {
     return "changed";
   };
 
-  for (const f of tpl.files) {
+  // The app's mode's files: update lays those, and removes a pinned file
+  // the mode does not lay ("dropped").
+  for (const f of files) {
     if (f.class !== "fixed" && f.class !== "docs") continue;
     const status = statusOf(f.path, hashFile(join(dir, f.path)), sha256(readFileSync(f.from)), f.class === "fixed" ? pins[f.path] : null);
     if (status) entries.push({ item: "template", path: f.path, status });
   }
-  const shipped = new Set(tpl.files.map((f) => f.path));
+  const shipped = new Set(files.map((f) => f.path));
   for (const p of Object.keys(pins)) {
     if (!p.startsWith(`${BLOCK_DIR}/`) && !shipped.has(p) && ownedPath(p, tpl)) entries.push({ item: "template", path: p, status: "dropped" });
   }
@@ -541,6 +782,7 @@ export function diff(dir) {
     from: manifest.version,
     to: v,
     compatible: compatible(manifest.version, v) && !newer(manifest.version, v),
+    mode: appMode,
     entries,
     package: pkg,
     blocks: manifest.blocks ?? {},

package/src/registry.mjs

@@ -56,6 +56,82 @@ export const FILE_CLASSES = ["fixed", "docs", "starter", "merged"];
 // Next 16 renamed proxy.js). `update` removes them from an app that has
 // them pinned; nothing lays them.
 
+/**
+ * The mode files/ is: a Next server in the workspace. Every other mode is
+ * files/ with some fixed files replaced and some left out (template.json
+ * `modes`), and an app says which in makersclaw.json `mode` (absent: this
+ * one). Browser mode (0.7.0, claw's STATIC-SPEC §3): the app's code runs
+ * in the member's browser, from files the platform serves, and every read
+ * and write goes through the platform's data door. So it lays no
+ * proxy.js, no /claw-alive, no pg (lib/db.js) and no server reads of the
+ * brain (lib/brain-server.js).
+ */
+export const BASE_MODE = "server";
+
+/**
+ * A mode's overlay and drop list, checked against the base's files. Pure:
+ * names in, the first thing wrong thrown, nothing returned. `base` is the
+ * base's files ({ path, class }), `overlay` the paths under the mode's
+ * overlay folder, `drop` the base paths the mode leaves out.
+ *   - No file is both dropped and overlaid: a mode lays a file or leaves
+ *     it out, never both.
+ *   - Each overlay file is a fixed file of the base. The overlay replaces
+ *     what the check pins (and update lays again); it adds no file, and
+ *     never a starter or a doc, which are the app's or read only.
+ *   - Each dropped file is a fixed file of the base: a drop the base does
+ *     not ship drops nothing, without a word, and only a pinned file is
+ *     the template's to remove from an app.
+ */
+export function checkMode(template, mode, { base, overlay, drop }) {
+  const fixed = new Set(base.filter((f) => f.class === "fixed").map((f) => f.path));
+  const dropped = new Set(drop);
+  for (const path of overlay) {
+    if (dropped.has(path)) throw new Error(`template ${template}: mode ${mode} both drops and overlays ${path} — a mode lays a file or leaves it out, not both`);
+    if (!fixed.has(path)) {
+      throw new Error(`template ${template}: mode ${mode} overlays ${path}, which is not a fixed file of files/ — an overlay replaces a fixed file and adds none`);
+    }
+  }
+  for (const path of drop) {
+    if (!fixed.has(path)) throw new Error(`template ${template}: mode ${mode} drops ${path}, which is not a fixed file of files/ — it would drop nothing`);
+  }
+}
+
+/** A mode's overlay folder: beside files/, a plain name. */
+const OVERLAY = /^[a-z]+$/;
+
+function loadModes(name, dir, meta, base) {
+  const modes = {};
+  for (const [mode, spec] of Object.entries(meta.modes ?? {})) {
+    if (!NAME.test(mode) || mode === BASE_MODE) throw new Error(`template ${name}: mode "${mode}" — ${BASE_MODE} is files/ itself, and a mode is named lowercase and dashed`);
+    const folder = spec?.overlay;
+    if (typeof folder !== "string" || !OVERLAY.test(folder) || folder === "files") {
+      throw new Error(`template ${name}: mode ${mode} names its overlay ${JSON.stringify(folder)} — a plain folder name beside files/`);
+    }
+    const root = join(dir, folder);
+    // A folder that is not there is an empty overlay: the mode only leaves
+    // files out. Browser mode's own files come after its drop list does.
+    const overlay = existsSync(root) ? walk(root) : [];
+    const drop = [...(spec.drop ?? [])];
+    checkMode(name, mode, { base, overlay, drop });
+    modes[mode] = { root, drop, files: overlay.map((path) => ({ path, class: "fixed", from: join(root, path) })) };
+  }
+  return modes;
+}
+
+/**
+ * The files a template lays in a mode: the base's, less the mode's drops,
+ * with the mode's copy in place of the base's where its overlay has one.
+ * The base mode is files/ as it is. null for a mode the template has not.
+ */
+export function modeFiles(template, mode = BASE_MODE) {
+  if (mode === BASE_MODE) return template.files;
+  const m = template.modes?.[mode];
+  if (!m) return null;
+  const over = new Map(m.files.map((f) => [f.path, f]));
+  const drop = new Set(m.drop);
+  return template.files.filter((f) => !drop.has(f.path)).map((f) => over.get(f.path) ?? f);
+}
+
 export function loadTemplate(name) {
   const dir = join(TEMPLATES, name);
   const meta = readJson(join(dir, "template.json"));
@@ -94,7 +170,8 @@ export function loadTemplate(name) {
   // The release lock (0.6.0 on): beside files/, never laid as it is. Each
   // app's pnpm-lock.yaml is cut from it (src/lockfile.mjs).
   const lock = existsSync(join(dir, RELEASE_LOCK)) ? join(dir, RELEASE_LOCK) : null;
-  return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components, retired, lock };
+  const modes = loadModes(name, dir, meta, files);
+  return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components, retired, lock, modes };
 }
 
 /** The release lock's file, in templates/<name>/: made by `npm run lock`

package/templates/next/browser/app/auto-refresh.jsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { useEffect } from "react";
+import { claw } from "../lib/claw";
+import { dataChanged, whenLanded } from "../lib/door";
+import { changeFeed, refreshLoop } from "./frame";
+
+// A browser app's auto-refresh (makersclaw.json "mode": "browser"). Rows
+// change under this page from outside it: the agent writes them while
+// the founder watches, and so do jobs and other members. The page is
+// files, so there is nothing to re-render from a server: the hooks that
+// read the rows (lib/data's useRows and the rest, lib/brain.js's) read
+// again, and only when the data door says something changed.
+//
+// The rules are app/frame.js's (refreshLoop, and the reasons with each),
+// the server app's every one:
+//
+//   - only while the tab is visible AND the App tab is on screen: no timer
+//     at all otherwise, and coming back asks at once;
+//   - only while someone is there: after 30 minutes with no key, pointer,
+//     touch, wheel or focus in the app it stops, and the next sign asks
+//     at once;
+//   - only while the founder is not typing and no dialog is open
+//     (isEditing), and never while a surface has opted out with
+//     data-claw-refresh="off" on its root;
+//   - one tick at a time, the next timed once the last has landed: the
+//     interval plus what the last one took.
+//
+// What a tick does is this mode's own (changeFeed):
+//
+//   - it asks GET _claw/data/changes?since=<cursor>. The first answer
+//     only sets the cursor and the stamp of the app's own tables; after
+//     it, a brain change or a different stamp is a change;
+//   - a change is dataChanged(), every hook on the page reading again,
+//     and the tick lands when whenLanded() says they all have their new
+//     rows. A read that fails keeps the rows it had;
+//   - never router.refresh(): under an export it fetches the same
+//     prebuilt payload. Never /claw-alive: nothing in the machine answers
+//     for a browser app, and the door is the platform's.
+//
+// The feed's first answer is asked as the page mounts, not at the first
+// tick. That answer only sets where the feed is, so a change between it
+// and the tick would never count: asked five seconds late, it would hide
+// every change made while the page opened. This sits ahead of the Shell
+// in the layout and React runs effects in that order, so the ask goes
+// out before the surfaces' first reads: a change made in between is read
+// twice, not missed.
+export default function AutoRefresh() {
+  useEffect(() => {
+    const feed = changeFeed((path, signal) => claw(path, { signal }));
+    feed.probe();
+    const loop = refreshLoop({
+      doc: document,
+      probe: feed.probe,
+      refresh: () => {
+        feed.covered();
+        dataChanged();
+        return whenLanded();
+      },
+    });
+    return () => {
+      loop.stop();
+      feed.stop();
+    };
+  }, []);
+  return null;
+}

package/templates/next/browser/app/layout.jsx

@@ -0,0 +1,94 @@
+import "./globals.css";
+import { Examples } from "../components/parts/fixture";
+import { surfaceNav } from "../surfaces";
+import AutoRefresh from "./auto-refresh";
+import ErrorRelay from "./error-relay";
+import EscapeRelay from "./escape-relay";
+import Shell from "./shell";
+
+// FIXED — the platform agent does not edit this file. Design lives in
+// app/shell.jsx and the surfaces; colour lives nowhere in the app.
+//
+// A browser app's layout (makersclaw.json "mode": "browser"). The app is
+// files: `next build` prerenders every page once, with `output: "export"`
+// (next.config.mjs), and the platform serves what it wrote. So nothing
+// here reads the request. There is no request: no headers(), no
+// cookies(), and no `dynamic` export, which an export refuses anyway.
+// Everything the server layout decides per request is decided here at
+// build, or in the browser.
+export const metadata = { title: process.env.CLAW_PRODUCT || "Artifact" };
+
+// The theme, decided in the browser before the body paints. It follows
+// the desk: the OS window opens the app with ?theme=light|dark, and the
+// product proxy keeps that query through its redirect and sets the
+// claw_theme cookie (Path=/, readable here) on the same answer, so every
+// later page reads the cookie. Dark when neither says: the desk is dark,
+// and so is the data-theme the build writes.
+//
+// Why there is no flash: an inline script in <head> runs while the HTML
+// is parsed, before anything paints, and _claw/theme.css after it still
+// blocks the first paint. suppressHydrationWarning on <html> covers the
+// one attribute React then finds changed. Anything that throws (a
+// browser with cookies off) leaves the build's dark.
+//
+// A plain string, not a function turned into one: what runs is exactly
+// what test/browser.test.mjs runs against a fake document.
+const THEME = `(function () {
+  try {
+    var d = document.documentElement;
+    var q = new URLSearchParams(location.search).get("theme");
+    var m = document.cookie.match(/(?:^|; )claw_theme=(light|dark)(?:;|$)/);
+    d.dataset.theme = q === "light" || q === "dark" ? q : m ? m[1] : "dark";
+  } catch (e) {}
+})();`;
+
+// <html> carries what the browser-side code reads: the base path for
+// lib/claw.js, the product name, the mode, the examples decision and
+// data-theme.
+//
+// The palette follows the WORKSPACE: <head> links `_claw/theme.css`, the
+// preset picked in System Settings → Appearance, served by the platform
+// with the page's own cookie as identity. app/globals.css holds the same
+// preset as defaults for a run with nothing serving it (a local `next
+// dev`, where the link 404s harmlessly). The href is prefixed by hand:
+// Next's basePath applies to next/link and assets, not to a literal
+// <link>.
+//
+// Examples (components/parts/fixture.jsx) are off inside a workspace, by
+// the server layout's own expression, read here at build: the platform
+// builds every browser app with its CLAW_ARTIFACT_ID, and its publish
+// refuses an export that says data-claw-examples="1". The store's own
+// loop builds without one, and shows its examples. The title and
+// data-claw-product are the name at build: a rename reaches them at the
+// next ship.
+export default function RootLayout({ children }) {
+  const basePath = process.env.CLAW_BASE_PATH || "";
+  const name = process.env.CLAW_PRODUCT || "Artifact";
+  const examples = process.env.CLAW_EXAMPLES === "1" || !process.env.CLAW_ARTIFACT_ID;
+  return (
+    <html
+      lang="en"
+      data-claw-base-path={basePath}
+      data-claw-product={name}
+      data-claw-mode="browser"
+      data-claw-examples={examples ? "1" : "0"}
+      data-theme="dark"
+      suppressHydrationWarning
+    >
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME }} />
+        <link rel="stylesheet" href={`${basePath}/_claw/theme.css`} />
+      </head>
+      <body>
+        <AutoRefresh />
+        <ErrorRelay />
+        <EscapeRelay />
+        <Examples allowed={examples}>
+          <Shell name={name} surfaces={surfaceNav()}>
+            {children}
+          </Shell>
+        </Examples>
+      </body>
+    </html>
+  );
+}