Frontend: SplitPane layout component — draggable, collapsible, persistent

[frankbria]

Parent Issue

Part of #500 — used by #508 (sessions/[id] page)

Context

The /sessions/[id] page needs a side-by-side layout: agent chat on the left, terminal on the right. The divider should be draggable, each pane should be collapsible, and the split position should persist across page loads.

What to Build

New file: web-ui/src/components/sessions/SplitPane.tsx

Props:

interface SplitPaneProps {
  left: React.ReactNode;
  right: React.ReactNode;
  defaultSplit?: number;    // 0–100, default 45 (left gets 45%)
  minPanePercent?: number;  // minimum pane width %, default 15
  storageKey?: string;      // localStorage key for persistence, default "split-pane-position"
  className?: string;
}

Behavior:

• Horizontal split (left | divider | right)
• Draggable divider: mousedown on divider → mousemove on document → update split % → mouseup release
• Constrain to [minPanePercent, 100 - minPanePercent]
• Collapse buttons on each pane edge (chevron icons):
  • Left collapse: left pane shrinks to 0, right takes full width
  • Right collapse: right pane shrinks to 0, left takes full width
  • Click again to restore to last non-collapsed position
• Persist split position to localStorage[storageKey] on drag end
• Restore from localStorage on mount
• Smooth CSS transition: width 200ms only during collapse/expand (not during drag)
• Resize handle: 4px wide, hover: highlight with primary color, cursor: col-resize

Responsive:

• On narrow viewports (< 768px): stack vertically, hide divider
• In vertical mode: chat on top (60%), terminal on bottom (40%)

Acceptance Criteria

• Dragging the divider updates pane widths in real-time
• Drag is smooth (no jank from state updates during mousemove — use ref for position, flush to state on mouseup)
• Collapse/expand buttons work for each pane
• Position persists in localStorage across page reloads
• Minimum pane width is enforced (no pane collapses to < 15% via drag)
• Transition is smooth on collapse/expand, absent during drag
• On mobile (< 768px): vertical stack layout

Notes

• This is a general-purpose component — keep it generic, no session-specific logic
• No external drag library needed; native mouse events are sufficient
• Reference: Optio apps/web/src/components/split-pane.tsx for the approach

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The target file is web-ui/src/components/sessions/SplitPane.tsx (under file:web-ui/src/components/). The project uses React 19 + Next.js 16, Tailwind CSS v3 with CSS custom properties for theming (--primary, --border, etc.), clsx/tailwind-merge via cn() from file:web-ui/src/lib/utils.ts, and @hugeicons/react for icons (e.g. ArrowLeft01Icon, ArrowRight01Icon are already used in the codebase). No external drag library is present or needed. All components use 'use client' when they need browser APIs.

Approach

Create a single self-contained SplitPane.tsx client component. State management uses a useRef for the live drag position (no re-renders during mousemove) and useState only for the committed split value (flushed on mouseup). A separate boolean ref tracks whether a transition should be applied, enabling smooth CSS transitions only during collapse/expand. This matches the "no jank" acceptance criterion and the pattern used in the referenced Optio component.

---

Implementation Steps

1. Create file:web-ui/src/components/sessions/SplitPane.tsx

Structure overview:

sequenceDiagram
    participant User
    participant Divider
    participant SplitPane
    participant localStorage

    User->>Divider: mousedown
    Divider->>SplitPane: start drag (set isDragging ref, disable transition ref)
    User->>SplitPane: mousemove on document
    SplitPane->>SplitPane: clamp & apply width via DOM ref (no setState)
    User->>SplitPane: mouseup
    SplitPane->>SplitPane: flush ref value → setState(splitPct)
    SplitPane->>localStorage: persist splitPct

    User->>SplitPane: click collapse button (left or right)
    SplitPane->>SplitPane: enable transition ref, setState(0 or 100)
    SplitPane->>localStorage: persist new value

Loading

Props interface (exactly as specified in the ticket):

• left: React.ReactNode
• right: React.ReactNode
• defaultSplit?: number — defaults to 45
• minPanePercent?: number — defaults to 15
• storageKey?: string — defaults to "split-pane-position"
• className?: string

Refs needed:

• containerRef — useRef<HTMLDivElement> pointing to the outer flex container, used to compute drag percentages from clientX
• leftPaneRef — useRef<HTMLDivElement> for direct DOM width mutation during drag (avoids React re-renders)
• rightPaneRef — useRef<HTMLDivElement> for the same reason
• isDragging — useRef<boolean> flag
• livePercent — useRef<number> stores the current drag value before flush
• lastNonCollapsed — useRef<number> stores the last non-zero/non-100 split for restore on collapse toggle
• transitionEnabled — useRef<boolean> controls whether CSS transition is active; set to false during drag, true during collapse/expand

State:

• splitPct: number — the committed split percentage (drives initial render and re-renders after drag end / collapse)
• isLeftCollapsed: boolean
• isRightCollapsed: boolean

