opencode-vim-navigation 0.1.2 → 0.1.4

package/README.md

@@ -1,66 +1,79 @@
 # opencode-vim-navigation
 
 Modal Vim-style transcript navigation for the **OpenCode terminal UI**.
-Scroll the conversation inside OpenCode itself—not your terminal emulator's,
-Neovim's, or tmux's scrollback—while keeping your prompt draft safe.
+Scroll the conversation inside OpenCode—not Neovim, tmux, or terminal-emulator
+scrollback—while keeping your prompt draft safe.
 
 Press **Ctrl+Q** to switch between INPUT and NAV. A compact, right-aligned
-mode label appears on a divider just above the prompt.
+mode label appears on a divider immediately above the prompt.
+
+When the native plan-review form is the only pending form, Ctrl+Q also enters
+NAV even though the prompt does not own focus. Navigation scrolls the session
+transcript behind the form; NAV consumes Enter, Escape, and all other
+non-navigation keys so they cannot approve, cancel, or edit the form. Press
+Ctrl+Q again to return to the form. Permission prompts and unrelated forms
+continue to own their keys and block NAV.
 
 ## Compatibility
 
-Tested with **OpenCode 2.1.4**. This uses OpenCode V2's TUI plugin API and is
-not a server plugin or a plugin for the desktop/web UI. Older releases and
-future API changes may require adaptation.
+Tested with **OpenCode 2.1.4**. This uses OpenCode V2's TUI plugin API, not the
+server plugin API or the desktop/web UI. Future host API changes may require
+adaptation, even if the peer dependency ranges still match.
+
+OpenCode supplies the plugin API, OpenTUI, and Solid runtime instances. The
+adapter is native JavaScript without JSX: no build step or React dependency
+is needed. Do not run the OpenCode entrypoint directly with Node.js.
+
+## Install from npm
 
-No build step is needed: OpenCode supplies `@opencode/plugin/tui`, OpenTUI,
-and `solid-js`. The adapter is plain JavaScript and constructs OpenTUI elements
-without JSX, avoiding different JSX transforms for local and npm installs.
-OpenTUI and Solid are declared
-as peer dependencies so the package documents its host compatibility.
-Do not run this entrypoint directly with Node.js.
+Add the package to `~/.config/opencode/cli.json`:
 
-## Install
+```json
+{
+  "plugins": ["opencode-vim-navigation"]
+}
+```
 
-### From a local checkout (available now)
+Merge this with your existing settings and restart OpenCode. This belongs in
+**`cli.json`**, not `opencode.json` or the V1-era `tui.json`.
 
-Clone the repository:
+For reproducible installations, check the available release and pin that
+version instead of using the bare package name:
 
 ```sh
-git clone https://github.com/Raaghav-Arya/opencode-vim-navigation.git
+npm view opencode-vim-navigation version
 ```
 
-Then add its **absolute directory path** to the `plugins` array in
-`~/.config/opencode/cli.json`:
+Use `opencode-vim-navigation@<published-version>` in the plugin array. Do not
+assume that an unpinned entry automatically updates an existing installation.
+Use OpenCode's plugin update workflow when upgrading.
 
-```json
-{
-  "plugins": ["/absolute/path/to/opencode-vim-navigation"]
-}
-```
+**Avoid versions 0.1.0 and 0.1.1:** they contain dependency/JSX packaging errors.
+Version 0.1.2 fixed loading. Source version **0.1.3** additionally hardens
+permission handling, prompt identity checks, and setup rollback. Check npm
+availability before pinning 0.1.3; use a local checkout to test changes that
+have not been published yet.
 
