@solidrt/3d 0.0.52 → 0.0.54

package/AGENTS.md

@@ -54,20 +54,37 @@ blendMode and pointer events like any element.
   the `castShadow` meshes (`<Mesh castShadow>`, `setCastShadow`) from an
   orthographic camera at the light's WORLD position along its world
   direction, `shadow.camera` (+-5, 0.5..500 by default) as the frustum.
-  Any directional light may cast (each map is a pass, capped by
-  MAX_LIGHTS = MAX_SHADOWS): shadow slot i is directional light i's -
-  the map's depth id binds as the target-level `uShadowMap<i>` of the
-  scene and every non-shadow view (a white texel when light i does not
-  cast), `uShadowMatrix[i]` is its view's own view-projection (the whole
-  array is one write per shadow-camera move), `uShadowCast[i]` says
-  whether it casts, `uShadowBias[i]`/`uShadowNormalBias[i]` its knobs;
-  `SHADOW_SLOTS` in glsl declares the set. Every `lit` material RECEIVES by default
+  Any directional light may cast (capped by MAX_LIGHTS = MAX_SHADOWS).
+  `shadow: { cascades: N }` (1..MAX_CASCADES = 4) replaces the box with
+  N maps fitted to slices of the SCENE camera's frustum (near ..
+  `shadow.distance`, default the camera far; the practical split; each
+  slice's bounding sphere as an ortho box along the light, its centre
+  snapped to the map's texel grid so edges do not swim; re-fitted
+  whenever the scene camera or the light moves) - a receiver samples the
+  tightest map that covers the point, fading into the next over the
+  map's outer 10% (`SHADOW_BLEND`) so the hand-over is a band, not a
+  seam; contact shadows stay sharp near the camera while the horizon
+  still has coarse ones, and pulling `distance` in sharpens all of them.
+  The box is the honest tier for a bounded scene; cascades are for a
+  scene that outgrows it, at N times the shadow fill. Every map is a
+  TILE of the scene's one shadow atlas (a `depth: "texture"` draw target,
+  a grid of cells the largest `mapSize` wide, scaled down uniformly
+  against `limits.maxTextureSize`), so N maps are ONE pass: the atlas
+  depth binds as the target-level `uShadowAtlas` of the scene and every
+  non-shadow view (a white texel when nothing casts); maps are MAP slots
+  dealt in light order, a light's cascades consecutive and tightest
+  first - `uShadowRect[j]` slot j's tile in atlas UV, `uShadowMatrix[j]`
+  its view's own view-projection (the whole array is one write per
+  shadow-camera move) - and per light i `uShadowFirst[i]`/`uShadowCount[i]`
+  name its slots (count 0 = it does not cast) with
+  `uShadowBias[i]`/`uShadowNormalBias[i]` its knobs; `SHADOW_SLOTS` in
+  glsl declares the set. Every `lit` material RECEIVES by default
   (Godot's and Three's default); `lit({ receiveShadow: false })` opts a
   material out and drops the map from its program - a material option,
   as with vertexColors/triplanar, because the material picks the program
   (Godot's `disable_receive_shadows`). The factor is `SHADOW`'s 3x3 PCF
   on each casting light's own term. `examples/shadows.tsx` (three
-  casting lights) is the shape.
+  casting lights) is the shape; `examples/cascades.tsx` the cascaded sun.
 - RETARGETED motion is native: `setTransition(node, { position:
   { duration: 400 }, ... })` makes setTransform writes TARGETS the core
   animates toward every frame (position/scale per lane, rotation along
@@ -114,9 +131,12 @@ blendMode and pointer events like any element.
   the upload), so swapping `<Mesh geometry>` reactively never accumulates
   old generations. `disposeGeometry` is the immediate explicit free.
 - Materials dedupe hard: one program + one pipeline per material CLASS
