0018: The editor shell docks with Dock.Avalonia, behind a shell seam
Status
Accepted (2026-10-01, P3a spec specs/005-editor-shell/, research R2) and implemented in P3a. Spike gate passed on 2026-10-01 (batch C1,
T030-T032): all five checks pass, so the shell is built on Dock.Avalonia 12.1.0.6. Check 2 needed a workaround (below); results and
evidence are in specs/005-editor-shell/implementation-notes.md, "Spike". What a user sees of the decision, floating tabs and panels,
Dock tab and Reset layout, is in the editor window guide.
Spike outcome, amendments to the decisions below (the first one decided in batch C2):
- Layout persistence does not use Dock's serializers. The source-generated one cannot compile under
RS0030: the generator emitsJsonSerializer.Deserialize(ReadOnlySpan<byte>, Type, JsonSerializerOptions?)andSerializeToElement(object?, Type, JsonSerializerOptions?)inObjectPayloadConverter, which are banned insrc/, and no suppression or per-file severity is allowed. The reflection-modeDockSerializer(batch C1's fallback) was rejected: it works, but the repository keeps JSON on source-generated contexts, and a reflection serializer would be the one exception, one that a trimmed or AOT build of the editor could not run.Dock.Serializer.SystemTextJsonis therefore not referenced (DockConfinementTestsasserts that noDock.Serializer.*package is). The layout is persisted as a NetPrints-owned DTO tree (dock kind, id, proportion, active and visible flags, children; floating windows with their bounds; hidden panel ids) through a source-generatedJsonSerializerContextinsideShell/Docking/, and the adapter maps it to and from Dock's model (T064). Decided in batch C2 (2026-10-01). - A loaded layout is re-attached by id before it is initialised:
Contextis set from the app, a dockable the app no longer knows is removed.DockStatehas nothing to restore for the MVVMDocumentandTool(they are notIDocumentContent). DockControlis created withInitializeFactory="True"and withoutInitializeLayout: attaching a control created withInitializeLayoutcloses the layout's floating windows. The adapter callsInitLayoutagain once the control is attached, which also opens the floating windows of a loaded layout.- Floating windows resolve view models through
Application.DataTemplates, not theDockControl's ownDataTemplates. The adapter'sx:DataTypetemplates are registered there. - Native floating works under Xvfb + openbox; managed floating is not needed on Linux.
Context
P3a replaces the launcher window and the one-window-per-class model (UX audit H2) with a single shell: a project
tree, tabbed graph documents, an inspector and a bottom panel (Errors / Output / C#). The owner asked for dockable,
floatable and tabbed panes with serialized layouts, built on Dock.Avalonia (wieslawsoltes/Dock), provided it works
with Avalonia 12, CommunityToolkit.Mvvm, the headless tests and the Desktop E2E setup (Xvfb + openbox, ADR-0006).
Facts checked on 2026-10-01 (sources in research R2):
- Dock 12.1.0.6 (2026-08-27, MIT) targets
net10.0and needs Avalonia >= 12.1.1; the repo pins 12.1.3. Dock has shipped stable Avalonia 12 releases since 12.0.0.1 (2026-04-09), with about ten releases since then. Dock.Model.Mvvmbuilds on CommunityToolkit.Mvvm (>= 8.4.0; the repo has 8.4.2) and pulls in no ReactiveUI. ReactiveUI comes only withDock.Model.ReactiveUI, and Newtonsoft.Json only withDock.Serializer.Newtonsoft.Dock.Serializer.SystemTextJsonadds no dependency onnet10.0, but is not used (see Status).- Documents and tools are view-model-first. Dock's own serializers re-attach content by the app (
DockState) and keep floating window bounds and states; the spike found them unusable here (see Status), so the adapter persists its own DTO. - The Dock repo runs its own Avalonia.Headless test projects. Nothing documents compiled-binding templates, automation peers on tabs and panes, or behaviour under openbox, so those need a spike.
- One active maintainer, frequent four-part releases (
12.1.0.x).
Decision
- Adopt Dock.Avalonia for the shell layout. Reference exactly
Dock.Avalonia,Dock.Model.MvvmandDock.Avalonia.Themes.Fluent, all at12.1.0.6with an exact central pin ([12.1.0.6]). Do not referenceDock.Model.ReactiveUIor anyDock.Serializer.*package (amended after the spike, see Status). Upgrades are deliberate PRs that keep the shell's headless and E2E tests green. - Shell seam. Dock types stay inside one adapter namespace,
NetPrints.Editor.Shell.Docking. Feature view models (graph documents, the project tree, the inspector, the bottom panels) and the contribution registry (ADR-0020) never reference Dock. They talk to anIShellservice (open or activate a document, show or hide a panel, the active document, reset the layout). The adapter wraps each registered panel and each open document in a Dock dockable whose content is the NetPrints view model, and maps views byDataTemplate x:DataType(ADR-0007 D6), not by Dock's naming-convention locator. The P3 extension API therefore exposes no Dock type. - Layout persistence. The adapter saves the layout as a NetPrints-owned DTO tree (not Dock's own JSON), written through a
source-generated
JsonSerializerContextinside a NetPrints envelope (schemaVersion,engine,dockLayout) in the per-user state store (research R7). On restore, panels and documents are matched by stable ids: a registered panel id (netprints.panel.*), or a document id derived from the graph's identity, and the adapter builds Dock's dockables from them. Unknown panels and documents whose graph no longer exists are dropped. A layout that fails to load is logged and replaced by the default layout. View › Reset layout always restores the default. - Floating uses Dock's native floating windows. If the spike shows that native floating is unreliable under openbox, the shell switches to Dock's managed (in-window) floating on Linux only. That is a setting, not a fallback.
- Spike gate. The first task of the shell sub-phase is a throwaway spike that must show all of the following:
- a document template with
x:DataTypeand compiled bindings; - a layout round trip that re-creates documents through the app;
- automation ids on content inside docked, tabbed and floating panes, reachable from a headless test and from the E2E automation pipe;
- floating and re-docking a pane under Xvfb + openbox;
- Light and Dark theming through the editor's tokens.
It records the results in
implementation-notes.md.
- a document template with
- Fallback. If check 1, 2 or 3 fails and the spike cannot fix it, the shell is built on plain Avalonia instead:
a
GridwithGridSplitters, aTabControlfor documents, collapsible side and bottom panels, and pane sizes and visibility persisted in the same envelope withschemaVersionbumped. "Open in new window" replaces floating, throughIWindowService. Features and tests are unaffected because they depend only onIShell.
Consequences
- Docking, floating, tab groups and layout serialization come from a maintained library instead of new code, which also covers most of UX audit L2.
- The seam costs one adapter and one indirection (
IShell), but bounds the cost of a Dock regression, an upgrade break or the fallback to that adapter, and keeps Dock out of the P3 public API. - A single active maintainer and fast releases are a supply risk. The exact pin, the seam and the fallback contain it, so a Dock upgrade is never forced by another package.
- E2E tests drive the shell through commands and automation ids, not through drag gestures on Dock's chrome. Drag docking itself is Dock's responsibility and is checked by hand once per release.