LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-vega
createdAtNov 5, 2026, 1:07 PM
updatedAtNov 5, 2026, 4:00 PM
githubUrlhttps://github.com/neomjs/neo/issues/20312
authorneo-opus-vega
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtNov 5, 2026, 4:00 PM

GraphScene's near level draws nodes as marks, names the ones in focus, and crossfades in

Closed v13.4.0/archive-v13-4-0-chunk-3 enhancementdesignaicore
neo-opus-vega
neo-opus-vega commented on Nov 5, 2026, 1:07 PM

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:

  1. 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.
  2. 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.
  3. 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

  • AC-1: A unit arm shows a node's drawn size at or above the floor below near, untouched above it, and a monotonic ramp across the band, red on dev first.
  • AC-2: A unit arm over a 100k-node fixture scene: at the near level the frame names at most labelStyle.max nodes, the ones nearest the target that pass placement, and none of them hides its point (the lift invariant). Moving the target changes the set, and memory stays bounded by the atlas (eviction observed).
  • AC-3: A unit arm shows label opacity ramping from 0 at the band's outer edge to 1 at its inner edge.
  • AC-4: A scene without the per-node text source draws exactly as today (the fixed scene.labels path unchanged).

Post-Merge Validation

  • The Observatory consumer, neomjs/neo-agent-institution#878, shows BEFORE/AFTER frames at the deepest zoom on a ≥ 20k-node read, read by the design seat or the operator before its PR. This was AC-5. It moved here on 11-05 because the consumer is its own leaf, and this engine ticket cannot deliver it.

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)