Skip to content

feat(graph)!: blocks and anchors draw through graph.scene (Canvas 2D or WebGL) - #454

Draft
draedful wants to merge 5 commits into
claude/webgl-connections-detachedfrom
claude/webgl-unified-scene
Draft

draedful wants to merge 5 commits into
claude/webgl-connections-detachedfrom
claude/webgl-unified-scene

Conversation

@draedful

@draedful draedful commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Every graph now has a scene runtime, graph.scene, and blocks and their anchors draw through it, with Canvas 2D (the default) or WebGL (renderer: "webgl"). A block describes its look as primitives per level of detail. Visual states (selected, hovered, dragging, your own) are tags, and their looks are style rules instead of code in component classes. The picture and the behaviour stay as in v1, both text modes included. The developer API changes; the breaking changes are listed below.

Stacked on #451.

What changes

Scene runtime (graph.scene)

  • Settings:
    • renderer: "canvas" (default) or "webgl".
    • webglBackend: an optional custom loader.
    • cameraAwareText.
    • graph.scene.setRenderer() switches the renderer at runtime, and $renderer reports its state: canvas, loading, webgl, lost, restoring, or webgl-fallback.
  • Frame order: the scene draws in the graph's frame task, right after all layers. The scene canvas sits above the GraphLayer canvas and below ReactLayer.
  • Level of detail: $level (minimalistic, schematic, detailed) is the single source for blocks, anchors and ReactLayer.
  • Clock: clock gives scene time, paused while the graph is stopped or the page is hidden.
  • Queries and export: compareOrder gives the draw and hit order. query(rect) and drawInterpreted() serve the minimap and custom drawing. toImage() exports the scene as a picture.
  • Lazy loading: the WebGL backend is a lazily imported chunk (about 110 KB gzip, luma.gl 9.4). "canvas" never loads it.

Blocks and anchors in the scene

  • SceneComponent: a component that owns one scene element. Its level methods run lazily, at most once per frame, when its view data changes or after invalidate().
  • Block: a SceneComponent with the level methods schematic(view) and detailed(view), and parts for body, border, title, halo and badge.
  • Anchor: a child element of its block, with the parts anchor and border. Anchors are created lazily and are neither drawn nor hit at the minimalistic level.
  • Component mode: static mode ("retained" | "immediate") replaces static detached.
  • LegacyCanvasBlock: a deprecated base class that keeps a v1 block's imperative drawing for one release. It draws on the GraphLayer canvas and never in WebGL.
  • Order and hit-testing: blocks are in z-bucket 200, and 201 while selected or dragged. Both draw order and hit-testing follow graph.scene.compareOrder.

Tags and styles

  • Tags: graph.scene.tags, with defineTag().
    • Built-in tags: selectedTag, hoveredTag, draggingTag and dropTargetTag.
    • connectionSourceTag and connectionTargetTag are defined now; their writer comes with connections.
  • Rules: graph.scene.styles. A rule has a target class, tags/notTags, root tags, a scope (levels, scale ranges) and a priority.
    • Cascade: theme, then data, then tags.
    • The theme rules come from TGraphColors.
  • Style properties:
    • color and visible;
    • width;
    • circle scale;
    • raise;
    • dim: opaque, toward the layer background;
    • opacity: per primitive, drawn in a translucent pass.
  • Introspection: graph.scene.explain() shows an entity's tags, the rules that matched and its computed style.
  • React:
    • useEntityStyle;
    • GraphBlock and GraphBlockAnchor get graph-tag-<name> classes and part colour variables. The selected classes stay as aliases.

Text

  • One layout: both renderers share one measured layout with v1's wrapping. That covers words, long-word splitting, the cut at the box height, maxLines and the ellipsis.
  • Two modes: cameraAware can be set on a text, on a style part, and graph-wide with the cameraAwareText setting. It chooses between two kinds of text:
    • text of a fixed screen size, re-fitted into its block at each zoom step;
    • text that scales like any world object.
  • Kill switch: cameraAwareText: false makes every scene text world-sized. It is meant for weak devices.
  • Clipping: a text is clipped only when its layout overflows its box, so a text that fits is never cut off.

