From 0bfa1f75927de4f2f2b511c1802ac1f44f10a22b Mon Sep 17 00:00:00 2001
From: zerodice0 <zerodice0@gmail.com>
Date: Sat, 10 Oct 2026 09:12:28 +0900
Subject: [PATCH] feat(terminal): repeat a held key-bar arrow like a held key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Change

On a phone, holding an arrow on the touch key bar sent one key and then nothing. It now repeats like a held hardware key.

- `src/lib/keyRepeat.ts` holds the timing as a pure state machine with an injectable clock: no key on press, the first repeat after `KEY_REPEAT_DELAY_MS` (400 ms), then one every `KEY_REPEAT_INTERVAL_MS` (50 ms) until release. Only `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight` key items repeat, including saved combinations such as Ctrl+←; Esc, Tab, Enter, ^C, catalog keys and the modifier and mode buttons do not.
- A tap is unchanged: it still sends one key through `onKey` → `pressKey` on `click`. After a hold has repeated, the click that follows the release is swallowed, so a hold never ends with an extra key. Every repeat goes through the same `onKey` path (latest callback through a ref), so held Ctrl/Alt/Shift and saved combinations apply to each repeated key.
- `Key` in `KeyBar.tsx` tracks the primary pointer with pointer capture. The repeat stops on `pointerup`, `pointercancel`, `lostpointercapture`, the button becoming disabled, the document becoming hidden, the window losing focus, and unmount. KeyBar is not remounted when the pane changes, so `PaneTerminal` passes a `holdScope` (`paneStorageId:view`) and a change of pane or lens cancels the hold.
- A sideways swipe that starts on an arrow keeps scrolling the row and sends nothing: moving more than 10 px before the repeat starts cancels the pending hold, as does the `pointercancel` the browser sends when it takes over the pan.
- Keys prevent `contextmenu`, and `.key` sets `-webkit-touch-callout: none`, so a long press opens no callout or menu.
- No setting, WS frame or server change: the existing `keys` frame and the server's queue merge carry the repeat. No new UI strings.
- Docs: `docs/terminal-input.md` (key bar), `docs/development.md` and `scripts/ci-browser.sh` list the new browser regression. CHANGELOG: `Unreleased → Added`.

On the issue's open questions this PR takes the narrow side: only the four arrows repeat, and 400 ms / 50 ms are fixed constants.

Closes #718

## Validation

- `bun run generate:types --check`, `bun run typecheck`, `bun run build`: pass.
- `bun run test:unit`: 2237 pass, 0 fail, run with `TMPDIR=/tmp`. New `src/lib/keyRepeat.test.ts` covers tap/hold boundaries at the delay and interval, release and cancel, the one-shot click suppression, the movement slop and which items repeat. `scripts/ci-browser.test.ts` now expects 22 browser scripts.
- New `scripts/key-bar-hold-repeat-regression.ts` (demo transport, 393×852 touch context, CDP touch events): all 7 checks pass, in three runs before rebasing onto current `main` and one after:
  - a tap on ← sends exactly one key;
  - holding ← sends 10–11 keys, none before the delay, and nothing after release;
  - a hold shorter than the delay sends one key;
  - a horizontal swipe from ← scrolls the overflowing row and sends no key;
  - a held Esc does not repeat (Chrome sends no `click` after a long touch, so it sends no key, as before this change);
  - with Ctrl held, every repeated key is Ctrl+←;
  - a held arrow prevents the `contextmenu` default.
- `scripts/sticky-modifiers-regression.ts`, `scripts/key-bar-customization-demo-regression.ts`, `scripts/terminal-arrows-clicks-regression.ts`: pass.
- Tried by hand on a phone over Tailscale Serve against a server built from this branch: tap, hold, release and sideways scroll behaved as described.
- Not run: the full `bun run test:integration` and `bun run test:ui`.
---
 CHANGELOG.md                              |   5 +
 docs/development.md                       |   1 +
 docs/terminal-input.md                    |   5 +
 scripts/ci-browser.sh                     |   1 +
 scripts/ci-browser.test.ts                |   2 +-
 scripts/key-bar-hold-repeat-regression.ts | 224 +++++++++++++++++++++
 src/components/KeyBar.css                 |   1 +
 src/components/KeyBar.tsx                 |  91 ++++++++-
 src/components/PaneTerminal.tsx           |   1 +
 src/lib/keyRepeat.test.ts                 | 225 ++++++++++++++++++++++
 src/lib/keyRepeat.ts                      |  90 +++++++++
 11 files changed, 639 insertions(+), 7 deletions(-)
 create mode 100644 scripts/key-bar-hold-repeat-regression.ts
 create mode 100644 src/lib/keyRepeat.test.ts
 create mode 100644 src/lib/keyRepeat.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b052735e4..523ffbc126 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ between releases do not reach them. Remote-PC runtime bundles are versioned sepa
 
 ## [Unreleased]
 
+### Added
+- Holding an arrow in the touch key bar repeats it until release, including held modifiers and
+  saved arrow combinations. A tap still sends one key, and swiping sideways scrolls the row
+  without sending a key.
+
 ### Fixed
 - A request that carries a session cookie but states no `Origin` is now read as cross-site rather
   than same-origin, so a header that went missing is no longer trusted as though a browser had
diff --git a/docs/development.md b/docs/development.md
index 6a1b0a6ca8..47c1bbb294 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -71,6 +71,7 @@ bun test                        # needs herdr installed; creates and removes its
 bun run test:ui                 # browser regression against isolated test servers
 bun scripts/sticky-modifiers-regression.ts # mobile held keys through real legacy/Kitty PTYs
 bun scripts/key-bar-customization-demo-regression.ts # mobile key layout, saved combinations and migration on demo fixtures
