@chalky/chalky 0.1.3 → 0.1.5

package/agent/extensions/doodle/guide.md

@@ -0,0 +1,22 @@
+# The board is shared: answer on it
+The user marks the page (doodles, handwriting, notes) and you can too, like a colleague at the same desk with a pen.
+- Prefer answering on the board when you show or point at something, or ask a specific clarification (mark the
+  options and ask which one). Use chat text only when it is clearly the better format.
+- Pen (doodle_mark): a gesture on one exact thing (the cell, not the column), with at most a few handwritten words.
+  "Circle it", "point at it", "show me which" mean the pen, not a change: never build a mark into the page or an app.
+  If the pen can't find the thing, say so and ask. The page's own controls have names ({element: "pen"}, "note",
+  "tools", "message-line", ...); for something with no name, look (screen_see) and use at: {x, y, width, height}.
+- If what they ask of you is unclear ("circle it": which?), ask before you act; don't guess.
+- Notes (note_add, note_reply): to explain or ask, in a thread on the thing. Answer a note in its own thread.
+- A question is not a request to change: answer it (on the board), and change things only when they ask for it.
+- Don't repeat in chat what you drew or wrote in a note: the user sees it on the board. Chat is one short line with
+  only what isn't there, or nothing.
+- If a mark of theirs could mean two different things, don't change anything: ask, on the board or in a note.
+- Marks come in groups (g1, g2, ...). doodle_clear a group when it is done:
+  - they asked for a change and you made it: clear it then (the change is the answer; no mark to confirm it);
+  - your answer is on the board (marks, a note, a question): leave it for them to see; clear it in a later turn,
+    once they have moved on or said it's fine.
+  Each message lists the other groups still on the page: clear the ones that are done. When you deal with one of
+  several things you marked, take that one mark away: doodle_clear(mark=...).
+A message "[doodles on the page]" is the user's drawing and clicks, with a picture per step: read README.md before
+you handle one, or before your first doodle_mark.

package/agent/extensions/doodle/index.ts

