@chalky/chalky 0.1.4 → 0.1.6

package/{app → agent}/extensions/page/page.html

@@ -2,7 +2,7 @@
 <!-- The page the user sees, served fresh on every load by the page extension (extensions/page/; edits show on reload).
   Design (pivot 2026-10-14, see the Chalky repo's NOTES.md "Direction"): what the agents build fills the screen; talk is secondary.
   Layout, every part fixed over the full window:
-    #top      main space: what the agents built (the ui plugin draws its surfaces here). Scrolls.
+    #top      main space: what the agents built (the card extension draws its cards here). Scrolls.
     #rail     left edge: icons that open a panel; clicking the open one closes it.
     #panel    a glass panel over the main space: #messages (the conversation) or #versions (history,
               a screenshot of each version, rollback; the user's way to undo the agent's own changes: keep it working).
@@ -14,9 +14,12 @@
               A tool with sub-tools (frames' Implement) is a <span class="tool">: its button, then a
               smaller row (.sub) that hangs directly under it, hidden while none of its buttons shows (pageApi.tool).
     #side     right edge: empty; a browser plugin fills it (the files plugin's file panel).
+  Names (data-name) an agent's pen can point at: tools (the palette), rail, messages, versions, message-line; the
+  palette's buttons get theirs from their plugins (pen, text, eraser, show-marks, note, frames, files, dictate).
   Look: glass layers on one soft background, tokens in :root (colours, glass, blur, sizes); icons are inline
   SVG from ICONS (data-icon="name").
-  Messages: only words are full text (the user's, and an agent's reply); everything else an agent does
+  Messages: only words are full text (the user's, and an agent's reply); a message the page wrote for the user
+  ("[note on the page] ...") shows their words, the whole text in its data-raw (plugins find their ids there); everything else an agent does
   (reasoning, tool calls, results, messages between agents) is a small icon: hover to peek, click to read.
   App agents (status "app": part of something built, e.g. a simulation's members) stay out of the messages,
   the picker and the working rows (one row per app): their app shows their talk.
@@ -24,7 +27,10 @@
   "status", "message", "version", errors. Sending: {to, text} is a message, {type: "stop"} stops all.
   Extending without editing this file: an extension's browser.js (extensions/<name>/browser.js; GET /page/scripts lists them);
   each script's default export gets pageApi: on(type, fn), send(obj) (-> the extensions' page handlers),
-  slot("top" | "status" | "side"), tool(button) -> the row under that palette tool (for its sub-tools), note(text), load(name), component(name, props) (components from extensions/ui/components),
+  slot("top" | "status" | "side"), tool(button) -> the row under that palette tool (for its sub-tools), note(text) -> the line, load(name), block(name, props) (blocks from extensions/card/blocks),
+  notice(content, onClose) -> {el, set(...content), close(), open}: a notice in the column at the top right, newest on
+  top (content: a string, a node, or a list of them; a <button class="go"> is the main action); its ✕ calls onClose,
+  then closes it; an action closes it with close(). Notices of every extension go here, so they never overlap.
   command(name, fn, description): "/name rest" typed in the input calls fn(rest) instead of sending (other "/..." text
   is sent); typing "/" lists the commands above the input, narrowing as you type.
   provide(name, obj) / use(name) -> promise of obj: what one browser plugin offers others (scripts load in any
@@ -32,11 +38,11 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Chalky</title>
-<!-- Libraries that components import by name (installed from extensions/ui/package.json). Must come before any module. -->
+<!-- Libraries that blocks import by name (the host's dependencies, served by the card extension). Must come before any module. -->
 <script type="importmap">
 { "imports": {
-    "marked": "/ui/node_modules/marked/lib/marked.esm.js",
-    "dompurify": "/ui/node_modules/dompurify/dist/purify.es.mjs"
+    "marked": "/card/node_modules/marked/lib/marked.esm.js",
+    "dompurify": "/card/node_modules/dompurify/dist/purify.es.mjs"
 } }
 </script>
 <style>
@@ -79,6 +85,24 @@
   #status .sub:not(:has(> :not([hidden]))) { display: none; }  /* only hidden buttons (or none): no row */
   #status .tool .badge { top: -4px; right: -4px; }  /* on the corner, off the icon */
   #side { position: fixed; top: 0; right: 0; z-index: 20; display: flex; flex-direction: column; align-items: flex-end; }
+  /* notices (pageApi.notice): a column at the top right, newest on top; above cards and frames */
+  #notices { position: fixed; top: 14px; right: 16px; z-index: 200000; width: min(340px, calc(100vw - 32px));
+             display: flex; flex-direction: column; pointer-events: none; }
+  #notices .notice { display: grid; grid-template-rows: 1fr; pointer-events: auto;
+                     transition: grid-template-rows .32s cubic-bezier(.3,.7,.3,1), opacity .25s, transform .32s cubic-bezier(.3,.7,.3,1); }
+  #notices .notice.out { grid-template-rows: 0fr; opacity: 0; transform: translateX(28px); }  /* arriving or leaving: no height, so the rest slide */
+  #notices .notice > div { min-height: 0; overflow: hidden; }
+  #notices .notice-box { position: relative; margin-bottom: 8px; padding: 10px 34px 10px 14px; border-radius: 14px; display: flex;
+                         flex-wrap: wrap; align-items: center; gap: 8px 10px; font-size: 13px; color: var(--text);
+                         background: var(--glass-strong, #fff); border: 1px solid var(--edge, #eee); box-shadow: 0 8px 26px rgba(0,0,0,.12);
+                         backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur); }
+  #notices .notice-box button { border: 0; border-radius: 8px; padding: 5px 11px; font: inherit; font-size: 12px; cursor: pointer;
+                                background: var(--line, #eee); color: var(--text); }
+  #notices .notice-box button.go { background: var(--accent, #0071e3); color: #fff; }
+  #notices .notice-box button.notice-x { position: absolute; top: 6px; right: 6px; width: 22px; height: 22px; padding: 0;
+                                         background: none; color: var(--muted); font-size: 13px; line-height: 22px; }
+  #notices .notice-box button.notice-x:hover { background: var(--hover, #eee); color: var(--text); }
+  @media (prefers-reduced-motion: reduce) { #notices .notice { transition: opacity .15s; } }
   #rail button, #status > button, #status > details > summary, #status > .tool > button, #status .sub > button {
     width: 38px; height: 38px; display: grid; place-items: center; border-radius: 12px; color: var(--muted);
     position: relative; list-style: none; cursor: pointer; transition: background 0.15s, color 0.15s; }
