@expofp/renderer 3.2.5 → 3.27.1

package/dist/objects/images/texture-budget.js

@@ -0,0 +1,215 @@
+import { createContext, useEffect, useSyncExternalStore } from 'react';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('texture-budget');
+/** Bytes one RGBA texel occupies. */
+const BYTES_PER_PIXEL = 4;
+/**
+ * How much a full mipmap chain adds over the base level: the 1/4 + 1/16 + … geometric series sums to
+ * 1/3, so a mipmapped texture costs ~4/3 its base size. The atlas textures upload with mipmaps on
+ * (see `makeAtlasTexture`), so the budget counts them, or it would under-report GPU use by a third.
+ */
+const MIPMAP_FACTOR = 4 / 3;
+/** A megabyte, the unit `memoryLimit` is given in. */
+const BYTES_PER_MB = 1024 * 1024;
+/**
+ * How much the resize factor must move before subscribers are told. A change this small shifts an
+ * atlas edge by well under a pixel, so re-deriving every texture for it would be churn with no
+ * visible effect — the point of the gate is to keep a burst of atlas mounts, each nudging the total,
+ * from re-scaling the whole scene once per mount.
+ */
+const FACTOR_EPSILON = 1e-3;
+/**
+ * The GPU footprint of an atlas of the given pixel size: RGBA, with the mipmap chain counted. Reads
+ * the atlas's full (packed) dimensions — the resize factor scales this down, so budgeting against
+ * the full size is what the factor is solved from.
+ * @param width - Atlas width in pixels.
+ * @param height - Atlas height in pixels.
+ * @returns The size in bytes.
+ */
+export function getAtlasSizeBytes(width, height) {
+    return width * height * BYTES_PER_PIXEL * MIPMAP_FACTOR;
+}
+/**
+ * The scene's shared texture-memory budget. Every image atlas registers its full size here, and the
+ * store solves for one linear resize factor that brings the resizable atlases within `memoryLimit` —
+ * shared by all of them, so their relative sizes are preserved with no priority.
+ *
+ * The factor is exposed through `useSyncExternalStore`: an atlas that mounts, unmounts, or a limit
+ * that changes recomputes it, and a material move re-derives only the resizable atlases' textures —
+ * never a repack, since uv regions are normalized and so invariant to the canvas's pixel size.
+ * Recompute runs synchronously per registration; the render churn that would cause is left to
+ * React's automatic batching to coalesce, and the `FACTOR_EPSILON` gate keeps sub-pixel nudges from
+ * notifying at all. When no cap is set the whole apparatus stands down: {@link TextureBudget.isActive}
+ * is false, atlases skip registration entirely (see {@link useResizeFactor}), and the factor is 1.
+ */
+export class TextureBudget {
+    /** The cap in megabytes, or undefined/`0` for no cap — a falsy value scales nothing. */
+    memoryLimitMb;
+    /** Every registered atlas; the entry object is its own handle. */
+    atlases = new Set();
+    /** Subscribers to the resize factor — the mounted resizable atlases. */
+    listeners = new Set();
+    /** The current shared linear resize factor; `1` means no scaling. */
+    factor = 1;
+    /**
+     * @param memoryLimitMb - The cap in megabytes, or undefined/`0` for no cap.
+     */
+    constructor(memoryLimitMb) {
+        this.memoryLimitMb = memoryLimitMb;
+    }
+    /**
+     * Whether a cap is in force. False for an absent or zero limit — nothing can be compressed, so
+     * consumers skip the budget entirely rather than do work that resolves to "no scaling".
+     * @returns Whether a positive limit is set.
+     */
+    isActive() {
+        return !!this.memoryLimitMb;
+    }
+    /**
+     * Changes the cap. Called when the renderer's `memoryLimit` prop changes, so a caller can raise,
+     * lower, or clear it at runtime and the resizable atlases re-derive their textures live.
+     * @param memoryLimitMb - The new cap, or undefined/`0` for no cap.
+     */
+    setMemoryLimit(memoryLimitMb) {
+        if (memoryLimitMb === this.memoryLimitMb)
+            return;
+        const wasActive = this.isActive();
+        this.memoryLimitMb = memoryLimitMb;
+        if (this.isActive() !== wasActive) {
+            // The cap turned on or off: recompute and always notify, so every atlas hook re-runs to
+            // register or drop itself and re-reads the factor, even when its numeric value did not move.
+            this.factor = this.computeResizeFactor();
+            this.notify();
+        }
+        else {
+            this.recompute();
+        }
+    }
+    /**
+     * Registers one atlas's full size, recomputing the factor. Only called while {@link isActive}, so
+     * an uncapped scene never populates this set.
+     * @param entry - The atlas's dimensions and kind; pass the same object back to unregister.
+     */
+    register(entry) {
+        this.atlases.add(entry);
+        this.recompute();
+    }
+    /**
+     * Drops an atlas's contribution, recomputing the factor.
+     * @param entry - The object {@link register} was given.
+     */
+    unregister(entry) {
+        if (this.atlases.delete(entry))
+            this.recompute();
+    }
+    /**
+     * The current shared resize factor.
+     * @returns The factor in `(0, 1]`.
+     */
+    getResizeFactor() {
+        return this.factor;
+    }
+    /**
+     * Subscribes to factor and active-state changes.
+     * @param listener - Called when the factor moves past {@link FACTOR_EPSILON} or the cap toggles.
+     * @returns The unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Recomputes the factor and, if it moved materially, notifies subscribers. */
+    recompute() {
+        const next = this.computeResizeFactor();
+        if (Math.abs(next - this.factor) < FACTOR_EPSILON)
+            return;
+        this.factor = next;
+        this.notify();
+    }
+    /** Notifies every subscriber. */
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    /**
+     * Solves for the linear factor that fits the resizable atlases in the budget the fixed ones leave.
+     *
+     * Every degenerate case falls back to `1` — no scaling — rather than forcing a fit: no cap, nothing
+     * resizable to scale, or a cap the fixed atlases alone already exceed (canvases cannot be
+     * compressed, so there is nothing to give). The factor is only ever clamped up to `1`, never down
+     * to a floor: an image is scaled by however much the budget demands.
+     * @returns The factor in `(0, 1]`.
+     */
+    computeResizeFactor() {
+        // Silent: reached only when a cap is cleared at runtime, since an atlas never registers without
+        // one (see useResizeFactor, which logs the no-cap case at the point it skips the work).
+        if (!this.memoryLimitMb)
+            return 1;
+        let totalResizable = 0;
+        let totalFixed = 0;
+        for (const entry of this.atlases) {
+            const bytes = getAtlasSizeBytes(entry.width, entry.height);
+            if (entry.resizable)
+                totalResizable += bytes;
+            else
+                totalFixed += bytes;
+        }
+        if (totalResizable === 0) {
+            logger.debug('no resizable atlases, atlases will not be scaled');
+            return 1;
+        }
+        const budget = this.memoryLimitMb * BYTES_PER_MB - totalFixed;
+        if (budget <= 0) {
+            logger.debug('memory limit too low to resize textures, atlases will not be scaled');
+            return 1;
+        }
+        const factor = Math.sqrt(budget / totalResizable);
+        if (factor >= 1)
+            return 1;
+        logger.debug('resize factor: %s (budget %d bytes, resizable %d bytes)', factor.toFixed(3), budget, totalResizable);
+        return factor;
+    }
+}
+/**
+ * The scene's texture budget, provided by `Renderer`. The default is an uncapped budget, so an image
+ * layer rendered outside a `Renderer` (a test, a story) behaves exactly as before this existed —
+ * everything uploads at full size.
+ */
+export const TextureBudgetContext = createContext(new TextureBudget());
+/**
+ * Registers an atlas with the scene budget for its mounted lifetime and returns the resize factor it
+ * should upload at: the shared factor for a resizable atlas, always `1` for a fixed one (its pixels
+ * still count toward the budget, they just never scale).
+ *
+ * When the budget is inactive — no `memoryLimit` — the atlas is not registered at all: there is
+ * nothing to solve, so an uncapped scene does no per-atlas budget work. Turning a cap on at runtime
+ * flips `isActive`, which re-runs the registration effect.
+ * @param budget - The scene budget from context.
+ * @param atlas - The atlas to register and read a factor for.
+ * @returns The linear factor this atlas's canvas should be scaled by before upload, in `(0, 1]`.
+ */
+export function useResizeFactor(budget, atlas) {
+    // The inline getters/subscribe close over `budget`; the React Compiler memoizes them on it, so
+    // `useSyncExternalStore` sees stable references and does not re-subscribe every render. They must
+    // be arrows (not `budget.subscribe`) so the call keeps its `this`.
+    const active = useSyncExternalStore((listener) => budget.subscribe(listener), () => budget.isActive());
+    const factor = useSyncExternalStore((listener) => budget.subscribe(listener), () => budget.getResizeFactor());
+    useEffect(() => {
+        // No cap in force: registering would only feed a computation that resolves to "no scaling", so
+        // an uncapped scene does no per-atlas budget work. A later `setMemoryLimit` flips `active` and
+        // re-runs this to register. The no-cap case is logged once by `Renderer`, not here per atlas.
+        if (!active)
+            return;
+        const entry = {
+            width: atlas.canvas.width,
+            height: atlas.canvas.height,
+            resizable: atlas.resizable,
+        };
+        budget.register(entry);
+        return () => budget.unregister(entry);
+    }, [budget, atlas, active]);
+    // A fixed atlas never scales; an uncapped budget leaves the factor at 1, so this is 1 then too.
+    return atlas.resizable ? factor : 1;
+}

