@chalky/chalky 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weihanfeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# Chalky
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chalky is a workspace where AI agents build what you see. You say what you want, the agents put a working
+first version on the page (forms, tables, dashboards, small apps), and then you point at things on it, draw on
+it and leave notes, and they change exactly that. The conversation is a side panel; what they build fills the
+screen.
+
+The agents run on [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). Everything they are made of
+is pi extensions they can edit themselves, the page included. Every change is versioned, and
+`http://127.0.0.1:3000/recover` takes you back to a version that worked if an agent breaks the page.
+
+## Install and run
+
+Needs Node.js 22.19 or newer and an OpenAI-compatible model endpoint (an OpenAI-style `/v1`, a LiteLLM proxy, a
+local server).
+
+```sh
+npm install -g @chalky/chalky
+MODEL_BASE_URL=https://your-endpoint/v1 MODEL_API_KEY=... MODEL_NAME=your-model chalky
+```
+
+Then open http://127.0.0.1:3000.
+
+| Variable | |
+|---|---|
+| `MODEL_BASE_URL` | the endpoint, up to `/v1` |
+| `MODEL_API_KEY` | its key |
+| `MODEL_NAME` | the model (default: `default`) |
+| `CHALKY_HOME` | where Chalky keeps its things (default: `~/.chalky`) |
+| `UI_HOST` | the address to serve on (default: `127.0.0.1`, this machine only) |
+| `PORT` | the port to serve on (default: `3000`) |
+
+## Where things are
+
+`~/.chalky` (or `CHALKY_HOME`) holds:
+
+- `app/`: the agents' code, copied from the package on the first run. The agents edit it, and each change is
+  versioned. A newer version of the package doesn't overwrite it.
+- `state/`: conversations, version history, what the apps keep.
+- `workspace/`: the agents' working folder.
+
+## MCP servers
+
+Tools from MCP servers go in `~/.chalky/app/mcp.json`, in pi's format (stdio or streamable HTTP; see pi's
+`docs/mcp.md`). Type `/mcp` on the page to choose which servers and tools the agents may use. Keep secrets in
+environment variables and refer to them as `${NAME}` in `headers` or `env`.

package/app/SYSTEM.md

