@graview/render

@graview/render is one of the 14 npm packages of Graview, a TypeScript framework that derives an app’s interface, permissions and agent tools from one declaration. The spatial renderer: the GPU capture path where the browser can capture into WebGPU, the DOM path everywhere else, one picture and one accessibility tree on both.

pnpm add @graview/render

Entry points: @graview/render, @graview/render/gpu

What it is

The spatial renderer: three planes, an affine transform per plane, and connectors drawn in SVG over the scene.

Two paths, and which one draws

A scene draws on the GPU where the browser can, and on the DOM path everywhere else — silently, per page. Scene and the Shell default to renderer="auto": gpuCapturePresent() asks, without a device, whether the page has WebGPU, an element-capture call on its queue, a canvas paint event, and hit-testing that follows the drawn geometry (below); where it does, ./gpu is fetched and attachGpu() takes the canvas. Its first-frame check falls back for good if no adapter is given, no paint arrives within FIRST_PAINT_WAIT_MS, a frame is refused, the device is lost, or the middle of the first FIRST_FRAMES frames' work is over FIRST_FRAME_BUDGET_MS. A page without any of it — Firefox, Safari, Chromium before element capture — never fetches ./gpu and says nothing. ?renderer=gpu|dom on the address (or graviewRenderer set on the page before it loads) decides auto for an operator; GRAVIEW_RENDERER does the same for every page of a harness run.

Element capture (CanvasDrawElement) is on by default in Chromium 158 and behind --enable-blink-features=CanvasDrawElement before it. Canary 158 respelled the API (content="drawable" on the canvas, drawable on each view, a plain { texture } destination); both spellings are written.

The two paths draw one picture. Each view is an ordinary element on both: on the DOM path it carries a CSS matrix3d, opacity and filter; on the GPU path it is a child of the canvas, captured, and the shader draws the same treatment from the same numbers (treatmentOf, recededOpacity). The accessibility tree is the same on both, and scripts/verify-renderer.mjs holds that, the picture, and the silence.

Blur. Receded planes are blurred, the focused plane always sharp. On the GPU the shader draws it at no measurable cost; the DOM path's CSS filter: blur() is dropped for the rest of the page if its frames run over a frame and a half while the picture moves. blur={false} on the Scene or the Shell turns it off, and so do prefers-reduced-motion, prefers-reduced-transparency and the reader's Motion setting (planeBlurOn).

Capture costs about 0.22 ms a view on Chromium 158, so retaking every live view every frame holds sixty frames a second only below about 64 views (6 fps at 512). attachGpu() keeps a page under that: it retakes a view only when the browser's paint event says it changed, skips what is off the canvas, spends at most CAPTURE_BUDGET retakes a frame, and hands a view that keeps changing faster than that to the DOM path, drawn at the same transform under the canvas. The discography holds about 500 fps with 512 live views that way (scripts/verify-scale.mjs).

Hit-testing. On Chromium 158 a view reported with updateElementGeometry is hit-tested where it was drawn — elementsFromPoint, hover and presses land on the drawn view — so the browser answers and the canvas says data-graview-hit="platform", which lets the views' content take the pointer. Earlier builds (the layoutSubtree spelling, Chrome 155 with capture switched on among them) accept the geometry and ignore it: a view's box stays where it was laid out, so a press, a screen reader and an automation all land somewhere other than where the view was drawn. gpuCapturePresent() is false there and the page draws on the DOM path. PointerRouter (data-graview-hit="router") remains for a host driving the Compositor itself on such a build. A pan moves the canvas by a transform, as it moves the DOM path's stage, and redraws nothing until it lands.

What is stable here

  • PLANE_STYLES, styleFor, mixStyles, transformFor — the plane model.
  • planFrame — what to capture, what to draw, where each view lands.
  • PointerRouter, hitTest — hit-testing a click against drawn geometry.

The compositor, the WGSL and the html-in-canvas platform bindings move with the browser feature they are built on.

What it exports (36)

Read off the package's own barrel, so this is what is there today.

  • CAPTURE_BUDGET
  • chooseRenderer
  • CONNECTOR_DASH
  • connectorStroke
  • connectorStyle
  • connectorWidth
  • distinguishable
  • FRAME_BUDGET_MS
  • framesHeld
  • fromLayout
  • gpuCapturePresent
  • hitTest
  • hueFor
  • IDENTITY
  • invertPlaneTransform
  • isAffine
  • LIGHT_PLANE_STYLES
  • mixStyles
  • OUTSET_ATTRIBUTE
  • outsetText
  • perspectiveProbeMatrix
  • PLANE_STYLES
  • planeBlurOn
  • PLANES
  • planeTransform
  • planFrame
  • PointerRouter
  • PROVISIONAL_DASH
  • PROVISIONAL_OPACITY
  • recededOpacity
  • rendererAsked
  • styleFor
  • toDOMMatrix
  • toLocal
  • transformFor
  • treatmentOf