@erclx/canon 4.53.0 → 4.55.0

package/scripts/core/regen-agent-fixture.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Writes web/src/fixtures/agent-view.json from a real `canon sessions list
+# --json` read of this repository's own sessions.
+#
+# The page it feeds re-creates an orchestrator dispatching workers, which is the
+# one thing this toolkit does that no other surface here shows. A re-creation
+# earns nothing if the rows behind it are invented, so the session half is a
+# live listing and never a literal.
+#
+# Every role in the roster appears, not the workers alone. The controlling
+# session is pinned above the bands and planners sit in them beside workers,
+# which is what the surface being re-created does. An earlier version of this
+# script filtered the listing down to sessions holding a feature branch, and
+# that dropped the orchestrator and every planner, since a controlling session
+# and a planning session both sit on the default branch. A page about a dispatch
+# that excludes the dispatcher is the defect that filter shipped.
+#
+# Two fields cannot come from the listing and are transcribed by hand into the
+# table below. The activity text is written by Claude Code into its own status
+# line and no verb here reports it. The pull request number sits on a task file
+# with nothing joining a session record to it, which the plan behind this script
+# took as a trade rather than building the join. Both are recorded as
+# transcribed in the fixture's own header, so a reader of the committed file can
+# tell which half was measured and which was typed.
+#
+# The honesty cost this leaves open is the one assets/captures/install.html.tmpl
+# already documents for the terminal frames: a hand-edit after generation
+# defeats the discipline silently, and nothing here detects one.
+#
+# Clone-only. It reads this repository's own sessions, and a registry install
+# carries no such listing.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+OUT="$PROJECT_ROOT/web/src/fixtures/agent-view.json"
+
+# Transcribed half, keyed by session name. The name is the only key that reaches
+# every row: a controlling session and a planning session both sit on the
+# default branch, so a branch cannot tell them apart or from each other. A
+# dispatched session is named `<role>-<project>-<slug>` after the work it was
+# given rather than after what it turned out to be doing, which is what makes
+# the name stable enough to key on here.
+#
+# Each row is `name|activity|pullRequest|state|age`. The state is `pinned`,
+# `working`, or `completed`, and it is where the row renders. An empty pull
+# request field is a session that had not reached its ship step when the
+# snapshot was taken.
+#
+# A pinned or working row has to appear in the live listing or this refuses, and
+# its age comes from the listing rather than the table, so the trailing field is
+# empty for those. A completed row names a session that has already exited, so
+# no listing carries it, its age is transcribed with the rest of the row, and
+# leaving that field blank would print an empty column on half the list.
+# Re-transcribe this table against a fresh listing rather than editing the
+# generated file.
+#
+# A planner belongs in this table as much as a worker does. `claude-planner`
+# forbids entering a worktree, so a planner registers on the default branch at
+# launch and stays there for its whole life, which is why the branch filter this
+# script used to carry dropped every one of them permanently rather than
+# occasionally.
+ROWS=(
+  "orchestrator-canon-lead|dispatching the planners that need a plan||pinned|"
+  "worker-canon-agent-view-and-deploy|PR #1510 open (landing page)|1510|working|" # canon-allow-reference: transcribed status text
+  "planner-canon-context-wireframe-draft|drafting the context and wireframe plan||working|"
+  "planner-canon-skill-coverage-pointers|reading the skill coverage pointers||working|"
+  "planner-canon-screenshot-trap-guard|planning the screenshot trap guard||working|"
+  "planner-canon-write-route-hook-bypass|plan written; tested write probe||completed|32m"
+  "planner-canon-indexes-list-lookup|plan and task board consistent||completed|13m"
+  "worker-canon-labels-scan-body-file|address-review pass finished|1508|completed|21m"
+  "worker-canon-web-context-entry|PR #1507 addressed with commit|1507|completed|20m" # canon-allow-reference: transcribed status text
+)
+
+# The listing reports a session's repository as the main `.git` directory, which
+# is what this resolves whether the script runs from the main checkout or from a
+# linked worktree. Comparing against PROJECT_ROOT instead would match nothing
+# from a worktree, where the two differ.
+MAIN_GIT_DIR="$(cd "$PROJECT_ROOT" && git rev-parse --path-format=absolute --git-common-dir)"
+
+# `bun src/cli.ts` rather than `canon`, since a globally linked binary resolves
+# to the main checkout no matter which worktree is running, and this script is
+# run from a worktree as often as not.
+SESSIONS_JSON="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts sessions list --json 2>/dev/null)"
+
+if [ -z "$SESSIONS_JSON" ]; then
+  echo "regen-agent-fixture: the session listing returned nothing, refusing to write an empty fixture" >&2
+  exit 1
+fi
+
+# The listing crosses into the eval as a file rather than an environment entry,
+# for the reason regen-hero.sh records: Linux caps a single env string at 128KB
+# and a machine running many sessions can cross it, which fails the exec with
+# E2BIG before any check can report a thing.
+SESSIONS_FILE="$(mktemp)"
+trap 'rm -f "$SESSIONS_FILE"' EXIT
+printf '%s' "$SESSIONS_JSON" >"$SESSIONS_FILE"
+
+TRANSCRIBED_ROWS="$(printf '%s\n' "${ROWS[@]}")"
+READ_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+export SESSIONS_FILE OUT PROJECT_ROOT READ_AT TRANSCRIBED_ROWS MAIN_GIT_DIR
+
+bun --eval '
+const { readFileSync } = require("node:fs")
+
+const { SESSIONS_FILE, OUT, PROJECT_ROOT, READ_AT, TRANSCRIBED_ROWS, MAIN_GIT_DIR } =
+  process.env
+
+const listing = JSON.parse(readFileSync(SESSIONS_FILE, "utf8"))
+
+const rows = TRANSCRIBED_ROWS.split("\n")
+  .map((line) => line.replace(/\s*#\s*canon-allow-reference:.*$/, "").trim())
+  .filter((line) => line !== "")
+  .map((line) => {
+    const [name, activity, pullRequest, state, age] = line.split("|")
+    return {
+      name,
+      activity,
+      pullRequest: pullRequest ? Number(pullRequest) : null,
+      state,
+      age: age || null,
+    }
+  })
+
+// Narrowed to this repository, and the reason is disclosure rather than scope.
+// `canon sessions list` is machine-wide, so an unfiltered read carries the
+// session names and worktree paths of every other project on the machine, which
+// here includes paths under a folder named `private` and several client names.
+// This fixture renders on a public page, so the filter is what keeps them off
+// it. The cost is a fidelity gap stated plainly: the real surface is
+// machine-wide and the depiction is one repository, and that is a deliberate
+// narrowing rather than an oversight.
+//
+// Keyed by name for the reason the shell comment gives: a session on the
+// default branch has no other identity, and the orchestrator and every planner
+// sit there.
+const live = new Map(
+  listing.sessions
+    .filter((session) => session.repository === MAIN_GIT_DIR)
+    .map((session) => [session.name, session]),
+)
+
+// The real surface shows an age per row, so the fixture carries one. It is
+// frozen at the read rather than live, which the rendered provenance line dates
+// so a reader is never told a stale figure is current.
+const ageLabel = (startedAt) => {
+  const minutes = Math.round(
+    (Date.parse(READ_AT) - Date.parse(startedAt)) / 60000,
+  )
+  if (!Number.isFinite(minutes) || minutes < 1) return "now"
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.round(minutes / 60)
+  return hours < 24 ? `${hours}h` : `${Math.round(hours / 24)}d`
+}
+
+// A row the page shows as running has to be running. Transcribing one that is
+// not is the failure the live half exists to prevent, so it refuses rather than
+// rendering.
+const absent = rows.filter(
+  (row) => row.state !== "completed" && !live.has(row.name),
+)
+if (absent.length > 0) {
+  console.error(
+    "regen-agent-fixture: no live session for " +
+      absent.map((row) => row.name).join(", ") +
+      ". Re-transcribe the table in this script against a fresh listing rather than editing the generated fixture.",
+  )
+  process.exit(1)
+}
+
+const sessions = rows.map((row) => {
+  const session = live.get(row.name)
+  return {
+    name: row.name,
+    branch: session ? session.branch : null,
+    state: row.state,
+    activity: row.activity,
+    pullRequest: row.pullRequest,
+    age: session ? ageLabel(session.startedAt) : row.age,
+  }
+})
+
+const ageless = sessions.filter((entry) => !entry.age)
+if (ageless.length > 0) {
+  console.error(
+    "regen-agent-fixture: no age for " +
+      ageless.map((entry) => entry.name).join(", ") +
+      ". A completed row carries its age in the table, since the session has exited and no listing reports one.",
+  )
+  process.exit(1)
+}
+
+// What the real surface prints above its own list. The remainder is every
+// session on the machine this page has no room to show, which is a real count.
+const summary = {
+  working: sessions.filter((entry) => entry.state === "working").length,
+  completed: sessions.filter((entry) => entry.state === "completed").length,
+  more: Math.max(0, listing.sessions.length - live.size),
+}
+
+const fixture = {
+  // Read by web/src/components/AgentView.astro. Every field below is either a
+  // live read or a hand transcription, and this header is what says which.
+  generatedBy: "scripts/core/regen-agent-fixture.sh",
+  readAt: READ_AT,
+  source: {
+    command: "canon sessions list --json",
+    live: [
+      "name",
+      "branch",
+      "age",
+      "that every pinned and working row is running",
+      "the remainder count",
+    ],
+    transcribed: {
+      activity:
+        "written by Claude Code into its own status line, which no verb here reports",
+      pullRequest:
+        "read off a task file by hand, since nothing joins a session record to one",
+      state:
+        "a completed session has already exited, so no listing carries the row at all",
+    },
+  },
+  summary,
+  sessions,
+}
+
+await Bun.write(OUT, JSON.stringify(fixture, null, 2) + "\n")
+console.error(
+  `regen-agent-fixture: wrote ${sessions.length} session rows to ${OUT.replace(PROJECT_ROOT + "/", "")}`,
+)
+'

package/src/claude/cases/authoring.ts

@@ -42,6 +42,16 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
     expect: 'docs-draft',
   },
+  {
+    prompt:
+      'Write a context entry for the payments domain, there is no .claude/context page for it yet.',
+    expect: 'context-draft',
+  },
+  {
+    prompt:
+      'Draft a wireframe for the settings panel, nothing under .claude/wireframes covers that surface yet.',
+    expect: 'wireframe-draft',
+  },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',
     expect: 'restate-plainly',

package/src/claude/cases/misc.ts

@@ -33,4 +33,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',
   },
