@chalky/chalky 0.1.5 → 0.1.6

package/README.md

@@ -21,6 +21,9 @@ MODEL_BASE_URL=https://your-endpoint/v1 MODEL_API_KEY=... MODEL_NAME=your-model
 
 Then open http://127.0.0.1:3000.
 
+To update: `npm update -g @chalky/chalky`, then restart `chalky`. The new version is merged with what your agents
+changed (see `agent/` below).
+
 | Variable | |
 |---|---|
 | `MODEL_BASE_URL` | the endpoint, up to `/v1` |
@@ -34,8 +37,11 @@ Then open http://127.0.0.1:3000.
 
 `~/.chalky` (or `CHALKY_HOME`) holds:
 
-- `agent/`: what the agents are: their prompt, settings and extensions (the page among them), copied from the
-  package on the first run. The agents edit it. A newer version of the package doesn't overwrite it.
+- `agent/`: what the agents are: their prompt, settings and extensions (the page among them). The agents edit it.
+  Each new version of the package is merged into it at the next start, as a version in the history: files only the
+  new version changed are updated, files only your agents changed stay theirs, and both changes go in when they
+  touch different lines. When both changed the same lines, yours stays, the new version waits next to it as
+  `<file>.new`, and agent1 merges the two. Undo an update like any change, in Versions.
 - `built/`: what the agents made for you: the cards on your boards, and the apps they wrote.
 - `data/`: what is kept while running: conversations, what you typed into cards and apps, notes, undo history.
 - `workspace/`: the agents' working folder; `workspace/drops/` holds your files.

package/agent/SYSTEM.md

@@ -1,6 +1,7 @@
 You are an agent in Chalky. You build what the user sees: the page is a workspace where what you build (cards on
 boards, each showing blocks or an app) 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.
+first version on screen that is already complete and polished; then they point at things on it and leave notes, and
+you change exactly that. The user marks up details, not missing basics.
 - 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.

package/agent/extensions/app/README.md

@@ -1,5 +1,12 @@
 # Making an app (the app extension)