@@ -113,17 +137,17 @@
          mask-image: var(--fade); -webkit-mask-image: var(--fade); }
   #log:hover { --fade: linear-gradient(transparent, #000 56px); }
   #log > :first-child { margin-top: auto; }  /* few messages: they sit at the bottom (flex-end would break scrolling) */
-  .block { margin: 0 0 22px; animation: rise 0.4s ease-out; }
+  .group { margin: 0 0 22px; animation: rise 0.4s ease-out; }
   @keyframes rise { from { opacity: 0; transform: translateY(14px); } }
   .who { display: flex; align-items: center; gap: 6px; font-size: 11.5px; font-weight: 500; letter-spacing: 0.01em;
          color: var(--c, var(--muted)); }
   .who svg { width: 16px; height: 16px; }
   .who time { margin-left: auto; font-weight: 400; color: var(--muted); opacity: 0; transition: opacity 0.2s; }
-  .block:hover .who time { opacity: 1; }
+  .group:hover .who time { opacity: 1; }
   .text { margin: 3px 0 0 22px; color: var(--soft); white-space: pre-wrap; overflow-wrap: anywhere; letter-spacing: -0.005em; }
-  .block:not([data-who="you"]) .text { color: var(--text); }
+  .group:not([data-who="you"]) .text { color: var(--text); }
   .text .to { color: var(--muted); font-size: 12px; margin-right: 4px; }
-  .text > ui-markdown, .text > ui-markdown > p:first-child { display: inline; }  /* first line next to .to */
+  .text > block-markdown, .text > block-markdown > p:first-child { display: inline; }  /* first line next to .to */
   .steps { display: flex; flex-wrap: wrap; gap: 1px; margin: 4px 0 0 19px; }
   .step { color: var(--muted); padding: 3px; border-radius: 6px; opacity: 0.8; }
   .step svg { width: 14px; height: 14px; }
@@ -187,9 +211,9 @@
 </style>
 <body data-panel="messages">
 <div id="top"></div>
-<nav id="rail">
-  <button id="show-messages" data-icon="messages" title="Messages"><span class="badge" id="unread"></span></button>
-  <button id="show-versions" data-icon="versions" title="Versions"></button>
+<nav id="rail" data-name="rail">
+  <button id="show-messages" data-name="messages" data-icon="messages" title="Messages"><span class="badge" id="unread"></span></button>
+  <button id="show-versions" data-name="versions" data-icon="versions" title="Versions"></button>
 </nav>
 <aside id="panel">
   <section id="messages"><div id="log"></div></section>
@@ -201,14 +225,15 @@
   </section>
 </aside>
 <div id="working" hidden><div id="busy"></div><button id="stop" data-icon="stop" title="Stop all agents"></button></div>
-<form id="f">
+<form id="f" data-name="message-line">
   <div id="cmds" hidden></div>
   <select id="to" title="Send to" hidden></select>
   <input id="text" placeholder="Tell the agents what to build or change" autocomplete="off">
   <button data-icon="send" title="Send"></button>
 </form>
-<nav id="status"></nav>
+<nav id="status" data-name="tools"></nav>
 <aside id="side"></aside>
+<div id="notices" aria-live="polite"></div>
 <script>
   const log = document.getElementById("log"), to = document.getElementById("to");
   const ws = new WebSocket((location.protocol === "https:" ? "wss://" : "ws://") + location.host + "/ws");
