Repository navigation
Conversation
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>
Reviewer's GuideData structuresDefine the scene primitives, visibility rules, element fields, and coordinate conventions that the store and renderer rely on.
Store scene elements in a tile index and return visible elements in z-index and sequence order.
Represent cached path and polygon elements as chunked, per-cell batch data with add, update, delete, and render operations.
Define the deterministic benchmark scenes, their block and connection data, and the shared visual primitives used to construct them.
ImplementationDraw scene primitives with Canvas2D, preserving ordering around shapes while batching compatible paths and polygons into capped runs.
Implement the canvas layer that queries visible store elements and interleaves them with batches by z-index.
Build and run the browser benchmark, including renderer selection, timing, screenshots, pixel comparisons, and profiling options.
Provide the benchmark’s browser harness and walk/interpreter adapters, including measured actions, scene setup, and query timing.
DocumentationExplain the scene benchmark’s renderers, measurement methodology, limitations, and command-line options.
TestsCheck scene-layer visibility, batching, z-order, run limits, and camera-to-world viewport conversion.
Check cached path-batch construction, viewport culling, updates, validation, chunking, and rendering behavior.
Check scene-store ordering, visibility, movement, deletion, and duplicate-id handling.
Check primitive visibility, text sizing, shape borders, path-run batching, and draw ordering.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Preview is ready. |
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>
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)renderer:"canvas"(default) or"webgl".webglBackend: an optional custom loader.cameraAwareText.graph.scene.setRenderer()switches the renderer at runtime, and$rendererreports its state: canvas, loading, webgl, lost, restoring, or webgl-fallback.GraphLayercanvas and belowReactLayer.$level(minimalistic, schematic, detailed) is the single source for blocks, anchors andReactLayer.clockgives scene time, paused while the graph is stopped or the page is hidden.compareOrdergives the draw and hit order.query(rect)anddrawInterpreted()serve the minimap and custom drawing.toImage()exports the scene as a picture."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 afterinvalidate().Block: aSceneComponentwith the level methodsschematic(view)anddetailed(view), and parts for body, border, title, halo and badge.Anchor: a child element of its block, with the partsanchorandborder. Anchors are created lazily and are neither drawn nor hit at the minimalistic level.static mode("retained"|"immediate") replacesstatic detached.LegacyCanvasBlock: a deprecated base class that keeps a v1 block's imperative drawing for one release. It draws on theGraphLayercanvas and never in WebGL.graph.scene.compareOrder.Tags and styles
graph.scene.tags, withdefineTag().selectedTag,hoveredTag,draggingTaganddropTargetTag.connectionSourceTagandconnectionTargetTagare defined now; their writer comes with connections.graph.scene.styles. A rule has a target class,tags/notTags,roottags, a scope (levels, scale ranges) and a priority.TGraphColors.colorandvisible;width;scale;raise;dim: opaque, toward the layer background;opacity: per primitive, drawn in a translucent pass.graph.scene.explain()shows an entity's tags, the rules that matched and its computed style.useEntityStyle;GraphBlockandGraphBlockAnchorgetgraph-tag-<name>classes and part colour variables. Theselectedclasses stay as aliases.Text
maxLinesand the ellipsis.cameraAwarecan be set on a text, on a style part, and graph-wide with thecameraAwareTextsetting. It chooses between two kinds of text:cameraAwareText: falsemakes every scene text world-sized. It is meant for weak devices.WebGL backend
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.selectedremoved from data:selectedis gone fromTBlock,TConnectionand their$state. Read$selected,selectedTagor the selection API.Blockrender members removed:render,renderBody,renderSchematicView,renderMinimalisticBlock,renderDetailedView,renderStrokeandrenderText;calcZIndexandraiseBlock;shouldRenderText,shouldRenderHtmlandraised.Port a look to level methods and tags with rules, or extend
LegacyCanvasBlockfor one release. In development, a class that still defines one of these members logs a warning.Component mode:
static detachedbecomesstatic 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
zIndexof 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
sizeis a number. Replacesize: { px, minWorld, maxWorld }withsize: px, cameraAware: { minWorld, maxWorld }.Performance
Bench setup:
Blockdrawn by the component walk, measured on ce527c0 (3 repeats).Known limitations
iconandpolygonprimitives, or thedashof rect and circle borders, yet; Canvas 2D does."immediate"components (LegacyCanvasBlock) still draw on theGraphLayercanvas, and groups on their own layer. Connections move into the scene in the next step.docs/system/scene.md. Development builds report an exceeded limit before falling back to Canvas 2D.Docs, stories, bench
system/scene.mdandsystem/tags-and-styles.md;components/block-component.mdandcomponents/anchors.md;scripts/bench/culling/):scene-run.mjshas block columns,--sweepand--toggle;scene-slice.mjsruns the GPU visual checks C1–C29 and the measurements M1–M8;scene-size.mjschecks the chunk split.scene-webgl.spec.ts. It skips where WebGL2 is unavailable.Test plan
pnpm run buildpnpm --dir packages/graph exec jest: 1667 passed, 6 todopnpm --dir packages/graph-react exec jest: 169 passedpnpm run typecheckpnpm run lint: 0 errorspnpm run test:package-contractnode scripts/bench/culling/scene-slice.mjs(Chromium on the GPU): 46 PASS, 0 FAILpnpm --filter @gravity-ui/graph-e2e exec playwright test: 289 passednode 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🤖 Generated with Claude Code