# Rail hover peek — pattern

> **Agents:** `.cursor/rules/exxat-rail-hover-peek.mdc` · `.cursor/skills/exxat-sidebar-nav/SKILL.md`

**Job:** a user who collapsed a rail to icons for canvas space can still read and use it without committing to expand it. Hover (or keyboard focus) the rail → the full panel floats over the page; leave → it goes away. Nothing reflows, nothing is persisted.

## Where it applies

| Rail | Component | Peek surface |
|------|-----------|--------------|
| Primary sidebar (icon mode) | `packages/ui/src/components/ui/sidebar.tsx` (`Sidebar`) | The same container, restyled flush + shadow, above the secondary rail |
| Secondary panel (compact strip) | `packages/ui/src/components/shell/secondary-panel.tsx` (`SecondaryPanelPeek`) | A `fixed` panel measured from the strip, full `SecondaryPanelFrame` |
| Drill-in (Settings, Tokens, …) | `packages/ui/src/components/ui/sidebar-drill-in.tsx` | Rides the primary peek — it lives inside the primary rail, no extra code |

Mobile / ≥200 % zoom is **not** peek: it keeps the scrim sheet (`isNavFlyout`).

## Behavior

- `useHoverPeek(enabled)` → `{ peek, handlers, dismiss }`. Spread `handlers` on the rail root.
- 120 ms open intent delay, 180 ms close grace, instant on keyboard `:focus-visible`, Esc dismisses, touch ignored.
- Primary: provider override makes `useSidebar().state === "expanded"` for descendants; `data-peek="true"` on the `[data-slot="sidebar"]` root; the layout gap stays at `--sidebar-width-icon`.
- Secondary: peek renders `SecondaryPanelFrame forceExpanded` inside a context with `secondaryPanelCompact: false`.

## Motion

`.rail-peek-reveal` — clip-path reveal from the rail's width (`--peek-from`) to full, 140 ms, `cubic-bezier(0.2, 0, 0, 1)`, `backwards` fill, off under `prefers-reduced-motion`. Width animation is banned (re-wraps text each frame).

## Look

Flush, square, full height, `--shadow-sheet-flyout`; secondary uses `--secondary-panel-bg` + `border-e border-sidebar-border`. Elevation order is unchanged (sidebar 0 → secondary 1 → canvas 2).

## Extending to a new rail

1. Pick `enabled` = "rail is collapsed to icons on desktop".
2. `const { peek, handlers } = useHoverPeek(enabled)`; spread on the rail root.
3. Render the **real** expanded body (force-expanded context), not a copy of the icon strip.
4. Float it (`fixed` + measured rect, or restyle the container), keep layout width unchanged, add `rail-peek-reveal` with `--peek-from`.
5. Raise z-index above neighbouring rails; add the rule's **Verify** steps to your PR.

## Gotchas learned

- Gap/width driven by `data-collapsible` — flipping it to expanded pushes neighbours; pin the gap with `group-data-[peek=true]`.
- Shell rails are `z-10`; a plain `z-30` on the primary peek still painted under the secondary.
- `animation-fill-mode: both` leaves `clip-path: inset(0)` and chops the shadow.
- Content-based panel bodies read `secondaryPanelCompact` themselves — override the context, don't just widen the box.