+  {
+    prompt: 'Is there a page anywhere in this repo that covers retries?',
+    expect: 'index-lookup',
+  },
 ]

package/src/commands/demo.ts

@@ -4,7 +4,7 @@ import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
-import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
+import { convertToGif, 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'
@@ -30,6 +30,7 @@ interface RunOptions {
   readonly cursor?: string
   readonly video: boolean
   readonly still: boolean
+  readonly gif?: boolean
   readonly json?: boolean
 }
 
@@ -82,6 +83,7 @@ export function register(program: Command): void {
     )
     .option('--no-video', 'Skip the recording and write only the still')
     .option('--no-still', 'Skip the still and write only the recording')
+    .option('--gif', 'Also write a gif, for a host that strips video')
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -93,6 +95,9 @@ export function register(program: Command): void {
         'Writes mp4 beside the webm when ffmpeg is on PATH, and skips it',
         `otherwise without failing the run. Install it with: ${INSTALL_CONVERTER}`,
         '',
+        'A gif is opt-in behind --gif, since it is far larger than the webm',
+        'and only a host that strips video needs one. GitHub is that host.',
+        '',
         'Exit codes:',
         '  0  the recording and the still were written',
         '  1  refused, with the reason on stderr',
@@ -306,16 +311,35 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
     }
   }
 
