Skip to content
ZincGitHubDownload

Layouts phase 2: docking (work plan and contract)

View as Markdown

Phase 2 of layouts.md (section 13): tab stacks, drag to dock, item pane sections as panes, keyboard move menus, undo. Phase 1 (commit e1269b7) draws the library from the layout model; read layouts.md sections 3 to 6 and 10 first.

The work is split between four agents, each on its own branch and worktree, cut from claude/layouts-phase2. Each agent owns a set of files. Do not edit a file another agent owns; if you need a change there, write it in your hand-over note and work around it (a local adapter in your own file). The base branch already contains the shared contract below, so every branch compiles on its own.

Shared contract (already on the base branch)

gpui-ui/src/shell/frameLayout.ts (pure model):

  • DropTarget: { kind: "tab", column, stack, index? } | { kind: "split", column, at } | { kind: "section" }. Indexes are the layout BEFORE the move.
  • movePane(l, id, to), canMove(l, id, to), setStackActive(l, id), locatePane(l, id).
  • sectionPaneId("tags") === "section:tags", isSectionPane, sectionIdOf.

gpui-ui/src/shell/layout.ts (the library’s store; the only place that writes the layout):

  • moveLibraryPane(id, to): boolean (undoable), activateLibraryPane(id), hideLibraryPane(id, hide) (undoable), undoLayout(): boolean, canUndoLayout(), libraryPaneLocation(id), libraryLayout(), setLibraryLayout(l).
  • Built-in library pane ids: items, item, and section:<id> for every id in shell/sidebarLayout.ts RIGHT_PARTS.

gpui-ui/src/shell/dock.tsx (stub, implemented by dock):

  • registerDropHost(spec: () => DropHostSpec, el): unregister, with DropHostSpec = stack / empty-right / section-gap.
  • paneDragSource(id: () => string) returns { onMouseDown, onMouseMove, onMouseUp, wasDrag } to spread on a drag source.
  • paneDragging(): string | null, DockOverlay() (mounted once by Frame).

gpui-ui/src/shell/sectionPanes.tsx (stub, implemented by sections):

  • isDetached(sectionId), detachSection(sectionId, to?), returnSection(sectionId, before?).

Decisions for this phase

  • Every stack draws a header row above its pane’s card, on the canvas colour, 26 px high: with one pane, its icon and title (muted) and a ⋯ menu button; with several, a tab strip (icon + title per tab, the active one raised as the top bar’s tabs are). The header is the drag source and the place the pane menu opens from. It replaces nothing inside the panes (the item list keeps its toolbar; the item pane keeps its own header).
  • Pane menu (right click or ⋯ on a header or tab, Shift+F10 / Menu key on a focused tab): Move to ▸ Centre column / Right column; Stack with ▸ (each other visible stack, by its active pane’s title); Move up / Move down (within the column); for a section: pane, Return to item pane; Hide (not for required panes).
  • Undo: a toast “Moved ” with an Undo action after every drop and menu move (undoLayout). No global undo key.
  • Nothing is removed from the tree to hide it. A move must insert the pane element into its new place before its old wrapper is removed (see layouts.md section 5: GPUIX destroys a removed element’s native state).

Agents, files and done criteria

model (frameLayout + layout store + splitter keyboard)

Owns: shell/frameLayout.ts, shell/frameLayout.test.ts, shell/frameLayout.fuzz.test.ts, shell/layout.ts, ui/resizable.tsx, new shell/layoutActions.ts.

  • Unit tests for movePane / canMove / setStackActive / locatePane (every target kind, same-stack reorder, same-column split above and below its own stack, the centre-never-empty rule, hidden panes shown on move, required panes).
  • Fuzz: random sequences of moves, activations and hides from any normalised layout keep checkValid; movePane never throws; a disallowed move returns the same object.
  • Tests for the store: moveLibraryPane + undoLayout round trip (run with ZN_UI_STATE=off).
  • ui/resizable.tsx: keyboard resizing. The handle is focusable, role="separator", aria-orientation, aria-valuenow (percent); arrows move 2%, Shift+arrows 10%, Home / End to the minimum / maximum. Find how GPUIX elements take focus and keys (look at existing focusable controls in ui/controls.tsx, sidebar/, cards/).
  • shell/layoutActions.ts: app actions (registerAppAction, see registry.ts and shell/layout.ts for examples): “Undo layout change” (no default key), “Reset pane sizes”, “Reset layout to Standard”. Load it with an import at the end of shell/layout.ts (App.tsx belongs to stacks).

