@chalky/chalky 0.1.4 → 0.1.6

package/app/extensions/frames/index.ts

@@ -1,85 +0,0 @@
-// Frames: wireframes the user lays out for the agents to fill (port of the Python frames plugin; browser.js is its
-// frames.js). browser.js adds a tool to the palette: drag boxes on the main space, type in each what goes there,
-// then press Implement. All the frames go together, as one message, to the agent picked in the chat (else agent1),
-// 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 ui_render's place puts a surface;
-// board: the one it was drawn on, boards/; Implement sends the frames of the board shown), with an
-// id (frame-1, frame-2, ...: never reused). An agent fills it with ui_render(surface="frame-1", place=<its place>);
-// when that surface appears (a ui watcher, host.api.ui.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 /frames             {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}, frames_send {to, board}
-//   event "frames"          {frames: {id: frame}} to every open page, when they changed
-// Saved in state/frames.json as {last: <last id number>, frames: {id: frame}}; shared by every agent (host.shared).
-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 FILE = path.join(host.state, "frames.json");
-if (!host.shared.has("frames"))
-  host.shared.set("frames", fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 0, frames: {} });
-const saved = host.shared.get("frames");  // {last, frames}
-const frames: Record<string, any> = saved.frames;
-
-function changed() {
-  fs.writeFileSync(FILE + ".tmp", JSON.stringify(saved));
-  fs.renameSync(FILE + ".tmp", FILE);
-  host.broadcast("frames", { frames });
-}
-const box = (msg: any, f: any = {}) => Object.fromEntries(["x", "y", "width", "height"].map((k) => [k, Math.round(Number(msg[k] ?? f[k] ?? 0))]));
-const place = (f: any) => JSON.stringify({ x: f.x, y: f.y, width: f.width, height: f.height });
-
-export default function (pi: ExtensionAPI) {
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it, read when it says
-    .replace("README.md", path.join(import.meta.dirname, "README.md"));
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.frames = guide; });
-
-  // a frame is done when a surface with its id appears (after all extensions loaded: the ui one may come later)
-  pi.on("session_start", () => {
-    host.api.ui?.watch("frames", (sid: string) => {
-      if (frames[sid] && host.shared.get("ui")?.surfaces[sid]) { delete frames[sid]; changed(); }
-    });
-    host.api.boards?.onRemove("frames", (n: number) => {  // a removed board (boards/) takes its frames with it
-      const ids = Object.keys(frames).filter((id) => (frames[id].board ?? 1) === n);
-      const gone = ids.map((id) => ({ owner: frames[id].sent ? frames[id].to : undefined, what: `frame ${id}` }));
-      for (const id of ids) delete frames[id];
-      if (ids.length) changed();
-      return gone;
-    });
-  });
-
-  host.routes.set("/frames", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(frames)));
-
-  host.pageHandlers.set("frames", (msg: any) => {
-    const f = frames[msg.id], swarm = host.api.swarm;
-    if (msg.type === "frame_add") {
-      frames[`frame-${++saved.last}`] = { ...box(msg), text: "", sent: false, board: Number(msg.board) || 1 };
-      changed();
-    } else if (msg.type === "frame_place" && f && !f.sent) {
-      Object.assign(f, box(msg, f));
-      changed();
-    } else if (msg.type === "frame_text" && f && !f.sent) {
-      f.text = String(msg.text ?? "");
-      changed();
-    } else if (msg.type === "frame_remove" && f) {
-      delete frames[msg.id];
-      changed();
-      if (f.sent) swarm?.send("user", f.to, `[frames on the UI] the user removed ${msg.id} ("${f.text}"): don't fill it.`, true);
-    } else if (msg.type === "frames_send" && swarm) {
-      const to = msg.to in swarm.status() ? msg.to : "agent1";
-      const board = Number(msg.board) || 1;  // the board shown: its frames only (the user sees no others)
-      const ready = Object.entries(frames).filter(([, f]: any) => !f.sent && f.text.trim() && (f.board ?? 1) === board);
-      if (!ready.length) return;
-      for (const [, f] of ready as any) Object.assign(f, { sent: true, to });
-      changed();
-      const lines = [`[frames on the UI] the user laid out ${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 ui_render(surface=<its id>, place=<its place>, board=${board}, ...); its dashed box goes when it appears.`];
-      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(", ")}.`);
-      swarm.send("user", to, lines.join("\n"));
-    }
-  });
-}

package/app/extensions/mcp/guide.md

@@ -1,5 +0,0 @@
-# MCP servers
-Servers are in {code}/mcp.json (pi's built-in MCP: pi's docs/mcp.md); their tools are named mcp__<server>__<tool>.
-The user ticks which servers and tools are on with /mcp on the page.
-- To add a server when asked: add its entry to that file (secrets as ${ENV_VAR} in headers or env, never written
-  out), then call reload.

package/app/extensions/point/README.md

@@ -1,22 +0,0 @@
-# Notes on the UI (the point extension)
-The user can click anything on the page and write a note there. You get "[note on the UI] <their words>"
-with the target: surface and component (from ui_render), the element they clicked (inside App frames
-too), the part (if the thing has partAt), its text, and the file it comes from. Act on that exact thing.
-- If the text is data (a table row, a score), change the surface's data, not the component's code.
-- "here" means the spot: to add something there, ui_render(..., place={"x", "y"}) with its position, and keep
-  it small (as wide as its content). On empty space the spot is all there is to the target.
-- A note with an "area" came with a drawing: the user circled that box. On empty space, build what they ask
-  for inside it: ui_render(..., place={"x", "y", "width", "height"}) from the area. On a surface, the drawing
-  marks the part of it the note is about: change that part, and leave the surface's place and size alone.
-  If the thing drawn on can say what is inside the drawing (partIn), the part lists exactly what was circled
-  (cells and values, paragraphs, lines, a picture of the area): the note is about that.
-- A note with "files": the user dropped those files there, from their computer or their file panel (all
-  in {work}/drops/). Look at them (read shows you pictures) and do what the note says with them, at
-  that spot or on that surface.
-- "[combine on the UI]": the user dragged surface A onto surface B and said how to combine them. Change B
-  so it takes A in, as they said: ui_render(surface=B, ..., made_from=<B's made_from plus A>,
-  instruction=<their words>, about=<updated>). Read A's data with {"ref": "A", "path": "/..."} props, so it
-  stays live; copy only what has to change shape. Never change or delete A: the user deletes it when they
-  want (B then gets a copy of what it read, automatically). Keep what B already showed unless they said otherwise.
-- Pointing is only as precise as your names: give elements you build a clear id or data-name.
-- Each note has an id. When you have dealt with it, call note_done(id): its pin fades from the page.

package/app/extensions/point/browser.js

@@ -1,247 +0,0 @@
-// Browser half of the point plugin (experiment). A pencil button in the tool palette (top) turns on a clear
-// layer over the page; the cursor is a pen, blue over something a click would point at.
-//   Click: a note box opens there.  Hold the button and draw: on release the note box opens, and the note
-//   covers the drawn area (its bounding box, in main-space px: where ui_render's place puts a surface).
-// The user sees only the box; the target goes to the agent with the note: surface and component (from
-// ui.js's data-surface / data-cid), the element itself (also inside App frames, which are same-origin),
-// its text, the source file to edit, the spot (main-space px; on empty space the spot is the whole target),
-// and the area if drawn. Enter sends it (point.py passes it to the surface's owner, gives it an id and
-// tells every open page to pin it, with its drawing). The pin fades when the agent marks the note
-// done (event "point_done") or the user closes it with its ✕; open notes are redrawn after a reload.
-// Esc or the button turns it off.
-// The same note box opens for two more things (Enter on an empty box sends its faded suggestion):
-//   combine  ui.js fires "ui-combine" {a, b, x, y} when a surface is dropped onto another: the note
-//            says how to combine them and goes to b's owner as point_combine (b changes; a stays)
-//   files    the files plugin fires "files-dropped" {x, y, files} when files land on the page (from the
-//            computer, or a row from its panel): a note with their paths, on what they were dropped on
-// Parts: an element (or an App page's window) with partAt(x, y) is asked what is at the spot (an enemy in a
-// canvas game); its answer goes with the note as "part". For a drawing, the thing under its middle is asked
-// partIn(points) instead, if it has it: what is inside the drawn shape (the circled cells, paragraphs, an
-// image of the area). points: [[x, y], ...] in window px (an App's window: px in its frame); it may be async.
-export default async function (page) {
-  let names = {};  // "ui-table" -> "Table" (tags are lower case; catalog names are not)
-  try { for (const n of Object.keys(await (await fetch("/ui-api/catalog")).json())) names[`ui-${n.toLowerCase()}`] = n; } catch {}
-
-  const layer = document.createElement("div");  // catches clicks, so the page underneath doesn't react
-  layer.style.cssText = "position:fixed;inset:0;z-index:9998;display:none";
-  // The cursor: the button's pen (white edge, so it shows on dark too), its tip (4, 20) is the spot pointed at.
-  const pen = (color) => `url("data:image/svg+xml,${encodeURIComponent(
-    `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke-linecap="round" stroke-linejoin="round">` +
-    `<g stroke="#fff" stroke-width="4"><path d="M4 20h4L19 9l-4-4L4 16z"/><path d="m13 7 4 4"/></g>` +
-    `<g stroke="${color}" stroke-width="2"><path d="M4 20h4L19 9l-4-4L4 16z"/><path d="m13 7 4 4"/></g></svg>`)}") 4 20, crosshair`;
-  const PEN = pen("#6e6e73"), PEN_ON = pen("#0071e3");  // grey: empty space; blue: over a thing
-  layer.style.cursor = PEN;
-  const input = document.createElement("input");  // the note box, opened where the user clicked
-  input.id = "point-note";
-  input.placeholder = "Write a note, Enter to send";
-  input.style.cssText = "position:fixed;z-index:9999;width:280px;box-sizing:border-box;font:inherit;font-size:14px;" +
-    "padding:8px 12px;border-radius:12px;outline:none;color:#1d1d1f;background:var(--glass-strong,#fff);" +  // the page's glass
-    "backdrop-filter:var(--blur);-webkit-backdrop-filter:var(--blur);border:1px solid var(--edge,#eee);" +
-    "box-shadow:0 8px 30px rgba(0,0,0,.1);display:none";
-  const SVG = "http://www.w3.org/2000/svg";
-  function strokeSvg(points) {  // a freehand stroke, drawn over the whole window (fixed, like the pins)
-    const svg = document.createElementNS(SVG, "svg");
-    svg.style.cssText = "position:fixed;inset:0;width:100vw;height:100vh;pointer-events:none";
-    const line = document.createElementNS(SVG, "polyline");
-    line.style.cssText = "fill:none;stroke:#f5b700;stroke-width:3;stroke-linecap:round;stroke-linejoin:round;opacity:.85";
-    line.setAttribute("points", points.map((p) => p.join(",")).join(" "));
-    svg.append(line);
-    return svg;
-  }
-  const ink = strokeSvg([]);  // the stroke being drawn
-  ink.style.zIndex = 9999;
-  ink.style.display = "none";
-  let current = null;  // {target, x, y, stroke} of the open note
-  let stroke = null;   // [[x, y], ...] while the mouse button is held down
-  document.body.append(layer, ink, input);
-
-  const button = document.createElement("button");
-  button.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h4L19 9l-4-4L4 16z"/><path d="m13 7 4 4"/></svg>`;
-  button.title = "Point: click anything, or hold and draw around an area, then write a note (Esc to stop)";
-  page.slot("status").prepend(button);  // the first tool in the palette, whichever script loads first
-  const setOn = (on) => {
-    layer.style.display = on ? "block" : "none";
-    button.classList.toggle("on", on);
-    if (!on) input.style.display = ink.style.display = "none";
-    if (!on) current = stroke = null;
-    if (on) document.dispatchEvent(new CustomEvent("tool-on", { detail: "point" }));  // the other tools turn off
-  };
-  button.onclick = () => setOn(layer.style.display === "none");
-  document.addEventListener("tool-on", (e) => { if (e.detail !== "point" && layer.style.display !== "none") setOn(false); });  // one tool at a time
-  document.addEventListener("keydown", (e) => { if (e.key === "Escape") setOn(false); });
-
-  const describe = (e) => e.localName + (e.id ? `#${e.id}` : "") + (e.dataset?.name ? `[data-name="${e.dataset.name}"]` : "") +
-    [...e.classList].slice(0, 2).map((c) => `.${c}`).join("");
-
-  function inMain(x, y) {  // window px -> main-space px (the main space scrolls; ui_render's place uses these)
-    const main = page.slot("top"), m = main.getBoundingClientRect();
-    return { x: Math.round(x - m.left + main.scrollLeft), y: Math.round(y - m.top + main.scrollTop) };
-  }
-
-  function target(x, y) {
-    const el = document.elementsFromPoint(x, y).find((e) => e !== layer);
-    if (!el) return null;
-    let inner = null, frame = null, box = el.getBoundingClientRect();
-    if (el.localName === "iframe") {  // look inside the frame (an App): same origin, so its document is readable
-      try {
-        const r = el.getBoundingClientRect(), dx = r.left + el.clientLeft, dy = r.top + el.clientTop;
-        inner = el.contentDocument?.elementFromPoint(x - dx, y - dy);
-        if (inner) { frame = el; const b = inner.getBoundingClientRect(); box = new DOMRect(b.x + dx, b.y + dy, b.width, b.height); }
-      } catch {}
-    }
-    const hitEl = inner || el;
-    const position = inMain(x, y);
-    if (el === page.slot("top")) return { owner: null, surface: null, components: [], element: "empty space in the main space",
-                              text: "", file: "", position, box: new DOMRect(x - 12, y - 12, 24, 24) };
-    const components = [];  // outermost first, e.g. ["root (Card)", "chart1 (Table)"]
-    for (let e = el.closest("[data-cid]"); e; e = e.parentElement?.closest("[data-cid]"))
-      components.unshift(`${e.dataset.cid} (${names[e.localName] || e.localName})`);
-    const path = [];  // a short selector: up to the nearest element with an id, at most 4 steps
-    for (let e = hitEl; e && path.length < 4 && e.localName !== "body"; e = e.parentElement) {
-      path.unshift(describe(e));
-      if (e.id) break;
-    }
-    const innermost = el.closest("[data-cid]");
-    let part = null;  // what the thing itself says is at this spot (partAt), e.g. {"name": "enemy-2"}
-    try {
-      if (frame?.contentWindow?.partAt) {
-        const r = frame.getBoundingClientRect();
-        part = frame.contentWindow.partAt(x - r.left - frame.clientLeft, y - r.top - frame.clientTop);
-      } else {
-        const owner = [hitEl, ...[...document.elementsFromPoint(x, y)]].find((e) => typeof e?.partAt === "function");
-        if (owner) { const r = owner.getBoundingClientRect(); part = owner.partAt(x - r.left, y - r.top); }
-      }
-    } catch (e) { console.warn("partAt:", e); }
-    const file = frame ? "/app" + new URL(frame.contentWindow.location.href).pathname  // /ui/apps/x/... -> /app/ui/apps/x/...
-      : innermost ? `/app/extensions/ui/components/${names[innermost.localName] || innermost.localName}.js`
-      : "/app/extensions/page/page.html (the page itself)";  // /app/: the code folder (the server puts in the real one)
-    return {
-      owner: el.closest("[data-owner]")?.dataset.owner || null,
-      surface: el.closest("[data-surface]")?.dataset.surface || null,
-      components,
-      element: path.join(" > "),
-      part,
-      text: (hitEl.innerText || hitEl.value || hitEl.alt || "").trim().replace(/\s+/g, " ").slice(0, 60),
-      file,
-      at: { x: Math.round(((x - box.x) / box.width) * 100) + "%", y: Math.round(((y - box.y) / box.height) * 100) + "%" },
-      position,
-      box,
-    };
-  }
-
-  // The note box at (x, y). `note`: what Enter sends besides the text (target, combine, files);
-  // `suggestion`: the faded text, sent as it is if the box is left empty (else the box needs words).
-  function openBox(x, y, note, suggestion = "") {
-    input.style.display = "block";
-    input.style.left = Math.min(x + 12, innerWidth - input.offsetWidth - 8) + "px";
-    input.style.top = Math.min(y + 12, innerHeight - input.offsetHeight - 8) + "px";
-    input.placeholder = suggestion || "Write a note, Enter to send";
-    current = { x, y, suggestion, ...note };
-    input.value = "";
-    input.focus();
-  }
-
-  function openNote(t, x, y, drawn = null) {  // a note on target t (and the drawn stroke)
-    if (!t) return;
-    const { box, ...rest } = t;
-    openBox(x, y, { type: "point_note", target: rest, stroke: drawn, to: rest.owner });
-  }
-
-  // Combine: a surface was dropped onto another (ui.js). The note goes to the target's owner.
-  document.addEventListener("ui-combine", ({ detail: { a, b, x, y } }) => {
-    const to = document.querySelector(`[data-surface="${CSS.escape(b)}"]`)?.dataset.owner;
-    openBox(x, y, { type: "point_combine", a, b, to }, `Add ${a} to ${b}`);
-  });
-
-  // Files dropped on the page (the files plugin: from the computer, or a row from its panel; already
-  // stored in /workspace/drops): a note on what they landed on. Esc closes the box; the files stay stored.
-  document.addEventListener("files-dropped", ({ detail: { x, y, files } }) => {
-    const t = target(x, y) || { owner: null, surface: null, components: [], element: "", text: "", file: "", position: inMain(x, y) };
-    const { box, ...rest } = t;
-    const paths = files.map((f) => `${f.path} (${Math.ceil(f.size / 1024)} KB)`);
-    openBox(x, y, { type: "point_note", target: rest, files: paths, to: rest.owner }, `Use ${files.map((f) => f.name).join(", ")} here`);
-  });
-
-  // Press, move, release: a small movement is a click on one thing; a bigger one is a drawing.
-  layer.onmousedown = (e) => {
-    stroke = [[e.clientX, e.clientY]];
-    input.style.display = ink.style.display = "none";
-  };
-  layer.onmousemove = (e) => {
-    if (!stroke) {
-      const t = target(e.clientX, e.clientY);
-      layer.style.cursor = t && t.surface ? PEN_ON : PEN;
-      return;
-    }
-    const [lx, ly] = stroke.at(-1);
-    if (Math.hypot(e.clientX - lx, e.clientY - ly) < 3) return;  // keep the stroke light
-    stroke.push([e.clientX, e.clientY]);
-    ink.style.display = "block";
-    ink.firstChild.setAttribute("points", stroke.map((p) => p.join(",")).join(" "));
-  };
-  async function partIn(x, y, points) {  // what the thing at (x, y) says is inside the drawing, or null
-    const el = document.elementsFromPoint(x, y).find((e) => e !== layer && e !== ink);
-    if (el?.localName === "iframe") {
-      try {
-        const r = el.getBoundingClientRect(), dx = r.left + el.clientLeft, dy = r.top + el.clientTop;
-        if (typeof el.contentWindow.partIn === "function") return await el.contentWindow.partIn(points.map(([px, py]) => [px - dx, py - dy]));
-      } catch (err) { console.warn("partIn:", err); }
-    }
-    const owner = document.elementsFromPoint(x, y).find((e) => typeof e.partIn === "function");
-    try { return owner ? await owner.partIn(points) : null; } catch (err) { console.warn("partIn:", err); return null; }
-  }
-
-  layer.onmouseup = async (e) => {
-    const points = stroke;
-    stroke = null;
-    if (!points) return;
-    const xs = points.map((p) => p[0]), ys = points.map((p) => p[1]);
-    const left = Math.min(...xs), top = Math.min(...ys), width = Math.max(...xs) - left, height = Math.max(...ys) - top;
-    if (width < 12 && height < 12) return openNote(target(e.clientX, e.clientY), e.clientX, e.clientY);
-    const t = target(left + width / 2, top + height / 2);  // what is under the middle of the drawing
-    if (t) t.area = { ...inMain(left, top), width: Math.round(width), height: Math.round(height) };
-    const inside = t && (await partIn(left + width / 2, top + height / 2, points));
-    if (inside) t.part = inside;
-    openNote(t, e.clientX, e.clientY, points);
-  };
-
-  input.onkeydown = (e) => {
-    const text = input.value.trim() || current?.suggestion;
-    if (e.key !== "Enter" || !text || !current) return;
-    const { suggestion, ...note } = current;
-    page.send({ ...note, text, to: note.to || document.getElementById("to")?.value,  // else the agent picked in the chat
-                board: Number(document.body.dataset.board) || 1 });  // the board shown (boards/): what it points at is on it
-    setOn(false);
-  };
-
-  const pins = {};  // note id -> pin element: its label, and its drawing if it has one
-  function pin({ id, text, to, x, y, stroke, board }) {  // stays where the note was written (doesn't follow scrolling yet)
-    if (pins[id]) return;
-    const el = (pins[id] = document.createElement("div"));
-    el.dataset.board = board ?? 1;  // shown only on its board (boards/)
-    el.style.cssText = "position:fixed;inset:0;z-index:9997;pointer-events:none;transition:opacity 1.5s";
-    if (stroke) el.append(strokeSvg(stroke));
-    const label = document.createElement("div");
-    label.style.cssText = `position:absolute;left:${x}px;top:${y}px;max-width:240px;` +
-      "background:#fff8c4;border:1px solid #e6c200;border-radius:4px;padding:3px 20px 3px 6px;font:12px sans-serif;" +
-      "box-shadow:0 1px 3px #0003";
-    label.textContent = `✎ ${text} · sent to ${to}`;
-    const close = document.createElement("button");
-    close.textContent = "✕";
-    close.title = "Close this note (its agent is told)";
-    close.style.cssText = "position:absolute;top:1px;right:3px;line-height:1;pointer-events:auto;border:0;background:none;cursor:pointer;padding:0 2px;font:inherit;color:#8a7400";
-    close.onclick = () => page.send({ type: "point_dismiss", id });
-    label.append(close);
-    el.append(label);
-    document.body.append(el);
-  }
-  page.on("point_pin", pin);
-  page.on("point_done", ({ id }) => {
-    const el = pins[id];
-    if (!el) return;
-    delete pins[id];
-    el.style.opacity = "0";
-    setTimeout(() => el.remove(), 1500);
-  });
-  try { for (const [id, n] of Object.entries(await (await fetch("/point/notes")).json())) pin({ id, ...n }); } catch {}
-}

