Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# 📋 PRD: Session Explorer — Spatial Auto-Lock, Sticky Zero-Drift Gutter, & Holographic Multi-IDE Cockpit

> **Document ID**: `PRD-SE-008`
> **Target Subsystem**: `tools/session-explorer`
> **Lifecycle Phase**: `draft` → `spec-review`
> **Author**: Antigravity Autonomous Agent & Systems Architect
> **Date**: 2026-11-10
> **Prerequisites**: `PRD-SE-005`, `PRD-SE-006`, `PRD-SE-007` (v0.5.2)

---

## 1. Executive Summary & Problem Formulation

In `v0.5.2`, Session Explorer introduced the **Holographic Git & Review Pane**, GitHub-standard dual line gutters, diff minimap heatmap, and sub-pixel alignment engine. However, real-world forensic evaluation across multi-thousand-line source codebases revealed three critical ergonomics and developer-experience friction points:

1. **Hunk Desynchronization on Step Scrubber Navigation**:
When stepping through agent mutation turns using `◀` / `▶` (or arrow keys), the review diff pane updates its inline/split view, but the left file viewer pane remains parked at its previous scroll offset. The user is forced to manually click the Hunk header / pill to locate and highlight where the change occurred on the file.
2. **Gutter Loss on Horizontal Scroll**:
When source code contains long lines exceeding the viewport width, scrolling horizontally to the right causes `.code-line-numbers` to scroll off to the left and disappear. The user loses line number orientation completely and must scroll all the way back to the left.
3. **Hardcoded Monolithic IDE Launcher**:
The "↗ IDE" button in the file viewer topbar hardcodes `cursor://file/<path>:<line>`. Developers using Visual Studio Code, Windsurf, JetBrains (IntelliJ, GoLand, PyCharm, WebStorm), Sublime Text, or terminal editors cannot launch their editor of choice, suffer browser URI scheme failures, and have no way to configure their preferred editor.

This PRD establishes the requirements to eliminate these friction points, transforming Session Explorer into a fluid, Year 2500 **GenAI Mission Control Cockpit**.

---

## 2. User Personas & The 4 Constitutional Lenses

| Lens | Role & Hat | Core Need in this Milestone |
| :--- | :--- | :--- |
| **🌱 Kindergarten Lens** | Junior Dev / First-Time Auditor | "When I click next turn, show me immediately what changed in the file. Don't hide line numbers when I scroll sideways. Let me click an editor I actually have installed." |
| **🛠️ Senior Pair Programmer Lens** | Full-Stack / GenAI Engineer | "Dynamic link between active hunk and IDE button. The moment I click 'Open in VS Code', land my cursor directly on the mutated AST symbol. Save my preference in `localStorage`." |
| **🏛️ Systems Architect Lens** | Tech Lead & Core Maintainer | "Dual-vector launch strategy: Go backend (`POST /api/ide/open`) launches local CLI tools directly with zero browser confirmation dialogs; browser URI protocol acts as graceful remote fallback." |
| **🔬 Research Scientist Lens** | AI Agent & Reasoning Auditor | "Maintain a zero-latency, context-preserving bridge between the agent's monologue/trajectory and the developer's runtime workspace. Zero cognitive friction." |

---

## 3. High-Level Requirements

### R-073: Automatic Hunk 1 Spatial Auto-Lock & Framing on Scrubber Navigation
- When navigating steps via the step scrubber (`◀` / `▶`), keyboard arrow keys (`Left`/`Right`), or review vector tab switching, the system must automatically invoke `stepToHunk(0)`.
- The left file viewer pane must smoothly scroll to the exact start line of the primary hunk.
- The ambient active hunk spotlight (`.hunk-active-spotlight`) must frame all lines of the hunk.
- The radiant beam pulse animation must trigger on the target line in the file viewer.
- The IDE launcher target line must dynamically sync to the active hunk's start line.

### R-074: Sub-Pixel Sticky Zero-Drift Line Number Gutter
- `.code-line-numbers` must be anchored with `position: sticky; left: 0; z-index: 10;`.
- The sticky gutter must use an opaque, frosted glassmorphic backdrop token across all 4 themes (**Liquid Glass**, **Fluent Aero Mica**, **Holo Cyberpunk**, **Matrix Obsidian**).
- Horizontal code scrolling behind the gutter must never bleed text or glyphs through the line number column.
- Gutter diff decorations (`.gutter-diff-add`, `.gutter-diff-mod`, `.gutter-diff-del`) must remain pinned to the left edge along with the line numbers.
- Maintain zero line-height drift (`line-height: 22px`) across 10,000+ lines.

