@erclx/canon 5.15.0 → 5.17.0

package/src/commands/canvas.ts

@@ -8,8 +8,12 @@ import {
   canvasDir,
   DEFAULT_FRAME,
   listPages,
+  moveFrame,
+  readPage,
+  readSelection,
   renamePage,
 } from '@/canvas/content'
+import { captureCanvas } from '@/canvas/capture'
 import { CANVAS_PORT, startCanvas } from '@/canvas/server'
 import { resolveFrameTokens } from '@/canvas/tokens'
 import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
@@ -34,7 +38,11 @@ interface RootOptions {
 
 interface Refused {
   readonly ok: false
-  readonly reason: ContentRefused['reason'] | 'no-root'
+  readonly reason:
+    | ContentRefused['reason']
+    | 'no-root'
+    | 'no-server'
+    | 'capture-failed'
   readonly detail: string
 }
 
@@ -94,7 +102,7 @@ export function register(program: Command): void {
     .command('canvas')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Local canvas of pages and HTML frames (serve, list, page, frame)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, capture)',
     )
     .addHelpText(
       'after',
@@ -108,6 +116,9 @@ export function register(program: Command): void {
         '  canon canvas serve',
         '  canon canvas page add drafts',
         '  canon canvas frame add drafts hero --width 1440 --height 900',
+        '  canon canvas frame move drafts hero --x 200 --y 120',
+        '  canon canvas selection --json',
+        '  canon canvas capture drafts/hero',
         '  canon canvas list --json',
         '',
       ].join('\n'),
@@ -212,7 +223,7 @@ export function register(program: Command): void {
   const frame = canvas
     .command('frame')
     .helpOption('-h, --help', 'Show this help message')
-    .description('Add a frame to a page')
+    .description('Add a frame to a page, or move one')
 
   withRoot(
     frame
@@ -256,6 +267,192 @@ export function register(program: Command): void {
       outro()
     },
   )
+
+  withRoot(
+    frame
+      .command('move')
+      .description('Move a frame, keeping its size')
+      .argument('<page>', 'Page the frame is on')
+      .argument('<name>', 'Frame name')
+      .option('--x <px>', 'New x, defaulting to where the frame is')
+      .option('--y <px>', 'New y, defaulting to where the frame is'),
+  ).action(
+    async (
+      pageName: string,
+      name: string,
+      opts: RootOptions & { x?: string; y?: string },
+    ) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const current = readPage(root, pageName)?.frames.find(
+        (candidate) => candidate.name === name,
+      )
+      const outcome = moveFrame(root, pageName, name, {
+        x: parsePosition(opts.x, current?.x ?? 0),
+        y: parsePosition(opts.y, current?.y ?? 0),
+      })
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+      if (opts.json) writeJson(outcome)
+      intro(BANNER)
+      logAdd(`${outcome.page}/${outcome.file}`)
+      logInfo(`at ${outcome.box.x}, ${outcome.box.y}`)
+      outro()
+    },
+  )
+
+  withRoot(
+    canvas
+      .command('selection')
+      .description(
+        'Report the frame, or the element in it, the operator selected',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reports none when nothing is selected or when the selected frame has',
+        'since been removed. Read this when the operator says "this one".',
+        '',
+        'An element is named by its index in document order, with the tag,',
+        'classes, and text it had when picked. stale is true once the frame',
+        'file changed since, since the index may then name another element.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOptions) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const selected = readSelection(root)
+      if (opts.json) {
+        writeJson({
+          ok: true,
+          selection: selected
+            ? {
+                ...selected,
+                path: resolve(canvasDir(root), selected.page, selected.file),
+              }
+            : null,
+        })
+      }
+      intro(BANNER)
+      if (!selected) {
+        logStep('Nothing selected')
+      } else {
+        logStep(`${selected.page}/${selected.frame}`)
+        const { box, element } = selected
+        logInfo(`${box.width} × ${box.height} at ${box.x}, ${box.y}`)
+        if (element) {
+          const classes = element.classes.map((name) => `.${name}`).join('')
+          logInfo(
+            `<${element.tag}${classes}> at index ${element.index}: ${element.text}`,
+          )
+          if (element.stale) {
+            logWarn('The frame changed since, so the index may have moved')
+          }
+        }
+      }
+      outro()
+    })
+
+  withRoot(
+    canvas
+      .command('capture')
+      .description('Capture a frame, or every frame of a page, as a PNG')
+      .argument('<target>', '<page>/<frame> for one frame, <page> for all')
+      .option(
+        '-o, --out <path>',
+        'The PNG for a frame, or the folder for a page; defaults to session scratch',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Serves the canvas for the call and captures through that address, so',
+        'the injected tokens are in the PNG and each frame renders at its own',
+        'width. The raw file on disk is never captured.',
+        '',
+        'Exit codes:',
+        '  0  every frame rendered',
+        '  1  refused or a frame failed, with the reason on stderr or in the JSON record',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: RootOptions & { out?: string }) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      let outcome: Awaited<ReturnType<typeof captureCanvas>>
+      try {
+        outcome = await captureCanvas(
+          resolved.root,
+          target,
+          opts.out ? resolve(process.cwd(), opts.out) : undefined,
+        )
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error)
+        process.exitCode = refuse(
+          { ok: false, reason: 'capture-failed', detail },
+          opts.json ?? false,
+        )
+        return
+      }
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+
+      const rows = outcome.captures.map(({ target: item, result }) =>
+        result.status === 'rendered'
+          ? {
+              page: item.page,
+              frame: item.frame,
+              status: result.status,
+              path: result.pngPath,
+              width: result.width,
+              height: result.height,
+            }
+          : {
+              page: item.page,
+              frame: item.frame,
+              status: result.status,
+              reason: result.reason,
+            },
+      )
+      const failed = rows.some((row) => row.status === 'failed')
+      if (opts.json) writeJson({ ok: !failed, captures: rows })
+      intro(BANNER)
+      for (const row of rows) {
+        if (row.status === 'rendered') {
+          logAdd(`${row.page}/${row.frame}`)
+          logInfo(`${displayPath(row.path)} ${row.width}x${row.height}`)
+        } else {
+          logError(`${row.page}/${row.frame}: ${row.reason}`)
+        }
+      }
+      outro()
+      if (failed) process.exitCode = 1
+    })
+}
+
+/** NaN for a value that is not a number, which the content module refuses. */
+function parsePosition(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback
+  return raw.trim() === '' ? Number.NaN : Number(raw)
 }
 
 async function runServe(

package/src/commands/demo.ts

@@ -333,6 +333,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
 
   if (result.videoPath) logInfo(display(result.videoPath))
   if (result.stillPath) logInfo(`${display(result.stillPath)}  still`)
+  if (result.timelinePath) logInfo(`${display(result.timelinePath)}  timeline`)
   logInfo(
     `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
   )
@@ -380,6 +381,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
     mp4: mp4Path ?? null,
     gif: gifPath ?? null,
     still: result.stillPath ?? null,
+    timeline: result.timelinePath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
     ...(mp4Reason ? { mp4Reason } : {}),

package/src/commands/migrate.ts

@@ -1222,7 +1222,7 @@ export function register(program: Command): void {
         '',
         'The changelog is never rewritten. Its entries record what shipped',
         'under the old name, and GitHub redirects the links they carry.',
-        'aitk-sandbox is a separate repository and is left alone.',
+        'aitk-sandbox, the old name of erclx/canon-sandbox, is left alone.',
         '',
         'Examples:',
         '  canon migrate rename',

package/src/commands/teach.ts

@@ -237,7 +237,9 @@ export function register(program: Command): void {
         'only place a later session reads that from.',
         '',
         'A URL already listed under either heading is refused rather than',
-        'repeated, because two entries split what rests on one source.',
+        'repeated, because two entries split what rests on one source. The one',
+        'exception is a --read URL listed under Leads, which moves to Read under',
+        'its new title.',
         '',
         'Examples:',
         '  canon teach resource regular-expressions --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions"',

package/src/demo/drive.ts

@@ -8,6 +8,8 @@ import { deriveSteps } from '@/demo/compile'
 import type { DemoPlan, DemoStep } from '@/demo/compile'
 import type { CursorSet } from '@/demo/pointer'
 import { pointerSource } from '@/demo/pointer'
+import type { StepTiming, TargetBox } from '@/demo/timeline'
+import { timelineEntry, timelinePath, writeTimeline } from '@/demo/timeline'
 
 declare global {
   interface Window {
@@ -84,6 +86,7 @@ export type DriveResult =
       status: 'recorded'
       videoPath?: string
       stillPath?: string
+      timelinePath?: string
       steps: number
       durationMs: number
     }
@@ -150,6 +153,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 
   let stillPath: string | undefined
   let videoPath: string | undefined
+  let timeline: string | undefined
 
   try {
     await context.addInitScript({
@@ -157,7 +161,12 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     })
     await context.addInitScript({ content: captionInitScript() })
     const page = await context.newPage()
+    // The recording begins with the page, so this is the instant a frame of
+    // the take is zero. Taking it at the first step instead would drift every
+    // entry by the opening page load.
+    const recordingStart = performance.now()
     const video = page.video()
+    const timings: StepTiming[] = []
     const pace: PointerPace = {}
 
     // The opening navigate is skipped when the plan already starts with one,
@@ -170,8 +179,16 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       }
     }
 
-    for (const step of plan.steps) {
-      await runStep(page, plan, step, pace)
+    for (const [index, step] of plan.steps.entries()) {
+      const startedAt = performance.now()
+      const box = await runStep(page, plan, step, pace)
+      timings.push({
+        index,
+        kind: step.kind,
+        startedAt,
+        endedAt: performance.now(),
+        ...(box ? { box } : {}),
+      })
       // The first marked step wins. One file holds one frame, so a plan a
       // person edited to mark several would otherwise write each over the last
       // and keep whichever ran last, with nothing saying so.
@@ -191,6 +208,11 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       // The engine keeps the auto-named recording beside the saved copy, so a
       // run that skipped this would leave two files for every demo.
       await video.delete()
+      timeline = timelinePath(videoPath)
+      writeTimeline(
+        timeline,
+        timings.map((timing) => timelineEntry(timing, recordingStart)),
+      )
     }
   } catch (error) {
     return failed('drive-failed', error)
@@ -203,6 +225,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     status: 'recorded',
     ...(videoPath ? { videoPath } : {}),
     ...(stillPath ? { stillPath } : {}),
+    ...(timeline ? { timelinePath: timeline } : {}),
     steps: plan.steps.length,
     durationMs: Date.now() - started,
   }
@@ -237,13 +260,17 @@ export interface PointerPace {
  * Exported so `drive.e2e.test.ts` can drive one real step against a real
  * caption and read it back, which is the integration a full `drive()` call
  * cannot assert without decoding the video it writes.
+ *
+ * Returns the box the pointer moved to, for the timeline, and nothing for
+ * a step that points at no target.
  */
 export async function runStep(
   page: Page,
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox | undefined> {
+  let box: TargetBox | undefined
   switch (step.kind) {
     case 'navigate':
       await page.goto(step.target || plan.url)
@@ -252,18 +279,18 @@ export async function runStep(
       }
       break
     case 'click':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       break
     case 'fill':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       await page.keyboard.type(step.text, { delay: plan.pointer.typeDelayMs })
       break
     case 'hover':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       break
     case 'scroll':
       // Centred rather than `scrollIntoViewIfNeeded`, which scrolls the least
@@ -307,6 +334,7 @@ export async function runStep(
   await setCaption(page, step.caption)
   if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
   await page.waitForTimeout(step.holdMs)
+  return box
 }
 
 /**
@@ -333,7 +361,7 @@ async function moveTo(
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox> {
   pace.roundTripMs ??= await calibrateRoundTrip(page)
   const locator = page.locator(step.target).first()
   await locator.waitFor()
@@ -342,6 +370,7 @@ async function moveTo(
   await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, {
     steps: deriveSteps(plan.pointer.travelMs, pace.roundTripMs),
   })
+  return box
 }
 
 /**

package/src/demo/timeline.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+import type { DemoStep } from '@/demo/compile'
+
+/**
+ * A step's target in viewport pixels, which are the video frame's own
+ * coordinates because the recording is sized to the viewport.
+ */
+export interface TargetBox {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** One step as the run clocked it, in wall-clock milliseconds. */
+export interface StepTiming {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startedAt: number
+  readonly endedAt: number
+  readonly box?: TargetBox
+}
+
+/**
+ * Times count from the recording's start rather than the first step, since
+ * that is the clock a composition places the take on. A step ends once its
+ * hold has played, so the span covers what the viewer sees of it.
+ */
+export interface TimelineEntry {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startMs: number
+  readonly endMs: number
+  readonly box?: TargetBox
+}
+
+export function timelineEntry(
+  timing: StepTiming,
+  recordingStart: number,
+): TimelineEntry {
+  return {
+    index: timing.index,
+    kind: timing.kind,
+    startMs: Math.round(timing.startedAt - recordingStart),
+    endMs: Math.round(timing.endedAt - recordingStart),
+    ...(timing.box ? { box: timing.box } : {}),
+  }
+}
+
+export function timelinePath(videoPath: string): string {
+  return join(
+    dirname(videoPath),
+    `${basename(videoPath, extname(videoPath))}.timeline.json`,
+  )
+}
+
+export function writeTimeline(
+  path: string,
+  entries: readonly TimelineEntry[],
+): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify({ entries }, null, 2)}\n`)
+}