+  let gifPath: string | undefined
+  let gifReason: string | undefined
+  if (result.videoPath && opts.gif) {
+    const converted = await convertToGif(result.videoPath)
+    if (converted.status === 'converted') {
+      gifPath = converted.gifPath
+      logInfo(display(gifPath))
+    } else if (converted.status === 'skipped') {
+      gifReason = converted.reason
+      logWarn('ffmpeg is not installed, so no gif was written.')
+      logWarn(`Install it with: ${INSTALL_CONVERTER}`)
+    } else {
+      gifReason = converted.reason
+      logWarn(`gif conversion failed: ${converted.reason}`)
+    }
+  }
+
   outro()
 
   emit(opts.json, {
     plan: source,
     video: result.videoPath ?? null,
     mp4: mp4Path ?? null,
+    gif: gifPath ?? null,
     still: result.stillPath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
     ...(mp4Reason ? { mp4Reason } : {}),
+    ...(gifReason ? { gifReason } : {}),
   })
   return 0
 }

package/src/commands/indexes.ts

@@ -2,6 +2,7 @@ import { stat } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
+import { buildIndexCatalog } from '@/indexes/list'
 import { exitCodeFor, type RegenResult, regenOne } from '@/indexes/regen'
 import { gitEnv } from '@/git-env'
 import { findIndexedAncestor, isIgnored, listIndexes } from '@/indexes/walk'
