@erclx/aitk 3.6.0 → 3.7.0

package/src/demo/beats.ts

@@ -0,0 +1,135 @@
+/**
+ * Reads the human-facing draft `claude-screencast` writes. Nothing here knows
+ * about a browser: the draft is prose aimed at a person, and turning it into
+ * something executable is `@/demo/compile`'s job.
+ */
+
+export interface Beat {
+  readonly index: number
+  readonly name: string
+  readonly onScreen: string
+  readonly action: string
+  readonly watchFor: string
+  readonly emphasis: string
+  readonly caption: string
+  readonly transitionOut?: string
+}
+
+export interface Draft {
+  readonly title: string
+  readonly beats: readonly Beat[]
+}
+
+export type DraftParse =
+  | { status: 'parsed'; draft: Draft }
+  | { status: 'failed'; reason: string }
+
+const TITLE = /^#\s+Screencast:\s*(.+)$/m
+const BEAT_SHEET = /^##\s+.*Beat sheet.*$/im
+const BEAT_HEADING = /^###\s+Beat\s+(\d+)\s*:\s*(.*)$/i
+const FIELD = /^-\s+([A-Za-z][A-Za-z\s]*?)\s*:\s*(.*)$/
+
+/**
+ * Labels are matched case-insensitively with whitespace collapsed, because the
+ * draft is hand-edited between being written and being compiled and a
+ * capitalization change there is not a reason to refuse the whole file.
+ */
+const FIELDS: Record<string, keyof Beat> = {
+  'on screen': 'onScreen',
+  action: 'action',
+  'watch for': 'watchFor',
+  emphasis: 'emphasis',
+  caption: 'caption',
+  'transition out': 'transitionOut',
+}
+
+export function parseDraft(markdown: string): DraftParse {
+  const sheet = beatSheetSection(markdown)
+  if (sheet === undefined) {
+    return {
+      status: 'failed',
+      reason: 'no "Beat sheet" section, so the draft carries no beats to run',
+    }
+  }
+
+  const beats = readBeats(sheet)
+  if (!beats.length) {
+    return {
+      status: 'failed',
+      reason: 'the beat sheet holds no "### Beat" heading',
+    }
+  }
+
+  return {
+    status: 'parsed',
+    draft: { title: TITLE.exec(markdown)?.[1]?.trim() ?? '', beats },
+  }
+}
+
+/**
+ * Returns the lines between the beat sheet heading and the next `##`, so a
+ * `### Beat` heading elsewhere in the draft cannot be read as a beat.
+ */
+function beatSheetSection(markdown: string): string[] | undefined {
+  const lines = markdown.split('\n')
+  const start = lines.findIndex((line) => BEAT_SHEET.test(line))
+  if (start === -1) return undefined
+
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s/.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+function readBeats(lines: string[]): Beat[] {
+  const beats: Beat[] = []
+  let open: Partial<Beat> | undefined
+
+  for (const line of lines) {
+    const heading = BEAT_HEADING.exec(line)
+    if (heading) {
+      if (open) beats.push(sealBeat(open))
+      open = {
+        index: Number(heading[1]),
+        name: (heading[2] ?? '').trim(),
+      }
+      continue
+    }
+
+    if (!open) continue
+    const field = FIELD.exec(line)
+    if (!field) continue
+
+    const key = FIELDS[normalizeLabel(field[1] ?? '')]
+    if (key) open = { ...open, [key]: (field[2] ?? '').trim() }
+  }
+
+  if (open) beats.push(sealBeat(open))
+  return beats
+}
+
+/**
+ * Fills the five required fields with empty strings rather than leaving them
+ * undefined, so a downstream reader distinguishes "the operator left it blank"
+ * from "the label was misspelt" by the presence of the key alone.
+ *
+ * `transitionOut` stays optional, because the draft adds it only when it is
+ * not the default and an empty one would claim a decision nobody made.
+ */
+function sealBeat(open: Partial<Beat>): Beat {
+  const beat: Beat = {
+    index: open.index ?? 0,
+    name: open.name ?? '',
+    onScreen: open.onScreen ?? '',
+    action: open.action ?? '',
+    watchFor: open.watchFor ?? '',
+    emphasis: open.emphasis ?? '',
+    caption: open.caption ?? '',
+  }
+  return open.transitionOut === undefined
+    ? beat
+    : { ...beat, transitionOut: open.transitionOut }
+}
+
+function normalizeLabel(label: string): string {
+  return label.trim().toLowerCase().replace(/\s+/g, ' ')
+}

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 },
+  },
+}