@aeratic/pagetailor 0.0.1 → 0.1.1

package/README.md

@@ -1,11 +1,75 @@
 # @aeratic/pagetailor
 
-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.
-
-Status: 0.0.1, name reservation. The engine (built on json-render) lands in 0.1.
+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
-npx @aeratic/pagetailor init
-npx @aeratic/pagetailor validate
+npm install @aeratic/pagetailor react react-dom
+npx pagetailor init
+npx pagetailor validate
+npx pagetailor dev        # http://localhost:4747/?user=giulia&role=marketing
+```
+
+## What `init` creates
+
+```
+pagetailor/
+  manifest.yaml         pages, home, navigation, roles
+  tokens.yaml           design tokens -> CSS variables --pt-*
+  data-catalog.yaml     data sources: params, returned type, allowed roles
+  data/sources.mjs      one async function per source (demo data)
+  pages/home.yaml       a page: tree of components, data bindings, grid with named areas
+  overrides/            user-giulia.yaml, role-magazzino.yaml: patches over a page, with a `why`
+  components/           registry.yaml + base components (yours to edit)
+```
+
+## A page
+
+```yaml
+page: home
+layout:
+  ref: layout/card@1.0.0
+  props: { title: "Dashboard" }
+  children:
+    - ref: layout/grid@1.0.0
+      props:
+        areas: |
+          chart chart
+          table kpi
+          table todo
+      children:
+        chart: { ref: charts/line@1.0.0,   data: { source: analytics.revenue, params: { period: 30d } } }
+        table: { ref: tables/simple@1.0.0, data: { source: sales.by_region } }
+        kpi:   { ref: kpi/number@1.0.0,    data: { source: sales.total } }
+        todo:  { ref: todo/list@1.0.0,     data: { source: tasks.mine } }
+```
+
+## An override
+
+```yaml
+# overrides/user-giulia.yaml
+extends: home
+why: "Reports every Monday, wants the KPI on top"
+patches:
+  - { op: set-areas, target: layout/grid, areas: "kpi kpi\nchart chart\ntable todo\n" }
+```
+
+Ops: `set-areas`, `set-props`, `set-data`, `replace`, `remove`, `insert`, `move`. Targets are component names or child names, never element ids. Role overrides (`role-<name>.yaml`) apply first, user overrides (`user-<name>.yaml`) second.
+
+## 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.
+
+## In your own server
+
+```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"
 ```
+
+## Status
+
+0.1: engine, CLI (`init`, `validate`, `dev`), history with rollback. Next: proposal/approval flow for shared pages and an agent endpoint.
+
+License: MIT.

package/bin/cli.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
 import { init } from "../src/init.js";
 import { validate } from "../src/validate.js";
+import { dev } from "../src/dev.js";
 
 const [cmd, ...args] = process.argv.slice(2);
+const flag = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
 const help = `pagetailor <command>
 
-  init        create the pagetailor/ folder with manifest, tokens, data catalog, a sample page and base components
-  validate    check every page and override against the catalog
+  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
+  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 === "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,7 +1,7 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.0.1",
-  "description": "Pages as data: declarative, per-user tailored UI that an AI agent can safely compose.",
+  "version": "0.1.1",
+  "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": {
@@ -9,7 +9,8 @@
   },
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./client": "./src/client.jsx"
   },
   "files": [
     "bin",
@@ -18,7 +19,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "server-driven-ui",
@@ -37,6 +38,21 @@
     "access": "public"
   },
   "dependencies": {
-    "yaml": "^2.6.0"
+    "@json-render/core": "0.21.1",
+    "@json-render/react": "0.21.1",
+    "esbuild": "^0.25.0",
+    "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"
+  },
+  "scripts": {
+    "test": "node --no-deprecation --import ./test/jsx-loader.mjs --test test/"
   }
 }

package/src/client.jsx

