Skip to content
ZincGitHubDownload

Customizable panes and layouts (design sketch)

View as Markdown

Status: proposal, nothing built. This page describes how Zinc could let users rearrange the window’s panes, save the arrangement as a named layout, and switch between layouts. It starts from the shell as it is on main (e89497a) and keeps WASM plugin panes inside the same model.

Decisions so far (2026-11-18)

  • Drag-to-dock ships in the first release, with menu and keyboard equivalents for every move.
  • Fixed frame. The left sidebar stays as it is (collections, saved searches, groups, tags; show/hide and width only). The centre and right columns are the dock: they can be split, and panes can be dragged between them.
  • Item pane sections are draggable too: a section can leave the item pane and become a pane of its own, or be dragged back.
  • The reader gets a context pane (Zotero’s item/notes pane beside the document) as part of this work.
  • A standalone notes pane is built as part of this work.
  • Left-side plugin panels stay outside the dock, next to the sidebar (section 7).
  • The item list can move: it may sit in the centre or the right column.
  • Layouts switch by hand only; nothing changes the layout automatically.
  • Plugins may ship named layouts (section 7.1).
  • No sync: layouts stay per machine in ui-state.json.
  • Panes can open in their own OS window (section 11), as a later phase, from the menu or by dropping a dragged pane outside the main window. A second full library window is not wanted.

1. What the shell does today

Piece Where What is customizable now
Library tab: sidebar, item list card, item pane card in one row App.tsx (LibraryPanels) Show/hide sidebar and item pane (shell.panelLeft, shell.panelRight); column fractions per visibility combination (shell.cols.11/10/01/00)
Row resizing ui/resizable.tsx (Resizable) Horizontal only: fractions plus per-panel minimum fractions, 12 px gutter
Sidebar groups (Library, Saved Searches, Collections, Groups, Tags) Sidebar.tsx, shell/sidebarLayout.ts Order and hidden set (shell.sidebarLayout); Tags is pinned last
Item pane sections itempane/index.tsx, shell/sidebarLayout.ts Order and hidden set (shell.itempaneLayout); plugin sections always come after the built-in ones. The body is one <virtual-list> whose entries are the Info section’s header and rows, then one entry per other section
Reader: left sidebar (thumbnails, outline, plugin panels), document reader/Reader.tsx, reader/core/state.ts Sidebar open, tab and width, in reader-state.json
Plugin side panels wasmplugins/extend/Chrome.tsx (PluginSidePanels) Fixed side, defaultWidth, minWidth; shown/hidden through panelOpen, which lives in memory only
Plugin tabs, banners wasmplugins/extend/Chrome.tsx Not layout: they are top-level tabs and a strip above the tab bar
Drag and drop dnd.ts Mouse-gesture drags (GPUIX has no HTML5 drag and drop); one payload kind, items

Every “shell.*” key goes through shell/prefs.ts (persisted, getPref, setPref) into ui-state.json, whose single writer is uiState in store.ts.

Constraints that shape the design:

  • Remounting is visible. LibraryPanels is keyed by the visibility combination, so toggling a panel rebuilds all three panels. Moving panes between containers must not do this: the item list would lose its scroll position and the reader its page bitmaps.
  • Cache regions. The sidebar, list body and item pane are each a GPUIX cacheRegion, which must take its size from its parent (100% or flex-grow). Every pane host has to keep that shape.
  • Rectangular clipping. GPUI clips to a rectangle, not the card’s rounded outline, so the pane chrome (card radius, tinted header) has to stay with the pane host, not with whatever the pane renders.
  • Keep-mounted tabs. Readers, the Library and plugin tabs stay mounted while hidden (HIDDEN). Layouts apply inside a tab; they do not replace the tab bar.

2. What becomes customizable

  1. Resize the three frame columns and every split inside the centre and right columns, remembered per layout.
  2. Show/hide any pane. A hidden pane keeps its place, so showing it again puts it back where it was.
  3. Drag to dock: drag a pane (by its tab) or an item pane section (by its header) to another place in the centre or right column: as a tab in an existing stack, or as a new stack above or below one.
  4. Split: a column holds one or more stacks one above the other (for example the item list above the item pane, as in Zotero’s Stacked view).
  5. Tabs: two or more panes in one stack share a small tab strip (for example item + notes + a plugin panel).
  6. Presets per view: the Library tab and the reader each have an active layout, picked from built-in presets or the user’s saved ones.

