From 14d4ea75b88e8ff7ae7712cd0c264709fb96a335 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 20:51:49 -0500 Subject: [PATCH] Confirm REPL bench interactions before dependent input --- examples/repl-bench/README.md | 20 +++++-- .../repl-bench/journeys/layout-queue.test.md | 7 +-- .../repl-bench/journeys/repl-bench.test.md | 5 +- .../journeys/repl-focus-shortcuts.test.md | 14 ++++- .../journeys/repl-inline-recovery.test.md | 7 +-- .../journeys/repl-saved-recovery.test.md | 4 +- .../journeys/repl-scripted-sidekick.test.md | 4 +- examples/repl-bench/lib/driver-bun.ts | 55 +++++++++++++++++++ examples/repl-bench/lib/protocol.ts | 7 +++ examples/repl-bench/lib/screen.ts | 28 ++++++++++ examples/repl-bench/plugin.ts | 13 ++++- examples/repl-bench/tests/screen.test.ts | 18 ++++++ 12 files changed, 155 insertions(+), 27 deletions(-) diff --git a/examples/repl-bench/README.md b/examples/repl-bench/README.md index dc5acb6a0..0b905246d 100644 --- a/examples/repl-bench/README.md +++ b/examples/repl-bench/README.md @@ -485,11 +485,15 @@ retained session again to verify that the current viewport supplies the size. | `Terminal.Region` | The paired `name="sidekick-composer"`, `name="transcript"`, or `name="history"` selects a visible region for its body. Nested regions override the selection for their body. Focus and pane selection stay where they were. | | `Terminal.WaitForText` | Waits for `text` in the nearest region or viewport. Optional `row` limits the match to a zero-based viewport row. Optional `at={{ row, column }}` matches its starting cell using zero-based coordinates. Optional `bold` matches the starting cell’s rendered bold attribute. `as` binds the unique positive match. Use `count` to wait for an exact number of matches. It cannot be combined with `as` or `present`. Zero matches or `present={false}` require the selected region to be visible. A `timeout` duration overrides the enclosing bench's wait duration. | | `Terminal.Scroll` | `delta` is the signed number of wheel steps over the nearest region. Zero does nothing. Nonzero steps require a visible scroll target. Optional `at={{ row, column }}` targets a cell inside the selected region or viewport. | +| `Repl.Sidekick.Activate` | Clicks the visible Sidekick tab and waits for the composer to gain focus. Start with focus elsewhere to exercise tab activation. | +| `Repl.Sidekick.OpenAnswer` | Clicks the visible Sidekick answer control and waits for focus in the answer editor. | For builds with numbered focus shortcuts, use the component for the region that should receive the next input. For example, use `` -before typing an entry. Each component sends the corresponding shortcut and -follows the [REPL focus rules](../../specs/repl-spec.md#move-between-regions-and-edit-within-them). +before typing an entry. Each component checks that its digit is offered, sends +it once, and waits for the REPL to dismiss the focus hints. An unavailable +digit fails the step and reports the offered shortcuts. See the +[REPL focus rules](../../specs/repl-spec.md#move-between-regions-and-edit-within-them). | Region | Component | | --- | --- | @@ -508,9 +512,15 @@ screen inspection require an active launch. The acceptance journeys also use `ReplBench` and `ReplBench.*`. Set initial dimensions on the enclosing `Terminal`. -`waitTimeout` sets the default `WaitForText` duration for an `` body, -including nested regions. It defaults to five seconds. Each bench supplies its -own duration, including when it uses `resume`. The enclosing `` deadline +Use the component that expresses the action you need. For a raw terminal gesture, +wait for the specific visible result before sending input that depends on it. +If the test exercises a burst of input, send the burst together and check its +result. Keep assertions for the journey’s outcome in the test. + +`waitTimeout` sets the default wait duration for `WaitForText` and the +`Repl.Focus.*` and `Repl.Sidekick.*` actions in an `` body, including +nested regions. It defaults to five seconds. Each bench supplies its own +duration, including when it uses `resume`. The enclosing `` deadline can end a wait earlier. Set `sidekick-agent` to an agent name or an explicit Markdown TestAgent path. diff --git a/examples/repl-bench/journeys/layout-queue.test.md b/examples/repl-bench/journeys/layout-queue.test.md index 63a24e67f..91d0b874d 100644 --- a/examples/repl-bench/journeys/layout-queue.test.md +++ b/examples/repl-bench/journeys/layout-queue.test.md @@ -16,8 +16,8 @@ - - + + @@ -51,8 +51,7 @@ - - + diff --git a/examples/repl-bench/journeys/repl-bench.test.md b/examples/repl-bench/journeys/repl-bench.test.md index eab0d3d8b..8e08194ff 100644 --- a/examples/repl-bench/journeys/repl-bench.test.md +++ b/examples/repl-bench/journeys/repl-bench.test.md @@ -27,10 +27,7 @@ - - - - + diff --git a/examples/repl-bench/journeys/repl-focus-shortcuts.test.md b/examples/repl-bench/journeys/repl-focus-shortcuts.test.md index 5ce95ba7b..5f7fb79b0 100644 --- a/examples/repl-bench/journeys/repl-focus-shortcuts.test.md +++ b/examples/repl-bench/journeys/repl-focus-shortcuts.test.md @@ -49,8 +49,15 @@ - - + + + + + + + + + @@ -58,7 +65,8 @@ - + + diff --git a/examples/repl-bench/journeys/repl-inline-recovery.test.md b/examples/repl-bench/journeys/repl-inline-recovery.test.md index 190edaf58..a1d7003a8 100644 --- a/examples/repl-bench/journeys/repl-inline-recovery.test.md +++ b/examples/repl-bench/journeys/repl-inline-recovery.test.md @@ -1,12 +1,11 @@ - - + + - - + diff --git a/examples/repl-bench/journeys/repl-saved-recovery.test.md b/examples/repl-bench/journeys/repl-saved-recovery.test.md index dcb16e8cc..8bd8075f8 100644 --- a/examples/repl-bench/journeys/repl-saved-recovery.test.md +++ b/examples/repl-bench/journeys/repl-saved-recovery.test.md @@ -1,7 +1,7 @@ - - + + diff --git a/examples/repl-bench/journeys/repl-scripted-sidekick.test.md b/examples/repl-bench/journeys/repl-scripted-sidekick.test.md index d762189e8..0074edf16 100644 --- a/examples/repl-bench/journeys/repl-scripted-sidekick.test.md +++ b/examples/repl-bench/journeys/repl-scripted-sidekick.test.md @@ -101,9 +101,7 @@ - - - + diff --git a/examples/repl-bench/lib/driver-bun.ts b/examples/repl-bench/lib/driver-bun.ts index 8a435df50..2c7c9b28c 100644 --- a/examples/repl-bench/lib/driver-bun.ts +++ b/examples/repl-bench/lib/driver-bun.ts @@ -323,6 +323,61 @@ export function useDriver(options: Launch) { ACTION_TIMEOUT, ); } + case "focus-shortcut": { + const { digit, timeout = ACTION_TIMEOUT } = command; + if (lastFrame().focusHints() === undefined) { + send(keyToAnsi(parseKey("Ctrl+G"))); + } + const hints = yield* wait( + `the numbered focus hints for shortcut [${digit}]`, + (frame) => frame.focusHints(), + timeout, + ); + if (!hints.includes(digit)) { + throw new Error( + `Focus shortcut [${digit}] is unavailable. Offered: ${hints.join(", ")}`, + ); + } + send(digit); + // The REPL keeps the hints open when a numbered shortcut is refused. + return yield* wait( + `the REPL to accept focus shortcut [${digit}]`, + (frame) => (frame.focusHints() === undefined ? true : undefined), + timeout, + ); + } + case "activate-sidekick": { + const { timeout = ACTION_TIMEOUT } = command; + const tab = yield* wait( + "the Sidekick tab", + (frame) => frame.sidekickControl(), + timeout, + ); + if (lastFrame().composerFocused) { + throw new Error( + "Move focus out of the Sidekick composer before testing tab activation", + ); + } + click(tab); + return yield* wait( + "the Sidekick composer to gain focus after clicking its tab", + (frame) => (frame.composerFocused ? true : undefined), + timeout, + ); + } + case "open-sidekick-answer": { + const { timeout = ACTION_TIMEOUT } = command; + const answer = yield* waitFor({ text: "[answer sidekick]", unique: true, timeout }); + if (answer === null || lastFrame().sidekickAnswerFocused) { + throw new Error("Expected a pending Sidekick question with its editor closed"); + } + click(answer); + return yield* wait( + "the Sidekick answer field to gain focus", + (frame) => (frame.sidekickAnswerFocused ? true : undefined), + timeout, + ); + } case "type": if (command.text.includes("\x1b[201~")) { throw new Error("Text contains the terminal’s paste delimiter"); diff --git a/examples/repl-bench/lib/protocol.ts b/examples/repl-bench/lib/protocol.ts index 8fab4c2d4..bd76b1e37 100644 --- a/examples/repl-bench/lib/protocol.ts +++ b/examples/repl-bench/lib/protocol.ts @@ -22,6 +22,13 @@ export const command = z.discriminatedUnion("action", [ z.object({ action: z.literal("ready") }), z.object({ action: z.literal("attachment-ready"), path: z.string() }), z.object({ action: z.literal("focus") }), + z.object({ + action: z.literal("focus-shortcut"), + digit: z.string().regex(/^[1-9]$/), + timeout: z.int().positive().optional(), + }), + z.object({ action: z.literal("activate-sidekick"), timeout: z.int().positive().optional() }), + z.object({ action: z.literal("open-sidekick-answer"), timeout: z.int().positive().optional() }), z.object({ action: z.literal("type"), text: z.string() }), z.object({ action: z.literal("key"), key: z.string().min(1) }), z.object({ action: z.literal("click"), at: point }), diff --git a/examples/repl-bench/lib/screen.ts b/examples/repl-bench/lib/screen.ts index 5a3dcd9d1..c87fd9937 100644 --- a/examples/repl-bench/lib/screen.ts +++ b/examples/repl-bench/lib/screen.ts @@ -15,6 +15,10 @@ export function viewport(backend: TerminalBackend, size: Size) { const colour = styled[row]?.[column]?.bg; return colour == null ? undefined : (colour.r << 16) | (colour.g << 8) | colour.b; } + function foreground({ row, column }: Point): number | undefined { + const colour = styled[row]?.[column]?.fg; + return colour == null ? undefined : (colour.r << 16) | (colour.g << 8) | colour.b; + } const full: Box = { left: 0, right: size.columns, top: 0, bottom: size.rows }; const rows = cells.map((row) => row.join("")); @@ -95,6 +99,30 @@ export function viewport(backend: TerminalBackend, size: Size) { bold: ({ row, column }: Point) => styled[row]?.[column]?.bold === true, composerLabel, composerFocused: composerLabel !== undefined && hasFocusMarker(composerLabel), + focusHints(): string[] | undefined { + for (const { row, column } of matches(" move focus · Esc closes")) { + if (row !== 0 && background(row, column + 1) !== REPL_PALETTE.drawerSurface) { + continue; + } + const before = cells[row].slice(0, column).join(""); + const offered = /(?:^|\s)([1-9](?: [1-9])*)$/.exec(before)?.[1]?.split(" "); + if ( + offered !== undefined && + [...matches(`[${offered[0]}]`)].some( + ({ row, column }) => background(row, column) === REPL_PALETTE.focusHint, + ) + ) { + return offered; + } + } + return undefined; + }, + get sidekickAnswerFocused(): boolean { + return ( + [...matches("> = ")].some((point) => foreground(point) === REPL_PALETTE.focus) && + matches("[submit]").next().value !== undefined + ); + }, box(region?: Region): Box | undefined { switch (region) { case "sidekick-composer": diff --git a/examples/repl-bench/plugin.ts b/examples/repl-bench/plugin.ts index 096b16a54..5e7c57a77 100644 --- a/examples/repl-bench/plugin.ts +++ b/examples/repl-bench/plugin.ts @@ -421,11 +421,19 @@ const focusActions = Object.entries({ SurfaceBar: "9", }).map(([area, key]) => registration(`Repl.Focus.${area}`, function* () { - yield* action({ action: "key", key: "Ctrl+G" }); - yield* action({ action: "key", key }); + yield* action({ action: "focus-shortcut", digit: key, timeout: yield* WaitTimeout.get() }); }), ); +const sidekickActions = [ + registration("Repl.Sidekick.Activate", function* () { + yield* action({ action: "activate-sidekick", timeout: yield* WaitTimeout.get() }); + }), + registration("Repl.Sidekick.OpenAnswer", function* () { + yield* action({ action: "open-sidekick-answer", timeout: yield* WaitTimeout.get() }); + }), +]; + const terminalActions = [ registration( "Terminal.Screenshot", @@ -558,6 +566,7 @@ export default Plugin({ })), ...terminalActions, ...focusActions, + ...sidekickActions, ...terminalActions.map((entry) => ({ ...entry, name: entry.name.replace("Terminal.", "ReplBench."), diff --git a/examples/repl-bench/tests/screen.test.ts b/examples/repl-bench/tests/screen.test.ts index aff6e41e5..dc7242b5d 100644 --- a/examples/repl-bench/tests/screen.test.ts +++ b/examples/repl-bench/tests/screen.test.ts @@ -41,3 +41,21 @@ Deno.test("recognizes the focused composer among lookalike queue and TODO rows", backend.destroy(); } }); + +Deno.test("reads the complete focus legend without treating document text as shortcuts", () => { + const backend = createXtermBackend({ cols: size.columns, rows: size.rows }); + try { + backend.feed(encoder.encode("XMD REPL\r\n[1] 1 5 move focus · Esc closes\r\n")); + assert.equal(viewport(backend, size).focusHints(), undefined); + + const badge = paint(REPL_PALETTE.focusHint, "[1]"); + backend.feed( + encoder.encode( + `${badge} ${paint(REPL_PALETTE.drawerSurface, "1 2 8 move focus · Esc closes")}\r\n`, + ), + ); + assert.deepEqual(viewport(backend, size).focusHints(), ["1", "2", "8"]); + } finally { + backend.destroy(); + } +});