package/dist/objects/layer/Layer.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import { type LayerDef } from '../../types/defs';
+/** Props for {@link Layer}. */
+export interface LayerProps {
+    /** The layer definition to render, together with its descendants. */
+    layer: LayerDef;
+    /**
+     * Rendered inside the root group, before the tree's own content — under the root layer's dim
+     * provider, which is what the scene's background quad mounts here for: the root's dim reaches it
+     * like any layer's, and its material exists before every layer's, which its draw order relies
+     * on.
+     */
+    children?: ReactNode;
+}
+/**
+ * Renders a {@link LayerDef} tree, mapping defs onto the scene-graph hierarchy.
+ *
+ * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
+ * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
+ * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
+ * carries: nothing above the root can hide it, and the whole tree's draw order lives inside
+ * `[0, 1)`.
+ * @param props - The layer props.
+ * @returns The tree's root group.
+ */
+export declare function Layer(props: LayerProps): import("react").JSX.Element;
+//# sourceMappingURL=Layer.d.ts.map

package/dist/objects/layer/Layer.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, use } from 'react';
+import { useLayoutTargets } from '../../events/layout-targets';
+import { usePointerProps } from '../../events/pointer';
+import { isImageDefs, isLayerDefs, isLineDefs, isModelDefs, isShapeDefs, isTextDefs, } from '../../types/guards';
+import { Images } from '../images';
+import { Lines } from '../lines';
+import { LayerDimContext } from '../materials/dim';
+import { Models } from '../models';
+import { Shapes } from '../shapes';
+import { Texts } from '../text';
+import { useStagedChildren } from './mount-scheduler';
+import { useVisibilityGui } from './visibility-gui';
+/**
+ * Renders a {@link LayerDef} tree, mapping defs onto the scene-graph hierarchy.
+ *
+ * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
+ * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
+ * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
+ * carries: nothing above the root can hide it, and the whole tree's draw order lives inside
+ * `[0, 1)`.
+ * @param props - The layer props.
+ * @returns The tree's root group.
+ */
+export function Layer(props) {
+    const { layer, children } = props;
+    useVisibilityGui(layer);
+    return (_jsx(LayerNode, { layer: layer, parentVisible: true, orderBase: 0, orderStep: 1, children: children }));
+}
+/**
+ * One layer of the tree as a three.js `<group>`, recursing into its child layers.
+ *
+ * Everything layer-shaped is handled here as group state — the name, visibility from
+ * `layer.hidden`, the dim the subtree inherits, and the pointer props that make the group
+ * interactive and picked (see `usePointerProps`) — so the containers below stay free of layer
+ * semantics and receive only their child defs. The children arrive through `useStagedChildren`,
+ * which is what makes `layer.hidden = true; update(layer)` flip a group prop instead of rebuilding
+ * anything, defers a membership change's instance-list sweep to transition priority, and stages
+ * leaf mounting one commit per frame — see the hook for all three.
+ *
+ * **Re-layout is registered, not rendered.** A layer registers the defs that declare an `onScale`
+ * with the renderer's re-layout targets — the children it holds, and itself, which is how a layer
+ * whose membership depends on the camera re-derives it. From then on a pixel-size change reaches
+ * those defs through the frame loop, with no render of this component involved.
+ *
+ * **Draw order is a group prop.** three propagates a group's `renderOrder` down its subtree as
+ * `groupOrder`, which `painterSortStable` compares before `renderOrder` and `material.id` — so
+ * numbering the groups is all it takes to make array order the draw order. A nested group
+ * overwrites `groupOrder` for its own subtree, so the value that decides a mesh's place is its
+ * nearest enclosing layer's; the numbers on layers above it are overwritten and simply do not
+ * matter. Without this the order falls out of `material.id`, which ascends in mount order and
+ * therefore puts any material built after first paint — every model's, since they exist only once
+ * its GLB has loaded — last in the scene regardless of where its layer sits.
+ * @param props - The node props.
+ * @returns The `<group>` for a layer def.
+ */
+function LayerNode(props) {
+    const { layer, children: prelude, parentVisible, orderBase, orderStep } = props;
+    // On screen only if nothing above hides it either — the value picking hangs off, and what the
+    // children inherit in turn.
+    const visible = parentVisible && !layer.hidden;
+    // Nearest declaration wins and reaches every material beneath through context — so only
+    // `undefined` inherits, and a layer's own `0` un-dims it inside a dimmed ancestor. Unlike
+    // visibility this is never a prop: nothing between here and the material has any use for it.
+    const inheritedDim = use(LayerDimContext);
+    const dim = layer.dim ?? inheritedDim;
+    const { children, admitted } = useStagedChildren(layer);
+    useLayoutTargets(layer, children);
+    const pointerProps = usePointerProps(layer, visible);
+    let contents = null;
+    if (isLayerDefs(children)) {
+        const childStep = orderStep / children.length;
+        contents = children.map((child, index) => (_jsx(LayerNode, { layer: child, parentVisible: visible, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
+    }
+    else if (admitted) {
+        contents = _jsx(LeafContent, { defs: children });
+    }
+    const group = (_jsxs("group", { name: layer.name, visible: !layer.hidden, renderOrder: orderBase, ...pointerProps, children: [prelude, contents] }));
+    // Always provided, never conditionally on the layer declaring a `dim`: making the provider appear
+    // when one is first set would change this component's element type, and React would remount the
+    // subtree — releasing and re-claiming every GPU slot beneath it, exactly what an eased dim must
+    // not do. A layer that declares none provides what it inherited, which no consumer can tell apart
+    // from not providing at all.
+    return _jsx(LayerDimContext, { value: dim, children: group });
+}
+/**
+ * The content of one leaf layer: the container for its defs' kind, inside a Suspense boundary of
+ * the leaf's own.
+ *
+ * The boundary means a content component that suspends — a loader hook, a lazily imported one —
+ * costs this leaf alone. Without it the nearest boundary is the one R3F's `<Canvas>` wraps
+ * everything in, and falling back to it hides *every* object in the scene (R3F's `hideInstance`
+ * writes `visible = false`) while the admission queue stalls forever, since the leaf never commits
+ * and so never reports mounted. With it, a suspended leaf behaves exactly like an empty one: the
+ * layer still commits, still reports, the next leaf is admitted on schedule, and the content mounts
+ * when it resolves.
+ * @param props - The leaf's defs.
+ * @returns The container for the defs' kind.
+ */
+function LeafContent(props) {
+    const { defs } = props;
+    let content = null;
+    if (isShapeDefs(defs))
+        content = _jsx(Shapes, { defs: defs });
+    else if (isImageDefs(defs))
+        content = _jsx(Images, { defs: defs });
+    else if (isTextDefs(defs))
+        content = _jsx(Texts, { defs: defs });
+    else if (isLineDefs(defs))
+        content = _jsx(Lines, { defs: defs });
+    else if (isModelDefs(defs))
+        content = _jsx(Models, { defs: defs });
+    return _jsx(Suspense, { fallback: null, children: content });
+}

package/dist/objects/layer/index.d.ts

@@ -0,0 +1,2 @@
+export { Layer, type LayerProps } from './Layer';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/layer/index.js

@@ -0,0 +1 @@
+export { Layer } from './Layer';

package/dist/objects/layer/mount-scheduler.d.ts

@@ -0,0 +1,102 @@
+import { type LayerDef, type RenderableDef, type RenderableDefCollection } from '../../types/defs';
+/**
+ * Admits shape layers into the scene one per frame, in registration order.
+ *
+ * Mounting a large layer's instances is one unbreakable commit — `useDeferredValue` can slice a
+ * render phase, but nothing can slice a commit — so the unit of progressive mounting is the leaf
+ * layer: a scene's first (small) layers paint without waiting for every later layer's commit.
+ * Priority is registration order, which is the **flattened leaf order** of the tree: leaves
+ * register from a passive mount effect, and React runs those children-first, in sibling order.
+ * Pacing is one admission per animation frame, granted after the previously admitted leaf reports
+ * its content committed — so each layer's frame actually presents before the next layer's commit
+ * begins.
+ *
+ * An **empty** leaf is exempt: it has no instances to commit, so it is admitted on registration and
+ * never paced. Without that, a layer filled after mount — wayfinding's route, markers, traffic —
+ * would have to wait out the staging of every leaf ahead of it (a real plan runs to ~90 leaves,
+ * ~20s) before it were allowed to draw at all.
+ */
+export interface MountScheduler {
+    /**
+     * Queues a leaf for admission. Call from a mount effect so call order is the flattened leaf
+     * order. Admission is sticky: a leaf that re-registers (StrictMode effect cycling, a remount)
+     * stays admitted.
+     * @param leaf - The shape layer to queue.
+     * @returns An unregister function.
+     */
+    register(leaf: LayerDef): () => void;
+    /**
+     * The queued leaves, in registration order — the flattened leaf order of the mounted tree. The
+     * queue doubles as the tree's leaf census, which is what the layer-visibility GUI lists.
+     * @returns A snapshot of the queue.
+     */
+    leaves(): readonly LayerDef[];
+    /**
+     * Whether a leaf may mount its content — the `useSyncExternalStore` snapshot.
+     * @param leaf - The shape layer to check.
+     * @returns `true` once admitted.
+     */
+    isAdmitted(leaf: LayerDef): boolean;
+    /**
+     * Subscribes to scheduler changes: admissions, registrations, and unregistrations.
+     * @param listener - Called after every change.
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Marks the admitted leaf's content as committed, releasing the next admission on the following
+     * animation frame.
+     * @param leaf - The shape layer whose content committed.
+     */
+    reportMounted(leaf: LayerDef): void;
+}
+/** What {@link useStagedChildren} hands a layer: the children to render, and their admission. */
+export interface StagedChildren<T extends RenderableDef> {
+    /** The layer's children — the deferred, version-keyed snapshot described on the hook. */
+    children: Readonly<RenderableDefCollection<T>>;
+    /** Whether a leaf layer may mount its content; always `true` for a layer of layers. */
+    admitted: boolean;
+}
+/**
+ * Builds the scheduler a `Layer` tree's root provides.
+ * @returns The scheduler.
+ */
+export declare function createMountScheduler(): MountScheduler;
+/**
+ * A layer's children as they should render now, together with the staged-mount admission for their
+ * content. Three behaviors fold together here, because their consumer needs all of them and the
+ * intermediate values are footguns — rendering the un-deferred snapshot would defeat the deferral:
+ *
+ * - **Subscription.** The store's version-keyed snapshot of `layer.children`: a new identity
+ *   exactly when the layer is updated, the cached one otherwise. The layer's own array is mutated
+ *   in place, so passing it down would leave a memoized container stale; the snapshot is what makes
+ *   `layer.hidden = true; update(layer)` re-render the layer while child identities survive, so
+ *   keyed reconciliation mounts and unmounts only the membership delta.
+ * - **Deferral.** Children flow through `useDeferredValue`, so a membership change's urgent render
+ *   is the layer component alone; the container's instance-list sweep re-renders at transition
+ *   priority, interruptible, keeping frames flowing. `update(def)` writes on leaf defs are
+ *   unaffected — they never pass through `children`.
+ * - **Admission.** Whether a leaf may mount its content, per {@link useStagedMount}. A leaf that is
+ *   not yet admitted renders `null` rather than an empty container, so each batch is still created
+ *   at its full size and never reallocates on mount. Defs stay the source of truth: `update()`
+ *   against a not-yet-admitted layer is harmless, because admission mounts whatever the defs hold
+ *   at that moment.
+ * @param layer - The layer to observe.
+ * @returns The current children snapshot and the admission flag.
+ */
+export declare function useStagedChildren<T extends RenderableDef>(layer: LayerDef<T>): StagedChildren<T>;
+/**
+ * Whether a layer may mount its content, per the tree's scheduler.
+ *
+ * Consumes the scheduler {@link MountSchedulerContext} provides. Without one — a plain `<Layer>`
+ * mount, or staging disabled — everything is admitted immediately and no queueing happens. Under a
+ * scheduler, a leaf is admitted one per frame in flattened leaf order, and reports back from the
+ * admission commit so the next leaf is released only after this one's content committed.
+ * @param layer - The layer def.
+ * @param leaf - Whether the layer is a shape layer; only leaves are staged.
+ * @returns Whether the layer's content may mount.
+ */
+export declare function useStagedMount(layer: LayerDef, leaf: boolean): boolean;
+/** The tree's scheduler, provided by `Scene` and inherited by every `Layer` beneath it. */
+export declare const MountSchedulerContext: import("react").Context<MountScheduler | null>;
+//# sourceMappingURL=mount-scheduler.d.ts.map

package/dist/objects/layer/mount-scheduler.js

@@ -0,0 +1,145 @@
+import { createContext, use, useDeferredValue, useEffect, useSyncExternalStore } from 'react';
+import { isLayerDefs } from '../../types/guards';
+import { childrenOf, subscribeDef } from '../../update';
+/**
+ * Builds the scheduler a `Layer` tree's root provides.
+ * @returns The scheduler.
+ */
+export function createMountScheduler() {
+    const queue = [];
+    // Weak and sticky: admission survives unregister (a StrictMode effect cycle must not unmount
+    // content already on screen), and an entry is collected with its def.
+    const admitted = new WeakSet();
+    const listeners = new Set();
+    let awaiting = null;
+    let pacing = false;
+    // Frame pacing in the browser; a macrotask in headless spec environments without rAF.
+    const nextFrame = typeof requestAnimationFrame === 'function'
+        ? (callback) => void requestAnimationFrame(callback)
+        : (callback) => void setTimeout(callback, 0);
+    const notifyAll = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const pump = () => {
+        if (awaiting || pacing)
+            return;
+        const next = queue.find((leaf) => !admitted.has(leaf));
+        if (!next)
+            return;
+        admitted.add(next);
+        awaiting = next;
+        notifyAll();
+    };
+    return {
+        register: (leaf) => {
+            // An empty leaf has no instances to commit, so it costs nothing to admit and nothing to
+            // pace: it takes no queue slot and never becomes `awaiting`. This is what keeps a layer
+            // filled *after* mount — wayfinding's route, markers, traffic — from waiting out the whole
+            // plan's staging before it may draw. Admission is sticky, so the later fill mounts at once,
+            // as the one small commit it is.
+            if (leaf.children.length === 0 && !admitted.has(leaf)) {
+                admitted.add(leaf);
+                notifyAll();
+            }
+            if (!queue.includes(leaf)) {
+                queue.push(leaf);
+                notifyAll();
+            }
+            pump();
+            return () => {
+                const index = queue.indexOf(leaf);
+                if (index >= 0) {
+                    queue.splice(index, 1);
+                    notifyAll();
+                }
+                // An admitted leaf that unmounts before reporting must not stall the queue forever.
+                if (awaiting === leaf) {
+                    awaiting = null;
+                    pump();
+                }
+            };
+        },
+        leaves: () => [...queue],
+        isAdmitted: (leaf) => admitted.has(leaf),
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        reportMounted: (leaf) => {
+            if (awaiting !== leaf)
+                return;
+            awaiting = null;
+            // The pacing flag keeps a registration arriving before the next frame from admitting
+            // synchronously and skipping the one-per-frame cadence.
+            pacing = true;
+            nextFrame(() => {
+                pacing = false;
+                pump();
+            });
+        },
+    };
+}
+/**
+ * A layer's children as they should render now, together with the staged-mount admission for their
+ * content. Three behaviors fold together here, because their consumer needs all of them and the
+ * intermediate values are footguns — rendering the un-deferred snapshot would defeat the deferral:
+ *
+ * - **Subscription.** The store's version-keyed snapshot of `layer.children`: a new identity
+ *   exactly when the layer is updated, the cached one otherwise. The layer's own array is mutated
+ *   in place, so passing it down would leave a memoized container stale; the snapshot is what makes
+ *   `layer.hidden = true; update(layer)` re-render the layer while child identities survive, so
+ *   keyed reconciliation mounts and unmounts only the membership delta.
+ * - **Deferral.** Children flow through `useDeferredValue`, so a membership change's urgent render
+ *   is the layer component alone; the container's instance-list sweep re-renders at transition
+ *   priority, interruptible, keeping frames flowing. `update(def)` writes on leaf defs are
+ *   unaffected — they never pass through `children`.
+ * - **Admission.** Whether a leaf may mount its content, per {@link useStagedMount}. A leaf that is
+ *   not yet admitted renders `null` rather than an empty container, so each batch is still created
+ *   at its full size and never reallocates on mount. Defs stay the source of truth: `update()`
+ *   against a not-yet-admitted layer is harmless, because admission mounts whatever the defs hold
+ *   at that moment.
+ * @param layer - The layer to observe.
+ * @returns The current children snapshot and the admission flag.
+ */
+export function useStagedChildren(layer) {
+    const snapshot = useSyncExternalStore((listener) => subscribeDef(layer, listener), () => childrenOf(layer));
+    const children = useDeferredValue(snapshot);
+    const admitted = useStagedMount(layer, !isLayerDefs(children));
+    return { children, admitted };
+}
+/**
+ * Whether a layer may mount its content, per the tree's scheduler.
+ *
+ * Consumes the scheduler {@link MountSchedulerContext} provides. Without one — a plain `<Layer>`
+ * mount, or staging disabled — everything is admitted immediately and no queueing happens. Under a
+ * scheduler, a leaf is admitted one per frame in flattened leaf order, and reports back from the
+ * admission commit so the next leaf is released only after this one's content committed.
+ * @param layer - The layer def.
+ * @param leaf - Whether the layer is a shape layer; only leaves are staged.
+ * @returns Whether the layer's content may mount.
+ */
+export function useStagedMount(layer, leaf) {
+    const scheduler = use(MountSchedulerContext);
+    const admitted = useSyncExternalStore((onStoreChange) => (scheduler ? scheduler.subscribe(onStoreChange) : noopUnsubscribe), () => !leaf || !scheduler || scheduler.isAdmitted(layer));
+    // Registration from a passive effect, deliberately: effect order across the tree is the
+    // flattened leaf order, which is the admission priority.
+    useEffect(() => {
+        if (!scheduler || !leaf)
+            return undefined;
+        return scheduler.register(layer);
+    }, [scheduler, layer, leaf]);
+    // Runs in the admission commit, after the children's effects — the content's slots are claimed
+    // by the time the next leaf is released.
+    useEffect(() => {
+        if (scheduler && leaf && admitted)
+            scheduler.reportMounted(layer);
+    }, [scheduler, layer, leaf, admitted]);
+    return admitted;
+}
+/** The tree's scheduler, provided by `Scene` and inherited by every `Layer` beneath it. */
+export const MountSchedulerContext = createContext(null);
+// What subscribing without a scheduler returns: nothing to unsubscribe from.
+const noopUnsubscribe = () => undefined;

package/dist/objects/layer/visibility-gui.d.ts

@@ -0,0 +1,19 @@
+import { type LayerDef } from '../../types/defs';
+/**
+ * Builds the layer-visibility debug GUI: called by the tree's root `Layer` alone, a no-op without
+ * a debug GUI in context. Two folders, one checkbox per layer:
+ *
+ * - **Main layers** — the root's direct child layers, in child order, kept current through the
+ *   same store subscription `update()` drives (a root membership change rebuilds the rows).
+ * - **Content layers** — every leaf (shape) layer in the tree, in the mount scheduler's
+ *   registration order, which is the flattened leaf order. No new bookkeeping tracks the leaves:
+ *   `useStagedMount` already registers each one with the scheduler, so this folder mirrors the
+ *   scheduler's queue and follows leaves as they mount and unmount. Without a scheduler in
+ *   context (a plain `<Layer>` mount outside `Scene`) the folder stays empty.
+ *
+ * The effect runs entirely against the defs and the GUI — toggles never re-render the layer tree
+ * beyond what `update()` itself triggers.
+ * @param layer - The tree's root layer def.
+ */
+export declare function useVisibilityGui(layer: LayerDef): void;
+//# sourceMappingURL=visibility-gui.d.ts.map