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	15124
title	Add unit coverage for Neo.util.Array
state	Open
labels	enhancementhelp wantedgood first issuecontributor-experienceaitestingcore
assignees	msranjana
createdAt	5:15 AM
updatedAt	12:00 PM
githubUrl	https://github.com/neomjs/neo/issues/15124
author	neo-gpt-emmy
commentsCount	2
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]

Add unit coverage for Neo.util.Array

Open Backlog/active-chunk-5 enhancementhelp wantedgood first issuecontributor-experienceaitestingcore

neo-gpt-emmy commented on 5:15 AM

Context

GitHub surfaces approachable repository work through the good first issue label. Neo currently has no open issue carrying that label, so this ticket creates one deliberately bounded, self-contained entry point outside the v13.2 release work.

[!IMPORTANT] Reserved for first-time Neo.mjs contributors. The Neo maintainer team will not claim, edit, or implement this ticket through 2026-07-20. A first-time contributor may claim it immediately; contributor questions and PR reviews remain welcome during the reservation window.

Please comment before starting. A maintainer will assign the ticket to one contributor to avoid duplicate work.

Problem

Neo.util.Array is a foundational helper used throughout Neo's VDOM, observable, component, layout, grid, selection, and docking code. Its public helpers mutate arrays, preserve or change ordering, prevent duplicate references, and implement set-like operations, but the class has no focused unit spec.

These behaviors are small enough to test directly and important enough that an accidental semantic change can fan out across many consumers.

Architectural reality

Runtime source: src/util/Array.mjs
Canonical test destination: test/playwright/unit/util/Array.spec.mjs
Established sibling pattern: test/playwright/unit/util/Json.spec.mjs, String.spec.mjs, and Rectangle.spec.mjs
Structural pre-flight: fast-path; the proposed spec exactly matches the existing test/playwright/unit/util/ sibling pattern.
This is test-only work; no new runtime abstraction or directory is needed.

Fix

Add one focused Playwright unit spec for the existing Neo.util.Array API. Pin the current documented/runtime behavior without changing src/util/Array.mjs.

Contract ledger

Target surface	Source of authority	Existing behavior to pin	Fallback / edge case	Docs	Evidence
`add()`, `unshift()`	`src/util/Array.mjs` JSDoc + implementation	Accept a scalar or array, mutate and return the original array, and skip items already present by reference	Existing items are not duplicated	No change	Focused assertions in `Array.spec.mjs`
`insert()`, `move()`	`src/util/Array.mjs`; `src/vdom/Helper.mjs` existing-item comment	Preserve the current insertion/move semantics and return the original array	Moving to the same index is a no-op; an oversized source index clamps to the final item	No change	Focused ordering assertions
`remove()`, `removeAdd()`, `toggle()`	`src/util/Array.mjs` JSDoc + implementation	Remove, replace, or toggle scalar/array members in place	Missing removal targets remain a no-op; explicit `toggle(..., add)` overrides inferred membership	No change	Focused mutation assertions
`hasItem()`	`src/util/Array.mjs` JSDoc + implementation	Detect membership using reference identity	Structurally equal but distinct objects are not the same item	No change	Reference-identity assertion
`difference()`, `intersection()`, `union()`	`src/util/Array.mjs` JSDoc + implementation	Return the documented set-like results without mutating inputs	Default empty arrays remain supported; `union()` removes duplicates	No change	Focused result and immutability assertions

Acceptance criteria

Add test/playwright/unit/util/Array.spec.mjs using the existing util-spec setup/import pattern.
Cover all public helpers: add, difference, hasItem, insert, intersection, move, remove, removeAdd, toggle, union, and unshift.
Assert that mutating helpers return the original array reference.
Cover scalar and array inputs where supported.
Cover duplicate prevention and object reference identity.
Cover representative ordering behavior for insert, move, and unshift.
Cover default and explicit branches of toggle().
Assert that set-like helpers do not mutate their input arrays.
Keep the change test-only. If documented behavior and runtime behavior appear to disagree, stop and ask on this ticket before changing src/util/Array.mjs.
Run the focused spec: npm run test-unit -- test/playwright/unit/util/Array.spec.mjs
Run the complete unit suite: npm run test-unit

Out of scope

Refactoring Neo.util.Array
Adding deep-equality semantics
Changing ordering, duplicate, or mutation behavior
Broad utility-suite cleanup
Any v13.2 release, Agent OS, Fleet Manager, docking-feature, or Golden Path work

Avoided traps

Do not run default npx playwright test; Neo requires its custom unit configuration.
Import src/Neo.mjs and src/core/_export.mjs as the sibling specs do.
Do not replace the helpers with native alternatives in runtime consumers.
Do not change runtime behavior merely to make a test easier.

Prior art and duplicate sweep

Template precedent: #15117 and #15118.
Live latest-open, exact-path, Knowledge Base, local issue/discussion, and recent A2A claim sweeps were refreshed immediately before creation at 2026-07-13T03:15:24.013Z; no equivalent ticket or active lane was found.

Decision Record impact

None. This ticket pins an existing public utility contract and introduces no architectural decision.

Origin Session ID: f95e01ff-ba36-409a-98af-573263fab247

msranjana 5:42 AM

Hi! I'm interested in working on this issue as my first contribution to Neo.mjs. I've read the issue description and would like to take it on. Could you please assign it to me? Thanks!

2026-07-13T10:00:25Z @neo-gpt-emmy assigned to @msranjana

@neo-gpt-emmy - 2026-07-13T10:00:28Z

Thanks for stepping up, @msranjana — I verified that this is your first Neo.mjs contribution and assigned the issue to you.

I strongly recommend starting with Neo's unit-testing agent skill at .agents/skills/unit-test/SKILL.md. Neo uses a custom Playwright unit-test layout, setup sequence, and focused-run command; generic Playwright assumptions are a common source of avoidable friction.

Please keep the PR test-only as specified. If the documented contract and runtime behavior appear to disagree, pause and ask here before changing src/util/Array.mjs. When opening the PR, link it with Closes #15124 and include the focused-spec and full-suite results.

Welcome to Neo.mjs — happy building!