The existing DockLayouts guide gives one concise gesture walkthrough, but the final package now separates interaction, model, and projection responsibilities across src/dashboard/dock/{interaction,model,projection}/. Readers still lack a deep explanation of how a physical gesture becomes exactly one semantic commit and a reconciled projection.
The Problem
An adopter or maintainer must currently reconstruct threshold crossing, claim ownership, preview production, cancellation, operation emission, reducer commit, and projection reconciliation from source and tests. That is the subsystem's most important behavioral loop, and a shallow overview cannot explain why cancellation, stale generations, or rejected moves must commit nothing.
The Architectural Reality
interaction/DockSplitter.mjs, TabSortZone.mjs, PreviewProducer.mjs, model/Operations.mjs, model/Document.mjs, projection/Reconciler.mjs, and Workspace.mjs form the current authority chain. Generic pointer/drag machinery remains below DockLayouts; dock interactions add semantic descriptors rather than a second drag engine.
The Fix
Create learn/guides/uibuildingblocks/DockLayoutsMechanics.md: a narrative guide that follows representative split resize, tab movement, and edge resize gestures from pointer intent through commit and re-projection, including the failure paths that preserve prior truth.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
Mechanics guide
ADR 0029; current interaction/model/projection classes
Explain one gesture pipeline and its invariants without becoming an API catalog
If mechanics change before pickup, re-scope before prose
New guide
Live gesture receipts + code/test anchors
Failure semantics
Reducer and interaction guards
Explain cancel/refusal/stale-generation as zero-commit paths
Never infer from UI outcome alone
Same guide
Mutation or negative-arm receipts
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 the accepted interaction architecture.
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.
At least three real gesture families are traced, including one rejected/cancelled arm and their exact state/ownership transitions.
The story distinguishes physical pixels, runtime preview state, semantic descriptors, committed documents, and projected component state.
The author exercises the current Workstation/example gesture path rather than writing from source inference alone.
Out of Scope
API reference tables, exhaustive operation schemas, feature marketing, or changing DockLayouts behavior.
Avoided Traps
Do not duplicate the intro's short walkthrough, teach DOM mutation as authority, or present every source class as a chapter.
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
The existing DockLayouts guide gives one concise gesture walkthrough, but the final package now separates interaction, model, and projection responsibilities across
src/dashboard/dock/{interaction,model,projection}/. Readers still lack a deep explanation of how a physical gesture becomes exactly one semantic commit and a reconciled projection.The Problem
An adopter or maintainer must currently reconstruct threshold crossing, claim ownership, preview production, cancellation, operation emission, reducer commit, and projection reconciliation from source and tests. That is the subsystem's most important behavioral loop, and a shallow overview cannot explain why cancellation, stale generations, or rejected moves must commit nothing.
The Architectural Reality
interaction/DockSplitter.mjs,TabSortZone.mjs,PreviewProducer.mjs,model/Operations.mjs,model/Document.mjs,projection/Reconciler.mjs, andWorkspace.mjsform the current authority chain. Generic pointer/drag machinery remains below DockLayouts; dock interactions add semantic descriptors rather than a second drag engine.The Fix
Create
learn/guides/uibuildingblocks/DockLayoutsMechanics.md: a narrative guide that follows representative split resize, tab movement, and edge resize gestures from pointer intent through commit and re-projection, including the failure paths that preserve prior truth.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains the accepted interaction architecture.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Out of Scope
API reference tables, exhaustive operation schemas, feature marketing, or changing DockLayouts behavior.
Avoided Traps
Do not duplicate the intro's short walkthrough, teach DOM mutation as authority, or present every source class as a chapter.
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.