@pascal-app/viewer 1.0.4 → 1.0.6

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/pointer-events.d.ts

@@ -1,15 +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 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.
+ * 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): boolean;
-export declare function createPascalPointerEvents(store: RootStore): EventManager<HTMLElement>;
+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;AAiED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,OAAO,CAUrE;AAkHD,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"}

package/dist/lib/pointer-events.js

@@ -21,11 +21,12 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  *
- * Vendored from R3F 9.8.1:
- * https://raw.githubusercontent.com/pmndrs/react-three-fiber/v9.8.1/packages/fiber/src/core/events.ts
+ * Vendored from R3F 9.8.2:
+ * https://raw.githubusercontent.com/pmndrs/react-three-fiber/v9.8.2/packages/fiber/src/core/events.ts
  * Ray collection is cached; camera-drag moves are throttled before stock dispatch.
  * The throttle is a vendored-manager policy; dev ?stockEvents uses untouched R3F.
  */
+import { sceneRegistry, useScene } from '@pascal-app/core';
 import { events as createWebEvents, getRootState, } from '@react-three/fiber';
 import * as THREE from 'three';
 import { acceleratedRaycast } from 'three-mesh-bvh';
@@ -61,10 +62,10 @@ function isSupportedRaycast(raycast) {
         supportedRaycasts.has(raycast) ||
         raycast[pureRaycast] === true);
 }