package/app/extensions/point/guide.md

@@ -1,6 +0,0 @@
-# Notes on the UI
-The user clicks anything on the page (or draws around it, or drops files there) and writes a note: you get
-"[note on the UI] <their words>" with exactly what it is on.
-- Change that exact thing. If its text is data (a row, a score), change the surface's data, not the component.
-- When you have dealt with it, call note_done(id).
-Before you handle your first note, read README.md.

package/app/extensions/point/index.ts

@@ -1,112 +0,0 @@
-// Notes on the UI (port of the Python point plugin; the browser half, browser.js, is its point.js): the user points at
-// things and writes a note there; the note and its target go to an agent, so it knows exactly what it is about.
-//   point_note     click anything on the page (or draw around an area) and write: the target is the surface,
-//                  component, element, part (partAt), its text and source file, the spot and the area.
-//                  Files dropped on the page come as a note too ("files": paths in <workspace>/drops).
-//   point_combine  the user dragged surface a onto surface b and wrote how to combine them. The agent changes b to
-//                  take a in, reading a's data live ({"ref"} props); a stays as it is.
-// Each note goes to the surface's owner (else the agent picked in the chat), gets an id (n1, n2, ...: never reused)
-// and stays pinned (state/notes.json: {"last", "open": {id: note}}, redrawn after a reload) until the agent calls
-// note_done(id). The user can also close a pin (its ✕): the note is dropped, and taken out of its agent's inbox if
-// its turn hasn't started (the agent never saw it); else its agent is told (a note).
-// guide.md: the short prompt section; README.md (copied from point.py): the whole of it, read before a first note.
-import fs from "node:fs";
-import path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
-const host = (globalThis as any).chalky;
-const FILE = path.join(host.state, "notes.json");
-if (!host.shared.has("point"))
-  host.shared.set("point", fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 0, open: {} });
-const notes = host.shared.get("point");  // {last, open: {id: {text, to, x, y, stroke, board}}}
-if (!host.shared.has("point-items")) host.shared.set("point-items", new Map());
-const items: Map<string, any> = host.shared.get("point-items");  // note id -> its swarm inbox item (not saved)
-const save = () => fs.writeFileSync(FILE, JSON.stringify(notes));
-
-function pin(text: string, to: string, msg: any) {  // a new open note: saved, pinned on every page
-  const id = `n${++notes.last}`;
-  notes.open[id] = { text, to, x: msg.x ?? 0, y: msg.y ?? 0, stroke: msg.stroke ?? null,  // with its drawing, if any
-                     board: Number(msg.board) || 1 };  // the board it was written on (boards/): its pin shows there
-  save();
-  host.broadcast("point_pin", { id, ...notes.open[id] });
-  return id;
-}
-
-function describe(sid: string) {  // a source of a combine, for the agent: cut short if long
-  const r = host.shared.get("ui")?.surfaces[sid] ?? {};
-  const text = JSON.stringify({ owner: r.owner, about: r.about, components: r.components, data: r.data });
-  return text.length < 3000 ? text : text.slice(0, 3000) + ` … (more in ${host.app}/ui/surfaces.json and ${host.state}/ui-data.json)`;
-}
-
-export default function (pi: ExtensionAPI) {
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it, read when it says
-    .replace("README.md", path.join(import.meta.dirname, "README.md"));
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.point = guide; });
-  // a removed board (boards/) takes its open notes with it; a note its agent hasn't seen yet is just taken back
-  pi.on("session_start", () => host.api.boards?.onRemove("point", (n: number) => {
-    const gone: { owner: string; what: string }[] = [];
-    for (const id of Object.keys(notes.open).filter((id) => (notes.open[id].board ?? 1) === n)) {
-      const note = notes.open[id], item = items.get(id);
-      delete notes.open[id];
-      items.delete(id);
-      host.broadcast("point_done", { id });
-      if (!(item && host.api.swarm?.withdraw(item))) gone.push({ owner: note.to, what: `note ${id} ("${note.text}")` });
-    }
-    save();
-    return gone;
-  }));
-
-  pi.registerTool({
-    name: "note_done", label: "Note done", description: "Mark a note the user pinned on the UI as dealt with; its pin fades.",
-    parameters: Type.Object({ id: Type.String({ description: "e.g. n3" }) }),
-    async execute(_id, a) {
-      if (!notes.open[a.id]) return { content: [{ type: "text", text: `error: no open note '${a.id}'. Open notes: ${Object.keys(notes.open).join(", ")}` }], details: undefined };
-      delete notes.open[a.id];
-      items.delete(a.id);
-      save();
-      host.broadcast("point_done", { id: a.id });
-      return { content: [{ type: "text", text: `note ${a.id} is done; its pin fades from the page` }], details: undefined };
-    },
-  });
-
-  host.routes.set("/point/notes", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(notes.open)));
-
-  host.pageHandlers.set("point", (msg: any) => {
-    const swarm = host.api.swarm;
-    if (msg.type === "point_dismiss" && notes.open[msg.id]) {
-      const note = notes.open[msg.id];
-      delete notes.open[msg.id];
-      save();
-      host.broadcast("point_done", { id: msg.id });
-      const item = items.get(msg.id);
-      items.delete(msg.id);
-      if (!(item && swarm?.withdraw(item)))
-        swarm?.send("user", note.to, `[note on the UI] the user closed note ${msg.id} ("${note.text}"): drop it if you haven't finished it.`, true);
-    }
-    if (!["point_note", "point_combine"].includes(msg.type) || !swarm) return;
-    const to = host.agents.has(msg.to) ? msg.to : "agent1";
-    const text = msg.text ?? "";
-    if (msg.type === "point_combine") {
-      const { a, b } = msg;
-      const madeFrom = [...(host.shared.get("ui")?.surfaces[b]?.made_from ?? []).filter((m: string) => m !== a), a];
-      const id = pin(`combine ${a} into ${b}: ${text}`, to, msg);
-      return items.set(id, swarm.send("user", to, [`[combine on the UI] ${text}`, `  id: ${id} (call note_done("${id}") when dealt with)`,
-        `  board: ${notes.open[id].board}`,
-        `  dragged: ${a} (keep it as it is)`, `  onto: ${b} (change this one)`,
-        `  so: ui_render(surface="${b}", ..., made_from=${JSON.stringify(madeFrom)}, instruction=<their words>), reading ${a}'s data with {"ref": "${a}", "path": ...}`,
-        `  ${a}: ${describe(a)}`, `  ${b}: ${describe(b)}`].join("\n")));
-    }
-    const t = msg.target ?? {};
-    const at = t.at && `${t.at.x} across, ${t.at.y} down the element`;
-    const pos = t.position && `x=${t.position.x}, y=${t.position.y} px in the main space (for ui_render's place)`;
-    const area = t.area && `x=${t.area.x}, y=${t.area.y}, width=${t.area.width}, height=${t.area.height} px in the main space `
-      + (t.surface ? "(the user drew around this part of the surface: the note is about it)" : "(the user drew around empty space: build inside it)");
-    const id = pin(text, to, msg);
-    const lines = [`[note on the UI] ${text}`, `  id: ${id} (call note_done("${id}") when dealt with)`,
-      ...([["board", notes.open[id].board], ["surface", t.surface], ["component", (t.components ?? []).join(" → ")], ["element", t.element],
-           ["part", t.part && JSON.stringify(t.part)], ["at", at], ["text", t.text], ["file", t.file?.replace(/^\/app\//, host.app + "/")], ["position", pos],
-           ["area", area], ["files", msg.files?.join(", ")]] as [string, any][]).filter(([, v]) => v).map(([k, v]) => `  ${k}: ${v}`)];
-    items.set(id, swarm.send("user", to, lines.join("\n")));
-  });
-}

package/app/extensions/prompt/index.ts

@@ -1,19 +0,0 @@
-// Where things are: the paths the prompt needs that depend on this machine, as the <paths> section. The prompt's
-// words are app/SYSTEM.md (pi's documented way to replace its default prompt), which is plain text and can't hold
-// these. pi adds the skills list and the working folder (<cwd>) itself.
-import { getDocsPath, getExamplesPath, getReadmePath, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-export default function (pi: ExtensionAPI) {
-  pi.on("before_agent_start", (event) => {
-    const host = (globalThis as any).chalky;
-    event.systemPromptOptions.sections.paths = [
-      `{code} = ${host.app}: your code (versioned: each turn that changes it is saved, and the user can roll back)`,
-      `{work} = ${host.work}: your working folder (<cwd>), for project work and the user's files`,
-      `{data} = ${host.state}: what the agents and apps keep (conversations, app data, surfaces' data; not versioned)`,
-      `{page} = http://127.0.0.1:${host.port}: the user's page, served by the host`,
-      `The host: ${host.root}/server.ts`,
-      `pi's docs: ${getDocsPath()}/extensions.md for extensions, examples in ${getExamplesPath()}/extensions/; the rest in `
-        + `${getReadmePath()} and ${getDocsPath()}/. Read pi's .md files completely and follow their links.`,
-    ].join("\n");
-  });
-}

package/app/extensions/ui/README.md

@@ -1,69 +0,0 @@
-# Showing UI to the user (the ui extension)
-Show forms, tables, dashboards or games as UI surfaces: cards in the page's main space, described as JSON.
-Prefer a surface over editing the page ({code}/extensions/page/page.html). Aim for one screen; make it scroll only if the user asks.
-A surface shows only what you build, with no frame: when asked for a thing (a smiley, a chart), show just
-that thing. Add a background, border or Card only if the thing itself needs one. An app's page should keep
-a transparent background, so it sits on the workspace.
-Name what you build (a clear surface id, ids or data-name on elements): the user points at things by name.
-Compose from existing components; write a new component only if none fits.
-Before building or restyling what the user sees, load the ui-design skill (how it should look and read).
-- ui_catalog: lists the components and their props. Read it first.
-- ui_render(surface, components, data): draw or replace a surface. components is a flat list; each has
-  "id", "component" (a catalog name), its props, and "children": [ids] or "child": id. One has id "root".
-  A prop can be {"path": "/x"} to bind it to this surface's data (inputs write to it), or
-  {"ref": "other-surface", "path": "/x"} to read another surface's data live (no copy: it follows changes).
-  Errors come back to you; fix and retry.
-- about="...": one or two sentences on what the surface is for and why it is built this way. The user reads
-  it on the surface's back side; you read it in {code}/ui/surfaces.json. Keep it true when you change things.
-- options=[{"label", "components", "data"}, ...] instead of components: when you are not sure what the user
-  meant, offer 2-3 versions; they flip through them and keep one.
-- Pinned surfaces (the user held their label): your ui_render, ui_update and ui_delete on them fail. Don't
-  work around it: make a new surface (made_from=[the pinned one]) or ask the user.
-- Surfaces stack in the main space and are as wide as their content. place={"x", "y", "width"?, "height"?}
-  (px from the main space's top-left) pins one at a spot instead: use it when the user points at a spot
-  ("here") or draws an area (then fill that area: its x, y, width and height).
-- Everything you show is draggable by default: the user moves a surface by its label (shown on hover), and
-  it stays where they put it (ui_render without place keeps it there; where things are now: the "place" of
-  each surface in {code}/ui/surfaces.json). Pass draggable=false only when the
-  user wants something fixed. In an app you build, make separate pieces draggable too, unless told otherwise.
-- Everything you show is resizable by default too: the user drags its bottom-right corner (shown on hover),
-  and the surface's root component fills the new size. So build things that fill their space (sizes in %,
-  flex, or scaled to their box, e.g. an SVG with a viewBox), not fixed px. Pass resizable=false only when the
-  user wants a fixed size.
-- ui_update(surface, path, value): change data only (fast; components keep their state). ui_delete(surface).
-- Data (what users typed, rows, scores) is kept in {data}/ui-data.json (not versioned); the rest of each
-  surface in {code}/ui/surfaces.json. The user can undo any change (theirs or yours), so don't keep backups.
-- When the user clicks a Button you get "[ui action] <name> ..." with the surface's data.
-- Voice input (dictation, meeting notes): import /ui/voice.js in the app (read its header), never the
-  browser's speech API or a provider directly: it uses the sandbox's speech-to-text API, or the browser's.
-- A new component: {code}/extensions/ui/components/<Name>.js. Start with a comment line "// Name: what it does" (more
-  comment lines if needed), then its about block, then
-  `export default class extends HTMLElement { update(props, ui) {...} }`.
-  The about block of a component (strict JSON after `export const about = `):
-    "version": 1             the shape of its props; raise it when they change, and export
-                             upgrade(props, fromVersion) -> props, so surfaces saved earlier still draw
-    "props": {"name": {"type": "text" | "number" | "boolean" | "choice" | "list" | "rows" | "object" | "action",
-                       "options": [...] (for choice), "default": ..., "doc": "what it is"}}
-    "children": "none" | "one" | "many"
-    "levers": ["Shown as {variant}."]   the back side: plain sentences; each {prop} becomes a control the user
-                             can change there (choice and boolean cycle, text and number are typed)
-    "accepts": "rows with a number column"   optional: what it can take when something is dropped on it
-    "example": {...props}    one sample, for the catalog and for checks
-  When you change a component's props in a way old surfaces would break on, raise "version" and export
-  upgrade(props, fromVersion) returning props in the new shape.
-  update() runs on every change, on the same element: keep internal state there (e.g. a game loop).
-  ui.children: child elements, placed with ui.mount(container); ui.set(prop, value) writes a bound prop;
-  ui.action(name, context) sends an action to you. Make it general so it can be reused. New components work
-  immediately; edited components and App files show when your turn ends (the page refreshes itself). Big multi-file apps: {code}/ui/apps/<name>/, shown with App.
-  Pointing inside a canvas: give the element (or an App page's window) a partAt(x, y) function returning
-  {"name", ...} for what is at that spot, so the user can point at parts (an enemy, a cell).
-- Agents inside what you build (a simulation's members, a debate, characters): load the agent-apps
-  skill first. They are real agents that belong to the app, not workers helping you build it.
-- Libraries: components import them by name (import { marked } from "marked"), as mapped in the import map
-  at the top of {code}/extensions/page/page.html; installed ones are in {code}/extensions/ui/package.json. To add
-  one, download its ES-module build into {code}/extensions/ui/node_modules/<pkg>/ and add a line to the import map.
-- Component pitfalls (you can't see the browser, so avoid them up front):
-  keep your own state in one object, this.state = {...}: fields like this.dir, this.title, this.hidden,
-  this.id, this.style, this.lang are built-in HTMLElement properties and silently break;
-  set a canvas's width/height BEFORE drawing (resizing clears it); don't create things twice in update();
-  remove document-level listeners/timers when the element is no longer connected.

package/app/extensions/ui/components/App.js

@@ -1,28 +0,0 @@
-// App: shows a full mini-site from {code}/ui/apps/<name>/ in a frame. For big things (multi-file games, editors)
-// that don't fit one component. Put index.html (and its scripts) in {code}/ui/apps/<name>/.
-// No frame of its own and a clear background: only the app's page shows (keep that page's background
-// transparent unless the app needs one). As wide as its surface; it fills its surface's placed area,
-// else it is `height` px tall. The app can talk to the agents and see their messages: /ui/agents.js.
-export const about = {
-  "version": 1,
-  "props": {
-    "src": {"type": "text", "doc": "path inside {code}/ui/apps, e.g. \"snake/index.html\""},
-    "height": {"type": "number", "default": 400, "doc": "px, when nothing else sizes it"}
-  },
-  "children": "none",
-  "levers": ["Shows {src}.", "{height} px tall when not placed."],
-  "example": {"src": "snake/index.html", "height": 400}
-};
-export default class extends HTMLElement {
-  update({ src = "", height = 400 }) {
-    if (!this.frame) {
-      this.style.cssText = "display:flex;flex-direction:column;align-self:stretch";
-      this.frame = document.createElement("iframe");
-      this.frame.style.cssText = "width:100%;min-height:0;border:0;background:transparent;color-scheme:normal";
-      this.append(this.frame);
-    }
-    this.frame.style.flex = `1 1 ${height}px`;  // height when nothing sizes it; grows or shrinks to a placed area
-    const url = `/ui/apps/${src}`;
-    if (this.frame.getAttribute("src") !== url) this.frame.setAttribute("src", url);  // don't restart a running app
-  }
-}