+bun scripts/key-bar-hold-repeat-regression.ts # phone touch-arrow taps, holds, swipes and sticky Ctrl on demo fixtures
 bun scripts/settings-pages-demo-regression.ts # every Settings page on a 390px and a 320px phone, and Back stepping out of the dialog
 bun scripts/chat-browser-qa.ts  # chat lens end to end
 bun scripts/output-browser-qa.ts # terminal output flow control end to end
diff --git a/docs/terminal-input.md b/docs/terminal-input.md
index d60e0937df..a96d1a912a 100644
--- a/docs/terminal-input.md
+++ b/docs/terminal-input.md
@@ -62,6 +62,11 @@ menus, not this terminal-input row.
 Ctrl, Alt and Shift stay held until tapped again and can be combined. Removing a modifier button
 clears its held state immediately. Ordinary key buttons use the held modifiers, while saved
 combinations send exactly their configured modifiers without changing the held state.
+Holding one of the four arrows (↑ ↓ ← →) starts repeating after about 400 ms, then sends a
+key about every 50 ms until release. A tap still sends exactly one key. Every repeat uses the
+same held modifiers or saved combination as a tap. Only arrows repeat, including saved arrow
+combinations; other key-bar buttons do not. A sideways swipe scrolls the row without sending
+a key. Long presses on key buttons do not open a callout or context menu.
 Direct typing and arrow buttons send logical key chords; Herdr encodes them for the
 PTY's keyboard protocol. Home/End, Page and Delete/Insert keys use CSI navigation through the attach
 stream because Herdr's RPC key parser lacks those names. Paste, IME commits and terminal reports pass through unchanged.
diff --git a/scripts/ci-browser.sh b/scripts/ci-browser.sh
index 42cfe3b165..cbef447c9b 100644
--- a/scripts/ci-browser.sh
+++ b/scripts/ci-browser.sh
@@ -55,6 +55,7 @@ run_script scripts/terminal-dispose-browser-qa.ts
 run_script scripts/sticky-modifiers-regression.ts
 run_script scripts/terminal-arrows-clicks-regression.ts
 run_script scripts/key-bar-customization-demo-regression.ts
+run_script scripts/key-bar-hold-repeat-regression.ts
 run_script scripts/settings-pages-demo-regression.ts
 run_script scripts/chat-history-browser-qa.ts
 run_script scripts/math-browser-qa.ts
