@aeratic/pagetailor 0.3.0 → 0.5.0

package/README.md

@@ -2,14 +2,56 @@
 
 Pages as data. Define your app's pages in YAML, bind them to a typed catalog of components and data sources, tailor them per role and per person with small patches, and let an AI agent compose them through a validation gate. Rendering is done by [json-render](https://github.com/vercel-labs/json-render).
 
-```
-npm init -y
+## Start here
+
+```bash
+# 1. Install and create the project
 npm install @aeratic/pagetailor react react-dom
 npx pagetailor init
+
+# 2. Check that everything fits together
 npx pagetailor validate
-npx pagetailor dev        # http://localhost:4747/?user=giulia&role=marketing
+
+# 3. Run the preview and the Studio
+npx pagetailor dev
+#   http://localhost:4747/?user=giulia&role=marketing   the page as Giulia sees it
+#   http://localhost:4747/?role=magazzino               the same page for the warehouse role
+#   http://localhost:4747/?view=studio                  visual editor of the whole project
+
+# 4. Enable the AI agent
+ANTHROPIC_API_KEY=sk-... npx pagetailor dev
+
+# 5. After editing components/registry.yaml, regenerate the component index
+npx pagetailor registry
 ```
 
+Three things to try in the first ten minutes:
+
+- **Change one user's layout.** Open `pagetailor/overrides/user-giulia.yaml`, move a row in `areas`, save: the browser reloads with her new page. Nobody else's page changes.
+- **Break something on purpose.** Put a data source that does not exist in `pages/home.yaml`. `validate` refuses it, and in the preview that widget becomes a red box with the reason while the rest of the page still renders.
+- **Ask the agent.** Type "put the KPI at the top" in the *Change this page…* box. The patch it writes is an ordinary override, checked by the same validator as your own edits.
+
+What pagetailor is not: a CMS, a page builder for end users, or an authenticated server. It is an engine for declarative pages with a gate that humans, the Studio and agents all go through. `pagetailor dev` writes project files over an unauthenticated API and binds to localhost only.
+
+## CLI
+
+| Command | What it does |
+| --- | --- |
+| `pagetailor init [--force]` | create `pagetailor/` with manifest, tokens, data catalog, a sample page, overrides and base components |
+| `pagetailor validate` | check manifest, pages and overrides against the component registry and the data catalog; exit 1 on problems |
+| `pagetailor registry` | write `pagetailor/components/index.js` exporting every component in `registry.yaml` |
+| `pagetailor dev [--port 4747] [--host 127.0.0.1]` | preview server with live reload and the Studio; pass `--host 0.0.0.0` to expose it |
+| `pagetailor help`, `pagetailor --version` | this text, the version |
+
+## Contents
+
+- [What `init` creates](#what-init-creates)
+- [A page](#a-page), [An override](#an-override), [The gate](#the-gate), [Component props](#component-props)
+- [Next.js](#nextjs), [Caching](#caching)
+- [Proposals and approval](#proposals-and-approval), [Reorder editor](#reorder-editor)
+- [The agent](#the-agent), [Pages as answers](#pages-as-answers)
+- [Studio](#studio), [Status](#status)
+
 ## What `init` creates
 
 ```
@@ -106,6 +148,8 @@ Changes go through `propose(root, { name, override, author, role })`, which firs
 - Each page lists the roles allowed to approve it in `manifest.yaml`: `owners: { home: [admin] }`.
 - `approve(root, { name, version, approver, approverRole })` re-runs the gate and commits a new applied version with `approvedFrom`; the proposal is marked `approved`. `reject(root, { name, version, approver, approverRole, reason })` marks it `rejected`. `listPending(root)` lists open proposals, newest first.
 
+Roles named in a proposal (the target role of a `role-*` override, the `role` of a user proposal, the `approverRole` of an approval) must exist in `manifest.roles`.
+
 Dev server routes: `POST /api/propose`, `GET /api/pending`, `POST /api/approve`, `POST /api/reject` (400 with `{ ok: false, errors }` when the gate or owner check fails). `POST /api/override` still commits directly.
 
 ## Reorder editor
@@ -127,10 +171,31 @@ A user asks in natural language ("put the KPI at the top"); the agent turns it i
 
 `complete` is any `async ({ system, user }) => text`, so any model or SDK works; pagetailor depends on none. `anthropicComplete({ apiKey, model })` is a built-in fetch call to the Anthropic Messages API (`claude-sonnet-5-5` by default).
 
