feat(extensions): line-exact review navigation with ctx.navigation.revealLine

[elucid]

What

Stacked on the line-highlights PR. Extension navigation gains its missing granularity:

ctx.navigation.revealLine(fileId, "new", 214);

selectHunk was previously the finest target an extension could name. That is fine until the hunk is large: a search extension can highlight a match on line 211, report "line 211" in its status — and the viewport still sits at the hunk anchor, pages above the match. revealLine scrolls the exact line into view and places the host's line cursor on it.

Design

• One landing spot, host-owned. The revealed line lands at Hunk's existing reveal position — max(2, 25% of viewport) rows of context above — the same policy note-to-note navigation and hunk reveals already use. Deliberately no placement option in the API: the extension states intent ("show this line"), the host owns presentation, and one learned landing zone beats per-extension conventions. Users can nudge afterwards with the align-current-line commands.
• Guarded like the rest of navigation. Live rather than snapshot, validated against the currently visible files; a hidden or unknown file warns and refuses. A line that currently has no rendered row (line-cursor stops disabled) degrades to the containing hunk — strictly no worse than selectHunk today. Only a line no hunk covers warns.
• Context lines resolve from either side's number, matching how the review actually draws them.
• Hardens the pane-actions contract. Implementation surfaced a latent stale-closure hazard: memoized pane hosts keep mount-time action callbacks, and revealLine was the first navigation member to read review state from its closure. It now reads through render-updated refs, so any held reference — memoized pane actions, an async handler navigating after an await — acts on the review as it is now, which is what the documented contract ("actions stay valid for as long as the component is mounted") always promised. Regression-tested at unit, host-PTY, and end-to-end-PTY levels, each demonstrated failing pre-fix.

What this unlocks

Paired with line highlights, marks and navigation compose into "look here":

• Search that lands the eye, not just the viewport — the active match arrives near the top of the pane with context above it, its characters inverted, regardless of hunk size.
• Agent-driven walkthroughs. Through the session daemon, an agent explaining a changeset can scroll the user's live terminal to the exact line it is discussing while marking the exact expression — today it can only jump hunk-to-hunk or leave comments and hope the user finds the spot.
• Diagnostics that take you there — a lint extension can mark the offending column and put the review on that line in one gesture.
• Anything that reports a position — coverage gaps, secret hits, TODO scanners — can now finish the job instead of naming a line the user scrolls for manually.

Notes

• Originally stacked on feat(extensions): let extensions mark character ranges inside diff lines (API v5) #726 (elucid/line-highlights); that PR squash-merged into main, and this branch is now rebased onto main with only its own six commits.
• No additional API version bump: feat(extensions): let extensions mark character ranges inside diff lines (API v5) #726's API v5 is still unreleased, so revealLine ships in the same generation and the docs describe both under one version note ("Version 5 adds line highlighters and line-granular navigation"). If v5 ships in a release before this lands, revealLine must become v6.
• Deliberately deferred: lowering revealLine into the core review intent vocabulary (a selection/reveal-line intent, a new reveal anchor, or moving the line-cursor reveal request into the review store). Line-cursor reveals are controller-local on main today, so this stays controller-local too; lowering it is a separate change if another surface ever needs line-exact reveals.
• After the rebase onto the post-feat(review): navigation intents, command catalog, and the address grammar (Phase 1 PR 3) #720/feat(review): producer runtime — generations, bounded resource serving, intent completion (Phase 2) #721 controller, the line-cursor reveal follows the selection through the shared selection/anchor intent (the replacement for the old preserveViewport option); the placement policy ("reveal" for jumps, "nearest" for stepping) is unchanged.
• The PTY regression test reproduces the real failure mode (a match 111 lines into a 130-line hunk) and was verified to discriminate: reverting to minimum-distance placement moves the token to the bottom edge and fails the test.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 14, 2026 4:10pm

[greptile-apps]

Greptile Summary

The PR adds line-exact extension navigation and hardens live pane navigation callbacks. The previously reported race between cross-file selection retries and exact-line placement is fixed.

• Adds ctx.navigation.revealLine(fileId, side, line) to the extension API and pane actions.
• Resolves rendered lines through current line-cursor geometry, with containing-hunk fallback.
• Gives explicit line reveals authority over pending selection and file-alignment retries.
• Adds unit, component, and PTY regression coverage plus API documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported selection retry is cancelled before exact-line scrolling and the regression path is covered.

Important Files Changed

Filename	Overview
src/ui/lib/extensionNavigation.ts	Adds guarded, live line navigation with validation and containing-hunk fallback.
src/ui/hooks/useReviewController.ts	Connects exact-line targets to current cursor state and host-owned reveal placement.
src/ui/components/panes/DiffPane.tsx	Makes explicit line reveals supersede queued selection and file-top alignment work, resolving the previously reported scroll race.
src/ui/lib/lineCursors.ts	Adds source-side and line-number lookup over the rendered line-cursor model.
src/extension-api/types.ts	Publishes the new line-granular navigation method through command and pane action contracts.
src/ui/components/ui-components.test.tsx	Covers the cross-file retry race with a tall-hunk exact-line reveal regression test.
test/pty/extensions-integration.test.ts	Verifies exact-line placement through the integrated terminal extension path.

Sequence Diagram

sequenceDiagram
  participant E as Extension
  participant N as Navigation Guard
  participant R as Review Controller
  participant D as DiffPane
  E->>N: revealLine(fileId, side, line)
  N->>N: Validate visible file and coordinates
  N->>R: Reveal matching cursor or select containing hunk
  R->>D: Selection and line-reveal request
  D->>D: Cancel pending selection retries
  D->>D: Scroll exact line to host reveal position

Loading

_{Reviews (2): Last reviewed commit: "fix(ui): let a revealed line survive the..." | Re-trigger Greptile}