diff --git a/scripts/ci-browser.test.ts b/scripts/ci-browser.test.ts
index d1188068f2..7435ea5bc2 100644
--- a/scripts/ci-browser.test.ts
+++ b/scripts/ci-browser.test.ts
@@ -57,7 +57,7 @@ describe("browser lane", () => {
   it("summarizes every script and exits zero on success without enabling local evidence", async () => {
     const { text, code, evidence } = await lane();
     expect(code).toBe(0);
-    expect(rows(text)).toHaveLength(21);
+    expect(rows(text)).toHaveLength(22);
     expect(rows(text).every((row) => row.code === 0 && row.seconds >= 0)).toBe(true);
     expect(rows(text).at(-1)?.script).toBe("scripts/machine-conflict-regression.ts");
     expect(evidence).toBe(false);
diff --git a/scripts/key-bar-hold-repeat-regression.ts b/scripts/key-bar-hold-repeat-regression.ts
new file mode 100644
index 0000000000..bee9bd5a9f
--- /dev/null
+++ b/scripts/key-bar-hold-repeat-regression.ts
@@ -0,0 +1,224 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { chromium, type CDPSession, type Locator, type Page } from "playwright-core";
+import type { KeyBarItem } from "../src/lib/keyBar.ts";
+import { KEY_REPEAT_DELAY_MS, KEY_REPEAT_INTERVAL_MS } from "../src/lib/keyRepeat.ts";
+import panes from "../site/demo/fixtures/panes.json";
+import { buildDemoApp } from "./demo-build.ts";
+
+// Production client over the demo's synthetic transport. The disposable app only listens on
+// loopback; no herdr session, user terminal or real input transport is opened.
+const app = mkdtempSync(join(tmpdir(), "herdr-key-bar-hold-repeat-"));
+const evidence = process.env.UI_EVIDENCE_DIR;
+const HOLD_MS = KEY_REPEAT_DELAY_MS + 10 * KEY_REPEAT_INTERVAL_MS;
+// These waits measure a gesture or give unwanted sends time to appear, not app readiness.
+const NO_SEND_WAIT_MS = 4 * KEY_REPEAT_INTERVAL_MS;
+const keyBarItems: KeyBarItem[] = [
+  { type: "key", key: "Escape" },
+  { type: "modifier", modifier: "ctrl" },
+  { type: "key", key: "ArrowLeft" },
+  ...["ArrowUp", "ArrowDown", "ArrowRight", "Tab", "Enter", "Backspace", "Delete", "Home", "End", "PageUp", "PageDown", "F1", "F2", "F3", "F4"].map((key): KeyBarItem => ({ type: "key", key })),
+];
+
+type InputFrame =
+  | { type: "keys"; pane_id: string; keys: string[] }
+  | { type: "input"; pane_id: string; text: string };
+interface Recorder {
+  keyBarFrames: InputFrame[];
+  keyBarReleaseFrameCount: number | null;
+}
+interface Point { x: number; y: number }
+
+const framesOf = (page: Page): Promise<InputFrame[]> => page.evaluate(() => (window as unknown as Recorder).keyBarFrames);
+const framesSince = async (page: Page, before: number): Promise<InputFrame[]> => (await framesOf(page)).slice(before).filter((frame) => frame.pane_id === panes.api);
+const sentKeys = (frames: InputFrame[]): string[] => frames.flatMap((frame) => frame.type === "keys" ? frame.keys : []);
+const leftKeys = (frames: InputFrame[]): string[] => sentKeys(frames).filter((key) => key === "left" || key.endsWith("+left"));
+const settled = (page: Page): Promise<void> => page.evaluate(() => new Promise<void>((done) => requestAnimationFrame(() => requestAnimationFrame(() => done()))));
+const touch = (cdp: CDPSession, type: "touchStart" | "touchMove" | "touchEnd", point?: Point): Promise<unknown> =>
+  cdp.send("Input.dispatchTouchEvent", { type, touchPoints: point ? [{ x: point.x, y: point.y }] : [] });
+
+async function centerOf(key: Locator): Promise<Point> {
+  await key.scrollIntoViewIfNeeded();
+  const box = await key.boundingBox();
+  assert.ok(box, "the key is visible for the touch gesture");
+  return { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
+}
+
+/** Returns the frame boundary captured on pointerup, before React handles the release click. */
+async function hold(page: Page, cdp: CDPSession, key: Locator, duration: number, during?: () => Promise<void>): Promise<number> {
+  const point = await centerOf(key);
+  await page.evaluate(() => { (window as unknown as Recorder).keyBarReleaseFrameCount = null; });
+  await touch(cdp, "touchStart", point);
+  await Bun.sleep(duration);
+  await during?.();
+  await touch(cdp, "touchEnd");
+  await settled(page);
+  const boundary = await page.evaluate(() => (window as unknown as Recorder).keyBarReleaseFrameCount);
+  assert.notEqual(boundary, null, "a stationary held finger ends with pointerup");
+  return boundary!;
+}
+
+try {
+  await buildDemoApp(app);
+  const index = join(app, "index.html");
+  const html = readFileSync(index, "utf8");
+  assert.match(html, /<script type="module"/);
+  // The demo replaces WebSocket itself. Install this synchronous send recorder after the
+  // transport and before the app, so release checks cannot race delayed WS frame reporting.
+  const record = `<script>(() => {
+    const Demo = window.WebSocket;
+    window.keyBarFrames = [];
+    window.keyBarReleaseFrameCount = null;
+    document.addEventListener("pointerup", (event) => {
+      if (event.pointerType === "touch") window.keyBarReleaseFrameCount = window.keyBarFrames.length;
+    }, true);
+    window.WebSocket = function (url, protocols) {
+      const socket = new Demo(url, protocols);
+      const send = socket.send.bind(socket);
+      socket.send = (raw) => {
+        const frame = JSON.parse(String(raw));
+        if (frame.type === "input" || frame.type === "keys") window.keyBarFrames.push(frame);
+        send(raw);
+      };
+      return socket;
+    };
+    for (const name of ["CONNECTING", "OPEN", "CLOSING", "CLOSED"]) Object.defineProperty(window.WebSocket, name, { value: Demo[name] });
+  })();</script>`;
+  writeFileSync(index, html.replace(/<script type="module"/, () => `<script src="./demo-transport.js"></script>\n    ${record}\n    <script type="module"`));
+
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0, async fetch(request) {
+    const path = new URL(request.url).pathname;
+    const prefix = "/herdr-web-ui/demo/app/";
+    if (!path.startsWith(prefix)) return new Response("not found", { status: 404 });
+    let file: string;
+    try { file = decodeURIComponent(path.slice(prefix.length)); }
+    catch { return new Response("bad path", { status: 400 }); }
+    if (!file || file.endsWith("/")) file += "index.html";
+    if (file.split("/").includes("..") || file.includes("\\")) return new Response("bad path", { status: 400 });
+    const body = Bun.file(join(app, file));
+    return await body.exists() ? new Response(body) : new Response("not found", { status: 404 });
+  } });
+  try {
+    const browser = await chromium.launch({ executablePath: process.env.CHROME_PATH ?? chromium.executablePath(), headless: true, args: ["--no-sandbox"] });
+    try {
+      const context = await browser.newContext({ viewport: { width: 393, height: 852 }, isMobile: true, hasTouch: true, locale: "en-US" });
+      try {
+        await context.addInitScript(({ pane, items }) => {
+          localStorage.setItem("herdr-web-ui:settings", JSON.stringify({ language: "en", terminalInputMode: "direct", keyBarItems: items }));
+          localStorage.setItem(`herdr-web-ui:view:${pane}`, "terminal");
+        }, { pane: panes.api, items: keyBarItems });
+        const page = await context.newPage();
+        const errors: string[] = [];
+        page.on("pageerror", (error) => errors.push(error.message));
+        await page.goto(`http://127.0.0.1:${server.port}/herdr-web-ui/demo/app/?pane=${encodeURIComponent(panes.api)}`);
+        await page.locator(".conn-live").waitFor({ state: "attached" });
+        await page.waitForFunction(() => document.querySelector<HTMLButtonElement>('.key-bar .key[data-key="ArrowLeft"]')?.disabled === false, undefined, { timeout: 5_000 });
+        await page.locator(".xterm-helper-textarea").focus();
+        const bar = page.locator(".key-bar");
+        const left = bar.locator('.key[data-key="ArrowLeft"]');
+        const escape = bar.locator('.key[data-key="Escape"]');
+        const ctrl = bar.locator('.key[data-key="Control"]');
+        const cdp = await context.newCDPSession(page);
+
+        // 1. Playwright's touch tap drives pointerdown, pointerup and the normal click path.
+        let before = (await framesOf(page)).length;
+        await left.tap();
+        await Bun.sleep(NO_SEND_WAIT_MS);
+        assert.deepEqual(sentKeys(await framesSince(page, before)), ["left"], "a touch tap sends one Left, never two");
+        console.log("PASS touch tap Left sends exactly one key");
+
+        // 2. Count individual keys, not frames: a future transport may batch several keys.
+        before = (await framesOf(page)).length;
+        const release = await hold(page, cdp, left, HOLD_MS);
+        const repeats = leftKeys(await framesSince(page, before));
+        assert.ok(repeats.length >= 5, `a held Left repeats before release (got ${repeats.length})`);
+        assert.ok(repeats.every((key) => key === "left"), "unmodified Left repeats stay unmodified");
+        assert.equal((await framesOf(page)).length, release, "the release click sends nothing after repeat starts");
+        await Bun.sleep(NO_SEND_WAIT_MS);
+        assert.equal(leftKeys(await framesSince(page, before)).length, repeats.length, "no repeat arrives after release");
+        assert.equal((await framesOf(page)).length, release, "release stops all input sends");
+        console.log(`PASS holding Left repeats (${repeats.length} keys) and release sends no extra click or later key`);
+
+        // 3. The pending delay sends nothing: only the release click sends the short hold's key.
+        before = (await framesOf(page)).length;
+        await hold(page, cdp, left, Math.floor(KEY_REPEAT_DELAY_MS / 2), async () => {
+          assert.deepEqual(await framesSince(page, before), [], "a short hold sends no key while the finger is down");
+        });
+        await Bun.sleep(NO_SEND_WAIT_MS);
+        assert.deepEqual(sentKeys(await framesSince(page, before)), ["left"], "a short hold remains exactly one click");
+        console.log("PASS a hold shorter than the repeat delay sends exactly one key on release");
+
+        // 4. The seeded layout really overflows. Keep native CDP panning enabled: synthetically
+        // dispatching pointermove would test cancellation but could not prove the row scrolls.
+        await bar.evaluate((row) => { row.scrollLeft = 0; });
+        await settled(page);
+        const scroll = await bar.evaluate((row) => ({ left: row.scrollLeft, width: row.clientWidth, content: row.scrollWidth }));
+        assert.ok(scroll.content > scroll.width, "the swipe fixture has a horizontally scrollable key row");
+        const start = await centerOf(left);
+        const distance = Math.min(120, start.x - 12);
+        assert.ok(distance >= 80, "the arrow leaves room for an 80px horizontal swipe");
+        before = (await framesOf(page)).length;
+        await touch(cdp, "touchStart", start);
+        for (let step = 1; step <= 8; step += 1) {
+          await touch(cdp, "touchMove", { x: Math.round(start.x - distance * step / 8), y: start.y });
+          await Bun.sleep(16);
+        }
+        await touch(cdp, "touchEnd");
+        await page.waitForFunction((initial) => (document.querySelector(".key-bar")?.scrollLeft ?? initial) > initial, scroll.left, { timeout: 2_000 });
+        await Bun.sleep(KEY_REPEAT_DELAY_MS + NO_SEND_WAIT_MS);
+        assert.equal(leftKeys(await framesSince(page, before)).length, 0, "a swipe sends no arrow");
+        assert.deepEqual(await framesSince(page, before), [], "a swipe sends no other input either");
+        assert.ok(await bar.evaluate((row) => row.scrollLeft) > scroll.left, "the native swipe scrolls the overflowing row");
+        console.log("PASS horizontal swipe from Left scrolls the overflowing row and sends zero keys");
+
+        // 5. A non-repeatable key does not repeat when held beyond the repeat threshold.
+        await bar.evaluate((row) => { row.scrollLeft = 0; });
+        before = (await framesOf(page)).length;
+        await hold(page, cdp, escape, HOLD_MS, async () => {
+          assert.deepEqual(await framesSince(page, before), [], "Escape does not send or repeat while held");
+        });
+        await Bun.sleep(NO_SEND_WAIT_MS);
+        // Chrome's touch long-press can suppress the release click, so zero keys is also valid.
+        const escapeKeys = sentKeys(await framesSince(page, before));
+        assert.ok(escapeKeys.length <= 1 && escapeKeys.every((key) => key === "esc"), `held Escape does not repeat: ${JSON.stringify(escapeKeys)}`);
+        console.log("PASS held Escape does not repeat");
+
+        // 6. Repeats must use the same sticky-modifier path as the existing touch click.
+        await ctrl.tap();
+        assert.equal(await ctrl.getAttribute("aria-pressed"), "true", "Ctrl is armed");
+        before = (await framesOf(page)).length;
+        const modifiedRelease = await hold(page, cdp, left, HOLD_MS);
+        const modifiedFrames = await framesSince(page, before);
+        const modifiedKeys = sentKeys(modifiedFrames);
+        assert.ok(leftKeys(modifiedFrames).length >= 5, "Ctrl+Left repeats while held");
+        assert.ok(modifiedFrames.every((frame) => frame.type === "keys"), "every repeat stays on the logical keys path");
+        assert.ok(modifiedKeys.every((key) => key === "ctrl+left"), `every repeat carries Ctrl: ${JSON.stringify(modifiedKeys)}`);
+        assert.equal((await framesOf(page)).length, modifiedRelease, "Ctrl+Left has no extra release click");
+        await Bun.sleep(NO_SEND_WAIT_MS);
+        assert.equal((await framesOf(page)).length, modifiedRelease, "Ctrl+Left stops after release");
+        assert.equal(await ctrl.getAttribute("aria-pressed"), "true", "repeat does not consume sticky Ctrl");
+        await ctrl.tap();
+        console.log(`PASS sticky Ctrl applies to every held Left repeat (${modifiedKeys.length} Ctrl+Left keys)`);
+
+        // 7. Probe the cancelable contextmenu while the arrow is physically held, not after it.
+        await hold(page, cdp, left, KEY_REPEAT_DELAY_MS + KEY_REPEAT_INTERVAL_MS, async () => {
+          const prevented = await left.evaluate((key) => {
+            const event = new MouseEvent("contextmenu", { bubbles: true, cancelable: true, button: 2 });
+            const allowed = key.dispatchEvent(event);
+            return { defaultPrevented: event.defaultPrevented, allowed };
+          });
+          assert.deepEqual(prevented, { defaultPrevented: true, allowed: false }, "held keys prevent the contextmenu default");
+        });
+        console.log("PASS a held arrow prevents the contextmenu default");
+
+        if (evidence) {
+          mkdirSync(evidence, { recursive: true });
+          await page.screenshot({ path: join(evidence, "key-bar-hold-repeat-phone.png") });
+        }
+        assert.deepEqual(errors, [], "the phone demo has no page errors");
+      } finally { await context.close(); }
+    } finally { await browser.close(); }
+  } finally { server.stop(true); }
+} finally { rmSync(app, { recursive: true, force: true }); }
diff --git a/src/components/KeyBar.css b/src/components/KeyBar.css
index c0a4814ebd..e7630c7340 100644
--- a/src/components/KeyBar.css
+++ b/src/components/KeyBar.css
@@ -43,6 +43,7 @@
   cursor: pointer;
   user-select: none;
   -webkit-user-select: none;
+  -webkit-touch-callout: none;
   -webkit-tap-highlight-color: transparent;
   touch-action: manipulation;
   transition:
diff --git a/src/components/KeyBar.tsx b/src/components/KeyBar.tsx
index 7cc243ea21..f6588b5700 100644
--- a/src/components/KeyBar.tsx
+++ b/src/components/KeyBar.tsx
@@ -1,16 +1,19 @@
-import type { MouseEvent, PointerEvent, ReactNode } from "react";
+import { useCallback, useLayoutEffect, useRef, type MouseEvent, type PointerEvent, type ReactNode } from "react";
 import { Keyboard } from "lucide-react";
 
 import "./KeyBar.css";
 
 import type { KeyBarExtra, KeyBarKey, StickyModifiers } from "../lib/keys.ts";
 import { keyBarItemId, keyBarItemLabel, type KeyBarItem, type KeyBarKeyItem } from "../lib/keyBar.ts";
+import { createKeyRepeat, isRepeatableKeyBarItem, type KeyRepeat } from "../lib/keyRepeat.ts";
 import { useT } from "../lib/i18n.ts";
 
 export type { KeyBarKey };
 
 export interface KeyBarProps {
   disabled?: boolean;
+  /** Changing the terminal target or lens cancels any held arrow. */
+  holdScope?: string;
   /** Modifier buttons toggle; other keys go to the terminal. */
   onKey: (item: KeyBarKeyItem) => void;
   modifiers: StickyModifiers;
@@ -35,10 +38,51 @@ interface KeyProps {
   label?: string;
   pressed?: boolean;
   onPress: () => void;
+  repeatable?: boolean;
+  holdScope?: string;
   children: ReactNode;
 }
 
-function Key({ dataKey, label, pressed, onPress, children, disabled }: KeyProps) {
+function Key({ dataKey, label, pressed, onPress, children, disabled, repeatable, holdScope }: KeyProps) {
+  const onPressRef = useRef(onPress);
+  onPressRef.current = onPress;
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
+  const pointerRef = useRef({ id: null as number | null, pendingClick: false, cancelClick: false });
+  const repeatRef = useRef<KeyRepeat | null>(null);
+  if (repeatable && repeatRef.current === null) {
+    repeatRef.current = createKeyRepeat(() => {
+      if (!disabledRef.current) onPressRef.current();
+    });
+  }
+
+  const cancelHold = useCallback(() => {
+    const pointer = pointerRef.current;
+    if (pointer.pendingClick) pointer.cancelClick = true;
+    pointer.id = null;
+    repeatRef.current?.cancel();
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!repeatable || disabled) {
+      cancelHold();
+      return;
+    }
+    const onVisibilityChange = (): void => {
+      if (document.hidden) cancelHold();
+    };
+    window.addEventListener("blur", cancelHold);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      cancelHold();
+      window.removeEventListener("blur", cancelHold);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [cancelHold, disabled, holdScope, repeatable]);
+
+  const cancelPointer = (event: PointerEvent<HTMLButtonElement>): void => {
+    if (pointerRef.current.id === event.pointerId) cancelHold();
+  };
   return (
     <button
       type="button"
@@ -48,9 +92,43 @@ function Key({ dataKey, label, pressed, onPress, children, disabled }: KeyProps)
       aria-label={label}
       aria-pressed={pressed}
       tabIndex={-1}
-      onPointerDown={keepFocus}
+      onPointerDown={(event) => {
+        keepFocus(event);
+        if (!repeatable || disabled || event.button !== 0 || !event.isPrimary || pointerRef.current.id !== null) return;
+        const pointer = pointerRef.current;
+        pointer.id = event.pointerId;
+        pointer.pendingClick = true;
+        pointer.cancelClick = false;
+        repeatRef.current?.press(event.clientX, event.clientY);
+        // Capture keeps release/move visible outside the key; browser panning can still cancel it.
+        try { event.currentTarget.setPointerCapture(event.pointerId); } catch {}
+      }}
+      onPointerMove={repeatable ? (event) => {
+        if (pointerRef.current.id !== event.pointerId) return;
+        if (repeatRef.current?.move(event.clientX, event.clientY)) pointerRef.current.cancelClick = true;
+      } : undefined}
+      onPointerUp={repeatable ? (event) => {
+        if (pointerRef.current.id !== event.pointerId) return;
+        repeatRef.current?.release();
+        // Ignore the lost capture that follows release, preserving the click gate.
+        pointerRef.current.id = null;
+      } : undefined}
+      onPointerCancel={repeatable ? cancelPointer : undefined}
+      onLostPointerCapture={repeatable ? cancelPointer : undefined}
       onMouseDown={keepFocus}
-      onClick={onPress}
+      onContextMenu={keepFocus}
+      onClick={() => {
+        if (!repeatable) {
+          onPress();
+          return;
+        }
+        const pointer = pointerRef.current;
+        const allowed = repeatRef.current?.takeClick() ?? true;
+        const cancelled = pointer.cancelClick;
+        pointer.pendingClick = false;
+        pointer.cancelClick = false;
+        if (allowed && !cancelled && !disabled) onPress();
+      }}
     >
       {children}
     </button>
@@ -95,7 +173,7 @@ export const EXTRA_KEY_CAPS: Partial<Record<KeyBarExtra, { cap: string; label?:
  * for touch, a hardware keyboard already has all of them. Hence role="group", not
  * toolbar: a toolbar promises arrow-key navigation between items, which these skip.
  */
-export function KeyBar({ onKey, modifiers, onToggleModifier, items, directTyping, onToggleDirect, disabled }: KeyBarProps) {
+export function KeyBar({ onKey, modifiers, onToggleModifier, items, directTyping, onToggleDirect, disabled, holdScope }: KeyBarProps) {
   const t = useT();
   return (
     <div className="key-bar" role="group" aria-label={t("Terminal keys")}>
@@ -120,7 +198,8 @@ export function KeyBar({ onKey, modifiers, onToggleModifier, items, directTyping
           : item.key === "PageUp" ? t("Page up")
           : item.key === "PageDown" ? t("Page down")
           : extra?.label ? t(extra.label) : undefined;
-        return <Key key={keyBarItemId(item)} disabled={disabled} dataKey={item.modifiers === undefined ? item.key : keyBarItemId(item)} label={label} onPress={() => onKey(item)}>
+        return <Key key={keyBarItemId(item)} disabled={disabled} dataKey={item.modifiers === undefined ? item.key : keyBarItemId(item)} label={label} onPress={() => onKey(item)}
+          repeatable={isRepeatableKeyBarItem(item)} holdScope={holdScope}>
           {arrow && item.modifiers === undefined ? <Chevron direction={arrow.direction} /> : keyBarItemLabel(item)}
         </Key>;
       })}
diff --git a/src/components/PaneTerminal.tsx b/src/components/PaneTerminal.tsx
index 1071c302a6..71576a1046 100644
--- a/src/components/PaneTerminal.tsx
+++ b/src/components/PaneTerminal.tsx
@@ -2118,6 +2118,7 @@ export function PaneTerminal({
       )}
       {paneId !== null && !secretActive && !observing && !ended && inputLine && <TerminalInput key={paneId} owner={paneStorageId(machineId, paneId)} onComposing={setComposing} connected={connected && !held} onSend={sendTerminalLine} onEnter={pressEnter} />}
       {paneId !== null && !secretActive && !observing && !chatView && <KeyBar disabled={composing || !connected || !inputReady || held || ended} onKey={pressKey}
+        holdScope={`${paneStorageId(machineId, paneId)}:${view}`}
         modifiers={modifiers} onToggleModifier={toggleModifier} items={settings.keyBarItems}
         {...(coarse ? { directTyping, onToggleDirect: toggleDirect } : {})} />}
     </div>
diff --git a/src/lib/keyRepeat.test.ts b/src/lib/keyRepeat.test.ts
new file mode 100644
index 0000000000..621071943a
--- /dev/null
+++ b/src/lib/keyRepeat.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it } from "bun:test";
+import {
+  createKeyRepeat, isRepeatableKeyBarItem, KEY_REPEAT_DELAY_MS, KEY_REPEAT_INTERVAL_MS,
+  KEY_REPEAT_MOVE_SLOP_PX, type KeyRepeat, type KeyRepeatClock,
+} from "./keyRepeat.ts";
+
+interface ScheduledTimer {
+  at: number;
+  callback: () => void;
+}
+
+function fakeClock() {
+  let now = 0;
+  let nextId = 0;
+  const timers = new Map<unknown, ScheduledTimer>();
+  const clock: KeyRepeatClock = {
+    setTimeout(callback, delay) {
+      const id = ++nextId;
+      timers.set(id, { at: now + delay, callback });
+      return id;
+    },
+    clearTimeout(id) { timers.delete(id); },
+  };
+  return {
+    clock,
+    now: () => now,
+    pending: () => timers.size,
+    advance(ms: number) {
+      const end = now + ms;
+      while (true) {
+        let next: { id: unknown; timer: ScheduledTimer } | undefined;
+        for (const [id, timer] of timers) {
+          if (timer.at <= end && (!next || timer.at < next.timer.at)) next = { id, timer };
+        }
+        if (!next) break;
+        now = next.timer.at;
+        timers.delete(next.id);
+        next.timer.callback();
+      }
+      now = end;
+    },
+  };
+}
+
+function fixture() {
+  const clock = fakeClock();
+  const sends: number[] = [];
+  const repeat = createKeyRepeat(() => sends.push(clock.now()), clock.clock);
+  return { clock, repeat, sends };
+}
+
+describe("key bar hold repeat", () => {
+  it("sends a quick tap exactly once on click, never on pointerdown or the delay timer", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(20, 30);
+    expect(sends).toEqual([]);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    repeat.release();
+    clock.advance(KEY_REPEAT_DELAY_MS + KEY_REPEAT_INTERVAL_MS);
+    expect(sends).toEqual([]);
+    expect(clock.pending()).toBe(0);
+    if (repeat.takeClick()) sends.push(clock.now());
+    expect(sends).toHaveLength(1);
+  });
+
+  it("sends first at the delay boundary and then at each interval boundary", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    expect(sends).toEqual([]);
+    clock.advance(1);
+    expect(sends).toEqual([KEY_REPEAT_DELAY_MS]);
+    clock.advance(KEY_REPEAT_INTERVAL_MS - 1);
+    expect(sends).toHaveLength(1);
+    clock.advance(1);
+    expect(sends).toEqual([KEY_REPEAT_DELAY_MS, KEY_REPEAT_DELAY_MS + KEY_REPEAT_INTERVAL_MS]);
+    clock.advance(2 * KEY_REPEAT_INTERVAL_MS);
+    expect(sends).toEqual([
+      KEY_REPEAT_DELAY_MS, KEY_REPEAT_DELAY_MS + KEY_REPEAT_INTERVAL_MS,
+      KEY_REPEAT_DELAY_MS + 2 * KEY_REPEAT_INTERVAL_MS, KEY_REPEAT_DELAY_MS + 3 * KEY_REPEAT_INTERVAL_MS,
+    ]);
+  });
+
+  it("stops all future sends on release and swallows the following click only once", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS + KEY_REPEAT_INTERVAL_MS);
+    repeat.release();
+    repeat.release();
+    clock.advance(10 * KEY_REPEAT_INTERVAL_MS);
+    expect(sends).toHaveLength(2);
+    expect(clock.pending()).toBe(0);
+    expect(repeat.takeClick()).toBe(false);
+    expect(repeat.takeClick()).toBe(true);
+
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    repeat.release();
+    if (repeat.takeClick()) sends.push(clock.now());
+    expect(sends).toHaveLength(3);
+  });
+
+  it("clears stale hold-click suppression when a new press begins", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS);
+    repeat.release();
+    // A browser need not deliver a click after the first hold.
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    repeat.release();
+    expect(repeat.takeClick()).toBe(true);
+    expect(sends).toHaveLength(1);
+  });
+
+  it("allows an ordinary click with no preceding pointer press", () => {
+    const { repeat } = fixture();
+    expect(repeat.takeClick()).toBe(true);
+    expect(repeat.takeClick()).toBe(true);
+    repeat.release();
+    expect(repeat.takeClick()).toBe(true);
+  });
+
+  it("cancels before the delay without sending or leaving a timer", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    repeat.cancel();
+    repeat.cancel();
+    repeat.release();
+    clock.advance(2 * KEY_REPEAT_DELAY_MS);
+    expect(sends).toEqual([]);
+    expect(clock.pending()).toBe(0);
+    expect(repeat.takeClick()).toBe(true);
+  });
+
+  it("cancels an active repeat without sending again", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS);
+    repeat.cancel();
+    repeat.release();
+    clock.advance(2 * KEY_REPEAT_DELAY_MS);
+    expect(sends).toHaveLength(1);
+    expect(clock.pending()).toBe(0);
+    expect(repeat.takeClick()).toBe(true);
+  });
+
+  it("keeps movement exactly at the slop boundary but cancels beyond it before repeating", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(20, 30);
+    expect(repeat.move(20 + KEY_REPEAT_MOVE_SLOP_PX, 30)).toBe(false);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    expect(repeat.move(20 + KEY_REPEAT_MOVE_SLOP_PX + 1, 30)).toBe(true);
+    expect(repeat.move(20 + KEY_REPEAT_MOVE_SLOP_PX + 2, 30)).toBe(false);
+    repeat.release();
+    clock.advance(KEY_REPEAT_DELAY_MS);
+    expect(sends).toEqual([]);
+    expect(clock.pending()).toBe(0);
+  });
+
+  it("measures slop in both axes from the original press", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(20, 30);
+    expect(repeat.move(20, 30 - KEY_REPEAT_MOVE_SLOP_PX)).toBe(false);
+    expect(repeat.move(20 + KEY_REPEAT_MOVE_SLOP_PX, 31)).toBe(true);
+    clock.advance(KEY_REPEAT_DELAY_MS);
+    expect(sends).toEqual([]);
+  });
+
+  it("does not cancel movement after repetition has begun", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS);
+    expect(repeat.move(10 * KEY_REPEAT_MOVE_SLOP_PX, 10 * KEY_REPEAT_MOVE_SLOP_PX)).toBe(false);
+    clock.advance(KEY_REPEAT_INTERVAL_MS);
+    expect(sends).toHaveLength(2);
+    repeat.release();
+    expect(repeat.takeClick()).toBe(false);
+  });
+
+  it("restarts the delay on a new press and discards the previous hold timer", () => {
+    const { clock, repeat, sends } = fixture();
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    repeat.press(10, 20);
+    clock.advance(KEY_REPEAT_DELAY_MS - 1);
+    expect(sends).toEqual([]);
+    clock.advance(1);
+    expect(sends).toEqual([2 * KEY_REPEAT_DELAY_MS - 1]);
+    expect(clock.pending()).toBe(1);
+  });
+
+  it("does not schedule another tick when sending synchronously releases the hold", () => {
+    const clock = fakeClock();
+    let sends = 0;
+    let repeat: KeyRepeat;
+    repeat = createKeyRepeat(() => { sends++; repeat.release(); }, clock.clock);
+    repeat.press(0, 0);
+    clock.advance(KEY_REPEAT_DELAY_MS + 10 * KEY_REPEAT_INTERVAL_MS);
+    expect(sends).toBe(1);
+    expect(clock.pending()).toBe(0);
+    expect(repeat.takeClick()).toBe(false);
+  });
+});
+
+describe("repeatable key bar items", () => {
+  it("repeats only the four arrows, including arrows with saved modifiers", () => {
+    for (const key of ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]) {
+      expect(isRepeatableKeyBarItem({ type: "key", key })).toBe(true);
+      expect(isRepeatableKeyBarItem({ type: "key", key, modifiers: { ctrl: true, alt: true, shift: true } })).toBe(true);
+      expect(isRepeatableKeyBarItem({ type: "key", key, modifiers: { ctrl: false, alt: false, shift: false } })).toBe(true);
+    }
+  });
+
+  it("does not repeat catalog keys, printable keys or modifier buttons", () => {
+    for (const key of ["Escape", "Tab", "Enter", "ctrl-c", "Backspace", "Delete", "PageUp", "PageDown", "Home", "End", "F1", "a"]) {
+      expect(isRepeatableKeyBarItem({ type: "key", key })).toBe(false);
+      expect(isRepeatableKeyBarItem({ type: "key", key, modifiers: { ctrl: true, alt: false, shift: false } })).toBe(false);
+    }
+    for (const modifier of ["ctrl", "alt", "shift"] as const) {
+      expect(isRepeatableKeyBarItem({ type: "modifier", modifier })).toBe(false);
+    }
+  });
+});
diff --git a/src/lib/keyRepeat.ts b/src/lib/keyRepeat.ts
new file mode 100644
index 0000000000..5049e42033
--- /dev/null
+++ b/src/lib/keyRepeat.ts
@@ -0,0 +1,90 @@
+import type { KeyBarItem } from "./keyBar.ts";
+
+export const KEY_REPEAT_DELAY_MS = 400;
+export const KEY_REPEAT_INTERVAL_MS = 50;
+export const KEY_REPEAT_MOVE_SLOP_PX = 10;
+
+export function isRepeatableKeyBarItem(item: KeyBarItem): boolean {
+  return item.type === "key" && (item.key === "ArrowUp" || item.key === "ArrowDown"
+    || item.key === "ArrowLeft" || item.key === "ArrowRight");
+}
+
+export interface KeyRepeatClock {
+  setTimeout: (callback: () => void, delay: number) => unknown;
+  clearTimeout: (timer: unknown) => void;
+}
+
+export interface KeyRepeat {
+  press: (x: number, y: number) => void;
+  /** Returns true only when movement cancels a hold that has not started repeating. */
+  move: (x: number, y: number) => boolean;
+  release: () => void;
+  cancel: () => void;
+  /** Consumes the one click suppressed by a released, repeating hold. */
+  takeClick: () => boolean;
+}
+
+const defaultClock: KeyRepeatClock = {
+  setTimeout: (callback, delay) => globalThis.setTimeout(callback, delay),
+  clearTimeout: (timer) => globalThis.clearTimeout(timer as number),
+};
+
+/** A hold sends only from timers; a tap stays on the caller's ordinary click path. */
+export function createKeyRepeat(send: () => void, clock: KeyRepeatClock = defaultClock): KeyRepeat {
+  let timer: unknown = null;
+  let generation = 0;
+  let active = false;
+  let repeating = false;
+  let suppressClick = false;
+  let startX = 0;
+  let startY = 0;
+
+  const stop = (): void => {
+    generation++;
+    active = false;
+    repeating = false;
+    if (timer !== null) clock.clearTimeout(timer);
+    timer = null;
+  };
+
+  return {
+    press(x, y) {
+      stop();
+      suppressClick = false;
+      active = true;
+      startX = x;
+      startY = y;
+      const pressedGeneration = generation;
+      const repeat = (): void => {
+        if (!active || generation !== pressedGeneration) return;
+        timer = null;
+        repeating = true;
+        send();
+        // Sending may synchronously release/cancel this hold or start a new one.
+        if (active && generation === pressedGeneration) timer = clock.setTimeout(repeat, KEY_REPEAT_INTERVAL_MS);
+      };
+      timer = clock.setTimeout(repeat, KEY_REPEAT_DELAY_MS);
+    },
+    move(x, y) {
+      if (!active || repeating) return false;
+      const dx = x - startX;
+      const dy = y - startY;
+      if (dx * dx + dy * dy <= KEY_REPEAT_MOVE_SLOP_PX * KEY_REPEAT_MOVE_SLOP_PX) return false;
+      stop();
+      return true;
+    },
+    release() {
+      if (repeating) suppressClick = true;
+      stop();
+    },
+    cancel() {
+      stop();
+      suppressClick = false;
+    },
+    takeClick() {
+      const allowed = !suppressClick;
+      suppressClick = false;
+      return allowed;
+    },
+  };
+}