@volter/editor-threejs 0.5.57

package/src/ecs/user-data.ts

@@ -0,0 +1,251 @@
+/**
+ * Typed registry for `Object3D.userData` keys used by the engine and editor.
+ *
+ * Three.js lets any code stash arbitrary values on `object.userData`, and over
+ * time the engine + editor accumulated ~20 stringly-typed keys that together
+ * form a *parallel object model* — meaning carried entirely in undocumented
+ * string literals. This module is the ONE documented place that lists every
+ * such key, its value type, and what it means. All engine/editor-internal
+ * `userData` access for these keys must go through {@link getUserData} /
+ * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
+ * strings live in exactly one place and are type-checked at every call site.
+ * Structural readers may use the narrow `object-marks` accessors instead;
+ * this registry includes that module's canonical keys and value schema.
+ *
+ * NOTE: This covers engine/editor *internal* keys only. User game code in the
+ * example template may stash its own ad-hoc keys; those are out of scope.
+ *
+ * ## Key reference
+ *
+ * Serialization / identity (load-bearing — editor identity):
+ * - `entityId`            — the entity's stable string id. Presence also marks an
+ *                           Object3D as a "real" entity (vs editor helper/env object).
+ *
+ * Runtime scene-query metadata (read by `scene-query.ts` and `scene-index.ts`):
+ * - `tags`                — string[] tags for `queryByTag` and the live index.
+ * - `attributes`          — per-object `Record<string, string|number|boolean>`
+ *                           of game-defined attributes (P2 `observe`). Written
+ *                           through `SceneIndex.setAttribute`, which emits an
+ *                           `attributechanged` signal; JSON-simple values only,
+ *                           so an attribute survives serialization unchanged.
+ *
+ * Runtime gameplay metadata:
+ * - `forward`             — `[x,y,z]` model-space visual forward exported as
+ *                           ordinary glTF extras for asset-facing validation.
+ * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
+ * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
+ * - `splineCurve`         — resolved THREE curve for a spline-following object.
+ * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
+ * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
+ *                           inspector facts, bounds, and deterministic disposal.
+ *
+ * Animation (load-bearing — ED5 disposal contract):
+ * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF.
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
+ * - `_animationRuntime`   — format-neutral live native mixer/action inspection.
+ *
+ * Disposal contract:
+ * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
+ *                           NOT be disposed by per-object cleanup (P0.2 contract).
+ *
+ * Editor shading overrides (editor-only, see `scene-sync.ts`):
+ * - `__shadeOrig`         — original material(s) stashed before a shading override.
+ * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
+ *
+ * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
+ * - `__ingest`            — `true` on every Object3D minted by ingestion; routes
+ *                           edits to live mutation.
+ * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
+ *                           root so re-reflects keep minting unique ids.
+ *
+ * Editor scene-graph tagging (editor-only):
+ * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
+ *                           (particle BatchedRenderer, debug-draw + its subtree).
+ *                           The editor's play-mode hierarchy skips these so they
+ *                           don't show up as selectable "entities".
+ * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
+ *                           its own authoring object instead of a part of the
+ *                           nearest ancestor owner.
+ * - `authoringInstance`   — source OID of the custom-component callsite that
+ *                           rendered this existing Object3D. Used to group
+ *                           implementation parts without adding wrappers.
+ * - `authoringLabel`      — authored literal name (or component tag fallback)
+ *                           for that source-backed component instance.
+ * - `authoringComponent`  — exact source component identity for portable-CSF
+ *                           association; unlike the label, never user-facing copy.
+ * - `authoringDocument`   — generic reference to the project-tool document
+ *                           that owns this scene instance's authored asset.
+ * - `authoringHierarchyId`, `authoringHierarchyParentId`,
+ *   `authoringHierarchyOrder` — source-owned semantic identity, parent identity,
+ *                           and sibling ordinal shared across native surfaces.
+ * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ *
+ * Hierarchy-presentation convention (written by GAME code, read by the editor —
+ * see `../adapter/hierarchy-marks.ts`, which is the ONLY place these two are
+ * read/written from; the `vgai` prefix marks them as the HOST's namespace on a
+ * node a game owns, unlike every other key above, which the engine/editor also
+ * write):
+ * - `vgaiComponentRoot`   — display name of the component instance this subtree
+ *                           IS. The node renders as one collapsed, expandable
+ *                           row named for it.
+ * - `vgaiBuiltInternal`   — `true` on the ROOT of a subtree runtime code
+ *                           CONSTRUCTED rather than authored (skeleton bones,
+ *                           particle renderers). Subtree-scoped: everything
+ *                           below a marked node is built-internal too.
+ * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
+ * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
+ * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
+ * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `reflectionProbe`     — live project-owned reflection probe projected from
+ *                           JSX props for renderer/editor integration.
+ * - `triggerVolume`       — plain `{ radius }` a GAME writes on the node that IS
+ *                           a trigger volume, so the editor can draw its ring
+ *                           (see `../adapter/trigger-volume.ts`).
+ * - `constraints`         — live project-owned spatial constraints projected
+ *                           into the shared Inspector and viewport.
+ * - `authoringSubject`    — transient identity/inspection for an ecosystem-native
+ *                           subject represented by an Object3D proxy.
+ * - `splineControlPoint`  — index of a spline control-point drag handle.
+ * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
+ */
+
+import type * as THREE from 'three';
+import type { ParticleSystem } from 'three.quarks';
+import type { ConstraintMark } from '../adapter/constraint';
+import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
+import type { ReflectionProbeMark } from '../adapter/reflection-probe';
+import type { TriggerVolumeMark } from '../adapter/trigger-volume';
+import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
+import { ObjectMarkKeys, type ObjectMarkSchema } from './object-marks';
+
+export type { EditorHelperType } from './object-marks';
+
+/**
+ * Maps each canonical accessor name to its value type. This is the single
+ * source of truth for what every known `userData` key holds.
+ */
+export interface UserDataSchema extends ObjectMarkSchema {
+  entityId: string;
+  forward: [number, number, number];
+  tags: string[];
+  attributes: Record<string, string | number | boolean>;
+  navRole: 'walkable' | 'obstacle';
+  pivot: [number, number, number];
+  splineCurve: THREE.Curve<THREE.Vector3>;
+  splineControlPoint: number;
+  _camera: THREE.Camera;
+  _particleSystem: ParticleSystem;
+  gaussianSplat: { src: string; numSplats: number };
+  _animMixer: THREE.AnimationMixer;
+  _animClips: Map<string, THREE.AnimationClip>;
+  _availableClips: string[];
+  _animationRuntime: AnimationRuntimeInspection;
+  __sharedGeometry: boolean;
+  __shadeOrig: THREE.Material | THREE.Material[];
+  __shadeUnlit: THREE.Material[];
+  __ingest: boolean;
+  __ingestNextId: number;
+  authoringRoot: boolean;
+  authoringInstance: string;
+  authoringLabel: string;
+  authoringComponent: string;
+  authoringDocument: {
+    readonly kind: 'project-tool';
+    readonly name: string;
+    readonly title: string;
+  };
+  /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
+  authoringHierarchyId: string;
+  /** Project-owned parent identity when the authored parent can live on another surface. */
+  authoringHierarchyParentId: string;
+  /** Source-owned sibling ordinal used when hierarchy rows cross native roots. */
+  authoringHierarchyOrder: number;
+  editorIcon: boolean;
+  envObject: boolean;
+  constraints: readonly ConstraintMark[];
+  authoringSubject: Object3DAuthoringSubjectMark;
+  reflectionProbe: ReflectionProbeMark;
+  triggerVolume: TriggerVolumeMark;
+  vcDirIdx: number;
+}
+
+/** Any key in the typed registry. */
+export type UserDataKey = keyof UserDataSchema;
+
+/**
+ * Canonical name → literal `userData` string key. The accessor names match the
+ * raw string keys 1:1 (this is the documented set referenced by the AC), so the
+ * literal strings are owned here or by the included structural mark registry.
+ */
+export const UserDataKeys = {
+  ...ObjectMarkKeys,
+  entityId: 'entityId',
+  forward: 'forward',
+  tags: 'tags',
+  attributes: 'attributes',
+  navRole: 'navRole',
+  pivot: 'pivot',
+  splineCurve: 'splineCurve',
+  splineControlPoint: 'splineControlPoint',
+  _camera: '_camera',
+  _particleSystem: '_particleSystem',
+  gaussianSplat: 'gaussianSplat',
+  _animMixer: '_animMixer',
+  _animClips: '_animClips',
+  _availableClips: '_availableClips',
+  _animationRuntime: '_animationRuntime',
+  __sharedGeometry: '__sharedGeometry',
+  __shadeOrig: '__shadeOrig',
+  __shadeUnlit: '__shadeUnlit',
+  __ingest: '__ingest',
+  __ingestNextId: '__ingestNextId',
+  authoringRoot: 'authoringRoot',
+  authoringInstance: 'authoringInstance',
+  authoringLabel: 'authoringLabel',
+  authoringComponent: 'authoringComponent',
+  authoringDocument: 'authoringDocument',
+  authoringHierarchyId: 'authoringHierarchyId',
+  authoringHierarchyParentId: 'authoringHierarchyParentId',
+  authoringHierarchyOrder: 'authoringHierarchyOrder',
+  editorIcon: 'editorIcon',
+  envObject: 'envObject',
+  constraints: 'constraints',
+  authoringSubject: 'authoringSubject',
+  reflectionProbe: 'reflectionProbe',
+  triggerVolume: 'triggerVolume',
+  vcDirIdx: 'vcDirIdx',
+} as const satisfies Record<UserDataKey, string>;
+
+/**
+ * Read a typed `userData` value. Returns `undefined` when the key is unset or
+ * when `obj` is nullish (so call sites can pass an optionally-resolved object).
+ */
+export function getUserData<K extends UserDataKey>(
+  obj: THREE.Object3D | null | undefined,
+  key: K,
+): UserDataSchema[K] | undefined {
+  return obj ? (obj.userData[UserDataKeys[key]] as UserDataSchema[K] | undefined) : undefined;
+}
+
+/** Write a typed `userData` value. */
+export function setUserData<K extends UserDataKey>(
+  obj: THREE.Object3D,
+  key: K,
+  value: UserDataSchema[K],
+): void {
+  obj.userData[UserDataKeys[key]] = value;
+}
+
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export function hasUserData(obj: THREE.Object3D | null | undefined, key: UserDataKey): boolean {
+  return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
+}
+
+/** Remove a `userData` key. */
+export function deleteUserData(obj: THREE.Object3D, key: UserDataKey): void {
+  delete obj.userData[UserDataKeys[key]];
+}