@@ -0,0 +1,274 @@
+// Doodle: draw on the page, click through it, and send the whole sequence to an agent. browser.js adds a marker, Text and an eraser to the palette: while the marker
+// is on, a drag draws, typing writes words where the pointer is, and a click works the page as usual. A click after
+// drawing makes the drawing a step: a picture of the screen as the user saw it (from the tab, shared once: the
+// screen extension), cropped to the drawing. Enter in the message line sends the steps and the words typed there,
+// together, to the agent picked in the chat (else agent1), with the pictures attached to the message itself
+// (the team's send, with images), in step order.
+//   page message   doodle_send {to, text, first: [click], steps: [{shot, area, drawn, words: [str], then: [click]}],
+//                  marks: [{kind: "line" | "words", points, text?, said, anchor?}]}
+//                  (shot: a path from /screen/shot, or null when the tab wasn't shared; area: the part of the main
+//                  space the picture shows, main px; drawn: anything drawn on it; words: what the user typed on it,
+//                  exactly; clicks are words browser.js wrote; marks: what is still drawn at Enter, main px, and
+//                  what the page can tell about each from geometry alone ("said": closed loop around "Total", ...), and
+//                  anchor: the thing it is most about ({card, text, row?} ..., at: where it was), so it moves with it)
+// The board is shared: the user's marks stay after Enter, and the agents draw too.
+//   groups   each Enter with marks is a group (g1, g2, ...): the user's marks, then the agent's marks in reply.
+//            data/doodle.json {last, lastMark, groups: {id: {board, to, by, state, dim, label, ts}},
+//            marks: {id: {group, by, kind, board, points?, text?, said?, gesture?, on?, to?, words?, box?}}}
+//            state: open (its agent hasn't answered yet) → answered (its turn ended) → cleared (by the user's ✓ or
+//            the agent's doodle_clear; it can be brought back from the chat log: doodle_restore). Nothing clears by
+//            itself. dim: an answered group, after the user sent something newer.
+//   tools    doodle_mark   a gesture on a thing (ring, underline, strike, tick, cross, arrow to another thing, or
+//                          none) with a few handwritten words; the page works out where, so no coordinates
+//            doodle_clear  a group is dealt with: its marks go for everyone (or one of the agent's own marks, for good)
+//   check    host.api.doodle.check(target): asks an open page where a thing is ({box} in main px, or {error});
+//            null when no page answers. note/ uses it too, for the agent's notes.
+//   events   doodle_group {group, marks}   doodle_gone {group}   doodle_mark {mark}   doodle_erased {id}   doodle_check
+//   page     doodle_clear {group}  doodle_restore {group}  doodle_erase {id}  doodle_dim  doodle_checked {req, box|error}
+//   GET /doodle/all   {groups, marks}
+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 s = (n: number) => (n === 1 ? "" : "s");
+const FILE = path.join(host.data, "doodle.json");
+if (!host.shared.has("doodle"))
+  host.shared.set("doodle", fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 0, lastMark: 0, groups: {}, marks: {} });
+const D = host.shared.get("doodle");
+if (!host.shared.has("doodle-run")) host.shared.set("doodle-run", { own: {}, current: {}, started: {}, checks: new Map() });
+const run = host.shared.get("doodle-run");  // own: agent -> the group it started this turn; current: agent -> the user's group this turn answers;
+// started: agent -> its turn began; checks: req -> resolve
+const save = () => fs.writeFileSync(FILE, JSON.stringify(D));
+const result = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
+const marksOf = (g: string) => Object.entries(D.marks).filter(([, m]: any) => m.group === g) as [string, any][];
+
+function dim() {  // the user sent something new: answered groups step back
+  const changed = Object.entries(D.groups).filter(([, g]: any) => g.state === "answered" && !g.dim);
+  for (const [, g] of changed as any) g.dim = true;
+  if (changed.length) { save(); for (const [id] of changed) host.broadcast("doodle_group", { group: id, ...D.groups[id] }); }
+}
+
+function check(target: any): Promise<any> {  // where is this thing on the page? The first page to answer says
+  const req = `c${Date.now()}${Math.random().toString(36).slice(2, 6)}`;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => { run.checks.delete(req); resolve(null); }, 4000);
+    run.checks.set(req, (answer: any) => { clearTimeout(timer); run.checks.delete(req); resolve(answer); });
+    host.broadcast("doodle_check", { req, target });
+  });
+}
+
+function label(m: any) { return m.said?.replace(/, box x=.*$/, "") || (m.text ? `"${m.text}"` : "a mark"); }  // without the numbers
+
+function newGroup(by: string, to: string, board: number, labelText: string) {
+  const id = `g${++D.last}`;
+  D.groups[id] = { board, to, by, state: by === "user" ? "open" : "answered", dim: false, label: labelText, ts: Date.now() };
+  return id;
+}
+
+// What is still on the board besides this group, for the agent (ids it can point at, or clear)
+function others(except: string) {
+  return Object.entries(D.groups).filter(([id, g]: any) => id !== except && g.state !== "cleared").map(([id, g]: any) =>
+    `  ${id} (${g.state}${g.dim ? ", dimmed" : ""}, board ${g.board}): ` + marksOf(id).map(([mid, m]) =>
+      m.by === "user" ? `${mid} ${label(m)}` : `${mid} ${m.by}'s ${m.gesture}${m.words ? ` "${m.words}"` : ""}`).join("; "));
+}
+
+function message(msg: any, group: string | null, ids: string[]) {
+  const steps: any[] = msg.steps ?? [];
+  const shots: string[] = steps.map((st) => st.shot).filter((p) => host.api.screen?.isShot(p));
+  const words = String(msg.text ?? "").trim();
+  const lines = [`[doodles on the page] ${words || "(no words: the drawing says it)"}`];
+  if (group) {
+    lines.push(`group: ${group} (your marks join it. If you make the change it asks for, doodle_clear("${group}") once it is made; if your answer is on the board, leave it for the user to see)`,
+      "marks still on the page (main-space px; what the page can tell from the geometry; the picture shows the rest):",
+      ...ids.map((id) => `  ${id}: ${D.marks[id].said}`));
+    const rest = others(group);
+    if (rest.length) lines.push("other groups still on the page (doodle_clear the ones that are done: their change is made, or their answer seen):", ...rest);
+  }
+  lines.push(`${steps.length} step${s(steps.length)}, ${shots.length} picture${s(shots.length)} attached in this order`
+    + (shots.length === steps.length ? "" : " (the tab wasn't shared for the others: words only)") + ":");
+  if (msg.first?.length) lines.push(`  first: ${msg.first.join("; ")}`);
+  let n = 0;
+  steps.forEach((st, i) => {
+    const has = shots.includes(st.shot), a = st.area;
+    if (has) n++;
+    lines.push(`Step ${i + 1}` + (st.board ? ` on board ${st.board}` : "") + (has ? ` (picture ${n})` : " (no picture)")
+      + (has && a ? `, showing x=${a.x} y=${a.y} w=${a.width} h=${a.height} of the page` : "")
+      + (st.drawn ? "" : ": nothing drawn, how the screen looked after those clicks"));
+    for (const w of st.words ?? []) lines.push(`  words: "${w}"`);
+    if (st.then?.length) lines.push(`  then: ${st.then.join("; ")}`);
+  });
+  return { text: lines.join("\n"), shots };
+}
+
+function clear(group: string, by: string) {
+  const g = D.groups[group];
+  g.state = "cleared";
+  g.clearedBy = by;
+  save();
+  host.broadcast("doodle_group", { group, ...g });
+}
+
+function erase(id: string) {  // a mark, for good (the eraser; an agent taking one of its marks away)
+  const group = D.marks[id].group;
+  delete D.marks[id];
+  if (!marksOf(group).length) delete D.groups[group];
+  save();
+  host.broadcast("doodle_erased", { id, group });
+}
+
+host.api.doodle = { check, dim };
+
+// A thing on the page, as the agent names it (the tools' "on" and "to")
+const Target = Type.Object({
+  card: Type.Optional(Type.String({ description: "card id" })),
+  block: Type.Optional(Type.String({ description: "block id in that card" })),
+  element: Type.Optional(Type.String({ description: "a CSS selector, or an element's id or data-name (also inside an app's frame)" })),
+  text: Type.Optional(Type.String({ description: "exact text shown on the page (in the card/element if given): the mark goes on just those words" })),
+  mark: Type.Optional(Type.String({ description: "a mark's id (m3): the user's mark or yours" })),
+  note: Type.Optional(Type.String({ description: "a note's id (n2)" })),
+  at: Type.Optional(Type.Object({ x: Type.Number(), y: Type.Number(), width: Type.Number(), height: Type.Number() }, {
+    description: "last resort, for something with no name: a box in window px, as screen_see's picture shows it" })),
+}, { description: "What the mark is on: give as few fields as name it exactly, e.g. {card, text}. The page's own controls "
+  + "have names too: {element: \"pen\"} (also text, eraser, show-marks, note, frames, files, dictate, tools, rail, messages, "
+  + "versions, message-line, boards, new-board)." });
+const named = (t: any) => Object.entries(t ?? {}).filter(([, v]) => v)
+  .map(([k, v]) => k === "at" ? `at x=${v.x} y=${v.y} w=${v.width} h=${v.height}` : `${k} "${v}"`).join(", ");
+
+export default function (pi: ExtensionAPI) {
+  const me = () => pi.getSessionName()!;
+  // a removed board (board/) takes its marks with it
+  pi.on("session_start", () => host.api.board?.onRemove("doodle", (n: number) => {
+    for (const [id, g] of Object.entries(D.groups) as any) if ((g.board ?? 1) === n) {
+      for (const [mid] of marksOf(id)) delete D.marks[mid];
+      delete D.groups[id];
+      host.broadcast("doodle_gone", { group: id });
+    }
+    save();
+    return [];
+  }));
+  pi.on("agent_start", () => {  // the group this turn answers: the newest the user sent this agent that it hasn't answered yet
+    delete run.own[me()];
+    run.started[me()] = Date.now();
+    run.current[me()] = Object.entries(D.groups).filter(([, g]: any) => g.to === me() && g.by === "user" && g.state === "open")
+      .sort(([, x]: any, [, y]: any) => y.ts - x.ts)[0]?.[0];
+  });
+  pi.on("agent_settled", () => {  // this agent's turn is over: the groups it had when it started are answered
+    let changed = false;
+    for (const [id, g] of Object.entries(D.groups) as any)
+      if (g.to === me() && g.state === "open" && g.ts <= (run.started[me()] ?? 0)) { g.state = "answered"; changed = true; host.broadcast("doodle_group", { group: id, ...g }); }
+    if (changed) save();
+  });
+
+  pi.registerTool({
+    name: "doodle_mark", label: "Doodle mark",
+    description: "Draw on the page in your own ink, by hand, as a colleague would with a pen: a gesture on a thing, and/or a few "
+      + "handwritten words beside it. The page works out where; you only name the thing. Use it to show, point out or "
+      + "ask about one exact thing. Explanations go in a note (note_add), not here.",
+    parameters: Type.Object({
+      gesture: Type.Union(["ring", "underline", "strike", "tick", "cross", "arrow", "none"].map((g) => Type.Literal(g)),
+        { description: "ring: circle it (look here, a problem, an option); underline; strike: through it (this is wrong); tick: ✓ beside it (yes, this one); cross: ✕ over it (only for: remove this); arrow: from on to to; none: only words" }),
+      on: Target,
+      to: Type.Optional(Target),
+      words: Type.Optional(Type.String({ description: "at most 40 characters, handwritten beside it" })),
+      group: Type.Optional(Type.String({ description: "the group you are answering (g3, from the message); left out: the group of the message you are answering, else a new group of your own" })),
+    }),
+    async execute(_id, a) {
+      const agent = me();
+      if (a.words && a.words.length > 40) return result(`error: words are at most 40 characters (yours: ${a.words.length}). Put the longer text in a note (note_add).`);
+      if (a.gesture === "arrow" && !a.to) return result("error: an arrow needs to (the thing it points at)");
+      if (a.gesture === "none" && !a.words) return result("error: gesture none needs words");
+      if (!named(a.on)) return result("error: on names nothing: give card, block, element, text, mark, note or at");
+      const unknown = a.group && !D.groups[a.group] ? a.group : null;  // a made-up group: use the usual one instead
+      if (unknown) a.group = undefined;
+      const where = await check(a.on);
+      if (where?.error) return result(`error: ${where.error} (on: ${named(a.on)}). Name it as it is on the page: a card id, a block id, an element's id or data-name, or its exact text.`);
+      const to = a.to ? await check(a.to) : null;
+      if (to?.error) return result(`error: ${to.error} (to: ${named(a.to)})`);
+      let group = a.group ?? run.current[agent] ?? run.own[agent];  // else this turn's own group (not an older one of the user's)
+      if (!group || D.groups[group]?.state === "cleared") {  // nothing of the user's to answer: a group of the agent's own
+        group = run.own[agent] = newGroup(agent, agent, where?.board ?? host.api.board?.current() ?? 1, `${agent}'s ${a.gesture} on ${named(a.on)}`);
+        host.broadcast("doodle_group", { group, ...D.groups[group] });
+      }
+      const id = `m${++D.lastMark}`;
+      D.marks[id] = { group, by: agent, kind: "gesture", board: where?.board ?? D.groups[group].board, gesture: a.gesture, on: a.on,
+                      ...(a.to && { to: a.to }), ...(a.words && { words: a.words }), ...(where?.box && { box: where.box }), ...(to?.box && { toBox: to.box }),
+                      ...(where?.fixed && { fixed: true }), ...(to?.fixed && { toFixed: true }) };  // fixed: on the page's own controls (window px)
+      save();
+      host.broadcast("doodle_mark", { id, ...D.marks[id] });
+      return result(`drew ${id} (${a.gesture}${a.words ? ` "${a.words}"` : ""} on ${named(a.on)}) in group ${group}`
+        + (unknown ? ` (there is no group '${unknown}': leave group out next time)` : "") + "; the user sees it: don't repeat it in your reply"
+        + (where ? "" : " (no page open to check the target: it shows when one opens)"));
+    },
+  });
+
+  pi.registerTool({
+    name: "doodle_clear", label: "Doodle clear",
+    description: "A group of marks is dealt with: clear it (the user's marks and yours in it go, for everyone; the user can bring "
+      + "them back from the chat log). Clear it when you have made the change it asks for (the change is the answer), or in a "
+      + "later turn once the user has seen your marks and moved on. Not while your answer on the board is still to be seen, or its question is open.",
+    parameters: Type.Object({
+      group: Type.Optional(Type.String({ description: "e.g. g3: the whole group" })),
+      mark: Type.Optional(Type.String({ description: "e.g. m7: just this one of your marks, for good (one of several things you marked is dealt with)" })),
+    }),
+    async execute(_id, a) {
+      if (a.mark) {
+        const m = D.marks[a.mark];
+        if (!m) return result(`error: no mark '${a.mark}'`);
+        if (m.by !== me()) return result(`error: ${a.mark} is ${m.by === "user" ? "the user's" : m.by + "'s"}: you can only take away your own marks (clear the group instead)`);
+        erase(a.mark);
+        return result(`took ${a.mark} away; the rest of ${m.group} stays`);
+      }
+      if (!a.group) return result("error: give group, or mark");
+      const g = D.groups[a.group];
+      if (!g) return result(`error: no group '${a.group}'. Groups: ${Object.keys(D.groups).join(", ") || "none"}`);
+      if (g.state === "cleared") return result(`${a.group} is already cleared`);
+      clear(a.group, me());
+      return result(`cleared ${a.group}: its marks are gone from the page`);
+    },
+  });
+
+  host.routes.set("/doodle/all", (_req: any, res: any) =>
+    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ groups: D.groups, marks: D.marks })));
+
+  host.pageHandlers.set("doodle", (msg: any) => {
+    const team = host.api.team;
+    if (msg.type === "doodle_checked") return run.checks.get(msg.req)?.(msg);
+    if (msg.type === "doodle_dim") return dim();
+    if (msg.type === "doodle_clear" && D.groups[msg.group]) {
+      clear(msg.group, "user");
+      const g = D.groups[msg.group];
+      if (host.agents.has(g.to)) team?.fyi("page", g.to, `[doodles on the page] the user cleared group ${msg.group} (${g.label}): done with it.`);
+      return;
+    }
+    if (msg.type === "doodle_restore" && D.groups[msg.group]) {
+      const g = D.groups[msg.group];
+      Object.assign(g, { state: "answered", dim: false });
+      delete g.clearedBy;
+      save();
+      host.broadcast("doodle_group", { group: msg.group, ...g });
+      if (host.agents.has(g.to)) team?.fyi("page", g.to, `[doodles on the page] the user brought group ${msg.group} (${g.label}) back onto the page.`);
+      return;
+    }
+    if (msg.type === "doodle_erase" && D.marks[msg.id]) return erase(msg.id);  // the eraser: for good
+    if (msg.type !== "doodle_send" || !team) return;
+    const to = msg.to in team.status() ? msg.to : "agent1";
+    dim();
+    let group: string | null = null;
+    const ids: string[] = [];
+    if (msg.marks?.length) {
+      const board = Number(msg.board) || 1;
+      group = newGroup("user", to, board, msg.marks.map(label).slice(0, 2).join(", ").slice(0, 80));
+      for (const m of msg.marks) {
+        const id = `m${++D.lastMark}`;
+        D.marks[id] = { group, by: "user", kind: m.kind, board, points: m.points, ...(m.text && { text: m.text }), said: m.said, ...(m.anchor && { anchor: m.anchor }) };
+        ids.push(id);
+      }
+      save();
+      host.broadcast("doodle_group", { group, ...D.groups[group], marks: Object.fromEntries(ids.map((id) => [id, D.marks[id]])) });
+    }
+    const { text, shots } = message(msg, group, ids);
+    team.send("user", to, text, false, shots);
+  });
+}