package/src/migrate/rename.ts

@@ -168,10 +168,11 @@ const AITK_ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
 /**
  * The `aitk` to `canon` rename.
  *
- * `aitk-sandbox` is a separate repository that is not being renamed. It has to
- * win against the bare token, and it also has to win against the owner-scoped
- * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
- * `erclx/canon-sandbox` and name a repository that does not exist.
+ * `aitk-sandbox` is the retired spelling of a repository that was later renamed
+ * `canon-sandbox`, and GitHub still resolves the old name through a redirect.
+ * It has to win against the bare token, and it also has to win against the
+ * owner-scoped spelling, so a consumer's text naming `erclx/aitk-sandbox` keeps
+ * the form that resolves rather than being rewritten.
  *
  * Case is carried in the map rather than derived, because the uppercase form
  * is an environment variable prefix and the title-case form is a heading word,

package/src/teach/browser/compile.ts

@@ -0,0 +1,44 @@
+type BrowserFunction = (...args: never[]) => unknown
+
+const transpiler = new Bun.Transpiler({ loader: 'ts' })
+
+const MODULE_SYNTAX = /^\s*(import|export)\b/m
+
+/**
+ * `</script>` inside a serialized argument would end the block early, and
+ * `<` is the same character to the JavaScript parser.
+ */
+function serialize(args: readonly unknown[]): string {
+  return JSON.stringify(args).slice(1, -1).replace(/</g, '\\u003c')
+}
+
+/**
+ * Turns a browser module's function into the `<script>` a page carries. The
+ * transpiler does not bundle, so a module is self-contained: whatever it
+ * calls but does not define arrives as a named function in `helpers`, and a
+ * value it needs arrives in `args`. Output holding module syntax throws, since
+ * a script block with an `import` fails in the browser with nothing in the
+ * type checker to say so.
+ */
+export function compileScript(
+  run: BrowserFunction,
+  args: readonly unknown[] = [],
+  helpers: readonly BrowserFunction[] = [],
+): string {
+  const source = helpers.length
+    ? `(function () {\n${helpers.map(String).join('\n')}\nreturn ${run};\n})()`
+    : String(run)
+  // A bare expression statement is dead code to the transpiler and comes back
+  // empty, so the source rides an export that it must keep.
+  const code = transpiler
+    .transformSync(`export default ${source}`)
+    .trim()
+    .replace(/^export default /, '')
+    .replace(/;$/, '')
+
+  if (MODULE_SYNTAX.test(code)) {
+    throw new Error(`Browser module ${run.name} left import or export syntax`)
+  }
+
+  return `<script>(${code})(${serialize(args)})</script>`
+}

