@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/images/worker/client.js

@@ -0,0 +1,249 @@
+/* eslint-disable-next-line import/default -- Vite answers this specifier with a module it
+generates, whose default export is a `Worker` subclass. The ESLint resolver drops the query and
+reads the worker entry instead, which exports no default of its own. `vite/client` declares the
+real shape, so tsc sees it. */
+import AtlasWorker from './atlas-worker?worker&inline';
+/**
+ * Packs a set of sources in a web worker.
+ *
+ * **One worker serves every pack, and no pack ever stops it.** The atlases come back as
+ * `ImageBitmap`s that `OffscreenCanvas.transferToImageBitmap()` produced, and Chrome backs those
+ * with GPU memory the worker owns. `Images` re-reads an atlas's pixels on every texture-budget
+ * move, and disposing a texture forces a fresh upload, so the producing worker has to outlive every
+ * bitmap it made, not only the first upload of it. Terminating the worker used to run before this
+ * function resolved, which destroyed those pixels and left booth logos blank on real GPUs.
+ *
+ * The one `terminate()` in this file is in `retire`, and it only ever stops a worker that broke
+ * before it handed out an atlas. A worker that has produced pixels is dropped from the pool and
+ * left running. The worker script is inlined into the bundle, so starting one resolves no URL at
+ * runtime, which matters because the SDK is loaded from origins it does not control.
+ *
+ * Each pack carries an `id`, because a shared worker can hold two layers' packs at once and a reply
+ * has to find its own caller. An abandoned pack is settled here and its `id` forgotten, so a reply
+ * that still arrives is discarded — and its atlases are closed, or each superseded pack would leak
+ * a layer's worth of GPU memory.
+ *
+ * The sources go over in batches so the main thread is never blocked for long by one structured
+ * clone, and so the worker can decode the early batches while the later ones are still being sent.
+ * A closing message tells it every source has arrived.
+ * @param sources - The unique sources to pack, in the caller's order; placements address them by
+ *   their index in this array.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @param options - The abort signal, and the worker factory a spec overrides.
+ * @returns The packed atlases and one report per source.
+ */
+export function packInWorker(sources, maxDimension, options = {}) {
+    const { signal, createWorker = createAtlasWorker } = options;
+    return new Promise((resolve, reject) => {
+        // Read the signal before anything is sent. A pack that is already abandoned must cost the
+        // worker nothing, so it posts no message at all.
+        if (signal?.aborted) {
+            reject(abandoned());
+            return;
+        }
+        let worker;
+        try {
+            worker = pooledWorker(createWorker);
+        }
+        catch (error) {
+            // A host page whose `script-src` forbids `blob:` and `data:` makes `new Worker()` throw. The
+            // caller falls back to an inline pack.
+            reject(asError(error));
+            return;
+        }
+        const id = ++lastRequestId;
+        // Every exit runs through here. Dropping this pack's entry is what stops delivery, because the
+        // worker is shared and goes on running.
+        const done = (settle) => {
+            signal?.removeEventListener('abort', onAbort);
+            pending.delete(id);
+            settle();
+        };
+        // A plain Error, not `signal.reason`, which Chrome 66 and Safari 15 do not have. Nothing
+        // branches on the error's type: every caller reads `signal.aborted` instead.
+        const onAbort = () => {
+            done(() => {
+                cancel(worker, id);
+                reject(abandoned());
+            });
+        };
+        pending.set(id, (message) => {
+            done(() => {
+                if (message.type === 'failed')
+                    reject(new Error(message.message));
+                else
+                    resolve({ atlases: message.atlases, reports: message.reports });
+            });
+        });
+        signal?.addEventListener('abort', onAbort);
+        try {
+            for (let start = 0; start < sources.length; start += SOURCE_CHUNK_SIZE) {
+                post(worker, {
+                    type: 'sources',
+                    id,
+                    sources: sources.slice(start, start + SOURCE_CHUNK_SIZE),
+                });
+            }
+            post(worker, { type: 'pack', id, maxDimension });
+        }
+        catch (error) {
+            // `postMessage` throws when the platform refuses to copy a source. The worker keeps the
+            // batches that did arrive until it is told otherwise, and the closing message never comes.
+            done(() => {
+                cancel(worker, id);
+                reject(asError(error));
+            });
+        }
+    });
+}
+/**
+ * Forgets the pooled worker without stopping it, and abandons every pack waiting on it.
+ *
+ * Only a spec calls this. Each spec drives its own fake worker, and the pool would otherwise hand
+ * the first spec's fake to every spec after it.
+ */
+export function resetAtlasWorkerPool() {
+    pool = null;
+    pending.clear();
+}
+/**
+ * Hands back the one worker every pack runs on, starting it on the first call.
+ *
+ * The reply handler lives on the worker and not on a pack, because the worker outlives every pack
+ * it serves and a reply for a pack nobody wants still has pixels to free.
+ * @param createWorker - Makes the worker, if there is not one yet.
+ * @returns The pooled worker.
+ */
+function pooledWorker(createWorker) {
+    if (pool)
+        return pool.worker;
+    // Not stored until it exists: a factory that throws must be retried by the next pack, not cached.
+    const started = { worker: createWorker(), produced: false };
+    started.worker.onmessage = (event) => {
+        const message = event.data;
+        const deliver = pending.get(message.id);
+        if (deliver) {
+            // These pixels are about to be mounted, so from here on this worker must not be stopped.
+            if (message.type === 'packed' && message.atlases.length > 0)
+                started.produced = true;
+            deliver(message);
+            return;
+        }
+        // Nobody is waiting: this pack was abandoned after the worker had already replied. An
+        // `ImageBitmap` holds its pixels outside the JavaScript heap and nothing else will ever close
+        // these, so every superseded pack would leak a layer's worth of GPU memory.
+        if (message.type === 'packed')
+            for (const atlas of message.atlases)
+                atlas.bitmap.close();
+    };
+    started.worker.onerror = (event) => {
+        retire(started);
+        failAll(event.message || 'atlas-worker: failed to start');
+    };
+    started.worker.onmessageerror = () => {
+        // This never fires on the primary target. `Worker`'s `messageerror` is `false` for Chrome,
+        // Chrome Android and Android WebView, and Safari only added it in 16.4, which is above the
+        // `safari15`/`ios15` floor (checked against `@mdn/browser-compat-data@6.1.5`, as installed
+        // here). Assigning it is free and Firefox has had it since 57, so it is kept for the browsers
+        // that do support it. It is not a guard the build targets can rely on.
+        //
+        // A reply that does not deserialize is lost, and it carries no id, so there is no way to tell
+        // whose it was. Without this the layer waits for a reply that never comes and stays blank.
+        retire(started);
+        failAll('atlas-worker: a reply could not be read');
+    };
+    pool = started;
+    return started.worker;
+}
+/**
+ * Drops a broken worker, so the next pack starts a fresh one.
+ *
+ * A worker that has handed out an atlas is dropped and left running. Stopping it would destroy the
+ * GPU memory behind every bitmap it made, which is the failure this whole file is shaped around. A
+ * worker that produced nothing is stopped, because nothing depends on it.
+ * @param broken - The pooled worker to drop.
+ */
+function retire(broken) {
+    if (pool === broken)
+        pool = null;
+    if (!broken.produced)
+        broken.worker.terminate();
+}
+/**
+ * Abandons every pack waiting on the worker that just broke.
+ * @param message - What to reject each of them with.
+ */
+function failAll(message) {
+    for (const [id, deliver] of [...pending])
+        deliver({ type: 'failed', id, message });
+}
+/**
+ * Tells the worker to drop a pack nobody wants any more.
+ *
+ * Termination used to do this. Now that the worker outlives its packs, a superseded pack would
+ * otherwise run to the end and hold the worker off the next one.
+ * @param worker - The pooled worker.
+ * @param id - The pack to drop.
+ */
+function cancel(worker, id) {
+    try {
+        post(worker, { type: 'cancel', id });
+    }
+    catch {
+        // A worker that will not take this message is already unusable, and the pack it would have
+        // dropped is dropped either way.
+    }
+}
+/**
+ * Sends one request to the worker.
+ *
+ * **Nothing is ever transferred.** A `Blob` is a handle to an immutable, reference-counted byte
+ * store, so a structured clone copies the handle and not the bytes. Being cheap to clone is the
+ * property that matters here; being transferable is not, and transferring a Blob is not a thing the
+ * platform offers. A `Blob` is also the only source that reaches this function, so no object a def
+ * owns is ever detached by a pack.
+ *
+ * The typed parameter is why this function exists: `postMessage` takes `any`, so a message built at
+ * the call site would go unchecked.
+ * @param worker - The worker to send to.
+ * @param request - The message.
+ */
+function post(worker, request) {
+    worker.postMessage(request);
+}
+/**
+ * Makes the bundled atlas worker.
+ * @returns A fresh worker.
+ */
+function createAtlasWorker() {
+    return new AtlasWorker();
+}
+/**
+ * The error every abandoned pack rejects with.
+ * @returns The error.
+ */
+function abandoned() {
+    return new Error('atlas-worker: the pack was abandoned');
+}
+/**
+ * Turns whatever was thrown into an `Error`.
+ * @param error - What was thrown.
+ * @returns An error.
+ */
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * How many sources one `postMessage` carries.
+ *
+ * Sending every source in one message left 18 dropped frames at a thousand logos on a 4x-throttled
+ * CPU; sending them in batches of 25 left one. Chunking is what removes the last stall, so this is
+ * the number that matters most in this file — tune it against the benchmark, not by taste.
+ */
+export const SOURCE_CHUNK_SIZE = 25;
+/** Every pack that has been sent and is waiting for its reply, by request id. */
+const pending = new Map();
+/** The worker every pack runs on, once the first pack has started it. */
+let pool = null;
+/** The last id handed to a pack. Ids only ever climb, so no reply can find the wrong caller. */
+let lastRequestId = 0;