WebGL backend

  • Context: it owns its WebGL2 context.
  • Passes:
    • an opaque pass with a depth key and alpha-to-coverage;
    • an alpha-only pass;
    • a translucent pass in scene order. 10,000 faded blocks take 3 draw calls.
  • Text: an SDF glyph atlas (tiny-sdf).
  • Updates: colour, visibility and dim live in a style table, so most state changes re-encode no geometry.
  • Camera-aware text: it keeps a constant glyph capacity and changes its lines in place. A frame uploads only the changed spans of an instance list, at most twice the changed bytes, and a dense change goes up as one enclosing write.
  • Fallback: a context lost during loading or drawing, a runtime failure or an exceeded limit falls back to Canvas 2D (webgl-fallback). The backend recovers when the context is restored.

Breaking changes

The full list, with before/after tables, is in docs/migration-guides/v1-to-v2.md.

  • selected removed from data: selected is gone from TBlock, TConnection and their $state. Read $selected, selectedTag or the selection API.

  • Block render members removed:

    • render, renderBody, renderSchematicView, renderMinimalisticBlock, renderDetailedView, renderStroke and renderText;
    • calcZIndex and raiseBlock;
    • shouldRenderText, shouldRenderHtml and raised.

    Port a look to level methods and tags with rules, or extend LegacyCanvasBlock for one release. In development, a class that still defines one of these members logs a warning.

  • Component mode: static detached becomes static override readonly mode, "retained" or "immediate".

  • Anchor ids: anchor selection and anchor tags use block-qualified ids, anchorEntityId(blockId, anchorId).

  • Hit order: a layer component must have a zIndex of at least 201 to be hit above blocks.

  • Screenshots: take them with graph.scene.toImage(). getGraphCanvas() no longer holds scene blocks.

  • Scene text sizes: a scene text's size is a number. Replace size: { px, minWorld, maxWorld } with size: px, cameraAware: { minWorld, maxWorld }.

Performance

Bench setup:

  • Scene: the guarantee scene, with 10,000 blocks, about 40,000 anchors, 9,900 connections and 1,000 groups.
  • View: 1600×1000 at scale 0.038, so the whole graph is in view.
  • Machine: Apple M3 Pro, Chromium 145 on the GPU (ANGLE Metal).
  • Method: the main-thread scheduler tick and bulk operations, as medians of 5 repeats.
  • Before: the v1 Block drawn by the component walk, measured on ce527c0 (3 repeats).
  • Look: both scene columns draw the same Nirvana-like block look. The Canvas 2D picture differs from the component walk in 4,952 of 6.4M pixels.
before (component walk) scene, Canvas 2D scene, WebGL
pan tick, ms 37.45 14.27 3.21
zoom tick, ms 35.31 14.24 3.07
drag tick, ms 72.90 15.86 5.30
pan frame interval p50, ms 42.2 18.5 16.7 (vsync)
mount, ms (scene share) 753.8 521.3 (47.3) 716.4 (288.9)
JS heap, MB 279.1 194.4 269.3
select all, ms 98.8 58.8 86.5
start dragging 1,000 blocks, ms 40.8 19.9 9.2
change every block, ms 267.0 139.0 179.9
  • Zoom sweep with camera-aware titles: 0.25 ↔ 1 in 30 steps each way.
    • The p95 tick is about 3 ms on both renderers (WebGL 2.6–2.9, Canvas 2D 3.3–3.5 across runs).
    • WebGL uploads about 95 KB per step on average (566 KB at most), at most twice the glyph bytes of the texts laid out again (1.99).
  • Bundle: the main chunk has no luma.gl.

Known limitations

  • WebGL primitives: WebGL does not draw icon and polygon primitives, or the dash of rect and circle borders, yet; Canvas 2D does.
  • WebGL text: WebGL draws glyphs from its atlas without shaping, so it has no ligatures or contextual forms. Line breaks still come from the shared layout.
  • Not in the scene yet: connections and "immediate" components (LegacyCanvasBlock) still draw on the GraphLayer canvas, and groups on their own layer. Connections move into the scene in the next step.
  • WebGL mount cost: the scene's share of mount on WebGL is about 290 ms. The total mount (716 ms) is within the component walk's 754 ms.
  • Upload policy: the rule for uploading changed spans was tuned on one GPU (ANGLE Metal on Apple M3 Pro).
  • Scene limits: at most 15 part names and 16 z-bands. Owners per band and depth are bounded too, as described in docs/system/scene.md. Development builds report an exceeded limit before falling back to Canvas 2D.