@@ -247,15 +272,15 @@
     to.hidden = to.options.length < 2;
   }
 
-  // ---- Component runtime: the catalog of reusable UI pieces (/ui/components/<Name>.js), each a custom
-  // element <ui-name> with update(props, ui). The page draws replies with it; browser plugins use
-  // page.load / page.component (the ui plugin draws agents' surfaces from the same catalog).
+  // ---- Block runtime: the catalog of blocks (/card/blocks/<Name>.js), each a custom element <block-name> with
+  // update(props, card). The page draws replies with it; browser parts use page.load / page.block (the card
+  // extension draws the agents' cards from the same catalog).
   let catalog = null;
-  const loading = {};  // name -> promise: true once <ui-name> is defined, false if there is no such component
+  const loading = {};  // name -> promise: true once <block-name> is defined, false if there is no such block
   const loaded = {};   // name -> version loaded (custom elements can't be redefined: changes need a reload)
   async function fetchCatalog() {  // false: the agent didn't answer (e.g. restarting); the catalog stays as it was
     try {
-      const r = await fetch("/ui-api/catalog");
+      const r = await fetch("/card/blocks");
       if (r.ok) { catalog = await r.json(); return true; }
     } catch {}
     catalog ??= {};
@@ -265,32 +290,32 @@
     return loading[name] ??= (async () => {
       if (!catalog || !(name in catalog)) await fetchCatalog();  // maybe just written
       if (!(name in catalog)) return false;
-      const tag = `ui-${name.toLowerCase()}`;
-      if (!customElements.get(tag)) customElements.define(tag, (await import(`/ui/components/${name}.js?v=${catalog[name]}`)).default);
+      const tag = `block-${name.toLowerCase()}`;
+      if (!customElements.get(tag)) customElements.define(tag, (await import(`/card/blocks/${name}.js?v=${catalog[name]}`)).default);
       loaded[name] = catalog[name];
       return true;
     })().catch((e) => { delete loading[name]; throw e; });  // a broken file: try again next time
   }
-  async function component(name, props = {}) {  // a ready element, or null if the component is missing/broken
-    try { if (!(await load(name))) return null; } catch (e) { console.warn(`component ${name}:`, e); return null; }
-    const el = document.createElement(`ui-${name.toLowerCase()}`);
+  async function block(name, props = {}) {  // a ready element, or null if the block is missing/broken
+    try { if (!(await load(name))) return null; } catch (e) { console.warn(`block ${name}:`, e); return null; }
+    const el = document.createElement(`block-${name.toLowerCase()}`);
     el.update(props, { children: [], mount() {}, set() {}, action() {} });
     return el;
   }
   // After an agent saves a version (end of its turn), show what it changed without a manual refresh:
-  // an App's files -> reload that App's frame; this page, a browser.js or a component in use -> reload the page
-  // (the browser can't redefine a custom element). New components need nothing: they load on first use.
+  // an app's files -> reload that app's frame; this page, a browser.js or a block in use -> reload the page
+  // (the browser can't redefine a custom element). New blocks need nothing: they load on first use.
   async function refreshAfter(files) {
     if (!(await fetchCatalog())) return reloadWhenUp();  // can't tell what changed: reload once the agent answers
     for (const [n, p] of Object.entries(loading)) p.then((ok) => { if (!ok) delete loading[n]; });  // maybe created now
     const changed = Object.keys(loaded).filter((n) => catalog[n] !== loaded[n]);
-    if (changed.length || files.some((f) => f === "extensions/page/page.html" || f.endsWith("/browser.js"))) return location.reload();
-    const apps = files.filter((f) => f.startsWith("ui/apps/")).map((f) => `/ui/apps/${f.split("/")[2]}/`);
+    if (changed.length || files.some((f) => f === "agent/extensions/page/page.html" || f.endsWith("/browser.js"))) return location.reload();
+    const apps = files.filter((f) => f.startsWith("built/apps/")).map((f) => `/built/apps/${f.split("/")[2]}/`);
     for (const frame of document.querySelectorAll("iframe"))
       if (apps.some((a) => new URL(frame.src, location.href).pathname.startsWith(a))) frame.contentWindow.location.reload();
   }
 
-  // ---- Messages: blocks of consecutive messages from one speaker (an agent, or "you"). A block has a
+  // ---- Messages: groups of consecutive messages from one speaker (an agent, or "you"). A group has a
   // header (robot in the agent's colour, name, time), then words as text and other work as rows of icons.
   let ts = null;  // time of the event being shown (set per event)
   let unread = 0;  // replies that arrived while the messages panel was closed
@@ -300,11 +325,11 @@
     if (atBottom) log.scrollTop = log.scrollHeight;
   }
 
