npm - @erclx/canon - Versions diffs - 5.69.0 → 5.71.0 - Mend

@erclx/canon 5.69.0 → 5.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/CHANGELOG.md +25 -0
package/README.md +33 -159
package/assets/brand/mark.svg +17 -9
package/claude/.claude-plugin/plugin.json +1 -1
package/claude/skills/app-drive/SKILL.md +3 -2
package/claude/skills/app-drive/references/drive-record.md +52 -10
package/claude/skills/app-drive/references/isolate.md +1 -1
package/claude/skills/design-pick/SKILL.md +1 -0
package/claude/skills/git-pr/references/task-number.md +13 -0
package/claude/skills/markdown-craft/references/markdown.md +1 -0
package/claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md +1 -0
package/claude/skills/role-orchestrator/references/orchestrator-launch.md +6 -20
package/claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md +10 -0
package/claude/skills/role-orchestrator/references/orchestrator-talk-launch.md +30 -0
package/claude/skills/task-board/references/tasks-record-lines.md +40 -0
package/claude/skills/task-board/references/tasks.md +4 -8
package/claude/skills/ui-craft/references/copy.md +4 -1
package/claude/skills/ui-film/REQUIREMENT.md +4 -2
package/claude/skills/ui-film/SKILL.md +24 -11
package/claude/skills/ui-film/references/compose-craft.md +81 -0
package/claude/skills/ui-film/references/config.md +6 -1
package/claude/skills/ui-film/references/handoff.md +13 -3
package/claude/skills/ui-film/references/take-craft.md +27 -1
package/docs/index.md +1 -0
package/docs/migrations/by-hand.md +107 -0
package/docs/migrations/by-verb.md +118 -0
package/docs/migrations/index.md +14 -0
package/docs/target/index.md +1 -2
package/docs/target/projects.md +2 -2
package/docs/target/sync.md +22 -2
package/docs/workflow/ai-workflow.md +1 -1
package/governance/ledger/skills/ui-craft/copy.md +8 -4
package/package.json +3 -1
package/scripts/core/design-sync.ts +204 -0
package/scripts/core/regen-web-favicon.ts +27 -12
package/scripts/core/regen-web-previews.ts +8 -1
package/scripts/core/render-film.ts +179 -0
package/src/capture/frame-values.ts +12 -12
package/src/commands/markdown.ts +6 -1
package/src/commands/records.ts +3 -2
package/src/commands/sandbox.ts +9 -2
package/src/commands/take.ts +159 -11
package/src/commands/tasks.ts +133 -0
package/src/design/favicon.ts +85 -13
package/src/design/reference.ts +98 -0
package/src/design/render.ts +16 -14
package/src/design/tokens.ts +4 -3
package/src/gate/stages.ts +6 -0
package/src/init/steps.ts +2 -2
package/src/markdown/colons.ts +102 -16
package/src/migrate/status.ts +3 -3
package/src/records/validate.ts +14 -2
package/src/sandbox/expect.ts +32 -0
package/src/sandbox/headless/run.ts +6 -3
package/src/take/camera.ts +99 -10
package/src/take/film.ts +35 -2
package/src/take/fixtures/input.html +138 -0
package/src/take/keys.ts +193 -0
package/src/take/log.ts +94 -1
package/src/take/perform.ts +165 -10
package/src/take/plan.ts +101 -6
package/src/take/screencast.ts +28 -3
package/src/take/stepper.ts +122 -18
package/src/tasks/archive.ts +54 -1
package/src/tasks/record.ts +118 -0
package/src/tasks/validate.ts +37 -0
package/docs/target/migrations.md +0 -205

package/src/take/fixtures/input.html ADDED Viewed

