@volter/editor-threejs 0.5.57

package/src/viewport/preview-renderer.ts

@@ -0,0 +1,179 @@
+/**
+ * The WebGL renderer the INSPECTOR-PREVIEW lane draws through — one per editor
+ * session, not one per selection.
+ *
+ * Why this module exists (measured, 2026-08-07): every chromeless preview
+ * (`components/InspectorObjectPreview.tsx` → `Object3DSnapshotDocument` →
+ * `Object3DDocumentViewport`) used to construct its own
+ * `THREE.WebGLRenderer` on mount, so SELECTING A THING built a whole GL stack.
+ * A renderer's constructor is a long chain of synchronous driver round trips
+ * (`WebGLCapabilities`/`getExtension`/`getParameter`), and its program cache
+ * starts empty, so every selection also recompiled the subject's shaders and
+ * re-baked the PMREM environment. A click profiled at ~1.9 s of frozen main
+ * thread, 3.5 s of self time in `gl.getParameter` alone. Sharing one renderer
+ * removes the construction entirely and lets the program cache and the IBL
+ * bake survive across selections.
+ *
+ * OWNERSHIP — the one place it is stated:
+ *  - This module OWNS every canvas, `WebGLRenderer` and baked
+ *    {@link StandardEnvironment} it creates. Nothing else may dispose them.
+ *  - SHARERS are lease holders: {@link acquireInspectorPreviewRenderer} hands
+ *    out a lease, the holder mounts `lease.canvas` in its own container and
+ *    draws through `lease.renderer` for as long as it is mounted.
+ *  - The ONE teardown path a holder has is {@link InspectorPreviewLease.release}
+ *    — it returns the renderer to the pool (or disposes it, if it was an
+ *    overflow lease that the pool does not keep). A holder never calls
+ *    `renderer.dispose()`, and never disposes `lease.environment()`, whose
+ *    handle is deliberately non-owning.
+ *  - Per-selection SCENE resources (the snapshot's skeletons, the dressing's
+ *    lights/grid/backdrop) stay the holder's, exactly as before: three's
+ *    program cache lives on the renderer and is not touched by disposing the
+ *    materials that populated it.
+ *
+ * Capacity is deliberately small. The inspector shows ONE live preview at a
+ * time by construction (`InspectionProjection.tsx` drops the disc to its glyph
+ * while the preview panel is open), so a second entry is slack for a handover
+ * frame, and anything beyond that is a transient renderer disposed on release
+ * rather than a growing pool.
+ */
+
+import * as THREE from 'three';
+import { createStandardEnvironment, type StandardEnvironment } from './environment';
+import { markHostRenderer } from './renderer-ownership';
+
+/** How many renderers the lane keeps alive between selections. */
+const POOL_CAPACITY = 2;
+
+interface PreviewRendererEntry {
+  readonly canvas: HTMLCanvasElement;
+  readonly renderer: THREE.WebGLRenderer;
+  environment: StandardEnvironment | null;
+  /** In the pool (kept between leases) rather than an overflow renderer. */
+  pooled: boolean;
+  leased: boolean;
+  /** The GL context went away; the entry is dead and is never leased again. */
+  lost: boolean;
+}
+
+const entries: PreviewRendererEntry[] = [];
+const liveEntries = new Set<PreviewRendererEntry>();
+
+export interface InspectorPreviewLease {
+  /** The canvas to mount. It is the renderer's own `domElement`. */
+  readonly canvas: HTMLCanvasElement;
+  readonly renderer: THREE.WebGLRenderer;
+  /**
+   * The lane's shared IBL bake, as a NON-OWNING handle: its `dispose()` is a
+   * no-op, so the standard dressing (which disposes the environment it is
+   * given) can take it under its usual contract without freeing a render
+   * target the next selection needs.
+   */
+  environment(): StandardEnvironment;
+  /** The one teardown path. Idempotent; unmounts the canvas. Discard after a
+   * render exception: Three may have skipped its internal render-stack cleanup. */
+  release(options?: { discard?: boolean }): void;
+}
+
+function createEntry(): PreviewRendererEntry {
+  const canvas = document.createElement('canvas');
+  canvas.style.width = '100%';
+  canvas.style.height = '100%';
+  canvas.style.display = 'block';
+  const renderer = markHostRenderer(
+    new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true }),
+  );
+  const entry: PreviewRendererEntry = {
+    canvas,
+    renderer,
+    environment: null,
+    pooled: false,
+    leased: true,
+    lost: false,
+  };
+  liveEntries.add(entry);
+  // A lost context cannot be drawn through again, and three's renderer does not
+  // rebuild itself. Drop the entry so the next acquisition builds a fresh one.
+  canvas.addEventListener('webglcontextlost', () => {
+    entry.lost = true;
+    const index = entries.indexOf(entry);
+    if (index >= 0) entries.splice(index, 1);
+    if (!entry.leased) disposeEntry(entry);
+  });
+  return entry;
+}
+
+function disposeEntry(entry: PreviewRendererEntry): void {
+  // forceContextLoss can deliver the loss event after an explicit discard.
+  if (!liveEntries.delete(entry)) return;
+  entry.environment?.dispose();
+  entry.environment = null;
+  entry.renderer.dispose();
+  // `dispose()` frees GPU RESOURCES; it does not give the CONTEXT back. The
+  // canvas holds it until garbage collection decides otherwise, and WebGL
+  // contexts are a hard ~16-per-page budget the browser enforces by killing
+  // the OLDEST — which is the main viewport, so the symptom is a white
+  // viewport and "too many active WebGL contexts" far from the cause
+  // (runhuman pass 104). Every other renderer owner in this editor already
+  // pairs the two (`asset-preview.ts`, `components/world-root-stage.ts`); this
+  // shared pool did not, and it backs both the Inspector preview and the
+  // Object3D tool's viewport, so its transients leaked a context each.
+  entry.renderer.forceContextLoss();
+  entry.canvas.remove();
+}
+
+/** Diagnostic readback kept separate from the interactive-document pool. */
+export function inspectorPreviewRendererCounts(): {
+  readonly active: number;
+  readonly idle: number;
+} {
+  return {
+    active: [...liveEntries].filter((entry) => entry.leased && !entry.lost).length,
+    idle: [...liveEntries].filter((entry) => !entry.leased && !entry.lost).length,
+  };
+}
+
+/** Take the lane's renderer for one mounted preview. Never fails to a caller:
+ *  when the pool is busy it hands back a transient renderer instead. */
+export function acquireInspectorPreviewRenderer(): InspectorPreviewLease {
+  let entry = entries.find((candidate) => !candidate.leased && !candidate.lost);
+  if (!entry) {
+    entry = createEntry();
+    if (entries.length < POOL_CAPACITY) {
+      entry.pooled = true;
+      entries.push(entry);
+    }
+  }
+  entry.leased = true;
+  const held = entry;
+  let released = false;
+  return {
+    canvas: held.canvas,
+    renderer: held.renderer,
+    environment(): StandardEnvironment {
+      held.environment ??= createStandardEnvironment(held.renderer);
+      const texture = held.environment.texture;
+      return { texture, dispose: () => {} };
+    },
+    release(options): void {
+      if (released) return;
+      released = true;
+      held.leased = false;
+      held.canvas.remove();
+      if (options?.discard) {
+        held.lost = true;
+        const index = entries.indexOf(held);
+        if (index >= 0) entries.splice(index, 1);
+      }
+      if (!held.pooled || held.lost) {
+        disposeEntry(held);
+        return;
+      }
+      // Leave nothing of this subject on the surface: the canvas is re-mounted
+      // for the NEXT subject and would otherwise show the last frame of the
+      // previous one until its first draw lands.
+      held.renderer.setScissorTest(false);
+      held.renderer.autoClear = true;
+      held.renderer.clear();
+    },
+  };
+}

