@chalky/chalky 0.1.5 → 0.1.7

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

@@ -9,6 +9,8 @@
 // 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"}).
+// Zoom: each board keeps its own (in this browser), as CSS zoom on #top, so places stay in main-space px; the control
+// at the bottom right (−, %, +, fit), or Ctrl/⌘ + wheel (a trackpad pinch). See setZoom below.
 //   page messages  board_view {board}: the board this page shows; board_add
 //   GET /board     {boards, current}        event "board" {boards, added?, by?}
 const CSS = `
@@ -25,9 +27,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 › */
@@ -64,7 +63,22 @@ const CSS = `
   .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 */`;
+  .boards-shelf.open .add { display: block; }  /* only in the open shelf: at rest it's just the dots */
+  /* zoom: CSS zoom on #top scales everything in the main space; its padding (room for the palette, rail, input) stays
+     the same on screen */
+  #top { padding: calc(var(--palette) / var(--zoom, 1)) calc((var(--rail) + 28px) / var(--zoom, 1))
+                  calc(var(--bar) / var(--zoom, 1)) calc((var(--rail) + 28px) / var(--zoom, 1)); }
+  .boards-zoom { position: fixed; right: 16px; bottom: 24px; z-index: 25; display: flex; align-items: center; gap: 2px; padding: 3px;
+    border-radius: 12px; background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+    border: 1px solid var(--edge); box-shadow: var(--shadow); font-size: 12px; color: var(--soft); }
+  .boards-zoom button { height: 26px; min-width: 26px; padding: 0 6px; border-radius: 8px; font-variant-numeric: tabular-nums; }
+  .boards-zoom button:hover { background: var(--hover); color: var(--text); }
+  .boards-zoom .pct { min-width: 46px; }
+  .boards-zoom .fit { font-size: 15px; }
+  /* the hand: drag the board to move around it; what is on it doesn't react meanwhile (apps' frames included) */
+  #top.panning { cursor: grab; }
+  #top.panning.grabbing { cursor: grabbing; }
+  #top.panning * { pointer-events: none !important; }`;
 
 export default async function (page) {
   document.head.insertAdjacentHTML("beforeend", `<style>${CSS}</style>`);
@@ -139,6 +153,129 @@ export default async function (page) {
       view.scrollLeft = s.offsetLeft - (view.clientWidth - s.offsetWidth) / 2;
   }
 
+  // ---- zoom: each board's own, kept in this browser (localStorage) ----
+  // CSS zoom on #top: places stay in main-space px (what cards, frames and marks store), and #top's scrollLeft/Top and
+  // clientWidth are in them too. Window px -> main px is (x - left) / zoom + scroll: the other extensions divide by
+  // #top's style.zoom where they turn the pointer into main px. Ctrl/⌘ + wheel (a trackpad pinch) zooms at the
+  // pointer; the control at the bottom right: −, the percentage (click: back to 100%), +, and fit (the whole board).
+  const MIN = 0.25, MAX = 2, KEY = "chalky.board-zoom";
+  const shot = new URLSearchParams(location.search).has("shot");  // the versions' headless view: always 100%
+  let zooms = {};
+  try { zooms = JSON.parse(localStorage.getItem(KEY)) || {}; } catch {}
+  const zoomOf = () => parseFloat(top.style.zoom) || 1;
+  function setZoom(z, at, save = true) {  // at: the window point that stays put (else the middle of the view)
+    z = shot ? 1 : Math.min(MAX, Math.max(MIN, Math.round(z * 100) / 100));
+    const m = top.getBoundingClientRect(), z0 = zoomOf();
+    at ??= { x: m.left + m.width / 2, y: m.top + m.height / 2 };
+    const p = { x: (at.x - m.left) / z0 + top.scrollLeft, y: (at.y - m.top) / z0 + top.scrollTop };  // in main px
+    top.style.zoom = z === 1 ? "" : z;
+    top.style.setProperty("--zoom", z);
+    if (z !== z0) { top.scrollLeft = p.x - (at.x - m.left) / z; top.scrollTop = p.y - (at.y - m.top) / z; }
+    pct.textContent = `${Math.round(z * 100)}%`;
+    if (save) {
+      if (z === 1) delete zooms[current]; else zooms[current] = z;
+      try { localStorage.setItem(KEY, JSON.stringify(zooms)); } catch {}
+    }
+  }
+  function fitZoom() {  // everything on this board in view
+    const els = [...container(current).children], z0 = zoomOf(), m = top.getBoundingClientRect();
+    if (!els.length) return setZoom(1);
+    const rs = els.map((el) => el.getBoundingClientRect()).filter((r) => r.width || r.height);
+    const main = (x, y) => ({ x: (x - m.left) / z0 + top.scrollLeft, y: (y - m.top) / z0 + top.scrollTop });
+    const a = main(Math.min(...rs.map((r) => r.left)), Math.min(...rs.map((r) => r.top)));
+    const b = main(Math.max(...rs.map((r) => r.right)), Math.max(...rs.map((r) => r.bottom)));
+    const s = getComputedStyle(document.documentElement), px = (v) => parseFloat(s.getPropertyValue(v)) || 0;
+    const side = px("--rail") + 28, w = innerWidth - 2 * side, h = innerHeight - px("--palette") - px("--bar");  // inside the padding
+    const z = Math.min(MAX, Math.max(MIN, Math.min(w / (b.x - a.x + 24), h / (b.y - a.y + 24), 1)));
+    setZoom(z);
+    top.scrollLeft = (a.x + b.x) / 2 - (m.width / 2) / z;
+    top.scrollTop = a.y - 12 - px("--palette") / z;
+  }
+  const zoomBar = Object.assign(document.createElement("div"), { className: "boards-zoom" });
+  zoomBar.dataset.name = "zoom";
+  const pct = button("pct", "100%", "Back to 100%", () => setZoom(1));
+  zoomBar.append(button("", "−", "Zoom out", () => setZoom(zoomOf() / 1.25)), pct,
+                 button("", "+", "Zoom in", () => setZoom(zoomOf() * 1.25)), button("fit", "⤢", "Fit the whole board", fitZoom));
+  document.body.append(zoomBar);
+  const pinch = (e, at) => {  // ctrl + wheel (a pinch on a trackpad sends that): zoom at the pointer, not the browser's
+    if (!e.ctrlKey && !e.metaKey) return;
+    e.preventDefault();
+    setZoom(zoomOf() * Math.exp(-e.deltaY * (e.deltaMode ? 0.05 : 0.01)), at);
+  };
+  // anywhere on the page, not only over the main space: over the messages panel (which lies over the board) a pinch
+  // would otherwise scroll the messages; captured, so nothing under the pointer scrolls with it
+  addEventListener("wheel", (e) => pinch(e, { x: e.clientX, y: e.clientY }), { passive: false, capture: true });
+  top.addEventListener("load", (e) => {  // an app's frame (same site): its pinches too, its px turned into window px
+    const fr = e.target;
+    if (fr.localName !== "iframe") return;
+    try {
+      fr.contentWindow.addEventListener("wheel", (ev) => {
+        const r = fr.getBoundingClientRect(), k = zoomOf();
+        pinch(ev, { x: r.left + fr.clientLeft * k + ev.clientX * k, y: r.top + fr.clientTop * k + ev.clientY * k });
+      }, { passive: false });
+    } catch {}  // another site's frame
+  }, true);
+
+  // ---- the hand: drag to move around the board (scrolls #top). The palette's hand tool (one tool at a time, Esc
+  // stops it); or hold Space (when not typing and no other tool is on); or drag with the middle button, any time.
+  // Two-finger scrolling on a trackpad moves around too (the browser's own scrolling).
+  const HAND = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 13V5.5a1.5 1.5 0 0 1 3 0V12"/>` +
+    `<path d="M11 5.5v-2a1.5 1.5 0 1 1 3 0V12"/><path d="M14 5.5a1.5 1.5 0 0 1 3 0V12"/>` +
+    `<path d="M17 7.5a1.5 1.5 0 0 1 3 0V16a6 6 0 0 1-6 6h-2 .2a6 6 0 0 1-5-2.7l-.2-.3c-.3-.5-1.4-2.4-3.3-5.7a1.5 1.5 0 0 1 .5-2 1.9 1.9 0 0 1 2.3.3L8 13"/></svg>`;
+  const handButton = Object.assign(document.createElement("button"), { innerHTML: HAND,
+    title: "Hand: drag to move around the board (or hold Space, or drag with the middle button; Esc to stop)" });
+  handButton.dataset.name = "hand";
+  handButton.style.order = 99;  // the palette's last tool, at the right end, whichever script adds its tools after this one
+  page.slot("status").append(handButton);
+  let hand = false, spaceHand = false, panning = null;  // panning: {x, y, left, top} at the press
+  const panMode = () => top.classList.toggle("panning", hand || spaceHand || !!panning);
+  function setHand(v) {
+    hand = v;
+    handButton.classList.toggle("on", v);
+    panMode();
+    if (v) document.dispatchEvent(new CustomEvent("tool-on", { detail: "hand" }));  // the other tools turn off
+  }
+  handButton.onclick = () => setHand(!hand);
+  document.addEventListener("tool-on", (e) => { if (hand && e.detail !== "hand") setHand(false); });
+  const typing = () => document.activeElement?.matches?.("input, textarea, select, [contenteditable=''], [contenteditable='true']") ||
+    document.activeElement?.localName === "iframe";  // an app has the keys
+  const otherTool = () => !!document.querySelector("#status button.on:not([data-name='show-marks']):not([data-name='hand'])");
+  addEventListener("keydown", (e) => {
+    if (e.key === "Escape") setHand(false);
+    if (e.code !== "Space") return;
+    if (spaceHand) return e.preventDefault();  // held: its repeats don't scroll the page either
+    if (typing() || otherTool() || e.ctrlKey || e.metaKey || e.altKey) return;
+    e.preventDefault();  // not a page scroll, nor a click on the focused button
+    spaceHand = true;
+    panMode();
+  }, true);
+  addEventListener("keyup", (e) => { if (e.code === "Space" && spaceHand) { spaceHand = false; panMode(); } }, true);
+  addEventListener("blur", () => { spaceHand = false; panMode(); });
+  top.addEventListener("pointerdown", (e) => {
+    if (!(e.button === 1 || (e.button === 0 && (hand || spaceHand)))) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();  // not a click, a line or a frame on what is under it
+    panning = { x: e.clientX, y: e.clientY, left: top.scrollLeft, top: top.scrollTop, id: e.pointerId };
+    top.setPointerCapture(e.pointerId);
+    top.classList.add("grabbing");
+    panMode();
+  }, true);
+  top.addEventListener("pointermove", (e) => {
+    if (!panning || e.pointerId !== panning.id) return;
+    const z = zoomOf();  // window px moved -> main px scrolled, so the board stays under the pointer
+    top.scrollLeft = panning.left - (e.clientX - panning.x) / z;
+    top.scrollTop = panning.top - (e.clientY - panning.y) / z;
+  });
+  const stopPan = (e) => {
+    if (!panning || e.pointerId !== panning.id) return;
+    panning = null;
+    top.classList.remove("grabbing");
+    panMode();
+  };
+  top.addEventListener("pointerup", stopPan);
+  top.addEventListener("pointercancel", stopPan);
+  top.addEventListener("auxclick", (e) => { if (e.button === 1) e.preventDefault(); });  // the middle button doesn't open links
+
   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)