package/agent/extensions/file/browser.js

@@ -0,0 +1,143 @@
+// The page side of the file extension: the file panel on the right edge (slot "side"), one name per row,
+// collapsed and opened by its folder button (remembered in this browser). Hidden while there are no files.
+//   Files dragged from the computer onto the page: uploaded (POST /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.
+//   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).
+//   Each row's checkbox (on hover, or on all rows once one is ticked) selects it; the bar then deletes the ticked
+//   files for good, after a confirm (POST /file/delete). The bar sits below the rows (sticky), so ticking one never
+//   moves the rows.
+// The list comes from GET /file, then from "file" events (after an upload, and after each agent turn).
+export default async function (page) {
+  const side = page.slot("side");
+  const style = document.createElement("style");
+  style.textContent = `
+    #side .file-toggle { width: 38px; height: 38px; display: grid; place-items: center; border-radius: 12px; color: var(--muted);
+                          align-self: flex-end; margin: 16px 9px 0 0; transition: background 0.15s, color 0.15s; }
+    #side .file-toggle:hover { background: var(--hover); color: var(--text); }
+    #side[data-open] .file-toggle { background: var(--glass-strong); color: var(--text);
+                                     box-shadow: 0 1px 6px rgba(0, 0, 0, 0.06), inset 0 0 0 1px var(--edge); }
+    #side .files { display: none; width: 220px; max-height: calc(100vh - 140px); overflow-y: auto; margin: 8px 9px 0 0;
+                   padding: 8px; box-sizing: border-box; border-radius: var(--radius); font-size: 13px;
+                   background: var(--glass-strong); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+                   border: 1px solid var(--edge); box-shadow: var(--shadow); }
+    #side[data-open] .files { display: block; }
+    #side[data-over] .files { outline: 2px solid var(--accent); outline-offset: -2px; }
+    #side .file-row { display: flex; align-items: center; gap: 6px; padding: 5px 8px; border-radius: 8px; color: var(--soft); cursor: grab; }
+    #side .file-row span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    #side .file-row input { appearance: none; -webkit-appearance: none; margin: 0; flex: none; visibility: hidden;
+                             width: 16px; height: 16px; border-radius: 50%; cursor: pointer; background: var(--glass-strong);
+                             box-shadow: inset 0 0 0 1px rgba(60, 60, 67, .3); transition: background-color .15s, box-shadow .15s; }
+    #side .file-row input:hover { box-shadow: inset 0 0 0 1px var(--accent); }
+    #side .file-row input:checked { box-shadow: none; background: var(--accent) center / 10px no-repeat
+      url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M2.5 6.2l2.3 2.3 4.7-5' fill='none' stroke='white' stroke-width='1.8' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E"); }
+    #side .file-row input:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    #side .file-row:hover input, #side .file-list[data-selecting] .file-row input { visibility: visible; }
+    #side .file-bar { display: flex; gap: 6px; position: sticky; bottom: -8px; margin: 4px -8px -8px; padding: 8px;
+                       background: var(--glass-strong); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+                       border-top: 1px solid var(--line); }
+    #side .file-bar[hidden] { display: none; }
+    #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); }`;
+  document.head.append(style);
+
+  const toggle = document.createElement("button");
+  toggle.className = "file-toggle";
+  toggle.dataset.name = "files";
+  toggle.title = "Files: drop files anywhere on the page; drag a name onto the page to use it there";
+  toggle.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>`;
+  const list = document.createElement("div");
+  list.className = "file-list";
+  side.append(toggle, list);
+
+  const setOpen = (open) => {
+    side.toggleAttribute("data-open", open);
+    try { localStorage.setItem("file-panel-open", open ? "1" : ""); } catch {}
+  };
+  let open = true;
+  try { open = localStorage.getItem("file-panel-open") !== ""; } catch {}
+  setOpen(open);
+  toggle.onclick = () => setOpen(!side.hasAttribute("data-open"));
+
+  const selected = new Set();  // names ticked for deleting
+  const bar = Object.assign(document.createElement("div"), { className: "file-bar", hidden: true });  // under the rows
+  const del = Object.assign(document.createElement("button"), { className: "delete" });
+  const cancel = Object.assign(document.createElement("button"), { textContent: "Cancel" });
+  bar.append(del, cancel);
+  const showBar = () => {
+    bar.hidden = !selected.size;
+    list.toggleAttribute("data-selecting", selected.size > 0);
+    del.textContent = `Delete ${selected.size} file${selected.size === 1 ? "" : "s"}`;
+  };
+  cancel.onclick = () => { selected.clear(); list.querySelectorAll(".file-row input").forEach((t) => (t.checked = false)); showBar(); };
+  del.onclick = async () => {
+    const names = [...selected];
+    if (!confirm(`Delete ${names.length === 1 ? names[0] : `${names.length} files`} for good?`)) return;
+    try {
+      const out = await (await fetch("/file/delete", { method: "POST", body: JSON.stringify({ names }) })).json();
+      if (out.errors.length) page.note(`Could not delete: ${out.errors.join("; ")}`);
+    } catch (err) { page.note(`Could not delete: ${err}`); }
+    selected.clear();
+    showBar();  // the rows go with the "file" event
+  };
+
+  const ROW = "application/x-chalky-file";  // a row being dragged: its file as JSON
+  function render(files) {
+    list.replaceChildren();
+    side.hidden = !files.length;  // no files yet: no panel (a drop from the computer still works anywhere)
+    for (const name of selected) if (!files.some((f) => f.name === name)) selected.delete(name);
+    showBar();
+    for (const f of files) {
+      const row = Object.assign(document.createElement("div"), { className: "file-row", draggable: true });
+      const tick = Object.assign(document.createElement("input"), { type: "checkbox", checked: selected.has(f.name), title: "Select to delete" });
+      tick.onclick = (e) => { e.stopPropagation(); tick.checked ? selected.add(f.name) : selected.delete(f.name); showBar(); };
+      row.append(tick, Object.assign(document.createElement("span"), { textContent: f.name }));
+      row.title = `${f.path} · ${Math.ceil(f.size / 1024)} KB · click to preview`;
+      row.dataset.path = f.path;
+      row.onclick = () => opened(f);  // a drag never ends in a click, so dragging a row still works
+      row.ondragstart = (e) => { e.dataTransfer.setData(ROW, JSON.stringify(f)); e.dataTransfer.effectAllowed = "copy"; };
+      list.append(row);
+    }
+    list.append(bar);
+  }
+  page.on("file", ({ files }) => render(files));
+  try { render(await (await fetch("/file")).json()); } catch { render([]); }
+
+  const kind = (e) => {
+    const types = [...(e.dataTransfer?.types || [])];
+    return types.includes(ROW) ? "row" : types.includes("Files") ? "files" : null;
+  };
+  const onPanel = (e) => side.contains(e.target);
+  const opened = (file) => document.dispatchEvent(new CustomEvent("file-open",
+    { detail: { file, row: list.querySelector(`[data-path="${CSS.escape(file.path)}"]`) } }));
+  const dropped = (x, y, files) => document.dispatchEvent(new CustomEvent("file-dropped", { detail: { x, y, files } }));
+
+  document.addEventListener("dragover", (e) => {
+    if (!kind(e)) return;
+    e.preventDefault();
+    side.toggleAttribute("data-over", kind(e) === "files" && onPanel(e));
+  });
+  document.addEventListener("dragleave", (e) => { if (!e.relatedTarget) side.removeAttribute("data-over"); });
+  document.addEventListener("drop", async (e) => {
+    const k = kind(e);
+    if (!k) return;
+    e.preventDefault();
+    side.removeAttribute("data-over");
+    const { clientX: x, clientY: y } = e;
+    if (k === "row") return onPanel(e) || dropped(x, y, [JSON.parse(e.dataTransfer.getData(ROW))]);
+    const stored = [];
+    for (const f of [...e.dataTransfer.files].slice(0, 10)) {
+      try {
+        const out = await (await fetch(`/file/upload?name=${encodeURIComponent(f.name)}`, { method: "POST", body: f })).json();
+        if (out.path) stored.push({ name: out.path.split("/").pop(), path: out.path, size: out.size });
+        else page.note(`Could not upload ${f.name}: ${out.error}`);
+      } catch (err) { page.note(`Could not upload ${f.name}: ${err}`); }
+    }
+    if (stored.length) opened(stored[0]);  // the list has its row by now (the "file" event comes before the reply)
+    if (stored.length && !onPanel(e)) dropped(x, y, stored);
+  });
+}

package/agent/extensions/file/guide.md

@@ -0,0 +1,5 @@
+# The user's files
+{workspace}/drops/ holds the user's files (dropped on the page, or saved there by you); they see them in the file
+panel. Read one only when the user points at it or names it; a document (docx, pptx, xlsx, pdf): viewer_read gives
+its text (load it with tool_search). To hand them a file (an export, an image), save it in
+{workspace}/drops/; other work files stay in {workspace}.

package/{app/extensions/files → agent/extensions/file}/index.ts

@@ -1,19 +1,20 @@
-// Files: the user's files, in one folder, <workspace>/drops (port of the Python files plugin; the browser half,
+// Files: the user's files, in one folder, workspace/drops (the browser half,
 // browser.js, is its files.js). browser.js shows them in a panel on the page's right edge and handles files dragged onto
-// the page (from the computer: uploaded here, listed, and a "files-dropped" DOM event so point's browser.js opens its note
+// 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).
-//   POST /files/upload?name=<file name>  the file's bytes: saved in DIR (a safe, new name), returns {path, size}
-//   GET  /files                          [{name, path, size}], newest first; files in folders too ("q3/costs.xlsx")
-//   event "files" {files: [...]}         to every open page, when the list changed
-// guide.md (copied from files.py, short enough to be whole) names pi's read tool for pictures (Python: view_image).
+//   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}
+//   event "file" {files: [...]}         to every open page, when the list changed
+// guide.md (short enough to be whole) names pi's read tool for pictures.
 import fs from "node:fs";
 import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const DIR = path.join(host.work, "drops");
+const DIR = path.join(host.workspace, "drops");
 const MAX_FILE = 25 * 1024 * 1024;  // bytes per uploaded file
 const MAX_LISTED = 500;             // rows in the panel (the newest)
 fs.mkdirSync(DIR, { recursive: true });  // there from the first turn, so the agent can save into it
@@ -28,21 +29,38 @@ function listing() {  // the files in DIR and its folders (not hidden ones), new
     .map(({ name, path, size }) => ({ name, path, size }));
 }
 
-function changed() {  // tell the pages, if the list is not what they were last sent
+function changed(always = false) {  // tell the pages, if the list is not what they were last sent (or always)
   const now = JSON.stringify(listing());
-  if (now === host.shared.get("files-last")) return;
-  host.shared.set("files-last", now);
-  host.broadcast("files", { files: JSON.parse(now) });
+  if (now === host.shared.get("file-last") && !always) return;
+  host.shared.set("file-last", now);
+  host.broadcast("file", { files: JSON.parse(now) });
 }
 
 export default function (pi: ExtensionAPI) {
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8");
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.files = guide; });
   pi.on("agent_settled", () => changed());  // the agent may have saved files there
-  if (!host.shared.has("files-last")) host.shared.set("files-last", JSON.stringify(listing()));
+  if (!host.shared.has("file-last")) host.shared.set("file-last", JSON.stringify(listing()));
 
-  host.routes.set("/files", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(listing())));
-  host.routes.set("/files/upload", (req: any, res: any) => {  // save one file in DIR (a new name if it exists)
+  host.routes.set("/file", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(listing())));
+  host.routes.set("/file/delete", (req: any, res: any) => {  // delete files in DIR; a name may not lead outside it
+    if (req.method !== "POST") return res.writeHead(405).end();
+    let body = "";
+    req.on("data", (chunk: Buffer) => { body += chunk; });
+    req.on("end", () => {
+      const deleted: string[] = [], errors: string[] = [];
+      let names: string[] = [];
+      try { names = JSON.parse(body).names ?? []; } catch {}
+      for (const name of names) {
+        const p = path.resolve(DIR, String(name));
+        if (!p.startsWith(DIR + path.sep)) { errors.push(`${name}: not in the files folder`); continue; }
+        if (!fs.statSync(p, { throwIfNoEntry: false })?.isFile()) { errors.push(`${name}: no such file`); continue; }
+        fs.rmSync(p);
+        deleted.push(name);
+      }
+      changed(true);  // always: files added outside the panel may have made the last list sent stale
+      res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ deleted, errors }));
+    });
+  });
+  host.routes.set("/file/upload", (req: any, res: any) => {  // save one file in DIR (a new name if it exists)
     if (req.method !== "POST") return res.writeHead(405).end();
     const given = path.basename(new URL(req.url, "http://x").searchParams.get("name") ?? "file");
     const name = given.replace(/[^\w.\-]+/g, "_").replace(/^[._]+|[._]+$/g, "") || "file";

package/{app/extensions/frames → agent/extensions/frame}/README.md

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