@chalky/chalky 0.1.4 → 0.1.5

package/{app/extensions/boards → agent/extensions/board}/index.ts

@@ -1,39 +1,39 @@
-// Boards: the main space is several numbered boards, and everything on it (surfaces, frames, notes; a doodle's
+// Boards: the main space is several numbered boards, and everything on it (cards, frames, notes; a doodle's
 // steps when sent) has a board number. Numbers are never reused: remove board 2 and the rest stay 1, 3, 4, so "board 3" keeps
 // meaning the same board to the user and to every agent. A thing with no number is on board 1.
-//   app/ui/boards.json   {last: <last number>, boards: [numbers]}: next to surfaces.json, so a rollback of the code
+//   built/board.json     {last: <last number>, boards: [numbers]}: next to card.json, so a rollback
 //                        brings back both together (read each time: never stale after one)
 // The board the user is looking at is the page's to say (in memory; board 1 until it does). browser.js: the shelf.
-// Tool boards(board?): the boards and what is on each, and the board the user is on. Others use host.api.boards:
+// Tool boards(board?): the boards and what is on each, and the board the user is on. Others use host.api.board:
 //   list() -> [numbers]   has(n)   add(by?) -> the new number   current() -> the user's board
 //   onRemove(name, fn)    remove(n): see below
-//   GET /boards  {boards, current}      page messages  board_view {board}, board_add, board_remove {board}
-//   event "boards"  {boards, added, by}: a board was added (by "user": that page goes there); {boards, removed}
+//   GET /board   {boards, current}      page messages  board_view {board}, board_add, board_remove {board}
+//   event "board"   {boards, added, by}: a board was added (by "user": that page goes there); {boards, removed}
 import fs from "node:fs";
 import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 const host = (globalThis as any).chalky;
-const FILE = path.join(host.app, "ui/boards.json");
+const FILE = path.join(host.built, "board.json");
 const read = () => (fs.existsSync(FILE) ? JSON.parse(fs.readFileSync(FILE, "utf8")) : { last: 1, boards: [1] });
 if (!host.shared.has("board-view")) host.shared.set("board-view", { current: 1 });
 const view = host.shared.get("board-view");
 