Docs, stories, bench

  • Docs:
    • new: system/scene.md and system/tags-and-styles.md;
    • rewritten: components/block-component.md and components/anchors.md;
    • updated: the migration guide, plus settings, lifecycle, scheduler and camera notes.
  • Storybook: Canvas/SceneRuntime, Canvas/SceneTags and Canvas/SceneBlocks. The in-repo blocks and stories are ported.
  • Bench (scripts/bench/culling/):
    • scene-run.mjs has block columns, --sweep and --toggle;
    • scene-slice.mjs runs the GPU visual checks C1–C29 and the measurements M1–M8;
    • scene-size.mjs checks the chunk split.
  • e2e: a WebGL smoke test, scene-webgl.spec.ts. It skips where WebGL2 is unavailable.

Test plan

  • pnpm run build
  • pnpm --dir packages/graph exec jest: 1667 passed, 6 todo
  • pnpm --dir packages/graph-react exec jest: 169 passed
  • pnpm run typecheck
  • pnpm run lint: 0 errors
  • pnpm run test:package-contract
  • node scripts/bench/culling/scene-slice.mjs (Chromium on the GPU): 46 PASS, 0 FAIL
  • pnpm --filter @gravity-ui/graph-e2e exec playwright test: 289 passed
  • node scripts/bench/culling/scene-run.mjs --gpu --scenes guarantee --scales 0.038 --modes pan,zoom,drag --renderers walk,cached,webgl,blocks,blocks-webgl,blocks-default --repeats 5
  • Storybook, both renderers: Playground, Canvas/SceneBlocks with camera-aware titles, and ETL. Text, wrapping and the ellipsis match between Canvas 2D and WebGL.

🤖 Generated with Claude Code

Adds an internal research prototype of a declarative scene (nothing is
exported from the package):

- packages/graph/src/lib/scene: primitive and element types, drawElements
  (Canvas2D drawing with run-batching of same-style paths, capped by
  maxRun), SceneStore (elements on a TileIndex in zIndex/sequence order),
  ScenePathBatch (paths and polygons of one z-level cached per cell on the
  core BatchScene, as BatchPath2DRenderer caches connections) and
  SceneCanvasLayer (draws a store and its batches in z-order).

Adds a scene bench next to the culling bench:

- scripts/bench/culling/scene-run.mjs and scene/: deterministic median,
  guarantee and stress scenes with a Nirvana-like look, drawn by three
  columns: walk (today's component tree), interpreter (SceneCanvasLayer
  over a SceneStore) and cached (connections in a ScenePathBatch). It times
  pan, zoom and drag on the scheduler tick plus the synchronous action,
  diffs the pictures against walk, and can record CPU profiles. Flags:
  --renderers, --run-cap, --gpu, --query-timing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 9, 2026

Copy link
Copy Markdown

Reviewer's Guide

Data structures

Define the scene primitives, visibility rules, element fields, and coordinate conventions that the store and renderer rely on.

  • packages/graph/src/lib/scene/types.ts L1-69

Store scene elements in a tile index and return visible elements in z-index and sequence order.

  • packages/graph/src/lib/scene/SceneStore.ts L1-84

Represent cached path and polygon elements as chunked, per-cell batch data with add, update, delete, and render operations.

  • packages/graph/src/lib/scene/ScenePathBatch.ts L1-178

Define the deterministic benchmark scenes, their block and connection data, and the shared visual primitives used to construct them.

  • scripts/bench/culling/scene/look.ts L1-222
  • scripts/bench/culling/scene/scenes.ts L1-170

Implementation

Draw scene primitives with Canvas2D, preserving ordering around shapes while batching compatible paths and polygons into capped runs.

  • packages/graph/src/lib/scene/drawPrimitives.ts L1-230

Implement the canvas layer that queries visible store elements and interleaves them with batches by z-index.

  • packages/graph/src/lib/scene/SceneCanvasLayer.ts L1-71

