Auto-hide dock items: edge-rail projection (phase 1 of #13280)

Context

Phase 1 of #13280 (the auto-hide/pin UI consumer under Epic #13158, QT-parity docking polish). #13280 spans three independent PRs — (1) the autoHidden→edge-rail projection, (2) the runtime reveal overlay, (3) the pin affordance — but agent-pr-body-lint mandates exactly one Resolves #N per PR (the 1-PR-per-ticket model, operator rule #12367). So #13280 becomes the parent and each phase a sub-issue; this is the projection phase. The implementation is already complete + green in PR #13770 — this ticket gives it a valid 1:1 close-target.

The claim-time contract for all three phases was settled on #13280 (rail = a new projection branch; reveal = a runtime-only overlay; pin = setItemPinned via the operation-descriptor path).

The Problem

The auto-hide model seam is merged (the persisted autoHidden item field + setItemAutoHidden + pin/auto-hide coherence), but nothing rendered it: DockLayoutAdapter projected every item as a full pane regardless of autoHidden, so an auto-hidden item was invisible to the user. This phase makes it visible as a thin edge rail — the QT-parity collapsed-to-sidebar affordance — without yet wiring the reveal/pin interactions (phases 2–3).

The Architectural Reality

• src/dashboard/DockLayoutAdapter.mjs — the model→config projection adapter (consumes committed dock-zone state; emits ordinary Neo container/tab configs). Methods: project → projectNode → projectEdgeZoneNode / projectSplitNode / projectTabsNode / projectItem.
• src/dashboard/DockZoneModel.mjs — the merged model seam (autoHidden field; setItemPinned clears autoHidden).
• Guardrails: ADR 0020 §4 (JSON-first — no DOMRect/hover geometry serialized; no parallel pointer system) + learn/agentos/HarnessDockZoneModel.md (Serializable vs Runtime).

The Fix (delivered in PR #13770)

• collectAutoHiddenItems(nodeId, context) — walks an edge-zone/split/tabs subtree, returns the autoHidden item ids.
• createEdgeRail / createRailTab — project a thin rail strip + clickable rail tabs carrying stable dockItemId/dockEdge metadata (the handle the phase-2/3 reveal/pin act on).
• projectEdgeZoneNode — collects autoHidden items per edge band (top/right/bottom/left), passes a railedItemIds set down, weaves the edge rails into the zone layout.
• projectTabsNode — drops railedItemIds from the tab flow; activeItemId falls back to the first remaining item.
• Fail-safe: a center-zone autoHidden item (main content does not auto-hide) is left in the tab flow rather than vanishing.

Contract Ledger Matrix

Acceptance Criteria

• An autoHidden edge item projects to an edge rail, not the tab flow.
• A pinned (non-autoHidden) item is never railed.
• A center-zone autoHidden item stays in the tab flow (fail-safe — never vanishes).
• The 9 existing DockLayoutAdapter specs stay green (backward-compatible — no autoHidden ⇒ identical projection).
• No DOMRect/hover/open geometry in any projected config (JSON-first).

Out of Scope

• The runtime reveal overlay (phase 2 — sibling sub of #13280).
• The pin affordance / setItemPinned wiring (phase 3 — sibling sub of #13280).
• Visual verification of the rendered rail (phase-2 Neural-Link / post-merge).

Decision Record impact

none — aligned-with ADR 0020 (QT-grade docking); no ADR mutation.

Related

• Parent: #13280 (auto-hide/pin UI consumer)
• Epic: #13158 (QT-parity docking polish)
• PR: #13770 (the implementation)

Live latest-open sweep: checked latest 20 open issues 2026-06-21; no equivalent found.

Origin Session ID: 80932414-00dc-4d2e-96e6-d0bcf1529733

Retrieval Hint: "DockLayoutAdapter autoHidden edge-rail projection phase 1"