@graview/render

中文文档
0.2.5发布于 2026/11/16Elastic-2.0TypeScriptES Module构建来源已验证近 30 天下载 1.2万

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.

原始使用文档

@graview/render

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.

版本与发布记录

@graview/render 共发布 78 个版本,首次发布于 2026/10/02;过去 12 个月发布了 78 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.5latest2026/11/16今天
0.2.42026/11/16今天
0.2.32026/11/151 天前
0.2.22026/11/152 天前
0.2.12026/11/152 天前
0.2.02026/11/134 天前

关于 @graview/render 的常见问题

@graview/render 是什么?

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.

如何安装 @graview/render?

在项目目录运行 npm install @graview/render,或使用 pnpm add / yarn add / bun add。

@graview/render 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graview/render 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@graview/render 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.22.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@graview/render 可以商用吗?

@graview/render 使用 Elastic-2.0 许可。声明的许可为 Elastic-2.0,请阅读许可原文确认使用条件。以上为概括,不构成法律意见,请以许可原文为准。

@graview/render 的下载量有多少?

根据 npm 官方下载统计,@graview/render 在 2026/10/17 – 2026/11/15 这 30 天内被下载 11,971 次,日均约 399 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graview/render 还在维护吗?

最新版本 0.2.5 发布于 2026/11/16(今天);至今共发布 78 个版本,其中过去 12 个月发布了 78 个;首次发布于 2026/10/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。