-  (unlit color, unlit map, each opaque or transparent), `depth: true` +
-  `cull: "back"`; an instance is
-  just per-entry uniforms (`uColor`) and bindings (`uMap`).
+  (a `shaderMaterialClass` per option combination for unlit, lit and
+  sprite alike: map x transparent x cull x alphaTest, lit's extras on
+  top), `depth: true` + `cull: "back"` unless the material says otherwise
+  (`cull: "none"` for double-sided geometry; lit flips the normal on back
+  faces); an instance is just per-entry uniforms (`uColor`) and bindings
+  (`uMap`).
 - The pure pieces (`math.ts`, `order.ts`, `geometry.ts`,
   `profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
   GPU-free BY DESIGN so they can be checked headless (and, for the two
@@ -151,6 +171,31 @@ elsewhere. Called once, untracked, inside the scene context. Scene
 layout, so render and display size separate - render at 2x and display
 smaller for supersampling.
 
+Filling the window: `width`/`height` are DEVICE pixels, the leaf's layout
+is LOGICAL. A `designSize` view fits the leaf to the window but never
+changes the target, so on a HiDPI display a 720-pixel scene is stretched
+across ~1100 device pixels and looks soft, and nothing warns (the
+examples' `SIZE = 720` is a verification convenience, not a sizing
+model). Render at the window's device size and lay the leaf out at its
+logical size:
+
+```tsx
+let target = createMemo(() => {
+  let { width, height } = windowSize()
+  let scale = displayScale()
+  return { w: Math.round(width * scale), h: Math.round(height * scale) }
+})
+<Scene width={target().w} height={target().h}
+       output={t => <texture src={t} width={windowSize().width}
+                             height={windowSize().height}
+                             {...useScene().scene.handlersFor(windowSize)} />}>
+```
+
+`windowSize` and `displayScale` come from `@solidrt/core`. The leaf's
+layout differs from the target, so it takes `handlersFor` (below), not
+`handlers`; `useScene()` works inside `output` because it runs in the
+scene context.
+
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
 zoomSpeed?, zoomAnchor?, rotateAnchor?, panSpeed?, viewport?, clampTarget? })`
@@ -304,8 +349,9 @@ uint16/uint32 indices by vertex count automatically.
 
 Materials:
 
-- `unlit({ color?, map? })` - straight `[r, g, b, a?]` 0..1, premultiplied
-  internally.
+- `unlit({ color?, map?, transparent?, cull?, alphaTest? })` - straight
+  `[r, g, b, a?]` 0..1, premultiplied internally; `cull` and `alphaTest`
+  as on lit (a mapped cutout casts its cutout).
 - `sprite({ color?, map?, transparent?, billboard? })` - unlit on a quad
   that turns to face the camera IN THE VERTEX STAGE (off the shared
   uCamRight/uCamUp, or uCamPos for `billboard: "fixed-y"`, which yaws
@@ -408,13 +454,18 @@ the material need that channel) and the pure functions `HEMISPHERE`
 (`hemisphere(n, sky, ground)`), `LAMBERT` (`lambert(n, l)`),
 `BLINN_SPECULAR` (`blinnSpecular(n, v, l, shininess)`), `FRESNEL`
 (`fresnel(n, v, power)`), and the shadow trio composed IN ORDER:
-`SHADOW_SLOTS` (the scene's shadow set: `uShadowMap0..N-1`,
-`uShadowMatrix[N]`, `uShadowCast[N]`, `uShadowBias[N]`,
-`uShadowNormalBias[N]`, slot i = directional light i), `SHADOW`
-(`shadow(map, coord, bias)` - one map's 3x3 PCF factor) and
-`SHADOW_LOOKUP` (`lightShadow(i, worldPos, n)` - light i's factor, 1
-when it does not cast; it hides the if-chain that picks the map, since
-GLSL ES 3.00 forbids dynamic sampler indexing). A receiving fragment
+`SHADOW_SLOTS` (the scene's shadow set: `uShadowAtlas`, per map slot
+`uShadowRect[M]`/`uShadowMatrix[M]`, per directional light
+`uShadowFirst[N]`/`uShadowCount[N]` (its slots; a cascaded light has
+several, tightest first), `uShadowBias[N]`, `uShadowNormalBias[N]`),
+`SHADOW` (`shadowPoint(coord)` - clip to map point, `shadowInside(p)` -
+does the map have it, `shadowSample(map, rect, p, bias)` - one tile's
+3x3 PCF factor, and `shadow(map, rect, coord, bias)` composing the
+three) and `SHADOW_LOOKUP`
+(`lightShadow(i, worldPos, n)` - light i's factor, 1 when it does not
+cast; it walks the light's slots and samples the first map that covers
+the point, which is the cascade select, blended into the next map over
+the outer `SHADOW_BLEND` of the map). A receiving fragment
 multiplies light i's term by `lightShadow(i, ...)`, exactly what `lit`
 composes; a non-receiving one composes none of the three and declares no
 samplers. Lights, colors and exponents are arguments, so
@@ -450,17 +501,22 @@ the directional list, Lambert diffuse, Blinn-Phong highlight when
 `specular` (0..1 strength) is set with `shininess` (default 30), the
 same `color`/`map`/`transparent` as unlit, `vertexColors: true` to
 multiply by the colored layout's aColor (so the geometry must carry it),
-and `triplanar: n` to sample `map` by world position at `n` repeats per
-world unit, blended across the three axis planes by the normal. Triplanar
+`triplanar: n` to sample `map` by world position at `n` repeats per
+world unit, blended across the three axis planes by the normal, and
+`alphaTest: t` for a cutout (a fragment whose final alpha is below `t`
+is discarded; Three's alphaTest, glTF MASK): opaque, depth-written, no
+sorting, usually with `cull: "none"` for cards. Triplanar
 is an OPTION, not the default: generators emit 0..1 UVs per face, so a
 map on a plane is a decal (UV) while a map on generated scenery wants one
 density across parts of any size (triplanar); the map must be created
 with `wrap: "repeat"`. Internally one `shaderMaterialClass` per option
-combination (map x vertexColors x triplanar x transparent), cached for
-the app's lifetime, one pipeline per vertex layout - a thousand lit
-meshes share one program. The view vector comes from the shared uCamPos;
-`uTriplanar` is declared only by the triplanar classes so the other
-classes do not warn about an inactive uniform.
+combination (map x vertexColors x triplanar x transparent x cull x
+alphaTest), cached for the app's lifetime, one pipeline per vertex layout
+- a thousand lit meshes share one program. The view vector comes from the
+shared uCamPos; `uTriplanar` and `uAlphaTest` are declared only by the
+classes that use them (the cutoff is a per-entry value, so every
+alphaTest material shares one class) so the other classes do not warn
+about an inactive uniform.
 
 ## Models
 
@@ -472,7 +528,8 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   bun and on flux): `ModelData` = `parts` (one per mesh node, its NAME
   kept, vertices in the standard layout with the node's WORLD transform
   baked in), `materials` (base color factor, `map` = index into `images`,
-  `doubleSided`, `transparent` = alphaMode BLEND), `images` (the encoded
+  `doubleSided`, `transparent` = alphaMode BLEND, `alphaMode` as written
+  and `alphaCutoff`, spec default 0.5), `images` (the encoded
   PNG/JPEG bytes, undecoded) and `bounds`. A .gltf's external files come
   through `resolve(uri)` (uri as written, still percent-encoded;
   `gltfExternalUris(bytes)` lists them so an async caller can read them
@@ -504,10 +561,10 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   "binary" }` then `createModel(parseGltf(bytes))`, see
   `examples/model.tsx`); bake anything big.
 
-Not in the subset, reported or dropped: `doubleSided` is reported and NOT
-applied (the standard materials cull back faces); vertex colors, tangents
-and further UV sets are dropped; samplers are ignored (every texture
-repeats); alphaMode MASK draws opaque; emissive/additive parts of a model
+Applied: `doubleSided` (the default material draws it with `cull:
+"none"`) and alphaMode MASK (`alphaTest: alphaCutoff`). Not in the
+subset, dropped: vertex colors, tangents and further UV sets; samplers
+are ignored (every texture repeats); emissive/additive parts of a model
 draw as their base color (a model's "glow" cards come out as dark wedges).
 The follow-ups are filed in okf/backlog/3d-model-loader.md.
 
@@ -546,7 +603,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   are opaque to the library, so any inferred box would be a guess. Supply
   `bounds` for anything pickable or transparent.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
-  [r, g, b, 0.5] })` still draws opaque; `unlit({ ..., transparent: true })`
+  [r, g, b, 0.5] })` still draws opaque, and opaque means it: the standard
+  classes write alpha 1 when not `transparent` (the scene target is
+  composited premultiplied, so a leaked texel or color alpha would punch
+  a see-through hole in an opaque draw - the source of "white cutouts"
+  on an alpha-mapped model drawn without alphaTest). A `shaderMaterial`
+  writes its own fragColor: give an opaque look alpha 1 too.
+  `unlit({ ..., transparent: true })`
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with
   `blend: "alpha"` and `depthWrite: false` (depth test stays on, so it hides
   behind opaques without occluding other translucents). The one inference:
@@ -653,7 +716,14 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   `shadow.normalBias` (world units along the receiver normal, the one to
   reach for first, ~0.02); the depth pass culls FRONT faces (Three's
   shadowSide default), so closed casters need little bias but a
-  single-sided plane casts nothing. Opting out of receiving is on the
+  back-culling plane casts only from its back. The shadow side follows
+  the material's `cull` (Three's shadowSide rule, Godot's shadow pass):
+  a `cull: "none"` foliage card or pane casts from both faces, and a
+  UV-mapped `alphaTest` material casts its cutout (leaves, not
+  rectangles), through the `Material.shadow` variant the standard
+  classes carry (a `shaderMaterial` gets the cull side from its `cull`
+  and supplies its own cutout variant as the `shadow` instance option).
+  Opting out of receiving is on the
   MATERIAL here (`receiveShadow: false`), not the object (Three's
   `mesh.receiveShadow`) - Godot's split, and URP's - and instanced
   meshes never cast (the depth override cannot know their records) - the
@@ -730,12 +800,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
-- Picking is the VOLUME tier: a hit means the ray crossed the mesh's
-  transformed bounding box, not its surface. Never present `point` as a
-  surface point (it is the box-entry point), and never add a
-  triangle-accurate path in JS - per-triangle rays at mesh scale are
-  interpreter-hostile; that tier is core work (BVH descent per the
-  differentiators ladder).
+- Picking is triangle-accurate for ordinary meshes (`point` is a surface
+  point, hits carry `face`/`uv`/`normal`) but box-only for instanced
+  meshes: there `point` is the entry point of the population `bounds`
+  box, and `face`/`uv`/`normal` are absent. Never present an instanced
+  hit as a surface hit. Both tiers run in the spatial core (Rust); never
+  add a per-triangle path in JS - rays at mesh scale are
+  interpreter-hostile, and the core already does it.
 - `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
   LAYOUT frame (every ancestor transform and design-size fit is already
   undone by the element hit test). `handlers` therefore assumes leaf

