@chalky/chalky 0.0.0-stage → 0.1.4

package/app/extensions/ui/skills/ui-check/scripts/check.mjs

@@ -0,0 +1,306 @@
+// Open a page in headless Chrome, act on it, and report what a user would hit. (Node port of check.py.)
+//
+// usage: node check.mjs URL [STEP ...] [--size 1280x800] [--shot out.png] [--full] [--fit SELECTOR]
+// steps, run in order after the page loads:
+//   wait:MS            wait MS milliseconds (the page gets 1500 ms after load before the first step)
+//   click:SELECTOR     click the centre of the first element matching the CSS selector
+//   drag:SELECTOR=DX,DY  press on its centre, move DX,DY px (in steps, button held), release
+//   altdrag:SELECTOR=DX,DY  the same with Alt (Option) held down
+//   hold:SELECTOR=MS   press on its centre, keep the button down MS milliseconds without moving, release
+//   dblclick:SELECTOR  double-click the centre of the first match
+//   type:SELECTOR=TEXT focus the element and type TEXT
+//   key:KEY            press a key: Enter, Escape, Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space, or a letter
+//   eval:JS            run a JavaScript expression; its value is printed (promises are awaited)
+//   shot:PATH          screenshot now (a page can be captured several times)
+//   dialog:accept      answer later confirm()/alert()/prompt() dialogs with OK (dialog:accept=TEXT types TEXT into a
+//                      prompt); dialog:dismiss answers Cancel. Default: dismiss, so a confirm on the live page doesn't act.
+// --fit SELECTOR: the --shot shows just the box around every element matching SELECTOR (even parts outside the
+// window), plus a margin, in the window's shape. Nothing matching: the plain shot.
+// Prints: errors (exceptions, console errors, failed requests), layout problems (clipped or overflowing
+// elements, cut-off text), step results, every dialog and how it was answered, screenshot paths. Exit code 1 if
+// a step failed or there were errors; layout problems alone don't count (some are meant: the agent judges them,
+// and pi shows an exit code 1 as a failed command); 2 if there is no browser (it prints the command that downloads one).
+// Talks to Chrome over the DevTools Protocol (CDP) with Node's own WebSocket and fetch; no libraries.
+// The browser: $CHROME, else chrome-headless-shell downloaded into BROWSERS, else an installed Chrome, Chromium or Edge.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const BROWSERS = process.env.CHALKY_BROWSERS || path.join(os.homedir(), ".cache", "chalky-browsers");
+const DOWNLOAD = `npx --yes @puppeteer/browsers@3.2.4 install chrome-headless-shell@155.0.8059.84 --path "${BROWSERS}"`;
+const SHELL = process.platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell";
+const INSTALLED = {
+  linux: ["/usr/local/bin/chrome-headless-shell", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium",
+    "/usr/bin/chromium-browser", "/snap/bin/chromium", "/usr/bin/microsoft-edge"],
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"],
+  win32: [`${process.env.PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`, `${process.env["PROGRAMFILES(X86)"]}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`, `${process.env["PROGRAMFILES(X86)"]}\\Microsoft\\Edge\\Application\\msedge.exe`],
+}[process.platform] ?? [];
+
+function findBrowser() {
+  if (process.env.CHROME) return process.env.CHROME;
+  const downloaded = fs.existsSync(BROWSERS) ? fs.readdirSync(BROWSERS, { recursive: true }).map(String)
+    .filter((p) => path.basename(p) === SHELL).map((p) => path.join(BROWSERS, p)).sort().at(-1) : undefined;
+  return downloaded ?? INSTALLED.find((p) => fs.existsSync(p));
+}
+
+const KEYS = { Enter: ["\r", 13], Escape: ["", 27], Tab: ["\t", 9], Space: [" ", 32], ArrowUp: ["", 38],
+  ArrowDown: ["", 40], ArrowLeft: ["", 37], ArrowRight: ["", 39], Backspace: ["", 8] };
+
+// Layout problems, found in the page itself. Inside scrollable boxes overflow is normal, so only boxes that
+// hide overflow (hidden/clip) count as clipping. Canvas drawings are pixels: check those on the screenshot.
+const LAYOUT = String.raw`(() => {
+  const name = el => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') +
+    (typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : '');
+  const shown = el => { const s = getComputedStyle(el), r = el.getBoundingClientRect();
+    return s.display !== 'none' && s.visibility !== 'hidden' && +s.opacity > 0 && r.width > 0 && r.height > 0; };
+  const out = [], W = innerWidth;
+  if (document.documentElement.scrollWidth > W + 1)
+    out.push('page scrolls sideways: content is ' + document.documentElement.scrollWidth + 'px wide, window ' + W + 'px');
+  for (const el of document.body.querySelectorAll('*')) {
+    if (['SCRIPT', 'STYLE', 'TEMPLATE'].includes(el.tagName) || !shown(el)) continue;
+    const r = el.getBoundingClientRect(), s = getComputedStyle(el);
+    const leaf = !el.children.length || ['CANVAS', 'IMG', 'SVG', 'svg', 'BUTTON', 'INPUT', 'TEXTAREA', 'SELECT'].includes(el.tagName);
+    if (leaf && (r.right > W + 1 || r.left < -1)) out.push(name(el) + ' sticks out of the window (x ' + Math.round(r.left) + '..' + Math.round(r.right) + ', window 0..' + W + ')');
+    if (leaf) for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+      const o = getComputedStyle(a); if (!/hidden|clip/.test(o.overflow + o.overflowX + o.overflowY)) continue;
+      const b = a.getBoundingClientRect();
+      if (r.left < b.left - 1 || r.right > b.right + 1 || r.top < b.top - 1 || r.bottom > b.bottom + 1)
+        out.push(name(el) + ' is cut off by ' + name(a) + ' (element ' + Math.round(r.width) + 'x' + Math.round(r.height) + ' at ' + Math.round(r.left) + ',' + Math.round(r.top)
+          + '; box ' + Math.round(b.width) + 'x' + Math.round(b.height) + ' at ' + Math.round(b.left) + ',' + Math.round(b.top) + ')');
+      break;
+    }
+    if (el.children.length === 0 && el.textContent.trim() && /hidden|clip/.test(s.overflow + s.overflowX) && el.scrollWidth > el.clientWidth + 1)
+      out.push(name(el) + ' text is cut off: "' + el.textContent.trim().slice(0, 40) + '"');
+  }
+  const box = el => { const r = el.getBoundingClientRect(); return Math.round(r.width) + 'x' + Math.round(r.height); };
+  const big = [...document.body.children].filter(shown).map(el => name(el) + ' ' + box(el)).join(', ');
+  return {title: document.title, window: W + 'x' + innerHeight, top_level: big, problems: [...new Set(out)].slice(0, 40)};
+})()`;
+
+// The box around all matches, in page coordinates (scrolling included): 32px margin, at least half the window,
+// widened or heightened to the window's shape and kept centred on the matches (not past the page's top or left).
+const FIT = `((sel, W, H) => {  // W x H: the window as asked for (it may be enlarged before the second measure)
+  const rs = [...document.querySelectorAll(sel)].map(e => e.getBoundingClientRect()).filter(r => r.width && r.height);
+  if (!rs.length) return null;
+  const m = 32, ratio = W / H;
+  const x0 = Math.min(...rs.map(r => r.left)) + scrollX - m, x1 = Math.max(...rs.map(r => r.right)) + scrollX + m;
+  const y0 = Math.min(...rs.map(r => r.top)) + scrollY - m, y1 = Math.max(...rs.map(r => r.bottom)) + scrollY + m;
+  let w = Math.max(x1 - x0, W / 2), h = Math.max(y1 - y0, H / 2);
+  if (w / h < ratio) w = h * ratio; else h = w / ratio;
+  return { x: Math.max(0, (x0 + x1 - w) / 2), y: Math.max(0, (y0 + y1 - h) / 2), width: w, height: h, scale: 1 };
+})`;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+class Page {
+  constructor(ws) {
+    this.ws = ws; this.n = 0; this.pending = new Map(); this.events = [];
+    this.dialog = [false, ""];  // how to answer dialogs: [accept, prompt text]; dismiss by default
+    ws.addEventListener("message", (m) => {
+      const msg = JSON.parse(m.data);
+      if (msg.id && this.pending.has(msg.id)) { this.pending.get(msg.id)(msg); this.pending.delete(msg.id); }
+      else if (msg.method) {
+        this.events.push(msg);
+        if (msg.method === "Page.javascriptDialogOpening") this.answer(msg.params);  // the page is blocked until answered
+      }
+    });
+  }
+  async answer(dialog) {
+    const [accept, text] = this.dialog;
+    await this.call("Page.handleJavaScriptDialog", { accept, promptText: text });
+    console.log(`dialog ${dialog.type} "${dialog.message.slice(0, 100)}" -> ${accept ? "accepted" : "dismissed"}`
+      + (accept && dialog.type === "prompt" ? ` with ${JSON.stringify(text)}` : ""));
+  }
+  call(method, params = {}) {
+    const id = ++this.n;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`${method}: no answer in 30 s`)); }, 30000);
+      this.pending.set(id, (msg) => { clearTimeout(timer); msg.error ? reject(new Error(`${method}: ${msg.error.message}`)) : resolve(msg.result); });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+  async js(expression) {
+    const r = await this.call("Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true });
+    if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description ?? r.exceptionDetails.text);
+    return r.result.value;
+  }
+}
+
+async function shot(page, file, full, fit) {
+  const [w, h] = await page.js("[innerWidth, innerHeight]");
+  let clip = fit && await page.js(`${FIT}(${JSON.stringify(fit)}, ${w}, ${h})`);
+  let r;
+  if (clip) {  // parts outside the window aren't drawn if the page scrolls inside an element: make the window reach
+    if (clip.x + clip.width > w || clip.y + clip.height > h) {
+      await page.call("Emulation.setDeviceMetricsOverride", { width: Math.floor(Math.max(w, clip.x + clip.width) + 1),
+        height: Math.floor(Math.max(h, clip.y + clip.height) + 1), deviceScaleFactor: 1, mobile: false });
+      await sleep(500);  // relayout, and apps that redraw on resize
+      clip = (await page.js(`${FIT}(${JSON.stringify(fit)}, ${w}, ${h})`)) ?? clip;
+    }
+    r = await page.call("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, clip });
+  } else r = await page.call("Page.captureScreenshot", { format: "png", captureBeyondViewport: full });
+  fs.writeFileSync(file, Buffer.from(r.data, "base64"));
+  return `screenshot: ${path.resolve(file)}`;
+}
+
+async function centre(page, sel) {  // the centre of the first match, scrolled into view
+  const box = await page.js(`(() => { const el = document.querySelector(${JSON.stringify(sel)});
+    if (!el) return null; el.scrollIntoView({block: 'center'}); const r = el.getBoundingClientRect();
+    return {x: r.left + r.width / 2, y: r.top + r.height / 2}; })()`);
+  if (!box) throw new Error(`no element matches ${sel}`);
+  return box;
+}
+
+const split = (s, sep, last = false) => {  // [before, after] at the first (or last) sep; [s, ""] if none
+  const i = last ? s.lastIndexOf(sep) : s.indexOf(sep);
+  return i < 0 ? (last ? ["", s] : [s, ""]) : [s.slice(0, i), s.slice(i + sep.length)];
+};
+const mouse = (page, type, x, y, extra = {}) => page.call("Input.dispatchMouseEvent", { type, x, y, ...extra });
+
+async function step(page, s, full) {
+  const [kind, arg] = split(s, ":");
+  if (kind === "wait") { await sleep(Number(arg)); return `waited ${arg} ms`; }
+  if (kind === "drag" || kind === "altdrag") {
+    const [sel, by] = split(arg, "=", true);  // the last "=": selectors may contain one ([data-x=y])
+    const [dx, dy] = by.split(",").map(Number);
+    const { x, y } = await centre(page, sel), modifiers = kind === "altdrag" ? 1 : 0;  // CDP modifiers: 1 = Alt
+    await mouse(page, "mouseMoved", x, y, { modifiers });
+    await mouse(page, "mousePressed", x, y, { button: "left", clickCount: 1, modifiers });
+    for (let i = 1; i <= 10; i++) {
+      await mouse(page, "mouseMoved", x + dx * i / 10, y + dy * i / 10, { button: "left", buttons: 1, modifiers });
+      await sleep(30);
+    }
+    await mouse(page, "mouseReleased", x + dx, y + dy, { button: "left", clickCount: 1, modifiers });
+    await sleep(300);
+    return `${modifiers ? "alt-" : ""}dragged ${sel} by ${dx},${dy}`;
+  }
+  if (kind === "hold") {
+    const [sel, ms] = split(arg, "=", true);
+    const { x, y } = await centre(page, sel);
+    await mouse(page, "mouseMoved", x, y);
+    await mouse(page, "mousePressed", x, y, { button: "left", clickCount: 1 });
+    await sleep(Number(ms));
+    await mouse(page, "mouseReleased", x, y, { button: "left", clickCount: 1 });
+    await sleep(300);
+    return `held ${sel} for ${ms} ms`;
+  }
+  if (kind === "dblclick") {
+    const { x, y } = await centre(page, arg);
+    for (const clickCount of [1, 2]) for (const t of ["mousePressed", "mouseReleased"]) await mouse(page, t, x, y, { button: "left", clickCount });
+    await sleep(300);
+    return `double-clicked ${arg}`;
+  }
+  if (kind === "click") {
+    const { x, y } = await centre(page, arg);
+    for (const t of ["mousePressed", "mouseReleased"]) await mouse(page, t, x, y, { button: "left", clickCount: 1 });
+    await sleep(300);
+    return `clicked ${arg}`;
+  }
+  if (kind === "type") {
+    const [sel, text] = split(arg, "=");
+    if (!await page.js(`(() => { const el = document.querySelector(${JSON.stringify(sel)}); if (el) el.focus(); return !!el; })()`))
+      throw new Error(`no element matches ${sel}`);
+    await page.call("Input.insertText", { text });
+    return `typed into ${sel}`;
+  }
+  if (kind === "key") {
+    const [text, code] = KEYS[arg] ?? [arg, arg.length === 1 ? arg.toUpperCase().charCodeAt(0) : 0];
+    await page.call("Input.dispatchKeyEvent", { type: "keyDown", key: arg, text, windowsVirtualKeyCode: code });
+    await page.call("Input.dispatchKeyEvent", { type: "keyUp", key: arg, windowsVirtualKeyCode: code });
+    await sleep(200);
+    return `pressed ${arg}`;
+  }
+  if (kind === "eval") return `eval ${arg.slice(0, 60)} -> ${String(JSON.stringify(await page.js(arg))).slice(0, 2000)}`;
+  if (kind === "shot") return shot(page, arg, full);
+  if (kind === "dialog") {
+    const [answer, text] = split(arg, "=");
+    if (!["accept", "dismiss"].includes(answer)) throw new Error("dialog:accept, dialog:accept=TEXT or dialog:dismiss");
+    page.dialog = [answer === "accept", text];
+    return `dialogs from now on: ${answer}` + (text ? ` with ${JSON.stringify(text)}` : "");
+  }
+  throw new Error(`unknown step ${JSON.stringify(s)} (wait, click, drag, altdrag, hold, dblclick, type, key, eval, shot, dialog)`);
+}
+
+function problems(events) {  // errors from the events Chrome sent: uncaught exceptions, console errors, failed requests
+  const out = [];
+  for (const { method: m, params: p } of events) {
+    if (m === "Runtime.exceptionThrown") {
+      const d = p.exceptionDetails;
+      out.push(`exception: ${d.exception?.description ?? d.text}`.split("\n    at ")[0]);
+    } else if (m === "Runtime.consoleAPICalled" && ["error", "assert"].includes(p.type))
+      out.push(("console.error: " + p.args.map((a) => String(a.value ?? a.description ?? "")).join(" ")).slice(0, 300));
+    else if (m === "Log.entryAdded" && p.entry.level === "error") out.push(`browser: ${p.entry.text.slice(0, 300)} ${p.entry.url ?? ""}`.trim());
+    else if (m === "Network.responseReceived" && p.response.status >= 400) out.push(`HTTP ${p.response.status}: ${p.response.url}`);
+    else if (m === "Network.loadingFailed" && !p.canceled) out.push(`request failed: ${p.errorText} (request ${p.requestId})`);
+  }
+  return [...new Set(out)];
+}
+
+async function main(url, steps, size, shotPath, full, fit) {
+  const chromePath = findBrowser();
+  if (!chromePath) {
+    console.log(`no headless browser found (looked at $CHROME, ${BROWSERS}, and the usual Chrome, Chromium and Edge places).\n`
+      + `Download one (about 270 MB on disk, once), then run this again:\n  ${DOWNLOAD}`);
+    return 2;
+  }
+  const [w, h] = size.split("x").map(Number);
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), "ui-check-"));
+  const headless = path.basename(chromePath).startsWith("chrome-headless-shell") ? [] : ["--headless"];  // a full browser: no window
+  const chrome = spawn(chromePath, [...headless, "--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu", "--no-first-run",
+    `--user-data-dir=${profile}`, "--remote-debugging-port=0", "about:blank"], { stdio: "ignore" });
+  let failed = false, page, layout;
+  try {
+    const portFile = path.join(profile, "DevToolsActivePort");
+    for (let i = 0; i < 100 && !(fs.existsSync(portFile) && fs.readFileSync(portFile, "utf8").trim()); i++) await sleep(100);  // written once ready
+    const port = fs.readFileSync(portFile, "utf8").split("\n")[0];
+    const target = await (await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: "PUT" })).json();
+    const ws = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => { ws.onopen = resolve; ws.onerror = () => reject(new Error("could not connect to the browser")); });
+    page = new Page(ws);
+    for (const domain of ["Page", "Runtime", "Log", "Network"]) await page.call(`${domain}.enable`);
+    await page.call("Emulation.setDeviceMetricsOverride", { width: w, height: h, deviceScaleFactor: 1, mobile: false });
+    await page.call("Page.navigate", { url });
+    let loaded = false;
+    for (let i = 0; i < 150 && !(loaded = page.events.some((e) => e.method === "Page.loadEventFired")); i++) await sleep(100);  // up to 15 s
+    if (!loaded) { console.log("problem: the page did not finish loading in 15 s"); failed = true; }
+    await sleep(1500);  // scripts, sockets and first renders
+    console.log(`opened ${url} at ${size}`);
+    for (const st of steps) {
+      try { console.log(await step(page, st, full)); } catch (e) { console.log(`step failed: ${st}: ${e.message}`); failed = true; }
+    }
+    layout = await page.js(LAYOUT);
+    if (shotPath) console.log(await shot(page, shotPath, full, fit));
+    ws.close();
+    const errors = problems(page.events);
+    console.log(`title: ${JSON.stringify(layout.title)}, window ${layout.window}; top-level elements: ${layout.top_level}`);
+    console.log(`errors (${errors.length}):` + errors.map((e) => `\n  - ${e}`).join(""));
+    console.log(`layout problems (${layout.problems.length}):` + layout.problems.map((p) => `\n  - ${p}`).join(""));
+    failed = failed || errors.length > 0;  // layout problems: printed, for the agent to judge
+  } finally {
+    chrome.kill();
+    await new Promise((r) => chrome.exitCode !== null ? r() : chrome.on("exit", r));
+    fs.rmSync(profile, { recursive: true, force: true });
+  }
+  return failed ? 1 : 0;
+}
+
+const args = process.argv.slice(2);
+if (!args.length || ["-h", "--help"].includes(args[0])) {
+  console.log(fs.readFileSync(new URL(import.meta.url), "utf8").split("\nimport ")[0].replace(/^\/\/ ?/gm, ""));
+  process.exit(0);
+}
+const steps = [];
+let size = "1280x800", shotPath = null, full = false, fit = null;
+const rest = args.slice(1);
+while (rest.length) {
+  const a = rest.shift();
+  if (a === "--size") size = rest.shift();
+  else if (a === "--shot") shotPath = rest.shift();
+  else if (a === "--full") full = true;
+  else if (a === "--fit") fit = rest.shift();
+  else steps.push(a);
+}
+process.exit(await main(args[0], steps, size, shotPath, full, fit));

