internal which-key plugin, inactive by default (#26337)

Author: kommander

packages/opencode/specs/tui-plugins.md

@@ -36,6 +36,7 @@ Example:
 - `plugin_enabled` is keyed by plugin id, not by plugin spec.
 - For file plugins, that id must come from the plugin module's exported `id`. For npm plugins, it is the exported `id` or the package name if `id` is omitted.
 - Plugins are enabled by default. `plugin_enabled` is only for explicit overrides, usually to disable a plugin with `false`.
+- Internal plugins can declare `enabled: false` to be registered but inactive by default; `plugin_enabled` and runtime KV can still enable them by id.
 - `plugin_enabled` is merged across config layers.
 - Runtime enable/disable state is also stored in KV under `plugin_enabled`; that KV state overrides config on startup.
 
@@ -227,6 +228,7 @@ Top-level API groups exposed to `tui(api, options, meta)`:
 - 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.
+- Built-in which-key shortcuts are resolved from `keymap.sections.which_key`, not plugin options.
 
 ### Keys
 
@@ -314,6 +316,7 @@ Theme install behavior:
 Current host slot names:
 
 - `app`
+- `app_bottom`
 - `home_logo`
 - `home_prompt` with props `{ workspace_id?, ref? }`
 - `home_prompt_right` with props `{ workspace_id? }`
@@ -332,7 +335,8 @@ Slot notes:
 - `api.slots.register(plugin)` does not return an unregister function.
 - Returned ids are `pluginId`, `pluginId:1`, `pluginId:2`, and so on.
 - Plugin-provided `id` is not allowed.
-- The current host renders `home_logo`, `home_prompt`, and `session_prompt` with `replace`, `home_footer`, `sidebar_title`, and `sidebar_footer` with `single_winner`, and `app`, `home_prompt_right`, `session_prompt_right`, `home_bottom`, and `sidebar_content` with the slot library default mode.
+- The current host renders `home_logo`, `home_prompt`, and `session_prompt` with `replace`, `home_footer`, `sidebar_title`, and `sidebar_footer` with `single_winner`, and `app`, `app_bottom`, `home_prompt_right`, `session_prompt_right`, `home_bottom`, and `sidebar_content` with the slot library default mode.
+- `app_bottom` is rendered in normal layout flow below the active route, while `app` is rendered afterward for global app-level UI.
 - Plugins can define custom slot names in `api.slots.register(...)` and render them from plugin UI with `ui.Slot`.
 
 ### Plugin control and lifecycle

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -399,6 +399,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
       {
         name: "command.palette.show",
         title: "Show command palette",
+        category: "System",
         hidden: true,
         run: () => {
           command.show()
@@ -852,6 +853,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     <box
       width={dimensions().width}
       height={dimensions().height}
+      flexDirection="column"
       backgroundColor={theme.background}
       onMouseDown={(evt) => {
         if (!Flag.OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT) return
@@ -867,17 +869,22 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
         <TimeToFirstDraw />
       </Show>
       <Show when={ready()}>
-        <Switch>
-          <Match when={route.data.type === "home"}>
-            <Home />
-          </Match>
-          <Match when={route.data.type === "session"}>
-            <Session />
-          </Match>
-        </Switch>
+        <box flexGrow={1} minHeight={0} flexDirection="column">
+          <Switch>
+            <Match when={route.data.type === "home"}>
+              <Home />
+            </Match>
+            <Match when={route.data.type === "session"}>
+              <Session />
+            </Match>
+          </Switch>
+          {plugin()}
+        </box>
+        <box flexShrink={0}>
+          <TuiPluginRuntime.Slot name="app_bottom" />
+        </box>
+        <TuiPluginRuntime.Slot name="app" />
       </Show>
-      {plugin()}
-      <TuiPluginRuntime.Slot name="app" />
       <StartupLoading ready={ready} />
     </box>
   )

packages/opencode/src/cli/cmd/tui/component/dialog-provider.tsx

@@ -243,6 +243,8 @@ function AutoMethod(props: AutoMethodProps) {
     bindings: [
       {
         key: "c",
+        desc: "Copy provider code",
+        group: "Dialog",
         cmd: () => {
           const code =
             props.authorization.instructions.match(/[A-Z0-9]{4}-[A-Z0-9]{4,5}/)?.[0] ?? props.authorization.url

packages/opencode/src/cli/cmd/tui/component/dialog-retry-action.tsx

@@ -48,18 +48,26 @@ export function DialogRetryAction(props: DialogRetryActionProps) {
     bindings: [
       {
         key: "left",
+        desc: "Previous retry option",
+        group: "Dialog",
         cmd: () => setSelected((value) => (value === "action" ? "dismiss" : "action")),
       },
       {
         key: "right",
+        desc: "Next retry option",
+        group: "Dialog",
         cmd: () => setSelected((value) => (value === "action" ? "dismiss" : "action")),
       },
       {
         key: "tab",
+        desc: "Next retry option",
+        group: "Dialog",
         cmd: () => setSelected((value) => (value === "action" ? "dismiss" : "action")),
       },
       {
         key: "return",
+        desc: "Confirm retry option",
+        group: "Dialog",
         cmd: () => {
           if (selected() === "action") runAction(props, dialog)
           else dismiss(props, dialog)

packages/opencode/src/cli/cmd/tui/component/dialog-session-delete-failed.tsx

@@ -42,11 +42,11 @@ export function DialogSessionDeleteFailed(props: {
 
   useBindings(() => ({
     bindings: [
-      { key: "return", cmd: () => void confirm() },
-      { key: "left", cmd: () => setStore("active", "delete") },
-      { key: "up", cmd: () => setStore("active", "delete") },
-      { key: "right", cmd: () => setStore("active", "restore") },
-      { key: "down", cmd: () => setStore("active", "restore") },
+      { key: "return", desc: "Confirm recovery option", group: "Dialog", cmd: () => void confirm() },
+      { key: "left", desc: "Delete broken session", group: "Dialog", cmd: () => setStore("active", "delete") },
+      { key: "up", desc: "Delete broken session", group: "Dialog", cmd: () => setStore("active", "delete") },
+      { key: "right", desc: "Restore broken session", group: "Dialog", cmd: () => setStore("active", "restore") },
+      { key: "down", desc: "Restore broken session", group: "Dialog", cmd: () => setStore("active", "restore") },
     ],
   }))
 

packages/opencode/src/cli/cmd/tui/component/dialog-workspace-unavailable.tsx

@@ -25,9 +25,9 @@ export function DialogWorkspaceUnavailable(props: { onRestore?: () => boolean |
 
   useBindings(() => ({
     bindings: [
-      { key: "return", cmd: () => void confirm() },
-      { key: "left", cmd: () => setStore("active", "cancel") },
-      { key: "right", cmd: () => setStore("active", "restore") },
+      { key: "return", desc: "Confirm workspace option", group: "Dialog", cmd: () => void confirm() },
+      { key: "left", desc: "Cancel workspace restore", group: "Dialog", cmd: () => setStore("active", "cancel") },
+      { key: "right", desc: "Restore workspace", group: "Dialog", cmd: () => setStore("active", "restore") },
     ],
   }))
 

packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx

@@ -528,32 +528,42 @@ export function Autocomplete(props: {
     commands: [
       {
         name: "prompt.autocomplete.prev",
+        title: "Previous autocomplete item",
+        category: "Autocomplete",
         run() {
           setStore("input", "keyboard")
           move(-1)
         },
       },
       {
         name: "prompt.autocomplete.next",
+        title: "Next autocomplete item",
+        category: "Autocomplete",
         run() {
           setStore("input", "keyboard")
           move(1)
         },
       },
       {
         name: "prompt.autocomplete.hide",
+        title: "Hide autocomplete",
+        category: "Autocomplete",
         run() {
           hide()
         },
       },
       {
         name: "prompt.autocomplete.select",
+        title: "Select autocomplete item",
+        category: "Autocomplete",
         run() {
           select()
         },
       },
       {
         name: "prompt.autocomplete.complete",
+        title: "Complete autocomplete item",
+        category: "Autocomplete",
         run() {
           const selected = options()[store.selected]
           if (selected?.isDirectory) {

packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

@@ -892,6 +892,8 @@ export function Prompt(props: PromptProps) {
       bindings: [
         {
           key: "!",
+          desc: "Shell mode",
+          group: "Prompt",
           cmd: () => {
             setStore("placeholder", randomIndex(shell().length))
             setStore("mode", "shell")
@@ -905,7 +907,7 @@ export function Prompt(props: PromptProps) {
     return {
       target: inputTarget,
       enabled: inputTarget() !== undefined && store.mode === "shell",
-      bindings: [{ key: "escape", cmd: () => setStore("mode", "normal") }],
+      bindings: [{ key: "escape", desc: "Exit shell mode", group: "Prompt", cmd: () => setStore("mode", "normal") }],
     }
   })
 
@@ -916,7 +918,7 @@ export function Prompt(props: PromptProps) {
         cursorVersion()
         return inputTarget() !== undefined && store.mode === "shell" && input?.visualCursor.offset === 0
       })(),
-      bindings: [{ key: "backspace", cmd: () => setStore("mode", "normal") }],
+      bindings: [{ key: "backspace", desc: "Exit shell mode", group: "Prompt", cmd: () => setStore("mode", "normal") }],
     }
   })
 
@@ -936,6 +938,8 @@ export function Prompt(props: PromptProps) {
       commands: [
         {
           name: "prompt.history.previous",
+          title: "Previous prompt history",
+          category: "Prompt",
           run() {
             if (input.cursorOffset !== 0) {
               input.cursorOffset = 0
@@ -972,6 +976,8 @@ export function Prompt(props: PromptProps) {
       commands: [
         {
           name: "prompt.history.next",
+          title: "Next prompt history",
+          category: "Prompt",
           run() {
             if (input.cursorOffset !== input.plainText.length) {
               input.cursorOffset = input.plainText.length

packages/opencode/src/cli/cmd/tui/config/tui-schema.ts

@@ -88,6 +88,20 @@ const GlobalKeymapSection = {
   "terminal.title.toggle": keymapBinding("none"),
 }
 
+const WhichKeyKeymapSection = {
+  "tui-which-key.toggle": keymapBinding("ctrl+alt+k"),
+  "tui-which-key.layout.toggle": keymapBinding("ctrl+alt+shift+k"),
+  "tui-which-key.pending.toggle": keymapBinding("ctrl+alt+shift+p"),
+  "tui-which-key.group.previous": keymapBinding("ctrl+alt+left,ctrl+alt+["),
+  "tui-which-key.group.next": keymapBinding("ctrl+alt+right,ctrl+alt+]"),
+  "tui-which-key.scroll.up": keymapBinding("ctrl+alt+up,ctrl+alt+p"),
+  "tui-which-key.scroll.down": keymapBinding("ctrl+alt+down,ctrl+alt+n"),
+  "tui-which-key.page.up": keymapBinding("ctrl+alt+pageup"),
+  "tui-which-key.page.down": keymapBinding("ctrl+alt+pagedown"),
+  "tui-which-key.home": keymapBinding("ctrl+alt+home"),
+  "tui-which-key.end": keymapBinding("ctrl+alt+end"),
+}
+
 const SessionKeymapSection = {
   "session.share": keymapBinding("none"),
   "session.rename": keymapBinding("ctrl+r"),
@@ -231,6 +245,7 @@ const HomeTipsKeymapSection = {
 
 const KeymapSectionsShape = {
   global: keymapSection(GlobalKeymapSection),
+  which_key: keymapSection(WhichKeyKeymapSection),
   session: keymapSection(SessionKeymapSection),
   prompt: keymapSection(PromptKeymapSection),
   autocomplete: keymapSection(AutocompleteKeymapSection),
@@ -246,6 +261,7 @@ const KeymapSectionsShape = {
 
 const KeymapSectionsInputShape = {
   global: keymapSectionInput(GlobalKeymapSection).optional(),
+  which_key: keymapSectionInput(WhichKeyKeymapSection).optional(),
   session: keymapSectionInput(SessionKeymapSection).optional(),
   prompt: keymapSectionInput(PromptKeymapSection).optional(),
   autocomplete: keymapSectionInput(AutocompleteKeymapSection).optional(),
@@ -271,6 +287,7 @@ export type KeymapInfo = {
 
 export const KeymapSectionGroups = {
   global: "Global",
+  which_key: "System",
   session: "Session",
   prompt: "Prompt",
   autocomplete: "Autocomplete",

packages/opencode/src/cli/cmd/tui/feature-plugins/home/footer.tsx

@@ -1,4 +1,5 @@
-import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { InternalTuiPlugin } from "../../plugin/internal"
 import { createMemo, Match, Show, Switch } from "solid-js"
 import { Global } from "@opencode-ai/core/global"
 
@@ -85,7 +86,7 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-const plugin: TuiPluginModule & { id: string } = {
+const plugin: InternalTuiPlugin = {
   id,
   tui,
 }