@@ -0,0 +1,138 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Input</title>
+    <!--
+      One target per input a take performs, each posting what the page saw to
+      /report with a sequence number, so a test reads the inputs in the order
+      the page received them after the take has closed the browser.
+      - #handle follows a pointer-event drag and reports where it dropped and
+        how many of its moves carried the held button
+      - #frame reports each dblclick
+      - #layer reports pointerdown, pointerup, and click with the Shift flag
+      - #field takes focus for key steps, and every keyup reports its value
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #f4f4f4;
+        font: 24px sans-serif;
+      }
+      #handle {
+        position: absolute;
+        left: 200px;
+        top: 200px;
+        width: 80px;
+        height: 80px;
+        /* Neutral, so the reel's blue ring reads over it at any alpha. */
+        background: #444;
+        touch-action: none;
+      }
+      #lane {
+        position: absolute;
+        left: 700px;
+        top: 160px;
+        width: 300px;
+        height: 160px;
+        border: 2px dashed #555;
+        box-sizing: border-box;
+      }
+      #frame,
+      #layer {
+        position: absolute;
+        top: 500px;
+        width: 200px;
+        height: 100px;
+        background: #ddd;
+        user-select: none;
+      }
+      #frame {
+        left: 200px;
+      }
+      #layer {
+        left: 700px;
+      }
+      #field {
+        position: absolute;
+        left: 200px;
+        top: 750px;
+        width: 400px;
+        height: 48px;
+        font: inherit;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="lane"></div>
+    <div id="handle"></div>
+    <div id="frame">Frame</div>
+    <div id="layer">Layer</div>
+    <input id="field" />
+    <script>
+      let seq = 0
+      const report = (entry) =>
+        fetch('/report', {
+          method: 'POST',
+          body: JSON.stringify({ seq: (seq += 1), ...entry }),
+          keepalive: true,
+        })
+      const handle = document.getElementById('handle')
+      const lane = document.getElementById('lane')
+      let drag = null
+      handle.addEventListener('pointerdown', (event) => {
+        handle.setPointerCapture(event.pointerId)
+        drag = { held: 0, hover: 0 }
+      })
+      handle.addEventListener('pointermove', (event) => {
+        if (!drag) return
+        if (event.buttons === 1) drag.held += 1
+        else drag.hover += 1
+        handle.style.left = `${event.clientX - 40}px`
+        handle.style.top = `${event.clientY - 40}px`
+      })
+      handle.addEventListener('pointerup', (event) => {
+        if (!drag) return
+        const box = lane.getBoundingClientRect()
+        const onTarget =
+          event.clientX >= box.left &&
+          event.clientX <= box.right &&
+          event.clientY >= box.top &&
+          event.clientY <= box.bottom
+        report({ type: 'drop', ...drag, onTarget, altKey: event.altKey })
+        drag = null
+      })
+      document
+        .getElementById('frame')
+        .addEventListener('dblclick', () => report({ type: 'dblclick' }))
+      const layer = document.getElementById('layer')
+      for (const type of ['pointerdown', 'pointerup', 'click']) {
+        layer.addEventListener(type, (event) =>
+          report({ type, shiftKey: event.shiftKey }),
+        )
+      }
+      const field = document.getElementById('field')
+      document.addEventListener('keydown', (event) =>
+        report({
+          type: 'keydown',
+          key: event.key,
+          ctrlKey: event.ctrlKey,
+        }),
+      )
+      document.addEventListener('keyup', (event) =>
+        report({ type: 'keyup', key: event.key, value: field.value }),
+      )
+    </script>
+  </body>
+</html>

package/src/take/keys.ts ADDED Viewed

