@expofp/renderer 0.0.0-experimental.cf063fc

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

@@ -0,0 +1,312 @@
+import { type Object3D } from 'three';
+import { type UniformSchemaShader } from '../../core/InstanceUniforms';
+import { type UniformValue } from '../../core/SquareDataTexture';
+import { type RenderableDef } from '../../types/defs';
+/**
+ * What a container needs from the mesh it writes into.
+ *
+ * A capability rather than a union of our mesh classes: `BatchedMeshImpl`, `InstancedMeshImpl`,
+ * `BatchedLinesImpl` and `BatchedTextImpl` share no base below `Object3D`, yet every one of them
+ * declares per-instance uniforms and hides an instance the same way — which is all a container
+ * touches generically. Everything else it reaches through its own mesh type, which the subclass
+ * names.
+ */
+export interface SlotMesh extends Object3D {
+    /**
+     * Declares per-instance uniforms, merged with whatever is already declared.
+     * @param schema - The uniforms to add.
+     */
+    addUniforms(schema: UniformSchemaShader): void;
+    /**
+     * Writes one instance's uniform.
+     * @param slot - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    setUniformAt(slot: number, name: string, value: UniformValue): void;
+    /**
+     * Shows or hides one instance.
+     * @param slot - The instance to show or hide.
+     * @param visible - Whether it draws.
+     */
+    setVisibleAt(slot: number, visible: boolean): void;
+}
+/**
+ * An entry in a mesh's render list. Every mesh's sort callback receives a list of these — the
+ * published shapes differ in what else they carry, but each entry identifies its instance by
+ * `index`, which is all a paint-order sort needs.
+ */
+export interface RenderListItem {
+    /** The instance id the entry draws. */
+    index: number;
+}
+/**
+ * One entry in the list `BatchedMesh.customSort` receives. three's published types describe only
+ * `start`, `count`, and `z`, but the runtime also passes `index` — the instance id — which is the
+ * only way a sort can map an entry back to the instance that produced it.
+ */
+export interface BatchedMeshRenderItem extends RenderListItem {
+    /** Offset of the instance's geometry in the shared draw range. */
+    start: number;
+    /** Length of the instance's geometry draw range. */
+    count: number;
+    /** Instance depth along the camera's view direction. */
+    z: number;
+}
+/** How one container differs from the default, passed up by its constructor. */
+export interface SlotContainerOptions {
+    /**
+     * The per-instance uniforms the mesh declares on {@link SlotContainer.bind}. Defaults to the dim
+     * alone, which every def type carries. A container whose mesh needs more (an image's uv region, a
+     * model's opacity) passes the merged schema rather than declaring twice: `InstanceUniforms.add`
+     * rebuilds the backing texture, so two calls would build it twice per bind.
+     */
+    schema?: UniformSchemaShader;
+    /**
+     * Sort the draw list descending, so the *first* instance drawn is the one that paints on top.
+     *
+     * For a batch whose material keeps the first fragment to reach a pixel and rejects the rest,
+     * which is how the line material stops translucent lines darkening where they overlap: there,
+     * draw order is the reverse of paint order. Slots are still labeled in paint order either way.
+     */
+    reverse?: boolean;
+}
+/**
+ * One layer's mesh bookkeeping: the bound mesh, which slot each def holds, and the paint order
+ * across them.
+ *
+ * A container is what stands between a layer's defs and one mesh. It is created during render,
+ * sized to the membership it first sees, and held in `useState` for as long as its component is
+ * mounted; the mesh itself is R3F's, constructed from the subclass's args and handed back through
+ * {@link bind}, so R3F owns its lifetime and disposal. Instances claim and release slots from their
+ * own effects, and write their type-specific state through the subclass's own methods.
+ *
+ * What lives here is everything that does not depend on which def type is drawn:
+ *
+ * - **Slot allocation**, in both directions. `slotOf` is what a paint-order pass over the layer's
+ *   defs looks each def up with, and {@link defAt} is what turns a pointer hit — which names a mesh
+ *   instance — back into the def that drew it. Slots come from a mesh's free list, so a released slot
+ *   may be handed to a different def later; freeing by slot keeps both directions from outliving the
+ *   claim they describe.
+ * - **Paint order**, explicitly. Instance ids come from a mesh's free list, so they do not track
+ *   sibling order — a container that let slot order stand in for paint order would reorder itself
+ *   after any claim/release churn, and again under StrictMode's remount, which re-claims in reverse.
+ *   Explicit order is also what the 2D painter's algorithm needs: 2D content never writes depth, so
+ *   nothing it draws is in the buffer for the next 2D fragment to test against, and the draw list's
+ *   order is the only thing that decides overlap.
+ * - **The two fields every def type carries**, `hidden` and `dim`, through {@link setVisibleAt} and
+ *   {@link setDimAt} — which is what lets one hook drive them for every def type.
+ *
+ * A subclass supplies {@link addInstance} and {@link removeInstance}, names its mesh and def types,
+ * and adds whatever its own defs need.
+ * @template R - The per-instance resource a claim allocates against (a geometry, a texture region,
+ *   a line count); compared by identity, so a stable reference means a stable slot. `null` for a
+ *   container whose members share everything.
+ * @template M - The mesh this container writes into.
+ * @template T - The def kind the layer holds.
+ */
+export declare abstract class SlotContainer<R, M extends SlotMesh = SlotMesh, T extends RenderableDef = RenderableDef> {
+    /**
+     * Sorts a mesh's render list into paint order. Assigned straight to the mesh's `customSort` JSX
+     * prop, whose R3F-generated type leaves the value effectively unchecked — so the entry type here
+     * needs no cast against three's published one, which omits `index`.
+     *
+     * An arrow property rather than a method, because it is handed over as a bare value and a
+     * prototype method would arrive unbound.
+     * @param list - The render list, sorted in place.
+     */
+    readonly customSort: (list: RenderListItem[]) => void;
+    /**
+     * The layer's membership, in authored paint order. Kept so a def whose own dim changes can re-run
+     * the order pass without this container having re-rendered — `update(def)` reaches the instance,
+     * not here.
+     */
+    protected layerDefs: readonly T[];
+    /**
+     * Whether the layer is dimmed, which is what a def without a `dim` of its own inherits.
+     *
+     * A flag rather than the layer's amount, because the amount is the shader's business and this is
+     * only ever asked a yes-or-no question. It is also what makes an eased layer dim cheap: the order
+     * pass re-runs when the value crosses zero, not on every frame of the ease.
+     */
+    protected layerDimmed: boolean;
+    /**
+     * Whether each slot currently draws dimmed, so a dim write that does not cross the split costs
+     * nothing.
+     */
+    protected readonly dimmedBySlot: (boolean | undefined)[];
+    /**
+     * Each def's order, durable and weak — collected with the def. It outlives a slot, so a re-claim
+     * can seed the new slot's order without waiting for the next order pass.
+     */
+    private readonly orderByDef;
+    /** Each slot's place in the paint order, read by {@link customSort}. */
+    private readonly orderBySlot;
+    private readonly slotByDef;
+    private readonly defBySlot;
+    private readonly schema;
+    private readonly sortDirection;
+    /** Set by {@link bind}, which runs before any effect can claim a slot. */
+    private boundMesh;
+    /** What to run when a member turns out to belong in a sibling container; see {@link reportKindMismatch}. */
+    private kindMismatchHandler;
+    /**
+     * @param options - How this container differs from the default.
+     */
+    constructor(options?: SlotContainerOptions);
+    /**
+     * The mesh every instance writes into. Undefined until {@link bind}; refs attach before passive
+     * effects run, so every claim and slot write sees it bound.
+     */
+    get mesh(): M;
+    /**
+     * Binds the mesh R3F constructed from this container's args, declaring its per-instance uniforms.
+     *
+     * Bind-once: the ref-cleanup `null` and any re-bind are ignored, because React StrictMode cycles
+     * refs (attach → cleanup → attach) around a passive effect cycle — a container that forgot its
+     * mesh there would turn {@link release} into a no-op and leak the slot when the remounted instance
+     * re-claims, and one that re-declared its uniforms would strand the values already written into
+     * them.
+     * @param mesh - The mounted mesh, or the ref-cleanup `null`.
+     */
+    bind(mesh: M | null): void;
+    /**
+     * Reserves a slot for one instance, backed by `resource`.
+     *
+     * Paint order is deliberately not a parameter: it is a property of the whole sibling list, so the
+     * component writes it for every def in one pass after each membership change (see
+     * {@link setPaintOrder}) — an instance never learns its index, which is what lets a memoized
+     * instance ignore structural re-renders entirely.
+     * @param def - The def the slot will draw; def-to-slot bookkeeping is keyed by its identity.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot index.
+     */
+    claim(def: RenderableDef, resource: R): number;
+    /**
+     * Frees a slot, and everything recorded about the claim it held.
+     * @param slot - The slot to free.
+     */
+    release(slot: number): void;
+    /**
+     * The def a mesh instance belongs to — the reverse of {@link claim}, and what picking asks, since
+     * an intersection names an instance and nothing else.
+     *
+     * The instance *is* the slot for every container but the text batch, whose defs own one member per
+     * line; that one overrides this to resolve the member's group first, which is why the parameter is
+     * the mesh's number rather than the container's.
+     * @param instance - The instance the mesh reported, or `undefined` for a hit that named none.
+     * @returns The def, or `undefined` when no claim holds that instance.
+     */
+    defAt(instance: number | undefined): RenderableDef | undefined;
+    /**
+     * Where a def sits in this container's draw order, counted from the one drawn first.
+     *
+     * The public read of an assignment the order pass makes privately. Picking uses it to break a tie
+     * the depth buffer never resolved: two surfaces closer together than `depthSeparation` are drawn
+     * in list order rather than depth order, so list order is also what decides which of them the
+     * pointer is on (see `orderCoplanarHits`). Per def rather than per slot, because a slot is a mesh's
+     * own numbering out of a free list and a def is what the layer ordered.
+     *
+     * A def this container never ordered reports the first place rather than the last: nothing is known
+     * about where it drew, and the one thing that must not happen is for that to outrank a def whose
+     * place is known.
+     * @param def - The def to place.
+     * @returns Its place in the draw order.
+     */
+    paintOrderOf(def: RenderableDef): number;
+    /**
+     * Registers what to do when a member turns out to belong in a sibling container; `undefined`
+     * clears it.
+     *
+     * Here rather than on each subclass because the situation is one situation: a layer is split
+     * across several containers by some property of the def, and that property can move after the def
+     * was placed. What splits them differs — a shape's color crossing alpha 1, a model's `opacity`,
+     * an image's orientation — but what a container does about it does not, and the component that
+     * owns the split is always the one that can repair it.
+     *
+     * A method rather than an assignable field because the container is held in `useState`, and the
+     * React Compiler rejects writing to a property of a state value ("This value cannot be modified").
+     * Calling a method is fine, which is how {@link reserve} already mutates.
+     * @param handler - The re-split to run, or `undefined` to clear it.
+     */
+    setKindMismatchHandler(handler: (() => void) | undefined): void;
+    /**
+     * Reports that a member no longer belongs in this container, so it is drawing from the wrong mesh.
+     * Runs the registered handler, if any; a container mounted without one — in a spec, or bare —
+     * drops the report rather than failing, since nothing it could do would be more correct than
+     * carrying on.
+     */
+    reportKindMismatch(): void;
+    /**
+     * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
+     * all of them.
+     * @param slot - The slot to show or hide.
+     * @param visible - Whether the instance should draw.
+     */
+    setVisibleAt(slot: number, visible: boolean): void;
+    /**
+     * Sets one instance's own dim, or clears it back to its layer's.
+     *
+     * The counterpart to {@link setVisibleAt}, and here for the same reason: `dim` is a `SharedDef`
+     * field, so `useDefSync` drives it for every def type. The raw field is passed through rather than
+     * an encoded amount, which keeps the sentinel — and the rest of the shader's contract — inside the
+     * material module that reads it.
+     * @param slot - The slot to dim.
+     * @param dim - The def's `dim`; `undefined` defers to the layer's.
+     */
+    setDimAt(slot: number, dim: number | undefined): void;
+    /**
+     * Writes an encoded dim into a slot's uniform — the part of {@link setDimAt} that knows how a slot
+     * maps onto the mesh, split out so a container whose slot spans several mesh instances overrides
+     * only that and keeps the split-crossing check above.
+     * @param slot - The slot to write.
+     * @param amount - The encoded amount, from `instanceDim`.
+     */
+    protected writeDim(slot: number, amount: number): void;
+    /**
+     * Declares the layer's membership and dim, and re-runs the order pass over them.
+     *
+     * The component calls this from an effect after each structural change — child effects run first,
+     * so every mounted instance has claimed by then. Defs that have not claimed yet are recorded
+     * anyway: a later claim seeds its slot's order from this assignment, which is what keeps a
+     * re-claim correctly ordered without React involvement.
+     * @param defs - The current membership, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs: readonly T[], layerDimmed: boolean): void;
+    /**
+     * The layer's defs in the order they draw, each labeled with its place in it.
+     *
+     * Every order pass starts here, the overriding ones included, so the labels exist whatever a
+     * container then does with the order — a sortable draw list for most of them, a rebuilt member
+     * list for a text batch. That is what lets {@link paintOrderOf} answer for any container's hits
+     * rather than only the ones whose mesh sorts.
+     * @returns The defs, dimmed first.
+     */
+    protected orderedDefs(): readonly T[];
+    /**
+     * Labels every claimed slot with its place in the layer's draw order, undimmed defs last.
+     *
+     * Overridden by a container whose mesh has no sortable draw list, where ordering means handing the
+     * mesh a rebuilt member list instead.
+     */
+    protected applyOrder(): void;
+    /**
+     * The slot a def holds, for an order pass walking the layer's defs.
+     * @param def - The def to look up.
+     * @returns The slot, or `undefined` when the def has not claimed one.
+     */
+    protected slotOf(def: RenderableDef): number | undefined;
+    /**
+     * Allocates one instance in the mesh.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot the mesh allocated.
+     */
+    protected abstract addInstance(resource: R): number;
+    /**
+     * Frees one instance in the mesh.
+     * @param slot - The slot to free.
+     */
+    protected abstract removeInstance(slot: number): void;
+}
+//# sourceMappingURL=SlotContainer.d.ts.map

