@aeratic/pagetailor 0.3.0 → 0.5.0

package/src/index.js

@@ -14,5 +14,6 @@ export async function dev(...args) {
 }
 export { writeRegistryFile } from "./registry-file.js";
 export { tokensToCss } from "./tokens.js";
-export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent } from "./agent.js";
+export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent, buildAskPrompt, runAsk, keepAnswer, pinAnswer } from "./agent.js";
 export { anthropicComplete } from "./llm.js";
+export { readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, scaffoldSource, scaffoldComponent, readProject } from "./files.js";

package/src/loader.js

@@ -13,6 +13,8 @@ export async function loadYaml(path) {
   return value;
 }
 
+export function forgetYaml(path) { cache.delete(path); }
+
 export async function exists(path) { try { await stat(path); return true; } catch { return false; } }
 
 export async function loadProject(root) {

package/src/proposals.js

@@ -12,6 +12,9 @@ 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);
+  const roles = project.manifest.roles ?? [];
+  if (role != null && !roles.includes(role)) return [`unknown role "${role}"`];
+  if (name.startsWith("role-") && !roles.includes(name.slice(5))) return [`unknown role "${name.slice(5)}"`];
   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;
@@ -24,7 +27,9 @@ 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] ?? []);
+  const manifest = (await loadProject(root)).manifest;
+  if (approverRole == null || !(manifest.roles ?? []).includes(approverRole)) return { errors: [`unknown role "${approverRole ?? "none"}"`] };
+  const owners = [].concat(manifest.owners?.[page] ?? []);
   if (!owners.includes(approverRole)) return { errors: [`role ${approverRole ?? "none"} cannot approve changes to page ${page}`] };
   return { entry };
 }

package/src/resolver.js

