Context
Planning-gap closure from the final-window roadmap audit (2026-07-04): the v13.2 cornerstone bar says "Qt-parity docking + stunning demos — NL-driven, animated" and #14591 already ASSERTS animations in e2e (animation assertions via the NL observe_motion path) — but no ticket implements the animation layer those assertions and demos presuppose. The gap would surface mid-blackout as either rubber-stamped assertions or an unshippable demo bar. Non-fable implementable; the boundaries below are complete.
The Problem
Dock operations currently commit as instant re-projections: a split resize jumps, a tab move teleports, auto-hide appears/disappears without motion. The Qt-ADS polish bar (and both showcase demos #14589/#14590 + the G3 scene #14772) need the adapter's projections to TRANSITION: eased splitter/size changes, tab insert/remove morphing, edge-rail slide for auto-hide, and a brief settle highlight on cross-window arrival.
The Architectural Reality
- Animation is projection-tier ONLY: the semantic model (
DockZoneModel documents) stays instant + pure — animations live in src/dashboard/DockLayoutAdapter.mjs (+ CSS transition classes in the dock theme layer), between commit and settled-DOM. Nothing about motion ever enters a document, a preview payload, or persistence (the ADR-0029 JSON-first guardrail extends).
- Neo's multi-threaded reality: prefer CSS transitions/keyframes driven by class/style toggles over JS rAF loops (main-thread cheap, worker-friendly);
Neo.util.Rectangle-class movement helpers + the vdom engine's existing transition affordances are the substrate — no new animation framework, no external deps.
- Observability contract: transitions must be deterministically assertable — fixed durations from ONE token set (
--dock-transition-* custom properties in the dock theme), a dock-animating class present during motion, and completion observable via transitionend-driven class removal. #14591's NL observe_motion assertions and #14640's tour-runner step-gating consume exactly this contract.
- Reduced-motion:
prefers-reduced-motion collapses durations to 0 — the token layer owns this, not per-call-site checks.
The Fix
One PR: transition tokens (light+dark safe — motion tokens are theme-agnostic) + adapter class-toggle choreography for the four motion classes (split size ease, tab insert/remove, auto-hide rail slide, arrival settle) + the dock-animating observability contract + reduced-motion collapse. Unit floor for the pure parts (class/token computation); visual verification on examples/dashboard/dock (the #13247 surface); #14591 wires the NL assertions against the contract in its own leaf.
Acceptance Criteria
Out of Scope
The e2e assertions themselves (#14591) · tour-runner step-gating (#14640) · demo content (#14589/#14590/#14772) · any DockZoneModel change.
Related
Parent #13158 · consumed by #14589/#14590/#14591/#14640/#14772 · authority: ADR 0029 JSON-first guardrail + the model contract's projection boundary. Decision Record impact: aligned-with ADR 0029.
Live sweep: title-search animation + latest-20 at 13:15Z — only #14591 (assertions, not the layer) and legacy #8541 (unrelated). A2A in-flight sweep 13:15Z: no competing claim.
Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4
Retrieval Hint: "dock transition animation layer tokens dock-animating observability"
Context
Planning-gap closure from the final-window roadmap audit (2026-07-04): the v13.2 cornerstone bar says "Qt-parity docking + stunning demos — NL-driven, animated" and
#14591already ASSERTS animations in e2e (animation assertions via the NL observe_motion path) — but no ticket implements the animation layer those assertions and demos presuppose. The gap would surface mid-blackout as either rubber-stamped assertions or an unshippable demo bar. Non-fable implementable; the boundaries below are complete.The Problem
Dock operations currently commit as instant re-projections: a split resize jumps, a tab move teleports, auto-hide appears/disappears without motion. The Qt-ADS polish bar (and both showcase demos
#14589/#14590+ the G3 scene#14772) need the adapter's projections to TRANSITION: eased splitter/size changes, tab insert/remove morphing, edge-rail slide for auto-hide, and a brief settle highlight on cross-window arrival.The Architectural Reality
DockZoneModeldocuments) stays instant + pure — animations live insrc/dashboard/DockLayoutAdapter.mjs(+ CSS transition classes in the dock theme layer), between commit and settled-DOM. Nothing about motion ever enters a document, a preview payload, or persistence (the ADR-0029 JSON-first guardrail extends).Neo.util.Rectangle-class movement helpers + the vdom engine's existing transition affordances are the substrate — no new animation framework, no external deps.--dock-transition-*custom properties in the dock theme), adock-animatingclass present during motion, and completion observable viatransitionend-driven class removal.#14591's NLobserve_motionassertions and#14640's tour-runner step-gating consume exactly this contract.prefers-reduced-motioncollapses durations to 0 — the token layer owns this, not per-call-site checks.The Fix
One PR: transition tokens (light+dark safe — motion tokens are theme-agnostic) + adapter class-toggle choreography for the four motion classes (split size ease, tab insert/remove, auto-hide rail slide, arrival settle) + the
dock-animatingobservability contract + reduced-motion collapse. Unit floor for the pure parts (class/token computation); visual verification onexamples/dashboard/dock(the#13247surface);#14591wires the NL assertions against the contract in its own leaf.Acceptance Criteria
dock-animatinglifecycle observable + deterministic (spec on the class-toggle logic; NL-assertable per the contract above).prefers-reduced-motioncollapses all dock motion to instant (token-layer, one place).Out of Scope
The e2e assertions themselves (
#14591) · tour-runner step-gating (#14640) · demo content (#14589/#14590/#14772) · any DockZoneModel change.Related
Parent
#13158· consumed by#14589/#14590/#14591/#14640/#14772· authority: ADR 0029 JSON-first guardrail + the model contract's projection boundary. Decision Record impact: aligned-with ADR 0029. Live sweep: title-searchanimation+ latest-20 at 13:15Z — only#14591(assertions, not the layer) and legacy#8541(unrelated). A2A in-flight sweep 13:15Z: no competing claim. Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4 Retrieval Hint: "dock transition animation layer tokens dock-animating observability"