-host.api.boards = {
+host.api.board = {
   list: () => read().boards as number[],
   has: (n: number) => read().boards.includes(n),
   add(by = "agent") {  // by "user": the page that asked goes there
     const saved = read();
     saved.boards.push(++saved.last);
     fs.writeFileSync(FILE, JSON.stringify(saved));
-    host.broadcast("boards", { boards: saved.boards, added: saved.last, by });
+    host.broadcast("board", { boards: saved.boards, added: saved.last, by });
     return saved.last;
   },
   current: () => (read().boards.includes(view.current) ? view.current : read().boards[0]),
   // Removing a board (the user's ✕, after its few seconds of Undo on the page): each extension takes its own things
   // off it (onRemove(name, fn): fn(n) deletes them and returns [{owner, what}], e.g. {owner: "agent2", what:
-  // "surface prices"}; name: the extension's, so its reload replaces its own). Each agent that owned something gets
+  // "card prices"}; name: the extension's, so its reload replaces its own). Each agent that owned something gets
   // one fyi (no turn of its own: it reads it on its next one). The last board stays.
   onRemove: (name: string, fn: (n: number) => { owner?: string; what: string }[]) => removers.set(name, fn),
   remove(n: number) {
@@ -46,11 +46,11 @@ host.api.boards = {
     }
     saved.boards = saved.boards.filter((b: number) => b !== n);
     fs.writeFileSync(FILE, JSON.stringify(saved));
-    host.broadcast("boards", { boards: saved.boards, removed: n });
+    host.broadcast("board", { boards: saved.boards, removed: n });
     const byOwner = new Map<string, string[]>();
     for (const g of gone) if (g.owner && host.agents.has(g.owner)) byOwner.set(g.owner, [...(byOwner.get(g.owner) ?? []), g.what]);
     for (const [owner, things] of byOwner)
-      host.api.swarm?.fyi("user", owner, `[board removed] The user removed board ${n}; your ${things.join(", ")} went with it.`);
+      host.api.team?.fyi("user", owner, `[board removed] The user removed board ${n}; your ${things.join(", ")} went with it.`);
   },
 };
 // on the host, so they outlive this file's reloads (as ui's watchers)
@@ -60,39 +60,41 @@ host.shared.set("board-removers", removers);
 const result = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
 
 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.boards = guide; });
 
   pi.registerTool({
-    name: "boards", label: "Boards",
+    name: "board_list", label: "Board list",
     description: "List the boards, what is on each, and the board the user is on. With a board: that one in detail.",
     parameters: Type.Object({ board: Type.Optional(Type.Number()) }),
     async execute(_id, a) {
-      // what has a board: surfaces (ui/), frames not filled yet (frames/), open notes (point/); doodles aren't kept
+      // what has a board: cards (card/), frames not filled yet (frame/), open notes (note/), marks not cleared (doodle/)
       const of = (m: any) => Object.entries(m ?? {}) as [string, any][];
-      const kinds = (n: number) => [of(host.shared.get("ui")?.surfaces), of(host.shared.get("frames")?.frames), of(host.shared.get("point")?.open)]
+      const kinds = (n: number) => [of(host.shared.get("card")?.cards), of(host.shared.get("frame")?.frames),
+                                    of(host.shared.get("note")?.notes).filter(([, r]) => r.state === "open"),
+                                    of(host.shared.get("doodle")?.groups).filter(([, r]) => r.state !== "cleared")]
         .map((list) => list.filter(([, r]) => (r.board ?? 1) === n));
-      const head = `the user is on board ${host.api.boards.current()}`;
+      const head = `the user is on board ${host.api.board.current()}`;
       if (a.board === undefined)
-        return result([head, ...host.api.boards.list().map((n: number) => {
-          const [s, f, notes] = kinds(n);
-          return `${n}  ${[s.map(([id]) => id).join(", "), f.map(([id]) => id).join(", "), notes.map(([id]) => `note ${id}`).join(", ")]
+        return result([head, ...host.api.board.list().map((n: number) => {
+          const [s, f, notes, marks] = kinds(n);
+          return `${n}  ${[s.map(([id]) => id).join(", "), f.map(([id]) => id).join(", "), notes.map(([id]) => `note ${id}`).join(", "),
+                           marks.map(([id]) => `marks ${id}`).join(", ")]
             .filter(Boolean).join(" · ") || "(empty)"}`;
         })].join("\n"));
-      if (!host.api.boards.has(a.board)) return result(`error: no board ${a.board}. Boards: ${host.api.boards.list().join(", ")}`);
-      const [s, f, notes] = kinds(a.board);
+      if (!host.api.board.has(a.board)) return result(`error: no board ${a.board}. Boards: ${host.api.board.list().join(", ")}`);
+      const [s, f, notes, marks] = kinds(a.board);
       return result([head, `board ${a.board}:`,
-        ...s.map(([id, r]) => `  surface ${id} · by ${r.owner} · place ${JSON.stringify(r.place)}${r.pinned ? " · pinned" : ""}`),
+        ...s.map(([id, r]) => `  card ${id} · by ${r.owner} · place ${JSON.stringify(r.place)}${r.pinned ? " · pinned" : ""}`),
         ...f.map(([id, r]) => `  frame ${id} "${r.text}" · ${r.sent ? `sent to ${r.to}` : "not sent"} · place ${JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height })}`),
-        ...notes.map(([id, r]) => `  note ${id} "${r.text}" · to ${r.to}`)].join("\n") + (s.length + f.length + notes.length ? "" : "\n  (empty)"));
+        ...notes.map(([id, r]) => `  note ${id} "${r.thread[0]?.text}" · to ${r.to}`),
+        ...marks.map(([id, r]) => `  marks ${id} (${r.state}) · ${r.label}`)].join("\n") + (s.length + f.length + notes.length + marks.length ? "" : "\n  (empty)"));
     },
   });
 
-  host.routes.set("/boards", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
-    .end(JSON.stringify({ boards: host.api.boards.list(), current: host.api.boards.current() })));
-  host.pageHandlers.set("boards", (msg: any) => {
-    if (msg.type === "board_view" && host.api.boards.has(Number(msg.board))) view.current = Number(msg.board);
-    else if (msg.type === "board_add") host.api.boards.add("user");
-    else if (msg.type === "board_remove") host.api.boards.remove(Number(msg.board));
+  host.routes.set("/board", (_req: any, res: any) => res.writeHead(200, { "content-type": "application/json" })
+    .end(JSON.stringify({ boards: host.api.board.list(), current: host.api.board.current() })));
+  host.pageHandlers.set("board", (msg: any) => {
+    if (msg.type === "board_view" && host.api.board.has(Number(msg.board))) view.current = Number(msg.board);
+    else if (msg.type === "board_add") host.api.board.add("user");
+    else if (msg.type === "board_remove") host.api.board.remove(Number(msg.board));
   });
 }

package/agent/extensions/card/README.md

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

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

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

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

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

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

@@ -0,0 +1,37 @@
+// Markdown: formatted text from a markdown string (headings, lists, tables, code, links, quotes).
+// HTML in the text is sanitised; links open in a new tab. The chat draws message bodies with it too.
+export const about = {
+  "version": 1,
+  "props": {
+    "text": {"type": "text", "doc": "markdown"}
+  },
+  "children": "none",
+  "levers": [],
+  "example": {"text": "**Lunch** closes *Friday 11:00*"}
+};
+import { marked } from "marked";      // bare names: resolved by the import map in page.html
+import DOMPurify from "dompurify";
+
+const CSS = `
+block-markdown { display: block; white-space: normal; }
+block-markdown p, block-markdown ul, block-markdown ol, block-markdown pre, block-markdown table, block-markdown blockquote { margin: 6px 0; }
+block-markdown ul, block-markdown ol { padding-left: 22px; }
+block-markdown h1, block-markdown h2, block-markdown h3, block-markdown h4 { font-size: 1.05em; margin: 8px 0 4px; }
+block-markdown code { font: 12.5px monospace; background: rgba(0, 0, 0, .06); padding: 1px 4px; border-radius: 3px; }
+block-markdown pre { background: var(--hover); padding: 8px; border-radius: 4px; overflow-x: auto; }
+block-markdown pre code { background: none; padding: 0; }
+block-markdown table { border-collapse: collapse; }
+block-markdown th, block-markdown td { border: 1px solid var(--line); padding: 3px 8px; }
+block-markdown blockquote { border-left: 3px solid var(--line); padding-left: 8px; color: var(--soft); }`;
+
+export default class extends HTMLElement {
+  update({ text = "" }) {
+    if (!document.getElementById("block-markdown-css")) {
+      document.head.insertAdjacentHTML("beforeend", `<style id="block-markdown-css">${CSS}</style>`);
+    }
+    if (this.state?.text === text) return;  // unchanged: keep the DOM (and any selection)
+    this.state = { text };
+    this.innerHTML = DOMPurify.sanitize(marked.parse(text, { gfm: true, breaks: true }));
+    for (const a of this.querySelectorAll("a")) { a.target = "_blank"; a.rel = "noopener"; }
+  }
+}

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

@@ -1,4 +1,4 @@
-// Card: a glass panel with an optional title; its children are stacked inside.
+// Panel: a glass panel with an optional title; its children are stacked inside.
 export const about = {
   "version": 1,
   "props": {
@@ -9,7 +9,7 @@ export const about = {
   "example": {"title": "Lunch orders"}
 };
 export default class extends HTMLElement {
-  update({ title = "" }, ui) {
+  update({ title = "" }, card) {
     if (!this.body) {
       this.style.cssText = "display:block;padding:14px 16px;border-radius:var(--radius);background:var(--glass-strong);" +
         "border:1px solid var(--edge);box-shadow:var(--shadow);backdrop-filter:var(--blur)";
@@ -18,6 +18,6 @@ export default class extends HTMLElement {
     }
     this.firstChild.textContent = title;
     this.firstChild.hidden = !title;
-    ui.mount(this.body);
+    card.mount(this.body);
   }
 }

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

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

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

@@ -12,17 +12,17 @@ export const about = {
   "example": {"label": "Your name", "value": "", "placeholder": "e.g. S. Tan"}
 };
 export default class extends HTMLElement {
-  update({ label = "", value = "", placeholder = "", multiline = false }, ui) {
+  update({ label = "", value = "", placeholder = "", multiline = false }, card) {
     if (!this.input) {
       this.style.cssText = "display:flex;flex-direction:column;gap:4px";
       this.innerHTML = `<label style="font-size:12px;color:var(--muted)"></label>`;
       this.input = document.createElement(multiline ? "textarea" : "input");
       this.input.style.cssText = "padding:8px 10px;font:inherit;color:inherit;border-radius:10px;" +
         "background:var(--glass-strong);border:1px solid var(--line)";
-      this.input.oninput = () => this.ui.set("value", this.input.value);
+      this.input.oninput = () => this.card.set("value", this.input.value);
       this.append(this.input);
     }
-    this.ui = ui;
+    this.card = card;
     this.firstChild.textContent = label;
     this.input.placeholder = placeholder;
     if (document.activeElement !== this.input) this.input.value = value ?? "";  // don't fight the user's typing