Not customizable: the left sidebar’s position (it can be shown, hidden and resized; its groups keep their own order setting), the top bar, the tab bar and banners. Not proposed: layouts for plugin tabs, automatic layout switching, and syncing layouts between machines.

Parity baseline. Zotero (7 onward, unchanged in 10) offers Standard and Stacked views (item pane beside or below the item list), toggles for the collections pane, item pane and tag selector, a reader sidebar, and a reader context pane showing the item pane or notes. The built-in presets cover all of these, so a Zotero user finds their layout with one click.

3. The frame

Each view has the same three columns:

┌──────────────┬──────────────────────────────┬──────────────────┐
│ left │ centre │ right │
│ (fixed │ ┌──────────────────────────┐ │ ┌──────────────┐ │
│ content) │ │ stack │ │ │ stack │ │
│ │ └──────────────────────────┘ │ ├──────────────┤ │
│ │ ┌──────────────────────────┐ │ │ stack │ │
│ │ │ stack │ │ └──────────────┘ │
│ │ └──────────────────────────┘ │ │
└──────────────┴──────────────────────────────┴──────────────────┘
View Left (fixed) Centre, by default Right, by default
Library Sidebar as today items item
Reader reader sidebar (thumbnails, annotations, outline, plugin reader panels) as today reader.doc ‹reader.item · notes›, hidden until opened, so the reader looks as it does now
  • The left column can be shown, hidden and resized. Its content is not a drop target and nothing is dragged out of it.
  • The view’s required pane (items or reader.doc) can sit in the centre or the right column, but cannot be hidden or sent to a separate window.
  • The centre column is never empty: a drag that would empty it is not offered (move another pane in first).
  • The right column may be empty, and then it collapses (today’s “item pane hidden”). While a drag is in progress, an empty right column shows a drop strip at the window’s right edge.
  • Columns split vertically only. There are never more than three columns, which keeps the frame predictable and the drop targets few.

4. Panes

A pane is a unit of content with an id, a title, an icon and a component. Panes are registered like app actions in registry.ts:

interface PaneDef {
id: string; // "items", "item", "notes", "section:tags", "reader.doc", "plugin:<plugin>:<panel>"
title: () => string;
icon: string;
views: ViewKind[]; // where it may appear: "library", "reader"
required?: boolean; // "items" in the library, "reader.doc" in the reader
minSize: { w: number; h: number }; // px, replaces the fraction minimums in App.tsx
render: (ctx: PaneContext) => JSX.Element;
}
Pane id Today Notes
items Toolbar + SortBar + CardList (or a virtual collection) Required in the library
item ItemPane Shows the sections that have not been dragged out
section:<id> One item pane section (info, abstract, notes, attachments, collections, tags, related, or plug:<plugin>:<id>) Exists only while the section is detached; see 4.1
notes none New: Zotero’s notes context pane. The selected item’s notes and all notes in the library, with search, opening a note in an editor inside the pane (reusing itempane/RichNote.tsx)
reader.doc Reader pages Required in the reader
reader.item none New: the item pane for the open document’s parent item, with the same sections. Plugin sections appear here, as wasm-plugins/extend.md already decided for reader tabs
plugin:<plugin>:<panel> PluginSidePanels with side: right See section 7

4.1 Sections as panes

A section dragged out of the item pane becomes the pane section:<id>:

  • It follows the same item as the item pane, so selection state moves out of the ItemPane component into a per-view provider (itempane/model.tsx already holds most of it). A detached section keeps working while item is hidden.
  • It renders the same component as inside the item pane. The Info section, which is several virtual-list entries, gets its own small virtual list in the detached pane.
  • Its header becomes the pane’s tab; it no longer collapses (hide it instead).
  • The item pane leaves it out of its list and its section tab row. Settings > Appearance > Sidebars shows it as “In its own pane” with a “Return to item pane” button.
  • Dragging it back onto the item pane (anywhere between two sections) returns it there, at that position. Dragging a section header up or down inside the item pane reorders sections, the same as the Settings arrows.
  • Each view detaches sections independently: detaching Tags in the library does not change the reader’s reader.item.
  • Plugin sections detach the same way; the plugin sees no difference (same item-pane-section surface and parameters).