### R-075: Sticky Viewport Docking for Diff Minimap Heatmap Rail
- `.file-diff-minimap-rail` must be anchored with `position: sticky; right: 0; z-index: 12;` within the scrolling code container.
- Horizontal code scrolling must not push the minimap heatmap rail offscreen; it must remain docked to the visible right boundary of `.file-viewer-body`.

### R-076: Holographic Multi-IDE Selector Split-Button & Glassmorphic Palette
- Replace the static "↗ IDE" button with an interactive holographic split-button:
- **Left Action**: Displays the active editor icon and name (e.g. `[ 🚀 Cursor ]` or `[ 💙 VS Code ]` or `[ 🌊 Windsurf ]`). Clicking it triggers immediate launch at the active hunk line.
- **Right Chevron (`▾`)**: Triggers the **Holographic IDE Selector Palette** dropdown.
- Palette options:
- 🚀 **Cursor** (`cursor://file/{path}:{line}`)
- 💙 **Visual Studio Code** (`vscode://file/{path}:{line}`)
- 🌊 **Windsurf** (`windsurf://file/{path}:{line}`)
- 🧠 **JetBrains** (IntelliJ IDEA / GoLand / PyCharm / WebStorm) (`idea://open?file={path}&line={line}`)
- ⚡ **VS Code Insiders** (`vscode-insiders://file/{path}:{line}`)
- 📜 **Sublime Text** (`subl://open?url=file://{path}&line={line}`)
- 🍎 **System Default** (`open {path}`)
- 📋 **Copy CLI Launch Command** (e.g. `cursor -g /path:123`) to clipboard with toast notification.
- Persistence: Default editor preference stored in `localStorage('se_preferred_ide')`.

### R-077: Backend Native Process Launch API (`POST /api/ide/open`)
- Implement a secure Go REST endpoint `POST /api/ide/open`.
- Request Payload:
```json
{
"editor": "cursor",
"path": "/absolute/path/to/file.rs",
"line": 42
}
```
- Backend execution via `exec.LookPath`:
- `cursor`: `cursor -g <path>:<line>`
- `code`: `code -g <path>:<line>`
- `windsurf`: `windsurf -g <path>:<line>`
- `idea`: `idea --line <line> <path>`
- `subl`: `subl <path>:<line>`
- `system`: `open <path>` (macOS) / `xdg-open` (Linux)
- Path validation & safety: reject directory traversal attacks or paths outside permitted roots.
- Fallback response: if binary is not installed in `$PATH`, returns `{ "success": false, "fallback_uri": "...", "command": "..." }`, prompting frontend to execute protocol URI or copy CLI command.

### R-078: Automated End-to-End Verification Harness
- Go unit test suite covering `/api/ide/open` payload parsing, security guards, and command resolution.
- Playwright automated browser verification confirming:
1. Scrubber click auto-scrolls and highlights Hunk 1 in file viewer.
2. Horizontal scroll retains sticky line numbers at `left: 0` without text bleed.
3. Sticky minimap rail stays pinned to visible `right: 0`.
4. IDE split-button opens palette, remembers preference, and executes dual-vector dispatch.
186 changes: 186 additions & 0 deletions specs/catalog/session-explorer-spatial-autolock-and-ide-cockpit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
# 📐 Specification: Spatial Auto-Lock, Sticky Zero-Drift Gutter, & Holographic Multi-IDE Cockpit

> **Document ID**: `SPEC-SE-008`
> **Target Subsystem**: `tools/session-explorer`
> **Lifecycle Phase**: `spec-review`
> **Author**: Antigravity Autonomous Agent & Systems Architect
> **Date**: 2026-11-10
> **Companion PRD**: [`specs/catalog/session-explorer-spatial-autolock-and-ide-cockpit-prd.md`](session-explorer-spatial-autolock-and-ide-cockpit-prd.md)
> **Version Target**: `v0.5.3`

---

## 1. Architectural Overview & Context

This specification defines the implementation contract for three interlocking enhancements in Session Explorer:
1. **Spatial Auto-Lock & Framing**: Synchronized bidirectional centering between step scrubbers, diff hunks, and full file contents.
2. **Sub-Pixel Sticky Zero-Drift Gutter**: Viewport-anchored line numbers and diff minimap rail during horizontal code scroll.
3. **Holographic Multi-IDE Selector Cockpit**: Dual-vector desktop IDE integration via Go backend CLI process execution and browser protocol fallback.

