feat(extensions): add interactive file-view modes

[benvinegar]

Summary

Adds opt-in keyboard modes for extension file views. A command can activate a view and its mode with fileViews.enterMode(viewId); the view then handles keys through onKey.

This also makes ctrl+<letter> chord matching accept bare C0 control bytes from synthetic or embedded input sources.

Mode behavior

• enterMode(viewId) selects the view and activates its mode in one step. Invalid or unavailable views are refused with a warning.
• Only one mode runs at a time. Replacing or exiting a mode preserves ordered, exactly-once onEnter and onExit callbacks, including re-entrant handoffs.
• onKey returns:
  • "handled" to consume the key
  • "pass" to continue through Hunk's commands and scrolling
  • "exit" to consume the key and leave the mode
• Dialogs and focused text inputs keep priority. Escape is always host-owned and exits the active mode.
• Modes also exit when the selected file, active presentation, extension set, or review session changes.
• Stale controls cannot activate a mode after a hard reload. Modes entered after a soft reload belong to the new review.
• Callback failures show a warning without breaking the review.
• The status bar shows <extension>:<view> mode — Esc exits while active.

C0 matching applies only to unnamed bare control-byte events. Named Tab and Enter events remain distinct, so ctrl+i and ctrl+m do not claim them.

Validation

Coverage includes activation and refusal policy, lifecycle ordering and re-entrancy, reload behavior, key routing, double-Escape handling, callback failures, C0 matching, scrollbox pass-through, and a real PTY interaction flow.

Typecheck, unit tests, PTY integration, TTY smoke tests, lint, package checks, documentation checks, and CI pass. Documentation and changesets are included.

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Aug 6, 2026 3:36pm

[greptile-apps]

Greptile Summary

This PR adds opt-in interactive keyboard modes for extension file views, including public API controls, host routing, lifecycle containment, status feedback, documentation, and end-to-end tests.

• Adds synchronous handled/pass/exit key routing ahead of the command table while preserving modal and focused-input precedence.
• Adds activation validation, automatic teardown on review or presentation changes, and extension-attributed failure containment.
• Extends consumer checks, documentation examples, app-level tests, and PTY integration coverage.

Confidence Score: 4/5

The mode replacement lifecycle defect should be fixed before merging because a valid extension callback or command can skip an active mode's required cleanup.

beginFileViewMode unconditionally publishes a new activation, so nested or repeated enterMode calls can overwrite the current activation without invoking its onExit callback and can report success after reentrant teardown.

Files Needing Attention: src/ui/App.tsx

Important Files Changed

Filename	Overview
src/ui/App.tsx	Integrates mode state, controls, lifecycle, validity checks, and status feedback, but replacing or reentrantly entering a mode can skip the prior activation's teardown.
src/ui/fileViews/mode.ts	Defines focused activation, validity, lifecycle-containment, key-delivery, and status-hint helpers.
src/ui/hooks/useAppKeyboardShortcuts.ts	Inserts mode routing after modal and focused-input owners and before command dispatch.
src/extension-api/types.ts	Publishes the mode callbacks, context, key results, and file-view control methods.
src/extensions/runExtension.ts	Validates that every declared file-view mode provides an onKey callback.
src/ui/AppHost.file-view-modes.test.tsx	Covers normal routing, exits, refusal cases, and thrown handlers, but not replacement or reentrant activation.
docs/extensions.md	Documents interactive mode activation, routing results, automatic exits, and a compiling stateful-view example.

Sequence Diagram

sequenceDiagram
  participant E as Extension command
  participant A as App mode state
  participant K as Keyboard router
  participant M as File-view mode
  participant C as Command table
  E->>A: enterMode(view)
  A->>M: onEnter(context)
  K->>M: onKey(key)
  alt handled
    M-->>K: handled
    K-->>K: consume key
  else pass
    M-->>K: pass
    K->>C: dispatch key
  else exit or Escape
    M-->>K: exit
    K->>A: exit mode
    A->>M: onExit(context)
  end

Loading

Prompt To Fix All With AI

### Issue 1
src/ui/App.tsx:719-720
**Mode replacement skips teardown**

When an active mode's `onKey` callback or a passed-through command calls `enterMode`, `beginFileViewMode` overwrites the current activation without invoking its `onExit`, causing that activation's cleanup and extension state teardown to be skipped. Reentrant entry from `onEnter` can also replace or exit the activation while the outer `enterMode` still reports success.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore: add changeset for interactive fil..." | Re-trigger Greptile}

[greptile-apps]

Mode replacement skips teardown

When an active mode's onKey callback or a passed-through command calls enterMode, beginFileViewMode overwrites the current activation without invoking its onExit, causing that activation's cleanup and extension state teardown to be skipped. Reentrant entry from onEnter can also replace or exit the activation while the outer enterMode still reports success.

Knowledge Base Used: Extension System: API, Loading, and Host Integration

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/ui/App.tsx
Line: 719-720

Comment:
**Mode replacement skips teardown**

When an active mode's `onKey` callback or a passed-through command calls `enterMode`, `beginFileViewMode` overwrites the current activation without invoking its `onExit`, causing that activation's cleanup and extension state teardown to be skipped. Reentrant entry from `onEnter` can also replace or exit the activation while the outer `enterMode` still reports success.

**Knowledge Base Used:** [Extension System: API, Loading, and Host Integration](https://app.greptile.com/modem/-/custom-context/knowledge-base/modem-dev/hunk/-/docs/extension-system.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.