-  function block(who) {
+  function group(who) {
     const last = log.lastElementChild;
     if (last?.dataset.who === who) return last;
     const b = document.createElement("div");
-    b.className = "block";
+    b.className = "group";
     b.dataset.who = who;
     if (who !== "you") b.style.setProperty("--c", colour(who));
     b.innerHTML = `<div class="who">${icon(who === "you" ? "person" : "robot")}<span></span><time></time></div>`;
@@ -318,18 +343,19 @@
     const div = document.createElement("div");
     div.className = "text";
     if (toWhom) div.append(Object.assign(document.createElement("span"), { className: "to", textContent: `→ ${toWhom}` }));
-    const span = document.createElement("span");  // plain at once; swapped for the Markdown component when ready
+    const span = document.createElement("span");  // plain at once; swapped for the Markdown block when ready
     span.textContent = words;
     div.append(span);
-    follow(() => block(who).append(div));
-    component("Markdown", { text: words }).then((el) => el && follow(() => span.replaceWith(el)));
+    follow(() => group(who).append(div));
+    block("Markdown", { text: words }).then((el) => el && follow(() => span.replaceWith(el)));
     if (who !== "you" && document.body.dataset.panel !== "messages")
       document.getElementById("unread").textContent = ++unread;
+    return div;
   }
 
   function step(agent, kind, title, content, error = false) {  // one icon in the agent's row; click to read it
     follow(() => {
-      const b = block(agent);
+      const b = group(agent);
       let row = b.lastElementChild;
       if (row.classList.contains("detail")) row = row.previousElementSibling;  // the row whose step is open
       if (!row.classList.contains("steps")) b.append((row = Object.assign(document.createElement("div"), { className: "steps" })));
@@ -351,8 +377,10 @@
     });
   }
 
-  function note(words) {  // a quiet line: joined, saved a version, errors, ...
-    follow(() => log.append(Object.assign(document.createElement("div"), { className: "note", textContent: words })));
+  function note(words) {  // a quiet line: joined, saved a version, errors, ... (returns it, for a plugin to act on)
+    const line = Object.assign(document.createElement("div"), { className: "note", textContent: words });
+    follow(() => log.append(line));
+    return line;
   }
 
   // ---- Working: animated dots for each agent that isn't idle (from "status" events), Stop beside them
@@ -391,11 +419,36 @@
     send: (obj) => ws.send(JSON.stringify(obj)),          // arrives at the extensions' page handlers
     slot: (id) => document.getElementById(id),  // "top": the main space; "status": the tool palette (top); "side": right edge
     note,       // note(text): a quiet line in the messages
-    load,       // load(name): define component <ui-name>; resolves false if there is no such component
-    component,  // component(name, props): a ready element, or null
+    load,       // load(name): define block <block-name>; resolves false if there is no such block
+    block,      // block(name, props): a ready element, or null
     command: (name, fn, description = "") => { commands[name] = { fn, description }; },
     provide: (name, obj) => { offered[name] = obj; for (const ok of wanted[name] || []) ok(obj); delete wanted[name]; },
     use: (name) => name in offered ? Promise.resolve(offered[name]) : new Promise((ok) => (wanted[name] ??= []).push(ok)),
+    notice: (content, onClose) => {  // a notice at the top right, newest on top; ✕ calls onClose, then it goes
+      const item = Object.assign(document.createElement("div"), { className: "notice out" });
+      const inner = document.createElement("div"), box = Object.assign(document.createElement("div"), { className: "notice-box" });
+      const x = Object.assign(document.createElement("button"), { className: "notice-x", textContent: "✕", title: "Close" });
+      let open = true;
+      const handle = {
+        el: box,
+        set: (...nodes) => box.replaceChildren(...nodes, x),  // new content, no new animation
+        close: () => {
+          if (!open) return;
+          open = false;
+          item.classList.add("out");
+          setTimeout(() => item.remove(), 360);
+        },
+        get open() { return open; },
+      };
+      x.onclick = () => { onClose?.(); handle.close(); };
+      handle.set(...[content].flat());
+      inner.append(box);
+      item.append(inner);
+      document.getElementById("notices").prepend(item);
+      item.offsetHeight;  // laid out closed first, so opening animates
+      item.classList.remove("out");
+      return handle;
+    },
     tool: (button) => {  // puts button in the palette with a row under it; returns the row, for its sub-tools
       const sub = Object.assign(document.createElement("div"), { className: "sub" });
       const wrap = Object.assign(document.createElement("span"), { className: "tool" });
@@ -409,7 +462,7 @@
   });
 
   const lastFrom = {};  // agent -> who its current turn's answer goes to
-  const asked = {};     // ask_agent / tell tool-call ids
+  const asked = {};     // team_ask / team_tell tool-call ids
 
   ws.onmessage = (e) => {
     const ev = JSON.parse(e.data);
@@ -433,11 +486,11 @@
         const m = /^\[(\w+) from ([^\s\]]+)[^\]]*\][^\n]*\n?/.exec(content);
         const from = m ? m[2] : "user", words = m ? content.slice(m[0].length) : content;
         if (ev.reply_to) lastFrom[a] = ev.reply_to;  // set on the message that starts a turn