@@ -0,0 +1,193 @@
+/**
+ * The keys a take plan may press, named as Playwright names them so the
+ * screencast passes a combination straight to `page.keyboard`, and each one's
+ * CDP descriptor so the stepper can send the same press as raw key events.
+ * A key outside this vocabulary refuses at plan read, since the stepper has no
+ * descriptor to send for it.
+ */
+export const MODIFIERS = ['Alt', 'Control', 'Meta', 'Shift'] as const
+export type Modifier = (typeof MODIFIERS)[number]
+/** A combination: the modifiers held, in order, around one key. */
+export interface Chord {
+  readonly modifiers: readonly Modifier[]
+  readonly key: string
+}
+/** The fields `Input.dispatchKeyEvent` needs to press one key. */
+export interface KeyDescriptor {
+  readonly key: string
+  readonly code: string
+  readonly keyCode: number
+  /** What the key types, absent for a key that types nothing. */
+  readonly text?: string
+  /** 1 for a modifier, which sits on the left of the keyboard. */
+  readonly location: number
+}
+/** CDP's modifier bit field: "Alt=1, Ctrl=2, Meta/Command=4, Shift=8". */
+const MODIFIER_BITS: Record<Modifier, number> = {
+  Alt: 1,
+  Control: 2,
+  Meta: 4,
+  Shift: 8,
+}
+const MODIFIER_KEY_CODES: Record<Modifier, number> = {
+  Alt: 18,
+  Control: 17,
+  Meta: 91,
+  Shift: 16,
+}
+const NAMED: Record<string, { code?: string; keyCode: number; text?: string }> =
+  {
+    Enter: { keyCode: 13, text: '\r' },
+    Tab: { keyCode: 9 },
+    Escape: { keyCode: 27 },
+    Backspace: { keyCode: 8 },
+    Delete: { keyCode: 46 },
+    Insert: { keyCode: 45 },
+    Space: { keyCode: 32, text: ' ' },
+    Home: { keyCode: 36 },
+    End: { keyCode: 35 },
+    PageUp: { keyCode: 33 },
+    PageDown: { keyCode: 34 },
+    ArrowLeft: { keyCode: 37 },
+    ArrowUp: { keyCode: 38 },
+    ArrowRight: { keyCode: 39 },
+    ArrowDown: { keyCode: 40 },
+    ...Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`F${i + 1}`, { keyCode: 112 + i }]),
+    ),
+  }
+/** The US layout's punctuation, each with its shifted twin on the same key. */
+const PUNCTUATION: readonly (readonly [string, string, string, number])[] = [
+  ['`', '~', 'Backquote', 192],
+  ['-', '_', 'Minus', 189],
+  ['=', '+', 'Equal', 187],
+  ['[', '{', 'BracketLeft', 219],
+  [']', '}', 'BracketRight', 221],
+  ['\\', '|', 'Backslash', 220],
+  [';', ':', 'Semicolon', 186],
+  ["'", '"', 'Quote', 222],
+  [',', '<', 'Comma', 188],
+  ['.', '>', 'Period', 190],
+  ['/', '?', 'Slash', 191],
+]
+const SHIFTED_DIGITS = ')!@#$%^&*('
+/**
+ * With `shift` set, a printable key types its shifted twin, as Playwright's
+ * keyboard swaps to it while Shift is held, so `Shift+a` types `A` on both
+ * routes.
+ */
+export function describeKey(
+  key: string,
+  options: { readonly shift?: boolean } = {},
+): KeyDescriptor | undefined {
+  return describeTyped(options.shift ? shiftedTwin(key) : key)
+}
+function shiftedTwin(key: string): string {
+  if (/^[a-z]$/.test(key)) return key.toUpperCase()
+  if (/^[0-9]$/.test(key)) return SHIFTED_DIGITS[Number(key)] ?? key
+  const row = PUNCTUATION.find(([plain]) => key === plain)
+  return row ? row[1] : key
+}
+function describeTyped(key: string): KeyDescriptor | undefined {
+  if (isModifier(key)) {
+    return {
+      key,
+      code: `${key}Left`,
+      keyCode: MODIFIER_KEY_CODES[key],
+      location: 1,
+    }
+  }
+  const named = NAMED[key]
+  if (named) {
+    return {
+      key: key === 'Space' ? ' ' : key,
+      code: named.code ?? key,
+      keyCode: named.keyCode,
+      ...(named.text ? { text: named.text } : {}),
+      location: 0,
+    }
+  }
+  if (key.length !== 1) return undefined
+  if (/^[a-z]$/i.test(key)) {
+    const upper = key.toUpperCase()
+    return printable(key, `Key${upper}`, upper.charCodeAt(0))
+  }
+  if (/^[0-9]$/.test(key)) {
+    return printable(key, `Digit${key}`, key.charCodeAt(0))
+  }
+  const shiftedDigit = SHIFTED_DIGITS.indexOf(key)
+  if (shiftedDigit >= 0) {
+    return printable(key, `Digit${shiftedDigit}`, 48 + shiftedDigit)
+  }
+  if (key === ' ') return printable(key, 'Space', 32)
+  const row = PUNCTUATION.find(
+    ([plain, shifted]) => key === plain || key === shifted,
+  )
+  return row ? printable(key, row[2], row[3]) : undefined
+}
+export type KeysRead =
+  | { readonly kind: 'parsed'; readonly chord: Chord }
+  | { readonly kind: 'refused'; readonly detail: string }
+/**
+ * Reads a combination such as `Control+K`, the modifiers first and the key
+ * last. A trailing `+` after a separator is the plus key itself.
+ */
+export function parseKeys(keys: string): KeysRead {
+  const parts =
+    keys === '+'
+      ? ['+']
+      : keys.endsWith('++')
+        ? [...keys.slice(0, -2).split('+'), '+']
+        : keys.split('+')
+  const key = parts.at(-1) ?? ''
+  const held = parts.slice(0, -1)
+  if (!key) return { kind: 'refused', detail: `${keys || 'it'} names no key` }
+  const modifiers: Modifier[] = []
+  for (const name of held) {
+    if (!isModifier(name)) {
+      return {
+        kind: 'refused',
+        detail: `${keys} holds ${name || 'nothing'}, which is not ${MODIFIERS.join(', ')}`,
+      }
+    }
+    if (modifiers.includes(name)) {
+      return { kind: 'refused', detail: `${keys} holds ${name} twice` }
+    }
+    modifiers.push(name)
+  }
+  if (!describeKey(key)) {
+    return {
+      kind: 'refused',
+      detail: `${keys} presses ${key}, which is not a modifier, one character, or a named key`,
+    }
+  }
+  return { kind: 'parsed', chord: { modifiers, key } }
+}
+export function modifierBits(modifiers: readonly Modifier[]): number {
+  return modifiers.reduce((bits, name) => bits | MODIFIER_BITS[name], 0)
+}
+export function isModifier(name: unknown): name is Modifier {
+  return MODIFIERS.includes(name as Modifier)
+}
+function printable(key: string, code: string, keyCode: number): KeyDescriptor {
+  return { key, code, keyCode, text: key, location: 0 }
+}

