@erclx/canon 4.0.0

package/src/demo/drive.ts

@@ -0,0 +1,357 @@
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { chromium } from 'playwright-core'
+import type { Browser, BrowserContext, Page } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
+import { deriveSteps } from '@/demo/compile'
+import type { DemoPlan, DemoStep } from '@/demo/compile'
+import type { CursorSet } from '@/demo/pointer'
+import { pointerSource } from '@/demo/pointer'
+
+declare global {
+  interface Window {
+    __canon_demo_caption__?: (text: string) => void
+  }
+}
+
+/**
+ * Drives a running application and records what it did. Every browser reference
+ * the demo feature adds lives here, and `src/commands/demo.ts` reaches it
+ * through a dynamic import so no other command resolves the engine at startup.
+ *
+ * Unlike `@/capture/render`, this module ships. The capture command is excluded
+ * from the published package because it regenerates images committed to this
+ * repository, and that reason does not transfer to a command whose whole
+ * purpose is running in someone else's project.
+ *
+ * It imports `playwright-core` rather than `@playwright/test`, which stays a
+ * development dependency for the capture module. Shipping puts the import in
+ * every target's dependency tree, and a target needs the driver rather than a
+ * test runner and an assertion library. Both are pinned to one version rather
+ * than a range, because `bunx playwright install chromium` fetches the browser
+ * revision the installed engine expects and a float would leave a target
+ * resolving a binary its engine cannot launch.
+ */
+
+const POINTER_SIZE = 32
+/**
+ * Where the pointer starts. Any position inside the viewport works, since the
+ * point is giving it one move to install and paint before it travels to the
+ * first target. A corner keeps that first move out of the way of the content.
+ */
+const START = { x: 8, y: 8 }
+const SETTLE_MS = 250
+/** Round trips sampled to price one, on the page a step is actually about to move across. */
+const CALIBRATION_STEPS = 8
+/** DOM id the caption bar installs under, read back by `drive.e2e.test.ts`. */
+export const CAPTION_ID = '__canon_demo_caption_bar__'
+
+/**
+ * The two output paths arrive resolved rather than as a root this re-resolves
+ * against, because the plan already carries a directory and resolving it twice
+ * nests the whole path inside itself.
+ *
+ * An absent path means the caller asked for that artifact not to be produced.
+ */
+export interface DriveOptions {
+  readonly plan: DemoPlan
+  readonly cursors: CursorSet
+  readonly videoPath?: string
+  readonly stillPath?: string
+}
+
+export type DriveResult =
+  | {
+      status: 'recorded'
+      videoPath?: string
+      stillPath?: string
+      steps: number
+      durationMs: number
+    }
+  | { status: 'failed'; reason: DriveRefusal; message: string }
+
+export type DriveRefusal = 'browser-missing' | 'drive-failed'
+
+interface DriveFailure {
+  readonly status: 'failed'
+  readonly reason: DriveRefusal
+  readonly message: string
+}
+
+type Launch = { status: 'launched'; value: Browser } | DriveFailure
+
+export async function drive(options: DriveOptions): Promise<DriveResult> {
+  const { plan } = options
+
+  const browser = await launch()
+  if (browser.status === 'failed') return browser
+
+  let videoDir: string | undefined
+  let context: BrowserContext
+  const started = Date.now()
+  try {
+    // Created after the launch, so a target with no browser binary does not
+    // leave an empty directory behind for a run that never started, and inside
+    // the try so a failure here closes the browser rather than leaking it.
+    videoDir = options.videoPath
+      ? mkdtempSync(join(tmpdir(), 'canon-demo-'))
+      : undefined
+
+    context = await browser.value.newContext({
+      viewport: plan.viewport,
+      // Pointed the opposite way from a test. A recording wants the motion the
+      // interface was designed with, where a test wants it suppressed.
+      reducedMotion: 'no-preference',
+      ...(videoDir
+        ? {
+            recordVideo: {
+              dir: videoDir,
+              size: plan.viewport,
+              showActions: {
+                duration: plan.annotations.durationMs,
+                position: plan.annotations.position,
+                fontSize: plan.annotations.fontSize,
+              },
+            },
+          }
+        : {}),
+    })
+  } catch (error) {
+    await browser.value.close()
+    if (videoDir) rmSync(videoDir, { recursive: true, force: true })
+    return failed('drive-failed', error)
+  }
+
+  let stillPath: string | undefined
+  let videoPath: string | undefined
+
+  try {
+    await context.addInitScript({
+      content: pointerSource(options.cursors, POINTER_SIZE),
+    })
+    await context.addInitScript({ content: captionInitScript() })
+    const page = await context.newPage()
+    const video = page.video()
+    const pace: PointerPace = {}
+
+    // The opening navigate is skipped when the plan already starts with one,
+    // because a draft written around an opening verb compiles to a `navigate`
+    // step for the same URL and the second load is a visible reload.
+    if (plan.steps[0]?.kind !== 'navigate') {
+      await page.goto(plan.url)
+      await page.mouse.move(START.x, START.y, { steps: 2 })
+    }
+
+    for (const step of plan.steps) {
+      await runStep(page, plan, step, pace)
+      // 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.
+      if (step.still && options.stillPath && !stillPath) {
+        stillPath = options.stillPath
+        mkdirSync(dirname(stillPath), { recursive: true })
+        await page.screenshot({ path: stillPath })
+      }
+    }
+
+    await context.close()
+
+    if (video && options.videoPath) {
+      videoPath = options.videoPath
+      mkdirSync(dirname(videoPath), { recursive: true })
+      await video.saveAs(videoPath)
+      // 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()
+    }
+  } catch (error) {
+    return failed('drive-failed', error)
+  } finally {
+    await browser.value.close()
+    if (videoDir) rmSync(videoDir, { recursive: true, force: true })
+  }
+
+  return {
+    status: 'recorded',
+    ...(videoPath ? { videoPath } : {}),
+    ...(stillPath ? { stillPath } : {}),
+    steps: plan.steps.length,
+    durationMs: Date.now() - started,
+  }
+}
+
+/**
+ * Reads the launch through `@/browser/engine`, which is where the separation
+ * between a binary that was never installed and every other launch failure now
+ * lives. It moved out of this file when `canon inventory` became the second
+ * command needing it, rather than being copied.
+ */
+async function launch(): Promise<Launch> {
+  try {
+    return { status: 'launched', value: await chromium.launch() }
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'drive-failed',
+      error,
+    )
+  }
+}
+
+/**
+ * Holds the round trip once a step has measured it, so every `moveTo` after
+ * the first reuses the same reading rather than re-timing on every move.
+ */
+export interface PointerPace {
+  roundTripMs?: number
+}
+
+/**
+ * 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.
+ */
+export async function runStep(
+  page: Page,
+  plan: DemoPlan,
+  step: DemoStep,
+  pace: PointerPace,
+): Promise<void> {
+  switch (step.kind) {
+    case 'navigate':
+      await page.goto(step.target || plan.url)
+      await page.mouse.move(START.x, START.y, { steps: 2 })
+      break
+    case 'click':
+      await moveTo(page, plan, step, pace)
+      await page.mouse.down()
+      await page.mouse.up()
+      break
+    case 'fill':
+      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)
+      break
+    case 'scroll':
+      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      await page.waitForTimeout(SETTLE_MS)
+      await moveTo(page, plan, step, pace)
+      break
+    case 'wait':
+    case 'hold':
+      break
+  }
+
+  // Set after the action rather than before it, so the caption shows for the
+  // hold that follows rather than for the page the action is about to leave.
+  await setCaption(page, step.caption)
+  if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
+  await page.waitForTimeout(step.holdMs)
+}
+
+/**
+ * Timed on the page a `moveTo` is actually about to move across, never on the
+ * blank page before it, since layout, paint, and page script are what a step
+ * pays the round trip against and a blank page has none of the three.
+ */
+async function calibrateRoundTrip(page: Page): Promise<number> {
+  const startedAt = Date.now()
+  await page.mouse.move(START.x, START.y, { steps: CALIBRATION_STEPS })
+  return (Date.now() - startedAt) / CALIBRATION_STEPS
+}
+
+/**
+ * Travel is the whole point of driving the engine's pointer rather than calling
+ * the element-clicking helper, which resolves a target and jumps to it. The
+ * step count is what separates a cursor that glides from one that teleports.
+ *
+ * Resolving through a bounding box assumes the target is in the viewport, so a
+ * target below the fold needs a `scroll` step ahead of it.
+ */
+async function moveTo(
+  page: Page,
+  plan: DemoPlan,
+  step: DemoStep,
+  pace: PointerPace,
+): Promise<void> {
+  pace.roundTripMs ??= await calibrateRoundTrip(page)
+  const locator = page.locator(step.target).first()
+  await locator.waitFor()
+  const box = await locator.boundingBox()
+  if (!box) throw new Error(`${step.target} has no box to point at`)
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, {
+    steps: deriveSteps(plan.pointer.travelMs, pace.roundTripMs),
+  })
+}
+
+/**
+ * Playwright's own `showActions` overlay names the API call it made, not the
+ * beat's narration, so a caption needs an element of its own rather than
+ * reusing that annotation. Runs alongside `pointerSource`, guarded the same
+ * way against a page that already carries one.
+ */
+export function captionInitScript(): string {
+  return `(() => {
+  if (window.__canon_demo_caption__) return;
+
+  let label;
+
+  const install = () => {
+    if (label || !document.body) return;
+    const bar = document.createElement('div');
+    bar.id = '${CAPTION_ID}';
+    bar.setAttribute('aria-hidden', 'true');
+    bar.style.cssText = [
+      'position:fixed',
+      'left:0',
+      'right:0',
+      'bottom:32px',
+      'display:flex',
+      'justify-content:center',
+      'pointer-events:none',
+      'z-index:2147483647',
+    ].join(';');
+    label = document.createElement('span');
+    label.style.cssText = [
+      'background:rgba(16,16,20,0.85)',
+      'color:#f4f4f5',
+      'font:600 20px/1.4 system-ui,sans-serif',
+      'padding:10px 22px',
+      'border-radius:8px',
+      'max-width:80vw',
+      'text-align:center',
+      'display:none',
+    ].join(';');
+    bar.appendChild(label);
+    document.body.appendChild(bar);
+    window.__canon_demo_caption__ = (text) => {
+      label.textContent = text || '';
+      label.style.display = text ? 'inline-block' : 'none';
+    };
+  };
+
+  if (document.readyState === 'loading') {
+    addEventListener('DOMContentLoaded', install, { once: true });
+  } else {
+    install();
+  }
+})();`
+}
+
+async function setCaption(page: Page, caption: string): Promise<void> {
+  await page.evaluate((text) => {
+    window.__canon_demo_caption__?.(text)
+  }, caption)
+}
+
+function failed(reason: DriveRefusal, error: unknown): DriveFailure {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}