@@ -14,7 +14,9 @@ const fingerprint = (root, page, user, role) => Promise.all([
 ].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, fresh = false, maxAge = 0 } = {}) {
+// opts.tree: an in-memory layout (e.g. an agent answer), no page file, no overrides, no cache
+export async function resolve(root, page, { user, role, sources, tree, fresh = false, maxAge = 0 } = {}) {
+  if (tree) return build(root, page, { user, role, sources, tree });
   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;
@@ -23,12 +25,12 @@ export async function resolve(root, page, { user, role, sources, fresh = false,
   return result;
 }
 
-async function build(root, page, { user, role, sources }) {
+async function build(root, page, { user, role, sources, tree: given }) {
   const project = await loadProject(root);
   const fetchers = sources ?? await loadSources(root);
-  let tree = (await loadPage(root, page)).layout;
+  let tree = given ?? (await loadPage(root, page)).layout;
   const errors = [];
-  for (const ov of await loadOverrides(root, page, user, role)) {
+  if (!given) 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 }));

package/src/studio/App.jsx

@@ -0,0 +1,21 @@
+import { useEffect, useState } from "react";
+import { Preview } from "./Preview.jsx";
+import { Studio } from "./Studio.jsx";
+import { bar } from "./ui.jsx";
+
+// Top level: "Preview" (the rendered app) | "Studio" (forms over the project files).
+export function App({ registry }) {
+  const [view, setView] = useState(new URLSearchParams(location.search).get("view") === "studio" ? "studio" : "preview");
+  const go = v => { const q = new URLSearchParams(location.search); q.set("view", v); history.replaceState(null, "", "?" + q); setView(v); };
+  // file changes: the preview reloads the tab, the studio refreshes its data without losing drafts
+  useEffect(() => {
+    const es = new EventSource("/events");
+    es.onmessage = () => { if (view === "preview") location.reload(); else window.dispatchEvent(new Event("pt:files-changed")); };
+    return () => es.close();
+  }, [view]);
+  const tab = v => <button onClick={() => go(v)} style={{ fontWeight: view === v ? 700 : 400, border: "none", background: "none", cursor: "pointer", borderBottom: view === v ? "2px solid var(--pt-color-primary)" : "2px solid transparent", padding: "4px 8px" }}>{v === "preview" ? "Preview" : "Studio"}</button>;
+  return <>
+    <nav style={{ ...bar, padding: "4px 16px", gap: 4 }}>{tab("preview")}{tab("studio")}</nav>
+    {view === "preview" ? <Preview registry={registry} /> : <Studio registry={registry} />}
+  </>;
+}

package/src/studio/Preview.jsx

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useState } from "react";
+import { Page, EditorContext, useEditor } from "../client.jsx";
+
+// The rendered app with user/role selectors, the reorder editor and the two agent boxes.
+export function Preview({ registry }) {
+  const q = new URLSearchParams(location.search);
+  const [page, setPage] = useState(q.get("page") || "__home__");
+  const [user, setUser] = useState(q.get("user") || "");
+  const [role, setRole] = useState(q.get("role") || "");
+  const [state, setState] = useState(null);
+  const load = useCallback(() => fetch(`/api/page/${page}?user=${user}&role=${role}`).then(r => r.json()).then(setState), [page, user, role]);
+  useEffect(() => { load(); }, [load]);
+  // keep page/user/role in the URL: the file watcher reloads the tab after an override is written
+  useEffect(() => { const u = new URLSearchParams(location.search); u.set("page", page); u.set("user", user); u.set("role", 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 }); }
+  };
+  const [question, setQuestion] = useState(""), [answer, setAnswer] = useState(null), [answerStatus, setAnswerStatus] = useState(null);
+  const post = (path, b) => fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(b) }).then(r => r.json());
+  const sendQuestion = async e => {
+    e.preventDefault(); if (!question.trim()) return;
+    setAnswer(null); setAnswerStatus({ text: "composing…" });
+    try {
+      const r = await post("/api/ask", { user, role: role || undefined, request: question });
+      if (r.ok) { setAnswer(r); setAnswerStatus(null); }
+      else setAnswerStatus({ error: true, text: r.refuse ?? (r.errors ?? [r.error ?? "ask failed"]).join("; ") });
+    } catch (err) { setAnswerStatus({ error: true, text: err.message }); }
+  };
+  const answerBody = () => ({ user, role: role || undefined, title: answer.title, tree: answer.tree, why: answer.why });
+  const keep = async () => {
+    const r = await post("/api/ask/keep", answerBody());
+    if (r.ok) { setAnswer(null); setAnswerStatus(null); setPage(r.page); } else setAnswerStatus({ error: true, text: (r.errors ?? [r.error]).join("; ") });
+  };
+  const pin = async () => {
+    const r = await post("/api/ask/pin", answerBody());
+    setAnswerStatus(r.ok ? { text: r.pending ? "sent for approval" : "applied to home" } : { error: true, text: (r.errors ?? [r.error]).join("; ") });
+  };
+  if (!state) return null;
+  const pages = state.manifest.pages, roles = state.manifest.roles ?? [];
+  return <>
+    <header style={{ display: "flex", gap: 12, alignItems: "center", padding: "10px 16px", borderBottom: "1px solid var(--pt-color-border)", background: "var(--pt-color-surface)", fontSize: 13 }}>
+      <strong>{state.manifest.app}</strong>
+      <label>page <select value={state.page} onChange={e => setPage(e.target.value)}>{pages.map(p => <option key={p}>{p}</option>)}</select></label>
+      <label>user <input value={user} placeholder="giulia" onChange={e => setUser(e.target.value)} style={{ width: 90 }} /></label>
+      <label>role <select value={role} onChange={e => setRole(e.target.value)}><option value="">(none)</option>{roles.map(r => <option key={r}>{r}</option>)}</select></label>
+      <button onClick={() => editor.setEditing(!editor.editing)} style={{ fontWeight: editor.editing ? 700 : 400 }}>{editor.editing ? "Done editing" : "Edit layout"}</button>
+      {editor.status === "saving" && <span>saving…</span>}
+      {editor.status === "pending" && <span>sent for approval</span>}
+      {editor.status === "error" && <span style={{ color: "var(--pt-color-danger)" }}>{editor.errors.join("; ")}</span>}
+      <form onSubmit={sendAsk} style={{ display: "flex", gap: 6 }}><input value={ask} placeholder="Change this page…" onChange={e => setAsk(e.target.value)} style={{ width: 220 }} /><button type="submit">Ask</button></form>
+      <form onSubmit={sendQuestion} style={{ display: "flex", gap: 6 }}><input value={question} placeholder="Ask…" onChange={e => setQuestion(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>
+    {(answer || answerStatus) && <div style={{ display: "flex", gap: 12, alignItems: "center", padding: "8px 16px", borderBottom: "1px solid var(--pt-color-border)", fontSize: 13 }}>
+      {answer && <><strong>{answer.title}</strong><span>{answer.why}</span><button onClick={keep}>Keep as page</button><button onClick={pin}>Pin to home</button><button onClick={() => { setAnswer(null); setAnswerStatus(null); }}>Back</button></>}
+      {answerStatus && <span style={{ color: answerStatus.error ? "var(--pt-color-danger)" : undefined }}>{answerStatus.text}</span>}
+    </div>}
+    <main style={{ padding: 16, maxWidth: 1100, margin: "0 auto" }}>{answer
+      ? <Page resolved={{ ...state, spec: answer.resolved.spec, errors: answer.resolved.errors }} registry={registry} />
+      : <EditorContext.Provider value={{ editing: editor.editing, propose: editor.propose }}><Page resolved={state} registry={registry} /></EditorContext.Provider>}</main>
+  </>;
+}

package/src/studio/Studio.jsx

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useState } from "react";
+import { AppTab } from "./tabs/AppTab.jsx";
+import { DataTab } from "./tabs/DataTab.jsx";
+import { ComponentsTab } from "./tabs/ComponentsTab.jsx";
+import { TokensTab } from "./tabs/TokensTab.jsx";
+import { PeopleTab } from "./tabs/PeopleTab.jsx";
+import { PagesTab } from "./tabs/PagesTab.jsx";
+import { bar } from "./ui.jsx";
+
+// Tabs over the project files. Each tab gets { project, reload, registry }; later tabs add entries here.
+const TABS = [
+  { id: "app", label: "App", Component: AppTab },
+  { id: "pages", label: "Pages", Component: PagesTab },
+  { id: "data", label: "Data", Component: DataTab },
+  { id: "components", label: "Components", Component: ComponentsTab },
+  { id: "tokens", label: "Tokens", Component: TokensTab },
+  { id: "people", label: "People", Component: PeopleTab },
+];
+
+export function useProject() {
+  const [project, setProject] = useState(null), [error, setError] = useState(null);
+  const reload = useCallback(() => fetch("/api/project").then(r => r.json()).then(p => { setProject(p); setError(null); }, e => setError(e.message)), []);
+  useEffect(() => { reload(); const on = () => reload(); window.addEventListener("pt:files-changed", on); return () => window.removeEventListener("pt:files-changed", on); }, [reload]);
+  return { project, reload, error };
+}
+
+export function Studio({ registry }) {
+  const [tab, setTab] = useState(new URLSearchParams(location.search).get("tab") || "app");
+  const { project, reload, error } = useProject();
+  const go = id => { const q = new URLSearchParams(location.search); q.set("tab", id); history.replaceState(null, "", "?" + q); setTab(id); };
+  const current = TABS.find(t => t.id === tab) ?? TABS[0];
+  return <>
+    <header style={{ ...bar, background: "var(--pt-color-surface)" }}>
+      <strong>{project?.manifest?.app ?? "Studio"}</strong>
+      {TABS.map(t => <button key={t.id} onClick={() => go(t.id)} style={{ fontWeight: current.id === t.id ? 700 : 400 }}>{t.label}</button>)}
+      {error && <span style={{ color: "var(--pt-color-danger)" }}>{error}</span>}
+    </header>
+    {project && <current.Component project={project} reload={reload} registry={registry} />}
+  </>;
+}

