@aeratic/pagetailor 0.1.0 → 0.3.0

package/README.md

@@ -58,18 +58,79 @@ Ops: `set-areas`, `set-props`, `set-data`, `replace`, `remove`, `insert`, `move`
 
 ## The gate
 
-Every page, override and agent proposal goes through the same validator: the component exists with that version, the data source exists, the user's role may read it, the source's returned type is accepted by the component, params are allowed, grid areas and children match. An invalid node renders as a fallback box with the reason; the rest of the page renders.
+Every page, override and agent proposal goes through the same validator: the component exists with that version, the data source exists, the user's role may read it, the source's returned type is accepted by the component, params are allowed, props match the component schema, grid areas and children match. An invalid node renders as a fallback box with the reason; the rest of the page renders.
 
-## In your own server
+## Component props
+
+Each entry in `components/registry.yaml` can declare a `props:` schema. Types: `string`, `number`, `boolean`, `text` (multiline string), `enum[a,b,c]`, `string[]`, `number[]`; a trailing `?` makes a prop optional. Undeclared props, missing required props, wrong types and values outside an enum are errors. Entries without `props:` accept anything; `data` and `names` are injected by the resolver and never checked. Containers set `container: true`.
+
+```yaml
+layout/card:
+  description: Card with an optional title wrapping its children
+  container: true
+  props: { title: string?, tone: "enum[info,warn]?" }
+  versions: { "1.0.0": { impl: ./Card.jsx } }
+```
+
+`buildCatalog(registry, z)` turns the registry into a json-render catalog (Zod props, `slots: ["default"]` on containers) for `defineCatalog(schema, ...)`.
+
+## Next.js
+
+Full example in [`examples/nextjs`](examples/nextjs). Add `transpilePackages: ["@aeratic/pagetailor"]` to `next.config.js` and run `npx pagetailor registry` to generate `pagetailor/components/index.js` (rerun it when `registry.yaml` changes).
 
 ```js
-import { resolve, commitOverride, listHistory, rollback } from "@aeratic/pagetailor";
-const { spec, errors } = await resolve("./pagetailor", "home", { user: "giulia", role: "marketing" });
-// send `spec` to the browser and render it with <Page resolved={...} registry={...}/> from "@aeratic/pagetailor/client"
+// app/api/page/[page]/route.js  (server only)
+import { join } from "node:path";
+import { resolve } from "@aeratic/pagetailor";
+export async function GET(req, { params }) {
+  const q = req.nextUrl.searchParams, { page } = await params;
+  return Response.json({ page, ...(await resolve(join(process.cwd(), "pagetailor"), page, { user: q.get("user"), role: q.get("role") })) });
+}
+
+// app/PageClient.jsx  ("use client": import only from /client, never the package root)
+import { Page } from "@aeratic/pagetailor/client";
+import { registry } from "../pagetailor/components/index.js";
+// fetch(`/api/page/home?user=giulia&role=marketing`) then <Page resolved={json} registry={registry} />
 ```
 
+## Caching
+
+`resolve` keeps resolved pages in memory per page/user/role and returns them without calling data sources again while the project files involved are unchanged. Pass `{ fresh: true }` to bypass it, or `{ maxAge: ms }` to expire entries (default 0, no time limit; `pagetailor dev` uses 2000). `clearResolveCache()` empties it.
+
+## Proposals and approval
+
+Changes go through `propose(root, { name, override, author, role })`, which first runs the gate: the override is applied to its page (`extends` is required) and validated for the role it targets. A failing gate returns `{ ok: false, errors }` and records nothing.
+
+- A user's own override (`user-ann` proposed by `ann`) is applied immediately.
+- Anything shared (a `role-*` override, or another user's override) is stored as `pending` and the override file is left untouched.
+- 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.
+
+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
+
+In `pagetailor dev`, set a user, then click **Edit layout** in the header: the cells of every `layout/grid` get a dashed outline and become draggable. Drop one cell on another to swap their area names (all occurrences of both) in `areas`.
+
+Each drop sends a `set-areas` patch through `POST /api/propose` as `user-<user>` (author = that user, `why: "reordered in the editor"`), merged into that user's existing override: an earlier `set-areas` on the same grid is replaced, other patches are kept. The user's own override applies at once and the page re-fetches; gate errors are shown in red.
+
+In your own app wrap `<Page>` in `<EditorContext.Provider value={{ editing, propose }}>` with values from `useEditor({ page, user, role, why, onApplied })` (all from `@aeratic/pagetailor/client`); the base Grid uses `EditableGrid` and renders as usual outside editing. The resolver adds a hidden `__pt: { path, name, container }` prop to every element for this mapping. This first version only swaps whole cells; resizing and moving across grids are not supported yet.
+
+## The agent
+
+A user asks in natural language ("put the KPI at the top"); the agent turns it into override patches that go through the same gate as everything else. It never writes files itself.
+
+1. `buildAgentPrompt(root, { page, user, role, request })` returns `{ system, user }`: the rules, the catalog visible to that role (`describeCatalog`: components with props and accepted type, readable data sources, the op vocabulary) and the current page for that user (`describePage`: the resolved tree with child names and grid areas).
+2. The model answers with JSON only: `{ "why", "patches": [...] }`, or `{ "refuse" }` when the catalog or the role cannot satisfy the request. `parseAgentReply` tolerates code fences and surrounding prose.
+3. `runAgent(root, { page, user, role, request, complete })` appends the patches to the user's existing override for that page (same merge rule as the editor) and calls `propose` as `user-<user>`: applied at once for the own user, pending otherwise.
+4. If the gate rejects, the gate errors are sent back once ("The previous patch was rejected: ... Fix it.") and the result is proposed again. The result reports `attempts`.
+
+`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.
+
 ## Status
 
-0.1: engine, CLI (`init`, `validate`, `dev`), history with rollback. Next: proposal/approval flow for shared pages and an agent endpoint.
+0.3: engine, CLI (`init`, `validate`, `registry`, `dev`), history with rollback, proposals with owner approval, reorder editor, agent with a pluggable model adapter.
 
 License: MIT.

package/bin/cli.js

@@ -2,6 +2,7 @@
 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";
 
 const [cmd, ...args] = process.argv.slice(2);
 const flag = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
@@ -9,12 +10,14 @@ 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
 `;
 
 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; }
 } catch (e) { console.error("pagetailor:", e.message); process.exitCode = 1; }

