@expofp/renderer 3.38.0 → 3.39.1

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

@@ -3,16 +3,21 @@ import { type RenderableDef } from '../../types/defs';
 import { type SlotContainer, type SlotMesh } from './SlotContainer';
 /**
  * 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, and how hits on its mesh resolve back to defs.
+ * mounted: the membership's paint order, how hits on its mesh resolve back to defs, and what runs
+ * when a member no longer belongs in this container's kind.
  *
  * The container is built once, from the first render's defs, and outlives every render after —
  * membership changes grow it in place rather than rebuilding it, which is what lets the mesh R3F
  * built from its args stand too. `create` is therefore called once and its later identities ignored.
  * @param create - Builds the container. Called on the first render only.
  * @param defs - The layer's defs, in authored paint order.
+ * @param onKindMismatch - Re-splits the layer, for a container that finds a member of the wrong
+ *   kind. Registered as {@link SlotContainer.setKindMismatchHandler} and cleared on unmount or
+ *   before a new identity replaces it. A container with no kind of its own to leave omits it, and
+ *   nothing is registered.
  * @returns The container.
  */
-export declare function useContainer<T extends RenderableDef, C extends SlotContainer<unknown, SlotMesh, T>>(create: () => C, defs: readonly T[]): C;
+export declare function useContainer<T extends RenderableDef, C extends SlotContainer<unknown, SlotMesh, T>>(create: () => C, defs: readonly T[], onKindMismatch?: () => void): C;
 /**
  * Claims a slot for one instance, releasing on unmount. Paint order is not this hook's concern —
  * the container writes it for the whole sibling list in one pass (see {@link useContainer}).
@@ -37,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,38 +1,71 @@
-import { useThree } from '@react-three/fiber';
-import { use, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+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 { LayerDimContext } from '../materials/effects/color-dim';
+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, and how hits on its mesh resolve back to defs.
+ * mounted: the membership's paint order, how hits on its mesh resolve back to defs, and what runs
+ * when a member no longer belongs in this container's kind.
  *
  * The container is built once, from the first render's defs, and outlives every render after —
  * membership changes grow it in place rather than rebuilding it, which is what lets the mesh R3F
  * built from its args stand too. `create` is therefore called once and its later identities ignored.
  * @param create - Builds the container. Called on the first render only.
  * @param defs - The layer's defs, in authored paint order.
+ * @param onKindMismatch - Re-splits the layer, for a container that finds a member of the wrong
+ *   kind. Registered as {@link SlotContainer.setKindMismatchHandler} and cleared on unmount or
+ *   before a new identity replaces it. A container with no kind of its own to leave omits it, and
+ *   nothing is registered.
  * @returns The container.
  */
-export function useContainer(create, defs) {
+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 = use(LayerDimContext) > 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.
     useEffect(() => registerHitResolver(container.mesh, (hit) => container.defFromHit(hit)), [container]);
+    // Assigned after mount rather than passed to `create`, because the container is built once and
+    // outlives every render, so it cannot close over a fresh callback. A caller with nothing to run on
+    // a mismatch passes no handler, and this then does nothing: no call into the container and no
+    // cleanup closure either.
+    useEffect(() => {
+        if (!onKindMismatch)
+            return;
+        container.setKindMismatchHandler(onKindMismatch);
+        return () => container.setKindMismatchHandler(undefined);
+    }, [container, onKindMismatch]);
     return container;
 }
 /**
@@ -46,7 +79,7 @@ export function useContainer(create, defs) {
  */
 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;
@@ -76,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.
      */
@@ -92,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
@@ -103,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/containers/mesh-writes.js

@@ -82,9 +82,9 @@ export function writeColorIfChanged(mesh, slot, def, logger) {
     mesh.setColorAt(slot, _colorWithAlpha);
     return true;
 }
-// Scratch shared by every write: each is filled and consumed within a single synchronous
-// statement, so a write costs buffer uploads and no allocation. `_matrix` is the one callers see
-// (through `shapeToMatrix`); the `_previous*` pair is only ever read back and compared inside the
+// Scratch shared by every write. Each is filled and consumed within a single synchronous
+// statement, so a write costs buffer uploads and no allocation. `_matrix` is the one callers see,
+// through `shapeToMatrix`. The `_previous*` values are only ever read back and compared inside the
 // write helpers, so a caller still holding `_matrix` never collides with them.
 const _position = new Vector3();
 const _quaternion = new Quaternion();