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

package/dist/index.js

@@ -17,9 +17,13 @@ export { buildGlbReferenceNodes, buildGlbReplaceNodes, } from './components/view
 export { GlbScene, } from './components/viewer/glb-scene';
 export { CROUCH_CAPSULE, CROUCH_EYE_OFFSET, CROUCH_FLOAT_HEIGHT, CROUCH_RUN_SPEED, CROUCH_WALK_SPEED, EYE_LERP_SPEED, GlbWalkthroughController, STAND_CAPSULE, STAND_CLEARANCE, STAND_FLOAT_HEIGHT, WALKTHROUGH_FOV, } from './components/viewer/glb-walkthrough-controller';
 export { DEFAULT_HOVER_STYLES, SSGI_PARAMS, } from './components/viewer/post-processing';
+export { SceneAtmosphere, useSceneAtmosphere, } from './components/viewer/scene-atmosphere';
 export { SceneEnvironment } from './components/viewer/scene-environment';
+export { SceneGroundReplacement, useSceneGroundReplacement, } from './components/viewer/scene-ground-replacement';
+export { isViewerPresentationTextureBorrowed, markViewerPresentationTextureBorrowed, registerViewerPresentation, ViewerPresentations, viewerPresentationRegistry, } from './components/viewer/viewer-presentations';
 export { useAssetUrl } from './hooks/use-asset-url';
 export { useGLTFKTX2 } from './hooks/use-gltf-ktx2';
+export { useLibraryMaterialsVersion } from './hooks/use-library-materials-version';
 export { useNodeEvents } from './hooks/use-node-events';
 export { ASSETS_CDN_URL, resolveAssetUrl, resolveCdnUrl } from './lib/asset-url';
 export { backdropGradient, deepSkyColor, horizonHazeColor } from './lib/backdrop';
@@ -29,16 +33,21 @@ export { applyWorldScaleBoxUVs } from './lib/box-uv';
 // because three-bvh-csg / three-mesh-bvh are viewer-only deps.
 export { ADDITION, Brush, computeGeometryBoundsTree, csgEvaluator, csgGeometry, csgMaterials, INTERSECTION, prepareBrushForCSG, SUBTRACTION, } from './lib/csg-utils';
 export { disposeObject3DResources } from './lib/dispose-object3d';
+export { PERF_OVERLAY_ENABLED } from './lib/gpu-perf';
 export { computeHeroFraming, DEFAULT_FRAMING_EXCLUDED_TYPES, heroCameraPose, temporarilyHideNodeTypes, unionRegisteredNodeBounds, } from './lib/hero-pose';
-export { applyIsolation, clearIsolation, collectIsolationSubtree, isIsolationActive, } from './lib/isolation';
+export { applyIsolation, clearIsolation, collectIsolationSubtree, isIsolationActive, refreshIsolation, } from './lib/isolation';
 export { configureKtx2Support, ensureKtx2Support } from './lib/ktx2-loader';
-export { BATCHED_LAYER, GRID_LAYER, OVERLAY_LAYER, SCENE_LAYER, setSurfaceRaycastLayers, ZONE_LAYER, } from './lib/layers';
-export { applyMaterialPresetToMaterials, BLUEPRINT_PALETTE, baseMaterial, CLAY_PALETTE, clearMaterialCache, createDefaultMaterial, createMaterial, createMaterialFromPresetRef, createSurfaceRoleMaterial, DEFAULT_CEILING_MATERIAL, DEFAULT_DOOR_MATERIAL, DEFAULT_ROOF_MATERIAL, DEFAULT_SHELF_MATERIAL, DEFAULT_SLAB_MATERIAL, DEFAULT_STAIR_MATERIAL, DEFAULT_WALL_MATERIAL, DEFAULT_WINDOW_MATERIAL, disposeMaterial, glassMaterial, MONO_PALETTE, PRESET_PALETTES, resolveMaterialRef, resolveSlotDefaultMaterial, resolveSurfaceColor, WHITE_PALETTE, } from './lib/materials';
+export { LayerPassIndex } from './lib/layer-pass';
+export { BATCHED_LAYER, GRID_LAYER, OVERLAY_LAYER, SCENE_LAYER, SHADOW_ONLY_LAYER, setSurfaceRaycastLayers, ZONE_LAYER, } from './lib/layers';
+export { applyMaterialPresetToMaterials, BLUEPRINT_PALETTE, baseMaterial, CLAY_PALETTE, clearMaterialCache, createDefaultMaterial, createMaterial, createMaterialFromPresetRef, createSurfaceRoleMaterial, DEFAULT_CEILING_MATERIAL, DEFAULT_DOOR_MATERIAL, DEFAULT_ROOF_MATERIAL, DEFAULT_SHELF_MATERIAL, DEFAULT_SLAB_MATERIAL, DEFAULT_STAIR_MATERIAL, DEFAULT_WALL_MATERIAL, DEFAULT_WINDOW_MATERIAL, disposeMaterial, glassMaterial, MONO_PALETTE, PRESET_PALETTES, registerMaterialCacheCleanup, resolveMaterialRef, resolveSlotDefaultMaterial, resolveSurfaceColor, WHITE_PALETTE, } from './lib/materials';
 export { mergedOutline } from './lib/merged-outline-node';
