chalk-talk 0.11.0 → 0.12.0

package/scripts/browser.mjs

@@ -1,47 +1,181 @@
-// A Chrome, Chromium or Edge without a window: opens a built page in one of its modes (#review, #snapshot) and reads
-// back what the page wrote in <pre id="chalk-<mode>">. Used by build.mjs and by the repository's tools.
-import { execFileSync } from 'node:child_process'
-import { existsSync, mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
+// 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.
+// Used by build.mjs and by the repository's tools. 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'
 
-/** The browser to use: CHROME_PATH, then the usual places on macOS and Windows, then `which` on Linux. */
-export function browser() {
-  const env = process.env.CHROME_PATH
-  if (env && existsSync(env)) return env
-  const mac = [
+/** 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',
-  ]
-  const win = ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe']
-  for (const p of [...mac, ...win]) if (existsSync(p)) return p
-  for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']) {
-    try {
-      const p = execFileSync('which', [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
-      if (p) return p
-    } catch {}
+    '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 null
+  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
 }
 
-/** Opens `file` (with the `query`, e.g. lesson=2) at `#mode` and returns what the page wrote, parsed; null without a
- * browser, { error } when it failed. */
-export function runPage(file, mode, query = '') {
-  const exe = browser()
-  if (!exe) return null
+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 {
-    const dom = execFileSync(exe, [
-      '--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--allow-file-access-from-files',
-      `--user-data-dir=${profile}`, '--virtual-time-budget=30000', '--dump-dom', `${pathToFileURL(file).href}${query ? `?${query}` : ''}#${mode}`,
-    ], { encoding: 'utf8', timeout: 90000, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
-    const found = dom.match(new RegExp(`<pre id="chalk-${mode}">([^<]*)</pre>`))
-    return found ? JSON.parse(decodeURIComponent(found[1])) : { error: `the page did not finish the ${mode}` }
-  } catch (e) {
-    return { error: e.message.split('\n')[0] }
+    ;({ 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 {
-    rmSync(profile, { recursive: true, force: true })
+    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/scripts/build.mjs

@@ -4,21 +4,25 @@
 // flowchart (.mmd, with `%% # chapter` and `%% > narration`), or Markdown (.md): each ```chalk-talk or ```mermaid block
 // in it is a lesson.
 //
-//   node build.mjs <recipe.json|.chalk|.mmd|.md> [out.html] [--no-review]
+//   node build.mjs <recipe.json|.chalk|.mmd|.md> [out.html] [--no-review] [--snapshots [folder]] [--review-timeout <s>]
 //   node build.mjs <one> <two> … --out course.html [--title "The course"] [--no-review]
 //   node build.mjs <recipe> [out.svg] --svg      an SVG that draws itself, with no script: it plays inside an <img>,
 //                                                in a README on GitHub too (one SVG per lesson, named by its id)
 //
-// Only paths ending in .html or .svg are ever written. Exit codes: 0 drawn and checked (or no browser to check with); 1 a
+// --snapshots writes, in <id>.snapshots/ beside the page (or the folder given), a PNG of each chapter as it ends at each
+// setting the reviewer tries, and <id>.contact-sheet.png with them all: a picture to look at before delivering.
+//
+// Only .html, .svg and .png files are ever written. Exit codes: 0 drawn and checked (or no browser to check with); 1 a
 // recipe breaks the contract (nothing written); 2 bad arguments; 3 drawn, but the reviewer found something to fix (off
-// the paper, text over text, a line across a text); 4 --svg with no browser to draw it in. Needs Node 18 or later and
-// nothing else; the review and --svg use Chrome, Chromium or Edge.
-import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+// the paper, text over text, a line across a text); 4 --svg or --snapshots with no browser to draw them in. Needs Node 18
+// or later and nothing else; the review, --snapshots and --svg use Chrome, Chromium or Edge (Playwright's Chromium too).
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { runPage } from './browser.mjs'
+import { runPages } from './browser.mjs'
 import { ChalkTextError, chaptersFor, parseChalk, PROP_ALIASES, PROP_NAMES, validateScene } from './contract.mjs'
+import { syntaxForLine, syntaxForStep } from './syntax.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const argv = process.argv.slice(2)
@@ -26,16 +30,20 @@ const option = (name) => {
   const at = argv.indexOf(name)
   return at >= 0 ? argv[at + 1] : undefined
 }
-const valued = new Set(['--out', '--title'])
-const args = argv.filter((a, i) => !a.startsWith('--') && !valued.has(argv[i - 1]))
-const noReview = argv.includes('--no-review')
+const KINDS = ['.json', '.chalk', '.mmd', '.md']
 const asSvg = argv.includes('--svg')
 const ext = asSvg ? '.svg' : '.html'
-const KINDS = ['.json', '.chalk', '.mmd', '.md']
+// --snapshots takes a folder only when one follows it (not another option, a recipe or the page).
+const snapAt = argv.indexOf('--snapshots')
+const snapFolder = snapAt >= 0 && argv[snapAt + 1] && !argv[snapAt + 1].startsWith('--') && ![...KINDS, ext].some((k) => argv[snapAt + 1].endsWith(k)) ? argv[snapAt + 1] : undefined
+const valued = new Set(['--out', '--title', '--review-timeout'])
+const args = argv.filter((a, i) => !a.startsWith('--') && !valued.has(argv[i - 1]) && !(snapFolder && i === snapAt + 1))
+const noReview = argv.includes('--no-review')
+const timeout = Number(option('--review-timeout') ?? 20)
 const sources = args.filter((a) => KINDS.some((k) => a.endsWith(k)))
 const outArg = option('--out') ?? args.find((a) => a.endsWith(ext))
-const usage = 'usage: node build.mjs <recipe.json> [out.html] [--no-review]\n       node build.mjs <one.json> <two.json> … --out course.html [--title "…"] [--no-review]\n       node build.mjs <recipe.json> [out.svg] --svg'
-if (!sources.length || args.some((a) => !KINDS.some((k) => a.endsWith(k)) && !a.endsWith(ext)) || (outArg && !outArg.endsWith(ext))) {
+const usage = 'usage: node build.mjs <recipe.json> [out.html] [--no-review] [--snapshots [folder]] [--review-timeout <s>]\n       node build.mjs <one.json> <two.json> … --out course.html [--title "…"] [--no-review]\n       node build.mjs <recipe.json> [out.svg] --svg'
+if (!sources.length || args.some((a) => !KINDS.some((k) => a.endsWith(k)) && !a.endsWith(ext)) || (outArg && !outArg.endsWith(ext)) || !(timeout > 0) || (asSvg && snapAt >= 0)) {
   console.error(usage)
   process.exit(2)
 }
@@ -44,26 +52,41 @@ const PROPS = [...PROP_NAMES, ...Object.keys(PROP_ALIASES)]
 // The Mermaid converter is large: loaded only for a Mermaid block.
 const mermaid = async (text) => (await import('./mermaid.mjs')).fromMermaid(text)
 
+// The text being read and the recipe being checked, so a mistake can show how its line is written.
+let reading = ''
+let checking
+const chalk = (text) => parseChalk((reading = text), PROPS)
+
 /** The recipes a file holds: one for .json, .chalk and .mmd; one per ```chalk-talk / ```mermaid block in a .md. */
 async function recipesOf(file) {
   const text = readFileSync(resolve(file), 'utf8')
   if (file.endsWith('.json')) return [JSON.parse(text)]
-  if (file.endsWith('.chalk')) return [parseChalk(text, PROPS)]
+  if (file.endsWith('.chalk')) return [chalk(text)]
   if (file.endsWith('.mmd')) return [await mermaid(text)]
   const blocks = [...text.matchAll(/^```(chalk-talk|mermaid)[^\n]*\n([\s\S]*?)^```/gm)]
   if (!blocks.length) throw new Error('no ```chalk-talk or ```mermaid block in this file.')
   const out = []
-  for (const [, kind, body] of blocks) out.push(kind === 'mermaid' ? await mermaid(body) : parseChalk(body, PROPS))
+  for (const [, kind, body] of blocks) out.push(kind === 'mermaid' ? await mermaid(body) : chalk(body))
   return out
 }
 
+/** How the line or step a mistake names is written, as lines to print under it. */
+function example(e) {
+  const line = e instanceof ChalkTextError
+    ? syntaxForLine(reading.split('\n')[e.line - 1] ?? '', PROPS)
+    : syntaxForStep(checking?.steps?.[Number(e.message.match(/^Step (\d+)/)?.[1]) - 1]?.type)
+  return line ? `  write it like:\n${line.split('\n').map((l) => `    ${l}`).join('\n')}` : ''
+}
+
 const scenes = []
 for (const file of sources) {
   try {
-    for (const recipe of await recipesOf(file)) scenes.push(validateScene(recipe))
+    for (const recipe of await recipesOf(file)) scenes.push(validateScene((checking = recipe)))
   } catch (e) {
     const where = sources.length > 1 || file.endsWith('.md') ? `${basename(file)}: ` : ''
     console.error(`✗ ${e instanceof ChalkTextError ? 'text' : 'contract'}: ${where}${e.message}`)
+    const hint = example(e)
+    if (hint) console.error(hint)
     process.exit(1)
   }
 }
@@ -86,24 +109,54 @@ scenes.forEach((scene, k) => {
   console.log(`✓ contract${who}${scene.steps.length} steps, ${chaptersFor(scene).length} chapters, ${values} values`)
 })
 
+// One browser for everything the page has to do: the review, the snapshots and the SVGs, lesson by lesson.
+const query = (k) => (course ? `lesson=${k + 1}` : '')
+const jobs = []
+scenes.forEach((_, k) => {
+  if (!noReview) jobs.push({ what: 'review', k, file: out, mode: 'review', query: query(k) })
+  if (snapAt >= 0) jobs.push({ what: 'snapshots', k, file: out, mode: 'snapshots', query: query(k) })
+  if (asSvg) jobs.push({ what: 'svg', k, file: out, mode: 'svg', query: query(k) })
+})
+const ran = jobs.length ? await runPages(jobs, { timeout }) : { results: [] }
+const name = (exe) => basename(exe).replace(/\.exe$/i, '')
+const result = (what, k) => ran.results?.[jobs.findIndex((j) => j.what === what && j.k === k)]
+
 let code = 0
 if (noReview) console.log('• review    skipped (--no-review); the page checks itself when opened')
+else if (!ran.results) console.log('• review    no Chrome, Chromium or Edge here: the page checks itself when opened')
 else {
   for (let k = 0; k < scenes.length; k++) {
     const who = course ? ` (${k + 1})` : ''
-    const r = runPage(out, 'review', course ? `lesson=${k + 1}` : '')
-    if (!r) {
-      console.log('• review    no Chrome, Chromium or Edge here: the page checks itself when opened')
-      break
-    }
-    if (r.error) console.log(`• review${who}    could not run (${r.error}); the page checks itself when opened`)
-    else if (!r.problems.length) console.log(`✓ review${who}    ${r.combos} ${r.combos === 1 ? 'setting' : 'settings'}: nothing off the paper, no text over text`)
+    const r = result('review', k)
+    if (r.error) console.log(`✗ review${who}    not checked: ${r.error}`)
+    else if (!r.problems.length) console.log(`✓ review${who}    ${r.combos} ${r.combos === 1 ? 'setting' : 'settings'}: nothing off the paper, no text over text (${name(ran.used)})`)
     else {
       for (const p of r.problems) console.log(`! review${who}    ${p}`)
       code = 3
     }
   }
 }
+
+if (snapAt >= 0) {
+  const folder = resolve(snapFolder ?? join(dirname(out), `${slug}.snapshots`))
+  for (let k = 0; k < scenes.length; k++) {
+    const r = result('snapshots', k)
+    if (!r || r.error) {
+      console.error(`✗ snapshots ${r ? r.error : 'no Chrome, Chromium or Edge here to draw them (set CHROME_PATH)'}`)
+      code = 4
+      break
+    }
+    const lesson = slugOf(scenes[k], sources[0])
+    const into = course ? join(folder, lesson) : folder
+    mkdirSync(into, { recursive: true })
+    const png = (file, data) => writeFileSync(join(into, file), Buffer.from(data.replace(/^data:image\/png;base64,/, ''), 'base64'))
+    for (const s of r.shots) png(`${lesson}.ch${s.chapter}.${s.label}.png`, s.png)
+    const sheet = join(into, `${lesson}.contact-sheet.png`)
+    png(`${lesson}.contact-sheet.png`, r.sheet)
+    console.log(`→ ${sheet} (${r.chapters} ${r.chapters === 1 ? 'chapter' : 'chapters'} × ${r.settings} ${r.settings === 1 ? 'setting' : 'settings'})`)
+  }
+}
+
 if (!asSvg) {
   console.log(`→ ${out} (${Math.round(statSync(out).size / 1024)} KB, opens offline${course ? `, ${scenes.length} lessons` : ''})`)
   process.exit(code)
@@ -112,7 +165,7 @@ if (!asSvg) {
 // --svg: each lesson drawn by the browser with its timing as CSS; one file, or one per lesson beside the first source.
 const where = outArg && !course ? undefined : dirname(resolve(outArg ?? sources[0]))
 for (let k = 0; k < scenes.length; k++) {
-  const r = runPage(out, 'svg', course ? `lesson=${k + 1}` : '')
+  const r = result('svg', k)
   if (!r) {
     console.error('✗ svg       no Chrome, Chromium or Edge here to draw it (set CHROME_PATH)')
     code = 4

package/scripts/contract.mjs

@@ -1,4 +1,4 @@
-// GENERATED by tools/assets.mjs from the drawing engine v0.250.0. Do not edit.
+// GENERATED by tools/assets.mjs from the drawing engine v0.252.0. Do not edit.
 var WORDS = ["and", "or", "not"];
 
 var PROP_NAMES = [