package/src/teach/browser/dismiss.ts

@@ -0,0 +1,76 @@
+export function dismiss(): void {
+  var MENUS = 'details.jump[open], details.sb-ws[open]'
+
+  function close(except: Element | null) {
+    document.querySelectorAll<HTMLDetailsElement>(MENUS).forEach(function (d) {
+      if (d !== except) d.open = false
+    })
+  }
+  document.addEventListener('click', function (e) {
+    var inside = (e.target as Element).closest('details.jump, details.sb-ws')
+    close(inside)
+  })
+  document.addEventListener('keydown', function (e) {
+    if (e.key !== 'Escape') return
+    var open = document.querySelector<HTMLDetailsElement>(MENUS)
+    if (!open) return
+    open.open = false
+    var s = open.querySelector('summary')
+    if (s) s.focus()
+  })
+
+  /* Hover intent on the breadcrumb only. The sidebar's workspace switcher stays
+     click-only on purpose: its panel opens directly over the lesson list, which
+     is where the pointer is headed, so hovering it would cover the thing
+     being reached for. The breadcrumb's panel drops over body text instead. */
+  var OPEN = 120,
+    SHUT = 260
+
+  document
+    .querySelectorAll<HTMLDetailsElement>('details.jump')
+    .forEach(function (d) {
+      var host = d.closest('.crumb-item') || d
+      var timer: ReturnType<typeof setTimeout> | undefined
+      var openedByHover = false
+
+      function arm(want: boolean) {
+        clearTimeout(timer)
+        timer = setTimeout(
+          function () {
+            if (want) close(d)
+            d.open = want
+          },
+          want ? OPEN : SHUT,
+        )
+      }
+
+      host.addEventListener('mouseenter', function () {
+        if (!d.open) openedByHover = true
+        arm(true)
+      })
+      host.addEventListener('mouseleave', function () {
+        openedByHover = false
+        arm(false)
+      })
+      /* Keeps it open while the pointer is inside the panel, without cancelling a
+       pending open, which is what silently disabled this on one of two menus. */
+      d.addEventListener('mouseenter', function () {
+        if (d.open) clearTimeout(timer)
+      })
+
+      /* Hover and click were wired to one disclosure and fought: hover opened the
+       panel, then the summary's native click toggled what hover had already
+       opened, so reaching for an item shut it. A click on a panel hover opened
+       keeps it open, and a second click closes. The click path stays live for
+       touch, where no hover exists, and for the keyboard, where Enter is the
+       only way in. */
+      var summary = d.querySelector('summary')
+      if (summary)
+        summary.addEventListener('click', function (e) {
+          if (d.open && openedByHover) {
+            e.preventDefault()
+            openedByHover = false
+          }
+        })
+    })
+}

package/src/teach/browser/focus-line.ts

@@ -0,0 +1,19 @@
+/**
+ * The outline rail's focus-line ramp. It runs from near the top at scroll 0 to
+ * the viewport's bottom edge at max scroll, so the last heading is reachable
+ * however little content trails it. A ramp ending 120px short of the edge left
+ * a heading with under 120px after it permanently unmarked, since its top never
+ * fell below the line even at max scroll.
+ *
+ * The sidebar script embeds this function's own source, so a test exercises
+ * what the browser runs.
+ */
+export function focusLine(
+  scrollY: number,
+  max: number,
+  innerHeight: number,
+): number {
+  if (max <= 0) return innerHeight
+  var progress = Math.min(1, Math.max(0, scrollY / max))
+  return 120 + progress * Math.max(0, innerHeight - 120)
+}