fix(usage): preserve migrated Go credential discovery

Follow the stored credential selection order so imported keys without an active flag remain discoverable, including when a legacy file is retained.

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
-## 0.15.0-beta.1 - 2026-11-01
+## 0.15.0 - 2026-11-03
 
-Daemon restarts now keep terminal programs running and automatically resume interrupted agents in their existing conversations.
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
 
 Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
 
@@ -13,7 +13,7 @@ Worktree setup can copy ignored files and use plugin-defined locations before ag
 - Insert known agent commands from replies into the Composer draft ([#8371](https://github.com/getpaseo/paseo/pull/8371))
 - Reuse running OpenCode v2 services ([#7435](https://github.com/getpaseo/paseo/pull/7435) by [@mcowger](https://github.com/mcowger))
 - Kept terminal programs running across daemon restarts, crashes and supported updates ([#7644](https://github.com/getpaseo/paseo/pull/7644), [#8155](https://github.com/getpaseo/paseo/pull/8155) by [@sebastianarena](https://github.com/sebastianarena))
-- Automatically resume interrupted agents in their existing conversations after a host restart ([#8127](https://github.com/getpaseo/paseo/pull/8127) by [@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
+- Added an opt-in setting to resume interrupted agents in their existing conversations after a host restart ([#8127](https://github.com/getpaseo/paseo/pull/8127), [#8619](https://github.com/getpaseo/paseo/pull/8619) by [@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
 - Added draggable terminal text-selection handles on iOS and Android ([#8348](https://github.com/getpaseo/paseo/pull/8348))
 - Let phones and tablets rotate with the system orientation setting ([#8256](https://github.com/getpaseo/paseo/pull/8256) by [@magiclaw](https://github.com/magiclaw), [@yzim](https://github.com/yzim))
 - Copy ignored files selected by `.worktreeinclude` into new worktrees before setup and agents start ([#8100](https://github.com/getpaseo/paseo/pull/8100) by [@cprecioso](https://github.com/cprecioso))
@@ -64,6 +64,7 @@ Worktree setup can copy ignored files and use plugin-defined locations before ag
 - Fixed the MiniMax Code catalog command failing to select an executable ([#8201](https://github.com/getpaseo/paseo/pull/8201) by [@Peanut-HZM](https://github.com/Peanut-HZM))
 - Fixed Android keeping the wrong layout after folding or unfolding while backgrounded ([#8285](https://github.com/getpaseo/paseo/pull/8285))
 - Fixed Android workspace layouts and header fades retaining their old size after rotation ([#8349](https://github.com/getpaseo/paseo/pull/8349), [#8377](https://github.com/getpaseo/paseo/pull/8377))
+- Fixed chat reconnecting and updating status being hidden behind the header on iOS and Android phones ([#8568](https://github.com/getpaseo/paseo/pull/8568))
 - Fixed deleted agents leaving unclosable tabs in another window ([#8248](https://github.com/getpaseo/paseo/pull/8248) by [@loganmeyer](https://github.com/loganmeyer))
 - Fixed transcript text retaining old theme colors after the theme changes while the window is hidden ([#8199](https://github.com/getpaseo/paseo/pull/8199) by [@Nurshot](https://github.com/Nurshot), [@dansabin](https://github.com/dansabin))
 - Fixed web menus snapping back to their loading size after content arrives ([#8180](https://github.com/getpaseo/paseo/pull/8180) by [@babo-jeonguk](https://github.com/babo-jeonguk))
@@ -74,7 +75,7 @@ Worktree setup can copy ignored files and use plugin-defined locations before ag
 ### Notes
 
 - The first upgrade from 0.14.0 still closes terminals; terminal preservation starts once the new daemon is installed, and Windows desktop app upgrades still close them
-- Automatic agent recovery is on by default and sends `Resume working.`; change the prompt or disable it in Host settings → Agents
+- Agent recovery is off by default; turn on **Resume agents after restart** in Host settings → Agents to send `Resume working.` or your own prompt
 - Before downgrading to 0.14.0, restore a backed-up `config.json` or remove the saved agent-resume and usage-check settings
 
 ## 0.14.0 - 2026-10-29

CHANGELOG.zh-CN.md

@@ -1,8 +1,8 @@
 # Changelog
 
-## 0.15.0-beta.1 - 2026-11-01
+## 0.15.0 - 2026-11-03
 
-daemon 重启后，终端中的程序继续运行，被中断的 Agent 会自动在原有会话中恢复工作。
+daemon 重启后，终端中的程序继续运行。开启 Agent 恢复后，被中断的 Agent 会在原有会话中恢复工作。
 
 移动端终端采用原生渲染，并提供可拖动的文本选择手柄。重新连接时最多恢复 10,000 行终端历史。
 
@@ -13,7 +13,7 @@ worktree 初始化支持复制被忽略的文件，并在 Agent 启动前使用
 - 点击回复中的已知 Agent 命令，将其插入 Composer 草稿 ([#8371](https://github.com/getpaseo/paseo/pull/8371))
 - 复用已运行的 OpenCode v2 服务 ([#7435](https://github.com/getpaseo/paseo/pull/7435)，贡献者：[@mcowger](https://github.com/mcowger))
 - 让终端中的程序在 daemon 重启、崩溃和支持的更新过程中继续运行 ([#7644](https://github.com/getpaseo/paseo/pull/7644), [#8155](https://github.com/getpaseo/paseo/pull/8155)，贡献者：[@sebastianarena](https://github.com/sebastianarena))
-- 主机重启后，自动在原有会话中恢复被中断的 Agent ([#8127](https://github.com/getpaseo/paseo/pull/8127)，贡献者：[@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
+- 新增可选设置，在主机重启后于原有会话中恢复被中断的 Agent ([#8127](https://github.com/getpaseo/paseo/pull/8127), [#8619](https://github.com/getpaseo/paseo/pull/8619)，贡献者：[@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
 - 在 iOS 和 Android 终端中新增可拖动的文本选择手柄 ([#8348](https://github.com/getpaseo/paseo/pull/8348))
 - 让手机和平板遵循系统屏幕旋转设置 ([#8256](https://github.com/getpaseo/paseo/pull/8256)，贡献者：[@magiclaw](https://github.com/magiclaw), [@yzim](https://github.com/yzim))
 - 通过 `.worktreeinclude` 选择要复制到新 worktree 的被忽略文件，在初始化和 Agent 启动前完成复制 ([#8100](https://github.com/getpaseo/paseo/pull/8100)，贡献者：[@cprecioso](https://github.com/cprecioso))
@@ -64,6 +64,7 @@ worktree 初始化支持复制被忽略的文件，并在 Agent 启动前使用
 - 修复了 MiniMax Code 目录命令无法选定可执行文件的问题 ([#8201](https://github.com/getpaseo/paseo/pull/8201)，贡献者：[@Peanut-HZM](https://github.com/Peanut-HZM))
 - 修复了 Android 应用在后台折叠或展开后保留错误布局的问题 ([#8285](https://github.com/getpaseo/paseo/pull/8285))
 - 修复了 Android 屏幕旋转后工作区布局和顶栏渐变保留旧尺寸的问题 ([#8349](https://github.com/getpaseo/paseo/pull/8349), [#8377](https://github.com/getpaseo/paseo/pull/8377))
+- 修复了 iOS 和 Android 手机聊天中重新连接和更新状态被顶栏遮挡的问题 ([#8568](https://github.com/getpaseo/paseo/pull/8568))
 - 修复了删除 Agent 后，另一个窗口留下无法关闭的标签页的问题 ([#8248](https://github.com/getpaseo/paseo/pull/8248)，贡献者：[@loganmeyer](https://github.com/loganmeyer))
 - 修复了窗口隐藏期间切换主题后，聊天文本保留旧主题颜色的问题 ([#8199](https://github.com/getpaseo/paseo/pull/8199)，贡献者：[@Nurshot](https://github.com/Nurshot), [@dansabin](https://github.com/dansabin))
 - 修复了网页菜单加载内容后跳回加载时尺寸的问题 ([#8180](https://github.com/getpaseo/paseo/pull/8180)，贡献者：[@babo-jeonguk](https://github.com/babo-jeonguk))
@@ -74,7 +75,7 @@ worktree 初始化支持复制被忽略的文件，并在 Agent 启动前使用
 ### 说明
 
 - 首次从 0.14.0 升级时仍会关闭终端；安装新 daemon 后才支持保留终端，Windows 桌面应用升级仍会关闭终端
-- Agent 自动恢复默认开启，并发送 `Resume working.`；可在主机设置 → Agent 中修改提示词或关闭此功能
+- Agent 恢复默认关闭；在主机设置 → Agent 中开启 **重启后恢复智能体**，即可发送 `Resume working.` 或自定义提示词
 - 降级到 0.14.0 前，请恢复备份的 `config.json`，或删除已保存的 Agent 恢复和用量查询设置
 
 ## 0.14.0 - 2026-10-29

CLAUDE.md

@@ -34,6 +34,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/hover.md](docs/hover.md)                                       | Hover — the canonical pattern (plain View + onPointerEnter/Leave, separate inner Pressable) and the three ways agents break it |
 | [docs/unistyles.md](docs/unistyles.md)                               | Unistyles gotchas — `useUnistyles()` is forbidden, alternatives in order                                                       |
 | [docs/floating-panels.md](docs/floating-panels.md)                   | Anchored popovers — Portal/Modal escape for Android, lifecycle gates, keyboard-shared-value, status-bar offset, the flash      |
+| [docs/keyboard-shortcuts.md](docs/keyboard-shortcuts.md)             | The binding table, per-platform key sources, badges vs routing, iOS `UIKeyCommand` limits                                      |
 | [docs/menus.md](docs/menus.md)                                       | The menu engine — popover vs sheet, submenu pages, hover intent, when a decision earns a submenu                               |
 | [docs/expo-router.md](docs/expo-router.md)                           | Expo Router route ownership, startup restore, and native blank-screen gotchas                                                  |
 | [docs/notifications.md](docs/notifications.md)                       | Notification tap ownership, native replay and acknowledgement, startup handoff, and payload QA                                 |

docs/agent-lifecycle.md

@@ -183,23 +183,42 @@ Some providers can create their own child sessions inside one provider runtime.
 
 The provider still owns the underlying runtime. Paseo keeps an agent record so the child can be opened, tracked, archived, and cascaded with the parent, but prompts and history hydration route through the provider adapter for that native child handle.
 
-## Background workspaces
+## Background visibility
 
-`workspace.background` controls discovery only. Background workspaces contain ordinary durable
-agents and terminals: provider history, plugin hooks, parentage, archive, and restart recovery
-keep their normal behavior. Visibility is creation-only; selecting an existing workspace cannot
-change it. New workspaces default to false, inherit the caller workspace's value when an agent
-creates one without an override, and accept explicit true or false.
+An agent is effectively background when it or its workspace is background:
+`agent.background || workspace.background`. Background controls discovery only. Background agents
+and the agents in background workspaces are ordinary durable agents: provider history, plugin
+hooks, parentage, finish notifications to a caller, archive, and restart recovery keep their
+normal behavior. Both flags are fixed at creation.
 
-The daemon derives agent discovery from workspace ownership. Default workspace and agent lists,
-including History requests, exclude background work; `filter.includeBackground` includes it.
-Exact-ID operations bypass discovery filtering. The app replicates both kinds and filters only
-its sidebar with **Show background**, so direct navigation and restored tabs remain available.
+- **Agent.** `create_agent_request.background` marks the agent. Use it for helpers the user does
+  not watch, such as a plugin's classifier in the user's open workspace. A background agent never
+  raises attention, adds nothing to its workspace's status bucket or Last prompt time, and stays
+  out of tabs, the parent's subagent track and agent lists in the app. A tab opened by id still
+  works.
+- **Workspace.** `workspace.background` hides the workspace from the sidebar unless **Show
+  background** is on.
+- **Inheritance.** When `background` is omitted, an agent created by a caller agent takes the
+  caller's own `background`. A new workspace takes the caller's effective background. A request
+  that creates its workspace applies `background` to both the agent and the workspace. Explicit
+  true or false always wins.
+
+`AgentDirectory` (`packages/server/src/server/agent/directory.ts`) owns visibility for lists.
+Default workspace and agent lists, including History requests, exclude background work;
+`includeBackground` includes it. Exact-ID operations bypass discovery filtering. The app
+replicates inclusively and filters at each surface.
+
+Sources without the `background_agents` hello capability get workspace-only visibility on
+inclusive reads and subscriptions: agents in background workspaces, but no agent-level background
+agents. Older apps replicate inclusively and auto-open a tab for every root agent, so a classifier
+run would otherwise open a tab each turn. That visibility has its own directory sync generation.
 
 Sequenced directories keep complete canonical collections. A filtered read must never replace
 those collections with its subset. Inclusive and default observations have distinct cursor
 scopes, so changing scope requires a fresh snapshot rather than reusing an incomplete cache.
-Clients gate creation and inclusive discovery on `features.backgroundWorkspaces`.
+Clients gate background workspaces and inclusive discovery on `features.backgroundWorkspaces`.
+They gate a background agent placed in an existing workspace or under a caller on
+`features.backgroundAgents`.
 
 ### Private daemon helpers
 

docs/android.md

@@ -174,7 +174,7 @@ REACT_NATIVE_PACKAGER_HOSTNAME=localhost \
 
 This is the Android counterpart of the iOS local-simulator flow in [development.md](development.md): on iOS the simulator shares the Mac's loopback so `localhost:<port>` works directly; on Android you need `10.0.2.2` or `adb reverse`.
 
-## Inverted timeline selection
+## Inverted timeline input
 
 Android focus and selection visibility requests must not reposition inverted timelines. The
 `modules/paseo-scroll` package keeps React Native's scroll manager interface and returns zero for
@@ -183,6 +183,10 @@ Native's Android list uses `scale: -1`, which decomposes into a 180-degree rotat
 `scaleY`; checking the scale property alone misses it. Dragging and explicit scroll
 commands still work; non-inverted scroll views keep Android's default behavior.
 
+Mouse wheel axes also bypass the inversion transform. The same module reverses the vertical
+wheel axis for inverted scroll views before delegating to Android, preserving native scroll
+bounds and React Native's scroll events and disabled-scroll behavior.
+
 Register this package before React Native's core package through its Expo config plugin. Normal
 Android builds use the prebuilt `react-android` library, so patching Java under `node_modules` does
 not change the shipped scroll view. Keep this behavior in the app's compiled native module.

docs/custom-providers.md

@@ -777,6 +777,8 @@ The built-in `claude` provider appends concrete model IDs from `~/.claude/settin
 
 This lets users who already configured Claude Code for Bedrock, OpenRouter, ollama, Z.AI, or another Anthropic-compatible gateway select the exact model ID in Paseo. Explicit model IDs are passed unchanged to Claude Code, even when the same string is a compatibility alias for a built-in model. When `agents.providers.claude.models` is set it **replaces** both the hardcoded first-party Claude list and any settings.json-discovered entries; use `agents.providers.claude.additionalModels` to keep the first-party list and append curated entries on top.
 
+Paseo's effort selector does not inherit `effortLevel` from Claude's settings.json. Select an effort in Paseo to choose a specific value.
+
 ### Gotcha: `extends: "claude"` with third-party endpoints
 
 When a custom provider extends `"claude"` but points `ANTHROPIC_BASE_URL` at a non-Anthropic API (Z.AI, Alibaba/Qwen, proxies), the Claude Agent SDK may try to use Anthropic-only server-side tools like `WebSearch`. Third-party APIs don't support these tools, causing errors.

docs/expo-router.md

@@ -96,7 +96,8 @@ hidden workspace can overwrite the remembered workspace before Settings or
 History returns.
 
 Plugin settings use the distinct `settings/hosts/[serverId]/plugins/[pluginId]/[screenId]` leaf;
-Back returns to that host's Plugins page.
+Back returns to that host's Plugins page. Its screen tabs change `screenId` with `router.setParams`,
+so switching tabs adds no stack entries.
 
 Settings detail routes are separate siblings on purpose. Keep
 `settings/[section]`, the host routes, the projects index, and project detail as

docs/forge-providers.md

@@ -97,19 +97,15 @@ Register the adapter in `defaultForgeRegistry` with:
 - `matchesHost` from manifest `cloudHosts`
 - `probeHost` when self-hosted/Enterprise detection is supported
 
-Current change-request lookup uses two identities deliberately:
+Current change-request lookup matches the branch and repository for both open and
+terminal requests. Prefer an open request, then a terminal request at the local
+HEAD, then the most recently updated terminal request. A reused branch can show
+its previous request until a new one opens. Auto-archive separately requires an
+observed open-to-merged transition and a fresh exact match between checkout HEAD
+and the PR head, along with the existing workspace safety checks.
 
-- An open PR/MR belongs to the checkout when its head branch and head repository
-  match. Its remote head SHA may differ because the checkout can be ahead,
-  behind, or contain commits that have not been pushed yet.
-- A merged or closed PR/MR belongs to the checkout only when its recorded head
-  SHA exactly matches the checkout's current `HEAD`. Branch names are reusable;
-  selecting the newest terminal request by branch alone can silently attach an
-  old promotion or feature request to new work.
-
-Thread the checkout head SHA through adapter cache and poll identities as well
-as the lookup itself. Otherwise a commit made on the same branch can inherit the
-previous commit's cached terminal status until the cache expires.
+Keep checkout HEAD in adapter cache and poll identities so checkout changes
+refresh the facts used by archive eligibility.
 
 Cloud hosts in the manifest are a bounded public-host list, not a self-host
 allowlist. Self-hosted detection is a trust gate: Paseo only talks to a forge
@@ -125,7 +121,8 @@ rendering stack:
 `acme.ts` exports a `ClientForgeLogicModule`:
 
 - `id`
-- optional `urlGrammar` (including `referencePaths` for composer auto-attachment)
+- optional `urlGrammar` (including `referencePaths` for composer auto-attachment
+  and Markdown shorthand references)
 - optional `facts` registration (schema, merge-capability, native-check fallbacks)
 
 `acme.view.tsx` exports a `ClientForgeViewModule`:
@@ -212,6 +209,12 @@ are stale, run `npm run build:server`.
   neutral extractor matches the pasted host and full repository path against
   the current remote before it invokes cwd-routed forge search. Do not add a
   central forge switch or guess a self-hosted Gitea-family brand from URL shape.
+- Shorthand references in rendered Markdown (`#12`, GitLab and Gitea `!12`,
+  cross-repository `owner/repo#12`) come from the `sigil` on each
+  `referencePaths` entry. Leave `sigil` off a kind the forge does not link in
+  prose: GitHub has no `!`, and its `#` targets `/issues/`, which GitHub
+  redirects to the pull request. `packages/app/src/git/forge-shorthand` builds
+  the recognition pattern from the workspace descriptor's forge and remote.
 - GitLab pipeline status constants belong to the GitLab adapter/client module,
   not protocol.
 - GitLab `manual` jobs need `allow_failure` to distinguish optional gray jobs

docs/glossary.md

@@ -28,6 +28,7 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **Workspace-owned state** — Per-workspace state that never leaks to a same-`cwd` sibling: tabs, agents, terminals, panes, title, plus review drafts, diff-mode overrides, composer attachments, and file-explorer open/expand state. Keyed by `workspaceId` (`cwd` only as a fallback for old payloads). See [architecture.md](architecture.md#right-sidebar-boundary-directory-backed-vs-workspace-owned).
 - **Last prompt** — Sidebar workspace sort by the most recent human prompt recorded by an agent in that workspace, including archived agents. Agent output, agent-to-agent messages, scheduled prompts, and opening a workspace do not count. A workspace without a human prompt uses its creation time.
 - **Workspace status bucket** — Aggregate activity signal for a workspace row. Same-`cwd` workspaces intentionally share agent and terminal status buckets, while tab, agent, and terminal visibility remains scoped by `workspaceId`.
+- **Background agent** — An agent hidden from default discovery and from app surfaces that announce agents: tabs, the subagent track, agent lists, workspace status and attention. It is otherwise an ordinary durable agent, addressable by id. An agent is effectively background when it or its workspace is background. Fixed at creation. Code: `background` on `AgentSnapshotPayload` and `create_agent_request`. See [agent-lifecycle.md](agent-lifecycle.md#background-visibility). Don't confuse with background work (provider shells and monitors) or the daemon's private internal helpers, which are never public ([agent-lifecycle.md](agent-lifecycle.md#private-daemon-helpers)).
 - **Agent session** — One running instance of an agent inside a workspace (one provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Moving toward this as the canonical term over "Agent". Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`).
 - **Session** — Two senses: (a) per-client connection to a daemon, internal; (b) user-facing agent session, see **Agent session**. Code: `Session` (`packages/server/src/server/session.ts`) for (a). Don't confuse with: provider-side agent session log.
 - **Profile** — Internal name for the persisted shape of a host. Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Never user-facing. Three other things are called "profile" in this codebase, so always qualify: **Agent profile**, **Terminal profile**, and the provider aliases in [custom-providers.md](custom-providers.md). Bare "profile" is forbidden in UI copy.

docs/keyboard-shortcuts.md

@@ -0,0 +1,86 @@
+# Keyboard shortcuts
+
+Define shortcuts in [the shared binding table](../packages/app/src/keyboard/keyboard-shortcuts.ts). Platforms contribute key sources, not separate action maps, so matching and user rebinds stay consistent across runtimes. Add a shortcut through a binding; add platform support through a key source.
+
+## Badges and routing
+
+Routing runs whenever the app mounts its key sources, independently of layout.
+Use `useHardwareKeyboardPresent()` for hints and the Shortcuts settings section.
+iOS reads `GCKeyboard.coalesced` and connection notifications. Android watches input
+devices and hardware keyboard configuration. Web starts with a fine hover pointer and recognizes the first modified
+keydown, including on touch devices. Compact Electron keeps its bindings.
+
+Keyboard navigation needs the sidebar's filtered workspace model even when its visual
+panel is hidden. Retain that model while keyboard navigation is active; gating it on
+panel visibility leaves number shortcuts with no targets after a compact startup.
+
+Composer send-key customization remains a separate capability. Native retains its
+existing Return submission path; advertising its web-only customization would expose
+settings the native composer does not implement.
+
+## Native sources
+
+Use the iOS window press stream for hardware keys. `UIKeyCommand` only takes keys
+that must bypass the focused text control: composer Return and the top overlay's
+Enter and arrows. Keep the stream as the sole shortcut emitter: a command-owned
+press is still observed by the window.
+
+The source spike used an iPad Pro 11-inch (M4) simulator on iOS 18.6 with a
+`UITextView` first responder. Both `UIWindow.sendEvent` and the root controller's
+`pressesBegan` received Cmd+B, Cmd+P and Escape. With Escape registered as a
+`UIKeyCommand`, the window observed it and the command handler also ran.
+
+Simulator reserves Cmd+K for Toggle Software Keyboard. Injecting it produced
+HID 184 with empty characters rather than K; plain K, Cmd+B and Cmd+P arrived
+normally. Keep Simulator input capture off: Send Keyboard Input to Device
+prevented synthetic AppleScript input from arriving, including plain text.
+For simulator QA, use Cmd+B/P to check delivery and rebind the command center to
+Cmd+J to check toggle and rebind behavior. Cmd+K delivery needs a physical iPad.
+Simulator also reserves Cmd+1…4, Cmd+Shift+A and Cmd+comma. Exercise those actions
+through rebinds. For numeric injection, use AppleScript physical key codes (for example
+25 for 9); `keystroke "9"` did not deliver a digit in the QA session.
+Simulator exposes a virtual `GCKeyboard` even with Connect Hardware Keyboard off.
+Verify the iOS absence case on a physical iPhone.
+
+Never register Backspace: it would take deletion away from text fields. Changes
+to the native module require a native rebuild; an over-the-air JavaScript update
+cannot deliver them.
+
+## Overlay ownership
+
+Register keyboard handling with `useOverlayRegistration` from `@/keyboard`.
+Pass the surface's open state, layer, handled keys and `onKeyDown`. The highest
+layer gets first refusal; the latest registration wins a tie. Native registration
+does not need a DOM ref. Web adds focus trapping and restoration through its adapter.
+
+Capture a global overlay’s layer in state for its opening lifetime. Memo caches can
+be discarded or removed by React Compiler; recomputing against the registry lets an
+open modal rise above its own children and creates competing focus traps.
+
+Declare Enter and arrow keys only while the surface owns them. Native sources
+use the top overlay's declarations to take those keys before text controls edit.
+Backspace stays with the focused input. Composition confirmation must not select
+an overlay row or submit the composer.
+
+Android modals have their own windows. Observe them through React Native's
+`ExtraWindowEventListener` as well as the activity window. The dev client bypasses
+Expo's root-container handler, so an activity root-view wrapper misses presses.
+A modal can forward an unhandled event into the activity window. Observe the event
+once across that nested delivery without retaining recycled Android `KeyEvent`s.
+Keep an overlay-owned press consumed through key-up, even if its key-down closes
+the overlay; otherwise the modal's default Escape handler can close a second layer.
+
+iOS scene startup installs the observing window after Expo creates its root view.
+Keep that integration in the hardware keyboard module's config plugin. Its window
+owns both the press stream and the text-control key commands, including above modals.
+
+## Focus scopes
+
+The composer and terminal declare focus with `useKeyboardFocusSurface`. Native
+scope derives from those declarations and command-center state. Releasing an old
+surface must not clear a newer owner's declaration during a tab switch. Web keeps
+its DOM-derived scope.
+
+Escape interrupts an agent only in the message input or an unclaimed surface.
+A focused terminal excludes that binding. The source leaves terminal Escape alone;
+terminal Escape/Ctrl forwarding is a separate feature.

docs/markdown-renderer.md

@@ -10,9 +10,9 @@ Every block is separated by one gap, `density.blockGap`: 12 on compact layouts,
 
 ## Links and images
 
-Workspace file links use the shared file-link resolver. The workspace supplies its client, root and open-file action once; chat can supply the agent's more specific context. URLs use the same link press path. Recognized inline-code paths stay tappable. The library callback carries the tapped occurrence’s syntax context. Preserve it when opening files: explicit Markdown links decode URL escapes, while recognized inline-code paths preserve literal percent characters and use suffix lookup. Identical URL strings in different occurrences must stay distinct. Explicit absolute workspace links receive a relative hover title; existing authored titles remain intact.
+Workspace file links use the shared file-link resolver. The workspace supplies its client, root and open-file action once; chat can supply the agent's more specific context. URLs use the same link press path. Recognized inline-code paths stay tappable. The library callback carries the tapped occurrence’s syntax context. Preserve it when opening files: explicit Markdown links decode URL escapes, while recognized inline-code paths preserve literal percent characters and use suffix lookup. Identical URL strings in different occurrences must stay distinct. Explicit absolute workspace links receive a relative hover title; existing authored titles remain intact. Inside a workspace, forge references such as `#12` and `owner/repo#12` are recognized in prose (not code) and open the workspace forge; the reference pattern comes before path recognition so `group/project#12` is not read as a path. See [forge providers](forge-providers.md#gotchas).
 
-Resolve workspace image paths over the existing session RPC, then give the library a cached native file URL or web blob URL. HTTP(S) images pass through unchanged. This preserves relay, SSH and local socket connections, which do not expose a daemon HTTP endpoint. Each mounted renderer owns its image acquisition identity, so a later reply reads a rewritten path again while the earlier mounted reply retains its snapshot. Image taps open the attachment lightbox. File previews resolve relative images against the Markdown file's directory. An image alone on its line becomes its own paragraph before the library sees it, so it renders as a block on every platform; the library only treats sole-child paragraph images as blocks, and with hard soft breaks every newline is a break node, which left own-line images inline on iOS and web. Images that share a line with text stay inline.
+Resolve workspace image paths over the existing session RPC, then give the library a cached native file URL or web blob URL. HTTP(S) images pass through unchanged. This preserves relay, SSH and local socket connections, which do not expose a daemon HTTP endpoint. Each mounted renderer owns its image acquisition identity, so a later reply reads a rewritten path again while the earlier mounted reply retains its snapshot. Image taps open the attachment lightbox. File previews resolve relative images against the Markdown file's directory. An image alone on its line becomes its own paragraph before the library sees it, so it renders as a block on every platform; the library only treats sole-child paragraph images as blocks, and with hard soft breaks every newline is a break node, which left own-line images inline on iOS and web. Images that share a line with text stay inline at line height and keep their aspect ratio. A linked image counts as an image, so review-bot badges such as `[![Retrigger](badge.svg)](url) Confidence` stay inline on web; the library's web renderer only checked direct paragraph children, so it rendered them as full-width block images (local patch in `patches/react-native-enriched-markdown+*.patch`).
 
 ## Engine constraints
 

fastlane/metadata/android/en-US/changelogs/150001.txt

@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog

fastlane/metadata/android/en-US/changelogs/150002.txt

@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog

fastlane/metadata/android/en-US/changelogs/150003.txt

@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog

fastlane/metadata/android/en-US/changelogs/150004.txt

@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-KN/AVZV/o0TleLLpmggSrdJqjFDJ/NJYVHiC54xb4jQ=
+sha256-VdM4lXdgNEXPpTfvHSFvF9nm302rK/ZbVkZUp9tyOfg=

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -36762,7 +36762,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -38930,12 +38930,13 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.15.0-beta.1",
-        "@getpaseo/protocol": "0.15.0-beta.1",
-        "@getpaseo/server": "0.15.0-beta.1",
+        "@getpaseo/client": "0.15.0",
+        "@getpaseo/protocol": "0.15.0",
+        "@getpaseo/server": "0.15.0",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -39182,10 +39183,11 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
-        "@getpaseo/protocol": "0.15.0-beta.1",
-        "@getpaseo/relay": "0.15.0-beta.1",
+        "@getpaseo/protocol": "0.15.0",
+        "@getpaseo/relay": "0.15.0",
         "ws": "^8.20.0",
         "zod": "^4.4.3"
       },
@@ -39197,7 +39199,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -40034,7 +40036,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -40080,7 +40082,8 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "@codemirror/language": "6.12.4",
         "@codemirror/legacy-modes": "^6.5.3",
@@ -40109,15 +40112,16 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^1.4.0",
         "i18next": "^26.3.0",
         "use-sync-external-store": "^1.6.0"
       },
       "devDependencies": {
-        "@getpaseo/client": "0.15.0-beta.1",
-        "@getpaseo/protocol": "0.15.0-beta.1",
+        "@getpaseo/client": "0.15.0",
+        "@getpaseo/protocol": "0.15.0",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.2.3",
@@ -40127,8 +40131,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.15.0-beta.1",
-        "@getpaseo/protocol": "0.15.0-beta.1",
+        "@getpaseo/client": "0.15.0",
+        "@getpaseo/protocol": "0.15.0",
         "react": ">=19.1.0 <20",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -40150,7 +40154,8 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "semver": "^7.8.5",
         "zod": "^4.4.3"
@@ -40177,7 +40182,8 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "@noble/ciphers": "^2.4.0",
         "@noble/curves": "^2.4.0",
@@ -40398,16 +40404,17 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
+      "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
         "@anthropic-ai/claude-agent-sdk": "0.3.246",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.15.0-beta.1",
-        "@getpaseo/highlight": "0.15.0-beta.1",
-        "@getpaseo/plugin": "0.15.0-beta.1",
-        "@getpaseo/protocol": "0.15.0-beta.1",
-        "@getpaseo/relay": "0.15.0-beta.1",
+        "@getpaseo/client": "0.15.0",
+        "@getpaseo/highlight": "0.15.0",
+        "@getpaseo/plugin": "0.15.0",
+        "@getpaseo/protocol": "0.15.0",
+        "@getpaseo/relay": "0.15.0",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
@@ -41354,7 +41361,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -42964,7 +42971,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.15.0-beta.1",
+      "version": "0.15.0",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.0",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [

packages/app/app.config.js

@@ -142,6 +142,7 @@ export default {
       searchPaths: ["../../node_modules", "./node_modules"],
     },
     plugins: [
+      "./modules/paseo-hardware-keyboard/app.plugin",
       "expo-router",
       withPasteInput,
       withAndroidScroll,

packages/app/app.config.test.ts

@@ -94,3 +94,21 @@ it("allows all orientations on iPhone and iPad", async () => {
     await rm(root, { recursive: true, force: true });
   }
 }, 30_000);
+
+// Scene startup is the integration boundary for the iOS keyboard window.
+describe("hardware keyboard scene integration", () => {
+  it("installs observation after Expo creates the scene window and is idempotent", () => {
+    const {
+      configureHardwareKeyboardAppDelegate,
+    } = require("./modules/paseo-hardware-keyboard/app.plugin.js");
+    const source =
+      "import Expo\nclass Scene {\n  super.scene(scene, willConnectTo: session, options: connectionOptions)\n}\n";
+    const configured = configureHardwareKeyboardAppDelegate(source);
+    expect(configured).toContain("import PaseoHardwareKeyboard");
+    expect(configured).toContain("PaseoHardwareKeyboardWindow.observing(window)");
+    expect(configured.indexOf("super.scene")).toBeLessThan(
+      configured.indexOf(".observing(window)"),
+    );
+    expect(configureHardwareKeyboardAppDelegate(configured)).toBe(configured);
+  });
+});

packages/app/e2e/browser/add-project-flow.spec.ts

@@ -15,6 +15,8 @@ import {
   expectNewWorkspaceForAddedProject,
   expectAddProjectResultVisible,
   navigateAddProjectResults,
+  navigateAndDismissAddProject,
+  watchAddProjectRenderWarnings,
   openAddProjectFlow,
   openAddProjectHostSelection,
 } from "../support/helpers/add-project-flow";
@@ -146,6 +148,7 @@ test.describe("Add Project command-center flow", () => {
     test("Escape and Back restore searchable page input before closing at the root", async ({
       page,
     }) => {
+      const renderWarnings = watchAddProjectRenderWarnings(page);
       await gotoAppShell(page);
       await addConnectedHostAndReload(page, {
         serverId: secondaryHost.serverId,
@@ -183,8 +186,9 @@ test.describe("Add Project command-center flow", () => {
 
       await page.keyboard.press("Escape");
       await expectAddProjectPage(page, "host");
-      await page.keyboard.press("Escape");
+      await navigateAndDismissAddProject(page);
       await expect(addProjectFlow(page)).not.toBeVisible();
+      expect(renderWarnings).toEqual([]);
     });
 
     test("New directory creates a Project on the selected remote host", async ({ page }) => {

packages/app/e2e/browser/background-agents.spec.ts

@@ -0,0 +1,65 @@
+import { test } from "../support/fixtures";
+import {
+  expectWorkspaceShownIdle,
+  finishAndArchiveAgent,
+  startBackgroundAgent,
+} from "../support/helpers/background-agents";
+import { openAgentRoute } from "../support/helpers/mock-agent";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import {
+  expectSubagentRowGone,
+  expectSubagentRowVisible,
+  openSubagentsTrack,
+  seedParentWithSubagent,
+  seedSubagent,
+} from "../support/helpers/subagents";
+import { expectOnlyWorkspaceAgentTabsVisible } from "../support/helpers/workspace-tabs";
+
+test.describe("Background agents", () => {
+  let workspace: SeededWorkspace;
+
+  test.beforeAll(async () => {
+    workspace = await seedWorkspace({
+      repoPrefix: "background-agents-",
+      title: "Classifier workspace",
+    });
+  });
+
+  test.afterAll(async () => {
+    await workspace?.cleanup();
+  });
+
+  test("a background agent runs in an open workspace without announcing itself", async ({
+    page,
+  }) => {
+    const agents = await seedParentWithSubagent(workspace, {
+      parentTitle: "Feature agent",
+      childTitle: "Visible helper",
+    });
+    await openAgentRoute(page, { workspaceId: agents.workspaceId, agentId: agents.parent.id });
+    await openSubagentsTrack(page);
+    await expectSubagentRowVisible(page, agents.child.id);
+
+    const classifier = await test.step("a plugin starts a background agent", () =>
+      startBackgroundAgent(workspace, { parentId: agents.parent.id, title: "Classifier" }));
+    // A visible child created after the classifier reaches the app on the same stream, so once
+    // its row shows, the app has processed the classifier too.
+    const marker = await seedSubagent(workspace, {
+      parentId: agents.parent.id,
+      title: "Ordering marker",
+    });
+
+    await test.step("it stays out of the track, the tabs and the sidebar status", async () => {
+      await expectSubagentRowVisible(page, marker.id);
+      await expectSubagentRowGone(page, classifier.id);
+      await expectOnlyWorkspaceAgentTabsVisible(page, [agents.parent.id]);
+      await expectWorkspaceShownIdle(page, "Classifier workspace");
+    });
+
+    await test.step("the plugin reads its finish and archives it", async () => {
+      await finishAndArchiveAgent(workspace, classifier.id);
+      await expectOnlyWorkspaceAgentTabsVisible(page, [agents.parent.id]);
+      await expectSubagentRowGone(page, classifier.id);
+    });
+  });
+});

packages/app/e2e/browser/compact-git-actions-menu.spec.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { mkdtemp, writeFile } from "node:fs/promises";
 import path from "node:path";
+import type { Locator } from "@playwright/test";
 import { test, expect, type Page } from "../support/fixtures";
 import { getServerId } from "../support/helpers/server-id";
 import { connectSeedClient } from "../support/helpers/seed-client";
@@ -59,6 +60,14 @@ async function openCompactActionsMenu(page: Page, workspaceId: string) {
   return menu;
 }
 
+async function expectActionsInOrder(menu: Locator, labels: readonly string[]) {
+  const items = menu.getByRole("menuitem");
+  await expect(items).toHaveCount(labels.length);
+  for (const [index, label] of labels.entries()) {
+    await expect(items.nth(index).getByText(label, { exact: true })).toBeVisible();
+  }
+}
+
 test("compact git actions menu lists a promoted Pull once", async ({ page }) => {
   const repoPath = await createRemoteRepo("compact-menu-pull-");
   cleanupTasks.push(async () => {
@@ -83,12 +92,7 @@ test("compact git actions menu lists a promoted Pull once", async ({ page }) =>
   const menu = await openCompactActionsMenu(page, workspaceId);
 
   await expect(menu.getByTestId("changes-menu-pull")).toHaveCount(1);
-  await expect(menu.getByRole("menuitem")).toHaveText([
-    "Pull",
-    "Push",
-    "Pull and push",
-    "Archive workspace",
-  ]);
+  await expectActionsInOrder(menu, ["Pull", "Push", "Pull and push", "Archive workspace"]);
 });
 
 test("compact git actions menu lists a promoted Push once", async ({ page }) => {
@@ -106,10 +110,5 @@ test("compact git actions menu lists a promoted Push once", async ({ page }) =>
   const menu = await openCompactActionsMenu(page, workspaceId);
 
   await expect(menu.getByTestId("changes-menu-push")).toHaveCount(1);
-  await expect(menu.getByRole("menuitem")).toHaveText([
-    "Push",
-    "Pull",
-    "Pull and push",
-    "Archive workspace",
-  ]);
+  await expectActionsInOrder(menu, ["Push", "Pull", "Pull and push", "Archive workspace"]);
 });

packages/app/e2e/browser/plugin-buttons.spec.ts

@@ -10,6 +10,7 @@ test("plugin header and composer buttons share actions, menus, content, and upda
     await buttons.verifyObservationLifetime();
     await buttons.openWideMenusAndPopovers();
     await buttons.runAndUpdateActions();
+    await buttons.keepTrackSpaceWithoutPills();
     await buttons.openCompactSheets();
     await buttons.useCompactWorkspaceMenu();
     await buttons.hideAndUnloadOpenButtons();

packages/app/e2e/browser/plugin-settings.spec.ts

@@ -16,6 +16,14 @@ import {
   returnAndReopenSettings,
   returnToPluginsPage,
   expectSettingsUnavailable,
+  openPluginsPage,
+  expectActionsMenuWithoutSettings,
+  expectNoSettingsCogWithoutScreens,
+  openTabbedSettings,
+  selectSettingsTab,
+  openTabbedSettingsLink,
+  expectSettingsTooltip,
+  expectNamedPluginRow,
 } from "../support/helpers/plugin-settings";
 
 test("display preferences survive a reload", async ({ page }) => {
@@ -49,6 +57,32 @@ test("Back to plugins returns from a plugin settings screen", async ({ page }) =
   await returnToPluginsPage(page);
 });
 
+test("plugin settings open from the cog and show a tab per screen", async ({ page }) => {
+  await openPluginsPage(page);
+  await test.step("plugin rows show the display name", async () => {
+    await expectNamedPluginRow(page);
+  });
+  await test.step("the cog explains itself", async () => {
+    await expectSettingsTooltip(page);
+  });
+  await test.step("the actions menu keeps only plugin actions", async () => {
+    await expectActionsMenuWithoutSettings(page);
+  });
+  await test.step("tabs switch between the plugin's settings screens", async () => {
+    await openTabbedSettings(page);
+    await selectSettingsTab(page, "Advanced");
+    await selectSettingsTab(page, "General");
+    await returnToPluginsPage(page);
+  });
+  await test.step("a plugin without settings screens shows no cog", async () => {
+    await expectNoSettingsCogWithoutScreens(page);
+  });
+});
+
+test("a settings screen link opens its tab", async ({ page }) => {
+  await openTabbedSettingsLink(page, "Advanced");
+});
+
 test.describe("compact plugin settings", () => {
   test.use({ viewport: { width: 390, height: 844 } });
 

packages/app/e2e/browser/plugin-sidebar-items.spec.ts

@@ -27,6 +27,7 @@ import { seedWorkspace } from "../support/helpers/seed-client";
 import { getServerId } from "../support/helpers/server-id";
 import { installUsageReportsFixture } from "../support/helpers/usage-reports";
 import { claudeAndCodexReports } from "../support/helpers/usage-sidebar-item";
+import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 
 const APP_SETTINGS_KEY = "@paseo:app-settings";
 
@@ -133,6 +134,30 @@ function sidebarFooter(page: Page): Locator {
   return visibleTestId(page, "sidebar-add-project").locator("xpath=..");
 }
 
+function isPluginCatalogResponse(message: string | Buffer): boolean {
+  if (typeof message !== "string") return false;
+  const frame = JSON.parse(message);
+  return frame.type === "session" && frame.message?.type === "plugin.catalog.get.response";
+}
+
+async function holdNextPluginCatalogResponse(page: Page) {
+  const response = Promise.withResolvers<() => void>();
+  let holdCatalog = true;
+  await page.routeWebSocket(daemonWsRoutePattern(), (socket) => {
+    const server = socket.connectToServer();
+    socket.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      if (holdCatalog && isPluginCatalogResponse(message)) {
+        holdCatalog = false;
+        response.resolve(() => socket.send(message));
+        return;
+      }
+      socket.send(message);
+    });
+  });
+  return { response: response.promise };
+}
+
 test.describe("Plugin sidebar items", () => {
   let workspaceId: string;
   let cleanup: () => Promise<void>;
@@ -151,6 +176,38 @@ test.describe("Plugin sidebar items", () => {
     await cleanup();
   });
 
+  test("a restored plugin screen waits for its catalog before rendering", async ({ page }) => {
+    await page.setViewportSize(WIDE);
+    await gotoWorkspace(page, workspaceId);
+    const row = headerRow(page, SHOWCASE_PLUGIN_ID, "deploys");
+    await expect(row).toBeVisible({ timeout: 30_000 });
+    await row.click();
+    const body = page.getByText("Deploys screen body", { exact: true });
+    await expect(body).toBeVisible();
+    const screenUrl = page.url();
+    const catalog = await holdNextPluginCatalogResponse(page);
+
+    await page.reload();
+    const releaseCatalog = await catalog.response;
+    try {
+      await expect(
+        page.getByRole("progressbar", { name: "Loading plugin", exact: true }),
+      ).toBeVisible();
+      await expect(
+        page.getByText("This plugin surface is unavailable.", { exact: true }),
+      ).toHaveCount(0);
+      await expect(body).toHaveCount(0);
+    } finally {
+      releaseCatalog();
+    }
+
+    await expect(body).toBeVisible();
+    await expect(
+      page.getByRole("progressbar", { name: "Loading plugin", exact: true }),
+    ).toHaveCount(0);
+    await expect(page).toHaveURL(screenUrl);
+  });
+
   test("a plugin's screen, header row, footer popover and command work together", async ({
     page,
   }) => {

packages/app/e2e/support/helpers/add-project-flow.ts

@@ -117,3 +117,25 @@ export async function expectAddProjectResultVisible(page: Page, text: string): P
 export async function chooseAddHostFromProjectFlow(page: Page): Promise<void> {
   await page.getByRole("button", { name: /Add host.*No connected hosts/ }).click();
 }
+
+export async function navigateAndDismissAddProject(page: Page): Promise<void> {
+  // Keep both keys in one task so Escape closes with a selection update still queued.
+  await page.evaluate(() => {
+    for (const key of ["ArrowDown", "Escape"]) {
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", { key, code: key, bubbles: true, cancelable: true }),
+      );
+    }
+  });
+}
+
+export function watchAddProjectRenderWarnings(page: Page): string[] {
+  const warnings: string[] = [];
+  page.on("console", (message) => {
+    const text = message.text();
+    if (text.includes("Cannot update a component") && text.includes("AddProjectFlow")) {
+      warnings.push(text);
+    }
+  });
+  return warnings;
+}

packages/app/e2e/support/helpers/background-agents.ts

@@ -0,0 +1,48 @@
+import { expect, type Page } from "@playwright/test";
+import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import type { SeededWorkspace } from "./seed-client";
+
+/**
+ * Starts a background agent the way a plugin helper does: in the workspace, under a parent,
+ * streaming for about ten seconds. Resolves once the daemon reports it running.
+ */
+export async function startBackgroundAgent(
+  workspace: Pick<SeededWorkspace, "client" | "repoPath" | "workspaceId">,
+  input: { parentId: string; title: string },
+): Promise<{ id: string }> {
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: input.title,
+    modeId: "load-test",
+    model: "ten-second-stream",
+    initialPrompt: "classify the last turn",
+    labels: { [PARENT_AGENT_ID_LABEL]: input.parentId },
+    background: true,
+  });
+  await workspace.client.waitForAgentUpsert(agent.id, (snapshot) => snapshot.status === "running");
+  return { id: agent.id };
+}
+
+/** Waits for the agent's turn to end and archives it, as the plugin does with a helper's reply. */
+export async function finishAndArchiveAgent(
+  workspace: Pick<SeededWorkspace, "client">,
+  agentId: string,
+): Promise<void> {
+  const finished = await workspace.client.waitForFinish(agentId, 60_000);
+  expect(finished.status).toBe("idle");
+  await workspace.client.archiveAgent(agentId);
+}
+
+export async function expectWorkspaceShownIdle(page: Page, workspaceName: string): Promise<void> {
+  const row = page.getByRole("button", {
+    name: new RegExp(`^${escapeRegExp(workspaceName)}(?:,|$)`),
+  });
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await expect(row.getByTestId("workspace-status-indicator-running")).toHaveCount(0);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

packages/app/e2e/support/helpers/plugin-buttons.ts

@@ -4,6 +4,9 @@ import path from "node:path";
 import type { Locator, TestInfo } from "@playwright/test";
 import { test, expect, type Page } from "@playwright/test";
 import { gotoAppShell } from "./app";
+import { scrollAgentChatToBottom, waitForScrollableChat } from "./agent-bottom-anchor";
+import { expectTurnCopyButton } from "./agent-stream";
+import { submitMessage } from "./composer";
 import { buildAgentRoute } from "./mock-agent";
 import { openCommandCenter } from "./command-center";
 import {
@@ -88,7 +91,7 @@ export default function contribute(client) {
   header("locked", { title: "Production locked", icon: "Lock", disabled: true, behavior: { kind: "action", onPress() {} } });
   const review = pill("review", { title: "Run review", icon: "Scan", label: "Review", behavior: { kind: "action", async onPress() { await new Promise((resolve) => { finishReview = resolve; }); review.update({ label: "Reviewed" }); } } });
   const pillMenu = pill("checks", { title: "Composer checks", icon: "ListChecks", label: "Checks", behavior: menu });
-  pill("usage", { title: "Composer status", icon: StatusIcon, label: "Status", behavior: { kind: "popover", Content: Details } });
+  const usage = pill("usage", { title: "Composer status", icon: StatusIcon, label: "Status", behavior: { kind: "popover", Content: Details } });
   const command = (id, title, onSelect) => client.addCommandCenterItem({ id, title, icon: "Settings", context: "workspace", onSelect });
   command("finish", "Finish deployment", () => finish());
   command("finish-review", "Finish review", () => finishReview());
@@ -102,10 +105,16 @@ export default function contribute(client) {
   command("hide-menu", "Hide composer menu", () => pillMenu.update({ visible: false }));
   command("show-menu", "Show composer menu", () => pillMenu.update({ visible: true }));
   const lifetime = new AbortController();
+  let pillsHidden = false;
   const applyWorkspace = (workspace) => {
     if (workspace.id !== workspaceId) return;
+    const hidePills = workspace.name === "No composer pills";
     deploy.update({ visible: workspace.name !== "Compact checks" });
-    pillMenu.update({ visible: workspace.name !== "Hide composer menu" });
+    pillMenu.update({ visible: workspace.name !== "Hide composer menu" && !hidePills });
+    if (hidePills === pillsHidden) return;
+    pillsHidden = hidePills;
+    review.update({ visible: !hidePills });
+    usage.update({ visible: !hidePills });
   };
   void client.paseo.workspaces.list({ subscribe: {}, signal: lifetime.signal }).then(({ subscription }) => {
     subscription.subscribe({
@@ -244,6 +253,38 @@ async function captureSchemes(page: Page, info: TestInfo, name: string, subject:
   await page.emulateMedia({ colorScheme: "light" });
 }
 
+const COMPOSER_PILLS = ["Run review", "Composer checks", "Composer status"] as const;
+
+function chevronOf(page: Page, title: string): Locator {
+  return page
+    .getByRole("button", { name: title, exact: true })
+    .getByTestId("plugin-button-chevron");
+}
+
+/** Composer pills that open a menu or popover carry a chevron; a one-tap action does not. */
+async function expectComposerPillChevrons(page: Page) {
+  await expect(chevronOf(page, "Composer checks")).toHaveCount(1);
+  await expect(chevronOf(page, "Composer status")).toHaveCount(1);
+  await expect(chevronOf(page, "Run review")).toHaveCount(0);
+}
+
+async function setComposerPillsShown(
+  page: Page,
+  showcase: { setTitle(title: string): Promise<unknown> },
+  shown: boolean,
+) {
+  await showcase.setTitle(shown ? "Button showcase" : "No composer pills");
+  for (const title of COMPOSER_PILLS) {
+    await expect(page.getByRole("button", { name: title, exact: true })).toHaveCount(shown ? 1 : 0);
+  }
+}
+
+async function lastTurnTop(page: Page): Promise<number> {
+  const box = await page.getByRole("button", { name: "Copy turn" }).last().boundingBox();
+  expect(box).not.toBeNull();
+  return box!.y;
+}
+
 async function expectHeaderTextTruncated(page: Page) {
   const title = page.getByTestId("workspace-header-title");
   const subtitle = page.getByTestId("workspace-header-subtitle");
@@ -276,6 +317,7 @@ export async function withButtonShowcase(
   run: (buttons: {
     openWideMenusAndPopovers(): Promise<void>;
     runAndUpdateActions(): Promise<void>;
+    keepTrackSpaceWithoutPills(): Promise<void>;
     openCompactSheets(): Promise<void>;
     useCompactWorkspaceMenu(): Promise<void>;
     hideAndUnloadOpenButtons(): Promise<void>;
@@ -348,11 +390,7 @@ export async function withButtonShowcase(
               .getByRole("button", { name: "Header checks", exact: true })
               .getByTestId("plugin-button-chevron"),
           ).toHaveCount(1);
-          await expect(
-            page
-              .getByRole("button", { name: "Composer checks", exact: true })
-              .getByTestId("plugin-button-chevron"),
-          ).toHaveCount(0);
+          await expectComposerPillChevrons(page);
           await expectSurfaceVisible(page);
           await captureSchemes(
             page,
@@ -476,10 +514,31 @@ export async function withButtonShowcase(
             "Review ready",
           );
         }),
+      keepTrackSpaceWithoutPills: () =>
+        test.step("the composer track keeps its space when every pill leaves and returns", async () => {
+          await page.setViewportSize(WIDE);
+          await submitMessage(page, "Stream a turn under the composer pills");
+          await expectTurnCopyButton(page);
+          await waitForScrollableChat(page, { minScrollableDistance: 200, timeout: 30_000 });
+          for (const viewport of [WIDE, COMPACT]) {
+            await page.setViewportSize(viewport);
+            await scrollAgentChatToBottom(page);
+            const top = await lastTurnTop(page);
+            await setComposerPillsShown(page, showcase, false);
+            expect(await lastTurnTop(page)).toBe(top);
+            await setComposerPillsShown(page, showcase, true);
+            expect(await lastTurnTop(page)).toBe(top);
+          }
+          await page.setViewportSize(WIDE);
+        }),
       openCompactSheets: () =>
         test.step("compact header leaves plugin actions to the workspace menu while composer triggers open sheets", async () => {
           await page.setViewportSize(COMPACT);
-          await expect(page.getByTestId("plugin-button-chevron")).toHaveCount(0);
+          await expect(
+            page.getByRole("toolbar", { name: "Workspace actions", exact: true }),
+          ).toHaveCount(0);
+          await expectComposerPillChevrons(page);
+          await expect(page.getByTestId("plugin-button-chevron")).toHaveCount(2);
           await expect(
             page.getByRole("button", { name: "Composer checks", exact: true }),
           ).toContainText("Checks");

packages/app/e2e/support/helpers/plugin-settings.ts

@@ -1,4 +1,7 @@
-import { copyPluginExample } from "./plugin-fixture";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
 import { expect, test as base, type Page } from "../fixtures";
 import { gotoAppShell, openSettings } from "./app";
 import { goBackInSettings, openCompactSettings, openHostSection } from "./settings";
@@ -9,6 +12,54 @@ import { connectNewWorkspaceDaemonClient } from "./new-workspace";
 
 type SettingsClient = Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
 
+const TABBED_PLUGIN_ID = "settings-tabs";
+const TABBED_PLUGIN_NAME = "Tabbed settings";
+/** Two settings screens, so the settings page shows a tab per screen. */
+const TABBED_SOURCE = `import React from "react";
+import { Text, View } from "react-native";
+import { defineTranslations, useTranslation } from "@getpaseo/plugin/client";
+
+const messages = defineTranslations({ resources: { en: { icon: "advanced-tab-icon" } } });
+
+function General({ theme }) {
+  return <Text style={{ color: theme.colors.foreground }}>General settings body</Text>;
+}
+
+function Advanced({ theme }) {
+  return <Text style={{ color: theme.colors.foreground }}>Advanced settings body</Text>;
+}
+
+// Component icons run with the plugin's runtime; one that throws costs its tab only the icon.
+function TranslatedIcon({ color, size }) {
+  const { t } = useTranslation(messages);
+  return <View testID={t("icon")} aria-hidden style={{ width: size, height: size, borderRadius: size / 2, backgroundColor: color }} />;
+}
+
+function BrokenIcon() {
+  throw new Error("Settings tab icon exploded");
+}
+
+export default function contribute(client) {
+  client.addSettingsScreen({ id: "general", title: "General", icon: BrokenIcon, Component: General });
+  client.addSettingsScreen({ id: "advanced", title: "Advanced", icon: TranslatedIcon, Component: Advanced });
+  return () => {};
+}
+`;
+
+async function writeTabbedPlugin() {
+  const directory = await mkdtemp(path.join(tmpdir(), `paseo-${TABBED_PLUGIN_ID}-`));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({
+      id: TABBED_PLUGIN_ID,
+      name: TABBED_PLUGIN_NAME,
+      requirements: pluginRequirements,
+    }),
+  );
+  await writeFile(path.join(directory, "index.client.tsx"), TABBED_SOURCE);
+  return { directory, cleanup: () => rm(directory, { recursive: true, force: true }) };
+}
+
 export const test = base.extend<{ settingsPlugin: SettingsClient }>({
   settingsPlugin: [
     async ({ e2eWorker, page }, provide, testInfo) => {
@@ -16,16 +67,20 @@ export const test = base.extend<{ settingsPlugin: SettingsClient }>({
       const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
       const previous = await client.getDaemonConfig();
       const example = await copyPluginExample("settings");
+      const tabbed = await writeTabbedPlugin();
       try {
         await client.patchDaemonConfig({ pluginsEnabled: true });
         await client.installDirectoryPlugin(example.directory);
+        await client.installDirectoryPlugin(tabbed.directory);
         await provide(client);
         await page.screenshot({ path: testInfo.outputPath("settings.png") });
       } finally {
         await client.removePlugin("settings-example");
+        await client.removePlugin(TABBED_PLUGIN_ID);
         await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
         await client.close();
         await example.cleanup();
+        await tabbed.cleanup();
       }
     },
     { auto: true },
@@ -44,9 +99,88 @@ export async function openCompactDisplaySettings(page: Page) {
 }
 async function openPluginScreen(page: Page) {
   await openHostSection(page, getServerId(), "plugins");
-  await page.getByRole("button", { name: "Actions for settings-example", exact: true }).click();
-  await page.getByRole("menuitem", { name: "Display", exact: true }).click();
+  await openSettingsFromCog(page);
+}
+/** The cog on a plugin's row. Its label is "Settings"; the row tells plugins apart. */
+function settingsButton(page: Page, pluginId: string) {
+  return page
+    .getByTestId(`plugin-row-${pluginId}`)
+    .filter({ visible: true })
+    .getByRole("button", { name: "Settings", exact: true });
+}
+async function openSettingsFromCog(page: Page) {
+  await settingsButton(page, "settings-example").click();
   await expect(page.getByRole("switch", { name: "Show metadata" })).toBeVisible();
+  // A plugin with one settings screen shows no tabs, and the header names only the plugin.
+  await expect(page.getByTestId("plugin-settings-tabs")).toHaveCount(0);
+  await expectSettingsHeader(page, "settings-example");
+}
+export async function openPluginsPage(page: Page) {
+  await gotoAppShell(page);
+  await openSettings(page);
+  await openHostSection(page, getServerId(), "plugins");
+}
+export async function expectActionsMenuWithoutSettings(page: Page) {
+  await page.getByRole("button", { name: "Actions for settings-example", exact: true }).click();
+  await expect(page.getByRole("menuitem", { name: "Reload", exact: true })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Display", exact: true })).toHaveCount(0);
+  await page.keyboard.press("Escape");
+}
+export async function expectNoSettingsCogWithoutScreens(page: Page) {
+  await page.getByRole("switch", { name: "settings-example: Disable" }).click();
+  await expect(page.getByRole("switch", { name: "settings-example: Enable" })).toBeVisible();
+  await expect(settingsButton(page, "settings-example")).toHaveCount(0);
+  await page.getByRole("switch", { name: "settings-example: Enable" }).click();
+  await expect(settingsButton(page, "settings-example")).toBeVisible();
+}
+export async function expectSettingsTooltip(page: Page) {
+  await settingsButton(page, "settings-example").hover();
+  await expect(page.getByRole("tooltip")).toHaveText("Settings");
+  await page.mouse.move(0, 0);
+}
+/** A manifest `name` titles the row and its controls; the id stays visible beneath it. */
+export async function expectNamedPluginRow(page: Page) {
+  const row = page.getByTestId(`plugin-row-${TABBED_PLUGIN_ID}`).filter({ visible: true });
+  await expect(row.getByText(TABBED_PLUGIN_NAME, { exact: true })).toBeVisible();
+  await expect(row.getByText(TABBED_PLUGIN_ID, { exact: true })).toBeVisible();
+  await expect(
+    page.getByRole("switch", { name: `${TABBED_PLUGIN_NAME}: Disable`, exact: true }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: `Actions for ${TABBED_PLUGIN_NAME}`, exact: true }),
+  ).toBeVisible();
+}
+export async function openTabbedSettings(page: Page) {
+  await settingsButton(page, TABBED_PLUGIN_ID).click();
+  await expectSettingsTab(page, "General");
+  // The Advanced icon reads the plugin's translations; the General icon throws and is dropped.
+  await expect(page.getByTestId("advanced-tab-icon")).toBeVisible();
+}
+function settingsTab(page: Page, title: string) {
+  return page.getByTestId("plugin-settings-tabs").getByRole("button", { name: title, exact: true });
+}
+export async function selectSettingsTab(page: Page, title: "General" | "Advanced") {
+  await settingsTab(page, title).click();
+  await expectSettingsTab(page, title);
+}
+export async function expectSettingsTab(page: Page, title: "General" | "Advanced") {
+  const other = title === "General" ? "Advanced" : "General";
+  await expect(settingsTab(page, title)).toHaveAttribute("aria-selected", "true");
+  await expect(page.getByText(`${title} settings body`, { exact: true })).toBeVisible();
+  await expect(page.getByText(`${other} settings body`, { exact: true })).toHaveCount(0);
+  // The header names the plugin by its manifest name; the tab names the screen.
+  await expectSettingsHeader(page, TABBED_PLUGIN_NAME);
+  await expectAppRoute(
+    page,
+    `${buildSettingsHostSectionRoute(getServerId(), "plugins")}/${TABBED_PLUGIN_ID}/${title.toLowerCase()}`,
+  );
+}
+export async function openTabbedSettingsLink(page: Page, title: "General" | "Advanced") {
+  await gotoAppShell(page);
+  await page.goto(
+    `${buildSettingsHostSectionRoute(getServerId(), "plugins")}/${TABBED_PLUGIN_ID}/${title.toLowerCase()}`,
+  );
+  await expectSettingsTab(page, title);
 }
 export async function groupByWorkspace(page: Page) {
   await page.getByRole("button", { name: /^Group agents by:/ }).click();
@@ -101,11 +235,7 @@ export async function discardTitle(page: Page) {
 }
 export async function returnAndReopenSettings(page: Page) {
   await goBackInSettings(page);
-  const actions = page.getByRole("button", { name: "Actions for settings-example", exact: true });
-  await expect(actions).toBeVisible();
-  await actions.click();
-  await page.getByRole("menuitem", { name: "Display", exact: true }).click();
-  await expect(page.getByRole("switch", { name: "Show metadata" })).toBeVisible();
+  await openSettingsFromCog(page);
 }
 export async function returnToPluginsPage(page: Page) {
   await page.getByRole("button", { name: "Back to plugins", exact: true }).click();
@@ -114,6 +244,10 @@ export async function returnToPluginsPage(page: Page) {
     page.getByRole("button", { name: "Actions for settings-example", exact: true }),
   ).toBeVisible();
 }
+async function expectSettingsHeader(page: Page, title: string) {
+  // Settings keeps the Plugins page mounted beneath, so read the visible title only.
+  await expect(page.getByText(title, { exact: true }).filter({ visible: true })).toHaveCount(1);
+}
 export async function expectSettingsUnavailable(page: Page) {
   await expect(
     page.getByText("This plugin settings screen is unavailable.", { exact: true }),

packages/app/e2e/support/helpers/seed-client.ts

@@ -118,6 +118,7 @@ export interface SeedDaemonClient {
     featureValues?: Record<string, unknown>;
     initialPrompt?: string;
     labels?: Record<string, string>;
+    background?: boolean;
   }): Promise<{ id: string; status: string }>;
   fetchAgents(options?: { scope?: "active" }): Promise<{
     entries: Array<{

packages/app/modules/paseo-hardware-keyboard/android/build.gradle

@@ -0,0 +1,16 @@
+apply plugin: 'com.android.library'
+apply plugin: 'expo-module-gradle-plugin'
+
+group = 'sh.paseo.keyboard'
+version = '0.1.0'
+android {
+  namespace 'sh.paseo.keyboard'
+  defaultConfig {
+    versionCode 1
+    versionName '0.1.0'
+  }
+}
+dependencies {
+  implementation 'com.facebook.react:react-android'
+  testImplementation 'junit:junit:4.13.2'
+}

packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/HardwareCharacterKey.kt

@@ -0,0 +1,7 @@
+package sh.paseo.keyboard
+
+import android.view.KeyCharacterMap
+
+internal fun hardwareCharacterKey(character: Int): String =
+  if (character and KeyCharacterMap.COMBINING_ACCENT != 0) "Dead"
+  else String(Character.toChars(character))

packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardModule.kt

@@ -0,0 +1,164 @@
+package sh.paseo.keyboard
+
+import android.content.ComponentCallbacks
+import android.content.res.Configuration
+import android.hardware.input.InputManager
+import android.os.Handler
+import android.os.Looper
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.Window
+import android.widget.EditText
+import android.view.inputmethod.BaseInputConnection
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.interfaces.ExtraWindowEventListener
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+internal object HardwareKeyboard {
+  var module: PaseoHardwareKeyboardModule? = null
+  @Volatile var overlayKeys: Set<String> = emptySet()
+  private val windows = mutableMapOf<Window, KeyboardWindowCallback>()
+  val dispatcher = WindowKeyDispatcher<KeyEvent>()
+  private val consumedPresses = mutableSetOf<Int>()
+
+  fun observe(window: Window) {
+    if (windows.containsKey(window)) return
+    val callback = KeyboardWindowCallback(window, window.callback)
+    windows[window] = callback
+    window.callback = callback
+  }
+  fun release(window: Window) {
+    val callback = windows.remove(window) ?: return
+    if (window.callback === callback) window.callback = callback.previous
+  }
+  fun releaseAll() {
+    windows.keys.toList().forEach { release(it) }
+    consumedPresses.clear()
+  }
+
+  fun dispatch(event: KeyEvent, composing: Boolean): Boolean {
+    if (event.flags and KeyEvent.FLAG_SOFT_KEYBOARD != 0) return false
+    if (event.action != KeyEvent.ACTION_DOWN && event.action != KeyEvent.ACTION_UP) return false
+    val code = code(event.keyCode)
+    if (code.isEmpty()) return false
+    val textModifiers = event.metaState and KeyEvent.META_CTRL_MASK.inv() and KeyEvent.META_META_MASK.inv()
+    val character = event.getUnicodeChar(textModifiers)
+    val named = !code.startsWith("Key") && !code.startsWith("Digit")
+    val key = when {
+      code.startsWith("Control") -> "Control"
+      code.startsWith("Meta") -> "Meta"
+      code.startsWith("Shift") -> "Shift"
+      code.startsWith("Alt") -> "Alt"
+      named && (character == 0 || code == "Enter" || code == "Tab" || code == "Backspace") -> code
+      character != 0 -> hardwareCharacterKey(character)
+      else -> code
+    }
+    module?.emit(mapOf(
+      "key" to key, "code" to code,
+      "altKey" to event.isAltPressed, "ctrlKey" to event.isCtrlPressed,
+      "metaKey" to event.isMetaPressed, "shiftKey" to event.isShiftPressed,
+      "repeat" to (event.repeatCount > 0), "isComposing" to composing,
+      "phase" to if (event.action == KeyEvent.ACTION_UP) "up" else "down"
+    ))
+    if (event.action == KeyEvent.ACTION_UP) return consumedPresses.remove(event.keyCode)
+    val overlayOwnsKey = key != "Dead" && key in overlayKeys && !event.isCtrlPressed && !event.isMetaPressed && !event.isAltPressed && !composing
+    if (overlayOwnsKey) consumedPresses.add(event.keyCode)
+    return overlayOwnsKey
+  }
+
+  private fun code(keyCode: Int): String = when (keyCode) {
+    in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z -> "Key" + ('A'.code + keyCode - KeyEvent.KEYCODE_A).toChar()
+    in KeyEvent.KEYCODE_0..KeyEvent.KEYCODE_9 -> "Digit" + (keyCode - KeyEvent.KEYCODE_0)
+    in KeyEvent.KEYCODE_F1..KeyEvent.KEYCODE_F12 -> "F" + (keyCode - KeyEvent.KEYCODE_F1 + 1)
+    KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> "Enter"
+    KeyEvent.KEYCODE_ESCAPE -> "Escape"
+    KeyEvent.KEYCODE_DEL -> "Backspace"
+    KeyEvent.KEYCODE_FORWARD_DEL -> "Delete"
+    KeyEvent.KEYCODE_TAB -> "Tab"
+    KeyEvent.KEYCODE_SPACE -> "Space"
+    KeyEvent.KEYCODE_DPAD_UP -> "ArrowUp"
+    KeyEvent.KEYCODE_DPAD_DOWN -> "ArrowDown"
+    KeyEvent.KEYCODE_DPAD_LEFT -> "ArrowLeft"
+    KeyEvent.KEYCODE_DPAD_RIGHT -> "ArrowRight"
+    KeyEvent.KEYCODE_CTRL_LEFT -> "ControlLeft"
+    KeyEvent.KEYCODE_CTRL_RIGHT -> "ControlRight"
+    KeyEvent.KEYCODE_META_LEFT -> "MetaLeft"
+    KeyEvent.KEYCODE_META_RIGHT -> "MetaRight"
+    KeyEvent.KEYCODE_SHIFT_LEFT -> "ShiftLeft"
+    KeyEvent.KEYCODE_SHIFT_RIGHT -> "ShiftRight"
+    KeyEvent.KEYCODE_ALT_LEFT -> "AltLeft"
+    KeyEvent.KEYCODE_ALT_RIGHT -> "AltRight"
+    KeyEvent.KEYCODE_COMMA -> "Comma"
+    KeyEvent.KEYCODE_PERIOD -> "Period"
+    KeyEvent.KEYCODE_MINUS -> "Minus"
+    KeyEvent.KEYCODE_EQUALS -> "Equal"
+    KeyEvent.KEYCODE_LEFT_BRACKET -> "BracketLeft"
+    KeyEvent.KEYCODE_RIGHT_BRACKET -> "BracketRight"
+    KeyEvent.KEYCODE_BACKSLASH -> "Backslash"
+    KeyEvent.KEYCODE_SEMICOLON -> "Semicolon"
+    KeyEvent.KEYCODE_APOSTROPHE -> "Quote"
+    KeyEvent.KEYCODE_GRAVE -> "Backquote"
+    KeyEvent.KEYCODE_SLASH -> "Slash"
+    else -> ""
+  }
+}
+
+private class KeyboardWindowCallback(private val window: Window, val previous: Window.Callback) : Window.Callback by previous {
+  override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+    val editable = (window.currentFocus as? EditText)?.text
+    val composing = editable != null && BaseInputConnection.getComposingSpanStart(editable) >= 0
+    return HardwareKeyboard.dispatcher.dispatch(event, { HardwareKeyboard.dispatch(event, composing) }, { previous.dispatchKeyEvent(event) })
+  }
+}
+
+class PaseoHardwareKeyboardModule : Module(), ExtraWindowEventListener, InputManager.InputDeviceListener, ComponentCallbacks {
+  private var inputManager: InputManager? = null
+  private var registeredReactContext: ReactContext? = null
+  private fun keyboardPresent(): Boolean {
+    val config = registeredReactContext?.resources?.configuration
+    return (config?.keyboard == Configuration.KEYBOARD_QWERTY && config.hardKeyboardHidden != Configuration.HARDKEYBOARDHIDDEN_YES) ||
+      InputDevice.getDeviceIds().any { id -> InputDevice.getDevice(id)?.let { !it.isVirtual && it.keyboardType == InputDevice.KEYBOARD_TYPE_ALPHABETIC } == true }
+  }
+  private fun presenceChanged() { sendEvent("onHardwareKeyboardPresenceChanged", emptyMap<String, Any>()) }
+  override fun onInputDeviceAdded(id: Int) { presenceChanged() }
+  override fun onInputDeviceRemoved(id: Int) { presenceChanged() }
+  override fun onInputDeviceChanged(id: Int) { presenceChanged() }
+  override fun onConfigurationChanged(config: Configuration) { presenceChanged() }
+  override fun onLowMemory() {}
+  override fun onExtraWindowCreate(window: Window) { HardwareKeyboard.observe(window) }
+  override fun onExtraWindowDestroy(window: Window) { HardwareKeyboard.release(window) }
+  override fun definition() = ModuleDefinition {
+    Name("PaseoHardwareKeyboard")
+    Events("onHardwareKeyboardShortcut", "onHardwareKeyboardPresenceChanged")
+    OnCreate {
+      HardwareKeyboard.module = this@PaseoHardwareKeyboardModule
+      val context = appContext.reactContext
+      require(context is ReactContext) { "Hardware keyboard observation requires a React context" }
+      registeredReactContext = context
+      context.registerComponentCallbacks(this@PaseoHardwareKeyboardModule)
+      inputManager = context.getSystemService(InputManager::class.java)
+      inputManager?.registerInputDeviceListener(this@PaseoHardwareKeyboardModule, Handler(Looper.getMainLooper()))
+      context.addExtraWindowEventListener(this@PaseoHardwareKeyboardModule)
+      UiThreadUtil.runOnUiThread { appContext.currentActivity?.window?.let { HardwareKeyboard.observe(it) } }
+    }
+    OnDestroy {
+      inputManager?.unregisterInputDeviceListener(this@PaseoHardwareKeyboardModule)
+      inputManager = null
+      registeredReactContext?.unregisterComponentCallbacks(this@PaseoHardwareKeyboardModule)
+      registeredReactContext?.removeExtraWindowEventListener(this@PaseoHardwareKeyboardModule)
+      registeredReactContext = null
+      if (HardwareKeyboard.module === this@PaseoHardwareKeyboardModule) {
+        HardwareKeyboard.module = null
+        HardwareKeyboard.overlayKeys = emptySet()
+        UiThreadUtil.runOnUiThread { if (HardwareKeyboard.module == null) HardwareKeyboard.releaseAll() }
+      }
+    }
+    Function("getHardwareKeyboardPresent") { keyboardPresent() }
+    Function("setOverlayKeys") { keys: List<String> ->
+      HardwareKeyboard.overlayKeys = keys.filter { it in setOf("Escape", "Enter", "ArrowUp", "ArrowDown") }.toSet()
+    }
+  }
+  internal fun emit(event: Map<String, Any>) { sendEvent("onHardwareKeyboardShortcut", event) }
+}

packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardPackage.kt

@@ -0,0 +1,17 @@
+package sh.paseo.keyboard
+
+import android.app.Activity
+import android.content.Context
+import android.os.Bundle
+import expo.modules.core.interfaces.Package
+import expo.modules.core.interfaces.ReactActivityLifecycleListener
+
+class PaseoHardwareKeyboardPackage : Package {
+  override fun createReactActivityLifecycleListeners(activityContext: Context): List<ReactActivityLifecycleListener> = listOf(
+    object : ReactActivityLifecycleListener {
+      override fun onCreate(activity: Activity, savedInstanceState: Bundle?) { HardwareKeyboard.observe(activity.window) }
+      override fun onResume(activity: Activity) { HardwareKeyboard.observe(activity.window) }
+      override fun onDestroy(activity: Activity) { HardwareKeyboard.release(activity.window) }
+    }
+  )
+}

packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/WindowKeyDispatcher.kt

@@ -0,0 +1,11 @@
+package sh.paseo.keyboard
+
+// A modal can forward the same physical event into the activity window. Keep
+// observation outside that nested delivery, without retaining recycled KeyEvents.
+internal class WindowKeyDispatcher<Event : Any> {
+  private val delivering = java.util.Collections.newSetFromMap(java.util.IdentityHashMap<Event, Boolean>())
+  fun dispatch(event: Event, observe: () -> Boolean, deliver: () -> Boolean): Boolean {
+    if (!delivering.add(event)) return deliver()
+    return try { observe() || deliver() } finally { delivering.remove(event) }
+  }
+}

packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/HardwareCharacterKeyTest.kt

@@ -0,0 +1,11 @@
+package sh.paseo.keyboard
+import org.junit.Assert.assertEquals
+import org.junit.Test
+class HardwareCharacterKeyTest {
+  @Test fun deadAccentUsesDomKeyWithoutThrowing() {
+    assertEquals("Dead", hardwareCharacterKey(Int.MIN_VALUE or 0xB4))
+  }
+  @Test fun ordinaryUnicodeRemainsText() {
+    assertEquals("é", hardwareCharacterKey(0xE9))
+  }
+}

packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/WindowKeyDispatcherTest.kt

@@ -0,0 +1,27 @@
+package sh.paseo.keyboard
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class WindowKeyDispatcherTest {
+  @Test fun observesOnePressAcrossNestedWindows() {
+    val dispatcher = WindowKeyDispatcher<Any>()
+    val event = Any()
+    var observations = 0
+    var deliveries = 0
+    dispatcher.dispatch(event, { observations++; false }, {
+      dispatcher.dispatch(event, { observations++; false }, { deliveries++; false })
+    })
+    assertEquals(1, observations)
+    assertEquals(1, deliveries)
+    dispatcher.dispatch(event, { observations++; false }, { false })
+    assertEquals(2, observations)
+  }
+  @Test fun consumedOverlayKeyDoesNotReachTheView() {
+    val dispatcher = WindowKeyDispatcher<Any>()
+    var deliveries = 0
+    assertTrue(dispatcher.dispatch(Any(), { true }, { deliveries++; false }))
+    assertEquals(0, deliveries)
+  }
+}

packages/app/modules/paseo-hardware-keyboard/app.plugin.js

@@ -0,0 +1,29 @@
+const { withAppDelegate } = require("expo/config-plugins");
+const SCENE_START = "super.scene(scene, willConnectTo: session, options: connectionOptions)";
+
+function configureHardwareKeyboardAppDelegate(source) {
+  source = source.replace(
+    /^import PaseoHardwareKeyboard$/m,
+    "internal import PaseoHardwareKeyboard",
+  );
+  if (source.includes("PaseoHardwareKeyboardWindow.observing(window)")) return source;
+  if (!source.includes(SCENE_START)) {
+    throw new Error("Hardware keyboard observation requires the app's Expo scene delegate");
+  }
+  const installation = `${SCENE_START}
+    if let window {
+      let observedWindow = PaseoHardwareKeyboardWindow.observing(window)
+      self.window = observedWindow
+      (UIApplication.shared.delegate as? ExpoReactNativeFactoryProvider)?.window = observedWindow
+    }`;
+  return "internal import PaseoHardwareKeyboard\n" + source.replace(SCENE_START, installation);
+}
+module.exports = function withHardwareKeyboardWindow(config) {
+  return withAppDelegate(config, (modConfig) => {
+    modConfig.modResults.contents = configureHardwareKeyboardAppDelegate(
+      modConfig.modResults.contents,
+    );
+    return modConfig;
+  });
+};
+module.exports.configureHardwareKeyboardAppDelegate = configureHardwareKeyboardAppDelegate;

packages/app/modules/paseo-hardware-keyboard/expo-module.config.json

@@ -1,7 +1,9 @@
 {
-  "platforms": ["ios"],
+  "platforms": ["ios", "android"],
   "ios": {
-    "modules": ["PaseoHardwareKeyboardModule"],
-    "reactDelegateHandlers": ["PaseoHardwareKeyboardReactDelegateHandler"]
+    "modules": ["PaseoHardwareKeyboardModule"]
+  },
+  "android": {
+    "modules": ["sh.paseo.keyboard.PaseoHardwareKeyboardModule"]
   }
 }

packages/app/modules/paseo-hardware-keyboard/ios/PaseoHardwareKeyboardModule.swift

@@ -1,53 +1,159 @@
 import ExpoModulesCore
 import UIKit
+import GameController
 
 private let hardwareSubmitEventName = "onHardwareKeyboardSubmit"
+private let hardwareShortcutEventName = "onHardwareKeyboardShortcut"
 
 private weak var activeModule: PaseoHardwareKeyboardModule?
 private var isHardwareSubmitEnabled = false
+private var overlayKeys: Set<String> = []
 
-@objc
-public class PaseoHardwareKeyboardReactDelegateHandler: ExpoReactDelegateHandler {
-  public override func createRootViewController() -> UIViewController? {
-    return PaseoHardwareKeyboardRootViewController()
+/// UIKit spells non-character keys as sentinel input strings rather than as the
+/// character they would type. JS sends the DOM `code` and the mapping lives
+/// here, so the constants stay in the one place that owns UIKit vocabulary.
+private let namedKeyInputs: [String: String] = [
+  "Escape": UIKeyCommand.inputEscape,
+  "ArrowUp": UIKeyCommand.inputUpArrow,
+  "ArrowDown": UIKeyCommand.inputDownArrow,
+  "Enter": "\r",
+]
+
+/// Whether the first responder is mid-IME-composition.
+///
+/// A committing key has to stay out of the way while a CJK candidate is being
+/// chosen: Enter confirms the candidate, and consuming it as a key command
+/// would submit the half-composed text instead.
+private func isComposingText() -> Bool {
+  guard let responder = UIResponder.paseoCurrentFirstResponder as? UITextInput else {
+    return false
   }
+  return responder.markedTextRange != nil
 }
 
 public class PaseoHardwareKeyboardModule: Module {
+  private var keyboardObservers: [NSObjectProtocol] = []
   public func definition() -> ModuleDefinition {
     Name("PaseoHardwareKeyboard")
 
-    Events(hardwareSubmitEventName)
+    Events(hardwareSubmitEventName, hardwareShortcutEventName, "onHardwareKeyboardPresenceChanged")
 
     OnCreate {
       activeModule = self
+      for name in [Notification.Name.GCKeyboardDidConnect, Notification.Name.GCKeyboardDidDisconnect] {
+        self.keyboardObservers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
+          self?.sendEvent("onHardwareKeyboardPresenceChanged", [:])
+        })
+      }
     }
 
+    Function("getHardwareKeyboardPresent") { GCKeyboard.coalesced != nil }
+
     Function("setHardwareKeyboardSubmitEnabled") { (enabled: Bool) in
       DispatchQueue.main.async {
         isHardwareSubmitEnabled = enabled
       }
     }
 
+    Function("setOverlayKeys") { (keys: [String]) in
+      DispatchQueue.main.async {
+        overlayKeys = Set(keys).intersection(["Enter", "ArrowUp", "ArrowDown"])
+        UIMenuSystem.main.setNeedsRebuild()
+      }
+    }
+
     OnDestroy {
+      self.keyboardObservers.forEach(NotificationCenter.default.removeObserver)
+      self.keyboardObservers = []
       if activeModule === self {
         activeModule = nil
+        isHardwareSubmitEnabled = false
+        overlayKeys = []
       }
-      isHardwareSubmitEnabled = false
     }
   }
 
   fileprivate func emitHardwareKeyboardSubmit() {
     sendEvent(hardwareSubmitEventName, [:])
   }
+
+  fileprivate func emitHardwareKeyboardPress(_ press: UIPress, isRepeat: Bool) {
+    guard let key = press.key else { return }
+    let code = hardwareKeyCode(key)
+    let characters = key.characters
+    let named = namedKeyInputs.first { $0.value == characters }?.key
+    let keyName: String
+    if code.hasPrefix("Meta") { keyName = "Meta" }
+    else if code.hasPrefix("Control") { keyName = "Control" }
+    else if code.hasPrefix("Shift") { keyName = "Shift" }
+    else if code.hasPrefix("Alt") { keyName = "Alt" }
+    else { keyName = named ?? (characters.isEmpty ? code : characters) }
+    guard !code.isEmpty else { return }
+    sendEvent(hardwareShortcutEventName, [
+      "key": keyName,
+      "code": code,
+      "altKey": key.modifierFlags.contains(.alternate),
+      "ctrlKey": key.modifierFlags.contains(.control),
+      "metaKey": key.modifierFlags.contains(.command),
+      "shiftKey": key.modifierFlags.contains(.shift),
+      "repeat": isRepeat,
+      "isComposing": isComposingText(),
+      "phase": press.phase == .ended || press.phase == .cancelled ? "up" : "down",
+    ])
+  }
 }
 
-private final class PaseoHardwareKeyboardRootViewController: UIViewController {
-  override var keyCommands: [UIKeyCommand]? {
-    guard isHardwareSubmitEnabled && UIDevice.current.userInterfaceIdiom == .pad else {
-      return super.keyCommands
-    }
+public final class PaseoHardwareKeyboardWindow: UIWindow {
+  private var pressedCodes: Set<Int> = []
+  public static func observing(_ original: UIWindow) -> UIWindow {
+    if original is PaseoHardwareKeyboardWindow { return original }
+    guard let scene = original.windowScene else { return original }
+    let observed = PaseoHardwareKeyboardWindow(windowScene: scene)
+    observed.windowLevel = original.windowLevel
+    observed.backgroundColor = original.backgroundColor
+    let controller = original.rootViewController
+    original.rootViewController = nil
+    original.isHidden = true
+    observed.rootViewController = controller
+    observed.makeKeyAndVisible()
+    return observed
+  }
 
+  public override func sendEvent(_ event: UIEvent) {
+    if let event = event as? UIPressesEvent {
+      for press in event.allPresses where press.phase == .began || press.phase == .ended || press.phase == .cancelled {
+        guard let key = press.key else { continue }
+        let raw = Int(key.keyCode.rawValue)
+        let isRepeat = press.phase == .began && pressedCodes.contains(raw)
+        if press.phase == .began { pressedCodes.insert(raw) }
+        else { pressedCodes.remove(raw) }
+        activeModule?.emitHardwareKeyboardPress(press, isRepeat: isRepeat)
+      }
+    }
+    super.sendEvent(event)
+  }
+  public override var keyCommands: [UIKeyCommand]? {
+    var commands = super.keyCommands ?? []
+    if isHardwareSubmitEnabled && !isPlainReturnClaimed && !isComposingText()
+      && UIDevice.current.userInterfaceIdiom == .pad
+    {
+      commands.append(makeSubmitCommand())
+    }
+    if !isComposingText() { commands.append(contentsOf: overlayKeys.compactMap(makeShortcutCommand)) }
+    return commands
+  }
+
+  /// Whether something registered has already asked for an unmodified Return.
+  ///
+  /// The submit command is registered for as long as the composer holds focus,
+  /// which includes while a picker is open over it. Registering both would put
+  /// two commands on one press, and the composer would win a press the picker
+  /// asked for — Enter would create the workspace instead of choosing a project.
+  private var isPlainReturnClaimed: Bool {
+    overlayKeys.contains("Enter")
+  }
+
+  private func makeSubmitCommand() -> UIKeyCommand {
     let command = UIKeyCommand(
       input: "\r",
       modifierFlags: [],
@@ -56,7 +162,14 @@ private final class PaseoHardwareKeyboardRootViewController: UIViewController {
     if #available(iOS 15.0, *) {
       command.wantsPriorityOverSystemBehavior = true
     }
-    return (super.keyCommands ?? []) + [command]
+    return command
+  }
+
+  private func makeShortcutCommand(_ key: String) -> UIKeyCommand? {
+    guard let input = namedKeyInputs[key] else { return nil }
+    let command = UIKeyCommand(input: input, modifierFlags: [], action: #selector(handleHardwareKeyboardShortcut(_:)))
+    if #available(iOS 15.0, *) { command.wantsPriorityOverSystemBehavior = true }
+    return command
   }
 
   @objc
@@ -67,6 +180,9 @@ private final class PaseoHardwareKeyboardRootViewController: UIViewController {
     activeModule?.emitHardwareKeyboardSubmit()
   }
 
+  @objc
+  private func handleHardwareKeyboardShortcut(_ sender: UIKeyCommand) {}
+
   private func canSubmitCurrentTextInput() -> Bool {
     guard let responder = UIResponder.paseoCurrentFirstResponder else {
       return false
@@ -97,3 +213,25 @@ private extension UIResponder {
     UIResponder.currentFirstResponder = self
   }
 }
+
+
+private func hardwareKeyCode(_ key: UIKey) -> String {
+  let raw = key.keyCode.rawValue
+  if raw >= 4 && raw <= 29 {
+    let letter = UnicodeScalar(Int(raw) + 61)!
+    return "Key" + String(letter)
+  }
+  if raw >= 30 && raw <= 38 { return "Digit" + String(raw - 29) }
+  if raw == 39 { return "Digit0" }
+  let codes: [Int: String] = [
+    40: "Enter", 41: "Escape", 42: "Backspace", 43: "Tab", 44: "Space",
+    45: "Minus", 46: "Equal", 47: "BracketLeft", 48: "BracketRight",
+    49: "Backslash", 51: "Semicolon", 52: "Quote", 53: "Backquote",
+    54: "Comma", 55: "Period", 56: "Slash", 76: "Delete", 79: "ArrowRight",
+    80: "ArrowLeft", 81: "ArrowDown", 82: "ArrowUp", 224: "ControlLeft",
+    225: "ShiftLeft", 226: "AltLeft", 227: "MetaLeft", 228: "ControlRight",
+    229: "ShiftRight", 230: "AltRight", 231: "MetaRight",
+  ]
+  if raw >= 58 && raw <= 69 { return "F" + String(raw - 57) }
+  return codes[Int(raw)] ?? ""
+}

packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt

@@ -4,11 +4,13 @@ import android.graphics.Rect
 import android.text.Selection
 import android.text.Spannable
 import android.view.View
+import android.view.InputDevice
+import android.view.MotionEvent
+import android.os.SystemClock
 import android.widget.FrameLayout
 import android.widget.TextView
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
-import com.facebook.react.bridge.BridgeReactContext
 import com.facebook.react.bridge.JavaOnlyArray
 import com.facebook.react.bridge.JavaOnlyMap
 import com.facebook.react.soloader.OpenSourceMergedSoMapping
@@ -24,6 +26,40 @@ import org.junit.runner.RunWith
 
 @RunWith(AndroidJUnit4::class)
 class ScrollSelectionTest {
+  @Test fun mouseWheelMovesInvertedViewportInVisualDirection() = withScroll(inverted = true) { scroll, _ ->
+    val before = scroll.scrollY
+    withWheel(1f) { event ->
+      assertTrue(scroll.dispatchGenericMotionEvent(event))
+      assertTrue("Wheel up must move toward older messages: $before -> ${scroll.scrollY}", scroll.scrollY > before)
+      assertEquals("The caller's event must not change", 1f, event.getAxisValue(MotionEvent.AXIS_VSCROLL))
+    }
+    val afterUp = scroll.scrollY
+    withWheel(-1f) { event ->
+      assertTrue(scroll.dispatchGenericMotionEvent(event))
+      assertTrue("Wheel down must move toward newer messages: $afterUp -> ${scroll.scrollY}", scroll.scrollY < afterUp)
+    }
+  }
+
+  @Test fun mouseWheelKeepsOrdinaryScrollDirection() = withScroll(inverted = false) { scroll, _ ->
+    val before = scroll.scrollY
+    withWheel(1f) { event ->
+      assertTrue(scroll.dispatchGenericMotionEvent(event))
+      assertTrue(scroll.scrollY < before)
+    }
+    val afterUp = scroll.scrollY
+    withWheel(-1f) { event ->
+      assertTrue(scroll.dispatchGenericMotionEvent(event))
+      assertTrue(scroll.scrollY > afterUp)
+    }
+  }
+
+  @Test fun mouseWheelRespectsDisabledScrolling() = withScroll(inverted = true) { scroll, _ ->
+    scroll.setScrollEnabled(false)
+    val before = scroll.scrollY
+    withWheel(1f) { scroll.dispatchGenericMotionEvent(it) }
+    assertEquals(before, scroll.scrollY)
+  }
+
   @Test fun focusingSelectableTextKeepsInvertedViewportStill() = withScroll(inverted = true) { scroll, text ->
     val before = scroll.scrollY
     assertTrue(text.requestFocus())
@@ -70,7 +106,7 @@ class ScrollSelectionTest {
       val appContext = instrumentation.targetContext
       DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(appContext)
       SoLoader.init(appContext, OpenSourceMergedSoMapping)
-      val reactContext = BridgeReactContext(appContext)
+      val reactContext = ScrollTestContext(appContext)
       val context = ThemedReactContext(reactContext, appContext)
       val manager = PaseoScrollPackage().createViewManager(reactContext, ReactScrollViewManager.REACT_CLASS) as ReactScrollViewManager
       val scroll = manager.createViewInstance(context)
@@ -98,4 +134,26 @@ class ScrollSelectionTest {
   }
 
   private fun exact(size: Int) = View.MeasureSpec.makeMeasureSpec(size, View.MeasureSpec.EXACTLY)
+
+  private fun withWheel(axis: Float, check: (MotionEvent) -> Unit) {
+    val time = SystemClock.uptimeMillis()
+    val properties = MotionEvent.PointerProperties().apply {
+      id = 0
+      toolType = MotionEvent.TOOL_TYPE_MOUSE
+    }
+    val coordinates = MotionEvent.PointerCoords().apply {
+      x = 150f
+      y = 150f
+      setAxisValue(MotionEvent.AXIS_VSCROLL, axis)
+    }
+    val event = MotionEvent.obtain(
+      time, time, MotionEvent.ACTION_SCROLL, 1, arrayOf(properties), arrayOf(coordinates),
+      0, 0, 1f, 1f, 0, 0, InputDevice.SOURCE_MOUSE, 0,
+    )
+    try {
+      check(event)
+    } finally {
+      event.recycle()
+    }
+  }
 }

packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java

@@ -0,0 +1,19 @@
+package sh.paseo.scroll;
+
+import android.content.Context;
+import com.facebook.react.bridge.BridgeReactContext;
+import com.facebook.react.uimanager.events.BlackHoleEventDispatcher;
+import com.facebook.react.uimanager.events.EventDispatcher;
+import com.facebook.react.uimanager.events.EventDispatcherProvider;
+
+/** Native-only tests use RN's dispatcher for a context without a JS instance. */
+final class ScrollTestContext extends BridgeReactContext implements EventDispatcherProvider {
+  ScrollTestContext(Context context) {
+    super(context);
+  }
+
+  @Override
+  public EventDispatcher getEventDispatcher() {
+    return BlackHoleEventDispatcher.INSTANCE;
+  }
+}

packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt

@@ -2,6 +2,8 @@ package sh.paseo.scroll
 
 import android.graphics.Matrix
 import android.graphics.Rect
+import android.view.InputDevice
+import android.view.MotionEvent
 import com.facebook.react.ReactPackage
 import com.facebook.react.ViewManagerOnDemandReactPackage
 import com.facebook.react.bridge.NativeModule
@@ -30,13 +32,47 @@ private class PaseoScrollViewManager : ReactScrollViewManager() {
 private class PaseoScrollView(context: ThemedReactContext) : ReactScrollView(context) {
   private val transformValues = FloatArray(9)
 
+  private fun isVerticallyInverted(): Boolean {
+    // Android FlatList uses scale: -1, which RN decomposes into a 180-degree
+    // rotation with positive scaleY. Read the resulting transform, not scaleY.
+    matrix.getValues(transformValues)
+    return transformValues[Matrix.MSCALE_Y] < 0
+  }
+
+  override fun onGenericMotionEvent(event: MotionEvent): Boolean {
+    if (!isVerticallyInverted() || event.actionMasked != MotionEvent.ACTION_SCROLL ||
+        !event.isFromSource(InputDevice.SOURCE_CLASS_POINTER)) {
+      return super.onGenericMotionEvent(event)
+    }
+    if (!scrollEnabled) return false
+
+    // Android applies wheel axes directly to scrollY; the inversion transform only
+    // transforms pointer coordinates. Reverse the vertical axis before delegating so
+    // platform scroll bounds and scroll events still apply.
+    val properties = Array(event.pointerCount) { index ->
+      MotionEvent.PointerProperties().also { event.getPointerProperties(index, it) }
+    }
+    val coordinates = Array(event.pointerCount) { index ->
+      MotionEvent.PointerCoords().also {
+        event.getPointerCoords(index, it)
+        it.setAxisValue(MotionEvent.AXIS_VSCROLL, -it.getAxisValue(MotionEvent.AXIS_VSCROLL))
+      }
+    }
+    val correctedEvent = MotionEvent.obtain(
+      event.downTime, event.eventTime, event.action, event.pointerCount, properties, coordinates,
+      event.metaState, event.buttonState, event.xPrecision, event.yPrecision,
+      event.deviceId, event.edgeFlags, event.source, event.flags,
+    )
+    return try {
+      super.onGenericMotionEvent(correctedEvent)
+    } finally {
+      correctedEvent.recycle()
+    }
+  }
+
   // Both RN focus handling and Android selection visibility requests use this calculation.
   // Its coordinates ignore inversion. Keep focus/selection bookkeeping, but leave timeline
   // movement to user gestures and explicit scroll commands.
-  override fun computeScrollDeltaToGetChildRectOnScreen(rect: Rect): Int {
-    // RN's Android scale: -1 becomes a 180-degree rotation with positive scaleY.
-    matrix.getValues(transformValues)
-    if (transformValues[Matrix.MSCALE_Y] < 0) return 0
-    return super.computeScrollDeltaToGetChildRectOnScreen(rect)
-  }
+  override fun computeScrollDeltaToGetChildRectOnScreen(rect: Rect): Int =
+    if (isVerticallyInverted()) 0 else super.computeScrollDeltaToGetChildRectOnScreen(rect)
 }

packages/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.0",
   "private": true,
   "main": "index.ts",
   "scripts": {
@@ -40,7 +40,7 @@
     "dev:ios": "npm --prefix ../.. run build:client && cross-env APP_VARIANT=development expo run:ios",
     "build:apk": "npm --prefix ../.. run build:apk",
     "build:apk:arm64": "npm --prefix ../.. run build:apk:arm64",
-    "test:android": "expo prebuild --platform android --no-install && cd android && ./gradlew :paseo-native-trace:testReleaseUnitTest :react-native-enriched-markdown:testReleaseUnitTest --tests '*InlineCodeFormattingTest' --no-daemon --max-workers=2 -Dorg.gradle.parallel=false"
+    "test:android": "expo prebuild --platform android --no-install && cd android && ./gradlew :paseo-native-trace:testReleaseUnitTest :paseo-hardware-keyboard:testReleaseUnitTest :react-native-enriched-markdown:testReleaseUnitTest --tests '*InlineCodeFormattingTest' --no-daemon --max-workers=2 -Dorg.gradle.parallel=false"
   },
   "dependencies": {
     "@codemirror/commands": "6.10.4",

packages/app/src/agent-stream/chat-find/index.web.tsx

@@ -15,7 +15,7 @@ import { PaneFind, findShortcutPlatform, isFindShortcut, type PaneFindHandle } f
 import { Button } from "@/components/ui/button";
 import { usePaneFocus } from "@/panels/pane-context";
 import { useRetainedPanelActive } from "@/components/retained-panel";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
+import { hasActiveOverlay } from "@/keyboard";
 import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { planTimelinePromptJump } from "@/timeline/timeline-sync-plan";
@@ -104,7 +104,7 @@ export function ChatFind({
   useEffect(() => {
     if (!active || !isInteractive) return;
     const onKeyDown = (event: KeyboardEvent) => {
-      if (event.defaultPrevented || hasActiveWebOverlay() || isImeComposingKeyboardEvent(event))
+      if (event.defaultPrevented || hasActiveOverlay() || isImeComposingKeyboardEvent(event))
         return;
       if (isFindShortcut(event, findShortcutPlatform())) {
         event.preventDefault();

packages/app/src/app/_layout.tsx

@@ -1,3 +1,4 @@
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { AddHostProvider, AddHostFlowHost } from "@/hosts/add-host";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useActiveWorkspaceSelection } from "@/stores/navigation-active-workspace-store";
@@ -90,7 +91,7 @@ import { useActiveWorktreeNewAction } from "@/hooks/use-active-worktree-new-acti
 import { useGlobalNewWorkspaceAction } from "@/hooks/use-global-new-workspace-action";
 import { useLatchedBoolean } from "@/hooks/use-latched-boolean";
 import { useFaviconStatus } from "@/hooks/use-favicon-status";
-import { useKeyboardShortcuts } from "@/hooks/use-keyboard-shortcuts";
+import { useKeyboardShortcuts } from "@/keyboard/use-shortcuts";
 import { KeyboardShiftProvider } from "@/keyboard/shift";
 import { useCompactWebViewportZoomLock } from "@/hooks/use-compact-web-viewport-zoom-lock";
 import { useOpenProject } from "@/hooks/use-open-project";
@@ -549,8 +550,12 @@ function SidebarChrome({
   const isMobileActive = useIsMobilePanelActive("agent-list");
   const isDesktopOpen = usePanelStore((state) => state.desktop.agentListOpen);
   const active = visible && (isCompactLayout ? isMobileActive : isDesktopOpen);
+  const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   return (
-    <SidebarModelProvider active={active}>
+    <SidebarModelProvider
+      active={active}
+      keyboardNavigationActive={keyboardShortcutsEnabled && hardwareKeyboardPresent}
+    >
       {mounted ? <LeftSidebar active={active} /> : null}
       <WorkspaceShortcutTargetsSubscriber enabled={keyboardShortcutsEnabled} />
     </SidebarModelProvider>

packages/app/src/command-center/command-center.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import equal from "fast-deep-equal";
 import { recordRenderProfileReasons } from "@/utils/render-profiler";
@@ -52,11 +53,7 @@ import { useProjects } from "@/hooks/use-projects";
 import { useTimeAgo } from "@/hooks/use-time-ago";
 import { createProjectIconTarget } from "@/projects/icon-target";
 import { useProjectIcons } from "@/projects/icons";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import {
   useKeyboardShortcutsStore,
@@ -763,6 +760,10 @@ function SectionRow({ row }: { row: Extract<CommandCenterListRow, { kind: "secti
   );
 }
 
+// Escape arrives without asking; it is registered for `agent.interrupt` anyway.
+// Backspace stays off deliberately — the palette pops its scope with it on web,
+// but a registered command would stop the search field deleting text.
+
 export function CommandCenter() {
   const { t } = useTranslation();
   const isCompact = useIsCompactFormFactor();
@@ -780,7 +781,7 @@ export function CommandCenter() {
     interaction,
   );
   const showBottomSheet = isCompact && isNative;
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && state.open && !showBottomSheet);
+  const modalLayer = useGlobalOverlayLayer("modal", state.open);
   const { sheetRef, handleSheetChange, handleSheetDismiss } = useIsolatedBottomSheetVisibility({
     visible: state.open,
     isEnabled: showBottomSheet,
@@ -874,23 +875,20 @@ export function CommandCenter() {
       : {}),
     scrollEventThrottle: 16,
   };
-  const keyPress = useCallback(
-    ({ nativeEvent: { key } }: { nativeEvent: { key: string } }) => state.key(key),
-    [state],
-  );
   const submit = useCallback(() => state.key("Enter"), [state]);
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (!state.key(event.key)) return false;
       event.preventDefault();
       return true;
     },
     [state],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && state.open && !showBottomSheet,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: state.open,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   if (showBottomSheet) {
@@ -911,45 +909,46 @@ export function CommandCenter() {
         keyboardBlurBehavior="restore"
         accessible={false}
       >
-        <View style={[styles.bottomSheetHeader, styles.searchRow]} testID="command-center-header">
-          {state.scope === "files" ? (
-            <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />
-          ) : null}
-          <ThemedBottomSheetTextInput
-            testID="command-center-input"
-            ref={bottomSheetInputRef}
-            initialValue={state.query}
-            variant="bottom-sheet"
-            onChangeText={state.setQuery}
-            onKeyPress={keyPress}
-            onSubmitEditing={submit}
-            placeholder={
-              state.scope === "files"
-                ? t("shell.commandCenter.filePlaceholder")
-                : t("shell.commandCenter.placeholder")
-            }
-            style={[styles.input, styles.growingInput]}
-            autoCapitalize="none"
-            autoCorrect={false}
-            autoFocus
-          />
-          <FileSearchLoadingIndicator
-            loading={state.fileSearchLoading}
-            label={t("shell.commandCenter.searchingFiles")}
-          />
-        </View>
-        {fileSearchError}
-        <BottomSheetFlatList ref={bottomSheetListRef} {...commonListProps} />
+        <OverlayLayerProvider layer={modalLayer}>
+          <View style={[styles.bottomSheetHeader, styles.searchRow]} testID="command-center-header">
+            {state.scope === "files" ? (
+              <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />
+            ) : null}
+            <ThemedBottomSheetTextInput
+              testID="command-center-input"
+              ref={bottomSheetInputRef}
+              initialValue={state.query}
+              variant="bottom-sheet"
+              onChangeText={state.setQuery}
+              onSubmitEditing={submit}
+              placeholder={
+                state.scope === "files"
+                  ? t("shell.commandCenter.filePlaceholder")
+                  : t("shell.commandCenter.placeholder")
+              }
+              style={[styles.input, styles.growingInput]}
+              autoCapitalize="none"
+              autoCorrect={false}
+              autoFocus
+            />
+            <FileSearchLoadingIndicator
+              loading={state.fileSearchLoading}
+              label={t("shell.commandCenter.searchingFiles")}
+            />
+          </View>
+          {fileSearchError}
+          <BottomSheetFlatList ref={bottomSheetListRef} {...commonListProps} />
+        </OverlayLayerProvider>
       </IsolatedBottomSheetModal>
     );
   }
   if (!state.open) return null;
   return (
-    <OverlayLayerProvider layer={isWeb ? modalLayer : 0}>
+    <OverlayLayerProvider layer={modalLayer}>
       <Modal visible transparent animationType="fade" onRequestClose={state.close}>
         <View style={styles.overlay}>
           <Pressable style={styles.backdrop} onPress={state.close} />
-          <View ref={setWebOverlayScope} testID="command-center-panel" style={styles.panel}>
+          <View ref={setOverlayScope} testID="command-center-panel" style={styles.panel}>
             <View style={[styles.header, styles.searchRow]} testID="command-center-header">
               {state.scope === "files" ? (
                 <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />

packages/app/src/command-center/root-registration.tsx

@@ -1,3 +1,4 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useMemo } from "react";
 import { router, type Href } from "expo-router";
 import { useTranslation } from "react-i18next";
@@ -15,12 +16,12 @@ import {
   Settings,
 } from "lucide-react-native";
 import { withUnistyles } from "react-native-unistyles";
-import { getIsElectronRuntime, useIsCompactFormFactor } from "@/constants/layout";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { useOpenAddProject } from "@/hooks/use-open-add-project";
 import { useImportSession } from "@/hooks/use-import-session";
 import { useKeyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher-context";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { resolveShortcutKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { usePanelStore } from "@/stores/panel-store";
@@ -111,7 +112,7 @@ export function CommandCenterRootActions() {
   const keyboardActionDispatcher = useKeyboardActionDispatcher();
   const { t } = useTranslation();
   const { overrides } = useKeyboardShortcutOverrides();
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAddProject = useOpenAddProject();
   const { open: openImportSession, sheet: importSessionSheet } = useImportSession();
   const settingsRoute = useMemo<Href>(() => buildSettingsRoute(), []);
@@ -128,7 +129,7 @@ export function CommandCenterRootActions() {
   const toggleDesktopAgentList = usePanelStore((state) => state.toggleDesktopAgentList);
   const toggleAgentList = isCompact ? toggleMobileAgentList : toggleDesktopAgentList;
   const shortcutPlatform = useMemo(
-    () => ({ isMac: getShortcutOs() === "mac", isDesktop: getIsElectronRuntime() }),
+    () => ({ isMac: getShortcutOs() === "mac", usesDesktopBindings }),
     [],
   );
   const actions = useMemo<CommandCenterContribution[]>(() => {

packages/app/src/command-center/workspace-registration.tsx

@@ -1,3 +1,4 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useCallback, useMemo, type ReactElement } from "react";
 import { useTranslation } from "react-i18next";
 import {
@@ -105,7 +106,7 @@ function staticIcon(element: ReactElement | undefined): CommandCenterIcon | unde
 }
 
 function resolveWorkspaceShortcuts(overrides: ShortcutOverrides): WorkspaceCommandCenterShortcuts {
-  const platform = { isMac: getShortcutOs() === "mac", isDesktop: getIsElectron() };
+  const platform = { isMac: getShortcutOs() === "mac", usesDesktopBindings };
   return resolveWorkspaceCommandCenterShortcuts({ overrides, platform });
 }
 

packages/app/src/command-center/workspace-shortcuts.test.ts

@@ -6,7 +6,7 @@ describe("resolveWorkspaceCommandCenterShortcuts", () => {
     expect(
       resolveWorkspaceCommandCenterShortcuts({
         overrides: {},
-        platform: { isMac: true, isDesktop: true },
+        platform: { isMac: true, usesDesktopBindings: true },
       }).newAgent,
     ).toEqual([["mod", "shift", "A"]]);
   });

packages/app/src/command-center/workspace-shortcuts.ts

@@ -6,7 +6,7 @@ import type { WorkspaceCommandCenterShortcuts } from "./workspace-contributions"
 
 interface ResolveWorkspaceCommandCenterShortcutsInput {
   overrides: ShortcutOverrides;
-  platform: { isMac: boolean; isDesktop: boolean };
+  platform: { isMac: boolean; usesDesktopBindings: boolean };
 }
 
 export function resolveWorkspaceCommandCenterShortcuts({

packages/app/src/components/adaptive-modal-sheet.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import type { ComponentProps, ReactNode } from "react";
 import { createPortal } from "react-dom";
@@ -6,12 +7,7 @@ import { Keyboard, Pressable, Text, View } from "react-native";
 import type { DimensionValue, StyleProp, ViewProps, ViewStyle } from "react-native";
 import { StyleSheet, useUnistyles, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "../lib/overlay-root";
+import { getOverlayRoot, OverlayLayerProvider, useGlobalOverlayLayer } from "../lib/overlay-root";
 import {
   BottomSheetHandle,
   useBottomSheetGestureHandlers,
@@ -655,7 +651,7 @@ export function AdaptiveModalSheet({
   });
   const [shouldRenderWeb, setShouldRenderWeb] = useState(visible);
   const [isWebClosing, setIsWebClosing] = useState(false);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && !isMobile && shouldRenderWeb);
+  const modalLayer = useGlobalOverlayLayer("modal", visible || shouldRenderWeb);
   const handleDismiss = useCallback(() => {
     handleSheetDismiss();
     onDismiss?.();
@@ -683,8 +679,8 @@ export function AdaptiveModalSheet({
     [isWebClosing, modalLayer],
   );
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key !== "Escape") return false;
       event.preventDefault();
       event.stopPropagation();
@@ -693,10 +689,11 @@ export function AdaptiveModalSheet({
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && !isMobile && visible,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: visible,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   useEffect(() => {
@@ -735,18 +732,20 @@ export function AdaptiveModalSheet({
         accessible={false}
         presentation={presentation}
       >
-        <CompactSheetBody
-          header={header}
-          onClose={onClose}
-          testID={testID}
-          footer={footerView}
-          isKeyboardVisible={isKeyboardVisible}
-          scrollable={scrollable}
-          bodyStyle={bodyStyle}
-          contentStyle={contentStyle}
-        >
-          {children}
-        </CompactSheetBody>
+        <OverlayLayerProvider layer={modalLayer}>
+          <CompactSheetBody
+            header={header}
+            onClose={onClose}
+            testID={testID}
+            footer={footerView}
+            isKeyboardVisible={isKeyboardVisible}
+            scrollable={scrollable}
+            bodyStyle={bodyStyle}
+            contentStyle={contentStyle}
+          >
+            {children}
+          </CompactSheetBody>
+        </OverlayLayerProvider>
       </IsolatedBottomSheetModal>
     );
   }
@@ -790,13 +789,7 @@ export function AdaptiveModalSheet({
         style={ABSOLUTE_FILL_STYLE}
         onPress={onClose}
       />
-      <View
-        ref={setWebOverlayScope}
-        style={desktopCardStyle}
-        role="dialog"
-        aria-modal
-        tabIndex={-1}
-      >
+      <View ref={setOverlayScope} style={desktopCardStyle} role="dialog" aria-modal tabIndex={-1}>
         {cardInner}
       </View>
     </View>

packages/app/src/components/add-project-flow.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
 import { usePanelStore } from "@/stores/panel-store";
@@ -69,19 +70,15 @@ import {
 } from "@/components/project-picker-options";
 import { Shortcut } from "@/components/ui/shortcut";
 import { useRevealActiveItem } from "@/components/ui/scroll-reveal";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { getIsElectronRuntime } from "@/constants/layout";
-import { isNative, isWeb } from "@/constants/platform";
+import { isWeb } from "@/constants/platform";
 import { pickDirectory } from "@/desktop/pick-directory";
 import { useFetchQuery } from "@/data/query";
 import { getOpenProjectFailureReason, registerProjectDescriptor } from "@/hooks/open-project";
 import { useIsLocalDaemon, useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import { useCloneGithubProject, useOpenProject } from "@/hooks/use-open-project";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import {
   useHosts,
   useHostRuntimeClient,
@@ -302,7 +299,7 @@ function FlowRow({
 }
 
 function FlowHint({ keys, action }: { keys: string[]; action: string }) {
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   if (!shortcutsAvailable) return null;
 
   return (
@@ -460,13 +457,10 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
   });
 
   const handleBack = useCallback(() => {
-    setState((current) => {
-      const previous = backAddProjectPage(current);
-      if (previous) return previous;
-      onClose();
-      return current;
-    });
-  }, [onClose]);
+    const previous = backAddProjectPage(state);
+    if (previous) setState(previous);
+    else onClose();
+  }, [onClose, state]);
 
   const openNewWorkspaceForProject = useCallback(
     (serverId: string, project: WorkspaceProjectDescriptorPayload) => {
@@ -815,30 +809,22 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     [activeIndex, handleBack, rows, submitActive],
   );
 
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb);
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const modalLayer = useGlobalOverlayLayer("modal", true);
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (!handleKey(event.key)) return false;
       event.preventDefault();
       return true;
     },
     [handleKey],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: true,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
-  const handleNativeKeyPress = useCallback(
-    ({ nativeEvent: { key } }: { nativeEvent: { key: string } }) => {
-      if (key === "ArrowDown" || key === "ArrowUp" || key === "Escape") {
-        handleKey(key);
-      }
-    },
-    [handleKey],
-  );
-
   const handleInputChange = useCallback((value: string) => {
     setState((current) =>
       currentAddProjectPage(current).kind === "new-directory-name"
@@ -873,7 +859,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
       <View style={styles.overlay} testID="add-project-flow">
         <Pressable style={styles.backdrop} onPress={onClose} testID="add-project-flow-backdrop" />
         <View
-          ref={setWebOverlayScope}
+          ref={setOverlayScope}
           style={styles.panel}
           testID={`add-project-flow-page-${page.kind}`}
           accessibilityLabel={`Add project: ${page.kind}`}
@@ -892,29 +878,11 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
                 ) : null}
               </View>
             </View>
-            {page.kind === "method" && isNative ? (
-              // Native hardware-keyboard events need a focused responder even without a visible field.
-              <TextInput
-                ref={inputRef}
-                onKeyPress={handleNativeKeyPress}
-                onSubmitEditing={submitActive}
-                showSoftInputOnFocus={false}
-                caretHidden
-                contextMenuHidden
-                accessible={false}
-                accessibilityElementsHidden
-                importantForAccessibility="no-hide-descendants"
-                pointerEvents="none"
-                style={styles.keyboardCapture}
-                testID="add-project-flow-keyboard-capture"
-              />
-            ) : null}
             {page.kind !== "method" ? (
               <ThemedTextInput
                 ref={inputRef}
                 initialValue={pageInput(page)}
                 onChangeText={handleInputChange}
-                onKeyPress={isWeb ? undefined : handleNativeKeyPress}
                 onSubmitEditing={isWeb ? undefined : submitActive}
                 placeholder={pagePlaceholder(page)}
                 style={styles.input}
@@ -996,7 +964,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     </Modal>
   );
 
-  return createElement(OverlayLayerProvider, { layer: isWeb ? modalLayer : 0 }, modal);
+  return createElement(OverlayLayerProvider, { layer: modalLayer }, modal);
 }
 
 const styles = StyleSheet.create((theme) => ({
@@ -1070,12 +1038,6 @@ const styles = StyleSheet.create((theme) => ({
     paddingVertical: theme.spacing[1],
     outlineStyle: "none",
   } as object,
-  keyboardCapture: {
-    position: "absolute",
-    width: 1,
-    height: 1,
-    opacity: 0,
-  },
   results: { flexGrow: 0, flexShrink: 1, minHeight: 0 },
   resultsContent: { paddingVertical: theme.spacing[2] },
   row: {

packages/app/src/components/attachment-lightbox.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
 import { Pressable, Text, View } from "react-native";
@@ -8,12 +9,12 @@ import { X } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import type { AttachmentMetadata } from "@/attachments/types";
 import { useAttachmentPreviewUrl } from "@/attachments/use-attachment-preview-url";
-import { isNative, isWeb } from "@/constants/platform";
+import { isNative } from "@/constants/platform";
 import { SPACING } from "@/styles/theme";
 import { WindowChromeRootRegion } from "@/utils/desktop-window";
 import { ZoomableImage } from "@/components/zoomable-viewport/image";
 import type { ViewportSize } from "@/components/zoomable-viewport/geometry";
-import { useGlobalWebOverlayLayer, useWebOverlayRegistration } from "@/lib/overlay-root";
+import { useGlobalOverlayLayer } from "@/lib/overlay-root";
 
 export type ImageLightboxSource =
   | { type: "attachment"; metadata: AttachmentMetadata }
@@ -34,14 +35,14 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
   const url = source?.type === "uri" ? source.uri : attachmentUrl;
   const contentSize = source?.type === "uri" ? source.contentSize : undefined;
   const [errored, setErrored] = useState(false);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && source !== null);
+  const modalLayer = useGlobalOverlayLayer("modal", source !== null);
 
   useEffect(() => {
     setErrored(false);
   }, [metadata?.id, url]);
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key !== "Escape") return false;
       event.preventDefault();
       event.stopPropagation();
@@ -50,10 +51,11 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && source !== null,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: source !== null,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   const actions = useMemo(
@@ -83,7 +85,7 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
             image was opened (inside a sheet tab, the bottom one is already spent). */}
         <SafeAreaProvider>
           <WindowChromeRootRegion corners="both">
-            <View ref={setWebOverlayScope} style={styles.root}>
+            <View ref={setOverlayScope} style={styles.root}>
               <Pressable
                 testID="attachment-lightbox-backdrop"
                 accessibilityRole="button"

packages/app/src/components/keyboard-shortcuts-dialog.tsx

@@ -1,8 +1,8 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { getIsElectronRuntime } from "@/constants/layout";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Shortcut } from "@/components/ui/shortcut";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
@@ -24,14 +24,13 @@ export function KeyboardShortcutsDialog() {
 
   const shortcutOs = getShortcutOs();
   const isMac = shortcutOs === "mac";
-  const isDesktopApp = getIsElectronRuntime();
   const { overrides } = useKeyboardShortcutOverrides();
   // Effective bindings, so a shortcut the user unassigned lists no keys here
   // instead of advertising a default that no longer fires.
   const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
   const sections = useMemo(
-    () => buildKeyboardShortcutHelpSections({ isMac, isDesktop: isDesktopApp }, bindings),
-    [bindings, isDesktopApp, isMac],
+    () => buildKeyboardShortcutHelpSections({ isMac, usesDesktopBindings }, bindings),
+    [bindings, isMac],
   );
   const visibleSections = useMemo(
     () => filterShortcutHelpSections({ sections, query, translate: t, shortcutOs }),

packages/app/src/components/markdown/images.ts

@@ -38,12 +38,18 @@ export interface MarkdownImageContext {
 export function useMarkdownSource(
   text: string,
   context: MarkdownImageContext,
-  commandNames?: ReadonlySet<string>,
+  links: { commandNames?: ReadonlySet<string>; forgeReferencePattern?: string } = {},
 ) {
   const occurrenceKey = useId();
+  const { commandNames, forgeReferencePattern } = links;
   const prepared = useMemo(
-    () => prepareMarkdownSource(text, context.workspaceRoot, { supportsSvg: isWeb, commandNames }),
-    [text, context.workspaceRoot, commandNames],
+    () =>
+      prepareMarkdownSource(text, context.workspaceRoot, {
+        supportsSvg: isWeb,
+        commandNames,
+        forgeReferencePattern,
+      }),
+    [text, context.workspaceRoot, commandNames, forgeReferencePattern],
   );
   const sources = [...new Set(prepared.images.map((image) => image.source))];
   const acquisitions = sources.map((source) => {

packages/app/src/components/markdown/renderer.test.ts

@@ -3,6 +3,7 @@ import { toNativeLinkRecognition } from "react-native-enriched-markdown/src/util
 import { parseMarkdown } from "react-native-enriched-markdown/src/web/parseMarkdown";
 import { recognizeTextLinks } from "react-native-enriched-markdown/src/web/recognizeTextLinks";
 import { matchCommandLink } from "@/agent-commands";
+import { createForgeShorthand } from "@/git/forge-shorthand";
 
 import { classifyAssistantFileLink } from "@/assistant-file-links";
 import { markInlineImages } from "react-native-enriched-markdown/src/web/utils";
@@ -110,6 +111,37 @@ describe("shared Markdown source adaptation", () => {
       ["https://x/q.png", false],
     ]);
   });
+  it("renders linked images that share a line with text inline", async () => {
+    // A review bot's summary header: linked badges inside a heading with the score text.
+    const reviewHeader =
+      '<h2><a href="https://x/retrigger"><picture><source media="(prefers-color-scheme: dark)" srcset="https://x/r-dark.svg"><img alt="Retrigger" src="https://x/r.svg" align="right"></picture></a>Confidence Score: 5/5</h2>';
+    const source = [
+      reviewHeader,
+      "[![Alone](https://x/alone.png)](https://x)",
+      "[![a](https://x/a.png)](https://x) [![b](https://x/b.png)](https://x)",
+      "See [![gh](https://x/gh.png) GitHub](https://x) for more.",
+    ].join("\n\n");
+    const tree = await parseMarkdown(prepareMarkdownSource(source).render(), {
+      hardSoftBreaks: true,
+      latexMath: false,
+    });
+    markInlineImages(tree);
+    const images: ASTNode[] = [];
+    const collect = (node: ASTNode) => {
+      if (node.type === "Image") images.push(node);
+      node.children?.forEach(collect);
+    };
+    collect(tree);
+    expect(
+      images.map((image) => [image.attributes?.url, image.attributes?.isInline === true]),
+    ).toEqual([
+      ["https://x/r.svg", true],
+      ["https://x/alone.png", false],
+      ["https://x/a.png", true],
+      ["https://x/b.png", true],
+      ["https://x/gh.png", true],
+    ]);
+  });
   it("escapes spoiler delimiters only in prose", () => {
     expect(prepareMarkdownSource("Show ||words|| and `||code||`.").render()).toBe(
       "Show \\|\\|words\\|\\| and `||code||`.",
@@ -412,6 +444,47 @@ it("lets the engine own code boundaries while classifying candidate values", asy
   ]);
 });
 
+it("recognizes forge references in prose but not in code, links or paths", async () => {
+  const shorthand = createForgeShorthand({
+    forge: "gitlab",
+    remoteUrl: "git@gitlab.com:g/p.git",
+  })!;
+  const source = [
+    "Fixed in #12 and !13, see g/sub/q#14 and https://example.com/a#15.",
+    "`#16` and [#17](https://example.com) and src/app/index.ts and src/a/b/c#18",
+    "```\n#19\n```",
+  ].join("\n\n");
+  const prepared = prepareMarkdownSource(source, "/repo", {
+    forgeReferencePattern: shorthand.pattern,
+  });
+  const tree = recognizeTextLinks(
+    await parseMarkdown(prepared.render(), { latexMath: false }),
+    prepared.linkRecognition.text,
+    prepared.linkRecognition.inlineCode,
+  );
+  const recognized: string[] = [];
+  function collect(node: ASTNode) {
+    if (node.type === "Link" && node.attributes?.recognizedLink === "true") {
+      recognized.push(String(node.attributes.url));
+    }
+    node.children?.forEach(collect);
+  }
+  collect(tree);
+  expect(recognized).toEqual(["#12", "!13", "g/sub/q#14", "src/app/index.ts", "src/a/b/c#18"]);
+  expect(recognized.map((url) => shorthand.resolve(url))).toEqual([
+    "https://gitlab.com/g/p/-/issues/12",
+    "https://gitlab.com/g/p/-/merge_requests/13",
+    "https://gitlab.com/g/sub/q/-/issues/14",
+    null,
+    "https://gitlab.com/src/a/b/c/-/issues/18",
+  ]);
+  // A rejected native regex silently falls back to no recognition at all.
+  expect(toNativeLinkRecognition(prepared.linkRecognition).text).toMatchObject({
+    isDisabled: false,
+    isDefault: false,
+  });
+});
+
 describe("bare URL sentence punctuation", () => {
   it.each([".", ",", ";", ":", "!", "?", ")", ").", "...", "?!"])(
     "leaves %s outside the link and preserves the rendered sentence",

packages/app/src/components/markdown/renderer.tsx

@@ -7,6 +7,8 @@ import {
 } from "@/assistant-file-links";
 import { useStableEvent } from "@/hooks/use-stable-event";
 import { matchCommandLink, useAgentCommandHints, type CommandHints } from "@/agent-commands";
+import { useForgeShorthand } from "@/git/forge-shorthand";
+import { openExternalUrl } from "@/utils/open-external-url";
 import { AttachmentLightbox, type ImageLightboxSource } from "@/components/attachment-lightbox";
 import type { Theme } from "@/styles/theme";
 import { isWeb } from "@/constants/platform";
@@ -89,6 +91,7 @@ const MarkdownPart = memo(function MarkdownPart({
 }: MarkdownRendererProps & { commandHints?: CommandHints | null }) {
   const environment = useAssistantFileLinkEnvironment();
   const actions = useAssistantFileLinkActions();
+  const forgeShorthand = useForgeShorthand();
   const client =
     imageContext.client ??
     (environment.client?.readFile
@@ -102,7 +105,7 @@ const MarkdownPart = memo(function MarkdownPart({
       ...imageContext,
       client,
     },
-    commandHints?.names,
+    { commandNames: commandHints?.names, forgeReferencePattern: forgeShorthand?.pattern },
   );
   const [image, setImage] = useState<ImageLightboxSource | null>(null);
   const pressLink = useStableEvent(({ url, sourceType }: LinkPressEvent) => {
@@ -111,6 +114,11 @@ const MarkdownPart = memo(function MarkdownPart({
       commandHints.insert(command);
       return;
     }
+    const forgeUrl = sourceType === "text" ? forgeShorthand?.resolve(url) : null;
+    if (forgeUrl) {
+      void openExternalUrl(forgeUrl);
+      return;
+    }
     const source = linkSource(url, sourceType);
     if (onLinkPress && !actions.canResolveFile(source)) onLinkPress(url);
     else actions.open(source, "preferred");

packages/app/src/components/markdown/renderers.web.tsx

@@ -7,6 +7,7 @@ import type {
 } from "react-native-enriched-markdown";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useFileLink } from "@/assistant-file-links";
+import { useForgeShorthand } from "@/git/forge-shorthand";
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
 import { HighlightedCodeBlock } from "@/components/highlighted-code-block";
 import type { Theme } from "@/styles/theme";
@@ -31,7 +32,13 @@ function WebCodeBlock({ code, language }: CodeBlockRendererProps) {
 const LINK_HOVER_STYLE = { textDecoration: "underline" } as const;
 
 function WebLink({ link, anchorProps, children }: LinkRendererProps) {
-  const { tooltipPath, onHoverIn } = useFileLink(markdownLinkSource(link.url, link.sourceType));
+  const forgeShorthand = useForgeShorthand();
+  // A forge reference like `#12` carries its web URL so hover, copy and new-tab opens work.
+  const forgeUrl = link.sourceType === "text" ? forgeShorthand?.resolve(link.url) : null;
+  const { tooltipPath, onHoverIn } = useFileLink(
+    forgeUrl ? markdownLinkSource(forgeUrl) : markdownLinkSource(link.url, link.sourceType),
+  );
+  const tooltip = forgeUrl ?? tooltipPath;
   const [hovered, setHovered] = useState(false);
   const handleMouseEnter = useCallback(() => setHovered(true), []);
   const handleMouseLeave = useCallback(() => setHovered(false), []);
@@ -46,6 +53,7 @@ function WebLink({ link, anchorProps, children }: LinkRendererProps) {
   const anchor = (
     <a
       {...anchorProps}
+      href={forgeUrl ?? anchorProps.href}
       style={anchorStyle}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
@@ -58,10 +66,10 @@ function WebLink({ link, anchorProps, children }: LinkRendererProps) {
       <TooltipTrigger asChild onHoverIn={onHoverIn}>
         <InlineLinkTrigger>{anchor}</InlineLinkTrigger>
       </TooltipTrigger>
-      {tooltipPath ? (
+      {tooltip ? (
         <TooltipContent side="top" align="start" maxWidth={520}>
           <Text selectable={false} style={styles.tooltipPath}>
-            {tooltipPath}
+            {tooltip}
           </Text>
         </TooltipContent>
       ) : null}

packages/app/src/components/markdown/source.ts

@@ -24,10 +24,12 @@ const FILE_NAME = String.raw`${PATH_SEGMENT}\.(?:${FILE_EXTENSIONS})`;
 // Bare prose paths need a known extension, a line suffix, or at least two separators.
 const PROSE_PATH = String.raw`(?:${PATH_PREFIX}${HAS_PATH_LETTER}${SEPARATED_PATH}|${HAS_PATH_LETTER}(?:${PATH_SEGMENT}(?:[\\/]${PATH_SEGMENT})*[\\/]${FILE_NAME}|${PATH_SEGMENT}(?:[\\/]${PATH_SEGMENT}){2,}|${SEPARATED_PATH}(?=:)))`;
 
-function createFilePattern(path: string): RegExp {
+function createTextPattern(path: string, forgeReferencePattern?: string): RegExp {
+  // Forge references come before paths so `group/project#12` is not read as a path.
+  const forgeReference = forgeReferencePattern ? `|${forgeReferencePattern}` : "";
   // The native adapter mistakes a literal + in lookbehind for a quantifier; use its hex escape.
   return new RegExp(
-    String.raw`(?:${BARE_URL}|(?<![a-zA-Z0-9\u0080-\uFFFF_@.%\x2b~:/\\-])(?:${path}|${FILE_NAME})${LINE_SUFFIX}(?![a-zA-Z0-9\u0080-\uFFFF_@%+:/\\-]|\.${PATH_CHARACTER}))`,
+    String.raw`(?:${BARE_URL}${forgeReference}|(?<![a-zA-Z0-9\u0080-\uFFFF_@.%\x2b~:/\\-])(?:${path}|${FILE_NAME})${LINE_SUFFIX}(?![a-zA-Z0-9\u0080-\uFFFF_@%+:/\\-]|\.${PATH_CHARACTER}))`,
     "g",
   );
 }
@@ -38,8 +40,20 @@ const URL_CHARACTER = String.raw`[^\s<>()"'\x60]`;
 const URL_GROUP = String.raw`\(${URL_CHARACTER}*\)`;
 const BARE_URL = String.raw`https?://(?:${URL_CHARACTER}|${URL_GROUP})*(?:[^\s<>()"'\x60.,;:!?]|${URL_GROUP})`;
 
-const FILE_PATTERN = createFilePattern(PROSE_PATH);
-function linkMetadata(inlineCodePaths: ReadonlySet<string>) {
+const TEXT_PATTERN = createTextPattern(PROSE_PATH);
+// One entry per distinct workspace forge remote; reuse keeps the engine's regex identity stable.
+const textPatternsByForgeReference = new Map<string, RegExp>();
+function textPattern(forgeReferencePattern?: string): RegExp {
+  if (!forgeReferencePattern) return TEXT_PATTERN;
+  let pattern = textPatternsByForgeReference.get(forgeReferencePattern);
+  if (!pattern) {
+    pattern = createTextPattern(PROSE_PATH, forgeReferencePattern);
+    textPatternsByForgeReference.set(forgeReferencePattern, pattern);
+  }
+  return pattern;
+}
+
+function linkMetadata(inlineCodePaths: ReadonlySet<string>, forgeReferencePattern?: string) {
   // The engine accepts regexes on both platforms. Classify complete code spans
   // first, then pass literal matches rather than maintaining a second path grammar.
   const alternatives = [...inlineCodePaths].map((path) =>
@@ -47,7 +61,7 @@ function linkMetadata(inlineCodePaths: ReadonlySet<string>) {
   );
   return {
     linkRecognition: {
-      text: FILE_PATTERN,
+      text: textPattern(forgeReferencePattern),
       inlineCode: new RegExp(
         String.raw`^(?:https?://[^\s<>]+${alternatives.length ? `|${alternatives.join("|")}` : ""})$`,
       ),
@@ -120,7 +134,12 @@ function workspaceHoverTitle(link: Link, markup: string, workspaceRoot?: string)
 export function prepareMarkdownSource(
   source: string,
   workspaceRoot?: string,
-  options: { supportsSvg?: boolean; commandNames?: ReadonlySet<string> } = {},
+  options: {
+    supportsSvg?: boolean;
+    commandNames?: ReadonlySet<string>;
+    /** Regex source for forge references such as `#12`; see `@/git/forge-shorthand`. */
+    forgeReferencePattern?: string;
+  } = {},
 ) {
   source = normalizeMarkdownHtml(source);
   const images: MarkdownImage[] = [];
@@ -132,6 +151,7 @@ export function prepareMarkdownSource(
     }));
   const metadata = linkMetadata(
     collectInlineCodePaths(source, workspaceRoot, options.commandNames),
+    options.forgeReferencePattern,
   );
   const edits: { start: number; end: number; text: string }[] = [];
   if (

packages/app/src/components/sidebar/sidebar-help-menu.tsx

@@ -18,7 +18,7 @@ import { DensityIcon } from "@/components/ui/density-icon";
 import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { useAppDiagnosticStore } from "@/diagnostics/store";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { useSessionStore } from "@/stores/session-store";
@@ -79,7 +79,7 @@ function HostVersionHint({ host }: { host: HostProfile }) {
 
 export function SidebarHelpMenu() {
   const { t } = useTranslation();
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAppDiagnostic = useAppDiagnosticStore((state) => state.open);
   const setShortcutsDialogOpen = useKeyboardShortcutsStore((state) => state.setShortcutsDialogOpen);
   const [open, setOpen] = useState(false);

packages/app/src/components/sidebar/sidebar-model.tsx

@@ -50,13 +50,16 @@ const SidebarModelContext = createContext<SidebarModel | null>(null);
 
 export function SidebarModelProvider({
   active,
+  keyboardNavigationActive = false,
   children,
 }: {
   active?: boolean;
+  keyboardNavigationActive?: boolean;
   children: ReactNode;
 }) {
   const { t } = useTranslation();
-  const list = useSidebarWorkspacesList({ enabled: active });
+  const modelActive = active !== false || keyboardNavigationActive;
+  const list = useSidebarWorkspacesList({ enabled: modelActive });
   const showBackground = useSidebarViewStore((state) => state.showBackground);
   const groupMode = useSidebarViewStore((state) => state.groupMode);
   const labelFilter = useSidebarViewStore((state) => state.labelFilter);
@@ -98,10 +101,11 @@ export function SidebarModelProvider({
   // anything; the label filter reads `labels`, which only exists on an entry. Hydration opens a
   // live session-store subscription over every workspace on every visible host, so widening this
   // for a filter that does not need it costs a retained-but-inactive sidebar real work.
+  // Hardware keyboard navigation needs the same filtered targets while the sidebar is hidden.
   const needsWorkspaceEntries = groupMode !== "project" || hasActiveLabelFilter;
   const workspaceEntriesByKey = useSidebarWorkspaceEntries(
     list.workspacePlacements,
-    active !== false || needsWorkspaceEntries,
+    modelActive || needsWorkspaceEntries,
   );
   const filteredWorkspaceEntriesByKey = useMemo(() => {
     const byProject = filterWorkspacesByProjects({

packages/app/src/components/terminal-pane.tsx

@@ -84,6 +84,7 @@ import {
 } from "./terminal-resize-debouncer";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
+import { useKeyboardFocusSurface } from "@/keyboard";
 import {
   applyTerminalRendererReadyChange,
   resolveTerminalStreamTarget,
@@ -458,6 +459,8 @@ export function TerminalPane({
     }
   }, [isMobile, isPaneFocused, isWorkspaceFocused, requestTerminalFocus, scopeKey, terminalId]);
 
+  useKeyboardFocusSurface("terminal", isTerminalPresented && isPaneFocused && terminalId != null);
+
   useEffect(() => {
     const canRequest = canRequestFocusClaim({
       isWorkspaceFocused: isTerminalPresented,

packages/app/src/components/ui/combobox.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
@@ -62,12 +63,7 @@ import {
 } from "@/components/adaptive-modal-sheet";
 import { FloatingSurface } from "@/components/ui/floating";
 import { useDismissKeyboardOnOpen } from "@/components/ui/keyboard-dismiss";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import { buildDesktopFrameStyle } from "./combobox-frame-style";
 
 export { buildDesktopFrameStyle } from "./combobox-frame-style";
@@ -526,7 +522,6 @@ type DesktopKey = "ArrowDown" | "ArrowUp" | "Enter" | "Escape";
 
 interface DesktopKeyHandlerInput {
   isOpen: boolean;
-  isMobile: boolean;
   orderedVisibleOptions: ComboboxOption[];
   activeIndex: number;
   setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
@@ -871,11 +866,12 @@ function isDesktopKey(key: string): key is DesktopKey {
 function dispatchDesktopKey(
   input: DesktopKeyHandlerInput,
   key: DesktopKey,
-  event?: KeyboardEvent,
+  event?: KeyboardInputEvent,
 ): boolean {
   if (!input.isOpen) return false;
-  if (!IS_WEB && input.isMobile) return false;
-
+  // A native mobile bail used to live here because native had no key source, so
+  // nothing could call this. It has one now, and the sheet highlights an active
+  // row like the popover does, so a hardware keyboard drives both.
   if (key === "ArrowDown" || key === "ArrowUp") {
     event?.preventDefault();
     handleDesktopArrowKey(input, key);
@@ -912,6 +908,7 @@ function resolveInitialActiveIndex(
 }
 
 interface MobileBodyProps {
+  overlayLayer: number;
   isOpen: boolean;
   snapPoints: string[];
   handleIndicatorStyle: { backgroundColor: string };
@@ -990,45 +987,47 @@ function MobileComboboxSheet(props: MobileBodyProps): ReactElement {
       keyboardBlurBehavior="none"
       presentation={props.presentation}
     >
-      <ComboboxSheetFrame footer={props.footer}>
-        {props.header ? (
-          <SheetHeaderView header={props.header} onClose={props.onClose} />
-        ) : (
-          <>
-            <View style={styles.bottomSheetHeader}>
-              <Text key={props.titleColor} style={comboboxTitleStyle}>
-                {props.title}
-              </Text>
-            </View>
-            {props.stickyHeader}
-            {!props.hasChildren && props.searchable ? (
-              <SearchInput
-                placeholder={props.searchPlaceholder}
-                onChangeText={props.setSearchQueryWithCallback}
-                onSubmitEditing={props.handleSubmitSearch}
-                autoFocus={false}
-                useBottomSheetInput
-                resetKey={props.searchResetKey}
-              />
-            ) : null}
-          </>
-        )}
-        {props.hasChildren && !props.mobileChildrenScrollEnabled ? (
-          body
-        ) : (
-          <BottomSheetScrollView
-            style={styles.mobileSheetBody}
-            contentContainerStyle={[
-              styles.comboboxScrollContent,
-              props.mobileChildrenContentContainerStyle,
-            ]}
-            keyboardShouldPersistTaps="handled"
-            showsVerticalScrollIndicator={false}
-          >
-            {body}
-          </BottomSheetScrollView>
-        )}
-      </ComboboxSheetFrame>
+      <OverlayLayerProvider layer={props.overlayLayer}>
+        <ComboboxSheetFrame footer={props.footer}>
+          {props.header ? (
+            <SheetHeaderView header={props.header} onClose={props.onClose} />
+          ) : (
+            <>
+              <View style={styles.bottomSheetHeader}>
+                <Text key={props.titleColor} style={comboboxTitleStyle}>
+                  {props.title}
+                </Text>
+              </View>
+              {props.stickyHeader}
+              {!props.hasChildren && props.searchable ? (
+                <SearchInput
+                  placeholder={props.searchPlaceholder}
+                  onChangeText={props.setSearchQueryWithCallback}
+                  onSubmitEditing={props.handleSubmitSearch}
+                  autoFocus={false}
+                  useBottomSheetInput
+                  resetKey={props.searchResetKey}
+                />
+              ) : null}
+            </>
+          )}
+          {props.hasChildren && !props.mobileChildrenScrollEnabled ? (
+            body
+          ) : (
+            <BottomSheetScrollView
+              style={styles.mobileSheetBody}
+              contentContainerStyle={[
+                styles.comboboxScrollContent,
+                props.mobileChildrenContentContainerStyle,
+              ]}
+              keyboardShouldPersistTaps="handled"
+              showsVerticalScrollIndicator={false}
+            >
+              {body}
+            </BottomSheetScrollView>
+          )}
+        </ComboboxSheetFrame>
+      </OverlayLayerProvider>
     </IsolatedBottomSheetModal>
   );
 }
@@ -1062,7 +1061,8 @@ interface DesktopBodyProps {
   overlayLayer: number;
   isOpen: boolean;
   handleClose: () => void;
-  handleDesktopKey: (key: DesktopKey, event?: KeyboardEvent) => boolean;
+  setOverlayScope: (node: unknown) => void;
+  handleDesktopKey: (key: DesktopKey, event?: KeyboardInputEvent) => boolean;
   refs: ReturnType<typeof useFloating>["refs"];
   shouldUseDesktopFade: boolean;
   desktopFrameStyle: StyleProp<ViewStyle>;
@@ -1189,25 +1189,13 @@ function DesktopComboboxOptionsBody(props: {
 
 function DesktopComboboxBody(props: DesktopBodyProps): ReactElement | null {
   const active = useRetainedPanelActive();
-  const handleDesktopKey = props.handleDesktopKey;
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
-      if (!isDesktopKey(event.key)) return false;
-      return handleDesktopKey(event.key, event);
-    },
-    [handleDesktopKey],
-  );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && props.isOpen,
-    layer: props.overlayLayer,
-    onKeyDown: handleWebOverlayKeyDown,
-  });
+  const setOverlayScope = props.setOverlayScope;
   const setFloatingRef = useCallback(
     (node: View | null) => {
       props.refs.setFloating(node);
-      setWebOverlayScope(node);
+      setOverlayScope(node);
     },
-    [props.refs, setWebOverlayScope],
+    [props.refs, setOverlayScope],
   );
 
   // Remove the portal before a retained chat can freeze its closing update.
@@ -1531,11 +1519,10 @@ export function Combobox({
   );
 
   const handleDesktopKey = useCallback(
-    (key: DesktopKey, event?: KeyboardEvent) => {
+    (key: DesktopKey, event?: KeyboardInputEvent) => {
       return dispatchDesktopKey(
         {
           isOpen,
-          isMobile,
           orderedVisibleOptions,
           activeIndex,
           setActiveIndex,
@@ -1546,7 +1533,7 @@ export function Combobox({
         event,
       );
     },
-    [activeIndex, handleClose, handleSelect, isMobile, isOpen, orderedVisibleOptions],
+    [activeIndex, handleClose, handleSelect, isOpen, orderedVisibleOptions],
   );
 
   useDismissKeyboardOnOpen(isOpen, isMobile);
@@ -1583,12 +1570,20 @@ export function Combobox({
     [],
   );
 
+  const setOverlayScope = useOverlayRegistration({
+    active: isOpen,
+    layer: floatingLayer,
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    onKeyDown: (event) => (isDesktopKey(event.key) ? handleDesktopKey(event.key, event) : false),
+  });
+
   const effectiveSearchPlaceholder = searchPlaceholder ?? resolvedPlaceholder;
   const hasChildren = Boolean(children);
 
   if (isMobile) {
     return (
       <MobileComboboxBody
+        overlayLayer={floatingLayer}
         isOpen={isOpen}
         snapPoints={snapPoints}
         handleIndicatorStyle={handleIndicatorStyle}
@@ -1628,6 +1623,7 @@ export function Combobox({
       isOpen={isOpen}
       handleClose={handleClose}
       handleDesktopKey={handleDesktopKey}
+      setOverlayScope={setOverlayScope}
       refs={refs}
       shouldUseDesktopFade={shouldUseDesktopFade}
       desktopFrameStyle={desktopFrameStyle}

packages/app/src/components/ui/hover-card.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import {
   createContext,
   useCallback,
@@ -14,11 +15,7 @@ import { Dimensions, View, type Role, type StyleProp, type ViewStyle } from "rea
 import { FadeIn, FadeOut } from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 import { Portal } from "@gorhom/portal";
-import {
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import { FloatingSurface } from "@/components/ui/floating";
 import {
   measureFloatingPanelPortalHost,
@@ -127,7 +124,7 @@ function WebHoverCard({
   }, [clearGraceTimer, disabled]);
 
   const keyPressed = useCallback(
-    (event: KeyboardEvent): boolean => {
+    (event: KeyboardInputEvent): boolean => {
       if (!isWeb) return false;
       const trigger = triggerRef.current as unknown as HTMLElement | null;
       if (!trigger) return false;
@@ -139,7 +136,7 @@ function WebHoverCard({
         return true;
       } else if (
         focusInside() &&
-        event.target === trigger &&
+        document.activeElement === trigger &&
         ["ArrowDown", "Enter", " "].includes(event.key)
       ) {
         event.preventDefault();
@@ -158,7 +155,8 @@ function WebHoverCard({
     [clearGraceTimer, focusInside, open, openNow],
   );
 
-  const setOverlayScope = useWebOverlayRegistration({
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
     active: !disabled && open,
     layer,
     onKeyDown: keyPressed,

packages/app/src/components/ui/menu/keyboard-navigation.ts

@@ -0,0 +1,4 @@
+import type { KeyboardInputEvent } from "@/keyboard";
+export function navigateMenuKeyboard(_event: KeyboardInputEvent): boolean {
+  return false;
+}

packages/app/src/components/ui/menu/keyboard-navigation.web.ts

@@ -0,0 +1,37 @@
+import type { KeyboardInputEvent } from "@/keyboard";
+export function navigateMenuKeyboard(event: KeyboardInputEvent): boolean {
+  const target = document.activeElement;
+  const surface = target?.closest<HTMLElement>('[data-menu-surface="true"]');
+  if (!surface) return false;
+  const items = Array.from(
+    surface.querySelectorAll<HTMLElement>(
+      '[data-menu-item="true"]:not([data-menu-disabled="true"])',
+    ),
+  );
+  if (items.length === 0) return false;
+  const currentIndex = items.findIndex((item) => item === document.activeElement);
+  let nextIndex: number | null = null;
+  if (event.key === "ArrowDown") {
+    if (currentIndex < 0) nextIndex = 0;
+    else nextIndex = (currentIndex + 1) % items.length;
+  }
+  if (event.key === "ArrowUp") {
+    if (currentIndex < 0) nextIndex = items.length - 1;
+    else nextIndex = (currentIndex - 1 + items.length) % items.length;
+  }
+  if (event.key === "Home") nextIndex = 0;
+  if (event.key === "End") nextIndex = items.length - 1;
+  if (nextIndex !== null) {
+    event.preventDefault();
+    event.stopPropagation();
+    items[nextIndex]?.focus();
+    return true;
+  }
+  if ((event.key === "Enter" || event.key === " ") && currentIndex >= 0) {
+    event.preventDefault();
+    event.stopPropagation();
+    items[currentIndex]?.click();
+    return true;
+  }
+  return false;
+}

packages/app/src/components/ui/menu/menu-overlay.tsx

@@ -1,3 +1,5 @@
+import { navigateMenuKeyboard } from "./keyboard-navigation";
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
@@ -24,12 +26,7 @@ import { StyleSheet } from "react-native-unistyles";
 import { FloatingScrollView, FloatingSurface } from "@/components/ui/floating";
 import { isWeb } from "@/constants/platform";
 import type { KeyboardFocusScope } from "@/keyboard/actions";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import {
   computePosition,
   getTransformOrigin,
@@ -405,8 +402,8 @@ export function MenuOverlay({
 }): ReactElement | null {
   const floatingLayer = useOverlayLayer("floating");
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key === "Escape") {
         event.preventDefault();
         event.stopPropagation();
@@ -414,44 +411,15 @@ export function MenuOverlay({
         return true;
       }
 
-      const target = event.target instanceof Element ? event.target : null;
-      const surface = target?.closest<HTMLElement>('[data-menu-surface="true"]');
-      if (!surface) return false;
-      const items = Array.from(
-        surface.querySelectorAll<HTMLElement>(
-          '[data-menu-item="true"]:not([data-menu-disabled="true"])',
-        ),
-      );
-      if (items.length === 0) return false;
-      const currentIndex = items.findIndex((item) => item === document.activeElement);
-      let nextIndex: number | null = null;
-      if (event.key === "ArrowDown")
-        nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % items.length;
-      if (event.key === "ArrowUp")
-        nextIndex =
-          currentIndex < 0 ? items.length - 1 : (currentIndex - 1 + items.length) % items.length;
-      if (event.key === "Home") nextIndex = 0;
-      if (event.key === "End") nextIndex = items.length - 1;
-      if (nextIndex !== null) {
-        event.preventDefault();
-        event.stopPropagation();
-        items[nextIndex]?.focus();
-        return true;
-      }
-      if ((event.key === "Enter" || event.key === " ") && currentIndex >= 0) {
-        event.preventDefault();
-        event.stopPropagation();
-        items[currentIndex]?.click();
-        return true;
-      }
-      return false;
+      return navigateMenuKeyboard(event);
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && visible,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: visible,
     layer: floatingLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
     restoreFocusRef,
   });
 
@@ -463,7 +431,7 @@ export function MenuOverlay({
         {...{
           onContextMenu: (event: { preventDefault?: () => void }) => event.preventDefault?.(),
         }}
-        ref={setWebOverlayScope}
+        ref={setOverlayScope}
         collapsable={false}
         style={[
           styles.overlay,

packages/app/src/components/ui/shortcut.tsx

@@ -1,7 +1,7 @@
 import React, { useMemo, type ReactElement } from "react";
 import { Text, View, type StyleProp, type TextStyle, type ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { normalizeDisplayChord } from "@/components/ui/normalize-display-chord";
 import { formatShortcut, type ShortcutKey } from "@/utils/format-shortcut";
 import { getShortcutOs } from "@/utils/shortcut-platform";
@@ -17,7 +17,7 @@ export function Shortcut({
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
 }): ReactElement | null {
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const displayChord = normalizeDisplayChord(chord, keys);
   const shortcutOs = getShortcutOs();
 

packages/app/src/components/workspace-shortcut-targets-subscriber.test.tsx

@@ -125,6 +125,20 @@ describe("WorkspaceShortcutTargetsSubscriber", () => {
     });
   });
 
+  it("keeps keyboard navigation populated when the sidebar starts hidden", async () => {
+    await act(async () => {
+      root?.render(
+        <SidebarModelProvider active={false} keyboardNavigationActive>
+          <WorkspaceShortcutTargetsSubscriber enabled />
+        </SidebarModelProvider>,
+      );
+    });
+    expect(useKeyboardShortcutsStore.getState().sidebarShortcutWorkspaceTargets).toEqual([
+      { serverId: "srv", workspaceId: "ws-1" },
+      { serverId: "srv", workspaceId: "ws-2" },
+    ]);
+  });
+
   it("publishes workspace shortcut targets without rendering the sidebar", async () => {
     await act(async () => {
       root?.render(

packages/app/src/composer/input/fullscreen-exit.browser.test.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { dispatchTopOverlayKeyDown } from "@/keyboard";
+import { useComposerFullscreenExit } from "./fullscreen-exit";
+
+it("the native entry claims Escape until fullscreen closes", () => {
+  let exits = 0;
+  function Harness({ active }: { active: boolean }) {
+    useComposerFullscreenExit(active, () => exits++);
+    return null;
+  }
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    flushSync(() => root.render(<Harness active />));
+    expect(dispatchTopOverlayKeyDown(new KeyboardEvent("keydown", { key: "Escape" }))).toBe(true);
+    expect(exits).toBe(1);
+    flushSync(() => root.render(<Harness active={false} />));
+    expect(dispatchTopOverlayKeyDown(new KeyboardEvent("keydown", { key: "Escape" }))).toBe(false);
+    expect(exits).toBe(1);
+  } finally {
+    root.unmount();
+    container.remove();
+  }
+});

packages/app/src/composer/input/fullscreen-exit.ts

@@ -1,4 +1,6 @@
-import { useOverlayLayer, useWebOverlayRegistration } from "@/lib/overlay-root";
+import { useComposerHardwareBackExit } from "./hardware-back-exit";
+import { useOverlayRegistration } from "@/keyboard";
+import { useOverlayLayer } from "@/lib/overlay-root";
 
 /**
  * Escape leaves fullscreen before app shortcuts see it. The registration only claims
@@ -8,8 +10,10 @@ export function useComposerFullscreenExit(
   active: boolean,
   onExit: () => void,
 ): ((node: unknown) => void) | undefined {
+  useComposerHardwareBackExit(active, onExit);
   const layer = useOverlayLayer("modal");
-  return useWebOverlayRegistration({
+  return useOverlayRegistration({
+    keys: ["Escape"],
     active,
     layer,
     manageFocus: false,

packages/app/src/composer/input/hardware-back-exit.android.ts

@@ -2,10 +2,7 @@ import { useEffect } from "react";
 import { BackHandler } from "react-native";
 
 /** The hardware back button leaves fullscreen instead of the screen. */
-export function useComposerFullscreenExit(
-  active: boolean,
-  onExit: () => void,
-): ((node: unknown) => void) | undefined {
+export function useComposerHardwareBackExit(active: boolean, onExit: () => void): void {
   useEffect(() => {
     if (!active) return;
     const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
@@ -14,5 +11,4 @@ export function useComposerFullscreenExit(
     });
     return () => subscription.remove();
   }, [active, onExit]);
-  return undefined;
 }

packages/app/src/composer/input/hardware-back-exit.ts

@@ -0,0 +1 @@
+export function useComposerHardwareBackExit(_active: boolean, _onExit: () => void): void {}

packages/app/src/composer/input/input.tsx

@@ -1,3 +1,4 @@
+import { useKeyboardFocusSurface } from "@/keyboard";
 import type { SendShortcut } from "@/hooks/use-settings";
 import {
   useComposerEditingSession,
@@ -1288,6 +1289,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     const dictationToggleKeys = useShortcutKeys("dictation-toggle");
     const focusInputKeys = useShortcutKeys("focus-message-input");
     const [isInputFocused, setIsInputFocused] = useState(false);
+    useKeyboardFocusSurface("message-input", isInputFocused && isPaneFocused);
     // Web text is DOM-owned between deferred draft publications. The action button only needs
     // this boundary, so publish empty/non-empty transitions without rerendering for every key.
     const initialHasLiveText = value.trim().length > 0;

packages/app/src/composer/tracks.tsx

@@ -29,8 +29,9 @@ import { COMPOSER_PILL_CLEARANCE, composerPillStyles } from "./pill-styles";
  * on every platform.
  *
  * The bar floats over the transcript with no background, so content remains visible underneath.
- * Its host gives the scroll viewport a small bottom inset only when the bar exists; that keeps
- * the final footer clear without turning the overlay into a layout band.
+ * Its host gives the scroll viewport a small bottom inset for as long as the bar is mounted, with
+ * or without pills: that keeps the final footer clear, and pills that come and go every turn do not
+ * move the transcript.
  */
 export function ComposerTrackBar({ children }: { children: ReactNode }): ReactElement {
   return (

packages/app/src/desktop/host.ts

@@ -1,6 +1,6 @@
 import { Platform } from "react-native";
 import { getElectronHost } from "@/desktop/electron/host";
-import type { BrowserKeyboardPolicy } from "@/desktop/browser/shortcuts";
+import type { BrowserKeyboardPolicy } from "@/keyboard";
 import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
 
 type BrowserAutomationExecuteRequest = Extract<

packages/app/src/file-panels/source/find/index.web.tsx

@@ -12,7 +12,7 @@ import { StyleSheet } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
 import { PaneFind, findShortcutPlatform, isFindShortcut, type PaneFindHandle } from "@/pane-find";
 import { usePaneFocus } from "@/panels/pane-context";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
+import { hasActiveOverlay } from "@/keyboard";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
 import { FileFindModel } from "./model.web";
@@ -39,7 +39,7 @@ export function FileFind({
   useEffect(() => {
     if (!isInteractive || !active) return;
     function onKeyDown(event: KeyboardEvent) {
-      if (event.defaultPrevented || hasActiveWebOverlay() || isImeComposingKeyboardEvent(event))
+      if (event.defaultPrevented || hasActiveOverlay() || isImeComposingKeyboardEvent(event))
         return;
       if (isFindShortcut(event, findShortcutPlatform())) {
         event.preventDefault();

packages/app/src/git/client-forge-module.ts

@@ -41,8 +41,15 @@ export interface ForgeReferencePath {
   kind: "change_request" | "issue";
   /** Path between the repository path and the numeric local id. */
   infix: string;
+  /**
+   * Shorthand marker the forge links in prose, e.g. GitHub `#12`, GitLab `!12`.
+   * Absent when the forge has no shorthand for this kind.
+   */
+  sigil?: ForgeReferenceSigil;
 }
 
+export type ForgeReferenceSigil = "#" | "!";
+
 /** Line/range anchor shared by every GitHub-family forge (github, gitea, forgejo, codeberg). */
 export function GITHUB_LINE_ANCHOR(start: number, end?: number): string {
   return end && end > start ? `#L${start}-L${end}` : `#L${start}`;
@@ -54,8 +61,8 @@ export const GITEA_FAMILY_URL_GRAMMAR: ForgeUrlGrammar = {
   blobInfix: "/src/branch/",
   lineAnchor: GITHUB_LINE_ANCHOR,
   referencePaths: [
-    { kind: "change_request", infix: "/pulls/" },
-    { kind: "issue", infix: "/issues/" },
+    { kind: "change_request", infix: "/pulls/", sigil: "!" },
+    { kind: "issue", infix: "/issues/", sigil: "#" },
   ],
 };
 

packages/app/src/git/forge-shorthand/index.tsx

@@ -0,0 +1,35 @@
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { createForgeShorthand, type ForgeShorthand } from "./shorthand";
+
+export { createForgeShorthand, type ForgeShorthand } from "./shorthand";
+
+const ForgeShorthandContext = createContext<ForgeShorthand | null>(null);
+
+/** Makes `#12`-style references in descendant Markdown open on the workspace forge. */
+export function ForgeShorthandProvider({
+  forge,
+  remoteUrl,
+  children,
+}: {
+  forge: string | null | undefined;
+  remoteUrl: string | null | undefined;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => createForgeShorthand({ forge, remoteUrl }), [forge, remoteUrl]);
+  return <ForgeShorthandContext.Provider value={value}>{children}</ForgeShorthandContext.Provider>;
+}
+
+export function useForgeShorthand(): ForgeShorthand | null {
+  return useContext(ForgeShorthandContext);
+}
+
+/** Carries the shorthand environment across a portal. */
+export function useForgeShorthandBridge() {
+  const value = useContext(ForgeShorthandContext);
+  return useCallback(
+    (children: ReactNode) => (
+      <ForgeShorthandContext.Provider value={value}>{children}</ForgeShorthandContext.Provider>
+    ),
+    [value],
+  );
+}

packages/app/src/git/forge-shorthand/shorthand.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createForgeShorthand } from "./shorthand";
+
+function matches(shorthand: { pattern: string }, text: string): string[] {
+  return [...text.matchAll(new RegExp(shorthand.pattern, "g"))].map((match) => match[0]);
+}
+
+describe("createForgeShorthand", () => {
+  const github = createForgeShorthand({
+    forge: "github",
+    remoteUrl: "git@github.com:getpaseo/paseo.git",
+  })!;
+  const gitlab = createForgeShorthand({
+    forge: "gitlab",
+    remoteUrl: "https://gitlab.com/g/p.git",
+  })!;
+
+  it("resolves same-repo and cross-repo references on the remote's host", () => {
+    expect(github.resolve("#8613")).toBe("https://github.com/getpaseo/paseo/issues/8613");
+    expect(github.resolve("acme/tools#4")).toBe("https://github.com/acme/tools/issues/4");
+    expect(gitlab.resolve("!7")).toBe("https://gitlab.com/g/p/-/merge_requests/7");
+    expect(gitlab.resolve("g/sub/q#3")).toBe("https://gitlab.com/g/sub/q/-/issues/3");
+  });
+
+  it("only recognizes the sigils the forge declares", () => {
+    expect(matches(github, "see #1 and !2")).toEqual(["#1"]);
+    expect(github.resolve("!2")).toBeNull();
+    expect(matches(gitlab, "see #1 and !2")).toEqual(["#1", "!2"]);
+  });
+
+  it("recognizes references only at word boundaries", () => {
+    expect(
+      matches(
+        github,
+        "(#1), #2. acme/tools#3, foo#4 #5abc  https://x/#7 #0 #08 wow!9 user@host#10",
+      ),
+    ).toEqual(["#1", "#2", "acme/tools#3"]);
+  });
+
+  it("falls back to the cloud host forge when the daemon reports none", () => {
+    expect(
+      createForgeShorthand({ forge: undefined, remoteUrl: "git@github.com:a/b.git" })?.resolve(
+        "#1",
+      ),
+    ).toBe("https://github.com/a/b/issues/1");
+  });
+
+  it("is absent without a remote or a known forge", () => {
+    expect(createForgeShorthand({ forge: "github", remoteUrl: null })).toBeNull();
+    expect(
+      createForgeShorthand({ forge: undefined, remoteUrl: "git@git.corp:a/b.git" }),
+    ).toBeNull();
+  });
+});

packages/app/src/git/forge-shorthand/shorthand.ts

@@ -0,0 +1,55 @@
+import type { ForgeReferenceSigil } from "@/git/client-forge-module";
+import { forgeFromRemoteUrl } from "@/git/forge";
+import { getClientForgeLogicModule } from "@/git/forges";
+import { buildForgeReferenceUrl } from "@/git/forge-url";
+
+/**
+ * Shorthand references in prose, such as `#12`, `!12` or `owner/repo#12`,
+ * resolved against one workspace remote.
+ */
+export interface ForgeShorthand {
+  /** Regex source for recognizing references in Markdown text. */
+  pattern: string;
+  /** Web URL for a recognized reference, or null. */
+  resolve(text: string): string | null;
+}
+
+// Keep these in the syntax shared by JavaScript, ICU and java.util.regex: the
+// pattern runs in the native Markdown engines too.
+const REPO = String.raw`[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)+`;
+const NUMBER = String.raw`[1-9][0-9]{0,8}`;
+// A reference never continues a word, path, URL fragment or entity.
+const BEFORE = String.raw`(?<![A-Za-z0-9_./@#!&-])`;
+const AFTER = String.raw`(?![A-Za-z0-9_])`;
+const REFERENCE = new RegExp(String.raw`^(?:(${REPO}))?([#!])(${NUMBER})$`);
+
+export function createForgeShorthand(input: {
+  forge: string | null | undefined;
+  remoteUrl: string | null | undefined;
+}): ForgeShorthand | null {
+  const remoteUrl = input.remoteUrl;
+  const forge = input.forge || forgeFromRemoteUrl(remoteUrl);
+  if (!forge || !remoteUrl) return null;
+  const sigils = forgeSigils(forge).filter(
+    (sigil) => buildForgeReferenceUrl(forge, { remoteUrl, sigil, number: 1 }) !== null,
+  );
+  if (sigils.length === 0) return null;
+  return {
+    pattern: `${BEFORE}(?:${REPO})?[${sigils.join("")}]${NUMBER}${AFTER}`,
+    resolve(text) {
+      const match = REFERENCE.exec(text);
+      if (!match) return null;
+      return buildForgeReferenceUrl(forge, {
+        remoteUrl,
+        repo: match[1] ?? null,
+        sigil: match[2] as ForgeReferenceSigil,
+        number: Number(match[3]),
+      });
+    },
+  };
+}
+
+function forgeSigils(forge: string): ForgeReferenceSigil[] {
+  const paths = getClientForgeLogicModule(forge)?.urlGrammar?.referencePaths ?? [];
+  return paths.flatMap((path) => (path.sigil ? [path.sigil] : []));
+}

packages/app/src/git/forge-url.test.ts

@@ -3,9 +3,77 @@ import {
   buildForgeBlobUrl,
   buildForgeBranchTreeUrl,
   buildForgeChecksUrl,
+  buildForgeReferenceUrl,
   hasForgeWebUrls,
 } from "./forge-url";
 
+describe("buildForgeReferenceUrl", () => {
+  it.each([
+    ["github", "git@github.com:acme/repo.git", "#", null, "https://github.com/acme/repo/issues/12"],
+    ["github", "git@github.com:acme/repo.git", "!", null, null],
+    [
+      "github",
+      "https://github.com/acme/repo",
+      "#",
+      "other/tools",
+      "https://github.com/other/tools/issues/12",
+    ],
+    ["gitlab", "git@gitlab.com:g/sub/p.git", "#", null, "https://gitlab.com/g/sub/p/-/issues/12"],
+    [
+      "gitlab",
+      "git@gitlab.com:g/sub/p.git",
+      "!",
+      null,
+      "https://gitlab.com/g/sub/p/-/merge_requests/12",
+    ],
+    [
+      "gitlab",
+      "https://gitlab.corp:8443/g/p.git",
+      "!",
+      "g/q",
+      "https://gitlab.corp:8443/g/q/-/merge_requests/12",
+    ],
+    [
+      "codeberg",
+      "https://codeberg.org/acme/repo.git",
+      "!",
+      null,
+      "https://codeberg.org/acme/repo/pulls/12",
+    ],
+    [
+      "gitea",
+      "http://forge.test:3000/team/repo.git",
+      "#",
+      null,
+      "http://forge.test:3000/team/repo/issues/12",
+    ],
+    [
+      "github",
+      "http://github.com/acme/repo.git",
+      "#",
+      null,
+      "https://github.com/acme/repo/issues/12",
+    ],
+    [
+      "forgejo",
+      "git@forge.example:acme/repo.git",
+      "#",
+      null,
+      "https://forge.example/acme/repo/issues/12",
+    ],
+    ["bitbucket", "git@bitbucket.org:acme/repo.git", "#", null, null],
+    ["github", null, "#", null, null],
+    ["github", "git@github.com:acme/repo.git", "#", "../escape", null],
+  ] as const)("builds %s %s %s in %s", (forge, remoteUrl, sigil, repo, expected) => {
+    expect(buildForgeReferenceUrl(forge, { remoteUrl, repo, sigil, number: 12 })).toBe(expected);
+  });
+
+  it("rejects non-positive numbers", () => {
+    const remoteUrl = "git@github.com:acme/repo.git";
+    expect(buildForgeReferenceUrl("github", { remoteUrl, sigil: "#", number: 0 })).toBeNull();
+  });
+});
+
 describe("buildForgeChecksUrl", () => {
   it.each([
     [

packages/app/src/git/forge-url.ts

@@ -12,6 +12,7 @@
  */
 import { getForgeDefinition } from "@getpaseo/protocol/forge-manifest";
 import { normalizeHost, parseGitRemoteLocation } from "@getpaseo/protocol/git-remote";
+import type { ForgeReferenceSigil } from "@/git/client-forge-module";
 import { getClientForgeLogicModule } from "@/git/forges";
 
 export interface ForgeBlobUrlInput {
@@ -27,6 +28,14 @@ export interface ForgeBranchTreeUrlInput {
   branch: string | null | undefined;
 }
 
+export interface ForgeReferenceUrlInput {
+  remoteUrl: string | null | undefined;
+  /** Repository path of a cross-repository reference; the remote's repository when absent. */
+  repo?: string | null;
+  sigil: ForgeReferenceSigil;
+  number: number;
+}
+
 export function buildForgeChecksUrl(forge: string, changeRequestUrl: string): string | null {
   const suffix = getClientForgeLogicModule(forge)?.urlGrammar?.changeRequestChecksSuffix;
   if (!suffix) {
@@ -45,6 +54,8 @@ export function buildForgeChecksUrl(forge: string, changeRequestUrl: string): st
 }
 
 interface ForgeWebLocation {
+  /** "http" only for a self-hosted http:// remote; every other remote browses over https. */
+  scheme: "http" | "https";
   host: string;
   /** Non-default port for a self-hosted http(s) origin, or undefined. */
   port?: string;
@@ -87,16 +98,18 @@ function resolveForgeWebLocation(
     !isCloudHost && (location.transport === "http" || location.transport === "https")
       ? location.port
       : undefined;
-  return { host: webHost, port, repo: location.path };
+  const scheme = !isCloudHost && location.transport === "http" ? "http" : "https";
+  return { scheme, host: webHost, port, repo: location.path };
 }
 
 function encodeBranch(branch: string): string {
   return branch.split("/").map(encodeURIComponent).join("/");
 }
 
-/** Host, plus `:port` when the remote pins a non-default port. */
-function forgeAuthority(location: ForgeWebLocation): string {
-  return location.port ? `${location.host}:${location.port}` : location.host;
+/** Scheme and host, plus `:port` when the remote pins a non-default port. */
+function forgeOrigin(location: ForgeWebLocation): string {
+  const authority = location.port ? `${location.host}:${location.port}` : location.host;
+  return `${location.scheme}://${authority}`;
 }
 
 function normalizeBlobPath(path: string | null | undefined): string | null {
@@ -131,7 +144,7 @@ export function buildForgeBranchTreeUrl(
   if (!grammar || !location || !branch || branch === "HEAD") {
     return null;
   }
-  return `https://${forgeAuthority(location)}/${location.repo}${grammar.treeInfix}${encodeBranch(branch)}`;
+  return `${forgeOrigin(location)}/${location.repo}${grammar.treeInfix}${encodeBranch(branch)}`;
 }
 
 export function buildForgeBlobUrl(forge: string, input: ForgeBlobUrlInput): string | null {
@@ -143,13 +156,40 @@ export function buildForgeBlobUrl(forge: string, input: ForgeBlobUrlInput): stri
     return null;
   }
   const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
-  let url = `https://${forgeAuthority(location)}/${location.repo}${grammar.blobInfix}${encodeBranch(branch)}/${encodedPath}`;
+  let url = `${forgeOrigin(location)}/${location.repo}${grammar.blobInfix}${encodeBranch(branch)}/${encodedPath}`;
   if (input.lineStart && input.lineStart > 0) {
     url += grammar.lineAnchor(input.lineStart, input.lineEnd);
   }
   return url;
 }
 
+/**
+ * Web URL of a shorthand reference such as `#12` or `group/project!12`. A
+ * cross-repository reference stays on the remote's host. Null when the forge
+ * has no shorthand for the sigil.
+ */
+export function buildForgeReferenceUrl(
+  forge: string,
+  input: ForgeReferenceUrlInput,
+): string | null {
+  const referencePath = getClientForgeLogicModule(forge)?.urlGrammar?.referencePaths?.find(
+    (path) => path.sigil === input.sigil,
+  );
+  const location = resolveForgeWebLocation(forge, input.remoteUrl);
+  const repo = input.repo ?? location?.repo;
+  if (
+    !referencePath ||
+    !location ||
+    !repo ||
+    !isValidRepoPath(repo) ||
+    !Number.isSafeInteger(input.number) ||
+    input.number <= 0
+  ) {
+    return null;
+  }
+  return `${forgeOrigin(location)}/${repo}${referencePath.infix}${input.number}`;
+}
+
 /** Whether the forge has web URL builders (i.e. a known URL grammar). */
 export function hasForgeWebUrls(forge: string): boolean {
   return getClientForgeLogicModule(forge)?.urlGrammar !== undefined;

packages/app/src/git/forges/github.ts

@@ -89,7 +89,8 @@ export const githubForgeLogic = {
     changeRequestChecksSuffix: "/checks",
     referencePaths: [
       { kind: "change_request", infix: "/pull/" },
-      { kind: "issue", infix: "/issues/" },
+      // GitHub redirects /issues/N to /pull/N, so `#N` covers both kinds.
+      { kind: "issue", infix: "/issues/", sigil: "#" },
     ],
   },
   facts: defineForgeFacts({

packages/app/src/git/forges/gitlab.ts

@@ -166,8 +166,8 @@ export const gitlabForgeLogic = {
     lineAnchor: gitlabLineAnchor,
     changeRequestChecksSuffix: "/pipelines",
     referencePaths: [
-      { kind: "change_request", infix: "/-/merge_requests/" },
-      { kind: "issue", infix: "/-/issues/" },
+      { kind: "change_request", infix: "/-/merge_requests/", sigil: "!" },
+      { kind: "issue", infix: "/-/issues/", sigil: "#" },
     ],
   },
   facts: defineForgeFacts({

packages/app/src/hooks/use-aggregated-agents.ts

@@ -76,7 +76,7 @@ export function useAggregatedAgents(options?: {
       }
       const serverLabel = serverLabelById.get(serverId) ?? serverId;
       for (const agent of agents.values()) {
-        if (!includeArchived && agent.archivedAt) {
+        if (agent.background || (!includeArchived && agent.archivedAt)) {
           continue;
         }
         const nextAgent: AggregatedAgent = {

packages/app/src/hooks/use-keyboard-shortcuts.ts

@@ -1,432 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
-import { usePathname, useRouter } from "expo-router";
-import { getIsElectronRuntime } from "@/constants/layout";
-import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
-import { setCommandCenterFocusRestoreElement } from "@/utils/command-center-focus-restore";
-import { getResidentBrowserWebview } from "@/desktop/browser/resident-webviews";
-import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
-import { useKeyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher-context";
-import {
-  type ChordState,
-  type KeyboardShortcutInput,
-  resolveKeyboardShortcut,
-  buildEffectiveBindings,
-  getWorkspaceIndexJumpModifierKey,
-} from "@/keyboard/keyboard-shortcuts";
-import { resolveKeyboardFocusScope } from "@/keyboard/focus-scope";
-import {
-  buildBrowserKeyboardPolicy,
-  parseBrowserShortcutInput,
-  shouldPublishBrowserShortcutPolicy,
-} from "@/desktop/browser/shortcuts";
-import type { KeyboardFocusScope, KeyboardShortcutPayload } from "@/keyboard/actions";
-import {
-  routeKeyboardShortcut,
-  type ShortcutAction,
-  type ShortcutCallbackName,
-} from "@/keyboard/route-shortcut";
-import { getShortcutOs } from "@/utils/shortcut-platform";
-import { useOpenAddProject } from "@/hooks/use-open-add-project";
-import { useStableEvent } from "@/hooks/use-stable-event";
-import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
-import { isNative } from "@/constants/platform";
-import { keyboardShortcutsAvailable } from "@/keyboard/availability";
-import { getDesktopHost, isElectronRuntime } from "@/desktop/host";
-import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
-import { buildOpenProjectRoute } from "@/utils/host-routes";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
-import {
-  type ActiveWorkspaceSelection,
-  navigateToLastWorkspace,
-  useActiveWorkspaceSelection,
-} from "@/stores/navigation-active-workspace-store";
-import { dispatchTopWebOverlayKeyDown, keyBelongsToDomPopover } from "@/lib/overlay-root";
-
-export function useKeyboardShortcuts({
-  enabled,
-  isMobile,
-  isWorkspaceFocusModeEnabled,
-  toggleAgentList,
-  toggleBothSidebars,
-  exitFocusMode,
-  cycleTheme,
-}: {
-  enabled: boolean;
-  isMobile: boolean;
-  isWorkspaceFocusModeEnabled: boolean;
-  toggleAgentList: () => void;
-  toggleBothSidebars?: () => void;
-  exitFocusMode: () => void;
-  cycleTheme?: () => void;
-}) {
-  const keyboardActionDispatcher = useKeyboardActionDispatcher();
-  const pathname = usePathname();
-  const router = useRouter();
-  const resetModifiers = useKeyboardShortcutsStore((s) => s.resetModifiers);
-  const { overrides } = useKeyboardShortcutOverrides();
-  const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
-  const shortcutsAvailable = keyboardShortcutsAvailable({ isNative, isCompact: isMobile });
-  const isDesktopApp = getIsElectronRuntime();
-  const isMac = getShortcutOs() === "mac";
-  const chordStateRef = useRef<ChordState>({
-    candidateIndices: [],
-    step: 0,
-    timeoutId: null,
-  });
-  const openProjectPickerAction = useOpenAddProject();
-  const activeWorkspaceSelection = useActiveWorkspaceSelection();
-  const keyboardWorkspaceSelectionRef = useRef<ActiveWorkspaceSelection | null>(null);
-
-  const publishBrowserShortcutPolicy = useCallback(
-    (chordState?: ChordState) => {
-      const policy =
-        enabled && shortcutsAvailable
-          ? buildBrowserKeyboardPolicy({
-              bindings,
-              chordState,
-              isMac,
-              isDesktop: isDesktopApp,
-            })
-          : { menuPrefixes: [], prefixes: [] };
-      void getDesktopHost()?.browser?.setShortcutPolicy?.(policy);
-    },
-    [bindings, enabled, isDesktopApp, isMac, shortcutsAvailable],
-  );
-
-  useEffect(() => {
-    if (activeWorkspaceSelection) {
-      keyboardWorkspaceSelectionRef.current = activeWorkspaceSelection;
-    }
-  }, [activeWorkspaceSelection]);
-
-  useEffect(() => {
-    if (!isDesktopApp) {
-      return;
-    }
-
-    publishBrowserShortcutPolicy();
-  }, [isDesktopApp, publishBrowserShortcutPolicy]);
-
-  // Only the modifier that actually performs the workspace-index jump on this
-  // runtime should reveal the sidebar number badges (Alt on web, Cmd on
-  // desktop Mac, Ctrl on desktop non-Mac). The store ORs altDown/cmdOrCtrlDown
-  // to drive badge visibility, so we set the flag matching this runtime.
-  // Derived from the effective bindings: `null` when the user unassigned or
-  // rebound the jump shortcut, and no `event.key` ever equals null, so the
-  // badges simply never appear.
-  const badgeModifierKey = getWorkspaceIndexJumpModifierKey(
-    { isMac, isDesktop: isDesktopApp },
-    bindings,
-  );
-
-  // The keyup listener matches the released key against the current modifier,
-  // so a modifier held while the jump binding changes could never be released
-  // and the badges would stay up until a blur. Clear them when it changes.
-  useEffect(() => {
-    resetModifiers();
-  }, [badgeModifierKey, resetModifiers]);
-
-  const setBadgeModifierDown = (down: boolean) => {
-    const state = useKeyboardShortcutsStore.getState();
-    if (isDesktopApp) {
-      state.setCmdOrCtrlDown(down);
-    } else {
-      state.setAltDown(down);
-    }
-  };
-
-  const shouldHandle = () => {
-    if (typeof document === "undefined") return false;
-    if (document.visibilityState !== "visible") return false;
-    return true;
-  };
-
-  const captureCommandCenterFocusRestore = (event: KeyboardEvent) => {
-    const target = event.target instanceof Element ? event.target : null;
-    const targetEl =
-      target?.closest?.("textarea, input, [contenteditable='true']") ??
-      (target instanceof HTMLElement ? target : null);
-    const active = document.activeElement;
-    const activeEl = active instanceof HTMLElement ? active : null;
-    setCommandCenterFocusRestoreElement((targetEl as HTMLElement | null) ?? activeEl ?? null);
-  };
-
-  const callbacksByName: Record<ShortcutCallbackName, (() => void) | undefined> = {
-    "toggle-agent-list": toggleAgentList,
-    "toggle-both-sidebars": toggleBothSidebars,
-    "cycle-theme": cycleTheme,
-  };
-
-  const performShortcutAction = (
-    action: ShortcutAction,
-    event: KeyboardEvent | null,
-    browserFocusRestoreElement: HTMLElement | null = null,
-  ): boolean => {
-    switch (action.kind) {
-      case "none":
-        return false;
-      case "dispatch":
-        return keyboardActionDispatcher.dispatch(action.action);
-      case "navigate-workspace":
-        keyboardWorkspaceSelectionRef.current = {
-          serverId: action.serverId,
-          workspaceId: action.workspaceId,
-        };
-        navigateToWorkspace({ serverId: action.serverId, workspaceId: action.workspaceId });
-        return true;
-      case "navigate-last-workspace":
-        if (navigateToLastWorkspace()) {
-          return true;
-        }
-        router.replace(buildOpenProjectRoute());
-        return true;
-      case "router-replace":
-        router.replace(action.route as Parameters<typeof router.replace>[0]);
-        return true;
-      case "router-back":
-        router.back();
-        return true;
-      case "router-push":
-        router.push(action.route as Parameters<typeof router.push>[0]);
-        return true;
-      case "open-project-picker":
-        void openProjectPickerAction();
-        return true;
-      case "callback":
-        callbacksByName[action.name]?.();
-        return true;
-      case "command-center-toggle": {
-        if (action.nextOpen) {
-          if (event) {
-            captureCommandCenterFocusRestore(event);
-          } else {
-            setCommandCenterFocusRestoreElement(browserFocusRestoreElement);
-          }
-        }
-        useKeyboardShortcutsStore
-          .getState()
-          .setCommandCenterOpen(action.nextOpen, action.scope ?? null);
-        return true;
-      }
-      case "shortcuts-dialog-toggle":
-        useKeyboardShortcutsStore.getState().setShortcutsDialogOpen(action.nextOpen);
-        return true;
-    }
-  };
-
-  const routeAndPerformShortcut = (input: {
-    action: string;
-    payload: KeyboardShortcutPayload;
-    domEvent: KeyboardEvent | null;
-    browserFocusRestoreElement?: HTMLElement | null;
-  }): boolean => {
-    const store = useKeyboardShortcutsStore.getState();
-    const shortcutAction = routeKeyboardShortcut(
-      { action: input.action, payload: input.payload },
-      {
-        pathname,
-        isMobile,
-        sidebarShortcutTargets: store.sidebarShortcutWorkspaceTargets,
-        navigationActiveWorkspace:
-          keyboardWorkspaceSelectionRef.current ?? activeWorkspaceSelection,
-        commandCenterOpen: store.commandCenterOpen,
-        shortcutsDialogOpen: store.shortcutsDialogOpen,
-      },
-    );
-    const handled = performShortcutAction(
-      shortcutAction,
-      input.domEvent,
-      input.browserFocusRestoreElement,
-    );
-    if (handled && isWorkspaceFocusModeEnabled && input.action.startsWith("sidebar.")) {
-      exitFocusMode();
-    }
-    return handled;
-  };
-
-  const resolveAndPerformShortcut = (input: {
-    event: KeyboardShortcutInput;
-    focusScope: KeyboardFocusScope;
-    domEvent: KeyboardEvent | null;
-    browserFocusRestoreElement?: HTMLElement | null;
-  }) => {
-    const store = useKeyboardShortcutsStore.getState();
-    const previousChordState = chordStateRef.current;
-    const result = resolveKeyboardShortcut({
-      event: input.event,
-      context: {
-        isMac,
-        isDesktop: isDesktopApp,
-        focusScope: input.focusScope,
-        commandCenterOpen: store.commandCenterOpen,
-      },
-      chordState: chordStateRef.current,
-      onChordReset: () => {
-        chordStateRef.current = {
-          candidateIndices: [],
-          step: 0,
-          timeoutId: null,
-        };
-        publishBrowserShortcutPolicy();
-      },
-      bindings,
-    });
-    chordStateRef.current = result.nextChordState;
-    if (
-      shouldPublishBrowserShortcutPolicy({
-        isBrowserInput: "browserId" in input.event,
-        previousChordState,
-        nextChordState: result.nextChordState,
-      })
-    ) {
-      publishBrowserShortcutPolicy(result.nextChordState);
-    }
-
-    if (result.preventDefault && input.domEvent) {
-      input.domEvent.preventDefault();
-      input.domEvent.stopPropagation();
-    }
-
-    if (!result.match) {
-      return;
-    }
-
-    const handled = routeAndPerformShortcut({
-      action: result.match.action,
-      payload: result.match.payload,
-      domEvent: input.domEvent,
-      browserFocusRestoreElement: input.browserFocusRestoreElement,
-    });
-    if (!handled || !input.domEvent) {
-      return;
-    }
-
-    if (result.match.preventDefault) {
-      input.domEvent.preventDefault();
-    }
-    if (result.match.stopPropagation) {
-      input.domEvent.stopPropagation();
-    }
-  };
-
-  // The window listeners must outlive ordinary re-renders: removing them resets
-  // any in-progress chord. Stable events let them read the latest render instead
-  // of being re-registered whenever a route, callback, or selection changes.
-  const handleKeyDown = useStableEvent((event: KeyboardEvent) => {
-    if (!shouldHandle()) {
-      return;
-    }
-
-    if (dispatchTopWebOverlayKeyDown(event)) {
-      return;
-    }
-
-    if (keyBelongsToDomPopover(event)) {
-      return;
-    }
-
-    // During IME composition, Enter confirms the candidate selection and must
-    // not route through global shortcuts like message send.
-    if (isImeComposingKeyboardEvent(event)) {
-      return;
-    }
-
-    const store = useKeyboardShortcutsStore.getState();
-    if (store.capturingShortcut) {
-      return;
-    }
-
-    const key = event.key ?? "";
-    if (
-      key === "Escape" &&
-      pathname.startsWith("/settings") &&
-      !isMobile &&
-      hasActiveWebOverlay()
-    ) {
-      return;
-    }
-    if (key === badgeModifierKey && !event.shiftKey) {
-      setBadgeModifierDown(true);
-    }
-    if (key === "Shift") {
-      const state = useKeyboardShortcutsStore.getState();
-      if (state.altDown || state.cmdOrCtrlDown) {
-        state.resetModifiers();
-      }
-    }
-
-    const focusScope = resolveKeyboardFocusScope({
-      target: event.target,
-      commandCenterOpen: store.commandCenterOpen,
-    });
-    resolveAndPerformShortcut({
-      event,
-      focusScope,
-      domEvent: event,
-    });
-  });
-
-  const handleKeyUp = useStableEvent((event: KeyboardEvent) => {
-    const key = event.key ?? "";
-    if (key === badgeModifierKey) {
-      setBadgeModifierDown(false);
-    }
-  });
-
-  const handleBrowserShortcutInput = useStableEvent((payload: unknown) => {
-    const input = parseBrowserShortcutInput(payload);
-    if (!input) {
-      return;
-    }
-    resolveAndPerformShortcut({
-      event: input,
-      focusScope: "browser",
-      domEvent: null,
-      browserFocusRestoreElement: getResidentBrowserWebview(input.browserId),
-    });
-  });
-
-  useEffect(() => {
-    if (!enabled) return;
-    if (!shortcutsAvailable) return;
-
-    const handleBlurOrHide = () => {
-      resetModifiers();
-    };
-
-    window.addEventListener("keydown", handleKeyDown, true);
-    window.addEventListener("keyup", handleKeyUp, true);
-    window.addEventListener("blur", handleBlurOrHide);
-    document.addEventListener("visibilitychange", handleBlurOrHide);
-
-    const browserShortcutSubscription = isElectronRuntime()
-      ? getDesktopHost()?.events?.on?.("browser-shortcut-input", handleBrowserShortcutInput)
-      : null;
-    return () => {
-      if (chordStateRef.current.timeoutId !== null) {
-        clearTimeout(chordStateRef.current.timeoutId);
-        chordStateRef.current = {
-          candidateIndices: [],
-          step: 0,
-          timeoutId: null,
-        };
-      }
-      window.removeEventListener("keydown", handleKeyDown, true);
-      window.removeEventListener("keyup", handleKeyUp, true);
-      window.removeEventListener("blur", handleBlurOrHide);
-      document.removeEventListener("visibilitychange", handleBlurOrHide);
-      if (typeof browserShortcutSubscription === "function") {
-        browserShortcutSubscription();
-      } else {
-        void browserShortcutSubscription?.then((dispose) => dispose());
-      }
-    };
-  }, [
-    enabled,
-    handleBrowserShortcutInput,
-    handleKeyDown,
-    handleKeyUp,
-    resetModifiers,
-    shortcutsAvailable,
-  ]);
-}

packages/app/src/hooks/use-shortcut-keys.ts

@@ -1,21 +1,20 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useMemo } from "react";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { resolveShortcutKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { getShortcutOs } from "@/utils/shortcut-platform";
-import { getIsElectronRuntime } from "@/constants/layout";
 
 /** `null` action ids are accepted so callers can keep the hook unconditional. */
 export function useShortcutKeys(actionId: string | null): ShortcutKey[][] | null {
   const { overrides } = useKeyboardShortcutOverrides();
   const isMac = getShortcutOs() === "mac";
-  const isDesktopApp = getIsElectronRuntime();
 
   return useMemo(() => {
     if (actionId === null) return null;
     return resolveShortcutKeysForAction(actionId, overrides, {
       isMac,
-      isDesktop: isDesktopApp,
+      usesDesktopBindings,
     });
-  }, [actionId, overrides, isMac, isDesktopApp]);
+  }, [actionId, overrides, isMac]);
 }

packages/app/src/hosts/host-chooser.tsx

@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
 import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -12,11 +13,7 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { HostStatusDotSlot } from "@/components/hosts/host-picker";
 import { isWeb } from "@/constants/platform";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import { orderHostsLocalFirst, type HostProfile } from "@/types/host-connection";
 
@@ -145,7 +142,7 @@ export function HostChooserModal() {
   const inputRef = useRef<EditingTextInputHandle>(null);
   const [query, setQuery] = useState("");
   const [activeIndex, setActiveIndex] = useState(0);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && request != null);
+  const modalLayer = useGlobalOverlayLayer("modal", request != null);
 
   const requestHosts = useMemo(() => {
     if (!request) return [];
@@ -186,8 +183,8 @@ export function HostChooserModal() {
     [close, request],
   );
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (
         event.key !== "ArrowDown" &&
         event.key !== "ArrowUp" &&
@@ -227,51 +224,56 @@ export function HostChooserModal() {
     },
     [activeOptionIndex, chooseHost, close, options],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && request != null,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: request != null,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   if (!request) return null;
 
   const modal = (
     <Modal visible transparent animationType="fade" onRequestClose={close} testID="host-chooser">
-      <View style={styles.overlay}>
-        <Pressable style={styles.backdrop} onPress={close} />
-        <View ref={setWebOverlayScope} style={styles.panel}>
-          <View style={styles.header}>
-            <Text style={styles.title}>{request.title}</Text>
-            <TextInput
-              ref={inputRef}
-              initialValue={query}
-              onChangeText={handleQueryChange}
-              placeholder="Search hosts..."
-              placeholderTextColor={theme.colors.foregroundMuted}
-              style={styles.input}
-              autoCapitalize="none"
-              autoCorrect={false}
-              testID="host-chooser-search"
-            />
-          </View>
-          <ScrollView
-            style={styles.results}
-            contentContainerStyle={styles.resultsContent}
-            keyboardShouldPersistTaps="always"
-            showsVerticalScrollIndicator={false}
-          >
-            {options.length === 0 ? <Text style={styles.emptyText}>No matching hosts</Text> : null}
-            {options.map((host, index) => (
-              <HostChooserRow
-                key={host.serverId}
-                host={host}
-                active={index === activeOptionIndex}
-                onChooseHost={chooseHost}
+      <OverlayLayerProvider layer={modalLayer}>
+        <View style={styles.overlay}>
+          <Pressable style={styles.backdrop} onPress={close} />
+          <View ref={setOverlayScope} style={styles.panel}>
+            <View style={styles.header}>
+              <Text style={styles.title}>{request.title}</Text>
+              <TextInput
+                ref={inputRef}
+                initialValue={query}
+                onChangeText={handleQueryChange}
+                placeholder="Search hosts..."
+                placeholderTextColor={theme.colors.foregroundMuted}
+                style={styles.input}
+                autoCapitalize="none"
+                autoCorrect={false}
+                testID="host-chooser-search"
               />
-            ))}
-          </ScrollView>
+            </View>
+            <ScrollView
+              style={styles.results}
+              contentContainerStyle={styles.resultsContent}
+              keyboardShouldPersistTaps="always"
+              showsVerticalScrollIndicator={false}
+            >
+              {options.length === 0 ? (
+                <Text style={styles.emptyText}>No matching hosts</Text>
+              ) : null}
+              {options.map((host, index) => (
+                <HostChooserRow
+                  key={host.serverId}
+                  host={host}
+                  active={index === activeOptionIndex}
+                  onChooseHost={chooseHost}
+                />
+              ))}
+            </ScrollView>
+          </View>
         </View>
-      </View>
+      </OverlayLayerProvider>
     </Modal>
   );
 

packages/app/src/i18n/resources/en.ts

@@ -2384,7 +2384,7 @@ export const en = {
       installing: "Installing…",
       logs: {
         action: "Logs",
-        title: "Logs: {{id}}",
+        title: "Logs: {{name}}",
         loading: "Loading logs…",
         refresh: "Refresh",
         refreshing: "Refreshing…",
@@ -2393,7 +2393,8 @@ export const en = {
       },
       status: { running: "running", disabled: "disabled", failed: "failed" },
       actions: {
-        menu: "Actions for {{id}}",
+        menu: "Actions for {{name}}",
+        settings: "Settings",
         reload: "Reload",
         reloading: "Reloading…",
         enable: "Enable",
@@ -2404,16 +2405,16 @@ export const en = {
         removing: "Removing…",
       },
       feedback: {
-        installed: "Installed {{id}}",
-        reload: "Reloaded {{id}}",
-        enable: "Enabled {{id}}",
-        disable: "Disabled {{id}}",
-        remove: "Removed {{id}}",
-        kept: "Kept {{id}}",
+        installed: "Installed {{name}}",
+        reload: "Reloaded {{name}}",
+        enable: "Enabled {{name}}",
+        disable: "Disabled {{name}}",
+        remove: "Removed {{name}}",
+        kept: "Kept {{name}}",
         globalEnabled: "Plugins enabled",
         globalDisabled: "Plugins disabled",
       },
-      removeConfirmTitle: "Remove {{id}}?",
+      removeConfirmTitle: "Remove {{name}}?",
       removeConfirmMessage: "This removes the configuration. The source directory is not deleted.",
       states: {
         offlineTitle: "Plugin host is offline",

packages/app/src/i18n/resources/plugin-settings.ts

@@ -1,7 +1,7 @@
 const shared = {
   logs: {
     action: "Logs",
-    title: "Logs: {{id}}",
+    title: "Logs: {{name}}",
     loading: "Loading logs…",
     refresh: "Refresh",
     refreshing: "Refreshing…",
@@ -33,7 +33,8 @@ export const pluginSettings = {
     installing: "جارٍ التثبيت…",
     status: { running: "قيد التشغيل", disabled: "معطّلة", failed: "فشلت" },
     actions: {
-      menu: "إجراءات {{id}}",
+      menu: "إجراءات {{name}}",
+      settings: "الإعدادات",
       reload: "إعادة تحميل",
       reloading: "جارٍ إعادة التحميل…",
       enable: "تفعيل",
@@ -44,16 +45,16 @@ export const pluginSettings = {
       removing: "جارٍ الإزالة…",
     },
     feedback: {
-      installed: "تم تثبيت {{id}}",
-      reload: "تمت إعادة تحميل {{id}}",
-      enable: "تم تفعيل {{id}}",
-      disable: "تم تعطيل {{id}}",
-      remove: "تمت إزالة {{id}}",
-      kept: "تم الإبقاء على {{id}}",
+      installed: "تم تثبيت {{name}}",
+      reload: "تمت إعادة تحميل {{name}}",
+      enable: "تم تفعيل {{name}}",
+      disable: "تم تعطيل {{name}}",
+      remove: "تمت إزالة {{name}}",
+      kept: "تم الإبقاء على {{name}}",
       globalEnabled: "تم تفعيل الإضافات",
       globalDisabled: "تم تعطيل الإضافات",
     },
-    removeConfirmTitle: "إزالة {{id}}؟",
+    removeConfirmTitle: "إزالة {{name}}؟",
     removeConfirmMessage: "يؤدي هذا إلى إزالة الإعداد فقط. لن يُحذف مجلد المصدر.",
     states: {
       offlineTitle: "مضيف الإضافات غير متصل",
@@ -88,7 +89,8 @@ export const pluginSettings = {
     installing: "Instalando…",
     status: { running: "en ejecución", disabled: "desactivado", failed: "fallido" },
     actions: {
-      menu: "Acciones para {{id}}",
+      menu: "Acciones para {{name}}",
+      settings: "Configuración",
       reload: "Recargar",
       reloading: "Recargando…",
       enable: "Activar",
@@ -99,16 +101,16 @@ export const pluginSettings = {
       removing: "Eliminando…",
     },
     feedback: {
-      installed: "{{id}} instalado",
-      reload: "{{id}} recargado",
-      enable: "{{id}} activado",
-      disable: "{{id}} desactivado",
-      remove: "{{id}} eliminado",
-      kept: "Se conservó {{id}}",
+      installed: "{{name}} instalado",
+      reload: "{{name}} recargado",
+      enable: "{{name}} activado",
+      disable: "{{name}} desactivado",
+      remove: "{{name}} eliminado",
+      kept: "Se conservó {{name}}",
       globalEnabled: "Plugins activados",
       globalDisabled: "Plugins desactivados",
     },
-    removeConfirmTitle: "¿Eliminar {{id}}?",
+    removeConfirmTitle: "¿Eliminar {{name}}?",
     removeConfirmMessage: "Esto elimina la configuración. El directorio de origen no se borra.",
     states: {
       offlineTitle: "El host de plugins está sin conexión",
@@ -143,7 +145,8 @@ export const pluginSettings = {
     installing: "Installation…",
     status: { running: "actif", disabled: "désactivé", failed: "échec" },
     actions: {
-      menu: "Actions pour {{id}}",
+      menu: "Actions pour {{name}}",
+      settings: "Paramètres",
       reload: "Recharger",
       reloading: "Rechargement…",
       enable: "Activer",
@@ -154,16 +157,16 @@ export const pluginSettings = {
       removing: "Suppression…",
     },
     feedback: {
-      installed: "{{id}} installé",
-      reload: "{{id}} rechargé",
-      enable: "{{id}} activé",
-      disable: "{{id}} désactivé",
-      remove: "{{id}} supprimé",
-      kept: "{{id}} conservé",
+      installed: "{{name}} installé",
+      reload: "{{name}} rechargé",
+      enable: "{{name}} activé",
+      disable: "{{name}} désactivé",
+      remove: "{{name}} supprimé",
+      kept: "{{name}} conservé",
       globalEnabled: "Plugins activés",
       globalDisabled: "Plugins désactivés",
     },
-    removeConfirmTitle: "Supprimer {{id}} ?",
+    removeConfirmTitle: "Supprimer {{name}} ?",
     removeConfirmMessage: "La configuration sera supprimée. Le dossier source ne sera pas effacé.",
     states: {
       offlineTitle: "L’hôte des plugins est hors ligne",
@@ -198,7 +201,8 @@ export const pluginSettings = {
     installing: "インストール中…",
     status: { running: "実行中", disabled: "無効", failed: "失敗" },
     actions: {
-      menu: "{{id}} のアクション",
+      menu: "{{name}} のアクション",
+      settings: "設定",
       reload: "再読み込み",
       reloading: "再読み込み中…",
       enable: "有効化",
@@ -209,16 +213,16 @@ export const pluginSettings = {
       removing: "削除中…",
     },
     feedback: {
-      installed: "{{id}} をインストールしました",
-      reload: "{{id}} を再読み込みしました",
-      enable: "{{id}} を有効にしました",
-      disable: "{{id}} を無効にしました",
-      remove: "{{id}} を削除しました",
-      kept: "{{id}} を保持しました",
+      installed: "{{name}} をインストールしました",
+      reload: "{{name}} を再読み込みしました",
+      enable: "{{name}} を有効にしました",
+      disable: "{{name}} を無効にしました",
+      remove: "{{name}} を削除しました",
+      kept: "{{name}} を保持しました",
       globalEnabled: "プラグインを有効にしました",
       globalDisabled: "プラグインを無効にしました",
     },
-    removeConfirmTitle: "{{id}} を削除しますか？",
+    removeConfirmTitle: "{{name}} を削除しますか？",
     removeConfirmMessage: "設定のみを削除します。ソースディレクトリは削除されません。",
     states: {
       offlineTitle: "プラグインホストはオフラインです",
@@ -252,7 +256,8 @@ export const pluginSettings = {
     installing: "설치 중…",
     status: { running: "실행 중", disabled: "비활성화", failed: "실패" },
     actions: {
-      menu: "{{id}} 작업",
+      menu: "{{name}} 작업",
+      settings: "설정",
       reload: "다시 로드",
       reloading: "다시 로드 중…",
       enable: "활성화",
@@ -263,16 +268,16 @@ export const pluginSettings = {
       removing: "제거 중…",
     },
     feedback: {
-      installed: "{{id}} 설치됨",
-      reload: "{{id}} 다시 로드됨",
-      enable: "{{id}} 활성화됨",
-      disable: "{{id}} 비활성화됨",
-      remove: "{{id}} 제거됨",
-      kept: "{{id}} 유지됨",
+      installed: "{{name}} 설치됨",
+      reload: "{{name}} 다시 로드됨",
+      enable: "{{name}} 활성화됨",
+      disable: "{{name}} 비활성화됨",
+      remove: "{{name}} 제거됨",
+      kept: "{{name}} 유지됨",
       globalEnabled: "플러그인 활성화됨",
       globalDisabled: "플러그인 비활성화됨",
     },
-    removeConfirmTitle: "{{id}}을(를) 제거할까요?",
+    removeConfirmTitle: "{{name}}을(를) 제거할까요?",
     removeConfirmMessage: "설정만 제거합니다. 소스 디렉터리는 삭제되지 않습니다.",
     states: {
       offlineTitle: "플러그인 호스트가 오프라인입니다",
@@ -307,7 +312,8 @@ export const pluginSettings = {
     installing: "Instalando…",
     status: { running: "em execução", disabled: "desativado", failed: "falhou" },
     actions: {
-      menu: "Ações para {{id}}",
+      menu: "Ações para {{name}}",
+      settings: "Configurações",
       reload: "Recarregar",
       reloading: "Recarregando…",
       enable: "Ativar",
@@ -318,16 +324,16 @@ export const pluginSettings = {
       removing: "Removendo…",
     },
     feedback: {
-      installed: "{{id}} instalado",
-      reload: "{{id}} recarregado",
-      enable: "{{id}} ativado",
-      disable: "{{id}} desativado",
-      remove: "{{id}} removido",
-      kept: "{{id}} mantido",
+      installed: "{{name}} instalado",
+      reload: "{{name}} recarregado",
+      enable: "{{name}} ativado",
+      disable: "{{name}} desativado",
+      remove: "{{name}} removido",
+      kept: "{{name}} mantido",
       globalEnabled: "Plugins ativados",
       globalDisabled: "Plugins desativados",
     },
-    removeConfirmTitle: "Remover {{id}}?",
+    removeConfirmTitle: "Remover {{name}}?",
     removeConfirmMessage: "Isso remove a configuração. O diretório de origem não será excluído.",
     states: {
       offlineTitle: "O host de plugins está offline",
@@ -362,7 +368,8 @@ export const pluginSettings = {
     installing: "Установка…",
     status: { running: "работает", disabled: "отключён", failed: "ошибка" },
     actions: {
-      menu: "Действия для {{id}}",
+      menu: "Действия для {{name}}",
+      settings: "Настройки",
       reload: "Перезагрузить",
       reloading: "Перезагрузка…",
       enable: "Включить",
@@ -373,16 +380,16 @@ export const pluginSettings = {
       removing: "Удаление…",
     },
     feedback: {
-      installed: "{{id}} установлен",
-      reload: "{{id}} перезагружен",
-      enable: "{{id}} включён",
-      disable: "{{id}} отключён",
-      remove: "{{id}} удалён",
-      kept: "{{id}} сохранён",
+      installed: "{{name}} установлен",
+      reload: "{{name}} перезагружен",
+      enable: "{{name}} включён",
+      disable: "{{name}} отключён",
+      remove: "{{name}} удалён",
+      kept: "{{name}} сохранён",
       globalEnabled: "Плагины включены",
       globalDisabled: "Плагины отключены",
     },
-    removeConfirmTitle: "Удалить {{id}}?",
+    removeConfirmTitle: "Удалить {{name}}?",
     removeConfirmMessage: "Конфигурация будет удалена. Исходный каталог останется на месте.",
     states: {
       offlineTitle: "Хост плагинов не в сети",
@@ -416,7 +423,8 @@ export const pluginSettings = {
     installing: "正在安装…",
     status: { running: "运行中", disabled: "已禁用", failed: "失败" },
     actions: {
-      menu: "{{id}} 的操作",
+      menu: "{{name}} 的操作",
+      settings: "设置",
       reload: "重新加载",
       reloading: "正在重新加载…",
       enable: "启用",
@@ -427,16 +435,16 @@ export const pluginSettings = {
       removing: "正在移除…",
     },
     feedback: {
-      installed: "已安装 {{id}}",
-      reload: "已重新加载 {{id}}",
-      enable: "已启用 {{id}}",
-      disable: "已禁用 {{id}}",
-      remove: "已移除 {{id}}",
-      kept: "已保留 {{id}}",
+      installed: "已安装 {{name}}",
+      reload: "已重新加载 {{name}}",
+      enable: "已启用 {{name}}",
+      disable: "已禁用 {{name}}",
+      remove: "已移除 {{name}}",
+      kept: "已保留 {{name}}",
       globalEnabled: "插件已启用",
       globalDisabled: "插件已禁用",
     },
-    removeConfirmTitle: "移除 {{id}}？",
+    removeConfirmTitle: "移除 {{name}}？",
     removeConfirmMessage: "这会移除配置，但不会删除源目录。",
     states: {
       offlineTitle: "插件主机离线",

packages/app/src/keyboard/availability.test.ts

@@ -1,11 +1,68 @@
 import { describe, expect, it } from "vitest";
-import { keyboardShortcutsAvailable } from "./availability";
+import { createHardwareKeyboardPresence } from "./internal/hardware-presence";
+import { buildEffectiveBindings } from "./keyboard-shortcuts";
+import { createKeyboardPipeline } from "./internal/pipeline";
+import { createOverlayRegistry } from "./internal/overlays";
+import { nativeKeyboardInput } from "./internal/sources/contract";
 
-describe("keyboardShortcutsAvailable", () => {
-  it("matches the environments where the shortcut dispatcher runs", () => {
-    expect(keyboardShortcutsAvailable({ isNative: false, isCompact: false })).toBe(true);
-    expect(keyboardShortcutsAvailable({ isNative: false, isCompact: true })).toBe(false);
-    expect(keyboardShortcutsAvailable({ isNative: true, isCompact: false })).toBe(false);
-    expect(keyboardShortcutsAvailable({ isNative: true, isCompact: true })).toBe(false);
+describe("hardware keyboard availability", () => {
+  it("publishes connection changes and cleans up the capability subscription", () => {
+    let present = false;
+    const changes = new Set<() => void>();
+    const presence = createHardwareKeyboardPresence({
+      read: () => present,
+      watch: (changed) => {
+        changes.add(changed);
+        return () => {
+          changes.delete(changed);
+        };
+      },
+    });
+    const observed: boolean[] = [];
+    const release = presence.subscribe(() => observed.push(presence.getSnapshot()));
+    expect(presence.getSnapshot()).toBe(false);
+    present = true;
+    for (const changed of changes) changed();
+    expect(presence.getSnapshot()).toBe(true);
+    for (const changed of changes) changed();
+    present = false;
+    for (const changed of changes) changed();
+    expect(observed).toEqual([true, false]);
+    release();
+    expect(changes.size).toBe(0);
+  });
+
+  it("routes compact Electron input independently of hint availability", () => {
+    const presence = createHardwareKeyboardPresence({ read: () => false, watch: () => () => {} });
+    const actions: string[] = [];
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({}),
+      isCapturing: () => false,
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+      overlays: createOverlayRegistry(),
+    });
+    pipeline.keyDown(
+      nativeKeyboardInput(
+        {
+          key: "k",
+          code: "KeyK",
+          metaKey: true,
+          ctrlKey: false,
+          altKey: false,
+          shiftKey: false,
+          repeat: false,
+          preventDefault() {},
+          stopPropagation() {},
+        },
+        "other",
+      ),
+    );
+    expect(presence.getSnapshot()).toBe(false);
+    expect(actions).toEqual(["command-center.toggle"]);
+    pipeline.dispose();
   });
 });

packages/app/src/keyboard/availability.ts

@@ -1,19 +1,9 @@
-import { useIsCompactFormFactor } from "@/constants/layout";
-import { isNative } from "@/constants/platform";
-
-interface KeyboardShortcutEnvironment {
-  isNative: boolean;
-  isCompact: boolean;
-}
-
-export function keyboardShortcutsAvailable({
-  isNative: native,
-  isCompact,
-}: KeyboardShortcutEnvironment): boolean {
-  return !native && !isCompact;
-}
-
-export function useKeyboardShortcutsAvailable(): boolean {
-  const isCompact = useIsCompactFormFactor();
-  return keyboardShortcutsAvailable({ isNative, isCompact });
+import { useSyncExternalStore } from "react";
+import { hardwareKeyboardPresence } from "./internal/presence";
+export function useHardwareKeyboardPresent(): boolean {
+  return useSyncExternalStore(
+    hardwareKeyboardPresence.subscribe,
+    hardwareKeyboardPresence.getSnapshot,
+    () => false,
+  );
 }

packages/app/src/keyboard/index.ts

@@ -0,0 +1,13 @@
+export { useOverlayRegistration } from "./internal/overlay-registration";
+export type { KeyboardInputEvent } from "./internal/overlays";
+export {
+  dispatchTopOverlayKeyDown,
+  hasActiveOverlay,
+  getTopOverlayKeys,
+  getTopOverlayLayer,
+  subscribeOverlays,
+} from "./internal/overlay-dispatch";
+export { useKeyboardFocusSurface } from "./internal/use-focus-surface";
+export { usesDesktopBindings, supportsConfigurableComposerSendKeys } from "./internal/conventions";
+export type { BrowserKeyboardPolicy } from "./internal/sources/electron-browser";
+export { useHardwareKeyboardPresent } from "./availability";

packages/app/src/keyboard/internal/conventions.ts

@@ -0,0 +1,3 @@
+export const usesDesktopBindings = true;
+// Native composer Return retains its existing submit path in this feature.
+export const supportsConfigurableComposerSendKeys = false;

packages/app/src/keyboard/internal/conventions.web.ts

@@ -0,0 +1,3 @@
+import { isElectronRuntime } from "@/desktop/host";
+export const usesDesktopBindings = isElectronRuntime();
+export const supportsConfigurableComposerSendKeys = true;

packages/app/src/keyboard/internal/dom-popover.ts

@@ -0,0 +1,6 @@
+export function keyBelongsToDomPopover(_event: { key: string }): boolean {
+  return false;
+}
+export function hasOpenDomPopover(): boolean {
+  return false;
+}

packages/app/src/keyboard/internal/dom-popover.web.ts

@@ -0,0 +1,24 @@
+/**
+ * True while an element shown with the Popover API is open. Such a layer
+ * floats above the app like a registered overlay but lives outside the
+ * registry: plugins draw their panels this way, since they cannot register.
+ */
+export function hasOpenDomPopover(): boolean {
+  if (typeof document === "undefined") return false;
+  try {
+    return document.querySelector(":popover-open") !== null;
+  } catch {
+    // An engine without the Popover API rejects the selector, and has none open.
+    return false;
+  }
+}
+
+/**
+ * Whether a key belongs to an open popover rather than to the app's shortcuts.
+ * An open popover (a plugin's panel) is the top layer and closes on its own
+ * Escape listener, which runs after the shortcut engine's capture listener:
+ * Escape must not also interrupt the running agent.
+ */
+export function keyBelongsToDomPopover(event: Pick<KeyboardEvent, "key">): boolean {
+  return event.key === "Escape" && hasOpenDomPopover();
+}