-        // a message the page wrote for the user ("[note on the UI] <their words>" + lines for the agent):
+        // a message the page wrote for the user ("[note on the page] <their words>" + lines for the agent):
         // show their words; the lines meant for the agent go behind an icon
         const tagged = from === "user" && /^\[([^\]]+)\] ?(.*)/.exec(words);
         if (tagged) {
-          text("you", tagged[2] || tagged[1], agents.size > 1 ? a : null);
+          text("you", tagged[2] || tagged[1], agents.size > 1 ? a : null).dataset.raw = words;  // all of it, for plugins (doodle: its group)
           if (words.includes("\n")) step("you", "inbox", `${tagged[1]}: what ${a} got`, words);
         } else if (from === "user") text("you", words, agents.size > 1 ? a : null);
         // from another agent: already shown as its "asks"/"tells" step, or as its answer
@@ -454,12 +507,12 @@
         for (const c of ev.tool_calls || []) {
           let args = {};
           try { args = JSON.parse(c.function.arguments); } catch {}
-          if (c.function.name === "ask_agent") { asked[c.id] = true; step(a, "ask", `${a} asks ${args.to}`, args.text || ""); }
-          else if (c.function.name === "tell") { asked[c.id] = true; step(a, "ask", `${a} tells ${args.to}`, args.text || ""); }
+          if (c.function.name === "team_ask") { asked[c.id] = true; step(a, "ask", `${a} asks ${args.to}`, args.text || ""); }
+          else if (c.function.name === "team_tell") { asked[c.id] = true; step(a, "ask", `${a} tells ${args.to}`, args.text || ""); }
           else step(a, "tool", `${a} → ${c.function.name}`, c.function.arguments);
         }
       }
-      // an ask_agent result is the other agent's answer, already shown as its reply; a tell result is
+      // a team_ask result is the other agent's answer, already shown as its reply; a team_tell result is
       // just "sent" (errors still shown)
       // a result may be a list of parts (view_image): text, and [image <path>] for an image
       const res = typeof ev.content === "string" ? ev.content
@@ -562,7 +615,7 @@
   };
 
   async function loadVersions() {
-    try { versions = await (await fetch("/versions")).json(); } catch { return; }  // no versions plugin
+    try { versions = await (await fetch("/version")).json(); } catch { return; }  // no versions plugin
     sel = Math.max(0, versions.findIndex((v) => v.current));
     renderWheel();
   }
@@ -587,7 +640,7 @@
     detail.textContent = `${v.short} · ${v.author} · ${new Date(v.date).toLocaleString()}` + (v.current ? " · current" : "");
     rollbackBtn.disabled = v.current;
     preview.hidden = !v.shot;  // a version made while no page was open has no picture
-    if (v.shot) preview.src = `/versions/${v.sha}/shot`;
+    if (v.shot) preview.src = `/version/${v.sha}/shot`;
   }
 
   function select(i) {
@@ -602,7 +655,7 @@
     if (!confirm(`Roll back to "${v.message}" (${v.short})?\n\nThe agent restarts and busy agents are interrupted. ` +
                  `Later changes stay in the history, so you can roll forward again.`)) return;
     note(`rolling back to ${v.short}…`);
-    await fetch(`/versions/${v.sha}/rollback`, { method: "POST" });
+    await fetch(`/version/${v.sha}/rollback`, { method: "POST" });
   };
 
   openPanel(SHOT ? "" : document.body.dataset.panel);