@@ -14,6 +15,10 @@ interface RegenCommandOptions {
   readonly stage?: boolean
 }
 
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const indexes = program
     .command('indexes')
@@ -51,6 +56,30 @@ export function register(program: Command): void {
     .action(async (paths: string[], opts: RegenCommandOptions) => {
       process.exitCode = await runRegen(paths, opts)
     })
+
+  indexes
+    .command('list')
+    .description('Flatten every folder index under a path into one catalog')
+    .argument('[path]', 'Folder to walk (default: cwd)')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable catalog on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  no frontmatter errors',
+        '  1  root not a directory, or a folder failed frontmatter validation',
+        '',
+        'Examples:',
+        '  canon indexes list',
+        '  canon indexes list --json docs/',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ListCommandOptions) => {
+      process.exitCode = await runList(path, opts)
+    })
 }
 
 async function runRegen(
@@ -115,6 +144,44 @@ async function runRegen(
   return exitCodeFor(results, { dryRun })
 }
 
+async function runList(
+  path: string | undefined,
+  opts: ListCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  if (!(await isDirectory(root))) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ error: `root not a directory: ${root}` })}\n`,
+      )
+      return 1
+    }
+    process.stderr.write(`Root is not a directory: ${root}\n`)
+    return 1
+  }
+
+  const catalog = await buildIndexCatalog(root)
+
+  for (const message of catalog.errors) {
+    process.stderr.write(`ERROR: ${message}\n`)
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...catalog })}\n`)
+  } else {
+    intro('canon indexes list')
+    logStep('Catalog')
+    for (const entry of catalog.entries) {
+      logInfo(`${entry.path}: ${entry.title} — ${entry.description}`)
+    }
+    outro()
+  }
+
+  return catalog.errors.length > 0 ? 1 : 0
+}
+
 function collectFromPaths(paths: string[], root: string): string[] {
   const dirs: string[] = []
 

package/src/demo/container.ts

@@ -15,6 +15,11 @@ export type ContainerResult =
   | { status: 'skipped'; reason: 'converter-missing' }
   | { status: 'failed'; reason: string }
 
+export type GifResult =
+  | { status: 'converted'; gifPath: 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
@@ -61,3 +66,59 @@ export async function convertToMp4(
   }
   return { status: 'converted', mp4Path }
 }
+
+/**
+ * Opt-in rather than written beside every recording, because a gif is an order
+ * of magnitude larger than the webm it derives from and only one destination
+ * needs one: a README on a host that strips `<video>`, which GitHub does. The
+ * mp4 above is unconditional for the opposite reason, being cheap and wanted
+ * wherever the webm already plays.
+ *
+ * A palette is generated from the source and then applied, rather than letting
+ * ffmpeg quantize per frame. A per-frame palette is what makes a screen
+ * recording of flat UI colors band and shimmer, which is precisely the artifact
+ * that would make a page look worse in the README than it does in a browser.
+ *
+ * Dithering is off because this command records applications rather than
+ * photographs. A global palette already covers flat interface colors, so the
+ * dither only writes noise the encoder then has to store: measured at 3.19MB
+ * against 2.70MB on one recording, with the same text region cropped from both
+ * and read as visually identical. Width is the larger lever at 2.38MB for 800
+ * pixels, and it is not taken, since the terminal rows are what the recording
+ * exists to have read. Frame rate is almost no lever at all.
+ *
+ * The missing-binary and failure handling matches `convertToMp4` exactly: the
+ * recording already succeeded by the time this runs, so an optional step never
+ * fails the run.
+ */
+export async function convertToGif(
+  webmPath: string,
+  bin: string = CONVERTER_BIN,
+): Promise<GifResult> {
+  const { dir, name } = parse(webmPath)
+  const gifPath = join(dir, `${name}.gif`)
+
+  const result = await execa(
+    bin,
+    [
+      '-y',
+      '-i',
+      webmPath,
+      '-filter_complex',
+      '[0:v] fps=12,scale=960:-1:flags=lanczos,split [a][b];[a] palettegen [p];[b][p] paletteuse=dither=none',
+      gifPath,
+    ],
+    { 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', gifPath }
+}

package/src/demo/drive.ts

@@ -38,6 +38,27 @@ const POINTER_SIZE = 32
  * first target. A corner keeps that first move out of the way of the content.
  */
 const START = { x: 8, y: 8 }
+
+/**
+ * Whether any step will move the pointer. The injected element installs on
+ * `DOMContentLoaded` and paints itself off-screen, so it costs nothing until
+ * something moves it, and seeding `START` is what first makes it visible.
+ *
+ * A plan that only navigates, scrolls and holds has nothing to point at, and
+ * seeding it anyway parked a cursor in the corner for the whole recording. That
+ * reads as a stuck artifact rather than a pointer, which is the same defect as
+ * resting it on a row of text, moved to a corner rather than fixed.
+ *
+ * `scroll` is absent deliberately. It is a targeted verb the compiler groups
+ * with the rest, and it stopped moving the pointer when a scroll step began
+ * leaving it where it was.
+ */
+function movesPointer(plan: DemoPlan): boolean {
+  return plan.steps.some(
+    (step) =>
+      step.kind === 'click' || step.kind === 'fill' || step.kind === 'hover',
+  )
+}
 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
@@ -100,16 +121,22 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       // Pointed the opposite way from a test. A recording wants the motion the
       // interface was designed with, where a test wants it suppressed.
       reducedMotion: 'no-preference',
+      // `showActions` is deliberately not passed. Playwright's annotation draws
+      // a dot on the interacted element and a title naming the API call it
+      // made, and this recorder already supersedes both: the injected pointer
+      // is a real cursor where the dot is a marker, and the caption bar carries
+      // the beat's narration where the title carries `Mouse move`. Leaving it
+      // on ran four overlays where two were wanted, and the two redundant ones
+      // were the two a viewer reads as noise. `plan.annotations` survives as a
+      // shape the type still carries and nothing now reads. It is not a record
+      // of what a committed plan configured, because `parsePlan` has always
+      // replaced it with the `ANNOTATIONS` constant rather than reading the
+      // file's own values, so that path never existed to preserve.
       ...(videoDir
         ? {
             recordVideo: {
               dir: videoDir,
               size: plan.viewport,
-              showActions: {
-                duration: plan.annotations.durationMs,
-                position: plan.annotations.position,
-                fontSize: plan.annotations.fontSize,
-              },
             },
           }
         : {}),
@@ -137,7 +164,9 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     // step for the same URL and the second load is a visible reload.
     if (plan.steps[0]?.kind !== 'navigate') {
       await page.goto(plan.url)
-      await page.mouse.move(START.x, START.y, { steps: 2 })
+      if (movesPointer(plan)) {
+        await page.mouse.move(START.x, START.y, { steps: 2 })
+      }
     }
 
     for (const step of plan.steps) {
@@ -217,7 +246,9 @@ export async function runStep(
   switch (step.kind) {
     case 'navigate':
       await page.goto(step.target || plan.url)
-      await page.mouse.move(START.x, START.y, { steps: 2 })
+      if (movesPointer(plan)) {
+        await page.mouse.move(START.x, START.y, { steps: 2 })
+      }
       break
     case 'click':
       await moveTo(page, plan, step, pace)
@@ -234,9 +265,36 @@ export async function runStep(
       await moveTo(page, plan, step, pace)
       break
     case 'scroll':
-      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      // Centred rather than `scrollIntoViewIfNeeded`, which scrolls the least
+      // it can and leaves a target taller than the remaining space flush
+      // against the bottom edge. Measured on this repository's own recording at
+      // 225 pixels of dead space above the content and 2 below, where centring
+      // splits it 114 and 113. A recording frames its subject, so the least
+      // scroll that technically reveals it is the wrong amount.
+      await page
+        .locator(step.target)
+        .first()
+        .evaluate((node) =>
+          node.scrollIntoView({
+            block: 'center',
+            inline: 'nearest',
+            // Explicit, because this runs in the page where
+            // `scrollIntoViewIfNeeded` ran through the debugging protocol and
+            // was always instant. An in-page scroll honours the document's own
+            // `scroll-behavior`, so a project setting it to `smooth` gets a
+            // call that returns before the scroll finishes, with only
+            // `SETTLE_MS` behind it. Nothing in this repository sets it, which
+            // is exactly why the recorder cannot catch this on its own pages.
+            behavior: 'instant',
+          }),
+        )
       await page.waitForTimeout(SETTLE_MS)
-      await moveTo(page, plan, step, pace)
+      // The pointer stays where it was. A scroll is not a pointing action, so
+      // gliding the cursor to the target's centre parks it on top of whatever
+      // the scroll just revealed and covers a row of it. A real session scrolls
+      // with a wheel and leaves the cursor alone. On a plan that points at
+      // nothing, `movesPointer` then keeps it off-screen for the whole run
+      // rather than parked in a corner.
       break
     case 'wait':
     case 'hold':

package/src/indexes/list.ts

@@ -0,0 +1,64 @@
+import { dirname, relative, resolve } from 'node:path'
+import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import { collectEntries } from '@/indexes/render'
+import { listIndexes } from '@/indexes/walk'
+
+export interface CatalogEntry {
+  readonly path: string
+  readonly title: string
+  readonly description: string
+}
+
+export interface IndexCatalog {
+  readonly entries: CatalogEntry[]
+  readonly errors: string[]
+}
+
+/**
+ * Flattens every folder index under `root` into one queryable catalog.
+ *
+ * A folder's own frontmatter error lands in `errors` without dropping the
+ * rest of the walk, the same isolation `regenOne` gives one folder.
+ */
+export async function buildIndexCatalog(root: string): Promise<IndexCatalog> {
+  const indexPaths = await listIndexes(root)
+  const entries: CatalogEntry[] = []
+  const errors: string[] = []
+
+  for (const indexPath of indexPaths) {
+    const dir = dirname(indexPath)
+    const frontmatter = await readFrontmatter(indexPath)
+    const title = readField(frontmatter, 'title')
+    const subtitle = readField(frontmatter, 'subtitle')
+
+    if (!title || !subtitle) {
+      errors.push(
+        `missing frontmatter field "title" or "subtitle" in ${indexPath}`,
+      )
+    } else {
+      entries.push({
+        path: relative(root, indexPath),
+        title,
+        description: subtitle,
+      })
+    }
+
+    const collected = await collectEntries(dir)
+    if (!collected.ok) {
+      errors.push(...collected.errors)
+      continue
+    }
+
+    for (const entry of collected.entries) {
+      entries.push({
+        path: relative(root, resolve(dir, entry.name)),
+        title: entry.title,
+        description: entry.description,
+      })
+    }
+  }
+
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  return { entries, errors }
+}