package/src/take/log.ts CHANGED Viewed

@@ -1,4 +1,5 @@
-import type { Route } from '@/take/plan'
+import type { Modifier } from '@/take/keys'
+import { ROUTES, type Route } from '@/take/plan'
 /**
  * The click log a take writes beside its clip, and the pointer path both
@@ -43,6 +44,33 @@ export type LogEvent =
       readonly kind: 'click'
       readonly at: Point
       readonly box: Box
+      /** The keys held through the press, absent when none is. */
+      readonly modifiers?: readonly Modifier[]
+      /** 2 for a double click, absent for a single one. */
+      readonly count?: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'drag'
+      /** Where the button went down and where it came up. */
+      readonly from: Point
+      readonly to: Point
+      /** The box pressed and the box it was dropped on. */
+      readonly box: Box
+      readonly drop: Box
+      readonly modifiers?: readonly Modifier[]
+      /**
+       * From press to release. The travel between is logged as `move` events,
+       * which the cursor is read off.
+       */
+      readonly ms: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'key'
+      /** The combination as the plan wrote it, such as `Control+K`. */
+      readonly keys: string
+      readonly ms: number
     }
   | {
       readonly t: number
@@ -68,10 +96,75 @@ export interface TakeLog {
   readonly fps: number
   /** The route that filmed the clip, which can differ from the one asked for. */
   readonly route: Route
+  /**
+   * The clip's size in pixels, which sets how deep the camera may zoom before
+   * the clip goes soft. A log written before this field read it off `route`.
+   */
+  readonly clip?: { readonly width: number; readonly height: number }
+  /** False when the beat turned the camera's zoom off. */
+  readonly push?: false
   readonly frames: number
   readonly events: readonly LogEvent[]
 }
+/** The size each route films at, the stepper at twice the viewport. */
+export const CLIP_SIZES: Record<
+  Route,
+  { readonly width: number; readonly height: number }
+> = {
+  step: { width: VIEWPORT.width * 2, height: VIEWPORT.height * 2 },
+  screencast: VIEWPORT,
+}
+export type TakeLogRead =
+  | { readonly kind: 'read'; readonly log: TakeLog }
+  | { readonly kind: 'refused'; readonly detail: string }
+/**
+ * Reads a log back off disk, checking the fields the camera builds on rather
+ * than every event, since a take wrote the events and a reader only ever
+ * points at the wrong file.
+ */
+export function readTakeLog(source: string): TakeLogRead {
+  let document: unknown
+  try {
+    document = JSON.parse(source)
+  } catch (error) {
+    return {
+      kind: 'refused',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+  if (typeof document !== 'object' || document === null) {
+    return { kind: 'refused', detail: 'the document is not an object' }
+  }
+  const log = document as Partial<Record<keyof TakeLog, unknown>>
+  const missing = [
+    isSize(log.viewport) ? '' : 'viewport',
+    isCount(log.fps) && log.fps > 0 ? '' : 'fps',
+    ROUTES.includes(log.route as Route) ? '' : 'route',
+    isCount(log.frames) ? '' : 'frames',
+    Array.isArray(log.events) ? '' : 'events',
+  ].filter(Boolean)
+  if (missing.length > 0) {
+    return {
+      kind: 'refused',
+      detail: `the document carries no valid ${missing.join(', ')}, so it is not a take's log.json`,
+    }
+  }
+  return { kind: 'read', log: document as TakeLog }
+}
+function isCount(value: unknown): value is number {
+  return Number.isInteger(value) && (value as number) >= 0
+}
+function isSize(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false
+  const { width, height } = value as Record<string, unknown>
+  return isCount(width) && isCount(height)
+}
 /** Where the pointer rests before a take's first move. */
 export const START: Point = { x: VIEWPORT.width / 2, y: VIEWPORT.height / 2 }

package/src/take/perform.ts CHANGED Viewed

@@ -6,6 +6,7 @@ import {
   along,
   travelMs,
 } from '@/take/log'
+import { type Chord, type Modifier, isModifier, parseKeys } from '@/take/keys'
 import type { TakeStep } from '@/take/plan'
 /**
@@ -23,11 +24,25 @@ const KEY_MS = 90
 /** How long a scroll's wheel travel runs. */
 const SCROLL_MS = 900
+/** How long a drag holds still after its press, so the viewer sees the grab land. */
+const GRAB_MS = 150
 export type PointerInput =
   | {
-      readonly type: 'move' | 'down' | 'up'
+      readonly type: 'move'
+      readonly x: number
+      readonly y: number
+      /** True while a drag holds the left button down. */
+      readonly held?: true
+      readonly modifiers?: readonly Modifier[]
+    }
+  | {
+      readonly type: 'down' | 'up'
       readonly x: number
       readonly y: number
+      /** Which press of a run this is, 2 being a double click's second. */
+      readonly clickCount: number
+      readonly modifiers?: readonly Modifier[]
     }
   | {
       readonly type: 'wheel'
@@ -36,6 +51,14 @@ export type PointerInput =
       readonly dy: number
     }
+/** One key going down or coming up. */
+export interface KeyInput {
+  readonly type: 'down' | 'up'
+  readonly key: string
+  /** The modifiers held once this input lands, so a modifier's own down counts it. */
+  readonly modifiers: readonly Modifier[]
+}
 export interface Stage {
   /** Milliseconds on the clip's own clock. */
   now(): number
@@ -45,12 +68,17 @@ export interface Stage {
   pointer(input: PointerInput): Promise<void>
   /** Types one character into the focused field and lets one frame pass. */
   key(text: string): Promise<void>
+  /** Sends one key down or up and lets one frame pass. */
+  press(input: KeyInput): 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 {
+  /** The page as it stood when the lookup failed, as a JPEG, when the route caught one. */
+  still?: Buffer
   constructor(readonly target: string) {
     super(`nothing on the page matches ${target}`)
   }
@@ -77,11 +105,40 @@ export async function performSteps(
         )
         break
       case 'click':
-        await click(stage, state, await boxOf(stage, step.target))
+      case 'dblclick':
+        await click(
+          stage,
+          state,
+          await boxOf(stage, step.target),
+          step.modifiers ?? [],
+          step.kind === 'dblclick' ? 2 : 1,
+        )
         break
+      case 'drag':
+        await drag(
+          stage,
+          state,
+          await boxOf(stage, step.from),
+          await boxOf(stage, step.to),
+          step.modifiers ?? [],
+        )
+        break
+      case 'key': {
+        const read = parseKeys(step.keys)
+        if (read.kind === 'refused') throw new Error(read.detail)
+        const start = stage.now()
+        await pressChord(stage, read.chord)
+        state.log?.push({
+          t: start,
+          kind: 'key',
+          keys: step.keys,
+          ms: stage.now() - start,
+        })
+        break
+      }
       case 'fill': {
         const box = await boxOf(stage, step.target)
-        await click(stage, state, box)
+        await click(stage, state, box, [], 1)
         const start = stage.now()
         for (const character of step.text) {
           await stage.key(character)
@@ -132,6 +189,7 @@ async function moveTo(
   stage: Stage,
   state: Performance,
   to: Point,
+  held?: { readonly modifiers: readonly Modifier[] },
 ): Promise<void> {
   const from = state.pointer
   if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
@@ -143,9 +201,12 @@ async function moveTo(
     to,
     ms: frames * FRAME_MS,
   })
+  const pressed = held
+    ? { held: true as const, ...withModifiers(held.modifiers) }
+    : {}
   for (let frame = 1; frame <= frames; frame += 1) {
     state.pointer = along(from, to, frame / frames)
-    await stage.pointer({ type: 'move', ...state.pointer })
+    await stage.pointer({ type: 'move', ...state.pointer, ...pressed })
   }
   state.pointer = to
 }
@@ -154,12 +215,100 @@ async function click(
   stage: Stage,
   state: Performance,
   box: Box,
+  modifiers: readonly Modifier[],
+  count: number,
 ): 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 })
+  await holding(stage, modifiers, async () => {
+    state.log?.push({
+      t: stage.now(),
+      kind: 'click',
+      at,
+      box,
+      ...withModifiers(modifiers),
+      ...(count > 1 ? { count } : {}),
+    })
+    for (let clickCount = 1; clickCount <= count; clickCount += 1) {
+      const press = { ...at, clickCount, ...withModifiers(modifiers) }
+      await stage.pointer({ type: 'down', ...press })
+      await stage.pointer({ type: 'up', ...press })
+    }
+  })
+}
+/**
+ * Presses on the source, holds a moment so the page reads a grab rather than
+ * a click, glides held to the target, and releases there. The drop target is
+ * read before the press, so a page that moves it once a drag starts is
+ * dropped on where it stood.
+ */
+async function drag(
+  stage: Stage,
+  state: Performance,
+  box: Box,
+  drop: Box,
+  modifiers: readonly Modifier[],
+): Promise<void> {
+  const from = center(box)
+  const to = center(drop)
+  await moveTo(stage, state, from)
+  await holding(stage, modifiers, async () => {
+    const start = stage.now()
+    const press = { clickCount: 1, ...withModifiers(modifiers) }
+    await stage.pointer({ type: 'down', ...from, ...press })
+    await stage.hold(GRAB_MS)
+    await moveTo(stage, state, to, { modifiers })
+    await stage.pointer({ type: 'up', ...to, ...press })
+    state.log?.push({
+      t: start,
+      kind: 'drag',
+      from,
+      to,
+      box,
+      drop,
+      ...withModifiers(modifiers),
+      ms: stage.now() - start,
+    })
+  })
+}
+/**
+ * Presses each modifier in order, runs the inputs they hold, and releases them
+ * in reverse, so a page reads every input between as modified on both routes.
+ */
+async function holding(
+  stage: Stage,
+  modifiers: readonly Modifier[],
+  inputs: () => Promise<void>,
+): Promise<void> {
+  for (const [i, key] of modifiers.entries()) {
+    await stage.press({
+      type: 'down',
+      key,
+      modifiers: modifiers.slice(0, i + 1),
+    })
+  }
+  await inputs()
+  for (const [i, key] of [...modifiers.entries()].reverse()) {
+    await stage.press({ type: 'up', key, modifiers: modifiers.slice(0, i) })
+  }
+}
+/** Presses a chord's key inside its modifiers, counting a modifier key as held while down. */
+async function pressChord(stage: Stage, chord: Chord): Promise<void> {
+  const { key, modifiers } = chord
+  await holding(stage, modifiers, async () => {
+    const down = isModifier(key) ? [...modifiers, key] : modifiers
+    await stage.press({ type: 'down', key, modifiers: down })
+    await stage.press({ type: 'up', key, modifiers })
+  })
+}
+function withModifiers(modifiers: readonly Modifier[]): {
+  modifiers?: readonly Modifier[]
+} {
+  return modifiers.length > 0 ? { modifiers } : {}
 }
 function center(box: Box): Point {
@@ -173,8 +322,10 @@ async function boxOf(stage: Stage, target: string): Promise<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.
+ * Finds a target's box in CSS pixels, reading `text=<words>` as the first
+ * innermost element with a size whose whole text is those words, so a hidden
+ * copy earlier in the page cannot shadow a visible one, 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.
@@ -188,7 +339,11 @@ export function boxExpression(target: string): string {
       const matches = [...document.querySelectorAll('body *')].filter(
         (node) => node.textContent.trim() === want,
       )
-      element = matches.find((node) => !matches.some((other) => other !== node && node.contains(other))) ?? null
+      const innermost = matches.filter((node) => !matches.some((other) => other !== node && node.contains(other)))
+      element = innermost.find((node) => {
+        const rect = node.getBoundingClientRect()
+        return rect.width > 0 && rect.height > 0
+      }) ?? null
     } else {
       element = document.querySelector(target)
     }