package/package.json

@@ -1,17 +1,42 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.1.0",
+  "version": "0.3.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",
-  "bin": { "pagetailor": "bin/cli.js" },
+  "bin": {
+    "pagetailor": "bin/cli.js"
+  },
   "main": "./src/index.js",
-  "exports": { ".": "./src/index.js", "./client": "./src/client.jsx" },
-  "files": ["bin", "src", "templates", "README.md"],
-  "engines": { "node": ">=20" },
-  "keywords": ["server-driven-ui", "generative-ui", "declarative-ui", "json-render", "yaml", "personalization", "ai-agent"],
-  "repository": { "type": "git", "url": "git+https://github.com/aeratic/pagetailor.git" },
-  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.jsx"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "server-driven-ui",
+    "generative-ui",
+    "declarative-ui",
+    "json-render",
+    "yaml",
+    "personalization",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aeratic/pagetailor.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@json-render/core": "0.21.1",
     "@json-render/react": "0.21.1",
@@ -19,6 +44,15 @@
     "yaml": "^2.6.0",
     "zod": "4.3.6"
   },
-  "peerDependencies": { "react": ">=19.2.3", "react-dom": ">=19.2.3" },
-  "devDependencies": { "react": "19.2.3", "react-dom": "19.2.3" }
+  "peerDependencies": {
+    "react": ">=19.2.3",
+    "react-dom": ">=19.2.3"
+  },
+  "devDependencies": {
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "scripts": {
+    "test": "node --no-deprecation --import ./test/jsx-loader.mjs --test test/"
+  }
 }

