What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13089
title	Harness docking: define split/tab adapter boundary
state	Closed
labels	enhancementdesignaiarchitecture
assignees	neo-gpt
createdAt	Jun 13, 2026, 12:56 PM
updatedAt	Jun 13, 2026, 4:57 PM
githubUrl	https://github.com/neomjs/neo/issues/13089
author	neo-gpt
commentsCount	0
parentIssue	13012
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 13, 2026, 4:57 PM

Harness docking: define split/tab adapter boundary

Closed v13.1.0/archive-v13-1-0-chunk-2 enhancementdesignaiarchitecture

neo-gpt commented on Jun 13, 2026, 12:56 PM

Context

#13030 is the scoping anchor for QT-grade docking strategies on Neo's infinite canvas: dock zones, nested splits, tabbed dock slots, and blueprint-compatible save/restore. The first leaf, #13061 / PR #13062, has landed the dock-zone model contract. The next leaf, #13086 / PR #13087, defines transient drag-to-dock preview state and is approved but not merged as of this filing.

This ticket is the next one-PR leaf in that decomposition. It defines the adapter boundary that turns the dock-zone model into renderable split/tab container structure without prematurely inventing a core Dock primitive or bundling persistence and preview visuals into the same PR.

Release classification: post-release Agent Harness product-line leaf; Project 13, not the v13 release board.

The Problem

The dock-zone model contract establishes the data shape, but there is still no documented boundary for consuming that model in Neo's existing UI primitives. If the next implementation jumps straight from model to full UI, it will conflate several separate decisions:

whether nested splits map through existing vbox / hbox composition or require a dedicated container;
whether tabbed dock slots consume existing src/tab/Container.mjs semantics or need a dashboard-specific adapter;
how stable dock item identity maps to component references and stale restore behavior already handled by #13063;
where drag-preview producers hand off to real layout mutation after #13086 lands;
whether blueprint persistence fields are consumed now or deferred to a persistence leaf.

That would recreate the #13030 broad-ticket problem inside a PR. The missing piece is a narrow adapter contract: model in, Neo layout/tab primitives out, no save/restore implementation yet.

The Architectural Reality

V-B-A before filing:

#13030 remains open as the scoping anchor and explicitly lists remaining leaves after #13061: drag-to-dock preview, split/tab rendering adapter, blueprint persistence, and demand validation.
#13061 is closed and PR #13062 is merged, so the dock-zone model contract is the source of authority for this adapter leaf.
#13086 / PR #13087 is approved and green but still open, so preview-state producer details should be treated as adjacent context, not a hard implementation dependency.
Live latest-open sweep at 2026-06-13T10:56Z checked the latest 20 open issues. Adjacent issues found: #13030, #13063, #13086. No equivalent split/tab adapter boundary leaf exists.
Scope-specific GitHub sweep for dock split tab rendering adapter found #13030 and #13063 only; neither defines the adapter boundary this ticket covers.
A2A last-30 sweep at 2026-06-13T10:56Z showed no competing [lane-claim] / [lane-intent] for this split/tab adapter scope.
Local source sweep found existing primitives that should be considered before adding anything new: src/tab/Container.mjs, src/component/Splitter.mjs, layout-family usage around vbox / hbox / card semantics, and the existing dashboard drag lineage named by #13030.
Knowledge Base semantic check was attempted and failed (Knowledge Base is not available: requested resource could not be found), so this ticket does not rely on KB silence.
Memory Core semantic search surfaced the active #13030 decomposition trail (#13061, #13086, #13087) and no prior split/tab adapter leaf.

The Fix

Define the split/tab adapter boundary for the docking model.

Expected shape:

