@expofp/renderer 3.34.1 → 3.35.0

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

@@ -1,42 +1,60 @@
 import { type LayerDef, type RenderableDef, type RenderableDefCollection } from '../../types/defs';
 /**
- * Admits shape layers into the scene one per frame, in registration order.
+ * Lets a shape layer mount its children a slice at a time, 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.
+ * React cannot split a commit. `useDeferredValue` splits a render phase, but the commit that
+ * follows runs to the end. So the unit of progressive mounting is whatever one commit mounts, and
+ * that unit is a slice of one leaf layer's children. Without slices, a layer holding thousands of
+ * defs mounts them in one commit, and no pacing of whole layers makes that frame shorter.
  *
- * 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.
+ * 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.
+ *
+ * A frame keeps taking slices until its budget runs out, and hands the rest to the next frame. One
+ * slice per frame was measured as 64% of the staging spent waiting rather than mounting.
+ *
+ * **What the budget covers.** Each slice is timed from the grant to the report, so the measurement
+ * holds React's work: the render phase, the commit, and the effects that claim slots and write
+ * their state. It does not hold what the frame does next. There three culls and sorts, uploads
+ * buffers and textures, compiles a new material's program and draws, and then the browser paints.
+ * Those cost more than the mount on a busy startup frame, and the budget cannot see any of them.
+ * Treat the budget as a cap on what mounting adds to a frame, not as a frame time.
+ *
+ * The slice size comes from measurement rather than from a fixed count, because a child of an image
+ * layer costs about ten times what a child of a shape layer costs. Every slice is timed, and the
+ * next one is sized from what the last one cost per child. One floor overrides the budget: a layer
+ * is never cut into more than {@link MAX_SLICES_PER_LEAF} slices, because a layer re-renders its
+ * whole mounted prefix on every slice.
+ *
+ * An empty leaf is exempt. It has no instances to commit, so it is admitted when it registers and
+ * is never paced. Without that, a layer filled after mount, such as wayfinding's route, the markers
+ * or the traffic, waits out the staging of every leaf ahead of it before it can draw. A leaf that
+ * finishes staging is exempt from then on, for the same reason: whatever it gains later mounts at
+ * once, as the one small commit it is.
  */
 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.
+     * Queues a leaf for admission. Call it from a mount effect, so the call order is the flattened
+     * leaf order. Admission is sticky: a leaf that registers again, after a StrictMode effect cycle
+     * or a remount, keeps every child it was already granted.
      * @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.
+     * The queued leaves, in registration order, which is the flattened leaf order of the mounted
+     * tree. The queue is also the tree's leaf census, and that 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.
+     * How many of a leaf's children can mount their content now, counted from the start of its list.
+     * This is the `useSyncExternalStore` snapshot.
      * @param leaf - The shape layer to check.
-     * @returns `true` once admitted.
+     * @returns The admitted count, which is every child once the leaf finishes staging.
      */
-    isAdmitted(leaf: LayerDef): boolean;
+    admittedCount(leaf: LayerDef): number;
     /**
      * Subscribes to scheduler changes: admissions, registrations, and unregistrations.
      * @param listener - Called after every change.
@@ -44,59 +62,70 @@ export interface MountScheduler {
      */
     subscribe(listener: () => void): () => void;
     /**
-     * Marks the admitted leaf's content as committed, releasing the next admission on the following
-     * animation frame.
+     * Reports that the admitted slice committed its content. The scheduler records what the slice
+     * cost and releases the next one. It releases it inside this frame while the budget holds, and on
+     * the next frame once it does not.
      * @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. */
+/** What {@link useStagedChildren} hands a layer: the children to render, and how many can mount. */
 export interface StagedChildren<T extends RenderableDef> {
-    /** The layer's children — the deferred, version-keyed snapshot described on the hook. */
+    /** The layer's children, as the deferred and version-keyed snapshot the hook describes. */
     children: Readonly<RenderableDefCollection<T>>;
-    /** Whether a leaf layer may mount its content; always `true` for a layer of layers. */
-    admitted: boolean;
+    /**
+     * How many of `children` can mount their instances, counted from the start of the list. A layer
+     * of layers is not staged, so it always gets all of them.
+     */
+    mounted: number;
 }
 /**
  * Builds the scheduler a `Layer` tree's root provides.
+ * @param budgetMs - How much of a frame mounting can take, in milliseconds, across as many slices
+ *   as fit. The frame also has to draw, so this is a fraction of a frame rather than the whole of
+ *   one. A budget smaller than one slice paces one slice per frame, which is what a spec wants when
+ *   its commits cost nothing measurable.
  * @returns The scheduler.
  */