-export { unionPolygons } from './lib/polygon-union';
+export * from './lib/perf-actions';
+export { publishPerfBatchStats } from './lib/perf-panel-store';
+export * from './lib/perf-tracks';
+export { markPureRaycast } from './lib/pointer-events';
 export { detectRendererCapability, initializeGpuRenderer, } from './lib/renderer-capability';
 export { getSceneTheme, SCENE_THEME_IDS, SCENE_THEMES, } from './lib/scene-themes';
-export { hideFromScene, showInScene } from './lib/scene-visibility';
+export { hideFromScene, showInScene, temporarilyShowShadowOnly, } from './lib/scene-visibility';
 export { createSnapshotPipeline, SNAPSHOT_MAX_EDGE, SNAPSHOT_MIME, SNAPSHOT_QUALITY, THUMBNAIL_HEIGHT, THUMBNAIL_WIDTH, } from './lib/snapshot-pipeline';
 export { buildTerrainPerimeterFillGeometry, } from './lib/terrain-perimeter-fill';
 export { getPascalTextureRef, stampPascalTextureRef, textureMapForSlot, } from './lib/texture-reference';
@@ -67,7 +76,7 @@ export { InteractiveSystem } from './systems/interactive/interactive-system';
 export { ItemSystem } from './systems/item/item-system';
 export { ItemLightSystem } from './systems/item-light/item-light-system';
 export { LevelSystem } from './systems/level/level-system';
-export { snapLevelsToTruePositions } from './systems/level/level-utils';
+export { EXPLODED_GAP, getLevelPresentationY, snapLevelsToTruePositions, } from './systems/level/level-utils';
 export { getRoofMaterialArray } from './systems/roof/roof-materials';
 // Generic roof-segment primitives. Kinds that compose CSG against
 // the roof shell (chimney's self-trim, dormer's virtual-segment cut)
@@ -90,7 +99,7 @@ export { getVisibleWallMaterials } from './systems/wall/wall-materials';
 // definition can compose them into `def.system` without duplicating the
 // 800+ lines of CSG / mitering logic during Phase 3. These exports are
 // removed in Phase 6 when the legacy mount points are deleted.
-export { drainRebuiltWalls, getPendingWallRebuildCount, WallSystem, } from './systems/wall/wall-system';
+export { drainRebuiltWalls, getPendingWallRebuildCount, isWallInitialBuildActive, WallSystem, } from './systems/wall/wall-system';
 export { poseWindowMovingParts, WindowAnimationSystem, } from './systems/window/window-animation-system';
 export { buildWindowPreviewMesh, WindowSystem } from './systems/window/window-system';
 export { ZoneSystem } from './systems/zone/zone-system';

package/dist/lib/csg-utils.d.ts

@@ -6,5 +6,6 @@ export declare function csgMaterials(brush: Brush): THREE.Material[];
 export declare const csgEvaluator: Evaluator;
 export declare function computeGeometryBoundsTree(geometry: THREE.BufferGeometry): void;
 export declare function prepareBrushForCSG(brush: Brush): void;
+export declare function subtractCsgBrush(left: Brush, right: Brush, evaluator: Evaluator): Brush;
 export { ADDITION, Brush, INTERSECTION, SUBTRACTION } from 'three-bvh-csg';
 //# sourceMappingURL=csg-utils.d.ts.map

