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	18313
title	Record observed popup placement as a transaction participant
state	Closed
labels	enhancementaitestingarchitecturecoredashboard
assignees	neo-gpt-emmy
createdAt	Sep 4, 2026, 8:17 PM
updatedAt	Sep 6, 2026, 11:43 AM
githubUrl	https://github.com/neomjs/neo/issues/18313
author	neo-gpt
commentsCount	3
parentIssue	18303
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[x] 18312 Commit multi-workspace dock transactions atomically, [x] 18310 Add immutable per-group transaction history and cursor, [x] 18309 Bind transaction groups across window generations, [x] 18308 Hard-cut dock topology persistence to keyed workspace records
blocking	[x] 18316 Add Workstation multi-window undo, redo, save, and reload
closedAt	Sep 6, 2026, 11:43 AM

Record observed popup placement as a transaction participant

Closed v13.2.0/archive-v13-2-0-chunk-19 enhancementaitestingarchitecturecoredashboard

neo-gpt commented on Sep 4, 2026, 8:17 PM

Context

D#18224 resolved window placement as a semantic participant expressed relative to the main frame. manager.Window already reports live outer rectangles and the dock drag coordinator already has a candidate-scoped 250ms quiescence endpoint. The missing behavior is free native movement outside a drag candidate.

The Problem

Persisting absolute screen coordinates breaks when monitor topology changes. Recording requested moveTo coordinates lies when the browser refuses or clamps them. Treating every relative-offset delta as a popup transaction is also wrong: moving the main frame changes all popup offsets even though no popup moved.

The Architectural Reality

manager.Window stays geometry-only. A Group-bound placement participant observes which windowId changed. Popup movement appends one quiesced before/after {dx,dy} effect-first transaction; main movement re-bases every durable hint and snapshot without advancing history. Undo updates the hint, requests movement, then records the observed effect separately.

Producer boundary

This participant observes placement for semantic workspace documents already registered in the Group. A documentless window reservation has no durable placement-hint key. #18314 owns ordinary tear-out admission as a full Workspace through the Group claim, including the first semantic document and shared-history write; #18316 proves the composed production save/reload/undo journey. This is the existing D#18224 full-Workspace contract, not permission to preserve bare vessels as the delivered product or to introduce a second document owner. All seven placement acceptance criteria below remain required.

The Fix

Lift the existing quiescence mechanism beyond candidate scope, bind it to Group workspace slots, derive offsets from observed main/popup rows, and implement popup-versus-main ingestion. Restore clamps against current screens or uses semantic fallbackTarget; the main slot persists no rectangle. Geometry caused by an admitted native effect is correlated to that effect's transaction and window generation; it completes an observed receipt rather than entering again as a free user move.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
placement hint	D#18224 OQ1	`{workspaceKey, dx, dy, fallbackTarget}`	semantic fallback/clamp	ADR + JSDoc	popup move/reload arm
quiescence	existing 250ms candidate clock	one start/end record for a free move	no stable end means no invented row	JSDoc	burst coalescing control
main movement	Mnemosyne falsifier	re-base hints/snapshot, preserve cursor	none	JSDoc	N-popup main-only move
requested native effect	main native API Boolean/observed rect	truth is observed outcome	refusal receipt, no fictive success	JSDoc	refusal/clamp controls

Decision Record impact

Amends/implements ADR 0029's former no-geometry rule with relative semantic hints only.

Decision Record

Required prerequisite: the #18303 hard-cut ADR leaf.

Discussion Criteria Mapping

Owns OQ1 and the native-effect half of criterion 8.

Acceptance Criteria

A popup free move produces one quiesced before/after relative-offset transaction from observed rows.
A burst of movement reports coalesces through the existing bounded clock; the mechanism is lifted, not duplicated.
Moving only the main window with N popups re-bases N hints and publishes one current snapshot without appending history or moving a popup.
Undo/redo requests popup placement from the updated hint and stores the observed terminal effect separately. Exercise undo → native move → geometry reports → quiescence: the reports append no new transaction, leave the undo cursor and redo tail intact, and redo remains usable. A subsequent independent user move still appends once; a blanket suppression that loses that move fails the control.
Refused/clamped native movement never records requested coordinates as truth. A late receipt for a retired window generation cannot move or update its successor.
The durable schema contains no absolute rect, monitor id, screen coordinate, or windowId; the main slot has no rect.
Missing screen topology clamps or uses fallbackTarget while keeping semantic composition restorable.

Out of Scope

Cross-Group movement, drag target isolation, transaction-history storage, or popup creation permission.

Avoided Traps

No absolute geometry; no manager.Window history logic; no candidate-only detector; no one-row-per-frame log; no popup row for a main-only move.

Part of #18303. Blocked by Group identity, immutable history, and atomic commit.

Causality precedent: NEO_INLINE_CODE_9 already excludes geometry produced by its parking/embodiment/settlement operations from fresh native gestures. Preserve that distinction when lifting quiescence. D#18224's transaction protocol owns transaction/effect correlation and generation-fenced receipts.

Origin Session ID: 01a06b6d-3323-7fa0-a10b-bbc4871c8780

Retrieval Hint: D18224 relative popup placement main move rebase quiescence observed effect

Creation freshness: live latest-open and all-status A2A sweeps found no equivalent placement-participant leaf.