5. Layout data model

interface Stack { panes: string[]; active: string }
interface Column { stacks: Stack[]; sizes: number[] } // top to bottom; sizes are fractions
interface ViewLayout {
left: { shown: boolean };
centre: Column;
right: Column; // may have no stacks
sizes: [number, number, number]; // left, centre, right fractions of the window width after gutters
hidden: string[]; // pane ids kept in place but not drawn
sectionOrder?: string[]; // item pane sections in this view, plugin sections included (see 4.1)
}
interface LayoutPreset {
id: string; // "builtin:standard", "user:3f2a…"
name: string;
builtin: boolean;
views: Partial<Record<ViewKind, ViewLayout>>; // a preset may cover only the library or only the reader
}

Rules, enforced by a normalizeLayout(value, panes) in the style of sidebarLayout.ts’s normalize:

  • Every pane id appears at most once per view. Unknown built-in ids are dropped.
  • A required pane missing from the layout is added back at the top of the centre column; it cannot be hidden.
  • A section:<id> pane and the same section inside the item pane never both exist: if both are stored, the pane wins.
  • Pane ids for plugin panels and plugin sections that are not registered (plugin disabled or not loaded yet) are kept as ghosts: not drawn, and their stack collapses if nothing else is in it, but the position is kept, so re-enabling the plugin restores it. Ghosts of uninstalled plugins are dropped when the plugin is removed.
  • Empty stacks are removed; a stack whose panes are all hidden is not drawn.
  • Sizes are fractions as Resizable uses now; pixel minimums come from PaneDef and win when the window is small.

sectionOrder also fixes today’s rule that plugin sections always come after the built-in ones: they get a stored position like any other section (with the ghost rule above).

Rendering without remounts

Each pane component is created once per view in its own Solid root (createRoot) and kept in a map by pane id. The renderer draws the frame and places the existing pane elements into stack hosts. Moving a pane re-parents its element; hiding it applies HIDDEN. This replaces the keyed LibraryPanels.

What @gpuix/solid 0.11 does (read from its host.js while building phase 1):

  • removeHostNode destroys the native element and its whole subtree (destroyElement). Inserting the same host node again creates a new native element, so native state (scroll offsets, cached views) is lost even though the Solid component survives.
  • insertHostNode on a node that is still mounted moves it: it is detached in JS and appended or inserted natively, with no destroy.

So phase 1 never removes anything to hide it: a hidden column, stack or pane stays mounted with display: none (Resizable has a shown prop for this). A move (phase 2) must insert the pane into its new place before its old wrapper is removed; that ordering is what the phase 0 spike still has to prove with Solid’s For.

Resizable gains a dir: "row" | "column" prop and keyboard resizing (section 10). A new PaneStack draws the tab strip when a stack holds more than one pane, and the pane’s header when it holds one.

6. Drag to dock

Built on dnd.ts, which already does mouse-gesture drags:

  • Sources: a stack’s tab (or the header of a single-pane stack), and an item pane section’s 36 px header. The drag starts after DRAG_THRESHOLD pixels, as list rows do. DragPayload gets a second kind, { kind: "pane"; id: string; fromSection?: boolean }. The OS drag-out hook (setDragHook, used for Quick Copy) must ignore this kind.

  • Pointer capture: a transparent window-sized layer while dragging, as Resizable uses for its handles, so the drag keeps working over any content (including a reader’s pages and plugin web views).

  • Drop targets, computed once at drag start from each stack host’s painted bounds (boundsOf):

    ┌───────────────────────────┐
    │ top band 25% │ → new stack above
    ├───────────────────────────┤
    │ │
    │ middle │ → add as a tab in this stack
    │ │
    ├───────────────────────────┤
    │ bottom band 25% │ → new stack below
    └───────────────────────────┘

    Plus: the gap between two sections inside item / reader.item (a section returns to the item pane there), and the right-edge strip when the right column is empty.

  • Feedback: the target area is filled with the primary tint at low opacity, and a ghost label (pane title) follows the pointer, as dragLabel does for items.

  • Cancel: Escape, or releasing over no target inside the window. Releasing outside the main window opens the pane in a new window (section 11, phase 7); until then it cancels.

  • Undo: after a drop, a toast offers Undo; the layout menu’s Revert returns to the saved preset.