-Everything a usual app needs is here: for one, you don't need the card README or the design and browser-check skills.
+Everything a usual app needs is here (you don't need the card README). The design skill goes deeper on charts,
+diagrams, game art and one look across cards: load it when the app has any of those.
+
+## Before you write
+The first version is already complete and polished: the user marks up details, not missing basics. So first list,
+in a short message, the 3-5 things that would make this app impressive for this subject: what someone who knows the
+subject would expect to find, and a picture (diagram, chart, animation) wherever one explains faster than text.
+Then build all of them in the first version, not a smaller first cut.
 
 ## Write it, show it
 - Write {built}/apps/<name>/index.html (other files next to it), then card_show(card=<id>, app=<name>, about="...").
@@ -45,20 +52,17 @@ The page is light, glassy and quiet; match it unless the user asks for another l
 - Show just the thing: no frame or panel around it unless it needs one. Group with flex/grid and gap.
 - Open in a working state (its real data, or a marked example), never an empty shell; `tabular-nums` for digits.
 - Buttons say what happens ("Add habit"); short plain words; status colours always with a word or icon.
+- Ground it in the subject: its real units, terms and conventions (a chess clock shows mm:ss; a kanban card has an
+  owner and a state). Real content, never lorem ipsum.
+- Summary before detail; show state in form (a pill, a chip, a stripe) as well as numbers.
+- Finish every state: empty, loading, error, done. Interactive things look interactive (hover, pressed, visible
+  keyboard focus); a small transition where something changes, never content hidden waiting for an animation.
 - Avoid the generic AI look: cream and terracotta, purple gradients, emoji as markers, the same shadowed card on
   everything. For a chart, a diagram, a game's art or a restyle, load the design skill.
 
 ## Check it works
-card_show covers errors and fit. Before telling the user what it does, try its main action and a reload with
-{agent}/skills/browser-check/scripts/check.mjs:
-```
-node <that check.mjs> {page}/built/apps/<name>/index.html "eval:(()=>{const i=document.querySelector('#new'); i.value='Test-1';
-  i.dispatchEvent(new Event('input',{bubbles:true})); i.form.requestSubmit(); return 'ok'})()" wait:800 \
-  "eval:document.body.innerText.includes('Test-1')"
-```
-Set values with eval (`type:` adds to what a field already holds). Run it again to see what a reload keeps.
-Your test writes the user's real data: note it first (cat {data}/app/<name>.json) and put it back afterwards
-(PUT, above). Say only what you saw working.
+card_show covers errors and fit. Then, before telling the user what it does, use it on their page as they would:
+load the test-your-app skill. Say only what you saw working.
 
 ## More
 - Calculations (totals, streaks, dates) belong in the page's code, never worked out by you and typed in.

package/agent/extensions/app/skills/test-your-app/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: test-your-app
+description: Test an app you built by using it on the user's page as they would - its main tasks start to finish, a look at it, a reload. Use after card_show, before you tell the user what the app does or that it works.
+---
+# Testing an app you built
+
+Load the interact-with-page skill first: this one only adds what testing needs.
+
+1. Save the app's data: `cat {data}/app/<name>.json > /tmp/<name>.saved.json` (no file: it has saved nothing yet).
+   The test writes the user's real data.
+2. List the user's main tasks, from the app's about and your plan: add, change, remove, filter, the one idea that
+   makes it worth having.
+3. Do each task start to finish through the interface, with the helpers, one or a few steps per page_run, each
+   ending with a read. Never call the app's own functions or set its state yourself: that tests your code, not what
+   the user gets. After each step: did what you expected appear? Any errors in the answer?
+4. Look once: screen_see, and check what reading can't: text cut off or overlapping, things outside their box,
+   colours off the palette, a chart that doesn't match its numbers, empty space. If the user doesn't share their
+   screen, take a browser-check screenshot of {page}/built/apps/<name>/index.html (--shot) and read it.
+5. Reload: `location.reload()` in one page_run, then a read in the next: what was kept?
+6. Fix what you found (edit the part), show it again, and redo the tasks that touched it.
+7. Put the data back: `curl -X PUT --data @/tmp/<name>.saved.json {page}/app/data/<name>` (nothing saved: `--data '{}'`).
+8. Tell the user what you did and what you saw ("added and ticked a habit, reloaded: kept; long names were cut off,
+   now they wrap"), not just "it works".

package/agent/extensions/board/browser.js

@@ -25,9 +25,6 @@ const CSS = `
   .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 › */
@@ -173,8 +170,7 @@ export default async function (page) {
   // ✕ 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);
+  let toast = null;  // the notice with Undo (pageApi.notice)
   function removeBoard(n) {
     if (pending) commit();
     const i = boards.indexOf(n);
@@ -182,20 +178,20 @@ export default async function (page) {
     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;
+    toast?.close();
+    toast = page.notice([`Board ${n} removed`, button("go", "Undo", "Bring it back", undo)], () => pending && commit());  // ✕: removed now
   }
   function commit() {
     clearTimeout(pending.timer);
     page.send({ type: "board_remove", board: pending.n });
     pending = null;
-    toast.hidden = true;
+    toast?.close();
   }
   function undo() {
     clearTimeout(pending.timer);
     const { n, was } = pending;
     pending = null;
-    toast.hidden = true;
+    toast?.close();
     if (was === n) show(n);
     else render();
   }

package/agent/extensions/card/index.ts

@@ -5,10 +5,10 @@
 // skill's headless browser and says what it found: errors, and whether the app fits its card. The cards are shared by every agent: one Cards object on
 // the host, made by whichever agent loads first.
 // One door: every change goes through change(): it saves, tells every open page, and calls every watcher with the
-// card, who did it and the words for it ("you moved s1"; none: part of a bigger change). restore() puts back a
-// saved state (not a change: no watchers). Watchers, registered from session_start:
+// card, who did it ("user" or the agent) and the words for it, without who ("moved s1"; none: part of a bigger
+// change). restore() puts back a saved state (not a change: no watchers). Watchers, registered from session_start:
 //   host.api.card.watch(name, fn(card, by, what))   name: the extension's, so its reload replaces its own
-// (history: a step per change with words; frame: a frame is done when its card appears).
+// (history: a step per change with words; frame: a frame is done when its card appears; version: a version's label).
 //   built/card.json  each card but its data (versioned)      data/card.json  each card's data (what users typed)
 // A card: {owner, blocks | app, data, place, board, about, pinned, options, made_from, instruction, draggable,
 //   resizable, height (an app's, when nothing else sizes it), kinds (each block's about.version, for upgrades)}.
@@ -200,7 +200,7 @@ export default function (pi: ExtensionAPI) {
     const gone = ids.map((id) => ({ owner: cards.cards[id].owner, what: `card ${id}` }));
     ids.forEach((id, i) => {
       cards.copyIntoUsers(id);  // cards elsewhere reading from it keep its values
-      cards.change(id, null, "user", i === ids.length - 1 ? `you removed board ${n} (${ids.join(", ")})` : undefined);
+      cards.change(id, null, "user", i === ids.length - 1 ? `removed board ${n} (${ids.join(", ")})` : undefined);
     });
     return gone;
   }));
@@ -268,13 +268,13 @@ export default function (pi: ExtensionAPI) {
                             ["instruction", a.instruction ?? old.instruction], ["options", options.length ? options : null]] as const) if (v) record[k] = v;
       // its board (board/): the one asked for, a new one, where it already is, or the one the user is on
       if (boards) record.board = a.board === "new" ? boards.add() : a.board ?? old.board ?? boards.current();
-      cards.change(a.card, record, agent, `${agent} showed ${a.card}` + (options.length ? ` (${options.length} options)` : ""));
+      cards.change(a.card, record, agent, `showed ${a.card}` + (options.length ? ` (${options.length} options)` : ""));
       const where = boards ? `on board ${record.board}${a.board === "new" ? " (a new board)" : ""}` : "on screen";
       if (options.length) return result(`card '${a.card}' shows ${options.length} options ${where}; the user flips through them and keeps one`);
       if (!main.app) return result(`card '${a.card}' is ${where}`);
       return result(`card '${a.card}' is ${where}, showing ${host.built}/${main.app} (at http://127.0.0.1:${host.port}/built/${main.app}); `
-        + await checkOnBoard(a.card) + ". Errors and fit are all this checked: now try its main action and a reload (the "
-        + "app README's check) before you tell the user what it does.");
+        + await checkOnBoard(a.card) + ". Errors and fit are all this checked: now use it as the user would (load the "
+        + "test-your-app skill) before you tell the user what it does.");
     },
   });
 