package/src/agent.js

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+import { loadProject, loadPage, loadOverrides, loadYaml, exists } from "./loader.js";
+import { applyOverride, mergePatch } from "./overrides.js";
+import { splitRef } from "./validator.js";
+import { propose } from "./proposals.js";
+
+// The agent never writes files: it turns a request into override patches and hands them to propose().
+const OPS = [
+  ["set-areas", { op: "set-areas", target: "layout/grid", areas: "kpi kpi\nchart chart\n" }],
+  ["set-props", { op: "set-props", target: "kpi", props: { label: "Sales" } }],
+  ["set-data", { op: "set-data", target: "chart", data: { source: "<source>", params: { "<param>": "<value>" } } }],
+  ["replace", { op: "replace", target: "chart", with: { ref: "<component@version>", props: { title: "..." }, data: { source: "<source>" } } }],
+  ["remove", { op: "remove", target: "kpi" }],
+  ["insert", { op: "insert", target: "layout/grid", name: "notes", node: { ref: "text/block@1.0.0", props: { content: "Hi" } }, area: "notes notes\nchart chart\n" }],
+  ["move", { op: "move", target: "todo/list", to: 0 }],
+];
+const readable = (src, role) => !src.roles || src.roles.includes("*") || (role != null && src.roles.includes(role));
+
+export function describeCatalog(project, { role } = {}) {
+  const out = ["COMPONENTS"];
+  for (const [name, c] of Object.entries(project.registry ?? {})) for (const v of Object.keys(c.versions ?? {})) {
+    const props = Object.entries(c.props ?? {}).map(([k, t]) => `${k}: ${t}`).join(", ");
+    out.push(`- ${name}@${v}: ${c.description ?? name}${c.container ? " [container]" : ""}${c.accepts ? `; accepts ${c.accepts}` : ""}; props { ${props} }`);
+  }
+  out.push("", `DATA SOURCES (readable by role ${role ?? "none"})`);
+  for (const [name, s] of Object.entries(project.catalog ?? {})) {
+    if (!readable(s, role)) continue;
+    const params = Object.entries(s.params ?? {}).map(([k, v]) => `${k}: ${[].concat(v).join("|")}`).join(", ");
+    out.push(`- ${name}: ${s.description ?? name}; returns ${s.returns ?? "any"}${params ? `; params { ${params} }` : ""}`);
+  }
+  out.push("", "OVERRIDE OPS (target = a child name or a component name)");
+  for (const [op, ex] of OPS) out.push(`- ${op}: ${JSON.stringify(ex)}${op === "move" ? " (array children only)" : ""}`);
+  return out.join("\n");
+}
+
+async function currentTree(root, page, { user, role } = {}) {
+  let tree = (await loadPage(root, page)).layout;
+  for (const ov of await loadOverrides(root, page, user, role)) tree = applyOverride(tree, ov).tree;
+  return tree;
+}
+
+export async function describePage(root, page, { user, role } = {}) {
+  const lines = [];
+  const walk = (node, name, depth) => {
+    if (!node || typeof node !== "object") return;
+    const data = node.data?.source ? ` (data: ${node.data.source}${node.data.params ? " " + JSON.stringify(node.data.params) : ""})` : "";
+    const props = Object.fromEntries(Object.entries(node.props ?? {}).filter(([k]) => k !== "areas"));
+    lines.push(`${"  ".repeat(depth)}${name}: ${node.ref}${data}${Object.keys(props).length ? " props " + JSON.stringify(props) : ""}`);
+    if (node.props?.areas) lines.push(`${"  ".repeat(depth + 1)}areas: ${JSON.stringify(String(node.props.areas))}`);
+    const kids = node.children;
+    if (Array.isArray(kids)) kids.forEach(c => walk(c, splitRef(c?.ref)[0], depth + 1));
+    else if (kids) for (const [k, c] of Object.entries(kids)) walk(c, k, depth + 1);
+  };
+  const tree = await currentTree(root, page, { user, role });
+  walk(tree, splitRef(tree.ref)[0], 0);
+  return `PAGE ${page} (user ${user ?? "none"}, role ${role ?? "none"})\n${lines.join("\n")}`;
+}
+
+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 }
+
+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).
+- 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.
+- 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.
+
+${describeCatalog(project, { role })}
+
+CURRENT ${await describePage(root, page, { user, role })}`;
+  return { system, user: request };
+}
+
+export function parseAgentReply(text) {
+  const s = String(text ?? "");
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
+  const candidates = [fenced?.[1], s];
+  for (const c of candidates) {
+    if (!c) continue;
+    const a = c.indexOf("{"), b = c.lastIndexOf("}");
+    if (a < 0 || b <= a) continue;
+    try {
+      const v = JSON.parse(c.slice(a, b + 1));
+      if (v && typeof v === "object" && !Array.isArray(v)) return v;
+    } catch {}
+  }
+  throw new Error(`agent reply is not a JSON object: ${s.slice(0, 200)}`);
+}
+
+export async function runAgent(root, { page, user, role, request, complete }) {
+  if (!user) return { ok: false, errors: ["user is required"], attempts: 0 };
+  const name = `user-${user}`;
+  const prompt = await buildAgentPrompt(root, { page, user, role, request });
+  const file = join(root, "overrides", `${name}.yaml`);
+  const existing = await exists(file) ? (await loadYaml(file)) ?? {} : {};
+  const base = existing.extends === page ? existing.patches ?? [] : [];
+  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 {
+        const patches = reply.patches.reduce(mergePatch, base);
+        const proposal = await propose(root, { name, author: user, role, override: { extends: page, why: reply.why, patches } });
+        if (proposal.ok) return { ok: true, reply, proposal, attempts };
+        errors = proposal.errors;
+      }
+    }
+    if (attempts === 2) return { ok: false, errors, reply, attempts };
+    message = `${prompt.user}\n\nThe previous patch was rejected: ${errors.join("; ")}. Fix it.`;
+    reply = undefined; errors = [];
+  }
+}

package/src/client.jsx

@@ -24,3 +24,4 @@ export function Page({ resolved, registry }) {
 }
 
 export { tokensToCss } from "./tokens.js";
+export { EditorContext, EditableGrid, useEditor, swapAreas, mergePatch } from "./editor.jsx";

package/src/dev.js

@@ -7,17 +7,24 @@ import * as esbuild from "esbuild";
 import { resolve } from "./resolver.js";
 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 { anthropicComplete } from "./llm.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
 export async function dev(cwd, { port = 4747 } = {}) {
   const root = join(cwd, "pagetailor");
-  const req = createRequire(join(cwd, "package.json"));
+  // 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);
   const alias = {};
-  for (const m of ["react", "react-dom", "react/jsx-runtime", "react-dom/client", "@json-render/react", "@json-render/core"]) {
-    try { alias[m] = req.resolve(m); } catch {}
+  for (const m of ["react", "react-dom", "react/jsx-runtime", "react-dom/client"]) {
+    try { alias[m] = reqProject.resolve(m); } catch { try { alias[m] = reqSelf.resolve(m); } catch {} }
   }
+  // components import "@aeratic/pagetailor/client": always the same file as the entry, so EditorContext is shared
+  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 () => {
@@ -31,8 +38,8 @@ export async function dev(cwd, { port = 4747 } = {}) {
     }
     return `${imports.join("\n")}
 import { createRoot } from "react-dom/client";