package/dist/lib/csg-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csg-utils.d.ts","sourceRoot":"","sources":["../../src/lib/csg-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,KAAK,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AA4CrD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,KAAK,CAAC,cAAc,GAC7B,KAAK,CAAC,cAAc,CAoCtB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,cAAc,CAE9D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAG3D;AAED,eAAO,MAAM,YAAY,WAAkB,CAAA;AAK3C,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,QAMvE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,QAI9C;AAID,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"csg-utils.d.ts","sourceRoot":"","sources":["../../src/lib/csg-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,KAAK,KAAK,EAAE,SAAS,EAAe,MAAM,eAAe,CAAA;AA4ClE,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,KAAK,CAAC,cAAc,GAC7B,KAAK,CAAC,cAAc,CAoCtB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,cAAc,CAE9D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAG3D;AAED,eAAO,MAAM,YAAY,WAAkB,CAAA;AAK3C,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,QAMvE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,QAI9C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK,CAIvF;AAID,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/lib/csg-utils.js

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { Evaluator } from 'three-bvh-csg';
+import { Evaluator, SUBTRACTION } from 'three-bvh-csg';
 import { computeBoundsTree } from 'three-mesh-bvh';
 /**
  * Shared CSG primitives used by kinds whose geometry subtracts pieces
@@ -88,6 +88,11 @@ export function prepareBrushForCSG(brush) {
     computeGeometryBoundsTree(brush.geometry);
     brush.updateMatrixWorld();
 }
+export function subtractCsgBrush(left, right, evaluator) {
+    const result = evaluator.evaluate(left, right, SUBTRACTION);
+    prepareBrushForCSG(result);
+    return result;
+}
 // Re-export Brush + SUBTRACTION + ADDITION + INTERSECTION so kinds don't need a
 // direct `three-bvh-csg` dependency.
 export { ADDITION, Brush, INTERSECTION, SUBTRACTION } from 'three-bvh-csg';

package/dist/lib/gpu-perf.d.ts

@@ -1,4 +1,2 @@
 export declare const PERF_OVERLAY_ENABLED: boolean;
-export declare function pushGpuSample(ms: number): void;
-export declare function drainGpuSamples(): number[];
 //# sourceMappingURL=gpu-perf.d.ts.map

package/dist/lib/gpu-perf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpu-perf.d.ts","sourceRoot":"","sources":["../../src/lib/gpu-perf.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,oBAAoB,SACyD,CAAA;AAK1F,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG9C;AAED,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAK1C"}
+{"version":3,"file":"gpu-perf.d.ts","sourceRoot":"","sources":["../../src/lib/gpu-perf.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,oBAAoB,SACyD,CAAA"}

package/dist/lib/gpu-perf.js

@@ -1,23 +1,9 @@
-// GPU work-time measurement, gated by `?perf` in the URL.
+// `?perf` gate. Kept in its own module because both the overlay and
+// `lib/perf-tracks.ts` (the instrumentation sink every system writes to) read
+// it, and perf-tracks must not import a React component tree.
 //
-// We can't use WebGPU timestamp queries here because the editor renders via
-// a custom `RenderPipeline.render()` path that bypasses three.js's built-in
-// timestamp infrastructure. Instead we use `device.queue.onSubmittedWorkDone()`,
-// which resolves when the GPU finishes all submitted work — measuring the
-// CPU→GPU-done delta gives a clean approximation of per-frame GPU duration
-// regardless of which render path produced it.
+// Timing itself lives in perf-tracks: `gpu-render` carries three's WebGPU
+// timestamp-query total for the frame's render passes, `gpu-queue` the
+// submit→onSubmittedWorkDone fence, `render-encode` the synchronous CPU cost of
+// building and submitting the frame. See components/viewer/post-processing.tsx.
 export const PERF_OVERLAY_ENABLED = typeof window !== 'undefined' && new URLSearchParams(window.location.search).has('perf');
-const MAX_SAMPLES = 256;
-const samples = [];
-export function pushGpuSample(ms) {
-    samples.push(ms);
-    if (samples.length > MAX_SAMPLES)
-        samples.shift();
-}
-export function drainGpuSamples() {
-    if (samples.length === 0)
-        return [];
-    const out = samples.slice();
-    samples.length = 0;
-    return out;
-}

package/dist/lib/isolation.d.ts

@@ -1,39 +1,23 @@
 import type { AnyNodeId } from '@pascal-app/core';
 import type { Object3D } from 'three';
-/** True while an isolation filter is applied (see {@link applyIsolation}). */
+/** True while a subtree is isolated, including before its lazy meshes mount. */
 export declare function isIsolationActive(): boolean;
-/**
- * Compute the union of every isolated subtree's `Object3D` descendants.
- *
- * Pure traversal — exported so future "focus mode" / debug tooling can
- * reuse the same definition of "what's in the isolated set". Each root
- * is walked via `Object3D.traverse` (the live Three.js graph, not the
- * data-model `children` array — those can disagree when systems mount
- * synthesized sub-meshes that the data model doesn't track).
- */
+/** Include synthesized meshes below a selected native root, including hosted openings. */
 export declare function collectIsolationSubtree(ids: ReadonlyArray<string>): Set<Object3D>;
 /**
- * Imperative visibility filter on the live `sceneRegistry`. Hides every
- * registered group (and its synthesized child meshes) outside the
- * 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 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 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}).
+ * Select native subtrees without mutating the saved scene or cascading visibility
+ * through their hosts. The next draw also filters unregistered presentation geometry.
  */
 export declare function applyIsolation(ids: ReadonlyArray<AnyNodeId> | null): void;
+/**
+ * Reconcile immediately before viewport or snapshot rendering. Environment, sky,
+ * ground and instance batches can live outside sceneRegistry or mount asynchronously.
+ * Lights/cameras remain usable; masks do not cascade, so an isolated door can still
+ * render under its hidden wall. Collective renderers fall back to native geometry.
+ * The returned cleanup restores fog after the synchronous draw, before atmosphere
+ * owners can change it again. Do not hold this cleanup across async GPU readback.
+ */
+export declare function refreshIsolation(scene?: Object3D): () => void;
+/** Restore even detached/unregistered meshes, without undoing solo or batching holds. */
 export declare function clearIsolation(): void;
 //# sourceMappingURL=isolation.d.ts.map

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;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"}
+{"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,EAAS,MAAM,OAAO,CAAA;AAQ5C,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CASjF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,IAAI,CAOzE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,IAAI,CA6B7D;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,IAAI,CAKrC"}

package/dist/lib/isolation.js

@@ -1,91 +1,87 @@
 'use client';
 import { sceneRegistry } from '@pascal-app/core';
 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;
-/** True while an isolation filter is applied (see {@link applyIsolation}). */
+let isolatedIds = null;
+let heldObjects = new Set();
+let liveScene;
+const noop = () => { };
+/** True while a subtree is isolated, including before its lazy meshes mount. */
 export function isIsolationActive() {
-    return isolationActive;
+    return isolatedIds !== null;
 }
-/**
- * Compute the union of every isolated subtree's `Object3D` descendants.
- *
- * Pure traversal — exported so future "focus mode" / debug tooling can
- * reuse the same definition of "what's in the isolated set". Each root
- * is walked via `Object3D.traverse` (the live Three.js graph, not the
- * data-model `children` array — those can disagree when systems mount
- * synthesized sub-meshes that the data model doesn't track).
- */
+/** Include synthesized meshes below a selected native root, including hosted openings. */
 export function collectIsolationSubtree(ids) {
     const keep = new Set();
     for (const id of ids) {
         const root = sceneRegistry.nodes.get(id);
-        if (!root)
-            continue;
-        root.traverse((child) => {
+        root?.traverse((child) => {
             keep.add(child);
         });
     }
     return keep;
 }
 /**
- * Imperative visibility filter on the live `sceneRegistry`. Hides every
- * registered group (and its synthesized child meshes) outside the
- * 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 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 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}).
+ * Select native subtrees without mutating the saved scene or cascading visibility
+ * through their hosts. The next draw also filters unregistered presentation geometry.
  */
 export function applyIsolation(ids) {
     if (ids == null || ids.length === 0) {
         clearIsolation();
         return;
     }
-    const keep = collectIsolationSubtree(ids);
-    // Iterate registered roots. For each one outside the keep set,
-    // 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;
-        hideRecursive(obj, keep);
-    }
-    isolationActive = true;
+    isolatedIds = [...ids];
+    refreshIsolation();
 }
-function hideRecursive(obj, keep) {
-    if (keep.has(obj))
-        return;
-    hideFromScene(obj, 'isolated');
-    for (const child of obj.children) {
-        hideRecursive(child, keep);
-    }
+/**
+ * Reconcile immediately before viewport or snapshot rendering. Environment, sky,
+ * ground and instance batches can live outside sceneRegistry or mount asynchronously.
+ * Lights/cameras remain usable; masks do not cascade, so an isolated door can still
+ * render under its hidden wall. Collective renderers fall back to native geometry.
+ * The returned cleanup restores fog after the synchronous draw, before atmosphere
+ * owners can change it again. Do not hold this cleanup across async GPU readback.
+ */
+export function refreshIsolation(scene) {
+    if (!isolatedIds)
+        return noop;
+    if (scene)
+        liveScene = scene;
+    const keep = collectIsolationSubtree(isolatedIds);
+    const visited = new Set();
+    const hidden = new Set();
+    const visit = (object) => {
+        if (visited.has(object))
+            return;
+        visited.add(object);
+        const flags = object;
+        if (keep.has(object) || flags.isLight || flags.isCamera)
+            return;
+        hideFromScene(object, 'isolated');
+        hidden.add(object);
+    };
+    liveScene?.traverse(visit);
+    // Also covers not-yet-attached registered roots and imperative callers without a scene.
+    for (const object of sceneRegistry.nodes.values())
+        object.traverse(visit);
+    for (const object of heldObjects)
+        if (!hidden.has(object))
+            showInScene(object, 'isolated');
+    heldObjects = hidden;
+    const atmosphere = scene;
+    if (!atmosphere?.isScene)
+        return noop;
+    const { fog, fogNode } = atmosphere;
+    atmosphere.fog = null;
+    atmosphere.fogNode = null;
+    return () => {
+        atmosphere.fog = fog;
+        atmosphere.fogNode = fogNode;
+    };
 }
+/** Restore even detached/unregistered meshes, without undoing solo or batching holds. */
 export function clearIsolation() {
-    // We don't know which objects were touched without re-walking, so
-    // 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) => {
-            showInScene(child, 'isolated');
-        });
-    }
-    isolationActive = false;
+    for (const object of heldObjects)
+        showInScene(object, 'isolated');
+    heldObjects.clear();
+    isolatedIds = null;
+    liveScene = undefined;
 }

