@erclx/aitk 3.11.2 → 3.12.1

package/src/demo/compile.ts

@@ -5,7 +5,7 @@ import type { Beat, Draft } from '@/demo/beats'
  * 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`.
+ * `.claude/groundwork/38-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
@@ -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/src/gov/adapter.ts

@@ -1,6 +1,8 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
+import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
+import { readStamp, stampedChain } from '@/sync/stamp'
 
 const RETIRED_GOV_FILE = join('.claude', 'GOV.md')
 
@@ -54,11 +56,38 @@ export function createGovAdapter(root: string): SyncAdapter {
     locateSource: (file: InstalledFile) =>
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
+    collectMissing: (target: string) => collectMissingGov(root, target),
     projectSubdir: 'project',
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }
 
+/**
+ * Rules the target's recorded chain entitles it to and its tree does not
+ * hold. Reports as `notice` text through the same shape `collectRetired`
+ * already returns, since both are surfaces the file walk cannot see: one an
+ * absence to remove, this one an absence to add.
+ */
+function collectMissingGov(root: string, target: string): RetiredSurface[] {
+  const chain = stampedChain(readStamp(target), 'governance')
+
+  return resolveMissingRules(root, target, chain).map((source) => {
+    const dest = join(
+      target,
+      '.claude',
+      'rules',
+      source.subdir,
+      `${source.rule}.md`,
+    )
+    const rel = relative(target, dest)
+    return {
+      path: dest,
+      rel,
+      notice: `${rel} (listed by ${chain[0]}, not installed. Run aitk gov install ${chain[0]} to add it.)`,
+    }
+  })
+}
+
 function collectRetiredGov(target: string): RetiredSurface[] {
   const path = join(target, RETIRED_GOV_FILE)
   if (!existsSync(path)) return []

package/src/gov/install.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
+import { basename, dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/copy'
 
 export interface RuleSource {
@@ -21,6 +21,27 @@ export function installedRulesDir(target: string): string {
   return join(target, '.claude', 'rules')
 }
 
+/**
+ * Rule names a target already holds, read off the installed tree by basename
+ * rather than off a recorded stack, since a target may hold rules `--add`
+ * layered on that no stack lists.
+ */
+export function installedRuleNames(target: string): Set<string> {
+  const dir = installedRulesDir(target)
+  const names = new Set<string>()
+  if (!existsSync(dir)) return names
+
+  for (const rel of new Bun.Glob('**/*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    names.add(basename(rel, '.md'))
+  }
+
+  return names
+}
+
 /**
  * Mirrors `rule_subdir` in `scripts/lib/gov.sh`, which stays in bash for the
  * sandbox loops. A rule sitting directly under `governance/rules/` has no

package/src/gov/stacks.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import {
+  installedRuleNames,
+  listRuleSourcePaths,
+  lookupRules,
+  type RuleSource,
+  rulesSourceDir,
+} from '@/gov/install'
 
 export interface GovStack {
   readonly name: string
@@ -151,6 +157,32 @@ export function unreferencedRules(root: string): string[] {
     .sort()
 }
 
+/**
+ * Rules the target's recorded chain entitles it to that its installed tree
+ * does not hold. `resolveRules` already walks a stack's `extends` ancestors,
+ * so reading its leaf entry is enough; no second walk resolves the chain
+ * itself. A stack the toolkit no longer ships resolves to nothing rather than
+ * throwing, the same way `readNewRules`'s band fallback already treats it.
+ */
+export function resolveMissingRules(
+  root: string,
+  target: string,
+  chain: readonly string[],
+): readonly RuleSource[] {
+  const stack = chain[0]
+  if (stack === undefined) return []
+
+  const resolution = resolveRules(root, stack)
+  if (!resolution.ok) return []
+
+  const { found } = lookupRules(root, resolution.rules)
+  const held = installedRuleNames(target)
+
+  return found
+    .filter((source) => !held.has(source.rule))
+    .sort((left, right) => left.rule.localeCompare(right.rule))
+}
+
 /**
  * Layers `--add` names on top of a resolved stack. The bash trimmed a single
  * leading and trailing space per entry; trimming fully is the same result for

package/src/intake/folder.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { readdir, readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import {
   INDEX_FILE,
   type IntakeItem,
@@ -13,6 +13,7 @@ import {
 export const INTAKE_REFUSALS = [
   'no-intake',
   'no-folder',
+  'ambiguous-slug',
   'no-cluster',
   'no-item',
   'answered',
@@ -110,6 +111,36 @@ async function listSlugs(dir: string): Promise<string[]> {
     .sort()
 }
 
+type SlugMatch =
+  | { readonly kind: 'matched'; readonly name: string }
+  | { readonly kind: 'ambiguous'; readonly names: readonly string[] }
+  | { readonly kind: 'none' }
+
+/**
+ * A folder carries a `<nn>-<slug>` name, but a caller names the topic alone.
+ * An exact match wins first, since it is what a name with no ordinal, or one
+ * already copied in full from a listing, resolves against. Otherwise the one
+ * entry whose name is an ordinal ahead of the given slug wins, which is what
+ * lets a topic keep working as its folder's identity gains a prefix. Two or
+ * more such entries is a collision the caller needs told apart from a typo,
+ * not a folder silently picked or silently missing.
+ */
+function matchSlug(names: readonly string[], slug: string): SlugMatch {
+  if (names.includes(slug)) return { kind: 'matched', name: slug }
+
+  const suffixed = names.filter(
+    (name) => name === `${extractOrdinal(name)}-${slug}`,
+  )
+
+  if (suffixed.length === 1) return { kind: 'matched', name: suffixed[0] }
+  if (suffixed.length > 1) return { kind: 'ambiguous', names: suffixed }
+  return { kind: 'none' }
+}
+
+function extractOrdinal(name: string): string {
+  return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
+}
+
 async function openFolder(
   root: string,
   slug: string,
@@ -120,17 +151,22 @@ async function openFolder(
     return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
   }
 
-  const folder = join(dir, slug)
+  const names = await listSlugs(dir)
+  const match = matchSlug(names, slug)
+
+  if (match.kind === 'none') {
+    return refuse('no-folder', `No intake folder named ${slug}.`, names)
+  }
 
-  if (!existsSync(folder)) {
+  if (match.kind === 'ambiguous') {
     return refuse(
-      'no-folder',
-      `No intake folder named ${slug}.`,
-      await listSlugs(dir),
+      'ambiguous-slug',
+      `More than one intake folder matches ${slug}.`,
+      match.names,
     )
   }
 
-  return folder
+  return join(dir, match.name)
 }
 
 /** Counts per folder, which is what a session picks a folder to work from. */
@@ -180,7 +216,11 @@ export async function readFolder(
   const opened = await openFolder(root, slug)
   if (typeof opened !== 'string') return opened
 
-  return { ok: true, slug, clusters: await readClusters(opened) }
+  return {
+    ok: true,
+    slug: basename(opened),
+    clusters: await readClusters(opened),
+  }
 }
 
 /**
@@ -272,7 +312,7 @@ export async function answerItems(
 
   return {
     ok: true,
-    slug,
+    slug: basename(opened),
     cluster: name,
     path,
     answered: selections,