-import { useEffect, useState } from "react";
-import { Page } from ${JSON.stringify(join(here, "client.jsx"))};
+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);
@@ -40,7 +47,21 @@ function App() {
   const [user, setUser] = useState(q.get("user") || "");
   const [role, setRole] = useState(q.get("role") || "");
   const [state, setState] = useState(null);
-  useEffect(() => { fetch(\`/api/page/\${page}?user=\${user}&role=\${role}\`).then(r => r.json()).then(setState); }, [page, user, role]);
+  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 ?? [];
@@ -50,9 +71,15 @@ function App() {
       <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" }}><Page resolved={state} registry={registry} /></main>
+    <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 />);`;
@@ -60,7 +87,7 @@ createRoot(document.getElementById("root")).render(<App />);`;
 
   const ctx = await esbuild.context({
     stdin: { contents: await entry(), resolveDir: join(root, "components"), loader: "jsx", sourcefile: "pagetailor-entry.jsx" },
-    bundle: true, write: false, format: "esm", jsx: "automatic", alias, outfile: "bundle.js", sourcemap: "inline", logLevel: "silent",
+    bundle: true, write: false, format: "esm", jsx: "automatic", alias, nodePaths, outfile: "bundle.js", sourcemap: "inline", logLevel: "silent",
     define: { "process.env.NODE_ENV": '"development"' },
   });
   let bundle = "", buildErrors = [];
@@ -94,16 +121,41 @@ createRoot(document.getElementById("root")).render(<App />);`;
       if (url.pathname.startsWith("/api/page/")) {
         let page = decodeURIComponent(url.pathname.slice(10));
         if (page === "__home__") page = (await loadProject(root)).manifest.home ?? (await listPages(root))[0];
-        const r = await resolve(root, page, { user: url.searchParams.get("user") || undefined, role: url.searchParams.get("role") || undefined });
+        const r = await resolve(root, page, { user: url.searchParams.get("user") || undefined, role: url.searchParams.get("role") || undefined, maxAge: 2000 });
         if (r.errors.length) console.warn(`[${page}]`, r.errors.map(e => `${e.path}: ${e.message}`).join("\n  "));
         return json(res, 200, { page, ...r });
       }
+      if (url.pathname.startsWith("/api/override/") && req.method === "GET") {
+        const name = decodeURIComponent(url.pathname.slice(14));
+        if (!/^[\w.-]+$/.test(name)) return json(res, 400, { error: "bad override name" });
+        let ov = {}; try { ov = (await loadYaml(join(root, "overrides", `${name}.yaml`))) ?? {}; } catch {}
+        return json(res, 200, ov);
+      }
       if (url.pathname.startsWith("/api/history/")) return json(res, 200, await listHistory(root, url.pathname.slice(13)));
       if (url.pathname === "/api/override" && req.method === "POST") { const b = await body(req); return json(res, 200, await commitOverride(root, b.name, b.override, { author: b.author })); }
+      if (url.pathname === "/api/agent/prompt" && req.method === "GET") {
+        const q = Object.fromEntries(url.searchParams);
+        return json(res, 200, await buildAgentPrompt(root, { page: q.page || "home", user: q.user || undefined, role: q.role || undefined, request: q.request ?? "" }));
+      }
+      if (url.pathname === "/api/agent" && 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 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/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); }
       if (url.pathname === "/api/rollback" && req.method === "POST") { const b = await body(req); return json(res, 200, await rollback(root, b.name, b.version, { author: b.author })); }
       json(res, 404, { error: "not found" });
     } catch (e) { console.error(e); json(res, 500, { error: e.message }); }
   });
