@chalky/chalky 0.0.0-stage → 0.1.3

package/app/extensions/files/browser.js

@@ -0,0 +1,96 @@
+// Browser half of the files plugin: the file panel on the right edge (slot "side"), one name per row,
+// collapsed and opened by its folder button (remembered in this browser). Hidden while there are no files.
+//   Files dragged from the computer onto the page: uploaded (POST /files/upload), then a "files-dropped"
+//   DOM event {x, y, files: [{name, path, size}]} at the drop spot (the point plugin opens its note box
+//   there). Dropped onto the panel itself: only stored.
+//   A row dragged out of the panel onto the page: the same event, with that file.
+//   A click on a row, or files dropped from the computer (the first of them): a "file-open" DOM event
+//   {file, row} (the viewer plugin opens a preview window attached to the row; rows carry data-path).
+// The list comes from GET /files, then from "files" events (after an upload, and after each agent turn).
+export default async function (page) {
+  const side = page.slot("side");
+  const style = document.createElement("style");
+  style.textContent = `
+    #side .files-toggle { width: 38px; height: 38px; display: grid; place-items: center; border-radius: 12px; color: var(--muted);
+                          align-self: flex-end; margin: 16px 9px 0 0; transition: background 0.15s, color 0.15s; }
+    #side .files-toggle:hover { background: var(--hover); color: var(--text); }
+    #side[data-open] .files-toggle { background: var(--glass-strong); color: var(--text);
+                                     box-shadow: 0 1px 6px rgba(0, 0, 0, 0.06), inset 0 0 0 1px var(--edge); }
+    #side .files { display: none; width: 220px; max-height: calc(100vh - 140px); overflow-y: auto; margin: 8px 9px 0 0;
+                   padding: 8px; box-sizing: border-box; border-radius: var(--radius); font-size: 13px;
+                   background: var(--glass-strong); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+                   border: 1px solid var(--edge); box-shadow: var(--shadow); }
+    #side[data-open] .files { display: block; }
+    #side[data-over] .files { outline: 2px solid var(--accent); outline-offset: -2px; }
+    #side .files-row { padding: 5px 8px; border-radius: 8px; color: var(--soft); cursor: grab;
+                       overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    #side .files-row:hover, #side .files-row.viewing { background: var(--hover); color: var(--text); }`;
+  document.head.append(style);
+
+  const toggle = document.createElement("button");
+  toggle.className = "files-toggle";
+  toggle.title = "Files: drop files anywhere on the page; drag a name onto the page to use it there";
+  toggle.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>`;
+  const list = document.createElement("div");
+  list.className = "files";
+  side.append(toggle, list);
+
+  const setOpen = (open) => {
+    side.toggleAttribute("data-open", open);
+    try { localStorage.setItem("files-open", open ? "1" : ""); } catch {}
+  };
+  let open = true;
+  try { open = localStorage.getItem("files-open") !== ""; } catch {}
+  setOpen(open);
+  toggle.onclick = () => setOpen(!side.hasAttribute("data-open"));
+
+  const ROW = "application/x-chalky-file";  // a row being dragged: its file as JSON
+  function render(files) {
+    list.replaceChildren();
+    side.hidden = !files.length;  // no files yet: no panel (a drop from the computer still works anywhere)
+    for (const f of files) {
+      const row = Object.assign(document.createElement("div"), { className: "files-row", textContent: f.name, draggable: true });
+      row.title = `${f.path} · ${Math.ceil(f.size / 1024)} KB · click to preview`;
+      row.dataset.path = f.path;
+      row.onclick = () => opened(f);  // a drag never ends in a click, so dragging a row still works
+      row.ondragstart = (e) => { e.dataTransfer.setData(ROW, JSON.stringify(f)); e.dataTransfer.effectAllowed = "copy"; };
+      list.append(row);
+    }
+  }
+  page.on("files", ({ files }) => render(files));
+  try { render(await (await fetch("/files")).json()); } catch { render([]); }
+
+  const kind = (e) => {
+    const types = [...(e.dataTransfer?.types || [])];
+    return types.includes(ROW) ? "row" : types.includes("Files") ? "files" : null;
+  };
+  const onPanel = (e) => side.contains(e.target);
+  const opened = (file) => document.dispatchEvent(new CustomEvent("file-open",
+    { detail: { file, row: list.querySelector(`[data-path="${CSS.escape(file.path)}"]`) } }));
+  const dropped = (x, y, files) => document.dispatchEvent(new CustomEvent("files-dropped", { detail: { x, y, files } }));
+
+  document.addEventListener("dragover", (e) => {
+    if (!kind(e)) return;
+    e.preventDefault();
+    side.toggleAttribute("data-over", kind(e) === "files" && onPanel(e));
+  });
+  document.addEventListener("dragleave", (e) => { if (!e.relatedTarget) side.removeAttribute("data-over"); });
+  document.addEventListener("drop", async (e) => {
+    const k = kind(e);
+    if (!k) return;
+    e.preventDefault();
+    side.removeAttribute("data-over");
+    const { clientX: x, clientY: y } = e;
+    if (k === "row") return onPanel(e) || dropped(x, y, [JSON.parse(e.dataTransfer.getData(ROW))]);
+    const stored = [];
+    for (const f of [...e.dataTransfer.files].slice(0, 10)) {
+      try {
+        const out = await (await fetch(`/files/upload?name=${encodeURIComponent(f.name)}`, { method: "POST", body: f })).json();
+        if (out.path) stored.push({ name: out.path.split("/").pop(), path: out.path, size: out.size });
+        else page.note(`Could not upload ${f.name}: ${out.error}`);
+      } catch (err) { page.note(`Could not upload ${f.name}: ${err}`); }
+    }
+    if (stored.length) opened(stored[0]);  // the list has its row by now (the "files" event comes before the reply)
+    if (stored.length && !onPanel(e)) dropped(x, y, stored);
+  });
+}

package/app/extensions/files/guide.md

@@ -0,0 +1,7 @@
+# The user's files
+{work}/drops/ holds the user's files: the ones they dropped on the page, and any you save there. The
+user sees all of them by name in the file panel on the page's right edge.
+- A file matters only when the user points at it (a note with "files": dropped from their computer or
+  dragged from their panel) or names it. Then read it from there (read shows you pictures).
+- To hand the user a file (an export, a generated image, a dataset), save it in {work}/drops/: it shows
+  in their panel when your turn ends. Other work files stay in {work}.

package/app/extensions/files/index.ts

@@ -0,0 +1,73 @@
+// Files: the user's files, in one folder, <workspace>/drops (port of the Python files plugin; the browser half,
+// browser.js, is its files.js). browser.js shows them in a panel on the page's right edge and handles files dragged onto
+// the page (from the computer: uploaded here, listed, and a "files-dropped" DOM event so point's browser.js opens its note
+// box there; onto the panel itself: only stored; a row from the panel: the same event with that file).
+// The agent always knows the folder (its prompt section); files it saves there show in the panel too (the list is
+// sent again when an agent's turn is over: pi's agent_settled).
+//   POST /files/upload?name=<file name>  the file's bytes: saved in DIR (a safe, new name), returns {path, size}
+//   GET  /files                          [{name, path, size}], newest first; files in folders too ("q3/costs.xlsx")
+//   event "files" {files: [...]}         to every open page, when the list changed
+// guide.md (copied from files.py, short enough to be whole) names pi's read tool for pictures (Python: view_image).
+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 DIR = path.join(host.work, "drops");
+const MAX_FILE = 25 * 1024 * 1024;  // bytes per uploaded file
+const MAX_LISTED = 500;             // rows in the panel (the newest)
+fs.mkdirSync(DIR, { recursive: true });  // there from the first turn, so the agent can save into it
+
+function listing() {  // the files in DIR and its folders (not hidden ones), newest first; name: the path inside DIR
+  return fs.readdirSync(DIR, { withFileTypes: true, recursive: true })
+    .map((e) => ({ e, name: path.relative(DIR, path.join(e.parentPath, e.name)) }))
+    .filter(({ e, name }) => e.isFile() && !name.split(path.sep).some((s) => s.startsWith(".")))
+    .map(({ name }) => { const p = path.join(DIR, name), st = fs.statSync(p); return { name, path: p, size: st.size, mtime: st.mtimeMs }; })
+    .sort((a, b) => b.mtime - a.mtime || a.name.localeCompare(b.name))
+    .slice(0, MAX_LISTED)
+    .map(({ name, path, size }) => ({ name, path, size }));
+}
+
+function changed() {  // tell the pages, if the list is not what they were last sent
+  const now = JSON.stringify(listing());
+  if (now === host.shared.get("files-last")) return;
+  host.shared.set("files-last", now);
+  host.broadcast("files", { files: JSON.parse(now) });
+}
+
+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.files = guide; });
+  pi.on("agent_settled", () => changed());  // the agent may have saved files there
+  if (!host.shared.has("files-last")) host.shared.set("files-last", JSON.stringify(listing()));
+
+  host.routes.set("/files", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(listing())));
+  host.routes.set("/files/upload", (req: any, res: any) => {  // save one file in DIR (a new name if it exists)
+    if (req.method !== "POST") return res.writeHead(405).end();
+    const given = path.basename(new URL(req.url, "http://x").searchParams.get("name") ?? "file");
+    const name = given.replace(/[^\w.\-]+/g, "_").replace(/^[._]+|[._]+$/g, "") || "file";
+    const ext = path.extname(name), stem = name.slice(0, name.length - ext.length);
+    let p = path.join(DIR, name), k = 1;
+    while (fs.existsSync(p)) p = path.join(DIR, `${stem}-${++k}${ext}`);
+    const out = fs.createWriteStream(p);
+    out.on("error", () => {});  // writes still queued when the size limit cuts it off
+    let size = 0, tooBig = false;
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_FILE && !tooBig) {
+        tooBig = true;
+        out.on("close", () => fs.rmSync(p, { force: true }));
+        out.destroy();
+        res.writeHead(413, { "content-type": "application/json" }).end(JSON.stringify({ error: `${name} is over ${MAX_FILE / 1024 / 1024} MB` }));
+        req.destroy();
+      } else if (!tooBig) out.write(chunk);
+    });
+    req.on("end", () => {
+      if (tooBig) return;
+      out.end(() => {
+        changed();
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ path: p, size }));
+      });
+    });
+  });
+}

package/app/extensions/frames/README.md

@@ -0,0 +1,37 @@
+# Wireframes (the frames extension)
+The user can lay out placeholder boxes (frames) on the page and write in each what goes there, then send
+them all at once: "[frames on the UI]" lists each frame's id, place and words. Frames sent together are
+one design, not separate requests: they share one look, and often each other's data.
+- The words in a frame are a title, not a spec: "my notes" means a real notes app. Build what a good
+  version of that thing does, the way the user would expect it from any app they know (notes are added
+  and kept, a list can be added to and edited, things saved somewhere can be found there again), working
+  on the page from the first version. Not the least that matches the words, and not a static mock with
+  sample data where the thing should hold the user's own. Say your assumptions in one line at the end.
+- Before building, look for the links: between the frames, and between them and the surfaces already on
+  the page. Does one show, file, pick from, summarise or act on another's items ("book of the week" from
+  "a reading list"; "my notes on what i'm reading": notes per book)? Do two hold the same things? Should a
+  frame use something already there (an existing notepad) instead of starting its own? The words are short,
+  so a link is often only hinted: work out what a person who drew these side by side would mean.
+- If the links are not obvious, don't pick a default silently and don't ask an open question: propose
+  the design and ask once, in one short reply, e.g. "Reading list: add books, mark read. Book of the week:
+  Pick on a row sets it. Notes: one box for the week's book, Save files the note in that book's folder.
+  Build it like that?" That reply is your answer for this turn; build when they answer. When the links are
+  obvious, build straight away. Never ask about what you can decide well yourself (look, layout, details).
+- Linked frames that change each other's data (pick a book, file a note into it, mark it read) are one
+  app: one App folder ({code}/ui/apps/<name>/) with a page per frame (reading/list.html, week.html,
+  notes.html), each frame its own surface showing its page, all keeping their data in the app's shared
+  store (agents.load / agents.save, see "App data"). A click in one updates the others at once, on the
+  page, with no agent in between. Separate component surfaces with {"ref"} props are for a frame that only
+  shows another's data (refs only read). Don't change the page's own code (page.html, the browser.js files) to
+  link frames.
+- Fill a frame with ui_render(surface=<its id>, place=<its place>, ...): its dashed box goes when that
+  surface appears. Keep the place: the user chose where and how big.
+- Split the work when it pays: several frames that are each real work and don't depend on each other can
+  go to helpers in parallel (spawn_agent, or idle agents you have): tell each one its frame, and what done
+  means: "surface <id> rendered at <place>, doing <their words>". Say the shared look in each message
+  (colours, type, spacing, the components to reuse), so the pieces match. A frame that needs another's data
+  waits for it: hand it out once that one is done. Small or tightly linked frames: do them yourself.
+- When all are filled, look at the whole page once (the pieces side by side) and fix what doesn't match,
+  and try each link end to end (add a note: does it show in the filer?) by clicking through it with the
+  ui-check skill.
+  Put back any data your clicks changed, so the user finds what you built, not your test.

package/app/extensions/frames/browser.js

@@ -0,0 +1,163 @@
+// 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
+// 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
+// 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.
+export default async function (page) {
+  const area = page.slot("top");
+  const style = document.createElement("style");
+  style.textContent = `
+    #top.framing { cursor: crosshair; z-index: 11; }  /* above the messages panel (10), so frames can be drawn there too */
+    #top .frame { position: absolute; z-index: 100000; box-sizing: border-box; display: grid; place-items: center; padding: 12px;
+                  border: 1.5px dashed var(--muted); border-radius: 12px; background: var(--glass); cursor: default;
+                  backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur); }
+    #top .frame.drawing { pointer-events: none; }
+    #top .frame textarea { width: 100%; max-width: 360px; border: 0; outline: 0; resize: none; background: none; font: inherit;
+                           font-size: 14px; color: var(--text); text-align: center; field-sizing: content; max-height: 100%; }
+    #top .frame textarea::placeholder { color: var(--muted); }
+    #top .frame.sent { border-color: var(--accent); }
+    #top .frame.sent textarea { color: var(--soft); }
+    #top .frame .frame-id { position: absolute; left: 10px; top: 6px; font-size: 11px; color: var(--muted); }
+    #top .frame.sent .frame-id::after { content: " · waiting for an agent"; }
+    #top .frame .frame-x { position: absolute; right: 6px; top: 4px; width: 22px; height: 22px; border-radius: 6px;
+                           color: var(--muted); opacity: 0; }
+    #top .frame:hover .frame-x { opacity: 1; }
+    #top .frame .frame-x:hover { background: var(--hover); color: var(--text); }
+    #top .frame .frame-resize { position: absolute; right: 0; bottom: 0; width: 10px; height: 10px; box-sizing: border-box;
+                                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); }`;
+  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.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.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
+  send.hidden = true;
+  page.tool(button).append(send);
+
+  let on = false, ready = 0;  // ready: unsent frames with words
+  const showReady = () => {  // only one row under the palette shows at a time: the tool that is on
+    send.hidden = !(on && ready);
+    send.querySelector(".badge").textContent = ready || "";
+    button.querySelector(".badge").textContent = !on && ready ? ready : "";
+  };
+  const setOn = (v) => {
+    on = v;
+    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
+  };
+  button.onclick = () => setOn(!on);
+  document.addEventListener("tool-on", (e) => { if (on && e.detail !== "frames") 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 });
+  };
+
+  const inMain = (x, y) => {  // window px -> main-space px (as point.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).
+  let start = null, ghost = null, focusNew = false;
+  area.addEventListener("mousedown", (e) => {
+    if (!on || e.button !== 0 || e.target.closest(".frame")) return;
+    e.preventDefault();
+    e.stopPropagation();
+    start = inMain(e.clientX, e.clientY);
+    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
+  window.addEventListener("mousemove", (e) => {
+    if (!start) return;
+    const p = inMain(e.clientX, e.clientY);
+    put(ghost, { x: Math.min(start.x, p.x), y: Math.min(start.y, p.y), width: Math.abs(p.x - start.x), height: Math.abs(p.y - start.y) });
+  });
+  window.addEventListener("mouseup", () => {
+    if (!start) return;
+    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
+  });
+
+  const boxes = {};  // id -> its box on the page
+  const timers = {};
+  let shown = {};  // the frames as last rendered
+  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;
+      delete shown[id];  // once, though the eraser keeps moving over it
+      page.send({ type: "frame_remove", id });
+    }
+  });
+  function render(frames) {
+    shown = { ...frames };
+    for (const id of Object.keys(boxes)) if (!frames[id]) { boxes[id].remove(); delete boxes[id]; }
+    let newest = null;
+    for (const [id, f] of Object.entries(frames)) {
+      let box = boxes[id];
+      if (!box) {
+        box = boxes[id] = Object.assign(document.createElement("div"), { className: "frame" });
+        box.dataset.frame = id;
+        const label = Object.assign(document.createElement("span"), { className: "frame-id", textContent: id });
+        const close = Object.assign(document.createElement("button"), { className: "frame-x", textContent: "✕", title: "Remove this frame" });
+        close.onclick = () => page.send({ type: "frame_remove", id });
+        const text = Object.assign(document.createElement("textarea"), { rows: 1, placeholder: "What goes here?" });
+        text.oninput = () => {
+          clearTimeout(timers[id]?.t);
+          const flush = timers[id] = () => { delete timers[id]; page.send({ type: "frame_text", id, text: text.value }); };
+          flush.t = setTimeout(flush, 300);
+        };
+        text.onkeydown = (e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); text.blur(); } };
+        const corner = Object.assign(document.createElement("div"), { className: "frame-resize", title: "Drag to resize" });
+        corner.onpointerdown = (e) => resize(box, id, e);
+        box.append(label, close, text, corner);
+        area.append(box);
+        newest = box;
+      }
+      put(box, f);
+      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;
+    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
+    e.preventDefault();
+    const corner = e.currentTarget, x = box.offsetLeft, y = box.offsetTop, w0 = box.offsetWidth, h0 = box.offsetHeight;
+    corner.setPointerCapture(e.pointerId);
+    let place = null;
+    corner.onpointermove = (ev) => {
+      place = { x, y, width: Math.max(40, Math.round(w0 + ev.clientX - e.clientX)), height: Math.max(30, Math.round(h0 + ev.clientY - e.clientY)) };
+      put(box, place);
+    };
+    corner.onpointerup = () => {
+      corner.onpointermove = corner.onpointerup = null;
+      if (place) page.send({ type: "frame_place", id, ...place });
+    };
+  }
+  page.on("frames", (ev) => render(ev.frames));
+  try { render(await (await fetch("/frames")).json()); } catch {}
+}

package/app/extensions/frames/guide.md

@@ -0,0 +1,7 @@
+# Wireframes
+The user lays out boxes (frames) on the page, writes in each what goes there, and sends them together:
+"[frames on the UI]".
+- Fill each frame with ui_render(surface=<the frame's id>, place=<its place>): its dashed box goes when it appears.
+- Build a working version of what the words name, as a good one would work (an App when it keeps or calculates
+  things), never a mock with sample data. Frames sent together are one design.
+Before you handle a frames message, read README.md.

package/app/extensions/frames/index.ts

@@ -0,0 +1,76 @@
+// Frames: wireframes the user lays out for the agents to fill (port of the Python frames plugin; browser.js is its
+// frames.js). 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?} (main-space px, where ui_render's place puts a surface), with an
+// id (frame-1, frame-2, ...: never reused). An agent fills it with ui_render(surface="frame-1", place=<its place>);
+// when that surface appears (a ui watcher, host.api.ui.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 /frames             {id: frame}
+//   page messages           frame_add {x, y, width, height}, frame_place {id, x, y, width, height}, frame_text {id, text},
+//                           frame_remove {id}, frames_send {to}
+//   event "frames"          {frames: {id: frame}} to every open page, when they changed
+// Saved in state/frames.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.state, "frames.json");
+if (!host.shared.has("frames"))
+  host.shared.set("frames", fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 0, frames: {} });
+const saved = host.shared.get("frames");  // {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("frames", { 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) {
+  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it, read when it says
+    .replace("README.md", path.join(import.meta.dirname, "README.md"));
+  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.frames = guide; });
+
+  // a frame is done when a surface with its id appears (after all extensions loaded: the ui one may come later)
+  pi.on("session_start", () => {
+    host.api.ui?.watch("frames", (sid: string) => {
+      if (frames[sid] && host.shared.get("ui")?.surfaces[sid]) { delete frames[sid]; changed(); }
+    });
+  });
+
+  host.routes.set("/frames", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(frames)));
+
+  host.pageHandlers.set("frames", (msg: any) => {
+    const f = frames[msg.id], swarm = host.api.swarm;
+    if (msg.type === "frame_add") {
+      frames[`frame-${++saved.last}`] = { ...box(msg), text: "", sent: false };
+      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) swarm?.send("user", f.to, `[frames on the UI] the user removed ${msg.id} ("${f.text}"): don't fill it.`, true);
+    } else if (msg.type === "frames_send" && swarm) {
+      const to = msg.to in swarm.status() ? msg.to : "agent1";
+      const ready = Object.entries(frames).filter(([, f]: any) => !f.sent && f.text.trim());
+      if (!ready.length) return;
+      for (const [, f] of ready as any) Object.assign(f, { sent: true, to });
+      changed();
+      const lines = [`[frames on the UI] the user laid out ${ready.length} frame${ready.length > 1 ? "s" : ""} to fill:`,
+        ...ready.map(([id, f]: any) => `  ${id}: "${f.text}" · place=${place(f)}`),
+        "  Fill each with ui_render(surface=<its id>, place=<its place>, ...); 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(", ")}.`);
+      swarm.send("user", to, lines.join("\n"));
+    }
+  });
+}

