@expofp/renderer 3.37.1 → 3.39.0

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

@@ -0,0 +1,45 @@
+import { createContext, use } from 'react';
+/**
+ * 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 function useLayerDim() {
+    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);
+}
+/**
+ * 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 const LayerDimContext = createContext(0);
+/**
+ * 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);

package/dist/objects/materials/ColorMaterial.js

@@ -1,10 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
+import { createLogger } from '../../utils/logging';
+import { useLayerOverlay } from '../layer/layer-context';
 import { applyAmbientOcclusion } from './effects/ao';
 import { useDimPatch } from './effects/color-dim';
 import { applyContactShadow } from './effects/contact-shadow';
 import { useSceneEffects } from './effects/effects-context';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
+const logger = createLogger('color-material');
 /**
  * The material a shape batch draws with. It renders as a child of the mesh, so R3F attaches, updates
  * and disposes it. It is also troika's base material for text, which never asks for `solid`. See
@@ -76,6 +79,16 @@ export function ColorMaterial(props) {
     // skips the component in silence, so only the running app shows the failure.
     const color = props.color ?? 'white';
     const solid = props.solid === true;
+    const overlay = useLayerOverlay();
+    // Overlay is a contract for planar content. A volume that stops depth testing loses its own self
+    // occlusion, because its far faces then paint over its near ones in pack order. Making it work
+    // needs a depth clear between the tiers, so a second render pass, which external mode does not
+    // own. So a volume ignores the flag completely and says once that it did.
+    useEffect(() => {
+        if (solid && overlay) {
+            logger.warn('overlay has no effect on a solid batch, so it is ignored.');
+        }
+    }, [solid, overlay]);
     // Handed to both branches, because a volume dims the way flat content does. The patch runs on
     // whatever `gl_FragColor` the material arrived at, which for a lit material is the shaded color.
     const dimPatch = useDimPatch();
@@ -107,5 +120,5 @@ export function ColorMaterial(props) {
         const translucent = props.translucent ?? false;
         return (_jsx("meshLambertMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
     }
-    return _jsx("meshBasicMaterial", { ...sharedParams, color: color, onBeforeCompile: onBeforeCompile });
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), color: color, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/LineMaterial.js

@@ -2,8 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { extend } from '@react-three/fiber';
 import { NotEqualStencilFunc, ReplaceStencilOp, } from 'three';
 import { LineMaterial as LineMaterialBase } from 'three/addons/lines/LineMaterial.js';
+import { useLayerOverlay } from '../layer/layer-context';
 import { useDimPatch } from './effects/color-dim';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
 /**
  * The stencil value a line layer stamps on every pixel it covers.
  *
@@ -55,6 +56,7 @@ export function LineMaterial(props) {
     const color = props.color ?? 'white';
     const width = props.width ?? 1;
     const onBeforeCompile = useDimPatch();
+    const overlay = useLayerOverlay();
     /**
      * Hands the batch about to draw a clean stencil to stamp.
      *
@@ -68,5 +70,5 @@ export function LineMaterial(props) {
     function onBeforeRender(renderer) {
         renderer.clearStencil();
     }
-    return (_jsx(LineMaterialElement, { ...sharedParams, color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
+    return (_jsx(LineMaterialElement, { ...sharedParams, ...(overlay ? overlayParams : null), color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/TextureMaterial.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { OneFactor } from 'three';
+import { useLayerOverlay } from '../layer/layer-context';
 import { useDimPatch } from './effects/color-dim';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
 /**
  * The material used to render a texture, optionally through a per-instance uv-offset uniform so an
  * instanced/batched mesh can pack many regions into one atlas.
@@ -15,6 +17,7 @@ import { sharedParams } from './shared';
 export function TextureMaterial(props) {
     const { map, uvOffset } = props;
     const applyDim = useDimPatch();
+    const overlay = useLayerOverlay();
     function onBeforeCompile(parameters) {
         applyDim(parameters);
         if (!uvOffset)
@@ -25,5 +28,14 @@ export function TextureMaterial(props) {
         vMapUv = uv * ${uvOffset}.zw + ${uvOffset}.xy;
       `.trim());
     }
-    return _jsx("meshBasicMaterial", { ...sharedParams, map: map, onBeforeCompile: onBeforeCompile });
+    // An atlas texture is premultiplied (see `makeAtlasTexture`'s `premultiplyAlpha` comment), so
+    // this material needs the premultiplied blend, not `sharedParams`'s straight-alpha one.
+    // `blendSrc: OneFactor` is the only change: the source term becomes `1 * (c * a)`, which already
+    // equals the straight blend's own `c * a` source term, so the composited color comes out the
+    // same either way. `blendDst` stays `OneMinusSrcAlphaFactor` from `sharedParams`, since that half
+    // does not depend on how the source is stored.
+    //
+    // The override lives here, not in `sharedParams`, because `ColorMaterial` and `LineMaterial`
+    // share that object and their colors are never premultiplied.
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
 }

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

@@ -8,7 +8,7 @@ import { type RenderableDef } from '../../../types/defs';
  */
 export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
 /**
- * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
  *
  * 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
@@ -86,15 +86,6 @@ export declare function instanceDim(dim: number | undefined): number;
  * @returns The amount, within `[0, 1]`.
  */
 export declare function clampDim(dim: number): number;