+  server.on("error", e => {
+    if (e.code !== "EADDRINUSE") throw e;
+    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`);
   return server;

package/src/editor.jsx

@@ -0,0 +1,68 @@
+import { createContext, useCallback, useContext, useEffect, useState } from "react";
+import { mergePatch } from "./overrides.js";
+export { mergePatch };
+
+// Reorder editor: drag a grid cell onto another to swap their area names, written as a set-areas patch.
+export const EditorContext = createContext({ editing: false, propose: null });
+
+// Swap every occurrence of area names a and b; keeps line breaks, normalises spacing inside a row.
+export function swapAreas(areas, a, b) {
+  return String(areas).trim().split("\n")
+    .map(l => l.trim().split(/\s+/).map(n => n === a ? b : n === b ? a : n).join(" "))
+    .join("\n") + "\n";
+}
+
+// props: the grid's props (areas, names, __pt); cells: one rendered child per entry of props.names.
+export function EditableGrid({ props, cells, style }) {
+  const { editing, propose } = useContext(EditorContext);
+  const [dragging, setDragging] = useState(null), [over, setOver] = useState(null);
+  const names = props.names ?? [];
+  const on = editing && typeof propose === "function";
+  const drop = to => {
+    const from = dragging; setDragging(null); setOver(null);
+    if (!from || from === to) return;
+    propose({ op: "set-areas", target: props.__pt?.name ?? "layout/grid", areas: swapAreas(props.areas, from, to) });
+  };
+  return (
+    <div style={style}>
+      {cells.map((k, i) => {
+        const name = names[i];
+        const cell = { gridArea: name, minWidth: 0 };
+        if (!on || !name) return <div key={name ?? i} style={cell}>{k}</div>;
+        return (
+          <div key={name} draggable
+            onDragStart={e => { e.dataTransfer.effectAllowed = "move"; e.dataTransfer.setData("text/plain", name); setDragging(name); }}
+            onDragEnd={() => { setDragging(null); setOver(null); }}
+            onDragOver={e => { e.preventDefault(); if (over !== name) setOver(name); }}
+            onDragLeave={() => setOver(o => o === name ? null : o)}
+            onDrop={e => { e.preventDefault(); drop(name); }}
+            style={{ ...cell, cursor: "grab", borderRadius: 8, outline: over === name && dragging !== name ? "2px solid var(--pt-color-primary, #2E6BE6)" : "1px dashed var(--pt-color-border, #999)", outlineOffset: 2, opacity: dragging === name ? 0.5 : 1 }}>
+            {k}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// status: "idle" | "saving" | "pending" | "error"; errors holds the gate errors.
+export function useEditor({ page, user, role, why, onApplied } = {}) {
+  const [editing, setEditing] = useState(false);
+  const [status, setStatus] = useState("idle"), [errors, setErrors] = useState([]), [pending, setPending] = useState(null);
+  const name = `user-${user}`;
+  const propose = useCallback(async patch => {
+    if (!user) { setStatus("error"); setErrors(["set a user to save layout changes"]); return; }
+    setStatus("saving"); setErrors([]);
+    try {
+      const current = await (await fetch(`/api/override/${encodeURIComponent(name)}`)).json();
+      const override = { extends: page, why, patches: mergePatch(current.extends === page ? current.patches ?? [] : [], patch) };
+      const r = await (await fetch("/api/propose", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ name, author: user, role: role || undefined, override }) })).json();
+      if (!r.ok) { setStatus("error"); setErrors(r.errors ?? [r.error ?? "propose failed"]); return; }
+      if (r.pending) { setPending(r.entry); setStatus("pending"); }
+      else { setPending(null); setStatus("idle"); }
+      onApplied?.(r);
+    } catch (e) { setStatus("error"); setErrors([e.message]); }
+  }, [page, user, role, why, name, onApplied]);
+  useEffect(() => { setStatus("idle"); setErrors([]); setPending(null); }, [page, user, role]);
+  return { editing, setEditing, propose, status, errors, pending };
+}

package/src/index.js

@@ -1,8 +1,18 @@
-export { resolve } from "./resolver.js";
+export { resolve, clearResolveCache } from "./resolver.js";
 export { validateTree, validateManifest, typeAccepts } from "./validator.js";
-export { applyOverride } from "./overrides.js";
+export { parseType, validateProps, propsToZod, buildCatalog } from "./props.js";
+export { applyOverride, mergePatch } from "./overrides.js";
 export { commitOverride, listHistory, rollback } from "./history.js";
+export { propose, listPending, approve, reject } from "./proposals.js";
 export { loadProject, loadPage, loadOverrides, listPages, listOverrides, loadSources } from "./loader.js";
 export { init } from "./init.js";
 export { validate } from "./validate.js";
-export { dev } from "./dev.js";
+// dev pulls esbuild: load it lazily so bundlers (Next.js) never trace it into an app
+export async function dev(...args) {
+  const m = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ new URL("./dev.js", import.meta.url).href);
+  return m.dev(...args);
+}
+export { writeRegistryFile } from "./registry-file.js";
+export { tokensToCss } from "./tokens.js";
+export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent } from "./agent.js";
+export { anthropicComplete } from "./llm.js";

package/src/init.js

@@ -1,6 +1,7 @@
 import { cp, mkdir, access, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { writeRegistryFile } from "./registry-file.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -10,6 +11,7 @@ export async function init(cwd, args = []) {
   try { await access(target); if (!force) throw new Error("pagetailor/ already exists (use --force to overwrite)"); } catch (e) { if (e.code !== "ENOENT") throw e; }
   await mkdir(target, { recursive: true });
   await cp(join(here, "..", "templates"), target, { recursive: true, force });
+  await writeRegistryFile(cwd);
   let needs = [];
   try {
     const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
@@ -23,7 +25,7 @@ export async function init(cwd, args = []) {
   data/sources.mjs         one async function per source (demo data, replace with your APIs)
   pages/home.yaml         a sample page: card > grid with named areas
   overrides/              per-user (user-giulia) and per-role (role-magazzino) patches
-  components/             registry.yaml + 9 base components, yours to edit
+  components/             registry.yaml + 9 base components, yours to edit; index.js generated by "pagetailor registry"
 `);
   if (needs.length) console.log(`install the runtime:\n  npm install ${needs.join(" ")}\n`);
   console.log(`then:\n  npx pagetailor validate\n  npx pagetailor dev`);

package/src/llm.js

@@ -0,0 +1,14 @@
+// Minimal Messages API call over global fetch; returns a `complete({ system, user })` for runAgent.
+export function anthropicComplete({ apiKey, model = "claude-sonnet-5-5" } = {}) {
+  if (!apiKey) throw new Error("anthropicComplete: apiKey is required");
+  return async ({ system, user }) => {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+      body: JSON.stringify({ model, max_tokens: 1024, system, messages: [{ role: "user", content: user }] }),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${text}`);
+    return (JSON.parse(text).content ?? []).filter(b => b.type === "text").map(b => b.text).join("");
+  };
+}

package/src/loader.js

@@ -49,6 +49,6 @@ export async function listOverrides(root) {
 export async function loadSources(root) {
   const p = join(root, "data", "sources.mjs");
   if (!(await exists(p))) return {};
-  const mod = await import(`file://${p}?t=${Date.now()}`);
+  const mod = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ `file://${p}?t=${Date.now()}`);
   return mod.default ?? mod.sources ?? mod;
 }

package/src/overrides.js

@@ -41,3 +41,10 @@ export function find(node, target, parent = null, key = null) {
   for (const [k, v] of Object.entries(kids)) { const r = find(v, target, kids, Array.isArray(kids) ? Number(k) : k); if (r) return r; }
   return null;
 }
+
+// A set-areas patch replaces an earlier set-areas on the same target; anything else is appended.
+export function mergePatch(patches = [], patch) {
+  const i = patch.op === "set-areas" ? patches.findIndex(p => p.op === "set-areas" && p.target === patch.target) : -1;
+  if (i < 0) return [...patches, patch];
+  const out = [...patches]; out[i] = patch; return out;
+}

package/src/proposals.js

@@ -0,0 +1,66 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadProject, loadPage, loadOverrides } from "./loader.js";
+import { applyOverride } from "./overrides.js";
+import { validateTree } from "./validator.js";
+import { commitOverride, listHistory } from "./history.js";
+
+// Own user overrides apply at once; role overrides go pending until a page owner approves.
+const file = (root, name, v) => join(root, ".history", name, `${String(v).padStart(4, "0")}.json`);
+const msg = e => typeof e === "string" ? e : `${e.path}: ${e.message}`;
+
+async function gate(root, name, override, role) {
+  if (!override?.extends) return ["override.extends is required"];
+  const project = await loadProject(root);
+  let page; try { page = await loadPage(root, override.extends); } catch { return [`page "${override.extends}" not found`]; }
+  const target = name.startsWith("role-") ? name.slice(5) : role ?? null;
+  let tree = page.layout;
+  if (name.startsWith("user-") && role) for (const ov of await loadOverrides(root, override.extends, null, role)) tree = applyOverride(tree, ov).tree;
+  const r = applyOverride(tree, { name, ...override });
+  return [...r.errors, ...validateTree(r.tree, project, { role: target })].map(msg);
+}
+
+async function pendingEntry(root, name, version, approverRole) {
+  const entry = (await listHistory(root, name)).find(e => e.version === version);
+  if (!entry || entry.status !== "pending") return { errors: [`${name} v${version} is not pending`] };
+  const page = entry.override?.extends;
+  const owners = [].concat((await loadProject(root)).manifest.owners?.[page] ?? []);
+  if (!owners.includes(approverRole)) return { errors: [`role ${approverRole ?? "none"} cannot approve changes to page ${page}`] };
+  return { entry };
+}
+const mark = (root, name, entry, extra) => writeFile(file(root, name, entry.version), JSON.stringify({ ...entry, ...extra }, null, 2));
+
+export async function propose(root, { name, override, author, role }) {
+  const errors = await gate(root, name, override, role);
+  if (errors.length) return { ok: false, errors };
+  if (name.startsWith("user-") && author === name.slice(5)) return { ok: true, entry: await commitOverride(root, name, override, { author }) };
+  const entry = await commitOverride(root, name, override, { author, status: "pending" });
+  if (role) { entry.role = role; await mark(root, name, entry, {}); }
+  return { ok: true, entry, pending: true };
+}
+
+export async function listPending(root) {
+  let names = []; try { names = await readdir(join(root, ".history")); } catch {}
+  const all = (await Promise.all(names.map(async name => (await listHistory(root, name)).map(e => ({ ...e, name }))))).flat();
+  return all.filter(e => e.status === "pending").sort((a, b) => b.at.localeCompare(a.at) || b.version - a.version);
+}
+
+export async function approve(root, { name, version, approver, approverRole }) {
+  const { entry, errors } = await pendingEntry(root, name, version, approverRole);
+  if (errors) return { ok: false, errors };
+  const gateErrors = await gate(root, name, entry.override, entry.role);
+  if (gateErrors.length) return { ok: false, errors: gateErrors };
+  const applied = await commitOverride(root, name, entry.override, { author: approver });
+  const out = { ...applied, approvedFrom: version };
+  await writeFile(file(root, name, applied.version), JSON.stringify(out, null, 2));
+  await mark(root, name, entry, { status: "approved" });
+  return { ok: true, entry: out };
+}
+
+export async function reject(root, { name, version, approver, approverRole, reason }) {
+  const { entry, errors } = await pendingEntry(root, name, version, approverRole);
+  if (errors) return { ok: false, errors };
+  const out = { ...entry, status: "rejected", reason, rejectedBy: approver };
+  await mark(root, name, entry, out);
+  return { ok: true, entry: out };
+}

