@erclx/aitk 3.11.1 → 3.12.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-pr-review/REQUIREMENT.md

@@ -11,6 +11,8 @@ Without this skill, a pull request is reviewed only by the session that wrote it
 
 A finding also stops being true by argument rather than by a fix. A worker naming the plan question that already declined it, or a constraint the pass could not see, settles it in the exchange that carried the answer, and the pass that accepts the argument drops the finding from its next body. A reader then sees a finding raised once and never mentioned again, which is indistinguishable from one everyone forgot.
 
+A request written under `## For the reviewer` also reached no reader. The authoring standard names it as what the reviewing session should confirm, and nothing on this side read the section by that name, so a branch author's question sat in the body until this skill answered it.
+
 ## Must
 
 - Post until the review closes. A first pass opens against the whole change, and each later pass checks whether the prior findings landed.
@@ -22,6 +24,7 @@ A finding also stops being true by argument rather than by a fix. A worker namin
 - State a withdrawal or a regrade on the thread with the fact that settled it, since a finding dropped in silence reads the same as one nobody answered
 - Key the body file on the pull request number and the head commit, and on the response it answers once the head repeats, so no two passes overwrite each other
 - Scan the comment for banned characters and internal phase labels before posting, since a finding phrased against a phase label reaches a reader with no task board
+- Answer a `## For the reviewer` bullet in the body, bounded to the section itself rather than the Summary or the Technical Context around it, so the independent vantage stays clear of the author's framing
 
 ## Must not
 

package/claude/skills/claude-pr-review/SKILL.md

@@ -15,7 +15,7 @@ review against the whole change, and every later pass reads only the commits
 added since. The heading reports state rather than pass number: a pass carrying
 anything owed takes `## Review`, and `## Review closed` covers a pass carrying
 none, so the most recent comment's heading reports whether any work is owed.
-Owed is a finding at any severity or a Testing question, defined once at Step 4. Every pass is this skill, and which one it is gets detected from
+Owed is a finding at any severity, a Testing question, or a reviewer request nobody has answered, defined once at Step 4. Every pass is this skill, and which one it is gets detected from
 the thread rather than named by the caller.
 
 ## Guards
@@ -89,6 +89,10 @@ Test every unchecked box against the testing discipline in `${CLAUDE_SKILL_DIR}/
 
 Ask rather than grade. Whether a human is genuinely required is a reading the branch author may hold a reason this session cannot see, so the question carries no severity and enters no count. What it does carry is the heading and the dispatch, on the rule Step 4 states, because a question the author never receives corrects nothing and the author is the only party who can answer it. Answering it closes it, and the answer may be that the requirement holds.
 
+Read `## For the reviewer` the same way, bounded to the bullets under that heading rather than the Summary or the Technical Context around it. Those two carry the author's argument for the change, and reading them while judging it is most of what an independent pass exists to avoid, so the read stops at the section itself.
+
+Answer each bullet in the body, on the same terms as a Testing question: no severity, no count. A request nobody can answer stays owed under the heading and dispatch Step 4 states, keeping the thread open exactly as an unanswered Testing box does. One the pass does answer carries no further weight, since the answer is discharged in the same comment that carries it.
+
 Apply the high-signal filter: flag only what will cause incorrect behavior, break a documented rule, or mislead a downstream feature. If uncertain, do not flag.
 
 A later pass applies the same axes to the delta, and adds one check the first pass cannot make: did each prior finding land, and did the fix regress anything it touched. Findings of its own are normal findings, stated at the same severity and counted the same way. That count is one of the two things Step 4 reads to pick the heading, so a pass raising a finding of its own is not a close-out at any severity.
@@ -160,7 +164,17 @@ A Testing box the Step 3 check raised goes in a `**Testing**` block placed after
 
 Keep it to the boxes the check raised. Restating a box whose stated requirement holds teaches the branch author to skip the block.
 