package/src/studio/entry.jsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { registry } from "pagetailor:registry";
+import { App } from "./App.jsx";
+
+createRoot(document.getElementById("root")).render(<App registry={registry} />);

package/src/studio/tabs/AppTab.jsx

@@ -0,0 +1,85 @@
+import { useState } from "react";
+import { Field, Select, Toggle, ListEditor, YamlPane, SaveBar, useFileDraft, api, errorText, danger, section, h } from "../ui.jsx";
+
+const SLUG = /^[a-z0-9-]+$/;
+
+// manifest.yaml: name, home, navigation, pages (with their files), roles and page owners.
+export function AppTab({ project, reload }) {
+  const file = useFileDraft("manifest");
+  const [note, setNote] = useState(null);
+  const m = file.draft;
+  if (!m) return null;
+  const pages = m.pages ?? [], roles = m.roles ?? [];
+  const ownersOf = p => [].concat(m.owners?.[p] ?? []);
+
+  const addPage = async slug => {
+    if (!SLUG.test(slug)) { setNote(`"${slug}": use lowercase letters, digits and dashes`); return false; }
+    if (pages.includes(slug)) { setNote(`page "${slug}" already exists`); return false; }
+    const r = await api(`/api/files/pages/${slug}`, "PUT", { value: { page: slug, layout: { ref: "layout/stack@1.0.0" } }, why: `new page ${slug}` });
+    if (!r.ok) { setNote(errorText(r)); return false; }
+    const next = { ...structuredClone(m), pages: [...pages, slug] };
+    file.setDraft(next);
+    const s = await file.save(next);
+    setNote(s.ok ? null : errorText(s)); reload();
+  };
+  const removePage = async i => {
+    const slug = pages[i];
+    if (slug === m.home) { setNote(`"${slug}" is the home page: choose another home first`); return; }
+    const r = await api(`/api/files/pages/${slug}`, "DELETE");
+    if (!r.ok) { setNote(errorText(r)); return; }
+    const next = structuredClone(m);
+    next.pages = pages.filter(p => p !== slug);
+    if (next.owners) delete next.owners[slug];
+    file.setDraft(next);
+    const s = await file.save(next);
+    setNote(s.ok ? null : errorText(s)); reload();
+  };
+  const addRole = role => {
+    if (!SLUG.test(role)) { setNote(`"${role}": use lowercase letters, digits and dashes`); return false; }
+    if (roles.includes(role)) { setNote(`role "${role}" already exists`); return false; }
+    setNote(null); file.update(d => { d.roles = [...(d.roles ?? []), role]; });
+  };
+  const removeRole = i => {
+    const role = roles[i];
+    const usedBy = [
+      ...pages.filter(p => ownersOf(p).includes(role)).map(p => `owner of page ${p}`),
+      ...Object.entries(project.catalog ?? {}).filter(([, s]) => (s.roles ?? []).includes(role)).map(([n]) => `data source ${n}`),
+    ];
+    if (usedBy.length) { setNote(`role "${role}" is used: ${usedBy.join(", ")}`); return; }
+    setNote(null); file.update(d => { d.roles = d.roles.filter(r => r !== role); });
+  };
+  const setOwner = (page, role, on) => file.update(d => {
+    const cur = [].concat(d.owners?.[page] ?? []);
+    const next = on ? [...cur, role] : cur.filter(r => r !== role);
+    d.owners ??= {};
+    if (next.length) d.owners[page] = next; else delete d.owners[page];
+  });
+
+  return <div style={{ display: "flex", flexDirection: "column", minHeight: "calc(100vh - 90px)" }}>
+    <main style={{ padding: 16, maxWidth: 800, width: "100%", boxSizing: "border-box", margin: "0 auto", flex: 1 }}>
+      <div style={section}>
+        <Field label="name" value={m.app} onChange={v => file.update(d => { d.app = v; })} />
+        <Select label="home" value={m.home} options={pages} onChange={v => file.update(d => { d.home = v; })} />
+        <Select label="navigation" value={m.nav?.position ?? "left"} options={["left", "top"]} onChange={v => file.update(d => { d.nav = { ...(d.nav ?? {}), position: v }; })} />
+      </div>
+      {note && <p style={{ ...danger, fontSize: 13 }}>{note}</p>}
+      <div style={section}>
+        <h3 style={h}>Pages</h3>
+        <ListEditor items={pages} addLabel="+ page" addPlaceholder="slug" onAdd={addPage} onRemove={removePage}
+          render={p => <>
+            <strong style={{ minWidth: 120 }}>{p}{p === m.home ? " (home)" : ""}</strong>
+            <span style={{ color: "var(--pt-color-muted)" }}>owners</span>
+            {roles.map(r => <Toggle key={r} label={r} checked={ownersOf(p).includes(r)} onChange={on => setOwner(p, r, on)} />)}
+          </>} />
+      </div>
+      <div style={section}>
+        <h3 style={h}>Roles</h3>
+        <ListEditor items={roles} addLabel="+ role" addPlaceholder="role" onAdd={addRole} onRemove={removeRole} />
+      </div>
+    </main>
+    <div style={{ position: "sticky", bottom: 0, background: "var(--pt-color-background)" }}>
+      <SaveBar file={file} />
+      <YamlPane name="manifest" value={m} />
+    </div>
+  </div>;
+}