package/src/props.js

@@ -0,0 +1,65 @@
+// Component props schema: { name: "string" | "number?" | "enum[a,b]" | "string[]" | "text" ... }
+const RESERVED = new Set(["data", "names", "__pt"]);
+const BASES = new Set(["string", "number", "boolean", "string[]", "number[]"]);
+
+export function parseType(str) {
+  let s = String(str).trim();
+  const optional = s.endsWith("?");
+  if (optional) s = s.slice(0, -1).trim();
+  const m = /^enum\[(.*)\]$/.exec(s);
+  if (m) return { base: "enum", optional, values: m[1].split(",").map(v => v.trim()).filter(Boolean) };
+  if (s === "text") s = "string";
+  if (!BASES.has(s)) throw new Error(`unknown prop type "${str}"`);
+  return { base: s, optional };
+}
+
+const check = (t, v) => {
+  switch (t.base) {
+    case "string": return typeof v === "string" ? null : "expected string";
+    case "number": return typeof v === "number" && !Number.isNaN(v) ? null : "expected number";
+    case "boolean": return typeof v === "boolean" ? null : "expected boolean";
+    case "string[]": return Array.isArray(v) && v.every(x => typeof x === "string") ? null : "expected string[]";
+    case "number[]": return Array.isArray(v) && v.every(x => typeof x === "number") ? null : "expected number[]";
+    case "enum": return t.values.includes(String(v)) ? null : `value ${JSON.stringify(v)} not in [${t.values.join(", ")}]`;
+  }
+};
+
+export function validateProps(props, schema) {
+  if (!schema) return [];
+  const errors = [], p = props ?? {};
+  const types = {};
+  for (const [k, s] of Object.entries(schema)) {
+    try { types[k] = parseType(s); } catch { types[k] = { bad: s }; }
+  }
+  for (const k of Object.keys(p)) if (!RESERVED.has(k) && !types[k]) errors.push(`prop "${k}": unknown prop`);
+  for (const [k, t] of Object.entries(types)) {
+    if (RESERVED.has(k)) continue;
+    if (t.bad !== undefined) { errors.push(`prop "${k}": unknown type "${t.bad}" in registry`); continue; }
+    const v = p[k];
+    if (v === undefined || v === null) { if (!t.optional) errors.push(`prop "${k}": missing required`); continue; }
+    const e = check(t, v); if (e) errors.push(`prop "${k}": ${e}`);
+  }
+  return errors;
+}
+
+const zodOf = (t, z) => {
+  const base = { string: () => z.string(), number: () => z.number(), boolean: () => z.boolean(),
+    "string[]": () => z.array(z.string()), "number[]": () => z.array(z.number()), enum: () => z.enum(t.values) }[t.base]();
+  return t.optional ? base.nullable().optional() : base;
+};
+
+export function propsToZod(schema, z) {
+  if (!schema) return z.looseObject({});
+  return z.object(Object.fromEntries(Object.entries(schema).filter(([k]) => !RESERVED.has(k)).map(([k, s]) => [k, zodOf(parseType(s), z)])));
+}
+
+export function buildCatalog(registry, z) {
+  const components = {};
+  for (const [name, entry] of Object.entries(registry ?? {}))
+    for (const version of Object.keys(entry.versions ?? {})) {
+      const c = { props: propsToZod(entry.props, z), description: entry.description ?? name };
+      if (entry.container) c.slots = ["default"];
+      components[`${name}@${version}`] = c;
+    }
+  return { components, actions: {} };
+}