@@ -0,0 +1,31 @@
+You are an agent in Chalky. You build what the user sees: the page is a workspace where what you build (UI
+surfaces and apps) fills the screen, and the conversation is a side panel. The user says what they want; you put a
+working first version on screen; then they point at things on it and leave notes, and you change exactly that.
+- Build, don't describe. A first version they can point at beats questions you could answer by building.
+- Your final reply is the only text they read in full: one or two sentences on what changed.
+- The page around your work is the user's: change it only when asked. Build inside the main space.
+
+What follows this: the skills you can load, your working folder (<cwd>: bash runs there), one short section for
+each part of you that has something to say (each comes from an extension), and <paths>: where your folders
+({code}, {work}, {data}), the host and pi's docs are. In these texts and the README.md files, {code}/..., {work}/...
+and {data}/... are paths in those folders. A section that names a README.md is the short version of its
+extension: read that file when the section says, once (it stays in your conversation).
+
+Your tools:
+- read to look at files and pictures (not cat or sed); bash for ls, grep, find and running things.
+- edit for precise changes: each edits[].oldText must match the file exactly and only once; keep it as small as
+  that allows. Several changes in one file: one edit call with several entries, each matched against the original
+  file, none overlapping. An edit whose newText equals its oldText changes nothing and is refused.
+- write only for new files or complete rewrites.
+- Name files by their full path when you mention them.
+
+Changing yourself: when the work needs it, you can change any part of you, the page included. You are pi
+extensions, one folder each: {code}/extensions/<name>/. In it, index.ts is `export default function (pi:
+ExtensionAPI) { ... }`, which registers tools (pi.registerTool), prompt sections and event handlers (pi.on); and as
+the extension needs them, guide.md (its short prompt section), README.md (the whole of it), browser.js (its part
+of the page) and skills/. The page itself is the page extension; this text is {code}/SYSTEM.md; pi's settings (e.g. compaction) are
+{code}/settings.json (pi's docs/settings.md). Extensions reach
+shared state and the web server through globalThis.chalky: the host, the fixed core under them (don't edit it).
+Read pi's extension docs (<paths>) before writing or changing an extension. After editing, call the reload tool:
+your extensions load again when your turn ends, and your conversation is kept. A changed page or browser.js shows
+when the page reloads, after your turn.

package/app/extensions/appdata/README.md

@@ -0,0 +1,10 @@
+# App data (the appdata extension)
+An App ({code}/ui/apps/<name>/) keeps what the user makes in it (notes, lists, picks) with
+`import agents from "/ui/agents.js"`: `await agents.load()` gives the app's saved data ({} at first),
+`agents.save(data)` replaces it, and `agents.on("app_data", ({app, data}) => ...)` hears every save of any
+app (check app === your app's folder name). Saved on the server in {data}/app-data/<name>.json: it
+survives reloads, is the same in every browser, and you can read it (cat the file) when the user points at
+something in the app. The same app shown in several surfaces shares this data, so one surface's clicks
+update the others at once, with no agent in between. To change it yourself, PUT the whole value:
+curl -X PUT --data @new.json {page}/ui-api/app-data/<name> (the open pages update).
+Not localStorage: that stays in one browser, and you can't see it.

package/app/extensions/appdata/guide.md

@@ -0,0 +1,4 @@
+# App data
+An App keeps what the user makes in it (notes, lists, picks) with /ui/agents.js (agents.load, agents.save), on the
+server and shared by every surface showing it; never localStorage (one browser only, and you can't see it).
+Before you build an App that keeps data, read README.md.

package/app/extensions/appdata/index.ts

@@ -0,0 +1,47 @@
+// App data: a small shared store for apps (app/ui/apps/<name>/, shown by the App component), saved here, so an
+// app's data outlives the page, is the same in every browser, and the agents can read it (port of the Python
+// appdata plugin). One JSON value per app, in state/app-data/<name>.json. The same app shown in several surfaces
+// shares it: when one saves, every open page and app frame gets an "app_data" event.
+// The app side is app/ui/agents.js: agents.load(), agents.save(data), agents.on("app_data", fn).
+//   GET /ui-api/app-data/<name>    the app's data ({} if none yet)
+//   PUT /ui-api/app-data/<name>    replace it (JSON, at most MAX_BYTES); event "app_data" {app, data}
+// Whole value replaced each time: the last save wins (keep one app's data in one value). A version check (refuse a
+// save made from an older value) is the fix if lost saves show up; not added yet.
+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.state, "app-data");
+const MAX_BYTES = 1024 * 1024;
+const json = (res: any, v: unknown, status = 200) => res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(v));
+
+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.appdata = guide; });
+
+  host.routes.set("/ui-api/app-data/", (req: any, res: any) => {
+    const name = decodeURIComponent(new URL(req.url, "http://x").pathname.slice("/ui-api/app-data/".length));
+    if (!/^[\w-]+$/.test(name)) return json(res, { error: "app names are letters, digits, _ and -" }, 400);
+    const p = path.join(DIR, name + ".json");
+    if (req.method === "GET") {
+      if (!fs.existsSync(p)) return json(res, {});
+      return res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }).end(fs.readFileSync(p));
+    }
+    if (req.method !== "PUT") return res.writeHead(405).end();
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on("data", (c: Buffer) => { size += c.length; if (size <= MAX_BYTES) chunks.push(c); });
+    req.on("end", () => {
+      if (size > MAX_BYTES) return json(res, { error: `bad app name, or over ${MAX_BYTES / 1024} KB` }, 400);
+      let data;
+      try { data = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch (e: any) { return json(res, { error: `not JSON: ${e.message}` }, 400); }
+      fs.mkdirSync(DIR, { recursive: true });
+      fs.writeFileSync(p + ".tmp", JSON.stringify(data));
+      fs.renameSync(p + ".tmp", p);
+      host.broadcast("app_data", { app: name, data });
+      json(res, { saved: true });
+    });
+  });
+}

package/app/extensions/boards/browser.js

