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

package/dist/shared/node-batch/system.js

@@ -0,0 +1,569 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { emitter, sceneRegistry, useInteractive, useLiveNodeOverrides, useLiveTransforms, useScene, } from '@pascal-app/core';
+import { getPendingWallRebuildCount, isIsolationActive, publishPerfBatchStats, registerMaterialCacheCleanup, useViewer, } from '@pascal-app/viewer';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useRef } from 'react';
+import { isSlotPaintPreviewActive, subscribeSlotPaintPreviews } from '../slot-paint';
+import { BATCH_KINDS, collectBatchCandidate, collectTintedNodes, getBatchableNodeIds, hideBatchedNode, revealAllBatchedHolds, revealBatchedNode, } from './candidates';
+import { NodeBatchStore } from './store';
+import { MIN_BATCH_ENTRIES, NODE_BATCH_SETTLE_MS } from './types';
+/**
+ * Orchestrates node draw-call batching (charter backlog #3a/#3b). Same shape
+ * as `../../wall/wall-batch-system.tsx`: membership follows the scene dirty
+ * signal, lit nodes draw themselves, appearance switches re-sew everything,
+ * and joins wait for a quiet window. The container differs — `NodeBatchStore`
+ * holds BatchedMeshes, so membership changes are instance add/deletes, not
+ * resews.
+ */
+const store = new NodeBatchStore((levelId) => sceneRegistry.nodes.get(levelId));
+/**
+ * Marks captured before the consuming systems (priority 2+) clear them — the
+ * walls' `drainRebuiltWalls` ledger, done from the outside: a priority-1 pass
+ * snapshots which nodes this frame touched. A dirty WALL cascades to its
+ * hosted doors/windows: the wall edit moves them in level space without
+ * marking them.
+ */
+const changedNodes = new Set();
+const surfaceLevelReadyAt = new Map();
+const staleNodes = new Set();
+/**
+ * Members whose wave joined only part of their meshes (the rest fell under
+ * MIN_BATCH_ENTRIES). `store.has` locks them out of later waves, so a new
+ * placement releases them for a full re-collect — the new copy may be what
+ * makes their leftover buckets viable.
+ */
+const partialNodes = new Set();
+/**
+ * Candidates whose whole wave fell under MIN_BATCH_ENTRIES. When a NEW
+ * leftover appears (the missing bucket-mate arriving late — it was deferred
+ * as selected/dirty/loading when its peers' wave ran), the whole set is
+ * re-offered in one wave so the bucket finally tallies together. A stable
+ * leftover set re-offers nothing, so genuinely small scenes stay quiet.
+ */
+const leftoverNodes = new Set();
+/** Last frame's batchable ids, for the add/remove diff below. */
+let knownNodeIds = null;
+// Probe-only counters (?perf sessions read them via __itemBatch).
+const waveDebug = { runs: 0, stale: 0, candidates: 0, joined: 0, nullCandidates: 0 };
+let lastNodeChangeAtMs = 0;
+let batchingSuspended = false;
+let lastLevelMode;
+let lastSelectedLevel;
+const lastAppearance = {
+    shading: undefined,
+    textures: undefined,
+    colorPreset: undefined,
+    sceneTheme: undefined,
+    materials: null,
+};
+// Same inputs as the wall batch: these re-resolve every batched node's
+// materials without marking a node (per-node paint goes through `node.slots`
+// → a dirty mark).
+function appearanceChanged() {
+    const viewer = useViewer.getState();
+    const materials = useScene.getState().materials;
+    if (lastAppearance.shading === viewer.shading &&
+        lastAppearance.textures === viewer.textures &&
+        lastAppearance.colorPreset === viewer.colorPreset &&
+        lastAppearance.sceneTheme === viewer.sceneTheme &&
+        lastAppearance.materials === materials) {
+        return false;
+    }
+    lastAppearance.shading = viewer.shading;
+    lastAppearance.textures = viewer.textures;
+    lastAppearance.colorPreset = viewer.colorPreset;
+    lastAppearance.sceneTheme = viewer.sceneTheme;
+    lastAppearance.materials = materials;
+    return true;
+}
+export function resetNodeBatchState() {
+    releaseAll();
+    changedNodes.clear();
+    surfaceLevelReadyAt.clear();
+    staleNodes.clear();
+    partialNodes.clear();
+    leftoverNodes.clear();
+    knownNodeIds = null;
+    lastNodeChangeAtMs = 0;
+    batchingSuspended = false;
+    lastLevelMode = undefined;
+    lastSelectedLevel = undefined;
+    lastAppearance.shading = undefined;
+    lastAppearance.textures = undefined;
+    lastAppearance.colorPreset = undefined;
+    lastAppearance.sceneTheme = undefined;
+    lastAppearance.materials = null;
+}
+// Membership truth for the ?perf panel's `batch` row — the panel cannot read
+// this package's store itself, and the per-pass multi-draw counters flip
+// between shadow/main/outline cameras.
+function publishBatchStats() {
+    const stats = store.stats();
+    publishPerfBatchStats({
+        items: stats.nodes,
+        instances: stats.instances,
+        containers: stats.batches,
+        releases: stats.releases,
+        joins: stats.joins,
+        geometryReplacements: stats.geometryReplacements,
+        overflowRebuilds: stats.overflowRebuilds,
+        geometryBytesCopied: stats.geometryBytesCopied,
+    });
+}
+function releaseNode(nodeId) {
+    partialNodes.delete(nodeId);
+    leftoverNodes.delete(nodeId);
+    store.release(nodeId);
+    revealBatchedNode(nodeId);
+}
+function releaseAll() {
+    for (const nodeId of [...store.nodeIds()])
+        releaseNode(nodeId);
+    store.disposeAll();
+    // Tracked refs can go stale when a system rebuilt a batched node's meshes;
+    // the sweep guarantees nothing stays draw-hidden after a full stand-down.
+    revealAllBatchedHolds();
+}
+export function subscribeBatchInteractions(invalidate) {
+    const changed = (nodeId) => {
+        const node = useScene.getState().nodes[nodeId];
+        if (!node || !BATCH_KINDS.has(node.type))
+            return;
+        releaseNode(nodeId);
+        changedNodes.add(nodeId);
+        invalidate();
+    };
+    const unsubscribeTransforms = useLiveTransforms.subscribe((state, previous) => {
+        for (const nodeId of state.transforms.keys()) {
+            if (!previous.transforms.has(nodeId))
+                changed(nodeId);
+        }
+        for (const nodeId of previous.transforms.keys()) {
+            if (!state.transforms.has(nodeId))
+                changed(nodeId);
+        }
+    });
+    const unsubscribePreviews = subscribeSlotPaintPreviews(changed);
+    const unsubscribeMaterials = registerMaterialCacheCleanup(() => {
+        releaseAll();
+        for (const nodeId of getBatchableNodeIds())
+            changedNodes.add(nodeId);
+        invalidate();
+    });
+    return () => {
+        unsubscribeTransforms();
+        unsubscribePreviews();
+        unsubscribeMaterials();
+    };
+}
+export function captureChangedNodes() {
+    const dirty = useScene.getState().dirtyNodes;
+    if (dirty.size === 0)
+        return;
+    const nodes = useScene.getState().nodes;
+    for (const id of dirty) {
+        const node = nodes[id];
+        if (!node)
+            continue;
+        if (BATCH_KINDS.has(node.type))
+            changedNodes.add(id);
+        else if (node.type === 'wall' && Array.isArray(node.children)) {
+            // The wall edit moved its openings in level space; their own marks may
+            // never come.
+            for (const childId of node.children) {
+                const child = nodes[childId];
+                if (child && (child.type === 'door' || child.type === 'window')) {
+                    changedNodes.add(childId);
+                }
+            }
+        }
+    }
+}
+export function runBatchFrame(invalidate, wakeRef) {
+    try {
+        processBatchFrame(invalidate, wakeRef);
+    }
+    finally {
+        store.flushReleases();
+        const emptyPending = store.pruneEmpty(performance.now(), new Set(surfaceLevelReadyAt.keys()), staleNodes.size > 0 ? lastNodeChangeAtMs + NODE_BATCH_SETTLE_MS : 0);
+        if (emptyPending && !wakeRef.current) {
+            wakeRef.current = setTimeout(() => {
+                wakeRef.current = null;
+                invalidate();
+            }, NODE_BATCH_SETTLE_MS + 20);
+        }
+        publishBatchStats();
+    }
+}
+function processBatchFrame(invalidate, wakeRef) {
+    const nodeIds = getBatchableNodeIds();
+    const frameNow = performance.now();
+    const sceneNodes = useScene.getState().nodes;
+    const draggingLevels = new Set();
+    for (const id of useLiveNodeOverrides.getState().overrides.keys()) {
+        const node = sceneNodes[id];
+        if (node?.type === 'wall' && node.parentId)
+            draggingLevels.add(node.parentId);
+    }
+    for (const level of draggingLevels)
+        surfaceLevelReadyAt.set(level, Infinity);
+    const wallsPending = getPendingWallRebuildCount() > 0;
+    for (const [level, readyAt] of surfaceLevelReadyAt) {
+        if (draggingLevels.has(level) || wallsPending)
+            surfaceLevelReadyAt.set(level, Infinity);
+        else if (readyAt === Infinity)
+            surfaceLevelReadyAt.set(level, frameNow + NODE_BATCH_SETTLE_MS);
+        else if (frameNow >= readyAt)
+            surfaceLevelReadyAt.delete(level);
+    }
+    let changed = changedNodes.size > 0;
+    // A level-subtree remount (thumbnail capture, tool-state swings) replaces
+    // the registry groups: batches die with the old groups and fresh sources
+    // mount with no hold. Detect it by parent identity and re-sew.
+    for (const nodeId of store.pruneDetached()) {
+        releaseNode(nodeId);
+        staleNodes.add(nodeId);
+        changed = true;
+    }
+    for (const nodeId of changedNodes) {
+        releaseNode(nodeId);
+        staleNodes.add(nodeId);
+    }
+    changedNodes.clear();
+    const viewer = useViewer.getState();
+    if (lastLevelMode !== viewer.levelMode || lastSelectedLevel !== viewer.selection.levelId) {
+        lastLevelMode = viewer.levelMode;
+        lastSelectedLevel = viewer.selection.levelId;
+        // Shadow-only sources were rejected and dropped from the previous join wave.
+        for (const nodeId of nodeIds)
+            if (!store.has(nodeId))
+                staleNodes.add(nodeId);
+        changed = true;
+    }
+    const tinted = collectTintedNodes(nodeIds);
+    for (const nodeId of tinted) {
+        if (!store.has(nodeId))
+            continue;
+        releaseNode(nodeId);
+        staleNodes.add(nodeId);
+        changed = true;
+    }
+    // A live override on a batched node — a collaborator's remote drag, a
+    // programmatic move — has no local selection to tint it; the batch copy
+    // would freeze at the join pose while the real meshes move.
+    for (const nodeId of useLiveNodeOverrides.getState().overrides.keys()) {
+        if (!store.has(nodeId))
+            continue;
+        releaseNode(nodeId);
+        staleNodes.add(nodeId);
+        changed = true;
+    }
+    // A door/window whose animation record just appeared must draw its own
+    // meshes for the tween — the batch copy would hold the pre-swing pose. The
+    // candidate filter keeps it out while the record lives; the completion
+    // dirty mark re-stales it at the settled pose.
+    const interactive = useInteractive.getState();
+    for (const animated of [interactive.doorAnimations, interactive.windowAnimations]) {
+        for (const nodeId of Object.keys(animated)) {
+            if (!store.has(nodeId))
+                continue;
+            releaseNode(nodeId);
+            staleNodes.add(nodeId);
+            changed = true;
+        }
+    }
+    if (appearanceChanged()) {
+        releaseAll();
+        for (const nodeId of nodeIds)
+            staleNodes.add(nodeId);
+        changed = true;
+    }
+    // Deleted nodes carry no mark of their own, so membership is diffed by id
+    // against last frame's registry — a size comparison would miss a same-size
+    // add-and-remove (compound undo, paste-replace) and leave the removed
+    // node's instances drawing as ghosts.
+    if (knownNodeIds === null) {
+        for (const nodeId of nodeIds)
+            staleNodes.add(nodeId);
+        changed = true;
+    }
+    else {
+        for (const nodeId of knownNodeIds) {
+            if (nodeIds.has(nodeId))
+                continue;
+            if (store.has(nodeId))
+                releaseNode(nodeId);
+            staleNodes.delete(nodeId);
+            changed = true;
+        }
+        let added = false;
+        for (const nodeId of nodeIds) {
+            if (knownNodeIds.has(nodeId) || store.has(nodeId))
+                continue;
+            staleNodes.add(nodeId);
+            added = true;
+            changed = true;
+        }
+        // A newly placed copy can be what pushes an under-threshold bucket over
+        // MIN_BATCH_ENTRIES — earlier copies were dropped from staleNodes when
+        // their wave came up short, so re-stale everything unbatched, and release
+        // partial members so their leftover meshes get re-offered too.
+        if (added) {
+            for (const nodeId of nodeIds) {
+                if (!store.has(nodeId))
+                    staleNodes.add(nodeId);
+            }
+            for (const nodeId of [...partialNodes]) {
+                releaseNode(nodeId);
+                staleNodes.add(nodeId);
+            }
+        }
+    }
+    knownNodeIds = nodeIds;
+    // Isolation hides everything outside the focused subtree; batches hang off
+    // level roots and would go dark with them, leaving members drawn by nobody
+    // when a batched node is the focus. Stand down entirely, re-sew after.
+    const suspended = isIsolationActive();
+    if (suspended !== batchingSuspended) {
+        batchingSuspended = suspended;
+        releaseAll();
+        staleNodes.clear();
+        if (!suspended)
+            for (const nodeId of nodeIds)
+                staleNodes.add(nodeId);
+        changed = true;
+    }
+    if (batchingSuspended) {
+        staleNodes.clear();
+        return;
+    }
+    const now = performance.now();
+    if (changed)
+        lastNodeChangeAtMs = now;
+    if (staleNodes.size === 0)
+        return;
+    const settled = !changed && now - lastNodeChangeAtMs >= NODE_BATCH_SETTLE_MS;
+    if (!settled) {
+        if (wakeRef.current)
+            clearTimeout(wakeRef.current);
+        wakeRef.current = setTimeout(() => {
+            wakeRef.current = null;
+            invalidate();
+        }, NODE_BATCH_SETTLE_MS + 20);
+        return;
+    }
+    const dirty = useScene.getState().dirtyNodes;
+    const candidates = [];
+    // A lit or still-dirty node is deferred, not dropped — it must rejoin once
+    // the tint lifts or the mark drains, and nothing later would re-stale it.
+    const deferred = new Set();
+    waveDebug.runs++;
+    waveDebug.stale = staleNodes.size;
+    waveDebug.nullCandidates = 0;
+    const overrides = useLiveNodeOverrides.getState();
+    for (const nodeId of staleNodes) {
+        if (store.has(nodeId))
+            continue;
+        // Overrides defer like tint/dirt — an in-flight gesture ends with a
+        // commit whose mark re-offers the node; dropping it here would strand it.
+        if (((sceneNodes[nodeId]?.type === 'slab' ||
+            sceneNodes[nodeId]?.type === 'ceiling') &&
+            (wallsPending ||
+                surfaceLevelReadyAt.has(sceneNodes[nodeId].parentId ?? ''))) ||
+            tinted.has(nodeId) ||
+            dirty.has(nodeId) ||
+            overrides.get(nodeId) !== undefined ||
+            useLiveTransforms.getState().get(nodeId) !== undefined ||
+            isSlotPaintPreviewActive(nodeId)) {
+            deferred.add(nodeId);
+            continue;
+        }
+        const candidate = collectBatchCandidate(nodeId);
+        if (candidate)
+            candidates.push(candidate);
+        else
+            waveDebug.nullCandidates++;
+    }
+    waveDebug.candidates = candidates.length;
+    // Hide exactly what the store took — an entry it skipped (below the
+    // new-batch threshold, rejected geometry, missing level root) must keep
+    // drawing itself.
+    const joined = store.join(candidates, MIN_BATCH_ENTRIES);
+    waveDebug.joined = joined.length;
+    const joinedByNode = new Map();
+    for (const entry of joined) {
+        const bucket = joinedByNode.get(entry.nodeId);
+        if (bucket)
+            bucket.push(entry);
+        else
+            joinedByNode.set(entry.nodeId, [entry]);
+    }
+    let newLeftovers = false;
+    for (const candidate of candidates) {
+        if (!joinedByNode.has(candidate.nodeId)) {
+            if (!leftoverNodes.has(candidate.nodeId))
+                newLeftovers = true;
+            leftoverNodes.add(candidate.nodeId);
+        }
+    }
+    for (const candidate of candidates) {
+        const joinedEntries = joinedByNode.get(candidate.nodeId);
+        if (!joinedEntries)
+            continue;
+        leftoverNodes.delete(candidate.nodeId);
+        hideBatchedNode({
+            nodeId: candidate.nodeId,
+            levelId: candidate.levelId,
+            entries: joinedEntries,
+        });
+        if (joinedEntries.length < candidate.entries.length)
+            partialNodes.add(candidate.nodeId);
+    }
+    staleNodes.clear();
+    for (const nodeId of deferred)
+        staleNodes.add(nodeId);
+    // A new leftover may be the bucket-mate its peers were missing — re-offer
+    // the whole set together next wave.
+    if (newLeftovers)
+        for (const nodeId of leftoverNodes)
+            staleNodes.add(nodeId);
+    if (deferred.size > 0) {
+        if (wakeRef.current)
+            clearTimeout(wakeRef.current);
+        wakeRef.current = setTimeout(() => {
+            wakeRef.current = null;
+            invalidate();
+        }, NODE_BATCH_SETTLE_MS + 20);
+    }
+}
+// The headless bake/thumbnail worker loads `?disable=draw` pages: one capture,
+// no interactive frames — batching there only risks the export (sources are
+// layer-held exactly when the clone happens) and wins nothing.
+const DRAW_DISABLED = typeof window !== 'undefined' &&
+    new Set((new URLSearchParams(window.location.search).get('disable') ?? '')
+        .split(',')
+        .map((s) => s.trim())).has('draw');
+export const NodeBatchSystem = () => {
+    if (DRAW_DISABLED)
+        return null;
+    return _jsx(NodeBatchSystemActive, {});
+};
+const NodeBatchSystemActive = () => {
+    const invalidate = useThree((state) => state.invalidate);
+    const wakeRef = useRef(null);
+    useEffect(() => subscribeBatchInteractions(invalidate), [invalidate]);
+    // Before the consuming systems (priority 2+) clear the marks this frame.
+    useFrame(captureChangedNodes, 1);
+    useFrame(() => runBatchFrame(invalidate, wakeRef), 5);
+    // GLB export / thumbnail capture clones the live scene and prunes anything
+    // off the scene layer — exactly where batched sources sit. Hand every node
+    // its own meshes back before the clone; the settle window re-sews after.
+    useEffect(() => {
+        const restoreForCapture = () => {
+            for (const nodeId of [...store.nodeIds()]) {
+                releaseNode(nodeId);
+                staleNodes.add(nodeId);
+            }
+            store.disposeAll();
+            revealAllBatchedHolds();
+            lastNodeChangeAtMs = performance.now();
+        };
+        emitter.on('thumbnail:before-capture', restoreForCapture);
+        return () => {
+            emitter.off('thumbnail:before-capture', restoreForCapture);
+        };
+    }, []);
+    // Scripted-probe hook, ?perf sessions only (mirrors __pascalPerf).
+    useEffect(() => {
+        if (!new URLSearchParams(window.location.search).has('perf'))
+            return;
+        const probe = {
+            stats: () => store.stats(),
+            staleCount: () => staleNodes.size,
+            lastChangeAgoMs: () => performance.now() - lastNodeChangeAtMs,
+            has: (nodeId) => store.has(nodeId),
+            ids: () => [...store.nodeIds()],
+            hovered: () => useViewer.getState().hoveredId ?? null,
+            wave: () => ({ ...waveDebug }),
+            releaseAllNow: () => {
+                releaseAll();
+                publishBatchStats();
+            },
+            staleAllNow: () => {
+                for (const nodeId of getBatchableNodeIds())
+                    staleNodes.add(nodeId);
+            },
+            batchRender: () => {
+                const out = [];
+                for (const levelId of sceneRegistry.byType.level ?? []) {
+                    const root = sceneRegistry.nodes.get(levelId);
+                    root?.traverse((child) => {
+                        if (child.name !== 'item-batch')
+                            return;
+                        let chain = true;
+                        let walker = child;
+                        let top = child;
+                        while (walker) {
+                            if (walker.visible === false)
+                                chain = false;
+                            top = walker;
+                            walker = walker.parent;
+                        }
+                        const b = child;
+                        out.push({
+                            segments: b._multiDrawCount ?? -1,
+                            visibleChain: chain && top.isScene === true,
+                            instances: b._maxInstanceCount ?? -1,
+                        });
+                    });
+                }
+                return out;
+            },
+            // Emits the real capture event and reports what is still draw-hidden
+            // afterwards — a nonzero heldSources here is exactly what the GLB
+            // exporter would prune.
+            simulateCapture: () => {
+                emitter.emit('thumbnail:before-capture', undefined);
+                let batchMeshes = 0;
+                const heldMeshes = [];
+                for (const levelId of sceneRegistry.byType.level ?? []) {
+                    const root = sceneRegistry.nodes.get(levelId);
+                    root?.traverse((child) => {
+                        if (child.name === 'item-batch')
+                            batchMeshes++;
+                        else if (child.isMesh && !child.layers.isEnabled(0)) {
+                            heldMeshes.push(`${child.name || '?'}`);
+                        }
+                    });
+                }
+                return { batchMeshes, held: heldMeshes.length, heldNames: heldMeshes.slice(0, 20) };
+            },
+            sceneCensus: () => {
+                let batchMeshes = 0;
+                let heldSources = 0;
+                for (const levelId of sceneRegistry.byType.level ?? []) {
+                    const root = sceneRegistry.nodes.get(levelId);
+                    root?.traverse((child) => {
+                        if (child.name === 'item-batch')
+                            batchMeshes++;
+                        else if (child.isMesh && !child.layers.isEnabled(0)) {
+                            heldSources++;
+                        }
+                    });
+                }
+                return { batchMeshes, heldSources };
+            },
+        };
+        window.__itemBatch = probe;
+        return () => {
+            delete window.__itemBatch;
+        };
+    }, []);
+    useEffect(() => () => {
+        if (wakeRef.current)
+            clearTimeout(wakeRef.current);
+        resetNodeBatchState();
+    }, []);
+    return null;
+};