7. Plugin panes

Plugins keep the API they have. register-side-panel (SidePanelRegistration: panelId, title, icon, side, defaultWidth, minWidth, tabKinds, defaultOpen) maps as follows:

  • side: right panels become dock panes with id plugin:<plugin>:<panelId> (the registry already keys by (plugin, id)). The first time one appears in a view it opens as a new stack at the bottom of the right column, shown if defaultOpen. After that the user’s layout wins. minWidth feeds PaneDef.minSize.w; defaultWidth is used only if the right column was empty and has to open.
  • side: left panels stay outside the dock, between the window edge and the sidebar as today, since the left column is fixed. They can be shown, hidden and resized, but not dragged. Their visibility persists like dock panes’.
  • tabKinds maps to views (library, reader); the default stays ["library"].
  • panelOpen becomes the pane’s entry in ViewLayout.hidden, so it persists (today it is lost on restart). set-side-panel-open from the plugin still shows or hides the pane in the active layout.
  • The content is still a PluginViewSlot with surface: "side-panel". params.side reports where the pane is now (right, centre or window).
  • Optional, additive WIT field (existing plugins keep working): placement: { beside: option<string> }, a pane id to open as a tab next to, such as item or notes.
  • Plugin item pane sections are sections, so they detach and dock as in 4.1. Plugin tabs stay top-level tabs.

7.1 Plugin layout presets

A plugin may register named layouts, for example a citation-graph plugin offering “Graph review” with its panel in the centre column below the item list.

  • New extend registration kind layout-preset: { preset-id, name: localized-string, views: string }, where views is a JSON object of ViewLayouts (section 5). JSON rather than WIT records, because the layout shape will keep growing and the host validates it anyway.
  • The host runs normalizeLayout on it at registration, so a preset can only place panes that exist: the plugin’s own panes and sections, plus built-in panes. Unknown ids are dropped and reported in the plugin log.
  • Preset id plugin:<plugin>:<preset-id>. Plugin presets are listed in the layout menu under the plugin’s name, below the built-ins and above the user’s presets.
  • A plugin preset is never applied by the plugin: only the user picks it (layouts switch by hand only). There is no call to read or change the user’s current layout.
  • Editing a plugin preset and saving creates a user copy, as with built-ins. If the plugin is disabled or removed while its preset is active, the working copy stays as it is (the plugin’s panes become ghosts) and the menu shows it as “Graph review (plugin removed)” until the user picks another.

8. Persistence

New keys in ui-state.json, written through shell/prefs.ts (so uiState stays the only writer):

{
"shell.layout.version": 1,
"shell.layout.active": { "library": "builtin:standard", "reader": "builtin:reading" },
// user presets; a built-in is never changed in place: editing one and saving creates a "user:…" copy
// ("Standard (edited)"), unless the user saves over it from the layout menu
"shell.layout.presets": [ { "id": "user:3f2a", "name": "Writing", "builtin": false, "views": { "library": { … } } } ],
// the working copy: what is on screen, including unsaved resizes and drags; one per view
"shell.layout.current.library": { … },
"shell.layout.current.reader": { … },
// panes open in their own OS windows (section 11)
"shell.layout.windows": [ { "id": "w1", "panes": ["notes"], "bounds": { "x": 1940, "y": 80, "w": 520, "h": 900 }, "from": { "view": "library", "column": "right", "stack": 1 } } ]
}
  • Layouts are per machine. They are not synced and not stored in the library database.

  • Resizing, dragging and showing/hiding change the working copy only, and the layout menu marks the layout as modified (“Standard •”). Save writes the working copy back to the preset; Save as creates a new one; Revert reloads it.

  • Writes of the working copy are debounced (proposed: 300 ms after the last change), since setPref writes the file.

  • Every key is validated with normalizeLayout on read, so a hand-edited or older file never breaks the window.

  • Settings > Appearance gets a “Layouts” page next to “Sidebars”: rename, duplicate, delete, reset built-ins, export/import a preset as JSON.

  • The existing reset paths (resetCols, clearPrefs("shell.")) reset to builtin:standard.

9. Presets

Names are proposals. [ ] is a pane, ─ a split inside a column, ‹a · b› a tab stack. The left column is the sidebar in the library and the reader sidebar in the reader.