package/src/loader.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared asset loading infrastructure.
+ *
+ * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
+ * (for raw fetch calls) so that all engine asset requests go through one
+ * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ *
+ * Three.js loaders constructed with `loadingManager` automatically rewrite
+ * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
+ * resolveUrl() to apply the same prefix.
+ */
+
+import * as THREE from 'three';
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+let _prefix = '/';
+
+function rewriteUrl(url: string): string {
+  if (
+    url.startsWith('/') ||
+    url.startsWith('http') ||
+    url.startsWith('data:') ||
+    url.startsWith('blob:')
+  ) {
+    return url;
+  }
+  return _prefix + url;
+}
+
+/** Shared Three.js LoadingManager — all engine loaders should use this. */
+export const loadingManager = new THREE.LoadingManager();
+loadingManager.setURLModifier(rewriteUrl);
+
+/** Pre-configured TextureLoader using the shared manager. */
+export const textureLoader = new THREE.TextureLoader(loadingManager);
+
+/**
+ * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
+ *
+ * The decoder wasm/js is vendored under
+ * packages/editor/template/public/jsm/libs/draco/gltf/ and served at the
+ * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
+ * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
+ * absolute path, so it deliberately does NOT go through the asset prefix —
+ * the decoder is engine infrastructure, not a scene asset.
+ */
+export const dracoLoader = new DRACOLoader(loadingManager);
+dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
+
+/**
+ * Shared KTX2Loader for decoding KHR_texture_basisu (KTX2/Basis) textures.
+ *
+ * Vendored and served EXACTLY like the DRACO decoder above — the Basis
+ * transcoder js/wasm live in repo-root `public/jsm/libs/basis/` (the editor)
+ * and `packages/editor/template/public/jsm/libs/basis/` (a scaffolded game's
+ * own build), pinned in `vendor/upstream-assets.lock.json`, and KTX2Loader
+ * appends `basis_transcoder.js` / `.wasm` to this absolute path.
+ *
+ * Without this wiring, the Asset Budget's "Compress textures · KTX2" output
+ * is a GLB nothing in the engine can load — which is why the op and this
+ * loader landed together.
+ */
+export const ktx2Loader = new KTX2Loader(loadingManager);
+ktx2Loader.setTranscoderPath('/jsm/libs/basis/');
+
+let ktx2SupportDetected = false;
+
+/**
+ * Teach the shared KTX2Loader which compressed formats THIS GPU accepts.
+ *
+ * KTX2Loader refuses to transcode until it has seen a renderer, and the
+ * answer is a property of the page's GPU rather than of any one renderer —
+ * so the FIRST renderer to exist supplies it and every later one is a no-op.
+ * Called by the engine's own renderer setup (`setup/setup-renderer.ts`) and
+ * by the editor's viewport, which between them cover every surface that
+ * parses a GLB.
+ *
+ * This sits on the MOUNT path, so it must never throw for a renderer it
+ * cannot question. `detectSupport` reads `renderer.extensions.has/get` (or
+ * `renderer.hasFeature` on a WebGPU renderer) — surface a headless stand-in
+ * (the test harnesses' fake renderers, any non-WebGL host) does not have.
+ * Such a renderer is skipped WITHOUT latching, so the first renderer that
+ * can actually answer still configures the loader for the whole page.
+ */
+export function detectKtx2Support(renderer: THREE.WebGLRenderer): void {
+  if (ktx2SupportDetected) return;
+  const probe = renderer as unknown as
+    | {
+        isWebGPURenderer?: boolean;
+        hasFeature?: unknown;
+        extensions?: { has?: unknown; get?: unknown };
+      }
+    | null
+    | undefined;
+  const canAnswer =
+    probe != null &&
+    (probe.isWebGPURenderer === true
+      ? typeof probe.hasFeature === 'function'
+      : typeof probe.extensions?.has === 'function' && typeof probe.extensions?.get === 'function');
+  if (!canAnswer) return;
+  ktx2Loader.detectSupport(renderer);
+  ktx2SupportDetected = true;
+}
+
+/** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
+export const gltfLoader = new GLTFLoader(loadingManager);
+gltfLoader.setDRACOLoader(dracoLoader);
+gltfLoader.setKTX2Loader(ktx2Loader);
+// EXT_meshopt_compression decoding (three's own bundled decoder — inline
+// wasm, no fetch). Without this, a meshopt-compressed GLB — including the
+// output of the editor's Asset Budget "Compress · meshopt" action (W4a M3) —
+// throws at load time in every runtime and the editor viewport. Symmetric
+// with the DRACO wiring above (CB2): the ONE shared loader owns codec setup.
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+
+/**
+ * Set the URL prefix prepended to relative asset paths.
+ * Called once by createGameRuntime(). Defaults to '/'.
+ */
+export function setAssetPrefix(prefix: string): void {
+  _prefix = prefix.endsWith('/') ? prefix : prefix ? `${prefix}/` : '/';
+}
+
+/**
+ * Resolve a relative asset URL using the current prefix.
+ * Use this for raw fetch() calls — Three.js loaders using
+ * `loadingManager` handle this automatically.
+ */
+export function resolveUrl(url: string): string {
+  return rewriteUrl(url);
+}

