@pascal-app/viewer 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/lib/geometry-groups.js

@@ -0,0 +1,53 @@
+import * as THREE from 'three';
+/**
+ * Rewrites a geometry's material groups so every material is drawn exactly once.
+ *
+ * A group is a contiguous slice of the index buffer, so a mesh whose triangles
+ * alternate between materials pays a draw call per *run*, not per material.
+ * Extruded walls hit this hard: `ExtrudeGeometry` emits the cap and side faces
+ * interleaved, so run-length grouping produces four groups for two materials —
+ * multiplied by a thousand walls, that is thousands of avoidable draw calls.
+ * Bucketing the triangles by material first makes each material one run.
+ *
+ * The geometry gains an index buffer if it had none. Triangle winding, vertex
+ * data and material assignment are untouched, so the rendered image is
+ * unchanged; only the order in which the GPU is asked to draw it differs.
+ */
+export function setGroupsSortedByMaterial(geometry, triangleMaterials) {
+    geometry.clearGroups();
+    const position = geometry.getAttribute('position');
+    if (!position)
+        return;
+    const sourceIndex = geometry.getIndex();
+    const triangleCount = Math.min(triangleMaterials.length, sourceIndex ? Math.floor(sourceIndex.count / 3) : Math.floor(position.count / 3));
+    if (triangleCount === 0)
+        return;
+    const buckets = new Map();
+    for (let triangle = 0; triangle < triangleCount; triangle += 1) {
+        const material = triangleMaterials[triangle] ?? 0;
+        const bucket = buckets.get(material);
+        if (bucket)
+            bucket.push(triangle);
+        else
+            buckets.set(material, [triangle]);
+    }
+    const singleMaterial = buckets.size === 1 ? [...buckets.keys()][0] : undefined;
+    if (singleMaterial !== undefined) {
+        geometry.addGroup(0, triangleCount * 3, singleMaterial);
+        return;
+    }
+    const reordered = new Uint32Array(triangleCount * 3);
+    let cursor = 0;
+    for (const [material, triangles] of [...buckets].sort((left, right) => left[0] - right[0])) {
+        const groupStart = cursor;
+        for (const triangle of triangles) {
+            const base = triangle * 3;
+            reordered[cursor] = sourceIndex ? sourceIndex.getX(base) : base;
+            reordered[cursor + 1] = sourceIndex ? sourceIndex.getX(base + 1) : base + 1;
+            reordered[cursor + 2] = sourceIndex ? sourceIndex.getX(base + 2) : base + 2;
+            cursor += 3;
+        }
+        geometry.addGroup(groupStart, cursor - groupStart, material);
+    }
+    geometry.setIndex(new THREE.BufferAttribute(reordered, 1));
+}

package/dist/lib/isolation.d.ts

