@plasius/gpu-renderer

Framework-agnostic WebGPU renderer runtime for Plasius projects. This package is intended to replace Three.js-dependent render orchestration with an explicit WebGPU-first runtime that can be consumed from React, vanilla, or worker-driven app surfaces.

Apache-2.0. ESM + CJS builds.

Install

npm install @plasius/gpu-renderer

Usage

import { createGpuRenderer } from "@plasius/gpu-renderer";

const renderer = await createGpuRenderer({
  canvas: document.querySelector("#scene"),
  clearColor: "#102035",
});

renderer.resize(window.innerWidth, window.innerHeight);
renderer.start();

Adaptive Frame Hooks

@plasius/gpu-renderer now exposes frame lifecycle hooks so the app can pass negotiated frame targets from @plasius/gpu-performance and opt into renderer frame sampling for @plasius/gpu-debug.

import { createGpuRenderer, createRendererDebugHooks } from "@plasius/gpu-renderer";

const rendererDebugHooks = createRendererDebugHooks({
  debugSession,
  getTargetFrameTimeMs: () => governor.getSnapshot().targetFrameTimeMs,
});

const renderer = await createGpuRenderer({
  canvas: "#scene",
  frameIdFactory: ({ frame, xrActive }) => `scene.${xrActive ? "xr" : "flat"}.${frame}`,
  ...rendererDebugHooks,
});

Worker DAG Manifests

The renderer also publishes worker-facing frame-stage manifests so @plasius/gpu-performance and @plasius/gpu-worker can reason about renderer work as a multi-root DAG instead of a flat queue.

import { getRendererWorkerManifest } from "@plasius/gpu-renderer";

const realtimeManifest = getRendererWorkerManifest();
const xrManifest = getRendererWorkerManifest("xr");

console.log(realtimeManifest.jobs.map((job) => job.worker.jobType));
console.log(xrManifest.jobs.find((job) => job.key === "lateLatch"));

• realtime publishes acquire, visibility, mainEncode, postProcess, and submit.
• xr publishes acquire, visibility, lateLatch, mainEncode, and submit.
• Jobs include queue class, priority, dependencies, adaptive budget levels, and debug metadata such as allocation tags.

Ray-Tracing-First Planning

The renderer now publishes a stable-snapshot render plan for the premium ray-tracing-first frame model.

import { createRayTracingRenderPlan } from "@plasius/gpu-renderer";

const plan = createRayTracingRenderPlan({
  snapshotId: "visual-snapshot-42",
});

console.log(plan.inputBoundary);
console.log(plan.renderStages.map((stage) => stage.key));
console.log(plan.representationBands);

The plan makes the stable visual snapshot boundary explicit, publishes the required RT-first stage ordering, and exposes representation-band plus acceleration-structure update policy metadata for downstream lighting and performance packages.

XR integration

import { createXrManager } from "@plasius/gpu-xr";
import { createGpuRenderer } from "@plasius/gpu-renderer";

const renderer = await createGpuRenderer({ canvas: "#scene" });
const xr = createXrManager();

renderer.bindXrManager(xr, {
  onSessionStart: () => console.log("XR active"),
  onSessionEnd: () => console.log("XR inactive"),
});

API

• supportsWebGpu(options)
• createGpuRenderer(options)
• createRendererDebugHooks(options)
• getRendererWorkerProfile(name?)
• getRendererWorkerManifest(name?)
• createRayTracingRenderPlan(options)
• bindRendererToXrManager(renderer, xrManager, options)
• defaultRendererClearColor
• rendererDebugOwner
• rendererWorkerQueueClass
• defaultRendererWorkerProfile
• rendererWorkerProfiles
• rendererWorkerProfileNames
• rendererWorkerManifests

Demo

Run the demo server from the repo root:

cd gpu-renderer
npm run demo

Then open http://localhost:8000/gpu-renderer/demo/.

The demo now reports explicit canvas state so it is clear whether the renderer is mounted, idle, running, or blocked by secure-context / WebGPU support.

Development Checks

npm run lint
npm run typecheck
npm run test:coverage
npm run build
npm run pack:check

Files

• src/index.js: WebGPU renderer runtime and XR binding helper.
• src/index.d.ts: public API typings.
• tests/package.test.js: unit tests for renderer lifecycle behavior.
• docs/design/worker-manifest-integration.md: renderer frame-stage DAG model.
• docs/adrs/*: architecture decisions for renderer runtime design.
• docs/tdrs/*: technical direction for frame hook integration.