On mount:

• Read localStorage[storageKey]; if a valid number is found, use it as the initial splitPct (overriding defaultSplit)

Drag logic (attach/detach on mount via useEffect):

• onMouseDown on the divider element: set isDragging.current = true, set transitionEnabled.current = false, remove the transition class from both pane refs directly
• onMouseMove on document: if isDragging.current, compute newPct = (e.clientX - containerRect.left) / containerRect.width * 100, clamp to [minPanePercent, 100 - minPanePercent], store in livePercent.current, and directly set leftPaneRef.current.style.width and rightPaneRef.current.style.width (no setState)
• onMouseUp on document: if isDragging.current, set isDragging.current = false, call setSplitPct(livePercent.current), update lastNonCollapsed.current, persist to localStorage

Collapse logic:

• Left collapse button: set transitionEnabled.current = true, add transition class to pane refs, set isLeftCollapsed(true), setSplitPct(0); if already collapsed, restore setSplitPct(lastNonCollapsed.current), setIsLeftCollapsed(false)
• Right collapse button: mirror of the above with setSplitPct(100)
• Persist the resulting value to localStorage after each collapse/expand

Rendering:

• Outer container: flex flex-row w-full h-full with ref={containerRef}, apply className prop
• Left pane: ref={leftPaneRef}, inline style={{ width: splitPct + '%' }}, overflow-hidden, flex-shrink-0; when splitPct === 0 add hidden or overflow-hidden w-0
• Divider: w-1 cursor-col-resize bg-border hover:bg-primary flex-shrink-0 relative, 4px wide; contains the collapse chevron buttons absolutely positioned on each edge
  • Left chevron button (collapses/restores left pane): uses ArrowLeft01Icon / ArrowRight01Icon from @hugeicons/react
  • Right chevron button (collapses/restores right pane): uses ArrowRight01Icon / ArrowLeft01Icon
• Right pane: ref={rightPaneRef}, inline style={{ width: (100 - splitPct) + '%' }}, overflow-hidden, flex-shrink-0

Transition handling:

• During collapse/expand: add transition-[width] duration-200 Tailwind class (or inline style={{ transition: 'width 200ms' }}) to both pane refs
• During drag: remove that transition so width updates are instant

Responsive (mobile < 768px):

• Wrap the entire component in a container that switches from flex-row to flex-col at the md breakpoint using Tailwind: flex flex-col md:flex-row
• In column mode, hide the divider with hidden md:flex
• Left pane gets h-[60%] w-full md:h-full md:w-auto
• Right pane gets h-[40%] w-full md:h-full md:w-auto
• The inline width style should only apply on md+; use a useEffect + window.matchMedia('(min-width: 768px)') listener to toggle whether inline styles are applied, or conditionally set them based on a isMobile state

Icon usage (consistent with existing codebase):

• Import ArrowLeft01Icon, ArrowRight01Icon from @hugeicons/react — these are already used in file:web-ui/src/components/review/DiffNavigation.tsx

Utility:

• Use cn() from file:web-ui/src/lib/utils.ts for conditional class merging

---

2. No other files need modification