@@ -15,21 +15,21 @@ export declare function collectIsolationSubtree(ids: ReadonlyArray<string>): Set
 /**
  * Imperative visibility filter on the live `sceneRegistry`. Hides every
  * registered group (and its synthesized child meshes) outside the
- * isolated subtree by disabling the {@link SCENE_LAYER} bit on the
- * relevant `Object3D.layers` masks.
+ * isolated subtree by taking it off the scene layer.
  *
  * Why layers instead of `obj.visible = false`? Three.js's visibility
  * flag *cascades* — hiding a parent hides every descendant — so we
  * can't hide a host wall while keeping a door rendered inside it.
  * Layer masks are per-object and don't cascade: `WebGLRenderer
  * .projectObject` skips objects whose layer mask doesn't intersect the
- * camera's, but always recurses into their children. So we can disable
- * `SCENE_LAYER` on the wall and the door (hosted under it in the
- * scene graph) still renders, with its local position relative to the
- * wall preserved automatically by the matrix walk.
+ * camera's, but always recurses into their children. So we can hide
+ * the wall and the door (hosted under it in the scene graph) still
+ * renders, with its local position relative to the wall preserved
+ * automatically by the matrix walk.
  *
- * The original `layers.mask` is stashed under a private Symbol so
- * {@link clearIsolation} can restore the exact prior state.
+ * The mask itself belongs to `lib/scene-visibility.ts`, which reconciles
+ * isolation with solo's shadow-caster pass, so {@link clearIsolation}
+ * gives an object back only what isolation took.
  *
  * Pass `null` to clear isolation (equivalent to calling
  * {@link clearIsolation}).

package/dist/lib/isolation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolation.d.ts","sourceRoot":"","sources":["../../src/lib/isolation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAgBrC,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAUjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,IAAI,CAiBzE;AAcD,wBAAgB,cAAc,IAAI,IAAI,CAcrC"}
+{"version":3,"file":"isolation.d.ts","sourceRoot":"","sources":["../../src/lib/isolation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AASrC,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAUjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,IAAI,CAiBzE;AAUD,wBAAgB,cAAc,IAAI,IAAI,CAUrC"}

package/dist/lib/isolation.js

@@ -1,12 +1,8 @@
 'use client';
 import { sceneRegistry } from '@pascal-app/core';
-import { SCENE_LAYER } from './layers';
-// Marker on each Object3D we modify during isolation so we can restore
-// the original `layers.mask` bitfield. Stored under a `Symbol` so it
-// can't collide with any kind's own userData fields.
-const ORIGINAL_LAYERS = Symbol('isolation:original-layers');
-// Whether a subtree is currently isolated (some objects have SCENE_LAYER
-// disabled). Read by consumers that must not act on the partial view — e.g.
+import { hideFromScene, showInScene } from './scene-visibility';
+// Whether a subtree is currently isolated (some objects are held off the
+// scene layer). Read by consumers that must not act on the partial view — e.g.
 // the project-thumbnail autosave skips capturing while isolated so it never
 // snapshots a single focused item as the whole project's thumbnail.
 let isolationActive = false;
@@ -38,21 +34,21 @@ export function collectIsolationSubtree(ids) {
 /**
  * Imperative visibility filter on the live `sceneRegistry`. Hides every
  * registered group (and its synthesized child meshes) outside the
- * isolated subtree by disabling the {@link SCENE_LAYER} bit on the
- * relevant `Object3D.layers` masks.
+ * isolated subtree by taking it off the scene layer.
  *
  * Why layers instead of `obj.visible = false`? Three.js's visibility
  * flag *cascades* — hiding a parent hides every descendant — so we
  * can't hide a host wall while keeping a door rendered inside it.
  * Layer masks are per-object and don't cascade: `WebGLRenderer
  * .projectObject` skips objects whose layer mask doesn't intersect the
- * camera's, but always recurses into their children. So we can disable
- * `SCENE_LAYER` on the wall and the door (hosted under it in the
- * scene graph) still renders, with its local position relative to the
- * wall preserved automatically by the matrix walk.
+ * camera's, but always recurses into their children. So we can hide
+ * the wall and the door (hosted under it in the scene graph) still
+ * renders, with its local position relative to the wall preserved
+ * automatically by the matrix walk.
  *
- * The original `layers.mask` is stashed under a private Symbol so
- * {@link clearIsolation} can restore the exact prior state.
+ * The mask itself belongs to `lib/scene-visibility.ts`, which reconciles
+ * isolation with solo's shadow-caster pass, so {@link clearIsolation}
+ * gives an object back only what isolation took.
  *
  * Pass `null` to clear isolation (equivalent to calling
  * {@link clearIsolation}).
@@ -64,9 +60,9 @@ export function applyIsolation(ids) {
     }
     const keep = collectIsolationSubtree(ids);
     // Iterate registered roots. For each one outside the keep set,
-    // disable `SCENE_LAYER` on it and on every descendant — *except*
-    // descendants that are themselves in `keep` (a kept node nested under
-    // a non-kept host: the isolated door under the hidden wall).
+    // hide it and every descendant — *except* descendants that are
+    // themselves in `keep` (a kept node nested under a non-kept host:
+    // the isolated door under the hidden wall).
     for (const [, obj] of sceneRegistry.nodes) {
         if (keep.has(obj))
             continue;
@@ -77,26 +73,18 @@ export function applyIsolation(ids) {
 function hideRecursive(obj, keep) {
     if (keep.has(obj))
         return;
-    const carrier = obj;
-    if (carrier[ORIGINAL_LAYERS] === undefined) {
-        carrier[ORIGINAL_LAYERS] = obj.layers.mask;
-    }
-    obj.layers.disable(SCENE_LAYER);
+    hideFromScene(obj, 'isolated');
     for (const child of obj.children) {
         hideRecursive(child, keep);
     }
 }
 export function clearIsolation() {
     // We don't know which objects were touched without re-walking, so
-    // walk every registered root + its descendants and restore any
-    // stashed original-mask. `traverse` is cheap and idempotent here.
+    // walk every registered root + its descendants and drop the isolation
+    // reason wherever it was set. `traverse` is cheap and idempotent here.
     for (const [, obj] of sceneRegistry.nodes) {
         obj.traverse((child) => {
-            const carrier = child;
-            if (carrier[ORIGINAL_LAYERS] !== undefined) {
-                child.layers.mask = carrier[ORIGINAL_LAYERS];
-                delete carrier[ORIGINAL_LAYERS];
-            }
+            showInScene(child, 'isolated');
         });
     }
     isolationActive = false;

package/dist/lib/layers.d.ts

@@ -1,3 +1,4 @@
+import type { Layers } from 'three';
 /** Default Three.js layer for main scene geometry. */
 export declare const SCENE_LAYER = 0;
 /**
@@ -30,4 +31,19 @@ export declare const GRID_LAYER = 3;
  * cascade) via `applyShadowOnly` / `clearShadowOnly` in `lib/shadow-only.ts`.
  */
 export declare const SHADOW_ONLY_LAYER = 4;
