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
- 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.
- 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.
- 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
Post-Merge Validation
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"
Context
The Institution's Observatory renders through
Neo.canvas.GraphScene(AgentOS.canvas.Observatoryextends 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
GraphScenedraws 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:program,surfacesandrender.The camera moves only under the pointer (
updateMouseState,onWheel) and throughfit(), 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
src/canvas/GraphScene.mjshas one program (SHADERS,compile).upload()buildssurfacesonce 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).initGlsets the premultiplied blendONE, ONE_MINUS_SRC_ALPHA.normalizeScenevalidates the scene's arrays and names what doesn't fit.getStatsreports the camera, counts, LOD and uploads.cameramember holds{dist, pitch, target, touched, yaw}.fit()frames an untouched camera, andzoombounds the wheel relative to the fitted distance. The staticproject()maps a point to the surface, or tonullbehind the camera.programandsurfaces; a restore re-runsinitGland thenupload.src/canvas/Sparkline.mjsdraws with a 2D context'sfillText.test/playwright/unit/canvas/GraphScene.spec.mjscovers the static math without GL.test/playwright/e2e/rendering/GraphScene.spec.mjscoversexamples/component/graphScene.The Fix
normalizeScenetakes an optionallabels:{nodes, texts, sizes?, color, outline}.nodesare node indices in priority order, with one text each.sizesare font sizes in CSS px, defaulting tolabelStyle.size. The two colours arrive with the scene, like every other colour.upload()rasterizes each text once into an atlas texture, drawn on a workerOffscreenCanvas2D context at the drawing buffer's pixel ratio, with the fill over an outline stroke. A ratio change inupdateSizere-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 atlabelStyle.max, and draws the placed labels as screen-aligned quads in the premultiplied blend.flyTo({index, distance, duration}).distance× the fitted distance, clamped tozoom, overdurationms. Each step owes one frame.flightconfig.getStats().labelsreturns{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 returnsnull.Contract Ledger
setScene({labels})normalizeSceneJSDocflyTo({index, distance, duration})remotegetStats().labelsnullwithout labelsgetStatsJSDoclabelStyle,flightconfigsAcceptance Criteria
labelsdraws each placed label at its node, in its colour over its outline, crisp at the buffer's pixel ratio. A scene withoutlabelsdraws today's frame.labelStyle.max. Its unit arms go red ondevfirst.normalizeScenerejects a label index that names no node, and atexts/nodeslength mismatch, naming the counts in the existing error style.flyToends 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.drawnlists what the last frame drew. The e2e onexamples/component/graphScenereads it before and after an orbit.Post-Merge Validation
Out of Scope
labelStyle.font).Avoided Traps
SharedCanvasand 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.programandsurfaces.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:
#19261; its Out of Scope labels exclusion is addressed above.#312, which is where this ticket's placement comes from.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"