package/src/viewport/renderer-ownership.ts

@@ -0,0 +1,86 @@
+/**
+ * The set of `WebGLRenderer`s the editor-side Three integration owns — its viewport, and every
+ * offscreen renderer it spins up for thumbnails, asset previews and asset
+ * compare.
+ *
+ * Why this exists: ingest's scene-capture trap
+ * (`@volter/editor-threejs-runtime/adapter/ingest/scene-capture`) is installed on the SHARED
+ * `three.WebGLRenderer.prototype` — that sharing is the whole mechanism, it is
+ * how an unmodified game's renderer gets instrumented without touching the
+ * game's source. But it means the editor's own renders arrive at the trap too,
+ * and the trap captures the first scene it sees. Any host renderer constructed
+ * after the trap installs (a thumbnail bake, an asset preview) could therefore
+ * be captured AS THE INGESTED GAME.
+ *
+ * That is not hypothetical: it is what made the "a game bundling its own three
+ * is DETECTED, never silently mistaken for a capture" spec pass or fail on
+ * timing alone. When it failed, the editor
+ * had adopted its own thumbnail scene as the game: a hierarchy of the editor's
+ * own lights, presented as the game's content.
+ *
+ * Marking is explicit at each construction site rather than inferred, because
+ * the honest question ("did the HOST make this renderer?") has no reliable
+ * signal at the trap: a host renderer and a game renderer are the same class,
+ * both constructed after install, and both render real scenes.
+ */
+
+const _hostRenderers = new WeakSet<object>();
+
+/** Record `renderer` as the editor's own. Returns it, so it can wrap a `new`. */
+/**
+ * WebGL contexts are a HARD, SMALL browser budget (order of sixteen per page),
+ * and this is the one chokepoint every editor-constructed renderer passes
+ * through — so it is where an editor that is quietly accumulating them can be
+ * caught naming its own culprit.
+ *
+ * A tester adding and deleting prefabs hit "too many active WebGL contexts"
+ * after five rounds and the whole viewport turned white, because the browser
+ * evicts the OLDEST context when the limit is reached and the oldest is the
+ * main viewport (runhuman pass 104). Three's warning comes from inside
+ * `three.module.js` and names nothing about who asked, which is what made it
+ * undiagnosable from the report.
+ *
+ * The count is LIVE: `dispose()` is wrapped so a renderer that is properly
+ * torn down stops counting. Past the budget the warning carries the creating
+ * stack, so the next sighting names the leak instead of the victim.
+ */
+const LIVE_RENDERER_WARN_AT = 8;
+let liveHostRenderers = 0;
+
+export function markHostRenderer<T extends object>(renderer: T): T {
+  _hostRenderers.add(renderer);
+  liveHostRenderers += 1;
+  const disposable = renderer as { dispose?: () => void };
+  const dispose = disposable.dispose;
+  if (typeof dispose === 'function') {
+    let counted = true;
+    disposable.dispose = function wrappedDispose(this: unknown, ...args: unknown[]) {
+      if (counted) {
+        counted = false;
+        liveHostRenderers -= 1;
+      }
+      return (dispose as (...a: unknown[]) => unknown).apply(this, args);
+    } as () => void;
+  }
+  if (liveHostRenderers >= LIVE_RENDERER_WARN_AT) {
+    // biome-ignore lint/suspicious/noConsole: the standing warning channel for a budget the browser enforces by destroying the viewport
+    console.warn(
+      `[host-renderers] ${liveHostRenderers} editor WebGL renderers are live at once. The ` +
+        'browser evicts the OLDEST context past its limit, which is the main viewport — a white ' +
+        'viewport and "too many active WebGL contexts" is this. Creating stack:',
+      new Error('renderer created here').stack,
+    );
+  }
+  return renderer;
+}
+
+/** Live count of editor-constructed renderers — for diagnostics that want the
+ *  number without waiting for the warning threshold. */
+export function liveHostRendererCount(): number {
+  return liveHostRenderers;
+}
+
+/** True when `renderer` is one the editor constructed for its own rendering. */
+export function isHostRenderer(renderer: unknown): boolean {
+  return typeof renderer === 'object' && renderer !== null && _hostRenderers.has(renderer);
+}