@@ -148,6 +285,7 @@ export default async function (page) {
     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);
+    setZoom(zooms[n] ?? 1, null, false);  // each board keeps its own zoom (in this browser)
     if (tell) page.send({ type: "board_view", board: n });
     render();
   }
@@ -173,8 +311,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 +319,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/browser.js

@@ -3,6 +3,7 @@
 // A card is bare: only what the agent built, no frame (its label shows on hover: name, owner, ✕). It is
 // stacked in the main space, its content keeping its own size; or pinned at place {x, y, width?, height?}
 // (px from the main space's top-left, so it scrolls with the page), its root block then filling it.
+// (a new card with no place gets one near the middle of the view: autoPlace)
 // What the user can do with the label (the handle, so clicks inside still work):
 //   drag          move it; a drop sends {type: "card_move", card, place} (unless draggable: false)
 //   drag and hold still over another card (it lights up), release   combine: it slides back and the page
@@ -287,11 +288,11 @@ export default async function (page) {
 
   page.on("card", (ev) => {
     if (ev.op === "render") {
-      const old = cards[ev.card] || {};
+      const isNew = !cards[ev.card], old = cards[ev.card] || {};
       const { op, type, card, ...record } = ev;
       cards[ev.card] = { ...record, box: old.box, label: old.label, body: old.body, nodes: old.nodes, frame: old.frame,
                                flipped: old.flipped, option: record.options ? old.option : 0 };
-      draw(ev.card);
+      draw(ev.card).then(() => { if (isNew && !record.place) autoPlace(ev.card); });
     } else if (ev.op === "delete" && cards[ev.card]) {
       cards[ev.card].box?.remove();
       delete cards[ev.card];
@@ -306,6 +307,47 @@ export default async function (page) {
     }
   });
 
+  // A new card the agent gave no place: near the middle of what the user sees (between the panel, if open, and the
+  // right edge; below the palette, above the input bar), clear of everything else on the board. The nearest free
+  // spot to the middle, on a 40 px grid, keeping a 24 px gap. Only the tab in view, and only on the board shown
+  // (a card for another board stays stacked). Sent as card_place: saved, with no step of its own in the history.
+  const GAP = 24, STEP = 40, RINGS = 60;
+  async function autoPlace(id) {
+    const s = cards[id];
+    if (!s?.box || s.place || document.visibilityState !== "visible") return;
+    if ((Number(s.board) || 1) !== (Number(document.body.dataset.board) || 1)) return;
+    await new Promise(requestAnimationFrame);  // its blocks drawn
+    if (s.place) return;
+    const box = s.box;
+    box.toggleAttribute("data-placed", true);  // its size as a placed card, off the stack
+    Object.assign(box.style, { position: "absolute", margin: "0", left: "0px", top: "0px", visibility: "hidden" });
+    const z = parseFloat(area.style.zoom) || 1, w = box.offsetWidth, h = box.offsetHeight;
+    const m = area.getBoundingClientRect();
+    const main = (x, y) => ({ x: (x - m.left) / z + area.scrollLeft, y: (y - m.top) / z + area.scrollTop });
+    const css = getComputedStyle(document.documentElement), px = (v) => parseFloat(css.getPropertyValue(v)) || 0;
+    const panel = document.getElementById("panel"), open = ["messages", "versions"].includes(document.body.dataset.panel);
+    const side = px("--rail") + 28;
+    const a = main(Math.max(side, open && panel ? panel.getBoundingClientRect().right : 0), px("--palette"));
+    const b = main(innerWidth - side, innerHeight - px("--bar"));
+    const cx = (a.x + b.x) / 2 - w / 2, cy = (a.y + b.y) / 2 - h / 2;
+    const others = [...(box.parentElement?.children ?? [])].filter((el) => el !== box).map((el) => el.getBoundingClientRect())
+      .filter((r) => r.width && r.height).map((r) => ({ ...main(r.left, r.top), w: r.width / z, h: r.height / z }));
+    const free = (x, y) => others.every((o) => x + w + GAP <= o.x || o.x + o.w + GAP <= x || y + h + GAP <= o.y || o.y + o.h + GAP <= y);
+    const spots = [];
+    for (let i = -RINGS; i <= RINGS; i++) for (let j = -RINGS; j <= RINGS; j++) {
+      const x = Math.round(cx + i * STEP), y = Math.round(cy + j * STEP);
+      if (x >= 0 && y >= 0) spots.push({ x, y, d: (i * i + j * j) });
+    }
+    spots.sort((p, q) => p.d - q.d);
+    const spot = spots.find((p) => free(p.x, p.y)) ?? { x: Math.max(0, Math.round(cx)), y: Math.max(0, Math.round(cy)) };
+    // an app keeps its width: a placed box with none shrinks to the room left of the window's edge, and in a narrower
+    // window (the card_show check's browser) an app far right would be 0px wide
+    s.place = s.app ? { x: spot.x, y: spot.y, width: w } : { x: spot.x, y: spot.y };
+    Object.assign(box.style, { left: `${spot.x}px`, top: `${spot.y}px`, visibility: "" });
+    if (s.app) { box.style.width = `${w}px`; s.frame && (s.frame.style.width = "100%"); }
+    page.send({ type: "card_place", card: id, place: s.place });
+  }
+
   function pinStacked() {  // pin each stacked card where it is now, so taking one out of the stack moves none
     const stacked = Object.entries(cards).filter(([, s]) => !s.place && s.box);
     for (const [, s] of stacked) s.place = { x: s.box.offsetLeft, y: s.box.offsetTop };  // read all, then move
@@ -325,6 +367,7 @@ export default async function (page) {
     const handle = e.currentTarget, box = s.box;
     handle.setPointerCapture(e.pointerId);  // keep getting moves over iframes and other cards
     let place = null, held = false, x0 = 0, y0 = 0;
+    const z = parseFloat(area.style.zoom) || 1;  // the board's zoom (board/browser.js): window px moved -> main px
     let under = null, armed = null, wait = null, sx = 0, sy = 0;  // the card under the pointer; armed: lit, ready to combine
     const hold = setTimeout(() => { held = true; page.send({ type: "card_pin", card: id, pinned: !s.pinned }); }, HOLD_MS);
     handle.onpointermove = (ev) => {
@@ -332,7 +375,7 @@ export default async function (page) {
       clearTimeout(hold);
       if (s.pinned || s.draggable === false) return;
       if (!place) { pinStacked(); x0 = box.offsetLeft; y0 = box.offsetTop; box.style.zIndex = 4; }  // offsets in the main space; above the rest while dragged
-      place = { ...s.place, x: Math.round(x0 + ev.clientX - e.clientX), y: Math.round(y0 + ev.clientY - e.clientY) };
+      place = { ...s.place, x: Math.round(x0 + (ev.clientX - e.clientX) / z), y: Math.round(y0 + (ev.clientY - e.clientY) / z) };
       box.toggleAttribute("data-placed", true);
       Object.assign(box.style, { position: "absolute", margin: "0", left: `${place.x}px`, top: `${place.y}px` });
       const now = cardAt(ev.clientX, ev.clientY, box);
@@ -366,12 +409,12 @@ export default async function (page) {
     if (s.pinned) return;
     pinStacked();
     const handle = e.currentTarget, box = s.box;
-    const x = box.offsetLeft, y = box.offsetTop, w0 = box.offsetWidth, h0 = box.offsetHeight;
+    const x = box.offsetLeft, y = box.offsetTop, w0 = box.offsetWidth, h0 = box.offsetHeight, z = parseFloat(area.style.zoom) || 1;
     handle.setPointerCapture(e.pointerId);
     let place = null;
     handle.onpointermove = (ev) => {
-      place = { x, y, width: Math.min(area.clientWidth - x, Math.max(40, Math.round(w0 + ev.clientX - e.clientX))),
-                height: Math.max(30, Math.round(h0 + ev.clientY - e.clientY)) };
+      place = { x, y, width: Math.min(area.clientWidth - x, Math.max(40, Math.round(w0 + (ev.clientX - e.clientX) / z))),
+                height: Math.max(30, Math.round(h0 + (ev.clientY - e.clientY) / z)) };
       box.toggleAttribute("data-placed", true);
       Object.assign(box.style, { position: "absolute", margin: "0", left: `${x}px`, top: `${y}px`,
                                  width: `${place.width}px`, height: `${place.height}px` });

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)}.
@@ -16,7 +16,7 @@
 //   GET /card/all           every card                   GET /card/about   block name -> its about block
 //   GET /card/blocks        block name -> mtime          GET /card/blocks/<Name>.js, /card/node_modules/{marked,dompurify}/...
 //   GET /card/lib/...       libraries the agents added for blocks (lib/ here: ES-module builds)
-//   page messages           card_set, card_prop, card_move, card_board, card_pin, card_keep, card_close, card_action
+//   page messages           card_set, card_prop, card_move, card_place, card_board, card_pin, card_keep, card_close, card_action
 //   page event "card"       {op: "render", card, ...record} | {op: "delete", card} | {op: "reset", cards}
 import fs from "node:fs";
 import path from "node:path";
@@ -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,33 @@ 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_place") {  // the page put a new card with no place near the middle of the view: not a move
+      if (r.place || r.pinned) return;   // the user saw it appear there, so no step of its own (it is part of the showing)
+      r.place = msg.place; cards.change(id, r);
     } 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/doodle/README.md

@@ -29,7 +29,7 @@ You name the thing; the page draws it by hand in your colour, and keeps it on th
   page (the mark goes on just those characters), element a CSS selector or an element's id or data-name (also inside
   an app's frame), mark one of the marks (theirs or yours: m7). Example: {"card": "shop", "text": "12.50"}.
 - The page's own controls can be marked too, by name: {element: "pen"} (the marker), "text", "eraser", "show-marks"
-  (the eye), "note" (the note pencil), "frames", "files", "dictate" (the mic), "tools" (the whole palette, top centre),
+  (the eye), "note" (the speech bubble), "frames", "files", "dictate" (the mic), "tools" (the whole palette, top centre),
   "rail" (left edge), "messages", "versions", "message-line" (bottom), "boards" (the shelf above it), "new-board". Such
   marks stay fixed to the window. Good for a tour: ring "pen" with "draw here".
 - at: {x, y, width, height} in window px, as screen_see's picture shows it: a last resort for something with no name