+/**
+ * Layer for source geometry that a collective batch already draws. No camera
+ * or pass enables it, so a batched object costs no draw call while its children
+ * and interaction proxies remain in the graph.
+ *
+ * Raycasters that query real surfaces must opt in via
+ * {@link setSurfaceRaycastLayers}, otherwise a sewn wall would stop answering
+ * measurement rays.
+ */
+export declare const BATCHED_LAYER = 5;
+/**
+ * Aims a raycaster at every real scene surface, whether a wall still draws
+ * itself or a level batch draws it for us.
+ */
+export declare function setSurfaceRaycastLayers(layers: Layers): void;
 //# sourceMappingURL=layers.d.ts.map

package/dist/lib/layers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../src/lib/layers.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,eAAO,MAAM,WAAW,IAAI,CAAA;AAE5B;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,IAAI,CAAA;AAE9B,oEAAoE;AACpE,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA"}
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../src/lib/layers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAEnC,sDAAsD;AACtD,eAAO,MAAM,WAAW,IAAI,CAAA;AAE5B;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,IAAI,CAAA;AAE9B,oEAAoE;AACpE,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,IAAI,CAAA;AAE9B;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG5D"}

package/dist/lib/layers.js

@@ -30,3 +30,21 @@ export const GRID_LAYER = 3;
  * cascade) via `applyShadowOnly` / `clearShadowOnly` in `lib/shadow-only.ts`.
  */
 export const SHADOW_ONLY_LAYER = 4;
+/**
+ * Layer for source geometry that a collective batch already draws. No camera
+ * or pass enables it, so a batched object costs no draw call while its children
+ * and interaction proxies remain in the graph.
+ *
+ * Raycasters that query real surfaces must opt in via
+ * {@link setSurfaceRaycastLayers}, otherwise a sewn wall would stop answering
+ * measurement rays.
+ */
+export const BATCHED_LAYER = 5;
+/**
+ * Aims a raycaster at every real scene surface, whether a wall still draws
+ * itself or a level batch draws it for us.
+ */
+export function setSurfaceRaycastLayers(layers) {
+    layers.set(SCENE_LAYER);
+    layers.enable(BATCHED_LAYER);
+}

package/dist/lib/renderer-capability.d.ts

