@aeratic/pagetailor 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @aeratic/pagetailor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+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

@@ -0,0 +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 [--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,6 +1,24 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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" },
+  "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" },
+  "dependencies": {
+    "@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" }
+}

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,110 @@
+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");
+  const req = createRequire(join(cwd, "package.json"));
+  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 {}
+  }
+
+  // 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, 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

@@ -0,0 +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

@@ -0,0 +1,30 @@
+import { cp, mkdir, access, readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export async function init(cwd, args = []) {
+  const target = join(cwd, "pagetailor");
+  const force = args.includes("--force");
+  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, 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 }));
+  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

@@ -0,0 +1,29 @@
+import { join } from "node:path";
+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 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}`);
+    }
+  }
+  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;
+}

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 (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

@@ -0,0 +1,20 @@
+// 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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,24 @@
+# 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: table<any>
+  versions: { "1.0.0": { impl: ./Table.jsx } }
+todo/list:
+  accepts: list<task>
+  versions: { "1.0.0": { impl: ./TodoList.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

@@ -0,0 +1,23 @@
+# 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, 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: ["*"]
+stock.levels:
+  description: "Warehouse stock levels"
+  returns: table<stock>
+  roles: [admin, magazzino]

package/templates/manifest.yaml

@@ -0,0 +1,6 @@
+app: my-app
+home: home
+nav:
+  position: left
+pages: [home]
+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

@@ -0,0 +1,16 @@
+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,   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

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