Build and run the browser benchmark, including renderer selection, timing, screenshots, pixel comparisons, and profiling options.

  • scripts/bench/culling/scene-run.mjs L1-312

Provide the benchmark’s browser harness and walk/interpreter adapters, including measured actions, scene setup, and query timing.

  • scripts/bench/culling/scene/entry.ts L1-210
  • scripts/bench/culling/scene/interpreter.ts L1-195
  • scripts/bench/culling/scene/sizes.check.ts L1-13
  • scripts/bench/culling/scene/walk.ts L1-155

Documentation

Explain the scene benchmark’s renderers, measurement methodology, limitations, and command-line options.

  • scripts/bench/culling/README.md L73-160

Tests

Check scene-layer visibility, batching, z-order, run limits, and camera-to-world viewport conversion.

  • packages/graph/src/lib/scene/SceneCanvasLayer.test.ts L1-249

Check cached path-batch construction, viewport culling, updates, validation, chunking, and rendering behavior.

  • packages/graph/src/lib/scene/ScenePathBatch.test.ts L1-215

Check scene-store ordering, visibility, movement, deletion, and duplicate-id handling.

  • packages/graph/src/lib/scene/SceneStore.test.ts L1-49

Check primitive visibility, text sizing, shape borders, path-run batching, and draw ordering.

  • packages/graph/src/lib/scene/drawPrimitives.test.ts L1-143

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@gravity-ui-bot

Copy link
Copy Markdown
Contributor

Preview is ready.

draedful and others added 4 commits November 10, 2026 14:36
An internal WebGL backend for the scene prototype, to test the v2 scene design end to end. Nothing is exported from
the package.

- Scene model: camera-aware sizes (TSceneSize, resolveSceneSize), `order` instead of `sequence`, parts and styles
  with overrides in the Canvas2D interpreter, and store change events.
- CPU modules in lib/scene/webgl: a dense depth key (zIndex band, rank, sub-order), element and style tables for the
  GPU, per-element instance ranges with in-place uploads, and encoders for rects, text (tiny-sdf atlas) and paths.
- WebGLSceneBackend on luma.gl 9.4: its own WebGL2 context, an opaque pass with depth and alpha-to-coverage, an
  alpha-only pass, a translucent pass, premultiplied alpha, and effects through a luma ShaderPlugin injection.
- SceneRendererLayer: the renderer setting, a lazy import of the backend, and the state machine canvas -> loading ->
  webgl -> lost -> restoring -> webgl | webgl-fallback. Animation runs through the global scheduler, and runtime
  failures fall back to Canvas2D.
- Bench:
  - scene-slice.mjs runs the visual checks C1-C12 in Chromium on the GPU;
  - the scene bench has a webgl column;
  - scene-size.mjs measures the lazily loaded backend chunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every graph now owns a scene runtime, `graph.scene` (GraphScene), which the scene components will draw through. The
scene only draws for now: elements in its store have no hit boxes or events and do not count towards usableRect.

- Settings `renderer` ("canvas" by default, or "webgl") and `webglBackend`. `graph.scene.$renderer` reports the
  renderer state, and `setRenderer()` switches it at runtime.
- One frame order: Graph's frame task runs `layers.update()` and then `scene.update()`, so the scene draws after
  every layer of its graph in the same tick. Layers can opt out of the layers pass (`createLayer(..., { selfUpdated })`).
- SceneClock: scene time in seconds, paused while the graph is stopped or the page is hidden.
- `$level` (createSceneLevel) is the single LOD source. Blocks, anchors and ReactLayer read it; ReactLayer switches
  its HTML on through `Layer.setHtmlActive()` at the detailed level.
- `query(rect)` and `drawInterpreted()` on the scene; store, layer and lifecycle methods are internal.
- SceneRendererLayer hardening: a context lost while the backend loads keeps that backend aside until it is
  restored, late web fonts reload the backend, and the scene canvas ignores pointer events and selection.
- graph-react: BlocksList bails out of empty updates, and the hook and layer tests count the scene canvas.
- Docs: system/scene.md, plus notes in graph settings, scheduler and camera docs.
- Bench: the slice checks and the webgl column run on `graph.scene`.
- Storybook: Canvas/SceneRuntime demo with both renderers, ordering, a style switch, 3000 elements and a simulated
  WebGL context loss.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Visual states become tags plus style rules instead of code in component classes. Tags and styles live on the scene:
