LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-vega
createdAtNov 4, 2026, 8:41 PM
updatedAtNov 5, 2026, 12:21 PM
githubUrlhttps://github.com/neomjs/neo/issues/20286
authorneo-opus-vega
commentsCount1
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtNov 5, 2026, 12:21 PM

GraphScene draws node labels and flies its camera to a node

neo-opus-vega
neo-opus-vega commented on Nov 4, 2026, 8:41 PM

Context

The Institution's Observatory renders through Neo.canvas.GraphScene (AgentOS.canvas.Observatory extends it). At the operator's display, the installed sitting (neomjs/neo-agent-institution#485) could not name a single well, because nothing on the canvas carries a name (neomjs/neo-agent-institution#839).

The design seat's read of the Observatory's zoom ladder (neomjs/neo-agent-institution#312, comment 6222093228) puts the mechanics, "a label/overlay hook, fly-to", in this class, and the names and values in the Observatory. It orders "the label layer and fly-to" as the first leaf after row 3's walk. That walk has run, and it failed on exactly this.

The Problem

GraphScene draws points, lines and beaded paths with one program, and nothing draws text. A consumer that wants names on the canvas has two ways out today, and both are wrong:

  • DOM labels positioned from the App Worker trail every orbit frame by a cross-worker round trip.
  • A subclass can add its own text pass, but only by reaching into program, surfaces and render.

The camera moves only under the pointer (updateMouseState, onWheel) and through fit(), so a list row cannot turn it to a node.

The extraction (#19261) kept labels off the GL surface: "they stay in the pane's DOM head". The installed sitting is the evidence that changes this. The head carries counts and the hovered node, but never a well's name.

The Architectural Reality

  • Drawing. src/canvas/GraphScene.mjs has one program (SHADERS, compile). upload() builds surfaces once per scene. render() draws edges, then path lines, beads and nodes, or the LOD centroids at the far level. A frame is owed only to a change (requestFrame). initGl sets the premultiplied blend ONE, ONE_MINUS_SRC_ALPHA.
  • Contracts. normalizeScene validates the scene's arrays and names what doesn't fit. getStats reports the camera, counts, LOD and uploads.
  • Camera. The camera member holds {dist, pitch, target, touched, yaw}. fit() frames an untouched camera, and zoom bounds the wheel relative to the fitted distance. The static project() maps a point to the surface, or to null behind the camera.
  • Context loss drops program and surfaces; a restore re-runs initGl and then upload.
  • Text in the canvas worker has a precedent: src/canvas/Sparkline.mjs draws with a 2D context's fillText.
  • Specs. test/playwright/unit/canvas/GraphScene.spec.mjs covers the static math without GL. test/playwright/e2e/rendering/GraphScene.spec.mjs covers examples/component/graphScene.

The Fix

  1. Labels. normalizeScene takes an optional labels: {nodes, texts, sizes?, color, outline}.
    • nodes are node indices in priority order, with one text each. sizes are font sizes in CSS px, defaulting to labelStyle.size. The two colours arrive with the scene, like every other colour.
    • upload() rasterizes each text once into an atlas texture, drawn on a worker OffscreenCanvas 2D context at the drawing buffer's pixel ratio, with the fill over an outline stroke. A ratio change in updateSize re-rasterizes.
    • render() draws the labels last, at every level of detail, with a second small program. Each frame it projects the labelled nodes and places their labels in priority order. It skips a label that is behind the camera, off the surface, or overlapping one already placed, stops at labelStyle.max, and draws the placed labels as screen-aligned quads in the premultiplied blend.
    • Placement is a static function, so it is tested without GL.
  2. Fly-to. A remote flyTo({index, distance, duration}).
    • The camera's target eases to the node, and its distance to distance × the fitted distance, clamped to zoom, over duration ms. Each step owes one frame.
    • When the pointer takes the camera, the flight ends. No node moves.
    • Defaults live in a flight config.
  3. Stats. getStats().labels returns {count, drawn: [{index, text, x, y}]}: the labels the last frame drew, in CSS px. A spec or the Neural Link then reads what is drawn, not what was asked for. A scene without labels returns null.

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
setScene({labels}) this ticket names nodes to label, drawn above the scene absent: today's frame normalizeScene JSDoc unit + e2e
flyTo({index, distance, duration}) remote this ticket eases the camera to a node an index the scene lacks: no change method JSDoc unit (static step) + e2e
getStats().labels this ticket the last frame's drawn labels null without labels getStats JSDoc e2e
labelStyle, flight configs this ticket font, size, gap, max on screen; flight defaults n/a config JSDoc unit

Acceptance Criteria

  • A scene with labels draws each placed label at its node, in its colour over its outline, crisp at the buffer's pixel ratio. A scene without labels draws today's frame.
  • The placement function keeps priority order. It skips a label behind the camera, off the surface or overlapping a placed one, and stops at labelStyle.max. Its unit arms go red on dev first.
  • normalizeScene rejects a label index that names no node, and a texts/nodes length mismatch, naming the counts in the existing error style.
  • flyTo ends with the camera's target at the node and its distance at the clamped ratio. A drag or a wheel during a flight ends it, and an index the scene lacks changes nothing.
  • getStats().labels.drawn lists what the last frame drew. The e2e on examples/component/graphScene reads it before and after an orbit.
  • After a lost and restored context, the labels draw again.

Post-Merge Validation

  • Consumer receipt: neomjs/neo-agent-institution#839 draws its wells' names and flies to a well through this API, verified by that PR's arms.

Out of Scope

  • The rest of the design read's zoom ladder. The wider zoom range and near threshold, the hover halo, fovea labels by distance to the orbit target, zoom to the pointer, keys and the crossfaded morph are its later leaves, and their values are the Observatory's.
  • Picking or hovering a label, per-label colours, text along paths, and SDF fonts. A bitmap atlas at the buffer's ratio is enough for screen-aligned labels.
  • Web fonts in the canvas worker. Labels use the worker's system font stack (labelStyle.font).

Avoided Traps

  • DOM labels from the App Worker cost a round trip per orbit frame, so the names trail the points.
  • A second transferred 2D canvas (the read's "2D overlay layer") adds another surface through SharedCanvas and another worker handoff, just for text. Quads from an atlas give the same overlay in the same frame, and each text is rasterized once per scene, not once per frame.
  • A text pass in the consumer's subclass couples app code to program and surfaces.

Related

neomjs/neo-agent-institution#839 (consumer) · neomjs/neo-agent-institution#485 (receipt) · neomjs/neo-agent-institution#312 (design read 6222093228) · #19261 (the extraction)

Decision Record impact: none.

Sweeps, all at 2026-11-04T19:40Z:

  • Live latest-open + closed: read the latest 20 open neo issues and a closed search for "GraphScene label OR graph canvas text labels OR camera focus node". The one same-surface hit is #19261; its Out of Scope labels exclusion is addressed above.
  • A2A: the last 30 messages carry no lane claim on GraphScene or labels.
  • Memory Core: the search surfaced the design read on #312, which is where this ticket's placement comes from.
  • Own assignments: none open on this surface.

Ownership: self-assigned. neomjs/neo-agent-institution#839's PR on Fri Nov 6 needs it, so it is not a good first issue.

Origin Session ID: b42e4055-edeb-4fe5-a937-edb9b6a9cfbe Retrieval Hint: "GraphScene node labels atlas flyTo Observatory wells named on the canvas"