@erclx/canon 5.66.0 → 5.68.0

package/src/take/perform.ts

@@ -0,0 +1,200 @@
+import {
+  type Box,
+  FPS,
+  type LogEvent,
+  type Point,
+  along,
+  travelMs,
+} from '@/take/log'
+import type { TakeStep } from '@/take/plan'
+
+/**
+ * Performs a beat's steps through a stage and logs what the edit needs. The
+ * choreography sits here once, and each capture route supplies the stage, being
+ * how an input reaches the page and how clip time passes, so a beat moves the
+ * same way whichever route filmed it.
+ */
+
+const FRAME_MS = 1000 / FPS
+
+/** The gap between keys, slow enough that a viewer reads each one land. */
+const KEY_MS = 90
+
+/** How long a scroll's wheel travel runs. */
+const SCROLL_MS = 900
+
+export type PointerInput =
+  | {
+      readonly type: 'move' | 'down' | 'up'
+      readonly x: number
+      readonly y: number
+    }
+  | {
+      readonly type: 'wheel'
+      readonly x: number
+      readonly y: number
+      readonly dy: number
+    }
+
+export interface Stage {
+  /** Milliseconds on the clip's own clock. */
+  now(): number
+  /** Lets `ms` of clip time pass. */
+  hold(ms: number): Promise<void>
+  /** Sends one pointer input and lets one frame pass. */
+  pointer(input: PointerInput): Promise<void>
+  /** Types one character into the focused field and lets one frame pass. */
+  key(text: string): Promise<void>
+  /** Evaluates an expression in the page. */
+  evaluate<T>(expression: string): Promise<T>
+}
+
+/** A target that resolved to nothing, which refuses rather than films a guess. */
+export class TargetMissing extends Error {
+  constructor(readonly target: string) {
+    super(`nothing on the page matches ${target}`)
+  }
+}
+
+export interface Performance {
+  pointer: Point
+  /** Omitted for setup steps, which run before the clip starts. */
+  readonly log?: LogEvent[]
+}
+
+export async function performSteps(
+  stage: Stage,
+  steps: readonly TakeStep[],
+  state: Performance,
+): Promise<void> {
+  for (const step of steps) {
+    switch (step.kind) {
+      case 'move':
+        await moveTo(
+          stage,
+          state,
+          'target' in step ? center(await boxOf(stage, step.target)) : step,
+        )
+        break
+      case 'click':
+        await click(stage, state, await boxOf(stage, step.target))
+        break
+      case 'fill': {
+        const box = await boxOf(stage, step.target)
+        await click(stage, state, box)
+        const start = stage.now()
+        for (const character of step.text) {
+          await stage.key(character)
+          await stage.hold(KEY_MS - FRAME_MS)
+        }
+        state.log?.push({
+          t: start,
+          kind: 'type',
+          at: state.pointer,
+          box,
+          chars: step.text.length,
+          ms: stage.now() - start,
+        })
+        break
+      }
+      case 'scroll': {
+        const at = center(await boxOf(stage, step.target))
+        await moveTo(stage, state, at)
+        const frames = Math.round(SCROLL_MS / FRAME_MS)
+        state.log?.push({
+          t: stage.now(),
+          kind: 'scroll',
+          at,
+          dx: 0,
+          dy: step.dy,
+          ms: frames * FRAME_MS,
+        })
+        let sent = 0
+        for (let frame = 1; frame <= frames; frame += 1) {
+          const want = along(
+            { x: 0, y: 0 },
+            { x: 0, y: step.dy },
+            frame / frames,
+          ).y
+          await stage.pointer({ type: 'wheel', ...at, dy: want - sent })
+          sent = want
+        }
+        break
+      }
+      case 'wait':
+        await stage.hold(step.ms)
+        break
+    }
+  }
+}
+
+async function moveTo(
+  stage: Stage,
+  state: Performance,
+  to: Point,
+): Promise<void> {
+  const from = state.pointer
+  if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
+  const frames = Math.max(1, Math.round(travelMs(from, to) / FRAME_MS))
+  state.log?.push({
+    t: stage.now(),
+    kind: 'move',
+    from,
+    to,
+    ms: frames * FRAME_MS,
+  })
+  for (let frame = 1; frame <= frames; frame += 1) {
+    state.pointer = along(from, to, frame / frames)
+    await stage.pointer({ type: 'move', ...state.pointer })
+  }
+  state.pointer = to
+}
+
+async function click(
+  stage: Stage,
+  state: Performance,
+  box: Box,
+): Promise<void> {
+  const at = center(box)
+  await moveTo(stage, state, at)
+  state.log?.push({ t: stage.now(), kind: 'click', at, box })
+  await stage.pointer({ type: 'down', ...at })
+  await stage.pointer({ type: 'up', ...at })
+}
+
+function center(box: Box): Point {
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
+}
+
+async function boxOf(stage: Stage, target: string): Promise<Box> {
+  const box = await stage.evaluate<Box | null>(boxExpression(target))
+  if (!box) throw new TargetMissing(target)
+  return box
+}
+
+/**
+ * Finds a target's box in CSS pixels, reading `text=<words>` as the innermost
+ * element whose whole text is those words and anything else as a CSS selector.
+ * It runs inside the page so both routes resolve a target the same way, and a
+ * match with no size counts as missing, since a click on it would land on
+ * whatever sits behind.
+ */
+export function boxExpression(target: string): string {
+  return `(() => {
+    const target = ${JSON.stringify(target)}
+    let element = null
+    if (target.startsWith('text=')) {
+      const want = target.slice(5).trim()
+      const matches = [...document.querySelectorAll('body *')].filter(
+        (node) => node.textContent.trim() === want,
+      )
+      element = matches.find((node) => !matches.some((other) => other !== node && node.contains(other))) ?? null
+    } else {
+      element = document.querySelector(target)
+    }
+    if (!element) return null
+    const rect = element.getBoundingClientRect()
+    if (rect.width === 0 || rect.height === 0) return null
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+  })()`
+}