-The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity and a Testing question alike, which is what keeps the two halves from separating. Sending that dispatch is `claude-orchestrate`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
+Every `## For the reviewer` bullet Step 3 read goes in a `**For the reviewer**` block placed after the Testing block, one bullet per request, each followed by its answer or, where the pass could not answer it, by what would settle it. It carries no severity and enters no count.
+
+An unanswered bullet is owed the same way an unanswered Testing box is, so a pass carrying one takes `## Review` and the full body rather than either ✅ line. A bullet the pass answered is not owed, since the answer is discharged in the same comment that carries it. A pass still posting a numeric summary line, because a finding, a Testing question, or an unanswered bullet already forces one, says so there as `plus N reviewer request(s)`. The all-answered close-out below carries the block in place of that line and needs no addition to it.
+
+```markdown
+**For the reviewer**
+
+- Confirm the 401 and 403 split reads correctly for the public API. Confirmed — `AuthService.authenticate()` returns 401 for an expired token and 403 for a missing scope, and both paths are covered under `## Testing`.
+```
+
+The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity, a Testing question, and a reviewer request nobody has answered alike, which is what keeps the two halves from separating. Sending that dispatch is `claude-orchestrate`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
 
 Keying either half on the grade was measured wrong: across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed rather than recorded, so a floor at should-fix loses real fixes to a grade that runs low. Splitting the two halves so the dispatch fired lower than the heading was the other candidate, and it left a thread reading closed while work was owed on it. The Testing question was first written to sit outside both, which is that same split reached from the other side, and it left the one party who could answer the question with no route to it.
 
@@ -192,7 +206,7 @@ gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>
 
 A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and the board.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
 
-A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. A pass carrying only Testing questions takes the same route for the same reason. Keep whichever scope sentence the pass owes on the summary line:
+A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. A pass carrying only Testing questions, or only an unanswered reviewer request, takes the same route for the same reason. Keep whichever scope sentence the pass owes on the summary line:
 
 ```markdown
 ## Review
@@ -208,6 +222,8 @@ A pass carrying only minors is an ordinary finding-carrying pass, so it takes th
 
 A pass that closed by withdrawing a finding rather than by reading its fix takes neither ✅ line, per the withdrawal rule in Step 3. Both claim a fix landed, and the second names it, so posting either over a withdrawal credits work nobody did on the one comment a reader treats as the verdict. Write the withdrawal and the fact that settled it in place of the canned line, keeping the heading and the footer.
 
+A pass whose only content is a `## For the reviewer` block with every bullet answered, and that owes nothing else, takes the same shape: `## Review closed`, the block in place of the canned line, and the footer. The heading reports what the branch author still owes rather than what the pass did, and an answer discharged in the same comment owes nothing back.
+
 Post a close-out even when there is nothing to report. A review left with no closing comment reads as one nobody answered.
 
 ## Step 5: output
@@ -218,4 +234,6 @@ X critical, Y should-fix, Z minor. Posted to PR #<number>.
 
 Add `N Testing question(s) raised.` to that line when the Step 3 check raised any. The counts cover findings alone, so a pass whose only output was a question otherwise reports as silent to the session that drove it. That session is not who the question is addressed to, which is what the dispatch covers.
 
+Add `N reviewer request(s) answered.` to that line when the PR body carried a `## For the reviewer` section. The counts and the Testing question line both cover something else, so a pass that only answered a request otherwise reports as silent too.
+
 Report the merge decision as a plain recommendation in chat (merge, or address findings first). Do not merge.

package/docs/agents/demo.md

@@ -34,6 +34,10 @@ The plan is committed, not scratch. Its timing is a starting point tuned by watc
 
 `aitk demo run` reads the plan, refuses if a field is still empty, and drives the application the plan's URL names. It records the whole run to `webm` and writes the still from the beat the draft calls the hero, falling back to the last beat, since a demo's final state is the payoff and a cold open is usually an empty screen.
 