-export declare function createMountScheduler(): MountScheduler;
+export declare function createMountScheduler(budgetMs?: number): 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:
+ * A layer's children as they render now, together with how many of them can mount.
+ *
+ * Three behaviors fold together here, because their consumer needs all three, and because the
+ * values in between are traps. Rendering the snapshot before the deferral defeats 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.
+ * - **Subscription.** The store's version-keyed snapshot of `layer.children`. It is a new identity
+ *   exactly when the layer is updated, and the cached one otherwise. The layer's own array is
+ *   mutated in place, so passing it down leaves a memoized container stale. The snapshot is what
+ *   makes `layer.hidden = true; update(layer)` re-render the layer while the child identities
+ *   survive, so keyed reconciliation mounts and unmounts only the membership delta.
+ * - **Deferral.** Children flow through `useDeferredValue`, so the urgent render of a membership
+ *   change is the layer component alone. The container's instance-list sweep re-renders at
+ *   transition priority, where React can interrupt it, and the frames keep flowing. `update(def)`
+ *   writes on leaf defs are unaffected, because they never pass through `children`.
+ * - **Admission.** How many of a leaf's children can mount their content, per {@link useStagedMount}.
+ *   A leaf granted nothing yet renders `null` rather than an empty container, so each batch is
+ *   still created at its full size and never reallocates as the granted prefix grows. Defs stay the
+ *   source of truth: `update()` against a def that has not mounted yet is harmless, because its
+ *   instance writes whatever the def holds when it does mount.
  * @param layer - The layer to observe.
- * @returns The current children snapshot and the admission flag.
+ * @returns The current children snapshot and how many of them can mount.
  */
 export declare function useStagedChildren<T extends RenderableDef>(layer: LayerDef<T>): StagedChildren<T>;
 /**
- * Whether a layer may mount its content, per the tree's scheduler.
+ * How many of a layer's children can mount, 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.
+ * Consumes the scheduler {@link MountSchedulerContext} provides. Without one, which is a plain
+ * `<Layer>` mount or staging turned off, everything is admitted at once and nothing queues. Under a
+ * scheduler, a leaf is granted a slice of its children at a time, in flattened leaf order. It
+ * reports back from each admission commit, so the next slice 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.
+ * @param leaf - Whether the layer is a shape layer. Only leaves are staged.
+ * @param total - How many children the layer holds, which is what an unstaged layer mounts.
+ * @returns How many of the layer's children can mount their content.
  */
-export declare function useStagedMount(layer: LayerDef, leaf: boolean): boolean;
+export declare function useStagedMount(layer: LayerDef, leaf: boolean, total: number): number;
 /** 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

@@ -1,19 +1,44 @@
 import { createContext, use, useDeferredValue, useEffect, useSyncExternalStore } from 'react';
 import { isLayerDefs } from '../../types/guards';
 import { childrenOf, subscribeDef } from '../../update';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('mount');
 /**
  * Builds the scheduler a `Layer` tree's root provides.
+ * @param budgetMs - How much of a frame mounting can take, in milliseconds, across as many slices
+ *   as fit. The frame also has to draw, so this is a fraction of a frame rather than the whole of
+ *   one. A budget smaller than one slice paces one slice per frame, which is what a spec wants when
+ *   its commits cost nothing measurable.
  * @returns The scheduler.
  */
