@driftengine/core 4.11.1 → 4.13.0

package/CHANGELOG.json

@@ -1,4 +1,106 @@
 [
+  {
+    "version": "4.13.0",
+    "date": "2026-10-10",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "The frame is encoded for the screen by default, every pass and the clear colour alike: `outputTransform` is `'srgb'`, so a model reads as it does elsewhere.",
+        "text": "`outputTransform` defaults to `'srgb'`. The light the renderer computes is linear, and a texture's colours are decoded to linear when they are read, so a frame written without encoding them back, which `'none'`, the default until now, did, reads every midtone far too dark: a textured model drawn from the manual with no quality options came out darker than the same file in any other engine, and the cause looks like lighting, so that is where people looked. **Every pass now grades where nothing after it will, and the clear colour with them**, so a colour handed to the renderer means one thing wherever it lands: the sky, water, scatter, the plumes, flocks, wind streaks, bolts, caustics, light volumes and film grade themselves, as the lit pass, particles, lines and world text already did; the decal multiply, the global medium, the skin blur's add and the resolve's occlusion work in the terms of a pixel already graded; and the gpu-driven pipeline's blit grades instead of warning. Until now, without `hdrScene`, those passes drew their colours as given beside a graded world, so a sky never met the fog fading into it. `'srgb'` is the display encoding with no tone curve; `'aces'` with an `outputExposure` still rolls highlights off. A world graded under `'none'` says so and draws exactly as it did, bit for bit, and a frame with `hdrScene` is graded once at the resolve exactly as before. What changes for a world on another curve without `hdrScene` is that its sky and water are graded with it, and its interface is encoded for the screen, as the next entry says."
+      },
+      {
+        "kind": "added",
+        "short": "Colours picked by eye are stated as such: `srgbColor(r, g, b)`, `MeshBuilder.build({ colorSpace: 'srgb' })` and `decodeSrgbInPlace`, each decoding to the linear values the renderer draws.",
+        "text": "A colour picked by eye, on a screen or in a paint program, is a display value, and the renderer draws linear ones, so typed in as it looks it comes out too light. Three ways say which it is. `srgbColor(r, g, b)` decodes one colour through the sRGB curve, so a surface lit at 1, a sky or a clear colour comes out as the colour picked. `MeshBuildOptions.colorSpace: 'srgb'` decodes every vertex colour and emissive colour of a built mesh once, at build, as a texture uploaded as sRGB is decoded at upload, so a world built from hand-picked colours changes one line. `decodeSrgbInPlace` decodes an array of them, leaving a negative sentinel alone, for a mesh written by hand. `srgbToLinear` decodes one channel, for a colour that arrives a number at a time, as a packed hex token does. A light's intensity is an amount rather than a look and stays as it is. The examples state their colours this way, and the starter, which a new project begins from, shows the default."
+      },
+      {
+        "kind": "changed",
+        "short": "Text, panels and the 2D layer are encoded for the screen and never tone mapped, so an interface comes out as picked under any transform and at any exposure.",
+        "text": "Screen text, `fillPanel` and `@driftengine/ui2d`'s 2D layer take the screen encode and never the curve or the exposure: `interfaceGrade` says which code that is, for a contributed pass that draws an interface. A caption or a panel is not light, and its colour was picked for the screen, so under `'aces'` a menu's white text came out grey, its dark panel crushed to black, and the whole interface brightened and darkened as the scene's exposure eased. Now every interface colour stated through `srgbColor`, or as a theme's hex token, comes out exactly as picked under every transform. Inside an `hdrScene` frame an interface is part of the picture the resolve tone maps, as it was; drawn after `endFrame`, it is not. Text drawn in the world at a model matrix is part of the world and keeps the curve."
+      },
+      {
+        "kind": "fixed",
+        "short": "A pass drawn after `endFrame` grades itself under an `hdrScene` composite too, where it drew its colours as display values beside a graded frame.",
+        "text": "With `hdrScene` the resolve grades the frame and every pass before it draws linear light. A pass drawn after `endFrame` lands on the canvas the resolve has already written, so nothing after it grades it, and it used to draw ungraded there: an interface drawn after the present, which is where the manual puts one to keep it out of the screen-space chain, was the one surface on screen reading its colours as display values. The decision is now one function both backends read, and past the present it answers the frame's own grade, composite or not."
+      },
+      {
+        "kind": "changed",
+        "short": "A colour picked for the screen is decoded where an interface takes one: ui2d's hex tokens, and a script's `ui.tint` and `sprites.tinted`.",
+        "text": "`unpackRgba` and `themeRgba` decode a packed `0xRRGGBBAA` token from the sRGB a hex colour is written in to the linear light a node holds, keeping its alpha as coverage. Read as linear, `0x336699` came out as `0x7caacb` under the new default, every panel a washed-out version of the one picked. DriftScript's `ui.tint` and `sprites.tinted` take a colour picked for the screen in the same terms and decode it, since a script has no `srgbColor` to say so, so a white sprite draws exactly the tint named. A renderer asked for `outputTransform: 'none'` draws these darker than picked, as it does every colour."
+      },
+      {
+        "kind": "changed",
+        "short": "A splat capture's colour is a display value, decoded after its view-dependent band, so a trained capture draws as it does in the tool that made it.",
+        "text": "A Gaussian capture is trained against photographs, so its colour terms reproduce their pixels drawn as they are. `SplatSource.colors` was documented as linear and drawn so, which under the new `'srgb'` default is a washed-out cloud. The splat shader now decodes a splat's colour after adding its l=1 band, which training added in the same space, and the eight bits a colour is packed into are spent where the eye sees them. What it gives up is the blend: splats compose in linear light rather than in the display values training composed them in, which moves a translucent edge a little. `@driftengine/capture` fits in linear light against decoded frames and now hands its colours over encoded, its l=1 band carried through the encode's slope at each colour, so a fitted capture draws as fitted."
+      },
+      {
+        "kind": "changed",
+        "short": "Sun shadows no longer dissolve past six metres or below 18° of sun: `directionalShadowMaxDistance` defaults to 1,000 and `directionalShadowMaxSlope` to 60.",
+        "text": "`directionalShadowMaxDistance` defaults to 1,000 metres and `directionalShadowMaxSlope` to 60. The old 6 and 3 were a tuning for short casters: any sun shadow longer than six metres along the ground dissolved, so a building's walls and arcades cast nothing on its floor under a high sun and the light read as random, and every sun shadow faded below about 18° of elevation, which is an evening without shadows. A shadow now reaches as far as its map holds, whose edge already fades it, and holds until the sun is about a degree above the horizon. The reach is a shadow's own length along the ground and not a distance from the camera, which its name suggests, and both options now say what their default gives up and what would make it wrong. A scene whose low sun streaks lowers the slope; one tuned around the old values sets them. The medium's shafts and a surface's shadows, which disagreed past six metres, now agree."
+      },
+      {
+        "kind": "added",
+        "short": "`DrftLoader` draws, casts and prepares its model: `draw()`, `casters` and `prepare()` apply every rule a container needs, and `PartDraws` does it for a chosen list.",
+        "text": "`DrftLoader.draw()` draws this frame's parts into the open mesh pass by every rule a baked container needs, each of which fails as a picture rather than an error when it is missed: a part's whole material, so foliage keeps its alpha test and a one-sided card its faces; its copies through one instanced draw, where a part drawn as a plain mesh shows one arch of a repeated row; a blended part translucent whatever its opacity and writing no depth, since its alpha is in its texture, where drawn opaque a grime decal is a black patch; a blended batch through the translucent instanced path; glass as glass, its options kept per pane so a frame allocates nothing; and each part's own reflectivity, with nothing left set for the caller's draws after it. `loader.casters` is a ready `ShadowCasters`: every part but a decal, which would shadow its own surface, each with its material so a cutout casts its shape, glass as glass and copies as copies. `await loader.prepare()` compiles every pipeline the parts draw with, off the frame, translucent where they will be drawn so. `PartDraws` is the same for any list of parts, several loaders' or a filtered one. The manual's chapter on importing models and the models example draw through them."
+      },
+      {
+        "kind": "added",
+        "short": "`computeLightMatrixForBounds` covers a box with the sun's map whole, and `DrftLoader.shadowFit` fits the map to a model as placed, from the bounds its file declares.",
+        "text": "`computeLightMatrixForBounds(lightDir, min, max, mapSize, out)` places a directional light's map around a box of known size: the sphere around the box, at its centre, widened by the half texel the centre's snap may move it, so a corner on the sphere stays inside. A focus and a radius chosen by eye around a guessed centre left part of a model outside the map, where it cast nothing. `DrftLoader.shadowFit(lightDir, mapSize, out)` does it for the model as fitted and returns the depth span for `shadowDepthSpan`, or null until `HEAD` has said how large the model is. What both give up is resolution on a large box, whose texels are spread over all of it; a world that follows a player keeps `computeLightMatrix` around the viewer."
+      },
+      {
+        "kind": "added",
+        "short": "`meshOcclusion` darkens the colour and the ambient light at once, each at its own strength: `colorStrength` beside `into: 'ambient'`, past 1 where a material asks.",
+        "text": "`SurfaceMeshOcclusion.colorStrength` is the colour's own strength: the blended colour times `max(0, 1 − colorStrength × (1 − occlusion))`, which up to 1 is the `mix` a strength always gave and past it darkens faster than the occlusion does. Named beside `into: 'ambient'`, one occlusion darkens the ambient light at `strength` and the colour at `colorStrength`, which is how a material that takes its ambient occlusion from a map and darkens its colour by the same map, at up to twice that, is drawn; with a single target it drew one of the two. Absent, it is `strength` where the colour is the target and 0 where the ambient light is, so every material written for 4.12.0 draws as it did. The two floats that carried a strength and a target now carry the two strengths."
+      },
+      {
+        "kind": "fixed",
+        "short": "A summed layer blend reflects the surface's own specular once where its layers name none, rather than its own times the sum of the layers' shares.",
+        "text": "Under `blend: 'sum'` a layer's share is its weight, and the shares add past 1 where the weights do, which is what a summed blend is for in colour. The specular took the same sum: a layer that named none gave the surface's own times its share, so a surface painted to weights adding to 2.5 or 3 reflected two and a half to three times its own specular, measured as a sandy floor 2.5% brighter across a frame than with its own. The layers that name no specular now give the surface's own at most once, whatever their shares add to, and named speculars still add as their colours do. A blend laid over, whose shares never pass 1, draws exactly as before, as does any layered material while no material has asked for looks."
+      },
+      {
+        "kind": "fixed",
+        "short": "A reflection probe stays ungraded when its bake's callback binds the mesh pass, so the frame no longer grades what it reads from the probe a second time.",
+        "text": "A probe stores radiance, so its bake holds the output transform at 0 while it draws the faces. `bindMeshPass`, which every bake's callback calls first, set the frame's grade again, so under any forward grade each face was graded as it was drawn and the frame graded what it read back from the cube a second time: reflections and probe ambient lifted and flattened. Every pass, the mesh pass among them, now asks one gate, which answers the frame's grade except in a probe's face or a capture. The same gate keeps particles, lines, text and contributed passes ungraded inside a bake."
+      }
+    ]
+  },
+  {
+    "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: 920.9 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
@@ -35,6 +35,7 @@ import {
   SceneNode,
   createEnvironment,
   createRenderer,
+  srgbColor,
   startLoop,
 } from '@driftengine/core';
 import { bindModule } from '@driftengine/script';
@@ -60,15 +61,23 @@ if (readout !== null) readout.textContent = `${backend}: ${reason}`;
 renderer.resize();
 addEventListener('resize', () => renderer.resize());
 
-/** Light, air and ground bounce. Chosen once, because these are allocation-sized decisions. */
+/**
+ * Light, air and ground bounce. Chosen once, because these are allocation-sized decisions.
+ *
+ * Every colour here and below was picked by eye, so it goes through `srgbColor`: the renderer
+ * lights in linear values and encodes them for the screen at the end, and a colour typed as it
+ * looks would come out too light. The clear colour in the loop is one of them.
+ */
+const CLEAR = srgbColor(0.05, 0.06, 0.09);
+
 const ENV = createEnvironment({
   directionalDir: [0.4, 0.7, 0.35],
-  directionalColor: [1, 0.96, 0.88],
-  ambient: [0.2, 0.22, 0.28],
-  ambientGround: [0.08, 0.08, 0.1],
+  directionalColor: srgbColor(1, 0.96, 0.88),
+  ambient: srgbColor(0.2, 0.22, 0.28),
+  ambientGround: srgbColor(0.08, 0.08, 0.1),
   emissiveGain: 0,
   nightFactor: 0,
-  fogColor: [0.16, 0.18, 0.24],
+  fogColor: srgbColor(0.16, 0.18, 0.24),
   fogDensity: 0.004,
   fogHeightFalloff: 0.03,
   fogBaseY: 0,
@@ -80,11 +89,11 @@ const ENV = createEnvironment({
  * is two units on a side.
  */
 const shapes = new MeshBuilder();
-shapes.addBox([0, 1, 0], [1, 1, 1], [0.85, 0.45, 0.25]);
+shapes.addBox([0, 1, 0], [1, 1, 1], srgbColor(0.85, 0.45, 0.25));
 const cube = renderer.createMesh(shapes.build());
 
 const slab = new MeshBuilder();
-slab.addBox([0, -0.25, 0], [12, 0.25, 12], [0.3, 0.32, 0.36]);
+slab.addBox([0, -0.25, 0], [12, 0.25, 12], srgbColor(0.3, 0.32, 0.36));
 const ground = renderer.createMesh(slab.build());
 
 const spinner = new SceneNode();
@@ -136,7 +145,7 @@ startLoop({
 
     camera.updateMatrices(canvas.height > 0 ? canvas.width / canvas.height : 1);
 
-    renderer.beginFrame([0.05, 0.06, 0.09]);
+    renderer.beginFrame(CLEAR);
     renderer.bindMeshPass(camera, ENV);
     renderer.drawMesh(ground, stillness.worldMatrix);
     renderer.drawMesh(cube, spinner.worldMatrix);

package/dist/geometry/meshBuilder.d.ts

@@ -10,6 +10,16 @@ export interface MeshBuildOptions {
      * sample them. On, for a mesh that will be drawn with a `SurfaceTexture`.
      */
     planarUvs?: boolean;
+    /**
+     * The space the builder's colours were given in. `'linear'`, the default, is the renderer's own:
+     * light as a surface reflects it. `'srgb'` is a colour picked by eye, on a screen or in a paint
+     * program, and decodes every vertex's colour and emissive colour to linear here, once — as a
+     * texture of colours uploaded as sRGB is decoded — so a world built from hand-picked colours draws
+     * them as picked under the default `outputTransform`, where the same numbers taken as linear come
+     * out pale. What it gives up: nothing at the colour picked; a colour meant as light rather than as
+     * a look wants a linear number of its own.
+     */
+    colorSpace?: 'linear' | 'srgb';
 }
 /**
  * CPU-side accumulator that merges axis-aligned boxes into one static mesh —

package/dist/geometry/meshBuilder.js

@@ -1,4 +1,5 @@
 import { GrowableF32, GrowableU32 } from './growable.js';
+import { decodeSrgbInPlace } from '../math/color.js';
 /**
  * The emissive colour of a vertex that has not been given one: negative, which no real
  * colour can be, so "inherit the surface's albedo" is representable without a second
@@ -914,14 +915,22 @@ export class MeshBuilder {
         /* Same promise as `specular`: a mesh nothing bound uploads no skinning buffers, and
            `MeshData` requires both arrays or neither. */
         const skinned = this.anyJoint;
+        /* Colours picked by eye, decoded once here: see `MeshBuildOptions.colorSpace`. */
+        const picked = options.colorSpace === 'srgb';
         return {
             positions: this.positions.toTyped(),
             normals: this.normals.toTyped(),
-            colors: this.colors.toTyped(),
+            colors: picked ? decodeSrgbInPlace(this.colors.toTyped()) : this.colors.toTyped(),
             emissive: this.emissive.toTyped(),
             ...(shines ? { specular: this.specular.toTyped() } : {}),
             ...(textured ? { relief: this.relief.toTyped() } : {}),
-            ...(tinted ? { emissiveColor: this.emissiveColor.toTyped() } : {}),
+            ...(tinted
+                ? {
+                    emissiveColor: picked
+                        ? decodeSrgbInPlace(this.emissiveColor.toTyped())
+                        : this.emissiveColor.toTyped(),
+                }
+                : {}),
             ...(rough ? { roughness: this.roughness.toTyped() } : {}),
             ...(mineral ? { grain: this.grain.toTyped() } : {}),
             ...(skinned ? { joints: this.expandedJoints(), weights: this.expandedWeights() } : {}),

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export type { CelestialSite, CelestialState } from './environment/celestialClock
 export { createDaylightPalette, createDaylightState, easeExposure, resolveDaylight, } from './environment/daylight.ts';
 export type { DaylightKey, DaylightPalette, DaylightState } from './environment/daylight.ts';
 export { TAU, DEG_TO_RAD, clamp, lerp, smoothstep, damp, dampTracking, angleDelta, dampAngle, wrapAngle, lerpAngle, } from './math/scalar.ts';
-export { hslToRgb, mixColor, mixColorInto, scaleColor } from './math/color.ts';
+export { decodeSrgbInPlace, hslToRgb, mixColor, mixColorInto, scaleColor, srgbColor, srgbToLinear, } from './math/color.ts';
 export type { Vec3 } from './math/color.ts';
 export { Camera } from './render/camera.ts';
 export { ThirdPersonCamera } from './render/thirdPersonCamera.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';
@@ -248,7 +250,7 @@ export type { LightGrid } from './render/lightGrid.ts';
 export type { PointLightBuffer, PointLightSource } from './render/pointLightSelection.ts';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.ts';
 export type { Flame, FlameOptions } from './render/flameLight.ts';
-export { computeLightMatrix } from './render/lightMatrix.ts';
+export { computeLightMatrix, computeLightMatrixForBounds } from './render/lightMatrix.ts';
 export { PlumeRenderer } from './render/plumeRenderer.ts';
 export { createEnvironment } from './render/backend/webgl2/renderer.ts';
 export type { InsetRect } from './render/backend/webgl2/renderer.ts';
@@ -262,6 +264,7 @@ export type { LoadTask, LoadSummary } from './core/loadTracker.ts';
 export { buildShellFill, shellSkin, shellFillMatrix, DEFAULT_SHELL_PROFILE, } from './geometry/shellFill.ts';
 export type { ShellStation, ShellFillOptions } from './geometry/shellFill.ts';
 export { OUTPUT_TRANSFORM_GLSL } from './render/shaders/outputTransform.ts';
+export { interfaceGrade } from './render/passGrade.ts';
 export { PLUME_VERT, FIRE_FRAG } from './render/shaders/fire.ts';
 export { ARCANE_FRAG } from './render/shaders/arcane.ts';
 export { SMOKE_FRAG } from './render/shaders/smoke.ts';

package/dist/index.js

@@ -35,7 +35,7 @@ export { MessageQueue } from './core/messageQueue.js';
 export { celestialStateAt, createCelestialState, moonIllumination, } from './environment/celestialClock.js';
 export { createDaylightPalette, createDaylightState, easeExposure, resolveDaylight, } from './environment/daylight.js';
 export { TAU, DEG_TO_RAD, clamp, lerp, smoothstep, damp, dampTracking, angleDelta, dampAngle, wrapAngle, lerpAngle, } from './math/scalar.js';
-export { hslToRgb, mixColor, mixColorInto, scaleColor } from './math/color.js';
+export { decodeSrgbInPlace, hslToRgb, mixColor, mixColorInto, scaleColor, srgbColor, srgbToLinear, } from './math/color.js';
 export { Camera } from './render/camera.js';
 export { ThirdPersonCamera } from './render/thirdPersonCamera.js';
 export { CinematicCamera } from './render/cinematicCamera.js';
@@ -305,7 +305,7 @@ export { describeGpu } from './render/gpuCapability.js';
 export { DEFAULT_POINT_LIGHT_VIEW_RANGE, createPointLightBuffer, selectGridLights, selectPointLights, } from './render/pointLightSelection.js';
 export { LIGHT_GRID_MAX_CELLS, createLightGrid, gatherLights } from './render/lightGrid.js';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.js';
-export { computeLightMatrix } from './render/lightMatrix.js';
+export { computeLightMatrix, computeLightMatrixForBounds } from './render/lightMatrix.js';
 export { PlumeRenderer } from './render/plumeRenderer.js';
 export { createEnvironment } from './render/backend/webgl2/renderer.js';
 export { TrampleField, TRAMPLE_SLOTS } from './render/trample.js';
@@ -337,6 +337,7 @@ export { buildShellFill, shellSkin, shellFillMatrix, DEFAULT_SHELL_PROFILE, } fr
  * this line the only way for it to comply was to copy, which is what the rule forbids.
  */
 export { OUTPUT_TRANSFORM_GLSL } from './render/shaders/outputTransform.js';
+export { interfaceGrade } from './render/passGrade.js';
 export { PLUME_VERT, FIRE_FRAG } from './render/shaders/fire.js';
 export { ARCANE_FRAG } from './render/shaders/arcane.js';
 export { SMOKE_FRAG } from './render/shaders/smoke.js';

package/dist/math/color.d.ts

@@ -6,3 +6,28 @@ export declare function mixColor(a: Vec3, b: Vec3, t: number): Vec3;
 /** In-place `mixColor` for per-frame use — allocating here would be a hot-path bug. */
 export declare function mixColorInto(out: Vec3, a: Vec3, b: Vec3, t: number): void;
 export declare function scaleColor(color: Vec3, factor: number): Vec3;
+/**
+ * A colour picked by eye — on a screen, in a paint program, as a CSS colour — as the linear value
+ * the renderer lights, blends, fogs and grades: each channel through the sRGB curve, which the
+ * default `outputTransform`, `'srgb'`, applies the other way at the end, so a colour drawn as it is,
+ * a sky, a clear or a surface lit at exactly 1, comes out as the colour picked.
+ *
+ * **Why a colour needs it**: everything the renderer draws is linear and encoded at the end, so a
+ * colour typed as it looks comes out too light — a brown picked as `(0.55, 0.3, 0.15)` draws as
+ * tan. **What it gives up**: nothing at the colour picked. **What would make it wrong** is a number
+ * that is an amount rather than a look: a light's intensity, a multiplier, a strength, which are
+ * linear already. Allocates, so it is for building a world rather than for a frame.
+ */
+export declare function srgbColor(r: number, g: number, b: number): Vec3;
+/**
+ * Every value of `values` decoded from sRGB in place, but a negative one, which is a sentinel and
+ * not a colour (`MeshBuilder`'s emissive colour left to the albedo). For whole arrays of colours
+ * picked by eye; see `MeshBuildOptions.colorSpace`.
+ */
+export declare function decodeSrgbInPlace(values: Float32Array): Float32Array;
+/**
+ * One channel, 0 to 1, through the sRGB decode: the straight segment below 0.04045. For a colour
+ * that arrives as numbers per channel rather than as a triple, a packed hex token being the usual
+ * one; allocates nothing.
+ */
+export declare function srgbToLinear(value: number): number;

package/dist/math/color.js

@@ -33,3 +33,40 @@ export function mixColorInto(out, a, b, t) {
 export function scaleColor(color, factor) {
     return [color[0] * factor, color[1] * factor, color[2] * factor];
 }
+/**
+ * A colour picked by eye — on a screen, in a paint program, as a CSS colour — as the linear value
+ * the renderer lights, blends, fogs and grades: each channel through the sRGB curve, which the
+ * default `outputTransform`, `'srgb'`, applies the other way at the end, so a colour drawn as it is,
+ * a sky, a clear or a surface lit at exactly 1, comes out as the colour picked.
+ *
+ * **Why a colour needs it**: everything the renderer draws is linear and encoded at the end, so a
+ * colour typed as it looks comes out too light — a brown picked as `(0.55, 0.3, 0.15)` draws as
+ * tan. **What it gives up**: nothing at the colour picked. **What would make it wrong** is a number
+ * that is an amount rather than a look: a light's intensity, a multiplier, a strength, which are
+ * linear already. Allocates, so it is for building a world rather than for a frame.
+ */
+export function srgbColor(r, g, b) {
+    return [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)];
+}
+/**
+ * Every value of `values` decoded from sRGB in place, but a negative one, which is a sentinel and
+ * not a colour (`MeshBuilder`'s emissive colour left to the albedo). For whole arrays of colours
+ * picked by eye; see `MeshBuildOptions.colorSpace`.
+ */
+export function decodeSrgbInPlace(values) {
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        if (value >= 0)
+            values[i] = srgbToLinear(value);
+    }
+    return values;
+}
+/**
+ * One channel, 0 to 1, through the sRGB decode: the straight segment below 0.04045. For a colour
+ * that arrives as numbers per channel rather than as a triple, a packed hex token being the usual
+ * one; allocates nothing.
+ */
+export function srgbToLinear(value) {
+    // determinism: build-time — a colour for drawing, which no tick reads
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}

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

@@ -1290,15 +1290,22 @@ 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;
     private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
+    /** `clearOf`'s scratch: a clear colour as the open target takes it. */
+    private readonly gradedClear;
     /**
      * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
      * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
@@ -2165,9 +2172,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.
@@ -2546,7 +2563,9 @@ export declare class WebGL2Renderer implements RendererApi {
      * real draw call touches the unit in the first place.
      */
     /**
-     * The output transform a forward pass should apply, and the exposure it should apply it at.
+     * The grade a pass applies to what it draws into the target open now, and the exposure it
+     * applies it at. The decision is `passGrade.ts`'s, for both backends; this only gathers the
+     * state it is taken from.
      *
      * **Only where that pass is genuinely the last one to touch the frame.** With a scene target
      * the resolve grades, so a pass that graded as well would be applying a curve to its own
@@ -2554,15 +2573,24 @@ export declare class WebGL2Renderer implements RendererApi {
      * `screenEffects` off there is no resolve at all and every pass writes straight to the canvas,
      * so each one has to grade itself or the frame comes out half converted: linear values in an
      * eight-bit buffer read as display values, which is a saturated, clipped version of the colour
-     * the caller asked for rather than a slightly different one.
+     * the caller asked for rather than a slightly different one. A probe's face or a capture is
+     * never graded, and past the present every pass grades itself, composite or not.
      *
      * One pair of accessors rather than the expression written out at each site, because that is
      * how the mesh pass and the particle pass came to disagree in the first place: the mesh pass
      * gated, and the particle pass uploaded the transform unconditionally to a stage that did not
      * yet declare it.
      */
-    private gradeCode;
-    private gradeExposure;
+    private passGrade;
+    private passGradeExposure;
+    /** Whether the frame's resolve applies the transform, so the passes before it draw linear. */
+    private resolveGrades;
+    /**
+     * A clear colour as the target open now takes it: graded as a pass would grade it, so a colour
+     * handed to the renderer is linear wherever it lands — the clear too, which the resolve grades
+     * with everything else under `hdrScene`. See `gradeColor.ts`. Into one scratch, read at once.
+     */
+    private clearOf;
     drawSdfText(handle: SdfTextRenderer, model: Float32Array, color: Vec3, opacity: number): void;
     /** Release an SDF text label. Takes no context; see `disposeText`. */
     disposeSdfText(handle: SdfTextRenderer): void;