+A step's caption from the draft renders as an overlay while its hold plays, so the narration a person wrote is what shows on screen rather than the name of the action the engine performed.
+
+When `ffmpeg` is on PATH, the run also writes an mp4 beside the webm, since webm plays in a `<video>` tag but nothing else accepts it. A target without `ffmpeg` still gets the webm and a line naming what to install, and the run does not fail over the missing converter.
+
 | Option           | Behavior                                                    |
 | ---------------- | ----------------------------------------------------------- |
 | `--out <dir>`    | Directory to write into, overriding what the plan names     |
@@ -48,7 +52,7 @@ A step waits on its `waitFor` selector becoming visible and then holds for its o
 
 The browser engine's own annotation draws a red dot at the moment of a click and an action label in a corner. It paints no cursor, so a run without more looks like the pointer teleports between targets.
 
-The recorder injects a pointer element before navigation and moves it through the engine's pointer with interpolated steps rather than through the element-clicking helper, which resolves a target and jumps to it. The step count is the whole difference between a cursor that travels and one that appears. The pointer reads the element under it on every move and switches between an arrow, a hand, and a text beam, so it reflects the page the way a real cursor does.
+The recorder injects a pointer element before navigation and moves it through the engine's pointer with interpolated steps rather than through the element-clicking helper, which resolves a target and jumps to it. The step count is the whole difference between a cursor that travels and one that appears, and how many steps a move takes is derived from the machine's own round-trip cost rather than fixed, so the same plan glides at roughly the same pace on a loaded machine as an idle one. It also reads the element under it on every move and switches between an arrow, a hand, and a text beam, so it reflects the page the way a real cursor does.
 
 `--cursor` points at a folder of Windows cursor resources and the browser decodes them directly, with no conversion step and no image tooling. Each resource carries a hotspot per size, and the largest entry's hotspot scaled to the drawn size is what puts the artwork's tip where the click lands. A theme contributes per state, so a folder holding an arrow and no hand still supplies its arrow and the bundled artwork covers the rest.
 
@@ -77,6 +81,6 @@ The cost is stated rather than hidden: the browser binary installs separately, s
 
 ## What it does not do
 
-A generated recording is a raw take. Nothing trims it, scores it, or narrates it, and the beat's caption does not reach the video, since the engine's overlay carries the action it performed rather than text from the draft.
+A generated recording is a raw take. Nothing trims it or scores it beyond the caption each beat already carries.
 
 It also does not replace a narrated screencast. That has a hero moment, a cut list, and a voice, none of which survives being generated. This answers the case where the alternative is recording nothing.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/demo.ts

