@expofp/renderer 3.39.0 → 3.40.0

package/dist/events/LayoutDriver.d.ts

@@ -14,12 +14,12 @@ export interface LayoutDriverProps {
  * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
  * costs nothing at all.
  *
- * A move starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
- * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
- * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
- * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
- * stay inside the frame callback, before three's own render, so their attribute writes upload in
- * the very frame that draws them.
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
  *
  * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
  * write them, so a zoom does not re-render a single component — which is what makes it affordable for

package/dist/events/LayoutDriver.js

@@ -5,14 +5,12 @@ import { Frustum } from 'three';
 import { useCameraControls } from '../controls';
 import { measurePixelSize, measureRoll, pixelSizeMoved } from '../space/layout-measure';
 import { useSpace } from '../space/Space';
-import { createLogger } from '../utils/logging';
 import { planFrustum } from './def-culling';
 import { createLayoutTargets, LayoutTargetsContext } from './layout-targets';
-const logger = createLogger('layout');
 /**
- * How much of a frame one drain may spend running layout rules, in milliseconds — the same budget
- * the legacy renderer's `UpdatesSystem` drained its update queue with. Small enough to leave a
- * 60fps frame its render; the backlog it leaves is carried into the next frame, visible defs first.
+ * How much of a frame one drain may spend writing laid-out defs into their slots, in milliseconds —
+ * the same budget the legacy renderer's `UpdatesSystem` drained its update queue with. Small enough
+ * to leave a 60fps frame its render; the backlog it leaves is carried into the next frame.
  */
 const LAYOUT_BUDGET_MS = 3;
 /**
@@ -25,12 +23,12 @@ const LAYOUT_BUDGET_MS = 3;
  * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
  * costs nothing at all.
  *
- * A move starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
- * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
- * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
- * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
- * stay inside the frame callback, before three's own render, so their attribute writes upload in
- * the very frame that draws them.
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
  *
  * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
  * write them, so a zoom does not re-render a single component — which is what makes it affordable for
@@ -62,7 +60,6 @@ export function LayoutDriver(props) {
         // The epsilon compares against the sweep's target size, so a camera that stopped mid-sweep does
         // not re-mark the same sweep on every one of the frames that finish it.
         if (pixelSize !== undefined && pixelSizeMoved(pixelSize, targets.pixelSize)) {
-            logger.debug(`pxToSvgScale ${+pixelSize.toFixed(3)}`);
             targets.applyScale(pixelSize);
         }
         // Roll has no epsilon — the imperative renderer swept its roll handlers on any bearing change

package/dist/events/layout-targets.d.ts

@@ -5,67 +5,68 @@ import { type LayerDef, type RenderableDef } from '../types/defs';
  * layout axes.
  *
  * Every def here declares its own `onScale` or `onRoll` — the registry never holds a handler, only
- * the value each def's rule last ran at, per axis. One registry per renderer, reached through {@link LayoutTargetsContext},
- * so two renderers showing the same defs at different zooms do not lay each other's out.
+ * the value each def's rule last ran at, per axis. One registry per renderer, reached through
+ * {@link LayoutTargetsContext}, so two renderers showing the same defs at different zooms do not lay
+ * each other's out.
  *
- * A pixel-size move is a **sweep**, not a synchronous pass: {@link applyScale} marks every registered def
- * stale and {@link drain} works the backlog off a frame's budget at a time, defs the camera can see
- * first. The shape is the legacy renderer's `UpdatesSystem` (fp-engine `core/updates.ts`), whose
- * pending/deferred queues and per-frame time budget this registry inherits — with the queue's unit
- * changed from "def whose fields moved" to "def whose layout rule must re-run".
+ * A move splits in two. **The rules all run at once**, in the frame that noticed it: they are the
+ * cheap half — arithmetic over a def's own fields — and running them together is what lets every
+ * def's *decision*, a dot's "show me now" included, exist the moment the camera moves. **The writes
+ * are a sweep**: what the rules reported changed is queued and {@link drain} carries it to the GPU a
+ * frame's budget at a time — defs whose visibility flipped first, then the rest the camera can see,
+ * then the culled. The queue's shape is the legacy renderer's `UpdatesSystem` (fp-engine
+ * `core/updates.ts`); its unit is a def whose fields moved.
  */
 export interface LayoutTargets {
     /**
-     * The pixel size the registered defs are laid out at — from the moment {@link applyScale} marks a
-     * sweep, the size defs are being *brought* to, which is what the driver's epsilon must compare
-     * against so a camera that stopped moving does not re-mark the same sweep every frame.
+     * The pixel size the registered defs are laid out at, which is what the driver's epsilon compares
+     * against.
      */
     readonly pixelSize: number;
     /**
      * The roll the registered defs are laid out at, in radians clockwise from north — the second
-     * layout axis, compared the way {@link pixelSize} is: against the sweep's target, not the last
-     * drained value.
+     * layout axis, compared the way {@link pixelSize} is.
      */
     readonly roll: number;
-    /** Whether a sweep still has defs to lay out — what makes a caller keep frames coming. */
+    /** Whether writes are still queued — what makes a caller keep frames coming. */
     readonly hasWork: boolean;
     /**
-     * Registers defs for re-layout, and lays out the ones that are not current — so a def is current
-     * from the moment it is registered, and a membership change re-lays out only what it added.
+     * Registers defs for re-layout, and lays out and writes the ones that are not current — so a def
+     * is current from the moment it is registered, and a membership change re-lays out only what it
+     * added.
      * @param defs - The defs to lay out; every one of them declares an `onScale` or an `onRoll`.
      * @returns An unregister function; it also drops whatever of these defs a sweep still queued.
      */
     register(defs: readonly RenderableDef[]): () => void;
     /**
-     * Starts a sweep: records the new pixel size and marks every registered def stale. Nothing is
-     * laid out here — that is {@link drain}'s job — so the frame that noticed the move pays only the
-     * marking. Applying again mid-sweep re-marks at the newer size, and a def the earlier sweep had
-     * not reached is simply laid out once, at that newer size: the backlog coalesces by construction.
+     * Records the new pixel size and runs every registered scale rule against it, queueing what they
+     * report changed. Nothing is written here — that is {@link drain}'s job. Applying again before
+     * the queue drains re-runs the rules at the newer size, and a queued def is written once, with
+     * whatever its fields hold by then: the writes coalesce by construction.
      * @param pixelSize - The new pixel size.
      */
     applyScale(pixelSize: number): void;
     /**
-     * Starts a roll sweep — {@link applyScale}'s counterpart on the other axis, marking only the defs that
-     * declare an `onRoll`. The two axes coalesce independently, and one {@link drain} works both off.
+     * {@link applyScale}'s counterpart on the other axis, running only the rules that declare an
+     * `onRoll`. Both axes feed the one write queue.
      * @param roll - The new roll, in radians clockwise from north.
      */
     applyRoll(roll: number): void;
     /**
-     * Works off the sweep within a frame's budget, and says whether any backlog remains — the
-     * caller's cue to ask for another frame.
+     * Writes queued defs within a frame's budget, and says whether any remain — the caller's cue to
+     * ask for another frame.
      *
-     * Two passes, in the legacy `UpdatesSystem`'s shape: the stale defs first, except that a hidden
-     * def or one the frustum rejects is *deferred* rather than laid out; then the deferred ones, with
-     * whatever budget is left. Priority is all deferral buys — every def is still laid out before the
-     * sweep ends, because whether a def draws can be exactly what its rule decides.
+     * Three passes, in priority order: defs whose rule flipped them between hidden and shown, then
+     * every other queued def, then the ones an earlier pass deferred because the frustum rejects
+     * them. A flip matters most because it is what the user sees change — a label vanishing or a dot
+     * appearing — while a resize of something already shown can wait a frame.
      *
-     * **A drain always takes at least one def**, across the two passes together, however little
-     * budget is left — including none, which is what a worker descheduled before the first check
-     * leaves. That is what makes a sweep unable to stall: each drain shortens the backlog, so the
-     * frames the driver keeps asking for eventually end it. Without the guarantee a drain can dequeue
-     * nothing, return "more to do", and be asked again on the next frame with the same result.
-     * @param frustum - The camera's frustum in plan space, when the caller has one; without it only
-     *   hidden defs are deferred.
+     * **A drain always takes at least one def**, however little budget is left — including none,
+     * which is what a worker descheduled before the first check leaves. That is what makes a sweep
+     * unable to stall: each drain shortens the queue, so the frames the driver keeps asking for
+     * eventually end it.
+     * @param frustum - The camera's frustum in plan space, when the caller has one; without it
+     *   nothing is deferred.
      * @param budgetMs - How much of the frame a call may spend. Non-positive means no limit.
      * @returns Whether defs remain for a later drain.
      */

package/dist/events/layout-targets.js

@@ -52,9 +52,9 @@ export function useLayoutTargets(layer, children) {
 export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
     const groups = new Set();
     /**
-     * The pixel size each def was last laid out at — the whole of the registry's state, because the
-     * rule that lays a def out is the def's own. Keyed by def rather than by group, so a membership
-     * change re-lays out only the defs that joined.
+     * The pixel size each def was last laid out at — the registry's layout state, because the rule
+     * that lays a def out is the def's own. Keyed by def rather than by group, so a membership change
+     * re-lays out only the defs that joined.
      *
      * A def whose `onScale` is *replaced* after it was laid out is not noticed: the record says only
      * "laid out at this size". Reassigning a handler is a thing nothing does — a def is built with its
@@ -63,21 +63,25 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
     const layouts = new WeakMap();
     /**
      * The roll each def's `onRoll` last ran at — the other axis's record, kept apart from
-     * {@link layouts} because the two move independently: a zoom leaves every roll record current,
-     * and a turn leaves every scale record current.
+     * {@link layouts} because the two move independently.
      */
     const rolls = new WeakMap();
     /**
-     * The sweep's backlog: defs an `apply` marked stale and {@link LayoutTargets.drain} has not
-     * reached. **One queue for every axis** — which of a queued def's rules actually runs is decided
-     * at drain time by the per-axis records above, so a def stale on both axes is dequeued once and
-     * laid out on both, and a new axis adds a record and a rule, never another queue. `deferred`
-     * holds the ones a drain pushed behind the visible — hidden defs, and defs the frustum
-     * rejected — worked off with whatever budget the stale pass leaves. Sets, not arrays, because one
-     * def can be re-marked while queued and must not be laid out twice.
+     * Whether each def was hidden when it was last written — what tells a visibility flip from a
+     * resize. Seeded at registration, which is when the def's instance wrote what it held.
      */
-    const pending = new Set();
+    const drawnHidden = new WeakMap();
+    /**
+     * The write queue, in priority order: defs a rule flipped between hidden and shown, then every
+     * other def a rule changed, then the ones a drain found outside the frustum. Sets, not arrays,
+     * because a def re-reported before its write must still be written once — with whatever its
+     * fields hold by then.
+     */
+    const flipped = new Set();
+    const queued = new Set();
     const deferred = new Set();
+    /** What the sweep in flight has cost so far, for the log line that closes it. */
+    let sweep;
     let current = pixelSize;
     let currentRoll = roll;
     /**
@@ -87,81 +91,90 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
      */
     const view = { pixelSize: current, roll: currentRoll };
     /**
-     * Runs a def's handler and writes the result.
-     *
-     * A leaf goes through the def's own registered sync — the same closure the React path runs after
-     * `update(def)` — so a handler mutating def fields needs no `update()` call of its own, and the two
-     * paths cannot disagree about what a def looks like. A def whose instance has not mounted yet syncs
-     * to nothing here and picks the mutation up when it does. A layer among the returned defs is
-     * reconciled instead, which is how a handler changes its own membership.
+     * Runs whatever of a def's rules are stale by their records, scale before roll so a rule that
+     * turns a label re-fits it at the size just applied. Each rule is recorded as run before anything
+     * it reported is handled, because handling can reach back in here.
      *
-     * A handler reporting nothing skips that write, which is the whole point of the return value: it is
-     * the half that costs. The def is still recorded as laid out, so a membership change does not run
-     * the handler over it again.
+     * A rule reporting nothing is still recorded as run, so a membership change does not run it over
+     * the def again — reporting nothing is how a rule skips the write, which is the half that costs.
      * @param def - The def to lay out.
-     * @returns Whether anything was written.
+     * @param report - Receives what each rule reported changed.
      */
-    function layOut(def) {
+    function layOutStale(def, report) {
         // Hidden defs are laid out too. Whether a def draws at all can be exactly what its rule decides
         // — a booth's dot appears only once the plan is far enough out for its label to stop fitting —
-        // so a registry that skipped them would never run the rule that would bring them back. Skipping
-        // the *waste* is the rule's own job instead: a handler with nothing worth drawing returns
-        // nothing, and the slot write is the half that costs.
-        if (!def.onScale || layouts.get(def) === current)
-            return false;
-        const changed = def.onScale(view);
-        // Recorded before the write, which runs the def's own sync and can reach back in here.
-        layouts.set(def, current);
-        if (!changed || changed.length === 0)
-            return false;
-        writeChanged(changed);
-        return true;
+        // so a registry that skipped them would never run the rule that would bring them back.
+        if (def.onScale && layouts.get(def) !== current) {
+            const changed = def.onScale(view);
+            layouts.set(def, current);
+            if (changed?.length)
+                report(changed);
+        }
+        if (def.onRoll && rolls.get(def) !== currentRoll) {
+            const changed = def.onRoll(view);
+            rolls.set(def, currentRoll);
+            if (changed?.length)
+                report(changed);
+        }
     }
     /**
-     * Runs a def's roll rule and writes the result — {@link layOut} on the other axis, with the same
-     * record-before-write ordering and the same "an empty return skips the write" contract.
-     * @param def - The def to lay out.
-     * @returns Whether anything was written.
+     * Writes a def now — the layer path or the slot path, per `writeChanged` — and records whether
+     * what it drew was hidden.
+     * @param def - The def to write.
      */
-    function layOutRoll(def) {
-        if (!def.onRoll || rolls.get(def) === currentRoll)
-            return false;
-        const changed = def.onRoll(view);
-        rolls.set(def, currentRoll);
-        if (!changed || changed.length === 0)
-            return false;
-        writeChanged(changed);
-        return true;
+    function write(def) {
+        drawnHidden.set(def, def.hidden === true);
+        writeChanged([def]);
     }
     /**
-     * Runs whatever of a def's rules are stale by their records — the one unit of work a dequeued def
-     * costs, scale before roll so a rule that turns a label re-fits it at the size just applied.
-     * @param def - The def to lay out.
-     * @returns Whether anything was written.
+     * Queues what a rule reported changed. A layer is written at once: its change is a membership
+     * change, which only React reconciles, and React already defers the sweep behind it.
+     * @param changed - The defs the rule reported.
      */
-    function layOutStale(def) {
-        const scaled = layOut(def);
-        const rolled = layOutRoll(def);
-        return scaled || rolled;
+    function enqueue(changed) {
+        for (const def of changed) {
+            if (isLayerDef(def)) {
+                write(def);
+                continue;
+            }
+            const drawn = drawnHidden.get(def);
+            if (drawn !== undefined && drawn !== (def.hidden === true)) {
+                queued.delete(def);
+                deferred.delete(def);
+                flipped.add(def);
+            }
+            else {
+                // Flipped and flipped back before its write: against what the slot holds it is a resize.
+                flipped.delete(def);
+                deferred.delete(def);
+                queued.add(def);
+            }
+        }
     }
     /**
-     * Marks stale defs for the sweep: the previous sweep's deferrals rejoin the queue — where the new
-     * frustum decides their priority afresh, and cross-axis work survives whichever axis moved — and
-     * every def carrying the moved axis's rule is (re-)queued.
-     * @param carriesRule - Whether a def declares the moved axis's rule.
+     * Runs the stale rules of every registered def the moved axis concerns, queueing their writes.
+     * @param axis - The axis that moved, for the log line.
+     * @param handler - The moved axis's handler, `onScale` or `onRoll`.
      */
-    function requeue(carriesRule) {
-        for (const def of deferred)
-            pending.add(def);
-        deferred.clear();
-        // Rule presence is read at marking time, so a rule cleared after registration — a hidden
-        // bookmark's — simply stops queueing, with nothing to unregister.
+    function runHandlers(axis, handler) {
+        const start = performance.now();
+        const before = flipped.size + queued.size + deferred.size;
+        let ran = 0;
         for (const defs of groups) {
             for (const def of defs) {
-                if (carriesRule(def))
-                    pending.add(def);
+                if (!def[handler])
+                    continue;
+                ran++;
+                layOutStale(def, enqueue);
             }
         }
+        const pending = flipped.size + queued.size + deferred.size;
+        if (pending > before) {
+            sweep ??= { defs: 0, drains: 0, writeMs: 0 };
+            sweep.defs += pending - before;
+        }
+        logger.debug(`${axis}: ran ${ran} ${handler} handlers in ${(performance.now() - start).toFixed(2)}ms, ` +
+            `${pending} defs to write (${flipped.size} visibility flips)`);
     }
     return {
         get pixelSize() {
@@ -171,25 +184,33 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
             return currentRoll;
         },
         get hasWork() {
-            return pending.size > 0 || deferred.size > 0;
+            return flipped.size > 0 || queued.size > 0 || deferred.size > 0;
         },
         register(defs) {
             groups.add(defs);
-            let laidOut = false;
+            let wrote = false;
             for (const def of defs) {
-                if (layOutStale(def))
-                    laidOut = true;
+                if (!drawnHidden.has(def))
+                    drawnHidden.set(def, def.hidden === true);
+                // Written at once, not queued: a def is current from the moment it registers, so one
+                // mounting mid-zoom draws at the size the plan is at.
+                layOutStale(def, (changed) => {
+                    for (const each of changed)
+                        write(each);
+                    wrote = true;
+                });
             }
             // Registration happens in an effect rather than inside the frame loop, so anything written here
             // needs a frame asking for it.
-            if (laidOut)
+            if (wrote)
                 invalidate();
             return () => {
                 groups.delete(defs);
-                // A queued def whose layer is gone must not be laid out from the backlog: its instances are
-                // unmounting, and its handler may read state its owner already tore down.
+                // A queued def whose layer is gone must not be written from the backlog: its instances are
+                // unmounting.
                 for (const def of defs) {
-                    pending.delete(def);
+                    flipped.delete(def);
+                    queued.delete(def);
                     deferred.delete(def);
                 }
             };
@@ -197,59 +218,58 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
         applyScale(nextPixelSize) {
             current = nextPixelSize;
             view.pixelSize = nextPixelSize;
-            requeue((def) => def.onScale !== undefined);
+            runHandlers(`pxToSvgScale ${+nextPixelSize.toFixed(3)}`, 'onScale');
         },
         applyRoll(nextRoll) {
             currentRoll = nextRoll;
             view.roll = nextRoll;
-            requeue((def) => def.onRoll !== undefined);
+            runHandlers(`roll ${+nextRoll.toFixed(3)}`, 'onRoll');
         },
         drain(frustum, budgetMs = -1) {
-            if (pending.size === 0 && deferred.size === 0)
+            if (flipped.size === 0 && queued.size === 0 && deferred.size === 0)
                 return false;
             const start = performance.now();
-            let wrote = 0;
             /**
-             * Defs this drain has taken off a queue, laid out or deferred.
+             * Defs this drain has taken off a queue, written or deferred.
              *
              * It gates the budget so that the **first** def of a drain is always taken. Without that, a
              * budget already spent before the loop began — the worker descheduled between `start` and the
              * check, which a loaded machine does routinely — dequeues nothing at all, and a drain that
-             * dequeues nothing is the stall this budget exists to prevent. Shared across both passes, so
-             * the guarantee is one def per drain rather than one per pass.
+             * dequeues nothing is the stall this budget exists to prevent.
              */
             let processed = 0;
             const overBudget = () => processed > 0 && budgetMs > 0 && performance.now() - start >= budgetMs;
-            // Sets iterate in insertion order and tolerate deletion mid-walk, which is what makes the two
-            // passes below plain loops: the order moves arrived is the priority within a pass, and a
-            // processed def leaves its set before its rules run.
-            for (const def of pending) {
-                if (overBudget())
-                    break;
-                processed++;
-                pending.delete(def);
-                // Deferral is priority, never a skip: a hidden def, or one the camera cannot see, joins the
-                // second pass rather than being laid out now. `def.hidden` needs no frustum — hidden is not
-                // drawn wherever it sits.
-                if (def.hidden === true || (frustum !== undefined && culledBy(def, frustum))) {
-                    deferred.add(def);
-                    continue;
+            // Sets iterate in insertion order and tolerate deletion mid-walk, which is what makes each pass
+            // a plain loop: a written def leaves its set before its write runs.
+            for (const queue of [flipped, queued]) {
+                for (const def of queue) {
+                    if (overBudget())
+                        break;
+                    processed++;
+                    queue.delete(def);
+                    // Deferral is priority, never a skip: a def the camera cannot see joins the last pass.
+                    if (frustum !== undefined && culledBy(def, frustum)) {
+                        deferred.add(def);
+                        continue;
+                    }
+                    write(def);
                 }
-                if (layOutStale(def))
-                    wrote++;
             }
             for (const def of deferred) {
                 if (overBudget())
                     break;
                 processed++;
                 deferred.delete(def);
-                if (layOutStale(def))
-                    wrote++;
+                write(def);
             }
-            const remaining = pending.size + deferred.size;
-            if (wrote > 0) {
-                const took = (performance.now() - start).toFixed(2);
-                logger.debug(`laid out ${wrote} defs (${remaining} remaining) in ${took}ms`);
+            const remaining = flipped.size + queued.size + deferred.size;
+            if (sweep) {
+                sweep.drains++;
+                sweep.writeMs += performance.now() - start;
+                if (remaining === 0) {
+                    logger.debug(`wrote ${sweep.defs} defs over ${sweep.drains} frames in ${sweep.writeMs.toFixed(2)}ms`);
+                    sweep = undefined;
+                }
             }
             return remaining > 0;
         },

package/dist/objects/containers/hooks.d.ts

@@ -42,10 +42,20 @@ export declare function useSlot<R>(container: SlotContainer<R>, def: RenderableD
  * never drawn, so computing its transform, color, or glyphs would be wasted; the update that shows
  * it re-runs this sync, which writes the then-current state. Everything type-specific stays in
  * `write`, which is what keeps this hook generic across every def type.
+ *
+ * **An `update(def)` renders nothing unless the slot's resource moved.** The only thing a render of
+ * an instance can do that a sync cannot is re-claim its slot, and that is needed only when the
+ * resource backing it changed — a text's line count, a shape's geometry. So the store's snapshot is
+ * the resource itself, not a version counter: an update that leaves it alone (a dim, a color, a
+ * move) is written by the subscription's own listener, straight into the slot, and React bails out
+ * of the render because the snapshot is unchanged. An update that moves it renders, and the render's
+ * re-claim writes the def into the new slot.
  * @param container - The container holding the slot.
  * @param def - The def this instance renders.
- * @param resource - The per-instance resource backing the slot; a new identity re-claims.
+ * @param resourceOf - Reads the per-instance resource backing the slot off the def; a new identity
+ *   re-claims. Called on every update, so it must be cheap and return the same identity for an
+ *   unchanged def. `null` for a container whose slots need no resource, which never re-claims.
  * @param write - Writes the def's type-specific state into its slot. Called only while visible.
  */
-export declare function useDefSync<R>(container: SlotContainer<R>, def: RenderableDef, resource: R, write: (slot: number) => void): void;
+export declare function useDefSync<R>(container: SlotContainer<R>, def: RenderableDef, resourceOf: (() => R) | null, write: (slot: number) => void): void;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/objects/containers/hooks.js

@@ -1,8 +1,8 @@
-import { useThree } from '@react-three/fiber';
+import { useStore } from '@react-three/fiber';
 import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { registerHitResolver } from '../../events/pointer';
-import { registerSlotWriter, subscribeDef, syncNow, versionOf } from '../../update';
-import { useLayerDim } from '../layer/layer-context';
+import { registerSlotWriter, subscribeDef, syncNow } from '../../update';
+import { resolveDim, subscribeDim, useDimChain } from '../layer/layer-context';
 /**
  * Creates one layer's container and keeps it wired to its layer for as long as the component is
  * mounted: the membership's paint order, how hits on its mesh resolve back to defs, and what runs
@@ -21,19 +21,37 @@ import { useLayerDim } from '../layer/layer-context';
  */
 export function useContainer(create, defs, onKindMismatch) {
     const [container] = useState(create);
-    // Only whether the layer is dimmed, not by how much: the order pass splits two ways, so an eased
-    // dim re-runs it as its value crosses zero rather than on every frame of the ease.
-    const layerDimmed = useLayerDim() > 0;
-    const invalidate = useThree((state) => state.invalidate);
+    const chain = useDimChain();
+    const invalidate = useInvalidate();
+    // The membership the dim subscription below re-orders, current as of the last commit.
+    const defsRef = useRef(defs);
+    useEffect(() => {
+        defsRef.current = defs;
+    });
     // Paint order for the whole membership, one pass per structural change. Child effects run before
     // this one, so every instance the change mounted has already claimed its slot; defs whose
     // instances bailed out (memo) never re-ran, which is fine — order lives in the container, not in
     // their props. Running inside the same effect flush as the claims is what keeps a frame from
     // drawing between a claim's default order and this pass.
     useEffect(() => {
-        container.setPaintOrder(defs, layerDimmed);
+        container.setPaintOrder(defs, resolveDim(chain) > 0);
         invalidate();
-    }, [container, defs, layerDimmed, invalidate]);
+    }, [container, defs, chain, invalidate]);
+    // And again as the layer's dim crosses zero — only whether it is dimmed, not by how much, since the
+    // order pass splits two ways. Followed by subscription, not render: an eased dim crosses zero once
+    // for every container in the plan in the same frame, and rendering each of them to get here cost
+    // that frame more than the passes themselves.
+    useEffect(() => {
+        let dimmed = resolveDim(chain) > 0;
+        return subscribeDim(chain, () => {
+            const next = resolveDim(chain) > 0;
+            if (next === dimmed)
+                return;
+            dimmed = next;
+            container.setPaintOrder(defsRef.current, next);
+            invalidate();
+        });
+    }, [container, chain, invalidate]);
     // How a hit on this container's mesh becomes a def. From an effect, so the mesh is bound by now;
     // the container answers which field of an intersection names its slot, so nothing here has to know
     // one mesh kind from another.
@@ -61,7 +79,7 @@ export function useContainer(create, defs, onKindMismatch) {
  */
 export function useSlot(container, def, resource) {
     const slotRef = useRef(-1);
-    const invalidate = useThree((state) => state.invalidate);
+    const invalidate = useInvalidate();
     useEffect(() => {
         const slot = container.claim(def, resource);
         slotRef.current = slot;
@@ -91,15 +109,36 @@ export function useSlot(container, def, resource) {
  * never drawn, so computing its transform, color, or glyphs would be wasted; the update that shows
  * it re-runs this sync, which writes the then-current state. Everything type-specific stays in
  * `write`, which is what keeps this hook generic across every def type.
+ *
+ * **An `update(def)` renders nothing unless the slot's resource moved.** The only thing a render of
+ * an instance can do that a sync cannot is re-claim its slot, and that is needed only when the
+ * resource backing it changed — a text's line count, a shape's geometry. So the store's snapshot is
+ * the resource itself, not a version counter: an update that leaves it alone (a dim, a color, a
+ * move) is written by the subscription's own listener, straight into the slot, and React bails out
+ * of the render because the snapshot is unchanged. An update that moves it renders, and the render's
+ * re-claim writes the def into the new slot.
  * @param container - The container holding the slot.
  * @param def - The def this instance renders.
- * @param resource - The per-instance resource backing the slot; a new identity re-claims.
+ * @param resourceOf - Reads the per-instance resource backing the slot off the def; a new identity
+ *   re-claims. Called on every update, so it must be cheap and return the same identity for an
+ *   unchanged def. `null` for a container whose slots need no resource, which never re-claims.
  * @param write - Writes the def's type-specific state into its slot. Called only while visible.
  */
-export function useDefSync(container, def, resource, write) {
+export function useDefSync(container, def, resourceOf, write) {
+    // A container without resources is a `SlotContainer<null>`, so `null` is the resource it claims.
+    const readResource = (resourceOf ?? readNull);
+    const invalidate = useInvalidate();
+    // Refreshed after every render below; declared first because the subscription reaches for it.
+    const syncRef = useRef(noop);
+    const resource = useSyncExternalStore((listener) => subscribeDef(def, () => {
+        // This instance's own write rather than `syncNow`, which runs every instance drawing the
+        // def: each of them holds a subscription of its own, so `syncNow` here would write a def
+        // with N instances N² times.
+        syncRef.current();
+        invalidate();
+        listener();
+    }), readResource);
     const slotRef = useSlot(container, def, resource);
-    const version = useSyncExternalStore((listener) => subscribeDef(def, listener), () => versionOf(def));
-    const invalidate = useThree((state) => state.invalidate);
     /**
      * Writes the def's current state into its slot: visibility always, the rest only when shown.
      */
@@ -107,6 +146,11 @@ export function useDefSync(container, def, resource, write) {
         const slot = slotRef.current;
         if (slot < 0)
             return;
+        // The slot was claimed for the resource this render saw. When the def has since moved on to
+        // another — more lines than the claimed group holds — the write would overrun it; the render
+        // the change triggers re-claims and writes then.
+        if (!Object.is(readResource(), resource))
+            return;
         const visible = !def.hidden;
         container.setVisibleAt(slot, visible);
         // Written even while hidden, unlike everything in `write`: it is one number, and writing it
@@ -118,16 +162,35 @@ export function useDefSync(container, def, resource, write) {
         write(slot);
     }
     // Held in a ref and refreshed after every render: `sync` closes over a fresh `write` each time,
-    // and the effect below must not re-run just because that identity changed — only a version bump
-    // means the def actually moved.
-    const syncRef = useRef(sync);
+    // and the effect below must not re-run just because that identity changed — only a new def or a
+    // new resource means the slot needs writing from here.
     useEffect(() => {
         syncRef.current = sync;
     });
     useEffect(() => registerSlotWriter(def, () => syncRef.current(), invalidate), [def, invalidate]);
-    // Through the registry rather than the ref, so the React path runs the very same write every other
-    // path does — the frame request that shows it included.
+    // The first write, and the one after a re-claim. Declared after the ref refresh above, so it runs
+    // the closure that knows the new resource — `useSlot`'s own sync ran the previous render's, which
+    // the resource check turned into a no-op. Through the registry, so the frame request that shows it
+    // comes with it.
     useEffect(() => {
         syncNow(def);
-    }, [def, version]);
+    }, [def, resource]);
+}
+/**
+ * The renderer's frame request, without subscribing to R3F's store for it.
+ *
+ * `useThree(selector)` subscribes, and every instance holds this hook's result — so with a selector
+ * each R3F state change (a canvas re-render re-configures the root) ran one selector per instance,
+ * tens of thousands on a large plan, for a value that never changes. The store handle is context
+ * alone, and reading `invalidate` at call time also follows a host that replaces it (external mode).
+ * @returns A stable function requesting a frame.
+ */
+function useInvalidate() {
+    const store = useStore();
+    const [invalidate] = useState(() => () => store.getState().invalidate());
+    return invalidate;
 }
+// The resource of an instance whose container needs none.
+const readNull = () => null;
+// What an instance's sync ref holds before its first render has committed.
+const noop = () => undefined;

package/dist/objects/images/ImageInstance.js

@@ -20,7 +20,7 @@ import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
  */
 export const ImageInstance = memo(function ImageInstance(props) {
     const { def, packed, container } = props;
-    useDefSync(container, def, packed, (slot) => {
+    useDefSync(container, def, () => packed, (slot) => {
         const tile = tileRect(packed);
         writeImageMatrix(container, slot, def, tile);
         writeImageAnchor(container, slot, def, tile);

package/dist/objects/layer/Layer.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense } from 'react';
+import { memo, Suspense } from 'react';
 import { useLayoutTargets } from '../../events/layout-targets';
 import { usePointerProps } from '../../events/pointer';
 import { isImageDefs, isLayerDefs, isLineDefs, isModelDefs, isShapeDefs, isTextDefs, } from '../../types/guards';
@@ -8,7 +8,7 @@ import { Lines } from '../lines';
 import { Models } from '../models';
 import { Shapes } from '../shapes';
 import { Texts } from '../text';
-import { LayerDimContext, LayerOverlayContext, useLayerDim, useLayerOverlay, } from './layer-context';
+import { LayerDimContext, LayerOverlayContext, useDimChain, useLayerOverlay, } from './layer-context';
 import { useStagedChildren } from './mount-scheduler';
 import { useVisibilityGui } from './visibility-gui';
 /**
@@ -26,7 +26,36 @@ import { useVisibilityGui } from './visibility-gui';
 export function Layer(props) {
     const { layer, children } = props;
     useVisibilityGui(layer);
-    return (_jsx(LayerNode, { layer: layer, hidden: false, orderBase: 0, orderStep: 1, children: children }));
+    return (_jsx(MemoLayerNode, { layer: layer, hidden: false, orderBase: 0, orderStep: 1, children: children }));
+}
+/**
+ * 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, mounted } = props;
+    let content = null;
+    if (isShapeDefs(defs))
+        content = _jsx(Shapes, { defs: defs, mounted: mounted });
+    else if (isImageDefs(defs))
+        content = _jsx(Images, { defs: defs, mounted: mounted });
+    else if (isTextDefs(defs))
+        content = _jsx(Texts, { defs: defs, mounted: mounted });
+    else if (isLineDefs(defs))
+        content = _jsx(Lines, { defs: defs, mounted: mounted });
+    else if (isModelDefs(defs))
+        content = _jsx(Models, { defs: defs, mounted: mounted });
+    return _jsx(Suspense, { fallback: null, children: content });
 }
 /**
  * One layer of the tree as a three.js `<group>`, recursing into its child layers.
@@ -46,6 +75,11 @@ export function Layer(props) {
  *
  * Draw order is a pair: the tier, then the layer's own place. `overlay` adds a whole band above
  * every plan-tier value. Array order still decides strictly within each band.
+ *
+ * **Dim is handed down as a source, and the node is rendered memoized.** An `update(layer)` renders this node
+ * alone: its child layers receive identical props, and the dim they inherit reaches its consumers
+ * through subscriptions to the layers themselves rather than a context value, so an eased dim — an update per frame
+ * on the root — renders one node instead of the whole tree.
  * @param props - The node props.
  * @returns The `<group>` for a layer def.
  */
@@ -53,16 +87,16 @@ function LayerNode(props) {
     const { layer, children: prelude, hidden: parentHidden, orderBase, orderStep } = props;
     // What the nearest ancestor already resolved for dim and overlay. A layer cannot see its
     // ancestors any other way.
-    const parentDim = useLayerDim();
+    const parentChain = useDimChain();
     const parentOverlay = useLayerOverlay();
     // Once hidden or once in the overlay tier, a subtree stays that way. A descendant that dropped
     // back into the plan tier would invert the nesting, and a descendant of a hidden layer is not on
     // screen whatever it says about itself.
     const hidden = parentHidden || layer.hidden === true;
     const overlay = parentOverlay || layer.overlay === true;
-    // Nearest declaration wins, so only `undefined` inherits. A layer's own 0 un-dims it inside a
-    // dimmed ancestor.
-    const dim = layer.dim ?? parentDim;
+    // Nearest first, so the chain resolves to this layer's own dim when it declares one. Stable for a
+    // mounted layer, so the consumers below follow its dim by subscription, never by render.
+    const dimChain = [layer, ...parentChain];
     // On screen only if nothing above hides it either. This is the value picking hangs off.
     const visible = !hidden;
     const { children, mounted } = useStagedChildren(layer);
@@ -71,7 +105,7 @@ function LayerNode(props) {
     let contents = null;
     if (isLayerDefs(children)) {
         const childStep = orderStep / children.length;
-        contents = children.map((child, index) => (_jsx(LayerNode, { layer: child, hidden: hidden, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
+        contents = children.map((child, index) => (_jsx(MemoLayerNode, { layer: child, hidden: hidden, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
     }
     else if (mounted > 0) {
         contents = _jsx(LeafContent, { defs: children, mounted: mounted });
@@ -80,37 +114,13 @@ function LayerNode(props) {
     // Always provided, never only when the layer declares one. Making a provider appear on first use
     // would change this component's element type and remount the subtree, which releases and re-claims
     // every GPU slot beneath it.
-    return (_jsx(LayerDimContext, { value: dim, children: _jsx(LayerOverlayContext, { value: overlay, children: group }) }));
+    return (_jsx(LayerDimContext, { value: dimChain, children: _jsx(LayerOverlayContext, { value: overlay, 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.
+ * {@link LayerNode}, memoized — what both the root and the recursion render, so an update renders
+ * the one node it names and its child layers bail out on equal props.
  */
-function LeafContent(props) {
-    const { defs, mounted } = props;
-    let content = null;
-    if (isShapeDefs(defs))
-        content = _jsx(Shapes, { defs: defs, mounted: mounted });
-    else if (isImageDefs(defs))
-        content = _jsx(Images, { defs: defs, mounted: mounted });
-    else if (isTextDefs(defs))
-        content = _jsx(Texts, { defs: defs, mounted: mounted });
-    else if (isLineDefs(defs))
-        content = _jsx(Lines, { defs: defs, mounted: mounted });
-    else if (isModelDefs(defs))
-        content = _jsx(Models, { defs: defs, mounted: mounted });
-    return _jsx(Suspense, { fallback: null, children: content });
-}
+const MemoLayerNode = memo(LayerNode);
 /**
  * Where the plan's own layers are numbered from. The tree subdivides `[0, 1)` depth first, so the
  * mantissa stays free for nesting.

package/dist/objects/layer/layer-context.d.ts

@@ -1,29 +1,62 @@
+import { type LayerDef } from '../../types/defs';
 /**
- * The dim amount a layer draws at, which every material beneath it reads.
- * @returns The nearest provided amount, or `0` with no layer above.
+ * The layers whose `dim` decides a subtree's, nearest first: the enclosing layer, then each of its
+ * ancestors. Nearest declaration wins, and a layer's own `0` un-dims it inside a dimmed ancestor.
+ *
+ * The chain rather than the resolved amount, because the amount animates — floorplan eases the
+ * venue's dim over 300ms, an `update(layer)` per frame — and a number in context re-rendered every
+ * consumer and every layer between on each of those frames. A chain never changes for a mounted
+ * layer, so the tree stays still: consumers read it with {@link resolveDim} and follow it with
+ * {@link subscribeDim}, which is the def store's own notification.
+ */
+export type DimChain = readonly LayerDef[];
+/**
+ * The dim amount a layer draws at, as a value, so the caller re-renders whenever it changes. A
+ * consumer that only writes the amount somewhere reads {@link useDimChain} and subscribes instead.
+ * @returns The nearest declared amount, or `0` with no layer above.
  */
 export declare function useLayerDim(): number;
+/**
+ * The enclosing layer's {@link DimChain}, for consumers that follow the dim without rendering: a
+ * material writing it into a uniform, a container re-running paint order when it crosses zero.
+ * @returns The chain, empty outside any layer.
+ */
+export declare function useDimChain(): DimChain;
 /**
  * Whether the current layer draws in the overlay tier.
  * @returns `true` if this layer or an ancestor opted into the overlay tier, `false` otherwise.
  */
 export declare function useLayerOverlay(): boolean;
 /**
- * The dim amount the current layer hands down to its descendants.
+ * Resolves a chain's dim amount.
+ * @param chain - The layers, nearest first.
+ * @returns The nearest declared dim, or `0` when none declares one.
+ */
+export declare function resolveDim(chain: DimChain): number;
+/**
+ * Follows every `update()` of a chain's layers — each one a possible dim change. The listener
+ * compares for itself; a membership update reaches it too and changes nothing.
+ * @param chain - The layers, nearest first.
+ * @param listener - Called after an update of any of them.
+ * @returns The unsubscribe function.
+ */
+export declare function subscribeDim(chain: DimChain, listener: () => void): () => void;
+/**
+ * The {@link DimChain} the current layer hands down to its descendants.
  *
  * Context rather than a prop, because the value crosses the whole subtree and concerns none of the
  * components between. A container hands its material nothing about layers, and a material that
  * never asked about them still dims correctly. Threading it as a prop would put a `dim` on every
  * material, every container, and every one of their inner components.
  *
- * Read through {@link useLayerDim} instead of directly. A `LayerNode` provides it, always, never
+ * Read through {@link useLayerDim} or {@link useDimChain} instead of directly. A `LayerNode` provides it, always, never
  * only when it declares a `dim` of its own. See `Layer.tsx` for why.
  *
- * Defaults to `0`, undimmed, which is what "no layer above me" means for a component rendered
+ * Defaults to an empty chain, which reads `0`, undimmed, which is what "no layer above me" means for a component rendered
  * outside a `Layer` tree. A fourth inherited field belongs in a context and a hook of its own here,
  * not folded into this one.
  */
-export declare const LayerDimContext: import("react").Context<number>;
+export declare const LayerDimContext: import("react").Context<DimChain>;
 /**
  * Whether the current layer hands its overlay tier down to its descendants.
  *

package/dist/objects/layer/layer-context.js

@@ -1,9 +1,20 @@
-import { createContext, use } from 'react';
+import { createContext, use, useSyncExternalStore } from 'react';
+import { subscribeDef } from '../../update';
 /**
- * The dim amount a layer draws at, which every material beneath it reads.
- * @returns The nearest provided amount, or `0` with no layer above.
+ * The dim amount a layer draws at, as a value, so the caller re-renders whenever it changes. A
+ * consumer that only writes the amount somewhere reads {@link useDimChain} and subscribes instead.
+ * @returns The nearest declared amount, or `0` with no layer above.
  */
 export function useLayerDim() {
+    const chain = use(LayerDimContext);
+    return useSyncExternalStore((listener) => subscribeDim(chain, listener), () => resolveDim(chain));
+}
+/**
+ * The enclosing layer's {@link DimChain}, for consumers that follow the dim without rendering: a
+ * material writing it into a uniform, a container re-running paint order when it crosses zero.
+ * @returns The chain, empty outside any layer.
+ */
+export function useDimChain() {
     return use(LayerDimContext);
 }
 /**
@@ -14,21 +25,47 @@ export function useLayerOverlay() {
     return use(LayerOverlayContext);
 }
 /**
- * The dim amount the current layer hands down to its descendants.
+ * Resolves a chain's dim amount.
+ * @param chain - The layers, nearest first.
+ * @returns The nearest declared dim, or `0` when none declares one.
+ */
+export function resolveDim(chain) {
+    for (const layer of chain) {
+        if (layer.dim !== undefined)
+            return layer.dim;
+    }
+    return 0;
+}
+/**
+ * Follows every `update()` of a chain's layers — each one a possible dim change. The listener
+ * compares for itself; a membership update reaches it too and changes nothing.
+ * @param chain - The layers, nearest first.
+ * @param listener - Called after an update of any of them.
+ * @returns The unsubscribe function.
+ */
+export function subscribeDim(chain, listener) {
+    const unsubscribes = chain.map((layer) => subscribeDef(layer, listener));
+    return () => {
+        for (const unsubscribe of unsubscribes)
+            unsubscribe();
+    };
+}
+/**
+ * The {@link DimChain} the current layer hands down to its descendants.
  *
  * Context rather than a prop, because the value crosses the whole subtree and concerns none of the
  * components between. A container hands its material nothing about layers, and a material that
  * never asked about them still dims correctly. Threading it as a prop would put a `dim` on every
  * material, every container, and every one of their inner components.
  *
- * Read through {@link useLayerDim} instead of directly. A `LayerNode` provides it, always, never
+ * Read through {@link useLayerDim} or {@link useDimChain} instead of directly. A `LayerNode` provides it, always, never
  * only when it declares a `dim` of its own. See `Layer.tsx` for why.
  *
- * Defaults to `0`, undimmed, which is what "no layer above me" means for a component rendered
+ * Defaults to an empty chain, which reads `0`, undimmed, which is what "no layer above me" means for a component rendered
  * outside a `Layer` tree. A fourth inherited field belongs in a context and a hook of its own here,
  * not folded into this one.
  */
-export const LayerDimContext = createContext(0);
+export const LayerDimContext = createContext([]);
 /**
  * Whether the current layer hands its overlay tier down to its descendants.
  *

package/dist/objects/materials/effects/color-dim.d.ts

@@ -8,7 +8,7 @@ import { type RenderableDef } from '../../../types/defs';
  */
 export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
 /**
- * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
+ * The dim patch every material installs, following the layer amount from {@link useDimChain}.
  *
  * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
  * so threading it as a prop would put a `dim` on each material, each container, and each of their
@@ -17,7 +17,8 @@ export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
  *
  * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
  * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
- * frame with no recompile.
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export declare function useDimPatch(): DimPatch;

package/dist/objects/materials/effects/color-dim.js

@@ -1,9 +1,9 @@
 import { useThree } from '@react-three/fiber';
 import { useEffect, useRef, useState } from 'react';
 import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source';
-import { useLayerDim } from '../../layer/layer-context';
+import { resolveDim, subscribeDim, useDimChain } from '../../layer/layer-context';
 /**
- * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
+ * The dim patch every material installs, following the layer amount from {@link useDimChain}.
  *
  * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
  * so threading it as a prop would put a `dim` on each material, each container, and each of their
@@ -12,11 +12,12 @@ import { useLayerDim } from '../../layer/layer-context';
  *
  * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
  * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
- * frame with no recompile.
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export function useDimPatch() {
-    const dim = useLayerDim();
+    const chain = useDimChain();
     const invalidate = useThree((state) => state.invalidate);
     // A ref, not state: this object is written after render, every frame of an eased dim, and a ref is
     // the container React sanctions that for. Its identity is what three holds onto, so the value can
@@ -25,11 +26,18 @@ export function useDimPatch() {
     // Created once and kept: R3F writes every changed prop onto the material, so handing it a fresh
     // handler each render risks a recompile per frame — the one thing an animated dim must not cost.
     const [patch] = useState(() => (parameters) => applyDim(parameters, uniformRef.current));
-    const amount = clampDim(dim);
     useEffect(() => {
-        uniformRef.current.value = amount;
-        invalidate();
-    }, [amount, invalidate]);
+        /** Writes the layer's current amount into the uniform, and asks for a frame when it moved. */
+        function follow() {
+            const amount = clampDim(resolveDim(chain));
+            if (uniformRef.current.value === amount)
+                return;
+            uniformRef.current.value = amount;
+            invalidate();
+        }
+        follow();
+        return subscribeDim(chain, follow);
+    }, [chain, invalidate]);
     return patch;
 }
 /**

package/dist/objects/shapes/ShapeInstance.js

@@ -24,8 +24,7 @@ const logger = createLogger('shape-instance');
  */
 export const ShapeInstance = memo(function ShapeInstance(props) {
     const { def, container } = props;
-    const geometry = container.geometryFor(def.shape);
-    useDefSync(container, def, geometry, (slot) => {
+    useDefSync(container, def, () => container.geometryFor(def.shape), (slot) => {
         writeMatrixIfChanged(container.mesh, slot, shapeToMatrix(def.shape));
         writeColorIfChanged(container.mesh, slot, def, logger);
         // Checked on every sync rather than only behind a color write, because a def leaves its batch's

package/dist/objects/text/TextInstance.js

@@ -22,7 +22,7 @@ const logger = createLogger('text-instance');
  */
 export const TextInstance = memo(function TextInstance(props) {
     const { def, container } = props;
-    useDefSync(container, def, def.lines.length, (slot) => {
+    useDefSync(container, def, () => def.lines.length, (slot) => {
         writeText(container, slot, def);
     });
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.39.0",
+  "version": "3.40.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.39.0"
+    "@expofp/geometry": "3.40.0"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",