package/src/render/matcap-texture.ts

@@ -0,0 +1,92 @@
+import * as THREE from 'three';
+
+/**
+ * The neutral matcap sphere, DRAWN rather than shipped.
+ *
+ * A matcap is just a picture of a lit sphere sampled by view-space normal, so
+ * there is nothing to vendor: the same three numbers a shader would use
+ * (key, fill, rim) evaluated once per texel produce the image. Keeping it
+ * procedural means the diagnostic look has no binary asset, no license, no
+ * provenance row, and no way to go missing from a build.
+ *
+ * The look is deliberately CLAY: one warm key from the upper left, a cool
+ * fill from the lower right, a tight rim, and a broad soft highlight — the
+ * neutral sculpting material whose whole job is to let form read without
+ * colour, texture or authored lighting getting a vote.
+ */
+
+const SIZE = 256;
+
+/** sRGB transfer curve — the canvas holds display-referred bytes. */
+function encode(value: number): number {
+  const c = Math.min(1, Math.max(0, value));
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+function normalize(x: number, y: number, z: number): [number, number, number] {
+  const length = Math.hypot(x, y, z) || 1;
+  return [x / length, y / length, z / length];
+}
+
+export function drawNeutralMatcap(size = SIZE): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (!context) return canvas;
+  const image = context.createImageData(size, size);
+
+  const key = normalize(-0.45, 0.62, 0.64);
+  const fill = normalize(0.65, -0.35, 0.5);
+  // View direction is +Z for a matcap: the sphere is drawn facing the camera.
+  const half = normalize(key[0], key[1], key[2] + 1);
+  const base = [0.7, 0.69, 0.68];
+  const fillColor = [0.34, 0.4, 0.52];
+  const rimColor = [0.85, 0.88, 1];
+
+  for (let py = 0; py < size; py++) {
+    for (let px = 0; px < size; px++) {
+      const nx = (px + 0.5) / size / 0.5 - 1;
+      const ny = 1 - (py + 0.5) / size / 0.5;
+      const r2 = nx * nx + ny * ny;
+      // Outside the unit disc a matcap is never sampled by a facing surface,
+      // but bilinear filtering reaches one texel past the silhouette. Clamp
+      // to the rim normal so the edge stays the rim colour instead of
+      // bleeding whatever happened to be there.
+      const clamped = r2 > 1;
+      const scale = clamped ? 1 / Math.sqrt(r2) : 1;
+      const x = nx * scale;
+      const y = ny * scale;
+      const z = clamped ? 0 : Math.sqrt(Math.max(0, 1 - r2));
+
+      const diffuse = Math.max(0, x * key[0] + y * key[1] + z * key[2]);
+      const fillTerm = Math.max(0, x * fill[0] + y * fill[1] + z * fill[2]);
+      const specular = Math.max(0, x * half[0] + y * half[1] + z * half[2]) ** 42 * 0.5;
+      const rim = (1 - z) ** 3.2 * 0.4;
+
+      const offset = (py * size + px) * 4;
+      for (let channel = 0; channel < 3; channel++) {
+        const lit =
+          base[channel]! * (0.16 + 0.8 * diffuse) +
+          fillColor[channel]! * 0.3 * fillTerm +
+          rimColor[channel]! * rim +
+          specular;
+        image.data[offset + channel] = Math.round(encode(lit) * 255);
+      }
+      image.data[offset + 3] = 255;
+    }
+  }
+  context.putImageData(image, 0, 0);
+  return canvas;
+}
+
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export function createNeutralMatcapTexture(size = SIZE): THREE.CanvasTexture {
+  const texture = new THREE.CanvasTexture(drawNeutralMatcap(size));
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.minFilter = THREE.LinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.needsUpdate = true;
+  return texture;
+}