package/src/studio/tabs/ComponentsTab.jsx

@@ -0,0 +1,143 @@
+import { useState } from "react";
+import { Field, Toggle, ListEditor, YamlPane, SaveBar, useFileDraft, api, danger, section, h } from "../ui.jsx";
+import { typeSuggestions, pagesUsing, valuesToText, textToValues } from "./DataTab.jsx";
+
+export const COMPONENT_NAME = /^[a-z0-9-]+\/[a-z0-9-]+$/;
+export const SEMVER = /^\d+\.\d+\.\d+$/;
+export const PROP_TYPES = ["string", "number", "boolean", "text", "string[]", "number[]", "enum"];
+
+// Same naming as files.js pascalName (kept here so the tab has no server import).
+export const pascalName = name => String(name).split(/[^a-zA-Z0-9]+/).filter(Boolean).map(s => s[0].toUpperCase() + s.slice(1)).join("");
+
+// { type, optional, values } <-> registry notation like "enum[a,b]?" or "string?".
+export function propToNotation({ type, optional, values }) {
+  const base = type === "enum" ? `enum[${[].concat(values ?? []).join(",")}]` : type;
+  return optional ? `${base}?` : base;
+}
+export function notationToProp(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 { type: "enum", optional, values: m[1].split(",").map(v => v.trim()).filter(Boolean) };
+  return { type: PROP_TYPES.includes(s) ? s : "string", optional };
+}
+
+const semverKey = v => v.split(".").map(Number);
+export function latestVersion(versions) {
+  return Object.keys(versions ?? {}).filter(v => SEMVER.test(v)).sort((a, b) => {
+    const x = semverKey(a), y = semverKey(b);
+    return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
+  }).at(-1);
+}
+// Next minor of the latest version, as a suggestion for "+ version".
+export function nextVersion(versions) {
+  const l = latestVersion(versions);
+  if (!l) return "1.0.0";
+  const [a, b] = semverKey(l);
+  return `${a}.${b + 1}.0`;
+}
+export const newComponentEntry = name => ({ description: "", props: {}, versions: { "1.0.0": { impl: `./${pascalName(name)}.jsx` } } });
+
+// components/registry.yaml: components, what data they accept, their props and versions.
+export function ComponentsTab({ project, reload }) {
+  const file = useFileDraft("components/registry");
+  const [note, setNote] = useState(null), [info, setInfo] = useState(null), [open, setOpen] = useState(null);
+  const [fresh, setFresh] = useState([]); // added since load: scaffolded on the next Save
+  const reg = file.draft;
+  if (!reg) return null;
+  const names = Object.keys(reg);
+  const types = typeSuggestions(project.catalog, reg);
+
+  const add = name => {
+    if (!COMPONENT_NAME.test(name)) { setNote(`"${name}": use group/name with lowercase letters, digits and dashes`); return false; }
+    if (name in reg) { setNote(`component "${name}" already exists`); return false; }
+    setNote(null); setOpen(name); setFresh(f => [...f, name]);
+    file.update(d => { d[name] = newComponentEntry(name); });
+  };
+  const remove = async i => {
+    const name = names[i];
+    const used = await pagesUsing(project.pages, n => typeof n.ref === "string" && n.ref.split("@")[0] === name);
+    if (used.length) { setNote(`component "${name}" is used by page ${used.join(", ")}`); return; }
+    setNote(null); setFresh(f => f.filter(n => n !== name)); file.update(d => { delete d[name]; });
+  };
+  const save = async () => {
+    const r = await file.save();
+    if (!r.ok) return;
+    const todo = fresh.filter(n => n in reg); setFresh([]);
+    const made = [];
+    for (const name of todo) {
+      const s = await api("/api/scaffold/component", "POST", { name, props: reg[name].props ?? {}, container: !!reg[name].container });
+      if (s.created) made.push(`components/${pascalName(name)}.jsx`); else if (s.error) setNote(s.error);
+    }
+    if (made.length) setInfo(`created ${made.join(", ")}, open it to write the React`);
+    reload();
+  };
+  const set = (name, fn) => file.update(d => { fn(d[name]); });
+  const props = name => Object.entries(reg[name].props ?? {});
+  const setProp = (name, key, patch) => set(name, x => { x.props[key] = propToNotation({ ...notationToProp(x.props[key]), ...patch }); });
+
+  const addVersion = name => v => {
+    if (!SEMVER.test(v)) { setNote(`"${v}": use a version like 1.2.0`); return false; }
+    if (v in (reg[name].versions ?? {})) { setNote(`version ${v} already exists`); return false; }
+    const impl = reg[name].versions?.[latestVersion(reg[name].versions)]?.impl ?? `./${pascalName(name)}.jsx`;
+    setNote(null); set(name, x => { x.versions = { ...(x.versions ?? {}), [v]: { impl } }; });
+  };
+
+  const row = name => {
+    const e = reg[name];
+    return <div style={{ width: "100%" }}>
+      <button onClick={() => setOpen(open === name ? null : name)} style={{ border: "none", background: "none", cursor: "pointer", padding: 0 }}>{open === name ? "▾" : "▸"} <strong>{name}</strong></button>
+      <span style={{ color: "var(--pt-color-muted)", marginLeft: 8 }}>{e.container ? "container" : e.accepts}</span>
+      {open === name && <div style={{ padding: "8px 0 0 16px" }}>
+        <Field label="description" value={e.description} onChange={v => set(name, x => { x.description = v; })} />
+        <label style={{ display: "flex", flexDirection: "column", gap: 4, fontSize: 13, marginBottom: 12 }}>accepts
+          <input list="pt-component-types" value={e.accepts ?? ""} disabled={!!e.container} onChange={ev => set(name, x => { if (ev.target.value) x.accepts = ev.target.value; else delete x.accepts; })} style={{ maxWidth: 320 }} />
+        </label>
+        <div style={{ marginBottom: 12 }}>
+          <Toggle label="container (has children, accepts no data)" checked={e.container} onChange={on => set(name, x => { if (on) { x.container = true; delete x.accepts; } else delete x.container; })} />
+        </div>
+        <div style={{ marginBottom: 12 }}>
+          <span style={{ fontSize: 13 }}>props</span>
+          <ListEditor items={props(name)} addLabel="+ prop" addPlaceholder="prop name"
+            onAdd={p => {
+              if (!/^[A-Za-z_$][\w$]*$/.test(p) || ["data", "names", "__pt"].includes(p)) { setNote(`"${p}": not a valid prop name`); return false; }
+              if (p in (e.props ?? {})) { setNote(`prop "${p}" already exists`); return false; }
+              setNote(null); set(name, x => { x.props = { ...(x.props ?? {}), [p]: "string?" }; });
+            }}
+            onRemove={i => set(name, x => { delete x.props[props(name)[i][0]]; })}
+            render={([p, notation]) => { const t = notationToProp(notation); return <>
+              <strong style={{ minWidth: 100 }}>{p}</strong>
+              <select value={t.type} onChange={ev => setProp(name, p, { type: ev.target.value, values: ev.target.value === "enum" ? (t.values ?? []) : undefined })}>
+                {PROP_TYPES.map(o => <option key={o} value={o}>{o}</option>)}
+              </select>
+              <Toggle label="optional" checked={t.optional} onChange={on => setProp(name, p, { optional: on })} />
+              {t.type === "enum" && <input value={valuesToText(t.values)} placeholder="values, comma separated" onChange={ev => setProp(name, p, { values: textToValues(ev.target.value) })} style={{ width: 200 }} />}
+              <code style={{ color: "var(--pt-color-muted)" }}>{notation}</code>
+            </>; }} />
+        </div>
+        <div>
+          <span style={{ fontSize: 13 }}>versions</span>
+          <ListEditor items={Object.entries(e.versions ?? {})} addLabel="+ version" addPlaceholder={nextVersion(e.versions)} onAdd={addVersion(name)}
+            render={([v, x]) => <><strong style={{ minWidth: 100 }}>{v}</strong><code>{x?.impl}</code></>} />
+        </div>
+      </div>}
+    </div>;
+  };
+
+  return <div style={{ display: "flex", flexDirection: "column", minHeight: "calc(100vh - 90px)" }}>
+    <main style={{ padding: 16, maxWidth: 800, width: "100%", boxSizing: "border-box", margin: "0 auto", flex: 1 }}>
+      <datalist id="pt-component-types">{types.map(t => <option key={t} value={t} />)}</datalist>
+      {note && <p style={{ ...danger, fontSize: 13 }}>{note}</p>}
+      {info && <p style={{ fontSize: 13 }}>{info}</p>}
+      <div style={section}>
+        <h3 style={h}>Components</h3>
+        <ListEditor items={names} addLabel="+ component" addPlaceholder="group/name, e.g. kpi/delta" onAdd={add} onRemove={remove} render={row} />
+      </div>
+    </main>
+    <div style={{ position: "sticky", bottom: 0, background: "var(--pt-color-background)" }}>
+      <SaveBar file={{ ...file, save, dirty: file.dirty || fresh.length > 0 }} />
+      <YamlPane name="registry" value={reg} />
+    </div>
+  </div>;
+}