@@ -0,0 +1,26 @@
+import { Renderer, JSONUIProvider } from "@json-render/react";
+
+// Components are written as ({ props, children, slots, emit }); json-render calls them with { element, ... }.
+// element.props already has $state bindings resolved by the renderer.
+export function wrapRegistry(components) {
+  const out = {};
+  for (const [name, C] of Object.entries(components))
+    out[name] = ({ element, children, slots, emit, on, bindings, loading }) => <C props={element.props ?? {}} children={children} slots={slots} emit={emit} on={on} bindings={bindings} loading={loading} />;
+  return out;
+}
+
+export function Fallback({ props }) {
+  return <div style={{ border: "1px dashed var(--pt-color-danger, #C0392B)", color: "var(--pt-color-danger, #C0392B)", borderRadius: 8, padding: 12, fontSize: 13 }}>{props.reason}</div>;
+}
+
+// registry: { "charts/line@1.0.0": Component, ... }  resolved: output of resolve()
+export function Page({ resolved, registry }) {
+  const reg = wrapRegistry({ "pt/fallback": Fallback, ...registry });
+  return (
+    <JSONUIProvider registry={reg} initialState={resolved.spec.state} key={JSON.stringify(resolved.spec.state)}>
+      <Renderer spec={resolved.spec} registry={reg} fallback={Fallback} />
+    </JSONUIProvider>
+  );
+}
+
+export { tokensToCss } from "./tokens.js";

package/src/dev.js