-/**
- * The dim amount a layer draws at, which every material beneath it reads.
- *
- * 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, and a material that never asked about
- * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
- * a layer without one is transparent to this, which is exactly what inheritance means.
- */
-export declare const LayerDimContext: import("react").Context<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

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

@@ -1,8 +1,9 @@
 import { useThree } from '@react-three/fiber';
-import { createContext, use, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source';
+import { useLayerDim } from '../../layer/layer-context';
 /**
- * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
  *
  * 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
@@ -15,7 +16,7 @@ import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export function useDimPatch() {
-    const dim = use(LayerDimContext);
+    const dim = useLayerDim();
     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
@@ -125,15 +126,6 @@ export function instanceDim(dim) {
 export function clampDim(dim) {
     return Math.min(Math.max(dim, 0), 1);
 }
-/**
- * The dim amount a layer draws at, which every material beneath it reads.
- *
- * 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, and a material that never asked about
- * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
- * a layer without one is transparent to this, which is exactly what inheritance means.
- */
-export const LayerDimContext = createContext(0);
 /**
  * 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
@@ -166,14 +158,25 @@ const DIM_FUNCTION = 'vec4 dimColor(';
 /**
  * Dimming's file-scope declarations.
  *
- * Dim is a desaturation toward gray, not a darkening — which is why it cannot be baked into a
+ * 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` takes straight (non-premultiplied) `gl_FragColor` and returns it the same way. The
- * imperative renderer divided rgb by alpha here and multiplied it back at the end; the round-trip
- * cancels — `mix(c, dot(w, c) / k, t)` is linear and homogeneous in `c`, so `f(c / a) * a == f(c)`
- * for every alpha — and it was the one thing that could produce a NaN, at `a == 0`, which SDF text
- * edges generate in quantity. Dropping it changes no pixel.
+ * `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};

package/dist/objects/materials/effects/effects-context.d.ts

@@ -25,11 +25,12 @@ import { type ContactShadow } from './contact-shadow';
  * `contact-shadow.ts` uses for its three uniforms, published the way `SpaceContext` publishes a
  * `Space` that is refitted in place.
  *
- * **`LayerDimContext` stays where it is and is not merged in.** It carries a single number, it is
- * re-provided by every `Layer`, and it nests. This bundle is one object per renderer mount whose
- * identity must never change, which is what lets a material capture it in `onBeforeCompile` and a
- * frame write `.value` with no recompile. Merging the two would either re-provide this object at
- * every layer boundary or flatten dim's nesting.
+ * **`LayerDimContext` and `LayerOverlayContext` stay where they are and are not merged in.** Each
+ * carries one primitive of a layer's inherited state, is re-provided by every layer, and nests.
+ * This bundle is one object per renderer mount whose identity must never change, which is what
+ * lets a material capture it in `onBeforeCompile` and a frame write `.value` with no recompile.
+ * Merging either one in would either re-provide this object at every layer boundary or flatten
+ * that nesting.
  */
 export type SceneEffects = AmbientOcclusion & ContactShadow;
 /**

package/dist/objects/materials/shared.d.ts

@@ -3,4 +3,22 @@ import { type MaterialParameters } from 'three';
  * Material parameter defaults, shared between all types
  */
 export declare const sharedParams: MaterialParameters;
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export declare const overlayParams: MaterialParameters;
 //# sourceMappingURL=shared.d.ts.map

package/dist/objects/materials/shared.js

@@ -49,3 +49,24 @@ export const sharedParams = {
     polygonOffsetUnits: -FLAT_BIAS_UNITS,
     forceSinglePass: true,
 };
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export const overlayParams = {
+    depthTest: false,
+    transparent: true,
+};

package/dist/objects/models/Models.js

@@ -139,15 +139,8 @@ function ModelPartMesh(props) {
     // instead — but the hit resolution is not: `InstancedMeshImpl.raycast` walks the live slots,
     // skipping deleted and hidden ones, and raycasts the real merged geometry, so a hit names the
     // model's actual triangles and the slot that drew them.
-    const container = useContainer(() => new ModelContainer(asset.extents, defs.length, kind), defs);
+    const container = useContainer(() => new ModelContainer(asset.extents, defs.length, kind), defs, onKindMismatch);
     const occluder = useOccluder();
-    // Assigned after mount rather than passed to the constructor: the container is built once and
-    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
-    // runs — the split that placed these defs was computed from the same opacities they mount with.
-    useEffect(() => {
-        container.setKindMismatchHandler(onKindMismatch);
-        return () => container.setKindMismatchHandler(undefined);
-    }, [container, onKindMismatch]);
     // The geometry belongs to the module-level cache and may be drawing in another layer, so it is
     // mounted as a `primitive` with `dispose={null}` — R3F must not free it on unmount. Sharing it is
     // safe because `InstancedMeshImpl` never writes to the geometry it is handed: its draw list lives in

package/dist/objects/shapes/Shapes.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { BatchedMesh } from '../../core/batch/BatchedMesh';
 import { defKey, useContainer } from '../containers';
 import { useOccluder } from '../lighting/occluder';
@@ -106,15 +106,8 @@ function ShapeBatch(props) {
     //
     // Stickiness costs this nothing: a batch mounts on the render that first fills it, so the defs
     // sizing the container are a real membership rather than the empty one it may later stand at.
-    const container = useContainer(() => new ShapeContainer(defs, kind), defs);
+    const container = useContainer(() => new ShapeContainer(defs, kind), defs, onKindMismatch);
     const occluder = useOccluder();
-    // Assigned after mount rather than passed to the constructor: the container is built once and
-    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
-    // runs — the split that placed these defs was computed from the same colors they mount with.
-    useEffect(() => {
-        container.setKindMismatchHandler(onKindMismatch);
-        return () => container.setKindMismatchHandler(undefined);
-    }, [container, onKindMismatch]);
     // Declares the incoming membership before React mounts the delta, so a change that outgrows the
     // mesh resizes each buffer once, to exactly this size, instead of once per claiming instance.
     // During render on purpose: instances claim in their mount effects, which run before any effect

package/dist/objects/text/TextInstance.js

@@ -77,7 +77,7 @@ function writeLine(mesh, lineSlot, text, line, placed, def) {
         writeColorAndOpacity(text, line.stroke.color, 'outline');
         text.outlineWidth = line.fontSize == 0 ? 0 : line.stroke.width / line.fontSize;
     }
-    applyPlacement(text, placed, def.bounds);
+    applyPlacement(text, placed, def.bounds, def.screenSpace === true);
 }
 function writeColorAndOpacity(text, color, field) {
     const colorFieldName = field == 'fill' ? 'color' : 'outlineColor';

package/dist/objects/text/text-layout.d.ts

@@ -61,16 +61,25 @@ export interface LaidOutLine {
  */
 export declare function layoutText(def: TextDef): LaidOutLine[];
 /**
- * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
  * offset, the line's scale, and its clip rect.
  *
- * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
- * batch — members are not in the scene graph, so nothing else would.
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
  * @param text - The member to place.
  * @param line - The line's local placement.
  * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
  */
-export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect): void;
+export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect, screenSpace: boolean): void;
 /**
  * The height one line's box occupies.
  *

package/dist/objects/text/text-layout.js

@@ -54,6 +54,11 @@ export function layoutText(def) {
         const scaleX = line.fontSize;
         // Negative: the y flip. Also why the clip rect below comes out correctly ordered — dividing by a
         // negative scale swaps its min and max back.
+        //
+        // `TextImpl.orientation` looks like the right tool for this flip, but it only reaches the shader
+        // as a uniform. `BatchedTextImpl.raycast` and `isDrawn` pick and cull through `text.matrix` and
+        // its geometry's bounds on the CPU, which never read it, so using `orientation` here draws
+        // correctly and picks the wrong region.
         const scaleY = -scaleX;
         placed.push({
             anchorX: alignment.horizontal,
@@ -80,16 +85,25 @@ export function layoutText(def) {
     return placed;
 }
 /**
- * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
  * offset, the line's scale, and its clip rect.
  *
- * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
- * batch — members are not in the scene graph, so nothing else would.
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
  * @param text - The member to place.
  * @param line - The line's local placement.
  * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
  */
-export function applyPlacement(text, line, bounds) {
+export function applyPlacement(text, line, bounds, screenSpace) {
     const { rotation } = bounds;
     const position = _position
         .set(line.offsetX, line.offsetY)
@@ -98,6 +112,18 @@ export function applyPlacement(text, line, bounds) {
     text.position.set(position.x, position.y, bounds.elevation);
     text.rotation.set(0, 0, rotation);
     text.scale.set(line.scaleX, line.scaleY, 1);
+    if (screenSpace) {
+        // Mutated in place rather than replaced, so a per-update write allocates nothing.
+        const anchor = text.spriteAnchor ?? new Vector2();
+        anchor.set(bounds.center.x, bounds.center.y);
+        text.spriteAnchor = anchor;
+        // The compose owns the matrix from here. Nothing may recompose it from the three fields above.
+        text.matrixAutoUpdate = false;
+    }
+    else {
+        text.spriteAnchor = null;
+        text.matrixAutoUpdate = true;
+    }
     text.updateMatrix();
     // Held as one array for the member's life: `clipRect` is not a syncable property, so this is a
     // plain per-frame read and mutating it in place avoids a per-update allocation.

package/dist/space/Space.d.ts

@@ -307,4 +307,19 @@ export declare function castRay(raycaster: Raycaster, ndc: NDCPointLike, camera:
  * would go.
  */
 export declare const HANDEDNESS_FLIP: Matrix4;
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export declare const Y_DOWN_FLIP: Matrix4;
 //# sourceMappingURL=Space.d.ts.map

package/dist/space/Space.js

@@ -2,7 +2,7 @@ import { Point } from '@expofp/geometry';
 import { createContext, use } from 'react';
 import { Matrix4, Plane, Ray, Raycaster, Vector2, Vector3, Vector4, } from 'three';
 import { createLogger } from '../utils/logging';
-import { clamp } from '../utils/math';
+import { axisLength, clamp } from '../utils/math';
 import { projectsFromFrustum } from './camera-kind';
 const logger = createLogger('space');
 /**
@@ -302,15 +302,6 @@ export function castRay(raycaster, ndc, camera) {
         .sub(raycaster.ray.origin)
         .normalize();
 }
-/**
- * The length one unit along an axis is drawn at.
- * @param matrix - The matrix to measure.
- * @param axis - Which axis: `0` for x, `1` for y.
- * @returns The transformed axis's length.
- */
-function axisLength(matrix, axis) {
-    return new Vector3().setFromMatrixColumn(matrix, axis).length();
-}
 /**
  * The last step of both paths into world space: mirror z.
  *
@@ -330,6 +321,21 @@ function axisLength(matrix, axis) {
  * would go.
  */
 export const HANDEDNESS_FLIP = new Matrix4().makeScale(1, 1, -1);
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export const Y_DOWN_FLIP = new Matrix4().makeScale(1, -1, 1);
 /** The plan's own plane in plan space, which every pointer position is reported on. */
 const PLAN_PLANE = new Plane(new Vector3(0, 0, 1), 0);
 /**

package/dist/types/defs.d.ts

@@ -2,8 +2,22 @@ import { type Box, type LineLike, type Rect, type Shape } from '@expofp/geometry
 import { type LayoutHandlers, type PointerHandlers } from './events';
 /** A color as a css string or a packed numeric value. */
 export type ColorInput = string | number;
-/** Any image-like source that can be uploaded as a texture. */
-export type ImageSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
+/**
+ * Any image-like source that the renderer can upload as a texture.
+ *
+ * A `Blob` is how anything fetched over the network arrives. It is a handle to an immutable byte
+ * store that the browser reference-counts. `postMessage` clones the handle, not the bytes. That is
+ * what lets atlas packing move to a worker. The renderer decodes the `Blob` itself, off the main
+ * thread wherever the environment allows it.
+ *
+ * `HTMLImageElement` is deliberately absent. Decoding one costs the main thread more than the
+ * packing it feeds: at a thousand logos on a throttled CPU, it stalled the page for two seconds.
+ * Leaving the member in the union would keep that slow path reachable. Pass a `Blob` instead.
+ *
+ * There is no `string` member either. The caller keeps all networking, so the renderer never
+ * learns about URLs, retries, or CORS.
+ */
+export type ImageSource = HTMLCanvasElement | ImageBitmap | OffscreenCanvas | Blob;
 /** Scene definition */
 export interface SceneDef {
     /** Root layer of the scene tree */
@@ -61,6 +75,22 @@ export interface LayerDef<T extends RenderableDef = RenderableDef> extends Share
     readonly name: string;
     /** Collection of layer's children. Mixing different types of children is not supported. */
     children: RenderableDefCollection<T>;
+    /**
+     * Draws this layer and its subtree above 3D content. Depth testing goes off, and the layer is
+     * ordered by the overlay tier rather than by the plan tier.
+     *
+     * A layer property, and a forced one. Depth mode is per material and render order is per group, so
+     * no implementation can vary either per instance. A def-level override could not be honored even
+     * if a caller wrote one.
+     *
+     * **This is for planar content.** A volume that stops depth testing loses its own self occlusion,
+     * because its far faces then paint over its near ones in pack order. So a solid shape batch and a
+     * model batch ignore this flag. A solid batch also warns once that it did.
+     *
+     * **A descendant cannot opt back out**: three propagates a group's render order to its whole
+     * subtree, so a descendant left in the plan tier would invert the nesting.
+     */
+    overlay?: boolean;
 }
 /** Shape definition. */
 export interface ShapeDef extends SharedDef {
@@ -91,6 +121,21 @@ export interface ImageDef extends SharedDef {
      * [0, 0] is the top-left corner, [0.5, 0.5] is the center (default), [1, 1] is the bottom-right corner.
      */
     origin?: [number, number];
+    /**
+     * Faces the camera, pivoting about `bounds.center` at `bounds.elevation`, at the size `bounds.size`
+     * gives in **plan units**. That is the same meaning `bounds.size` has for a flat def. A caller that
+     * wants a constant on-screen size keeps doing what markers do today, which is an `onScale` rule
+     * that rebuilds the bounds from the pixel size.
+     *
+     * `bounds.rotation` keeps its meaning, which is a spin about the content plane's normal. For a
+     * screen-space def that plane is the screen, so there is no separate spin field. An `onRoll` rule
+     * still runs, so keep this off where the rotation carries a plan bearing. Such a def would point
+     * at one screen direction however the plan is turned.
+     *
+     * Changing this at runtime is supported. The def moves between the layer's flat mesh and its
+     * camera-facing mesh, which never touches the atlas packing.
+     */
+    screenSpace?: boolean;
 }
 /** Text definition */
 export interface TextDef extends SharedDef {
@@ -109,6 +154,12 @@ export interface TextDef extends SharedDef {
     padding: [number, number];
     /** {@link TextAlignment} object describing text's alignment */
     alignment: TextAlignment;
+    /**
+     * As `ImageDef.screenSpace`. The block faces the camera and keeps its plan anchor and its
+     * plan-unit font sizes. The whole block pivots about `bounds.center`, on one anchor shared by
+     * every line, which is what keeps a stack from splaying under tilt.
+     */
+    screenSpace?: boolean;
 }
 /** Single text line definition */
 export interface TextLineDef {

package/dist/utils/logging.d.ts

@@ -12,9 +12,12 @@ export interface Logger {
     error: Debugger;
 }
 /**
- * Creates a logger with the given namespace.
- * @param namespace - The namespace to use for the logger.
- * @returns A logger with the given namespace.
+ * Creates a logger for one namespace, nested under the root namespace.
+ *
+ * Each level prints only if you enable its namespace, for example with
+ * `debug.enable('efp:renderer:*')`.
+ * @param namespace - The namespace to nest under the root namespace.
+ * @returns A logger with four levels, all under that namespace.
  */
 export declare function createLogger(namespace: string): Logger;
 /**