package/src/take/plan.ts

@@ -0,0 +1,193 @@
+/**
+ * The take plan: the beats a take films, each a list of steps. It reuses
+ * `canon drive`'s kind names for the steps the two share and adds `move`,
+ * since a take films the pointer's travel and a drive skips it. `tab` is left
+ * out because a take draws its cursor from the log, and focus moved by the
+ * keyboard leaves nothing in the log to draw.
+ */
+
+/** How a beat is filmed: frame stepping, or Playwright's real-time screencast. */
+export const ROUTES = ['step', 'screencast'] as const
+
+export type Route = (typeof ROUTES)[number]
+
+export type TakeStep =
+  | { readonly kind: 'move'; readonly target: string }
+  | { readonly kind: 'move'; readonly x: number; readonly y: number }
+  | { readonly kind: 'click'; readonly target: string }
+  | { readonly kind: 'fill'; readonly target: string; readonly text: string }
+  | { readonly kind: 'scroll'; readonly target: string; readonly dy: number }
+  | { readonly kind: 'wait'; readonly ms: number }
+
+export interface Beat {
+  readonly name: string
+  /**
+   * The route asked for. A `step` beat that frame stepping cannot drive falls
+   * back to `screencast` on its own, and the take's record says which ran.
+   */
+  readonly route: Route
+  /** Runs after the page loads and before the first frame is kept. */
+  readonly setup: readonly TakeStep[]
+  readonly steps: readonly TakeStep[]
+}
+
+export interface TakePlan {
+  readonly beats: readonly Beat[]
+}
+
+export type TakePlanRefusal =
+  | 'unreadable-plan'
+  | 'no-beats'
+  | 'bad-beat'
+  | 'no-steps'
+  | 'unknown-route'
+  | 'bad-step'
+
+export type TakePlanRead =
+  | { readonly kind: 'read'; readonly plan: TakePlan }
+  | {
+      readonly kind: 'refused'
+      readonly reason: TakePlanRefusal
+      readonly detail: string
+    }
+
+class Refusal extends Error {
+  constructor(
+    readonly reason: TakePlanRefusal,
+    detail: string,
+  ) {
+    super(detail)
+  }
+}
+
+/**
+ * Reads a take plan out of a JSON document, the same form `canon drive` reads
+ * its run in, refusing the first thing a take could not perform.
+ */
+export function readTakePlan(source: string): TakePlanRead {
+  let document: unknown
+  try {
+    document = JSON.parse(source)
+  } catch (error) {
+    return {
+      kind: 'refused',
+      reason: 'unreadable-plan',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  try {
+    return { kind: 'read', plan: readPlan(document) }
+  } catch (error) {
+    if (!(error instanceof Refusal)) throw error
+    return { kind: 'refused', reason: error.reason, detail: error.message }
+  }
+}
+
+function readPlan(document: unknown): TakePlan {
+  if (!isRecord(document)) {
+    throw new Refusal('unreadable-plan', 'the document is not an object')
+  }
+  const { beats } = document
+  if (!Array.isArray(beats) || beats.length === 0) {
+    throw new Refusal(
+      'no-beats',
+      'beats carries no entry, so nothing is filmed',
+    )
+  }
+  return { beats: beats.map((entry, index) => readBeat(entry, index)) }
+}
+
+function readBeat(entry: unknown, index: number): Beat {
+  const at = `beat ${index + 1}`
+  if (!isRecord(entry)) throw new Refusal('bad-beat', `${at} is not an object`)
+
+  const name = typeof entry.name === 'string' ? entry.name : ''
+  if (!name) {
+    throw new Refusal(
+      'bad-beat',
+      `${at} carries no name, and its clip is named by it`,
+    )
+  }
+
+  const route = entry.route ?? 'step'
+  if (!ROUTES.includes(route as Route)) {
+    throw new Refusal(
+      'unknown-route',
+      `${name} names route ${String(route)}. This build records on: ${ROUTES.join(', ')}.`,
+    )
+  }
+
+  if (!Array.isArray(entry.steps) || entry.steps.length === 0) {
+    throw new Refusal(
+      'no-steps',
+      `${name} names no step, so its take would film nothing`,
+    )
+  }
+  if (entry.setup !== undefined && !Array.isArray(entry.setup)) {
+    throw new Refusal('bad-beat', `${name} carries a setup that is not a list`)
+  }
+
+  return {
+    name,
+    route: route as Route,
+    setup: (entry.setup ?? []).map((step: unknown, i: number) =>
+      readStep(step, `${name}, setup step ${i + 1}`),
+    ),
+    steps: entry.steps.map((step: unknown, i: number) =>
+      readStep(step, `${name}, step ${i + 1}`),
+    ),
+  }
+}
+
+function readStep(entry: unknown, at: string): TakeStep {
+  if (!isRecord(entry)) throw new Refusal('bad-step', `${at} is not an object`)
+
+  const target = typeof entry.target === 'string' ? entry.target : undefined
+  const needTarget = (): string => {
+    if (target) return target
+    throw new Refusal('bad-step', `${at} is a ${entry.kind} with no target`)
+  }
+
+  switch (entry.kind) {
+    case 'move':
+      if (target) return { kind: 'move', target }
+      if (isNumber(entry.x) && isNumber(entry.y)) {
+        return { kind: 'move', x: entry.x, y: entry.y }
+      }
+      throw new Refusal(
+        'bad-step',
+        `${at} is a move with neither a target nor an x and y`,
+      )
+    case 'click':
+      return { kind: 'click', target: needTarget() }
+    case 'fill':
+      if (typeof entry.text !== 'string') {
+        throw new Refusal('bad-step', `${at} is a fill with no text`)
+      }
+      return { kind: 'fill', target: needTarget(), text: entry.text }
+    case 'scroll':
+      if (!isNumber(entry.dy)) {
+        throw new Refusal('bad-step', `${at} is a scroll with no dy in pixels`)
+      }
+      return { kind: 'scroll', target: needTarget(), dy: entry.dy }
+    case 'wait':
+      if (!isNumber(entry.ms) || entry.ms < 0) {
+        throw new Refusal('bad-step', `${at} is a wait with no ms`)
+      }
+      return { kind: 'wait', ms: entry.ms }
+    default:
+      throw new Refusal(
+        'bad-step',
+        `${at} names kind ${String(entry.kind)}, which is not move, click, fill, scroll, or wait`,
+      )
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}

package/src/take/pointer.ts

@@ -0,0 +1,168 @@
+import type { Point } from '@/take/log'
+
+/**
+ * Draws the cursor arrow and the click ring onto one decoded frame, in the
+ * shape groundwork track `193-ui-record` rendered them: a dark arrow outlined
+ * in white, and a blue ring that grows from its tip and fades out. Both stay
+ * one size whatever the frame shows, so the pointer reads the same in every
+ * beat of a reel. Drawn in TypeScript rather than a browser, so the reel needs
+ * no page and no seek, and a test can read the pixels it leaves.
+ */
+
+export interface Frame {
+  /** RGBA, four bytes a pixel, row by row. */
+  readonly data: Uint8Array
+  readonly width: number
+  readonly height: number
+}
+
+/** The arrow, relative to its tip, from the groundwork's 24 px cursor path. */
+const ARROW: readonly Point[] = [
+  { x: 0, y: 0 },
+  { x: 0, y: 17 },
+  { x: 4.5, y: 12.5 },
+  { x: 7.5, y: 19 },
+  { x: 10, y: 18 },
+  { x: 7, y: 11.5 },
+  { x: 13.5, y: 11.5 },
+]
+
+const ARROW_FILL = [17, 17, 17] as const
+const ARROW_STROKE = [255, 255, 255] as const
+const STROKE_HALF = 0.75
+
+/** The ring's outer radius at full size, and its stroke at that size. */
+export const RING_RADIUS = 18
+const RING_STROKE = 2
+const RING_COLOR = [37, 99, 235] as const
+/** The ring starts at this share of its size and grows by the expansion. */
+const RING_START = 0.4
+
+/**
+ * Draws the pointer with its tip at `at`, in the frame's own pixels, and the
+ * ring around it when `ring` is a 0 to 1 expansion. The ring sits under the
+ * arrow, and anything past the frame's edge is clipped.
+ */
+export function drawPointer(
+  frame: Frame,
+  at: Point,
+  ring: number | null,
+): void {
+  if (ring !== null) drawRing(frame, at, ring)
+  drawArrow(frame, at)
+}
+
+function drawRing(frame: Frame, at: Point, ring: number): void {
+  const scale = RING_START + ring
+  const stroke = RING_STROKE * scale
+  const middle = RING_RADIUS * scale - stroke / 2
+  const opacity = 1 - ring
+  if (opacity <= 0) return
+
+  const reach = RING_RADIUS * scale + 1
+  forEachPixel(frame, at, reach, reach, reach, reach, (px, py) => {
+    const distance = Math.hypot(px - at.x, py - at.y)
+    const coverage = clamp01(stroke / 2 + 0.5 - Math.abs(distance - middle))
+    return coverage > 0
+      ? { color: RING_COLOR, alpha: coverage * opacity }
+      : null
+  })
+}
+
+function drawArrow(frame: Frame, at: Point): void {
+  const reach = STROKE_HALF + 1
+  forEachPixel(frame, at, reach, 13.5 + reach, reach, 19 + reach, (px, py) => {
+    const d = signedDistance({ x: px - at.x, y: py - at.y })
+    // Coverage of the outlined shape, then of the fill inside the outline,
+    // each antialiased across one pixel.
+    const outer = clamp01(0.5 - (d - STROKE_HALF))
+    if (outer <= 0) return null
+    const inner = clamp01(0.5 - (d + STROKE_HALF))
+    return {
+      color: ARROW_STROKE,
+      alpha: outer,
+      over: ARROW_FILL,
+      overAlpha: inner,
+    }
+  })
+}
+
+interface Paint {
+  readonly color: readonly [number, number, number]
+  readonly alpha: number
+  /** A second color laid over the first, for the fill inside the outline. */
+  readonly over?: readonly [number, number, number]
+  readonly overAlpha?: number
+}
+
+/**
+ * Calls `paint` for each pixel center inside the box around `at`, clipped to
+ * the frame, and blends whatever it returns onto that pixel.
+ */
+function forEachPixel(
+  frame: Frame,
+  at: Point,
+  left: number,
+  right: number,
+  up: number,
+  down: number,
+  paint: (x: number, y: number) => Paint | null,
+): void {
+  const x0 = Math.max(0, Math.floor(at.x - left))
+  const x1 = Math.min(frame.width - 1, Math.ceil(at.x + right))
+  const y0 = Math.max(0, Math.floor(at.y - up))
+  const y1 = Math.min(frame.height - 1, Math.ceil(at.y + down))
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const result = paint(x + 0.5, y + 0.5)
+      if (!result) continue
+      const i = (y * frame.width + x) * 4
+      blend(frame.data, i, result.color, result.alpha)
+      if (result.over && result.overAlpha) {
+        blend(frame.data, i, result.over, result.overAlpha)
+      }
+    }
+  }
+}
+
+function blend(
+  data: Uint8Array,
+  i: number,
+  color: readonly [number, number, number],
+  alpha: number,
+): void {
+  for (let c = 0; c < 3; c += 1) {
+    const base = data[i + c] ?? 0
+    data[i + c] = Math.round(base + ((color[c] ?? 0) - base) * alpha)
+  }
+}
+
+/** Distance from `p` to the arrow's outline, negative inside it. */
+function signedDistance(p: Point): number {
+  let nearest = Number.POSITIVE_INFINITY
+  let inside = false
+  for (let i = 0, j = ARROW.length - 1; i < ARROW.length; j = i, i += 1) {
+    const a = ARROW[j] ?? ARROW[0]
+    const b = ARROW[i] ?? ARROW[0]
+    if (!a || !b) continue
+    nearest = Math.min(nearest, segmentDistance(p, a, b))
+    if (
+      a.y > p.y !== b.y > p.y &&
+      p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x
+    ) {
+      inside = !inside
+    }
+  }
+  return inside ? -nearest : nearest
+}
+
+function segmentDistance(p: Point, a: Point, b: Point): number {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const k = clamp01(((p.x - a.x) * dx + (p.y - a.y) * dy) / (dx * dx + dy * dy))
+  return Math.hypot(p.x - (a.x + k * dx), p.y - (a.y + k * dy))
+}
+
+function clamp01(value: number): number {
+  return Math.min(Math.max(value, 0), 1)
+}