@@ -0,0 +1,112 @@
+import http from "node:http";
+import { watch } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+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 { tokensToCss } from "./tokens.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export async function dev(cwd, { port = 4747 } = {}) {
+  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);
+  const alias = {};
+  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 {} }
+  }
+  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 { useEffect, useState } from "react";
+import { Page } 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);
+  useEffect(() => { fetch(\`/api/page/\${page}?user=\${user}&role=\${role}\`).then(r => r.json()).then(setState); }, [page, user, role]);
+  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>
+      {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>
+  </>;
+}
+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, nodePaths, outfile: "bundle.js", sourcemap: "inline", logLevel: "silent",
+    define: { "process.env.NODE_ENV": '"development"' },
+  });
+  let bundle = "", buildErrors = [];
+  const rebuild = async () => {
+    try { const r = await ctx.rebuild(); bundle = r.outputFiles[0].text; buildErrors = []; }
+    catch (e) { buildErrors = e.errors ?? [{ text: e.message }]; console.error("build:", buildErrors.map(x => x.text).join("\n")); }
+  };
+  await rebuild();
+
+  const clients = new Set();
+  let timer;
+  watch(root, { recursive: true }, (_, file) => {
+    if (file?.includes(".history")) return;
+    clearTimeout(timer);
+    timer = setTimeout(async () => { await rebuild(); for (const c of clients) c.write("data: reload\n\n"); console.log("reloaded:", file); }, 80);
+  });
+
+  const json = (res, code, body) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(body)); };
+  const body = req => new Promise(r => { let s = ""; req.on("data", c => s += c); req.on("end", () => r(s ? JSON.parse(s) : {})); });
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, "http://x");
+    try {
+      if (url.pathname === "/") {
+        const { tokens, manifest } = await loadProject(root);
+        res.writeHead(200, { "content-type": "text/html" });
+        return res.end(`<!doctype html><html><head><meta charset="utf-8"><title>${manifest.app}</title><style>${tokensToCss(tokens)} body{margin:0;background:var(--pt-color-background);color:var(--pt-color-text);font-family:var(--pt-font-base);font-size:var(--pt-font-size)}</style></head><body><div id="root"></div><script type="module" src="/bundle.js"></script></body></html>`);
+      }
+      if (url.pathname === "/bundle.js") { res.writeHead(200, { "content-type": "text/javascript" }); return res.end(buildErrors.length ? `document.body.innerHTML='<pre style="color:#C0392B;padding:16px">'+${JSON.stringify(buildErrors.map(e => e.text).join("\n"))}+'</pre>'` : bundle); }
+      if (url.pathname === "/events") { res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); res.write("\n"); clients.add(res); req.on("close", () => clients.delete(res)); return; }
+      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 });
+        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/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/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 }); }
+  });
+  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/history.js

@@ -0,0 +1,27 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+
+// 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));
+  return entry;
+}
+
+export async function listHistory(root, name) {
+  try { const files = (await readdir(dirOf(root, name))).sort(); return Promise.all(files.map(async f => JSON.parse(await readFile(join(dirOf(root, name), f), "utf8")))); }
+  catch { return []; }
+}
+
+export async function rollback(root, name, version, { author = "system" } = {}) {
+  const entry = JSON.parse(await readFile(join(dirOf(root, name), `${pad(version)}.json`), "utf8"));
+  return commitOverride(root, name, { ...entry.override, why: `rollback to v${version}: ${entry.override.why ?? ""}`.trim() }, { author });
+}

package/src/index.js

@@ -1,2 +1,8 @@
+export { resolve } from "./resolver.js";
+export { validateTree, validateManifest, typeAccepts } from "./validator.js";
+export { applyOverride } from "./overrides.js";
+export { commitOverride, listHistory, rollback } from "./history.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";

package/src/init.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, access } from "node:fs/promises";
+import { cp, mkdir, access, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,13 +10,21 @@ 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 });
+  let needs = [];
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    for (const d of ["@aeratic/pagetailor", "react", "react-dom"]) if (!deps[d]) needs.push(d);
+  } catch { needs = ["@aeratic/pagetailor", "react", "react-dom"]; }
   console.log(`created ${target}/
-  manifest.yaml        app shape: pages, home, navigation, roles
-  tokens.yaml          design tokens
-  data-catalog.yaml    typed data sources with roles
-  pages/home.yaml      a sample page
-  overrides/           per-user and per-role patches
-  components/          base components, yours to edit
-
-next: npx pagetailor validate`);
+  manifest.yaml           app shape: pages, home, navigation, roles
+  tokens.yaml             design tokens, exposed as CSS variables --pt-*
+  data-catalog.yaml       typed data sources with roles
+  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
+`);
+  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/loader.js

@@ -0,0 +1,54 @@
+import { readFile, stat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+const cache = new Map(); // path -> { mtime, value }
+
+export async function loadYaml(path) {
+  const { mtimeMs } = await stat(path);
+  const hit = cache.get(path);
+  if (hit && hit.mtime === mtimeMs) return hit.value;
+  const value = parse(await readFile(path, "utf8"));
+  cache.set(path, { mtime: mtimeMs, value });
+  return value;
+}
+
+export async function exists(path) { try { await stat(path); return true; } catch { return false; } }
+
+export async function loadProject(root) {
+  const [manifest, tokens, catalog, registry] = await Promise.all([
+    loadYaml(join(root, "manifest.yaml")),
+    loadYaml(join(root, "tokens.yaml")),
+    loadYaml(join(root, "data-catalog.yaml")),
+    loadYaml(join(root, "components", "registry.yaml")),
+  ]);
+  return { root, manifest, tokens, catalog, registry };
+}
+
+export async function loadPage(root, page) { return loadYaml(join(root, "pages", `${page}.yaml`)); }
+
+export async function loadOverrides(root, page, user, role) {
+  // role first, then user: each one a small patch file, missing file = no patch
+  const out = [];
+  for (const name of [role && `role-${role}`, user && `user-${user}`].filter(Boolean)) {
+    const p = join(root, "overrides", `${name}.yaml`);
+    if (await exists(p)) { const ov = await loadYaml(p); if (!ov.extends || ov.extends === page) out.push({ name, ...ov }); }
+  }
+  return out;
+}
+
+export async function listPages(root) {
+  return (await readdir(join(root, "pages"))).filter(f => f.endsWith(".yaml")).map(f => f.slice(0, -5));
+}
+export async function listOverrides(root) {
+  const dir = join(root, "overrides");
+  if (!(await exists(dir))) return [];
+  return (await readdir(dir)).filter(f => f.endsWith(".yaml")).map(f => f.slice(0, -5));
+}
+
+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()}`);
+  return mod.default ?? mod.sources ?? mod;
+}

package/src/overrides.js

@@ -0,0 +1,43 @@
+import { splitRef } from "./validator.js";
+
+// Ops work on the YAML tree, by component name or by child name, never by element id.
+//   { op: set-areas, target: layout/grid, areas: "..." }
+//   { op: replace,   target: chart, with: { ref, props, data } }
+//   { op: remove,    target: kpi }
+//   { op: set-props, target: charts/line, props: { title: "..." } }
+//   { op: set-data,  target: chart, data: { source, params } }
+//   { op: insert,    target: <container>, name?: todo2, node: {...}, before?: <child name>, area?: "..." }
+//   { op: move,      target: <child name>, to: 0 }   (array children only)
+
+export function applyOverride(tree, override) {
+  const t = structuredClone(tree);
+  const errors = [];
+  for (const [i, p] of (override.patches ?? []).entries()) {
+    const found = find(t, p.target);
+    if (!found) { errors.push({ path: `${override.name ?? "override"}/${i}`, message: `patch target "${p.target}" not found` }); continue; }
+    const { parent, key, node } = found;
+    switch (p.op) {
+      case "set-areas": (node.props ??= {}).areas = p.areas; break;
+      case "set-props": Object.assign(node.props ??= {}, p.props); break;
+      case "set-data":  node.data = p.data; break;
+      case "replace":   if (parent) parent[key] = p.with; else Object.assign(t, p.with); break;
+      case "remove":    if (Array.isArray(parent)) parent.splice(key, 1); else delete parent[key]; break;
+      case "insert": {
+        if (Array.isArray(node.children)) { const at = p.before != null ? node.children.findIndex(c => splitRef(c.ref)[0] === p.before) : node.children.length; node.children.splice(at < 0 ? node.children.length : at, 0, p.node); }
+        else { (node.children ??= {})[p.name] = p.node; if (p.area) (node.props ??= {}).areas = p.area; }
+        break;
+      }
+      case "move": { if (!Array.isArray(parent)) { errors.push({ path: `${i}`, message: "move works on array children" }); break; } const [n] = parent.splice(key, 1); parent.splice(p.to, 0, n); break; }
+      default: errors.push({ path: `${i}`, message: `unknown op "${p.op}"` });
+    }
+  }
+  return { tree: t, errors };
+}
+
+export function find(node, target, parent = null, key = null) {
+  if (!node || typeof node !== "object") return null;
+  if (key === target || (node.ref && splitRef(node.ref)[0] === target) || node.ref === target) return { parent, key, node };
+  const kids = node.children; if (!kids) return 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;
+}

package/src/resolver.js

@@ -0,0 +1,44 @@
+import { loadProject, loadPage, loadOverrides, loadSources } from "./loader.js";
+import { validateTree } from "./validator.js";
+import { applyOverride } from "./overrides.js";
+
+// YAML page + overrides + data  ->  json-render flat spec { root, elements, state }
+export async function resolve(root, page, { user, role, sources } = {}) {
+  const project = await loadProject(root);
+  const fetchers = sources ?? await loadSources(root);
+  let tree = (await loadPage(root, page)).layout;
+  const errors = [];
+  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: 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 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 ?? {}) };
+    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)) {
+        const fn = fetchers[node.data.source];
+        state.data[key] = fn ? await fn(node.data.params ?? {}, { user, role }) : null;
+      }
+      props.data = { $state: `/data/${key}` };
+    }
+    const el = { type: node.ref, props };
+    if (node.children) {
+      const named = !Array.isArray(node.children);
+      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}`));
+    }
+    elements[id] = el; return id;
+  };
+  const rootId = await walk(tree, "root");
+  return { spec: { root: rootId, elements, state }, errors, tokens: project.tokens, manifest: project.manifest };
+}