package/src/render/spark-renderer-lifecycle.ts

@@ -0,0 +1,64 @@
+import type { SparkRenderer } from '@sparkjsdev/spark';
+import type * as THREE from 'three';
+import { hasUserData } from '../ecs/user-data';
+
+const IDLE_POLL_MS = 16;
+const MAX_IDLE_WAIT_MS = 3_000;
+export const SPARK_DISCOVERY_INTERVAL_MS = 500;
+
+/** Gate fallback discovery so ordinary non-splat scenes are never traversed every frame. */
+export function shouldDiscoverGaussianSplat(lastCheckAt: number, now: number): boolean {
+  return now - lastCheckAt >= SPARK_DISCOVERY_INTERVAL_MS;
+}
+
+/** True when a native scene currently contains at least one Gaussian payload. */
+export function sceneHasGaussianSplat(scene: THREE.Object3D): boolean {
+  let found = false;
+  scene.traverse((object) => {
+    if (!found && hasUserData(object, 'gaussianSplat')) found = true;
+  });
+  return found;
+}
+
+/**
+ * Stop and dispose Spark after its asynchronous depth-sort worker is idle.
+ *
+ * SparkRenderer.dispose() rejects any worker calls still in flight. Spark's
+ * automatic update path intentionally does not await those calls, so disposing
+ * synchronously during an editor stop otherwise produces an unhandled
+ * `Worker terminate` rejection. Disable future work immediately, then release
+ * the renderer once the current sort has naturally settled.
+ */
+export function disposeSparkRendererWhenIdle(renderer: SparkRenderer): void {
+  renderer.autoUpdate = false;
+  renderer.sortDirty = false;
+
+  if (renderer.updateTimeoutId !== -1) {
+    clearTimeout(renderer.updateTimeoutId);
+    renderer.updateTimeoutId = -1;
+  }
+  if (renderer.sortTimeoutId !== -1) {
+    clearTimeout(renderer.sortTimeoutId);
+    renderer.sortTimeoutId = -1;
+  }
+
+  let remainingIdleWaitMs = MAX_IDLE_WAIT_MS;
+  const disposeWhenIdle = (): void => {
+    if (renderer.sorting) {
+      if (remainingIdleWaitMs > 0) {
+        remainingIdleWaitMs -= IDLE_POLL_MS;
+        setTimeout(disposeWhenIdle, IDLE_POLL_MS);
+      } else {
+        // A stuck upstream worker is safer to abandon than to turn a routine
+        // editor stop into an unhandled rejection. Page teardown will reclaim
+        // the worker; normal sorts complete in a few milliseconds.
+        // biome-ignore lint/suspicious/noConsole: This rare upstream worker leak must degrade loudly.
+        console.warn('SparkRenderer did not become idle; skipped worker termination.');
+      }
+      return;
+    }
+    renderer.dispose();
+  };
+
+  disposeWhenIdle();
+}