package/examples/README.md

@@ -50,6 +50,14 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   ground and the casters receiving through plain `lit` (the default);
   each shadow camera follows its light's world matrix, each map is
   rendered by an internal view.
+- `cascades.tsx` - cascaded shadow maps: a sun with `shadow: { cascades:
+  3 }` over a field of pillars to the horizon under a slowly flying
+  camera; three maps fitted to slices of the camera frustum, sampled
+  tightest-first, so the shadows are sharp at the camera's feet and still
+  there at the far edge of the ground. A click cycles 1..4 cascades (1 is
+  the plain box widened to cover the field: one map's texels spread over
+  it, blocky everywhere) and the `cascades`/`fly` debug commands set the
+  count and the shadow distance and park the flight.
 - `model.tsx` - a model from a file: `model.glb` (a small rover with
   nested node transforms, a mirrored node, a textured material, a
   transparent dome and a mesh without normals) parsed with `parseGltf`

package/examples/cascades.tsx

@@ -0,0 +1,121 @@
+// Cascaded shadow maps: a field of pillars to the horizon under a slowly
+// flying camera, lit by one casting sun with `shadow: { cascades: 3 }`.
+// A box shadow (`shadow.camera`) is one map over a fixed area: widened to
+// cover this field its 1024 texels spread over 260 world units and every
+// shadow is blocky, kept tight the far field is unshadowed. With cascades
+// the light renders one map per slice of the SCENE camera's frustum
+// (near..far, tightest first), re-fitted every time the camera or the
+// light moves, and a receiver samples the tightest map that has the
+// point: sharp contact shadows at the camera's feet, coarser ones toward
+// the horizon, at the cost of N times the shadow fill. Every map is a
+// tile of the scene's one atlas, so the pass count is unchanged.
+//
+// A click cycles 1..4 cascades (1 = the box, widened over the field).
+// The `cascades` debug command sets the count and the shadow distance
+// (`{ count, distance }`; the range the cascades split, the camera's far
+// by default - pulling it in sharpens every cascade) and `fly` parks the
+// flight (`{ t: seconds }`), so a capture repeats.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { box, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
+import type { Geometry, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+const FIELD = 260
+const FAR = 200
+// The flight: a circle over the field, looking ahead along it.
+const RADIUS = 50
+const HEIGHT = 5
+const PERIOD = 90
+
+let [cascades, setCascades] = createSignal(3)
+let [distance, setDistance] = createSignal<number | null>(null)
+// The flight clock, in seconds; `parked` holds it.
+let [time, setTime] = createSignal(0)
+let parked: number | null = null
+
+registerDebug("cascades", (args?: Record<string, unknown>) => {
+  if (typeof args?.count === "number") setCascades(args.count)
+  if (typeof args?.distance === "number" || args?.distance === null) setDistance(args.distance)
+  return { cascades: cascades(), distance: distance() }
+})
+registerDebug("fly", (args?: Record<string, unknown>) => {
+  if (typeof args?.t === "number") {
+    parked = args.t
+    setTime(args.t)
+  } else if (args?.t === null) {
+    parked = null
+  }
+  return { t: time(), parked: parked !== null }
+})
+
+// A grid of pillars with a sphere on every third one, heights varying so
+// the shadows differ in length; one geometry per height, shared.
+let pillars: { position: Vec3; height: number; ball: boolean }[] = []
+let step = 16
+for (let i = -7; i <= 7; i++) {
+  for (let j = -7; j <= 7; j++) {
+    let h = 2 + ((i * 7 + j * 3 + 100) % 5)
+    pillars.push({ position: [i * step + (j % 2) * 4, h / 2, j * step + (i % 2) * 5], height: h, ball: (i + j) % 3 === 0 })
+  }
+}
+let boxes = new Map<number, Geometry>()
+let pillar = (height: number): Geometry => {
+  let g = boxes.get(height)
+  if (g === undefined) boxes.set(height, (g = box({ width: 1.2, height, depth: 1.2 })))
+  return g
+}
+let orb = sphere({ radius: 0.9 })
+
+function App() {
+  onFrame(tick => {
+    if (parked === null) setTime(tick / 1000)
+  })
+  let eye = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2
+    return [Math.sin(a) * RADIUS, HEIGHT, Math.cos(a) * RADIUS]
+  }
+  let ahead = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2 + 0.5
+    return [Math.sin(a) * RADIUS, 1.5, Math.cos(a) * RADIUS]
+  }
+
+  let ground = lit({ color: [0.5, 0.55, 0.45] })
+  let stone = lit({ color: [0.75, 0.7, 0.62] })
+  let ball = lit({ color: [0.85, 0.35, 0.3], specular: 0.4, shininess: 30 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="cascades">
+          <PerspectiveCamera fov={50} near={0.5} far={FAR} position={eye()} lookAt={ahead()} />
+          <HemisphereLight sky={[0.5, 0.58, 0.7]} ground={[0.25, 0.22, 0.18]} />
+          <DirectionalLight
+            color={[1, 0.95, 0.85]}
+            intensity={0.9}
+            position={[40, 90, 30]}
+            direction={[-1, -0.55, -0.4]}
+            castShadow
+            shadow={{
+              mapSize: 1024,
+              normalBias: 0.08,
+              cascades: cascades(),
+              distance: distance(),
+              // The box tier's frustum, when cascades is 1: the whole field.
+              camera: { left: -FIELD / 2, right: FIELD / 2, top: FIELD / 2, bottom: -FIELD / 2, near: 1, far: 400 },
+            }}
+          />
+          <Mesh geometry={plane({ width: FIELD, height: FIELD })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {pillars.map(p => (
+            <>
+              <Mesh geometry={pillar(p.height)} material={stone} position={p.position} castShadow />
+              {p.ball ? <Mesh geometry={orb} material={ball} position={[p.position[0], p.height + 0.9, p.position[2]]} castShadow /> : null}
+            </>
+          ))}
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -13,12 +13,12 @@
   },
   "files": [
     "src/",
+    "tools/",
     "examples/",
-    "demos/",
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.1",
-    "@solidrt/core": "0.0.52"
+    "@solidjs/signals": "2.0.0-rc.3",
+    "@solidrt/core": "0.0.54"
   }
 }

package/src/components.tsx

@@ -379,8 +379,8 @@ export type DirectionalLightProps = TransformProps & {
    * each is a pass). Its shadow camera sits at the light's WORLD
    * position, so give a casting light a `position` above the scene. */
   castShadow?: boolean
-  /** Shadow-map options (mapSize, bias, normalBias, camera frustum),
-   * merged key by key. */
+  /** Shadow-map options (mapSize, bias, normalBias, camera frustum,
+   * cascades, distance), merged key by key. */
   shadow?: ShadowOptions
   ref?: (light: DirectionalLightNode) => void
 }

