@pascal-app/viewer 0.8.0 → 0.9.2

package/dist/lib/drawable-geometry.js

@@ -0,0 +1,22 @@
+/**
+ * True when `geometry` has a bound, non-empty `position` attribute — i.e. it is
+ * safe to submit to the WebGPU renderer.
+ *
+ * A geometry whose `position` attribute has `count === 0` (or no `position` at
+ * all) leaves WebGPU **vertex buffer slot 0 unbound**. The validator rejects the
+ * draw with "Vertex buffer slot 0 … was not set", and — critically — that single
+ * rejected draw **poisons the entire command encoder**: every other draw in the
+ * frame (the whole scene + every editor overlay) is discarded on the next queue
+ * submit ("Invalid CommandBuffer"). The visible result is the whole canvas
+ * flickering/garbling, not just the offending mesh.
+ *
+ * Individual call-sites guard against *creating* empty geometry (see
+ * `createPlaceholderGeometry`, the ceiling/door degenerate fallbacks, etc.), but
+ * transient/derived geometries can still slip through. This predicate is the
+ * renderer-level safety net: skipping a count-0 draw is a no-op visually (it
+ * would draw nothing anyway) while keeping the command encoder healthy.
+ */
+export function hasDrawableGeometry(geometry) {
+    const position = geometry?.attributes?.position;
+    return Boolean(position && position.count > 0);
+}

package/dist/lib/edge-style.d.ts

@@ -0,0 +1,4 @@
+export type EdgeMode = 'off' | 'soft' | 'strong';
+export declare function edgeColorFor(background: string): string;
+export declare function edgeOpacityScaleFor(background: string): number;
+//# sourceMappingURL=edge-style.d.ts.map

package/dist/lib/edge-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-style.d.ts","sourceRoot":"","sources":["../../src/lib/edge-style.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;AAgBhD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAWvD;AAID,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/lib/edge-style.js

@@ -0,0 +1,31 @@
+function lumaOf(background) {
+    const hex = background.replace('#', '');
+    const r = Number.parseInt(hex.slice(0, 2), 16) / 255;
+    const g = Number.parseInt(hex.slice(2, 4), 16) / 255;
+    const b = Number.parseInt(hex.slice(4, 6), 16) / 255;
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+// Ink line colour follows background luminance — light backgrounds get
+// near-black lines (the rule Mapbox uses for label outlines). Dark backgrounds
+// get a tint *derived from the background* rather than a near-white constant:
+// full-white lines glow harshly against night/twilight scenes, while lifting
+// the background's own hue toward white stays legible but reads native to the
+// theme.
+export function edgeColorFor(background) {
+    if (lumaOf(background) > 0.5)
+        return '#1a1d24';
+    const hex = background.replace('#', '');
+    let out = '#';
+    for (let i = 0; i < 3; i++) {
+        const c = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16) / 255;
+        out += Math.round((c + (1 - c) * 0.42) * 255)
+            .toString(16)
+            .padStart(2, '0');
+    }
+    return out;
+}
+// Dark scenes additionally run the ink slightly transparent — even a muted
+// tint at full alpha reads as glowing wireframe against a low-luma backdrop.
+export function edgeOpacityScaleFor(background) {
+    return lumaOf(background) > 0.5 ? 1 : 0.7;
+}

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +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"}

package/dist/lib/gpu-perf.js

@@ -0,0 +1,23 @@
+// GPU work-time measurement, gated by `?perf` in the URL.
+//
+// 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.
+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/ink-edges.d.ts

@@ -0,0 +1,9 @@
+export declare function inkedEdges({ depthTex, normalTex, inkColor, radius, opacity, sceneRgb, }: {
+    depthTex: any;
+    normalTex: any;
+    inkColor: any;
+    radius: number;
+    opacity: any;
+    sceneRgb: any;
+}): any;
+//# sourceMappingURL=ink-edges.d.ts.map