@@ -296,11 +296,11 @@ export default function (pi: ExtensionAPI) {
         b[a.path] = a.value;
         const errors = problems(r.blocks, r.made_from);
         if (errors.length) return result("error: " + errors.join("; "));
-        cards.change(a.card, r, agent, `${agent} set ${a.path} of ${a.block} in ${a.card}`);
+        cards.change(a.card, r, agent, `set ${a.path} of ${a.block} in ${a.card}`);
         return result("updated");
       }
       setPath(r.data, a.path, a.value);
-      cards.change(a.card, r, agent, `${agent} changed ${a.path} in ${a.card}`);
+      cards.change(a.card, r, agent, `changed ${a.path} in ${a.card}`);
       return result("updated");
     },
   });
@@ -313,7 +313,7 @@ export default function (pi: ExtensionAPI) {
       const locked = cards.locked(a.card);
       if (locked) return result(locked);
       const users = cards.copyIntoUsers(a.card), agent = pi.getSessionName() ?? "agent";
-      cards.change(a.card, null, agent, `${agent} removed ${a.card}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+      cards.change(a.card, null, agent, `removed ${a.card}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
       return result("removed" + (users.length ? `; ${users.join(", ")} read from it, so they got a copy of its data` : ""));
     },
   });
@@ -339,30 +339,30 @@ export default function (pi: ExtensionAPI) {
     if (!r || !type?.startsWith("card_")) return;
     if (type === "card_close") {
       const users = cards.copyIntoUsers(id);
-      cards.change(id, null, "user", `you closed ${id}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
+      cards.change(id, null, "user", `closed ${id}` + (users.length ? ` (${users.join(", ")} got a copy)` : ""));
     }
     else if (type === "card_move") {
       if (r.pinned) return host.broadcast("card", { op: "render", card: id, ...r });
-      r.place = msg.place; cards.change(id, r, "user", `you moved ${id}`);
+      r.place = msg.place; cards.change(id, r, "user", `moved ${id}`);
     } else if (type === "card_board" && host.api.board?.has(msg.board)) {  // dropped on another board's thumbnail
       if (r.pinned) return host.broadcast("card", { op: "render", card: id, ...r });
-      r.board = msg.board; r.place = msg.place ?? null; cards.change(id, r, "user", `you moved ${id} to board ${msg.board}`);
-    } else if (type === "card_set") { setPath(r.data, msg.path ?? "/", msg.value); cards.change(id, r, "user", `you changed ${msg.path} in ${id}`); }
+      r.board = msg.board; r.place = msg.place ?? null; cards.change(id, r, "user", `moved ${id} to board ${msg.board}`);
+    } else if (type === "card_set") { setPath(r.data, msg.path ?? "/", msg.value); cards.change(id, r, "user", `changed ${msg.path} in ${id}`); }
     else if (type === "card_prop") {
       for (const b of r.blocks ?? []) if (b.id === msg.block && !STRUCTURE.includes(msg.prop)) b[msg.prop] = msg.value;
-      cards.change(id, r, "user", `you set ${msg.prop} of ${msg.block} in ${id}`);
-    } else if (type === "card_pin") { r.pinned = !!msg.pinned; cards.change(id, r, "user", `you ${r.pinned ? "pinned" : "unpinned"} ${id}`); }
+      cards.change(id, r, "user", `set ${msg.prop} of ${msg.block} in ${id}`);
+    } else if (type === "card_pin") { r.pinned = !!msg.pinned; cards.change(id, r, "user", `${r.pinned ? "pinned" : "unpinned"} ${id}`); }
     else if (type === "card_keep" && r.options) {
       const o = r.options[Number(msg.index ?? 0)];
       delete r.options;
       if (o) {
         delete r.blocks; delete r.app;
         Object.assign(r, o.app ? { app: o.app } : { blocks: o.blocks }, { data: o.data });
-        cards.change(id, r, "user", `you kept ${o.label} of ${id}`);
+        cards.change(id, r, "user", `kept ${o.label} of ${id}`);
       }
     } else if (type === "card_action") {
       r.data = msg.data ?? r.data;
-      cards.change(id, r, "user", `you used ${msg.name} in ${id}`);
+      cards.change(id, r, "user", `used ${msg.name} in ${id}`);
       host.send("user", r.owner, `[card action] ${msg.name} on card '${id}' (${msg.block === "app" ? "its app" : `block ${msg.block}`})\n`
         + `context: ${JSON.stringify(msg.context ?? {})}\ndata: ${JSON.stringify(r.data)}`);
     }

package/agent/extensions/file/browser.js

@@ -3,6 +3,8 @@
 //   Files dragged from the computer onto the page: uploaded (POST /file/upload), then a "file-dropped"
 //   DOM event {x, y, files: [{name, path, size}]} at the drop spot (the note extension opens its note box
 //   there). Dropped onto the panel itself: only stored.
+//   Pasted (Ctrl+V / ⌘V) with files on the clipboard: the same as a drop where the pointer last was (copied
+//   images, all named image.png, become pasted-<date>-<time>.png). Text pastes as usual.
 //   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 extension opens a preview window attached to the row; rows carry data-path).
@@ -42,7 +44,11 @@ export default async function (page) {
     #side .file-bar button { font: inherit; color: var(--text); background: var(--glass-strong); border: 1px solid var(--line);
                               border-radius: 8px; padding: 3px 10px; cursor: pointer; }
     #side .file-bar .delete { color: #fff; background: var(--danger); border-color: transparent; }
-    #side .file-row:hover, #side .file-row.viewing { background: var(--hover); color: var(--text); }`;
+    #side .file-row:hover, #side .file-row.viewing { background: var(--hover); color: var(--text); }
+    .file-uploading { position: fixed; z-index: 200000; max-width: 240px; padding: 5px 10px; border-radius: 10px; font-size: 12px;
+                      white-space: nowrap; overflow: hidden; text-overflow: ellipsis; 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); }`;
   document.head.append(style);
 
   const toggle = document.createElement("button");
@@ -129,15 +135,48 @@ export default async function (page) {
     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)) {
+    store([...e.dataTransfer.files], x, y, onPanel(e));
+  });
+
+  // Upload files (at most MAX), then preview the first and fire "file-dropped" at (x, y), unless they landed on the panel
+  const MAX = 10;
+  async function store(all, x, y, panel, names = all.map((f) => f.name)) {
+    if (all.length > MAX) page.notice([`You added ${all.length} files: only the first ${MAX} were kept.`]);
+    const stored = [], files = all.slice(0, MAX), size = files.reduce((n, f) => n + f.size, 0);
+    const tag = Object.assign(document.createElement("div"), { className: "file-uploading",
+      textContent: `Uploading ${files.length > 1 ? `${files.length} files` : names[0]} · ${Math.ceil(size / 1024)} KB` });
+    Object.assign(tag.style, { left: `${Math.min(x + 14, innerWidth - 260)}px`, top: `${Math.min(y + 16, innerHeight - 40)}px` });
+    const slow = setTimeout(() => document.body.append(tag), 500);  // only when it takes a while
+    for (const [i, f] of files.entries()) {
       try {
-        const out = await (await fetch(`/file/upload?name=${encodeURIComponent(f.name)}`, { method: "POST", body: f })).json();
+        const out = await (await fetch(`/file/upload?name=${encodeURIComponent(names[i])}`, { 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}`); }
+        else page.notice([`Could not upload ${names[i]}: ${out.error}`]);
+      } catch (err) { page.notice([`Could not upload ${names[i]}: ${err}`]); }
     }