package/agent/extensions/page/skills/interact-with-page/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interact-with-page
+description: Use the page the user has open the way they would, while they watch - read what's on screen, click, type, press keys, drag - in any card, app or part of the page. Use to check what the user sees, show them something, fill something in for them, reproduce what they pointed at, or try something you built.
+---
+# Using the user's page
+
+The page_run tool (load it: tool_search "page_run") runs JavaScript in the page the user has open, as it is right
+now. With card=<id> it runs inside that card's app: `document` is the app's page. The code is the body of an async
+function: `await` works, and you `return` what you want back.
+
+## Act with the helpers
+They act as a person would: your pointer moves to the thing first, what you touch gets an outline with your name,
+and typing goes letter by letter, so the user can follow.
+- `await click(t)`
+- `await type(t, text)`: replaces what the field holds (`{add: true}` adds to it). A dropdown picks the option with
+  that text; a slider, date or colour field is set to that value.
+- `await press(key, t?)`: Enter, Escape, Tab, ArrowDown, "Ctrl+z"... to t, else to what has focus. Enter in a form
+  field submits the form.
+- `await drag(t, dx, dy)` by pixels, or `await drag(t, other)` onto another thing. A draggable thing (a file row)
+  is dragged and dropped as the browser does it, so drop targets get it.
+- `read(t?)`: what's on screen as short lines: headings, controls with their value and state ([selected],
+  [checked], [disabled]), short texts. Only what's in view; `read(null, {all: true})` for the whole page. The
+  conversation (the chat log) is left out: you know it; `read("#log")` if you need it.
+- `await wait(ms)`, `await wait(".row.new")` (until it appears), `await wait(() => condition)`.
+
+t is an element, a CSS selector, or the visible text: a button's words, a field's placeholder or label. Or a spot
+`{x: 600, y: 300}` in window px (screen_see's picture, or an element's getBoundingClientRect()): whatever is on top
+there gets it, as with a real mouse. Use a spot for empty space (`await drag({x: 400, y: 300}, 300, 200)` draws a
+frame there) and for tools that work through a layer over the page (Point: click the tool, then the spot).
+```
+page_run(card="habit-tracker", code=`await type("New habit", "Drink water");
+  await click("Add habit");
+  return read()`)
+```
+Plain DOM code is fine for reading and checking precisely: `getComputedStyle(el)`, `el.scrollWidth > el.clientWidth`
+(text cut off), state the app exposes. For acting, use the helpers: a bare `el.click()` happens at once, and the user
+only sees an outline afterwards.
+
+## Look after each step, cheaply
+One step, or a few, per page_run, ending with a small read: `return read()` or the one value you need. You see what
+happened before you decide the next step. A read is about a hundred tokens; a picture (screen_see) is over a thousand
+and stays in your conversation, so look at a picture when the look matters (layout, colours, clipped or overlapping
+things), not after every step. From bash the same is `curl -X POST --data '{"code": "...", "card": "<id>"}' {page}/page/run`,
+for a loop or a script.
+
+## The user is watching, and can take over
+While you use the page a bar says so, with a Stop button. If the user clicks or types on the page, page_run answers
+"the user took over": stop there, don't retry, and say in a sentence what you were doing. When they press
+"Let <you> continue" you get a message: read the page again first, it may have changed.
+
+## Care
+- It's the live page: clicks really happen and data really changes. Touch only what your task needs, and don't send
+  messages through the chat box.
+- The page's Stop button and rollbacks refuse code: they are the user's.
+- Events from code are not quite real input: hover styles, native dropdown lists, file pickers, and copy and paste
+  don't respond. For those, and for other window sizes, use the browser-check skill
+  (a separate headless browser).
+- Errors the page logs while your code runs come back with the answer: read them.
+- An answer marked "not on the board the user is looking at" ran on a card they can't see right now.

package/agent/extensions/prompt/index.ts

