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	13022
title	Harness visual system: neo-dark/light from day one
state	Closed
labels	enhancementdesignaiarchitecture
assignees	neo-gpt
createdAt	Jun 12, 2026, 11:30 PM
updatedAt	Jun 13, 2026, 12:44 AM
githubUrl	https://github.com/neomjs/neo/issues/13022
author	neo-gpt
commentsCount	0
parentIssue	13012
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 13, 2026, 12:44 AM

Harness visual system: neo-dark/light from day one

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

neo-gpt commented on Jun 12, 2026, 11:30 PM

Context

Operator design direction on Epic #13012 made the harness UI quality bar explicit: one peer should own the visual/design focus, and the harness must support the portal theme pair (neo-theme-neo-dark + neo-theme-neo-light) from day one rather than treating theming as polish after functionality lands. A later #13012 strategy update sharpened the product frame: Claude-Desktop-style parity is the floor; the category bet is the flat-peer, cross-family institution getting a face. The visual system is therefore not decoration — it is part of the product proof.

Release classification: post-release harness product-line work; attach to Project 13 (Agent Harness live state), not the v13 release board.

The Problem

The harness roadmap is splitting into settings, chat, transcript, grid-pane, Fleet Manager, and deploy-plane work. Without a focused visual-system leaf, each slice can make local UI choices and still pass its narrow acceptance criteria, leaving the first integrated harness feeling assembled instead of designed. That is especially risky here because the first user journey must make a multi-agent institution legible: users need to understand agent identity, lane state, review state, messages, and work surfaces at a glance.

The risk is not "missing colors". The risk is product incoherence: theme support, density, contrast, state treatment, and interaction hierarchy drift independently across surfaces that should feel like one cockpit.

The Architectural Reality

The theme pair is real and already shipped in current substrate: apps/portal/neo-config.json includes neo-theme-neo-dark and neo-theme-neo-light; the SCSS trees include resources/scss/theme-neo-dark/** and resources/scss/theme-neo-light/**; apps/portal/view/ViewportController.mjs toggles the pair.
src/DefaultConfig.mjs already documents theme configuration and includes neo-theme-neo-light in defaults.
Epic #13012 owns the harness product shape. Board 13 is the live work-state surface; #13020 owns ADR 0020 as the cold-read concept anchor; #13018 owns the Markdown VDOM component, not the harness visual system.
The first harness surfaces named in the operator direction are settings pane, chat, transcript, and grid-pane flows. This ticket owns the cross-cutting visual-system foundation for those surfaces; it does not own their full product behavior.

The Fix

Create the first focused visual-system/theming foundation for the Agent Harness app line:

Identify the current or intended harness app surface path during intake. If the app shell is not present yet, do not invent a blind path; either create the minimal shell prerequisite under the correct parent ticket or mark this ticket blocked on that prerequisite.
Ensure the harness app surface loads both neo-theme-neo-dark and neo-theme-neo-light from the start, following the portal theme-pair precedent rather than a one-theme MVP.
Define a small, reusable visual contract for the first harness work surfaces: settings pane, chat, transcript, and grid-pane. The contract should cover density, hierarchy, theme roles, empty/loading/error states, focus/selection states, and agent/lane status affordances.
Add visual verification evidence for both themes on the implemented surfaces. For app/UI work, use the repo's browser/visual verification path and include desktop plus mobile viewport evidence where the surface exists.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Harness app theme configuration	Epic #13012 operator design directive; portal `neo-config.json` precedent	Load `neo-theme-neo-dark` and `neo-theme-neo-light` from the first harness UI slice	If no harness app shell exists, block on/apply the shell prerequisite instead of inventing a path	App config / harness README if present	`rg` verified portal theme pair + theme SCSS substrate
Harness visual-system contract	Epic #13012 strategy: institution gets a face; H2 user journey ladder	Shared quality bar for settings, chat, transcript, grid-pane surfaces	Document surface stubs when behavior is not yet implemented; do not fake completed UI	Repo-local harness design note or app README section	Visual verification screenshots in both themes
Visual verification evidence	Neo frontend verification discipline	Desktop and mobile screenshots or equivalent browser evidence for both themes	If the app shell is absent, record the blocker and do not claim visual completion	PR body evidence	Browser/Playwright/Neural-Link evidence, scoped to the surfaces touched

Decision Record impact

depends-on #13020 for the cold-read Agent Harness concept anchor, and aligned-with ADR 0018 for Neo's identity framing: the harness is the Institution getting a user-facing Body, not a generic chat wrapper. No accepted ADR conflict identified.

Acceptance Criteria

The implementation confirms the harness app path before writing UI code; no blind apps/ path invention.
The harness app config or equivalent shell loads both neo-theme-neo-dark and neo-theme-neo-light from the first UI slice.
Settings pane, chat, transcript, and grid-pane surfaces have a shared theme-aware baseline contract, even if some are still stubs.
Empty, loading, error, focus/selection, and agent/lane-status states are accounted for in the contract or implemented UI.
Visual verification covers both themes; desktop and mobile evidence are included when the surface can render.
The PR body states which roadmap horizon(s) it serves from #13012, with H2 Your-first-agent-beautifully as the default unless the implemented slice proves a stronger horizon mapping.

Out of Scope

Full Fleet Manager feature behavior (#13015).
Markdown parser/component implementation (#13018).
ADR 0020 authorship (#13020).
Deploy plane and hosted-service monetization surfaces.
Marketing landing pages or hero-page polish. This ticket is about the actual harness tool surfaces.

Avoided Traps

Afterthought theming — adding dark/light later guarantees UI drift across early slices.
One-note palette — the design bar is theme-aware hierarchy and state clarity, not tinting every surface one color.
Marketing-first composition — the harness is an operational cockpit; the first screen should be usable product surface, not a landing page.
Path invention — if the harness app shell is not present, the correct move is a prerequisite or blocker, not guessing a directory.

Parent: Epic #13012. Live board: Project 13. Concept anchor: #13020. Fleet Manager epic: #13015. Markdown VDOM sibling: #13018.

Duplicate / freshness sweep:

KB semantic sweep: searched for Agent Harness visual system theme foundation neo-dark neo-light design system settings chat transcript grid pane duplicate ticket; no equivalent active ticket returned, only historical theme precedents.
Live latest-open sweep: checked latest 20 open issues at 2026-06-12T21:28:52Z; #13012/#13020/#13018 exist, no concrete harness visual-system/theme leaf found.
A2A in-flight sweep: checked latest 30 messages immediately before filing; found my own [lane-intent], #13018 parser progress, #13012 strategy update, and no competing concrete visual-system leaf.

Origin Session ID: 019eba1b-f70e-74c0-9dfb-8666901c3c0d

Retrieval Hint: "Agent Harness visual system neo-dark neo-light settings chat transcript grid-pane H2 Your-first-agent-beautifully"