package/app/extensions/ui/skills/ui-design/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ui-design
+description: How to make what you build for the user look good and read clearly - surfaces, components, apps, charts and diagrams. Use before building or restyling anything the user will see in the main space.
+---
+# Designing what the user sees
+
+What you build fills the user's screen, and the user then points at it and marks it up.
+So it must look like it belongs on the page, and each piece must be a clear thing to point at.
+Precedence: the user's own words, then the page's existing look, then your choices.
+
+## 1. Fit the page
+The page is light, glassy and quiet (Apple-like): soft gradient background, translucent white glass,
+thin edges, system font. Match it unless the user asks for another look.
+- Use the page's tokens instead of literal colours (they are defined on the page and reach components;
+  apps in a frame copy the values they need):
+  `--text #1d1d1f`, `--soft rgba(29,29,31,.72)`, `--muted rgba(60,60,67,.55)`, `--accent #0071e3`,
+  `--danger #e5484d`, `--line rgba(0,0,0,.06)`, `--glass rgba(255,255,255,.45)`,
+  `--glass-strong rgba(255,255,255,.7)`, `--edge rgba(255,255,255,.75)`, `--radius 16px`.
+- The built-in components (Card, Button, Table, Text, TextField, Markdown) already use these tokens;
+  prefer them, and style your own components the same way.
+- Font: inherit the page's system font. Use a Google Font only when the subject calls for it
+  (a pixel-art game, a poster), and always give a fallback stack.
+- Show just the thing: no frame, card or background around it unless it needs one. Transparent app backgrounds.
+- A user-requested look (pixel art, neon, paper) wins. Commit to it fully inside that surface,
+  and keep the rest of the page as it is.
+
+## 2. Ground it in the subject
+- Pick one concrete job for each surface. Use real content, never lorem ipsum.
+- Take at least one detail from the subject's own world: its real units, terms, conventions
+  (a chess clock shows mm:ss; a kanban card has an owner and a state).
+- Structure must mean something: number things only when order matters; a divider only between real groups.
+
+## 3. Lay it out
+- Group siblings with flex or grid and `gap`, not per-element margins.
+- Make repeated things consistent: same padding, edges and baselines on every card in a row;
+  a recurring element sits in the same place on each.
+- Let content set the height. Text that can outgrow its box wraps or scrolls inside it; clipped text is a bug.
+- `font-variant-numeric: tabular-nums` wherever digits line up.
+- Borders, fills, radius and shadow mark something as a separate object. Use them on the one
+  element that needs it, not on every block.
+- Keep it complete at rest: visible when it loads, never left at `opacity: 0` waiting for an animation.
+- A tool opens in a working state: sample rows or a loaded example (marked as such), not an empty shell.
+
+## 4. Type and words
+- One type scale; keep to it. Running text near 65 characters wide. Headings `text-wrap: balance`.
+- Small uppercase labels get a little letter-spacing.
+- Name things by what the user recognises, not how it's built. Buttons say exactly what happens
+  ("Start round", then "Round 2 started"). Errors say what went wrong and how to fix it. Short, plain sentences.
+
+## 5. Avoid the generic AI look (unless the user asks for it)
+Cream background with a serif and terracotta accent; near-black with one acid-green pop;
+purple-to-blue gradient heroes; emoji as section markers; everything centred; the same rounded
+shadowed card on everything; a coloured accent bar down the side of cards.
+
+## 6. Dashboards and tools
+They are scanned and operated, not read top to bottom.
+- Summary before detail. Show state in form as well as numbers (a pill, a chip, a stripe),
+  so what needs attention is visible at a glance.
+- Status colours (good / warning / critical) are separate from the accent, and always come with
+  an icon or a word, never colour alone.
+- Interactive things look interactive; keyboard focus is visible.
+
+## 7. Charts
+Pick the form first, colour last.
+- The data's job picks the chart: magnitude (bar), change over time (line), share (stacked bar),
+  one headline number (a stat, not a chart). Sometimes the answer is a sentence or a table.
+- Colour by job: identity = distinct hues in a fixed order (never cycled, and a hue follows its
+  entity even when filters change); magnitude = one hue light to dark; polarity = two hues with a grey middle.
+  Never a rainbow. More than about 8 series: fold into "Other" or split into small charts.
+- One y-axis. Never two scales on one chart; use two charts instead.
+- Thin marks: 2px lines, bars with a 2px gap, markers at least 8px. Faint grid, quiet axes.
+- Place marks, ticks and labels with one scale; every tick names a value the chart reaches.
+- Two or more series: a legend, plus direct labels when there are 4 or fewer. Label a few points, not every one.
+- Text uses text colours (`--text`, `--muted`), never the series colour.
+- Add hover: a tooltip per bar/dot, a crosshair on lines. Hit targets bigger than the mark.
+
+## 8. Diagrams
+Draw only when a picture shows a mechanism faster than a sentence: what flows where, which parts
+talk, what changes between two options.
+- Draw the mechanism, not its name: the path a request takes, the boundary crossed, the edge that appears or disappears.
+- Comparing options: draw the difference side by side, so the user can point at what they are choosing between.
+- Label every arrow (`writes`, `polls every 30s`). Short labels (1-3 words); sentences go in a caption.
+- Inline `<svg viewBox="0 0 W H">` scaled by CSS (`max-width:100%; height:auto`). Strokes and text in
+  `currentColor`; one literal hue only for the element that carries the point. Arrowheads via `<marker>`.
+  Text about 11-13px. Align to a grid with even gaps. Give every shape an explicit fill.
+- Wrap in `<figure>` with a `<figcaption>` that states the claim.
+
+## 9. Make it easy to reshape
+The user changes what you build by hand (pins, levers on the back side, combining, undo), so build for that.
+- One clear thing per surface, with a name the user would say (`lunch-orders`, not `surface3`).
+- Write `about`: what it is for and any decision a later change should respect ("drinks are not counted").
+- Put what changes in data (rows, scores, settings) and the look in components: data changes are instant
+  for the user and never need you.
+- Read other surfaces' data with `{"ref": "<surface>", "path": "/..."}` instead of copying it, so it stays live.
+- A component you write: its about block lists every prop with a type, and `levers` for the few a user
+  would want to change (a size, a mode, a label), written as plain sentences.
+
+## 10. One look
+What the user builds over time should look like one hand made it: a garden and the wrestler standing
+in it share a palette, a way of shading and a level of detail.
+- Before drawing something new, look at what is already there (a screenshot, and the code of the
+  surfaces it sits beside). Match its palette, shading, line weight and detail. Read their code and
+  reuse their colours and helpers rather than redrawing them from memory.
+- Keep a small palette: a ground, a main colour for shapes, an ink for words, and one accent for the
+  one thing to look at. Mix shades from those (`color-mix(in srgb, <main> 70%, <ground>)`, lighter and
+  darker) rather than inventing new colours. Many shades of a few colours look designed; many
+  unrelated colours look accidental.
+- Keep the palette in one place the code can reuse (CSS variables, a small shared module), so a
+  later change touches one spot.
+- Readable first: text needs strong contrast with what is behind it (about 4.5:1; shapes about 3:1;
+  compute it if unsure). Colours that differ in hue but are equally bright blur together: vary the lightness.
+- Taste: start from the subject's own world (a temple garden, a night market, a ledger). Tone the
+  extremes (a warm off-white, a deep ink, rarely pure white or black). One accent used sparingly beats
+  three. Neon, glows, gloss and full saturation everywhere look machine-made unless the subject calls for them.
+- Games and 3D: the same idea as art direction, not exact colours. One sky or fog colour and one light
+  colour across the scene hold it together, however many materials it has; the accent marks what the
+  player should notice; the HUD and menus use the palette like any surface.
+- A default, not a rule: when the user asks for another look, or a piece clearly needs its own world
+  (a dark space game beside a light garden), give it one, commit to it, and say so in its `about`.
+
+## 11. Check it
+Load ui-check and look at a screenshot: overlaps, clipped text, labels colliding, things outside their box.
+Fix what you see once, then stop polishing; the user will point at what they want changed.

