Cross-window object permanence is a defining DockLayouts capability, but the current guide gives only the ownership map and the Adoption guide gives only the render-target hook. The final window/ package now separates participation, workspace sets, tear-out, conversion, embodiment, and parking.
The Problem
Readers lack one explanatory path through pane → popup vessel → conversion/parking → reintegration. Generic multi-window documentation and the portability matrix do not explain DockLayouts' semantic ownership, SharedWorker identity, native-titlebar handoff, or failure/terminal behavior.
The Architectural Reality
window/{Participation,WorkspaceSet,TearOut,VesselConversion,VesselEmbodiment,VesselPark,DragTarget}.mjs, Workspace hooks, main-thread window operations, and dock-blind drag coordination divide the choreography. The App worker retains semantic truth; render targets and physical windows are embodiments.
The Fix
Create learn/guides/uibuildingblocks/DockLayoutsWindows.md: a story-led guide following a real pane through tear-out, cross-window participation, conversion/parking, disconnect, and reintegration, with links to the generic multi-window concepts and portability reference.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
Window guide
ADR 0029 + current window package + host hooks
Explain one lifecycle across semantic and physical owners
Revalidate terminals after refactors
New guide
Real headed multi-window journey
Portability relationship
Generic multi-window guide + tear-out matrix
Explain concepts; link matrix as reference
Never duplicate platform rows
Same guide
Rendered links + receipt
Registration
Existing guide siblings
One discoverable UI-building-blocks guide
No generated-output edits
tree + SEO inputs
lint + rendered portal
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains accepted multi-window ownership.
Acceptance Criteria
The guide clears the full guide-authoring bar: source/tool-grounded narrative, reader-owned benefits, lived maintainer voice, and at least one render-verified flowchart TD.
The guide separates explanation from reference: no inlined API/schema/test catalog, and no ticket or PR ids in guide prose.
The new source guide is registered in learn/tree.json and the SEO PRIORITIES input; generated sitemap/LLM outputs remain untouched.
Current-source consistency, guide lint, tree lint, portal rendering, and an independent cross-family whole-guide review are recorded in the PR.
A real headed journey covers vessel birth, same-pane continuity where promised, conversion/parking, disconnect/terminal handling, and reintegration.
The guide distinguishes App-worker semantic state, main-thread window authority, render-target embodiment, and drag coordination.
Platform portability facts link to the existing matrix instead of copying it.
Failure and cleanup paths are included, not only the happy tear-out animation.
Out of Scope
A platform matrix rewrite, Electron/browser API reference, or new tear-out behavior.
Avoided Traps
Do not treat a popup as the state owner, promise same JS heap across unsupported worker topology, or conflate native-titlebar drag with in-document drag.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Retrieval Hint: query_raw_memories("DockLayouts guide series post-refactor final API")
Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.
Context
Cross-window object permanence is a defining DockLayouts capability, but the current guide gives only the ownership map and the Adoption guide gives only the render-target hook. The final
window/package now separates participation, workspace sets, tear-out, conversion, embodiment, and parking.The Problem
Readers lack one explanatory path through pane → popup vessel → conversion/parking → reintegration. Generic multi-window documentation and the portability matrix do not explain DockLayouts' semantic ownership, SharedWorker identity, native-titlebar handoff, or failure/terminal behavior.
The Architectural Reality
window/{Participation,WorkspaceSet,TearOut,VesselConversion,VesselEmbodiment,VesselPark,DragTarget}.mjs, Workspace hooks, main-thread window operations, and dock-blind drag coordination divide the choreography. The App worker retains semantic truth; render targets and physical windows are embodiments.The Fix
Create
learn/guides/uibuildingblocks/DockLayoutsWindows.md: a story-led guide following a real pane through tear-out, cross-window participation, conversion/parking, disconnect, and reintegration, with links to the generic multi-window concepts and portability reference.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains accepted multi-window ownership.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Out of Scope
A platform matrix rewrite, Electron/browser API reference, or new tear-out behavior.
Avoided Traps
Do not treat a popup as the state owner, promise same JS heap across unsupported worker topology, or conflate native-titlebar drag with in-document drag.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Origin Session ID: 309a78d7-2d95-4f23-bdfc-69d2ae393a5d
Retrieval Hint:
query_raw_memories("DockLayouts guide series post-refactor final API")Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.