stacks (Frame, headers and tabs, pane menu, F6)

Owns: shell/Frame.tsx, new shell/PaneStack.tsx, shell/builtinPanes.tsx, App.tsx, scripts/shot-app.tsx.

  • PaneStack: header / tab strip as decided above; tab click = activateLibraryPane; spreads paneDragSource(() => id) on each tab and on the single-pane header; registers its host with registerDropHost(() => ({ kind: "stack", column, stack }), el).
  • Frame: renders stacks through PaneStack; moves panes without rebuilding them (insert before remove). Mounts <DockOverlay /> once. Registers the empty right column as { kind: "empty-right" } while it is empty.
  • Pane menu (see decisions) built from canMove so impossible entries are disabled; menu moves call moveLibraryPane and show the undo toast.
  • F6 / Shift+F6: focus the next / previous visible pane (reading order); remember the focused element per pane if GPUIX allows; register as app actions.
  • Pane hosts: role="region", aria-label = pane title; tab strip role="tablist", tabs role="tab".
  • scripts/shot-app.tsx: add --move (scroll the list, move item into a tab beside items and back, through the menu functions: host ids unchanged and list scroll kept, as --toggle checks) and --tabs (screenshots of a stack with two tabs, light and dark).

dock (drag to dock)

Owns: shell/dock.tsx, dnd.ts, features/cite/dragout.ts, new scripts/shot-dock.tsx.

  • Implement the dock.tsx contract: pane drags through dnd.ts (add { kind: "pane"; id: string } to DragPayload; dragout.ts’s OS hand-off must ignore pane drags); a window-sized pointer-capture layer while dragging (as Resizable does), drop zones from the registered hosts’ bounds read at drag start (ui/core.ts boundsOf): stack top 25% = split above, bottom 25% = split below, middle = tab; section gaps; the empty-right strip (a 48 px strip at the window’s right edge, shown only while dragging and only when registered).
  • Preview: fill the target area with the primary colour at low alpha; a ghost label with the pane title follows the pointer.
  • Escape or release over no target cancels. A drop calls moveLibraryPane (or, for a section dropped on a section gap, returnSection(sectionId, before); for a section not yet detached dropped on a stack, moveLibraryPane("section:<id>", …)), then shows the undo toast.
  • scripts/shot-dock.tsx: a headless test that registers hosts as the real app does (mount <App/> through scripts/shell-shot-lib.tsx), drags the item pane’s header with nativeSimulateMouseDown/Move/Up onto the bottom quarter of the items stack, and checks the resulting layout; screenshots mid-drag (preview visible) and after. If stacks has not landed headers yet on your branch, call paneDragSource from a small test harness instead and say so in your note.

sections (item pane sections as panes)

Owns: shell/sectionPanes.tsx, everything under itempane/, settings/defs/sidebars.tsx, new scripts/shot-sections.tsx.

  • A per-view item model so a detached section shows the same item as the item pane, also while item is hidden (itempane/model.tsx holds most of it; lift what ItemPane creates into something both use).
  • Register a pane section:<id> (registerPane in shell/panes.ts, views: ["library"]) for each built-in section, and for plugin sections (wasmplugins/extend/Sections.tsx) as section:plug:<plugin>:<id>; title and icon from the section. Its content: the section’s own component, in its own small virtual list for Info (several entries).
  • The item pane leaves detached sections out of its body and its section tab row.
  • Section headers in the item pane are drag sources (paneDragSource(() => sectionPaneId(id))) and register section gaps as drop hosts ({ kind: "section-gap", before }); a header menu entry “Open in its own pane” calls detachSection.
  • returnSection(id, before) puts the section back at that place in shell.itempaneLayout order (rightLayout in shell/sidebarLayout.ts; do not change that file’s API, it belongs to no agent: call rightLayout.set).
  • Settings > Appearance > Sidebars: a detached section shows “In its own pane” and a “Return to item pane” button.
  • scripts/shot-sections.tsx: detach Tags and Abstract into the right column (through detachSection), screenshot with an item selected; return one; check the item pane’s section list each time.

