introduce opentui keymap as sole key/cmd engine

.opencode/tui.json

@@ -6,11 +6,20 @@
       {
         "enabled": false,
         "label": "workspace",
-        "keybinds": {
-          "modal": "ctrl+alt+m",
-          "screen": "ctrl+alt+o",
-          "home": "escape,ctrl+shift+h",
-          "dialog_close": "escape,q"
+        "keymap": {
+          "sections": {
+            "global": {
+              "plugin.smoke.modal": "ctrl+alt+m",
+              "plugin.smoke.screen": "ctrl+alt+o"
+            },
+            "screen": {
+              "plugin.smoke.screen.home": "escape,ctrl+shift+h",
+              "plugin.smoke.screen.modal": "ctrl+alt+m"
+            },
+            "dialog": {
+              "plugin.smoke.dialog.close": "escape,q"
+            }
+          }
         }
       }
     ]

package.json

@@ -13,6 +13,7 @@
     "dev:storybook": "bun --cwd packages/storybook storybook",
     "lint": "oxlint",
     "typecheck": "bun turbo typecheck",
+    "upgrade-opentui": "bun run script/upgrade-opentui.ts",
     "postinstall": "bun run --cwd packages/opencode fix-node-pty",
     "prepare": "husky",
     "random": "echo 'Random script'",
@@ -34,8 +35,9 @@
       "@types/cross-spawn": "6.0.6",
       "@octokit/rest": "22.0.0",
       "@hono/zod-validator": "0.4.2",
-      "@opentui/core": "0.2.2",
-      "@opentui/solid": "0.2.2",
+      "@opentui/core": "0.2.4",
+      "@opentui/keymap": "0.2.4",
+      "@opentui/solid": "0.2.4",
       "ulid": "3.0.1",
       "@kobalte/core": "0.13.11",
       "@types/luxon": "3.7.1",

packages/opencode/package.json

@@ -11,7 +11,6 @@
     "test:ci": "mkdir -p .artifacts/unit && bun test --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml",
     "build": "bun run script/build.ts",
     "fix-node-pty": "bun run script/fix-node-pty.ts",
-    "upgrade-opentui": "bun run script/upgrade-opentui.ts",
     "dev": "bun run --conditions=browser ./src/index.ts",
     "dev:temporary": "bun run --conditions=browser ./src/temporary.ts",
     "db": "bun drizzle-kit"
@@ -125,6 +124,7 @@
     "@opentelemetry/sdk-trace-base": "2.6.1",
     "@opentelemetry/sdk-trace-node": "2.6.1",
     "@opentui/core": "catalog:",
+    "@opentui/keymap": "catalog:",
     "@opentui/solid": "catalog:",
     "@parcel/watcher": "2.5.1",
     "@pierre/diffs": "catalog:",

packages/opencode/script/schema.ts

@@ -59,5 +59,5 @@ await Bun.write(configFile, JSON.stringify(generate(Config.Info.zod), null, 2))
 
 if (tuiFile) {
   console.log(tuiFile)
-  await Bun.write(tuiFile, JSON.stringify(generate(TuiConfig.Info), null, 2))
+  await Bun.write(tuiFile, JSON.stringify(generate(TuiConfig.JsonSchemaInfo), null, 2))
 }

packages/opencode/specs/tui-plugins.md