package/dist/lib/ink-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ink-edges.d.ts","sourceRoot":"","sources":["../../src/lib/ink-edges.ts"],"names":[],"mappings":"AAoBA,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,MAAM,EACN,OAAO,EACP,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,GAAG,CAAA;IACb,SAAS,EAAE,GAAG,CAAA;IACd,QAAQ,EAAE,GAAG,CAAA;IAKb,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,GAAG,CAAA;IACZ,QAAQ,EAAE,GAAG,CAAA;CACd,OAsCA"}

package/dist/lib/ink-edges.js

@@ -0,0 +1,49 @@
+import { abs, float, max, min, mix, screenSize, screenUV, smoothstep, vec2 } from 'three/tsl';
+import { unpackRGBToNormal } from './tsl-compat';
+// Screen-space ink outline (SketchUp / Moebius look). Reads the scene-pass
+// depth + normal MRT and inks two signals:
+//
+//   1. Crease  — center normal vs each neighbour (`1 - dot`): 0 on a flat
+//      surface, ~1 at a 90° corner. Catches wall↔roof, wall↔wall and window-
+//      reveal creases. Normals are re-normalized because the 8-bit normal MRT
+//      decodes to non-unit vectors, which otherwise crushes the signal.
+//   2. Depth   — raw-depth Laplacian (screen-linear across planes → ~0 on flat
+//      ground, no banding) normalized by (1 - depth)² so it becomes ≈
+//      worldStep / near, i.e. DISTANCE-INDEPENDENT (a window reveal reads the
+//      same zoomed in or out). A raw-Laplacian gate rejects flat-plane
+//      quantization noise so the far ground/roof never inks.
+//
+// Topology-agnostic: works on CSG triangle soup, organic GLBs, anything — it
+// only sees the rendered buffers. `intensity` scales the final mask; `inkColor`
+// should track the background luminance (dark lines on light scenes).
+export function inkedEdges({ depthTex, normalTex, inkColor, radius, opacity, sceneRgb, }) {
+    const px = vec2(1, 1).div(screenSize).mul(radius);
+    const uvN = screenUV;
+    const dC = depthTex.sample(uvN).r;
+    const dR = depthTex.sample(uvN.add(vec2(px.x, 0))).r;
+    const dL = depthTex.sample(uvN.sub(vec2(px.x, 0))).r;
+    const dU = depthTex.sample(uvN.add(vec2(0, px.y))).r;
+    const dD = depthTex.sample(uvN.sub(vec2(0, px.y))).r;
+    const depthLap = abs(dR.add(dL).add(dU).add(dD).sub(dC.mul(4)));
+    const invDepth = float(1).sub(dC);
+    const depthMetric = depthLap.div(invDepth.mul(invDepth).add(float(0.00002)));
+    const noiseGate = smoothstep(float(0.00002), float(0.00006), depthLap);
+    // ≈ metres of step / near (near≈0.1): ~5cm starts a line, ~25cm solid.
+    const depthEdge = smoothstep(float(0.5), float(2.5), depthMetric).mul(noiseGate);
+    const nC = unpackRGBToNormal(normalTex.sample(uvN)).normalize();
+    const nR = unpackRGBToNormal(normalTex.sample(uvN.add(vec2(px.x, 0)))).normalize();
+    const nL = unpackRGBToNormal(normalTex.sample(uvN.sub(vec2(px.x, 0)))).normalize();
+    const nU = unpackRGBToNormal(normalTex.sample(uvN.add(vec2(0, px.y)))).normalize();
+    const nD = unpackRGBToNormal(normalTex.sample(uvN.sub(vec2(0, px.y)))).normalize();
+    // Ink is a near/mid-field affordance: fade it out with raw depth so the
+    // horizon (the infinite ground disc vanishing against the backdrop) and
+    // other far-field depth cliffs never draw a line across the sky junction.
+    // ~full ink below ≈150 m, none beyond ≈350 m (perspective near 0.1/far 1000).
+    const distanceFade = float(1).sub(smoothstep(float(0.9994), float(0.9998), dC));
+    const nDiff = max(max(float(1).sub(nC.dot(nR)), float(1).sub(nC.dot(nL))), max(float(1).sub(nC.dot(nU)), float(1).sub(nC.dot(nD))));
+    const normalEdge = smoothstep(float(0.01), float(0.05), nDiff);
+    // TSL's typed overloads are finicky across versions; the runtime is proven in
+    // the aesthetic sandbox, so cast at the mask/mix boundary.
+    const edgeMask = min(max(depthEdge, normalEdge).mul(opacity).mul(distanceFade), float(1));
+    return mix(sceneRgb, inkColor, edgeMask);
+}

