Part of #18474. The #18476 prerequisite is merged.
Context
This leaf makes the shipped dock example consume the stage-one panes/zones contract. Its deliverable is a working representative consumer and its acceptance evidence, not another engine API or a guide. Dedicated first-layout and adoption-guide leaves depend on this example.
The Problem
The example mixes initial graph construction and a config-shaped pane resolver with its legitimate perspective toolbar, storage adapter and tour behavior. Adopting the engine declaration surface must remove the former without deleting or rewriting the latter as an unrequested persistence redesign.
The Architectural Reality
Source baseline: Engine dev b537d0a3c8101c7d9fcb2a23317b6133d8d356ec.
- MainContainer.mjs:22–52 holds the initial document; adjacent reviewDockModel/seededPerspectives retain purpose as example-owned named layouts.
- construct:177 creates the example collection/toolbar and starts its existing load. The engine already mounts the first shell.
- resolvePane:207 returns ordinary component configs and the existing ReloadablePane.
- Existing browser journeys live in test/playwright/e2e/dashboard, including DockOperationsNL, DockAutoHideRevealNL and DockReloadActionNL. They exercise the real example and must remain meaningful after adoption.
The Fix
Express initial panes and nested placement through the #18476 public configs. Remove the manually maintained initial graph and the example's config-shaped resolver; remove only initialization made redundant by the host. Preserve collection loading/saving, perspective toolbar identity/order, review/operator presets, ReloadablePane behavior and tour replay.
Where an advanced example behavior needs a named structural node, use a deliberate supported authored id/reference. Do not reconstruct a global structural symbol table merely to preserve old implementation coordinates. Update tests that address incidental node names to stable pane/semantic behavior, while retaining their original behavioral assertions.
Demonstrate the basic consumer separately from the advanced chrome in code comments/example organization: the arrangement works from declarations, while perspective/tour functionality remains existing example logic. Do not add proposed perspectives, persistence, workspaces or bound-panes configs.
Adoption prerequisite found during browser validation
The unchanged example passes the existing committed-addTab motion arm. With declared pane retention, the same arm fails repeatedly: the detached pane remains live, and LayoutAdapter.decorateProjectedItem() returns that live instance before applying its addTab header decoration. This leaf includes the bounded correction in that existing adapter method: live/config answers receive the same operation-correlated header; live header metadata is restored on an unrelated projection. Keep object identity, existing stack-grip restoration and the one-use motion contract. No new resolver, public API or motion scheduler.
Two separate macOS theme snapshots fail on both the old and adopted example with byte-identical actual images (86/76 title pixels). Those baseline differences are not acceptance evidence for this adapter fix and will not be rebaselined here.
Contract Ledger Matrix
| Target surface |
Source of authority |
Required behavior |
Refusal / fallback |
Docs |
Evidence |
| Initial example arrangement |
#18476 public contract; current example document |
Same useful tab/split/edge composition from panes/zones |
Declaration errors stay engine-owned |
Example class/config JSDoc |
Rendered arrangement and semantic readback |
| Pane definitions |
Existing resolver and ReloadablePane |
Ordinary component/header/policy definitions; no custom example resolver/cache for declaration plumbing |
Retain standard lifecycle behavior |
Inline intent only; guides live in their own leaves |
Lazy/same-class host evidence plus example reload regression |
| Perspective and tour features |
Existing MainContainer collection/toolbar/tour methods |
Preset selection, save/load and replay still work with the declared initial layout |
Existing storage and restore failures remain visible |
Existing API comments updated where changed |
Current example journeys and toolbar/preset controls |
| Retained-pane addTab header |
Existing LayoutAdapter + TabEnterButton contract |
Apply the same one-use insertion correlation to a retained live pane; restore its ordinary header afterward |
No decoration for an unrelated operation or node; preserve stack-grip restoration |
Existing adapter JSDoc |
Live-instance red control and unchanged rendered motion arm |
| Consumer simplification |
D#18468 adoption bar |
Remove manual graph/resolver/redundant seed ownership; do not replace it with equivalent hidden plumbing |
Keep justified advanced feature code |
PR deletion ledger |
Before/after responsibility and source comparison |
Discussion Criteria Mapping
Source criteria 1, 3, 4 and 5: a real consumer uses the shipped declarations, retains meaningful runtime behaviors and removes its engine plumbing. Documentation deliverables have separate guide owners.
Acceptance Criteria
Validation
Load the whitebox-e2e guidance before modifying/running these journeys. Run the updated example's relevant exact-head coverage, at minimum:
NEO_AGENTOS_RUNTIME_ROOT="/absolute/path/to/configured/neo-agent-brain" npx playwright test -c test/playwright/playwright.config.e2e.mjs dashboard/DockOperationsNL.spec.mjs dashboard/DockAutoHideRevealNL.spec.mjs dashboard/DockReloadActionNL.spec.mjs
Use the fixture's own configured server/checkout. Replace the sample runtime path with the configured Brain checkout. NEO_AGENTOS_RUNTIME_ROOT is required: the Engine e2e selector excludes these Neural Link specs when it is absent (playwright.config.e2e.mjs / test/playwright/externalBrainSelection.mjs). Run the same command with --list first and verify all three named files are selected. A missing runtime is unavailable evidence, not a passing skip.
Record a browser view of the adopted example and a before/after identity control, plus preset/load/replay outcomes; add focused coverage to the existing appropriate suite for any uncovered changed behavior. Do not claim an unrun browser matrix from static source review.
Dependencies and Decision Record
Native blocked-by dependency: #18476. Read its final public API and lifecycle contract before editing the example; the model dependency is transitive.
Decision Record: REQUIRED at the parent capability. Decision Record impact: aligned-with the ADR 0029 amendment already landed with #18476; no new ADR or schema change.
Out of Scope
Engine normalization/resolution redesign; new persistent-library ownership; multi-window authoring; reactive authorization; guides; Workstation responsibility extraction.
Avoided Traps
Do not delete advanced example features to make the line count look better. Do not retain manual engine plumbing under renamed helpers. Do not keep tests green by replacing semantic assertions with source-token assertions.
Related and Pickup
Related: #18474; #18476.
unowned-rationale: Available for peer self-selection once the host contract is delivered; guide authors consume the resulting public example.
Retrieval Hint: stage-one MainContainer panes/zones adoption; preserve seededPerspectives, toolbar/load/tour and ReloadablePane behavior.
Origin Session ID: 4f9b7bbe-9dbc-4d36-a167-38fe0d288113
Creation checks
Latest 20 open issues, latest 30 all-state A2A, the MainContainer/initialDockModel/resolver problem-memory query, and eight own assignments checked immediately before filing. Existing #18456 is a different Workstation simplification lane; no duplicate dock-example adoption leaf exists. #18475 and #18476 are this packet's intended predecessors. Source and exact baseline are cited above; no new source directory is prescribed.
Part of #18474. The #18476 prerequisite is merged.
Context
This leaf makes the shipped dock example consume the stage-one panes/zones contract. Its deliverable is a working representative consumer and its acceptance evidence, not another engine API or a guide. Dedicated first-layout and adoption-guide leaves depend on this example.
The Problem
The example mixes initial graph construction and a config-shaped pane resolver with its legitimate perspective toolbar, storage adapter and tour behavior. Adopting the engine declaration surface must remove the former without deleting or rewriting the latter as an unrequested persistence redesign.
The Architectural Reality
Source baseline: Engine dev b537d0a3c8101c7d9fcb2a23317b6133d8d356ec.
The Fix
Express initial panes and nested placement through the #18476 public configs. Remove the manually maintained initial graph and the example's config-shaped resolver; remove only initialization made redundant by the host. Preserve collection loading/saving, perspective toolbar identity/order, review/operator presets, ReloadablePane behavior and tour replay.
Where an advanced example behavior needs a named structural node, use a deliberate supported authored id/reference. Do not reconstruct a global structural symbol table merely to preserve old implementation coordinates. Update tests that address incidental node names to stable pane/semantic behavior, while retaining their original behavioral assertions.
Demonstrate the basic consumer separately from the advanced chrome in code comments/example organization: the arrangement works from declarations, while perspective/tour functionality remains existing example logic. Do not add proposed perspectives, persistence, workspaces or bound-panes configs.
Adoption prerequisite found during browser validation
The unchanged example passes the existing committed-addTab motion arm. With declared pane retention, the same arm fails repeatedly: the detached pane remains live, and
LayoutAdapter.decorateProjectedItem()returns that live instance before applying its addTab header decoration. This leaf includes the bounded correction in that existing adapter method: live/config answers receive the same operation-correlated header; live header metadata is restored on an unrelated projection. Keep object identity, existing stack-grip restoration and the one-use motion contract. No new resolver, public API or motion scheduler.Two separate macOS theme snapshots fail on both the old and adopted example with byte-identical actual images (86/76 title pixels). Those baseline differences are not acceptance evidence for this adapter fix and will not be rebaselined here.
Contract Ledger Matrix
Discussion Criteria Mapping
Source criteria 1, 3, 4 and 5: a real consumer uses the shipped declarations, retains meaningful runtime behaviors and removes its engine plumbing. Documentation deliverables have separate guide owners.
Acceptance Criteria
AC-1: The initial arrangement and pane definitions use the host's public stage-one API. The old initial graph and config-shaped resolvePane are gone, and no substitute consumer resolver/cache/compile call appears.
AC-2: The real example boots with the intended center split, tab groups, edge pane and policy/header behavior. An auto-hidden pane reveals and pins back correctly; moving a pane retains its identity.
AC-3: Existing Operator/Review presets, perspective toolbar synchronization, collection save/load and tour replay remain functional. Changing the declared default does not override an explicitly restored document through host seeding.
AC-4: The existing ReloadablePane demonstration and ordinary tab actions still function. This adoption does not introduce a new recreate policy.
AC-5: Existing tests retain their behavior assertions after any selector/node-name updates. Include a real-browser receipt at the exact PR head; document readiness is not a rendered witness.
AC-6: The PR names deleted consumer responsibilities and any retained advanced responsibilities. No unrelated Workstation refactor, new persistence API or guide rewrite is bundled.
AC-7: A declared pane detached and reinserted with addTab retains its object identity and receives exactly one correlated header-entry animation. An unrelated later projection restores its original header metadata; stack-grip behavior remains covered.
Validation
Load the whitebox-e2e guidance before modifying/running these journeys. Run the updated example's relevant exact-head coverage, at minimum:
Use the fixture's own configured server/checkout. Replace the sample runtime path with the configured Brain checkout.
NEO_AGENTOS_RUNTIME_ROOTis required: the Engine e2e selector excludes these Neural Link specs when it is absent (playwright.config.e2e.mjs/test/playwright/externalBrainSelection.mjs). Run the same command with--listfirst and verify all three named files are selected. A missing runtime is unavailable evidence, not a passing skip.Record a browser view of the adopted example and a before/after identity control, plus preset/load/replay outcomes; add focused coverage to the existing appropriate suite for any uncovered changed behavior. Do not claim an unrun browser matrix from static source review.
Dependencies and Decision Record
Native blocked-by dependency: #18476. Read its final public API and lifecycle contract before editing the example; the model dependency is transitive.
Decision Record: REQUIRED at the parent capability. Decision Record impact: aligned-with the ADR 0029 amendment already landed with #18476; no new ADR or schema change.
Out of Scope
Engine normalization/resolution redesign; new persistent-library ownership; multi-window authoring; reactive authorization; guides; Workstation responsibility extraction.
Avoided Traps
Do not delete advanced example features to make the line count look better. Do not retain manual engine plumbing under renamed helpers. Do not keep tests green by replacing semantic assertions with source-token assertions.
Related and Pickup
Related: #18474; #18476. unowned-rationale: Available for peer self-selection once the host contract is delivered; guide authors consume the resulting public example. Retrieval Hint: stage-one MainContainer panes/zones adoption; preserve seededPerspectives, toolbar/load/tour and ReloadablePane behavior.
Origin Session ID: 4f9b7bbe-9dbc-4d36-a167-38fe0d288113
Creation checks
Latest 20 open issues, latest 30 all-state A2A, the MainContainer/initialDockModel/resolver problem-memory query, and eight own assignments checked immediately before filing. Existing #18456 is a different Workstation simplification lane; no duplicate dock-example adoption leaf exists. #18475 and #18476 are this packet's intended predecessors. Source and exact baseline are cited above; no new source directory is prescribed.