@expofp/renderer 3.37.1 → 3.39.0

package/dist/objects/images/worker/atlas-worker.js

@@ -0,0 +1,123 @@
+import { packSources, } from '../pack-sources';
+/**
+ * Waits for every batch to decode, packs them, and moves each atlas's pixels out of its canvas.
+ * @param id - Which pack to run.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @returns The reply to post back, or null when the pack was canceled and nothing is owed.
+ */
+async function pack(id, maxDimension) {
+    // `requestFor` and not `requests.get`, because a layer with no sources sends its closing message
+    // and nothing else. That is an empty pack, and it still owes a reply: without one the layer
+    // waits forever and draws nothing. The only other way to reach this with no state is a cancel
+    // that arrived first, and that happens only when the closing message was never sent, so the
+    // empty reply it produces goes to a caller that has already forgotten the id and is discarded.
+    const request = requestFor(id);
+    request.packing = true;
+    const decoded = await Promise.all(request.decoding);
+    requests.delete(id);
+    // The only yield point in a pack. `packSources` runs straight through once it starts, so this is
+    // the last moment a cancel can save the worker's time for the next pack.
+    if (request.canceled) {
+        closeDecoded(decoded);
+        return null;
+    }
+    // `createAtlasCanvas` returns an `OffscreenCanvas` here and never takes its fallback branch. A
+    // worker runs at all only because `selectTier` found `OffscreenCanvas` on the main thread, and
+    // the constructor is exposed to both globals or to neither. No fallback is worth writing: a
+    // worker has no `document`, so without `OffscreenCanvas` it could build no canvas at all.
+    const { atlases, reports } = packSources(decoded, maxDimension);
+    // `transferToImageBitmap` moves the canvas's backing bitmap out instead of copying it, which is
+    // what makes an atlas cheap to return. The canvas is left blank, and this code drops it anyway.
+    const packed = atlases.map((atlas) => ({
+        bitmap: atlas.canvas.transferToImageBitmap(),
+        placements: atlas.placements,
+        resizable: atlas.resizable,
+    }));
+    // The atlases hold the pixels now, so every decoded bitmap is dead. This worker decoded all of
+    // them and owns all of them. Close them rather than leaving a thousand to the collector.
+    closeDecoded(decoded);
+    return { type: 'packed', id, atlases: packed, reports };
+}
+/**
+ * Abandons one pack.
+ *
+ * A pack that has not reached {@link pack} yet is dropped here, because nothing else will ever read
+ * its decodes. A pack that is already running is only marked: it reads the mark at its one yield
+ * point and cleans up there.
+ * @param id - Which pack to abandon.
+ */
+function cancel(id) {
+    const request = requests.get(id);
+    // Already replied, or never started. Either way this worker holds nothing for that pack.
+    if (!request)
+        return;
+    request.canceled = true;
+    if (request.packing)
+        return;
+    requests.delete(id);
+    void Promise.all(request.decoding).then(closeDecoded);
+}
+/**
+ * Frees decoded pixels this worker owns.
+ *
+ * An `ImageBitmap` holds its pixels outside the JavaScript heap, where collection does not reclaim
+ * them promptly. A canceled pack of a thousand logos would otherwise sit on a thousand of them.
+ * @param decoded - What the sources decoded into.
+ */
+function closeDecoded(decoded) {
+    for (const source of decoded)
+        if (source && 'close' in source)
+            source.close();
+}
+/**
+ * Finds a pack's state, starting it on the first batch that arrives.
+ * @param id - Which pack the batch belongs to.
+ * @returns That pack's state.
+ */
+function requestFor(id) {
+    let request = requests.get(id);
+    if (!request) {
+        request = { decoding: [], canceled: false, packing: false };
+        requests.set(id, request);
+    }
+    return request;
+}
+/**
+ * Every pack this worker is working on, by request id.
+ *
+ * The main thread does not terminate this worker once it has returned an atlas, because those
+ * atlases are backed by GPU memory the worker owns. It stops a worker only when that worker broke
+ * before it produced anything. So one worker serves every pack of every layer, for the life of the
+ * page, and each pack's state has to be kept apart from the others'. An entry is deleted as soon
+ * as its pack replies or is canceled.
+ */
+const requests = new Map();
+/** This worker's global scope. */
+const scope = self;
+scope.onmessage = (event) => {
+    const message = event.data;
+    if (message.type === 'sources') {
+        const request = requestFor(message.id);
+        // Null rather than a rejection, so one set of bytes that is not an image drops its own def
+        // instead of failing the whole layer's pack. `packSources` skips it as a source with no pixels.
+        for (const source of message.sources) {
+            request.decoding.push(createImageBitmap(source).catch(() => null));
+        }
+        return;
+    }
+    if (message.type === 'cancel') {
+        cancel(message.id);
+        return;
+    }
+    const { id } = message;
+    pack(id, message.maxDimension).then((response) => {
+        // Nothing is owed for a canceled pack. The main thread has already settled it.
+        if (!response)
+            return;
+        // The bitmaps move rather than copy. After this the worker holds nothing for this pack.
+        scope.postMessage(response, response.atlases.map((atlas) => atlas.bitmap));
+    }, (error) => {
+        requests.delete(id);
+        scope.postMessage({ type: 'failed', id, message: String(error) });
+    });
+};

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