package/dist/lib/isolation.d.ts

@@ -0,0 +1,39 @@
+import type { AnyNodeId } from '@pascal-app/core';
+import type { Object3D } from 'three';
+/** True while an isolation filter is applied (see {@link applyIsolation}). */
+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).
+ */
+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 disabling the {@link SCENE_LAYER} bit on the
+ * relevant `Object3D.layers` masks.
+ *
+ * Why layers instead of `obj.visible = false`? Three.js's visibility
+ * flag *cascades* — hiding a parent hides every descendant — so we
+ * can't hide a host wall while keeping a door rendered inside it.
+ * Layer masks are per-object and don't cascade: `WebGLRenderer
+ * .projectObject` skips objects whose layer mask doesn't intersect the
+ * camera's, but always recurses into their children. So we can disable
+ * `SCENE_LAYER` on the wall and the door (hosted under it in the
+ * scene graph) still renders, with its local position relative to the
+ * wall preserved automatically by the matrix walk.
+ *
+ * The original `layers.mask` is stashed under a private Symbol so
+ * {@link clearIsolation} can restore the exact prior state.
+ *
+ * Pass `null` to clear isolation (equivalent to calling
+ * {@link clearIsolation}).
+ */
+export declare function applyIsolation(ids: ReadonlyArray<AnyNodeId> | null): void;
+export declare function clearIsolation(): void;
+//# sourceMappingURL=isolation.d.ts.map

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

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

package/dist/lib/isolation.js

@@ -0,0 +1,103 @@
+'use client';
+import { sceneRegistry } from '@pascal-app/core';
+import { SCENE_LAYER } from './layers';
+// Marker on each Object3D we modify during isolation so we can restore
+// the original `layers.mask` bitfield. Stored under a `Symbol` so it
+// can't collide with any kind's own userData fields.
+const ORIGINAL_LAYERS = Symbol('isolation:original-layers');
+// Whether a subtree is currently isolated (some objects have SCENE_LAYER
+// disabled). Read by consumers that must not act on the partial view — e.g.
+// 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}). */
+export function isIsolationActive() {
+    return isolationActive;
+}
+/**
+ * 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).
+ */
+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) => {
+            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 disabling the {@link SCENE_LAYER} bit on the
+ * relevant `Object3D.layers` masks.
+ *
+ * Why layers instead of `obj.visible = false`? Three.js's visibility
+ * flag *cascades* — hiding a parent hides every descendant — so we
+ * can't hide a host wall while keeping a door rendered inside it.
+ * Layer masks are per-object and don't cascade: `WebGLRenderer
+ * .projectObject` skips objects whose layer mask doesn't intersect the
+ * camera's, but always recurses into their children. So we can disable
+ * `SCENE_LAYER` on the wall and the door (hosted under it in the
+ * scene graph) still renders, with its local position relative to the
+ * wall preserved automatically by the matrix walk.
+ *
+ * The original `layers.mask` is stashed under a private Symbol so
+ * {@link clearIsolation} can restore the exact prior state.
+ *
+ * Pass `null` to clear isolation (equivalent to calling
+ * {@link clearIsolation}).
+ */
+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,
+    // disable `SCENE_LAYER` on it and on every descendant — *except*
+    // descendants that are themselves in `keep` (a kept node nested under
+    // a non-kept host: the isolated door under the hidden wall).
+    for (const [, obj] of sceneRegistry.nodes) {
+        if (keep.has(obj))
+            continue;
+        hideRecursive(obj, keep);
+    }
+    isolationActive = true;
+}
+function hideRecursive(obj, keep) {
+    if (keep.has(obj))
+        return;
+    const carrier = obj;
+    if (carrier[ORIGINAL_LAYERS] === undefined) {
+        carrier[ORIGINAL_LAYERS] = obj.layers.mask;
+    }
+    obj.layers.disable(SCENE_LAYER);
+    for (const child of obj.children) {
+        hideRecursive(child, keep);
+    }
+}
+export function clearIsolation() {
+    // We don't know which objects were touched without re-walking, so
+    // walk every registered root + its descendants and restore any
+    // stashed original-mask. `traverse` is cheap and idempotent here.
+    for (const [, obj] of sceneRegistry.nodes) {
+        obj.traverse((child) => {
+            const carrier = child;
+            if (carrier[ORIGINAL_LAYERS] !== undefined) {
+                child.layers.mask = carrier[ORIGINAL_LAYERS];
+                delete carrier[ORIGINAL_LAYERS];
+            }
+        });
+    }
+    isolationActive = false;
+}

package/dist/lib/ktx2-loader.d.ts

@@ -0,0 +1,43 @@
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/**
+ * 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.
+ */
+declare class AlignmentSafeKTX2Loader extends KTX2Loader {
+    private rgbaFallback;
+    private fallbackLoader;
+    /** Both `load()` and GLTFLoader's KHR_texture_basisu path funnel through
+     *  this internal — overriding it covers every entry point. */
+    _createTexture(buffer: ArrayBuffer, config?: Record<string, unknown>): Promise<unknown>;
+    dispose(): 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 declare const ktx2Loader: AlignmentSafeKTX2Loader;
+/**
+ * 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 declare function whenKtx2Ready(): Promise<void>;
+/** Returns true once support has been detected for this renderer (KTX2 safe to load). */
+export declare function ensureKtx2Support(renderer: unknown): boolean;
+export declare function isKtx2Url(url: string): boolean;
+export {};
+//# sourceMappingURL=ktx2-loader.d.ts.map

package/dist/lib/ktx2-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-loader.d.ts","sourceRoot":"","sources":["../../src/lib/ktx2-loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAwBrE;;;;;;;;;;GAUG;AACH,cAAM,uBAAwB,SAAQ,UAAU;IAC9C,OAAO,CAAC,YAAY,CAA0B;IAE9C,OAAO,CAAC,cAAc;IAkBtB;kEAC8D;IACxD,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAmC7F,OAAO,IAAI,IAAI;CAMhB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,yBAAgC,CAAA;AAWvD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7C;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAkB5D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C"}

package/dist/lib/ktx2-loader.js

@@ -0,0 +1,136 @@
+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 isKtx2Url(url) {
+    return url.toLowerCase().endsWith('.ktx2');
+}

package/dist/lib/layers.d.ts

@@ -1,5 +1,33 @@
 /** Default Three.js layer for main scene geometry. */
 export declare const SCENE_LAYER = 0;
+/**
+ * Layer for editor-only overlays (gizmos, move handles, tool previews, grid).
+ * The post-processing pipeline excludes this layer from the depth/normal MRT
+ * scene pass so the screen-space ink and SSGI never treat overlays as geometry,
+ * then composites it back on top via a dedicated overlay pass.
+ *
+ * Editor's `EDITOR_LAYER` (packages/editor) re-exports this — they MUST match.
+ */
+export declare const OVERLAY_LAYER = 1;
 /** Layer used for zone rendering (floor fills and wall borders). */
 export declare const ZONE_LAYER = 2;
+/**
+ * Layer for the editor ground grid. Rendered *inside* the scene pass (so scene
+ * geometry depth-occludes it instead of it bleeding through walls/objects) — it
+ * is a flat, depth-non-writing plane, so the screen-space ink never picks it up.
+ * Kept off OVERLAY_LAYER because overlays composite on top with no scene-depth
+ * test, which is exactly what we don't want for a full-floor plane. Excluded
+ * 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,oEAAoE;AACpE,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

@@ -1,4 +1,32 @@
 /** Default Three.js layer for main scene geometry. */
 export const SCENE_LAYER = 0;
+/**
+ * Layer for editor-only overlays (gizmos, move handles, tool previews, grid).
+ * The post-processing pipeline excludes this layer from the depth/normal MRT
+ * scene pass so the screen-space ink and SSGI never treat overlays as geometry,
+ * then composites it back on top via a dedicated overlay pass.
+ *
+ * Editor's `EDITOR_LAYER` (packages/editor) re-exports this — they MUST match.
+ */
+export const OVERLAY_LAYER = 1;
 /** Layer used for zone rendering (floor fills and wall borders). */
 export const ZONE_LAYER = 2;
+/**
+ * Layer for the editor ground grid. Rendered *inside* the scene pass (so scene
+ * geometry depth-occludes it instead of it bleeding through walls/objects) — it
+ * is a flat, depth-non-writing plane, so the screen-space ink never picks it up.
+ * Kept off OVERLAY_LAYER because overlays composite on top with no scene-depth
+ * test, which is exactly what we don't want for a full-floor plane. Excluded
+ * 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,20 +1,43 @@
-import { type MaterialPresetPayload, type MaterialSchema } 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 { MeshStandardNodeMaterial } from 'three/webgpu';
-export declare const baseMaterial: MeshStandardNodeMaterial;
-export declare const glassMaterial: MeshStandardNodeMaterial;
+import { MeshLambertNodeMaterial } from 'three/webgpu';
+export type RenderShading = 'solid' | 'rendered';
+export type ColorPreset = 'clay' | 'white' | 'mono' | 'blueprint';
+export declare const CLAY_PALETTE: Record<SurfaceRole, string>;
+export declare const WHITE_PALETTE: Record<SurfaceRole, string>;
+export declare const MONO_PALETTE: Record<SurfaceRole, string>;
+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 applyMaterialPresetToMaterials(materialInput: THREE.Material | THREE.Material[], preset: MaterialPresetPayload | null | undefined): void;
-export declare function createMaterialFromPreset(preset: MaterialPresetPayload): THREE.MeshStandardMaterial;
-export declare function createMaterialFromPresetRef(materialPreset?: string): THREE.MeshStandardMaterial | null;
-export declare function createMaterial(material?: MaterialSchema): THREE.MeshStandardMaterial;
-export declare function createDefaultMaterial(color?: string, roughness?: number): THREE.MeshStandardMaterial;
-export declare const DEFAULT_WALL_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_SLAB_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_DOOR_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_WINDOW_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_CEILING_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_ROOF_MATERIAL: THREE.MeshStandardMaterial;
-export declare const DEFAULT_STAIR_MATERIAL: THREE.MeshStandardMaterial;
+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;
+export declare function DEFAULT_WALL_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_SLAB_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_DOOR_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_WINDOW_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_CEILING_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_ROOF_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_SHELF_MATERIAL(shading?: RenderShading): THREE.Material;
+export declare function DEFAULT_STAIR_MATERIAL(shading?: RenderShading): THREE.Material;
 export declare function disposeMaterial(material: THREE.Material): void;
 export declare function clearMaterialCache(): void;
 //# sourceMappingURL=materials.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../../src/lib/materials.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EAEpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAEvD,eAAO,MAAM,YAAY,0BAIvB,CAAA;AAEF,eAAO,MAAM,aAAa,0BAOxB,CAAA;AAkNF,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,GAC5B,KAAK,CAAC,oBAAoB,CAW5B;AAED,wBAAgB,2BAA2B,CACzC,cAAc,CAAC,EAAE,MAAM,GACtB,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAInC;AAED,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC,oBAAoB,CAsBpF;AAED,wBAAgB,qBAAqB,CACnC,KAAK,SAAY,EACjB,SAAS,SAAM,GACd,KAAK,CAAC,oBAAoB,CAO5B;AAED,eAAO,MAAM,qBAAqB,4BAAwC,CAAA;AAC1E,eAAO,MAAM,qBAAqB,4BAAwC,CAAA;AAC1E,eAAO,MAAM,qBAAqB,4BAAwC,CAAA;AAC1E,eAAO,MAAM,uBAAuB,4BAOlC,CAAA;AACF,eAAO,MAAM,wBAAwB,4BAAyC,CAAA;AAC9E,eAAO,MAAM,qBAAqB,4BAAyC,CAAA;AAC3E,eAAO,MAAM,sBAAsB,4BAAwC,CAAA;AAE3E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAE9D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAWzC"}
+{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../../src/lib/materials.ts"],"names":[],"mappings":"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"}