Dockview saved-layout contract

Chris's decision on 8 September 2026: converge on one Dockview format before production. Old staging/test panel arrangements may be discarded. Do not maintain parallel v1/v2 layout slots for rollback. This decision concerns layout preferences only; study answers, comments and review data must never be cleared or migrated by this work. Keep the existing separate-window mechanism initially.

Stored format and scope

The existing per-reviewer workspace settings collection remains the owner. Each reviewer has separate screening, annotation and combined capability slots. The sole writable envelope is version: 2, dockJson (serialized Dockview layout JSON), sourceMode and optional sourceBounds. Obsolete arrangement/order fields are ignored on database reads and are not part of the new contract. Live renderer parameters and Angular templates never enter the payload.

GET omits obsolete or invalid preferences, so the client displays defaults. Nothing is deleted in bulk or rewritten during a read. An explicit Save layout atomically replaces only the selected capability slot. Other capabilities, reviewer profiles, answers and comments are untouched. Old clients cannot write their obsolete layout format; saving requires the Dockview client. The non-Dockview workspace therefore offers session-only arrangement and source controls without a Save action; it cannot overwrite a saved Dockview layout.

The API validates a 64 KiB JSON ceiling, bounded tree depth/dimensions, allowed renderer keys, one occurrence of each capability panel, group/active-view consistency and source-only floating groups. Native popout and edge groups are not accepted in this format. Floating positions are serialized in top-left coordinates of the application floating layer below navigation, independently of the docked grid. Earlier grid-relative positions remain valid and are clamped into the available application area on restore. The authenticated active investigator remains the only identity used for read/write.

Runtime behavior

The workspace loads its capability slot when reviewer/capability resolve and cancels requests when that scope changes. Invalid, missing or incompatible preferences use fresh defaults. Load failure offers Retry or Use defaults; save is disabled until a layout loaded or defaults were explicitly chosen. Save failure retains the current arrangement for retry.

Restoration reconstructs renderer parameters from live templates and uses reuseExistingPanels: true; layout restoration and defaults must preserve dirty answer/comment components. Restored arrangements use the existing user-defined-arrangement state so late panels cannot overwrite the chosen arrangement. Floating source bounds are clamped against the current container and navigation toolbar.

A saved separate-window preference does not automatically open a popup. The source stays available in the main page and an Open study source window button invokes the existing coordinator from a user gesture. Native Dockview popout remains follow-up.

Delivery

The API must accept this contract before a client writes it. This PR changes the contract and runtime together but does not deploy, activate flags, delete documents or migrate review data. Staging/preview acceptance remains distinct from local validation. Disabling Dockview or using an old client may show default layout preferences, which is explicitly accepted for these unreleased layouts.

Application space and panel headers

The docked workspace fills the viewport below its controls, with a small usable floor on short screens and scrollable panel bodies. Window resizing and navigation height changes update its dimensions. Floating Study source uses Dockview’s overlay host across the application viewport below navigation; movement and resize bounds are independent of the docked grid. It remains a Dockview group, preserving return to docked mode and the same layout persistence contract.

Dockview tabs serve as the shared panel header in both ordinary and rearrangement modes. Duplicate content titles are suppressed inside this workspace. Grouped Screening/Annotation tabs remain selectable with pointer and keyboard; rearrangement mode reveals move grips and menus. Material theme tokens and existing Material buttons/icons style the header. Native Dockview tab semantics retain keyboard navigation without introducing a second tab widget or remounting form content. Dividers are transparent at rest and visible on hover, focus, or rearrangement; their native pointer and touch hit areas remain intact.

These corrections remain behind stageReviewDockview; no additional flag is needed.