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	13086
title	Harness docking: define drag-to-dock preview state
state	Closed
labels	enhancementdesignaiarchitecture
assignees	neo-gpt
createdAt	Jun 13, 2026, 12:14 PM
updatedAt	Jun 13, 2026, 4:45 PM
githubUrl	https://github.com/neomjs/neo/issues/13086
author	neo-gpt
commentsCount	0
parentIssue	13012
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 13, 2026, 4:45 PM

Harness docking: define drag-to-dock preview state

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

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

Context

Epic #13012 names the Agent Harness / infinite-canvas product line, and #13030 captured the QT-grade docking strategy scoping anchor for dock zones, nested splits, tabbed slots, preview feedback, and persistence.

The first decomposition leaf, #13061, defined the dock-zone model contract and PR #13062 is merged. That unlocks the next leaf: preview state for drag-to-dock interactions. This ticket deliberately stays before split/tab rendering and before layout persistence.

Release classification: post-release product-line leaf; boardless, not v13 release-gating.

The Problem

The accepted dock-zone model gives future code a semantic target, but users still need feedback while dragging: which edge, split target, or tab slot would receive the pane if dropped now.

If preview state is bundled with split/tab rendering or persistence, reviewers would have to decide interaction semantics, visual affordances, layout mutation, and serialization in one PR. That repeats the broad-ticket risk #13030 explicitly avoided.

The missing substrate is narrower: a transient, runtime-only preview-state contract that rides the existing drag pipeline and can later be consumed by rendering and persistence leaves.

The Architectural Reality

V-B-A before filing:

#13030 is open as the scoping anchor, and its comments record #13061 / PR #13062 as the completed dock-zone model-contract leaf.
PR #13062 is merged, so the model leaf is no longer a blocker for preview-state decomposition.
Latest-open sweep checked the latest 20 open issues at 2026-06-13T10:12Z; no equivalent preview-state leaf exists. Closest issues: #13030 scoping anchor and #13063 stale componentRef restore behavior.
Scope-specific GitHub searches for drag-to-dock preview and dock preview state returned only #13030 and #13063, not a preview-state contract leaf.
Local exact sweep over resources/content/issues and resources/content/discussions for drag-to-dock, dock preview, docking preview, dock-zone preview, and dock zone preview returned no existing preview-state ticket or Discussion.
A2A last-30 sweep at 2026-06-13T10:12Z had no overlapping lane-claim or lane-intent; the active #13077 claim is wake-delivery retry-store work and non-overlapping.
Knowledge Base semantic duplicate check was attempted and failed because the KB server is currently unhealthy (knowledgeBase:null; requested resource not found), so this ticket does not rely on KB silence.
Labels were verified live: enhancement, ai, architecture, and design exist.

The preview state must compose with the existing continuous-drag pipeline and dock-zone model. It must not create a second drag system and must not persist hover-only runtime state into future blueprints.

The Fix

Define the drag-to-dock preview-state contract for the harness docking lane.

Expected shape:

Name the runtime preview-state fields needed while a pane is dragged over a dock target.
Bind those fields to the accepted dock-zone model terms: edge target, split orientation/position, tab slot, rejected target, and stable item identity.
State which existing drag/sort/window signals are allowed to produce preview state and which new parallel drag paths are forbidden.
Distinguish runtime-only hover/preview data from serializable blueprint fields.
Provide at least one harness-self-use scenario that validates the preview contract independently of the anonymized QT-migration market signal.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Boundary	Docs / Evidence
Drag-to-dock preview-state contract	#13030 + #13061 model contract	Define a transient preview payload for edge/split/tab drop intent	Do not implement split/tab rendering or persistence in this leaf	Contract doc, schema-like table, or JSDoc-backed code
Drag pipeline integration	Existing continuous-drag / dashboard sorting pipeline	Preview state is produced from existing drag move/hover signals	No parallel drag manager for docking previews	PR body cites source surfaces read before implementation
Runtime vs blueprint boundary	Neo JSON-first / blueprint direction from #13012	Runtime hover state stays ephemeral; only accepted layout mutations become serializable later	Fail closed by not writing preview-only fields into saved layout records	Tests or static examples prove preview fields are not persistence fields
Consumer handoff	Future split/tab rendering and persistence leaves	Downstream leaves can consume the preview-state contract without redefining intent semantics	If rendering exposes a missing field, update the contract before broadening implementation	PR body names downstream consumer boundaries

Decision Record impact

Aligned-with ADR 0020. This ticket refines the harness infinite-canvas / dashboard-composition lane and does not amend an ADR.

Acceptance Criteria

A drag-to-dock preview-state contract exists in a durable repo surface or JSDoc-backed code surface.
The contract covers edge targets, split preview orientation/position, tab-slot preview, rejected targets, stable item identity, and target container identity.
The contract names the existing drag/sort/window signal path that produces preview state and explicitly rejects a parallel drag system.
Runtime-only preview fields are separated from future serializable blueprint fields.
At least one harness-self-use scenario validates the preview contract independently of the anonymized QT-migration market signal.
Split/tab rendering, layout persistence, and cross-window choreography are not bundled into this PR.
If new .mjs files are introduced, the PR documents structural-pre-flight evidence for the chosen path.

Out of Scope

Split/tab container rendering.
Save/restore layout persistence implementation.
Cross-window choreography; #13025 and #13028 own that surface.
Partner-specific presets.
Styling the final visual affordance beyond what is needed to define the preview-state contract.

Avoided Traps

Parallel drag system — rejected. Preview state must ride the existing drag pipeline.
Persisting hover state — rejected. Preview state is runtime-only until a drop commits a layout mutation.
Bundling with rendering and persistence — rejected. The preview contract should be reviewable before UI and serialization land.
Treating external docking libraries as shape authority — rejected. They can inform semantics, but Neo's worker/layout/blueprint substrate owns the contract.

Parent: #13012 Scoping source: #13030 Prior model leaf: #13061 Prior model PR: #13062 Adjacent choreography: #13025, #13028

Retrieval Hint: "drag-to-dock preview state dock-zone model contract runtime hover split tab preview blueprint boundary"