package/dist/objects/containers/SlotContainer.js

@@ -0,0 +1,311 @@
+import { DIM_SCHEMA, DIM_UNIFORM, dimOrdered, instanceDim, isDimmed, } from '../materials/effects/color-dim';
+/**
+ * One layer's mesh bookkeeping: the bound mesh, which slot each def holds, and the paint order
+ * across them.
+ *
+ * A container is what stands between a layer's defs and one mesh. It is created during render,
+ * sized to the membership it first sees, and held in `useState` for as long as its component is
+ * mounted; the mesh itself is R3F's, constructed from the subclass's args and handed back through
+ * {@link bind}, so R3F owns its lifetime and disposal. Instances claim and release slots from their
+ * own effects, and write their type-specific state through the subclass's own methods.
+ *
+ * What lives here is everything that does not depend on which def type is drawn:
+ *
+ * - **Slot allocation**, in both directions. `slotOf` is what a paint-order pass over the layer's
+ *   defs looks each def up with, and {@link defAt} is what turns a pointer hit — which names a mesh
+ *   instance — back into the def that drew it. Slots come from a mesh's free list, so a released slot
+ *   may be handed to a different def later; freeing by slot keeps both directions from outliving the
+ *   claim they describe.
+ * - **Paint order**, explicitly. Instance ids come from a mesh's free list, so they do not track
+ *   sibling order — a container that let slot order stand in for paint order would reorder itself
+ *   after any claim/release churn, and again under StrictMode's remount, which re-claims in reverse.
+ *   Explicit order is also what the 2D painter's algorithm needs: 2D content never writes depth, so
+ *   nothing it draws is in the buffer for the next 2D fragment to test against, and the draw list's
+ *   order is the only thing that decides overlap.
+ * - **The two fields every def type carries**, `hidden` and `dim`, through {@link setVisibleAt} and
+ *   {@link setDimAt} — which is what lets one hook drive them for every def type.
+ *
+ * A subclass supplies {@link addInstance} and {@link removeInstance}, names its mesh and def types,
+ * and adds whatever its own defs need.
+ * @template R - The per-instance resource a claim allocates against (a geometry, a texture region,
+ *   a line count); compared by identity, so a stable reference means a stable slot. `null` for a
+ *   container whose members share everything.
+ * @template M - The mesh this container writes into.
+ * @template T - The def kind the layer holds.
+ */
+export class SlotContainer {
+    /**
+     * Sorts a mesh's render list into paint order. Assigned straight to the mesh's `customSort` JSX
+     * prop, whose R3F-generated type leaves the value effectively unchecked — so the entry type here
+     * needs no cast against three's published one, which omits `index`.
+     *
+     * An arrow property rather than a method, because it is handed over as a bare value and a
+     * prototype method would arrive unbound.
+     * @param list - The render list, sorted in place.
+     */
+    customSort = (list) => {
+        const order = this.orderBySlot;
+        list.sort((a, b) => this.sortDirection * ((order[a.index] ?? 0) - (order[b.index] ?? 0)));
+    };
+    /**
+     * The layer's membership, in authored paint order. Kept so a def whose own dim changes can re-run
+     * the order pass without this container having re-rendered — `update(def)` reaches the instance,
+     * not here.
+     */
+    layerDefs = [];
+    /**
+     * Whether the layer is dimmed, which is what a def without a `dim` of its own inherits.
+     *
+     * A flag rather than the layer's amount, because the amount is the shader's business and this is
+     * only ever asked a yes-or-no question. It is also what makes an eased layer dim cheap: the order
+     * pass re-runs when the value crosses zero, not on every frame of the ease.
+     */
+    layerDimmed = false;
+    /**
+     * Whether each slot currently draws dimmed, so a dim write that does not cross the split costs
+     * nothing.
+     */
+    dimmedBySlot = [];
+    /**
+     * Each def's order, durable and weak — collected with the def. It outlives a slot, so a re-claim
+     * can seed the new slot's order without waiting for the next order pass.
+     */
+    orderByDef = new WeakMap();
+    /** Each slot's place in the paint order, read by {@link customSort}. */
+    orderBySlot = [];
+    slotByDef = new Map();
+    defBySlot = new Map();
+    schema;
+    sortDirection;
+    /** Set by {@link bind}, which runs before any effect can claim a slot. */
+    boundMesh;
+    /** What to run when a member turns out to belong in a sibling container; see {@link reportKindMismatch}. */
+    kindMismatchHandler;
+    /**
+     * @param options - How this container differs from the default.
+     */
+    constructor(options = {}) {
+        this.schema = options.schema ?? DIM_SCHEMA;
+        this.sortDirection = options.reverse ? -1 : 1;
+    }
+    /**
+     * The mesh every instance writes into. Undefined until {@link bind}; refs attach before passive
+     * effects run, so every claim and slot write sees it bound.
+     */
+    get mesh() {
+        // Asserted rather than guarded: reading before the ref attached is a programming error, and the
+        // ordering that rules it out is React's, not something a check here could repair.
+        return this.boundMesh;
+    }
+    /**
+     * Binds the mesh R3F constructed from this container's args, declaring its per-instance uniforms.
+     *
+     * Bind-once: the ref-cleanup `null` and any re-bind are ignored, because React StrictMode cycles
+     * refs (attach → cleanup → attach) around a passive effect cycle — a container that forgot its
+     * mesh there would turn {@link release} into a no-op and leak the slot when the remounted instance
+     * re-claims, and one that re-declared its uniforms would strand the values already written into
+     * them.
+     * @param mesh - The mounted mesh, or the ref-cleanup `null`.
+     */
+    bind(mesh) {
+        if (!mesh || this.boundMesh)
+            return;
+        this.boundMesh = mesh;
+        // The material owns each uniform's name and shape; the mesh only has to declare the rows before
+        // any slot writes into them — which the ref this runs from guarantees, since refs attach before
+        // the effects that claim slots and long before the first draw.
+        mesh.addUniforms(this.schema);
+    }
+    /**
+     * Reserves a slot for one instance, backed by `resource`.
+     *
+     * Paint order is deliberately not a parameter: it is a property of the whole sibling list, so the
+     * component writes it for every def in one pass after each membership change (see
+     * {@link setPaintOrder}) — an instance never learns its index, which is what lets a memoized
+     * instance ignore structural re-renders entirely.
+     * @param def - The def the slot will draw; def-to-slot bookkeeping is keyed by its identity.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot index.
+     */
+    claim(def, resource) {
+        const slot = this.addInstance(resource);
+        this.slotByDef.set(def, slot);
+        this.defBySlot.set(slot, def);
+        // Seeded from the durable assignment so a re-claim keeps its order; a first claim before any
+        // `setPaintOrder` defaults to 0 and the component's order pass relabels it in the same effect
+        // flush, before anything draws.
+        this.orderBySlot[slot] = this.orderByDef.get(def) ?? 0;
+        // Seeded here as well, so the instance's first `setDimAt` — every instance writes its dim as it
+        // mounts — reads the split it already draws on rather than `undefined`, and leaves the order
+        // pass to the structural one. Without it, mounting a layer of n defs runs n full order passes.
+        // A dim that arrives with the sync still crosses the split and still re-orders, and a claim
+        // made before the layer's own dim is known is relabelled by `setPaintOrder` in the same flush.
+        this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
+        return slot;
+    }
+    /**
+     * Frees a slot, and everything recorded about the claim it held.
+     * @param slot - The slot to free.
+     */
+    release(slot) {
+        this.removeInstance(slot);
+        this.orderBySlot[slot] = 0;
+        this.dimmedBySlot[slot] = undefined;
+        const def = this.defBySlot.get(slot);
+        if (!def)
+            return;
+        this.slotByDef.delete(def);
+        this.defBySlot.delete(slot);
+    }
+    /**
+     * The def a mesh instance belongs to — the reverse of {@link claim}, and what picking asks, since
+     * an intersection names an instance and nothing else.
+     *
+     * The instance *is* the slot for every container but the text batch, whose defs own one member per
+     * line; that one overrides this to resolve the member's group first, which is why the parameter is
+     * the mesh's number rather than the container's.
+     * @param instance - The instance the mesh reported, or `undefined` for a hit that named none.
+     * @returns The def, or `undefined` when no claim holds that instance.
+     */
+    defAt(instance) {
+        return instance === undefined ? undefined : this.defBySlot.get(instance);
+    }
+    /**
+     * Where a def sits in this container's draw order, counted from the one drawn first.
+     *
+     * The public read of an assignment the order pass makes privately. Picking uses it to break a tie
+     * the depth buffer never resolved: two surfaces closer together than `depthSeparation` are drawn
+     * in list order rather than depth order, so list order is also what decides which of them the
+     * pointer is on (see `orderCoplanarHits`). Per def rather than per slot, because a slot is a mesh's
+     * own numbering out of a free list and a def is what the layer ordered.
+     *
+     * A def this container never ordered reports the first place rather than the last: nothing is known
+     * about where it drew, and the one thing that must not happen is for that to outrank a def whose
+     * place is known.
+     * @param def - The def to place.
+     * @returns Its place in the draw order.
+     */
+    paintOrderOf(def) {
+        return this.orderByDef.get(def) ?? 0;
+    }
+    /**
+     * Registers what to do when a member turns out to belong in a sibling container; `undefined`
+     * clears it.
+     *
+     * Here rather than on each subclass because the situation is one situation: a layer is split
+     * across several containers by some property of the def, and that property can move after the def
+     * was placed. What splits them differs — a shape's color crossing alpha 1, a model's `opacity`,
+     * an image's orientation — but what a container does about it does not, and the component that
+     * owns the split is always the one that can repair it.
+     *
+     * A method rather than an assignable field because the container is held in `useState`, and the
+     * React Compiler rejects writing to a property of a state value ("This value cannot be modified").
+     * Calling a method is fine, which is how {@link reserve} already mutates.
+     * @param handler - The re-split to run, or `undefined` to clear it.
+     */
+    setKindMismatchHandler(handler) {
+        this.kindMismatchHandler = handler;
+    }
+    /**
+     * Reports that a member no longer belongs in this container, so it is drawing from the wrong mesh.
+     * Runs the registered handler, if any; a container mounted without one — in a spec, or bare —
+     * drops the report rather than failing, since nothing it could do would be more correct than
+     * carrying on.
+     */
+    reportKindMismatch() {
+        this.kindMismatchHandler?.();
+    }
+    /**
+     * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
+     * all of them.
+     * @param slot - The slot to show or hide.
+     * @param visible - Whether the instance should draw.
+     */
+    setVisibleAt(slot, visible) {
+        this.mesh.setVisibleAt(slot, visible);
+    }
+    /**
+     * Sets one instance's own dim, or clears it back to its layer's.
+     *
+     * The counterpart to {@link setVisibleAt}, and here for the same reason: `dim` is a `SharedDef`
+     * field, so `useDefSync` drives it for every def type. The raw field is passed through rather than
+     * an encoded amount, which keeps the sentinel — and the rest of the shader's contract — inside the
+     * material module that reads it.
+     * @param slot - The slot to dim.
+     * @param dim - The def's `dim`; `undefined` defers to the layer's.
+     */
+    setDimAt(slot, dim) {
+        this.writeDim(slot, instanceDim(dim));
+        // Crossing the dimmed/lit split changes where this def draws, and nothing else will notice: a
+        // def's own `update()` reaches its instance, never the component that renders this container.
+        const dimmed = isDimmed(dim, this.layerDimmed);
+        if (this.layerDefs.length === 0 || this.dimmedBySlot[slot] === dimmed)
+            return;
+        this.applyOrder();
+    }
+    /**
+     * Writes an encoded dim into a slot's uniform — the part of {@link setDimAt} that knows how a slot
+     * maps onto the mesh, split out so a container whose slot spans several mesh instances overrides
+     * only that and keeps the split-crossing check above.
+     * @param slot - The slot to write.
+     * @param amount - The encoded amount, from `instanceDim`.
+     */
+    writeDim(slot, amount) {
+        this.mesh.setUniformAt(slot, DIM_UNIFORM, amount);
+    }
+    /**
+     * Declares the layer's membership and dim, and re-runs the order pass over them.
+     *
+     * The component calls this from an effect after each structural change — child effects run first,
+     * so every mounted instance has claimed by then. Defs that have not claimed yet are recorded
+     * anyway: a later claim seeds its slot's order from this assignment, which is what keeps a
+     * re-claim correctly ordered without React involvement.
+     * @param defs - The current membership, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs, layerDimmed) {
+        this.layerDefs = defs;
+        this.layerDimmed = layerDimmed;
+        this.applyOrder();
+    }
+    /**
+     * The layer's defs in the order they draw, each labeled with its place in it.
+     *
+     * Every order pass starts here, the overriding ones included, so the labels exist whatever a
+     * container then does with the order — a sortable draw list for most of them, a rebuilt member
+     * list for a text batch. That is what lets {@link paintOrderOf} answer for any container's hits
+     * rather than only the ones whose mesh sorts.
+     * @returns The defs, dimmed first.
+     */
+    orderedDefs() {
+        const ordered = dimOrdered(this.layerDefs, this.layerDimmed);
+        for (let order = 0; order < ordered.length; order++)
+            this.orderByDef.set(ordered[order], order);
+        return ordered;
+    }
+    /**
+     * Labels every claimed slot with its place in the layer's draw order, undimmed defs last.
+     *
+     * Overridden by a container whose mesh has no sortable draw list, where ordering means handing the
+     * mesh a rebuilt member list instead.
+     */
+    applyOrder() {
+        const ordered = this.orderedDefs();
+        for (let order = 0; order < ordered.length; order++) {
+            const def = ordered[order];
+            const slot = this.slotOf(def);
+            if (slot === undefined)
+                continue;
+            this.orderBySlot[slot] = order;
+            this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
+        }
+    }
+    /**
+     * The slot a def holds, for an order pass walking the layer's defs.
+     * @param def - The def to look up.
+     * @returns The slot, or `undefined` when the def has not claimed one.
+     */
+    slotOf(def) {
+        return this.slotByDef.get(def);
+    }
+}