@@ -0,0 +1,38 @@
+// The prompt after SYSTEM.md (pi's documented way to replace its default prompt, plain text): one section per
+// extension, its guide.md, then <paths>. A guide.md is found by looking in each extension folder, as the page finds
+// browser.js, so an extension has nothing to register. Read again on every input (an edited guide shows at once).
+// In a guide: {agent} {built} {data} {workspace} {page} become the full paths and address, {name} and {role} this
+// agent's, and README.md the full path of that extension's README.md. pi adds the skills list and <cwd> itself.
+// READMEs and skills keep the placeholders as written (agents edit them; <paths> says what each one is).
+import fs from "node:fs";
+import path from "node:path";
+import { getDocsPath, getExamplesPath, getReadmePath, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+const EXTENSIONS = path.dirname(import.meta.dirname);
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", (event) => {
+    const name = pi.getSessionName() ?? "", page = `http://127.0.0.1:${host.port}`;
+    const values: Record<string, string> = { agent: host.agent, built: host.built, data: host.data, workspace: host.workspace,
+      page, name, role: host.agents.get(name)?.role ?? "" };
+    const sections = event.systemPromptOptions.sections;
+    for (const ext of fs.readdirSync(EXTENSIONS).sort()) {
+      const guide = path.join(EXTENSIONS, ext, "guide.md");
+      if (!fs.existsSync(guide)) continue;
+      sections[ext] = fs.readFileSync(guide, "utf8").replace(/\{(\w+)\}/g, (m, k) => values[k] ?? m)
+        .replaceAll("README.md", path.join(EXTENSIONS, ext, "README.md"));
+    }
+    sections.paths = [
+      `{agent} = ${host.agent}: you: your prompt, settings, extensions/ and skills/`,
+      `{built} = ${host.built}: what you make for the user: card.json (the cards), board.json (the boards), apps/<name>/ (the apps)`,
+      `  {agent} and {built} are versioned together: each turn that changes them is saved, and the user can roll both back.`,
+      `{data} = ${host.data}: what is kept while running (conversations, what users typed into cards and apps, notes; not versioned)`,
+      `{workspace} = ${host.workspace}: your working folder (<cwd>), for project work; drops/ in it holds the user's files`,
+      `{page} = ${page}: the user's page; a file in {built} is at {page}/built/<its path in {built}>`,
+      `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 → agent}/extensions/reload/index.ts

@@ -1,8 +1,8 @@
-// Self-edits take effect: the Python agent's restart plugin, the pi way. The tool only asks; when this agent's turn
+// Reload: an agent's edits to itself take effect. The tool only asks; when this agent's turn
 // has ended, the host calls pi's session.reload() (extensions, skills and prompt load again; the conversation stays).
 // Not pi's reload-runtime.ts example: its pi.sendUserMessage("/reload-runtime") reaches the model as text in 1.4.0
 // (expandPromptTemplates defaults to false), and the model kept calling the tool again.
-// No process restart, so no start.sh (a rollback: the versions plugin, which reloads every agent).
+// No process restart, so no start.sh (a rollback: the version extension, which reloads every agent).
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -13,7 +13,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_id, a) {
       const host = (globalThis as any).chalky, name = pi.getSessionName();
       host.reloadAfterTurn.set(name, false);  // not quiet: the page notes the reload
-      host.shared.set(`reload-reason ${name}`, a.reason);  // the versions plugin's commit message for this turn
+      host.shared.set(`reload-reason ${name}`, a.reason);  // the version extension's commit message for this turn
       return { content: [{ type: "text", text: "Reload scheduled for when your turn ends. End your turn now; don't call reload again." }],
                details: undefined };
     },

package/{app → agent}/extensions/screen/browser.js

@@ -1,23 +1,15 @@
-// Browser half of the screen extension (Python's screen.js, unchanged but for this header): this tab, shared once (getDisplayMedia), for every plugin that needs a picture
-// of what the user sees. Offered as page.provide("screen", {...}); a plugin gets it with await page.use("screen"):
+// The page side of the screen extension: this tab, shared once (getDisplayMedia), for every extension that needs a picture
+// of what the user sees. Offered as page.provide("screen", {...}); an extension gets it with await page.use("screen"):
 //   share()            ask the browser to share this tab (only works right after a click: transient activation);
 //                      resolves true if shared. The user can stop sharing any time (the browser's bar).
 //   shared()           whether the tab is shared now
 //   frame()            the screen right now, as a canvas (null when not shared)
 //   picture(full, box) crop a frame to box (window px {x, y, w, h}), upload it (POST /screen/shot): {path, url}
-// An agent can ask to see the screen (its tool see_user_screen, event screen_ask): if the tab is shared, a picture
-// of the whole window goes back at once; else a card asks "Share / No" first, since the agent's ask is no click
+// An agent can ask to see the screen (its tool screen_see, event screen_ask): if the tab is shared, a picture
+// of the whole window goes back at once; else a notice asks "Share" (✕: no) first, since the agent's ask is no click
 // (screen_reply {id, shot, window, main}).
 export default async function (page) {
   const area = page.slot("top");
-  const style = document.createElement("style");
-  style.textContent = `
-    .screen-ask { position: fixed; top: 76px; left: 50%; transform: translateX(-50%); z-index: 100; display: flex; align-items: center; gap: 10px;
-                  padding: 8px 8px 8px 14px; border-radius: 14px; background: var(--glass-strong, #fff); border: 1px solid var(--edge, #eee);
-                  box-shadow: 0 8px 30px rgba(0, 0, 0, .12); font-size: 13px; color: var(--text); }
-    .screen-ask button { border: 0; border-radius: 9px; padding: 5px 12px; font: inherit; cursor: pointer; background: var(--line, #eee); color: var(--text); }
-    .screen-ask button.yes { background: var(--accent, #0071e3); color: #fff; }`;
-  document.head.append(style);
 
   let stream = null, video = null;
   async function share() {
@@ -53,24 +45,19 @@ export default async function (page) {
   // ---- an agent asks to see the screen ----
   const asks = {};  // id -> its card, while the agent waits
   async function answer(id) {
-    for (const card of Object.values(asks)) card.remove();  // not in the picture
-    await new Promise((ok) => setTimeout(ok, 300));         // a fresh frame from the shared tab
+    for (const card of Object.values(asks)) card.close();   // not in the picture
+    await new Promise((ok) => setTimeout(ok, 400));         // it has slid away; a fresh frame from the shared tab
     const full = frame();
     const s = full && await picture(full, { x: 0, y: 0, w: innerWidth, h: innerHeight }).catch(() => null);
-    const m = area.getBoundingClientRect();  // window (0, 0) in main-space px (as point.js)
+    const m = area.getBoundingClientRect();  // window (0, 0) in main-space px (as note/browser.js)
     page.send({ type: "screen_reply", id, shot: s?.path || null, window: { width: innerWidth, height: innerHeight },
                 main: { x: area.scrollLeft - m.left, y: area.scrollTop - m.top } });
   }
   page.on("screen_ask", ({ id, agent }) => {
     if (shared()) return answer(id);
-    const card = Object.assign(document.createElement("div"), { className: "screen-ask" });
-    const yes = Object.assign(document.createElement("button"), { className: "yes", textContent: "Share" });
-    const no = Object.assign(document.createElement("button"), { textContent: "No" });
-    card.append(`${agent} wants to see your screen`, yes, no);
+    const yes = Object.assign(document.createElement("button"), { className: "go", textContent: "Share" });
     yes.onclick = async () => { await share(); answer(id); };
-    no.onclick = () => page.send({ type: "screen_reply", id, shot: null });
-    asks[id] = card;
-    document.body.append(card);
+    asks[id] = page.notice([`${agent} wants to see your screen`, yes], () => page.send({ type: "screen_reply", id, shot: null }));  // ✕: no
   });
-  page.on("screen_ask_done", ({ id }) => { asks[id]?.remove(); delete asks[id]; });  // answered (here or in another tab), or timed out
+  page.on("screen_ask_done", ({ id }) => { asks[id]?.close(); delete asks[id]; });  // answered (here or in another tab), or timed out
 }

package/{app → agent}/extensions/screen/index.ts

@@ -1,9 +1,9 @@
-// Screen: what the user sees, as pictures (port of the Python screen plugin; browser.js is its screen.js). The
+// Screen: what the user sees, as pictures. The
 // browser half shares the tab once (for every extension: doodle's steps, an agent's look) and uploads pictures
-// cropped from it. This half keeps them and gives agents the tool see_user_screen: the user's window as it is now
-// (their size, scroll, panels, running apps; ui-check's headless Chrome is a fresh window of its own).
-//   POST /screen/shot       a png (at most MAX_BYTES): saved in state/screens, {path} back
-//   event "screen_ask"      {id, agent} to every open page, when an agent calls see_user_screen
+// cropped from it. This half keeps them and gives agents the tool screen_see: the user's window as it is now
+// (their size, scroll, panels, running apps; browser-check's headless Chrome is a fresh window of its own).
+//   POST /screen/shot       a png (at most MAX_BYTES): saved in data/screen, {path} back
+//   event "screen_ask"      {id, agent} to every open page, when an agent calls screen_see
 //   page message            screen_reply {id, shot, window: {width, height}, main: {x, y}}: the first answers
 //                           (shot null: the user said no; main: window (0, 0) in main-space px)
 //   event "screen_ask_done" {id} to every page when answered or after ASK_WAIT s, so the asks go away
@@ -14,14 +14,14 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 const host = (globalThis as any).chalky;
-const SHOTS = path.join(host.state, "screens");  // outside app/: not code
+const SHOTS = path.join(host.data, "screen");
 const MAX_BYTES = 8 * 1024 * 1024;
 const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const ASK_WAIT = 90;  // s for the user to answer see_user_screen
+const ASK_WAIT = 90;  // s for the user to answer screen_see
 
 const isShot = (p: unknown) => typeof p === "string" && path.dirname(p) === SHOTS && fs.existsSync(p);
 host.api.screen = { isShot };
-// id -> resolve, while see_user_screen waits for a page (on the host: the tool is per agent, the page handler one)
+// id -> resolve, while screen_see waits for a page (on the host: the tool is per agent, the page handler one)
 const asks: Map<string, (msg: any) => void> = host.shared.get("screen-asks") ?? new Map();
 host.shared.set("screen-asks", asks);
 
@@ -50,9 +50,9 @@ const result = (text: string, png?: string) => ({ details: undefined, content: [
 
 export default function (pi: ExtensionAPI) {
   pi.registerTool({
-    name: "see_user_screen", label: "See the user's screen",
+    name: "screen_see", label: "Screen see", exposure: "deferred",
     description: "See the user's screen as they see it right now: a picture of their whole window (their size, scroll, "
-      + "open panels, apps as they are running). ui-check's headless Chrome is a fresh window of its own, not theirs: when "
+      + "open panels, apps as they are running). browser-check's headless Chrome is a fresh window of its own, not theirs: when "
       + "the user talks about what they see, or before you say something looks right to them, look here. The first "
       + "time, the user is asked to share the tab (they may say no); then it's instant.",
     parameters: Type.Object({}),
@@ -74,7 +74,7 @@ export default function (pi: ExtensionAPI) {
       const mx = Math.round(m.x ?? 0), my = Math.round(m.y ?? 0);
       return result(`the user's screen right now: their window is ${w.width}x${w.height} px; the picture is the whole window, `
         + `${pw}x${ph} px (${+k.toFixed(3)} picture px per window px). Window (0, 0) is main-space (${mx}, ${my}): a spot in `
-        + `the picture is main-space x = ${mx} + picture x / ${+k.toFixed(3)}, the same for y (what ui_render's place uses).`, reply.shot);
+        + `the picture is main-space x = ${mx} + picture x / ${+k.toFixed(3)}, the same for y (what card_show's place uses).`, reply.shot);
     },
   });
 }

package/{app/extensions/steps → agent/extensions/step}/index.ts

@@ -1,4 +1,4 @@
-// A limit on steps (model calls) per input, as the Python loop's MAX_STEPS: pi's loop has none, and a model that
+// Step: a limit on steps (model calls) per input: pi's loop has none, and a model that
 // keeps calling tools would run on (it did once: 55 rounds). At the limit the run is stopped and the agent says so.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";