@@ -0,0 +1,62 @@
+import { type SourceReport } from '../pack-sources';
+import { type WorkerAtlas, type WorkerSource } from './atlas-worker';
+/** Options for {@link packInWorker}. */
+export interface PackInWorkerOptions {
+    /** Abandons the pack. The worker is told to drop it, and a reply that still arrives is thrown away. */
+    signal?: AbortSignal;
+    /**
+     * Makes the pooled worker, on the first pack that needs it. Defaults to the bundled atlas worker,
+     * and exists so a spec can drive the protocol against a fake one without a browser. It is ignored
+     * once a worker is pooled.
+     */
+    createWorker?: () => Worker;
+}
+/**
+ * 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 declare function packInWorker(sources: readonly WorkerSource[], maxDimension: number, options?: PackInWorkerOptions): Promise<{
+    atlases: WorkerAtlas[];
+    reports: SourceReport[];
+}>;
+/**
+ * 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 declare function resetAtlasWorkerPool(): void;
+/**
+ * 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 declare const SOURCE_CHUNK_SIZE = 25;
+//# sourceMappingURL=client.d.ts.map

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

@@ -5,10 +5,10 @@ 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 — under the root layer's dim
-     * provider, which is what the scene's background quad mounts here for: the root's dim reaches it
-     * like any layer's, and its material exists before every layer's, which its draw order relies
-     * on.
+     * 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;
 }
@@ -18,8 +18,9 @@ export interface LayerProps {
  * 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: nothing above the root can hide it, and the whole tree's draw order lives inside
- * `[0, 1)`.
+ * 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.
  */

package/dist/objects/layer/Layer.js

