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();
+ }
+});