@pascal-app/viewer 1.0.3 → 1.0.5

package/dist/lib/materials.js

@@ -1,4 +1,4 @@
-import { getMaterialPresetByRef, parseMaterialRef, resolveMaterial, } from '@pascal-app/core';
+import { getMaterialPresetByRef, materialColorPaint, parseMaterialColor, parseMaterialRef, resolveMaterial, } from '@pascal-app/core';
 import { addAfterEffect, invalidate } from '@react-three/fiber';
 import * as THREE from 'three';
 import { float, mix, positionViewDirection, transformedNormalView } from 'three/tsl';
@@ -82,12 +82,35 @@ const defaultMaterialCache = new Map();
 const surfaceRoleMaterialCache = new Map();
 const textureCache = new Map();
 const textureLoadPromises = new Map();
+const pendingTextures = new Set();
+const failedTextures = new Set();
 const textureLoader = new THREE.TextureLoader();
 let materialTextureVersion = 0;
 // Highlight clones can observe late assignments without polling every material.
 export function getMaterialTextureVersion() {
     return materialTextureVersion;
 }
+/** Conservative capture readiness across the current material cache. */
+export function materialTextureLoadState() {
+    return { pending: pendingTextures.size + textureLoadPromises.size, failed: failedTextures.size };
+}
+function loadTexture(url, key) {
+    pendingTextures.add(key);
+    try {
+        return pickTextureLoader(url).load(url, () => {
+            pendingTextures.delete(key);
+            failedTextures.delete(key);
+        }, undefined, () => {
+            pendingTextures.delete(key);
+            failedTextures.add(key);
+        });
+    }
+    catch (error) {
+        pendingTextures.delete(key);
+        failedTextures.add(key);
+        throw error;
+    }
+}
 // `.ktx2` finish maps transcode through the shared KTX2 loader (support is
 // detected once at viewer init); everything else loads as a normal image.
 function pickTextureLoader(url) {
@@ -157,7 +180,7 @@ function getTexture(material) {
     const resolvedUrl = /^(?:asset|blob|data):/.test(textureConfig.url)
         ? textureConfig.url
         : (resolveCdnUrl(textureConfig.url) ?? textureConfig.url);
-    const texture = pickTextureLoader(resolvedUrl).load(resolvedUrl);
+    const texture = loadTexture(resolvedUrl, cacheKey);
     texture.wrapS = THREE.RepeatWrapping;
     texture.wrapT = THREE.RepeatWrapping;
     const [repeatX, repeatY] = resolveTextureRepeat(textureConfig.repeat, textureConfig.scale);
@@ -207,7 +230,7 @@ function getPresetTexture(path, props, slot) {
     const cached = textureCache.get(cacheKey);
     if (cached)
         return cached;
-    const texture = pickTextureLoader(resolvedPath).load(resolvedPath);
+    const texture = loadTexture(resolvedPath, cacheKey);
     applyTextureProperties(texture, props, slot);
     stampPascalTextureRef(texture, {
         kind: 'material',
@@ -263,11 +286,13 @@ async function loadPresetTexture(path, props, slot) {
         setTextureCacheKey(texture, cacheKey);
         textureCache.set(cacheKey, texture);
         textureLoadPromises.delete(cacheKey);
+        failedTextures.delete(cacheKey);
         return texture;
     })
         .catch((error) => {
         console.warn('[viewer] Failed to load material texture', resolvedPath, error);
         textureLoadPromises.delete(cacheKey);
+        failedTextures.add(cacheKey);
         return null;
     });
     textureLoadPromises.set(cacheKey, promise);
@@ -346,6 +371,12 @@ function applyMaterialMapProperties(material, mapProperties) {
 // Glass-like transparency threshold: any standard material authored as
 // `transparent` with opacity below this gets the fresnel treatment.
 const GLASS_OPACITY_THRESHOLD = 0.6;
+/** Glass lets light through; shadow maps would otherwise treat it as a solid panel. */
+export function materialCastsShadow(material) {
+    const materials = Array.isArray(material) ? material : [material];
+    return !materials.some((entry) => entry.transmission > 0 ||
+        (entry.transparent && entry.opacity < GLASS_OPACITY_THRESHOLD));
+}
 /**
  * Fresnel-driven opacity for glass: nearly the authored opacity head-on,
  * increasingly opaque (showing the environment reflection) at grazing angles.
@@ -413,7 +444,8 @@ export function createMaterialFromPresetRef(materialPreset, shading = 'rendered'
 }
 export function createMaterial(material, shading = 'rendered') {
     const props = resolveMaterial(material);
-    const cacheKey = `${getCacheKey(props, shading)}-${getTextureKey(material)}`;
+    const glassPreset = material?.preset === 'glass';
+    const cacheKey = `${getCacheKey(props, shading)}-${getTextureKey(material)}-${glassPreset}`;
     if (materialCache.has(cacheKey)) {
         return materialCache.get(cacheKey);
     }
@@ -433,7 +465,9 @@ export function createMaterial(material, shading = 'rendered') {
             roughness: props.roughness,
             metalness: props.metalness,
         });
-    maybeApplyGlassFresnel(threeMaterial);
+    // Explicit source transparency keeps its opacity; the glass preset owns this styling.
+    if (glassPreset)
+        maybeApplyGlassFresnel(threeMaterial);
     threeMaterial.userData.__pascalCachedMaterial = true;
     materialCache.set(cacheKey, threeMaterial);
     return threeMaterial;
@@ -446,14 +480,19 @@ export function createMaterial(material, shading = 'rendered') {
  * the dangling-ref fallback for the whole session.
  */
 export function materialPresetRefSignature(ref) {
-    return getMaterialPresetByRef(ref) ? ref : `${ref}#unresolved`;
+    return getMaterialPresetByRef(ref) || parseMaterialColor(ref) ? ref : `${ref}#unresolved`;
 }
 /**
- * Resolve a MaterialRef ('library:<id>' | 'scene:<id>') to a three.js material.
- * Returns null for an unknown / dangling ref so callers fall back to the
- * slot's default (authored material, then themed default). Never throws.
+ * Resolve a MaterialRef ('library:<id>' | 'scene:<id>') or a plain '#rrggbb'
+ * colour to a three.js material; the colour paints like
+ * `material: { properties: { color } }`. Returns null for an unknown / dangling
+ * ref so callers fall back to the slot's default (authored material, then
+ * themed default). Never throws.
  */
 export function resolveMaterialRef(ref, sceneMaterials, shading = 'rendered') {
+    const color = parseMaterialColor(ref);
+    if (color)
+        return createMaterial(materialColorPaint(color), shading);
     const parsed = parseMaterialRef(ref);
     if (!parsed)
         return null;
@@ -470,7 +509,22 @@ export function resolveMaterialRef(ref, sceneMaterials, shading = 'rendered') {
  * procedural kinds whose colored-mode unpainted appearance comes from a
  * declarative default (slab, wall).
  */
+let slotDefaultOverrides = null;
+/**
+ * Swaps declared slot DEFAULTS (never painted refs) for another finish, e.g.
+ * the worker thumbnail renders unpainted walls as plaster instead of the
+ * prepared-drywall default. Must be set before the scene builds its
+ * materials; `null` restores the declared defaults.
+ */
+export function setSlotDefaultOverrides(overrides) {
+    slotDefaultOverrides = overrides;
+}
+/** A declared slot default after `setSlotDefaultOverrides`. */
+export function resolveSlotDefaultRef(slotDefault) {
+    return slotDefaultOverrides?.[slotDefault] ?? slotDefault;
+}
 export function resolveSlotDefaultMaterial(slotDefault, shading = 'rendered', roughness = 0.9) {
+    slotDefault = resolveSlotDefaultRef(slotDefault);
     if (parseMaterialRef(slotDefault)?.kind === 'library') {
         return (createMaterialFromPresetRef(slotDefault, shading) ??
             cachedDefaultMaterial(`slot-#ffffff-${roughness}`, '#ffffff', roughness, shading));
@@ -604,6 +658,8 @@ export function clearMaterialCache() {
     surfaceRoleMaterialCache.clear();
     textureCache.clear();
     textureLoadPromises.clear();
+    pendingTextures.clear();
+    failedTextures.clear();
     const disposals = [];
     for (const cleanup of materialCacheCleanups) {
         const dispose = cleanup();

package/dist/lib/merged-outline-node.d.ts

@@ -63,6 +63,10 @@ export declare class MergedOutlineNode extends TempNode {
     private readonly _proxiesA;
     private readonly _proxiesB;
     private readonly _proxyMaskMaterials;
+    private readonly _cutoutMasksA;
+    private readonly _cutoutMasksB;
+    private readonly _usedCutoutMasksA;
+    private readonly _usedCutoutMasksB;
     private readonly _maskSceneA;
     private readonly _maskSceneB;
     private _wroteGroupALastFrame;
@@ -90,6 +94,7 @@ export declare class MergedOutlineNode extends TempNode {
     private _syncProxies;
     private _supportsProxies;
     private _disposeProxyMaterial;
+    private _pruneCutoutMasks;
     private _runEdgePipeline;
     setup(builder: any): any;
     dispose(): void;

package/dist/lib/merged-outline-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merged-outline-node.d.ts","sourceRoot":"","sources":["../../src/lib/merged-outline-node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"merged-outline-node.d.ts","sourceRoot":"","sources":["../../src/lib/merged-outline-node.ts"],"names":[],"mappings":"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"}

package/dist/lib/merged-outline-node.js

@@ -124,6 +124,10 @@ export class MergedOutlineNode extends TempNode {
     _proxiesA = new Map();
     _proxiesB = new Map();
     _proxyMaskMaterials = new WeakMap();
+    _cutoutMasksA = new Map();
+    _cutoutMasksB = new Map();
+    _usedCutoutMasksA = new Set();
+    _usedCutoutMasksB = new Set();
     _maskSceneA = new Scene();
     _maskSceneB = new Scene();
     // Tracks whether either group rendered last frame. We use this to decide
@@ -267,7 +271,23 @@ export class MergedOutlineNode extends TempNode {
         this._buildCache(this.secondaryObjects, this._cacheB);
         const useProxiesA = this._syncProxies(this._cacheA, this._proxiesA, this._maskSceneA);
         const useProxiesB = this._syncProxies(this._cacheB, this._proxiesB, this._maskSceneB);
+        this._usedCutoutMasksA.clear();
+        this._usedCutoutMasksB.clear();
+        for (const [cache, used] of [
+            [this._cacheA, this._usedCutoutMasksA],
+            [this._cacheB, this._usedCutoutMasksB],
+        ]) {
+            for (const object of cache) {
+                if (!(object instanceof Mesh))
+                    continue;
+                const materials = Array.isArray(object.material) ? object.material : [object.material];
+                for (const source of materials)
+                    if (source?.alphaTest > 0)
+                        used.add(source);
+            }
+        }
         if (!hasAny) {
+            this._pruneCutoutMasks();
             RendererUtils.restoreRendererAndSceneState(renderer, scene, _rendererState);
             return;
         }
@@ -300,6 +320,7 @@ export class MergedOutlineNode extends TempNode {
             this._runEdgePipeline(renderer, 'A');
         if (hasSecondary)
             this._runEdgePipeline(renderer, 'B');
+        this._pruneCutoutMasks();
         RendererUtils.restoreRendererAndSceneState(renderer, scene, _rendererState);
     }
     _renderMask(renderer, group, useProxies) {
@@ -309,6 +330,8 @@ export class MergedOutlineNode extends TempNode {
         const maskScene = isA ? this._maskSceneA : this._maskSceneB;
         const material = isA ? this._prepareMaskMatA : this._prepareMaskMatB;
         const spriteMaterial = isA ? this._prepareMaskSpriteMatA : this._prepareMaskSpriteMatB;
+        const cutoutMasks = isA ? this._cutoutMasksA : this._cutoutMasksB;
+        const usedCutoutMasks = isA ? this._usedCutoutMasksA : this._usedCutoutMasksB;
         if (useProxies) {
             for (const [source, proxy] of proxies)
                 proxy.matrixWorld.copy(source.matrixWorld);
@@ -316,11 +339,39 @@ export class MergedOutlineNode extends TempNode {
         renderer.setRenderTarget((isA ? this._groupA : this._groupB).maskBuffer);
         // Keep source materials on proxies for material visibility and geometry
         // groups; substitute only at submission, just like the full-scene path.
-        renderer.setRenderObjectFunction((obj, sc, cam, geo, _mat, grp, lights, clip) => {
+        renderer.setRenderObjectFunction((obj, sc, cam, geo, sourceMaterial, grp, lights, clip) => {
             if (!hasDrawableGeometry(geo))
                 return;
             if (useProxies || cache.has(obj)) {
                 let maskMaterial = obj.isSprite ? spriteMaterial : material;
+                if (!obj.isSprite && sourceMaterial?.alphaTest > 0) {
+                    let cutoutMask = cutoutMasks.get(sourceMaterial);
+                    const opacityNode = sourceMaterial.opacityNode ??
+                        (sourceMaterial.map
+                            ? cutoutMask?.userData.sourceMap === sourceMaterial.map
+                                ? cutoutMask.opacityNode
+                                : texture(sourceMaterial.map).a
+                            : null);
+                    if (opacityNode) {
+                        if (!cutoutMask) {
+                            cutoutMask = material.clone();
+                            cutoutMasks.set(sourceMaterial, cutoutMask);
+                        }
+                        const positionNode = sourceMaterial.positionNode ?? null;
+                        const changed = cutoutMask.opacityNode !== opacityNode ||
+                            cutoutMask.positionNode !== positionNode ||
+                            cutoutMask.side !== sourceMaterial.side;
+                        cutoutMask.opacityNode = opacityNode;
+                        cutoutMask.positionNode = positionNode;
+                        cutoutMask.alphaTest = sourceMaterial.alphaTest;
+                        cutoutMask.side = sourceMaterial.side;
+                        cutoutMask.userData.sourceMap = sourceMaterial.map;
+                        if (changed)
+                            cutoutMask.needsUpdate = true;
+                        maskMaterial = cutoutMask;
+                        usedCutoutMasks.add(sourceMaterial);
+                    }
+                }
                 if (useProxies) {
                     let ownedMaterial = this._proxyMaskMaterials.get(obj);
                     if (!ownedMaterial) {
@@ -329,8 +380,16 @@ export class MergedOutlineNode extends TempNode {
                         ownedMaterial = maskMaterial.clone();
                         this._proxyMaskMaterials.set(obj, ownedMaterial);
                     }
-                    if (ownedMaterial.colorNode !== maskMaterial.colorNode) {
+                    if (ownedMaterial.colorNode !== maskMaterial.colorNode ||
+                        ownedMaterial.opacityNode !== maskMaterial.opacityNode ||
+                        ownedMaterial.positionNode !== maskMaterial.positionNode ||
+                        ownedMaterial.alphaTest !== maskMaterial.alphaTest ||
+                        ownedMaterial.side !== maskMaterial.side) {
                         ownedMaterial.colorNode = maskMaterial.colorNode;
+                        ownedMaterial.opacityNode = maskMaterial.opacityNode;
+                        ownedMaterial.positionNode = maskMaterial.positionNode;
+                        ownedMaterial.alphaTest = maskMaterial.alphaTest;
+                        ownedMaterial.side = maskMaterial.side;
                         ownedMaterial.needsUpdate = true;
                     }
                     maskMaterial = ownedMaterial;
@@ -413,6 +472,19 @@ export class MergedOutlineNode extends TempNode {
         this._proxyMaskMaterials.get(proxy)?.dispose();
         this._proxyMaskMaterials.delete(proxy);
     }
+    _pruneCutoutMasks() {
+        for (const [materials, used] of [
+            [this._cutoutMasksA, this._usedCutoutMasksA],
+            [this._cutoutMasksB, this._usedCutoutMasksB],
+        ]) {
+            for (const [source, mask] of materials) {
+                if (used.has(source))
+                    continue;
+                mask.dispose();
+                materials.delete(source);
+            }
+        }
+    }
     _runEdgePipeline(renderer, group) {
         const isA = group === 'A';
         const g = isA ? this._groupA : this._groupB;
@@ -586,6 +658,12 @@ export class MergedOutlineNode extends TempNode {
         this._proxiesB.clear();
         this._cacheA.clear();
         this._cacheB.clear();
+        for (const mask of this._cutoutMasksA.values())
+            mask.dispose();
+        for (const mask of this._cutoutMasksB.values())
+            mask.dispose();
+        this._cutoutMasksA.clear();
+        this._cutoutMasksB.clear();
         this._depthRT.dispose();
         this._groupA.dispose();
         this._groupB.dispose();

package/dist/lib/node-top-surface-height.d.ts

@@ -0,0 +1,6 @@
+import { type AnyNodeId } from '@pascal-app/core';
+type HeightSampler = (x: number, z: number) => number | null;
+/** Samples one locked node's upward-facing mesh in level-local coordinates. */
+export declare function createNodeTopSurfaceHeightSampler(hostId: AnyNodeId, levelId: AnyNodeId): HeightSampler | null;
+export {};
+//# sourceMappingURL=node-top-surface-height.d.ts.map

package/dist/lib/node-top-surface-height.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-top-surface-height.d.ts","sourceRoot":"","sources":["../../src/lib/node-top-surface-height.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,kBAAkB,CAAA;AAKhE,KAAK,aAAa,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;AAS5D,+EAA+E;AAC/E,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,GACjB,aAAa,GAAG,IAAI,CAqEtB"}

package/dist/lib/node-top-surface-height.js

@@ -0,0 +1,74 @@
+import { sceneRegistry } from '@pascal-app/core';
+import { Box3, Matrix3, Raycaster, Vector3 } from 'three';
+import useViewer from '../store/use-viewer';
+import { setSurfaceRaycastLayers } from './layers';
+const samplerCache = new WeakMap();
+/** Samples one locked node's upward-facing mesh in level-local coordinates. */
+export function createNodeTopSurfaceHeightSampler(hostId, levelId) {
+    const host = sceneRegistry.nodes.get(hostId);
+    const level = sceneRegistry.nodes.get(levelId);
+    if (!(host && level))
+        return null;
+    host.updateWorldMatrix(true, false);
+    level.updateWorldMatrix(true, false);
+    const revision = useViewer.getState().geometryRevision;
+    const cached = samplerCache.get(host)?.get(level);
+    if (cached?.revision === revision &&
+        cached.hostMatrix.every((value, index) => value === host.matrixWorld.elements[index]) &&
+        cached.levelMatrix.every((value, index) => value === level.matrixWorld.elements[index])) {
+        return cached.sample;
+    }
+    host.updateWorldMatrix(true, true);
+    const bounds = new Box3().setFromObject(host);
+    if (bounds.isEmpty())
+        return null;
+    const raycaster = new Raycaster();
+    setSurfaceRaycastLayers(raycaster.layers);
+    raycaster.far = Math.max(4, bounds.max.y - bounds.min.y + 4);
+    const origin = new Vector3();
+    const direction = new Vector3(0, -1, 0);
+    const normal = new Vector3();
+    const normalMatrix = new Matrix3();
+    const registeredRoots = new Set(sceneRegistry.nodes.values());
+    const sample = (x, z) => {
+        origin.set(x, 0, z);
+        level.localToWorld(origin);
+        origin.y = bounds.max.y + 2;
+        raycaster.set(origin, direction);
+        for (const hit of raycaster.intersectObject(host, true)) {
+            if (!hit.face)
+                continue;
+            let owner = hit.object.parent;
+            let nestedNode = false;
+            while (owner && owner !== host) {
+                if (registeredRoots.has(owner)) {
+                    nestedNode = true;
+                    break;
+                }
+                owner = owner.parent;
+            }
+            if (nestedNode)
+                continue;
+            normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+            normal.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
+            if (normal.y < 0.1)
+                continue;
+            const point = hit.point.clone();
+            level.worldToLocal(point);
+            return point.y;
+        }
+        return null;
+    };
+    let byLevel = samplerCache.get(host);
+    if (!byLevel) {
+        byLevel = new WeakMap();
+        samplerCache.set(host, byLevel);
+    }
+    byLevel.set(level, {
+        revision,
+        hostMatrix: [...host.matrixWorld.elements],
+        levelMatrix: [...level.matrixWorld.elements],
+        sample,
+    });
+    return sample;
+}

package/dist/lib/perf-probe-state.d.ts

@@ -0,0 +1,39 @@
+type TemporalLike = {
+    temporal: {
+        getState(): {
+            pastStates: readonly unknown[];
+            futureStates: readonly unknown[];
+            isTracking: boolean;
+        };
+    };
+};
+type SelectionLike = {
+    getState(): {
+        selection: {
+            buildingId: string | null;
+            levelId: string | null;
+            zoneId: string | null;
+            selectedIds: readonly string[];
+        };
+    };
+};
+export type PerfHistoryState = {
+    /** Undo entries. */
+    past: number;
+    /** Redo entries. */
+    future: number;
+    /** False while any owner has history paused. */
+    tracking: boolean;
+    /** Refcounted pause owners (`pauseSceneHistory` + leases); direct `temporal.pause()` is not counted. */
+    pauseDepth: number;
+};
+export type PerfSelectionState = {
+    buildingId: string | null;
+    levelId: string | null;
+    zoneId: string | null;
+    selectedIds: string[];
+};
+export declare function readPerfHistory(store: TemporalLike): PerfHistoryState;
+export declare function readPerfSelection(store: SelectionLike): PerfSelectionState;
+export {};
+//# sourceMappingURL=perf-probe-state.d.ts.map

package/dist/lib/perf-probe-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-probe-state.d.ts","sourceRoot":"","sources":["../../src/lib/perf-probe-state.ts"],"names":[],"mappings":"AAMA,KAAK,YAAY,GAAG;IAClB,QAAQ,EAAE;QACR,QAAQ,IAAI;YACV,UAAU,EAAE,SAAS,OAAO,EAAE,CAAA;YAC9B,YAAY,EAAE,SAAS,OAAO,EAAE,CAAA;YAChC,UAAU,EAAE,OAAO,CAAA;SACpB,CAAA;KACF,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,QAAQ,IAAI;QACV,SAAS,EAAE;YACT,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;YACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;YACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;YACrB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;SAC/B,CAAA;KACF,CAAA;CACF,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,QAAQ,EAAE,OAAO,CAAA;IACjB,wGAAwG;IACxG,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB,CAAA;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,CAQrE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,kBAAkB,CAG1E"}

package/dist/lib/perf-probe-state.js

@@ -0,0 +1,17 @@
+// Read-only state for scripted `?perf` receipts (bench/next-house, scripts/perf): the scene
+// history and the viewer selection, so production builds can report undo entries and
+// history pauses without dev-only store handles.
+import { getSceneHistoryPauseDepth } from '@pascal-app/core';
+export function readPerfHistory(store) {
+    const temporal = store.temporal.getState();
+    return {
+        past: temporal.pastStates.length,
+        future: temporal.futureStates.length,
+        tracking: temporal.isTracking,
+        pauseDepth: getSceneHistoryPauseDepth(),
+    };
+}
+export function readPerfSelection(store) {
+    const { buildingId, levelId, zoneId, selectedIds } = store.getState().selection;
+    return { buildingId, levelId, zoneId, selectedIds: [...selectedIds] };
+}

package/dist/lib/pointer-events.d.ts

@@ -1,7 +1,31 @@
 import { events as createWebEvents, type EventManager, type RootStore } from '@react-three/fiber';
 import * as THREE from 'three';
+/** A diagnostic the viewer hands its host, shaped for an error reporter's breadcrumb trail. */
+export type ViewerBreadcrumb = {
+    category: string;
+    message: string;
+    level: 'info' | 'warning';
+    data?: Record<string, unknown>;
+};
+export type ViewerBreadcrumbHandler = (breadcrumb: ViewerBreadcrumb) => void;
 /** Opt in only when the raycast appends hits without reading prior hits or mutating scene/query state. */
 export declare function markPureRaycast<T extends THREE.Object3D['raycast']>(raycast: T): T;
-export declare function choosePointerEvents(search?: string): typeof createWebEvents;
-export declare function createPascalPointerEvents(store: RootStore): EventManager<HTMLElement>;
+export declare function choosePointerEvents(search?: string, onBreadcrumb?: ViewerBreadcrumbHandler): typeof createWebEvents;
+/**
+ * Whether a mesh has a material for everything a raycast reads: three indexes
+ * a material array by each geometry group, and one with no entry throws on
+ * `material.side`. A mesh caught mid-swap (a preview restored an older array
+ * over a rebuilt geometry) is skipped for this move instead of taking the whole
+ * pointer event down; its children are still tested. `material` asks the same of
+ * an array the mesh would wear.
+ */
+export declare function hasMaterialsForGroups(object: THREE.Object3D, material?: THREE.Material | THREE.Material[] | undefined): boolean;
+type SkipInvalidMaterial = (object: THREE.Object3D) => void;
+/**
+ * Three's recursive `intersectObject`, skipping meshes `hasMaterialsForGroups`
+ * rejects. A raycaster with its own `intersectObject` is asked directly.
+ */
+export declare function intersectDrawable(raycaster: THREE.Raycaster, object: THREE.Object3D, skip: SkipInvalidMaterial): THREE.Intersection[];
+export declare function createPascalPointerEvents(store: RootStore, onBreadcrumb?: ViewerBreadcrumbHandler): EventManager<HTMLElement>;
+export {};
 //# sourceMappingURL=pointer-events.d.ts.map

package/dist/lib/pointer-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pointer-events.d.ts","sourceRoot":"","sources":["../../src/lib/pointer-events.ts"],"names":[],"mappings":"AA6BA,OAAO,EACL,MAAM,IAAI,eAAe,EAGzB,KAAK,YAAY,EAMjB,KAAK,SAAS,EAEf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqC9B,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGlF;AAYD,wBAAgB,mBAAmB,CACjC,MAAM,SAA8D,GACnE,OAAO,eAAe,CAIxB;AAiLD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC,WAAW,CAAC,CAmBrF"}
+{"version":3,"file":"pointer-events.d.ts","sourceRoot":"","sources":["../../src/lib/pointer-events.ts"],"names":[],"mappings":"AA8BA,OAAO,EACL,MAAM,IAAI,eAAe,EAGzB,KAAK,YAAY,EAMjB,KAAK,SAAS,EAEf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B,+FAA+F;AAC/F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAA;AAmC5E,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGlF;AAYD,wBAAgB,mBAAmB,CACjC,MAAM,SAA8D,EACpE,YAAY,CAAC,EAAE,uBAAuB,GACrC,OAAO,eAAe,CAIxB;AAiED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,KAAK,CAAC,QAAQ,EACtB,QAAQ,GAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,GAAG,SAA2C,GACxF,OAAO,CAST;AAMD,KAAK,mBAAmB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAA;AAmC3D;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,KAAK,CAAC,SAAS,EAC1B,MAAM,EAAE,KAAK,CAAC,QAAQ,EACtB,IAAI,EAAE,mBAAmB,GACxB,KAAK,CAAC,YAAY,EAAE,CAiBtB;AA+GD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,YAAY,CAAC,EAAE,uBAAuB,GACrC,YAAY,CAAC,WAAW,CAAC,CAmB3B"}