package/dist/objects/images/worker/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The worker's public face: the main thread's half only.
+ *
+ * The worker entry is deliberately absent. It imports `packSources` and carries the
+ * `?worker&inline` specifier, and nothing outside this directory should pull either in by
+ * reaching past the barrel. Types are the exception, because they are erased at emit.
+ */
+export { type WorkerAtlas, type WorkerSource } from './atlas-worker';
+export { packInWorker, type PackInWorkerOptions, SOURCE_CHUNK_SIZE } from './client';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/images/worker/index.js

@@ -0,0 +1 @@
+export { packInWorker, SOURCE_CHUNK_SIZE } from './client';

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

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

package/dist/objects/layer/Layer.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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';
+import { Images } from '../images';
+import { Lines } from '../lines';
+import { Models } from '../models';
+import { Shapes } from '../shapes';
+import { Texts } from '../text';
+import { LayerDimContext, LayerOverlayContext, useDimChain, useLayerOverlay, } from './layer-context';
+import { useStagedChildren } from './mount-scheduler';
+import { useVisibilityGui } from './visibility-gui';
+/**
+ * Renders a {@link LayerDef} tree, mapping defs onto the scene-graph hierarchy.
+ *
+ * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
+ * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
+ * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
+ * carries with `hidden`, at `false`. Dim and overlay need no seed: `LayerDimContext` and
+ * `LayerOverlayContext` already default to undimmed and plan tier, which is what "no layer above
+ * me" means for either one. The whole tree's draw order lives inside `[0, 1)`.
+ * @param props - The layer props.
+ * @returns The tree's root group.
+ */
+export function Layer(props) {
+    const { layer, children } = props;
+    useVisibilityGui(layer);
+    return (_jsx(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.
+ *
+ * Everything layer-shaped is handled here as group state — the name, visibility from
+ * `layer.hidden`, the dim the subtree inherits, and the pointer props that make the group
+ * interactive and picked (see `usePointerProps`) — so the containers below stay free of layer
+ * semantics and receive only their child defs. The children arrive through `useStagedChildren`,
+ * which is what makes `layer.hidden = true; update(layer)` flip a group prop instead of rebuilding
+ * anything, defers a membership change's instance-list sweep to transition priority, and stages
+ * leaf mounting one commit per frame — see the hook for all three.
+ *
+ * **Re-layout is registered, not rendered.** A layer registers the defs that declare an `onScale`
+ * with the renderer's re-layout targets — the children it holds, and itself, which is how a layer
+ * whose membership depends on the camera re-derives it. From then on a pixel-size change reaches
+ * those defs through the frame loop, with no render of this component involved.
+ *
+ * Draw order is a 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.
+ */
+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 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 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);
+    useLayoutTargets(layer, children);
+    const pointerProps = usePointerProps(layer, visible);
+    let contents = null;
+    if (isLayerDefs(children)) {
+        const childStep = orderStep / children.length;
+        contents = children.map((child, index) => (_jsx(MemoLayerNode, { layer: child, hidden: hidden, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
+    }
+    else if (mounted > 0) {
+        contents = _jsx(LeafContent, { defs: children, mounted: mounted });
+    }
+    const group = (_jsxs("group", { name: layer.name, visible: !layer.hidden, renderOrder: (overlay ? OVERLAY_TIER : PLAN_TIER) + orderBase, ...pointerProps, children: [prelude, contents] }));
+    // 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: dimChain, children: _jsx(LayerOverlayContext, { value: overlay, children: group }) }));
+}
+/**
+ * {@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.
+ */
+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.
+ */
+const PLAN_TIER = 0;
+/**
+ * Where an overlay subtree is numbered from, which puts it in `[1, 2)`. That is after every
+ * plan-tier layer, whatever renderOrder those layers hold. The whole cost is one bit of mantissa for
+ * subdivision.
+ */
+const OVERLAY_TIER = 1;

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

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

package/dist/objects/layer/index.js

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

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

@@ -0,0 +1,74 @@
+import { type LayerDef } from '../../types/defs';
+/**
+ * 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;
+/**
+ * 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} 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 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<DimChain>;
+/**
+ * Whether the current layer hands its overlay tier down to its descendants.
+ *
+ * Context rather than a prop, for the reason {@link LayerDimContext} is. It is also not a shading
+ * term, which is why `overlayParams`, the material parameters this tier unlocks, stays in
+ * `objects/materials/shared.ts` instead of moving here.
+ *
+ * Read through {@link useLayerOverlay} instead of directly. A `LayerNode` provides it, always,
+ * never only when it declares an `overlay` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `false`, the plan tier, which is what "no layer above me" means for a component
+ * rendered outside a `Layer` tree.
+ */
+export declare const LayerOverlayContext: import("react").Context<boolean>;
+//# sourceMappingURL=layer-context.d.ts.map

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

@@ -0,0 +1,82 @@
+import { createContext, use, useSyncExternalStore } from 'react';
+import { subscribeDef } from '../../update';
+/**
+ * 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);
+}
+/**
+ * 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 function useLayerOverlay() {
+    return use(LayerOverlayContext);
+}
+/**
+ * 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} 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 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([]);
+/**
+ * Whether the current layer hands its overlay tier down to its descendants.
+ *
+ * Context rather than a prop, for the reason {@link LayerDimContext} is. It is also not a shading
+ * term, which is why `overlayParams`, the material parameters this tier unlocks, stays in
+ * `objects/materials/shared.ts` instead of moving here.
+ *
+ * Read through {@link useLayerOverlay} instead of directly. A `LayerNode` provides it, always,
+ * never only when it declares an `overlay` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `false`, the plan tier, which is what "no layer above me" means for a component
+ * rendered outside a `Layer` tree.
+ */
+export const LayerOverlayContext = createContext(false);