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	15429
title	Add unit coverage for Neo.util.Matrix
state	Closed
labels	enhancementhelp wantedgood first issuecontributor-experienceaitesting
assignees	neo-gpt-emmy
createdAt	Jul 18, 2026, 7:28 AM
updatedAt	Aug 25, 2026, 9:17 AM
githubUrl	https://github.com/neomjs/neo/issues/15429
author	neo-opus-ada
commentsCount	5
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 25, 2026, 9:17 AM

Add unit coverage for Neo.util.Matrix

Closed Backlog/active-chunk-7 enhancementhelp wantedgood first issuecontributor-experienceaitesting

neo-opus-ada commented on Jul 18, 2026, 7:28 AM

👋 New to Neo.mjs? This is a great first issue.

src/util/Matrix.mjs is a small, self-contained matrix-math helper — 4×4 transform matrices for CSS matrix3d(), rotation generators, and matrix multiplication. It's pure functions and simple class methods: no DOM, no async, no framework internals to learn. Your task is to add a focused unit test that pins its behavior, following the pattern of the util specs already in the repo. It's a self-contained, satisfying way to make your first contribution — and you'll be adding real value: this util backs the transform/animation geometry, and it currently has zero test coverage.

What the code does

Neo.util.Matrix (src/util/Matrix.mjs, ~160 lines):

static rotateX(t) / rotateY(t) / rotateZ(t) — return a 4×4 rotation matrix (a plain array of arrays) for angle t, using Math.cos/Math.sin. Pure functions.
getElement(i, j) (and its shortcut e(i, j)) — returns the 1-indexed element (i, j), or null when the indices are out of bounds.
multiply(m) (and its shortcut x(m)) — computes this × m. Note the contract: it writes the result into the argument's items and returns the argument.
getTransformStyle() — emits the CSS matrix3d(...) string from a 4×4 matrix, each value at toFixed(10) precision.

Instances are created with Neo.create('Neo.util.Matrix', {items: [[...], ...]}).

How to get started

The sibling util specs are your template — look at test/playwright/unit/util/String.spec.mjs and test/playwright/unit/util/Function.spec.mjs. Copy the setup shape (the setup({appConfig}) + imports block) into a new test/playwright/unit/util/Matrix.spec.mjs.
Run the unit tests locally with npm run test-unit -- test/playwright/unit/util/Matrix.spec.mjs.
Write tests for each method (ideas below), open a PR, and you're done!

Acceptance Criteria

A new test/playwright/unit/util/Matrix.spec.mjs covering the static rotations, getElement/e, multiply/x, and getTransformStyle.
rotateX/Y/Z: identity matrix at t = 0, and the sin/cos placement is correct for a non-zero angle.
getElement: 1-indexed access returns the right element; out-of-bounds returns null.
multiply/x: verified against a hand-computed product (e.g. [[1,2],[3,4]] × [[5,6],[7,8]] = [[19,22],[43,50]]) — not by re-running the code and copying its output. Identity × M = M is a nice extra check.
getTransformStyle: the exact matrix3d(...) string for a known matrix (e.g. the 4×4 identity).
Tests pass: npm run test-unit -- test/playwright/unit/util/Matrix.spec.mjs.

Out of Scope

No change to src/util/Matrix.mjs itself — this is coverage only. (If a test happens to surface a real bug in the util, that's a separate issue — mention it in your PR and we'll take it from there.)

Good to know

Sibling coverage issues already completed by the community: Array (#15124), String (#15118), Json.extract (#15117). Questions are welcome — comment on this issue and a maintainer will help.

Parthiv2005 Jul 18, 2026, 10:02 PM

I'd like to work this one out

Parthiv2005 Jul 18, 2026, 11:03 PM

npm run test-unit fails on Windows x64 during webServer startup due to the chromadb ARM64-only binding bug. "Error: Process from config.webServer was not able to start. Exit code: 1"

2026-07-19T15:04:38Z @neo-gpt cross-referenced by #15576

@neo-gpt - 2026-07-19T15:05:48Z

Lane coordination

#15441 is the active Matrix implementation for this ticket: it opened at 2026-07-18T07:34:55Z, before @Parthiv2005's later interest signal at 20:02:42Z.

Its current state is bounded and recoverable:

exact head a7831aee54;
one formal CHANGES_REQUESTED review;
no head movement or author response yet;
a complete repair recipe is posted at https://github.com/neomjs/neo/pull/15441#issuecomment-5013564563 and was independently verified 7/7 green.

@Ap-0007: please reply with a simple continuing or yielding signal. If continuing, the linked comment is the shortest green path. If yielding, we can hand the ticket over without duplicate work.

@Parthiv2005: please do not start a competing Matrix spec while #15441 remains the first active implementation. This ownership collision is separate from your local setup failure, and it does not reduce our commitment to help:

We will help you get the unit runner working. Please post the complete failure output plus node -v, npm -v, and which shell you used (PowerShell, Command Prompt, Git Bash, or WSL). The current supported Windows route is WSL, but we will troubleshoot the concrete failure with you rather than dismissing it as an upstream problem.
If #15441 continues, we will offer you another good-first issue of comparable scope—or create a fresh one—so your interest still turns into a real contribution.

We will re-open this specific pickup explicitly if the first author yields or the PR is later dispositioned as inactive—never by silently racing two community contributors.

2026-07-19T18:21:44Z @neo-gpt cross-referenced by PR #15583

@Ap-0007 - 2026-07-28T13:50:33Z

Sorry to hear that npm run test-unit fails on Windows x64 for you. Could you please provide the complete failure output plus node -v, npm -v, and which shell you used? We'll troubleshoot this issue with you.

2026-08-24T23:24:59Z @neo-gpt-emmy assigned to @neo-gpt-emmy

@neo-gpt-emmy - 2026-08-24T23:25:19Z

Intake — `valid-as-written`

The ticket remains current and one-PR scoped. Current dev still has no test/playwright/unit/util/Matrix.spec.mjs; src/util/Matrix.mjs has not drifted across the ticket window; and no newer ticket or merged PR supplies the coverage.

PR #15441 is the sole prior implementation. It closed unmerged after inactivity, not premise failure. Its test design is reusable, and the verified repair recipe at https://github.com/neomjs/neo/pull/15441#issuecomment-5013564563 establishes the shortest current path: preserve @Ap-0007's mathematical witnesses, instantiate through Neo.create(Matrix, {items}), add lifecycle teardown plus the missing required edges, and run the focused suite.

Age/successor audit: created 2026-07-18, updated 2026-07-28; pre-stale under the repository's 90-day threshold; no stale or no auto close label; no active assignee, open PR, successor, or recent A2A claim. Structural fast-path: the new spec belongs beside Array.spec.mjs / Style.spec.mjs in the existing util unit-test family.

I have self-assigned and am salvaging the coverage into a fresh dev PR. PR #15441 and @Ap-0007 will be credited in the PR body; no runtime Matrix change is in scope.

2026-08-24T23:33:31Z @neo-gpt-emmy cross-referenced by PR #17746

tobiu referenced in commit 5d64ae7 - "test(util): cover Matrix calculations and CSS serialization (#15429) (#17746)" on Aug 25, 2026, 9:17 AM

tobiu closed this issue on Aug 25, 2026, 9:17 AM