package/src/studio/tabs/DataTab.jsx

@@ -0,0 +1,123 @@
+import { useState } from "react";
+import { Field, Toggle, ListEditor, YamlPane, SaveBar, useFileDraft, api, danger, section, h } from "../ui.jsx";
+
+export const SOURCE_NAME = /^[a-z0-9_.]+$/;
+export const BASE_TYPES = ["money", "number", "string", "timeseries<money>", "timeseries<number>", "table<any>", "list<task>"];
+
+// Suggestions for returns/accepts: the base list plus every type already used in catalog and registry.
+export function typeSuggestions(catalog = {}, registry = {}) {
+  const used = [...Object.values(catalog ?? {}).map(s => s?.returns), ...Object.values(registry ?? {}).map(c => c?.accepts)];
+  return [...new Set([...BASE_TYPES, ...used.filter(t => typeof t === "string" && t)])];
+}
+
+// roles: ["*"] means everyone; toggling a single role drops "*".
+export function rolesToggle(roles, role, on) {
+  const cur = [].concat(roles ?? []).filter(r => r !== "*");
+  if (role === "*") return on ? ["*"] : [];
+  return on ? [...new Set([...cur, role])] : cur.filter(r => r !== role);
+}
+
+export const valuesToText = values => [].concat(values ?? []).join(", ");
+export const textToValues = text => String(text).split(",").map(v => v.trim()).filter(Boolean);
+
+// Every node of a page tree (layout plus children, either array or named map).
+export function* walkNodes(node) {
+  if (!node || typeof node !== "object") return;
+  yield node;
+  const kids = node.children;
+  for (const c of Array.isArray(kids) ? kids : Object.values(kids ?? {})) yield* walkNodes(c);
+}
+export const sourcesUsedIn = page => [...walkNodes(page?.layout)].map(n => n.data?.source).filter(Boolean);
+
+// Pages (by slug) whose tree matches pred(node); reads every page file.
+export async function pagesUsing(slugs, pred) {
+  const hits = [];
+  for (const slug of slugs ?? []) {
+    const r = await api(`/api/files/pages/${slug}`);
+    if ([...walkNodes(r.value?.layout)].some(pred)) hits.push(slug);
+  }
+  return hits;
+}
+
+// data-catalog.yaml: typed data sources, their params and the roles allowed to read them.
+export function DataTab({ project, reload }) {
+  const file = useFileDraft("data-catalog");
+  const [note, setNote] = useState(null), [info, setInfo] = useState(null), [open, setOpen] = useState(null);
+  const [fresh, setFresh] = useState([]); // added since load: scaffolded on the next Save
+  const c = file.draft;
+  if (!c) return null;
+  const names = Object.keys(c), roles = project.manifest?.roles ?? [];
+  const types = typeSuggestions(c, project.registry);
+
+  const add = name => {
+    if (!SOURCE_NAME.test(name)) { setNote(`"${name}": use lowercase letters, digits, dots and underscores`); return false; }
+    if (name in c) { setNote(`source "${name}" already exists`); return false; }
+    setNote(null); setOpen(name); setFresh(f => [...f, name]);
+    file.update(d => { d[name] = { description: "", returns: "", roles: ["*"] }; });
+  };
+  const remove = async i => {
+    const name = names[i];
+    const used = await pagesUsing(project.pages, n => n.data?.source === name);
+    if (used.length) { setNote(`source "${name}" is used by page ${used.join(", ")}`); return; }
+    setNote(null); setFresh(f => f.filter(n => n !== name)); file.update(d => { delete d[name]; });
+  };
+  const save = async () => {
+    const r = await file.save();
+    if (!r.ok) return;
+    let stub = false;
+    const todo = fresh.filter(n => n in c); setFresh([]);
+    for (const name of todo) {
+      const s = await api("/api/scaffold/source", "POST", { name });
+      if (s.created) stub = true; else if (s.error) setNote(s.error);
+    }
+    if (stub) setInfo("stub added to data/sources.mjs");
+    reload();
+  };
+  const set = (name, fn) => file.update(d => { fn(d[name]); });
+  const params = name => Object.entries(c[name].params ?? {});
+
+  const row = name => {
+    const s = c[name], everyone = [].concat(s.roles ?? []).includes("*");
+    return <div style={{ width: "100%" }}>
+      <button onClick={() => setOpen(open === name ? null : name)} style={{ border: "none", background: "none", cursor: "pointer", padding: 0 }}>{open === name ? "▾" : "▸"} <strong>{name}</strong></button>
+      <span style={{ color: "var(--pt-color-muted)", marginLeft: 8 }}>{s.returns}</span>
+      {open === name && <div style={{ padding: "8px 0 0 16px" }}>
+        <Field label="description" value={s.description} onChange={v => set(name, x => { x.description = v; })} />
+        <label style={{ display: "flex", flexDirection: "column", gap: 4, fontSize: 13, marginBottom: 12 }}>returns
+          <input list="pt-data-types" value={s.returns ?? ""} onChange={e => set(name, x => { x.returns = e.target.value; })} style={{ maxWidth: 320 }} />
+        </label>
+        <div style={{ marginBottom: 12 }}>
+          <span style={{ fontSize: 13 }}>params</span>
+          <ListEditor items={params(name)} addLabel="+ param" addPlaceholder="param name"
+            onAdd={p => { if (!/^[A-Za-z_][\w]*$/.test(p)) { setNote(`"${p}": not a valid param name`); return false; } set(name, x => { x.params = { ...(x.params ?? {}), [p]: [] }; }); }}
+            onRemove={i => set(name, x => { delete x.params[params(name)[i][0]]; if (!Object.keys(x.params).length) delete x.params; })}
+            render={([p, vals]) => <>
+              <strong style={{ minWidth: 100 }}>{p}</strong>
+              <input value={valuesToText(vals)} placeholder="allowed values, comma separated" onChange={e => set(name, x => { x.params[p] = textToValues(e.target.value); })} style={{ width: 260 }} />
+            </>} />
+        </div>
+        <div style={{ display: "flex", gap: 8, flexWrap: "wrap", alignItems: "center" }}>
+          <span style={{ color: "var(--pt-color-muted)", fontSize: 13 }}>roles</span>
+          <Toggle label="everyone (*)" checked={everyone} onChange={on => set(name, x => { x.roles = rolesToggle(x.roles, "*", on); })} />
+          {!everyone && roles.map(r => <Toggle key={r} label={r} checked={[].concat(s.roles ?? []).includes(r)} onChange={on => set(name, x => { x.roles = rolesToggle(x.roles, r, on); })} />)}
+        </div>
+      </div>}
+    </div>;
+  };
+
+  return <div style={{ display: "flex", flexDirection: "column", minHeight: "calc(100vh - 90px)" }}>
+    <main style={{ padding: 16, maxWidth: 800, width: "100%", boxSizing: "border-box", margin: "0 auto", flex: 1 }}>
+      <datalist id="pt-data-types">{types.map(t => <option key={t} value={t} />)}</datalist>
+      {note && <p style={{ ...danger, fontSize: 13 }}>{note}</p>}
+      {info && <p style={{ fontSize: 13 }}>{info}</p>}
+      <div style={section}>
+        <h3 style={h}>Data sources</h3>
+        <ListEditor items={names} addLabel="+ source" addPlaceholder="name, e.g. sales.total" onAdd={add} onRemove={remove} render={row} />
+      </div>
+    </main>
+    <div style={{ position: "sticky", bottom: 0, background: "var(--pt-color-background)" }}>
+      <SaveBar file={{ ...file, save, dirty: file.dirty || fresh.length > 0 }} />
+      <YamlPane name="data-catalog" value={c} />
+    </div>
+  </div>;
+}