chalk-talk 0.14.0 → 0.14.1

package/README.md

@@ -10,7 +10,7 @@ Hand-drawn lessons that draw themselves, from a small JSON **recipe** — the pl
 <meta charset="utf-8">
 <title>My lesson</title>
 <script type="application/json" id="chalk-recipe">{ "id": "my-lesson", "title": "…", "width": 900, "height": 560, "steps": [ … ] }</script>
-<script src="https://cdn.jsdelivr.net/npm/chalk-talk@0.14.0/player.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/chalk-talk@0.14.1/player.js"></script>
 ```
 
 The player builds the page around the recipe — chapters, Next / Back, values to move, the check, downloads — and needs

package/kit/browser.mjs

@@ -121,7 +121,7 @@ async function start(exe) {
 
 /** 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) {
+async function open(b, file, mode, query, ms, shot) {
   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.
@@ -133,8 +133,24 @@ async function open(b, file, mode, query, ms) {
   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 (shot) await ask('Emulation.setDeviceMetricsOverride', { width: shot.width, height: shot.height, deviceScaleFactor: 1, mobile: false })
+    if (shot?.scheme) await ask('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: shot.scheme }] })
+    const nav = await ask('Page.navigate', { url: `${pathToFileURL(file).href}${query ? `?${query}` : ''}${mode ? `#${mode}` : ''}` })
     if (nav.errorText) return { error: `the page did not open (${nav.errorText})` }
+    // A picture of the page as it is once loaded, its fonts in and (when it says so) data-ready on the body.
+    if (shot) {
+      const ready = "document.readyState === 'complete' && document.fonts.status === 'loaded' && (document.body?.dataset.ready ?? '1') === '1'"
+      while (Date.now() < until) {
+        const r = await ask('Runtime.evaluate', { expression: ready, returnByValue: true })
+        if (r.result?.value === true) {
+          await pause(shot.settle ?? 400)
+          const { data } = await ask('Page.captureScreenshot', { format: 'png' })
+          return { png: `data:image/png;base64,${data}` }
+        }
+        await pause(50)
+      }
+      throw new BrowserFailed(`the page was not ready in ${Math.round(ms / 1000)} s`)
+    }
     while (Date.now() < until) {
       const r = await ask('Runtime.evaluate', { expression: `document.getElementById('chalk-${mode}')?.textContent ?? null`, returnByValue: true })
       const text = r.result?.value
@@ -149,7 +165,8 @@ async function open(b, file, mode, query, ms) {
   }
 }
 
-/** Runs `jobs` ({ file, mode, query }) in one browser and returns their results in order, with the browser used —
+/** Runs `jobs` ({ file, mode, query, shot }) in one browser — `shot: { width, height }` answers with { png } (a
+ * picture of the page once loaded) instead of what the page wrote — 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. */
@@ -162,7 +179,7 @@ export async function runPages(jobs, { timeout = 20 } = {}) {
     try {
       b = await start(exe)
       const results = []
-      for (const { file, mode, query = '' } of jobs) results.push(await open(b, file, mode, query, timeout * 1000))
+      for (const { file, mode = '', query = '', shot } of jobs) results.push(await open(b, file, mode, query, timeout * 1000, shot))
       return { results, used: exe, tried }
     } catch (e) {
       tried.push(`${exe}: ${e instanceof BrowserFailed ? e.message : e.message.split('\n')[0]}`)

package/kit/format.check.ts

@@ -12,6 +12,7 @@ if (r.ok) {
   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)
+  assert.equal(r.format.lineOf(text.indexOf('cake')), 6)
 }
 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)

package/kit/format.ts

@@ -6,13 +6,15 @@ 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 type FormatProblem = { line: number; key: 'syntax'; detail: string } | { line: number; key: 'format' }
 
 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
+  /** The line of a position in the text (a node's `range[0]`). */
+  lineOf: (offset: number) => number
 }
 
 export type Read = { ok: true; format: Format } | { ok: false; problem: FormatProblem }
@@ -33,5 +35,5 @@ export function readFormat(text: string, format: string): Read {
   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 } }
+  return { ok: true, format: { raw: raw as Record<string, unknown>, doc, at, lineOf: (offset) => lines.linePos(offset).line } }
 }

package/kit/tools/gallery.mjs

@@ -1,13 +1,14 @@
 // 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).
+// <docs>/thumbs/, in a headless browser (the kit's browser.mjs, over the DevTools pipe). Either the page draws its own
+// picture (`mode`, the #mode that answers with it, and `pick`, which takes the PNG data: URL from the answer) or the
+// browser takes one (`shot: { width, height }`, after `mode` if any). 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 }) {
+export async function gallery(docs, items, { pages = 'lessons', mode, pick = (r) => r.png, shot, 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 })
@@ -18,7 +19,7 @@ export async function gallery(docs, items, { pages = 'lessons', mode, pick, time
     writeFileSync(file, html)
     return file
   })
-  const { results } = await runPages(files.map((file) => ({ file, mode })), { timeout })
+  const { results } = await runPages(files.map((file) => ({ file, mode, shot })), { timeout })
   items.forEach(({ name }, k) => {
     const r = results[k]
     const png = r && !r.error ? pick(r) : undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chalk-talk",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Hand-drawn lessons that draw themselves: a player for chalk-talk recipes (one script for the browser or a CDN), a lesson you can mount inside any element, and a command that checks a recipe and builds one HTML file.",
   "license": "MIT",
   "type": "module",

package/scripts/browser.mjs

@@ -121,7 +121,7 @@ async function start(exe) {
 
 /** 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) {
+async function open(b, file, mode, query, ms, shot) {
   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.
@@ -133,8 +133,24 @@ async function open(b, file, mode, query, ms) {
   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 (shot) await ask('Emulation.setDeviceMetricsOverride', { width: shot.width, height: shot.height, deviceScaleFactor: 1, mobile: false })
+    if (shot?.scheme) await ask('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: shot.scheme }] })
+    const nav = await ask('Page.navigate', { url: `${pathToFileURL(file).href}${query ? `?${query}` : ''}${mode ? `#${mode}` : ''}` })
     if (nav.errorText) return { error: `the page did not open (${nav.errorText})` }
+    // A picture of the page as it is once loaded, its fonts in and (when it says so) data-ready on the body.
+    if (shot) {
+      const ready = "document.readyState === 'complete' && document.fonts.status === 'loaded' && (document.body?.dataset.ready ?? '1') === '1'"
+      while (Date.now() < until) {
+        const r = await ask('Runtime.evaluate', { expression: ready, returnByValue: true })
+        if (r.result?.value === true) {
+          await pause(shot.settle ?? 400)
+          const { data } = await ask('Page.captureScreenshot', { format: 'png' })
+          return { png: `data:image/png;base64,${data}` }
+        }
+        await pause(50)
+      }
+      throw new BrowserFailed(`the page was not ready in ${Math.round(ms / 1000)} s`)
+    }
     while (Date.now() < until) {
       const r = await ask('Runtime.evaluate', { expression: `document.getElementById('chalk-${mode}')?.textContent ?? null`, returnByValue: true })
       const text = r.result?.value
@@ -149,7 +165,8 @@ async function open(b, file, mode, query, ms) {
   }
 }
 
-/** Runs `jobs` ({ file, mode, query }) in one browser and returns their results in order, with the browser used —
+/** Runs `jobs` ({ file, mode, query, shot }) in one browser — `shot: { width, height }` answers with { png } (a
+ * picture of the page once loaded) instead of what the page wrote — 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. */
@@ -162,7 +179,7 @@ export async function runPages(jobs, { timeout = 20 } = {}) {
     try {
       b = await start(exe)
       const results = []
-      for (const { file, mode, query = '' } of jobs) results.push(await open(b, file, mode, query, timeout * 1000))
+      for (const { file, mode = '', query = '', shot } of jobs) results.push(await open(b, file, mode, query, timeout * 1000, shot))
       return { results, used: exe, tried }
     } catch (e) {
       tried.push(`${exe}: ${e instanceof BrowserFailed ? e.message : e.message.split('\n')[0]}`)