@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/materials/effects/ao/blur-pass.js

@@ -0,0 +1,101 @@
+import { Vector2 } from 'three';
+import { NOISE_TILE } from './ambient-occlusion-pass';
+/**
+ * Builds one blur pass's uniforms: the two textures it reads, its own texel step, and the scene's
+ * own kernel side.
+ *
+ * Per mount rather than per module, for the reason `createAoPassUniforms` is. These carry textures
+ * allocated in whichever GL context drew them, and a second mounted scene has a second set.
+ *
+ * {@link AmbientOcclusion.aoBlur} arrives by identity rather than by copy, so the debug GUI's write
+ * lands in this shader with nothing in between. The frame writes into everything else in place, so
+ * a frame costs no allocation and no shader recompile.
+ * @param occlusion - The mounted scene's own occlusion state, for the kernel side the debug GUI
+ *   tunes.
+ * @returns The uniform record, ready to hand to a `ShaderMaterial`.
+ */
+export function createBlurPassUniforms(occlusion) {
+    return {
+        /** The raw term the AO pass wrote, which this pass smooths. `null` until the AO pass runs. */
+        uOcclusion: { value: null },
+        /** The prepass's depth, which weights every tap. `null` until the prepass runs. */
+        uDepth: { value: null },
+        /** One texel of this pass's own target in uv, the step the kernel walks. */
+        uTexel: { value: new Vector2(1, 1) },
+        /** The kernel's side in texels, the scene's own object. See {@link AmbientOcclusion.aoBlur}. */
+        uBlur: occlusion.aoBlur,
+    };
+}
+/**
+ * How far apart two depths sit before a read stops treating them as one surface. Measured as a
+ * share of the range still ahead of the nearer one.
+ *
+ * One number for both readers, because they ask the same question. The blur pass asks it of every
+ * tap, so occlusion does not bleed across the edge between a wall and whatever stands behind it.
+ * The lit read asks it once, so a translucent surface, which drew into no prepass, takes no
+ * occlusion from whatever stands behind it.
+ *
+ * Too tight, and the tile's rotation survives the blur as visible noise, because the pass throws
+ * most taps away. Too loose, and occlusion bleeds a few pixels past a silhouette. The bleed is the
+ * gentler failure, so this number errs generous.
+ */
+export const AO_EDGE_TOLERANCE = 0.05;
+/**
+ * The blur pass's fragment stage: the depth-weighted square kernel that smooths the raw term.
+ *
+ * The kernel runs here rather than inside the lit material's read. There it bills per lit fragment
+ * at full resolution and once per overdraw, at `2 · side²` fetches. Measured on a real plan: `2 ms`
+ * with no occlusion at all, `4 ms` at side `1`, and `8 ms` at side `4`. The AO pass's tap count
+ * makes no measurable difference. Here the kernel bills once per texel of a quarter-area target
+ * with no overdraw, and the lit read drops to two fetches.
+ *
+ * The pass samples the depth texture while it writes a color texture, so it binds a target with no
+ * depth attachment. A write through the prepass's own target is a rendering feedback loop, which
+ * WebGL2 leaves undefined and browsers refuse. That is what the third render target is for, see
+ * `occlusion-targets.ts`.
+ *
+ * This fragment's own depth comes from the texture, because the pass carries no geometry that
+ * writes one. One fetch, at this texel's own center.
+ */
+export const BLUR_FRAGMENT_SHADER = /* glsl */ `
+  uniform sampler2D uOcclusion;
+  uniform sampler2D uDepth;
+  uniform vec2 uTexel;
+  uniform int uBlur;
+  varying vec2 vUv;
+
+  const float AO_EDGE = ${AO_EDGE_TOLERANCE};
+
+  void main() {
+    float depth = texture2D(uDepth, vUv).x;
+    // Symmetric at any side, and this texel alone at side 1.
+    float center = float(uBlur - 1) * .5;
+    float occluded = 0.;
+    float total = 0.;
+    // GLSL ES 1.00 on the old Android WebViews this SDK reaches needs constant loop bounds, and the
+    // break is what skips the fetches.
+    for (int y = 0; y < ${NOISE_TILE}; y++) {
+      if (y >= uBlur) break;
+      for (int x = 0; x < ${NOISE_TILE}; x++) {
+        if (x >= uBlur) break;
+        vec2 at = vUv + (vec2(float(x), float(y)) - center) * uTexel;
+        // Depth-aware, so occlusion does not bleed across the edge between a wall and whatever
+        // stands behind it. Stored depth is not linear, so the difference is a share of the range
+        // still ahead of this texel.
+        float stored = texture2D(uDepth, at).x;
+        float apart = abs(stored - depth) / max(1. - depth, 1e-6);
+        float weight = 1. - smoothstep(0., AO_EDGE, apart);
+        occluded += texture2D(uOcclusion, at).r * weight;
+        total += weight;
+      }
+    }
+
+    // Nothing around this texel describes the surface it is on, so there is no term to write and no
+    // total to divide by. Open, which a lit read of it leaves alone.
+    if (total <= 0.) {
+      gl_FragColor = vec4(0., 0., 0., 1.);
+      return;
+    }
+    gl_FragColor = vec4(occluded / total, 0., 0., 1.);
+  }
+`;