@@ -0,0 +1,357 @@
+// Browser half of boards: the main space as numbered boards, and the shelf to move between them (above the input).
+// Each board is a container in #top. The one you're on is display: contents (its things sit in the main space as
+// before); the others are laid out but hidden, so apps in them keep running and the shelf can draw them.
+// Any element with data-board="n" that lands in #top (a surface, a frame) is moved into board n's container, and
+// moved again when its data-board changes (a MutationObserver): no extension needs this one. One on the body (a
+// note's pin, fixed to the window) shows only while its board is shown.
+// Other scripts read the board shown from body[data-board] (new things go there), and get a DOM event "board"
+// {from, to} just before it changes (doodle: the drawing so far becomes a step; frames: count this board's).
+// The shelf: a dot per board (yours is bigger). Hover it and the dots open into thumbnails, with + for a new board;
+// click one to go there. It stays clear of the chat panel: more thumbnails than fit scroll between ‹ and › (grey at
+// the ends; a new board scrolls to the end). Drag a surface by its label onto a thumbnail to move it to that board, where it was ({type: "ui_board"}).
+//   page messages  board_view {board}: the board this page shows; board_add
+//   GET /boards    {boards, current}        event "boards" {boards, added?, by?}
+const CSS = `
+  #top > .board:not(.on) { position: absolute; top: 0; left: 0; right: 0; height: 0; overflow: hidden; padding: inherit;
+    box-sizing: border-box; visibility: hidden; pointer-events: none; }
+  #top > .board.on { display: contents; }
+  #top > .board.on:empty::before { content: "What should we build?"; position: absolute; inset: 0; display: grid; place-items: center;
+    font-size: 30px; font-weight: 300; letter-spacing: -0.02em; color: rgba(0, 0, 0, 0.2); pointer-events: none; }
+  .boards-shelf { position: fixed; left: 50%; bottom: 72px; transform: translateX(-50%); z-index: 25; display: flex; align-items: flex-end;
+    gap: 8px; padding: 5px 8px; border-radius: 14px; border: 1px solid transparent; transition: background 0.15s; }
+  .boards-shelf.open { background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+    border-color: var(--edge); box-shadow: var(--shadow); }
+  .boards-shelf .slot { position: relative; display: grid; justify-items: center; gap: 4px; padding: 0; }
+  .boards-shelf .slot .x { display: none; position: absolute; top: 3px; right: 3px; width: 16px; height: 16px; border-radius: 50%;
+    font-size: 9px; line-height: 16px; text-align: center; color: var(--danger); background: var(--glass-strong); box-shadow: var(--shadow); }
+  .boards-shelf.open .slot:hover .x { display: block; }
+  .boards-toast { position: fixed; left: 50%; top: 76px; transform: translateX(-50%);  /* under the palette: clear of the shelf */ z-index: 27; display: flex; gap: 12px;
+    align-items: center; padding: 7px 14px; border-radius: 10px; background: rgba(29, 29, 31, 0.88); color: #fff; font-size: 13px; }
+  .boards-toast button { color: #9cc3f5; font-weight: 600; }
+  .boards-shelf .dot { width: 7px; height: 7px; border-radius: 50%; background: rgba(0, 0, 0, 0.22); transition: all 0.15s; }
+  .boards-shelf .slot.on .dot { width: 11px; height: 11px; background: var(--text); }
+  /* more boards than fit (fit(): clear of the chat panel): the thumbnails scroll inside .view, between ‹ and › */
+  .boards-shelf .view { overflow: hidden; scroll-behavior: smooth; padding: 3px; }
+  .boards-shelf .track { position: relative; display: flex; align-items: flex-end; gap: 8px; width: max-content; }
+  .boards-shelf .arrow { display: none; width: 24px; height: 70px; margin-top: 3px; align-self: flex-start; border-radius: 6px;
+    font-size: 20px; color: var(--text); }
+  .boards-shelf.open.more .arrow { display: block; }
+  .boards-shelf .arrow:disabled { opacity: 0.25; cursor: default; }
+  .boards-shelf .arrow:not(:disabled):hover { background: var(--hover); }
+  .boards-shelf .mini { display: none; position: relative; width: 120px; overflow: hidden; border-radius: 6px;
+    background: rgba(255, 255, 255, 0.6); border: 1px solid var(--line); }
+  .boards-shelf .mini i, .boards-peek .mini i { position: absolute; overflow: hidden; border-radius: 3px; background: rgba(0, 0, 0, 0.08); }
+  /* a surface: a card in its own main colour (light grey when it has none) */
+  .boards-shelf .mini i.s, .boards-peek .mini i.s { --accent-of: rgb(200, 203, 210);
+    background: color-mix(in srgb, var(--accent-of) 30%, #fff);
+    box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--accent-of) 70%, transparent), 0 1px 3px rgba(0, 0, 0, 0.08); }
+  .boards-shelf .mini i.s::before, .boards-peek .mini i.s::before { content: ""; position: absolute; left: 0; right: 0; top: 0;
+    height: max(2px, 12%); background: var(--accent-of); }
+  .boards-peek .mini i.s.detail { background: #fff; }  /* the sketch of its insides shows its colours */
+  .boards-peek .mini i.s.detail::before { display: none; }
+  .boards-peek .mini i u, .boards-peek .mini i img { display: block; }
+  .boards-peek { position: fixed; z-index: 26; transform: translateX(-50%); padding: 6px; border-radius: 12px; pointer-events: none;
+    background: var(--glass-strong); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+    border: 1px solid var(--edge); box-shadow: var(--shadow); }
+  .boards-peek .n { font-size: 11px; color: var(--muted); margin: 0 2px 4px; }
+  .boards-peek .mini { position: relative; width: 320px; overflow: hidden; border-radius: 8px; background: rgba(255, 255, 255, 0.6);
+    border: 1px solid var(--line); }
+  .boards-peek .empty { position: absolute; inset: 0; display: grid; place-items: center; font-size: 12px; color: var(--muted); }
+  .boards-shelf .n { display: none; font-size: 10.5px; color: var(--muted); }
+  .boards-shelf.open .mini, .boards-shelf.open .n { display: block; }
+  .boards-shelf.open .dot { display: none; }
+  .boards-shelf .slot.on .mini { outline: 2px solid var(--text); outline-offset: 1px; }
+  .boards-shelf .slot.drop .mini { outline: 2px solid var(--accent); outline-offset: 1px; }
+  .boards-shelf .add { display: none; width: 122px; height: 70px; border-radius: 6px;  /* a thumbnail's size, border included */ border: 1px dashed rgba(0, 0, 0, 0.25);
+    color: var(--muted); font-size: 13px; align-self: flex-start; margin-top: 3px; }
+  .boards-shelf.open .add { display: block; }  /* only in the open shelf: at rest it's just the dots */`;
+
+export default async function (page) {
+  document.head.insertAdjacentHTML("beforeend", `<style>${CSS}</style>`);
+  const top = page.slot("top");
+  const containers = {};
+  let boards = [1], current = 1, drag = null, over = null, adding = false;  // adding: this page clicked +
+
+  const container = (n) => {
+    if (!containers[n]) {
+      containers[n] = Object.assign(document.createElement("div"), { className: "board" });
+      containers[n].dataset.n = n;
+      top.append(containers[n]);
+    }
+    return containers[n];
+  };
+  const home = (el) => {  // an element with data-board: into its board's container
+    const c = container(Number(el.dataset.board) || 1);
+    if (el.parentElement !== c) c.append(el);
+  };
+  new MutationObserver((records) => {
+    for (const r of records) {
+      if (r.type === "attributes") home(r.target);
+      else for (const el of r.addedNodes) if (el.parentElement === top && el.dataset?.board) home(el);
+    }
+  }).observe(top, { childList: true, subtree: true, attributeFilter: ["data-board"] });
+
+  // the shelf: ‹ [the thumbnails, scrolling] › +   (+ outside the scrolling part, so it is always there)
+  const shelf = Object.assign(document.createElement("div"), { className: "boards-shelf" });
+  const button = (className, textContent, title, onclick) => Object.assign(document.createElement("button"), { className, textContent, title, onclick });
+  const view = Object.assign(document.createElement("div"), { className: "view" });
+  const track = Object.assign(document.createElement("div"), { className: "track" });
+  const step = (d) => view.scrollBy({ left: d * Math.max(130, view.clientWidth - 130) });  // about a view's width
+  const prev = button("arrow", "‹", "Earlier boards", () => step(-1));
+  const next = button("arrow", "›", "Later boards", () => step(1));
+  const add = button("add", "+", "New board", () => { adding = true; page.send({ type: "board_add" }); });
+  view.append(track);
+  shelf.append(prev, view, next, add);
+  document.body.append(shelf);
+  shelf.onmouseenter = () => open(true);
+  shelf.onmouseleave = () => { if (!drag) open(false); };
+  view.onscroll = arrows;
+  // the wheel's left/right (or up/down): each click moves the strip as an arrow does; the page doesn't scroll. At
+  // most one step per 250 ms, as a trackpad swipe sends many small wheel events
+  let lastWheel = 0;
+  shelf.addEventListener("wheel", (e) => {
+    const d = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
+    if (!shelf.classList.contains("more") || !d) return;
+    e.preventDefault();
+    if (Date.now() - lastWheel < 250) return;
+    lastWheel = Date.now();
+    step(Math.sign(d));
+  }, { passive: false });
+  addEventListener("resize", fit);
+  new MutationObserver(fit).observe(document.body, { attributeFilter: ["data-panel"] });  // the chat panel opened or closed
+
+  function fit() {  // as wide as fits between the chat panel (or the rail) and the same gap on the right, centred
+    const side = ["messages", "versions"].includes(document.body.dataset.panel) ? "panel" : "rail";
+    const left = document.getElementById(side)?.getBoundingClientRect().right ?? 0;
+    view.style.maxWidth = `${Math.max(130, innerWidth - 2 * (left + 16) - 2 * 32 - 140)}px`;  // the arrows and + beside it
+    shelf.classList.toggle("more", track.scrollWidth > view.clientWidth + 1);
+    arrows();
+  }
+  function arrows() {  // grey at the ends
+    prev.disabled = view.scrollLeft <= 0;
+    next.disabled = view.scrollLeft + view.clientWidth >= view.scrollWidth - 1;
+  }
+  function reveal() {  // the board shown, in view (a new one: the strip goes to the end)
+    const s = track.querySelector(".slot.on");
+    if (s && (s.offsetLeft < view.scrollLeft || s.offsetLeft + s.offsetWidth > view.scrollLeft + view.clientWidth))
+      view.scrollLeft = s.offsetLeft - (view.clientWidth - s.offsetWidth) / 2;
+  }
+
+  const others = document.createElement("style");  // hides what is on the body for other boards (a note's pin)
+  document.head.append(others);
+  function show(n, tell = true) {  // go to board n (tell: the server, which the first show got it from)
+    // before the switch, so a doodle in progress becomes a step with a picture of this board
+    if (n !== current) document.dispatchEvent(new CustomEvent("board", { detail: { from: current, to: n } }));
+    current = n;
+    document.body.dataset.board = n;
+    others.textContent = `body > [data-board]:not([data-board="${n}"]) { display: none !important; }`;
+    for (const b of boards) container(b).classList.toggle("on", b === n);
+    if (tell) page.send({ type: "board_view", board: n });
+    render();
+  }
+
+  function render() {
+    const shown = boards.filter((n) => n !== pending?.n);
+    track.replaceChildren(...shown.map((n) => {
+      const slot = document.createElement("button");
+      slot.className = "slot" + (n === current ? " on" : "");
+      slot.dataset.n = n;
+      slot.title = `Board ${n}`;
+      slot.innerHTML = `<span class="mini"></span><span class="dot"></span><span class="n">${n}</span>` +
+        (shown.length > 1 ? `<span class="x" role="button" title="Remove board ${n} and everything on it">✕</span>` : "");  // the last board stays
+      slot.onclick = (e) => (e.target.closest(".x") ? removeBoard(n) : show(n));
+      slot.onmouseenter = () => showPeek(slot);
+      slot.onmouseleave = () => { peek.hidden = true; };  // off it (onto +, a gap): no preview
+      return slot;
+    }));
+    if (shelf.classList.contains("open")) { thumbnails(); fit(); reveal(); }
+    else fit();
+  }
+
+  // ✕ on a thumbnail: the board leaves the shelf with a few seconds of Undo, and only then goes from the server
+  // (board_remove: its things go with it). Leaving the page in those seconds removes it at once.
+  let pending = null;  // {n, was: the board shown when ✕ was clicked, timer}
+  const toast = Object.assign(document.createElement("div"), { className: "boards-toast", hidden: true });
+  document.body.append(toast);
+  function removeBoard(n) {
+    if (pending) commit();
+    const i = boards.indexOf(n);
+    pending = { n, was: current, timer: setTimeout(commit, 5000) };
+    peek.hidden = true;
+    if (current === n) show(boards.filter((b) => b !== n)[Math.max(0, i - 1)]);  // the one before it (else after)
+    else render();
+    toast.replaceChildren(`Board ${n} removed`, button("", "Undo", "Bring it back", undo));
+    toast.hidden = false;
+  }
+  function commit() {
+    clearTimeout(pending.timer);
+    page.send({ type: "board_remove", board: pending.n });
+    pending = null;
+    toast.hidden = true;
+  }
+  function undo() {
+    clearTimeout(pending.timer);
+    const { n, was } = pending;
+    pending = null;
+    toast.hidden = true;
+    if (was === n) show(n);
+    else render();
+  }
+  addEventListener("pagehide", () => { if (pending) commit(); });
+
+  function thumbnails() {
+    for (const slot of shelf.querySelectorAll(".slot")) drawBoard(slot.querySelector(".mini"), Number(slot.dataset.n), 120, 68);
+  }
+  // board n's things where they are in the main space, scaled down into mini (w x h): a surface is a small card in
+  // its main colour (accentOf), no words. Zoomed to fit what's on the board (not the whole window), so the cards fill it.
+  function drawBoard(mini, n, W, H) {
+    const PAD = 12, els = [...container(n).children];
+    const rects = els.map((el) => el.getBoundingClientRect());
+    const x0 = Math.min(...rects.map((r) => r.left)) - PAD, y0 = Math.min(...rects.map((r) => r.top)) - PAD;
+    const k = Math.min(W / (Math.max(...rects.map((r) => r.right)) + PAD - x0), H / (Math.max(...rects.map((r) => r.bottom)) + PAD - y0), 0.5);
+    mini.style.height = `${H}px`;
+    mini.replaceChildren(...els.map((el, n) => {
+      const r = rects[n], i = document.createElement("i");
+      if (el.dataset.surface) {
+        const accent = accentOf(el.querySelector(".surface-body") ?? el);
+        i.className = "s";
+        i.title = el.dataset.surface;
+        if (accent) i.style.setProperty("--accent-of", accent);
+        if (W > 200) { i.classList.add("detail"); sketch(el, i, k); }  // the big preview: what's inside it
+      }
+      Object.assign(i.style, { left: `${(r.left - x0) * k}px`, top: `${(r.top - y0) * k}px`,
+                               width: `${Math.max(2, r.width * k)}px`, height: `${Math.max(2, r.height * k)}px` });
+      return i;
+    }));
+  }
+  // hover one thumbnail: a bigger picture of that board above the shelf, to read it
+  const peek = Object.assign(document.createElement("div"), { className: "boards-peek", hidden: true });
+  document.body.append(peek);
+  function showPeek(slot) {
+    if (!slot || drag) return (peek.hidden = true);
+    const n = Number(slot.dataset.n), mini = Object.assign(document.createElement("div"), { className: "mini" });
+    peek.replaceChildren(Object.assign(document.createElement("div"), { className: "n", textContent: `Board ${n}` }), mini);
+    peek.hidden = false;
+    drawBoard(mini, n, 320, 180);
+    if (!mini.children.length) mini.append(Object.assign(document.createElement("span"), { className: "empty", textContent: "Empty" }));
+    const s = slot.getBoundingClientRect(), half = peek.offsetWidth / 2;
+    peek.style.left = `${Math.min(innerWidth - half - 8, Math.max(half + 8, s.left + s.width / 2))}px`;
+    peek.style.bottom = `${innerHeight - shelf.getBoundingClientRect().top + 8}px`;
+  }
+  // a surface's insides, scaled by k into its card (the big preview): each line of text a bar in its colour, coloured
+  // areas (buttons, filled boxes) in theirs, pictures and canvases (a game) as small images. Apps' pages too (same
+  // server). No words. At most 400 pieces a surface.
+  function sketch(surface, card, k) {
+    const base = surface.getBoundingClientRect();
+    const put = (tag, r, dx, dy, style) => {
+      if (r.width * k < 0.5 || r.height * k < 0.5) return null;
+      const e = card.appendChild(document.createElement(tag));
+      Object.assign(e.style, { position: "absolute", left: `${(r.left + dx - base.left) * k}px`, top: `${(r.top + dy - base.top) * k}px`,
+                               width: `${r.width * k}px`, height: `${r.height * k}px` }, style);
+      return e;
+    };
+    const roots = [[surface.querySelector(".surface-body") ?? surface, 0, 0]];
+    for (const f of surface.querySelectorAll("iframe")) {
+      try { const r = f.getBoundingClientRect(); if (f.contentDocument?.body) roots.push([f.contentDocument.body, r.left + f.clientLeft, r.top + f.clientTop]); } catch {}
+    }
+    let n = 0;
+    for (const [root, dx, dy] of roots) {
+      const win = root.ownerDocument.defaultView, walk = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+      for (let node = walk.currentNode; node && n < 400; node = walk.nextNode()) {
+        if (node.nodeType === 3) {  // text: a bar per line, in its colour
+          if (!node.data.trim() || node.parentElement.closest("style, script")) continue;
+          const range = root.ownerDocument.createRange();
+          range.selectNodeContents(node);
+          const color = win.getComputedStyle(node.parentElement).color;
+          for (const r of range.getClientRects())
+            if (put("u", { left: r.left, top: r.top + r.height * 0.3, width: r.width, height: r.height * 0.4 }, dx, dy,
+                     { background: color, opacity: "0.45", borderRadius: "1px" })) n++;
+          continue;
+        }
+        const cs = win.getComputedStyle(node), r = node.getBoundingClientRect();
+        if (node.localName === "img" && node.currentSrc) { const e = put("img", r, dx, dy, { objectFit: cs.objectFit }); if (e) { e.src = node.currentSrc; n++; } }
+        else if (node.localName === "canvas") {
+          let src = null;
+          try { src = node.toDataURL("image/png"); } catch {}  // a canvas painted from another site can't be read
+          const e = put(src ? "img" : "u", r, dx, dy, src ? {} : { background: "rgba(0, 0, 0, 0.12)" });
+          if (e && src) e.src = src;
+          if (e) n++;
+        } else if ((cs.backgroundColor.match(/[\d.]+/g)?.[3] ?? 1) > 0.05 && !/^rgba?\(255, 255, 255/.test(cs.backgroundColor) && cs.backgroundColor !== "transparent") {
+          if (put("u", r, dx, dy, { background: cs.backgroundColor, borderRadius: `${parseFloat(cs.borderTopLeftRadius) * k}px` })) n++;
+        }
+      }
+    }
+  }
+  // the colour a thing shows most: each coloured background counts by its area, a border or text a little; whites,
+  // greys and blacks don't count. Apps are pages from this server, so their frame's insides count too. None: null
+  function accentOf(node) {
+    const roots = [node, ...[...node.querySelectorAll("iframe")].map((f) => { try { return f.contentDocument?.body; } catch { return null; } })];
+    const score = {};
+    const add = (color, weight) => {
+      const m = color.match(/[\d.]+/g)?.map(Number);
+      if (!m || (m[3] ?? 1) < 0.3) return;
+      const [r, g, b] = m, max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 510;
+      const sat = max === min ? 0 : (max - min) / 255 / (1 - Math.abs(2 * l - 1));
+      if (sat < 0.25 || l < 0.12 || l > 0.92) return;  // white, grey, black
+      const key = `rgb(${r & 0xf0},${g & 0xf0},${b & 0xf0})`;  // near colours count together
+      score[key] = { color: `rgb(${r},${g},${b})`, n: (score[key]?.n ?? 0) + weight };
+    };
+    for (const root of roots.filter(Boolean)) {
+      for (const e of [root, ...root.querySelectorAll("*")].slice(0, 400)) {
+        const cs = e.ownerDocument.defaultView.getComputedStyle(e);
+        add(cs.backgroundColor, Math.min(e.offsetWidth * e.offsetHeight, 60000));
+        if (parseFloat(cs.borderTopWidth) > 0) add(cs.borderTopColor, 400);
+        if ([...e.childNodes].some((c) => c.nodeType === 3 && c.data.trim())) add(cs.color, 300);
+        if (e.localName === "svg" || e.closest("svg")) add(cs.fill, 600);
+      }
+    }
+    return Object.values(score).sort((a, b) => b.n - a.n)[0]?.color ?? null;
+  }
+  function open(yes) {
+    shelf.classList.toggle("open", yes);
+    if (yes) { thumbnails(); fit(); reveal(); }
+    else { peek.hidden = true; fit(); }
+  }
+
+  // drag a surface (by its label: ui/browser.js moves it) onto a thumbnail: it goes to that board, at the place it had
+  document.addEventListener("pointerdown", (e) => {
+    const box = e.target.closest?.("[data-surface] > .surface-label")?.parentElement;
+    if (!box || e.target.closest("button")) return;
+    const px = (v) => (v ? parseFloat(v) : undefined);
+    drag = { id: box.dataset.surface, board: Number(box.dataset.board) || 1,
+             place: box.hasAttribute("data-placed") ? { x: box.offsetLeft, y: box.offsetTop, width: px(box.style.width), height: px(box.style.height) } : null };
+  });
+  document.addEventListener("pointermove", (e) => {
+    if (!drag) return;
+    const r = shelf.getBoundingClientRect();
+    if (!shelf.classList.contains("open") && e.clientY > r.top - 80 && e.clientX > r.left - 80 && e.clientX < r.right + 80) open(true);
+    const under = document.elementsFromPoint(e.clientX, e.clientY);
+    const now = under.find((el) => el.matches(".boards-shelf .slot")) ?? null;
+    if (now !== over) { over?.classList.remove("drop"); over = now; over?.classList.add("drop"); }
+    const arrow = under.find((el) => el.matches(".boards-shelf .arrow:not(:disabled)"));  // held over ‹ or ›: the strip moves on
+    if (arrow && Date.now() - lastStep > 600) { lastStep = Date.now(); step(arrow === prev ? -1 : 1); }
+  });
+  let lastStep = 0;
+  document.addEventListener("pointerup", () => {
+    if (!drag) return;
+    const to = over && Number(over.dataset.n);
+    if (to && to !== drag.board) page.send({ type: "ui_board", surface: drag.id, board: to, place: drag.place });
+    over?.classList.remove("drop");
+    drag = over = null;
+    if (!shelf.matches(":hover")) open(false);
+  });
+
+  page.on("boards", (ev) => {
+    boards = ev.boards;
+    if (ev.removed) {  // its things went with it (their own events); its container goes now
+      containers[ev.removed]?.remove();
+      delete containers[ev.removed];
+      if (!boards.includes(current)) return show(boards[0]);  // another page removed the board this one shows
+    }
+    if (ev.added && ev.by === "user" && adding) { adding = false; return show(ev.added); }  // the + clicked here: go there
+    render();
+  });
+
+  try { ({ boards, current } = await (await fetch("/boards")).json()); } catch {}
+  show(current, false);  // nothing to tell: the server said it (and the page's WebSocket may not be open yet)
+}

package/app/extensions/boards/guide.md

@@ -0,0 +1,4 @@
+# Boards
+The user's work is on numbered boards; the page shows one at a time. A plain message doesn't say which board the
+user means: when it names one, use that; when it is about something already built, use that thing's board; else
+call boards() (it says which board the user is on) and, if it is still unclear, ask the user.

package/app/extensions/boards/index.ts

@@ -0,0 +1,98 @@
+// Boards: the main space is several numbered boards, and everything on it (surfaces, frames, notes; a doodle's
+// steps when sent) has a board number. Numbers are never reused: remove board 2 and the rest stay 1, 3, 4, so "board 3" keeps
+// meaning the same board to the user and to every agent. A thing with no number is on board 1.
+//   app/ui/boards.json   {last: <last number>, boards: [numbers]}: next to surfaces.json, so a rollback of the code
+//                        brings back both together (read each time: never stale after one)
+// The board the user is looking at is the page's to say (in memory; board 1 until it does). browser.js: the shelf.
+// Tool boards(board?): the boards and what is on each, and the board the user is on. Others use host.api.boards:
+//   list() -> [numbers]   has(n)   add(by?) -> the new number   current() -> the user's board
+//   onRemove(name, fn)    remove(n): see below
+//   GET /boards  {boards, current}      page messages  board_view {board}, board_add, board_remove {board}
+//   event "boards"  {boards, added, by}: a board was added (by "user": that page goes there); {boards, removed}
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const host = (globalThis as any).chalky;
+const FILE = path.join(host.app, "ui/boards.json");
+const read = () => (fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 1, boards: [1] });
+if (!host.shared.has("board-view")) host.shared.set("board-view", { current: 1 });
+const view = host.shared.get("board-view");
+
+host.api.boards = {
+  list: () => read().boards as number[],
+  has: (n: number) => read().boards.includes(n),
+  add(by = "agent") {  // by "user": the page that asked goes there
+    const saved = read();
+    saved.boards.push(++saved.last);
+    fs.writeFileSync(FILE, JSON.stringify(saved));
+    host.broadcast("boards", { boards: saved.boards, added: saved.last, by });
+    return saved.last;
+  },
+  current: () => (read().boards.includes(view.current) ? view.current : read().boards[0]),
+  // Removing a board (the user's ✕, after its few seconds of Undo on the page): each extension takes its own things
+  // off it (onRemove(name, fn): fn(n) deletes them and returns [{owner, what}], e.g. {owner: "agent2", what:
+  // "surface prices"}; name: the extension's, so its reload replaces its own). Each agent that owned something gets
+  // one fyi (no turn of its own: it reads it on its next one). The last board stays.
+  onRemove: (name: string, fn: (n: number) => { owner?: string; what: string }[]) => removers.set(name, fn),
+  remove(n: number) {
+    const saved = read();
+    if (!saved.boards.includes(n) || saved.boards.length === 1) return;
+    const gone: { owner?: string; what: string }[] = [];
+    for (const [name, fn] of removers) {
+      try { gone.push(...fn(n)); }
+      catch (e) { host.broadcast("error", { agent: "server", text: `board ${n} removal, ${name}: ${e}` }); }
+    }
+    saved.boards = saved.boards.filter((b: number) => b !== n);
+    fs.writeFileSync(FILE, JSON.stringify(saved));
+    host.broadcast("boards", { boards: saved.boards, removed: n });
+    const byOwner = new Map<string, string[]>();
+    for (const g of gone) if (g.owner && host.agents.has(g.owner)) byOwner.set(g.owner, [...(byOwner.get(g.owner) ?? []), g.what]);
+    for (const [owner, things] of byOwner)
+      host.api.swarm?.fyi("user", owner, `[board removed] The user removed board ${n}; your ${things.join(", ")} went with it.`);
+  },
+};
+// on the host, so they outlive this file's reloads (as ui's watchers)
+const removers: Map<string, (n: number) => { owner?: string; what: string }[]> = host.shared.get("board-removers") ?? new Map();
+host.shared.set("board-removers", removers);
+
+const result = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
+
+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.boards = guide; });
+
+  pi.registerTool({
+    name: "boards", label: "Boards",
+    description: "List the boards, what is on each, and the board the user is on. With a board: that one in detail.",
+    parameters: Type.Object({ board: Type.Optional(Type.Number()) }),
+    async execute(_id, a) {
+      // what has a board: surfaces (ui/), frames not filled yet (frames/), open notes (point/); doodles aren't kept
+      const of = (m: any) => Object.entries(m ?? {}) as [string, any][];
+      const kinds = (n: number) => [of(host.shared.get("ui")?.surfaces), of(host.shared.get("frames")?.frames), of(host.shared.get("point")?.open)]
+        .map((list) => list.filter(([, r]) => (r.board ?? 1) === n));
+      const head = `the user is on board ${host.api.boards.current()}`;
+      if (a.board === undefined)
+        return result([head, ...host.api.boards.list().map((n: number) => {
+          const [s, f, notes] = kinds(n);
+          return `${n}  ${[s.map(([id]) => id).join(", "), f.map(([id]) => id).join(", "), notes.map(([id]) => `note ${id}`).join(", ")]
+            .filter(Boolean).join(" · ") || "(empty)"}`;
+        })].join("\n"));
+      if (!host.api.boards.has(a.board)) return result(`error: no board ${a.board}. Boards: ${host.api.boards.list().join(", ")}`);
+      const [s, f, notes] = kinds(a.board);
+      return result([head, `board ${a.board}:`,
+        ...s.map(([id, r]) => `  surface ${id} · by ${r.owner} · place ${JSON.stringify(r.place)}${r.pinned ? " · pinned" : ""}`),
+        ...f.map(([id, r]) => `  frame ${id} "${r.text}" · ${r.sent ? `sent to ${r.to}` : "not sent"} · place ${JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height })}`),
+        ...notes.map(([id, r]) => `  note ${id} "${r.text}" · to ${r.to}`)].join("\n") + (s.length + f.length + notes.length ? "" : "\n  (empty)"));
+    },
+  });
+
+  host.routes.set("/boards", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
+    .end(JSON.stringify({ boards: host.api.boards.list(), current: host.api.boards.current() })));
+  host.pageHandlers.set("boards", (msg: any) => {
+    if (msg.type === "board_view" && host.api.boards.has(Number(msg.board))) view.current = Number(msg.board);
+    else if (msg.type === "board_add") host.api.boards.add("user");
+    else if (msg.type === "board_remove") host.api.boards.remove(Number(msg.board));
+  });
+}