Read the merged dock-zone model contract from #13061 / PR #13062 and identify the minimal adapter input it exposes.
Define how nested split nodes map to existing Neo layout composition (vbox, hbox, splitter affordances) without adding a parallel layout engine.
Define how tabbed dock slots map to existing tab/container semantics, including stable item identity and active-item selection.
State where the adapter boundary lives: dashboard/harness adapter, general layout helper, or a new primitive. If a new .mjs file is proposed, run structural-pre-flight before implementation.
Keep blueprint persistence as shape compatibility only. Actual save/restore belongs to a later leaf.
Keep drag-to-dock preview visuals out of scope; this adapter receives committed layout changes, not hover-state rendering.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Boundary	Docs / Evidence
Split/tab adapter boundary	#13061 dock-zone model contract + #13030 decomposition	One named boundary consumes dock-zone model nodes and produces Neo layout/tab structures	If ownership is uncertain, document rejected placements and keep implementation docs-only	PR body names chosen owner and cites source reads
Nested split mapping	Existing `vbox` / `hbox` / splitter primitives	Represent split orientation and ratio using existing layout concepts where possible	Do not invent a parallel split graph unless source evidence proves existing primitives cannot host it	Static contract examples and unit/static tests if code lands
Tabbed dock slot mapping	Existing tab/container semantics	Map dock slot item order and active item to tab-compatible structure	Do not fork tab semantics for harness-only convenience	Contract table or adapter tests cover order + active item
Component identity handoff	#13063 stale componentRef restore behavior + dock model stable IDs	Preserve stable dock item identity while allowing stale runtime refs to fail closed	Do not make runtime component refs part of serializable blueprint state	Contract distinguishes serializable IDs from runtime refs
Preview producer boundary	#13086 preview-state contract when merged	Adapter consumes committed drop/layout mutations, not live hover/preview state	If #13086 is not on `dev`, name the pending dependency and keep preview coupling out	PR body distinguishes producer vs committed adapter boundary
Blueprint persistence seam	#13030 blueprint compatibility requirement	Keep emitted structure persistence-compatible	Actual save/restore implementation is a later leaf	JSON examples remain persistence-ready without writing storage code

Decision Record Impact

Aligned-with ADR 0020 and Epic #13012. This ticket refines the harness docking product-line decomposition and should not amend an ADR unless implementation proves the adapter must become a general core layout primitive.

Acceptance Criteria

A durable adapter-boundary contract exists for consuming the dock-zone model into split/tab renderable structures.
The contract names the owning layer and rejects at least two alternative placements with source-backed rationale.
Nested split orientation, ratio/default sizing, and child ordering are mapped to existing Neo layout primitives or explicitly deferred with evidence.
Tabbed dock slot item order, active item, and stable identity semantics are mapped to existing tab/container primitives or explicitly deferred with evidence.
Runtime component references remain outside the serializable layout state and align with #13063's stale-restore behavior.
Drag-preview/hover state from #13086 is not bundled; the boundary is for committed layout structure.
Blueprint persistence remains compatibility-only; no save/restore storage implementation lands in this PR.
If implementation introduces or relocates any .mjs file, the PR documents structural-pre-flight evidence for the chosen destination.

Out of Scope

Drag-to-dock preview rendering or hover feedback.
Layout save/restore persistence implementation.
Cross-window choreography (#13025 / #13028).
Partner-specific layout presets or public client naming.
Neural Link mutation-to-commit write-through.
A general core Dock primitive unless source evidence proves the adapter cannot remain narrower.

Avoided Traps

Core primitive too early — rejected. Start with an adapter boundary and let implementation evidence justify any later core lift.
Parallel tab system — rejected. Existing tab/container semantics must be consumed or explicitly proven insufficient.
Preview-state coupling — rejected. Hover/preview producers are separate from committed layout structure.
Persistence bundling — rejected. The adapter must be persistence-compatible, but storage/save/restore is a later leaf.

Parent: #13012 Scoping source: #13030 Depends on: #13061 / PR #13062 Adjacent: #13063, #13086 / PR #13087, #13025, #13028

Origin Session ID: d2d31447-5009-47a8-992e-9ecc35b806c1 Retrieval Hint: "harness docking split tab adapter boundary dock-zone model vbox hbox tab Container Splitter blueprint componentRef"