@chalky/chalky 0.1.3 → 0.1.5

package/agent/extensions/board/browser.js

@@ -0,0 +1,359 @@
+// The page side of the board extension: 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 card, 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 card by its label onto a thumbnail to move it to that board, where it was ({type: "card_board"}).
+//   page messages  board_view {board}: the board this page shows; board_add
+//   GET /board     {boards, current}        event "board" {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 card: a tile 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" });
+  shelf.dataset.name = "boards";
+  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" }); });
+  add.dataset.name = "new-board";
+  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 card is a small tile in
+  // its main colour (accentOf), no words. Zoomed to fit what's on the board (not the whole window), so the tiles 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.card) {
+        const accent = accentOf(el.querySelector(".card-body") ?? el);
+        i.className = "s";
+        i.title = el.dataset.card;
+        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 card's insides, scaled by k into its tile (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 card.
+  function sketch(card, tile, k) {
+    const base = card.getBoundingClientRect();
+    const put = (tag, r, dx, dy, style) => {
+      if (r.width * k < 0.5 || r.height * k < 0.5) return null;
+      const e = tile.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 = [[card.querySelector(".card-body") ?? card, 0, 0]];
+    for (const f of card.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 card (by its label: card/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-card] > .card-label")?.parentElement;
+    if (!box || e.target.closest("button")) return;
+    const px = (v) => (v ? parseFloat(v) : undefined);
+    drag = { id: box.dataset.card, 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: "card_board", card: drag.id, board: to, place: drag.place });
+    over?.classList.remove("drop");
+    drag = over = null;
+    if (!shelf.matches(":hover")) open(false);
+  });
+
+  page.on("board", (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("/board")).json()); } catch {}
+  show(current, false);  // nothing to tell: the server said it (and the page's WebSocket may not be open yet)
+}

package/agent/extensions/board/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
+leave board out (card_show puts a new card on the board the user is on). board_list() lists them all.

package/agent/extensions/board/index.ts

@@ -0,0 +1,100 @@
+// Boards: the main space is several numbered boards, and everything on it (cards, 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.
+//   built/board.json     {last: <last number>, boards: [numbers]}: next to card.json, so a rollback
+//                        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.board:
+//   list() -> [numbers]   has(n)   add(by?) -> the new number   current() -> the user's board
+//   onRemove(name, fn)    remove(n): see below
+//   GET /board   {boards, current}      page messages  board_view {board}, board_add, board_remove {board}
+//   event "board"   {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.built, "board.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.board = {
+  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("board", { 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:
+  // "card 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("board", { 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.team?.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) {
+
+  pi.registerTool({
+    name: "board_list", label: "Board list",
+    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: cards (card/), frames not filled yet (frame/), open notes (note/), marks not cleared (doodle/)
+      const of = (m: any) => Object.entries(m ?? {}) as [string, any][];
+      const kinds = (n: number) => [of(host.shared.get("card")?.cards), of(host.shared.get("frame")?.frames),
+                                    of(host.shared.get("note")?.notes).filter(([, r]) => r.state === "open"),
+                                    of(host.shared.get("doodle")?.groups).filter(([, r]) => r.state !== "cleared")]
+        .map((list) => list.filter(([, r]) => (r.board ?? 1) === n));
+      const head = `the user is on board ${host.api.board.current()}`;
+      if (a.board === undefined)
+        return result([head, ...host.api.board.list().map((n: number) => {
+          const [s, f, notes, marks] = kinds(n);
+          return `${n}  ${[s.map(([id]) => id).join(", "), f.map(([id]) => id).join(", "), notes.map(([id]) => `note ${id}`).join(", "),
+                           marks.map(([id]) => `marks ${id}`).join(", ")]
+            .filter(Boolean).join(" · ") || "(empty)"}`;
+        })].join("\n"));
+      if (!host.api.board.has(a.board)) return result(`error: no board ${a.board}. Boards: ${host.api.board.list().join(", ")}`);
+      const [s, f, notes, marks] = kinds(a.board);
+      return result([head, `board ${a.board}:`,
+        ...s.map(([id, r]) => `  card ${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.thread[0]?.text}" · to ${r.to}`),
+        ...marks.map(([id, r]) => `  marks ${id} (${r.state}) · ${r.label}`)].join("\n") + (s.length + f.length + notes.length + marks.length ? "" : "\n  (empty)"));
+    },
+  });
+
+  host.routes.set("/board", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
+    .end(JSON.stringify({ boards: host.api.board.list(), current: host.api.board.current() })));
+  host.pageHandlers.set("board", (msg: any) => {
+    if (msg.type === "board_view" && host.api.board.has(Number(msg.board))) view.current = Number(msg.board);
+    else if (msg.type === "board_add") host.api.board.add("user");
+    else if (msg.type === "board_remove") host.api.board.remove(Number(msg.board));
+  });
+}

package/agent/extensions/card/README.md

