@chalky/chalky 0.1.3 → 0.1.5

package/{app/extensions/frames → agent/extensions/frame}/browser.js

@@ -1,12 +1,12 @@
-// Browser half of the frames extension (Python's frames.js, unchanged but for this header): a frame tool in the palette (a dashed box). While it is on, drag on the
+// The page side of the frame extension: a frame tool in the palette (a dashed box). While it is on, drag on the
 // main space to lay down a frame: a dashed box with a field for what goes there (Enter finishes it). While the
 // tool is on, an Implement button (a hammer with the number of frames in a bubble, in the row under the tool)
-// sends every unsent frame that has words, together (frames_send, to the agent picked in the chat); while it is
-// off, the bubble sits on the tool itself, so waiting frames still show. Until then, a frame's corner resizes it, like a surface's (frame_place).
-// Sent frames stay as they are, marked waiting, until an agent renders a surface with their id (index.ts
+// sends every unsent frame that has words, together (frame_send, to the agent picked in the chat); while it is
+// off, the bubble sits on the tool itself, so waiting frames still show. Until then, a frame's corner resizes it, like a card's (frame_place).
+// Sent frames stay as they are, marked waiting, until an agent renders a card with their id (index.ts
 // then drops them); ✕ on a frame, or the eraser passing over an unsent one ("erase" event), removes it.
 // Esc or the tool turns drawing off.