package/src/registry-file.js

@@ -0,0 +1,24 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadYaml } from "./loader.js";
+
+// Writes pagetailor/components/index.js: imports every impl in registry.yaml, exports { "name@version": Component }.
+export async function writeRegistryFile(cwd) {
+  const dir = join(cwd, "pagetailor", "components");
+  const reg = await loadYaml(join(dir, "registry.yaml"));
+  const entries = [];
+  for (const [name, def] of Object.entries(reg ?? {})) for (const [ver, v] of Object.entries(def.versions ?? {}))
+    if (v.impl) entries.push([`${name}@${ver}`, v.impl.startsWith(".") ? v.impl : `./${v.impl}`]);
+  entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const src = `// generated by \`pagetailor registry\`, do not edit
+${entries.map(([, impl], i) => `import C${i} from ${JSON.stringify(impl)};`).join("\n")}
+
+export const registry = {
+${entries.map(([key], i) => `  ${JSON.stringify(key)}: C${i},`).join("\n")}
+};
+export default registry;
+`;
+  const out = join(dir, "index.js");
+  await writeFile(out, src);
+  return { path: out, count: entries.length };
+}

package/src/resolver.js

@@ -1,9 +1,29 @@
 import { loadProject, loadPage, loadOverrides, loadSources } from "./loader.js";
 import { validateTree } from "./validator.js";
 import { applyOverride } from "./overrides.js";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+
+// in-memory cache: data sources are not called again while the project files are unchanged
+const cache = new Map();
+export function clearResolveCache() { cache.clear(); }
+const mtime = p => stat(p).then(s => s.mtimeMs, () => 0);
+const fingerprint = (root, page, user, role) => Promise.all([
+  "manifest.yaml", "data-catalog.yaml", join("components", "registry.yaml"), join("pages", `${page}.yaml`),
+  join("overrides", `role-${role}.yaml`), join("overrides", `user-${user}.yaml`), join("data", "sources.mjs"),
+].map(f => mtime(join(root, f)))).then(a => Math.max(...a));
 
 // YAML page + overrides + data  ->  json-render flat spec { root, elements, state }