```mermaid
flowchart TD
subgraph Step Scrubber Pipeline
S1["User navigates step (◀/▶, ArrowKeys, Tab)"] --> S2["stepReviewScrubber(delta)"]
S2 --> S3["renderStepsVector()"]
S3 --> S4["renderDiffSurface()"]
S4 -->|Auto-Sync| S5["stepToHunk(0)"]
S5 --> S6["File Viewer: Smooth scroll to start line"]
S5 --> S7["File Viewer: Apply .hunk-active-spotlight"]
S5 --> S8["File Viewer: Trigger radiant beam pulse"]
S5 --> S9["Diff Pane: Scroll & Highlight Hunk 1"]
S5 --> S10["Update state.fileViewerTargetLine"]
end

subgraph Sticky Gutter Engine
G1["User scrolls horizontally (scrollLeft > 0)"] --> G2[".code-line-numbers { position: sticky; left: 0 }"]
G2 --> G3["Pinned Line Numbers & Gutter Diff Indicators"]
G1 --> G4[".file-diff-minimap-rail { position: sticky; right: 0 }"]
G4 --> G5["Pinned Heatmap Rail at Viewport Edge"]
end

subgraph Dual-Vector IDE Dispatcher
I1["User clicks IDE button / picks editor"] --> I2{"Invoke Backend API"}
I2 -->|POST /api/ide/open| I3["exec.Command(binary, args...)"]
I3 -->|Binary Found & Executed| I4["Instant Launch (Zero Browser Prompt)"]
I3 -->|Binary Not Found / Remote| I5["Fallback: window.open(protocolUri)"]
I5 -->|Blocked / Unhandled| I6["Fallback: Copy CLI Command to Clipboard"]
end
```

---

## 2. Requirements & Acceptance Criteria (Traceability Matrix)

| Requirement | Description | Acceptance Criteria |
| :--- | :--- | :--- |
| **R-073** | Automatic Hunk 1 Spatial Auto-Lock & Framing | **AC-186**: When `stepReviewScrubber` runs, `stepToHunk(0)` executes automatically if hunks exist.<br>**AC-187**: The left file viewer smoothly scrolls to the primary hunk start line.<br>**AC-188**: `.hunk-active-spotlight` is added across all lines in the hunk.<br>**AC-189**: The primary line receives `.jump-pulse` radiant beam animation.<br>**AC-190**: `state.fileViewerTargetLine` updates to the active hunk line. |
| **R-074** | Sub-Pixel Sticky Zero-Drift Line Number Gutter | **AC-191**: `.code-line-numbers` has `position: sticky; left: 0; z-index: 10;`.<br>**AC-192**: Opaque, frosted glassmorphic backdrops configured for all 4 themes.<br>**AC-193**: Scrolling horizontally to the right preserves visible line numbers docked to the left edge.<br>**AC-194**: Gutter diff indicators (`.gutter-diff-add`, `.gutter-diff-mod`, `.gutter-diff-del`) remain pinned.<br>**AC-195**: Zero text bleed-through from underlying scrolling code lines. |
| **R-075** | Sticky Viewport Docking for Diff Minimap Heatmap Rail | **AC-196**: `.file-diff-minimap-rail` has `position: sticky; right: 0; z-index: 12;`.<br>**AC-197**: Minimap rail remains pinned to visible right edge of the file viewer body during horizontal scrolling. |
| **R-076** | Holographic Multi-IDE Selector Split-Button & Palette | **AC-198**: Split button rendered with active editor icon/label on left, dropdown chevron on right.<br>**AC-199**: Clicking chevron opens glassmorphic palette listing Cursor, VS Code, Windsurf, JetBrains, Sublime, System.<br>**AC-200**: Selecting an editor updates the active button, launches the editor, and persists to `localStorage('se_preferred_ide')`.<br>**AC-201**: Includes "Copy CLI Command" option with toast feedback. |
| **R-077** | Backend Native Process Launch API (`POST /api/ide/open`) | **AC-202**: Go handler `HandleOpenInIDE` bound to `POST /api/ide/open`.<br>**AC-203**: Validates file path existence and containment.<br>**AC-204**: Dispatches `exec.Command` for supported editor binaries (`cursor`, `code`, `windsurf`, `idea`, `subl`, `open`).<br>**AC-205**: Returns `{ success: true }` or fallback URI / command on binary absence. |
| **R-078** | Test & Verification Suite | **AC-206**: Go unit tests pass in `api_test.go`.<br>**AC-207**: Automated Playwright browser tests verify scrubber auto-framing, sticky gutter, and IDE launcher. |