package/app/extensions/ui/voice.js

@@ -0,0 +1,114 @@
+// Voice input for apps: speech from the microphone, as text. An app imports it:
+//   import voice from "/ui/voice.js";
+//   await voice.start(onText, opts)  start listening; onText(text) gets each finished piece of speech, in order
+//                                    opts: language ("en", optional), onState(state, detail) with state one of
+//                                    "listening", "speech", "sending", "off", "error" (detail: the message)
+//   voice.stop()                     stop listening; a piece still being spoken is sent first
+//   voice.mode()                     "api" or "browser", known after start
+// "api" (the sandbox has STT_BASE_URL, see /app/plugins/voice.py): the mic is cut into pieces at pauses
+// (2 to 10 s), each sent as a complete audio file to /voice-api/transcribe; silent pieces aren't sent.
+// "browser": the browser's own speech recognition (Chrome, Edge, Safari; audio goes to their vendor).
+const shot = new URLSearchParams(window.top.location.search).has("shot");  // a screenshot: don't listen
+let mode = null, stopNow = null;
+
+async function start(onText, { language = "", onState = () => {} } = {}) {
+  if (shot || stopNow) return;
+  const config = await fetch("/voice-api/config").then((r) => r.json()).catch(() => ({ api: false }));
+  mode = config.api ? "api" : "browser";
+  stopNow = mode === "api" ? await startApi(onText, language, onState) : startBrowser(onText, language, onState);
+}
+
+function stop() {
+  if (stopNow) stopNow();
+  stopNow = null;
+}
+
+// ---------- api: pauses by loudness, one complete file per piece ----------
+const QUIET_MS = 700, MIN_MS = 2000, MAX_MS = 10000;
+
+async function startApi(onText, language, onState) {
+  let stream;
+  try { stream = await navigator.mediaDevices.getUserMedia({ audio: true }); }
+  catch (e) { onState("error", "microphone: " + e.message); return null; }
+  const ctx = new AudioContext();
+  const analyser = ctx.createAnalyser();
+  ctx.createMediaStreamSource(stream).connect(analyser);
+  const samples = new Float32Array(analyser.fftSize);
+
+  let floor = 0.005;          // the room's quiet level, learned as it goes
+  let recorder = null, began = 0, spoke = false, quietSince = null;
+  let lastText = "", queue = Promise.resolve();
+
+  // A recorder makes one complete file from start() to stop(); timeslice chunks would lack the file header.
+  function newPiece() {
+    const old = recorder, hadSpeech = spoke;
+    recorder = new MediaRecorder(stream);
+    recorder.start();          // start the next piece before stopping this one: no gap between them
+    began = Date.now(); spoke = false; quietSince = null;
+    if (!old) return;
+    old.ondataavailable = (e) => { if (hadSpeech) queue = queue.then(() => send(e.data)); };
+    old.stop();
+  }
+
+  async function send(blob) {  // one at a time, in order: each gets the text before it as its prompt
+    const form = new FormData();
+    form.append("file", blob, "chunk." + (blob.type.split(/[/;]/)[1] || "webm"));
+    if (language) form.append("language", language);
+    if (lastText) form.append("prompt", lastText.slice(-200));
+    onState("sending");
+    try {
+      const r = await fetch("/voice-api/transcribe", { method: "POST", body: form });
+      const data = await r.json();
+      if (data.error) return onState("error", data.error);
+      if (data.text.trim()) { lastText = data.text; onText(data.text.trim()); }
+      onState("listening");
+    } catch (e) { onState("error", "transcribe: " + e.message); }
+  }
+
+  const timer = setInterval(() => {
+    analyser.getFloatTimeDomainData(samples);
+    const rms = Math.sqrt(samples.reduce((s, x) => s + x * x, 0) / samples.length);
+    const speaking = rms > Math.max(0.008, floor * 3);
+    floor += (rms - floor) * (speaking ? 0.001 : 0.05);  // follows the room, slowly while someone speaks
+    const now = Date.now(), age = now - began;
+    if (speaking) { if (!spoke) onState("speech"); spoke = true; quietSince = null; }
+    else quietSince ??= now;
+    if (spoke && quietSince && now - quietSince > QUIET_MS && age > MIN_MS) newPiece();
+    else if (age > MAX_MS) newPiece();  // a long speech is cut anyway; silence just starts over
+  }, 50);
+
+  newPiece();
+  onState("listening");
+  return () => {
+    clearInterval(timer);
+    newPiece();                // send what was being said
+    recorder.ondataavailable = null;
+    recorder.stop();
+    stream.getTracks().forEach((t) => t.stop());
+    ctx.close();
+    onState("off");
+  };
+}
+
+// ---------- browser: its speech recognition, restarted when it ends by itself ----------
+function startBrowser(onText, language, onState) {
+  const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
+  if (!SR) { onState("error", "no speech recognition in this browser, and no STT_BASE_URL in the sandbox"); return null; }
+  const rec = new SR();
+  let on = true;
+  rec.continuous = true;
+  rec.interimResults = false;
+  if (language) rec.lang = language;
+  rec.onresult = (e) => {
+    for (let i = e.resultIndex; i < e.results.length; i++)
+      if (e.results[i].isFinal && e.results[i][0].transcript.trim()) onText(e.results[i][0].transcript.trim());
+  };
+  rec.onspeechstart = () => onState("speech");
+  rec.onerror = (e) => { if (e.error !== "no-speech" && e.error !== "aborted") onState("error", e.error); };
+  rec.onend = () => { if (on) setTimeout(() => on && rec.start(), 300); };  // it stops after silence or minutes
+  rec.start();
+  onState("listening");
+  return () => { on = false; rec.stop(); onState("off"); };
+}
+
+export default { start, stop, mode: () => mode };