package/app/extensions/mcp/browser.js

@@ -0,0 +1,64 @@
+// Browser half of the mcp extension: "/mcp" in the chat input opens a picker of the servers in app/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 = `
+  .mcp { width: min(560px, calc(100vw - 32px)); max-height: 75vh; padding: 16px 18px; box-sizing: border-box;
+         border-radius: var(--radius, 16px); border: 1px solid var(--edge, #eee); color: var(--text, #1d1d1f);
+         background: var(--glass-strong, #fff); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+         box-shadow: var(--shadow, 0 8px 30px rgba(0,0,0,.1)); font-size: 13px; }
+  .mcp::backdrop { background: rgba(0, 0, 0, .08); }
+  .mcp header { display: flex; justify-content: space-between; margin-bottom: 10px; font-weight: 600; }
+  .mcp header button { font: inherit; color: var(--muted, #888); background: none; border: 0; cursor: pointer; }
+  .mcp p { color: var(--muted, #888); margin: 0 0 10px; } .mcp p.error { color: #c62828; }
+  .mcp details { border-top: 1px solid rgba(128, 128, 128, .2); padding: 8px 0; }
+  .mcp summary { display: flex; gap: 8px; align-items: center; cursor: pointer; list-style: none; }
+  .mcp summary span { margin-left: auto; color: var(--muted, #888); }
+  .mcp label { display: flex; gap: 8px; align-items: baseline; padding: 4px 0 4px 24px; cursor: pointer; }
+  .mcp label span { color: var(--muted, #888); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+`;
+
+export default function (page) {
+  const style = document.createElement("style");
+  style.textContent = STYLE;
+  document.head.append(style);
+  const box = document.createElement("dialog");
+  box.className = "mcp";
+  document.body.append(box);
+  box.onclick = (e) => { if (e.target === box) box.close(); };  // a click on the backdrop closes it
+  let state = null;  // the "mcp" event: {file, servers, error}
+  const open = new Set();  // servers whose tools are shown, kept across redraws
+  const el = (tag, props, ...kids) => { const e = Object.assign(document.createElement(tag), props); e.append(...kids); return e; };
+  const tick = (checked, onchange, more = {}) => el("input", { type: "checkbox", checked, onchange, ...more });
+
+  function render() {
+    const close = el("button", { title: "Close", onclick: () => box.close() }, "✕");
+    box.replaceChildren(el("header", {}, "MCP tools", close));
+    if (!state) return box.append("Asking…");
+    box.append(el("p", {}, `Tick what the agents may use. The servers are in ${state.file}.`));
+    if (state.error) box.append(el("p", { className: "error" }, state.error));
+    const servers = Object.entries(state.servers);
+    if (!servers.length && !state.error) box.append(el("p", {}, "No servers yet: add them to that file."));
+    for (const [server, s] of servers) {
+      const on = s.tools.filter((t) => t.on).length;
+      const all = tick(s.enabled, () => page.send({ type: "mcp_set", server, on: all.checked }),
+        { onclick: (e) => e.stopPropagation() });  // ticking the server doesn't open or close it
+      const count = s.tools.length ? `${on}/${s.tools.length}` : s.enabled ? "no tools yet" : "off";
+      const d = el("details", { open: open.has(server) },
+        el("summary", {}, all, el("b", { title: s.description }, server), el("span", {}, count)));
+      d.ontoggle = () => d.open ? open.add(server) : open.delete(server);
+      for (const t of s.tools) {
+        const one = tick(t.on, () => page.send({ type: "mcp_set", server, tool: t.name, on: one.checked }), { disabled: !s.enabled });
+        d.append(el("label", { title: t.description }, one, t.name, el("span", {}, t.description)));
+      }
+      box.append(d);
+    }
+  }
+
+  page.command("mcp", () => {
+    state = null;  // ask again each time: mcp.json or the connections may have changed
+    render();
+    box.showModal();
+    page.send({ type: "mcp_list" });
+  }, "Choose the MCP tools the agents may use");
+  page.on("mcp", (ev) => { state = ev; if (box.open) render(); });
+}

package/app/extensions/mcp/guide.md

@@ -0,0 +1,5 @@
+# MCP servers
+Servers are in {code}/mcp.json (pi's built-in MCP: pi's docs/mcp.md); their tools are named mcp__<server>__<tool>.
+The user ticks which servers and tools are on with /mcp on the page.
+- To add a server when asked: add its entry to that file (secrets as ${ENV_VAR} in headers or env, never written
+  out), then call reload.

package/app/extensions/mcp/index.ts

@@ -0,0 +1,64 @@
+// MCP picker: "/mcp" on the page ticks which servers in app/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).
+// Tools: agent1's, from pi (getAllTools), once its connection to the server is up.
+//   page message  mcp_list                                 -> event "mcp" {file, servers: {name: {enabled, description,
+//                 mcp_set {server, on} | {server, tool, on}       tools: [{name, description, on}]}}, error}
+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.app, "mcp.json");
+
+function state() {
+  const servers = JSON.parse(fs.readFileSync(FILE, "utf8")).mcpServers ?? {};
+  const tools = host.agents.get("agent1")?.session.getAllTools() ?? [];
+  const out: Record<string, any> = {};
+  for (const [name, c] of Object.entries<any>(servers)) {
+    const enabled = c.enabled !== false;
+    out[name] = { enabled, description: c.description ?? c.url ?? c.command ?? "",
+      tools: tools.filter((t: any) => t.namespace?.aliases?.[0] === name).map((t: any) => {
+        const tool = t.name.slice(t.namespace.name.length + 2);  // mcp__<server>__<tool>
+        return { name: tool, description: t.description, on: enabled && (c.toolExposure?.[tool] ?? t.exposure) !== "hidden" };
+      }) };
+  }
+  return { file: FILE, servers: out, error: "" };
+}
+
+function set(msg: any) {
+  const json = JSON.parse(fs.readFileSync(FILE, "utf8")), c = json.mcpServers?.[msg.server];
+  if (!c) return;
+  if (msg.tool === undefined) { if (msg.on) delete c.enabled; else c.enabled = false; }
+  else {
+    const own = c.exposure ?? "codemode";  // pi's default
+    (c.toolExposure ??= {})[msg.tool] = !msg.on ? "hidden" : own === "hidden" ? "direct" : own;
+  }
+  fs.writeFileSync(FILE, JSON.stringify(json, null, 2) + "\n");
+}
+
+async function reloadAll() {
+  for (const a of host.agents.values()) {
+    if (a.session.isStreaming) { if (!host.reloadAfterTurn.has(a.name)) host.reloadAfterTurn.set(a.name, true); }
+    else await host.reloadAgent(a.name, true);  // quiet: ticking isn't news for the conversation
+  }
+}
+
+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;
+    try {
+      if (msg.type === "mcp_set") set(msg);
+      host.broadcast("mcp", state());  // before the reloads: agent1's tools are still listed, the file has the ticks
+    } catch (e: any) {
+      return host.broadcast("mcp", { file: FILE, servers: {}, error: `${FILE}: ${e.message}` });
+    }
+    // reloads one after another, also across this extension's own reloads (host.shared outlives them)
+    if (msg.type === "mcp_set") host.shared.set("mcp-reloads", (host.shared.get("mcp-reloads") ?? Promise.resolve())
+      .then(reloadAll).catch((e: any) => console.error("mcp: reload failed:", e)));
+  });
+}

package/app/extensions/model/index.ts

@@ -0,0 +1,20 @@
+// The model: one OpenAI-compatible endpoint (in Chalky: keyproxy -> LiteLLM), as the Python agent's llm plugin.
+// MODEL_BASE_URL (up to /v1), MODEL_API_KEY, MODEL_NAME (a LiteLLM route, "default"). pi does the calls,
+// streaming, retries, thinking and compaction; this only tells it where. The host selects provider "chalky".
+// MODEL_CONTEXT_WINDOW: the model's context size; pi compacts when a request would leave less than 16384 tokens of it.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  if (!process.env.MODEL_BASE_URL) return;  // pi then says no model is configured on each message
+  pi.registerProvider("chalky", {
+    baseUrl: process.env.MODEL_BASE_URL,
+    apiKey: "$MODEL_API_KEY",  // read from the environment by pi, not stored in the session
+    api: "openai-completions",
+    compat: { supportsStore: false, supportsDeveloperRole: false },  // LiteLLM may not take "store" (pi-ai docs)
+    models: [{
+      id: process.env.MODEL_NAME || "default", name: "Chalky default route", reasoning: true,
+      input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: Number(process.env.MODEL_CONTEXT_WINDOW || 200000), maxTokens: 16000,
+    }],
+  });
+}