Standard (today’s layout, Zotero’s Standard view):

┌──────────────┬──────────────────────────────┬──────────────────┐
│ sidebar │ items │ item │
│ │ │ │
│ │ │ │
└──────────────┴──────────────────────────────┴──────────────────┘
0.18 0.54 0.28

Stacked (Zotero’s Stacked view, for narrow or portrait screens; right column empty):

┌──────────────┬─────────────────────────────────────────────────┐
│ sidebar │ items │
│ ├─────────────────────────────────────────────────┤
│ │ item │
└──────────────┴─────────────────────────────────────────────────┘

Triage (sorting and filing: the Tags and Collections sections detached into the right column, item pane hidden):

┌──────────────┬──────────────────────────────┬──────────────────┐
│ sidebar │ items │ section:tags │
│ │ │ │
│ │ ├──────────────────┤
│ │ │ section: │
│ │ │ collections │
└──────────────┴──────────────────────────────┴──────────────────┘

Notes (item details over notes, plus a plugin panel as a tab):

┌──────────────┬────────────────────────┬────────────────────────┐
│ sidebar │ items │ ‹item · plugin› │
│ │ ├────────────────────────┤
│ │ │ notes │
└──────────────┴────────────────────────┴────────────────────────┘

Reading (reader: Zotero’s reader sidebar and context pane):

┌────────────────┬──────────────────────────────┬────────────────┐
│ reader sidebar │ reader.doc │ ‹reader.item · │
│ (thumbnails, │ │ notes› │
│ annotations, │ │ │
│ outline) │ │ │
└────────────────┴──────────────────────────────┴────────────────┘

Reading and writing (reader: notes under the document, abstract detached on the right):

┌────────────────┬──────────────────────────────┬────────────────┐
│ reader sidebar │ reader.doc │ section: │
│ │ │ abstract │
│ ├──────────────────────────────┤ │
│ │ notes │ │
└────────────────┴──────────────────────────────┴────────────────┘

Focus reading: reader.doc alone; left column and right column hidden, one key brings them back.

10. Keyboard and accessibility

  • Every pane host has role="region" and aria-label from the pane title; a stack’s strip is role="tablist" with role="tab" children; splitters are role="separator" with aria-orientation and aria-valuenow (the size in percent).
  • F6 / Shift+F6 move focus to the next/previous visible pane in reading order (left to right, top to bottom), and remember the focused element inside each pane, so returning to a pane lands where the user was. F6 is unbound today.
  • With a splitter focused: arrow keys resize by 2%, Shift+arrow by 10%, Home/End to the minimum/maximum.
  • With a tab strip focused: Left/Right switch tabs, Ctrl+Shift+Left/Right reorder.
  • Every drop has a keyboard path. The context menu of a pane tab or section header (right click, Shift+F10 or the Menu key) has “Move to ▸ Centre column / Right column”, “Stack with ▸ (each visible pane)”, “Move up / Move down”, “Detach from item pane” / “Return to item pane”, “Open in new window”, and “Hide”.
  • Layout commands are app actions (registerAppAction), so they show in menus and the shortcut list and can be rebound: toggle each built-in pane, “Next layout” / “Previous layout”, “Layout 1…9” (no default keys: Ctrl+Alt+1/2 are the reader’s highlight/underline), “Reset layout”.
  • A move should be announced (“Tags moved to the right column”). Toasts have no live region today, so this needs one (or an announcement call in GPUIX’s accessibility layer, if it has one).
  • When the focused pane is hidden or moved, focus goes with it, or to the view’s required pane if it was hidden.
  • The layout menu lives in the top bar, not only the View menubar menu, because the menubar is shown only while plugins are on.

11. Separate windows

