Context
The operator on the Observatory, 2026-11-05: "the max zoom out level for observatory feels fine. zooming in is not enough though. you could explore apps/covid inside the engine repo => MapBox GL. … after zooming in up to a specific level, items get rendered differently. the same could in theory happen for our agent os graph. i am open minded: after all, we are dealing with around 100k nodes."
The design read already exists. Clio's zoom ladder (neomjs/neo-agent-institution#312, comment 6222093228, 2026-10-16) has three levels: L0 sky, L1 field, and L2 street, crossfaded between. She ordered it (a) zoom range plus near band, (b) the label layer plus fly-to, (c) the morph.
- (b) shipped: #20286, PR #20288.
- (a)'s range and band ship with neomjs/neo-agent-institution#839 (
zoom.min 0.1, near 0.35, as Observatory config).
- What remains is the part the operator describes, nodes rendered differently past a zoom threshold. That part is engine mechanics.
The Problem
Below near, GraphScene draws the same thing as above it, only bigger:
- No mark floor.
gl_PointSize = aSize * uScale / max(vDepth, 0.1) (src/canvas/GraphScene.mjs:25) divides by vDepth, the depth relative to the camera distance, which is 1 at the orbit target. So a node there draws at its uploaded size at every zoom. A dense Observatory read's node is 0.4 units. uScale is the drawing buffer's shorter side over 400, so on an 800 CSS px surface that is 0.8 CSS px at any pixel ratio. No zoom makes it a readable mark; zooming in only spreads the nodes apart. Clio's target is ≥ 6 px at L2. (Corrected 11-05: this line first claimed the node grows to 4 px at the deepest zoom.)
- No names for what's in focus. The label layer (#20286) packs a FIXED label set into one atlas at upload (
uploadLabels / packLabels). The Observatory labels its wells. Naming the nodes nearest the orbit target means a per-frame label set over the whole scene, which a once-packed atlas cannot hold for 100k nodes (2048² limit).
- No transition. Levels switch at a threshold (
getLodLevel, :574-588), so a level change pops.
The Architectural Reality
- The precedent is
apps/covid/view/mapboxGl/Component.mjs:30-82. A heatmap carries density up to zoom 5 and fades out 5→6 (heatmap-opacity interpolated on zoom). Per-item circles fade in 5→6, and their count labels 5→7. Aggregate becomes individual, with opacity ramps across the threshold rather than a switch. MapBox is not used here; the pattern is.
- GraphScene already has the levels and the distance:
lod thresholds as config (:101-106), getLodLevel() from camera.dist / fittedDistance, a label layer with labelStyle.max (30, Clio's "≤ 30 labels on screen") and collision placement (placeLabels), and per-node positions/sizes on the scene.
- The scene owns the names.
scene.labels today carries {nodes, texts, sizes} for a fixed set. A fovea set needs a text for any node the camera can approach, given once with the scene and rasterized on demand.
The Fix
At the near level and below, as engine config the app sets:
- A mark floor. A uniform minimum point size applies past the
near threshold, ramped across it rather than switched (lodStyle.near.minPointSize, or the shape the implementer finds cleaner). The app sets the value; the Observatory starts at Clio's 6–8 px.
- Fovea labels. Each frame names up to
labelStyle.max of the nodes nearest the orbit target that pass placeLabels' gap and on-surface checks, from a per-node text source on the scene. Glyphs rasterize on demand into the atlas, which evicts the least recently drawn. packLabels' two invariants stay: a label never claims more than the atlas holds, and never hides the point it names. A scene without the text source behaves as today.
- A crossfade. Mark size and label opacity interpolate across the
near threshold over a configurable band (the covid ramps' shape), so crossing the level reads as a morph, not a pop.
Acceptance Criteria
Post-Merge Validation
Out of Scope
- Zoom toward the pointer, the keyboard zoom, double-click fly-to, and the canvas hover halo: Clio's other L2 motions. Each is its own leaf when wanted.
- Any 3D beyond the orbit. Clio's read keeps the orbit and goes no further.
- MapBox or any map library.
Related
neomjs/neo-agent-institution#312 (the design read) · neomjs/neo-agent-institution#839 (step (a), the first consumer) · #20286 (the label layer it extends) · apps/covid/view/mapboxGl/Component.mjs (the precedent)
Live latest-open + closed sweep: the latest 20 open neo issues plus searches ("semantic zoom", "GraphScene level of detail", "GraphScene labels zoom", "fovea", "zoom-to-pointer", "size floor", "zoom ladder") across neo and Institution at 2026-11-05T12:0xZ. Hits: #20286 (closed, the label layer this extends), and Institution #312 / #839 (the design read and its first step). No equivalent. A2A (today's claims): none on GraphScene. MC: Clio's 10-16 zoom-ladder session is the design source, not a duplicate. Own-assignment sweep: no same-surface ticket.
Origin Session ID: 57180f73-f0b4-4ae5-bac8-095fd4813333
Retrieval Hint: "GraphScene near level mark floor fovea labels crossfade zoom ladder street level"
Authored by Vega (Opus 5.5, Claude Code)
Context
The operator on the Observatory, 2026-11-05: "the max zoom out level for observatory feels fine. zooming in is not enough though. you could explore apps/covid inside the engine repo => MapBox GL. … after zooming in up to a specific level, items get rendered differently. the same could in theory happen for our agent os graph. i am open minded: after all, we are dealing with around 100k nodes."
The design read already exists. Clio's zoom ladder (neomjs/neo-agent-institution#312, comment 6222093228, 2026-10-16) has three levels: L0 sky, L1 field, and L2 street, crossfaded between. She ordered it (a) zoom range plus
nearband, (b) the label layer plus fly-to, (c) the morph.zoom.min0.1,near0.35, as Observatory config).The Problem
Below
near, GraphScene draws the same thing as above it, only bigger:gl_PointSize = aSize * uScale / max(vDepth, 0.1)(src/canvas/GraphScene.mjs:25) divides byvDepth, the depth relative to the camera distance, which is 1 at the orbit target. So a node there draws at its uploaded size at every zoom. A dense Observatory read's node is 0.4 units.uScaleis the drawing buffer's shorter side over 400, so on an 800 CSS px surface that is 0.8 CSS px at any pixel ratio. No zoom makes it a readable mark; zooming in only spreads the nodes apart. Clio's target is ≥ 6 px at L2. (Corrected 11-05: this line first claimed the node grows to 4 px at the deepest zoom.)uploadLabels/packLabels). The Observatory labels its wells. Naming the nodes nearest the orbit target means a per-frame label set over the whole scene, which a once-packed atlas cannot hold for 100k nodes (2048² limit).getLodLevel,:574-588), so a level change pops.The Architectural Reality
apps/covid/view/mapboxGl/Component.mjs:30-82. A heatmap carries density up to zoom 5 and fades out 5→6 (heatmap-opacityinterpolated onzoom). Per-item circles fade in 5→6, and their count labels 5→7. Aggregate becomes individual, with opacity ramps across the threshold rather than a switch. MapBox is not used here; the pattern is.lodthresholds as config (:101-106),getLodLevel()fromcamera.dist / fittedDistance, a label layer withlabelStyle.max(30, Clio's "≤ 30 labels on screen") and collision placement (placeLabels), and per-nodepositions/sizeson the scene.scene.labelstoday carries{nodes, texts, sizes}for a fixed set. A fovea set needs a text for any node the camera can approach, given once with the scene and rasterized on demand.The Fix
At the
nearlevel and below, as engine config the app sets:nearthreshold, ramped across it rather than switched (lodStyle.near.minPointSize, or the shape the implementer finds cleaner). The app sets the value; the Observatory starts at Clio's 6–8 px.labelStyle.maxof the nodes nearest the orbit target that passplaceLabels' gap and on-surface checks, from a per-node text source on the scene. Glyphs rasterize on demand into the atlas, which evicts the least recently drawn.packLabels' two invariants stay: a label never claims more than the atlas holds, and never hides the point it names. A scene without the text source behaves as today.nearthreshold over a configurable band (the covid ramps' shape), so crossing the level reads as a morph, not a pop.Acceptance Criteria
near, untouched above it, and a monotonic ramp across the band, red ondevfirst.labelStyle.maxnodes, the ones nearest the target that pass placement, and none of them hides its point (theliftinvariant). Moving the target changes the set, and memory stays bounded by the atlas (eviction observed).scene.labelspath unchanged).Post-Merge Validation
Out of Scope
Related
neomjs/neo-agent-institution#312 (the design read) · neomjs/neo-agent-institution#839 (step (a), the first consumer) · #20286 (the label layer it extends) ·
apps/covid/view/mapboxGl/Component.mjs(the precedent)Live latest-open + closed sweep: the latest 20 open neo issues plus searches ("semantic zoom", "GraphScene level of detail", "GraphScene labels zoom", "fovea", "zoom-to-pointer", "size floor", "zoom ladder") across neo and Institution at 2026-11-05T12:0xZ. Hits: #20286 (closed, the label layer this extends), and Institution #312 / #839 (the design read and its first step). No equivalent. A2A (today's claims): none on GraphScene. MC: Clio's 10-16 zoom-ladder session is the design source, not a duplicate. Own-assignment sweep: no same-surface ticket.
Origin Session ID: 57180f73-f0b4-4ae5-bac8-095fd4813333
Retrieval Hint: "GraphScene near level mark floor fovea labels crossfade zoom ladder street level"
Authored by Vega (Opus 5.5, Claude Code)