---

## 3. UI/UX Design & Holographic Tokens

### 3.1 IDE Split-Button Topbar Markup
```html
<div class="ide-split-button-group" id="fileViewerIdeGroup">
<button class="btn-ghost-sm ide-primary-btn" id="fileViewerIdePrimaryBtn" title="Open in Preferred IDE">
<span class="ide-icon" id="fileViewerIdeIcon">🚀</span>
<span class="ide-name" id="fileViewerIdeName">Cursor</span>
</button>
<button class="btn-ghost-sm ide-dropdown-btn" id="fileViewerIdeDropdownBtn" title="Choose Editor (Cursor, VS Code, Windsurf, JetBrains, Sublime)">
▾
</button>
<div class="ide-picker-menu holo-glassmorphic-menu" id="fileViewerIdeMenu" style="display: none;">
<div class="ide-menu-header">Select Desktop IDE</div>
<div class="ide-menu-item" data-editor="cursor">
<span class="ide-menu-icon">🚀</span>
<span class="ide-menu-label">Cursor</span>
<span class="ide-menu-badge">Default</span>
</div>
<div class="ide-menu-item" data-editor="vscode">
<span class="ide-menu-icon">💙</span>
<span class="ide-menu-label">Visual Studio Code</span>
</div>
<div class="ide-menu-item" data-editor="windsurf">
<span class="ide-menu-icon">🌊</span>
<span class="ide-menu-label">Windsurf</span>
</div>
<div class="ide-menu-item" data-editor="idea">
<span class="ide-menu-icon">🧠</span>
<span class="ide-menu-label">JetBrains (IDEA / PyCharm / GoLand)</span>
</div>
<div class="ide-menu-item" data-editor="sublime">
<span class="ide-menu-icon">📜</span>
<span class="ide-menu-label">Sublime Text</span>
</div>
<div class="ide-menu-item" data-editor="system">
<span class="ide-menu-icon">🍎</span>
<span class="ide-menu-label">System Default</span>
</div>
<div class="ide-menu-divider"></div>
<div class="ide-menu-item ide-menu-copy" id="ideMenuCopyCliBtn">
<span class="ide-menu-icon">📋</span>
<span class="ide-menu-label">Copy CLI Launch Command</span>
</div>
</div>
</div>
```

### 3.2 4-Theme Sticky Gutter Tokens
```css
/* Liquid Glass (Dark Default) */
.code-line-numbers {
position: sticky;
left: 0;
z-index: 10;
background: rgba(11, 15, 25, 0.96);
backdrop-filter: blur(16px);
-webkit-backdrop-filter: blur(16px);
border-right: 1px solid var(--border-glass);
box-shadow: 4px 0 16px rgba(0, 0, 0, 0.45);
}

/* Fluent Aero Mica */
[data-theme="mica"] .code-line-numbers {
background: rgba(248, 250, 252, 0.96);
border-right-color: rgba(0, 0, 0, 0.12);
box-shadow: 4px 0 16px rgba(0, 0, 0, 0.08);
color: #64748b;
}

/* Holo Cyberpunk */
[data-theme="holo"] .code-line-numbers {
background: rgba(13, 6, 32, 0.96);
border-right-color: rgba(236, 72, 153, 0.35);
box-shadow: 4px 0 20px rgba(236, 72, 153, 0.25);
color: #f472b6;
}

/* Matrix Obsidian */
[data-theme="matrix"] .code-line-numbers {
background: rgba(0, 15, 5, 0.96);
border-right-color: rgba(34, 197, 94, 0.35);
box-shadow: 4px 0 20px rgba(34, 197, 94, 0.25);
color: #86efac;
}
```

---

## 4. Backend API Contract (`POST /api/ide/open`)

### Request
```http
POST /api/ide/open HTTP/1.1
Content-Type: application/json

{
"editor": "vscode",
"path": "/Users/aparv/.../tools/session-explorer/src/server.go",
"line": 42
}
```

### Response (Success)
```json
{
"success": true,
"message": "Opened file in Visual Studio Code at line 42",
"editor": "vscode",
"command": "code -g /Users/aparv/.../tools/session-explorer/src/server.go:42"
}
```