package/src/glsl.ts

@@ -23,6 +23,15 @@ import { glsl } from "@solidrt/core/gpu"
  * the app (see okf/backlog/app-runtime-config.md). */
 export const MAX_LIGHTS = 4
 
+/** The most cascades one casting light splits its shadow into
+ * (`shadow.cascades`, 1..MAX_CASCADES). */
+export const MAX_CASCADES = 4
+
+/** The shadow-map slot count of the scene's shadow set: every casting
+ * light owns `shadow.cascades` consecutive slots (one per map), so this
+ * bounds `uShadowRect`/`uShadowMatrix`. */
+export const MAX_SHADOW_MAPS = MAX_LIGHTS * MAX_CASCADES
+
 /**
  * The standard lit vertex stage: clip position via uViewProj * uModel,
  * with world position, world normal (via `mat3(uNormal)`, correct under
@@ -119,74 +128,120 @@ export const FRESNEL = glsl`
 `
 
 /**
- * The scene's shadow set as a receiving program declares it, one slot per
- * directional light index: `uShadowMap0..N-1` (each light's depth map, a
- * white texel when it does not cast), `uShadowMatrix[N]` (its light-space
- * viewProj), `uShadowCast[N]` (1 when light i casts), `uShadowBias[N]` and
+ * The scene's shadow set as a receiving program declares it: ONE
+ * `uShadowAtlas` (every casting light's depth map is a tile of it, so N
+ * maps render as one pass; a white texel when nothing casts), a MAP slot
+ * set of `MAX_SHADOW_MAPS` - `uShadowRect[M]` (map slot j's tile as x, y,
+ * width, height in atlas 0..1 UV) and `uShadowMatrix[M]` (its light-space
+ * viewProj) - and, per directional light index, `uShadowFirst[N]` /
+ * `uShadowCount[N]` (light i's maps are slots `first .. first + count - 1`;
+ * count 0 = it does not cast; a box light has one map, a cascaded light
+ * `shadow.cascades` of them, tightest first), `uShadowBias[N]` and
  * `uShadowNormalBias[N]`. The scene binds and writes all of it on every
  * target a receiving material can draw into; a custom material composes
  * this, then SHADOW, then SHADOW_LOOKUP (in that order) and multiplies
- * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape.
- * A material that does not receive composes none of it, so it declares
- * no samplers for nothing.
+ * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape. A
+ * material that does not receive composes none of it, so it declares no
+ * sampler for nothing.
  */
 export const SHADOW_SLOTS = glsl`
-  ${Array.from({ length: MAX_LIGHTS }, (_, i) => `uniform sampler2D uShadowMap${i};`).join("\n  ")}
-  uniform mat4 uShadowMatrix[${MAX_LIGHTS}];
-  uniform int uShadowCast[${MAX_LIGHTS}];
+  uniform sampler2D uShadowAtlas;
+  uniform vec4 uShadowRect[${MAX_SHADOW_MAPS}];
+  uniform mat4 uShadowMatrix[${MAX_SHADOW_MAPS}];
+  uniform int uShadowFirst[${MAX_LIGHTS}];
+  uniform int uShadowCount[${MAX_LIGHTS}];
   uniform float uShadowBias[${MAX_LIGHTS}];
   uniform float uShadowNormalBias[${MAX_LIGHTS}];
 `
 
 /**
- * `float shadow(sampler2D map, vec4 coord, float bias)` - the directional
- * shadow factor (1 lit, 0 shadowed) for a world point carried into a
- * casting light's clip space by its `uShadowMatrix[i]`:
- * `shadow(uShadowMap0, uShadowMatrix[0] * vec4(vWorldPos, 1.0), uShadowBias[0])`.
- * Perspective divide, 0..1 remap, out-of-frustum returns 1 (lit), then a
- * 3x3 PCF over texel neighbours comparing the map's `.r` (a stage-1 depth
- * texture samples nearest, so the softness is this loop, not the sampler).
- * `bias` is subtracted from the point's depth against acne; SHADOW_LOOKUP
- * also offsets the point along its normal by `uShadowNormalBias[i]`
- * before the transform.
+ * The shadow lookup in three steps plus their composition, one map at a
+ * time. `vec3 shadowPoint(vec4 coord)` takes a world point carried into a
+ * casting light's clip space by that map's `uShadowMatrix[j]` to its map
+ * point: xy in 0..1 across the map, z the depth to compare. `bool
+ * shadowInside(vec3 p)` is whether the map has it at all (xy in 0..1, z
+ * not past the far plane) - the cascade select. `float shadowSample(
+ * sampler2D map, vec4 rect, vec3 p, float bias)` is the factor (1 lit, 0
+ * shadowed) of a point the map has: a 3x3 PCF over texel neighbours in
+ * the map's tile `rect` (x, y, width, height in `map`'s 0..1 UV;
+ * `vec4(0, 0, 1, 1)` is a whole map) comparing the map's `.r` (a stage-1
+ * depth texture samples nearest, so the softness is this loop, not the
+ * sampler); every tap is clamped to the tile inset by half a texel, so
+ * no tap reads a neighbouring map's tile; `bias` is subtracted from the
+ * point's depth against acne. `float shadow(sampler2D map, vec4 rect,
+ * vec4 coord, float bias)` composes the three: 1 (lit) outside the map,
+ * else the sample -
+ * `shadow(uShadowAtlas, uShadowRect[0], uShadowMatrix[0] * vec4(vWorldPos, 1.0), uShadowBias[0])`.
+ * SHADOW_LOOKUP uses the steps, so it projects each map once.
  */
 export const SHADOW = glsl`
-  float shadow(sampler2D map, vec4 coord, float bias) {
-    vec3 p = coord.xyz / coord.w * 0.5 + 0.5;
-    if (p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0 || p.z > 1.0) return 1.0;
+  vec3 shadowPoint(vec4 coord) {
+    return coord.xyz / coord.w * 0.5 + 0.5;
+  }
+
+  bool shadowInside(vec3 p) {
+    return all(greaterThanEqual(p.xy, vec2(0.0))) && all(lessThanEqual(p, vec3(1.0)));
+  }
+
+  float shadowSample(sampler2D map, vec4 rect, vec3 p, float bias) {
     vec2 texel = 1.0 / vec2(textureSize(map, 0));
+    vec2 lo = rect.xy + 0.5 * texel;
+    vec2 hi = rect.xy + rect.zw - 0.5 * texel;
+    vec2 base = rect.xy + p.xy * rect.zw;
     float lit = 0.0;
     for (int y = -1; y <= 1; y++) {
       for (int x = -1; x <= 1; x++) {
-        float d = texture(map, p.xy + vec2(float(x), float(y)) * texel).r;
+        float d = texture(map, clamp(base + vec2(float(x), float(y)) * texel, lo, hi)).r;
         lit += p.z - bias <= d ? 1.0 : 0.0;
       }
     }
     return lit / 9.0;
   }
+
+  float shadow(sampler2D map, vec4 rect, vec4 coord, float bias) {
+    vec3 p = shadowPoint(coord);
+    return shadowInside(p) ? shadowSample(map, rect, p, bias) : 1.0;
+  }
 `
 
 /**
  * The step from a light index to its shadow factor, over SHADOW_SLOTS and
- * SHADOW (compose both first). `float shadowAt(int i, vec4 coord, float
- * bias)` picks light i's map - an if-chain over the slots, because GLSL
- * ES 3.00 only indexes a sampler array by a constant - and samples it
- * with `shadow`. `float lightShadow(int i, vec3 worldPos, vec3 n)` is
- * the one to call per light: 1 for a light that does not cast, else the
- * factor for `worldPos` pushed along its normal `n` by
- * `uShadowNormalBias[i]` (the acne knob to reach for first) and carried
- * through `uShadowMatrix[i]` with `uShadowBias[i]`. Position and normal
- * are arguments, so no varying name is pinned and a custom vertex stage
- * composes freely.
+ * SHADOW (compose both first). `float lightShadow(int i, vec3 worldPos,
+ * vec3 n)` is the one to call per light: 1 for a light that does not
+ * cast, else the factor for `worldPos` pushed along its normal `n` by
+ * `uShadowNormalBias[i]` (the acne knob to reach for first), looked up in
+ * the FIRST of light i's maps that has the point (a box light has one; a
+ * cascaded light's maps come tightest first, so the sharpest cascade
+ * that has the point wins and a point past the last is lit) with that
+ * map's `uShadowMatrix[j]`, its tile and `uShadowBias[i]`. Inside the
+ * outer SHADOW_BLEND of a map (in map 0..1 units, so 0.1 is its outer
+ * 10% on each side) the factor fades into the next cascade's, so the
+ * hand-over is a band and not a seam; the last map, a box light's only
+ * one, and any rim the next cascade does not reach (the near side, at
+ * the camera's feet) have no band. Position and normal are arguments, so
+ * no varying name is pinned and a custom vertex stage composes freely.
  */
 export const SHADOW_LOOKUP = glsl`
-  float shadowAt(int i, vec4 coord, float bias) {
-    ${Array.from({ length: MAX_LIGHTS }, (_, i) => `if (i == ${i}) return shadow(uShadowMap${i}, coord, bias);`).join("\n    ")}
-    return 1.0;
-  }
+  const float SHADOW_BLEND = 0.1;
 
   float lightShadow(int i, vec3 worldPos, vec3 n) {
-    if (uShadowCast[i] != 1) return 1.0;
-    return shadowAt(i, uShadowMatrix[i] * vec4(worldPos + n * uShadowNormalBias[i], 1.0), uShadowBias[i]);
+    int count = uShadowCount[i];
+    if (count == 0) return 1.0;
+    vec4 w = vec4(worldPos + n * uShadowNormalBias[i], 1.0);
+    float bias = uShadowBias[i];
+    int first = uShadowFirst[i];
+    int last = first + count - 1;
+    for (int j = first; j <= last; j++) {
+      vec3 p = shadowPoint(uShadowMatrix[j] * w);
+      if (!shadowInside(p)) continue;
+      float s = shadowSample(uShadowAtlas, uShadowRect[j], p, bias);
+      if (j == last) return s;
+      float edge = min(min(p.x, 1.0 - p.x), min(p.y, 1.0 - p.y));
+      if (edge >= SHADOW_BLEND) return s;
+      vec3 q = shadowPoint(uShadowMatrix[j + 1] * w);
+      if (!shadowInside(q)) return s;
+      return mix(shadowSample(uShadowAtlas, uShadowRect[j + 1], q, bias), s, edge / SHADOW_BLEND);
+    }
+    return 1.0;
   }
 `