@@ -0,0 +1,88 @@
+# Cards (the card extension)
+A card is one thing you show the user on a board in the page's main space: a form, a table, a dashboard, a game.
+It shows either blocks (pieces described as JSON) or an app (a page you write). Prefer a card over editing the page
+({agent}/extensions/page/page.html). Aim for one screen; make it scroll only if the user asks.
+A card shows only what you build, with no frame: when asked for a thing (a smiley, a chart), show just that thing.
+Add a background, border or Panel only if the thing itself needs one. An app's page should keep a transparent
+background, so it sits on the board.
+Name what you build (a clear card id, block ids, ids or data-name on elements): the user points at things by name.
+Blocks or an app? What the user clicks never wakes you, so the page must do everything a click should do:
+- Blocks (card_show with blocks), when clicks and typing only store a value: the layout is fixed, the user types,
+  picks, ticks or switches tabs (Button set, when, bindings), and you read the data when they next write. Status,
+  tables, summaries, forms, settings, a fixed checklist, a dashboard you fill in.
+- An app, when the page must work something out or change its own shape while the user uses it: compute a value
+  (a total, a streak, a score), add or remove items, follow rules or time (a game, a timer), draw (a chart).
+  Trackers, calculators, games, editors, charts.
+The test: if a click or keystroke should change anything other than the value it sets, it is an app. Blocks
+can't append to a list or calculate; a Button only writes the fixed value it was given.
+A new block is for one part blocks can't do yet that many cards will reuse; then use it from JSON.
+Before building or restyling what the user sees, load the design skill (how it should look and read).
+- card_blocks (load it with tool_search): lists the blocks and their props. Read it first.
+- card_show(card, blocks, data): show a card, or replace it. blocks is a flat list; each has "id", "block" (its
+  kind, a name from card_blocks), its props, and "children": [ids] or "child": id. One has id "root".
+  A prop can be {"path": "/x"} to bind it to this card's data (inputs write to it), or
+  {"ref": "other-card", "path": "/x"} to read another card's data live (no copy: it follows changes).
+  Any block can have "when": {"path": "/x", "is": value}: hidden while the data there is something else.
+  Tabs: Buttons with "set": {"/tab": "today"} etc., and one block per tab with "when": {"path": "/tab", "is": ...};
+  start the data with the first tab ({"tab": "today"}). Errors come back to you; fix and retry.
+- card_show(card, app=<name>): the card shows that app, then says what it found on the board (errors, and whether
+  it fits its card): fix what it reports. Write the page first, in
+  {built}/apps/<name>/index.html (its other files next to it); the app extension's README says how an app keeps
+  its data and talks to the agents. height: its height in px when nothing else sizes it (default 400).
+- about="...": one or two sentences on what the card is for and why it is built this way. The user reads it on
+  the card's back side; you read it in {built}/card.json. Keep it true when you change things.
+- options=[{"label", "blocks" or "app", "data"}, ...] instead of blocks or app: when you are not sure what the user
+  meant, offer 2-3 versions; they flip through them and keep one.
+- Pinned cards (the user held their label): your card_show, card_update and card_remove on them fail. Don't work
+  around it: make a new card (made_from=[the pinned one]) or ask the user.
+- Cards stack in the main space and are as wide as their content. place={"x", "y", "width"?, "height"?}
+  (px from the main space's top-left) pins one at a spot instead: use it when the user points at a spot ("here")
+  or draws an area (then fill that area: its x, y, width and height).
+- Everything you show is draggable by default: the user moves a card by its label (shown on hover), and it stays
+  where they put it (card_show without place keeps it there; where things are now: the "place" of each card in
+  {built}/card.json). Pass draggable=false only when the user wants something fixed. In an app you build, make
+  separate pieces draggable too, unless told otherwise.
+- Everything you show is resizable by default too: the user drags its bottom-right corner (shown on hover), and
+  the card's root block (or its app) fills the new size. So build things that fill their space (sizes in %, flex,
+  or scaled to their box, e.g. an SVG with a viewBox), not fixed px. Pass resizable=false only when the user wants
+  a fixed size.
+- card_update(card, path, value): change data only (fast; blocks keep their state). With block=<its id>, path is a
+  prop of that block (e.g. a label's text): a small fix without card_show. card_show without data keeps the card's
+  data. card_remove(card) takes it off its board.
+- Data (what users typed, rows, scores) is kept in {data}/card.json (not versioned); the rest of each card in
+  {built}/card.json. The user can undo any change (theirs or yours), so don't keep backups.
+- A Button's click writes its set ({path: value}) into the card's data on the page; you are not woken, and you
+  see the data in {data}/card.json. A row of Buttons setting the same path works as tabs.
+- Voice input (dictation, meeting notes): import /voice/voice.js in the app (read its header), never the browser's
+  speech API or a provider directly: it uses the sandbox's speech-to-text API, or the browser's.
+- A new block: {agent}/extensions/card/blocks/<Name>.js. Start with a comment line "// Name: what it does" (more
+  comment lines if needed), then its about block, then
+  `export default class extends HTMLElement { update(props, card) {...} }`.
+  The about block of a block (strict JSON after `export const about = `):
+    "version": 1             the shape of its props; raise it when they change, and export
+                             upgrade(props, fromVersion) -> props, so cards saved earlier still draw
+    "props": {"name": {"type": "text" | "number" | "boolean" | "choice" | "list" | "rows" | "object" | "action",
+                       "options": [...] (for choice), "default": ..., "doc": "what it is"}}
+    "children": "none" | "one" | "many"
+    "levers": ["Shown as {variant}."]   the back side: plain sentences; each {prop} becomes a control the user
+                             can change there (choice and boolean cycle, text and number are typed)
+    "accepts": "rows with a number column"   optional: what it can take when something is dropped on it
+    "example": {...props}    one sample, for the catalog and for checks
+  update() runs on every change, on the same element: keep internal state there (e.g. a game loop).
+  card.children: child elements, placed with card.mount(container); card.set(prop, value) writes a bound prop;
+  card.data is the card's data and card.write({path: value}) changes it (saved, you are not woken).
+  card.action(name, context) sends an action to you and wakes you: only for what truly needs you (e.g. "ask the
+  agents"), never for clicks the page can handle. Make it general so it can be reused. New blocks work
+  immediately; edited blocks and app files show when your turn ends (the page refreshes itself).
+  Pointing inside a canvas: give the element (or an app page's window) a partAt(x, y) function returning
+  {"name", ...} for what is at that spot, so the user can point at parts (an enemy, a cell).
+- Agents inside what you build (a simulation's members, a debate, characters): load the app-agents skill first.
+  They are real agents that belong to the app, not workers helping you build it.
+- Libraries: blocks import marked and dompurify by name (import { marked } from "marked"), as mapped in the import
+  map at the top of {agent}/extensions/page/page.html. To add one, put its ES-module build in
+  {agent}/extensions/card/lib/<pkg>/ and import it by path (/card/lib/<pkg>/<file>.js).
+- Block pitfalls (you can't see the browser, so avoid them up front):
+  keep your own state in one object, this.state = {...}: fields like this.dir, this.title, this.hidden,
+  this.id, this.style, this.lang are built-in HTMLElement properties and silently break;
+  set a canvas's width/height BEFORE drawing (resizing clears it); don't create things twice in update();
+  remove document-level listeners/timers when the element is no longer connected.

package/agent/extensions/card/blocks/Button.js

@@ -0,0 +1,34 @@
+// Button: a click writes {set} into the card's data, on the page (no agent is woken). It looks primary
+// while the data already holds those values, so a row of them works as tabs.
+export const about = {
+  "version": 2,
+  "props": {
+    "label": {"type": "text", "default": "OK"},
+    "set": {"type": "object", "doc": "{path: value, ...} written into this card's data on click, e.g. {\"/tab\": \"training\"}"},
+    "variant": {"type": "choice", "options": ["primary", "secondary"], "default": "primary", "doc": "its look when not selected"}
+  },
+  "children": "none",
+  "levers": ["Says {label}.", "Sets {set}.", "Looks {variant}."],
+  "example": {"label": "Training", "set": {"/tab": "training"}, "variant": "secondary"}
+};
+export function upgrade(props, from) {  // version 1 sent an action to the agent instead
+  const { action, context, ...rest } = props;
+  return rest;
+}
+const get = (data, path) => path.split("/").filter(Boolean).reduce((o, k) => o?.[k], data);
+export default class extends HTMLElement {
+  update(props, card) {
+    if (!this.button) {
+      this.button = document.createElement("button");
+      this.button.onclick = () => this.props.set && this.card.write(this.props.set);
+      this.append(this.button);
+    }
+    this.props = props;
+    this.card = card;
+    const selected = props.set && Object.entries(props.set).every(([p, v]) => get(card.data, p) === v);
+    this.button.textContent = props.label || "OK";
+    this.button.style.cssText = "border-radius:980px;padding:7px 16px;font-weight:500;" + (!selected && props.variant === "secondary"
+      ? "background:var(--glass-strong);color:var(--accent);border:1px solid var(--line)"
+      : "background:var(--accent);color:#fff;border:0");
+  }
+}

package/{app/extensions/ui/components → agent/extensions/card/blocks}/Column.js

@@ -10,8 +10,8 @@ export const about = {
   "example": {"gap": 8}
 };
 export default class extends HTMLElement {
-  update({ gap = 8, align = "stretch" }, ui) {
+  update({ gap = 8, align = "stretch" }, card) {
     this.style.cssText = `display:flex;flex-direction:column;gap:${gap}px;align-items:${align}`;
-    ui.mount(this);
+    card.mount(this);
   }
 }