package/dist/lib/layer-pass.d.ts

@@ -0,0 +1,28 @@
+import { type Camera, Object3D, type Scene } from 'three';
+import { type NodeFrame, PassNode } from 'three/webgpu';
+export declare class LayerPassIndex {
+    readonly source: Scene;
+    private readonly members;
+    private readonly cleanups;
+    constructor(source: Scene, layers: number[]);
+    register(subtree: Object3D): void;
+    private attach;
+    private detach;
+    prepare(layer: number, roots: Object3D[]): {
+        drawable: boolean;
+        shadowLight: boolean;
+    };
+    dispose(): void;
+}
+export declare class LayerPassNode extends PassNode {
+    private readonly index;
+    private readonly layer;
+    private readonly mainPass;
+    private readonly roots;
+    private readonly size;
+    private needsClear;
+    constructor(index: LayerPassIndex, camera: Camera, layer: number, mainPass: PassNode);
+    dispose(): void;
+    updateBefore(frame: NodeFrame): undefined;
+}
+//# sourceMappingURL=layer-pass.d.ts.map

package/dist/lib/layer-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-pass.d.ts","sourceRoot":"","sources":["../../src/lib/layer-pass.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,MAAM,EAAiB,QAAQ,EAAE,KAAK,KAAK,EAAW,MAAM,OAAO,CAAA;AACjF,OAAO,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAoBvD,qBAAa,cAAc;IAKvB,QAAQ,CAAC,MAAM,EAAE,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAGhD,MAAM,EAAE,KAAK,EACtB,MAAM,EAAE,MAAM,EAAE;IAWlB,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAU1B,OAAO,CAAC,MAAM,CA2Cb;IAED,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE;;;;IAoCxC,OAAO;CAIR;AAiBD,qBAAa,aAAc,SAAQ,QAAQ;IAMvC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAO;gBAGN,KAAK,EAAE,cAAc,EACtC,MAAM,EAAE,MAAM,EACG,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ;IAc5B,OAAO;IAKP,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS;CAgEnD"}