@@ -0,0 +1,56 @@
+export type RendererCapabilityCanvas = {
+    getContext(contextId: 'webgl2'): unknown;
+};
+/** Mirrors `GPUPowerPreference` without pulling WebGPU ambient types into the declaration build. */
+export type RendererPowerPreference = 'high-performance' | 'low-power';
+type RendererGpuAdapter = {
+    features?: Iterable<string>;
+    requestDevice(descriptor?: {
+        requiredFeatures?: string[];
+    }): Promise<unknown>;
+};
+type RendererGpu = {
+    requestAdapter(options?: Record<string, unknown>): Promise<RendererGpuAdapter | null>;
+};
+export type RendererCapability = {
+    backend: 'webgpu';
+    device: unknown;
+    status: 'supported';
+} | {
+    backend: 'webgl';
+    status: 'supported';
+} | {
+    error?: unknown;
+    status: 'unsupported';
+};
+export type RendererBackendParameters = {
+    device?: unknown;
+    forceWebGL?: boolean;
+};
+type InitializableRenderer = {
+    dispose?: () => void;
+    init: () => Promise<unknown>;
+};
+export type RendererInitializationResult<Renderer> = {
+    backend: 'webgpu' | 'webgl';
+    renderer: Renderer;
+    status: 'ready';
+} | {
+    error?: unknown;
+    status: 'unsupported';
+};
+export declare function detectRendererCapability({ canvas, gpu, powerPreference, webgpuTimeoutMs, }?: {
+    canvas?: RendererCapabilityCanvas | null;
+    gpu?: RendererGpu | null;
+    powerPreference?: RendererPowerPreference;
+    webgpuTimeoutMs?: number;
+}): Promise<RendererCapability>;
+export declare function initializeGpuRenderer<Renderer extends InitializableRenderer>({ createRenderer, gpu, powerPreference, probeCanvas, webgpuTimeoutMs, }: {
+    createRenderer: (parameters: RendererBackendParameters) => Renderer;
+    gpu?: RendererGpu | null;
+    powerPreference?: RendererPowerPreference;
+    probeCanvas?: RendererCapabilityCanvas | null;
+    webgpuTimeoutMs?: number;
+}): Promise<RendererInitializationResult<Renderer>>;
+export {};
+//# sourceMappingURL=renderer-capability.d.ts.map

package/dist/lib/renderer-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-capability.d.ts","sourceRoot":"","sources":["../../src/lib/renderer-capability.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAA;CACzC,CAAA;AAED,oGAAoG;AACpG,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,WAAW,CAAA;AAEtE,KAAK,kBAAkB,GAAG;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC3B,aAAa,CAAC,UAAU,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9E,CAAA;AAED,KAAK,WAAW,GAAG;IACjB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;CACtF,CAAA;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC3D;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACzC;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAE9C,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,4BAA4B,CAAC,QAAQ,IAC7C;IAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACpE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAiD9C,wBAAsB,wBAAwB,CAAC,EAC7C,MAAwB,EACxB,GAAkB,EAClB,eAAe,EACf,eAAkD,GACnD,GAAE;IACD,MAAM,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAA;IACxC,GAAG,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BnC;AAED,wBAAsB,qBAAqB,CAAC,QAAQ,SAAS,qBAAqB,EAAE,EAClF,cAAc,EACd,GAAG,EACH,eAAe,EACf,WAA6B,EAC7B,eAAkD,GACnD,EAAE;IACD,cAAc,EAAE,CAAC,UAAU,EAAE,yBAAyB,KAAK,QAAQ,CAAA;IACnE,GAAG,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,WAAW,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAA;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,4BAA4B,CAAC,QAAQ,CAAC,CAAC,CAuClD"}

package/dist/lib/renderer-capability.js

