@driftengine/core 4.11.0 → 4.12.0

package/CHANGELOG.json

@@ -1,4 +1,76 @@
 [
+  {
+    "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",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.layers` takes its mask from the ORM array or the vertex colour, sums layers, places them by the world, lays one by facing up, and lays a normal under them.",
+        "text": "`layers` covers more of the ways a layered surface is blended. `mask: 'orm'` reads the mask from the ORM array's layer past the material's layers, which leaves the model's slot to a lightmap's page, so a lightmapped surface blends its layers; `mask: 'vertex'` takes the weights from the vertex colour, which then tints nothing. `blend: 'sum'` mixes the base toward each layer times its weight, by the weights' sum held to 1, besides laying each over the ones before it. Under a `projection` the layers are placed by the world, each at its own repeats a metre, and `addMask` adds a mask placed the same way to one layer's weight. `facing` weighs one layer by how much the surface faces up, and `meshNormal` lays a normal map read at the mesh's own coordinates under the layers' blended normal. A triplanar projection lays layers on the horizontal plane, and says so once. On `demo/dev/layerFamilies.html` a mask carried by the ORM array draws exactly as the same mask as a map, keeps its layers under a lightmap's page, and every mode draws the same on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.transmissionColor` names the colour light through a thin surface takes, where it was always the surface's own.",
+        "text": "`transmissionColor`, linear, is the colour the light from behind a thin surface (`diffuseTransmission`) takes through it, in place of the surface's own colour: a printed banner glowing a flat red behind its print rather than lit through in the print's colours. Absent, the surface's colour, as before. It rides the glass tint's colour lanes, which no opaque material reads, and a pane drawn between two draws of the material puts it back. On `demo/dev/thinLight.html?color=0,0.4,1` a red banner lit from behind went from 163, 24, 19 to 16, 74, 171 under the sun with no red let through, the same to the pixel on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`setAmbientOcclusionFade(distance, radius)` fades ambient occlusion out with distance, so a sky dome or a far range is not shaded in rings.",
+        "text": "Ambient occlusion is whole up to `distance` metres from the eye and gone `radius` metres past it, held until changed; a negative distance, the default, fades nothing. Far off, the depth buffer's steps are metres apart and the estimate shaded them in bands across a sky dome or a mountain range; past the fade those pixels are left open and skip the estimate's walk. Bound in DriftScript as `drift/render`'s `occlusionFade`. On `demo/dev/aoFade.html` a ridge 3 km off went from 66,267 banded pixels to none, while the feet of the near boxes darkened exactly as before, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "A lightmapped instance fades by `setDitherOpacity` too: its opacity rides its page region in sixty-fourths, where it had none.",
+        "text": "A lightmapped batch carries its page regions in the lane `MeshInstances.alphas` would take, so its instances could not fade. Their opacity now travels as whole steps added to the region's U offset, 64 of them, the screen door's own resolution, and the vertex stage takes them back off. An opaque instance's region is written to the bit as before; a fading one's offset keeps 16 bits of fraction, a sixteenth of a texel on a 4,096 page. On `demo/dev/lightmap.html?mode=tiles&fade=0.5` the faded tiles keep 50.0% of their pixels, each lit exactly as unfaded, and nothing else changes, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`prepareMesh` and `prepareInstanced` compile a draw's pipelines in its material before its first frame, so a scene drawn under `pipelineCompile: 'skip'` shows whole.",
+        "text": "`prepareMesh(mesh, material)` and `prepareInstanced(batch, material)` compile, off the main thread, every pipeline a draw of that mesh or batch in that material takes that making it did not: a two-sided, cut-out or surface-model variant, a skin's halves under the screen-space blur, and the material's lit switches; `{ translucent: true }` adds the blended ones. `ready()` resolves once they have. Under `pipelineCompile: 'skip'` a draw whose pipeline is new is left out until it lands, so a figure brought on screen came without its skin and hair for a few frames; prepared, it is drawn whole in its first frame. On WebGPU a prepared key is the one the draw asks for, worked out by the same function; on WebGL2 a surface model's programs are what a draw can wait for, and are what it prepares."
+      },
+      {
+        "kind": "added",
+        "short": "`holdSplash(promise, { capMs })` keeps the engine's badge up until the game's own first screen has loaded, under a cap of its own.",
+        "text": "The badge left three seconds after the first frame, twenty at most, so a game whose first screen loads for longer was seen loading. `holdSplash` keeps it up until the promise settles, either way, as well as until the first frame; frames run behind it while the game loads, since a load may need them, and are held once it has settled for what is left of the minimum. `capMs` is the game's ceiling in place of the engine's twenty seconds, the longest of several holds, and the call answers whether there was a badge to hold. On `demo/dev/splashHold.html` a load settling at 6.2 s took the badge down at 6.7 s with 361 frames run under it, a rejected load the same, and an 8-second cap at 8.4 s."
+      }
+    ]
+  },
   {
     "version": "4.11.0",
     "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: 898.2 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

@@ -155,7 +155,7 @@ export { BLOOM_LEVELS } from './render/bloomChain.ts';
 export type { BloomResponse } from './render/bloomChain.ts';
 export { probeDevice } from './render/backend/probe.ts';
 export type { ProbeVerdict } from './render/backend/probe.ts';
-export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
+export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, PrepareOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
 export type { ClothBindingData } from './render/clothBindingData.ts';
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.ts';
 export type { AnisotropicModel, EyeModel, HairModel, LightmapModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.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';
@@ -344,7 +346,7 @@ export type { TouchControlsOptions } from './input/touchControls.ts';
 export { pixelCursor } from './ui/pixelCursor.ts';
 export { fullscreenWanted, requestFullscreenOnGesture } from './ui/fullscreen.ts';
 export type { FullscreenConditions } from './ui/fullscreen.ts';
-export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.ts';
+export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, holdSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.ts';
 export type { MountedSplash, SplashConditions, SplashDecision, SplashOptions, } from './ui/splash.ts';
 export { DEFAULT_CLIP_FPS, FrameRecorder, offerClip } from './ui/frameRecorder.ts';
 export { stillFrame } from './ui/stillFrame.ts';

package/dist/index.js

@@ -439,7 +439,7 @@ export { fullscreenWanted, requestFullscreenOnGesture } from './ui/fullscreen.js
  * they are here for the consumer that declines the automatic one and places its own, and because
  * the two decisions behind it are worth reading before overriding either.
  */
-export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.js';
+export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, holdSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.js';
 export { DEFAULT_CLIP_FPS, FrameRecorder, offerClip } from './ui/frameRecorder.js';
 // Not on `FrameRecorder`, so a screenshot does not cost a clip pipeline. See the module.
 export { stillFrame } from './ui/stillFrame.js';

package/dist/render/ambientOcclusionPass.d.ts

@@ -46,8 +46,9 @@ export declare class AmbientOcclusionPass {
      * by, or null if this pass could not run, which the caller must read as "no occlusion"
      * rather than as black.
      *
-     * `invProjection` is column-major, as `gl-matrix` produces it.
+     * `invProjection` is column-major, as `gl-matrix` produces it. `fade` is `uFade`, where the
+     * occlusion fades out with distance (`occlusionFade.ts`).
      */
-    run(depth: WebGLTexture, width: number, height: number, radius: number, projScale: Float32Array, invProjection: Float32Array): WebGLTexture | null;
+    run(depth: WebGLTexture, width: number, height: number, radius: number, projScale: Float32Array, invProjection: Float32Array, fade: Float32Array): WebGLTexture | null;
     dispose(): void;
 }

package/dist/render/ambientOcclusionPass.js

@@ -102,9 +102,10 @@ export class AmbientOcclusionPass {
      * by, or null if this pass could not run, which the caller must read as "no occlusion"
      * rather than as black.
      *
-     * `invProjection` is column-major, as `gl-matrix` produces it.
+     * `invProjection` is column-major, as `gl-matrix` produces it. `fade` is `uFade`, where the
+     * occlusion fades out with distance (`occlusionFade.ts`).
      */
-    run(depth, width, height, radius, projScale, invProjection) {
+    run(depth, width, height, radius, projScale, invProjection, fade) {
         if (!this.ensureSize(width, height))
             return null;
         const { gl } = this;
@@ -123,6 +124,7 @@ export class AmbientOcclusionPass {
         gl.uniform1i(this.estimateUniforms['uDepth'] ?? null, 0);
         gl.uniform2fv(this.estimateUniforms['uProjScale'] ?? null, projScale);
         gl.uniform1f(this.estimateUniforms['uRadius'] ?? null, radius);
+        gl.uniform2fv(this.estimateUniforms['uFade'] ?? null, fade);
         gl.uniformMatrix4fv(this.estimateUniforms['uInvProjection'] ?? null, false, invProjection);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         /*

package/dist/render/backend/api.d.ts

@@ -177,6 +177,14 @@ export interface SurfaceTextureHandle {
  * `WebGLBuffer` in a private field, so no WebGPU object can satisfy it however identical its
  * shape. It is not meant to be read; it is meant to be enforced.
  */
+/** Which of a draw's pipelines `prepareMesh` and `prepareInstanced` compile beside the opaque ones. */
+export interface PrepareOptions {
+    /**
+     * The blended ones too, for a draw made with `drawTranslucentMesh` or `drawTranslucentInstanced`.
+     * Off by default: an opaque surface would pay a compile it never draws with.
+     */
+    readonly translucent?: boolean;
+}
 /** What a mesh needs to be told at creation that its geometry cannot say. */
 export interface MeshOptions {
     /**
@@ -190,7 +198,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'prepareMesh' | 'prepareInstanced' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -299,6 +307,18 @@ export type RendererApi = Omit<{
      * setter each — and `setSurfaceTexture` is now a wrapper over it.
      */
     setMaterial(material: SurfaceMaterial<SurfaceTextureHandle> | null): void;
+    /**
+     * Compile, off the main thread, every pipeline a draw of `mesh` in `material` takes that making
+     * the mesh did not — a two-sided, cut-out or shaded-by-a-model variant, a material's lit switches,
+     * a skin's halves — so the first frame that draws it waits on none; `ready()` resolves once they
+     * have. For `pipelineCompile: 'skip'` above all, where a draw whose pipeline is new is left out
+     * until it lands: a figure brought on screen whole rather than without its face for a few frames.
+     * A rigged mesh is prepared as drawn with a palette, and one with targets both with weights and
+     * without. Call it between frames: it sets `material` to read it and leaves none set after.
+     */
+    prepareMesh(mesh: MeshHandle, material: SurfaceMaterial<SurfaceTextureHandle> | null, options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch drawn in `material`, its own pipelines being its own. */
+    prepareInstanced(batch: InstancedHandle, material: SurfaceMaterial<SurfaceTextureHandle> | null, options?: PrepareOptions): void;
     /**
      * A 3D text object: one string, drawn as instanced glyph cubes over the scene.
      *

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

@@ -49,7 +49,7 @@ import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts
 import { Mesh } from '../../mesh.ts';
 import type { IncrementalMesh } from '../../mesh.ts';
 import type { MeshData } from '../../mesh.ts';
-import type { MeshOptions } from '../api.ts';
+import type { MeshOptions, PrepareOptions } from '../api.ts';
 import { SurfaceTexture } from '../../surfaceTexture.ts';
 import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
@@ -1114,6 +1114,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly aoProjScale;
     /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
     private readonly aoOffset;
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    private readonly aoFade;
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -1281,14 +1283,23 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedProjectionRoom;
     /** `uWorldUv`, the current material's projection packed. See `surfaceProjection.ts`. */
     private readonly projection;
-    /** The current material's `diffuseTransmission`, `uGlassTint.w`, 0 to 1. */
-    private diffuseTransmission;
+    /**
+     * `uGlassTint` as the current material leaves it: its light from behind and that light's colour,
+     * which a pane overwrites for its own draw and `unbindSeeThrough` puts back. See `transmission.ts`.
+     */
+    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;
     private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
@@ -1959,6 +1970,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * `uScale`/`vScale` are repeats across the mesh's own UV range: geometry authored in
      * metres is textured at whatever density the material wants without rebuilding it.
      */
+    /**
+     * Compile, off the frame, every program a draw of `mesh` in `material` takes that making the mesh
+     * did not, so the first frame that draws it waits on none: the program of the material's shading
+     * model for each vertex variant the mesh can be drawn with (its rig, with a palette; its targets,
+     * with weights and without), a skin's halves under the screen-space blur, and the lit switches
+     * the material turns on. `ready()` resolves once they have.
+     *
+     * **For `pipelineCompile: 'skip'` above all**, where a draw whose program is new is left out until
+     * it lands: a figure brought on screen whole rather than without its face and hair for the frames
+     * those take. Where draws wait, the programs compile here, at the call, rather than in a frame.
+     * Two-sided and cut-out surfaces are draw state on this backend and need nothing; on WebGPU they
+     * are pipelines of their own, prepared the same way.
+     *
+     * **Call it between frames**: it sets `material` to read it and leaves no material set after, as
+     * `setMaterial(null)` does. `options` is the other backend's; blended draws share a program here.
+     */
+    prepareMesh(mesh: Mesh, material: SurfaceMaterial | null, _options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch: its own programs, and its model's for its variant. */
+    prepareInstanced(batch: InstancedBatch, material: SurfaceMaterial | null, _options?: PrepareOptions): void;
     /**
      * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
      *
@@ -2140,7 +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 the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
+    /**
+     * 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, 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.
@@ -2236,7 +2278,8 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * What it gives up: a fade reads as grain while it lasts, which a temporal resolve smooths and a
      * plain frame does not; a blended draw that asks spends its opacity here and blends none of it;
-     * and a lightmapped batch carries regions where the opacities would be, so it has none to fade.
+     * and a lightmapped batch's opacities ride its page regions, so they fade in steps of a
+     * sixty-fourth, which is the pattern's own resolution (`MeshInstances.lightmapRegions`).
      */
     setDitherOpacity(on: boolean): void;
     /**
@@ -2404,6 +2447,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * taking it mid-bake is how a probe's next face came to be attached to the scene's framebuffer.
      */
     private bindSeeThrough;
+    /** `uGlassTint` as the current material leaves it. See `transmission`. */
+    private writeTransmission;
     /** Put back what `bindSeeThrough` bound: the binding outlives its frame (the 2026-08-27 rule). */
     private unbindSeeThrough;
     disposeMesh(mesh: Mesh): void;
@@ -3293,6 +3338,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * once rather than doing nothing. See `shaders/localExposure.ts`.
      */
     setLocalExposure(strength: number): void;
+    /**
+     * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
+     * gone `radius` metres past it, so the far depth buffer's steps — a sky dome kilometres off, a
+     * mountain range — are not shaded in rings, and those pixels skip the occlusion's sampling.
+     *
+     * A distance that is not a finite number at or above zero is no fade, which is the default, and
+     * `Infinity` reads as "never fades"; a radius below zero is a cut at `distance`. Set before
+     * `endFrame` and held until changed, like `setDepthOfField`. Nothing at all when
+     * `ambientOcclusion` is 0. See `occlusionFade.ts` for what it gives up.
+     */
+    setAmbientOcclusionFade(distance: number, radius: number): void;
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take.