`graph.scene.tags` and `graph.scene.styles`.

- Tags: `defineTag<V>()`, a tag store keyed by (entityType, id) with set/add/delete/clear, `bind` to a signal (one
  writer per tag), root tags and per-entity `$of` signals. Built-in tags: `selectedTag` (bound to the selection
  buckets), `hoveredTag` (GraphLayer hover), `draggingTag` (DragService), `dropTargetTag` (group transfer layer), and
  `connectionSourceTag`/`connectionTargetTag` (defined; their writer comes with connections).
- Rules: `target`, `tags`, `notTags`, `root`, `scope` (levels and scale ranges), `priority` and `style` (a value or a
  function of tag values), typed by the target's parts (`declare readonly __styleParts?: TStyleParts<...>`;
  subclasses may add parts). Cascade: theme < data < tags; rules without tags/notTags/root fill unset values; rules
  sort by priority and theme rules win ties. Theme rules come from `TGraphColors`.
- Computed styles are interned per (target, tags) into scene style rows with reference counts; a rule, root tag, level
  or theme change rewrites rows. `graph.scene.bindStyle()` keeps an element on its entity's style, `styleFor()` and
  `$styleGeneration` serve React, and `explain()` shows tags, matched rules and the computed style.
- Style properties: `color` and `visible` (style table, no re-encode), `width` and circle `scale` (re-encode one
  element), `raise` (adds to the zIndex bucket), opaque `dim` towards the theme's layer background (style table) and
  per-primitive `opacity` (re-encode, translucent pass; what lies below shows through). Paint colours and stroke width
  are optional in primitives, so the theme can fill them.
- Renderers: the Canvas2D interpreter and the WebGL backend draw the same rows. WebGL keeps overrides, base colours
  and dims in the style table, bakes element properties at encode, and redraws on table-only changes. Translucent
  primitives draw in scene order, batched by overlap levels, so 10k faded blocks take 3 draws.
- Breaking: `selected` is removed from `TBlock`, `TConnection` and their `$state`; read `$selected`, `selectedTag` or
  the selection API.
- React: `useEntityStyle`; `GraphBlock` and `GraphBlockAnchor` get `graph-tag-<name>` classes and part colour
  variables (the `selected` classes stay as aliases).
- Docs: system/tags-and-styles.md, migration notes. Storybook: Canvas/SceneTags. Bench: slice checks C13-C16 and
  `--block-opacity`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Blocks and their anchors now draw through `graph.scene`, on the Canvas 2D and the WebGL renderer.

- Components. `static mode` ("retained" | "immediate") replaces `static detached`. A `SceneComponent` owns one
  scene element; its level methods run lazily, at most once per frame, when its view data changes or after
  `invalidate()`. `Block` is a `SceneComponent` with three level methods and five parts, and each `Anchor` owns a
  child element styled by the theme's anchor rules. The old imperative drawing lives on, deprecated, in
  `LegacyCanvasBlock`.
- Scene. Primitives carry level masks, so a level change re-encodes nothing on WebGL. Child elements share their
  parent's depth key, hidden state, raise, dim and opacity. Store changes reach the backend once per frame.
  Hit-testing follows `graph.scene.compareOrder`, and `graph.scene.toImage()` exports the scene.
- Text. Both renderers share one measured layout with v1's wrapping: words, long-word splitting, the height cut,
  `maxLines` and the ellipsis. `cameraAware` on a text, on a style part, and the `cameraAwareText` setting choose
  between text of a fixed screen size, re-fitted into its block at each zoom step, and text that scales like any
  world object. A text is clipped only when its layout overflows its box.
- WebGL text. A camera-aware text keeps a constant glyph capacity and changes its lines in place; a frame uploads
  the changed spans, at most twice the changed bytes.
- Ports of the in-repo blocks and stories, docs, e2e, and the scene bench: block columns, a zoom sweep and GPU
  checks C1-C29.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@draedful draedful changed the title feat(graph): scene interpreter prototype and scene bench feat(graph)!: blocks and anchors draw through graph.scene (Canvas 2D or WebGL) Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants