@pascal-app/viewer 0.9.1 → 1.0.0-beta.1

package/dist/lib/ktx2-loader.js

@@ -0,0 +1,142 @@
+import { DataTexture, LinearFilter, LinearMipmapLinearFilter, RGBAFormat, UnsignedByteType, } from 'three';
+// Deep path, NOT the `Addons.js` aggregate: the aggregate re-exports
+// LottieLoader/TTFLoader, whose CDN URL imports (`lottie-web`, `opentype.js`)
+// crash bun's test runtime for every consumer of the viewer barrel.
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/** Base width/height of a Basis-supercompressed KTX2 payload needing transcode
+ *  (vkFormat 0 = ETC1S/UASTC) whose dimensions aren't block-aligned, or null
+ *  for anything safe. Little-endian u32s: vkFormat at byte 12, pixelWidth at
+ *  20, pixelHeight at 24. */
+function readMisalignedBasisSize(buffer) {
+    if (buffer.byteLength < 28)
+        return null;
+    const view = new DataView(buffer);
+    const vkFormat = view.getUint32(12, true);
+    if (vkFormat !== 0)
+        return null;
+    const width = view.getUint32(20, true);
+    const height = view.getUint32(24, true);
+    return width % 4 !== 0 || height % 4 !== 0 ? { width, height } : null;
+}
+/**
+ * KTX2Loader that survives block-misaligned textures. WebGPU rejects
+ * block-compressed textures whose base dimensions aren't multiples of 4;
+ * three's KTX2Loader only warns and transcodes anyway, and the resulting
+ * invalid texture poisons every render pass that binds it (endless
+ * "Invalid BindGroup … Invalid CommandBuffer" spam — baked GLBs carrying an
+ * odd-sized user-item texture triggered exactly this). Such payloads are
+ * routed to a fallback loader whose support flags report no compressed
+ * formats, which makes the transcoder emit plain RGBA32 — uncompressed
+ * textures have no alignment requirement.
+ */
+class AlignmentSafeKTX2Loader extends KTX2Loader {
+    rgbaFallback = null;
+    fallbackLoader() {
+        if (!this.rgbaFallback) {
+            this.rgbaFallback = new KTX2Loader(this.manager);
+            this.rgbaFallback.setTranscoderPath(this.transcoderPath);
+            this.rgbaFallback.workerConfig = {
+                astcSupported: false,
+                astcHDRSupported: false,
+                etc1Supported: false,
+                etc2Supported: false,
+                dxtSupported: false,
+                bptcSupported: false,
+                pvrtcSupported: false,
+            };
+        }
+        return this.rgbaFallback;
+    }
+    /** Both `load()` and GLTFLoader's KHR_texture_basisu path funnel through
+     *  this internal — overriding it covers every entry point. */
+    async _createTexture(buffer, config) {
+        const misaligned = readMisalignedBasisSize(buffer);
+        if (misaligned) {
+            console.warn(`[viewer] KTX2 texture is ${misaligned.width}x${misaligned.height} (not multiple-of-4); ` +
+                'transcoding uncompressed so WebGPU can create it.');
+            const transcoded = (await this.fallbackLoader()._createTexture(buffer, config));
+            // The RGBA32 result still arrives as a CompressedTexture; three's WebGPU
+            // texture upload treats every CompressedTexture as block-compressed and
+            // crashes looking up a block descriptor for rgba8. Repackage the decoded
+            // pixels as a plain DataTexture instead.
+            const mip = transcoded.mipmaps?.[0];
+            if (!mip)
+                return transcoded;
+            const texture = new DataTexture(mip.data, mip.width, mip.height, RGBAFormat, UnsignedByteType);
+            texture.colorSpace = transcoded.colorSpace;
+            texture.generateMipmaps = true;
+            texture.minFilter = LinearMipmapLinearFilter;
+            texture.magFilter = LinearFilter;
+            texture.needsUpdate = true;
+            transcoded.dispose();
+            return texture;
+        }
+        return KTX2Loader.prototype._createTexture.call(this, buffer, config);
+    }
+    dispose() {
+        this.rgbaFallback?.dispose();
+        this.rgbaFallback = null;
+        super.dispose();
+        return this;
+    }
+}
+/**
+ * Single shared KTX2 loader for the whole viewer — used both by the GLB loader
+ * (`use-gltf-ktx2`) and by catalog finish textures (`materials.ts`). KTX2 must
+ * be transcoded at load via the Basis WASM, and `detectSupport(renderer)` has to
+ * run once before any `.ktx2` is loaded so the loader picks a GPU format the
+ * device supports. `ensureKtx2Support` is idempotent per renderer and is called
+ * from the viewer root the moment the renderer is ready (even when no GLB is in
+ * the scene, so catalog `.ktx2` finishes still load).
+ */
+export const ktx2Loader = new AlignmentSafeKTX2Loader();
+ktx2Loader.setTranscoderPath('https://cdn.jsdelivr.net/gh/pmndrs/drei-assets@master/basis/');
+const configuredRenderers = new WeakSet();
+const warnedRenderers = new WeakSet();
+let resolveKtx2Ready;
+const ktx2ReadyPromise = new Promise((resolve) => {
+    resolveKtx2Ready = resolve;
+});
+/**
+ * Resolves once `detectSupport` has succeeded for any renderer. `.ktx2` loads
+ * issued before that point would throw inside KTX2Loader ("Missing
+ * initialization with `.detectSupport( renderer )`"), so texture loaders await
+ * this instead of failing — covers materials created while the renderer is
+ * still initializing (e.g. a standalone capture canvas).
+ */
+export function whenKtx2Ready() {
+    return ktx2ReadyPromise;
+}
+/** Returns true once support has been detected for this renderer (KTX2 safe to load). */
+export function ensureKtx2Support(renderer) {
+    const key = renderer;
+    if (!key)
+        return false;
+    if (configuredRenderers.has(key))
+        return true;
+    try {
+        ;
+        ktx2Loader.detectSupport(renderer);
+        configuredRenderers.add(key);
+        resolveKtx2Ready();
+        return true;
+    }
+    catch (error) {
+        // Some WebGPU flows can transiently call this before backend init; don't
+        // crash the scene — a later call (or the next render) retries.
+        if (!warnedRenderers.has(key)) {
+            console.warn('[viewer] Skipping KTX2 support detection for now.', error);
+            warnedRenderers.add(key);
+        }
+        return false;
+    }
+}
+export function configureKtx2Support(loader, renderer) {
+    if (!ensureKtx2Support(renderer))
+        return false;
+    loader.setKTX2Loader(ktx2Loader);
+    return true;
+}
+export function isKtx2Url(url) {
+    return url.toLowerCase().endsWith('.ktx2');
+}

package/dist/lib/layers.d.ts

@@ -20,4 +20,14 @@ export declare const ZONE_LAYER = 2;
  * from thumbnails like the other editor-only layers.
  */
 export declare const GRID_LAYER = 3;
+/**
+ * Layer for geometry hidden from the color passes but still rendered into the
+ * shadow map ("shadow-caster-only"). Used when cutaway/solo views hide roofs
+ * or non-selected levels: the sun keeps casting their shadows, so interiors
+ * get window-shaped light patches instead of flooding with uniform sun.
+ * No camera or pass enables this layer — only each shadow-casting light's
+ * shadow camera does (see `lights.tsx`). Applied per-object (layers don't
+ * cascade) via `applyShadowOnly` / `clearShadowOnly` in `lib/shadow-only.ts`.
+ */
+export declare const SHADOW_ONLY_LAYER = 4;
 //# 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"}
+{"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"}

package/dist/lib/layers.js

@@ -20,3 +20,13 @@ export const ZONE_LAYER = 2;
  * from thumbnails like the other editor-only layers.
  */
 export const GRID_LAYER = 3;
+/**
+ * Layer for geometry hidden from the color passes but still rendered into the
+ * shadow map ("shadow-caster-only"). Used when cutaway/solo views hide roofs
+ * or non-selected levels: the sun keeps casting their shadows, so interiors
+ * get window-shaped light patches instead of flooding with uniform sun.
+ * No camera or pass enables this layer — only each shadow-casting light's
+ * shadow camera does (see `lights.tsx`). Applied per-object (layers don't
+ * cascade) via `applyShadowOnly` / `clearShadowOnly` in `lib/shadow-only.ts`.
+ */
+export const SHADOW_ONLY_LAYER = 4;

package/dist/lib/materials.d.ts

@@ -1,4 +1,4 @@
-import { type MaterialPresetPayload, type MaterialSchema, type SurfaceRole } from '@pascal-app/core';
+import { type MaterialPresetPayload, type MaterialSchema, type SceneMaterial, type SceneMaterialId, type SurfaceRole } from '@pascal-app/core';
 import * as THREE from 'three';
 import { MeshLambertNodeMaterial } from 'three/webgpu';
 export type RenderShading = 'solid' | 'rendered';
@@ -10,10 +10,25 @@ export declare const BLUEPRINT_PALETTE: Record<SurfaceRole, string>;
 export declare const PRESET_PALETTES: Record<ColorPreset, Record<SurfaceRole, string>>;
 export declare function resolveSurfaceColor(role: SurfaceRole, preset: ColorPreset, sceneThemeId?: string): string;
 export declare const glassMaterial: MeshLambertNodeMaterial;
+export declare function resolveTextureRepeat(repeat: unknown, scale: unknown): [number, number];
+export declare function getTextureKey(material?: MaterialSchema): string;
 export declare function applyMaterialPresetToMaterials(materialInput: THREE.Material | THREE.Material[], preset: MaterialPresetPayload | null | undefined): void;
 export declare function createMaterialFromPreset(preset: MaterialPresetPayload, shading?: RenderShading): THREE.Material;
 export declare function createMaterialFromPresetRef(materialPreset?: string, shading?: RenderShading): THREE.Material | null;
 export declare function createMaterial(material?: MaterialSchema, shading?: RenderShading): THREE.Material;
+/**
+ * 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.
+ */
+export declare function resolveMaterialRef(ref: string | undefined, sceneMaterials: Record<SceneMaterialId, SceneMaterial> | undefined, shading?: RenderShading): THREE.Material | null;
+/**
+ * Resolve a node kind's declared slot default — either a catalog `library:<id>`
+ * finish or a flat `#rrggbb` colour — to a renderable material. Shared by the
+ * procedural kinds whose colored-mode unpainted appearance comes from a
+ * declarative default (slab, wall).
+ */
+export declare function resolveSlotDefaultMaterial(slotDefault: string, shading?: RenderShading, roughness?: number): THREE.Material;
 export declare function createDefaultMaterial(color?: string, roughness?: number, shading?: RenderShading, side?: THREE.Side): THREE.Material;
 export declare function createSurfaceRoleMaterial(role: SurfaceRole, preset: ColorPreset, side?: THREE.Side, sceneThemeId?: string): THREE.Material;
 export declare function baseMaterial(shading?: RenderShading): THREE.Material;

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