-In `pagetailor dev`, set `ANTHROPIC_API_KEY` (and optionally `PAGETAILOR_MODEL`) and use the "Ask the agent…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 without the key). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
+In `pagetailor dev`, set `ANTHROPIC_API_KEY` (and optionally `PAGETAILOR_MODEL`) and use the "Change this page…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 without the key). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
+
+## Pages as answers
+
+A user asks a question ("how did sales go this week?") and the agent composes a brand-new page from the catalog instead of changing an existing one.
+
+1. `runAsk(root, { user, role, request, complete })` starts from an empty `layout/stack`, asks the model for `{ "title", "why", "patches" }` using only `insert` ops (cards, grids, widgets), applies them in memory and resolves the tree with `resolve(root, "answer", { user, role, tree })`. Gate or resolve errors are sent back once, like `runAgent`.
+2. The result (`{ title, why, tree, resolved }`) is rendered as is. Nothing is written to disk until the user decides.
+3. Keep as page: `keepAnswer(root, { user, role, title, tree, why })` writes `pages/<slug>.yaml` with `owner: <user>` and adds the slug to `manifest.pages` (slugs are made unique with `-2`, `-3`).
+4. Pin to home: `pinAnswer(root, { user, role, title, tree, why })` proposes, as `user-<user>`, an `insert` of a `layout/card` with the answer's widgets into the home's main container; on a grid it gets its own full-width row at the bottom. Same gate and proposal rules as any override.
+
+Both go through the gate with the user's role first. In `pagetailor dev` use the "Ask…" box: `POST /api/ask` `{ user, role, request }` (503 without `ANTHROPIC_API_KEY`), `POST /api/ask/keep` and `POST /api/ask/pin` with `{ user, role, title, tree, why }`.
+
+## Studio
+
+`pagetailor dev` has two views in the top bar: **Preview** (the app as rendered, with the editor and agent boxes) and **Studio**, a visual editor for the whole `pagetailor/` project (`http://localhost:4747/?view=studio`). The first tab, **App**, edits `manifest.yaml`: name, home, navigation position, pages (adding one creates `pages/<slug>.yaml` with an empty `layout/stack`; the home page cannot be removed), roles (a role still used as a page owner or by a data source cannot be removed) and page owners.
+
+The **Pages** tab edits `pages/<slug>.yaml`: a tree of the page's components (with the child name under a grid and the bound data source) and an inspector for the selected node. The component select lists every `name@version` in the registry (switching keeps the props the new schema still declares), props are form fields generated from the registry schema (free JSON when a component has none), the data select offers only the catalog sources whose type the component accepts, with their params. Containers can add, remove and reorder children; a grid renames and removes named children together with their cells in `areas`, and a new child gets a full-width row. The tree is validated live with the same `validateTree` as the server, so problems show before Save.
+
+The files stay the source of truth: each tab loads its file into a draft, the YAML pane at the bottom shows the draft as it will be written, and **Save** writes the file through the same validator as `pagetailor validate` (errors are shown in red and nothing is written; saving a page also re-applies every override that extends it, so renaming a child that an override targets is refused with the override's name). Saves rewrite the file keeping its top-level comments. Every save is versioned under `.history/files/<name>/NNNN.json` with the content before and after and a `why` (versions are allocated exclusively, so concurrent writers never collide); **Undo** restores the previous content as a new version. The **auto-save** checkbox saves 1.5 s after the last change.
+
+Routes: `GET /api/project`, `GET|PUT|DELETE /api/files/<name>`, `GET /api/files/<name>/history`, `POST /api/files/<name>/undo`, where `<name>` is `manifest`, `tokens`, `data-catalog`, `components/registry`, `pages/<slug>` or `overrides/<name>`. The same functions are exported: `readProjectFile`, `writeProjectFile`, `deleteProjectFile`, `listFileHistory`, `undoFile`, `scaffoldSource`, `scaffoldComponent`.
 
 ## Status
 
-0.3: engine, CLI (`init`, `validate`, `registry`, `dev`), history with rollback, proposals with owner approval, reorder editor, agent with a pluggable model adapter.
+0.4: engine, CLI (`init`, `validate`, `registry`, `dev`), history with rollback, proposals with owner approval, reorder editor, agent with a pluggable model adapter, pages as answers.
 
 License: MIT.

package/bin/cli.js

@@ -3,21 +3,28 @@ import { init } from "../src/init.js";
 import { validate } from "../src/validate.js";
 import { dev } from "../src/dev.js";
 import { writeRegistryFile } from "../src/registry-file.js";
+import { readFile } from "node:fs/promises";
 
 const [cmd, ...args] = process.argv.slice(2);
 const flag = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+const version = async () => JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
 const help = `pagetailor <command>
 
   init [--force]     create pagetailor/ with manifest, tokens, data catalog, a sample page, overrides and base components
   validate           check manifest, pages and overrides against the component registry and the data catalog
   registry          write pagetailor/components/index.js exporting every component in registry.yaml
-  dev [--port 4747]  preview server with live reload; ?page=home&user=giulia&role=marketing
+  dev [--port 4747] [--host 127.0.0.1]
+                    preview server with live reload (localhost only unless --host is given); ?page=home&user=giulia&role=marketing
+  help              this text
+  --version, -v     print the version
 `;
 
 try {
   if (cmd === "init") await init(process.cwd(), args);
   else if (cmd === "validate") process.exitCode = (await validate(process.cwd())) ? 0 : 1;
   else if (cmd === "registry") { const r = await writeRegistryFile(process.cwd()); console.log(`wrote ${r.path} (${r.count} components)`); }
-  else if (cmd === "dev") await dev(process.cwd(), { port: Number(flag("--port", 4747)) });
-  else { console.log(help); if (cmd && cmd !== "help") process.exitCode = 1; }
+  else if (cmd === "dev") await dev(process.cwd(), { port: Number(flag("--port", 4747)), host: flag("--host", "127.0.0.1") });
+  else if (cmd === "--version" || cmd === "-v" || cmd === "version") console.log(await version());
+  else if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") console.log(help);
+  else { console.error(`pagetailor: unknown command "${cmd}"\n`); console.log(help); process.exitCode = 1; }
 } catch (e) { console.error("pagetailor:", e.message); process.exitCode = 1; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Pages as data: declarative YAML pages, typed data catalog, per-user overrides, validated for AI agents. Renders with json-render.",
   "license": "MIT",
   "type": "module",

package/src/agent.js

@@ -1,8 +1,10 @@
 import { join } from "node:path";
-import { loadProject, loadPage, loadOverrides, loadYaml, exists } from "./loader.js";
+import { writeYaml } from "./yaml-write.js";
+import { loadProject, loadPage, loadOverrides, loadYaml, exists, listPages } from "./loader.js";
 import { applyOverride, mergePatch } from "./overrides.js";
-import { splitRef } from "./validator.js";
+import { splitRef, validateTree } from "./validator.js";
 import { propose } from "./proposals.js";
+import { resolve } from "./resolver.js";
 
 // The agent never writes files: it turns a request into override patches and hands them to propose().
 const OPS = [
@@ -56,22 +58,27 @@ export async function describePage(root, page, { user, role } = {}) {
   return `PAGE ${page} (user ${user ?? "none"}, role ${role ?? "none"})\n${lines.join("\n")}`;
 }
 
+const RULES = `- Use only the components, data sources and ops listed below; refs include the version (name@version).
+- Respect types: a component bound to data must accept the type the source returns. Use only params listed for a source.
+- Respect the role: never use a data source that is not listed (the role cannot read it).`;
+const GRID_RULE = "- A grid with areas must place every child exactly once";
+const reply = shape => `Answer ONLY with a JSON object, no prose:
+  ${shape}
+or, when the request cannot be satisfied with this catalog or this user's role:
+  { "refuse": string }`;
+const LANG = (...f) => `- Write ${f.map(x => `"${x}"`).join(", ")} (and "refuse") in the user's language.`;
+
 export async function buildAgentPrompt(root, { page, user, role, request }) {
   const project = await loadProject(root);
   const system = `You modify a declarative UI page for one user by writing override patches.
-Answer ONLY with a JSON object, no prose:
-  { "why": string, "patches": [ ...override ops... ] }
-or, when the request cannot be satisfied with this catalog or this user's role:
-  { "refuse": string }
+${reply('{ "why": string, "patches": [ ...override ops... ] }')}
 
 RULES
-- Use only the components, data sources and ops listed below; refs include the version (name@version).
-- Respect types: a component bound to data must accept the type the source returns. Use only params listed for a source.
-- Respect the role: never use a data source that is not listed (the role cannot read it).
+${RULES}
 - Targets are existing child names or component names from the current page.
-- A grid with areas must place every child exactly once: when you insert, remove or replace grid children, update areas too.
+${GRID_RULE}: when you insert, remove or replace grid children, update areas too.
 - Keep patches minimal: change only what the request asks for. Patches are appended to the user's existing ones.
-- Write "why" (and "refuse") in the user's language.
+${LANG("why")}
 
 ${describeCatalog(project, { role })}
 
@@ -79,6 +86,28 @@ CURRENT ${await describePage(root, page, { user, role })}`;
   return { system, user: request };
 }
 
+export const ANSWER_SKELETON = { ref: "layout/stack@1.0.0", children: [] };
+
+export async function buildAskPrompt(root, { user, role, request }) {
+  const project = await loadProject(root);
+  const system = `You answer a user's question by composing a brand-new UI page from a catalog of components and data sources.
+${reply('{ "title": string, "why": string, "patches": [ ...insert ops only... ] }')}
+
+RULES
+${RULES}
+- Use ONLY "insert" ops, onto the page's root layout/stack (target "layout/stack") or onto a layout/grid or layout/card you inserted.
+- Add a layout/card (with a title) or a layout/grid to group widgets as needed. To fill a grid, insert it with named children and areas in one node.
+${GRID_RULE}.
+- "title" names the page in a few words; "why" says briefly how the page answers the question.
+${LANG("title", "why")}
+
+${describeCatalog(project, { role })}
+
+CURRENT PAGE answer (empty, user ${user ?? "none"}, role ${role ?? "none"})
+layout/stack: layout/stack@1.0.0`;
+  return { system, user: request };
+}
+
 export function parseAgentReply(text) {
   const s = String(text ?? "");
   const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
@@ -121,3 +150,70 @@ export async function runAgent(root, { page, user, role, request, complete }) {
     reply = undefined; errors = [];
   }
 }
+
+// Pages as answers: compose a page in memory; nothing is written until keepAnswer or pinAnswer.
+export async function runAsk(root, { user, role, request, complete }) {
+  const prompt = await buildAskPrompt(root, { user, role, request });
+  let message = prompt.user, reply, errors = [];
+  for (let attempts = 1; attempts <= 2; attempts++) {
+    const text = await complete({ system: prompt.system, user: message });
+    try { reply = parseAgentReply(text); } catch (e) { errors = [e.message]; }
+    if (reply?.refuse) return { ok: false, refuse: reply.refuse, reply, attempts };
+    if (reply && !errors.length) {
+      if (!Array.isArray(reply.patches)) errors = ["reply has no patches array"];
+      else if (reply.patches.some(p => p?.op !== "insert")) errors = ["only insert ops are allowed"];
+      else {
+        const r = applyOverride(ANSWER_SKELETON, { name: "answer", patches: reply.patches });
+        const resolved = await resolve(root, "answer", { user, role, tree: r.tree });
+        errors = [...r.errors, ...resolved.errors].map(e => `${e.path}: ${e.message}`);
+        if (!errors.length) return { ok: true, title: reply.title ?? "Answer", why: reply.why, tree: r.tree, resolved: { spec: resolved.spec, errors: resolved.errors }, attempts };
+      }
+    }
+    if (attempts === 2) return { ok: false, errors, reply, attempts };
+    message = `${prompt.user}\n\nThe previous page was rejected: ${errors.join("; ")}. Fix it.`;
+    reply = undefined; errors = [];
+  }
+}
+
+const slugify = s => String(s ?? "").normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "answer";
+
+export async function keepAnswer(root, { user, role, title, tree, why }) {
+  const project = await loadProject(root);
+  const errors = validateTree(tree, project, { role: role ?? null });
+  if (errors.length) return { ok: false, errors: errors.map(e => `${e.path}: ${e.message}`) };
+  const taken = new Set([...(await listPages(root)), ...(project.manifest.pages ?? [])]);
+  const base = slugify(title); let slug = base;
+  for (let n = 2; taken.has(slug); n++) slug = `${base}-${n}`;
+  await writeYaml(join(root, "pages", `${slug}.yaml`), { page: slug, title, owner: user, ...(why ? { why } : {}), layout: tree });
+  const mfile = join(root, "manifest.yaml");
+  const manifest = (await loadYaml(mfile)) ?? {};
+  await writeYaml(mfile, { ...manifest, pages: [...(manifest.pages ?? []), slug] });
+  return { ok: true, page: slug };
+}
+
+// The home's main container: the root, or the single grid it wraps.
+function mainContainer(tree) {
+  let node = tree;
+  while (Array.isArray(node.children) && node.children.length === 1 && node.children[0]?.children && !Array.isArray(node.children[0].children)) node = node.children[0];
+  return node;
+}
+
+export async function pinAnswer(root, { user, role, page, title, tree, why }) {
+  if (!user) return { ok: false, errors: ["user is required"] };
+  page ??= (await loadProject(root)).manifest.home;
+  const name = `user-${user}`;
+  const file = join(root, "overrides", `${name}.yaml`);
+  const existing = await exists(file) ? (await loadYaml(file)) ?? {} : {};
+  const base = existing.extends === page ? existing.patches ?? [] : [];
+  const target = mainContainer(await currentTree(root, page, { user, role }));
+  const card = { ref: "layout/card@1.0.0", props: { title: title ?? "Answer" }, children: structuredClone(tree.children ?? []) };
+  const insert = { op: "insert", target: splitRef(target.ref)[0], node: card };
+  if (target.children && !Array.isArray(target.children)) {
+    let n = 1; while (`answer-${n}` in target.children) n++;
+    insert.name = `answer-${n}`;
+    const areas = String(target.props?.areas ?? "").trimEnd();
+    const cols = areas ? areas.split("\n")[0].trim().split(/\s+/).length : 1;
+    insert.area = `${areas ? areas + "\n" : ""}${Array(cols).fill(insert.name).join(" ")}\n`;
+  }
+  return propose(root, { name, author: user, role, override: { extends: page, why: why ?? `pinned: ${title ?? "answer"}`, patches: mergePatch(base, insert) } });
+}

package/src/dev.js

@@ -9,12 +9,14 @@ import { loadProject, loadYaml, listPages } from "./loader.js";
 import { commitOverride, listHistory, rollback } from "./history.js";
 import { propose, listPending, approve, reject } from "./proposals.js";
 import { tokensToCss } from "./tokens.js";
-import { buildAgentPrompt, runAgent } from "./agent.js";
+import { buildAgentPrompt, runAgent, runAsk, keepAnswer, pinAnswer } from "./agent.js";
 import { anthropicComplete } from "./llm.js";
+import { isProjectFile, readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, readProject, scaffoldSource, scaffoldComponent } from "./files.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
-export async function dev(cwd, { port = 4747 } = {}) {
+// Binds to localhost only: the API writes project files and has no authentication. Pass host to expose it.
+export async function dev(cwd, { port = 4747, host = "127.0.0.1" } = {}) {
   const root = join(cwd, "pagetailor");
   // Bundle one React only: the project's if installed, otherwise the one shipped with this package.
   const reqProject = createRequire(join(cwd, "package.json")), reqSelf = createRequire(import.meta.url);
@@ -26,67 +28,28 @@ export async function dev(cwd, { port = 4747 } = {}) {
   alias["@aeratic/pagetailor/client"] = join(here, "client.jsx");
   const nodePaths = [join(cwd, "node_modules"), join(here, "..", "node_modules")];
 
-  // one generated entry: imports every component from registry.yaml, mounts <Page>
-  const entry = async () => {
-    const reg = await loadYaml(join(root, "components", "registry.yaml"));
-    const imports = [], map = [];
-    let i = 0;
-    for (const [name, def] of Object.entries(reg)) for (const [ver, v] of Object.entries(def.versions ?? {})) {
-      if (!v.impl) continue; const id = `C${i++}`;
-      imports.push(`import ${id} from ${JSON.stringify(v.impl)};`);
-      map.push(`${JSON.stringify(`${name}@${ver}`)}: ${id}`);
-    }
-    return `${imports.join("\n")}
-import { createRoot } from "react-dom/client";
-import { useCallback, useEffect, useState } from "react";
-import { Page, EditorContext, useEditor } from ${JSON.stringify(join(here, "client.jsx"))};
-const registry = { ${map.join(", ")} };
-function App() {
-  const q = new URLSearchParams(location.search);
-  const [page, setPage] = useState(q.get("page") || "__home__");
-  const [user, setUser] = useState(q.get("user") || "");
-  const [role, setRole] = useState(q.get("role") || "");
-  const [state, setState] = useState(null);
-  const load = useCallback(() => fetch(\`/api/page/\${page}?user=\${user}&role=\${role}\`).then(r => r.json()).then(setState), [page, user, role]);
-  useEffect(() => { load(); }, [load]);
-  // keep page/user/role in the URL: the file watcher reloads the tab after an override is written
-  useEffect(() => { const u = new URLSearchParams({ page, user, role }); history.replaceState(null, "", "?" + u); }, [page, user, role]);
-  const editor = useEditor({ page: state?.page, user, role, why: "reordered in the editor", onApplied: r => { if (!r.pending) load(); } });
-  const [ask, setAsk] = useState(""), [agent, setAgent] = useState(null);
-  const sendAsk = async e => {
-    e.preventDefault(); if (!ask.trim()) return;
-    setAgent({ text: "thinking…" });
-    try {
-      const r = await (await fetch("/api/agent", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ page: state.page, user, role: role || undefined, request: ask }) })).json();
-      if (r.ok) setAgent({ text: (r.proposal.pending ? "sent for approval: " : "applied: ") + (r.reply.why ?? "") });
-      else setAgent({ error: true, text: r.refuse ?? (r.errors ?? [r.error ?? "agent failed"]).join("; ") });
-    } catch (err) { setAgent({ error: true, text: err.message }); }
-  };
-  useEffect(() => { const es = new EventSource("/events"); es.onmessage = () => location.reload(); return () => es.close(); }, []);
-  if (!state) return null;
-  const pages = state.manifest.pages, roles = state.manifest.roles ?? [];
-  return <>
-    <header style={{ display: "flex", gap: 12, alignItems: "center", padding: "10px 16px", borderBottom: "1px solid var(--pt-color-border)", background: "var(--pt-color-surface)", fontSize: 13 }}>
-      <strong>{state.manifest.app}</strong>
-      <label>page <select value={state.page} onChange={e => setPage(e.target.value)}>{pages.map(p => <option key={p}>{p}</option>)}</select></label>
-      <label>user <input value={user} placeholder="giulia" onChange={e => setUser(e.target.value)} style={{ width: 90 }} /></label>
-      <label>role <select value={role} onChange={e => setRole(e.target.value)}><option value="">(none)</option>{roles.map(r => <option key={r}>{r}</option>)}</select></label>
-      <button onClick={() => editor.setEditing(!editor.editing)} style={{ fontWeight: editor.editing ? 700 : 400 }}>{editor.editing ? "Done editing" : "Edit layout"}</button>
-      {editor.status === "saving" && <span>saving…</span>}
-      {editor.status === "pending" && <span>sent for approval</span>}
-      {editor.status === "error" && <span style={{ color: "var(--pt-color-danger)" }}>{editor.errors.join("; ")}</span>}
-      <form onSubmit={sendAsk} style={{ display: "flex", gap: 6 }}><input value={ask} placeholder="Ask the agent…" onChange={e => setAsk(e.target.value)} style={{ width: 220 }} /><button type="submit">Ask</button></form>
-      {agent && <span style={{ color: agent.error ? "var(--pt-color-danger)" : undefined }}>{agent.text}</span>}
-      {state.errors.length > 0 && <span style={{ color: "var(--pt-color-danger)" }}>{state.errors.length} problem(s), see console</span>}
-    </header>
-    <main style={{ padding: 16, maxWidth: 1100, margin: "0 auto" }}><EditorContext.Provider value={{ editing: editor.editing, propose: editor.propose }}><Page resolved={state} registry={registry} /></EditorContext.Provider></main>
-  </>;
-}
-createRoot(document.getElementById("root")).render(<App />);`;
+  // the Studio entry imports the project's components through a virtual module built from registry.yaml,
+  // regenerated on every rebuild
+  const registryPlugin = {
+    name: "pagetailor-registry",
+    setup(build) {
+      build.onResolve({ filter: /^pagetailor:registry$/ }, () => ({ path: "registry", namespace: "pagetailor" }));
+      build.onLoad({ filter: /.*/, namespace: "pagetailor" }, async () => {
+        const reg = await loadYaml(join(root, "components", "registry.yaml"));
+        const imports = [], map = [];
+        let i = 0;
+        for (const [name, def] of Object.entries(reg ?? {})) for (const [ver, v] of Object.entries(def.versions ?? {})) {
+          if (!v.impl) continue; const id = `C${i++}`;
+          imports.push(`import ${id} from ${JSON.stringify(v.impl)};`);
+          map.push(`${JSON.stringify(`${name}@${ver}`)}: ${id}`);
+        }
+        return { contents: `${imports.join("\n")}\nexport const registry = { ${map.join(", ")} };\n`, resolveDir: join(root, "components"), loader: "jsx" };
+      });
+    },
   };
 
   const ctx = await esbuild.context({
-    stdin: { contents: await entry(), resolveDir: join(root, "components"), loader: "jsx", sourcefile: "pagetailor-entry.jsx" },
+    entryPoints: [join(here, "studio", "entry.jsx")], plugins: [registryPlugin],
     bundle: true, write: false, format: "esm", jsx: "automatic", alias, nodePaths, outfile: "bundle.js", sourcemap: "inline", logLevel: "silent",
     define: { "process.env.NODE_ENV": '"development"' },
   });
@@ -144,6 +107,30 @@ createRoot(document.getElementById("root")).render(<App />);`;
         const r = await runAgent(root, { page: b.page, user: b.user, role: b.role || undefined, request: b.request, complete });
         return json(res, r.ok ? 200 : 400, r);
       }
+      if (url.pathname === "/api/ask" && req.method === "POST") {
+        if (!process.env.ANTHROPIC_API_KEY) return json(res, 503, { error: "set ANTHROPIC_API_KEY to use the agent" });
+        const b = await body(req);
+        const complete = anthropicComplete({ apiKey: process.env.ANTHROPIC_API_KEY, ...(process.env.PAGETAILOR_MODEL ? { model: process.env.PAGETAILOR_MODEL } : {}) });
+        const r = await runAsk(root, { user: b.user || undefined, role: b.role || undefined, request: b.request, complete });
+        return json(res, r.ok ? 200 : 400, r);
+      }
+      const answer = { "/api/ask/keep": keepAnswer, "/api/ask/pin": pinAnswer }[url.pathname];
+      if (answer && req.method === "POST") { const b = await body(req); const r = await answer(root, { ...b, user: b.user || undefined, role: b.role || undefined }); return json(res, r.ok ? 200 : 400, r); }
+      if (url.pathname === "/api/project" && req.method === "GET") return json(res, 200, await readProject(root));
+      if (url.pathname.startsWith("/api/files/")) {
+        let name = decodeURIComponent(url.pathname.slice(11)), action = null;
+        const m = /^(.+)\/(history|undo)$/.exec(name);
+        if (m && isProjectFile(m[1])) { name = m[1]; action = m[2]; }
+        if (!isProjectFile(name)) return json(res, 400, { ok: false, errors: [`not a project file: ${name}`] });
+        if (action === "history" && req.method === "GET") return json(res, 200, await listFileHistory(root, name));
+        if (action === "undo" && req.method === "POST") { const r = await undoFile(root, name, { author: "studio" }); return json(res, r.ok ? 200 : 400, r); }
+        if (!action && req.method === "GET") return json(res, 200, { name, value: await readProjectFile(root, name) });
+        if (!action && req.method === "PUT") { const b = await body(req); const r = await writeProjectFile(root, name, b.value, { author: b.author ?? "studio", why: b.why ?? "edited in studio" }); return json(res, r.ok ? 200 : 400, r); }
+        if (!action && req.method === "DELETE") { const r = await deleteProjectFile(root, name, { author: "studio" }); return json(res, r.ok ? 200 : 400, r); }
+        return json(res, 405, { ok: false, errors: ["method not allowed"] });
+      }
+      if (url.pathname === "/api/scaffold/source" && req.method === "POST") { const b = await body(req); return json(res, 200, await scaffoldSource(root, b.name)); }
+      if (url.pathname === "/api/scaffold/component" && req.method === "POST") { const b = await body(req); return json(res, 200, await scaffoldComponent(root, b.name, { props: b.props, container: b.container })); }
       if (url.pathname === "/api/pending") return json(res, 200, await listPending(root));
       const flow = { "/api/propose": propose, "/api/approve": approve, "/api/reject": reject }[url.pathname];
       if (flow && req.method === "POST") { const r = await flow(root, await body(req)); return json(res, r.ok ? 200 : 400, r); }
@@ -156,7 +143,7 @@ createRoot(document.getElementById("root")).render(<App />);`;
     console.error(`pagetailor: port ${port} is already in use (try --port ${port + 1})`);
     process.exit(1);
   });
-  await new Promise(r => server.listen(port, r));
-  console.log(`pagetailor dev  http://localhost:${port}\n  pages from ${root}\n  ?page=home&user=giulia&role=marketing`);
+  await new Promise(r => server.listen(port, host, r));
+  console.log(`pagetailor dev  http://${host === "0.0.0.0" || host === "::" ? "localhost" : host}:${port}\n  pages from ${root}\n  ?page=home&user=giulia&role=marketing`);
   return server;
 }

package/src/files.js

@@ -0,0 +1,157 @@
+import { mkdir, readdir, readFile, writeFile, rm } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse } from "yaml";
+import { toYaml, writeYaml, appendVersion } from "./yaml-write.js";
+export { toYaml };
+import { loadProject, listPages, listOverrides, exists, forgetYaml } from "./loader.js";
+import { validateTree, validateManifest } from "./validator.js";
+import { clearResolveCache } from "./resolver.js";
+import { applyOverride } from "./overrides.js";
+
+// The YAML files of a project, read and written as plain objects; every write is versioned
+// under .history/files/<name with / as __>/NNNN.json with the previous and the new content.
+const FIXED = { manifest: "manifest.yaml", tokens: "tokens.yaml", "data-catalog": "data-catalog.yaml", "components/registry": "components/registry.yaml" };
+const SLUG = /^[a-z0-9-]+$/;
+const msg = e => typeof e === "string" ? e : `${e.path}: ${e.message}`;
+
+export function isProjectFile(name) {
+  if (typeof name !== "string") return false;
+  if (FIXED[name]) return true;
+  const [dir, slug, extra] = name.split("/");
+  return (dir === "pages" || dir === "overrides") && extra === undefined && SLUG.test(slug ?? "");
+}
+const pathOf = (root, name) => {
+  if (!isProjectFile(name)) throw new Error(`not a project file: ${name}`);
+  return join(root, FIXED[name] ?? `${name}.yaml`);
+};
+const historyDir = (root, name) => join(root, ".history", "files", name.replace("/", "__"));
+
+export async function readProjectFile(root, name) {
+  const p = pathOf(root, name);
+  if (!(await exists(p))) return null;
+  return parse(await readFile(p, "utf8")) ?? null;
+}
+
+async function validateFile(root, name, value) {
+  if (name === "tokens") return [];
+  if (!value || typeof value !== "object") return [`${name}: content must be an object`];
+  const project = await loadProject(root);
+  const pages = await listPages(root);
+  if (name === "manifest") return validateManifest(value, pages).map(msg);
+  if (name.startsWith("pages/")) {
+    if (!value.layout) return [`${name}: layout is required`];
+    const errors = validateTree(value.layout, project).map(msg);
+    // the overrides extending this page must still apply: a renamed child would break them silently
+    for (const ov of await listOverrides(root)) {
+      const o = await readProjectFile(root, `overrides/${ov}`);
+      if (!o || (o.extends && o.extends !== name.slice(6))) continue;
+      const r = applyOverride(value.layout, { name: ov, ...o });
+      for (const e of [...r.errors, ...validateTree(r.tree, project, ov.startsWith("role-") ? { role: ov.slice(5) } : {})]) errors.push(`overrides/${ov}: ${msg(e)}`);
+    }
+    return errors;
+  }
+  if (name.startsWith("overrides/")) {
+    // same check as the proposals gate; a role override is validated for its role, a user override with no role
+    const ov = name.slice(10);
+    if (!value.extends) return ["override.extends is required"];
+    const page = await readProjectFile(root, `pages/${value.extends}`);
+    if (!page) return [`page "${value.extends}" not found`];
+    const r = applyOverride(page.layout, { name: ov, ...value });
+    return [...r.errors, ...validateTree(r.tree, project, ov.startsWith("role-") ? { role: ov.slice(5) } : {})].map(msg);
+  }
+  // registry or catalog: every page must still validate against the new version
+  const next = { ...project, ...(name === "data-catalog" ? { catalog: value } : { registry: value }) };
+  const errors = [];
+  for (const page of pages) {
+    const doc = await readProjectFile(root, `pages/${page}`);
+    for (const e of validateTree(doc?.layout, next)) errors.push(`pages/${page} ${msg(e)}`);
+  }
+  return errors;
+}
+
+async function record(root, name, before, after, { author = "studio", why = "" } = {}) {
+  return appendVersion(historyDir(root, name), version => ({ version, at: new Date().toISOString(), author, why, before, after }));
+}
+
+async function put(root, name, value) {
+  const p = pathOf(root, name);
+  if (value === null) await rm(p, { force: true });
+  else { await mkdir(dirname(p), { recursive: true }); await writeYaml(p, value); }
+  forgetYaml(p); clearResolveCache();
+}
+
+export async function writeProjectFile(root, name, value, { author, why, skipValidation = false } = {}) {
+  if (!isProjectFile(name)) return { ok: false, errors: [`not a project file: ${name}`] };
+  const errors = skipValidation ? [] : await validateFile(root, name, value);
+  if (errors.length) return { ok: false, errors };
+  const before = await readProjectFile(root, name);
+  await put(root, name, value);
+  return { ok: true, entry: await record(root, name, before, value, { author, why }) };
+}
+
+export async function deleteProjectFile(root, name, { author, why = "deleted" } = {}) {
+  if (!isProjectFile(name) || !/^(pages|overrides)\//.test(name)) return { ok: false, errors: [`${name} cannot be deleted`] };
+  const before = await readProjectFile(root, name);
+  if (before === null) return { ok: false, errors: [`${name} does not exist`] };
+  if (name.startsWith("pages/") && (await loadProject(root)).manifest.home === name.slice(6))
+    return { ok: false, errors: [`${name.slice(6)} is the home page`] };
+  await put(root, name, null);
+  return { ok: true, entry: await record(root, name, before, null, { author, why }) };
+}
+
+export async function listFileHistory(root, name) {
+  if (!isProjectFile(name)) return [];
+  const dir = historyDir(root, name);
+  let files = []; try { files = (await readdir(dir)).filter(f => f.endsWith(".json")); } catch { return []; }
+  const all = await Promise.all(files.map(async f => JSON.parse(await readFile(join(dir, f), "utf8"))));
+  return all.sort((a, b) => b.version - a.version);
+}
+
+// Restores the content before the latest version; the restore itself is a new version.
+export async function undoFile(root, name, { author } = {}) {
+  const [last] = await listFileHistory(root, name);
+  if (!last) return { ok: false, errors: [`${name} has no history`] };
+  const current = await readProjectFile(root, name);
+  await put(root, name, last.before);
+  return { ok: true, value: last.before, entry: await record(root, name, current, last.before, { author, why: "undo" }) };
+}
+
+// Adds a stub implementation to data/sources.mjs, before the closing `};` of the default export.
+export async function scaffoldSource(root, name) {
+  const p = join(root, "data", "sources.mjs");
+  let src = (await exists(p)) ? await readFile(p, "utf8") : "export default {\n};\n";
+  if (src.includes(JSON.stringify(name))) return { created: false, path: p };
+  const at = src.lastIndexOf("};");
+  if (at < 0) throw new Error("data/sources.mjs: cannot find the end of the default export");
+  const stub = `  ${JSON.stringify(name)}: async (params, { user, role }) => { /* TODO: query */ return null; },\n`;
+  src = src.slice(0, at) + stub + src.slice(at);
+  await mkdir(dirname(p), { recursive: true }); await writeFile(p, src);
+  clearResolveCache();
+  return { created: true, path: p };
+}
+
+export const pascalName = name => String(name).split(/[^a-zA-Z0-9]+/).filter(Boolean).map(s => s[0].toUpperCase() + s.slice(1)).join("");
+
+// Creates components/<PascalName>.jsx reading the declared props; never overwrites.
+export async function scaffoldComponent(root, name, { props = {}, container = false } = {}) {
+  const file = `${pascalName(name)}.jsx`, p = join(root, "components", file);
+  if (await exists(p)) return { created: false, path: p, impl: `./${file}` };
+  const keys = Object.keys(props ?? {}).filter(k => /^[A-Za-z_$][\w$]*$/.test(k));
+  const read = keys.length ? `  const { ${keys.join(", ")} } = props;\n` : "";
+  const show = keys.map(k => `      <div><strong>${k}</strong>: {String(${k} ?? "")}</div>\n`).join("");
+  const src = `// ${name}: generated by pagetailor studio, edit freely.
+export default function ${pascalName(name)}({ props, children }) {
+${read}  return (
+    <div style={{ padding: "var(--pt-spacing-md)", border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)" }}>
+${show}${container ? "      {children}\n" : "      {props.data !== undefined && <pre style={{ margin: 0, fontSize: 12 }}>{JSON.stringify(props.data, null, 2)}</pre>}\n"}    </div>
+  );
+}
+`;
+  await mkdir(dirname(p), { recursive: true }); await writeFile(p, src);
+  return { created: true, path: p, impl: `./${file}` };
+}
+
+export async function readProject(root) {
+  const [project, pages, overrides] = await Promise.all([loadProject(root), listPages(root), listOverrides(root)]);
+  return { manifest: project.manifest, tokens: project.tokens, catalog: project.catalog, registry: project.registry, pages, overrides };
+}

package/src/history.js

@@ -1,18 +1,14 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { stringify } from "yaml";
+import { writeYaml, appendVersion, pad } from "./yaml-write.js";
 
 // Every write to an override is a new numbered version under .history/<name>/NNNN.json.
 // The current override file is rewritten from the version being committed.
 const dirOf = (root, name) => join(root, ".history", name);
-const pad = n => String(n).padStart(4, "0");
 
 export async function commitOverride(root, name, override, { author = "system", status = "applied" } = {}) {
-  const dir = dirOf(root, name); await mkdir(dir, { recursive: true });
-  const n = (await readdir(dir)).length + 1;
-  const entry = { version: n, at: new Date().toISOString(), author, status, override };
-  await writeFile(join(dir, `${pad(n)}.json`), JSON.stringify(entry, null, 2));
-  if (status === "applied") await writeFile(join(root, "overrides", `${name}.yaml`), stringify(override));
+  const entry = await appendVersion(dirOf(root, name), version => ({ version, at: new Date().toISOString(), author, status, override }));
+  if (status === "applied") await writeYaml(join(root, "overrides", `${name}.yaml`), override);
   return entry;
 }