-export function choosePointerEvents(search = typeof window !== 'undefined' ? window.location.search : '') {
+export function choosePointerEvents(search = typeof window !== 'undefined' ? window.location.search : '', onBreadcrumb) {
     return process.env.NODE_ENV !== 'production' && new URLSearchParams(search).has('stockEvents')
         ? createWebEvents
-        : createPascalPointerEvents;
+        : (store) => createPascalPointerEvents(store, onBreadcrumb);
 }
 function querySnapshot(raycaster) {
     if (Object.getPrototypeOf(raycaster) !== THREE.Raycaster.prototype ||
@@ -117,13 +118,13 @@ function querySnapshot(raycaster) {
  * 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.
+ * pointer event down; its children are still tested. `material` asks the same of
+ * an array the mesh would wear.
  */
-export function hasMaterialsForGroups(object) {
+export function hasMaterialsForGroups(object, material = object.material) {
     const mesh = object;
     if (!mesh.isMesh)
         return true;
-    const material = mesh.material;
     if (!material)
         return false;
     if (!Array.isArray(material))
@@ -137,7 +138,67 @@ export function hasMaterialsForGroups(object) {
 function distanceOrder(a, b) {
     return a.distance - b.distance;
 }
-function createCachedRaycast() {
+/** The scene node `object` draws for: itself or its nearest registered ancestor. */
+function owningNode(object) {
+    const owners = new Map();
+    for (const [id, registered] of sceneRegistry.nodes)
+        owners.set(registered, id);
+    for (let at = object; at; at = at.parent) {
+        const id = owners.get(at);
+        if (id === undefined)
+            continue;
+        const node = useScene.getState().nodes[id];
+        return { id, type: node?.type ?? null };
+    }
+    return null;
+}
+/**
+ * Reports each mesh a pointer raycast skips for groups with no material, once
+ * per material it wears: pointer moves would otherwise repeat it every frame.
+ */
+function createInvalidMaterialReporter(onBreadcrumb) {
+    const reported = new WeakMap();
+    return (object) => {
+        const material = object.material;
+        if (!onBreadcrumb || (reported.has(object) && reported.get(object) === material))
+            return;
+        reported.set(object, material);
+        const node = owningNode(object);
+        onBreadcrumb({
+            category: 'raycast_invalid_material',
+            message: 'Pointer raycast skipped a mesh whose geometry groups have no material',
+            level: 'warning',
+            data: { nodeType: node?.type ?? null, nodeId: node?.id ?? null, objectName: object.name },
+        });
+    };
+}
+/**
+ * Three's recursive `intersectObject`, skipping meshes `hasMaterialsForGroups`
+ * rejects. A raycaster with its own `intersectObject` is asked directly.
+ */
+export function intersectDrawable(raycaster, object, skip) {
+    if (raycaster.intersectObject !== stockIntersectObject) {
+        return raycaster.intersectObject(object, true);
+    }
+    const hits = [];
+    const visit = (current) => {
+        let result;
+        if (current.layers.test(raycaster.layers)) {
+            if (hasMaterialsForGroups(current))
+                result = current.raycast(raycaster, hits);
+            else
+                skip(current);
+        }
+        if (result === false)
+            return;
+        const children = current.children;
+        for (let i = 0, length = children.length; i < length; i++)
+            visit(children[i]);
+    };
+    visit(object);
+    return hits.sort(distanceOrder);
+}
+function createCachedRaycast(skip) {
     const queries = new WeakMap();
     const activeQueries = [];
     const rootHits = [];
@@ -164,6 +225,8 @@ function createCachedRaycast() {
             }
             if (hasMaterialsForGroups(object))
                 result = object.raycast(raycaster, hits);
+            else
+                skip(object);
         }
         if (result !== false) {
             const children = object.children;
@@ -246,9 +309,9 @@ function createCachedRaycast() {
         },
     };
 }
-export function createPascalPointerEvents(store) {
+export function createPascalPointerEvents(store, onBreadcrumb) {
     const manager = createWebEvents(store);
-    const { handlePointer } = createEvents(store);
+    const { handlePointer } = createEvents(store, onBreadcrumb);
     for (const name of Object.keys(manager.handlers)) {
         manager.handlers[name] = handlePointer(name);
     }
@@ -269,7 +332,7 @@ export function createPascalPointerEvents(store) {
     return manager;
 }
 function makeId(event) {
-    // biome-ignore lint/style/useTemplate: Keep the vendored dispatch identical to R3F 9.8.1.
+    // biome-ignore lint/style/useTemplate: Keep the vendored dispatch identical to R3F 9.8.2.
     return (event.eventObject || event.object).uuid + '/' + event.index + event.instanceId;
 }
 /**
@@ -287,7 +350,8 @@ function releaseInternalPointerCapture(capturedMap, obj, captures, pointerId) {
         }
     }
 }
-function createEvents(store) {
+function createEvents(store, onBreadcrumb) {
+    const skipInvalidMaterial = createInvalidMaterialReporter(onBreadcrumb);
     const stats = {
         events: 0,
         cachedEvents: 0,
@@ -343,7 +407,7 @@ function createEvents(store) {
             // Make sure root-level pointer and ray are set up
             state.events.compute?.(event, state);
         }
-        collectors[collectionDepth] ??= createCachedRaycast();
+        collectors[collectionDepth] ??= createCachedRaycast(skipInvalidMaterial);
         const collector = collectors[collectionDepth++];
         let hits = [];
         let stock = false;
@@ -365,7 +429,7 @@ function createEvents(store) {
                 }
                 if (layer.raycaster.camera) {
                     const rootHits = stock
-                        ? layer.raycaster.intersectObject(obj, true)
+                        ? intersectDrawable(layer.raycaster, obj, skipInvalidMaterial)
                         : collector.intersectObject(obj, layer);
                     if (!rootHits) {
                         const unsupported = collector.unsupportedObject;

package/dist/lib/post-processing-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-processing-resources.d.ts","sourceRoot":"","sources":["../../src/lib/post-processing-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIlD,qBAAa,uBAAuB;IAClC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAO;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAK;IAChC,OAAO,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAO;IAC1C,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAO;IAEtC,OAAO;CAUR"}
+{"version":3,"file":"post-processing-resources.d.ts","sourceRoot":"","sources":["../../src/lib/post-processing-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIlD,qBAAa,uBAAuB;IAClC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAO;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAK;IAChC,OAAO,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAO;IAC1C,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAO;IAEtC,OAAO,SASN;CACF"}

package/dist/lib/reveal-candidates.d.ts

@@ -0,0 +1,80 @@
+import { type AnyNode, type AnyNodeId, type RevealStyle, type SceneCommit } from '@pascal-app/core';
+import type { RevealCandidate } from './reveal-schedule';
+import type { PlayedStyle } from './reveal-wipe';
+/**
+ * How much of the construction plays. `off` shows a build at once; `simple`
+ * keeps the scattered order with only `rise` and `scale`; `full` adds the
+ * falls, settles, cuts, assembled roofs and the dust. `framing` plays the
+ * same motions on the lazy, nested schedule (floor by floor, room by room,
+ * piece by piece; `planLazyReveal`), overdone a little, and plugins that stage
+ * their own members (the framing) read it and play them in the prerolls.
+ */
+export type ConstructionRevealLevel = 'off' | 'simple' | 'full' | 'framing';
+/** A candidate; for an assembled node's part, also the node it assembles. */
+export type StagedCandidate = RevealCandidate & {
+    host?: string;
+};
+/** A roof piece lifts this share of its drop before it falls: a hair, 20 cm of 4 m. */
+export declare const PART_LEAD = 0.05;
+/** `simple` keeps the stagger with only the two slice-one motions. */
+export declare function styleAt(style: RevealStyle, at: ConstructionRevealLevel): PlayedStyle;
+/** Kinds that hold the others: staging one would unmount everything under it. */
+export declare const CONTAINERS: ReadonlySet<string>;
+/**
+ * What `commit` stages at `at`: each node it creates whose kind declares a
+ * reveal, and the new parts (children declaring none) of each one that
+ * assembles. A new node of a kind that declares none comes in with a default
+ * reveal when what holds it was already there (under a new host, it comes in
+ * with the host). `seq` counts on from `firstSeq` in arrival order. Each
+ * candidate carries its room and its place in it (`layoutRevealCandidates`).
+ */
+export declare function commitRevealCandidates({ before, current, author }: SceneCommit, at: ConstructionRevealLevel, firstSeq?: number): StagedCandidate[];
+/**
+ * Gives each candidate its room for the lazy schedule: the room it stands in (a node on a line, the
+ * room on either side of its middle), else, for a node on a line, a run of the lines it meets end to
+ * end (`capabilities.revealLayout`); its room's
+ * sweep across the floor; and its place in the room (around the room's centre, or along the run).
+ * What stands in no room keeps none: it belongs to the floor.
+ */
+export declare function layoutRevealCandidates(candidates: StagedCandidate[], nodes: Record<AnyNodeId, AnyNode>): void;
+/** Where a piece stood in its level: its position, and its turn about the vertical. */
+export type Placement = {
+    position: [number, number, number];
+    yaw: number;
+};
+/**
+ * A piece changed by a commit. `from` is where a moved piece stood when it can glide from there, else
+ * null; `edited` marks a piece whose picture was edited (a wall bent, a slab resized), which plays its
+ * reveal again, quickly (`commitEditCandidates`).
+ */
+export type ChangeCandidate = StagedCandidate & {
+    from: Placement | null;
+    edited?: true;
+};
+/**
+ * What `commit` moves: each piece of furniture it finds already there that is placed differently
+ * (another position, turn or parent). Furniture only, for now: walls and openings move with the
+ * rooms and walls that hold them.
+ */
+export declare function commitChangeCandidates({ before, current, author }: SceneCommit, at: ConstructionRevealLevel, firstSeq?: number): ChangeCandidate[];
+/**
+ * What taking `ids` back reveals: each of them, and everything under them (a wall's openings, a
+ * room's furniture), as the build would have staged it: by what its kind declares, or the default
+ * reveal a kind that declares none came in with. What stands in a host that goes (a segment of a
+ * stair, a part of a pool) goes with it; an assembled node (a roof) goes whole, not part by part.
+ */
+export declare function nodeRevealCandidates(ids: Iterable<string>, nodes: Record<AnyNodeId, AnyNode>, at: ConstructionRevealLevel): RevealCandidate[];
+/**
+ * What `commit` edits: each node already there whose kind lists `capabilities.revealOnEdit` and one of
+ * those fields (the ones that make its picture) changed. A change to any other field stays instant, and
+ * so does what the structure reconciler derived from an edit (`derivedWrites`: the plates and ceilings it
+ * owns, the fields it wrote on a node): a wall moved does not make its room's floor rise again.
+ */
+export declare function commitEditCandidates({ before, current, author, derivedWrites }: SceneCommit, at: ConstructionRevealLevel, firstSeq?: number): ChangeCandidate[];
+/**
+ * What `commit` deletes that the picture can play out: each node that was there and is gone whose kind
+ * stages a reveal, as it was staged when built (a node standing in a host that goes with it goes with
+ * its host). Derived construction the reconciler retires is not a deletion the person or the agent made.
+ */
+export declare function commitDeleteCandidates({ before, current, author, derivedWrites }: SceneCommit, at: ConstructionRevealLevel, firstSeq?: number): StagedCandidate[];
+//# sourceMappingURL=reveal-candidates.d.ts.map

package/dist/lib/reveal-candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-candidates.d.ts","sourceRoot":"","sources":["../../src/lib/reveal-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,SAAS,EAMd,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAA;AAE3E,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjE,uFAAuF;AACvF,eAAO,MAAM,SAAS,OAAO,CAAA;AAE7B,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,uBAAuB,GAAG,WAAW,CAKpF;AAED,iFAAiF;AACjF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAA0C,CAAA;AAiFrF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EACxC,EAAE,EAAE,uBAAuB,EAC3B,QAAQ,SAAI,GACX,eAAe,EAAE,CA0CnB;AA2FD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAChC,IAAI,CAqEN;AAoED,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3E;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAmCzF;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EACxC,EAAE,EAAE,uBAAuB,EAC3B,QAAQ,SAAI,GACX,eAAe,EAAE,CAoBnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EACrB,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,uBAAuB,GAC1B,eAAe,EAAE,CAsBnB;AAgBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,WAAW,EACvD,EAAE,EAAE,uBAAuB,EAC3B,QAAQ,SAAI,GACX,eAAe,EAAE,CA4BnB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,WAAW,EACvD,EAAE,EAAE,uBAAuB,EAC3B,QAAQ,SAAI,GACX,eAAe,EAAE,CA4BnB"}