@@ -1 +1 @@
-{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../../src/lib/materials.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../../src/lib/materials.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EAGnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,uBAAuB,EAA4B,MAAM,cAAc,CAAA;AAOhF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,CAAA;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAA;AAEjE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQpD,CAAA;AAID,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQrD,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQpD,CAAA;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQzD,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAK5E,CAAA;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAKR;AAOD,eAAO,MAAM,aAAa,yBAKxB,CAAA;AA6FF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWtF;AAED,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAK/D;AAySD,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,EAChD,MAAM,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,QAcjD;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,aAA0B,GAClC,KAAK,CAAC,QAAQ,CAchB;AAED,wBAAgB,2BAA2B,CACzC,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,GAAE,aAA0B,GAClC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAIvB;AAED,wBAAgB,cAAc,CAC5B,QAAQ,CAAC,EAAE,cAAc,EACzB,OAAO,GAAE,aAA0B,GAClC,KAAK,CAAC,QAAQ,CAqChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,SAAS,EAClE,OAAO,GAAE,aAA0B,GAClC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAOvB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,aAA0B,EACnC,SAAS,SAAM,GACd,KAAK,CAAC,QAAQ,CAQhB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,SAAY,EACjB,SAAS,SAAM,EACf,OAAO,GAAE,aAA0B,EACnC,IAAI,GAAE,KAAK,CAAC,IAAsB,GACjC,KAAK,CAAC,QAAQ,CAehB;AAmBD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,KAAK,CAAC,IAAsB,EAClC,YAAY,CAAC,EAAE,MAAM,GACpB,KAAK,CAAC,QAAQ,CAgChB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAEzF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CA2B3F;AAED,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAE5F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAEzF;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAE1F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,aAA0B,GAAG,KAAK,CAAC,QAAQ,CAE1F;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAE9D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAqBzC"}

package/dist/lib/materials.js

@@ -1,8 +1,11 @@
-import { getMaterialPresetByRef, resolveMaterial, } from '@pascal-app/core';
+import { getMaterialPresetByRef, parseMaterialRef, resolveMaterial, } from '@pascal-app/core';
 import * as THREE from 'three';
+import { float, mix, positionViewDirection, transformedNormalView } from 'three/tsl';
 import { MeshLambertNodeMaterial, MeshStandardNodeMaterial } from 'three/webgpu';
 import { resolveCdnUrl } from './asset-url';
+import { isKtx2Url, ktx2Loader, whenKtx2Ready } from './ktx2-loader';
 import { getSceneTheme } from './scene-themes';
+import { stampPascalTextureRef } from './texture-reference';
 export const CLAY_PALETTE = {
     wall: '#dcd6c7',
     floor: '#cfc8b6',
@@ -12,14 +15,16 @@ export const CLAY_PALETTE = {
     glazing: '#c8d4dc',
     furnishing: '#d2ccbe',
 };
+// Albedos are clamped to ≈0.83 linear (max channel #eb): real white paint
+// reflects ~80%, and pure-white albedo kills GI/shadow contrast.
 export const WHITE_PALETTE = {
-    wall: '#f4f3ef',
-    floor: '#ece9e2',
-    ceiling: '#fbfaf6',
+    wall: '#ebeae6',
+    floor: '#e7e4dd',
+    ceiling: '#ebeae6',
     roof: '#dedbd2',
-    joinery: '#e8e5dc',
+    joinery: '#e5e2d9',
     glazing: '#dbe8ee',
-    furnishing: '#efede7',
+    furnishing: '#e9e7e1',
 };
 export const MONO_PALETTE = {
     wall: '#c8c8c8',
@@ -49,7 +54,7 @@ export function resolveSurfaceColor(role, preset, sceneThemeId) {
     // The active scene theme may tint individual roles (e.g. Mediterranean's blue
     // roof); fall back to the chosen colour preset's palette when it doesn't.
     const tints = sceneThemeId ? getSceneTheme(sceneThemeId).clayTints : undefined;
-    return tints?.[role] ?? PRESET_PALETTES[preset][role];
+    return tints?.[role] ?? (PRESET_PALETTES[preset] ?? CLAY_PALETTE)[role];
 }
 // DoubleSide on any NodeMaterial inside the MRT scenePass (SSGI's output /
 // diffuseColor / normal targets) causes WebGPU to create a render pipeline
@@ -62,10 +67,14 @@ export const glassMaterial = new MeshLambertNodeMaterial({
     opacity: 0.35,
     side: THREE.FrontSide,
 });
+glassMaterial.userData.__pascalCachedMaterial = true;
+function resolveNodeMaterialSide(side) {
+    return side === THREE.DoubleSide ? THREE.FrontSide : side;
+}
 const sideMap = {
     front: THREE.FrontSide,
     back: THREE.BackSide,
-    double: THREE.DoubleSide,
+    double: THREE.FrontSide,
 };
 const materialCache = new Map();
 const defaultMaterialCache = new Map();
@@ -73,6 +82,13 @@ const surfaceRoleMaterialCache = new Map();
 const textureCache = new Map();
 const textureLoadPromises = new Map();
 const textureLoader = new THREE.TextureLoader();
+// `.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) {
+    // KTX2Loader's load/loadAsync are call-compatible with TextureLoader (url →
+    // Texture / Promise<Texture>); cast for typing.
+    return isKtx2Url(url) ? ktx2Loader : textureLoader;
+}
 const wrapMap = {
     Repeat: THREE.RepeatWrapping,
     ClampToEdge: THREE.ClampToEdgeWrapping,
@@ -100,13 +116,29 @@ function getTextureChannel(slot) {
 function getCacheKey(props, shading) {
     return `${shading}-${props.color}-${props.roughness}-${props.metalness}-${props.opacity}-${props.transparent}-${props.side}`;
 }
-function getTextureKey(material) {
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function resolveTextureRepeat(repeat, scale) {
+    const fallback = isFiniteNumber(scale) ? scale : 1;
+    if (Array.isArray(repeat) && isFiniteNumber(repeat[0]) && isFiniteNumber(repeat[1])) {
+        return [repeat[0], repeat[1]];
+    }
+    if (isFiniteNumber(repeat))
+        return [repeat, repeat];
+    if (repeat && typeof repeat === 'object' && 'x' in repeat && 'y' in repeat) {
+        const { x, y } = repeat;
+        if (isFiniteNumber(x) && isFiniteNumber(y))
+            return [x, y];
+    }
+    return [fallback, fallback];
+}
+export function getTextureKey(material) {
     const texture = material?.texture;
     if (!texture)
         return 'none';
-    const repeat = texture.repeat?.join('x') ?? 'default';
-    const scale = texture.scale ?? 'default';
-    return `${texture.url}-${repeat}-${scale}`;
+    const [repeatX, repeatY] = resolveTextureRepeat(texture.repeat, texture.scale);
+    return `${texture.url}-${repeatX}x${repeatY}`;
 }
 function getTexture(material) {
     const textureConfig = material?.texture;
@@ -116,14 +148,21 @@ function getTexture(material) {
     const cached = textureCache.get(cacheKey);
     if (cached)
         return cached;
-    const texture = textureLoader.load(textureConfig.url);
+    const resolvedUrl = /^(?:asset|blob|data):/.test(textureConfig.url)
+        ? textureConfig.url
+        : (resolveCdnUrl(textureConfig.url) ?? textureConfig.url);
+    const texture = pickTextureLoader(resolvedUrl).load(resolvedUrl);
     texture.wrapS = THREE.RepeatWrapping;
     texture.wrapT = THREE.RepeatWrapping;
-    const repeatX = textureConfig.repeat?.[0] ?? textureConfig.scale ?? 1;
-    const repeatY = textureConfig.repeat?.[1] ?? textureConfig.scale ?? 1;
+    const [repeatX, repeatY] = resolveTextureRepeat(textureConfig.repeat, textureConfig.scale);
     texture.repeat.set(repeatX, repeatY);
     texture.updateMatrix();
     texture.colorSpace = THREE.SRGBColorSpace;
+    stampPascalTextureRef(texture, {
+        kind: 'project-asset',
+        src: resolvedUrl,
+        slot: 'map',
+    });
     textureCache.set(cacheKey, texture);
     return texture;
 }
@@ -162,8 +201,13 @@ function getPresetTexture(path, props, slot) {
     const cached = textureCache.get(cacheKey);
     if (cached)
         return cached;
-    const texture = textureLoader.load(resolvedPath);
+    const texture = pickTextureLoader(resolvedPath).load(resolvedPath);
     applyTextureProperties(texture, props, slot);
+    stampPascalTextureRef(texture, {
+        kind: 'material',
+        src: resolvedPath,
+        slot: slot ?? 'map',
+    });
     setTextureCacheKey(texture, cacheKey);
     textureCache.set(cacheKey, texture);
     return texture;
@@ -195,10 +239,21 @@ async function loadPresetTexture(path, props, slot) {
     const existingPromise = textureLoadPromises.get(cacheKey);
     if (existingPromise)
         return existingPromise;
-    const promise = textureLoader
-        .loadAsync(resolvedPath)
+    // `.ktx2` loads wait for `detectSupport` (KTX2Loader.load throws before it) —
+    // materials can be created while a capture canvas's renderer is still
+    // initializing, and failing here would cache the material permanently
+    // texture-less (white).
+    const load = isKtx2Url(resolvedPath)
+        ? whenKtx2Ready().then(() => ktx2Loader.loadAsync(resolvedPath))
+        : textureLoader.loadAsync(resolvedPath);
+    const promise = load
         .then((texture) => {
         applyTextureProperties(texture, props, slot);
+        stampPascalTextureRef(texture, {
+            kind: 'material',
+            src: resolvedPath,
+            slot: slot ?? 'map',
+        });
         setTextureCacheKey(texture, cacheKey);
         textureCache.set(cacheKey, texture);
         textureLoadPromises.delete(cacheKey);
@@ -215,7 +270,13 @@ async function loadPresetTexture(path, props, slot) {
 function queueTextureAssignment(material, slot, path, props) {
     const textureMaterial = material;
     if (!path) {
-        textureMaterial[slot] = null;
+        if (textureMaterial[slot] != null) {
+            // Rebuild the node graph: a cached WebGPU material keeps a TextureNode
+            // for the slot, whose per-frame material reference would pull the null
+            // and crash in TextureNode.update ("null (reading 'matrix')").
+            textureMaterial[slot] = null;
+            material.needsUpdate = true;
+        }
         return;
     }
     const resolvedPath = resolveCdnUrl(path) ?? path;
@@ -230,7 +291,14 @@ function queueTextureAssignment(material, slot, path, props) {
         material.needsUpdate = true;
         return;
     }
-    textureMaterial[slot] = null;
+    // Cold load: clear the slot for the fetch window, and rebuild the node
+    // graph if it previously held a texture — reused cached materials otherwise
+    // keep a TextureNode whose reference pulls the null and crashes the render
+    // pass. Cold loads are the norm for freshly generated library materials.
+    if (textureMaterial[slot] != null) {
+        textureMaterial[slot] = null;
+        material.needsUpdate = true;
+    }
     loadPresetTexture(path, props, slot).then((texture) => {
         if (!texture)
             return;
@@ -257,15 +325,35 @@ function applyMaterialMapProperties(material, mapProperties) {
     }
     material.transparent = mapProperties.transparent;
     material.opacity = mapProperties.opacity;
-    material.side =
-        mapProperties.side === 0
-            ? THREE.FrontSide
-            : mapProperties.side === 1
-                ? THREE.BackSide
-                : THREE.DoubleSide;
+    material.side = resolveNodeMaterialSide(mapProperties.side === 0
+        ? THREE.FrontSide
+        : mapProperties.side === 1
+            ? THREE.BackSide
+            : THREE.DoubleSide);
     applyTexturePropertiesToMaterial(material, mapProperties);
     material.needsUpdate = true;
 }
+// Glass-like transparency threshold: any standard material authored as
+// `transparent` with opacity below this gets the fresnel treatment.
+const GLASS_OPACITY_THRESHOLD = 0.6;
+/**
+ * Fresnel-driven opacity for glass: nearly the authored opacity head-on,
+ * increasingly opaque (showing the environment reflection) at grazing angles.
+ * This is what makes glass read as a surface instead of a flat blue tint.
+ */
+function applyGlassFresnel(material) {
+    const facing = transformedNormalView.dot(positionViewDirection).clamp(0, 1);
+    const fresnel = facing.oneMinus().pow(3);
+    material.opacityNode = mix(float(material.opacity), float(0.92), fresnel);
+    material.envMapIntensity = 1.4;
+}
+function maybeApplyGlassFresnel(material) {
+    if (material instanceof MeshStandardNodeMaterial &&
+        material.transparent &&
+        material.opacity < GLASS_OPACITY_THRESHOLD) {
+        applyGlassFresnel(material);
+    }
+}
 function applyMaterialPresetTextures(material, preset) {
     const { maps, mapProperties } = preset;
     queueTextureAssignment(material, 'map', maps.albedoMap, mapProperties);
@@ -302,6 +390,8 @@ export function createMaterialFromPreset(preset, shading = 'rendered') {
     }
     const material = shading === 'solid' ? new MeshLambertNodeMaterial() : new MeshStandardNodeMaterial();
     applyMaterialPresetToMaterials(material, preset);
+    maybeApplyGlassFresnel(material);
+    material.userData.__pascalCachedMaterial = true;
     materialCache.set(cacheKey, material);
     return material;
 }
@@ -333,21 +423,53 @@ export function createMaterial(material, shading = 'rendered') {
             roughness: props.roughness,
             metalness: props.metalness,
         });
+    maybeApplyGlassFresnel(threeMaterial);
+    threeMaterial.userData.__pascalCachedMaterial = true;
     materialCache.set(cacheKey, threeMaterial);
     return threeMaterial;
 }
+/**
+ * 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.
+ */
+export function resolveMaterialRef(ref, sceneMaterials, shading = 'rendered') {
+    const parsed = parseMaterialRef(ref);
+    if (!parsed)
+        return null;
+    if (parsed.kind === 'library')
+        return createMaterialFromPresetRef(ref, shading);
+    const sceneMaterial = sceneMaterials?.[parsed.id];
+    if (!sceneMaterial)
+        return null;
+    return createMaterial(sceneMaterial.material, shading);
+}
+/**
+ * Resolve a node kind's declared slot default — either a catalog `library:<id>`
+ * finish or a flat `#rrggbb` colour — to a renderable material. Shared by the
+ * procedural kinds whose colored-mode unpainted appearance comes from a
+ * declarative default (slab, wall).
+ */
+export function resolveSlotDefaultMaterial(slotDefault, shading = 'rendered', roughness = 0.9) {
+    if (parseMaterialRef(slotDefault)?.kind === 'library') {
+        return (createMaterialFromPresetRef(slotDefault, shading) ??
+            createDefaultMaterial('#ffffff', roughness, shading));
+    }
+    return createDefaultMaterial(slotDefault, roughness, shading);
+}
 export function createDefaultMaterial(color = '#ffffff', roughness = 0.9, shading = 'rendered', side = THREE.FrontSide) {
+    const resolvedSide = resolveNodeMaterialSide(side);
     if (shading === 'solid') {
         return new MeshLambertNodeMaterial({
             color,
-            side,
+            side: resolvedSide,
         });
     }
     return new MeshStandardNodeMaterial({
         color,
         roughness,
         metalness: 0,
-        side,
+        side: resolvedSide,
     });
 }
 function cachedDefaultMaterial(key, color, roughness, shading, side = THREE.FrontSide) {
@@ -356,6 +478,7 @@ function cachedDefaultMaterial(key, color, roughness, shading, side = THREE.Fron
     if (cached)
         return cached;
     const material = createDefaultMaterial(color, roughness, shading, side);
+    material.userData.__pascalCachedMaterial = true;
     defaultMaterialCache.set(cacheKey, material);
     return material;
 }
@@ -368,7 +491,7 @@ export function createSurfaceRoleMaterial(role, preset, side = THREE.FrontSide,
     // on both gable faces on the first frame). Callers that need both sides
     // visible (e.g. dormer back gable) must rotate the host mesh 180° so the
     // FrontSide faces the viewer.
-    const resolvedSide = role === 'glazing' ? THREE.FrontSide : side;
+    const resolvedSide = role === 'glazing' ? THREE.FrontSide : resolveNodeMaterialSide(side ?? THREE.FrontSide);
     const cacheKey = `${role}-${preset}-${resolvedSide}-${sceneThemeId ?? 'base'}`;
     const cached = surfaceRoleMaterialCache.get(cacheKey);
     if (cached)
@@ -390,10 +513,10 @@ export function createSurfaceRoleMaterial(role, preset, side = THREE.FrontSide,
     return material;
 }
 export function baseMaterial(shading = 'rendered') {
-    return cachedDefaultMaterial('base', '#f2f0ed', 0.5, shading);
+    return cachedDefaultMaterial('base', '#e9e7e3', 0.5, shading);
 }
 export function DEFAULT_WALL_MATERIAL(shading = 'rendered') {
-    return cachedDefaultMaterial('wall', '#ffffff', 0.9, shading);
+    return cachedDefaultMaterial('wall', '#e9e6e0', 0.9, shading);
 }
 export function DEFAULT_SLAB_MATERIAL(shading = 'rendered') {
     return cachedDefaultMaterial('slab', '#e5e5e5', 0.8, shading);
@@ -424,20 +547,21 @@ export function DEFAULT_WINDOW_MATERIAL(shading = 'rendered') {
             roughness: 0.1,
             metalness: 0.1,
         });
+    maybeApplyGlassFresnel(material);
     defaultMaterialCache.set(cacheKey, material);
     return material;
 }
 export function DEFAULT_CEILING_MATERIAL(shading = 'rendered') {
-    return cachedDefaultMaterial('ceiling', '#f5f5dc', 0.95, shading);
+    return cachedDefaultMaterial('ceiling', '#ebebd3', 0.95, shading);
 }
 export function DEFAULT_ROOF_MATERIAL(shading = 'rendered') {
     return cachedDefaultMaterial('roof', '#808080', 0.85, shading);
 }
 export function DEFAULT_SHELF_MATERIAL(shading = 'rendered') {
-    return cachedDefaultMaterial('shelf', '#ffffff', 0.9, shading);
+    return cachedDefaultMaterial('shelf', '#e9e6e0', 0.9, shading);
 }
 export function DEFAULT_STAIR_MATERIAL(shading = 'rendered') {
-    return cachedDefaultMaterial('stair', '#ffffff', 0.9, shading);
+    return cachedDefaultMaterial('stair', '#e9e6e0', 0.9, shading);
 }
 export function disposeMaterial(material) {
     material.dispose();

package/dist/lib/materials.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=materials.test.d.ts.map

package/dist/lib/materials.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materials.test.d.ts","sourceRoot":"","sources":["../../src/lib/materials.test.ts"],"names":[],"mappings":""}

package/dist/lib/materials.test.js

@@ -0,0 +1,25 @@
+// @ts-expect-error — bun:test is provided by the Bun runtime; viewer does not
+// depend on @types/bun so the import type is unresolved at compile time.
+import { describe, expect, test } from 'bun:test';
+import { getTextureKey, resolveTextureRepeat } from './materials';
+function materialWithRepeat(repeat) {
+    return {
+        texture: {
+            url: 'https://example.com/texture.png',
+            repeat,
+        },
+    };
+}
+describe('legacy texture repeat values', () => {
+    test('normalizes tuple, scalar, and Vector2-shaped repeats', () => {
+        expect(resolveTextureRepeat([2, 3], undefined)).toEqual([2, 3]);
+        expect(resolveTextureRepeat(2, undefined)).toEqual([2, 2]);
+        expect(resolveTextureRepeat({ x: 2, y: 3 }, undefined)).toEqual([2, 3]);
+    });
+    test('falls back to scale for malformed repeats', () => {
+        expect(resolveTextureRepeat({ width: 2 }, 4)).toEqual([4, 4]);
+    });
+    test('keeps distinct Vector2-shaped repeats in distinct cache entries', () => {
+        expect(getTextureKey(materialWithRepeat({ x: 2, y: 3 }))).not.toBe(getTextureKey(materialWithRepeat({ x: 4, y: 5 })));
+    });
+});

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merged-outline-node.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merged-outline-node.test.d.ts","sourceRoot":"","sources":["../../src/lib/merged-outline-node.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,22 @@
+// @ts-expect-error — bun:test is provided by the Bun runtime; viewer does not
+// depend on @types/bun so the import type is unresolved at compile time.
+import { describe, expect, test } from 'bun:test';
+import { Object3D, PerspectiveCamera, Scene } from 'three';
+import { mergedOutline } from './merged-outline-node';
+describe('merged outline rendering', () => {
+    test('keeps selected outlines active during camera interaction', () => {
+        const cameraInteractionActive = true;
+        const params = {
+            enabled: () => !cameraInteractionActive,
+            primaryObjects: [new Object3D()],
+        };
+        const outline = mergedOutline(new Scene(), new PerspectiveCamera(), params);
+        const frame = {
+            get renderer() {
+                throw new Error('outline renderer was reached');
+            },
+        };
+        expect(() => outline.updateBefore(frame)).toThrow('outline renderer was reached');
+        outline.dispose();
+    });
+});

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

@@ -4,6 +4,7 @@ export type SceneTheme = {
     name: string;
     appearance: 'light' | 'dark';
     background: string;
+    backgroundSky?: string;
     ground: string;
     ambient: {
         color: string;