package/dist/lib/layer-pass.js

@@ -0,0 +1,254 @@
+// Only one index may observe a scene, and observed objects must own their Layers.
+// Insertions without childadded are not observed: call register(subtree) afterward.
+// Replaced Layers are repaired for known members during prepare(); other objects
+// need register(object), since discovering them would require a full-scene scan.
+import { Object3D, Vector2 } from 'three';
+import { PassNode } from 'three/webgpu';
+const maskObserver = Symbol('LayerPassIndex.maskObserver');
+function maskOwner(object) {
+    const get = Object.getOwnPropertyDescriptor(object.layers, 'mask')?.get;
+    return get?.[maskObserver];
+}
+// Observe mask writes as well as child events: R3F's numeric `layers` prop calls
+// Layers.set(), while imperative producers also use enable() and direct masks.
+// Nothing on Object3D/Layers.prototype is patched, and detach restores the field.
+export class LayerPassIndex {
+    source;
+    members = new Map();
+    cleanups = new Map();
+    constructor(source, layers) {
+        this.source = source;
+        for (const layer of layers)
+            this.members.set(1 << layer, new Set());
+        try {
+            this.attach(source);
+        }
+        catch (error) {
+            this.dispose();
+            throw error;
+        }
+    }
+    register(subtree) {
+        this.detach(subtree);
+        for (let object = subtree; object; object = object.parent) {
+            if (object === this.source) {
+                this.attach(subtree);
+                return;
+            }
+        }
+    }
+    attach = (object) => {
+        if (this.cleanups.has(object))
+            return;
+        const layers = object.layers;
+        if (maskOwner(object)) {
+            throw new Error('LayerPassIndex requires one index per scene and unshared Layers');
+        }
+        let mask = layers.mask;
+        const sync = () => {
+            for (const [bit, members] of this.members) {
+                if ((mask & bit) !== 0 && object !== this.source)
+                    members.add(object);
+                else
+                    members.delete(object);
+            }
+        };
+        const getMask = Object.assign(() => mask, { [maskObserver]: object });
+        Object.defineProperty(layers, 'mask', {
+            configurable: true,
+            enumerable: true,
+            get: getMask,
+            set: (value) => {
+                if (mask === value)
+                    return;
+                mask = value;
+                sync();
+            },
+        });
+        const added = ({ child }) => this.attach(child);
+        const removed = ({ child }) => this.detach(child);
+        object.addEventListener('childadded', added);
+        object.addEventListener('childremoved', removed);
+        this.cleanups.set(object, () => {
+            object.removeEventListener('childadded', added);
+            object.removeEventListener('childremoved', removed);
+            if (Object.getOwnPropertyDescriptor(layers, 'mask')?.get === getMask) {
+                Object.defineProperty(layers, 'mask', {
+                    configurable: true,
+                    enumerable: true,
+                    writable: true,
+                    value: mask,
+                });
+            }
+            for (const members of this.members.values())
+                members.delete(object);
+        });
+        sync();
+        for (const child of object.children)
+            this.attach(child);
+    };
+    detach(object) {
+        for (const child of object.children)
+            this.detach(child);
+        this.cleanups.get(object)?.();
+        this.cleanups.delete(object);
+    }
+    prepare(layer, roots) {
+        roots.length = 0;
+        const members = this.members.get(1 << layer);
+        // Repairs can change membership, so finish them before choosing nested roots.
+        for (const tracked of this.members.values()) {
+            for (const object of [...tracked]) {
+                let root = object;
+                while (root.parent && root !== this.source)
+                    root = root.parent;
+                if (root !== this.source)
+                    this.detach(root);
+                else if (maskOwner(object) !== object)
+                    this.register(object);
+            }
+        }
+        let drawable = false;
+        let shadowLight = false;
+        for (const object of members) {
+            let visible = object.visible;
+            let nested = false;
+            for (let parent = object.parent; parent; parent = parent.parent) {
+                if (!parent.visible)
+                    visible = false;
+                if (members.has(parent))
+                    nested = true;
+            }
+            if (!visible)
+                continue;
+            const { material, isLight, castShadow } = object;
+            if (material) {
+                drawable ||= Array.isArray(material) ? material.some((m) => m.visible) : material.visible;
+            }
+            shadowLight ||= isLight === true && castShadow;
+            if (!nested)
+                roots.push(object);
+        }
+        // Keep source traversal order even when a producer switches layers after
+        // mounting. Ancestors on this layer remain intact, retaining group order,
+        // clipping and LOD behavior; layers do not inherit through other ancestors.
+        roots.sort(compareSceneOrder);
+        return { drawable, shadowLight };
+    }
+    dispose() {
+        for (const cleanup of this.cleanups.values())
+            cleanup();
+        this.cleanups.clear();
+    }
+}
+function compareSceneOrder(a, b) {
+    const pathA = [];
+    const pathB = [];
+    for (let object = a; object; object = object.parent)
+        pathA.push(object);
+    for (let object = b; object; object = object.parent)
+        pathB.push(object);
+    let i = pathA.length - 1;
+    let j = pathB.length - 1;
+    while (i >= 0 && j >= 0 && pathA[i] === pathB[j]) {
+        i--;
+        j--;
+    }
+    const siblings = pathA[i + 1].children;
+    return siblings.indexOf(pathA[i]) - siblings.indexOf(pathB[j]);
+}
+export class LayerPassNode extends PassNode {
+    index;
+    layer;
+    mainPass;
+    roots = [];
+    size = new Vector2();
+    needsClear = true;
+    constructor(index, camera, layer, mainPass) {
+        super(PassNode.COLOR, index.source, camera);
+        this.index = index;
+        this.layer = layer;
+        this.mainPass = mainPass;
+        // A scene view, not cloned meshes: callbacks, environment, fog, materials,
+        // skeletons and world matrices retain their original owners and values.
+        this.scene = new Proxy(index.source, {
+            get: (source, key) => {
+                if (key === 'children')
+                    return this.roots;
+                if (key === 'matrixWorldAutoUpdate')
+                    return false;
+                return Reflect.get(source, key, source);
+            },
+        });
+    }
+    dispose() {
+        this.roots.length = 0;
+        super.dispose();
+    }
+    updateBefore(frame) {
+        // NodeFrame deduplicates FRAME updates. Make the dependency explicit rather
+        // than relying on which composite expression the TSL builder visits first.
+        frame.updateBeforeNode(this.mainPass);
+        const { drawable, shadowLight } = this.index.prepare(this.layer, this.roots);
+        const renderer = frame.renderer;
+        const source = this.index.source;
+        const hasBackground = source.background !== null || ('backgroundNode' in source && source.backgroundNode != null);
+        const hasSceneCallbacks = source.onBeforeRender !== Object3D.prototype.onBeforeRender ||
+            source.onAfterRender !== Object3D.prototype.onAfterRender;
+        if (drawable || hasBackground || hasSceneCallbacks) {
+            this.needsClear = true;
+            // Shadows need all source casters; custom callbacks need the original
+            // scene receiver and graph, including when they enable an empty layer.
+            const root = this.scene;
+            if (shadowLight || hasSceneCallbacks)
+                this.scene = source;
+            try {
+                if (this.scene !== source) {
+                    const updatedAncestors = new Set();
+                    const updateAncestor = (object) => {
+                        if (!object || updatedAncestors.has(object))
+                            return;
+                        updateAncestor(object.parent);
+                        // Force world refreshes even when a manual local matrix is clean.
+                        object.matrixWorldNeedsUpdate = true;
+                        object.updateWorldMatrix(false, false);
+                        updatedAncestors.add(object);
+                    };
+                    for (const root of this.roots) {
+                        updateAncestor(root.parent);
+                        root.updateMatrixWorld(true);
+                    }
+                }
+                super.updateBefore(frame);
+            }
+            finally {
+                this.scene = root;
+            }
+            return;
+        }
+        const outputTarget = renderer.getOutputRenderTarget();
+        if (outputTarget && 'isXRRenderTarget' in outputTarget && outputTarget.isXRRenderTarget)
+            this.size.set(outputTarget.width, outputTarget.height);
+        else
+            renderer.getDrawingBufferSize(this.size);
+        const width = this.renderTarget.width;
+        const height = this.renderTarget.height;
+        this.setSize(this.size.x, this.size.y);
+        if (width !== this.renderTarget.width || height !== this.renderTarget.height)
+            this.needsClear = true;
+        if (!this.needsClear)
+            return;
+        const target = renderer.getRenderTarget();
+        const mrt = renderer.getMRT();
+        try {
+            renderer.setRenderTarget(this.renderTarget);
+            renderer.setMRT(null);
+            renderer.clear(true, true, true);
+            this.needsClear = false;
+        }
+        finally {
+            renderer.setRenderTarget(target);
+            renderer.setMRT(mrt);
+        }
+    }
+}