-// Frames live in the main space (slot "top"), in main-space px, so they scroll with the surfaces.
+// Frames live in the main space (slot "top"), in main-space px, so they scroll with the cards.
 export default async function (page) {
   const area = page.slot("top");
   const style = document.createElement("style");
@@ -31,15 +31,17 @@ export default async function (page) {
                                 border: solid var(--muted); border-width: 0 2px 2px 0; border-radius: 0 0 4px 0; cursor: nwse-resize; opacity: 0; }
     #top .frame:hover .frame-resize { opacity: 1; }
     #top .frame.sent .frame-resize { display: none; }
-    #status button.frames-send { color: var(--accent); }`;
+    #status button.frame-send { color: var(--accent); }`;
   document.head.append(style);
 
   const button = document.createElement("button");
   button.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="5" width="17" height="14" rx="2" stroke-dasharray="3 2.5"/></svg>`;
+  button.dataset.name = "frames";  // names an agent's pen can point at (doodle_mark on: {element: "frames"})
   button.title = "Frames: drag boxes on the page and write what goes in each, then Implement them together (Esc to stop)";
   button.append(Object.assign(document.createElement("span"), { className: "badge" }));  // frames waiting, while the tool is off
   const send = document.createElement("button");
-  send.className = "frames-send";
+  send.className = "frame-send";
+  send.dataset.name = "implement";
   send.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m15 12-8.4 8.4a2.1 2.1 0 0 1-3-3L12 9"/><path d="m18 15 4-4"/>` +
     `<path d="m21.5 11.5-1.9-1.9a2 2 0 0 1-.6-1.4V7l-2.3-2.3a6 6 0 0 0-4.2-1.7H9l.9.8A6.2 6.2 0 0 1 12 8.4V10l2 2h1.2a2 2 0 0 1 1.4.6l1.9 1.9"/></svg>` +
     `<span class="badge"></span>`;  // the hammer: build these
@@ -57,23 +59,25 @@ export default async function (page) {
     button.classList.toggle("on", v);
     area.classList.toggle("framing", v);
     showReady();
-    if (v) document.dispatchEvent(new CustomEvent("tool-on", { detail: "frames" }));  // the other tools turn off
+    if (v) document.dispatchEvent(new CustomEvent("tool-on", { detail: "frame" }));  // the other tools turn off
   };
   button.onclick = () => setOn(!on);
-  document.addEventListener("tool-on", (e) => { if (on && e.detail !== "frames") setOn(false); });  // one tool at a time
+  document.addEventListener("tool-on", (e) => { if (on && e.detail !== "frame") setOn(false); });  // one tool at a time
   document.addEventListener("keydown", (e) => { if (e.key === "Escape") setOn(false); });
   send.onclick = () => {
     for (const flush of Object.values(timers)) { clearTimeout(flush.t); flush(); }  // text still waiting on the typing pause goes first
-    page.send({ type: "frames_send", to: document.getElementById("to")?.value });
+    page.send({ type: "frame_send", to: document.getElementById("to")?.value, board: board() });
   };
+  const board = () => Number(document.body.dataset.board) || 1;  // the board shown (board/): frames are drawn and sent there
+  document.addEventListener("board", () => setTimeout(() => render(shown)));  // after the switch: count that board's
 
-  const inMain = (x, y) => {  // window px -> main-space px (as point.js)
+  const inMain = (x, y) => {  // window px -> main-space px (as note/browser.js)
     const m = area.getBoundingClientRect();
     return { x: Math.round(x - m.left + area.scrollLeft), y: Math.round(y - m.top + area.scrollTop) };
   };
   const put = (box, f) => Object.assign(box.style, { left: `${f.x}px`, top: `${f.y}px`, width: `${f.width}px`, height: `${f.height}px` });
 
-  // Drawing: on the main space, over empty space or surfaces, but not on a frame (that is for typing).
+  // Drawing: on the main space, over empty space or cards, but not on a frame (that is for typing).
   let start = null, ghost = null, focusNew = false;
   area.addEventListener("mousedown", (e) => {
     if (!on || e.button !== 0 || e.target.closest(".frame")) return;
@@ -83,7 +87,7 @@ export default async function (page) {
     ghost = Object.assign(document.createElement("div"), { className: "frame drawing" });
     area.append(ghost);
   }, true);
-  area.addEventListener("click", (e) => { if (on && !e.target.closest(".frame")) e.stopPropagation(); }, true);  // surfaces don't react
+  area.addEventListener("click", (e) => { if (on && !e.target.closest(".frame")) e.stopPropagation(); }, true);  // cards don't react
   window.addEventListener("mousemove", (e) => {
     if (!start) return;
     const p = inMain(e.clientX, e.clientY);
@@ -94,7 +98,7 @@ export default async function (page) {
     const f = { x: parseInt(ghost.style.left), y: parseInt(ghost.style.top), width: parseInt(ghost.style.width), height: parseInt(ghost.style.height) };
     ghost.remove();
     start = ghost = null;
-    if (f.width >= 40 && f.height >= 30) { focusNew = true; page.send({ type: "frame_add", ...f }); }  // a click or a slip is not a frame
+    if (f.width >= 40 && f.height >= 30) { focusNew = true; page.send({ type: "frame_add", ...f, board: board() }); }  // a click or a slip is not a frame
   });
 
   const boxes = {};  // id -> its box on the page
@@ -103,7 +107,7 @@ export default async function (page) {
   document.addEventListener("erase", (e) => {  // the doodle eraser at {x, y}, main px: unsent frames under it go
     const p = e.detail;
     for (const [id, f] of Object.entries(shown)) {
-      if (f.sent || p.x < f.x || p.x > f.x + f.width || p.y < f.y || p.y > f.y + f.height) continue;
+      if (f.sent || (f.board ?? 1) !== board() || p.x < f.x || p.x > f.x + f.width || p.y < f.y || p.y > f.y + f.height) continue;
       delete shown[id];  // once, though the eraser keeps moving over it
       page.send({ type: "frame_remove", id });
     }
@@ -134,17 +138,18 @@ export default async function (page) {
         newest = box;
       }
       put(box, f);
+      box.dataset.board = f.board ?? 1;  // board/ shows it on its board
       box.classList.toggle("sent", f.sent);
       const text = box.querySelector("textarea");
       text.readOnly = f.sent;
       if (document.activeElement !== text) text.value = f.text;
     }
     if (focusNew && newest) { focusNew = false; newest.querySelector("textarea").focus(); }
-    ready = Object.values(frames).filter((f) => !f.sent && f.text.trim()).length;
+    ready = Object.values(frames).filter((f) => !f.sent && f.text.trim() && (f.board ?? 1) === board()).length;
     showReady();
     send.title = `Implement: send ${ready} frame${ready > 1 ? "s" : ""} to the agent to build, together`;
   }
-  function resize(box, id, e) {  // drag the corner (as ui.js does for surfaces); on release the new size is saved
+  function resize(box, id, e) {  // drag the corner (as card/browser.js does for cards); on release the new size is saved
     e.preventDefault();
     const corner = e.currentTarget, x = box.offsetLeft, y = box.offsetTop, w0 = box.offsetWidth, h0 = box.offsetHeight;
     corner.setPointerCapture(e.pointerId);
@@ -158,6 +163,6 @@ export default async function (page) {
       if (place) page.send({ type: "frame_place", id, ...place });
     };
   }
-  page.on("frames", (ev) => render(ev.frames));
-  try { render(await (await fetch("/frames")).json()); } catch {}
+  page.on("frame", (ev) => render(ev.frames));
+  try { render(await (await fetch("/frame")).json()); } catch {}
 }

package/agent/extensions/frame/guide.md

@@ -0,0 +1,3 @@
+# Wireframes
+A message "[frames on the page]" is boxes the user laid out, each saying what goes there: read README.md before you
+handle one.

package/agent/extensions/frame/index.ts

@@ -0,0 +1,81 @@
+// Frames: wireframes the user lays out for the agents to fill. browser.js adds a tool to the palette: drag boxes on the main space, type in each what goes there,
+// then press Implement. All the frames go together, as one message, to the agent picked in the chat (else agent1),
+// so it sees the whole layout and decides how to split the work (alone, or with helpers: README.md, not code).
+// A frame is {x, y, width, height, text, sent, to?, board} (main-space px, where card_show's place puts a card;
+// board: the one it was drawn on, board/; Implement sends the frames of the board shown), with an
+// id (frame-1, frame-2, ...: never reused). An agent fills it with card_show(card="frame-1", place=<its place>);
+// when that card appears (a card watcher, host.api.card.watch), the frame is done and its dashed box goes. The user
+// can remove a frame (its ✕); if it was sent, its agent is told. Until a frame is sent, its corner resizes it.
+//   GET /frame              {id: frame}
+//   page messages           frame_add {x, y, width, height, board}, frame_place {id, x, y, width, height}, frame_text {id, text},
+//                           frame_remove {id}, frame_send {to, board}
+//   event "frame"           {frames: {id: frame}} to every open page, when they changed
+// Saved in data/frame.json as {last: <last id number>, frames: {id: frame}}; shared by every agent (host.shared).
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+const FILE = path.join(host.data, "frame.json");
+if (!host.shared.has("frame"))
+  host.shared.set("frame", fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 0, frames: {} });
+const saved = host.shared.get("frame");  // {last, frames}
+const frames: Record<string, any> = saved.frames;
+
+function changed() {
+  fs.writeFileSync(FILE + ".tmp", JSON.stringify(saved));
+  fs.renameSync(FILE + ".tmp", FILE);
+  host.broadcast("frame", { frames });
+}
+const box = (msg: any, f: any = {}) => Object.fromEntries(["x", "y", "width", "height"].map((k) => [k, Math.round(Number(msg[k] ?? f[k] ?? 0))]));
+const place = (f: any) => JSON.stringify({ x: f.x, y: f.y, width: f.width, height: f.height });
+
+export default function (pi: ExtensionAPI) {
+
+  // a frame is done when a card with its id appears (after all extensions loaded: the card one may come later)
+  pi.on("session_start", () => {
+    host.api.card?.watch("frame", (sid: string) => {
+      if (frames[sid] && host.shared.get("card")?.cards[sid]) { delete frames[sid]; changed(); }
+    });
+    host.api.board?.onRemove("frame", (n: number) => {  // a removed board (board/) takes its frames with it
+      const ids = Object.keys(frames).filter((id) => (frames[id].board ?? 1) === n);
+      const gone = ids.map((id) => ({ owner: frames[id].sent ? frames[id].to : undefined, what: `frame ${id}` }));
+      for (const id of ids) delete frames[id];
+      if (ids.length) changed();
+      return gone;
+    });
+  });
+
+  host.routes.set("/frame", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(frames)));
+
+  host.pageHandlers.set("frame", (msg: any) => {
+    const f = frames[msg.id], team = host.api.team;
+    if (msg.type === "frame_add") {
+      frames[`frame-${++saved.last}`] = { ...box(msg), text: "", sent: false, board: Number(msg.board) || 1 };
+      changed();
+    } else if (msg.type === "frame_place" && f && !f.sent) {
+      Object.assign(f, box(msg, f));
+      changed();
+    } else if (msg.type === "frame_text" && f && !f.sent) {
+      f.text = String(msg.text ?? "");
+      changed();
+    } else if (msg.type === "frame_remove" && f) {
+      delete frames[msg.id];
+      changed();
+      if (f.sent) team?.send("user", f.to, `[frames on the page] the user removed ${msg.id} ("${f.text}"): don't fill it.`, true);
+    } else if (msg.type === "frame_send" && team) {
+      const to = msg.to in team.status() ? msg.to : "agent1";
+      const board = Number(msg.board) || 1;  // the board shown: its frames only (the user sees no others)
+      const ready = Object.entries(frames).filter(([, f]: any) => !f.sent && f.text.trim() && (f.board ?? 1) === board);
+      if (!ready.length) return;
+      for (const [, f] of ready as any) Object.assign(f, { sent: true, to });
+      changed();
+      const lines = [`[frames on the page] the user laid out ${ready.length} frame${ready.length > 1 ? "s" : ""} on board ${board} to fill:`,
+        ...ready.map(([id, f]: any) => `  ${id}: "${f.text}" · place=${place(f)}`),
+        `  Fill each with card_show(card=<its id>, place=<its place>, board=${board}, ...); its dashed box goes when it appears.`];
+      const waiting = Object.keys(frames).filter((id) => frames[id].sent && !ready.some(([r]) => r === id));
+      if (waiting.length) lines.push(`  Sent before and not filled yet: ${waiting.join(", ")}.`);
+      team.send("user", to, lines.join("\n"));
+    }
+  });
+}

package/{app/extensions/ui_history → agent/extensions/history}/browser.js

@@ -1,25 +1,25 @@
-// Browser half of the ui_history plugin: undo, redo and rewind the surfaces.
+// The page side of the history extension: undo, redo and rewind the cards.
 //   Ctrl+Z / ⌘Z: undo.  Ctrl+Shift+Z / ⌘⇧Z / Ctrl+Y: redo.  (Not while typing in a field: that undoes the typing.)
 //   Hold Alt (Option) and drag sideways anywhere: scrub along the history; let go to stay there.
 //   Doing something new after going back starts a branch; a note offers to bring the other one back.
-// It only sends messages (ui_undo, ui_redo, ui_goto); the server puts the surfaces back and ui.js redraws them.
+// It only sends messages (history_undo, history_redo, history_goto); the server puts the cards back and the card extension redraws them.
 const CSS = `
-  #ui-history-bar { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex;
+  #history-bar { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex;
     flex-direction: column; align-items: center; gap: 6px; max-width: calc(100vw - 32px); padding: 8px 14px; border-radius: 12px;
     font-size: 12px; color: #fff; background: rgba(29, 29, 31, .92); pointer-events: none; }
-  #ui-history-bar .ticks { display: flex; gap: 2px; flex-wrap: wrap; justify-content: center; }
-  #ui-history-bar .ticks i { width: 6px; height: 14px; border-radius: 2px; background: #fff; opacity: .3; }
-  #ui-history-bar .ticks i.now { opacity: 1; background: #f4d35e; }
-  #ui-history-bar .ticks i.ahead { opacity: .12; }
-  #ui-history-toast { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex; gap: 10px;
+  #history-bar .ticks { display: flex; gap: 2px; flex-wrap: wrap; justify-content: center; }
+  #history-bar .ticks i { width: 6px; height: 14px; border-radius: 2px; background: #fff; opacity: .3; }
+  #history-bar .ticks i.now { opacity: 1; background: #f4d35e; }
+  #history-bar .ticks i.ahead { opacity: .12; }
+  #history-toast { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex; gap: 10px;
     align-items: center; padding: 8px 14px; border-radius: 12px; font-size: 13px; color: #fff; background: rgba(29, 29, 31, .92); }
-  #ui-history-toast button { font: inherit; color: inherit; background: none; border: 1px solid currentColor; border-radius: 8px;
+  #history-toast button { font: inherit; color: inherit; background: none; border: 1px solid currentColor; border-radius: 8px;
     padding: 2px 10px; cursor: pointer; }`;
 
 export default function (page) {
-  document.head.insertAdjacentHTML("beforeend", `<style id="ui-history-css">${CSS}</style>`);
-  const bar = Object.assign(document.createElement("div"), { id: "ui-history-bar", hidden: true });
-  const toastEl = Object.assign(document.createElement("div"), { id: "ui-history-toast", hidden: true });
+  document.head.insertAdjacentHTML("beforeend", `<style id="history-css">${CSS}</style>`);
+  const bar = Object.assign(document.createElement("div"), { id: "history-bar", hidden: true });
+  const toastEl = Object.assign(document.createElement("div"), { id: "history-toast", hidden: true });
   document.body.append(bar, toastEl);
   let toastTimer;
   function toast(text, button, onclick) {
@@ -35,8 +35,8 @@ export default function (page) {
   document.addEventListener("keydown", (e) => {
     if (!(e.ctrlKey || e.metaKey) || typing(e)) return;
     const k = e.key.toLowerCase();
-    if (k === "z" && !e.shiftKey) { e.preventDefault(); page.send({ type: "ui_undo" }); }
-    else if ((k === "z" && e.shiftKey) || k === "y") { e.preventDefault(); page.send({ type: "ui_redo" }); }
+    if (k === "z" && !e.shiftKey) { e.preventDefault(); page.send({ type: "history_undo" }); }
+    else if ((k === "z" && e.shiftKey) || k === "y") { e.preventDefault(); page.send({ type: "history_redo" }); }
   });
 
   // {x0, x, line, start, i} while Alt-dragging. It starts at the press, before the history has come (line: null till
@@ -57,7 +57,7 @@ export default function (page) {
     const i = Math.max(0, Math.min(scrub.line.length - 1, scrub.start + Math.round((scrub.x - scrub.x0) / step)));
     if (i === scrub.i) return;
     scrub.i = i;
-    page.send({ type: "ui_goto", step: scrub.line[i].n });
+    page.send({ type: "history_goto", step: scrub.line[i].n });
     showBar();
   }
   document.addEventListener("pointerdown", async (e) => {
@@ -65,7 +65,7 @@ export default function (page) {
     e.preventDefault(); e.stopPropagation();
     const me = scrub = { x0: e.clientX, x: e.clientX, line: null };
     let history;
-    try { history = await (await fetch("/ui-api/history")).json(); } catch { if (scrub === me) scrub = null; return; }
+    try { history = await (await fetch("/history")).json(); } catch { if (scrub === me) scrub = null; return; }
     if (scrub !== me) return;  // let go before the history came: nothing to do
     me.line = history.line;
     me.start = me.i = history.line.findIndex((s) => s.n === history.at);
@@ -89,9 +89,9 @@ export default function (page) {
     if (ahead) toast("Gone back. Do something new to branch from here, or Ctrl+Shift+Z to come forward.");
   }
 
-  page.on("ui_history", (ev) => {
+  page.on("history", (ev) => {
     if (ev.event === "moved" && !scrub) toast(`Back to just after: ${ev.what}`);
     if (ev.event === "branched") toast("You branched from an earlier moment. The other version is kept.", "Bring it back",
-      () => page.send({ type: "ui_goto", step: ev.tip }));
+      () => page.send({ type: "history_goto", step: ev.tip }));
   });
 }

package/{app/extensions/ui_history → agent/extensions/history}/index.ts

@@ -1,23 +1,22 @@
-// Every state of the UI surfaces, kept: undo, redo and rewind for the user (port of the Python ui_history plugin; the
-// browser half, browser.js, is its ui_history.js). After each change (ui.ts's change() with words for it, from the user or
-// an agent) it saves a step: a full copy of all surfaces, design and data. Steps form a tree: each has a parent, so
-// undoing and then doing something new starts a branch and loses nothing; redo follows the newest branch.
-//   Page messages:  ui_undo, ui_redo, ui_goto {step}
-//   Server -> page: {"type": "ui_history", "event": "moved", "at", "what"}  after undo/redo/goto
-//                   {"type": "ui_history", "event": "branched", "tip"}       a change made after undoing
-//   GET /ui-api/history: {"at", "line": [{"n", "ts", "by", "what"}]}, the current line (root to newest tip)
-// Kept in state/ui-history.jsonl (one step per line), for HISTORY_KEEP_DAYS (default 7). Older steps are dropped at
+// Every state of the cards, kept: undo, redo and rewind for the user (browser.js: the keys and the bar). After each
+// change (the card extension's change() with words for it, from the user or an agent) it saves a step: a full copy
+// of all cards, design and data. Steps form a tree: each has a parent, so undoing and then doing something new
+// starts a branch and loses nothing; redo follows the newest branch.
+//   page messages   history_undo, history_redo, history_goto {step}
+//   page event      "history" {event: "moved", at, what} after undo/redo/goto; {event: "branched", tip} a change made after undoing
+//   GET /history    {"at", "line": [{"n", "ts", "by", "what"}]}, the current line (root to newest tip)
+// Kept in data/history.jsonl (one step per line), for HISTORY_KEEP_DAYS (default 7). Older steps are dropped at
 // start and every PRUNE_EVERY steps; the current step is always kept.
-// Undo puts back the surfaces only: code (components, apps) has its own history (the versions extension).
+// Undo puts back the cards only: agent/ and built/ have their own history (the version extension).
 // pi has no undo for this: /tree and /fork rewind one agent's conversation, not the shared page.
-// It watches the ui extension's changes (host.api.ui.watch); others reach it as host.api.uiHistory. Not pi.events:
+// It watches the card extension's changes (host.api.card.watch); others reach it as host.api.history. Not pi.events:
 // each agent has its own bus, and a reload keeps the old listeners on it, so every change would be recorded again.
 import fs from "node:fs";
 import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const FILE = path.join(host.state, "ui-history.jsonl");
+const FILE = path.join(host.data, "history.jsonl");
 const KEEP_DAYS = Number(process.env.HISTORY_KEEP_DAYS ?? 7);
 const PRUNE_EVERY = 200;
 
@@ -25,12 +24,12 @@ const PRUNE_EVERY = 200;
 // "data" last, one just drawn has it in the middle)
 const sorted = (v: any) => JSON.stringify(v, (_k, x) => x && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort()) : x);
 
-type Step = { n: number, parent: number | null, ts: number, by: string, what: string, surfaces: Record<string, any> };
+type Step = { n: number, parent: number | null, ts: number, by: string, what: string, cards: Record<string, any> };
 
 class History {
   steps = new Map<number, Step>();
-  at: number | null = null;  // the step the surfaces are at now
-  constructor(public ui: any) {
+  at: number | null = null;  // the step the cards are at now
+  constructor(public cards: any) {
     if (fs.existsSync(FILE))
       for (const line of fs.readFileSync(FILE, "utf8").split("\n").filter(Boolean)) {
         const entry = JSON.parse(line);
@@ -39,19 +38,19 @@ class History {
       }                                                                // missed this: after a goto, a restart went back there)
     if (this.at === null || !this.steps.has(this.at)) this.at = this.steps.size ? Math.max(...this.steps.keys()) : null;
     this.prune();
-    if (this.at === null || sorted(this.steps.get(this.at)!.surfaces) !== sorted(ui.surfaces))
-      this.add("start", "the surfaces as loaded");  // first start, or the files changed while we were away
+    if (this.at === null || sorted(this.steps.get(this.at)!.cards) !== sorted(cards.cards))
+      this.add("start", "the cards as loaded");  // first start, or the files changed while we were away
   }
   write(entry: object) { fs.appendFileSync(FILE, JSON.stringify(entry) + "\n"); }
   add(by: string, what: string) {  // a new step after the current one; tells the pages if it left a branch behind
     const left = this.children(this.at).length ? this.tip(this.at!) : null;
     const n = this.steps.size ? Math.max(...this.steps.keys()) + 1 : 0;
-    const step = { n, parent: this.at, ts: Date.now() / 1000, by, what, surfaces: this.ui.snapshot() };
+    const step = { n, parent: this.at, ts: Date.now() / 1000, by, what, cards: this.cards.snapshot() };
     this.steps.set(n, step);
     this.at = n;
     this.write(step);
     if (n % PRUNE_EVERY === 0) this.prune();
-    if (left !== null) host.broadcast("ui_history", { event: "branched", tip: left });
+    if (left !== null) host.broadcast("history", { event: "branched", tip: left });
   }
   children(n: number | null) { return [...this.steps.values()].filter((s) => s.parent === n).map((s) => s.n).sort((a, b) => a - b); }
   tip(n: number) {  // follow the newest child down to the end of the line
@@ -69,8 +68,8 @@ class History {
     if (!this.steps.has(n) || n === this.at) return;
     this.at = n;
     this.write({ at: n });
-    this.ui.restore(this.steps.get(n)!.surfaces);
-    host.broadcast("ui_history", { event: "moved", at: n, what: this.steps.get(n)!.what });
+    this.cards.restore(this.steps.get(n)!.cards);
+    host.broadcast("history", { event: "moved", at: n, what: this.steps.get(n)!.what });
   }
   prune() {  // drop steps older than KEEP_DAYS (never the current one), then rewrite the file
     const cutoff = Date.now() / 1000 - KEEP_DAYS * 86400;
@@ -84,26 +83,26 @@ class History {
 }
 
 export default function (pi: ExtensionAPI) {
-  // made once all of an agent's extensions are loaded (pi loads them in folder order, not by name, so ui and its
-  // surfaces may come after this file); the first agent's session_start makes it, at startup, before any change
+  // made once all of an agent's extensions are loaded (pi loads them in folder order, not by name, so the card
+  // extension may come after this file); the first agent's session_start makes it, at startup, before any change
   pi.on("session_start", () => {
-    if (!host.shared.has("ui-history")) host.shared.set("ui-history", new History(host.shared.get("ui")));
-    host.api.uiHistory = host.shared.get("ui-history");
-    host.api.ui?.watch("ui_history", (_sid: string, by?: string, what?: string) => { if (what) host.api.uiHistory.add(by, what); });
+    if (!host.shared.has("history")) host.shared.set("history", new History(host.shared.get("card")));
+    host.api.history = host.shared.get("history");
+    host.api.card?.watch("history", (_id: string, by?: string, what?: string) => { if (what) host.api.history.add(by, what); });
   });
-  const shared = (): History | undefined => host.shared.get("ui-history");
+  const shared = (): History | undefined => host.shared.get("history");
 
-  host.pageHandlers.set("ui_history", (msg: any) => {
+  host.pageHandlers.set("history", (msg: any) => {
     const history = shared();
     if (!history) return;
     const now = history.at === null ? undefined : history.steps.get(history.at);
-    if (msg.type === "ui_undo" && now && now.parent !== null) history.goto(now.parent);
-    else if (msg.type === "ui_redo") { const kids = history.children(history.at); if (kids.length) history.goto(kids.at(-1)!); }
-    else if (msg.type === "ui_goto") history.goto(msg.step);
+    if (msg.type === "history_undo" && now && now.parent !== null) history.goto(now.parent);
+    else if (msg.type === "history_redo") { const kids = history.children(history.at); if (kids.length) history.goto(kids.at(-1)!); }
+    else if (msg.type === "history_goto") history.goto(msg.step);
   });
-  host.routes.set("/ui-api/history", (_req: any, res: any) => {
+  host.routes.set("/history", (_req: any, res: any) => {
     const history = shared();
     res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ at: history?.at ?? null,
-      line: (history?.line() ?? []).map((n) => { const { surfaces, parent, ...s } = history!.steps.get(n)!; return s; }) }));
+      line: (history?.line() ?? []).map((n) => { const { cards, parent, ...s } = history!.steps.get(n)!; return s; }) }));
   });
 }

package/{app → agent}/extensions/mcp/browser.js

@@ -1,4 +1,4 @@
-// Browser half of the mcp extension: "/mcp" in the chat input opens a picker of the servers in app/mcp.json. A
+// The page side of the mcp extension: "/mcp" in the chat input opens a picker of the servers in agent/mcp.json. A
 // server's box turns it on or off; open it to tick single tools (greyed while the server is off). Each change is
 // saved at once (mcp_set). A server's tools show once the agents have connected to it.
 const STYLE = `

package/agent/extensions/mcp/guide.md

@@ -0,0 +1,3 @@
+# MCP servers
+Servers are in {agent}/mcp.json (pi's docs/mcp.md); the user turns them on and off with /mcp. To add one when asked:
+its entry there ("exposure": "deferred", secrets as ${ENV_VAR}, never written out), then call reload.

package/{app → agent}/extensions/mcp/index.ts

@@ -1,4 +1,4 @@
-// MCP picker: "/mcp" on the page ticks which servers in app/mcp.json, and which of their tools, the agents may use.
+// MCP picker: "/mcp" on the page ticks which servers in agent/mcp.json, and which of their tools, the agents may use.
 // pi's built-in MCP does the rest (server.ts loads it; pi's docs/mcp.md). A tick writes the fields pi's own /mcp
 // screen writes, in that file: "enabled": false for a server, toolExposure "<tool>": "hidden" (or back to the
 // server's exposure) for a tool. Then every agent reloads, one change at a time (a busy agent after its turn).
@@ -10,7 +10,7 @@ import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const FILE = path.join(host.app, "mcp.json");
+const FILE = path.join(host.agent, "mcp.json");
 
 function state() {
   const servers = JSON.parse(fs.readFileSync(FILE, "utf8")).mcpServers ?? {};
@@ -46,8 +46,6 @@ async function reloadAll() {
 }
 
 export default function (pi: ExtensionAPI) {
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8");
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.mcp = guide; });
 
   host.pageHandlers.set("mcp", async (msg: any) => {
     if (msg.type !== "mcp_list" && msg.type !== "mcp_set") return;