package/src/demo/pointer.ts

@@ -0,0 +1,178 @@
+/**
+ * The pointer the recording shows. The browser engine's own annotation draws a
+ * dot at the moment of a click and paints no cursor, so a run without this
+ * looks like the pointer teleports between targets.
+ *
+ * Nothing here touches a browser. `pointerSource` returns the script text that
+ * `@/demo/drive` installs before navigation, which keeps the hotspot arithmetic
+ * and the state table testable without launching anything.
+ */
+
+export interface CursorHotspot {
+  readonly width: number
+  readonly height: number
+  readonly hotspotX: number
+  readonly hotspotY: number
+}
+
+export interface Cursor {
+  readonly image: string
+  readonly hotspot: CursorHotspot
+}
+
+export type CursorSet = Readonly<Record<string, Cursor>>
+
+const HEADER_BYTES = 6
+const ENTRY_BYTES = 16
+const CURSOR_TYPE = 2
+/** The format stores 256 as a zero, since the field is one byte wide. */
+const SIZE_256 = 256
+
+/**
+ * Reads the directory of a Windows cursor resource and returns the hotspot of
+ * its largest entry. A resource carries several sizes with a hotspot each, and
+ * taking the largest is what matches the artwork the recorder draws at.
+ *
+ * Only the header and directory are read. The pixel payload is left to the
+ * browser, which spike 3 measured as decoding the format directly with no
+ * conversion step and no image tooling on the machine.
+ */
+export function cursorHotspot(bytes: Uint8Array): CursorHotspot | undefined {
+  if (bytes.byteLength < HEADER_BYTES + ENTRY_BYTES) return undefined
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (view.getUint16(2, true) !== CURSOR_TYPE) return undefined
+
+  const count = view.getUint16(4, true)
+  if (count === 0) return undefined
+
+  let largest: CursorHotspot | undefined
+  for (let index = 0; index < count; index += 1) {
+    const at = HEADER_BYTES + index * ENTRY_BYTES
+    if (at + ENTRY_BYTES > bytes.byteLength) break
+
+    const entry: CursorHotspot = {
+      width: bytes[at] === 0 ? SIZE_256 : (bytes[at] ?? 0),
+      height: bytes[at + 1] === 0 ? SIZE_256 : (bytes[at + 1] ?? 0),
+      hotspotX: view.getUint16(at + 4, true),
+      hotspotY: view.getUint16(at + 6, true),
+    }
+    if (!largest || entry.width * entry.height > largest.width * largest.height)
+      largest = entry
+  }
+  return largest
+}
+
+/**
+ * Converts a hotspot stated against the source artwork into an offset in the
+ * size the pointer is drawn at. Skipping this puts the artwork's top left where
+ * the click lands instead of its tip, which offsets every action by roughly a
+ * third of a cursor.
+ */
+export function scaleHotspot(
+  hotspot: CursorHotspot,
+  drawnSize: number,
+): { x: number; y: number } {
+  const scale = drawnSize / hotspot.width
+  return {
+    x: hotspot.hotspotX * scale,
+    y: hotspot.hotspotY * (drawnSize / hotspot.height),
+  }
+}
+
+interface PointerState {
+  readonly image: string
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * Returns the script installed before navigation. It is a string rather than a
+ * function reference because the cursor payload is data resolved on this side,
+ * and passing artwork through an argument would still need serializing.
+ *
+ * The element inherits the page's world, so a site with its own element at this
+ * id, a stacking context that outranks it, or a style rule reaching it will
+ * interfere. That is the cost of drawing the pointer inside the page rather
+ * than reaching for a desktop recorder.
+ */
+export function pointerSource(cursors: CursorSet, size: number): string {
+  const states: Record<string, PointerState> = {}
+  for (const [name, cursor] of Object.entries(cursors)) {
+    const offset = scaleHotspot(cursor.hotspot, size)
+    states[name] = { image: cursor.image, x: offset.x, y: offset.y }
+  }
+
+  const config = JSON.stringify({ size, states })
+
+  return `(() => {
+  const CONFIG = ${config};
+  const ID = '__canon_demo_pointer__';
+  if (window[ID]) return;
+  window[ID] = true;
+
+  let node;
+  let state = 'default';
+  let pressed = false;
+  let x = -9999;
+  let y = -9999;
+
+  const install = () => {
+    if (node || !document.body) return;
+    node = document.createElement('img');
+    node.id = ID;
+    node.setAttribute('aria-hidden', 'true');
+    node.style.cssText = [
+      'position:fixed',
+      'left:0',
+      'top:0',
+      'width:' + CONFIG.size + 'px',
+      'height:' + CONFIG.size + 'px',
+      'z-index:2147483647',
+      'pointer-events:none',
+      'user-select:none',
+      'will-change:transform',
+      'transition:transform 90ms ease-out',
+    ].join(';');
+    document.body.appendChild(node);
+    paint();
+  };
+
+  const paint = () => {
+    if (!node) return;
+    const cursor = CONFIG.states[state] || CONFIG.states.default;
+    if (!cursor) return;
+    if (node.getAttribute('src') !== cursor.image) node.setAttribute('src', cursor.image);
+    const scale = pressed ? 0.88 : 1;
+    node.style.transform =
+      'translate(' + (x - cursor.x) + 'px,' + (y - cursor.y) + 'px) scale(' + scale + ')';
+  };
+
+  const stateAt = (target) => {
+    if (!(target instanceof Element)) return 'default';
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || target.isContentEditable) return 'text';
+    const style = getComputedStyle(target).cursor;
+    if (style === 'pointer' && CONFIG.states.pointer) return 'pointer';
+    if (style === 'text' && CONFIG.states.text) return 'text';
+    return 'default';
+  };
+
+  addEventListener('mousemove', (event) => {
+    x = event.clientX;
+    y = event.clientY;
+    state = stateAt(event.target);
+    install();
+    paint();
+  }, true);
+
+  addEventListener('mousedown', () => { pressed = true; paint(); }, true);
+  addEventListener('mouseup', () => { pressed = false; paint(); }, true);
+
+  if (document.readyState === 'loading') {
+    addEventListener('DOMContentLoaded', install, { once: true });
+  } else {
+    install();
+  }
+})();`
+}

package/src/demo/theme.ts

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cursorHotspot, type Cursor, type CursorSet } from '@/demo/pointer'
+
+/**
+ * Reads a cursor theme folder so `--cursor` can point at one. Spike 3 measured
+ * the browser decoding a Windows cursor resource directly, so nothing here
+ * converts anything: the bytes go into a data URI and the header supplies the
+ * hotspot.
+ *
+ * Three of the nineteen states a theme carries are read. A drag, a resize, or a
+ * wait shows the default arrow where a real session would show something else,
+ * and the two animated states have no still frame to draw at all.
+ */
+
+const CURSOR_MIME = 'image/x-icon'
+const EXTENSION = /\.cur$/i
+
+/** Ordered per state, most specific first, so an exact name beats a longer one. */
+const NAMES: Record<string, readonly string[]> = {
+  default: ['arrow', 'normal', 'default'],
+  pointer: ['link', 'hand', 'pointer'],
+  text: ['ibeam', 'beam', 'text'],
+}
+
+export type CursorFiles = Partial<Record<string, string>>
+
+/**
+ * Picks one file per state out of a directory listing. Matching runs on the
+ * name rather than on the contents because a theme states its intent there, and
+ * a shorter match wins so `Arrow.cur` beats `Arrow Alternate.cur`.
+ */
+export function matchCursorFiles(files: readonly string[]): CursorFiles {
+  const cursors = files.filter((file) => EXTENSION.test(file))
+  const matched: CursorFiles = {}
+
+  for (const [state, names] of Object.entries(NAMES)) {
+    const found = names
+      .flatMap((name) =>
+        cursors.filter((file) => file.toLowerCase().includes(name)),
+      )
+      .sort((left, right) => left.length - right.length)[0]
+    if (found) matched[state] = found
+  }
+
+  return matched
+}
+
+export type ThemeLoad =
+  | { status: 'loaded'; cursors: CursorSet; states: string[] }
+  | { status: 'failed'; reason: string }
+
+/**
+ * Falls back to the bundled artwork per state rather than per theme, so a
+ * folder carrying an arrow and no hand still contributes its arrow.
+ */
+export function loadCursorTheme(dir: string, fallback: CursorSet): ThemeLoad {
+  let listing: string[]
+  try {
+    listing = readdirNames(dir)
+  } catch (error) {
+    return {
+      status: 'failed',
+      reason: `${dir} could not be read: ${message(error)}`,
+    }
+  }
+
+  const matched = matchCursorFiles(listing)
+  const states = Object.keys(matched)
+  if (!states.length) {
+    return {
+      status: 'failed',
+      reason: `${dir} holds no .cur file named after a pointer, link, or text state`,
+    }
+  }
+
+  const cursors: Record<string, Cursor> = { ...fallback }
+  for (const [state, file] of Object.entries(matched)) {
+    if (!file) continue
+    const loaded = readCursor(join(dir, file))
+    if (loaded) cursors[state] = loaded
+  }
+
+  return { status: 'loaded', cursors, states }
+}
+
+function readCursor(path: string): Cursor | undefined {
+  let bytes: Uint8Array
+  try {
+    bytes = readFileSync(path)
+  } catch {
+    return undefined
+  }
+
+  const hotspot = cursorHotspot(bytes)
+  if (!hotspot) return undefined
+
+  return {
+    image: `data:${CURSOR_MIME};base64,${Buffer.from(bytes).toString('base64')}`,
+    hotspot,
+  }
+}
+
+function readdirNames(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}