-export function createMountScheduler() {
+export function createMountScheduler(budgetMs = FRAME_BUDGET_MS) {
     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();
+    // How many children each leaf has been granted. Weak, so an entry goes when its def goes. Sticky,
+    // so an unregister keeps the count: a StrictMode effect cycle must not unmount content that is
+    // already on screen.
+    const granted = new WeakMap();
+    // Leaves that are not paced at all. A leaf lands here when it registers empty, and when it
+    // finishes staging. Both mount whatever they hold the moment they hold it.
+    const unpaced = new WeakSet();
+    // What one child of this leaf cost to mount, in milliseconds, as last measured. Kept per leaf
+    // because the spread is wide: a plain shape costs a fraction of what an image costs.
+    const rateByLeaf = new WeakMap();
     const listeners = new Set();
     let awaiting = null;
+    let awaitingSize = 0;
+    let awaitingSince = 0;
     let pacing = false;
-    // Frame pacing in the browser; a macrotask in headless spec environments without rAF.
+    // What this frame already spent on mounting, and how many slices it took. A frame keeps taking
+    // slices until one of the two runs out. That is what stops the pacing from costing a whole frame
+    // per slice, which on a large plan leaves most of the staging waiting instead of mounting.
+    let frameSpent = 0;
+    let frameSlices = 0;
+    // The leaves this frame granted to, for the one debug line each of them gets when the frame ends.
+    const framed = [];
+    // Seeds the first slice of a leaf that nothing has measured yet. Every measurement refreshes it,
+    // so the seed follows the scene being mounted rather than a number chosen here.
+    let rate = INITIAL_MS_PER_CHILD;
+    // Frame pacing in the browser. A macrotask in headless spec environments, which have no rAF.
     const nextFrame = typeof requestAnimationFrame === 'function'
         ? (callback) => void requestAnimationFrame(callback)
         : (callback) => void setTimeout(callback, 0);
@@ -21,25 +46,97 @@ export function createMountScheduler() {
         for (const listener of [...listeners])
             listener();
     };
+    /**
+     * How many more of a leaf's children the next commit can take.
+     * @param leaf - The leaf being staged.
+     * @param from - How many of its children are already granted.
+     * @param available - What is left of this frame's mounting budget, in milliseconds.
+     * @returns The slice size, at least one child and never past the end.
+     */
+    const sliceFor = (leaf, from, available) => {
+        const measured = rateByLeaf.get(leaf);
+        const fit = Math.max(1, Math.round(available / Math.max(measured ?? rate, MIN_MS_PER_CHILD)));
+        // A leaf that nothing has measured gets a capped first slice. That slice pays the fixed costs
+        // of the layer, which are the material's compile, the mesh's allocation and the first atlas
+        // upload. A seed taken from a cheaper layer sizes it far too generously.
+        const size = measured === undefined ? Math.min(fit, FIRST_SLICE) : fit;
+        // The floor is what keeps slicing from turning quadratic. A layer renders its whole mounted
+        // prefix on every slice, so the elements React builds over a staging run come to slices times
+        // prefix. That is cheap over a handful of slices and ruinous over hundreds. The floor caps a
+        // layer at MAX_SLICES_PER_LEAF slices and overrides the budget to do it, so a big layer takes
+        // one frame longer than the budget instead of paying that cost hundreds of times.
+        const floor = Math.ceil(leaf.children.length / MAX_SLICES_PER_LEAF);
+        return Math.min(leaf.children.length - from, Math.max(size, floor));
+    };
+    /**
+     * How many of a leaf's children can mount now.
+     * @param leaf - The leaf to count.
+     * @returns The admitted count.
+     */
+    const countOf = (leaf) => unpaced.has(leaf)
+        ? leaf.children.length
+        : Math.min(granted.get(leaf) ?? 0, leaf.children.length);
+    /** Reports what the frame admitted, one line per layer it touched, and clears the tally. */
+    const logFrame = () => {
+        if (framed.length === 0)
+            return;
+        for (const leaf of framed) {
+            logger.debug(`${leaf.name ?? '?'}, admitted ${countOf(leaf)}/${leaf.children.length}`);
+        }
+        framed.length = 0;
+    };
+    /** Hands the rest of the queue to the next frame, and starts that frame's budget over. */
+    const yieldFrame = () => {
+        if (pacing)
+            return;
+        pacing = true;
+        logFrame();
+        nextFrame(() => {
+            pacing = false;
+            frameSpent = 0;
+            frameSlices = 0;
+            pump();
+        });
+    };
     const pump = () => {
         if (awaiting || pacing)
             return;
-        const next = queue.find((leaf) => !admitted.has(leaf));
-        if (!next)
+        const next = queue.find((leaf) => !unpaced.has(leaf) && (granted.get(leaf) ?? 0) < leaf.children.length);
+        if (!next) {
+            logFrame();
             return;
-        admitted.add(next);
+        }
+        const available = budgetMs - frameSpent;
+        // Out of budget, or enough slices for one frame, so the rest waits for the next frame. A frame
+        // always takes its first slice, however small the budget is, so the scheduler can never stall.
+        // The re-layout drain follows the same rule. The slice cap is a guard rather than a policy:
+        // every grant is a React update raised from an effect, and React stops a component that raises
+        // them without end.
+        const spent = available < MIN_SLICE_BUDGET_MS || frameSlices >= MAX_SLICES_PER_FRAME;
+        if (spent && frameSlices > 0) {
+            yieldFrame();
+            return;
+        }
+        const from = granted.get(next) ?? 0;
+        const size = sliceFor(next, from, available);
+        granted.set(next, from + size);
+        if (from + size >= next.children.length)
+            unpaced.add(next);
         awaiting = next;
+        awaitingSize = size;
+        awaitingSince = performance.now();
+        if (!framed.includes(next))
+            framed.push(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);
+            // An empty leaf has no instances to commit. It costs nothing to admit and nothing to pace, so
+            // it never becomes `awaiting`. This is what lets a layer filled after mount, such as
+            // wayfinding's route, the markers or the traffic, draw without waiting out the whole staging.
+            // It stays exempt, so the later fill mounts at once, as the one small commit it is.
+            if (leaf.children.length === 0 && !unpaced.has(leaf)) {
+                unpaced.add(leaf);
                 notifyAll();
             }
             if (!queue.includes(leaf)) {
@@ -53,7 +150,7 @@ export function createMountScheduler() {
                     queue.splice(index, 1);
                     notifyAll();
                 }
-                // An admitted leaf that unmounts before reporting must not stall the queue forever.
+                // An admitted leaf that unmounts before it reports must not stall the queue for good.
                 if (awaiting === leaf) {
                     awaiting = null;
                     pump();
@@ -61,7 +158,9 @@ export function createMountScheduler() {
             };
         },
         leaves: () => [...queue],
-        isAdmitted: (leaf) => admitted.has(leaf),
+        admittedCount: (leaf) => unpaced.has(leaf)
+            ? leaf.children.length
+            : Math.min(granted.get(leaf) ?? 0, leaf.children.length),
         subscribe: (listener) => {
             listeners.add(listener);
             return () => {
@@ -71,75 +170,120 @@ export function createMountScheduler() {
         reportMounted: (leaf) => {
             if (awaiting !== leaf)
                 return;
+            // Timed from the grant. The effect this runs from is inside the commit the grant caused, and
+            // it runs after the children's own effects, so the span covers that commit's React work. It
+            // does not cover the draw that follows, which the interface doc explains.
+            const cost = performance.now() - awaitingSince;
+            if (awaitingSize > 0) {
+                rate = Math.max(cost / awaitingSize, MIN_MS_PER_CHILD);
+                rateByLeaf.set(leaf, rate);
+            }
             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();
-            });
+            frameSpent += cost;
+            frameSlices++;
+            // Straight on to the next slice while this frame still has budget. `pump` hands the queue to
+            // the next frame itself once the budget or the slice count runs out.
+            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:
+ * A layer's children as they render now, together with how many of them can mount.
  *
- * - **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.
+ * Three behaviors fold together here, because their consumer needs all three, and because the
+ * values in between are traps. Rendering the snapshot before the deferral defeats the deferral.
+ *
+ * - **Subscription.** The store's version-keyed snapshot of `layer.children`. It is a new identity
+ *   exactly when the layer is updated, and the cached one otherwise. The layer's own array is
+ *   mutated in place, so passing it down leaves a memoized container stale. The snapshot is what
+ *   makes `layer.hidden = true; update(layer)` re-render the layer while the child identities
+ *   survive, so keyed reconciliation mounts and unmounts only the membership delta.
+ * - **Deferral.** Children flow through `useDeferredValue`, so the urgent render of a membership
+ *   change is the layer component alone. The container's instance-list sweep re-renders at
+ *   transition priority, where React can interrupt it, and the frames keep flowing. `update(def)`
+ *   writes on leaf defs are unaffected, because they never pass through `children`.
+ * - **Admission.** How many of a leaf's children can mount their content, per {@link useStagedMount}.
+ *   A leaf granted nothing yet renders `null` rather than an empty container, so each batch is
+ *   still created at its full size and never reallocates as the granted prefix grows. Defs stay the
+ *   source of truth: `update()` against a def that has not mounted yet is harmless, because its
+ *   instance writes whatever the def holds when it does mount.
  * @param layer - The layer to observe.
- * @returns The current children snapshot and the admission flag.
+ * @returns The current children snapshot and how many of them can mount.
  */
 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 };
+    const mounted = useStagedMount(layer, !isLayerDefs(children), children.length);
+    return { children, mounted };
 }
 /**
- * Whether a layer may mount its content, per the tree's scheduler.
+ * How many of a layer's children can mount, 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.
+ * Consumes the scheduler {@link MountSchedulerContext} provides. Without one, which is a plain
+ * `<Layer>` mount or staging turned off, everything is admitted at once and nothing queues. Under a
+ * scheduler, a leaf is granted a slice of its children at a time, in flattened leaf order. It
+ * reports back from each admission commit, so the next slice 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.
+ * @param leaf - Whether the layer is a shape layer. Only leaves are staged.
+ * @param total - How many children the layer holds, which is what an unstaged layer mounts.
+ * @returns How many of the layer's children can mount their content.
  */
-export function useStagedMount(layer, leaf) {
+export function useStagedMount(layer, leaf, total) {
     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.
+    const mounted = useSyncExternalStore((onStoreChange) => (scheduler ? scheduler.subscribe(onStoreChange) : noopUnsubscribe), () => (!leaf || !scheduler ? total : scheduler.admittedCount(layer)));
+    // Registration from a passive effect, deliberately. Effect order across the tree is the flattened
+    // leaf order, and that order 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.
+    // Runs in the admission commit, after the children's effects, so the slice has claimed its slots
+    // by the time the next one is released. Keyed on the count, so every slice reports, not only the
+    // first.
     useEffect(() => {
-        if (scheduler && leaf && admitted)
+        if (scheduler && leaf && mounted > 0)
             scheduler.reportMounted(layer);
-    }, [scheduler, layer, leaf, admitted]);
-    return admitted;
+    }, [scheduler, layer, leaf, mounted]);
+    return mounted;
 }
 /** The tree's scheduler, provided by `Scene` and inherited by every `Layer` beneath it. */
 export const MountSchedulerContext = createContext(null);
+/**
+ * How much of a frame mounting can take, in milliseconds, across as many slices as fit. Two thirds
+ * of a 60Hz frame, which leaves the draw and the paint their share. The budget is what a frame
+ * spends in total, not what one slice spends: a budget of one slice per frame leaves a large scene
+ * waiting on frames for most of its staging.
+ */
+const FRAME_BUDGET_MS = 11;
+/**
+ * The least budget worth starting a slice on, in milliseconds. Below it the frame counts as spent.
+ * The alternative is a one-child slice, which still costs a whole React commit.
+ */
+const MIN_SLICE_BUDGET_MS = 2;
+/**
+ * The most slices one frame takes, however cheap they are. Every grant is a React update raised
+ * from an effect, and React stops a component that raises them without end.
+ */
+const MAX_SLICES_PER_FRAME = 12;
+/**
+ * What a child is assumed to cost before anything is measured, in milliseconds. Deliberately
+ * pessimistic, because the first slice of the first leaf is the one grant no measurement informs.
+ */
+const INITIAL_MS_PER_CHILD = 0.25;
+/**
+ * The cheapest a child is ever assumed to be, in milliseconds. Without a floor, a layer whose slice
+ * measured as instant sizes the next one at every child it holds.
+ */
+const MIN_MS_PER_CHILD = 0.02;
+/** The most children a leaf is granted before one of its own slices has been measured. */
+const FIRST_SLICE = 64;
+/**
+ * The most slices one leaf is ever cut into. A layer re-renders its whole mounted prefix per slice,
+ * so the number of slices decides how much of that cost the staging pays. Eight keeps it to a few
+ * thousand elements even for a layer of several thousand defs.
+ */
+const MAX_SLICES_PER_LEAF = 8;
 // What subscribing without a scheduler returns: nothing to unsubscribe from.
 const noopUnsubscribe = () => undefined;

package/dist/objects/lighting/Lighting.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Props for {@link Lighting}: every value the debug GUI can move, apart from the two that aim the key light.
+ *
+ * Each one is optional, and each one overrides the design's own default for as long as it is given.
+ * The pitch and `trackPitch` are deliberately absent. Where the key light points is the design's
+ * decision rather than a caller's, and the GUI keeps both of them for settling it.
+ *
+ * **A prop beats the GUI only when the prop changes.** {@link Lighting} writes these into the rig
+ * and into the scene's effect state from an effect keyed on the values themselves, so a control the
+ * GUI moved stays moved until a caller passes something different.
+ */
+export interface LightingProps extends Partial<Omit<LightSettings, 'trackPitch' | 'pitchDegrees'>> {
+    /** The shade both darkening terms blend toward, and each term's own numbers. */
+    shadow?: ShadowProps;
+}
+/**
+ * The darkening values: the shade both terms share, the contact shadow's two numbers, and ambient
+ * occlusion's switch and two numbers.
+ *
+ * One object rather than six loose props, because they are one visual decision. The names are the
+ * GUI's own labels, so a caller and a slider talk about the same thing — and so that the two
+ * strengths cannot be mistaken for each other, which is the reason the GUI renamed them.
+ *
+ * Omit a value to keep the design's own default. `CONTACT_SHADOW_DEFAULTS` and `OCCLUSION_DEFAULTS`
+ * are where those live, each beside the term that owns it.
+ */
+export interface ShadowProps {
+    /** The shade both terms blend toward, as a CSS hex string. */
+    color?: string;
+    /** The contact shadow's reach above a volume's base, in plan units. */
+    contactDistance?: number;
+    /** How far the contact shadow blends a volume's base toward the shade, from `0` to `1`. */
+    contactStrength?: number;
+    /**
+     * Whether ambient occlusion runs at all.
+     *
+     * A switch rather than a capability: the term also turns itself off for good on a context that
+     * cannot give it a depth texture, and there is nothing here to say about that.
+     */
+    ambientOcclusion?: boolean;
+    /** How far ambient occlusion looks for an occluder, in plan units. */
+    aoRadius?: number;
+    /** How far ambient occlusion blends an occluded fragment toward the shade, from `0` to `1`. */
+    aoStrength?: number;
+}
+/**
+ * The light rig, as the debug GUI edits it.
+ *
+ * One object per mounted `Lighting`, mutated in place: the frame reads it, so a slider drag costs a
+ * few numbers and no render. A remount gives a fresh rig rather than reusing module state.
+ */
+export interface LightSettings {
+    /** Whether the light copies the camera's backward axis in full, the pre-overhaul behavior. */
+    trackPitch: boolean;
+    /** The light's angle from the plan's up axis, in degrees. Unread while `trackPitch` is on. */
+    pitchDegrees: number;
+    /**
+     * How directional the rig is, from `0` (pure hemisphere, flat) to `1` (the most directional light
+     * this pitch and these colors take before a wall clips). Normalized rather than an intensity ratio,
+     * whose usable range moves with the pitch. See {@link intensitiesFromContrast}.
+     */
+    contrast: number;
+    /** Hemisphere sky color, as a CSS hex string. */
+    skyColor: string;
+    /** Hemisphere ground color, which every downward face receives. */
+    groundColor: string;
+    /** Directional color, warm against the cool sky so lit faces separate by temperature too. */
+    directionalColor: string;
+}
+/**
+ * Scene lighting: a hemisphere fill along the plan's up axis, and a warm directional light at a
+ * fixed pitch on the camera's heading. The one intensity control is `contrast`, and `Lighting`
+ * derives both `π`-unit intensities from it every frame — so an up-facing surface (a roof) lands on
+ * its authored color and no surface the design accounts for clips.
+ *
+ * That is also why the renderer skips tone mapping (see `Renderer.tsx` and `ExternalCanvas.tsx`): a
+ * curve brings an unbounded light sum back into range, and `contrast` keeps this rig's sum in range
+ * to begin with, at every pitch.
+ *
+ * Only lit materials see the lights — solid shape batches and models. Every 2D primitive draws
+ * through a `MeshBasicMaterial`, so lines, text and images are unaffected.
+ *
+ * **The lights sit inside the scene's world matrix**, so every direction below is in the plan's own
+ * space, taken there through {@link Space.matrixInverse}. Three reads a light's direction from where
+ * it ends up in the *world*, so the two transforms cancel and the light points where it was aimed
+ * under any fit. The directional light needs its target under the same matrix for that, since its
+ * direction is the difference of two world positions.
+ * @param props - The values a caller set, any subset; see {@link LightingProps}.
+ * @returns The two lights, and the directional light's target.
+ */
+export declare function Lighting(props: LightingProps): import("react").JSX.Element;
+//# sourceMappingURL=Lighting.d.ts.map