-export async function resolve(root, page, { user, role, sources } = {}) {
+export async function resolve(root, page, { user, role, sources, fresh = false, maxAge = 0 } = {}) {
+  const key = `${root}|${page}|${user}|${role}`, fp = await fingerprint(root, page, user, role);
+  const hit = cache.get(key);
+  if (!fresh && hit && hit.fp === fp && (!maxAge || Date.now() - hit.at < maxAge)) return hit.result;
+  const result = await build(root, page, { user, role, sources });
+  cache.set(key, { fp, at: Date.now(), result });
+  return result;
+}
+
+async function build(root, page, { user, role, sources }) {
   const project = await loadProject(root);
   const fetchers = sources ?? await loadSources(root);
   let tree = (await loadPage(root, page)).layout;
@@ -11,16 +31,18 @@ export async function resolve(root, page, { user, role, sources } = {}) {
   for (const ov of await loadOverrides(root, page, user, role)) {
     const r = applyOverride(tree, ov); tree = r.tree; errors.push(...r.errors);
   }
-  errors.push(...validateTree(tree, project, { role }));
+  errors.push(...validateTree(tree, project, { role: role ?? null }));
   const byPath = new Map(); for (const e of errors) byPath.set(e.path, [...(byPath.get(e.path) ?? []), e.message]);
 
   const elements = {}, state = { data: {}, user: { id: user ?? null, role: role ?? null } };
   let n = 0;
-  const walk = async (node, path) => {
+  const label = n => n?.ref ? n.ref.split("@")[0] : null;
+  // __pt maps an element back to its YAML target: own name (child name or component name) and the parent's.
+  const walk = async (node, path, name = label(node), container = null) => {
     const id = `e${n++}`;
     const bad = byPath.get(path);
     if (bad) { elements[id] = { type: "pt/fallback", props: { reason: bad.join("; ") } }; return id; }
-    const props = { ...(node.props ?? {}) };
+    const props = { ...(node.props ?? {}), __pt: { path, name, container } };
     if (node.data?.source) {
       const key = `${node.data.source}${node.data.params ? ":" + JSON.stringify(node.data.params) : ""}`.replace(/[^\w]/g, "_");
       if (!(key in state.data)) {
@@ -35,7 +57,7 @@ export async function resolve(root, page, { user, role, sources } = {}) {
       const entries = named ? Object.entries(node.children) : node.children.map((c, i) => [i, c]);
       if (named) props.names = entries.map(([k]) => k);
       el.children = [];
-      for (const [i, [, c]] of entries.entries()) el.children.push(await walk(c, `${path}/${i}`));
+      for (const [i, [k, c]] of entries.entries()) el.children.push(await walk(c, `${path}/${i}`, named ? k : label(c), name));
     }
     elements[id] = el; return id;
   };

package/src/validator.js

@@ -1,3 +1,5 @@
+import { validateProps } from "./props.js";
+
 // One validator used everywhere: CLI, resolver at runtime, agent gate.
 // A node is { ref: "name@version", props?, data?: { source, params? }, children?: [] | {name: node} }
 
@@ -20,11 +22,12 @@ export function validateTree(tree, project, { role } = {}) {
     const comp = project.registry[name];
     if (!comp) errors.push({ path, message: `unknown component "${name}"` });
     else if (version && !comp.versions?.[version]) errors.push({ path, message: `"${name}" has no version ${version}` });
+    if (comp) for (const message of validateProps(node.props, comp.props)) errors.push({ path, message });
     if (node.data?.source) {
       const src = project.catalog[node.data.source];
       if (!src) errors.push({ path, message: `unknown data source "${node.data.source}"` });
       else {
-        if (src.roles && !src.roles.includes("*") && !src.roles.includes(role))
+        if (role !== undefined && src.roles && !src.roles.includes("*") && !src.roles.includes(role))
           errors.push({ path, message: `role "${role ?? "none"}" cannot read "${node.data.source}"` });
         if (comp?.accepts && src.returns && !typeAccepts(comp.accepts, src.returns))
           errors.push({ path, message: `"${name}" accepts ${comp.accepts} but "${node.data.source}" returns ${src.returns}` });
@@ -51,6 +54,10 @@ export function validateManifest(manifest, pages) {
   const errors = [];
   for (const p of manifest.pages ?? []) if (!pages.includes(p)) errors.push({ path: "manifest", message: `page "${p}" listed but pages/${p}.yaml is missing` });
   for (const p of pages) if (!(manifest.pages ?? []).includes(p)) errors.push({ path: "manifest", message: `pages/${p}.yaml exists but is not listed in manifest.pages` });
+  for (const [page, roles] of Object.entries(manifest.owners ?? {})) {
+    if (!(manifest.pages ?? []).includes(page)) errors.push({ path: "manifest", message: `owners: page "${page}" is not in pages` });
+    for (const r of [].concat(roles ?? [])) if (!(manifest.roles ?? []).includes(r)) errors.push({ path: "manifest", message: `owners: role "${r}" of page "${page}" is not in roles` });
+  }
   if (manifest.home && !pages.includes(manifest.home)) errors.push({ path: "manifest", message: `home "${manifest.home}" is not a page` });
   return errors;
 }

package/templates/components/Grid.jsx

@@ -1,13 +1,11 @@
 import { Children } from "react";
+import { EditableGrid } from "@aeratic/pagetailor/client";
 
 // props.areas is a multiline string like CSS grid-template-areas; props.names lists the children in order.
+// Inside an EditorContext with editing on, cells can be dragged onto each other to swap areas.
 export default function Grid({ props, children }) {
   const rows = String(props.areas).trim().split("\n").map(l => l.trim().split(/\s+/));
   const cols = Math.max(...rows.map(r => r.length));
-  const kids = Children.toArray(children);
-  return (
-    <div style={{ display: "grid", gap: "var(--pt-spacing-md)", gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`, gridTemplateAreas: rows.map(r => `"${r.join(" ")}"`).join(" ") }}>
-      {kids.map((k, i) => <div key={props.names?.[i] ?? i} style={{ gridArea: props.names?.[i], minWidth: 0 }}>{k}</div>)}
-    </div>
-  );
+  const style = { display: "grid", gap: "var(--pt-spacing-md)", gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`, gridTemplateAreas: rows.map(r => `"${r.join(" ")}"`).join(" ") };
+  return <EditableGrid props={props} cells={Children.toArray(children)} style={style} />;
 }

package/templates/components/registry.yaml

@@ -1,24 +1,47 @@
-# name -> accepted data type (optional) and versions -> implementation file.
-# Containers accept no data. Add a new version when props change in an incompatible way.
+# name -> accepted data type (optional), props schema (optional) and versions -> implementation file.
+# Containers accept no data and have `container: true`. Add a new version when props change in an incompatible way.
+# Prop types: string, number, boolean, text, enum[a,b], string[], number[]; a trailing ? makes it optional.
 layout/stack:
+  description: Vertical stack of children
+  container: true
+  props: { gap: string? }
   versions: { "1.0.0": { impl: ./Stack.jsx } }
 layout/row:
+  description: Horizontal row of children
+  container: true
+  props: { gap: string? }
   versions: { "1.0.0": { impl: ./Row.jsx } }
 layout/card:
+  description: Card with an optional title wrapping its children
+  container: true
+  props: { title: string? }
   versions: { "1.0.0": { impl: ./Card.jsx } }
 layout/grid:
+  description: CSS grid with named areas, one named child per area
+  container: true
+  props: { areas: text }
   versions: { "1.0.0": { impl: ./Grid.jsx } }
 text/block:
+  description: Paragraph of text
+  props: { content: string, muted: boolean? }
   versions: { "1.0.0": { impl: ./Text.jsx } }
 kpi/number:
+  description: Single money figure with a label
   accepts: money
+  props: { label: string? }
   versions: { "1.0.0": { impl: ./Kpi.jsx } }
 charts/line:
+  description: Line chart of a money timeseries
   accepts: timeseries<money>
+  props: { title: string? }
   versions: { "1.0.0": { impl: ./LineChart.jsx } }
 tables/simple:
+  description: Simple table of rows
   accepts: table<any>
+  props: { title: string? }
   versions: { "1.0.0": { impl: ./Table.jsx } }
 todo/list:
+  description: List of tasks
   accepts: list<task>
+  props: { title: string? }
   versions: { "1.0.0": { impl: ./TodoList.jsx } }

package/templates/manifest.yaml

@@ -3,4 +3,5 @@ home: home
 nav:
   position: left
 pages: [home]
+owners: { home: [admin] }   # roles that may approve shared changes to a page
 roles: [admin, marketing, magazzino]