@@ -3,6 +3,7 @@ import { basename, dirname, extname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
+import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
 import { DEFAULT_CURSORS } from '@/demo/cursors'
 import { loadCursorTheme } from '@/demo/theme'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
@@ -89,6 +90,9 @@ export function register(program: Command): void {
         'Needs a browser binary. Install it with:',
         `  ${INSTALL_BROWSER}`,
         '',
+        'Writes mp4 beside the webm when ffmpeg is on PATH, and skips it',
+        `otherwise without failing the run. Install it with: ${INSTALL_CONVERTER}`,
+        '',
         'Exit codes:',
         '  0  the recording and the still were written',
         '  1  refused, with the reason on stderr',
@@ -283,14 +287,35 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
   logInfo(
     `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
   )
+
+  let mp4Path: string | undefined
+  let mp4Reason: string | undefined
+  if (result.videoPath) {
+    logStep('Container')
+    const converted = await convertToMp4(result.videoPath)
+    if (converted.status === 'converted') {
+      mp4Path = converted.mp4Path
+      logInfo(display(mp4Path))
+    } else if (converted.status === 'skipped') {
+      mp4Reason = converted.reason
+      logWarn('ffmpeg is not installed, so no mp4 was written.')
+      logWarn(`Install it with: ${INSTALL_CONVERTER}`)
+    } else {
+      mp4Reason = converted.reason
+      logWarn(`mp4 conversion failed: ${converted.reason}`)
+    }
+  }
+
   outro()
 
   emit(opts.json, {
     plan: source,
     video: result.videoPath ?? null,
+    mp4: mp4Path ?? null,
     still: result.stillPath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
+    ...(mp4Reason ? { mp4Reason } : {}),
   })
   return 0
 }

package/src/demo/compile.ts

@@ -13,11 +13,42 @@ import type { Beat, Draft } from '@/demo/beats'
  */
 
 /** Hand-tuned in spike 2 against one fixture. Nothing establishes them in general. */
-const POINTER_STEPS = 45
+const POINTER_TRAVEL_MS = 400
 const TYPE_DELAY_MS = 110
 const HOLD_MS = 600
 const FINAL_HOLD_MS = 1200
 
+/**
+ * A step is a round trip to the browser, so a fixed count reproduces the
+ * defect under a new name if it does not respond to the round-trip cost
+ * measured at drive time. The bounds guard the extremes a bad measurement
+ * could produce: too few steps teleports rather than glides, and a
+ * near-zero measured cost cannot be trusted enough to let the count run
+ * away.
+ *
+ * Measured on 2026-08-26 against a served fixture, post-navigation: 10
+ * rounds of `page.mouse.move` averaged 16.6 milliseconds a step, well short
+ * of either bound at the 400 millisecond default (about 24 steps). A
+ * machine landing under `POINTER_TRAVEL_MS / MAX_POINTER_STEPS`, 3.33
+ * milliseconds a step here, hits the cap and stops responding to a faster
+ * one still. Nothing measured here establishes where a real machine sits
+ * relative to that boundary in general.
+ */
+export const MIN_POINTER_STEPS = 6
+export const MAX_POINTER_STEPS = 120
+
+/**
+ * Pure on purpose: the round-trip cost comes from a real browser and can
+ * only be measured at drive time, so this takes it as an argument rather
+ * than measuring it itself, which is what keeps it testable against a
+ * stubbed cost.
+ */
+export function deriveSteps(travelMs: number, roundTripMs: number): number {
+  if (roundTripMs <= 0) return MAX_POINTER_STEPS
+  const steps = Math.round(travelMs / roundTripMs)
+  return Math.min(MAX_POINTER_STEPS, Math.max(MIN_POINTER_STEPS, steps))
+}
+
 const VIEWPORT = { width: 1280, height: 720 } as const
 const ANNOTATIONS = {
   durationMs: 900,
@@ -82,7 +113,7 @@ export interface DemoPlan {
   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 pointer: { readonly travelMs: number; readonly typeDelayMs: number }
   readonly annotations: typeof ANNOTATIONS
   readonly steps: readonly DemoStep[]
 }
@@ -103,7 +134,7 @@ export function compilePlan(draft: Draft, options: CompileOptions): DemoPlan {
       video: `${options.outDir}/${options.slug}.webm`,
       still: `${options.outDir}/${options.slug}.png`,
     },
-    pointer: { steps: POINTER_STEPS, typeDelayMs: TYPE_DELAY_MS },
+    pointer: { travelMs: POINTER_TRAVEL_MS, typeDelayMs: TYPE_DELAY_MS },
     annotations: ANNOTATIONS,
     steps: draft.beats.map((beat, position) =>
       compileStep(beat, {
@@ -218,7 +249,7 @@ export function parsePlan(text: string): PlanParse {
         still: asText(output.still) || `demos/${slug || 'demo'}.png`,
       },
       pointer: {
-        steps: asNumber(pointer.steps, POINTER_STEPS),
+        travelMs: asNumber(pointer.travelMs, POINTER_TRAVEL_MS),
         typeDelayMs: asNumber(pointer.typeDelayMs, TYPE_DELAY_MS),
       },
       annotations: ANNOTATIONS,

package/src/demo/container.ts

@@ -0,0 +1,63 @@
+import { join, parse } from 'node:path'
+import { execa } from 'execa'
+
+/**
+ * A post-step on the file `@/demo/drive` already wrote. It touches neither
+ * the compiler nor the driving code, which is why deferring it out of the
+ * feature that shipped first cost no rework.
+ */
+
+const CONVERTER_BIN = 'ffmpeg'
+export const INSTALL_CONVERTER = 'ffmpeg (see https://ffmpeg.org/download.html)'
+
+export type ContainerResult =
+  | { status: 'converted'; mp4Path: string }
+  | { status: 'skipped'; reason: 'converter-missing' }
+  | { status: 'failed'; reason: string }
+
+/**
+ * Writes mp4 beside the webm rather than instead of it, since both stated use
+ * cases are a `<video>` tag on a page the operator controls, where webm
+ * already plays, and the social platform case is what mp4 is for.
+ *
+ * A missing binary is reported as skipped rather than failed. The recording
+ * already succeeded, and failing the run over an optional step would discard
+ * a good artifact.
+ */
+export async function convertToMp4(
+  webmPath: string,
+  bin: string = CONVERTER_BIN,
+): Promise<ContainerResult> {
+  const { dir, name } = parse(webmPath)
+  const mp4Path = join(dir, `${name}.mp4`)
+
+  const result = await execa(
+    bin,
+    [
+      '-y',
+      '-i',
+      webmPath,
+      '-c:v',
+      'libx264',
+      '-pix_fmt',
+      'yuv420p',
+      '-c:a',
+      'aac',
+      '-movflags',
+      '+faststart',
+      mp4Path,
+    ],
+    { reject: false },
+  )
+
+  if (result.failed && result.code === 'ENOENT') {
+    return { status: 'skipped', reason: 'converter-missing' }
+  }
+  if (result.exitCode !== 0) {
+    return {
+      status: 'failed',
+      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
+    }
+  }
+  return { status: 'converted', mp4Path }
+}

package/src/demo/drive.ts

@@ -3,10 +3,17 @@ 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 { 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 {
+    __aitk_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
@@ -34,6 +41,10 @@ const POINTER_SIZE = 32
  */
 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 = '__aitk_demo_caption_bar__'
 
 /**
  * The two output paths arrive resolved rather than as a root this re-resolves
@@ -118,8 +129,10 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     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`
@@ -130,7 +143,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     }
 
     for (const step of plan.steps) {
-      await runStep(page, plan, step)
+      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.
@@ -187,10 +200,24 @@ async function launch(): Promise<Launch> {
   }
 }
 
-async function runStep(
+/**
+ * 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':
@@ -198,33 +225,47 @@ async function runStep(
       await page.mouse.move(START.x, START.y, { steps: 2 })
       break
     case 'click':
-      await moveTo(page, plan, step)
+      await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       break
     case 'fill':
-      await moveTo(page, plan, step)
+      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)
+      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)
+      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
@@ -237,16 +278,78 @@ 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: plan.pointer.steps,
+    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.__aitk_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.__aitk_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.__aitk_demo_caption__?.(text)
+  }, caption)
+}
+
 function failed(reason: DriveRefusal, error: unknown): DriveFailure {
   return {
     status: 'failed',

package/standards/pr.md

@@ -43,7 +43,7 @@ Does not govern:
 - `## Testing` (optional): specify exact commands or test cases run
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
-- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
+- `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
 
 ## Testing discipline
@@ -88,7 +88,7 @@ Does not govern:
 
 ## For the reviewer
 
-- <What the reviewer should confirm>
+- <What the reviewing session should confirm>
 ```
 
 ### Correct
@@ -134,5 +134,5 @@ This PR updates the authentication system to be more robust. # "This PR" opener
 
 - Tested manually # no specific command or case
 - [ ] `npm run test:auth` # unchecked box for a check the agent can run
-- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+- [ ] The reviewing session confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
 ```