### Response (Fallback / Binary Missing)
```json
{
"success": false,
"message": "Editor executable 'code' not found in server PATH",
"fallback_uri": "vscode://file//Users/aparv/.../tools/session-explorer/src/server.go:42",
"command": "code -g /Users/aparv/.../tools/session-explorer/src/server.go:42"
}
```
19 changes: 19 additions & 0 deletions tools/session-explorer/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.5.3] - 2026-11-10

### Fixed
- **Front-Pinned Hunk Controls & Spatial Visibility (R-078, AC-205..AC-209)**:
- Re-architected `.diff-hunk-header` in unified and split diff views to place `[Hunk #]` and `[📋 Hunk]` at the very front (left edge), followed by the isolated range `[@@ -old,len +new,len @@]` and a flexible `[⚡ AST Symbol]` pill with truncation ellipsis.
- Eliminated horizontal off-screen clipping where copy buttons were pushed to $x > 440\text{px}$ on narrower panes or long line headers. Core controls are pinned at `left: 0` (`z-index: 6`) and stay immediately accessible across all viewport splits (20% to 80%).
- **Bi-Pane Horizontal Scroll Auto-Reset & Jitter Elimination (R-074, AC-186..AC-191)**:
- Removed `transform: scale(1.02)` and `scale(1.01)` from `@keyframes jumpPulseAnim`, completely eliminating code line bounding box expansion and browser scroll engine twitches during line pulses.
- Implemented `resetPanesHorizontalScroll()` and wired it into `stepToHunk`, `stepReviewScrubber`, `jumpToFileViewerLine`, diff line clicks, and hunk header clicks, ensuring both panes always default to `scrollLeft = 0`.
- **Zero-Drift Sticky Gutters on Horizontal Scroll (R-075, AC-192..AC-195)**:
- Set `.file-viewer-code-container` to `min-width: 100%; width: max-content;` and pinned `.code-line-numbers` at `position: sticky; left: 0; z-index: 10;`, maintaining 0.00px gutter drift even under extreme horizontal scrolling.

### Added
- **Automated Host-Wide Desktop IDE Auto-Discovery Engine (R-076, R-077, AC-196..AC-204)**:
- Implemented `ide_detector.go` probing `/Applications`, `~/Applications`, and system `$PATH` for 9 desktop IDEs (VS Code, IntelliJ IDEA, GoLand, PyCharm, WebStorm, Sublime Text, Antigravity IDE, Xcode, System Default).
- Added REST endpoints `GET /api/ide/detected` and `POST /api/ide/open` with native OS process execution and fallback browser protocol URI schemes.
- Mounted split dropdown cockpit in the File Viewer header with glowing `● Installed` badges and 1-click CLI launch command copying.


## [0.5.2] - 2026-11-09

### Fixed
Expand Down
14 changes: 7 additions & 7 deletions tools/session-explorer/CONTEXT.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
tool: session-explorer
status: released
last_session: 2026-11-09
status: review
last_session: 2026-11-10
last_agent: "Antigravity"
blockers: []
---
Expand All @@ -16,19 +16,19 @@ blockers: []

## Current State

- **SDLC Phase**: `released`
- **Version**: 0.5.2
- **SDLC Phase**: `review`
- **Version**: 0.5.3
- **Language**: Go 1.22+ (backend) + vanilla HTML/CSS/JS (frontend, Bun-bundled)
- **Category**: GenAI & ML

### Progress

| Metric | Done | Total | Status |
|--------|------|-------|--------|
| Spec Requirements (R-XXX) | 72 | 72 | 🟢 100% Verified (R-001..R-072) |
| Acceptance Criteria (AC-XXX) | 185 | 185 | 🟢 100% Verified (AC-001..AC-185) |
| Spec Requirements (R-XXX) | 79 | 79 | 🟢 100% Verified (R-001..R-079) |
| Acceptance Criteria (AC-XXX) | 209 | 209 | 🟢 100% Verified (AC-001..AC-209) |
| Non-Functional (NF-XXX) | 9 | 9 | 🧪 100% Verified |
| Test Coverage | 100% | 100% | 🧪 42 Go unit tests passing + Playwright verified |
| Test Coverage | 100% | 100% | 🧪 44 Go unit tests passing + Playwright verified |
| Documentation | Complete | — | ✅ PRD, Spec, STATUS, DEVLOG, CONTEXT, README updated |

---
Expand Down
Loading
Loading