@@ -53,13 +53,21 @@ Minimal module shape:
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
 
 const tui: TuiPlugin = async (api, options, meta) => {
-  api.command.register(() => [
-    {
-      title: "Demo",
-      value: "demo.open",
-      onSelect: () => api.route.navigate("demo"),
-    },
-  ])
+  api.keymap.registerLayer({
+    commands: [
+      {
+        name: "demo.open",
+        title: "Demo",
+        category: "Plugin",
+        namespace: "palette",
+        slashName: "demo",
+        run() {
+          api.route.navigate("demo")
+        },
+      },
+    ],
+    bindings: [{ key: "ctrl+shift+m", cmd: "demo.open", desc: "Open demo" }],
+  })
 
   api.route.register([
     {
@@ -194,10 +202,10 @@ That is what makes local config-scoped plugins able to import `@opencode-ai/plug
 Top-level API groups exposed to `tui(api, options, meta)`:
 
 - `api.app.version`
-- `api.command.register(cb)` / `api.command.trigger(value)` / `api.command.show()`
+- `api.keys.formatSequence(parts)`, `formatBindings(bindings)`
+- `api.keymap`
 - `api.route.register(routes)` / `api.route.navigate(name, params?)` / `api.route.current`
 - `api.ui.Dialog`, `DialogAlert`, `DialogConfirm`, `DialogPrompt`, `DialogSelect`, `Slot`, `Prompt`, `ui.toast`, `ui.dialog`
-- `api.keybind.match`, `print`, `create`
 - `api.tuiConfig`
 - `api.kv.get`, `set`, `ready`
 - `api.state`
@@ -209,23 +217,23 @@ Top-level API groups exposed to `tui(api, options, meta)`:
 - `api.plugins.list()`, `activate(id)`, `deactivate(id)`, `add(spec)`, `install(spec, options?)`
 - `api.lifecycle.signal`, `api.lifecycle.onDispose(fn)`
 
-### Commands
+### Keymap
 
-`api.command.register` returns an unregister function. Command rows support:
+- `api.keymap` exposes the raw `Keymap<Renderable, KeyEvent>` instance from the host.
+- The host already installs the default OpenTUI bundle (`default keys`, metadata fields, and enabled fields) plus OpenCode's comma bindings, leader token, base layout fallback, pending-sequence helpers, and managed textarea layer.
+- Register commands with `api.keymap.registerLayer({ commands: [...] })`.
+- Register key bindings with `bindings: [{ key, cmd, desc }]` in the same layer or a separate layer.
+- Use `api.keymap.acquireResource(...)` for shared plugin addon setup that should ref-count against the host keymap.
+- To surface a command in the host command palette, set `namespace: "palette"` and provide metadata such as `title`, `category`, `desc`, `suggested`, `hidden`, `enabled`, `slashName`, and `slashAliases` on the command.
+- Use `api.keymap.dispatchCommand(name)` for user-style execution semantics and `api.keymap.runCommand(name)` only for forced programmatic execution.
+- Disposers returned by `api.keymap` registrations and `acquireResource(...)` are automatically cleaned up when the plugin deactivates. You do not need to add those disposers to `api.lifecycle.onDispose(...)` yourself.
 
-- `title`, `value`
-- `description`, `category`
-- `keybind`
-- `suggested`, `hidden`, `enabled`
-- `slash: { name, aliases? }`
-- `onSelect`
+### Keys
 
-Command behavior:
-
-- Registrations are reactive.
-- Later registrations win for duplicate `value` and for keybind handling.
-- Hidden commands are removed from the command dialog and slash list, but still respond to keybinds and `command.trigger(value)` if `enabled !== false`.
-- `api.command.show()` opens the host command dialog directly.
+- `api.keys` exposes host-formatted shortcut display helpers for plugin UI.
+- `formatSequence(parts)` formats parsed key sequence parts using the host's display policy.
+- `formatBindings(bindings)` formats binding lists and returns `undefined` when there is nothing to show.
+- For generic config-to-bindings helpers, import `resolveBindingSections` from `@opencode-ai/plugin/tui`.
 
 ### Routes
 
@@ -252,13 +260,6 @@ Command behavior:
   - `setSize("medium" | "large" | "xlarge")`
   - readonly `size`, `depth`, `open`
 
-### Keybinds
-
-- `api.keybind.match(key, evt)` and `print(key)` use the host keybind parser/printer.
-- `api.keybind.create(defaults, overrides?)` builds a plugin-local keybind set.
-- Only missing, blank, or non-string overrides are ignored. Key syntax is not validated.
-- Returned keybind set exposes `all`, `get(name)`, `match(name, evt)`, `print(name)`.
-
 ### KV, state, client, events
 
 - `api.kv` is the shared app KV store backed by `state/kv.json`. It is not plugin-namespaced.

packages/opencode/specs/v2/keymappings.md

@@ -8,3 +8,29 @@ Make it `keymappings`, closer to neovim. Can be layered like `<leader>abc`. Comm
 
 _Why_
 Currently its keybindings that have an `id` like `message_redo` and then a command can use that or define it's own binding. While some keybindings are just used with `.match` in arbitrary key handlers and there is no info what the key is used for, except the binding id maybe. It also is unknown in which context/scope what binding is active, so a plugin like `which-key` is nearly impossible to get right.
+
+## OpenTUI Keymap Migration
+
+The v2 TUI uses `@opentui/keymap` as the key/cmd engine. The remaining legacy compatibility is config-only and exists to migrate users from `keybinds` to `keymap`:
+
+- `packages/opencode/src/config/keybinds.ts`: old `keybinds` schema, defaults, and legacy key names.
+- `packages/opencode/src/cli/cmd/tui/config/legacy-keymap-transform.ts`: transforms parsed legacy `keybinds` into OpenTUI `keymap` sections.
+- `packages/opencode/src/cli/cmd/tui/config/tui-migrate.ts`: migrates legacy TUI keys from `opencode.json` into `tui.json`, including `theme`, `keybinds`, and nested `tui`.
+- `packages/opencode/src/cli/cmd/tui/config/tui-schema.ts`: still accepts deprecated `keybinds` via `KeybindOverride` and marks it as deprecated. This file also contains the new `keymap` config schema.
+- `packages/opencode/src/cli/cmd/tui/config/tui.ts`: parses legacy `keybinds`, applies the Windows `terminal_suspend`/`input_undo` adjustment, and uses `LegacyKeymapTransform.create(...)` as the fallback when no `keymap` section is configured.
+- `packages/plugin/src/tui.ts`: plugin-facing `tuiConfig` still includes `keybinds` through `PluginConfig`; this should be removed when the public plugin API no longer exposes legacy config.
+
+The transform must stay while users are migrating. It lets users upgrade without first rewriting their existing `keybinds` config. If `keymap` is configured, `keybinds` are ignored for keymap resolution. If `keymap` is missing, `legacy-keymap-transform.ts` turns legacy `keybinds` into the resolved `keymap` consumed by OpenTUI.
+
+## Removing Legacy Later
+
+When switching fully to the new config style, remove legacy support with these exact changes:
+
+- Delete `packages/opencode/src/config/keybinds.ts`.
+- Delete `packages/opencode/src/cli/cmd/tui/config/legacy-keymap-transform.ts`.
+- Delete `packages/opencode/src/cli/cmd/tui/config/tui-migrate.ts`.
+- In `packages/opencode/src/cli/cmd/tui/config/tui-schema.ts`, remove the `ConfigKeybinds` import, remove `KeybindOverride`, and delete the deprecated `keybinds` field from `TuiInfo`.
+- In `packages/opencode/src/cli/cmd/tui/config/tui.ts`, remove `migrateTuiConfig(...)`, remove `ConfigKeybinds`, remove the Windows legacy keybind adjustment, remove `LegacyKeymapTransform.create(...)`, and require/default `keymap` through the new config path instead.
+- In `packages/opencode/src/cli/cmd/tui/config/tui.ts`, remove `keybinds` from `Resolved`; resolved TUI config should expose `keymap` only.
+- In `packages/plugin/src/tui.ts`, remove `keybinds` from plugin-facing `TuiConfigView`.
+- Remove or rewrite tests that write or assert `keybinds`, especially in `packages/opencode/test/config/tui.test.ts`, `packages/opencode/test/fixture/tui-runtime.ts`, and TUI plugin loader tests.