Rules for every agent

  • Work only in your worktree (C:\Users\abora\zotero-next\.claude\worktrees\layouts-p2-<agent>), on your branch (claude/layouts-p2-<agent>). Commit there when done; never merge, push, switch branches or touch main.
  • Bun only: bun check (typecheck), bun test. Never npm, npx, node, bun install, bun add, bun remove. node_modules, core/vendor are junctions to the main checkout: never delete them.
  • Never open or write data/library.sqlite or anything under C:\Users\abora\Zotero\; never use ports 23119 / 23120.
  • No windows on the screen: check UI only with the headless GPUIX scripts (scripts/shell-shot-lib.tsx, createTestRoot). A core on a library copy is running at http://127.0.0.1:23165 for screenshots: ZN_URL=http://127.0.0.1:23165, and set ZN_SHOTS to your own folder: C:\Users\abora\AppData\Local\Temp\claude\layouts-p2\<agent>.
  • Done means: bun check clean in gpui-ui, the full bun test in gpui-ui passing (67 plugin tests included), your own tests and shots, one commit (or a few) on your branch, and a hand-over note at C:\Users\abora\AppData\Roaming\Claude\side-session-notes\local_f33c2830-2344-4819-9bb4-d646b2b1074e\layouts-p2-<agent>.md: what you built, files, how you verified it (with screenshot paths), anything another agent’s file needs, and open issues.
  • Code style: follow the files around you (comment headers that say what a file does, tabs, the t() / tok() style helpers, testId props for headless checks). Keep comments plain and short.

Outcome (2026-11-18)

Built by four GPT-6.1 Sol agents (Paseo, OMP) on claude/layouts-p2-{model,stacks,dock,sections}, merged into claude/layouts-phase2 with these integration fixes:

  • Section headers: the drag and collapse handlers sit on the title area, not the whole row. In GPUIX a row with mouse-down / mouse-move listeners swallows the clicks of the buttons inside it (the section menu stopped working). The title area also spreads the drag source’s onMouseUp: without it, a section dragged out of the item pane showed the preview but never dropped.
  • scripts/shot-dock.tsx drives the real tabs, headers and gaps (the agents’ version used test-only drop hosts).
  • The agents’ commit tool stored files with CRLF; they are stored with LF again.

Checks: bun check clean; bun test 605 pass, 6 skip, 0 fail (67 plugin tests included); scripts/shot-app.tsx --move --focus --tabs --toggle (49 checks: moves and hides keep pane host ids, list scroll and pixels), --stacked --drag; scripts/shot-sections.tsx (90 checks); scripts/shot-dock.tsx (split, tab, Escape, Undo, host ids, list scroll, a list click after a move, a section dragged out and back).

Open issues:

  • In the headless renderer, a click on a button inside the item pane’s virtual list does not arrive after that list was scrolled (by scrollToItem or the wheel); clicks at the list’s top position work. Not seen to be layout-specific; check in the real window before treating it as a bug.
  • GPUIX 0.11 drops aria-orientation and aria-valuenow before they reach the native tree; splitters expose the value through aria-valuetext and the keys through aria-description instead.
  • Undo covers the layout only: returning a section to the item pane also changes shell.itempaneLayout order (and plugin section anchors, shell.itempanePluginPositions), which undoLayout does not restore.
  • Stack headers (26 px) are new above every pane card, including in Standard; review the look in the real window.
  • Agents in OMP use jj by default; the main checkout is a colocated jj repo, and jj run from a worktree nested under it acts on the main checkout. Tell agents not to use jj, or put agent worktrees outside the main checkout.

Revision after trying it (2026-11-18)

The user tried the phase 2 build in a dev window: everything worked, but the always-on header row above every pane, its tabs and the extra spacing did not look right, and “Items” / “Item” read as the same thing. Changes:

  • Clean by default, edit mode to customize (shell/layoutEdit.tsx). Panes draw no header in normal use, so the window looks as it did before layouts. A stack shows a tab strip only when it holds two or more panes (quiet tabs, the active one underlined). Edit layout mode shows every pane’s header (grip, title, ⋯ menu) and an outline, with a bar above the library (Reset, Done; Escape leaves). Entered from Settings or Tools > Edit layout. Item pane section titles stay draggable.
  • Names: the item list pane is titled by what it shows (My Library, the collection, the saved search, Trash, …); the item pane is “Item details”.
  • Settings > Appearance > Layout: Default layout (Standard, Stacked, Triage: LIBRARY_PRESETS in shell/frameLayout.ts), Customize… (edit mode), Reset layout. Choosing a default arranges the library that way; Reset returns to it (undoable).
  • GPUIX has no display: none that hides a subtree: hidden headers use HIDDEN from shell/kit.tsx.
  • test/log-preload.ts sets ZN_UI_STATE=off: test files share one process, and one that loaded store.ts first pointed later writes at the user’s real ui-state.json (a test run had written layout keys and a section order there; repaired, with a backup next to it).