feat(extensions): prototype constrained JSX file views

[benvinegar]

Summary

• add constrained fixed-height React/OpenTUI row components to experimental extension file views
• keep review-stream geometry, immutable measurement, binary windowing, stable row ids, hunk navigation, clipping, and symbolic fallback host-owned
• prove the complete folder-extension → TSX loader → live-TUI path with a hook-using opt-in example
• add a checked-in gallery with a TypeScript change atlas, exact-source CSS swatches, semantic dependency-version highlights, and a long five-file mixed raw/custom review
• define cooperative interaction and ephemeral component-state policies, with attributed row-level error fallback
• bound and cancel extension layout work, coalesce rapid resize preparation, retain exact unaffected per-file layouts, and deduplicate warnings per concrete extension registration
• streamline the file-view API and advance hunk.apiVersion to 3

Context

This is a stacked draft on top of #632. It preserves and evaluates the JSX/OpenTUI direction without rewriting that PR.

The contract mounts components per validated row rather than handing an extension an entire file section. Each component declares a fixed terminal height and retains symbolic spans as fallback. Hunk snapshots accepted layouts, clips ordinary descendants to the declared rectangle, mounts only visible rows, and continues to own the surrounding multi-file review stream.

Release ordering

The streamlined file-view shape differs from the earlier API-v2 shape on the stacked base. This PR advances the extension API to version 3 so the contracts remain distinguishable if #632 ships separately. Prefer landing the stack in one release; do not publish the API-v2 file-view contract as final documentation for the version-3 shape.

Interaction and state policy

• custom rows are non-focusable paint surfaces; registered commands and menus are the supported keyboard path
• cooperative left-button mouse-up may act when normal routing delivers it, but pointer delivery is not guaranteed; wheel, drag, and unhandled input remain host-owned
• hook state survives selected-hunk prop changes while a row remains mounted
• hook state resets after row-window unmount, file-view changes, extension reloads, width relayouts, or replacement layout generations
• fixed-height symbolic fallback is clipped to the same declared rectangle when a component fails

Demo gallery

examples/extensions/jsx-file-view-gallery/ contains three conservative public-API-only previews with checked-in before/after fixtures. Its mixed-review launcher creates a temporary five-file Git working tree where all three previews remain active between raw Markdown and Python diffs in one scrollable review stream.

Known limitations

• component-driven resizing is ignored and clipped
• portals, renderer access, and other global OpenTUI capabilities can escape normal row composition; extensions are trusted code, not sandboxed code
• inline notes still force raw diff pending source-to-row bindings
• synchronous render/lifecycle errors fall back per row; event-handler, timer, promise, portal, and renderer-global failures remain outside React error boundaries

Validation

• full unit/session/CLI suite: 1,709 passed, 9 skipped
• full PTY integration suite: 74 passed
• TTY transcript smoke suite: 9 passed on the preceding runtime-hardening commit
• focused gallery unit suite: 6 passed
• bun run typecheck
• bun run lint
• changed-file formatting checks
• bun run check:pack

This PR description was generated by Pi using OpenAI GPT-5

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Jul 29, 2026 3:39pm

[greptile-apps]

Too many files changed for review. (55 files found, 50 file limit)

Bypass the limit by tagging @greptile-apps to review.