chalk-talk 0.12.0 → 0.14.0

package/kit/SKILL.template.md

@@ -0,0 +1,55 @@
+---
+name: <the-skill>
+description: <What it makes, in one sentence> — <what comes out: one file that opens offline, a workbook…>. Use when someone asks to <the requests, in the words people use, in English and Portuguese> ("…", "…"), or <the situation it fits>.
+license: MIT
+compatibility: Best with code execution and Node.js 18 or later (Chrome, Chromium or Edge, when installed, lets the script check the result first).
+metadata:
+  version: "0.1.0"
+---
+
+<!-- The shape the skills of this kit share (chalk-talk, stage-door, dress-rehearsal, front-of-house). A reference for
+a new skill, not a file the skills import: copy it, then replace every <…>. Keep SKILL.md under 500 lines; what the
+model only needs sometimes goes in references/. -->
+
+# <the-skill>: <what it does, in a few words>
+
+You write only the **source** (`<id>.<ext>`, a short text a person can read and change); `scripts/build.mjs` checks
+it and makes everything else. Never write what the script makes. Paths are relative to this skill's folder.
+
+## 1. Make it first
+
+For an ordinary request **do not ask and do not show a plan: make it.** Decide what is missing yourself — the
+reasonable bet, never an invented fact — and say what you chose when you deliver.
+
+Ask first — once, all together, only what is missing — when <the cases where a wrong guess is costly: for a class, a
+real decision, data only the person has>, when the request could mean two things, or when the person asks to see the
+plan.
+
+## 2. Write the source
+
+<The cheat sheet: the lines of the usual case, each a line that builds (the kit's checks build every example). The
+whole format in references/<format>.md, opened only when a line is not in the sheet or a message does not settle a
+mistake.>
+
+## 3. Build and check
+
+```
+node scripts/build.mjs <id>.<ext>
+```
+
+- `✗ <file>:<line>: …` (exit 1, nothing written): fix that line the way the message says.
+- `! …` (exit 3): made, but the check found something to fix — fix it and build again.
+- `✓ …`: done. `✗ … not checked`: done, but tell the person it was not checked.
+
+At most **two** rounds of fixes; then deliver and say in plain words what is left.
+
+## 4. Deliver
+
+The path of what was made (or the file itself where the person downloads files), in one line **what you chose and an
+offer to change it**, and one sentence on what to look at first.
+
+## Never
+
+- Never edit `assets/` or the generated `scripts/`.
+- Never put HTML, links or scripts in the source.
+- Never invent a fact, a number or a quote to fill a gap: ask, or leave it visibly open.

package/kit/browser.mjs

@@ -0,0 +1,181 @@
+// A Chrome, Chromium or Edge without a window: opens a built page in one of its modes (#review, #snapshots, #svg…) and
+// reads back what the page wrote in <pre id="chalk-<mode>">. It talks to the browser over the DevTools protocol on a
+// pipe (--remote-debugging-pipe) and waits for that <pre> itself: --dump-dom hangs on some machines, the pipe does not.
+// The browsers are tried in order; one that does not start or does not answer in time gives way to the next.
+// Part of the skills kit (chalk-talk/kit): copied into each skill by its tools/assets.mjs. Node only, no dependency.
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** Playwright's own Chromium: the package's answer when it is installed here, else what it downloaded. */
+function playwright() {
+  const found = []
+  const req = createRequire(join(process.cwd(), 'noop.js'))
+  for (const name of ['playwright', 'playwright-core']) {
+    try {
+      const p = req(name).chromium.executablePath()
+      if (p) found.push(p)
+    } catch {}
+  }
+  const caches = [process.env.PLAYWRIGHT_BROWSERS_PATH, join(homedir(), '.cache/ms-playwright'), join(homedir(), 'Library/Caches/ms-playwright'), '/opt/pw-browsers'].filter(Boolean)
+  const inside = ['chrome-linux64/chrome', 'chrome-linux/chrome', 'chrome-linux-arm64/chrome', 'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium']
+  for (const cache of caches) {
+    let dirs = []
+    try {
+      dirs = readdirSync(cache).filter((d) => /^chromium-\d+$/.test(d)).sort().reverse()
+    } catch {}
+    for (const d of dirs) for (const p of inside) found.push(join(cache, d, p))
+  }
+  return found
+}
+
+/** Every browser worth trying, in order: CHROME_PATH, PUPPETEER_EXECUTABLE_PATH, Playwright's Chromium, the usual places
+ * on macOS and Windows, then `which` on Linux. Only paths that exist, each once. */
+export function candidates() {
+  const paths = [process.env.CHROME_PATH, process.env.PUPPETEER_EXECUTABLE_PATH, ...playwright(),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe']
+  if (process.platform !== 'win32') {
+    for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']) {
+      try {
+        paths.push(execFileSync('which', [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim())
+      } catch {}
+    }
+  }
+  return [...new Set(paths.filter((p) => p && existsSync(p)))]
+}
+
+/** The first browser there is, or null. */
+export function browser() {
+  return candidates()[0] ?? null
+}
+
+/** What the browser needs besides the usual: on Linux no sandbox as root (Chromium refuses to start otherwise) and no
+ * /dev/shm (small in containers). */
+export function launchFlags(platform = process.platform, uid = process.getuid?.()) {
+  const flags = ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--allow-file-access-from-files',
+    '--disable-background-networking', '--disable-component-update', '--disable-sync', '--remote-debugging-pipe']
+  if (platform === 'linux') flags.push('--disable-dev-shm-usage')
+  if (platform === 'linux' && uid === 0) flags.push('--no-sandbox')
+  return flags
+}
+
+class BrowserFailed extends Error {}
+
+// A wait that never keeps Node running by itself.
+const pause = (ms) => new Promise((ok) => setTimeout(ok, ms).unref())
+
+/** One browser, started with a profile of its own, spoken to over the pipe. */
+async function start(exe) {
+  const profile = mkdtempSync(join(tmpdir(), 'chalk-talk-'))
+  const child = spawn(exe, [...launchFlags(), `--user-data-dir=${profile}`, 'about:blank'], { stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'] })
+  const waiting = new Map()
+  let id = 0
+  let dead
+  // a failure of the whole browser rejects every call still waiting
+  const fail = (why) => {
+    dead ??= why
+    for (const { reject } of waiting.values()) reject(new BrowserFailed(dead))
+    waiting.clear()
+  }
+  child.on('error', (e) => fail(e.message))
+  const exited = new Promise((ok) => child.once('exit', (code) => (fail(`it stopped (exit ${code})`), ok())))
+  let buf = Buffer.alloc(0)
+  child.stdio[4].on('data', (d) => {
+    buf = Buffer.concat([buf, d])
+    let at
+    while ((at = buf.indexOf(0)) >= 0) {
+      const msg = JSON.parse(buf.subarray(0, at).toString('utf8'))
+      buf = buf.subarray(at + 1)
+      const call = msg.id && waiting.get(msg.id)
+      if (!call) continue
+      waiting.delete(msg.id)
+      if (msg.error) call.reject(new Error(msg.error.message))
+      else call.ok(msg.result)
+    }
+  })
+  child.stdio[3].on('error', (e) => fail(e.message))
+  const send = (method, params = {}, sessionId) => new Promise((ok, reject) => {
+    if (dead) return reject(new BrowserFailed(dead))
+    const n = ++id
+    waiting.set(n, { ok, reject })
+    child.stdio[3].write(JSON.stringify({ id: n, method, params, ...(sessionId ? { sessionId } : {}) }) + '\0')
+  })
+  const close = async () => {
+    if (!dead) {
+      send('Browser.close').catch(() => {})
+      await Promise.race([exited, pause(3000)])
+    }
+    child.kill()
+    await Promise.race([exited, pause(2000)])
+    rmSync(profile, { recursive: true, force: true })
+  }
+  return { send, close }
+}
+
+/** Opens `file` at `#mode` (with `query`) in a tab of its own and returns what the page wrote, parsed — { error } when
+ * the page could not be opened or wrote nothing in `ms`. */
+async function open(b, file, mode, query, ms) {
+  const until = Date.now() + ms
+  let sessionId
+  // Every call waits at most until the page's time is up: a page busy forever does not hold the build.
+  const ask = (method, params, wait = until - Date.now()) => {
+    let timer
+    const late = new Promise((_, reject) => (timer = setTimeout(() => reject(new BrowserFailed(`no answer in ${Math.round(ms / 1000)} s`)), Math.max(0, wait))))
+    return Promise.race([b.send(method, params, sessionId), late]).finally(() => clearTimeout(timer))
+  }
+  const { targetId } = await ask('Target.createTarget', { url: 'about:blank' })
+  try {
+    ;({ sessionId } = await ask('Target.attachToTarget', { targetId, flatten: true }))
+    const nav = await ask('Page.navigate', { url: `${pathToFileURL(file).href}${query ? `?${query}` : ''}#${mode}` })
+    if (nav.errorText) return { error: `the page did not open (${nav.errorText})` }
+    while (Date.now() < until) {
+      const r = await ask('Runtime.evaluate', { expression: `document.getElementById('chalk-${mode}')?.textContent ?? null`, returnByValue: true })
+      const text = r.result?.value
+      if (typeof text === 'string' && text) return JSON.parse(decodeURIComponent(text))
+      await pause(50)
+    }
+    const at = await ask('Runtime.evaluate', { expression: 'location.href', returnByValue: true }, 1000).catch(() => undefined)
+    throw new BrowserFailed(`no answer in ${Math.round(ms / 1000)} s${at?.result?.value ? ` at ${at.result.value}` : ''}`)
+  } finally {
+    sessionId = undefined
+    b.send('Target.closeTarget', { targetId }).catch(() => {})
+  }
+}
+
+/** Runs `jobs` ({ file, mode, query }) in one browser and returns their results in order, with the browser used —
+ * `results` null when there is no browser at all. A browser that fails (does not start, stops, or a page gets no answer
+ * in `timeout` seconds) gives way to the next one, which runs every job again; when none works, each result is
+ * { error } naming what was tried. */
+export async function runPages(jobs, { timeout = 20 } = {}) {
+  const list = candidates()
+  if (!list.length) return { results: null, tried: [] }
+  const tried = []
+  for (const exe of list) {
+    let b
+    try {
+      b = await start(exe)
+      const results = []
+      for (const { file, mode, query = '' } of jobs) results.push(await open(b, file, mode, query, timeout * 1000))
+      return { results, used: exe, tried }
+    } catch (e) {
+      tried.push(`${exe}: ${e instanceof BrowserFailed ? e.message : e.message.split('\n')[0]}`)
+    } finally {
+      await b?.close()
+    }
+  }
+  const error = `no browser answered — ${tried.join('; ')}. Point CHROME_PATH at another one, or give it more time with --review-timeout`
+  return { results: jobs.map(() => ({ error })), tried }
+}
+
+/** One page: what it wrote, parsed; null without a browser, { error } when it failed. */
+export async function runPage(file, mode, query = '', opts) {
+  const { results } = await runPages([{ file, mode, query }], opts)
+  return results ? results[0] : null
+}

package/kit/format.check.ts

@@ -0,0 +1,22 @@
+// The kit's format reader: the line of a path, the nearest part of it in the file, a syntax error and a file of
+// another format. Run by tools/check.mjs.
+import assert from 'node:assert/strict'
+import { readFormat } from './format'
+
+const text = 'format: shop/v1\nname: Corner shop\nitems:\n  - id: tea\n    price: 3\n  - id: cake\n'
+const r = readFormat(text, 'shop/v1')
+assert.ok(r.ok)
+if (r.ok) {
+  assert.equal(r.format.raw.name, 'Corner shop')
+  assert.equal(r.format.at(['name']), 2)
+  assert.equal(r.format.at(['items', 1]), 6)
+  assert.equal(r.format.at(['items', 1, 'price']), 6, 'a path not in the file says where its nearest part is')
+  assert.equal(r.format.at(['nowhere']), 1)
+}
+const syntax = readFormat('format: shop/v1\nname: x\n  bad: indent\n', 'shop/v1')
+assert.ok(!syntax.ok && syntax.problem.key === 'syntax' && syntax.problem.line === 2)
+const other = readFormat('format: other/v1\nname: x\n', 'shop/v1')
+assert.ok(!other.ok && other.problem.key === 'format' && other.problem.line === 1)
+const list = readFormat('- a\n- b\n', 'shop/v1')
+assert.ok(!list.ok && list.problem.key === 'format')
+console.log('kit format checks ok')

package/kit/format.ts

@@ -0,0 +1,37 @@
+// Reading a skill's YAML file so every mistake can say its line: the document, where a path is in the file, and the
+// two problems that stop reading at once (YAML that does not parse, a file that is not of this format). Part of the
+// skills kit (chalk-talk/kit): a skill's esbuild puts it in its engine.mjs. Needs the `yaml` package.
+import { isMap, LineCounter, parseDocument, type Document } from 'yaml'
+
+export type Path = (string | number)[]
+
+/** A problem the reader found before the skill's own checks: `syntax` (with YAML's code) or `format`. */
+export interface FormatProblem { line: number; key: 'syntax' | 'format'; detail?: string }
+
+export interface Format {
+  raw: Record<string, unknown>
+  doc: Document
+  /** The line where `path` (or the nearest part of it that is in the file) starts; 1 when none is. */
+  at: (path: Path) => number
+}
+
+export type Read = { ok: true; format: Format } | { ok: false; problem: FormatProblem }
+
+/** Parses `text`, which must be a YAML map whose `format:` is `format`. */
+export function readFormat(text: string, format: string): Read {
+  const lines = new LineCounter()
+  const doc = parseDocument(text, { lineCounter: lines, prettyErrors: false })
+  const at = (path: Path) => {
+    for (let p = path; p.length; p = p.slice(0, -1)) {
+      const node = doc.getIn(p, true) as { range?: [number, number, number] } | undefined
+      if (node?.range) return lines.linePos(node.range[0]).line
+    }
+    return 1
+  }
+  if (doc.errors.length) return { ok: false, problem: { line: lines.linePos(doc.errors[0].pos[0]).line, key: 'syntax', detail: doc.errors[0].code } }
+  const raw = doc.toJS() as unknown
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || (raw as Record<string, unknown>).format !== format || !isMap(doc.contents)) {
+    return { ok: false, problem: { line: at(['format']), key: 'format' } }
+  }
+  return { ok: true, format: { raw: raw as Record<string, unknown>, doc, at } }
+}

package/kit/page.mjs

@@ -0,0 +1,15 @@
+// Making the one HTML file a skill delivers: a value as JSON that can sit inside a <script> tag, and a page template
+// with its {{KEYS}} filled. Part of the skills kit (chalk-talk/kit): copied into each skill by its tools/assets.mjs.
+
+/** `value` as JSON, with "<" escaped so no text in it can end the <script> tag it goes in. */
+export const inline = (value) => JSON.stringify(value).replace(/</g, '\\u003c')
+
+/** `template` with each {{KEY}} replaced by its value (a function replacer, so `$` in a value is kept as it is). */
+export function fill(template, values) {
+  let page = template
+  for (const [key, value] of Object.entries(values)) {
+    if (!page.includes(`{{${key}}}`)) throw new Error(`The page has no {{${key}}} to fill.`)
+    page = page.replace(`{{${key}}}`, () => value)
+  }
+  return page
+}

package/kit/tools/audit.mjs

@@ -0,0 +1,42 @@
+// Before a push: no name that must not be in a public repository is in the files git tracks. The names themselves live
+// outside every repository — ~/.config/skill-kit/audit.txt, one pattern per line (a regular expression, matched
+// without case; # starts a comment) — since writing them in a public repository would publish them. Without that file
+// it says so and passes. Part of the skills kit (chalk-talk/kit).
+//
+//   node audit.mjs [<repository>] [--skip <glob> …]   exit 1 when a name is found
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const AUDIT_LIST = join(homedir(), '.config/skill-kit/audit.txt')
+
+/** The tracked text files that match a pattern of the list, as "file:line" — skipping the `skip` pathspecs (generated
+ * and minified files). null when there is no list. */
+export function audit(repo, skip = []) {
+  if (!existsSync(AUDIT_LIST)) return null
+  const patterns = readFileSync(AUDIT_LIST, 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+  if (!patterns.length) return []
+  try {
+    const out = execFileSync('git', ['-C', repo, 'grep', '-I', '-n', '-i', '-E', patterns.join('|'), '--', '.', ...skip.map((s) => `:!${s}`)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
+    // only where, never what: the matched text is not printed
+    return out.trim().split('\n').filter(Boolean).map((l) => l.split(':').slice(0, 2).join(':'))
+  } catch (e) {
+    if (e.status === 1) return []
+    throw e
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2)
+  const skip = args.flatMap((a, i) => (args[i - 1] === '--skip' ? [a] : []))
+  const repo = resolve(args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--skip') ?? '.')
+  const found = audit(repo, skip)
+  if (found === null) console.log(`• audit     no list at ${AUDIT_LIST}: nothing checked`)
+  else if (!found.length) console.log('✓ audit     no listed name in the tracked files')
+  else {
+    for (const f of found) console.log(`✗ audit     ${f}`)
+    process.exit(1)
+  }
+}

package/kit/tools/checks.mjs

@@ -0,0 +1,67 @@
+// The skeleton every skill's tools/check.mjs shares: what passed and what did not, running the skill's own build,
+// SKILL.md's frontmatter, one version everywhere, and a page probed in a headless browser. Part of the skills kit
+// (chalk-talk/kit).
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { runPage } from '../browser.mjs'
+
+/** `expect(ok, what, detail)` prints ✓/✗; `done(name)` ends the process with 1 when anything failed. */
+export function checker() {
+  let failed = 0
+  return {
+    expect(ok, what, detail = '') {
+      console.log(`${ok ? '✓' : '✗'} ${what}${!ok && detail ? `\n${detail}` : ''}`)
+      if (!ok) failed++
+      return ok
+    },
+    done(name) {
+      if (failed) {
+        console.error(`✗ ${failed} check${failed === 1 ? '' : 's'} failed`)
+        process.exit(1)
+      }
+      console.log(`✓ ${name} checks ok`)
+    },
+  }
+}
+
+/** Runs a Node script (the skill's build.mjs) with `args`; the result of spawnSync, as text. */
+export const runNode = (script, args = [], opts = {}) => spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', ...opts })
+
+/** SKILL.md's frontmatter as { name, description, version, … } (the version from metadata.version). */
+export function skillFrontmatter(skillMd) {
+  const head = readFileSync(skillMd, 'utf8').match(/^---\n([\s\S]*?)\n---/)?.[1] ?? ''
+  const field = (k) => head.match(new RegExp(`^${k}: (.*)$`, 'm'))?.[1] ?? ''
+  return { name: field('name'), description: field('description'), version: head.match(/version: "([^"]+)"/)?.[1] ?? '', lines: readFileSync(skillMd, 'utf8').split('\n').length }
+}
+
+/** The usual checks of SKILL.md: its name is the folder's, a description of at most 1024 characters, under 500 lines. */
+export function checkSkillMd(expect, skillMd, name) {
+  const f = skillFrontmatter(skillMd)
+  expect(f.name === name, 'SKILL.md name is the folder name')
+  expect(f.description.length > 0 && f.description.length <= 1024, `SKILL.md description has ${f.description.length} of 1024 characters`)
+  expect(f.lines < 500, 'SKILL.md under 500 lines')
+  return f
+}
+
+/** One version everywhere: { where: version } all equal. */
+export function checkOneVersion(expect, versions) {
+  const all = Object.values(versions)
+  expect(all.every((v) => v && v === all[0]), `one version everywhere: ${Object.entries(versions).map(([k, v]) => `${k} ${v}`).join(', ')}`)
+}
+
+/** Opens `html` (with a script that writes <pre id="chalk-probe">) in a headless browser; what it wrote, parsed — null
+ * without a browser. */
+export async function pageProbe(html, { timeout = 60 } = {}) {
+  const file = join(mkdtempSync(join(tmpdir(), 'skill-probe-')), 'probe.html')
+  writeFileSync(file, html)
+  return runPage(file, 'probe', '', { timeout })
+}
+
+/** The script a probed page ends with: `body` is async code that fills `out`; it is written for pageProbe to read. */
+export const probeScript = (body) => `<script type="module">
+const out = {}
+try { ${body} } catch (e) { out.failed = String(e && e.message || e) }
+const pre = document.createElement('pre'); pre.id = 'chalk-probe'; pre.textContent = encodeURIComponent(JSON.stringify(out)); document.body.append(pre)
+</script>`

package/kit/tools/eval-metrics.mjs

@@ -0,0 +1,70 @@
+// How fast a skill delivers, from an eval run kept with --keep-temp and --json: for each run, the seconds until the
+// first page (the first build that wrote an .html), the files read before the source was written, the rounds of fixes
+// (builds after the first page) and the quality grader. Per case, the mean of its runs. Part of the skills kit
+// (chalk-talk/kit).
+//
+//   node eval-metrics.mjs <run.json> [<another run.json> …]
+import { readFileSync } from 'node:fs'
+
+const isBuild = (u) => u.name === 'Bash' && /build\.mjs/.test(u.input?.command ?? '')
+const isRecipe = (u) => (u.name === 'Write' || u.name === 'Edit') && /\.(chalk|mmd|json|md|ya?ml)$/.test(u.input?.file_path ?? '')
+const text = (c) => (typeof c === 'string' ? c : (c ?? []).map((x) => x.text ?? '').join(''))
+
+function metrics(tracePath, startedAt) {
+  let lines
+  try {
+    lines = readFileSync(tracePath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+  } catch {
+    return undefined
+  }
+  const uses = new Map()
+  let reads = 0
+  let wrote = false
+  let first
+  let builds = 0
+  let drawnAt
+  for (const e of lines) {
+    for (const c of e.message?.content ?? []) {
+      if (c.type === 'tool_use') {
+        uses.set(c.id, c)
+        // what the skill had to read before writing: files opened with Read, or with cat/sed/head/grep in a shell
+        if (!wrote && c.name === 'Read') reads++
+        if (!wrote && c.name === 'Bash') reads += (c.input?.command?.match(/(?:references|SKILL)[\w./-]*\.(?:md|json|chalk|mmd)/g) ?? []).length
+        if (isRecipe(c)) wrote = true
+        if (isBuild(c)) builds++
+      }
+      if (c.type === 'tool_result' && !drawnAt) {
+        const u = uses.get(c.tool_use_id)
+        if (u && isBuild(u) && /\.html\b/.test(text(c.content)) && !/^✗ (?!review)/m.test(text(c.content))) {
+          drawnAt = Date.parse(e.timestamp)
+          first = builds
+        }
+      }
+    }
+  }
+  return {
+    firstDrawing: drawnAt ? (drawnAt - Date.parse(startedAt)) / 1000 : undefined,
+    reads,
+    fixes: first ? builds - first : undefined,
+  }
+}
+
+const mean = (xs) => {
+  const v = xs.filter((x) => typeof x === 'number')
+  return v.length ? v.reduce((a, b) => a + b, 0) / v.length : undefined
+}
+const show = (x, digits = 0) => (x === undefined ? '—' : x.toFixed(digits))
+
+for (const file of process.argv.slice(2)) {
+  const run = JSON.parse(readFileSync(file, 'utf8'))
+  console.log(`\n${file} — ${run.claudeVersion ?? ''}, ${run.durationSeconds ?? '?'} s, US$ ${(run.costUsd ?? 0).toFixed(2)}`)
+  console.log('case                     | 1st drawing s | reads before writing | fixes | quality | runs drawn')
+  for (const c of run.cases) {
+    const runs = (c.arms?.with ?? []).map((r) => ({ ...r, m: metrics(r.tracePath, r.startedAt) }))
+    const ms = runs.map((r) => r.m).filter(Boolean)
+    const drawn = ms.filter((m) => m.firstDrawing !== undefined).length
+    // the score is the quality grader (or, for a case that should ask, every grader)
+    const quality = runs.map((r) => { const q = r.graders?.find((g) => g.name === 'quality'); return q ? Number(q.passed) : r.score })
+    console.log(`${c.name.padEnd(24)} | ${show(mean(ms.map((m) => m.firstDrawing))).padStart(13)} | ${show(mean(ms.map((m) => m.reads)), 1).padStart(20)} | ${show(mean(ms.map((m) => m.fixes)), 1).padStart(5)} | ${show(mean(quality), 2).padStart(5)} | ${drawn}/${runs.length}`)
+  }
+}

package/kit/tools/gallery.mjs

@@ -0,0 +1,30 @@
+// The pages and pictures of a skill's GitHub Pages gallery: each example's page in <docs>/<pages>/ and a PNG of it in
+// <docs>/thumbs/, drawn by the page itself in a headless browser (the kit's browser.mjs, over the DevTools pipe). The
+// page says what its picture is: `mode` is the #mode that answers with it and `pick` takes the PNG data: URL from the
+// answer. The gallery's index stays the skill's own. Part of the skills kit (chalk-talk/kit).
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { browser, runPages } from '../browser.mjs'
+
+/** `items`: [{ name, html }]. Writes every page, then every picture in one opening of the browser. */
+export async function gallery(docs, items, { pages = 'lessons', mode, pick, timeout = 60 }) {
+  if (!browser()) throw new Error('No Chrome, Chromium or Edge: the pictures need one (set CHROME_PATH).')
+  for (const dir of [pages, 'thumbs']) {
+    rmSync(join(docs, dir), { recursive: true, force: true })
+    mkdirSync(join(docs, dir), { recursive: true })
+  }
+  const files = items.map(({ name, html }) => {
+    const file = join(docs, pages, `${name}.html`)
+    writeFileSync(file, html)
+    return file
+  })
+  const { results } = await runPages(files.map((file) => ({ file, mode })), { timeout })
+  items.forEach(({ name }, k) => {
+    const r = results[k]
+    const png = r && !r.error ? pick(r) : undefined
+    if (!png) throw new Error(`${name}: the picture failed (${r?.error ?? 'no picture in the answer'})`)
+    writeFileSync(join(docs, 'thumbs', `${name}.png`), Buffer.from(png.replace(/^data:image\/png;base64,/, ''), 'base64'))
+    console.log(`✓ ${name}`)
+  })
+  return files
+}

package/kit/tools/linux-check.mjs

@@ -0,0 +1,31 @@
+// A skill's build as in a cloud sandbox: Linux, as root, with Playwright's Chromium and no other browser. Each case is
+// a file to build and the exit code it must give — never «not checked» from a browser that did not answer. Needs
+// Docker; downloads node:22-slim and Playwright's Chromium (~150 MB). Part of the skills kit (chalk-talk/kit).
+import { execFileSync } from 'node:child_process'
+import { basename } from 'node:path'
+
+/** `skill`: the skill's folder; `cases`: [{ file, args?, exit }]. Returns true when every case gave its exit code. */
+export function linuxCheck(skill, cases) {
+  const name = `skill-linux-check-${process.pid}`
+  const sh = (cmd) => execFileSync('docker', ['exec', name, 'bash', '-c', cmd], { encoding: 'utf8' })
+  try {
+    execFileSync('docker', ['run', '-d', '--name', name, 'node:22-slim', 'sleep', '1800'], { stdio: 'ignore' })
+    sh('mkdir -p /work/skill /work/files')
+    for (const dir of ['scripts', 'assets']) execFileSync('docker', ['cp', `${skill}/${dir}`, `${name}:/work/skill/`])
+    for (const c of cases) execFileSync('docker', ['cp', c.file, `${name}:/work/files/`])
+    sh('cd /work && npm init -y >/dev/null && npm i playwright >/dev/null 2>&1 && npx playwright install --with-deps chromium >/dev/null 2>&1')
+    let ok = true
+    for (const c of cases) {
+      const args = (c.args ?? []).map((a) => `'${a}'`).join(' ')
+      const out = sh(`cd /work && node skill/scripts/build.mjs files/${basename(c.file)} ${args}; echo "exit=$?"`)
+      const exit = Number(out.match(/exit=(\d+)\s*$/)?.[1])
+      const unchecked = /not checked|could not run|no Chrome/.test(out)
+      const good = exit === c.exit && !unchecked
+      ok &&= good
+      console.log(`${good ? '✓' : '✗'} linux as root: ${basename(c.file)} exit ${exit} (expected ${c.exit})${unchecked ? ', the review did not run' : ''}`)
+    }
+    return ok
+  } finally {
+    execFileSync('docker', ['rm', '-f', name], { stdio: 'ignore' })
+  }
+}

package/kit/tools/vendor.mjs

@@ -0,0 +1,24 @@
+// A skill carries the kit's runtime files itself (claude.ai installs no packages): `vendor` copies them into the skill
+// and says which kit they came from. Part of the skills kit (chalk-talk/kit), used by a skill's tools/assets.mjs.
+import { copyFileSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const kit = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** The kit's version: the chalk-talk package it ships in (or the repository's plugin when used from source). */
+export function kitVersion() {
+  for (const p of [join(kit, '../package.json'), join(kit, '../.claude-plugin/plugin.json')]) {
+    try {
+      const { name, version } = JSON.parse(readFileSync(p, 'utf8'))
+      if (version && (name === 'chalk-talk' || p.endsWith('plugin.json'))) return version
+    } catch {}
+  }
+  return 'unknown'
+}
+
+/** Copies the kit's `files` (e.g. ['browser.mjs', 'page.mjs']) into `into`; returns the line for assets/VERSION. */
+export function vendor(into, files) {
+  for (const f of files) copyFileSync(join(kit, f), join(into, f))
+  return `kit chalk-talk ${kitVersion()} (${files.join(', ')})`
+}

package/kit/tools/zip.mjs

@@ -0,0 +1,14 @@
+// Packs a skill for claude.ai (Settings › Skills) and the API: <root>/dist/<name>.zip with the skills/<name>/ folder
+// inside. Part of the skills kit (chalk-talk/kit).
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, rmSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export function zip(root, name) {
+  const out = join(root, 'dist', `${name}.zip`)
+  mkdirSync(dirname(out), { recursive: true })
+  rmSync(out, { force: true })
+  execFileSync('zip', ['-qr', out, name, '-x', '*.DS_Store'], { cwd: join(root, 'skills') })
+  console.log(`✓ ${out} (${Math.round(statSync(out).size / 1024)} KB)`)
+  return out
+}

package/markdown.js

@@ -1,4 +1,4 @@
-// chalk-talk/markdown (engine v0.252.0) — MIT. GENERATED by tools/assets.mjs.
+// chalk-talk/markdown (engine v0.254.0) — MIT. GENERATED by tools/assets.mjs.
 // player/markdown.ts
 var FENCES = { "chalk-talk": "text", "chalk-mermaid": "mermaid" };
 function fenceKind(info) {