package/dist/shared/node-batch/types.d.ts

@@ -0,0 +1,99 @@
+import type { BufferGeometry, Material, Matrix4, Mesh, Object3D } from 'three';
+/**
+ * Contract for node draw-call batching (charter backlog #3a/#3b).
+ *
+ * Mirrors the wall-batch architecture (`../../wall/wall-batch-system.tsx`)
+ * with one structural upgrade: the container is a `THREE.BatchedMesh` per
+ * `(levelId, material, attribute-signature, castShadow, receiveShadow)`;
+ * membership changes are incremental instance adds/deletes.
+ *
+ * Batched kinds: items, columns, ceilings and slabs (level-parented), doors
+ * and windows (wall-hosted, resolved to the host wall's level). Walls keep
+ * their own merged-geometry batch and cutaway lifecycle.
+ *
+ * Invariants every module must respect:
+ * - Source meshes STAY MOUNTED. They are draw-hidden via
+ *   `hideFromScene(mesh, 'batched')` while batched; picking, measuring,
+ *   outlines and the GLB exporter keep working through them. Batch meshes
+ *   are draw-only: `raycast` is a noop, name is `'item-batch'`.
+ * - Batch meshes are parented under the LEVEL ROOT, so level visibility and
+ *   isolation cull batches exactly like every other level child.
+ * - A tinted node (selected, externally selected, preview-selected or hovered)
+ *   is released and draws itself, as do hosted openings whose host wall is
+ *   tinted or mid-gesture.
+ * - Membership follows the scene dirty signal + the node-count tell; a batch
+ *   never chases per-frame transforms. Live transforms and slot paint previews
+ *   release sources until they end. A dirty host wall releases its
+ *   openings (their level-space transforms move with the wall).
+ * - Doors/windows with an active animation record are excluded while it
+ *   runs; the completion dirty mark re-joins them at the settled pose.
+ */
+/** One batchable mesh of one node. */
+export type BatchEntry = {
+    nodeId: string;
+    levelId: string;
+    /** Stable node/part identity for mutable surface geometry. */
+    allocationKey?: string;
+    /** Source mesh in the node's mounted subtree; draw-hidden while batched. */
+    mesh: Mesh;
+    geometry: BufferGeometry;
+    /**
+     * The mesh's resolved material — a shared/cached instance; its `uuid` is
+     * part of the batch key. Array-material meshes are not batchable.
+     */
+    material: Material;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    /** Source mesh world matrix expressed in level-root space, captured at join. */
+    matrixInLevel: Matrix4;
+};
+/** Everything batchable about one node. `entries` empty ⇒ not batchable. */
+export type BatchCandidate = {
+    nodeId: string;
+    levelId: string;
+    entries: BatchEntry[];
+};
+export type NodeBatchStats = {
+    batches: number;
+    instances: number;
+    nodes: number;
+    releases: number;
+    joins: number;
+    geometryReplacements: number;
+    overflowRebuilds: number;
+    geometryBytesCopied: number;
+};
+/**
+ * Owns every BatchedMesh. Implementation in `store.ts`; consumed only by
+ * `system.tsx`.
+ */
+export type NodeBatchStoreApi = {
+    /**
+     * Adds a wave of candidates, growing/creating batches as needed, and
+     * returns the entries actually joined — the caller draw-hides exactly
+     * those meshes and no others. An EXISTING batch always accepts a matching
+     * entry (a released node must be able to rejoin alone); a NEW batch is
+     * only created when the wave brings at least `minEntriesForNewBatch`
+     * matching entries — below that, a batch trades plain draws for
+     * bookkeeping and wins nothing.
+     */
+    join(candidates: BatchCandidate[], minEntriesForNewBatch: number): BatchEntry[];
+    /** Hides draws immediately; deletion is coalesced by flushReleases. Caller reveals sources. */
+    release(nodeId: string): boolean;
+    flushReleases(now?: number): void;
+    pruneEmpty(now?: number, retainedLevels?: ReadonlySet<string>, earliestDisposalAt?: number): boolean;
+    /** Drops batches orphaned by a level-subtree remount; returns their nodes. */
+    pruneDetached(): Set<string>;
+    has(nodeId: string): boolean;
+    nodeIds(): ReadonlySet<string>;
+    /** Tears down every batch on a level (level deleted / isolation). */
+    disposeLevel(levelId: string): void;
+    disposeAll(): void;
+    stats(): NodeBatchStats;
+};
+export type GetLevelRoot = (levelId: string) => Object3D | undefined;
+/** A (level, material) bucket below this many entries is not worth a batch. */
+export declare const MIN_BATCH_ENTRIES = 3;
+/** Quiet window after the last node change before joins run (walls: 180). */
+export declare const NODE_BATCH_SETTLE_MS = 180;
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/node-batch/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shared/node-batch/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sCAAsC;AACtC,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,IAAI,EAAE,IAAI,CAAA;IACV,QAAQ,EAAE,cAAc,CAAA;IACxB;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,aAAa,EAAE,OAAO,CAAA;IACtB,gFAAgF;IAChF,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,UAAU,EAAE,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB,EAAE,MAAM,CAAA;IAC5B,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;OAQG;IACH,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,qBAAqB,EAAE,MAAM,GAAG,UAAU,EAAE,CAAA;IAC/E,+FAA+F;IAC/F,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,UAAU,CACR,GAAG,CAAC,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EACpC,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAA;IACV,8EAA8E;IAC9E,aAAa,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;IAC5B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IAC5B,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IAC9B,qEAAqE;IACrE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,UAAU,IAAI,IAAI,CAAA;IAClB,KAAK,IAAI,cAAc,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAA;AAEpE,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAClC,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,MAAM,CAAA"}

package/dist/shared/node-batch/types.js

@@ -0,0 +1,4 @@
+/** A (level, material) bucket below this many entries is not worth a batch. */
+export const MIN_BATCH_ENTRIES = 3;
+/** Quiet window after the last node change before joins run (walls: 180). */
+export const NODE_BATCH_SETTLE_MS = 180;