A dock pane can move into its own OS window and back.

  • Prerequisite. The GPUI host cannot open a second window today: ui.open-window in wasmplugins/ui/host.tsx throws “Zinc cannot open a second window yet”. This needs a GPUIX spike (one JS runtime, two GPUI windows, one Solid tree per window). The same work unblocks the plugin ui.open-window call.
  • Opening. “Open in new window” in the pane’s tab menu, or dropping a dragged pane outside the main window (only pane drags do this; item drags leaving the window still go to the OS as Quick Copy).
  • Contents. A pop-out window holds one column of stacks, drawn by the same PaneStack, so panes can be dragged between pop-out windows and back into the main window’s centre or right column. Required panes (items, reader.doc) and the left column cannot leave the main window.
  • Behaviour. All windows share one store, so a pane keeps following the view it came from: a library pane follows the library selection; a reader pane follows the active reader tab and shows its empty state while no reader tab is active. Each window has its own overlay host (menus, dialogs, toasts), keyboard handler and F6 cycle.
  • Closing. Closing a pop-out window returns its panes to where they came from (from in section 8), or to the bottom of the right column if that place no longer exists.
  • Restoring. Windows are part of the working copy and of saved presets. On restart they reopen at their stored bounds, clamped to the displays present; on Wayland, where a window cannot place itself, only the size is restored.

A second full library window (two item lists on different collections) is a different feature: the store holds one library view, and splitting it per window is much larger. It is not wanted (decided 2026-11-18).

To limit accidental windows when a drag overshoots the window edge, a drop outside opens a window only if the pointer is at least 24 px past the edge; nearer than that, the drag cancels. Whether GPUIX reports pointer positions outside the window during a drag is checked in the multi-window spike (dnd.ts already detects the pointer leaving the window, for Quick Copy); if it does not, any release outside the window opens one.

12. Migration from the fixed layout

On first start with the new code (shell.layout.version absent):

  1. Build the library working copy from builtin:standard, then apply the old keys: shell.panelLeft=false hides the left column; shell.panelRight=false hides item (the right column collapses); shell.cols.<key> for the current visibility combination becomes the frame sizes (the other combinations are dropped).
  2. shell.itempaneLayout seeds sectionOrder and the item pane’s hidden sections, in both views. shell.sidebarLayout is unchanged: the sidebar keeps its own setting.
  3. Plugin panels need no migration: their first appearance uses the placement rules in section 7, which match what they do today.
  4. Reader: reader-state.json’s sidebar open, tab and width seed the reader’s left column; the right column starts hidden.
  5. Write shell.layout.version = 1. The old keys are left in the file for one release, so a downgrade still finds them, and are removed in the release after.

The top bar’s two panel buttons stay: they toggle the left column and item (in the reader: the reader sidebar and the context stack).

13. Phased plan

Phase Delivers Main work
0. Spikes Proof that a pane can move between parents without remount; drag overlay over a reader and a plugin web view Re-parent a cacheRegion host in a headless GPUIX test root (gpui-ui/scripts/shot-*.tsx pattern), check that list scroll and reader bitmaps survive; pick re-parent or absolute layout
1. Frame The same window as today, drawn from ViewLayout PaneDef registry, frame renderer, normalizeLayout with unit and fuzz tests (as sidebarLayout.test.ts, collectionRows.fuzz.test.ts), Resizable column direction, migration, ui-state.json keys
2. Docking Tab stacks, drag to dock, sections as panes, keyboard move menus, undo PaneStack, dnd.ts pane payload and drop overlay, per-view item-selection provider, detached section rendering, accessibility pass
3. Presets Standard, Stacked, Triage, Notes (once phase 5 lands); layout menu; save / save as / revert; Settings > Layouts Preset definitions, menus, settings page, headless screenshots of each preset
4. Reader context reader.item, reader right column, Reading and Focus presets, plugin sections in reader tabs Item pane fed from the reader’s item, per-view active layout
5. Notes pane notes in both views; Notes and Reading and writing presets Notes list (item / all, search), editor reusing RichNote.tsx
6. Plugin panes Right-side plugin panels in the dock, persisted visibility for all plugin panels, optional placement.beside WIT field, plugin layout presets Map SidePanelRegistration, ghosts, extend.wit additions (placement, layout-preset) and SDK docs
7. Separate windows Panes in their own OS windows, restored on restart GPUIX multi-window spike first; per-window overlay host, key handling and F6; drag between windows; plugin ui.open-window on the same base

First release: phases 0 to 3 (drag to dock included). Phases 4 and 5 can follow in either order; 6 is small and can go with whichever ships first. Phase 7 depends on the multi-window spike, which can run early (alongside phase 0) to size it.

14. Open questions

None at the design level; the scope decisions are at the top of this page. The two spikes (phase 0, and the multi-window spike for phase 7) may reopen the rendering approach in section 5 and the timing of section 11.