@@ -1,14 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense, use } from 'react';
+import { 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 { LayerDimContext } from '../materials/effects/color-dim';
 import { Models } from '../models';
 import { Shapes } from '../shapes';
 import { Texts } from '../text';
+import { LayerDimContext, LayerOverlayContext, useLayerDim, useLayerOverlay, } from './layer-context';
 import { useStagedChildren } from './mount-scheduler';
 import { useVisibilityGui } from './visibility-gui';
 /**
@@ -17,15 +17,16 @@ import { useVisibilityGui } from './visibility-gui';
  * 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: nothing above the root can hide it, and the whole tree's draw order lives inside
- * `[0, 1)`.
+ * 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(LayerNode, { layer: layer, parentVisible: true, orderBase: 0, orderStep: 1, children: children }));
+    return (_jsx(LayerNode, { layer: layer, hidden: false, orderBase: 0, orderStep: 1, children: children }));
 }
 /**
  * One layer of the tree as a three.js `<group>`, recursing into its child layers.
@@ -43,45 +44,43 @@ export function Layer(props) {
  * 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 group prop.** three propagates a group's `renderOrder` down its subtree as
- * `groupOrder`, which `painterSortStable` compares before `renderOrder` and `material.id` — so
- * numbering the groups is all it takes to make array order the draw order. A nested group
- * overwrites `groupOrder` for its own subtree, so the value that decides a mesh's place is its
- * nearest enclosing layer's; the numbers on layers above it are overwritten and simply do not
- * matter. Without this the order falls out of `material.id`, which ascends in mount order and
- * therefore puts any material built after first paint — every model's, since they exist only once
- * its GLB has loaded — last in the scene regardless of where its layer sits.
+ * 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.
  * @param props - The node props.
  * @returns The `<group>` for a layer def.
  */
 function LayerNode(props) {
-    const { layer, children: prelude, parentVisible, orderBase, orderStep } = props;
-    // On screen only if nothing above hides it either — the value picking hangs off, and what the
-    // children inherit in turn.
-    const visible = parentVisible && !layer.hidden;
-    // Nearest declaration wins and reaches every material beneath through context — so only
-    // `undefined` inherits, and a layer's own `0` un-dims it inside a dimmed ancestor. Unlike
-    // visibility this is never a prop: nothing between here and the material has any use for it.
-    const inheritedDim = use(LayerDimContext);
-    const dim = layer.dim ?? inheritedDim;
+    const { layer, children: prelude, hidden: parentHidden, orderBase, orderStep } = props;
+    // What the nearest ancestor already resolved for dim and overlay. A layer cannot see its
+    // ancestors any other way.
+    const parentDim = useLayerDim();
+    const parentOverlay = useLayerOverlay();
+    // Once hidden or once in the overlay tier, a subtree stays that way. A descendant that dropped
+    // back into the plan tier would invert the nesting, and a descendant of a hidden layer is not on
+    // screen whatever it says about itself.
+    const hidden = parentHidden || layer.hidden === true;
+    const overlay = parentOverlay || layer.overlay === true;
+    // Nearest declaration wins, so only `undefined` inherits. A layer's own 0 un-dims it inside a
+    // dimmed ancestor.
+    const dim = layer.dim ?? parentDim;
+    // 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(LayerNode, { layer: child, parentVisible: visible, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
+        contents = children.map((child, index) => (_jsx(LayerNode, { 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: orderBase, ...pointerProps, children: [prelude, contents] }));
-    // Always provided, never conditionally on the layer declaring a `dim`: making the provider appear
-    // when one is first set would change this component's element type, and React would remount the
-    // subtree — releasing and re-claiming every GPU slot beneath it, exactly what an eased dim must
-    // not do. A layer that declares none provides what it inherited, which no consumer can tell apart
-    // from not providing at all.
-    return _jsx(LayerDimContext, { value: dim, children: group });
+    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: dim, children: _jsx(LayerOverlayContext, { value: overlay, children: group }) }));
 }
 /**
  * The content of one leaf layer: the container for its defs' kind, inside a Suspense boundary of
@@ -112,3 +111,14 @@ function LeafContent(props) {
         content = _jsx(Models, { defs: defs, mounted: mounted });
     return _jsx(Suspense, { fallback: null, children: content });
 }
+/**
+ * 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/layer-context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The dim amount a layer draws at, which every material beneath it reads.
+ * @returns The nearest provided amount, or `0` with no layer above.
+ */
+export declare function useLayerDim(): number;
+/**
+ * Whether the current layer draws in the overlay tier.
+ * @returns `true` if this layer or an ancestor opted into the overlay tier, `false` otherwise.
+ */
+export declare function useLayerOverlay(): boolean;
+/**
+ * The dim amount the current layer hands down to its descendants.
+ *
+ * Context rather than a prop, because the value crosses the whole subtree and concerns none of the
+ * components between. A container hands its material nothing about layers, and a material that
+ * never asked about them still dims correctly. Threading it as a prop would put a `dim` on every
+ * material, every container, and every one of their inner components.
+ *
+ * Read through {@link useLayerDim} instead of directly. A `LayerNode` provides it, always, never
+ * only when it declares a `dim` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `0`, undimmed, which is what "no layer above me" means for a component rendered
+ * outside a `Layer` tree. A fourth inherited field belongs in a context and a hook of its own here,
+ * not folded into this one.
+ */
+export declare const LayerDimContext: import("react").Context<number>;
+/**
+ * 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