package/app/extensions/ui_history/browser.js

@@ -0,0 +1,97 @@
+// Browser half of the ui_history plugin: undo, redo and rewind the surfaces.
+//   Ctrl+Z / ⌘Z: undo.  Ctrl+Shift+Z / ⌘⇧Z / Ctrl+Y: redo.  (Not while typing in a field: that undoes the typing.)
+//   Hold Alt (Option) and drag sideways anywhere: scrub along the history; let go to stay there.
+//   Doing something new after going back starts a branch; a note offers to bring the other one back.
+// It only sends messages (ui_undo, ui_redo, ui_goto); the server puts the surfaces back and ui.js redraws them.
+const CSS = `
+  #ui-history-bar { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex;
+    flex-direction: column; align-items: center; gap: 6px; max-width: calc(100vw - 32px); padding: 8px 14px; border-radius: 12px;
+    font-size: 12px; color: #fff; background: rgba(29, 29, 31, .92); pointer-events: none; }
+  #ui-history-bar .ticks { display: flex; gap: 2px; flex-wrap: wrap; justify-content: center; }
+  #ui-history-bar .ticks i { width: 6px; height: 14px; border-radius: 2px; background: #fff; opacity: .3; }
+  #ui-history-bar .ticks i.now { opacity: 1; background: #f4d35e; }
+  #ui-history-bar .ticks i.ahead { opacity: .12; }
+  #ui-history-toast { position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 9999; display: flex; gap: 10px;
+    align-items: center; padding: 8px 14px; border-radius: 12px; font-size: 13px; color: #fff; background: rgba(29, 29, 31, .92); }
+  #ui-history-toast button { font: inherit; color: inherit; background: none; border: 1px solid currentColor; border-radius: 8px;
+    padding: 2px 10px; cursor: pointer; }`;
+
+export default function (page) {
+  document.head.insertAdjacentHTML("beforeend", `<style id="ui-history-css">${CSS}</style>`);
+  const bar = Object.assign(document.createElement("div"), { id: "ui-history-bar", hidden: true });
+  const toastEl = Object.assign(document.createElement("div"), { id: "ui-history-toast", hidden: true });
+  document.body.append(bar, toastEl);
+  let toastTimer;
+  function toast(text, button, onclick) {
+    toastEl.replaceChildren(Object.assign(document.createElement("span"), { textContent: text }));
+    if (button) toastEl.append(Object.assign(document.createElement("button"), { textContent: button,
+      onclick: () => { toastEl.hidden = true; onclick(); } }));
+    toastEl.hidden = false;
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => (toastEl.hidden = true), button ? 8000 : 2500);
+  }
+
+  const typing = (e) => e.target.closest?.("input, textarea, select, [contenteditable='true']");
+  document.addEventListener("keydown", (e) => {
+    if (!(e.ctrlKey || e.metaKey) || typing(e)) return;
+    const k = e.key.toLowerCase();
+    if (k === "z" && !e.shiftKey) { e.preventDefault(); page.send({ type: "ui_undo" }); }
+    else if ((k === "z" && e.shiftKey) || k === "y") { e.preventDefault(); page.send({ type: "ui_redo" }); }
+  });
+
+  // {x0, x, line, start, i} while Alt-dragging. It starts at the press, before the history has come (line: null till
+  // then), so a release or moves during the fetch are not lost; it ends at the release, or at the first move without
+  // the button held (released outside the window), a cancelled drag, or the window losing focus.
+  let scrub = null;
+  function showBar() {
+    const { line, i } = scrub, from = Math.max(0, line.length - 80);
+    const ticks = Object.assign(document.createElement("div"), { className: "ticks" });
+    for (let j = from; j < line.length; j++) ticks.append(Object.assign(document.createElement("i"), { className: j === i ? "now" : j > i ? "ahead" : "" }));
+    const step = line[i];
+    bar.replaceChildren(Object.assign(document.createElement("span"), {
+      textContent: `${i + 1} of ${line.length}: ${step.what}, ${new Date(step.ts * 1000).toLocaleTimeString()}` }), ticks);
+    bar.hidden = false;
+  }
+  function follow() {  // go to the step under the pointer
+    const step = Math.max(10, Math.min(40, 600 / scrub.line.length));  // px per step: the whole line fits in ~600 px
+    const i = Math.max(0, Math.min(scrub.line.length - 1, scrub.start + Math.round((scrub.x - scrub.x0) / step)));
+    if (i === scrub.i) return;
+    scrub.i = i;
+    page.send({ type: "ui_goto", step: scrub.line[i].n });
+    showBar();
+  }
+  document.addEventListener("pointerdown", async (e) => {
+    if (!e.altKey) return;
+    e.preventDefault(); e.stopPropagation();
+    const me = scrub = { x0: e.clientX, x: e.clientX, line: null };
+    let history;
+    try { history = await (await fetch("/ui-api/history")).json(); } catch { if (scrub === me) scrub = null; return; }
+    if (scrub !== me) return;  // let go before the history came: nothing to do
+    me.line = history.line;
+    me.start = me.i = history.line.findIndex((s) => s.n === history.at);
+    showBar();
+    follow();  // the pointer may have moved meanwhile
+  }, true);
+  document.addEventListener("pointermove", (e) => {
+    if (!scrub) return;
+    if (!(e.buttons & 1)) return end();  // the button is up: it was let go outside the window
+    scrub.x = e.clientX;
+    if (scrub.line) follow();
+  });
+  document.addEventListener("pointerup", () => end());
+  document.addEventListener("pointercancel", () => end());
+  addEventListener("blur", () => end());
+  function end() {
+    if (!scrub) return;
+    const ahead = scrub.line && scrub.i < scrub.line.length - 1;
+    scrub = null;
+    bar.hidden = true;
+    if (ahead) toast("Gone back. Do something new to branch from here, or Ctrl+Shift+Z to come forward.");
+  }
+
+  page.on("ui_history", (ev) => {
+    if (ev.event === "moved" && !scrub) toast(`Back to just after: ${ev.what}`);
+    if (ev.event === "branched") toast("You branched from an earlier moment. The other version is kept.", "Bring it back",
+      () => page.send({ type: "ui_goto", step: ev.tip }));
+  });
+}