@driftengine/core 4.11.1 → 4.12.0

package/CHANGELOG.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "4.12.0",
+    "date": "2026-10-10",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`npm create @driftengine` starts a game that runs: a Vite and TypeScript project with the instructions a coding agent reads, the engine's skill, and `npm run check`.",
+        "text": "`@driftengine/create` is the new package `npm create @driftengine@latest my-game` runs. It starts a Vite and TypeScript project from the `starter` example, a lit cube turning at a rate a DriftScript rule sets, or with `-- --template first-game` from the complete 3D game, and both are generated from the typechecked examples, so a new project starts as code the compiler and the examples page have already run. It asks nothing and installs nothing, because the caller is as likely to be a coding agent as a person and an agent cannot answer a prompt. A project carries an `AGENTS.md` naming its commands, the rules the compiler cannot check and what done means there; the `driftengine` skill in `.agents/skills/` and `.claude/skills/`, the folders Codex, Cursor and Claude Code read skills from; and `npm run check`, which typechecks, runs the tests in Node and looks at the game. `-- --skill` adds the skill to a project that already exists. The engine is pinned at the command's own version and DriftScript exactly at the engine's pin. Vitest is 5 rather than the 4.1 this repository runs: Vitest 4.1 cannot be installed into a project with no lockfile by npm 10.9, the npm Node 22 ships, whose resolver stops on its peer list. `npm run cleanroom` now starts both templates from the packed tarballs and typechecks, tests and builds them, and with `--look` photographs them; both pass."
+      },
+      {
+        "kind": "added",
+        "short": "`npm run look` photographs a game on WebGPU and on WebGL2 on the machine's own GPU, and fails on a console error or warning, an empty canvas, or a backend that fell back.",
+        "text": "`@driftengine/core/scripts/look.mjs` is the engine's capture instruments as one verdict, for whoever cannot see the screen. `look({ url })` opens the page once with `?backend=webgpu` and once with `?backend=webgl2`, declines the boot badge, and writes what a player sees on each, the canvas alone beside it, and `look.json` with every console line. It says which backend actually drew, read from the context the page's canvas asked for rather than from the address, and how much of the canvas changed between two frames. It fails on a console error or a warning, on a canvas that is 99.5% one colour, measured with the page's own interface hidden so a readout over an empty canvas does not pass, and on a backend asked for and not used. With no hardware GPU it refuses rather than trust a software rasteriser. Against the starter it reported both backends drawing; against a page clearing its canvas under a text readout it reported nothing drew on either, and against a page with no canvas that no renderer started. A started project runs it as `npm run look`, and `-- --headed` opens a real window where a headless browser cannot reach the GPU."
+      },
+      {
+        "kind": "added",
+        "short": "The `driftengine` skill teaches a coding agent the engine at the version a project installed: `npx skills add drftrun/driftengine`, or `--skill` in a project.",
+        "text": "`skills/driftengine/` is an agent skill in the Agent Skills format: when the engine fits and when it does not, how to start and check a project, the shape of a program, the rules the compiler cannot check, the traps that look like engine faults, and where to read further. Its code is regions of the typechecked examples, rewritten from them by `npm run create:templates`, and its three references, every manual page, every example and every package, are generated from the repository with addresses at the installed version's tag, so a page added to the manual reaches the skill on the next run. A test fails when any of it is stale, when its frontmatter breaks the format, and when it names a type, function or option the engine's source does not declare. The manual gains a chapter, Working with a coding agent, and the installation page starts from `npm create @driftengine`."
+      },
+      {
+        "kind": "changed",
+        "short": "The capture tools look for Chrome or Edge on Windows and macOS as well as Linux, and stop the browser they start on Windows too.",
+        "text": "`browser.mjs` knew only Chrome's Linux and macOS paths and stopped a browser by signalling its process group, which Windows does not have, so neither the capture tools nor `look` could run there. `browserCandidates(platform, env)` lists Chrome, Chromium and Edge where each system installs them: under both Program Files and the per-user folder on Windows, where Edge is always present, and under `/Applications` and `~/Applications` on macOS. On Windows the browser's whole tree is stopped with `taskkill /T`. `look` uses each system's own graphics path through ANGLE: Vulkan on Linux, Metal on macOS, Direct3D 11 on Windows. Run on Linux only so far; on Windows and macOS the first run is a measurement still owed, and `look` prints the GPU it found on its second line."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.layers` picks each layer from arrays materials share, and gives each layer its own tint, ranges, normal strength, specular and repeats down.",
+        "text": "A layered material read layer i from arrays of its own, so a texture worn by many materials in many tints was baked once per material with the tint in its pixels: in the case reported, about 1 GB of arrays for 140 MB of textures. `arrayLayers` picks which layer of the albedo, normal and ORM arrays each layer reads, so materials share one array of each kind; `extrasAt` says where a material's own maps beyond its layers start, a mask and a mesh normal among them, which just past the layers no longer is once arrays are shared. `looks` gives each layer a `tint`, linear and allowed above 1, the `roughness` and `metalness` ranges its ORM's channels are spread over, a `normalStrength` its normal map's slopes are scaled by, and a `specular`, blended as the colours are, that every highlight, reflection and area light reads in place of the vertices'; and a layer's repeat may be a pair, across and down apart. They are a lit switch of their own, `LAYER_LOOKS`, fifteen fragment uniform vectors on WebGL2, off until a material names one, and a layered material that names none draws as before. On `demo/dev/layerLooks.html` layers picked from shared arrays draw the same picture as the same layers in arrays of their own, white tinted draws the same as the coloured texture, a strength of 0 draws the same as a flat map while 3 bands the surface harder than 1, roughness spread over 0 to 0.1 against 0.9 to 1 moved 13.9% of the frame, a layer's specular of 0 took the highlight off, and a repeat of `[4, 4]` drew the same as `4` while `[4, 1]` stretched the layer, identically on both backends. `SurfaceLayers` and `SurfaceLayerLook` are exported for consumers that build them."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceLayers.meshOcclusion` darkens a layered surface's colour or its ambient light by an occlusion read at the mesh's own coordinates, over a range.",
+        "text": "A cliff blended from layers repeating dozens of times across it lost the shading of its own large shape, which only a map at the mesh's coordinates holds. `meshOcclusion` reads the red of the ORM array's layer after the material's mask and added mask, at the mesh's coordinates as `meshNormal` reads its normal, spreads it over a `range`, and darkens the surface by `mix(1, occlusion, strength)`. A number is the strength and darkens the blended colour, and so every light on it; `{ into: 'ambient' }` darkens the ambient light alone, sky, ground and probe, as an ambient occlusion does, leaving the sun and the lamps as they were. Absent or 0, nothing is read. On `demo/dev/layerLooks.html` a wall under an occlusion ramp darkened from black at its left edge to untouched at its right, 35.9% of the frame against the same wall without it; lit only by its ambient, the two targets drew the same picture, and with a sun on it the ambient target kept the sun's share; a range of 0.5 to 1 left the edge half dark. The same on both backends."
+      }
+    ]
+  },
   {
     "version": "4.11.1",
     "date": "2026-10-10",

package/README.md

@@ -6,7 +6,7 @@ WebGL2 everywhere else, behind one API, and carries the fixed-step loop, the ren
 input, the scene graph, geometry, text and the whole of `@driftengine/physics`, which it re-exports.
 Everything else is a separate package a game adds when it reaches for it.
 
-**Cost: 904.6 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 910.1 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -229,6 +229,8 @@ export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 export type { SurfaceProjection } from './render/surfaceProjection.ts';
+export type { SurfaceLayers } from './render/surfaceLayers.ts';
+export type { SurfaceLayerLook } from './render/surfaceLayerLooks.ts';
 export { compressedFormatName, isCompressedSource, levelBytes, uploadsCompressed, } from './render/compressedSource.ts';
 export type { BlockFormat, CompressedTextureFormat, CompressedTextureSource, SurfaceSource, } from './render/compressedSource.ts';
 export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.ts';

package/dist/render/backend/webgl2/renderer.d.ts

@@ -1290,9 +1290,14 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly transmission;
     /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
     private readonly layerFloats;
+    /** `uLayerLooks`, the current material's layer picks and looks packed. See `surfaceLayerLooks.ts`. */
+    private readonly lookFloats;
     /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
     private layersRoom;
     private warnedLayersRoom;
+    /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
+    private looksRoom;
+    private warnedLooksRoom;
     private warnedLayersModelMap;
     private warnedLayersTriplanar;
     private warnedOverlayRoom;
@@ -2165,9 +2170,19 @@ export declare class WebGL2Renderer implements RendererApi {
      * no room for their two vectors each leave one layer, the last two said once each.
      */
     private layersOf;
+    /**
+     * Whether a layered material's picks and looks are drawn: asked for, and room for their fifteen
+     * vectors beside the layers' four. Refused, the layers are drawn reading layer `i` of their arrays
+     * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
+     * the sentence names the way out.
+     */
+    private looksFit;
     /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
     private warnLayersTriplanar;
-    /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
+    /**
+     * Whether the lit shader with `feature` compiled in, and `beside` with it where a switch means
+     * nothing alone, fits this GPU's fragment uniform vectors.
+     */
     private switchFits;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.

package/dist/render/backend/webgl2/renderer.js

@@ -41,6 +41,7 @@ import { resolveTransmission } from '../../transmission.js';
 import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
 import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
+import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
@@ -963,9 +964,14 @@ export class WebGL2Renderer {
     transmission = new Float32Array([-1, -1, -1, 0]);
     /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
     layerFloats = new Float32Array(LAYER_FLOATS);
+    /** `uLayerLooks`, the current material's layer picks and looks packed. See `surfaceLayerLooks.ts`. */
+    lookFloats = new Float32Array(LOOK_FLOATS);
     /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
     layersRoom = null;
     warnedLayersRoom = false;
+    /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
+    looksRoom = null;
+    warnedLooksRoom = false;
     warnedLayersModelMap = false;
     warnedLayersTriplanar = false;
     warnedOverlayRoom = false;
@@ -3267,6 +3273,10 @@ export class WebGL2Renderer {
         if (layers !== null)
             this.askLit('LAYERED');
         gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+        packLayerLooks(layers, this.lookFloats);
+        if (this.looksFit(layers))
+            this.askLit('LAYER_LOOKS');
+        gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
         gl.uniform1i(u['uModelMap'] ?? null, MODEL_MAP_TEXTURE_UNIT);
         packModel(material?.model ?? null, modelMap !== null, this.modelParams, material?.physicalSpecular === true);
         /* The first physical highlight asked for is when the lit programs start carrying one. */
@@ -3539,6 +3549,27 @@ export class WebGL2Renderer {
         }
         return null;
     }
+    /**
+     * Whether a layered material's picks and looks are drawn: asked for, and room for their fifteen
+     * vectors beside the layers' four. Refused, the layers are drawn reading layer `i` of their arrays
+     * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
+     * the sentence names the way out.
+     */
+    looksFit(layers) {
+        if (!asksLayerLooks(layers))
+            return false;
+        this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
+        if (this.looksRoom)
+            return true;
+        if (!this.warnedLooksRoom) {
+            this.warnedLooksRoom = true;
+            console.warn("Renderer: a layered material's picks and looks are refused on this device. They take " +
+                'fifteen fragment uniform vectors the lit shader does not have, so its layers read layer ' +
+                'i of its arrays, untinted, at one repeat each. A lower `maxLights` makes the room, or ' +
+                'WebGPU has it.');
+        }
+        return false;
+    }
     /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
     warnLayersTriplanar() {
         if (this.warnedLayersTriplanar)
@@ -3547,9 +3578,14 @@ export class WebGL2Renderer {
         console.warn("Renderer: a layered material's triplanar projection is laid on the horizontal plane: every " +
             "layer's maps on three planes would be three times the reads. See `SurfaceMaterial.layers`.");
     }
-    /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
-    switchFits(feature) {
+    /**
+     * Whether the lit shader with `feature` compiled in, and `beside` with it where a switch means
+     * nothing alone, fits this GPU's fragment uniform vectors.
+     */
+    switchFits(feature, beside) {
         const asIf = { [feature]: true };
+        if (beside !== undefined)
+            asIf[beside] = true;
         return (countUniformVectors(this.flatFragAt(this.lightBudget, asIf)) <= this.fragmentVectorLimit());
     }
     /**
@@ -5495,6 +5531,7 @@ export class WebGL2Renderer {
             worldUvs: asIf.WORLD_UVS ?? this.litOn.WORLD_UVS,
             movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
             layered: asIf.LAYERED ?? this.litOn.LAYERED,
+            layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
             maxLights: budget.maxLights,
             maxAreaLights: budget.maxAreaLights,
         });
@@ -7351,6 +7388,7 @@ export class WebGL2Renderer {
         resolveTransmission(null, this.transmission);
         /* Nor layers: one layer until a material asks for more. */
         this.layerFloats.fill(0);
+        this.lookFloats.fill(0);
         this.overlayMaps = null;
         this.overlayTexture = null;
         /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -7494,6 +7532,7 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
         gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+        gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
         /* Neither refracting nor glass, which is every draw that does not say otherwise. See
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);

package/dist/render/backend/webgpu/renderer.d.ts

@@ -1189,6 +1189,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly projection;
     /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
     private readonly layerFloats;
+    /** `uLayerLooks`, the material's layer picks and looks packed by `packLayerLooks`. */
+    private readonly lookFloats;
     /**
      * `uGlassTint` as the material leaves it, its light from behind and that light's colour, which a
      * pane overwrites for its own draw and `releaseSeeThrough` puts back. See `transmission.ts`.

package/dist/render/backend/webgpu/renderer.js

@@ -67,6 +67,7 @@ import { resolveTransmission } from '../../transmission.js';
 import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
 import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
+import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
 import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
 import { REFLECTION_SURFACE_FORMAT, ReflectionSurfacePass } from './reflectionSurfacePass.js';
 import { validateClothBinding } from '../../clothBindingData.js';
@@ -2256,6 +2257,8 @@ export class WebGPURenderer {
     projection = new Float32Array(PROJECTION_FLOATS);
     /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
     layerFloats = new Float32Array(LAYER_FLOATS);
+    /** `uLayerLooks`, the material's layer picks and looks packed by `packLayerLooks`. */
+    lookFloats = new Float32Array(LOOK_FLOATS);
     /**
      * `uGlassTint` as the material leaves it, its light from behind and that light's colour, which a
      * pane overwrites for its own draw and `releaseSeeThrough` puts back. See `transmission.ts`.
@@ -2745,6 +2748,11 @@ export class WebGPURenderer {
             f.set(this.layerFloats, this.materialField('uLayers'));
             if (layers !== null)
                 this.enableLit('LAYERED');
+            /* And which layer of shared arrays each reads, with its look: layerLooks.ts. */
+            packLayerLooks(layers, this.lookFloats);
+            f.set(this.lookFloats, this.materialField('uLayerLooks'));
+            if (asksLayerLooks(layers))
+                this.enableLit('LAYER_LOOKS');
             f.set(this.modelParams, this.materialField('uModelParams'));
         });
         /*
@@ -7186,6 +7194,7 @@ export class WebGPURenderer {
         f.set(this.transmission, at('uGlassTint'));
         /* Nor layers: one layer until a material asks for more. */
         f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
+        f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
         f[at('uCutout')] = 0;
         f[at('uCutout') + 1] = 0;
         this.cutoutResolveStaged = 'hard';

package/dist/render/shaders/flat/areaLight.d.ts

@@ -7,4 +7,4 @@
  *
  * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
  */
-export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's\n * positive edge: `p` the fragment's place along the axis, `height` its height above the\n * rectangle's plane, `halfSize` the rectangle's half extent, and the door's tip `tipOut` beyond\n * the edge and `tipUp` above the plane. Points of the rectangle past the answer are hidden.\n *\n * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a\n * fragment beside the door and outside its line is hidden from all of it, and one inside the door's\n * reach is hidden from none of it.\n */\nfloat barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {\n  float tipAt = halfSize + tipOut;\n  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);\n  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;\n  return 1e9;\n}\n\n/**\n * The part of a rectangle a fragment sees past its barn doors, written into `centre` and\n * `halfSize` as the smaller rectangle that is left, or false where the doors hide all of it.\n * `doors` is the cosine of their angle from the normal and their length; a length of 0 is no doors.\n * Each axis is clipped by its own two doors, which is what makes this four projections and a min.\n */\nbool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {\n  if (doors.y <= 0.0) return true;\n  vec3 toFragment = vWorldPos - centre;\n  float height = dot(toFragment, cross(right, up));\n  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */\n  if (height <= 0.0) return true;\n  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));\n  float tipUp = doors.y * doors.x;\n  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));\n  vec2 hi = vec2(\n    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),\n    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  vec2 lo = vec2(\n    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),\n    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  if (hi.x <= lo.x || hi.y <= lo.y) return false;\n  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));\n  halfSize = 0.5 * (hi - lo);\n  return true;\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (vSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";
+export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's\n * positive edge: `p` the fragment's place along the axis, `height` its height above the\n * rectangle's plane, `halfSize` the rectangle's half extent, and the door's tip `tipOut` beyond\n * the edge and `tipUp` above the plane. Points of the rectangle past the answer are hidden.\n *\n * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a\n * fragment beside the door and outside its line is hidden from all of it, and one inside the door's\n * reach is hidden from none of it.\n */\nfloat barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {\n  float tipAt = halfSize + tipOut;\n  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);\n  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;\n  return 1e9;\n}\n\n/**\n * The part of a rectangle a fragment sees past its barn doors, written into `centre` and\n * `halfSize` as the smaller rectangle that is left, or false where the doors hide all of it.\n * `doors` is the cosine of their angle from the normal and their length; a length of 0 is no doors.\n * Each axis is clipped by its own two doors, which is what makes this four projections and a min.\n */\nbool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {\n  if (doors.y <= 0.0) return true;\n  vec3 toFragment = vWorldPos - centre;\n  float height = dot(toFragment, cross(right, up));\n  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */\n  if (height <= 0.0) return true;\n  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));\n  float tipUp = doors.y * doors.x;\n  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));\n  vec2 hi = vec2(\n    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),\n    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  vec2 lo = vec2(\n    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),\n    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  if (hi.x <= lo.x || hi.y <= lo.y) return false;\n  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));\n  halfSize = 0.5 * (hi - lo);\n  return true;\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (surfaceSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";

package/dist/render/shaders/flat/areaLight.js

@@ -123,7 +123,7 @@ void areaLightAdd(
   lampOpen += areaDiffuse;
   lampShadowed += areaDiffuse * occl * glass;
 
-  if (vSpecular > 0.0 || metal > 0.0) {
+  if (surfaceSpecular > 0.0 || metal > 0.0) {
     vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
     vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
     vec3 c2 = centre + right * halfSize.x - up * halfSize.y;

package/dist/render/shaders/flat/glassTint.d.ts

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */

package/dist/render/shaders/flat/glassTint.js

@@ -37,6 +37,7 @@ export function noLitSwitches() {
         WORLD_UVS: false,
         MOVING_SUN: false,
         LAYERED: false,
+        LAYER_LOOKS: false,
     };
 }
 /**

package/dist/render/shaders/flat/index.d.ts

@@ -140,6 +140,11 @@ export interface FlatShaderOptions {
      * True when absent. See \`layeredGlsl\`.
      */
     readonly layered?: boolean;
+    /**
+     * Whether a layered material's layers are picked from shared arrays and given looks of their own,
+     * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
+     */
+    readonly layerLooks?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

package/dist/render/shaders/flat/index.js

@@ -513,7 +513,7 @@ export function flatFrag(options) {
         /* After the reflection maps, so its switch takes the next id; main calls it. worldUv.ts. */
         worldUvGlsl(options.worldUvs ?? true),
         /* After the projection, so its switch takes the next id; the normal map below calls it. */
-        layeredGlsl(options.layered ?? true),
+        layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
         /* Where each map is read, after both of the ways it can be read otherwise. See mapReads.ts. */
         MAP_READS_GLSL,
         /* After the frame and the projection it calls, unconditional for the same reason as the

package/dist/render/shaders/flat/layerLooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which layer of the shared arrays each of a layered material's layers reads, and how each looks:
+ * `uLayerLooks`, packed by `surfaceLayerLooks.ts`, read by `layered.ts`.
+ *
+ * **Every helper is the identity where the switch is off**, written as a branch on `LAYER_LOOKS`
+ * itself because the generated WGSL carries one string for both values of an override: layer `i`
+ * reads layer `i`, the maps beyond the layers start at the layer count, a tint is white, a range is
+ * 0 to 1, a normal is as stored, a specular is the surface's own, a repeat down is the repeat
+ * across, and nothing is occluded — exactly what `layered.ts` did before this existed, which is what
+ * a layered material that asks for none of it has to keep drawing.
+ *
+ * **A lit switch, `LAYER_LOOKS`**, off until a material first asks and declared after `LAYERED`, so
+ * every switch before it keeps its id. It is only ever compiled beside `LAYERED`, whose `uLayers`
+ * it reads.
+ */
+export declare function layerLooksGlsl(on: boolean): string;

package/dist/render/shaders/flat/layerLooks.js

@@ -0,0 +1,116 @@
+/**
+ * Which layer of the shared arrays each of a layered material's layers reads, and how each looks:
+ * `uLayerLooks`, packed by `surfaceLayerLooks.ts`, read by `layered.ts`.
+ *
+ * **Every helper is the identity where the switch is off**, written as a branch on `LAYER_LOOKS`
+ * itself because the generated WGSL carries one string for both values of an override: layer `i`
+ * reads layer `i`, the maps beyond the layers start at the layer count, a tint is white, a range is
+ * 0 to 1, a normal is as stored, a specular is the surface's own, a repeat down is the repeat
+ * across, and nothing is occluded — exactly what `layered.ts` did before this existed, which is what
+ * a layered material that asks for none of it has to keep drawing.
+ *
+ * **A lit switch, `LAYER_LOOKS`**, off until a material first asks and declared after `LAYERED`, so
+ * every switch before it keeps its id. It is only ever compiled beside `LAYERED`, whose `uLayers`
+ * it reads.
+ */
+export function layerLooksGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool LAYER_LOOKS = false;  // wgsl:override
+float layerArray(int i) { return float(i); }
+float layerExtras() { return uLayers[1].y; }
+vec3 layerTint(int i) { return vec3(1.0); }
+vec2 layerRanges(int i, vec2 roughMetal) { return roughMetal; }
+vec3 layerStrengthen(int i, vec3 texel) { return texel; }
+float layerSpecular(int i, float own) { return own; }
+float layerRepeatDown(int i, float across) { return across; }
+float layerOcclusionStrength() { return 0.0; }
+bool layerOcclusionAmbient() { return false; }
+vec2 layerOcclusionRange() { return vec2(0.0, 1.0); }
+`;
+    }
+    return /* glsl */ `
+/* Whether layers are picked from shared arrays and given looks of their own: layerLooks.ts. */
+const bool LAYER_LOOKS = true;  // wgsl:override
+/*
+ * Fifteen vectors, as surfaceLayerLooks.ts packs them: the array layer each of the five reads, base
+ * first (floats 0 to 4); where the maps beyond the layers start (5), the mesh occlusion's strength
+ * (6) and whether it darkens the ambient light rather than the colour (7); then two vectors a
+ * layer, base first: its tint (x y z) and normal strength (w), then its roughness range (x to y)
+ * and metalness range (z to w); then each layer's specular, -1 for the surface's own (48 to 52), its
+ * repeat down (53 to 57), and the occlusion's range (58 to 59).
+ */
+uniform vec4 uLayerLooks[15]; // wgsl:material
+
+/* Float k of the fifteen vectors. */
+float layerLook(int k) {
+  return uLayerLooks[k / 4][k % 4];
+}
+
+/* The layer of the albedo, normal and ORM arrays a material's layer i reads. */
+float layerArray(int i) {
+  if (LAYER_LOOKS) return layerLook(i);
+  return float(i);
+}
+
+/* Where the maps beyond the layers start in each array. */
+float layerExtras() {
+  if (LAYER_LOOKS) return uLayerLooks[1].y;
+  return uLayers[1].y;
+}
+
+vec3 layerTint(int i) {
+  if (LAYER_LOOKS) return uLayerLooks[2 + i * 2].xyz;
+  return vec3(1.0);
+}
+
+/* The ORM's roughness and metalness, each spread over the layer's own range. */
+vec2 layerRanges(int i, vec2 roughMetal) {
+  if (LAYER_LOOKS) {
+    vec4 range = uLayerLooks[3 + i * 2];
+    return vec2(mix(range.x, range.y, roughMetal.x), mix(range.z, range.w, roughMetal.y));
+  }
+  return roughMetal;
+}
+
+/*
+ * A tangent-space texel bent further or less by the layer's strength: its x and y scaled, its z
+ * kept, so 0 lies flat and a strength above 1 steepens every slope the map holds. z is held above
+ * zero so a texel lying exactly flat on its surface cannot normalise to nothing at strength 0.
+ */
+vec3 layerStrengthen(int i, vec3 texel) {
+  if (LAYER_LOOKS) return normalize(vec3(texel.xy * uLayerLooks[2 + i * 2].w, max(texel.z, 1e-4)));
+  return texel;
+}
+
+/* The layer's specular, or the surface's own where it names none. */
+float layerSpecular(int i, float own) {
+  if (LAYER_LOOKS) {
+    float named = layerLook(48 + i);
+    return named < 0.0 ? own : named;
+  }
+  return own;
+}
+
+/* The layer's repeat down, which is its repeat across unless it gave two. */
+float layerRepeatDown(int i, float across) {
+  if (LAYER_LOOKS) return layerLook(53 + i);
+  return across;
+}
+
+float layerOcclusionStrength() {
+  if (LAYER_LOOKS) return uLayerLooks[1].z;
+  return 0.0;
+}
+
+bool layerOcclusionAmbient() {
+  if (LAYER_LOOKS) return uLayerLooks[1].w > 0.5;
+  return false;
+}
+
+vec2 layerOcclusionRange() {
+  if (LAYER_LOOKS) return uLayerLooks[14].zw;
+  return vec2(0.0, 1.0);
+}
+`;
+}

package/dist/render/shaders/flat/layered.d.ts

@@ -2,7 +2,8 @@
  * A material blended from layers by a mask: `SurfaceMaterial.layers`, packed into `uLayers` by
  * `surfaceLayers.ts`.
  *
- * **Layer `i` is layer `i` of the material's arrays**, each read at its own repeat of where the
+ * **Layer `i` is layer `i` of the material's arrays** — or the layer `layerLooks.ts` picks, with the
+ * tint, ranges and normal strength it gives each — each read at its own repeat of where the
  * layers are laid: the mesh's coordinates, or the world's horizontal plane where the material has a
  * projection (`worldUv.ts`). The mask's channels weigh layers 1 to 4 — red, green, blue, alpha — and
  * come from a map read where a shading model's would be, from the ORM array's layer past the layers,
@@ -21,7 +22,8 @@
  * in uniform control flow (AGENTS.md 2026-08-07), so the loop is bounded by the layer count, a
  * uniform, and never skips on a share, which is the pixel's own.
  *
- * **A lit switch, `LAYERED`**, off until a material first asks, declared last so every switch before
- * it keeps its id. Compiled out, its four vectors are not declared and its calls are constants.
+ * **A lit switch, `LAYERED`**, off until a material first asks, declared after every switch before
+ * it so each keeps its id. Compiled out, its four vectors are not declared and its calls are
+ * constants. `looks` compiles `LAYER_LOOKS` in beside it, and means nothing without it.
  */
-export declare function layeredGlsl(on: boolean): string;
+export declare function layeredGlsl(on: boolean, looks?: boolean): string;