SplitPane is a generic layout primitive. It will be consumed by the sessions page (issue #508) without any changes to existing files.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The target file is `web-ui/src/components/sessions/SplitPane.tsx` (under `file:web-ui/src/components/`). The project uses **React 19 + Next.js 16**, **Tailwind CSS v3** with CSS custom properties for theming (`--primary`, `--border`, etc.), `clsx`/`tailwind-merge` via `cn()` from `file:web-ui/src/lib/utils.ts`, and `@hugeicons/react` for icons (e.g. `ArrowLeft01Icon`, `ArrowRight01Icon` are already used in the codebase). No external drag library is present or needed. All components use `'use client'` when they need browser APIs.

## Approach

Create a single self-contained `SplitPane.tsx` client component. State management uses a `useRef` for the live drag position (no re-renders during `mousemove`) and `useState` only for the committed split value (flushed on `mouseup`). A separate boolean ref tracks whether a transition should be applied, enabling smooth CSS transitions only during collapse/expand. This matches the "no jank" acceptance criterion and the pattern used in the referenced Optio component.

---

## Implementation Steps

### 1. Create `file:web-ui/src/components/sessions/SplitPane.tsx`

**Structure overview:**

```mermaid
sequenceDiagram
    participant User
    participant Divider
    participant SplitPane
    participant localStorage

    User->>Divider: mousedown
    Divider->>SplitPane: start drag (set isDragging ref, disable transition ref)
    User->>SplitPane: mousemove on document
    SplitPane->>SplitPane: clamp & apply width via DOM ref (no setState)
    User->>SplitPane: mouseup
    SplitPane->>SplitPane: flush ref value → setState(splitPct)
    SplitPane->>localStorage: persist splitPct

    User->>SplitPane: click collapse button (left or right)
    SplitPane->>SplitPane: enable transition ref, setState(0 or 100)
    SplitPane->>localStorage: persist new value
```

**Props interface** (exactly as specified in the ticket):

- `left: React.ReactNode`
- `right: React.ReactNode`
- `defaultSplit?: number` — defaults to `45`
- `minPanePercent?: number` — defaults to `15`
- `storageKey?: string` — defaults to `"split-pane-position"`
- `className?: string`

**Refs needed:**

- `containerRef` — `useRef<HTMLDivElement>` pointing to the outer flex container, used to compute drag percentages from `clientX`
- `leftPaneRef` — `useRef<HTMLDivElement>` for direct DOM width mutation during drag (avoids React re-renders)
- `rightPaneRef` — `useRef<HTMLDivElement>` for the same reason
- `isDragging` — `useRef<boolean>` flag
- `livePercent` — `useRef<number>` stores the current drag value before flush
- `lastNonCollapsed` — `useRef<number>` stores the last non-zero/non-100 split for restore on collapse toggle
- `transitionEnabled` — `useRef<boolean>` controls whether CSS transition is active; set to `false` during drag, `true` during collapse/expand

**State:**

- `splitPct: number` — the committed split percentage (drives initial render and re-renders after drag end / collapse)
- `isLeftCollapsed: boolean`
- `isRightCollapsed: boolean`

**On mount:**

- Read `localStorage[storageKey]`; if a valid number is found, use it as the initial `splitPct` (overriding `defaultSplit`)

**Drag logic (attach/detach on mount via `useEffect`):**

- `onMouseDown` on the divider element: set `isDragging.current = true`, set `transitionEnabled.current = false`, remove the transition class from both pane refs directly
- `onMouseMove` on `document`: if `isDragging.current`, compute `newPct = (e.clientX - containerRect.left) / containerRect.width * 100`, clamp to `[minPanePercent, 100 - minPanePercent]`, store in `livePercent.current`, and directly set `leftPaneRef.current.style.width` and `rightPaneRef.current.style.width` (no `setState`)
- `onMouseUp` on `document`: if `isDragging.current`, set `isDragging.current = false`, call `setSplitPct(livePercent.current)`, update `lastNonCollapsed.current`, persist to `localStorage`

**Collapse logic:**

- Left collapse button: set `transitionEnabled.current = true`, add transition class to pane refs, set `isLeftCollapsed(true)`, `setSplitPct(0)`; if already collapsed, restore `setSplitPct(lastNonCollapsed.current)`, `setIsLeftCollapsed(false)`
- Right collapse button: mirror of the above with `setSplitPct(100)`
- Persist the resulting value to `localStorage` after each collapse/expand

**Rendering:**

- Outer container: `flex flex-row w-full h-full` with `ref={containerRef}`, apply `className` prop
- Left pane: `ref={leftPaneRef}`, inline `style={{ width: splitPct + '%' }}`, `overflow-hidden`, `flex-shrink-0`; when `splitPct === 0` add `hidden` or `overflow-hidden w-0`
- Divider: `w-1 cursor-col-resize bg-border hover:bg-primary flex-shrink-0 relative`, 4px wide; contains the collapse chevron buttons absolutely positioned on each edge
  - Left chevron button (collapses/restores left pane): uses `ArrowLeft01Icon` / `ArrowRight01Icon` from `@hugeicons/react`
  - Right chevron button (collapses/restores right pane): uses `ArrowRight01Icon` / `ArrowLeft01Icon`
- Right pane: `ref={rightPaneRef}`, inline `style={{ width: (100 - splitPct) + '%' }}`, `overflow-hidden`, `flex-shrink-0`

**Transition handling:**

- During collapse/expand: add `transition-[width] duration-200` Tailwind class (or inline `style={{ transition: 'width 200ms' }}`) to both pane refs
- During drag: remove that transition so width updates are instant

**Responsive (mobile < 768px):**

- Wrap the entire component in a container that switches from `flex-row` to `flex-col` at the `md` breakpoint using Tailwind: `flex flex-col md:flex-row`
- In column mode, hide the divider with `hidden md:flex`
- Left pane gets `h-[60%] w-full md:h-full md:w-auto`
- Right pane gets `h-[40%] w-full md:h-full md:w-auto`
- The inline `width` style should only apply on `md+`; use a `useEffect` + `window.matchMedia('(min-width: 768px)')` listener to toggle whether inline styles are applied, or conditionally set them based on a `isMobile` state

**Icon usage** (consistent with existing codebase):

- Import `ArrowLeft01Icon`, `ArrowRight01Icon` from `@hugeicons/react` — these are already used in `file:web-ui/src/components/review/DiffNavigation.tsx`

**Utility:**

- Use `cn()` from `file:web-ui/src/lib/utils.ts` for conditional class merging

---

### 2. No other files need modification

`SplitPane` is a generic layout primitive. It will be consumed by the sessions page (issue #508) without any changes to existing files.

---

Execution Information

Branch: main
Commit: cb074e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.