package/dist/objects/materials/effects/ao/index.d.ts

@@ -0,0 +1,129 @@
+import { type DepthTexture, type IUniform, type Object3D, type Texture, Vector2 } from 'three';
+export * from './ambient-occlusion-pass';
+export * from './ambient-occlusion-patch';
+export * from './blur-pass';
+/**
+ * The scene-wide state this term owns: the uniforms every lit material reads, the values the debug
+ * GUI tunes, and the registry of what asks for the term.
+ *
+ * The term declares its own state, so it sits here rather than in `effects-context.ts`, and
+ * `OCCLUSION_DEFAULTS` sits here for the same reason.
+ *
+ * Every field keeps its `ao` prefix because the bundle is flat, and the contact shadow brings a
+ * strength and a color of its own. The last four fields carry no prefix, because no shader reads
+ * them.
+ *
+ * A uniform here is a uniform some shader captures by identity, so a GUI write lands straight in a
+ * shader. A value a pass reads by copy is a plain number instead.
+ */
+export interface AmbientOcclusion {
+    /**
+     * The smoothed occlusion the blur pass wrote, or `null` before the first frame. `0` is open, `1`
+     * is closed. The blur pass writes this one, and the AO pass writes the raw term behind it.
+     */
+    aoMap: IUniform<Texture | null>;
+    /**
+     * The prepass's depth, or `null` before the first frame.
+     *
+     * A depth texture rather than any texture, so nothing assigns this and the map to each other by
+     * mistake. three binds it like any other texture.
+     *
+     * The lit read weights the term with it, which keeps a translucent surface from taking the
+     * occlusion of whatever stands behind it. The main pass binds no framebuffer that carries this
+     * texture, so the sample there is legal.
+     */
+    aoDepth: IUniform<DepthTexture | null>;
+    /**
+     * `1` while the passes drew this frame, `0` when they did not. Every gate clears it before it
+     * returns, so a frame that skipped the passes shades correctly rather than sampling a stale
+     * texture.
+     */
+    aoActive: IUniform<number>;
+    /**
+     * The guard band, `g`: how much wider than the main frustum the two passes run.
+     *
+     * The main pass finds its own fragment in the AO texture with this one scalar rather than a
+     * matrix: `((gl_FragCoord.xy / viewport) * 2 - 1) / (1 + g) * 0.5 + 0.5`.
+     */
+    aoGuard: IUniform<number>;
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    aoStrength: IUniform<number>;
+    /**
+     * The blur kernel's side length in texels, from `1` to {@link NOISE_TILE}.
+     *
+     * A measurement dial rather than a free quality setting. The blur pass costs `2 · side²` texture
+     * fetches a texel, and it bills per texel of a quarter-area target rather than per lit fragment.
+     * Side `1` is the floor, where the pass copies the raw term through.
+     *
+     * A `4 × 4` kernel averages the `4 × 4` rotation tile, which turns rotated sampling into a smooth
+     * result. A smaller side leaves structured noise behind.
+     */
+    aoBlur: IUniform<number>;
+    /** The drawing buffer's size in pixels, the unit `gl_FragCoord` counts in. */
+    aoViewport: IUniform<Vector2>;
+    /** Whether the term runs at all. The debug GUI's switch, not a capability check. */
+    enabled: boolean;
+    /** How far the term looks for an occluder, in plan units. */
+    radius: number;
+    /**
+     * How many of the kernel's {@link AO_TAPS} offsets the AO pass walks. Fewer taps measure less of
+     * the hemisphere, so the pass misses a narrow occluder more often.
+     */
+    taps: number;
+    /**
+     * Every mesh that asks for occlusion, which is every mesh the depth prepass draws.
+     *
+     * A set rather than a count, so React's StrictMode double mount cannot make it drift.
+     * `useOccluder` fills it. An empty set means nothing on this plan asked, so `OcclusionPasses`
+     * holds no render targets and draws no pass.
+     */
+    occluders: Set<Object3D>;
+}
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * `createAoPassUniforms` builds what the AO pass alone reads. This builds what the whole scene
+ * shares, and what `createSceneEffects` spreads into the bundle it publishes.
+ * @returns A fresh object, whose identity outlives every write into it.
+ */
+export declare function createAmbientOcclusion(): AmbientOcclusion;
+/**
+ * The occlusion values this design agreed, and what each mount starts from.
+ *
+ * `radius` and `strength` are starting points rather than settled numbers, and the GUI tunes both
+ * per plan. `radius` is an absolute figure in plan units, so it suits one plan's booth sizes and
+ * not another's.
+ *
+ * `blur` and `taps` start at each loop's own bound, which is the shipped look.
+ */
+export declare const OCCLUSION_DEFAULTS: {
+    /** Whether the term runs at all. */
+    enabled: boolean;
+    /**
+     * How far the term looks for an occluder, in plan units.
+     *
+     * Chosen against the story plans, whose booths run about a hundred plan units across. That makes
+     * a band under a tenth of a booth wide, where a junction's shadow reads as shading rather than as
+     * an outline.
+     */
+    radius: number;
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    strength: number;
+    /**
+     * The blur kernel's side length in texels. It starts at the side that covers the rotation tile,
+     * see {@link AmbientOcclusion.aoBlur}.
+     */
+    blur: number;
+    /** How many of the kernel's offsets the AO pass walks, see {@link AmbientOcclusion.taps}. */
+    taps: number;
+    /**
+     * How much wider than the main frustum the two passes run.
+     *
+     * Without the band, geometry just outside the frustum does not occlude geometry inside it, and a
+     * seam of missing darkening runs down the screen edges. `0.15` covers the widest reach a tap
+     * takes at half resolution. The cost is a lower effective resolution and more geometry in the
+     * frustum.
+     */
+    guard: number;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/materials/effects/ao/index.js

@@ -0,0 +1,72 @@
+import { Vector2 } from 'three';
+import { AO_TAPS, NOISE_TILE } from './ambient-occlusion-pass';
+// The folder's public face. One specifier carries every member the outside asks for.
+//
+// The three siblings must never import a value from here. Both pass shaders and the lit read are
+// template literals that interpolate constants at module initialization. A cycle through this file
+// evaluates one of those constants before its own module assigns it. The emit erases the
+// `import type` the siblings use, so that import forms no cycle.
+export * from './ambient-occlusion-pass';
+export * from './ambient-occlusion-patch';
+export * from './blur-pass';
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * `createAoPassUniforms` builds what the AO pass alone reads. This builds what the whole scene
+ * shares, and what `createSceneEffects` spreads into the bundle it publishes.
+ * @returns A fresh object, whose identity outlives every write into it.
+ */
+export function createAmbientOcclusion() {
+    return {
+        aoMap: { value: null },
+        aoDepth: { value: null },
+        aoActive: { value: 0 },
+        aoGuard: { value: OCCLUSION_DEFAULTS.guard },
+        aoStrength: { value: OCCLUSION_DEFAULTS.strength },
+        aoBlur: { value: OCCLUSION_DEFAULTS.blur },
+        aoViewport: { value: new Vector2(1, 1) },
+        enabled: OCCLUSION_DEFAULTS.enabled,
+        radius: OCCLUSION_DEFAULTS.radius,
+        taps: OCCLUSION_DEFAULTS.taps,
+        occluders: new Set(),
+    };
+}
+/**
+ * The occlusion values this design agreed, and what each mount starts from.
+ *
+ * `radius` and `strength` are starting points rather than settled numbers, and the GUI tunes both
+ * per plan. `radius` is an absolute figure in plan units, so it suits one plan's booth sizes and
+ * not another's.
+ *
+ * `blur` and `taps` start at each loop's own bound, which is the shipped look.
+ */
+export const OCCLUSION_DEFAULTS = {
+    /** Whether the term runs at all. */
+    enabled: true,
+    /**
+     * How far the term looks for an occluder, in plan units.
+     *
+     * Chosen against the story plans, whose booths run about a hundred plan units across. That makes
+     * a band under a tenth of a booth wide, where a junction's shadow reads as shading rather than as
+     * an outline.
+     */
+    radius: 8,
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    strength: 0.35,
+    /**
+     * The blur kernel's side length in texels. It starts at the side that covers the rotation tile,
+     * see {@link AmbientOcclusion.aoBlur}.
+     */
+    blur: NOISE_TILE,
+    /** How many of the kernel's offsets the AO pass walks, see {@link AmbientOcclusion.taps}. */
+    taps: AO_TAPS,
+    /**
+     * How much wider than the main frustum the two passes run.
+     *
+     * Without the band, geometry just outside the frustum does not occlude geometry inside it, and a
+     * seam of missing darkening runs down the screen edges. `0.15` covers the widest reach a tap
+     * takes at half resolution. The cost is a lower effective resolution and more geometry in the
+     * frustum.
+     */
+    guard: 0.15,
+};

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

@@ -0,0 +1,115 @@
+import { type IUniform, type WebGLProgramParametersWithUniforms } from 'three';
+import { type UniformSchemaShader } from '../../../core/InstanceUniforms';
+import { type RenderableDef } from '../../../types/defs';
+/**
+ * Patches a compiled shader to dim what it draws. Returned by {@link useDimPatch} and called from a
+ * material's own `onBeforeCompile`, so a material that already patches its shader composes the two
+ * rather than choosing between them.
+ */
+export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
+/**
+ * The dim patch every material installs, following the layer amount from {@link useDimChain}.
+ *
+ * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
+ * so threading it as a prop would put a `dim` on each material, each container, and each of their
+ * inner components, and any new one would have to remember to forward it. What a material needs to
+ * know is only *how* to be dimmed; what it is dimmed *by* belongs to the layer it draws under.
+ *
+ * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
+ * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
+ * @returns The patch to call from the material's `onBeforeCompile`.
+ */
+export declare function useDimPatch(): DimPatch;
+/**
+ * Installs dimming into a shader about to be compiled: the layer's uniform, the declarations, and
+ * the application.
+ *
+ * **Applies only once the mesh's uniform prologue is in the shader**, and that guard is what makes
+ * installation order stop mattering. The applied line reads the per-instance amount the prologue
+ * declares as a *local of `main`*, so it has to land in the same `main`. Most meshes inject their
+ * prologue and then call the material's handler, so a material-installed patch is already last. Text
+ * is the exception: troika calls the base material's handler first and then rebuilds `main` around
+ * it — renaming the original `troikaOrigMain` and calling it from a new one — so a patch installed
+ * there would land in a scope the prologue's local never reaches. With this guard that early call
+ * simply does nothing, and `BatchedTextImpl` runs the same patch again once its prologue is in.
+ * @param parameters - The shader being compiled.
+ * @param uniform - The layer's dim amount.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader has no output chain, which would leave
+ *   dimming silently absent from a material that asked for it.
+ */
+export declare function applyDim(parameters: WebGLProgramParametersWithUniforms, uniform: IUniform<number>): boolean;
+/**
+ * Orders a layer's defs so the dimmed ones draw first and the undimmed ones last, on top.
+ *
+ * What this is for: dimming the venue behind a search leaves the few undimmed defs as the subject of
+ * the frame, and a subject that a dimmed neighbor happens to overlap would be covered by it. Paint
+ * order is the only thing that resolves overlap in a 2D layer — 2D content never writes depth,
+ * leaving depth testing nothing of its own to compare against — so being undimmed has to lift a def
+ * above the defs it is being distinguished from.
+ *
+ * **Stable**, and that is load-bearing rather than a nicety: within each group the defs keep their
+ * array order, which is the order the caller authored and the only thing that decides overlap
+ * between two defs that are both dimmed or both lit. A dim is allowed to lift a def over the dimmed
+ * ones; it is not allowed to reshuffle anything else.
+ *
+ * Returns the input array itself when the rule changes nothing — every def in one group, which is
+ * every layer that is uniformly dimmed or uniformly not. Callers key their order pass on the
+ * identity of what comes back, so an unchanged layer costs neither an allocation nor a re-label.
+ * @param defs - The layer's defs, in authored order.
+ * @param layerDimmed - Whether the layer is dimmed, which is what a def without a `dim` of its own
+ *   inherits. Only the fact is needed, never the amount: this is a two-way split, and every amount
+ *   above zero lands on the same side of it. That is also what keeps an eased layer dim cheap — the
+ *   order pass re-runs when the value crosses zero, not on each of the frames between.
+ * @returns The defs in draw order.
+ */
+export declare function dimOrdered<T extends RenderableDef>(defs: readonly T[], layerDimmed: boolean): readonly T[];
+/**
+ * Whether a def draws dimmed at all — the one question paint order asks about dimming, as opposed
+ * to the amount, which only the shader reads.
+ * @param dim - The def's own `dim`; `undefined` inherits.
+ * @param layerDimmed - Whether the layer it draws under is dimmed.
+ * @returns Whether it draws dimmed.
+ */
+export declare function isDimmed(dim: number | undefined, layerDimmed: boolean): boolean;
+/**
+ * Encodes a def's own `dim` for its per-instance uniform.
+ * @param dim - The def's `dim`; `undefined` defers to the layer.
+ * @returns The value to write.
+ */
+export declare function instanceDim(dim: number | undefined): number;
+/**
+ * Clamps a dim amount into the range the shader interpolates over, so `mix` never extrapolates into
+ * a color that is not a dim of the original.
+ * @param dim - The amount to clamp.
+ * @returns The amount, within `[0, 1]`.
+ */
+export declare function clampDim(dim: number): number;
+/**
+ * The per-instance uniform a def's own dim is written to. Declared by every container that draws
+ * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to
+ * declare it before any slot writes one.
+ */
+export declare const DIM_UNIFORM = "instanceDim";
+/**
+ * What an instance writes to defer to its layer.
+ *
+ * Any negative value would do; the sentinel only has to fall outside `[0, 1]`, which is why the
+ * amount itself can be stored as-is rather than packed around a zero that means "inherit". The
+ * imperative renderer needed that packing because its texture zero-filled and nothing wrote an
+ * instance on mount — here every instance writes its own value through `useDefSync`, so the fill is
+ * never what a draw reads.
+ */
+export declare const DIM_INHERIT = -1;
+/**
+ * The schema a container declares to give its instances a dim of their own.
+ *
+ * Declared in the **vertex** stage although only the fragment shader reads it: that is what makes
+ * `InstanceUniforms` fetch it once per vertex and deliver it as a varying, instead of a texel fetch
+ * per fragment. It also moves any sibling uniform the same way, which costs nothing — images, lines
+ * and models already declare vertex uniforms, and shapes and text declare none besides this.
+ */
+export declare const DIM_SCHEMA: UniformSchemaShader;
+//# sourceMappingURL=color-dim.d.ts.map

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

@@ -0,0 +1,206 @@
+import { useThree } from '@react-three/fiber';
+import { useEffect, useRef, useState } from 'react';
+import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source';
+import { resolveDim, subscribeDim, useDimChain } from '../../layer/layer-context';
+/**
+ * The dim patch every material installs, following the layer amount from {@link useDimChain}.
+ *
+ * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
+ * so threading it as a prop would put a `dim` on each material, each container, and each of their
+ * inner components, and any new one would have to remember to forward it. What a material needs to
+ * know is only *how* to be dimmed; what it is dimmed *by* belongs to the layer it draws under.
+ *
+ * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
+ * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
+ * @returns The patch to call from the material's `onBeforeCompile`.
+ */
+export function useDimPatch() {
+    const chain = useDimChain();
+    const invalidate = useThree((state) => state.invalidate);
+    // A ref, not state: this object is written after render, every frame of an eased dim, and a ref is
+    // the container React sanctions that for. Its identity is what three holds onto, so the value can
+    // move underneath a program that is already built.
+    const uniformRef = useRef({ value: 0 });
+    // Created once and kept: R3F writes every changed prop onto the material, so handing it a fresh
+    // handler each render risks a recompile per frame — the one thing an animated dim must not cost.
+    const [patch] = useState(() => (parameters) => applyDim(parameters, uniformRef.current));
+    useEffect(() => {
+        /** Writes the layer's current amount into the uniform, and asks for a frame when it moved. */
+        function follow() {
+            const amount = clampDim(resolveDim(chain));
+            if (uniformRef.current.value === amount)
+                return;
+            uniformRef.current.value = amount;
+            invalidate();
+        }
+        follow();
+        return subscribeDim(chain, follow);
+    }, [chain, invalidate]);
+    return patch;
+}
+/**
+ * Installs dimming into a shader about to be compiled: the layer's uniform, the declarations, and
+ * the application.
+ *
+ * **Applies only once the mesh's uniform prologue is in the shader**, and that guard is what makes
+ * installation order stop mattering. The applied line reads the per-instance amount the prologue
+ * declares as a *local of `main`*, so it has to land in the same `main`. Most meshes inject their
+ * prologue and then call the material's handler, so a material-installed patch is already last. Text
+ * is the exception: troika calls the base material's handler first and then rebuilds `main` around
+ * it — renaming the original `troikaOrigMain` and calling it from a new one — so a patch installed
+ * there would land in a scope the prologue's local never reaches. With this guard that early call
+ * simply does nothing, and `BatchedTextImpl` runs the same patch again once its prologue is in.
+ * @param parameters - The shader being compiled.
+ * @param uniform - The layer's dim amount.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader has no output chain, which would leave
+ *   dimming silently absent from a material that asked for it.
+ */
+export function applyDim(parameters, uniform) {
+    const fragment = parameters.fragmentShader;
+    // Nothing to read, so nothing to do — either the mesh declared no per-instance dim, or its
+    // prologue has not been injected yet.
+    if (!fragment.includes(DIM_UNIFORM))
+        return false;
+    // Already installed, which is how a second call after the prologue arrives stays harmless.
+    if (fragment.includes(DIM_FUNCTION))
+        return false;
+    const anchor = sceneColorAnchor(fragment);
+    if (!anchor)
+        throw new Error('applyDim: the shader has no output chain to dim before.');
+    parameters.uniforms[LAYER_DIM] = uniform;
+    // Ahead of `main`, because these are file-scope declarations — and `dimColor` takes the amount as a
+    // parameter precisely so it needs nothing `main` declares.
+    parameters.fragmentShader = declareBeforeMain(fragment, DIM_DEFS).replace(anchor, `${DIM_APPLY}\n${anchor}`);
+    return true;
+}
+/**
+ * Orders a layer's defs so the dimmed ones draw first and the undimmed ones last, on top.
+ *
+ * What this is for: dimming the venue behind a search leaves the few undimmed defs as the subject of
+ * the frame, and a subject that a dimmed neighbor happens to overlap would be covered by it. Paint
+ * order is the only thing that resolves overlap in a 2D layer — 2D content never writes depth,
+ * leaving depth testing nothing of its own to compare against — so being undimmed has to lift a def
+ * above the defs it is being distinguished from.
+ *
+ * **Stable**, and that is load-bearing rather than a nicety: within each group the defs keep their
+ * array order, which is the order the caller authored and the only thing that decides overlap
+ * between two defs that are both dimmed or both lit. A dim is allowed to lift a def over the dimmed
+ * ones; it is not allowed to reshuffle anything else.
+ *
+ * Returns the input array itself when the rule changes nothing — every def in one group, which is
+ * every layer that is uniformly dimmed or uniformly not. Callers key their order pass on the
+ * identity of what comes back, so an unchanged layer costs neither an allocation nor a re-label.
+ * @param defs - The layer's defs, in authored order.
+ * @param layerDimmed - Whether the layer is dimmed, which is what a def without a `dim` of its own
+ *   inherits. Only the fact is needed, never the amount: this is a two-way split, and every amount
+ *   above zero lands on the same side of it. That is also what keeps an eased layer dim cheap — the
+ *   order pass re-runs when the value crosses zero, not on each of the frames between.
+ * @returns The defs in draw order.
+ */
+export function dimOrdered(defs, layerDimmed) {
+    const dimmed = [];
+    const lit = [];
+    for (const def of defs)
+        (isDimmed(def.dim, layerDimmed) ? dimmed : lit).push(def);
+    return dimmed.length === 0 || lit.length === 0 ? defs : [...dimmed, ...lit];
+}
+/**
+ * Whether a def draws dimmed at all — the one question paint order asks about dimming, as opposed
+ * to the amount, which only the shader reads.
+ * @param dim - The def's own `dim`; `undefined` inherits.
+ * @param layerDimmed - Whether the layer it draws under is dimmed.
+ * @returns Whether it draws dimmed.
+ */
+export function isDimmed(dim, layerDimmed) {
+    return dim === undefined ? layerDimmed : dim > 0;
+}
+/**
+ * Encodes a def's own `dim` for its per-instance uniform.
+ * @param dim - The def's `dim`; `undefined` defers to the layer.
+ * @returns The value to write.
+ */
+export function instanceDim(dim) {
+    return dim === undefined ? DIM_INHERIT : clampDim(dim);
+}
+/**
+ * Clamps a dim amount into the range the shader interpolates over, so `mix` never extrapolates into
+ * a color that is not a dim of the original.
+ * @param dim - The amount to clamp.
+ * @returns The amount, within `[0, 1]`.
+ */
+export function clampDim(dim) {
+    return Math.min(Math.max(dim, 0), 1);
+}
+/**
+ * The per-instance uniform a def's own dim is written to. Declared by every container that draws
+ * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to
+ * declare it before any slot writes one.
+ */
+export const DIM_UNIFORM = 'instanceDim';
+/**
+ * What an instance writes to defer to its layer.
+ *
+ * Any negative value would do; the sentinel only has to fall outside `[0, 1]`, which is why the
+ * amount itself can be stored as-is rather than packed around a zero that means "inherit". The
+ * imperative renderer needed that packing because its texture zero-filled and nothing wrote an
+ * instance on mount — here every instance writes its own value through `useDefSync`, so the fill is
+ * never what a draw reads.
+ */
+export const DIM_INHERIT = -1;
+/**
+ * The schema a container declares to give its instances a dim of their own.
+ *
+ * Declared in the **vertex** stage although only the fragment shader reads it: that is what makes
+ * `InstanceUniforms` fetch it once per vertex and deliver it as a varying, instead of a texel fetch
+ * per fragment. It also moves any sibling uniform the same way, which costs nothing — images, lines
+ * and models already declare vertex uniforms, and shapes and text declare none besides this.
+ */
+export const DIM_SCHEMA = { vertex: { [DIM_UNIFORM]: 'float' } };
+/** The uniform carrying the layer-level amount an instance without one of its own falls back to. */
+const LAYER_DIM = 'uDim';
+/** The signature {@link applyDim} looks for to tell an already-patched shader from a fresh one. */
+const DIM_FUNCTION = 'vec4 dimColor(';
+/**
+ * Dimming's file-scope declarations.
+ *
+ * Dim is a desaturation toward gray, not a darkening. That is why it cannot be baked into a
+ * per-instance tint: a texel sampled per fragment has no tint to bake into.
+ *
+ * `dimColor` works on `gl_FragColor` whichever way it is stored, and hands it back stored the same
+ * way. It only ever scales `col.rgb`: `mix(c, dot(w, c) / k, t)` is linear and homogeneous in `c`,
+ * so scaling the input by any constant scales the output by that same constant. That homogeneity
+ * is also why a premultiplied, `SRGBColorSpace`-tagged atlas texture dims to the same composited
+ * pixels as the straight-alpha texture this renderer used before it. Measuring old against new
+ * leaves a small residual: at most about 8 of 255 on one channel, across every alpha and dim
+ * amount tested.
+ *
+ * `stories/objects/layer/Dim.stories.tsx` does not cover any of this. Its image layer draws
+ * `markerCanvas(tint)`, whose whole surface is opaque, so no pixel in that story ever carries a
+ * partial alpha for `dimColor` to distort.
+ *
+ * The imperative renderer divided rgb by alpha here and multiplied it back at the end. The round
+ * trip cancels for the same reason: `f(c / a) * a == f(c)` for every alpha. Dividing by alpha was
+ * also the one step that could produce a NaN, at `a == 0`, which SDF text edges generate in
+ * quantity. Dropping it changes no pixel.
+ */
+const DIM_DEFS = /* glsl */ `
+  uniform float ${LAYER_DIM};
+
+  const vec3 grayWeights = vec3(0.299, 0.587, 0.114);
+  const float darkenFactor = pow(2., 2.2); // Gamma corrected
+
+  ${DIM_FUNCTION}vec4 col, float amount) {
+    vec3 gray = vec3(dot(grayWeights, col.rgb));
+    return vec4(mix(col.rgb, gray / darkenFactor, amount), col.a);
+  }
+`;
+/**
+ * Dimming applied while the color is still linear and scene-referred, which is what `darkenFactor`'s
+ * gamma correction assumes. See {@link sceneColorAnchor}.
+ */
+const DIM_APPLY = /* glsl */ `
+  gl_FragColor = dimColor(gl_FragColor, ${DIM_UNIFORM} < 0. ? ${LAYER_DIM} : ${DIM_UNIFORM});
+`;