package/src/tokens.js

@@ -0,0 +1,12 @@
+// Flatten tokens.yaml into CSS variables: color.primary -> --pt-color-primary, spacing.md -> 16px
+export function tokensToCss(tokens, prefix = "--pt") {
+  const out = [];
+  const walk = (o, path) => {
+    for (const [k, v] of Object.entries(o ?? {})) {
+      if (v && typeof v === "object") walk(v, `${path}-${k}`);
+      else out.push(`${path}-${k}: ${typeof v === "number" ? v + "px" : v};`);
+    }
+  };
+  walk(tokens, prefix);
+  return `:root { ${out.join(" ")} }`;
+}

package/src/validate.js

@@ -1,43 +1,29 @@
-import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
-import { parse } from "yaml";
-
-const load = async (p) => parse(await readFile(p, "utf8"));
+import { loadProject, loadPage, listPages, listOverrides, loadYaml } from "./loader.js";
+import { validateTree, validateManifest } from "./validator.js";
+import { applyOverride } from "./overrides.js";
 
 export async function validate(cwd) {
   const root = join(cwd, "pagetailor");
-  const manifest = await load(join(root, "manifest.yaml"));
-  const data = await load(join(root, "data-catalog.yaml"));
-  const registry = await load(join(root, "components", "registry.yaml"));
-  const errors = [];
-
-  const walk = (node, page, path = "root") => {
-    if (!node || typeof node !== "object") return;
-    if (node.ref) {
-      const [name, version] = String(node.ref).split("@");
-      const comp = registry[name];
-      if (!comp) errors.push(`${page}: ${path}: unknown component "${name}"`);
-      else if (version && !comp.versions?.[version]) errors.push(`${page}: ${path}: "${name}" has no version ${version}`);
-      if (node.data?.source) {
-        const src = data[node.data.source];
-        if (!src) errors.push(`${page}: ${path}: unknown data source "${node.data.source}"`);
-        else if (comp?.accepts && src.returns && !compatible(comp.accepts, src.returns))
-          errors.push(`${page}: ${path}: "${name}" accepts ${comp.accepts} but "${node.data.source}" returns ${src.returns}`);
-      }
+  const project = await loadProject(root);
+  const pages = await listPages(root);
+  const problems = validateManifest(project.manifest, pages).map(e => `manifest.yaml: ${e.message}`);
+  const trees = {};
+  for (const p of pages) {
+    trees[p] = (await loadPage(root, p)).layout;
+    for (const e of validateTree(trees[p], project)) problems.push(`pages/${p}.yaml ${e.path}: ${e.message}`);
+  }
+  for (const name of await listOverrides(root)) {
+    const ov = await loadYaml(join(root, "overrides", `${name}.yaml`));
+    const targets = ov.extends ? [ov.extends] : pages;
+    const role = name.startsWith("role-") ? name.slice(5) : undefined;
+    for (const p of targets) {
+      if (!trees[p]) { problems.push(`overrides/${name}.yaml: extends unknown page "${p}"`); continue; }
+      const r = applyOverride(trees[p], { name, ...ov });
+      for (const e of r.errors) problems.push(`overrides/${name}.yaml ${e.path}: ${e.message}`);
+      for (const e of validateTree(r.tree, project, { role })) problems.push(`overrides/${name}.yaml on ${p} ${e.path}: ${e.message}`);
     }
-    (node.children ?? []).forEach((c, i) => walk(c, page, `${path}/${i}`));
-  };
-
-  for (const file of await readdir(join(root, "pages"))) {
-    if (!file.endsWith(".yaml")) continue;
-    const page = await load(join(root, "pages", file));
-    if (!manifest.pages?.includes(page.page)) errors.push(`${file}: page "${page.page}" is not listed in manifest.yaml`);
-    walk(page.layout, file);
   }
-
-  if (errors.length) { console.error(errors.join("\n")); console.error(`\n${errors.length} problem(s)`); return false; }
-  console.log("all pages valid"); return true;
+  if (problems.length) { console.error(problems.join("\n")); console.error(`\n${problems.length} problem(s)`); return false; }
+  console.log(`all pages valid (${pages.length} page(s))`); return true;
 }
-
-// v0: exact match or "any"; a real type lattice comes later.
-const compatible = (accepts, returns) => accepts === "any" || accepts === returns;

package/src/validator.js

@@ -0,0 +1,56 @@
+// One validator used everywhere: CLI, resolver at runtime, agent gate.
+// A node is { ref: "name@version", props?, data?: { source, params? }, children?: [] | {name: node} }
+
+export const childrenOf = (node) => !node?.children ? [] : Array.isArray(node.children) ? node.children : Object.values(node.children);
+export const splitRef = (ref) => { const i = String(ref).lastIndexOf("@"); return i < 0 ? [ref, null] : [ref.slice(0, i), ref.slice(i + 1)]; };
+
+// v0 type lattice: exact match, "any" accepts everything, "list<any>" / "table<any>" accept any list / table
+export function typeAccepts(accepts, returns) {
+  if (!accepts || accepts === "any") return true;
+  if (accepts === returns) return true;
+  const m = /^(\w+)<any>$/.exec(accepts);
+  return !!m && returns.startsWith(m[1] + "<");
+}
+
+export function validateTree(tree, project, { role } = {}) {
+  const errors = [];
+  const walk = (node, path) => {
+    if (!node || typeof node !== "object" || !node.ref) { errors.push({ path, message: "node has no ref" }); return; }
+    const [name, version] = splitRef(node.ref);
+    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 (node.data?.source) {
+      const src = project.catalog[node.data.source];
+      if (!src) errors.push({ path, message: `unknown data source "${node.data.source}"` });
+      else {
+        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}` });
+        for (const [k, v] of Object.entries(node.data.params ?? {})) {
+          const allowed = src.params?.[k];
+          if (allowed === undefined) errors.push({ path, message: `"${node.data.source}" has no param "${k}"` });
+          else if (Array.isArray(allowed) && !allowed.includes(v)) errors.push({ path, message: `param ${k}=${v} not in [${allowed.join(", ")}]` });
+        }
+      }
+    }
+    if (node.children && !Array.isArray(node.children) && node.props?.areas) {
+      const names = Object.keys(node.children);
+      const inAreas = new Set(String(node.props.areas).split(/\s+/).filter(Boolean).filter(a => a !== "."));
+      for (const a of inAreas) if (!names.includes(a)) errors.push({ path, message: `area "${a}" has no child` });
+      for (const n of names) if (!inAreas.has(n)) errors.push({ path, message: `child "${n}" is not placed in areas` });
+    }
+    childrenOf(node).forEach((c, i) => walk(c, `${path}/${i}`));
+  };
+  walk(tree, "root");
+  return errors;
+}
+
+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` });
+  if (manifest.home && !pages.includes(manifest.home)) errors.push({ path: "manifest", message: `home "${manifest.home}" is not a page` });
+  return errors;
+}

package/templates/components/Card.jsx

@@ -0,0 +1,8 @@
+export default function Card({ props, children }) {
+  return (
+    <section style={{ background: "var(--pt-color-surface)", border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)", padding: "var(--pt-spacing-lg)" }}>
+      {props.title && <h2 style={{ margin: "0 0 var(--pt-spacing-md)", fontSize: 18 }}>{props.title}</h2>}
+      <div style={{ display: "flex", flexDirection: "column", gap: "var(--pt-spacing-md)" }}>{children}</div>
+    </section>
+  );
+}

package/templates/components/Grid.jsx

@@ -0,0 +1,13 @@
+import { Children } from "react";
+
+// props.areas is a multiline string like CSS grid-template-areas; props.names lists the children in order.
+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>
+  );
+}

package/templates/components/Kpi.jsx

@@ -0,0 +1,9 @@
+const fmt = new Intl.NumberFormat("it-IT", { style: "currency", currency: "EUR", maximumFractionDigits: 0 });
+export default function Kpi({ props }) {
+  return (
+    <div style={{ padding: "var(--pt-spacing-md)", border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)", height: "100%", boxSizing: "border-box" }}>
+      <div style={{ color: "var(--pt-color-muted)", fontSize: 13 }}>{props.label}</div>
+      <div style={{ fontSize: 32, fontWeight: 600, color: "var(--pt-color-primary)" }}>{typeof props.data === "number" ? fmt.format(props.data) : "–"}</div>
+    </div>
+  );
+}

package/templates/components/LineChart.jsx

@@ -1,3 +1,20 @@
-export default function LineChart({ props, data, children }) {
-  return <div data-pagetailor="LineChart">{props?.title}{children}</div>;
+// A dependency-free SVG line chart for timeseries<money>: [{ date, value }]
+export default function LineChart({ props }) {
+  const pts = Array.isArray(props.data) ? props.data : [];
+  const W = 600, H = 180, pad = 24;
+  const vals = pts.map(p => p.value), lo = Math.min(...vals, 0), hi = Math.max(...vals, 1);
+  const x = i => pad + (i / Math.max(pts.length - 1, 1)) * (W - 2 * pad);
+  const y = v => H - pad - ((v - lo) / (hi - lo)) * (H - 2 * pad);
+  const d = pts.map((p, i) => `${i ? "L" : "M"}${x(i).toFixed(1)} ${y(p.value).toFixed(1)}`).join(" ");
+  return (
+    <div style={{ border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)", padding: "var(--pt-spacing-md)" }}>
+      {props.title && <div style={{ fontWeight: 600, marginBottom: 8 }}>{props.title}</div>}
+      <svg viewBox={`0 0 ${W} ${H}`} style={{ width: "100%", height: "auto", display: "block" }} role="img" aria-label={props.title}>
+        <line x1={pad} y1={H - pad} x2={W - pad} y2={H - pad} stroke="var(--pt-color-border)" />
+        <path d={d} fill="none" stroke="var(--pt-color-primary)" strokeWidth="2" />
+        {pts.length > 0 && <text x={pad} y={14} fontSize="11" fill="var(--pt-color-muted)">{pts[0].date}</text>}
+        {pts.length > 1 && <text x={W - pad} y={14} fontSize="11" textAnchor="end" fill="var(--pt-color-muted)">{pts.at(-1).date}</text>}
+      </svg>
+    </div>
+  );
 }

package/templates/components/Row.jsx

@@ -0,0 +1,3 @@
+export default function Row({ props, children }) {
+  return <div style={{ display: "flex", flexDirection: "row", gap: props.gap ?? "var(--pt-spacing-md)", alignItems: "stretch" }}>{children}</div>;
+}

package/templates/components/Stack.jsx

@@ -1,3 +1,3 @@
-export default function Stack({ props, data, children }) {
-  return <div data-pagetailor="Stack">{props?.title}{children}</div>;
+export default function Stack({ props, children }) {
+  return <div style={{ display: "flex", flexDirection: "column", gap: props.gap ?? "var(--pt-spacing-md)" }}>{children}</div>;
 }

package/templates/components/Table.jsx

@@ -1,3 +1,13 @@
-export default function Table({ props, data, children }) {
-  return <div data-pagetailor="Table">{props?.title}{children}</div>;
+export default function Table({ props }) {
+  const rows = Array.isArray(props.data) ? props.data : [];
+  const cols = rows.length ? Object.keys(rows[0]) : [];
+  return (
+    <div style={{ border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)", padding: "var(--pt-spacing-md)", height: "100%", boxSizing: "border-box" }}>
+      {props.title && <div style={{ fontWeight: 600, marginBottom: 8 }}>{props.title}</div>}
+      <table style={{ width: "100%", borderCollapse: "collapse", fontSize: 14 }}>
+        <thead><tr>{cols.map(c => <th key={c} style={{ textAlign: "left", padding: "4px 6px", color: "var(--pt-color-muted)", fontWeight: 500, borderBottom: "1px solid var(--pt-color-border)" }}>{c}</th>)}</tr></thead>
+        <tbody>{rows.map((r, i) => <tr key={i}>{cols.map(c => <td key={c} style={{ padding: "4px 6px" }}>{String(r[c])}</td>)}</tr>)}</tbody>
+      </table>
+    </div>
+  );
 }

package/templates/components/Text.jsx

@@ -1,3 +1,3 @@
-export default function Text({ props, data, children }) {
-  return <div data-pagetailor="Text">{props?.title}{children}</div>;
+export default function Text({ props }) {
+  return <p style={{ margin: 0, color: props.muted ? "var(--pt-color-muted)" : "inherit" }}>{props.content}</p>;
 }

package/templates/components/TodoList.jsx

@@ -1,3 +1,11 @@
-export default function TodoList({ props, data, children }) {
-  return <div data-pagetailor="TodoList">{props?.title}{children}</div>;
+export default function TodoList({ props }) {
+  const items = Array.isArray(props.data) ? props.data : [];
+  return (
+    <div style={{ border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)", padding: "var(--pt-spacing-md)", height: "100%", boxSizing: "border-box" }}>
+      {props.title && <div style={{ fontWeight: 600, marginBottom: 8 }}>{props.title}</div>}
+      <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 6 }}>
+        {items.map(t => <li key={t.id ?? t.title} style={{ textDecoration: t.done ? "line-through" : "none", color: t.done ? "var(--pt-color-muted)" : "inherit" }}>{t.done ? "☑" : "☐"} {t.title}</li>)}
+      </ul>
+    </div>
+  );
 }

package/templates/components/registry.yaml

@@ -1,14 +1,24 @@
-# name -> versions, and the data type each component accepts
+# name -> accepted data type (optional) and versions -> implementation file.
+# Containers accept no data. Add a new version when props change in an incompatible way.
 layout/stack:
   versions: { "1.0.0": { impl: ./Stack.jsx } }
+layout/row:
+  versions: { "1.0.0": { impl: ./Row.jsx } }
+layout/card:
+  versions: { "1.0.0": { impl: ./Card.jsx } }
+layout/grid:
+  versions: { "1.0.0": { impl: ./Grid.jsx } }
+text/block:
+  versions: { "1.0.0": { impl: ./Text.jsx } }
+kpi/number:
+  accepts: money
+  versions: { "1.0.0": { impl: ./Kpi.jsx } }
 charts/line:
   accepts: timeseries<money>
   versions: { "1.0.0": { impl: ./LineChart.jsx } }
 tables/simple:
-  accepts: any
+  accepts: table<any>
   versions: { "1.0.0": { impl: ./Table.jsx } }
 todo/list:
   accepts: list<task>
   versions: { "1.0.0": { impl: ./TodoList.jsx } }
-text/block:
-  versions: { "1.0.0": { impl: ./Text.jsx } }

package/templates/data/sources.mjs

@@ -0,0 +1,19 @@
+// One async function per data source, same names as data-catalog.yaml.
+// Receives the node's params and { user, role }. Replace the demo data with your API calls.
+const days = (n, base) => Array.from({ length: n }, (_, i) => ({ date: `2026-10-${String(i + 1).padStart(2, "0")}`, value: Math.round(base + Math.sin(i / 2) * base * 0.2 + i * 15) }));
+
+export default {
+  "analytics.revenue": async ({ period = "30d" }) => days({ "7d": 7, "30d": 30, "90d": 90 }[period], 1200),
+  "sales.total": async () => 48250,
+  "sales.by_region": async () => [
+    { region: "Nord", total: 21000 }, { region: "Centro", total: 15250 }, { region: "Sud", total: 12000 },
+  ],
+  "tasks.mine": async (_, { user }) => [
+    { id: 1, title: `Rivedere il report settimanale (${user ?? "anon"})`, done: false },
+    { id: 2, title: "Chiamare il fornitore", done: true },
+    { id: 3, title: "Preparare la riunione di lunedì", done: false },
+  ],
+  "stock.levels": async () => [
+    { sku: "A-100", name: "Vite M6", qty: 1200 }, { sku: "B-220", name: "Staffa", qty: 85 }, { sku: "C-310", name: "Guarnizione", qty: 0 },
+  ],
+};

package/templates/data-catalog.yaml

@@ -1,10 +1,23 @@
-# Typed data sources. Components can only bind to sources whose `returns` they accept.
+# Typed data sources. A component binds to a source only if it accepts the type the source returns
+# and the user's role is listed. Implementations live in data/sources.mjs, keyed by the same names.
 analytics.revenue:
   description: "Revenue over time"
   params: { period: [7d, 30d, 90d] }
   returns: timeseries<money>
-  roles: [admin]
+  roles: [admin, marketing]
+sales.total:
+  description: "Total sales for the current month"
+  returns: money
+  roles: [admin, marketing]
+sales.by_region:
+  description: "Sales grouped by region"
+  returns: table<region>
+  roles: [admin, marketing]
 tasks.mine:
   description: "Tasks assigned to the current user"
   returns: list<task>
-  roles: [admin, user]
+  roles: ["*"]
+stock.levels:
+  description: "Warehouse stock levels"
+  returns: table<stock>
+  roles: [admin, magazzino]

package/templates/manifest.yaml

@@ -3,4 +3,4 @@ home: home
 nav:
   position: left
 pages: [home]
-roles: [admin, user]
+roles: [admin, marketing, magazzino]

package/templates/overrides/role-magazzino.yaml

@@ -0,0 +1,15 @@
+extends: home
+why: "Il magazzino non vede le vendite: al posto del grafico le giacenze"
+patches:
+  - op: replace
+    target: chart
+    with: { ref: tables/simple@1.0.0, props: { title: "Giacenze" }, data: { source: stock.levels } }
+  - op: remove
+    target: table
+  - op: remove
+    target: kpi
+  - op: set-areas
+    target: layout/grid
+    areas: |
+      chart chart
+      todo  todo

package/templates/overrides/user-giulia.yaml

@@ -0,0 +1,9 @@
+extends: home
+why: "Giulia fa il report ogni lunedì: vuole il KPI grande in alto e il grafico sotto"
+patches:
+  - op: set-areas
+    target: layout/grid
+    areas: |
+      kpi    kpi
+      chart  chart
+      table  todo

package/templates/pages/home.yaml

@@ -1,10 +1,16 @@
 page: home
 layout:
-  ref: layout/stack@1.0.0
+  ref: layout/card@1.0.0
+  props: { title: "Dashboard" }
   children:
-    - ref: charts/line@1.0.0
-      props: { title: "Revenue, last 30 days" }
-      data: { source: analytics.revenue, params: { period: 30d } }
-    - ref: todo/list@1.0.0
-      props: { filter: mine }
-      data: { source: tasks.mine }
+    - ref: layout/grid@1.0.0
+      props:
+        areas: |
+          chart  chart
+          table  kpi
+          table  todo
+      children:
+        chart: { ref: charts/line@1.0.0,   props: { title: "Ricavi, ultimi 30 giorni" }, data: { source: analytics.revenue, params: { period: 30d } } }
+        table: { ref: tables/simple@1.0.0, props: { title: "Vendite per zona" }, data: { source: sales.by_region } }
+        kpi:   { ref: kpi/number@1.0.0,    props: { label: "Vendite del mese" }, data: { source: sales.total } }
+        todo:  { ref: todo/list@1.0.0,     props: { title: "Le mie attività" }, data: { source: tasks.mine } }

package/templates/tokens.yaml

@@ -1,6 +1,11 @@
 color:
   primary: "#1D9E75"
   surface: "#FFFFFF"
+  background: "#F5F6F8"
   text: "#1A1A1A"
+  muted: "#6B7280"
+  border: "#E5E7EB"
+  danger: "#C0392B"
 spacing: { sm: 8, md: 16, lg: 24 }
-font: { base: "Inter", size: 15 }
+radius: 8
+font: { base: "Inter, system-ui, sans-serif", size: 15 }

package/templates/overrides/README.md

@@ -1,6 +0,0 @@
-One file per user or role, e.g. `user-giulia.yaml`:
-
-    extends: home
-    why: "Reports every Monday, wants revenue first"
-    patches:
-      - { op: move, ref: charts/line, to: 0 }