-Merge this into any existing TUI config; do not overwrite other settings.
-Restart OpenCode. No `npm install` is needed for this local package.
+[npm package](https://www.npmjs.com/package/opencode-vim-navigation) ·
+[GitHub](https://github.com/Raaghav-Arya/opencode-vim-navigation)
 
-Alternatively, symlink the package directory into
-`~/.config/opencode/plugins/opencode-vim-navigation` for automatic discovery.
-Use **one installation method**, not both.
+### Install a local checkout
 
-### From npm (after publication)
+```sh
+git clone https://github.com/Raaghav-Arya/opencode-vim-navigation.git
+```
 
-Once the package has been published as `opencode-vim-navigation`, use:
+Then use its **absolute directory path** in `cli.json`:
 
 ```json
 {
-  "plugins": ["opencode-vim-navigation@0.1.0"]
+  "plugins": ["/absolute/path/to/opencode-vim-navigation"]
 }
 ```
 
-This belongs in **`cli.json`**, not the server plugin list in `opencode.json`.
-OpenCode V1-era documentation may mention `tui.json`; these instructions target V2.
-OpenCode installs the package. Pin a version for reproducible configuration.
-Until the first npm release, use the local-checkout installation above.
-Check [npm](https://www.npmjs.com/package/opencode-vim-navigation) for availability.
+No `npm install` is needed for this local package. Alternatively, symlink its
+directory into `~/.config/opencode/plugins/opencode-vim-navigation` for automatic
+discovery. Use **one installation method**, not both. Restart OpenCode.
 
 ## Keys
 
@@ -75,23 +88,24 @@ Check [npm](https://www.npmjs.com/package/opencode-vim-navigation) for availabil
 | **i** | Type normally | Return to INPUT, follow latest output, preserve draft |
 | **Escape / Ctrl+C** | OpenCode default | Leave NAV without moving the viewport, then perform OpenCode's normal interrupt/clear action |
 
-Only Ctrl+Q is intercepted in INPUT. In particular, Ctrl+U/D retain their
-normal prompt-editing/exit behavior until you enter NAV.
-
-In NAV, other keys, Enter, and pasted text are ignored to protect your draft
-and prevent accidental submissions. This is **transcript navigation**, not
-Vim editing, cursor selection, or visual mode.
+Only Ctrl+Q is intercepted in INPUT, and only when the actual normal prompt
+is focused. Ctrl+U/D keep their default prompt-editing/exit behavior until NAV.
+In NAV, other keys, Enter, and pasted text are ignored to protect the draft
+and avoid accidental submissions. This is transcript navigation, not Vim
+editing, selection, or visual mode.
 
-Dialogs, autocomplete, composer panels, and other non-base modes keep their
-own keyboard handling. Incoming permission/form requests and session changes
-exit NAV. Existing mouse behavior is unchanged. The home screen is unchanged.
+Dialogs and other non-base modes keep their own keyboard handling. NAV is
+not entered from shell mode, autocomplete, unrelated textareas, or permission
+rejection editors. Pending permissions/forms prevent NAV entry; incoming
+requests exit NAV. Root-session checks include descendant/subagent requests,
+and location-scoped global forms are checked as well. Session changes reset
+NAV. The home screen and mouse behavior are unchanged.
 
 ### Neovim / Sidekick
 
 Stay in Neovim **terminal mode**. OpenCode draws its own transcript, so normal
-terminal-buffer scrollback cannot reliably navigate the conversation.
-
-Let OpenCode receive Ctrl+Q and handle scrolling:
+terminal-buffer scrollback cannot reliably navigate it. Let OpenCode receive
+Ctrl+Q and handle scrolling:
 
 ```lua
 cli = {
@@ -104,160 +118,159 @@ cli = {
 }
 ```
 
-Merge these options into your existing Sidekick configuration. Terminal or
-multiplexer mappings that intercept these keys must also be disabled.
+Merge these options into your existing configuration. Disable terminal or
+multiplexer mappings that intercept the same keys.
 
-## Development
+## Development and verification
 
-Use Node.js 22 or newer for the development commands:
+Use Node.js 22 or newer:
 
 ```sh
 npm test
 npm run check
-npm pack --dry-run
+npm run test:package
 ```
 
-There are no development dependencies to install. `npm run check` checks the
-JavaScript controller, TUI adapter, and tests. OpenCode loads the small
-TypeScript entrypoint; the adapter itself is native JavaScript, without JSX.
+- **Unit/adapter tests:** use the real controller and adapter with an injected,
+  mocked host. Cover input consumption, draft/submission spies, request
+  aggregation, focus identity, modal stacking, cleanup, and failure rollback.
+  These tests are not a real OpenCode renderer or Solid reactivity test.
+- **Syntax checks:** parse all runtime JavaScript and test files. There is no
+  TSX compilation stage; this is not a TypeScript typecheck.
+- **Package test:** packs the real archive, checks its contents, installs it
+  into a temporary consumer with normal peer resolution and scripts disabled,
+  and verifies installed source syntax/relative imports. Requires npm registry
+  access. It does not load OpenCode's host-provided runtime modules.
+
+The GitHub workflow runs all three checks. `prepublishOnly` also runs all
+three before publication. Package tests leave no dependencies or archives in
+the working checkout.
 
 ```text
 tui.ts                    Conventional local/package entrypoint
 src/
+  tui.mjs                 Host imports and plugin definition
+  adapter.mjs             Host integration, request/focus guards, mode indicator
   navigation.mjs          Mode state and input routing
-  tui.mjs                 OpenCode adapter and mode indicator (no JSX)
 tests/
-  navigation.test.mjs     Controller tests using node:test
+  navigation.test.mjs     Controller tests
+  adapter.test.mjs        Adapter regression tests with mocked host
+scripts/
+  test-package.mjs        Packed consumer installation checks
 ```
 
-The 13 tests mock the host and cover toggling, navigation, INPUT passthrough,
-paste/draft protection, dialog isolation, route cleanup, and missing commands.
-They do not replace interactive rendering tests.
-
-The initial implementation also passed a live pseudo-terminal smoke test
-against OpenCode 2.1.4: INPUT/NAV switched, navigation changed the viewport,
-and returning to INPUT preserved the draft, without submitting any prompt.
-The 0.1.2 packaging fix was additionally tested through OpenCode's **npm
-package loader**, using a temporary local registry serving the packed archive:
-installation, INPUT/NAV switching, scrolling, and draft preservation passed.
-This exercises the package-loading path rather than a source-directory install.
-Recheck the same behavior after changing the adapter or upgrading OpenCode.
-
-### Implementation details
+### Manual OpenCode runtime check
+
+Test both a checkout **and the packed/published package**, since OpenCode's
+local and npm loaders differ. The earlier JSX regression only occurred in
+the npm loading path. Validate:
+
+1. The installed package loads without plugin errors; INPUT is visible.
+2. Enter a draft without submitting it. Ctrl+Q enters NAV.
+3. j/k, gg/G, Ctrl+U/D visibly change the transcript viewport.
+4. Unknown keys, Enter, and bracketed paste in NAV do not alter the draft or
+   submit a prompt. Test submission-sensitive input only in an isolated session
+   without model access; do not risk sending an actual user's draft.
+5. `i` returns to INPUT with the **exact final draft** intact, not merely draft
+   text appearing somewhere in a terminal recording.
+6. Ctrl+U/D behave normally in INPUT.
+7. Existing/new permission requests, including subagent requests, remain
+   interactive. Ctrl+Q does not capture their rejection-reason editor.
+8. Dialogs, forms, shell mode, session switches, and plugin disable/re-enable
+   retain correct input ownership, with no duplicate listeners.
+
+A load/keyboard smoke test against the public 0.1.2 package passed. The packed
+0.1.3 archive also passed a live OpenCode npm-loader smoke test using a
+temporary local registry and isolated package cache. These checks verify
+loading, mode indicator changes, and keyboard-driven rendering, not every
+permission interaction or a strict no-submission guarantee. Earlier
+smoke assertions based only on terminal byte counts or a draft substring
+were insufficient to prove exact draft preservation or absence of submission.
+Do not describe those checks as a complete end-to-end guarantee.
+
+### Implementation notes
 
 The root `tui.ts` re-exports `src/tui.mjs`. OpenCode 2.1.4's local-directory
-loader looks for a conventional root `tui` entrypoint; npm packages also
-expose it via the `./tui` package export. Keep both when reorganizing source.
-
-See the [OpenCode V2 CLI plugin guide](https://opencode.ai/v2/docs/build/plugins/cli)
-for the host API and package conventions.
+loader expects a conventional root `tui` entrypoint; npm packages expose it
+through `./tui`. Keep both when reorganizing source.
 
-The plugin uses OpenTUI's public prepended key/paste listeners to stop NAV
-input before it reaches the prompt. A named OpenCode keymap mode isolates
-normal prompt shortcuts. Host transcript commands scroll the actual
-conversation, including virtualized history/backfill; the plugin does not
-scrape a terminal buffer. Listeners, mode, effects, and the mode indicator
-are cleaned up when the plugin deactivates.
+Prepended OpenTUI key/paste listeners stop NAV input before the editor.
+OpenCode keymap modes isolate prompt shortcuts, while host transcript
+commands handle scrolling and virtualized history/backfill. The adapter uses
+OpenCode's prompt traits to distinguish the main prompt from other textareas.
+Blocking requests are checked reactively and again at event dispatch to avoid
+races with incoming permissions. Acquired resources are unwound on setup
+failure as well as normal plugin teardown.
 
 In **2.1.4**, `session.page.up/down` move by half of `scroll.height`, whereas
-`session.half.page.up/down` move by a quarter. The plugin deliberately uses
-the former. It checks for expected commands before entering NAV, but future
-releases could retain names while changing semantics.
+`session.half.page.up/down` move by a quarter. This plugin deliberately uses
+the former. Required-command checks cannot detect future semantic changes.
+
+See the [OpenCode V2 CLI plugin guide](https://opencode.ai/v2/docs/build/plugins/cli)
+for host APIs and package conventions.
 
 ## Disable / uninstall
 
-Remove the package entry from `cli.json`, then restart OpenCode. If installed
-via automatic discovery instead, remove the symlink from `plugins/`.
-Merely renaming a package directory within `plugins/` does not disable it.
+Remove the package entry from `cli.json`, then restart OpenCode. For automatic
+discovery, remove its symlink from `plugins/`; merely renaming a package
+directory within `plugins/` does not disable it.
 
-The plugin ID in OpenCode's TUI plugin manager is `opencode-vim-navigation`.
+The TUI plugin manager ID is `opencode-vim-navigation`.
 
 ## Maintainer: publishing to npm
 
-GitHub hosts the source; npm distributes the installable package. Publishing
-to GitHub does not automatically publish to npm. Public unscoped packages
-can be published with a free npm account.
+GitHub hosts the source; npm distributes the package. Pushing to GitHub does
+not automatically publish to npm. A free npm account can publish this public,
+unscoped package.
 
-### First release
+### Account setup (once)
 
-1. Create an account at [npmjs.com/signup](https://www.npmjs.com/signup) if
-   needed, verify your email, and enable two-factor authentication in your
-   account settings. GitHub CLI authentication does **not** log you into npm.
-   Save your recovery codes privately; never commit tokens or recovery codes.
-2. From your checkout, log in using the browser flow:
+1. Create an account at [npmjs.com/signup](https://www.npmjs.com/signup), verify
+   your email, and enable two-factor authentication. Keep recovery codes private.
+   GitHub CLI authentication does not log you into npm.
+2. Authenticate using the browser flow:
 
    ```sh
-   npm login --registry=https://registry.npmjs.org/
+   npm login --auth-type=web --registry=https://registry.npmjs.org/
    npm whoami --registry=https://registry.npmjs.org/
    ```
 
-3. Check the package name:
+If publication returns E403 requiring 2FA, finish account 2FA setup and refresh
+your login. Complete npm's browser/OTP prompts privately. Do not share tokens,
+authentication codes, or recovery codes in issues or chat.
 
-   ```sh
-   npm view opencode-vim-navigation name version --registry=https://registry.npmjs.org/
-   ```
+### Release
 
-   An E404 means no public package was found; it is not a reservation or a
-   guarantee that npm will accept the name. If someone else owns it, choose
-   a scoped name such as `@YOUR_NPM_USERNAME/opencode-vim-navigation` and
-   update `package.json` and the installation examples before publishing.
-4. Review the release from the repository root:
+1. Review the diff, choose a new version, and run checks. A version already
+   published to npm cannot be overwritten or reused. If the working checkout
+   has already been bumped for the release, **do not bump it again**.
+2. Review the artifact and publication dry run:
 
    ```sh
    npm test
    npm run check
+   npm run test:package
    npm pack --dry-run
    npm publish --dry-run
    ```
 
-   The package should include `LICENSE`, `README.md`, `package.json`, `tui.ts`,
-   and `src/`. Tests and GitHub workflows stay on GitHub, not in the tarball.
-   Dry runs do not upload the package and do not prove your account has
-   permission to publish. The `prepublishOnly` script reruns tests and
-   JavaScript syntax checks before publication.
-5. Publish version **0.1.0**:
+   Tests, scripts, and GitHub workflows stay on GitHub, not in the archive.
+   Dry runs do not upload a package or prove permission to publish.
+3. Commit the reviewed release changes, then publish:
 
    ```sh
    npm publish --access public
    ```
 
-   Complete npm's browser / two-factor prompts. Do not paste authentication
-   codes or tokens into issues or chat. A successful publish ends with
-   `+ opencode-vim-navigation@0.1.0`.
-6. Verify the release:
-
-   ```sh
-   npm view opencode-vim-navigation@0.1.0 version dist.tarball
-   ```
-
-   Replace the local path in your OpenCode `cli.json` with
-   `opencode-vim-navigation@0.1.0` and restart OpenCode. Remove the
-   "after publication" wording in this README once the package is live.
-7. Optionally mark the published source on GitHub:
-
-   ```sh
-   git tag v0.1.0
-   git push origin v0.1.0
-   ```
-
-   Tag the exact commit used for publication; commit any release changes first.
-
-### Later releases
-
-npm versions cannot be overwritten or reused. For a compatible bug fix,
-start from a clean checkout, update the changelog/README as appropriate, run
-checks, then:
-
-```sh
-npm version patch
-npm publish --access public
-git push origin main --follow-tags
-```
+4. Verify the published version using `npm view opencode-vim-navigation`,
+   install that exact version in OpenCode, and run the runtime checklist above.
+5. Tag the exact published commit (`git tag v<VERSION>`), push the commit and
+   tag, then create the matching GitHub release.
 
-`npm version patch` updates the version and creates a commit and tag. Use a
-minor or major bump when appropriate instead. Publish manually initially;
-if automated releases are added later, prefer npm trusted publishing rather
-than storing a long-lived npm token in the repository.
+For later fixes from a clean checkout, `npm version patch` updates the version
+and creates a commit/tag. Use a minor/major bump when appropriate. Do not use
+that command on an already-bumped release. If automating publication later,
+prefer npm trusted publishing over long-lived tokens.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-vim-navigation",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Modal Vim-style transcript navigation for the OpenCode terminal UI",
   "license": "MIT",
   "author": "Raaghav Arya",
@@ -17,11 +17,20 @@
     "registry": "https://registry.npmjs.org/"
   },
   "type": "module",
-  "keywords": ["opencode", "opencode-plugin", "tui", "vim", "navigation"],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "vim",
+    "navigation"
+  ],
   "exports": {
     "./tui": "./tui.ts"
   },
-  "files": ["tui.ts", "src/"],
+  "files": [
+    "tui.ts",
+    "src/"
+  ],
   "peerDependencies": {
     "@opentui/core": ">=0.6.8 <0.7.0",
     "@opentui/solid": ">=0.6.8 <0.7.0",
@@ -29,7 +38,8 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "check": "node --check src/navigation.mjs && node --check src/tui.mjs && node --check tests/navigation.test.mjs",
-    "prepublishOnly": "npm test && npm run check"
+    "check": "node --check src/navigation.mjs && node --check src/adapter.mjs && node --check src/tui.mjs && node --check tests/navigation.test.mjs && node --check tests/adapter.test.mjs && node --check scripts/test-package.mjs",
+    "test:package": "node scripts/test-package.mjs",
+    "prepublishOnly": "npm test && npm run check && npm run test:package"
   }
 }

package/src/adapter.mjs

@@ -0,0 +1,124 @@
+import { navigation } from "./navigation.mjs"
+
+// Inject host-provided rendering/reactivity APIs so tests exercise the real adapter
+// without rewriting its imports or depending on OpenCode's runtime module loader.
+export function createSetup({ InputRenderable, TextareaRenderable, createElement, spread, createEffect, createRoot, createSignal }) {
+  return function setup(context) {
+    const { renderer, keymap, ui, data } = context
+    if (!renderer.keyInput?.prependListener || !renderer.keyInput?.removeListener
+      || !keymap.mode?.push || !keymap.mode?.current
+      || !data.session?.get || !data.session?.family
+      || !data.session?.permission?.list || !data.session?.form?.list) {
+      throw new Error("Vim navigation requires the OpenCode 2.1.4 TUI API")
+    }
+    const [nav, setNav] = createSignal(false)
+    const session = () => {
+      const route = ui.router.current()
+      return route.type === "session" ? route.sessionID : undefined
+    }
+    const promptFocused = () => {
+      const editor = renderer.currentFocusedEditor
+      const traits = editor?.traits
+      return editor instanceof TextareaRenderable && !(editor instanceof InputRenderable)
+        && traits?.owner === "opencode" && traits?.role === "prompt"
+        && !traits.status
+        && !traits.capture?.includes("navigate") && !traits.capture?.includes("submit")
+        && !traits.capture?.includes("autocomplete")
+    }
+    const visibleForms = () => {
+      const id = session()
+      if (!id) return []
+      const info = data.session.get(id)
+      const location = info?.location ?? context.location
+      // Match the host's visible request set: root sessions aggregate their
+      // descendants; child sessions show global/location forms only.
+      const forms = [...(data.session.form.list("global", location) ?? [])]
+      if (info?.parentID) return forms
+      const ids = new Set([id, ...data.session.family(id)])
+      for (const sessionID of ids) forms.push(...(data.session.form.list(sessionID) ?? []))
+      return forms
+    }
+    const planReviewForm = () => {
+      const forms = visibleForms()
+      return forms.length > 0 && forms.every((form) => form.metadata?.plugin === "raaghav.plan-review")
+    }
+    const blocked = () => {
+      const id = session()
+      if (!id) return false
+      const info = data.session.get(id)
+      if (info?.parentID) return visibleForms().some((form) => form.metadata?.plugin !== "raaghav.plan-review")
+      const location = info?.location ?? context.location
+      if (data.session.permission.list(id)?.length) return true
+      if (data.session.family(id).some((sessionID) => data.session.permission.list(sessionID)?.length)) return true
+      return visibleForms().some((form) => form.metadata?.plugin !== "raaghav.plan-review")
+    }
+    const required = ["session.line.up", "session.line.down", "session.page.up", "session.page.down", "session.first", "session.last"]
+    const controller = navigation({
+      session,
+      mode: keymap.mode,
+      promptFocused,
+      blocked,
+      planReviewForm,
+      ready: () => {
+        const commands = new Set(keymap.commands().map((command) => command.id))
+        if (required.every((id) => commands.has(id))) return true
+        ui.toast.show({ message: "Vim navigation: this OpenCode version lacks the expected scrolling commands", variant: "error" })
+        return false
+      },
+      dispatch: (id) => keymap.dispatch(id),
+      changed: setNav,
+    })
+    const cleanups = [() => controller.leave()]
+    let cleaned = false
+    const cleanup = () => {
+      if (cleaned) return
+      cleaned = true
+      const errors = []
+      for (const release of cleanups.reverse()) {
+        try { release() } catch (error) { errors.push(error) }
+      }
+      if (errors.length) throw new AggregateError(errors, "Vim navigation cleanup failed")
+    }
+    try {
+      // Register rollback BEFORE each acquisition: even a partially failing
+      // listener registration must not leave a failed generation intercepting keys.
+      cleanups.push(() => renderer.keyInput.removeListener("keypress", controller.key))
+      renderer.keyInput.prependListener("keypress", controller.key)
+      cleanups.push(() => renderer.keyInput.removeListener("paste", controller.paste))
+      renderer.keyInput.prependListener("paste", controller.paste)
+      createRoot((dispose) => {
+        cleanups.push(dispose)
+        createEffect(() => {
+          nav()
+          session()
+          blocked()
+          planReviewForm()
+          promptFocused()
+          controller.sync()
+        })
+      })
+      cleanups.push(ui.slot({
+        append: "session.composer.top",
+        render: () => {
+          const element = createElement("box")
+          spread(element, {
+            height: 1,
+            width: "100%",
+            border: ["top"],
+            get borderColor() { return context.theme.border.base },
+            get title() { return nav() ? " NAV · i: input " : " INPUT · Ctrl+Q: navigate " },
+            get titleColor() { return nav() ? context.theme.text.base : context.theme.text.muted },
+            titleAlignment: "right",
+          })
+          return element
+        },
+      }))
+      return cleanup
+    } catch (error) {
+      try { cleanup() } catch (rollbackError) {
+        throw new AggregateError([error, rollbackError], "Vim navigation setup and rollback failed")
+      }
+      throw error
+    }
+  }
+}

package/src/navigation.mjs

@@ -6,17 +6,20 @@ export function navigation(context) {
   let pendingG = false
 
   const active = () => popMode !== undefined
+  const planReview = () => context.planReviewForm?.() === true
+  const navigationAllowed = () => !context.blocked?.() && (context.promptFocused() || planReview())
   function leave(follow = false) {
     if (!active()) return
-    popMode()
+    const release = popMode
     popMode = undefined
     pendingG = false
     sessionID = undefined
-    context.changed(false)
+    try { release() } finally { context.changed(false) }
     if (follow) context.dispatch("session.last")
   }
   function sync() {
-    if (active() && context.session() !== sessionID) leave()
+    if (active() && (context.session() !== sessionID || !navigationAllowed()
+      || (context.mode.current() === MODE && !context.promptFocused() && !planReview()))) leave()
   }
   function scroll(id) {
     context.dispatch(id)
@@ -27,11 +30,15 @@ export function navigation(context) {
   }
   function key(event) {
     sync()
-    if (!context.session()) return
+    if (!context.session() || !navigationAllowed()) return
     // Dialogs, permission forms, autocomplete, and embedded terminals own their keys.
     const mode = context.mode.current()
-    if (mode !== "base" && mode !== MODE) return
-    if (!active() && !context.promptFocused()) return
+    const isPlanReview = planReview()
+    if (mode !== "base" && mode !== MODE && !isPlanReview) return
+    if (!context.promptFocused() && !isPlanReview) {
+      if (active()) leave()
+      return
+    }
     const plain = !event.ctrl && !event.meta && !event.super && !event.hyper
     const ctrl = event.ctrl && !event.meta && !event.super && !event.hyper && !event.shift
     const name = event.name
@@ -91,7 +98,10 @@ export function navigation(context) {
   }
   function paste(event) {
     sync()
-    if (active() && context.mode.current() === MODE) consume(event)
+    if (active() && context.mode.current() === MODE) {
+      if (!context.promptFocused() && !planReview()) leave()
+      else consume(event)
+    }
   }
   return { key, paste, leave, sync, active }
 }

package/src/tui.mjs

@@ -2,72 +2,9 @@ import { Plugin } from "@opencode/plugin/tui"
 import { InputRenderable, TextareaRenderable } from "@opentui/core"
 import { createElement, spread } from "@opentui/solid"
 import { createEffect, createRoot, createSignal } from "solid-js"
-import { navigation } from "./navigation.mjs"
+import { createSetup } from "./adapter.mjs"
 
 export default Plugin.define({
   id: "opencode-vim-navigation",
-  setup(context) {
-    const { renderer, keymap, ui } = context
-    if (!renderer.keyInput?.prependListener || !keymap.mode?.push) {
-      throw new Error("Transcript navigation requires the OpenCode 2.1.4 TUI API")
-    }
-    const [nav, setNav] = createSignal(false)
-    const session = () => {
-      const route = ui.router.current()
-      return route.type === "session" ? route.sessionID : undefined
-    }
-    const required = ["session.line.up", "session.line.down", "session.page.up", "session.page.down", "session.first", "session.last"]
-    const controller = navigation({
-      session,
-      mode: keymap.mode,
-      promptFocused: () => renderer.currentFocusedEditor instanceof TextareaRenderable
-        && !(renderer.currentFocusedEditor instanceof InputRenderable),
-      ready: () => {
-        const commands = new Set(keymap.commands().map((command) => command.id))
-        if (required.every((id) => commands.has(id))) return true
-        ui.toast.show({ message: "Transcript navigation: this OpenCode version lacks the expected scrolling commands", variant: "error" })
-        return false
-      },
-      dispatch: (id) => keymap.dispatch(id),
-      changed: setNav,
-    })
-    // OpenTUI's public global input listeners run before the focused editor.
-    // Prepending also precedes OpenCode's own keymap, so NAV cannot submit or edit a draft.
-    renderer.keyInput.prependListener("keypress", controller.key)
-    renderer.keyInput.prependListener("paste", controller.paste)
-    const dispose = createRoot((dispose) => {
-      createEffect(() => {
-        controller.sync()
-        const id = session()
-        // Never trap an incoming permission request or interactive form in NAV.
-        if (id && (context.data.session.permission.list(id)?.length || context.data.session.form.list(id)?.length)) {
-          controller.leave()
-        }
-      })
-      return dispose
-    })
-    const removeStatus = ui.slot({
-      append: "session.composer.top",
-      render: () => {
-        const element = createElement("box")
-        spread(element, {
-          height: 1,
-          width: "100%",
-          border: ["top"],
-          get borderColor() { return context.theme.border.base },
-          get title() { return nav() ? " NAV · i: input " : " INPUT · Ctrl+Q: navigate " },
-          get titleColor() { return nav() ? context.theme.text.base : context.theme.text.muted },
-          titleAlignment: "right",
-        })
-        return element
-      },
-    })
-    return () => {
-      renderer.keyInput.removeListener("keypress", controller.key)
-      renderer.keyInput.removeListener("paste", controller.paste)
-      controller.leave()
-      removeStatus()
-      dispose()
-    }
-  },
+  setup: createSetup({ InputRenderable, TextareaRenderable, createElement, spread, createEffect, createRoot, createSignal }),
 })