@@ -0,0 +1,114 @@
+const WEBGPU_INITIALIZATION_TIMEOUT_MS = 4000;
+function browserGpu() {
+    if (typeof navigator === 'undefined')
+        return null;
+    return navigator.gpu ?? null;
+}
+function browserCanvas() {
+    if (typeof document === 'undefined')
+        return null;
+    return document.createElement('canvas');
+}
+/**
+ * Because we hand the device to `WebGPURenderer` ourselves, three treats it as
+ * caller-owned and never destroys it, and `Renderer.dispose()` is a no-op when
+ * `init()` failed. Any device we request and then abandon has to be released
+ * here or it counts against the browser's concurrent-device limit for the rest
+ * of the page's life.
+ */
+function releaseDevice(device) {
+    try {
+        ;
+        device?.destroy?.();
+    }
+    catch { }
+}
+function withTimeout(promise, timeoutMs, operation) {
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(`${operation} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timeout));
+}
+async function requestWebGpuDevice(gpu, powerPreference) {
+    const adapter = await gpu.requestAdapter({
+        featureLevel: 'compatibility',
+        ...(powerPreference ? { powerPreference } : {}),
+    });
+    if (!adapter)
+        return null;
+    const requiredFeatures = adapter.features ? Array.from(adapter.features) : undefined;
+    return adapter.requestDevice(requiredFeatures?.length ? { requiredFeatures } : undefined);
+}
+export async function detectRendererCapability({ canvas = browserCanvas(), gpu = browserGpu(), powerPreference, webgpuTimeoutMs = WEBGPU_INITIALIZATION_TIMEOUT_MS, } = {}) {
+    let capabilityError;
+    if (gpu) {
+        const pending = requestWebGpuDevice(gpu, powerPreference);
+        try {
+            const device = await withTimeout(pending, webgpuTimeoutMs, 'WebGPU adapter/device request');
+            if (device)
+                return { backend: 'webgpu', device, status: 'supported' };
+        }
+        catch (error) {
+            capabilityError = error;
+            // Losing the race means a device may still arrive after we have given up
+            // on it, so reclaim it. Attaching the handler only on this path keeps
+            // ownership of a device we did return unambiguous.
+            pending.then(releaseDevice).catch(() => { });
+        }
+    }
+    if (canvas) {
+        try {
+            const context = canvas.getContext('webgl2');
+            if (context)
+                return { backend: 'webgl', status: 'supported' };
+        }
+        catch (error) {
+            capabilityError ??= error;
+        }
+    }
+    return { error: capabilityError, status: 'unsupported' };
+}
+export async function initializeGpuRenderer({ createRenderer, gpu, powerPreference, probeCanvas = browserCanvas(), webgpuTimeoutMs = WEBGPU_INITIALIZATION_TIMEOUT_MS, }) {
+    const capability = await detectRendererCapability({
+        canvas: probeCanvas,
+        gpu,
+        powerPreference,
+        webgpuTimeoutMs,
+    });
+    if (capability.status === 'unsupported')
+        return capability;
+    let renderer;
+    try {
+        renderer = createRenderer(capability.backend === 'webgpu' ? { device: capability.device } : { forceWebGL: true });
+        const initPromise = renderer.init();
+        await (capability.backend === 'webgpu'
+            ? withTimeout(initPromise, webgpuTimeoutMs, 'WebGPU renderer initialization')
+            : initPromise);
+        return { backend: capability.backend, renderer, status: 'ready' };
+    }
+    catch (error) {
+        try {
+            renderer?.dispose?.();
+        }
+        catch { }
+        if (capability.backend !== 'webgpu')
+            return { error, status: 'unsupported' };
+        releaseDevice(capability.device);
+        renderer = undefined;
+        try {
+            renderer = createRenderer({ forceWebGL: true });
+            await renderer.init();
+            return { backend: 'webgl', renderer, status: 'ready' };
+        }
+        catch (fallbackError) {
+            try {
+                renderer?.dispose?.();
+            }
+            catch { }
+            return { error: fallbackError, status: 'unsupported' };
+        }
+    }
+}

package/dist/lib/scene-visibility.d.ts

@@ -0,0 +1,14 @@
+import type { Object3D } from 'three';
+/**
+ * Why an object is currently held off the scene layer.
+ *
+ * - `isolated` — outside the focused subtree of the viewer's isolation filter.
+ * - `shadow-only` — solo mode: out of the color passes, still casting shadows.
+ * - `batched` — a level's merged wall mesh draws this wall now.
+ */
+export type HiddenReason = 'isolated' | 'shadow-only' | 'batched';
+/** Holds `obj` off the scene layer for `reason`. Idempotent per reason. */
+export declare function hideFromScene(obj: Object3D, reason: HiddenReason): void;
+/** Drops `reason`, restoring the mask `obj` had before the first one arrived. */
+export declare function showInScene(obj: Object3D, reason: HiddenReason): void;
+//# sourceMappingURL=scene-visibility.d.ts.map

package/dist/lib/scene-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-visibility.d.ts","sourceRoot":"","sources":["../../src/lib/scene-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAGrC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAA;AAmBjE,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAMvE;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAarE"}

package/dist/lib/scene-visibility.js

@@ -0,0 +1,48 @@
+import { BATCHED_LAYER, SCENE_LAYER, SHADOW_ONLY_LAYER } from './layers';
+/**
+ * Single owner of `Object3D.layers` for every feature that hides an object.
+ *
+ * Isolation, solo's shadow-caster pass and wall batching all hide by clearing
+ * {@link SCENE_LAYER}, and they overlap freely — a wall can be sewn into a
+ * batch, then soloed, then isolated. While each stashed and restored the mask privately, the
+ * second to finish wrote back a mask the first had since changed. Recording
+ * *reasons* rather than masks makes the order irrelevant: the mask is
+ * recomputed from the one snapshot taken when the first reason arrived, and
+ * handed back only when the last one leaves.
+ */
+const HOLD = Symbol('pascal:scene-visibility:hold');
+/** Holds `obj` off the scene layer for `reason`. Idempotent per reason. */
+export function hideFromScene(obj, reason) {
+    const holder = obj;
+    const hold = holder[HOLD] ?? { original: obj.layers.mask, reasons: new Set() };
+    holder[HOLD] = hold;
+    hold.reasons.add(reason);
+    applyHold(obj, hold);
+}
+/** Drops `reason`, restoring the mask `obj` had before the first one arrived. */
+export function showInScene(obj, reason) {
+    const holder = obj;
+    const hold = holder[HOLD];
+    if (!hold)
+        return;
+    hold.reasons.delete(reason);
+    if (hold.reasons.size > 0) {
+        applyHold(obj, hold);
+        return;
+    }
+    obj.layers.mask = hold.original;
+    delete holder[HOLD];
+}
+function applyHold(obj, hold) {
+    obj.layers.mask = hold.original;
+    obj.layers.disable(SCENE_LAYER);
+    // A batched wall is both drawn and shadowed by the merged mesh, so it stays
+    // out of the shadow pass too — enabling the shadow-only bit would submit its
+    // triangles a second time, on top of the copy the batch already casts.
+    if (hold.reasons.has('batched')) {
+        obj.layers.enable(BATCHED_LAYER);
+        return;
+    }
+    if (hold.reasons.has('shadow-only'))
+        obj.layers.enable(SHADOW_ONLY_LAYER);
+}

package/dist/lib/shadow-only.d.ts

@@ -1,4 +1,20 @@
 import type { Object3D } from 'three';
+/**
+ * Shadow-caster-only hiding: removes an object (and its descendants) from the
+ * color passes while keeping it in the shadow map, so a hidden roof or level
+ * still shadows the interior and sun enters through windows correctly.
+ *
+ * Uses layer masks instead of `visible = false` for two reasons: `visible`
+ * cascades (and, critically, prunes the object from the shadow pass too),
+ * while layers are tested per-object against the rendering camera — the main
+ * camera never enables the shadow-only layer, but every shadow-casting
+ * light's shadow camera does (see `lights.tsx`).
+ *
+ * The mask itself belongs to `lib/scene-visibility.ts`, which reconciles this
+ * with the isolation filter. Both calls are idempotent and cheap to reapply —
+ * solo re-runs `applyShadowOnly` every frame so meshes rebuilt while hidden
+ * get re-hidden.
+ */
 export declare function applyShadowOnly(root: Object3D): void;
 export declare function clearShadowOnly(root: Object3D): void;
 //# sourceMappingURL=shadow-only.d.ts.map

package/dist/lib/shadow-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadow-only.d.ts","sourceRoot":"","sources":["../../src/lib/shadow-only.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAuBrC,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CASpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAOpD"}
+{"version":3,"file":"shadow-only.d.ts","sourceRoot":"","sources":["../../src/lib/shadow-only.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAGrC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAIpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAIpD"}

package/dist/lib/shadow-only.js

@@ -1,4 +1,4 @@
-import { SCENE_LAYER, SHADOW_ONLY_LAYER } from './layers';
+import { hideFromScene, showInScene } from './scene-visibility';
 /**
  * Shadow-caster-only hiding: removes an object (and its descendants) from the
  * color passes while keeping it in the shadow map, so a hidden roof or level
@@ -7,30 +7,21 @@ import { SCENE_LAYER, SHADOW_ONLY_LAYER } from './layers';
  * Uses layer masks instead of `visible = false` for two reasons: `visible`
  * cascades (and, critically, prunes the object from the shadow pass too),
  * while layers are tested per-object against the rendering camera — the main
- * camera never enables {@link SHADOW_ONLY_LAYER}, but every shadow-casting
+ * camera never enables the shadow-only layer, but every shadow-casting
  * light's shadow camera does (see `lights.tsx`).
  *
- * The original `layers.mask` is stashed under a private Symbol so
- * {@link clearShadowOnly} restores the exact prior state. Both calls are
- * idempotent and cheap to reapply.
+ * The mask itself belongs to `lib/scene-visibility.ts`, which reconciles this
+ * with the isolation filter. Both calls are idempotent and cheap to reapply —
+ * solo re-runs `applyShadowOnly` every frame so meshes rebuilt while hidden
+ * get re-hidden.
  */
-const ORIGINAL_LAYERS = Symbol('pascal:shadow-only:original-layers');
 export function applyShadowOnly(root) {
     root.traverse((obj) => {
-        const carrier = obj;
-        if (carrier[ORIGINAL_LAYERS] === undefined) {
-            carrier[ORIGINAL_LAYERS] = obj.layers.mask;
-        }
-        obj.layers.disable(SCENE_LAYER);
-        obj.layers.enable(SHADOW_ONLY_LAYER);
+        hideFromScene(obj, 'shadow-only');
     });
 }
 export function clearShadowOnly(root) {
     root.traverse((obj) => {
-        const carrier = obj;
-        if (carrier[ORIGINAL_LAYERS] === undefined)
-            return;
-        obj.layers.mask = carrier[ORIGINAL_LAYERS];
-        delete carrier[ORIGINAL_LAYERS];
+        showInScene(obj, 'shadow-only');
     });
 }

package/dist/lib/snapshot-pipeline.d.ts

@@ -3,6 +3,15 @@ import { type WebGPURenderer } from 'three/webgpu';
 import { type EdgeMode } from './edge-style';
 export declare const THUMBNAIL_WIDTH = 1920;
 export declare const THUMBNAIL_HEIGHT = 1080;
+/**
+ * Captures are re-renderable artifacts, not user originals, so they encode as
+ * webp: a 1920×1080 hero shot lands roughly an order of magnitude under PNG,
+ * which is what listings and the catalog actually ship over the wire. Alpha
+ * survives, so transparent item/preset captures keep working.
+ */
+export declare const SNAPSHOT_MIME = "image/webp";
+export declare const SNAPSHOT_QUALITY = 0.9;
+export declare const SNAPSHOT_MAX_EDGE = 2048;
 export type SnapshotCaptureMode = 'standard' | 'viewport' | 'area';
 export type SnapshotCropRegion = {
     x: number;

package/dist/lib/snapshot-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/snapshot-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAkB,KAAK,KAAK,EAAoB,MAAM,OAAO,CAAA;AAqBjF,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAGhF,OAAO,EAAE,KAAK,QAAQ,EAAqC,MAAM,cAAc,CAAA;AAK/E,eAAO,MAAM,eAAe,OAAO,CAAA;AACnC,eAAO,MAAM,gBAAgB,OAAO,CAAA;AAEpC,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;AAElE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,IAAI,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gBAAgB,EAAE,CAAC,EACjB,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,OAAO,CAAA;QACpB,KAAK,EAAE,OAAO,CAAA;QACd,KAAK,EAAE,QAAQ,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;KACf,KAAK,IAAI,CAAA;IACV,OAAO,EAAE,CAAC,EACR,WAAW,EACX,UAAU,EACV,YAAY,GACb,EAAE;QACD,WAAW,CAAC,EAAE,mBAAmB,CAAA;QACjC,UAAU,CAAC,EAAE,kBAAkB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;KAC5B,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACpC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED,wBAAsB,sBAAsB,CAAC,EAC3C,QAAQ,EACR,KAAK,EACL,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,cAAc,CAAA;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoSnC"}
+{"version":3,"file":"snapshot-pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/snapshot-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAkB,KAAK,KAAK,EAAoB,MAAM,OAAO,CAAA;AAqBjF,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAGhF,OAAO,EAAE,KAAK,QAAQ,EAAqC,MAAM,cAAc,CAAA;AAK/E,eAAO,MAAM,eAAe,OAAO,CAAA;AACnC,eAAO,MAAM,gBAAgB,OAAO,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,eAAe,CAAA;AACzC,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAUrC,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;AAElE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,IAAI,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gBAAgB,EAAE,CAAC,EACjB,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,OAAO,CAAA;QACpB,KAAK,EAAE,OAAO,CAAA;QACd,KAAK,EAAE,QAAQ,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;KACf,KAAK,IAAI,CAAA;IACV,OAAO,EAAE,CAAC,EACR,WAAW,EACX,UAAU,EACV,YAAY,GACb,EAAE;QACD,WAAW,CAAC,EAAE,mBAAmB,CAAA;QACjC,UAAU,CAAC,EAAE,kBAAkB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;KAC5B,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACpC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED,wBAAsB,sBAAsB,CAAC,EAC3C,QAAQ,EACR,KAAK,EACL,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,cAAc,CAAA;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAwSnC"}

package/dist/lib/snapshot-pipeline.js

@@ -12,6 +12,23 @@ import { getSceneTheme } from './scene-themes';
 import { packNormalToRGB, unpackRGBToNormal } from './tsl-compat';
 export const THUMBNAIL_WIDTH = 1920;
 export const THUMBNAIL_HEIGHT = 1080;
+/**
+ * Captures are re-renderable artifacts, not user originals, so they encode as
+ * webp: a 1920×1080 hero shot lands roughly an order of magnitude under PNG,
+ * which is what listings and the catalog actually ship over the wire. Alpha
+ * survives, so transparent item/preset captures keep working.
+ */
+export const SNAPSHOT_MIME = 'image/webp';
+export const SNAPSHOT_QUALITY = 0.9;
+// Retina canvases make viewport/area captures multi-MB; 2048 keeps them near the 1920 presets.
+export const SNAPSHOT_MAX_EDGE = 2048;
+function clampSnapshotSize(width, height) {
+    const maxEdge = Math.max(width, height);
+    if (maxEdge <= SNAPSHOT_MAX_EDGE)
+        return { w: width, h: height };
+    const scale = SNAPSHOT_MAX_EDGE / maxEdge;
+    return { w: Math.round(width * scale), h: Math.round(height * scale) };
+}
 export async function createSnapshotPipeline({ renderer, scene, camera, }) {
     try {
         if (renderer.init)
@@ -200,20 +217,27 @@ export async function createSnapshotPipeline({ renderer, scene, camera, }) {
                 let outH;
                 let blob;
                 if (captureMode === 'viewport') {
-                    outW = captureWidth;
-                    outH = captureHeight;
+                    ;
+                    ({ w: outW, h: outH } = clampSnapshotSize(captureWidth, captureHeight));
                     const offscreen = new OffscreenCanvas(outW, outH);
-                    offscreen.getContext('2d').drawImage(srcCanvas, 0, 0);
-                    blob = await offscreen.convertToBlob({ type: 'image/png' });
+                    const ctx = offscreen.getContext('2d');
+                    if (outW !== captureWidth || outH !== captureHeight)
+                        ctx.imageSmoothingQuality = 'high';
+                    ctx.drawImage(srcCanvas, 0, 0, captureWidth, captureHeight, 0, 0, outW, outH);
+                    blob = await offscreen.convertToBlob({ type: SNAPSHOT_MIME, quality: SNAPSHOT_QUALITY });
                 }
                 else if (captureMode === 'area' && cropRegion) {
                     const sx = Math.round(cropRegion.x * captureWidth);
                     const sy = Math.round(cropRegion.y * captureHeight);
-                    outW = Math.round(cropRegion.width * captureWidth);
-                    outH = Math.round(cropRegion.height * captureHeight);
+                    const sourceW = Math.round(cropRegion.width * captureWidth);
+                    const sourceH = Math.round(cropRegion.height * captureHeight);
+                    ({ w: outW, h: outH } = clampSnapshotSize(sourceW, sourceH));
                     const offscreen = new OffscreenCanvas(outW, outH);
-                    offscreen.getContext('2d').drawImage(srcCanvas, sx, sy, outW, outH, 0, 0, outW, outH);
-                    blob = await offscreen.convertToBlob({ type: 'image/png' });
+                    const ctx = offscreen.getContext('2d');
+                    if (outW !== sourceW || outH !== sourceH)
+                        ctx.imageSmoothingQuality = 'high';
+                    ctx.drawImage(srcCanvas, sx, sy, sourceW, sourceH, 0, 0, outW, outH);
+                    blob = await offscreen.convertToBlob({ type: SNAPSHOT_MIME, quality: SNAPSHOT_QUALITY });
                 }
                 else {
                     // Standard: center-crop to the requested aspect (default 1920×1080)
@@ -237,7 +261,7 @@ export async function createSnapshotPipeline({ renderer, scene, camera, }) {
                     offscreen
                         .getContext('2d')
                         .drawImage(srcCanvas, sx, sy, sWidth, sHeight, 0, 0, outW, outH);
-                    blob = await offscreen.convertToBlob({ type: 'image/png' });
+                    blob = await offscreen.convertToBlob({ type: SNAPSHOT_MIME, quality: SNAPSHOT_QUALITY });
                 }
                 return { blob, outW, outH };
             },