+    clearTimeout(slow); tag.remove();
     if (stored.length) opened(stored[0]);  // the list has its row by now (the "file" event comes before the reply)
-    if (stored.length && !onPanel(e)) dropped(x, y, stored);
+    if (stored.length && !panel) dropped(x, y, stored);
+  }
+
+  // Paste (Ctrl+V / ⌘V): files on the clipboard are added as if dropped where the pointer last was.
+  // Text pastes as usual. A paste inside a card's app goes to that app (its own page): Chalky never hears it.
+  let pointer = { x: innerWidth / 2, y: innerHeight / 2 };
+  document.addEventListener("pointermove", (e) => { pointer = { x: e.clientX, y: e.clientY }; }, { passive: true });
+  document.addEventListener("paste", (e) => {
+    const files = [...(e.clipboardData?.files || [])];
+    if (!files.length) {  // a Linux file manager copies the file's address, not the file
+      const text = e.clipboardData?.getData("text/plain") ?? "";
+      const typing = e.target.closest?.("input, textarea, [contenteditable]");
+      if (!typing && /^file:\/\//.test(text.trim())) page.notice(["You copied a file's address, not the file. Drag the file onto the page instead."]);
+      return;
+    }
+    e.preventDefault();
+    const d = new Date(), p = (n) => String(n).padStart(2, "0");
+    const stamp = `pasted-${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
+    let n = 0;  // every copied image arrives as image.png
+    const names = files.map((f) => (!f.name || f.name === "image.png") ? `${stamp}${n++ ? `-${n}` : ""}.${f.type.split("/")[1] || "png"}` : f.name);
+    const { x, y } = pointer;
+    store(files, x, y, side.contains(document.elementFromPoint(x, y)), names);
   });
 }

package/agent/extensions/file/index.ts

@@ -3,7 +3,8 @@
 // the page (from the computer: uploaded here, listed, and a "file-dropped" DOM event so note'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).
+// sent again after each of its tool calls, pi's tool_execution_end, if it changed: a file it saves shows at once,
+// while it is still working).
 //   POST /file/upload?name=<file name>  the file's bytes: saved in DIR (a safe, new name), returns {path, size}
 //   GET  /file                           [{name, path, size}], newest first; files in folders too ("q3/costs.xlsx")
 //   POST /file/delete                   {names: [...]} (names as listed): deleted for good, returns {deleted, errors}
@@ -37,7 +38,7 @@ function changed(always = false) {  // tell the pages, if the list is not what t
 }
 
 export default function (pi: ExtensionAPI) {
-  pi.on("agent_settled", () => changed());  // the agent may have saved files there
+  pi.on("tool_execution_end", () => changed());  // the agent may have saved files there
   if (!host.shared.has("file-last")) host.shared.set("file-last", JSON.stringify(listing()));
 
   host.routes.set("/file", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(listing())));

package/agent/extensions/frame/README.md

@@ -24,8 +24,8 @@ one design, not separate requests: they share one look, and often each other's d
   on the page, with no agent in between. Separate block cards 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 card_show(card=<its id>, place=<its place>, ...): its dashed box goes when that
-  card appears. Keep the place: the user chose where and how big.
+- Fill a frame with card_show(place=<its place>, ...), with any card id (a name for what it is): its
+  dashed box goes when a card appears exactly there. 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 (team_spawn, or idle agents you have): tell each one its frame, and what done
   means: "card <id> shown at <place>, doing <their words>". Say the shared look in each message

package/agent/extensions/frame/index.ts

@@ -3,12 +3,12 @@
 // so it sees the whole layout and decides how to split the work (alone, or with helpers: README.md, not code).
 // A frame is {x, y, width, height, text, sent, to?, board} (main-space px, where card_show's place puts a card;
 // board: the one it was drawn on, board/; Implement sends the frames of the board shown), with an
-// id (frame-1, frame-2, ...: never reused). An agent fills it with card_show(card="frame-1", place=<its place>);
-// when that card appears (a card watcher, host.api.card.watch), the frame is done and its dashed box goes. The user
+// id (frame-1, frame-2, ...: never reused). An agent fills it with card_show(place=<its place>) (any card id);
+// when a card appears at its place (or with its id) (a card watcher, host.api.card.watch), the frame is done and its dashed box goes. The user
 // can remove a frame (its ✕); if it was sent, its agent is told. Until a frame is sent, its corner resizes it.
 //   GET /frame              {id: frame}
 //   page messages           frame_add {x, y, width, height, board}, frame_place {id, x, y, width, height}, frame_text {id, text},
-//                           frame_remove {id}, frame_send {to, board}
+//                           frame_remove {id}, frame_send {to, board, by?} (by: the agent whose code pressed Implement)
 //   event "frame"           {frames: {id: frame}} to every open page, when they changed
 // Saved in data/frame.json as {last: <last id number>, frames: {id: frame}}; shared by every agent (host.shared).
 import fs from "node:fs";
@@ -32,10 +32,17 @@ const place = (f: any) => JSON.stringify({ x: f.x, y: f.y, width: f.width, heigh
 
 export default function (pi: ExtensionAPI) {
 
-  // a frame is done when a card with its id appears (after all extensions loaded: the card one may come later)
+  // a frame is done when a card appears at its place on its board, or with its id (after all extensions loaded: the
+  // card one may come later). The place is what the user chose; agents often give the card a name of its own.
   pi.on("session_start", () => {
     host.api.card?.watch("frame", (sid: string) => {
-      if (frames[sid] && host.shared.get("card")?.cards[sid]) { delete frames[sid]; changed(); }
+      const card = host.shared.get("card")?.cards[sid];
+      if (!card) return;
+      const at = (f: any) => card.place && (card.board ?? 1) === (f.board ?? 1)
+        && ["x", "y", "width", "height"].every((k) => Math.round(card.place[k]) === f[k]);
+      const done = Object.keys(frames).filter((id) => id === sid || at(frames[id]));
+      for (const id of done) delete frames[id];
+      if (done.length) changed();
     });
     host.api.board?.onRemove("frame", (n: number) => {  // a removed board (board/) takes its frames with it
       const ids = Object.keys(frames).filter((id) => (frames[id].board ?? 1) === n);
@@ -70,9 +77,11 @@ export default function (pi: ExtensionAPI) {
       if (!ready.length) return;
       for (const [, f] of ready as any) Object.assign(f, { sent: true, to });
       changed();
-      const lines = [`[frames on the page] the user laid out ${ready.length} frame${ready.length > 1 ? "s" : ""} on board ${board} to fill:`,
+      // by: an agent's code pressed Implement (page/browser.js), not the user
+      const who = !msg.by ? "the user laid out" : msg.by === to ? "you pressed Implement for" : `${msg.by} pressed Implement for`;
+      const lines = [`[frames on the page] ${who} ${ready.length} frame${ready.length > 1 ? "s" : ""} on board ${board} to fill:`,
         ...ready.map(([id, f]: any) => `  ${id}: "${f.text}" · place=${place(f)}`),
-        `  Fill each with card_show(card=<its id>, place=<its place>, board=${board}, ...); its dashed box goes when it appears.`];
+        `  Fill each with card_show(place=<its place>, board=${board}, ...) (any card id): its dashed box goes when a card appears there.`];
       const waiting = Object.keys(frames).filter((id) => frames[id].sent && !ready.some(([r]) => r === id));
       if (waiting.length) lines.push(`  Sent before and not filled yet: ${waiting.join(", ")}.`);
       team.send("user", to, lines.join("\n"));

package/agent/extensions/history/index.ts

@@ -88,7 +88,9 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", () => {
     if (!host.shared.has("history")) host.shared.set("history", new History(host.shared.get("card")));
     host.api.history = host.shared.get("history");
-    host.api.card?.watch("history", (_id: string, by?: string, what?: string) => { if (what) host.api.history.add(by, what); });
+    host.api.card?.watch("history", (_id: string, by?: string, what?: string) => {  // the card's words don't say who
+      if (what) host.api.history.add(by, `${by === "user" ? "you" : by} ${what}`);
+    });
   });
   const shared = (): History | undefined => host.shared.get("history");
 

package/agent/extensions/note/README.md

@@ -32,4 +32,6 @@ thing has partAt), its text, and the file it comes from. Act on that exact thing
   pointer ("this one") use the pen (doodle_mark) instead.
 - When you did what a note asked, note_done(id): its pin turns into a faded ✓, which the user can reopen or delete. If your
   answer leaves anything to them (you suggest something, ask, or offer a choice), leave the note open: their reply
-  comes in the same thread, and you close it once that is settled. The user can close one too (✓ Done); you get an fyi.
+  comes in the same thread, and you close it once that is settled. The user can close one too (✓) or delete it (✕);
+  you get an fyi. A note you started that is no longer needed (it explained a step, the step is past) can go for
+  good: note_done(id, delete: true). Notes the user or another agent started you only close.

package/agent/extensions/note/browser.js

@@ -9,7 +9,8 @@
 // tells every open page to pin it, with its drawing). Esc or the button turns it off.
 // Pins: a numbered pin per note (the agents' in their colour), on the thing it is on, scrolling with the main space
 // and moving with its card. Click one for its thread: who wrote what, a reply box (Enter sends it to the note's
-// agent), ✓ Done; a closed note stays as a faded ✓ (Reopen, or Delete for good). An agent's reply opens the bubble while
+// agent), ✓ (close) and ✕ (delete) at its top right; a closed note stays as a faded ✓ (Reopen). ✕ asks nothing: the pin
+// goes, a notice offers Undo for a few seconds, and only then is the delete sent. An agent's new note, or its reply, opens the bubble while
 // the note stays open. Show marks (doodle/)
 // hides the pins with the other marks.
 // The same note box opens for two more things (Enter on an empty box sends its faded suggestion):
@@ -246,6 +247,9 @@ export default async function (page) {
     .note-pin .bubble .busy { color: var(--muted, #888); font-style: italic; }
     .note-pin .bubble textarea { width: 100%; box-sizing: border-box; min-height: 48px; resize: vertical; font: inherit; padding: 6px 8px;
       border-radius: 8px; border: 1px solid rgba(0, 0, 0, .15); outline: none; background: rgba(255, 255, 255, .8); }
+    .note-pin .bubble .top { float: right; display: flex; gap: 2px; margin: -4px -6px 0 6px; }
+    .note-pin .bubble .top button { width: 24px; height: 24px; border-radius: 6px; font-size: 13px; color: var(--soft, #555); }
+    .note-pin .bubble .top button:hover { background: var(--hover, rgba(0, 0, 0, .05)); color: var(--text, #1d1d1f); }
     .note-pin .bubble .acts { display: flex; justify-content: flex-end; gap: 6px; margin-top: 6px; }
     .note-pin .bubble .acts button { padding: 3px 10px; border-radius: 999px; font-size: 12px; border: 1px solid rgba(0, 0, 0, .12); }
     .note-pin .bubble .acts button.primary { color: #fff; background: var(--accent, #0071e3); border-color: transparent; }`;
@@ -262,7 +266,21 @@ export default async function (page) {
     if (card) { const r = card.getBoundingClientRect(), c = inMain(r.left, r.top); return { x: c.x + n.anchor.dx, y: c.y + n.anchor.dy }; }
     return n.at ?? { x: 0, y: 0 };
   }
+  // Deleting: the pin goes at once, and a notice offers Undo for UNDO_MS; only then is the delete sent (so an undo
+  // needs nothing from the server, and other pages keep the note until it is really gone)
+  const UNDO_MS = 6000;
+  const leaving = {};  // id -> timer, while its undo is offered
+  function remove(id) {
+    openId = null;
+    pins[id]?.remove(); delete pins[id];
+    const undo = Object.assign(document.createElement("button"), { type: "button", className: "go", textContent: "Undo" });
+    const notice = page.notice(["Note deleted", undo], () => {});
+    const gone = () => { delete leaving[id]; notice.close(); page.send({ type: "note_delete", id }); };
+    leaving[id] = setTimeout(gone, UNDO_MS);
+    undo.onclick = () => { clearTimeout(leaving[id]); delete leaving[id]; notice.close(); if (notes[id]) draw(id); };
+  }
   function draw(id) {
+    if (id in leaving) return;  // deleted, its undo still offered
     const n = notes[id];
     let el = pins[id];
     if (!el) {
@@ -283,6 +301,7 @@ export default async function (page) {
     }
     const b = Object.assign(document.createElement("button"), { className: "pin", type: "button", textContent: n.state === "open" ? id.slice(1) : "✓",
       title: `${n.thread[0]?.text ?? ""}${n.state === "open" ? "" : " (closed)"}` });
+    b.setAttribute("aria-label", `note ${id}${n.state === "open" ? "" : " (closed)"}: ${n.thread[0]?.text ?? ""}`);  // what read() and screen readers say
     Object.assign(b.style, { left: `${p.x}px`, top: `${p.y}px` });
     b.onclick = (e) => { e.stopPropagation(); openId = openId === id ? null : id; for (const k of Object.keys(pins)) draw(k); };
     el.append(b);
@@ -309,6 +328,16 @@ export default async function (page) {
       b.onclick = fn;
       acts.append(b);
     };
+    // top right: ✓ closes (a faded pin, can be reopened), ✕ deletes (no question: a few seconds to undo instead)
+    const top = Object.assign(document.createElement("div"), { className: "top" });
+    const corner = (text, title, fn) => {
+      const b = Object.assign(document.createElement("button"), { type: "button", textContent: text, title });
+      b.onclick = fn;
+      top.append(b);
+    };
+    if (n.state === "open") corner("✓", "Done: close this note", () => { openId = null; page.send({ type: "note_close", id }); });
+    corner("✕", "Delete this note", () => remove(id));
+    d.prepend(top);
     if (n.state === "open") {
       const ta = Object.assign(document.createElement("textarea"), { placeholder: "Reply… (Enter sends)", value: drafts[id] ?? "" });
       ta.oninput = () => { drafts[id] = ta.value; };
@@ -319,13 +348,9 @@ export default async function (page) {
         if (e.key === "Escape") { openId = null; draw(id); }
       };
       d.append(ta);
-      button("✓ Done", () => { openId = null; page.send({ type: "note_close", id }); });
       button("Reply", go, true);
       setTimeout(() => ta.focus(), 0);
-    } else {
-      button("Delete", () => { if (confirm("Delete this note for good?")) { openId = null; page.send({ type: "note_delete", id }); } });
-      button("Reopen", () => page.send({ type: "note_reopen", id }));
-    }
+    } else button("Reopen", () => page.send({ type: "note_reopen", id }));
     d.append(acts);
     return d;
   }
@@ -338,8 +363,9 @@ export default async function (page) {
   setInterval(layout, 1500);
   page.on("note_pin", ({ id, type, agent, ts, ...n }) => {
     const reply = notes[id] && n.thread.length > notes[id].thread.length && n.thread.at(-1).by !== "user" && n.state === "open";  // an answer still waiting on the user
+    const started = !notes[id] && n.by !== "user" && n.state === "open";  // an agent's new note (the notes there at load come from /note/all)
     notes[id] = n;
-    if (reply && openId !== id) openId = id;  // an agent answered in the thread: show it
+    if ((reply || started) && openId !== id) openId = id;  // an agent wrote: show it open, so the user sees it
     if (openId === id && n.state !== "open" && n.thread.at(-1)?.by !== "user") openId = null;  // and closed it: done, so out of the way
     draw(id);
   });

package/agent/extensions/note/guide.md

@@ -4,5 +4,6 @@ A note is a thread pinned on a thing; you and the user can both start one. The u
 - Change that exact thing. If its text is data (a row, a score), change the card's data, not the block.
 - Answer in the note's thread (note_reply), not in chat. Ask or explain on a thing with note_add(on, text).
 - When you did what it asked, call note_done(id): the pin stays as a faded ✓ the user can reopen. If your answer
-  leaves anything to them (a suggestion, a question, a choice), leave it open for their reply.
+  leaves anything to them (a suggestion, a question, a choice), leave it open for their reply. A note you started
+  that has served its purpose can go: note_done(id, delete: true).
 Before you handle your first note, read README.md.