@erclx/aitk 3.6.0 → 3.8.0

package/src/demo/compile.ts

@@ -0,0 +1,295 @@
+import type { Beat, Draft } from '@/demo/beats'
+
+/**
+ * Turns the human-facing draft into the machine-facing plan. The two are
+ * separate artifacts on purpose: a beat carries no target, no wait condition,
+ * and no timing, and putting those four fields on every beat would destroy the
+ * property the draft was designed around. See
+ * `.claude/groundwork/demo-recorder/06-decision.md`.
+ *
+ * A compiled plan is committed rather than scratch, because the timing below is
+ * a starting point the operator tunes and the draft cannot reproduce a tuned
+ * value.
+ */
+
+/** Hand-tuned in spike 2 against one fixture. Nothing establishes them in general. */
+const POINTER_STEPS = 45
+const TYPE_DELAY_MS = 110
+const HOLD_MS = 600
+const FINAL_HOLD_MS = 1200
+
+const VIEWPORT = { width: 1280, height: 720 } as const
+const ANNOTATIONS = {
+  durationMs: 900,
+  position: 'bottom-right',
+  fontSize: 22,
+} as const
+
+export type StepKind =
+  | 'navigate'
+  | 'click'
+  | 'fill'
+  | 'hover'
+  | 'scroll'
+  | 'wait'
+  | 'hold'
+
+/** Verbs that point at an element, so a plan without a target cannot run. */
+const TARGETED: ReadonlySet<StepKind> = new Set<StepKind>([
+  'click',
+  'fill',
+  'hover',
+  'scroll',
+])
+
+const VERBS: Record<string, StepKind> = {
+  navigate: 'navigate',
+  open: 'navigate',
+  visit: 'navigate',
+  load: 'navigate',
+  click: 'click',
+  press: 'click',
+  tap: 'click',
+  submit: 'click',
+  toggle: 'click',
+  type: 'fill',
+  fill: 'fill',
+  enter: 'fill',
+  input: 'fill',
+  hover: 'hover',
+  scroll: 'scroll',
+  wait: 'wait',
+  pause: 'wait',
+  settle: 'wait',
+}
+
+export interface DemoStep {
+  readonly beat: number
+  readonly name: string
+  readonly kind: StepKind
+  readonly target: string
+  readonly text: string
+  readonly waitFor: string
+  readonly holdMs: number
+  readonly caption: string
+  readonly still: boolean
+  readonly note?: string
+}
+
+export interface DemoPlan {
+  readonly slug: string
+  readonly title: string
+  readonly url: string
+  readonly viewport: { readonly width: number; readonly height: number }
+  readonly output: { readonly video: string; readonly still: string }
+  readonly pointer: { readonly steps: number; readonly typeDelayMs: number }
+  readonly annotations: typeof ANNOTATIONS
+  readonly steps: readonly DemoStep[]
+}
+
+export interface CompileOptions {
+  readonly slug: string
+  readonly outDir: string
+}
+
+export function compilePlan(draft: Draft, options: CompileOptions): DemoPlan {
+  const stillAt = heroIndex(draft.beats)
+  return {
+    slug: options.slug,
+    title: draft.title,
+    url: '',
+    viewport: VIEWPORT,
+    output: {
+      video: `${options.outDir}/${options.slug}.webm`,
+      still: `${options.outDir}/${options.slug}.png`,
+    },
+    pointer: { steps: POINTER_STEPS, typeDelayMs: TYPE_DELAY_MS },
+    annotations: ANNOTATIONS,
+    steps: draft.beats.map((beat, position) =>
+      compileStep(beat, {
+        still: position === stillAt,
+        last: position === draft.beats.length - 1,
+      }),
+    ),
+  }
+}
+
+function compileStep(
+  beat: Beat,
+  place: { still: boolean; last: boolean },
+): DemoStep {
+  const verb = firstVerb(beat.action)
+  const kind = verb ? VERBS[verb] : undefined
+  const step: DemoStep = {
+    beat: beat.index,
+    name: beat.name,
+    kind: kind ?? 'hold',
+    target: '',
+    text: '',
+    waitFor: '',
+    holdMs: place.last ? FINAL_HOLD_MS : HOLD_MS,
+    caption: beat.caption,
+    still: place.still,
+  }
+
+  if (kind) return step
+  return {
+    ...step,
+    note: `no step maps to the verb "${beat.action.trim()}", so this beat only waits`,
+  }
+}
+
+/**
+ * The draft specifies one verb per beat, and a hand-edited beat reads as a
+ * phrase often enough that matching only the whole field would refuse work a
+ * reader can see is a click. The first recognized word wins.
+ */
+function firstVerb(action: string): string | undefined {
+  return action
+    .toLowerCase()
+    .split(/[^a-z]+/)
+    .find((word) => word in VERBS)
+}
+
+/**
+ * The still is a landing frame, so it wants the beat the draft calls the hero
+ * rather than an arbitrary one. Falling back to the last beat rather than the
+ * first is deliberate: a demo's final state is the payoff, and a cold open is
+ * usually an empty screen.
+ */
+function heroIndex(beats: readonly Beat[]): number {
+  const named = beats.findIndex((beat) => /hero/i.test(beat.name))
+  return named === -1 ? beats.length - 1 : named
+}
+
+export type PlanParse =
+  | { status: 'parsed'; plan: DemoPlan }
+  | { status: 'failed'; reason: string }
+
+/**
+ * Validates a plan read off disk. The file is hand-edited between being
+ * compiled and being run, which is the whole reason it is committed rather than
+ * regenerated, so every field is checked here rather than trusted.
+ *
+ * An absent field takes the seeded default and a present one is kept, so a
+ * plan that dropped a timing block still runs while a tuned one is never
+ * overwritten.
+ */
+export function parsePlan(text: string): PlanParse {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch (error) {
+    return {
+      status: 'failed',
+      reason: error instanceof Error ? error.message : 'unreadable json',
+    }
+  }
+
+  if (!isRecord(raw)) return { status: 'failed', reason: 'not a json object' }
+  if (!Array.isArray(raw.steps))
+    return { status: 'failed', reason: 'steps is not an array' }
+  if (!raw.steps.length) return { status: 'failed', reason: 'steps is empty' }
+
+  const steps: DemoStep[] = []
+  for (const [index, entry] of raw.steps.entries()) {
+    const step = parseStep(entry, index)
+    if ('reason' in step) return { status: 'failed', reason: step.reason }
+    steps.push(step.step)
+  }
+
+  const slug = asText(raw.slug)
+  const output = isRecord(raw.output) ? raw.output : {}
+  const pointer = isRecord(raw.pointer) ? raw.pointer : {}
+  const viewport = isRecord(raw.viewport) ? raw.viewport : {}
+
+  return {
+    status: 'parsed',
+    plan: {
+      slug,
+      title: asText(raw.title),
+      url: asText(raw.url),
+      viewport: {
+        width: asNumber(viewport.width, VIEWPORT.width),
+        height: asNumber(viewport.height, VIEWPORT.height),
+      },
+      output: {
+        video: asText(output.video) || `demos/${slug || 'demo'}.webm`,
+        still: asText(output.still) || `demos/${slug || 'demo'}.png`,
+      },
+      pointer: {
+        steps: asNumber(pointer.steps, POINTER_STEPS),
+        typeDelayMs: asNumber(pointer.typeDelayMs, TYPE_DELAY_MS),
+      },
+      annotations: ANNOTATIONS,
+      steps,
+    },
+  }
+}
+
+function parseStep(
+  entry: unknown,
+  index: number,
+): { step: DemoStep } | { reason: string } {
+  if (!isRecord(entry)) return { reason: `steps[${index}] is not an object` }
+
+  const kind = asText(entry.kind)
+  if (!isStepKind(kind)) {
+    return {
+      reason: `steps[${index}].kind is "${kind}", which is not a step this can drive`,
+    }
+  }
+
+  const step: DemoStep = {
+    beat: asNumber(entry.beat, index + 1),
+    name: asText(entry.name),
+    kind,
+    target: asText(entry.target),
+    text: asText(entry.text),
+    waitFor: asText(entry.waitFor),
+    holdMs: asNumber(entry.holdMs, HOLD_MS),
+    caption: asText(entry.caption),
+    still: entry.still === true,
+  }
+  const note = asText(entry.note)
+  return { step: note ? { ...step, note } : step }
+}
+
+function isStepKind(value: string): value is StepKind {
+  return (
+    value === 'navigate' ||
+    value === 'click' ||
+    value === 'fill' ||
+    value === 'hover' ||
+    value === 'scroll' ||
+    value === 'wait' ||
+    value === 'hold'
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function asNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+/**
+ * Names every field a person still has to fill before the plan can drive
+ * anything. Compile reports these and run refuses on them, so an unfilled plan
+ * fails at the point it is written rather than part-way through a recording.
+ */
+export function unresolved(plan: DemoPlan): string[] {
+  const missing: string[] = plan.url.trim() ? [] : ['url']
+  plan.steps.forEach((step, index) => {
+    if (TARGETED.has(step.kind) && !step.target.trim()) {
+      missing.push(`steps[${index}].target`)
+    }
+  })
+  return missing
+}

package/src/demo/cursors.ts

@@ -0,0 +1,55 @@
+import type { CursorSet } from '@/demo/pointer'
+
+/**
+ * The bundled pointer artwork, drawn as vector markup rather than read from a
+ * theme on disk. Spike 3 proved the browser decodes a Windows cursor resource
+ * directly, so `--cursor` points at a theme folder and gets that path instead.
+ * This set is what makes the command work in a target that has no theme to
+ * point at, which is every target on first run.
+ *
+ * Each drawing sits in a 48 by 48 box so one hotspot scale factor covers the
+ * set, and each carries a drop shadow so it stays visible over a light surface
+ * and a dark one.
+ */
+
+const SHADOW =
+  '<filter id="s" x="-50%" y="-50%" width="200%" height="200%">' +
+  '<feDropShadow dx="0" dy="1" stdDeviation="1.2" flood-opacity="0.45"/></filter>'
+
+function svg(body: string): string {
+  return `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48">${SHADOW}<g filter="url(#s)">${body}</g></svg>`,
+  )}`
+}
+
+const STROKE = 'fill="#ffffff" stroke="#1b1b1b" stroke-width="2.2"'
+
+/**
+ * Hotspots are stated against the 48 by 48 box each drawing uses, so the
+ * pointer scales them the same way it scales a hotspot read off a real cursor
+ * resource. Skipping the scale offsets the artwork by roughly a third of a
+ * cursor, which is the defect spike 3 recorded.
+ */
+export const DEFAULT_CURSORS: CursorSet = {
+  default: {
+    image: svg(
+      `<path ${STROKE} d="M5 3 L5 35 L13.5 27 L19 39.5 L25 37 L19.5 25 L31 24.5 Z"/>`,
+    ),
+    hotspot: { width: 48, height: 48, hotspotX: 5, hotspotY: 3 },
+  },
+  pointer: {
+    image: svg(
+      `<path ${STROKE} d="M18 4 a3.2 3.2 0 0 1 6.4 0 v14 a3 3 0 0 1 5.6 0 v2 a3 3 0 0 1 5.6 0 v2 a3 3 0 0 1 5.4 0 v9 a12 12 0 0 1 -12 12 h-6 a12 12 0 0 1 -12 -12 v-9 a3.2 3.2 0 0 1 6.4 0 z"/>`,
+    ),
+    hotspot: { width: 48, height: 48, hotspotX: 21, hotspotY: 4 },
+  },
+  // Drawn as one filled outline rather than three stroked segments. A stroked
+  // version needs its own fill, and a second fill attribute on a path carrying
+  // STROKE makes the markup invalid, which renders as a broken image.
+  text: {
+    image: svg(
+      `<path ${STROKE} d="M18 5 h12 v3.5 h-4 v31 h4 V43 h-12 v-3.5 h4 v-31 h-4 z"/>`,
+    ),
+    hotspot: { width: 48, height: 48, hotspotX: 24, hotspotY: 24 },
+  },
+}

package/src/demo/drive.ts

@@ -0,0 +1,256 @@
+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 type { DemoPlan, DemoStep } from '@/demo/compile'
+import type { CursorSet } from '@/demo/pointer'
+import { pointerSource } from '@/demo/pointer'
+
+/**
+ * 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
+
+/**
+ * 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(), 'aitk-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),
+    })
+    const page = await context.newPage()
+    const video = page.video()
+
+    // 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)
+      // 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,
+  }
+}
+
+/**
+ * Separates a browser binary that was never installed from every other launch
+ * failure, because the first is a setup step the operator has to run and the
+ * second is a defect. A target inherits that setup step, which is the stated
+ * cost of shipping this command outside the toolkit.
+ */
+async function launch(): Promise<Launch> {
+  try {
+    return { status: 'launched', value: await chromium.launch() }
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error)
+    return failed(
+      /executable doesn't exist|playwright install/i.test(text)
+        ? 'browser-missing'
+        : 'drive-failed',
+      error,
+    )
+  }
+}
+
+async function runStep(
+  page: Page,
+  plan: DemoPlan,
+  step: DemoStep,
+): 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)
+      await page.mouse.down()
+      await page.mouse.up()
+      break
+    case 'fill':
+      await moveTo(page, plan, step)
+      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)
+      break
+    case 'scroll':
+      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      await page.waitForTimeout(SETTLE_MS)
+      await moveTo(page, plan, step)
+      break
+    case 'wait':
+    case 'hold':
+      break
+  }
+
+  if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
+  await page.waitForTimeout(step.holdMs)
+}
+
+/**
+ * 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,
+): Promise<void> {
+  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: plan.pointer.steps,
+  })
+}
+
+function failed(reason: DriveRefusal, error: unknown): DriveFailure {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}