trid3d 0.3.1 → 0.4.0

package/trid/render/canvasRenderer.js

@@ -6,6 +6,8 @@ import { parseColor } from "./color.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { textureReady, textureSize, textureIsLive, textureVersion } from "../loaders/texture.js";
 import { uvsFor, uvTransform, applyUVTransform } from "./uvMapping.js";
+import { DEFAULT_LIGHT, DEFAULT_AMBIENT, sceneLights, lightAt as lightOf, lightLevels } from "./lights.js";
+import { runCanvasPost } from "./post.js";
 
 export { newell };
 
@@ -23,11 +25,7 @@ export function materialsOf(obj) {
   return m.length && m[0] ? m : null;
 }
 
-/** Direction light comes from when the scene doesn't set one: above, left, in front. */
-export const DEFAULT_LIGHT = { x: -0.5, y: 1, z: -0.8 };
-
-/** How bright a face turned fully away from the light still is (0..1). */
-export const DEFAULT_AMBIENT = 0.25;
+export { DEFAULT_LIGHT, DEFAULT_AMBIENT };
 
 /**
  * Material: how an object's faces look. Objects without one are drawn
@@ -115,12 +113,13 @@ export class CanvasRenderer {
         drawInstance(ctx, obj, camera, w, h, obj.color ?? scene.color, obj.lineWidth ?? scene.lineWidth, obj.world);
       }
       for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
+      runCanvasPost(scene, scene.post, this._start);
       return;
     }
 
     const near = camera.near ?? DEFAULT_NEAR;
-    const light = normalize(scene.light ?? DEFAULT_LIGHT);
-    const ambient = scene.ambient ?? DEFAULT_AMBIENT;
+    // Every light, colors parsed (see trid/render/lights.js)
+    const lights = sceneLights(scene, (css) => this._rgba(ctx, css));
     const toScreen = (p) => cameraToScreen(p, camera, w, h);
     const items = [];
     // For effects
@@ -168,16 +167,9 @@ export class CanvasRenderer {
         const na = normalAt(corners, F, a), nb = normalAt(corners, F, b);
         return normalize({ x: na.x + nb.x, y: na.y + nb.y, z: na.z + nb.z });
       };
-      const lightAt = (n, back) => {
-        const r = transformNormal(nm, n);
-        const d = (back ? -1 : 1) * (r.x * light.x + r.y * light.y + r.z * light.z);
-        return ambient + (1 - ambient) * Math.max(0, d);
-      };
-      const flatLight = (face, back) => {
-        const nw = flatNormal(face);
-        const d = (back ? -1 : 1) * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
-        return ambient + (1 - ambient) * Math.max(0, d);
-      };
+      // Light reaching a point, as [r, g, b]: at a corner (smooth) or a face's center (flat)
+      const lightAt = (n, back, p) => lightOf(lights, flipIf(transformNormal(nm, n), back), p);
+      const flatLight = (face, back) => lightOf(lights, flipIf(flatNormal(face), back), centroid(face.map((i) => world[i])));
       const toWorldNormal = (n) => transformNormal(nm, n);
 
       // Everything a material needs, worked out once per object and frame
@@ -247,9 +239,12 @@ export class CanvasRenderer {
           const ts = face.map((i) => L.uvAt(F, i));
           if (ts.every(Boolean)) {
             let lit;
-            if (!shade) lit = face.map(() => 1);
-            else if (corners) lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
-            else lit = face.map(() => flatLight(face, back));
+            if (!shade) lit = face.map(() => WHITE);
+            else if (corners) lit = face.map((i) => lightAt(normalAt(corners, F, i), back, world[i]));
+            else {
+              const one = flatLight(face, back);
+              lit = face.map(() => one);
+            }
             const screen = pts.map(toScreen);
             const n = face.length;
             for (let k = 1; k < n - 1; k++) {
@@ -282,17 +277,18 @@ export class CanvasRenderer {
 
           const position = centroid(face.map((i) => world[i]));
           const toCam = { x: camPos.x - position.x, y: camPos.y - position.y, z: camPos.z - position.z };
-          const diffuse = Math.max(0, nw.x * light.x + nw.y * light.y + nw.z * light.z);
-          const lit = shade ? ambient + (1 - ambient) * diffuse : 1;
+          const reach = lightOf(lights, nw, position);
+          const { light: level, diffuse } = lightLevels(reach, lights.ambientLevel);
+          const lightColor = shade ? reach : WHITE.slice();
           const rgba = this._rgba(ctx, fill);
           const s = {
             base: rgba, normal: nw, position, local: centroid(face.map((i) => verts[i])),
-            view: normalize(toCam), lightDir: light, diffuse, light: lit, ambient,
+            view: normalize(toCam), lightDir: lights.mainDir, diffuse, light: shade ? level : 1, ambient: lights.ambientLevel, lightColor,
             uv: centerUV(face.map((i) => L.uvAt(F, i))),
             depth: Math.hypot(toCam.x, toCam.y, toCam.z), time, background,
             rgba: (v) => (typeof v === "string" ? this._rgba(ctx, v) : Array.isArray(v) ? v : [v.x, v.y, v.z, 1]),
           };
-          let col = [rgba[0] * lit, rgba[1] * lit, rgba[2] * lit, rgba[3]];
+          let col = [rgba[0] * lightColor[0], rgba[1] * lightColor[1], rgba[2] * lightColor[2], rgba[3]];
           for (const e of L.effects) if (e.canvas) col = e.canvas(col, s, e.uniforms ?? {});
           const k = col.map((x) => Math.min(1, Math.max(0, x)));
           items.push({
@@ -305,7 +301,7 @@ export class CanvasRenderer {
         }
 
         if (corners) {
-          const lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
+          const lit = face.map((i) => lightAt(normalAt(corners, F, i), back, world[i]));
           if (clipped === pts) {
             // One gradient per triangle: brightness changes linearly across a triangle
             const screen = pts.map(toScreen);
@@ -323,13 +319,12 @@ export class CanvasRenderer {
             }
             continue;
           }
-          // Cut by the near plane: use the average brightness
-          const avg = lit.reduce((a, b) => a + b, 0) / lit.length;
-          items.push({ depth: c.z, poly: clipped.map(toScreen), fill: this._shade(ctx, fill, avg), outline, lineWidth, edges });
+          // Cut by the near plane: use the average light
+          items.push({ depth: c.z, poly: clipped.map(toScreen), fill: this._shade(ctx, fill, average(lit)), outline, lineWidth, edges });
           continue;
         }
 
-        const brightness = shade ? flatLight(face, back) : 1;
+        const brightness = shade ? flatLight(face, back) : WHITE;
         items.push({
           depth: c.z,
           poly: clipped.map(toScreen),
@@ -394,6 +389,9 @@ export class CanvasRenderer {
 
     // Meshes marked as changed have been redrawn from their new data
     for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
+
+    // Post effects that have a canvas version (see trid/render/post.js)
+    runCanvasPost(scene, scene.post, this._start);
   }
 
   /**
@@ -487,15 +485,17 @@ export class CanvasRenderer {
   }
 
   /**
-   * A fill for a triangle whose corners have different brightness:
-   * a linear gradient along the direction brightness changes fastest.
-   * Exact, because brightness changes linearly across a triangle.
+   * A fill for a triangle whose corners get different light ([r, g, b] each):
+   * a linear gradient along the direction the light changes fastest.
+   * Exact for white light (brightness changes linearly across a triangle);
+   * close for colored lights whose colors change in different directions.
    */
   _gradient(ctx, color, tri, lit) {
-    const g = gradientLine(tri, lit);
-    if (!g) return this._shade(ctx, color, (Math.min(...lit) + Math.max(...lit)) / 2);
+    const g = gradientLine(tri, lit.map((c) => c[0] + c[1] + c[2]));
+    if (!g) return this._shade(ctx, color, average(lit));
     const grad = ctx.createLinearGradient(g.x0, g.y0, g.x1, g.y1);
-    const a = this._shade(ctx, color, g.lo), b = this._shade(ctx, color, g.hi);
+    const a = this._shade(ctx, color, lightOnTriangle(tri, lit, g.x0, g.y0));
+    const b = this._shade(ctx, color, lightOnTriangle(tri, lit, g.x1, g.y1));
     grad.addColorStop(0, a.css);
     grad.addColorStop(1, b.css);
     return { css: grad, opaque: a.opaque };
@@ -551,19 +551,40 @@ export class CanvasRenderer {
       ctx.globalCompositeOperation = "source-over";
     }
 
-    // Light: black on top, as see-through as the face is bright
-    const lo = Math.min(...it.lit), hi = Math.max(...it.lit);
-    if (lo >= 0.999) return;
-    const g = gradientLine(it.poly, it.lit);
+    // Light (the canvas can darken a texture, not make it brighter than it is)
+    const lit = it.lit.map((c) => c.map((x) => Math.min(1, x)));
+    if (lit.every((c) => c[0] >= 0.999 && c[1] >= 0.999 && c[2] >= 0.999)) return;
+    const white = lit.every((c) => Math.abs(c[0] - c[1]) < 1e-3 && Math.abs(c[1] - c[2]) < 1e-3);
+    if (white) {
+      // White light: black on top, as see-through as the face is bright
+      const level = lit.map((c) => c[0]);
+      const lo = Math.min(...level), hi = Math.max(...level);
+      const g = gradientLine(it.poly, level);
+      if (g) {
+        const grad = ctx.createLinearGradient(g.x0, g.y0, g.x1, g.y1);
+        grad.addColorStop(0, `rgba(0, 0, 0, ${1 - g.lo})`);
+        grad.addColorStop(1, `rgba(0, 0, 0, ${1 - g.hi})`);
+        ctx.fillStyle = grad;
+      } else {
+        ctx.fillStyle = `rgba(0, 0, 0, ${1 - (lo + hi) / 2})`;
+      }
+      ctx.fill();
+      return;
+    }
+    // Colored light: multiply by its color
+    const css = (c) => `rgb(${Math.round(c[0] * 255)}, ${Math.round(c[1] * 255)}, ${Math.round(c[2] * 255)})`;
+    const g = gradientLine(it.poly, lit.map((c) => c[0] + c[1] + c[2]));
     if (g) {
       const grad = ctx.createLinearGradient(g.x0, g.y0, g.x1, g.y1);
-      grad.addColorStop(0, `rgba(0, 0, 0, ${1 - g.lo})`);
-      grad.addColorStop(1, `rgba(0, 0, 0, ${1 - g.hi})`);
+      grad.addColorStop(0, css(lightOnTriangle(it.poly, lit, g.x0, g.y0)));
+      grad.addColorStop(1, css(lightOnTriangle(it.poly, lit, g.x1, g.y1)));
       ctx.fillStyle = grad;
     } else {
-      ctx.fillStyle = `rgba(0, 0, 0, ${1 - (lo + hi) / 2})`;
+      ctx.fillStyle = css(average(lit));
     }
+    ctx.globalCompositeOperation = "multiply";
     ctx.fill();
+    ctx.globalCompositeOperation = "source-over";
   }
 
   /**
@@ -591,16 +612,20 @@ export class CanvasRenderer {
     return c;
   }
 
-  /** CSS color for `color` at a brightness, cached (brightness is rounded to 1/255). */
-  _shade(ctx, color, brightness) {
-    const level = Math.round(brightness * 255);
-    const key = color + "|" + level;
+  /**
+   * CSS color for `color` under some light: a brightness, or [r, g, b]
+   * (colored light). Cached; the light is rounded to 1/255.
+   */
+  _shade(ctx, color, light) {
+    const [lr, lg, lb] = typeof light === "number" ? [light, light, light] : light;
+    const q = (x) => Math.round(Math.max(0, x) * 255);
+    const key = color + "|" + q(lr) + "," + q(lg) + "," + q(lb);
     let out = this._shades.get(key);
     if (!out) {
       const [r, g, b, a] = parseColor(ctx, color);
-      const k = level / 255;
+      const ch = (c, k) => Math.min(255, Math.round((c * q(k)) / 255));
       out = {
-        css: `rgba(${Math.round(r * k)}, ${Math.round(g * k)}, ${Math.round(b * k)}, ${a})`,
+        css: `rgba(${ch(r, lr)}, ${ch(g, lg)}, ${ch(b, lb)}, ${a})`,
         opaque: a >= 1,
       };
       this._shades.set(key, out);
@@ -629,6 +654,32 @@ function gradientLine(tri, lit) {
   return { x0: p0.x + gx * s, y0: p0.y + gy * s, x1: p0.x + gx * e, y1: p0.y + gy * e, lo, hi };
 }
 
+/** Light [r, g, b] at screen point (x, y), blended from a triangle's corners (it can lie outside). */
+function lightOnTriangle(tri, lit, x, y) {
+  const [a, b, c] = tri;
+  const d = (b.y - c.y) * (a.x - c.x) + (c.x - b.x) * (a.y - c.y);
+  if (Math.abs(d) < 1e-9) return average(lit);
+  const u = ((b.y - c.y) * (x - c.x) + (c.x - b.x) * (y - c.y)) / d;
+  const v = ((c.y - a.y) * (x - c.x) + (a.x - c.x) * (y - c.y)) / d;
+  const w = 1 - u - v;
+  return [0, 1, 2].map((i) => Math.max(0, u * lit[0][i] + v * lit[1][i] + w * lit[2][i]));
+}
+
+/** Average of [r, g, b] lights. */
+function average(lit) {
+  const out = [0, 0, 0];
+  for (const c of lit) for (let i = 0; i < 3; i++) out[i] += c[i] / lit.length;
+  return out;
+}
+
+/** White light: colors drawn as they are. */
+const WHITE = [1, 1, 1];
+
+/** The vector, reversed when `back` (a face seen from behind is lit from its other side). */
+function flipIf(n, back) {
+  return back ? { x: -n.x, y: -n.y, z: -n.z } : n;
+}
+
 /** A polygon pushed outward from its center by `px` pixels. */
 function grow(poly, px) {
   const cx = poly.reduce((a, p) => a + p.x, 0) / poly.length;

package/trid/render/effects.js

@@ -29,10 +29,14 @@
  * @property {{x,y,z}} position - World position
  * @property {{x,y,z}} local - Position in the mesh's own space
  * @property {{x,y,z}} view - Unit direction from the point to the camera
- * @property {{x,y,z}} lightDir - Unit direction light comes from
- * @property {number} diffuse - How much the point faces the light (0..1)
- * @property {number} light - Brightness Trid used: ambient + (1 - ambient) × diffuse
- * @property {number} ambient - The scene's ambient level
+ * @property {{x,y,z}} lightDir - Unit direction the scene's first directional light comes from
+ * @property {number} diffuse - How much of the light comes from the lights rather than the
+ *   ambient, 0..1. With the default single light: how much the point faces it
+ * @property {number} light - Brightness Trid used (the brightest channel of `lightColor`):
+ *   ambient + (1 - ambient) × diffuse with the default lights
+ * @property {number[]} lightColor - The light reaching the point, [r, g, b] (all the
+ *   scene's lights added up; can go above 1). Trid's color is `base × lightColor`
+ * @property {number} ambient - The scene's ambient level (brightest channel)
  * @property {number} depth - Distance to the camera
  * @property {number} time - Seconds since the renderer started
  * @property {number[]} background - The scene's background color [r, g, b, a]
@@ -50,6 +54,7 @@ struct Surface {
   vec3 lightDir;
   float diffuse;
   float light;
+  vec3 lightColor;
   float ambient;
   float depth;
   float time;
@@ -59,6 +64,7 @@ struct Surface {
 
 /**
  * Cartoon look: the light comes in a few hard steps instead of a smooth fade.
+ * Colored lights keep their color; only the brightness is stepped.
  *
  * @param {Object} [opts]
  * @param {number} [opts.steps=3] - Number of brightness levels
@@ -71,12 +77,14 @@ export function toon({ steps = 3 } = {}) {
 vec4 effect(vec4 color, Surface s) {
   float level = min(floor(s.diffuse * uSteps), uSteps - 1.0) / max(uSteps - 1.0, 1.0);
   float b = s.ambient + (1.0 - s.ambient) * level;
-  return vec4(s.base.rgb * b, color.a);
+  vec3 hue = s.lightColor / max(s.light, 1e-4); // the light's color at full brightness
+  return vec4(s.base.rgb * hue * b, color.a);
 }`,
     canvas: (color, s, u) => {
       const level = Math.min(Math.floor(s.diffuse * u.uSteps), u.uSteps - 1) / Math.max(u.uSteps - 1, 1);
       const b = s.ambient + (1 - s.ambient) * level;
-      return [s.base[0] * b, s.base[1] * b, s.base[2] * b, color[3]];
+      const k = b / Math.max(s.light, 1e-4);
+      return [0, 1, 2].map((i) => s.base[i] * s.lightColor[i] * k).concat(color[3]);
     },
   };
 }
@@ -170,14 +178,13 @@ export function gradient({
 vec4 effect(vec4 color, Surface s) {
   float t = clamp((s.${p}[${k}] - uMin) / (uMax - uMin), 0.0, 1.0);
   vec3 c = mix(uFrom.rgb, uTo.rgb, t);
-  return vec4(c * mix(1.0, s.light, uLit), color.a);
+  return vec4(c * mix(vec3(1.0), s.lightColor, uLit), color.a);
 }`,
     canvas: (color, s, u) => {
       const v = s[p][axis] ?? s[p].y;
       const t = Math.min(1, Math.max(0, (v - u.uMin) / (u.uMax - u.uMin)));
       const a = s.rgba(u.uFrom), b = s.rgba(u.uTo);
-      const l = u.uLit ? s.light : 1;
-      return [0, 1, 2].map((i) => (a[i] + (b[i] - a[i]) * t) * l).concat(color[3]);
+      return [0, 1, 2].map((i) => (a[i] + (b[i] - a[i]) * t) * (u.uLit ? s.lightColor[i] : 1)).concat(color[3]);
     },
   };
 }

package/trid/render/grid.js

@@ -0,0 +1,177 @@
+/**
+ * Floor grids: lines on a plane, drawn as line-only meshes (no faces, so
+ * they're drawn with the object's `color` and `lineWidth`).
+ *
+ *   scene.add(gridHelper({ size: 4, divisions: 40 }));         // a floor with axes, fading out
+ *   scene.add({ mesh: gridMesh({ size: 2 }), color: "#444" });  // just the lines
+ */
+
+/** Which world axes each plane uses: [first, second], and the one it faces. */
+const PLANES = {
+  xz: ["x", "z", "y"],
+  xy: ["x", "y", "z"],
+  yz: ["y", "z", "x"],
+};
+
+/** Axis colors, the same as `TransformGizmo` and `ViewGizmo`. */
+const AXIS_COLORS = { x: "#e8605a", y: "#7cc46b", z: "#5f9be8" };
+
+/** A point on a plane at (a, b) along its two axes. */
+function onPlane(plane, a, b) {
+  const [p, q] = PLANES[plane];
+  const v = { x: 0, y: 0, z: 0 };
+  v[p] = a;
+  v[q] = b;
+  return v;
+}
+
+function planeOf(plane) {
+  if (!PLANES[plane]) throw new Error(`Trid: unknown grid plane "${plane}" (use "xz", "xy" or "yz")`);
+  return plane;
+}
+
+/**
+ * A square grid of lines, centered on the origin: `divisions + 1` lines
+ * each way. A line-only mesh (`vertices` + `edges`).
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.size=4] - Width of the whole grid
+ * @param {number} [opts.divisions=40] - Cells along each side
+ * @param {"xz"|"xy"|"yz"} [opts.plane="xz"] - The plane it lies in ("xz" = a floor)
+ * @returns {{ vertices:{x,y,z}[], edges:number[][] }}
+ */
+export function gridMesh({ size = 4, divisions = 40, plane = "xz" } = {}) {
+  planeOf(plane);
+  const half = size / 2;
+  const n = Math.max(1, Math.round(divisions));
+  const vertices = [];
+  const edges = [];
+  for (let i = 0; i <= n; i++) {
+    const t = -half + (size * i) / n;
+    vertices.push(onPlane(plane, t, -half), onPlane(plane, t, half), onPlane(plane, -half, t), onPlane(plane, half, t));
+    const k = vertices.length;
+    edges.push([k - 4, k - 3], [k - 2, k - 1]);
+  }
+  return { vertices, edges };
+}
+
+/**
+ * A floor grid like 3D editors have, as one object to `scene.add`: thin
+ * minor lines, brighter major lines every `major` cells, the two axes
+ * through the origin in their colors (X red, Y green, Z blue), fading out
+ * toward the edge. It can't be picked (`pickable: false`).
+ *
+ * It's a group whose children are line-only meshes (one per color and
+ * fade step), so move, turn or hide it like any object.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.size=4] - Width of the whole grid
+ * @param {number} [opts.divisions=40] - Cells along each side
+ * @param {number} [opts.major=10] - A major line every this many cells (0: none)
+ * @param {"xz"|"xy"|"yz"} [opts.plane="xz"] - The plane it lies in ("xz" = a floor)
+ * @param {string} [opts.color="rgba(255, 255, 255, 0.12)"] - Minor lines
+ * @param {string} [opts.majorColor="rgba(255, 255, 255, 0.25)"] - Major lines
+ * @param {boolean|{[axis:string]:string}} [opts.axes=true] - Draw the axes; or their colors, like `{ x: "#f00" }`
+ * @param {boolean|number} [opts.fade=true] - Fade toward the edge; a number is where the fade starts
+ *   (0 = center, 1 = edge; `true` = 0.5). Needs colors written as hex, `rgb()` or `rgba()`
+ * @param {number} [opts.lineWidth=1] - Line width in pixels
+ * @returns {Object} A scene object (a group)
+ */
+export function gridHelper({
+  size = 4,
+  divisions = 40,
+  major = 10,
+  plane = "xz",
+  color = "rgba(255, 255, 255, 0.12)",
+  majorColor = "rgba(255, 255, 255, 0.25)",
+  axes = true,
+  fade = true,
+  lineWidth = 1,
+} = {}) {
+  planeOf(plane);
+  const [p, q] = PLANES[plane];
+  const half = size / 2;
+  const n = Math.max(1, Math.round(divisions));
+  const cell = size / n;
+  const axisColors = axes ? { ...AXIS_COLORS, ...(typeof axes === "object" ? axes : {}) } : null;
+  const fadeFrom = fade === false ? null : typeof fade === "number" ? Math.min(0.99, Math.max(0, fade)) : 0.5;
+
+  // Lines, sorted by color; with a fade each line is cut at every cell so its
+  // pieces can get fainter with distance (one object per color and step)
+  const STEPS = fadeFrom === null ? 1 : 8;
+  const groups = new Map(); // "color|step" → { color, step, vertices, edges }
+  const add = (css, a0, b0, a1, b1) => {
+    const pieces = fadeFrom === null ? 1 : n;
+    for (let k = 0; k < pieces; k++) {
+      const s = k / pieces, e = (k + 1) / pieces;
+      const pa = a0 + (a1 - a0) * s, pb = b0 + (b1 - b0) * s;
+      const qa = a0 + (a1 - a0) * e, qb = b0 + (b1 - b0) * e;
+      let step = 0;
+      if (fadeFrom !== null) {
+        // Distance of the piece's middle from the center: 0 → 1 at the edge (circle)
+        const r = Math.hypot((pa + qa) / 2, (pb + qb) / 2) / half;
+        if (r >= 1) continue;
+        step = r <= fadeFrom ? 0 : Math.min(STEPS - 1, 1 + Math.floor(((r - fadeFrom) / (1 - fadeFrom)) * (STEPS - 1)));
+      }
+      const key = css + "|" + step;
+      let g = groups.get(key);
+      if (!g) groups.set(key, (g = { css, step, vertices: [], edges: [] }));
+      g.vertices.push(onPlane(plane, pa, pb), onPlane(plane, qa, qb));
+      g.edges.push([g.vertices.length - 2, g.vertices.length - 1]);
+    }
+  };
+
+  const center = n / 2; // the line through the origin, when divisions is even
+  for (let i = 0; i <= n; i++) {
+    const t = -half + i * cell;
+    if (axisColors && i === center) continue; // the axes go there
+    // Major lines count from the origin (or from the edge when no line goes through it)
+    const from = Number.isInteger(center) ? i - center : i;
+    const css = major > 0 && from % major === 0 ? majorColor : color;
+    add(css, t, -half, t, half); // along the second axis
+    add(css, -half, t, half, t); // along the first axis
+  }
+  if (axisColors) {
+    add(axisColors[p], -half, 0, half, 0);
+    add(axisColors[q], 0, -half, 0, half);
+  }
+
+  const children = [];
+  for (const g of groups.values()) {
+    children.push({
+      name: "grid lines",
+      mesh: { vertices: g.vertices, edges: g.edges },
+      color: g.step === 0 ? g.css : fadeColor(g.css, 1 - g.step / STEPS),
+      lineWidth,
+    });
+  }
+  return { name: "grid", pickable: false, children };
+}
+
+/**
+ * A CSS color with its alpha multiplied by `k`, for hex, `rgb()` and
+ * `rgba()` colors; other colors come back unchanged.
+ */
+function fadeColor(css, k) {
+  const c = parseSimpleColor(css);
+  if (!c) return css;
+  return `rgba(${c[0]}, ${c[1]}, ${c[2]}, ${+(c[3] * k).toFixed(4)})`;
+}
+
+function parseSimpleColor(css) {
+  const s = String(css).trim();
+  let m = /^#([0-9a-f]{3,8})$/i.exec(s);
+  if (m) {
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) h = [...h].map((x) => x + x).join("");
+    if (h.length !== 6 && h.length !== 8) return null;
+    const v = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    return v.concat(h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1);
+  }
+  m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/i.exec(s);
+  if (m) {
+    let a = m[4] === undefined ? 1 : m[4].endsWith("%") ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
+    return [+m[1], +m[2], +m[3], a];
+  }
+  return null;
+}

package/trid/render/lights.js

@@ -0,0 +1,162 @@
+/**
+ * Lights: what makes faces bright or dark.
+ *
+ * A scene has a list of lights, `scene.lights`. Each one is a plain object:
+ *
+ *   { type: "ambient", color: "#ffffff", intensity: 0.25 }                  // everywhere, from every side
+ *   { type: "directional", direction: { x: -0.5, y: 1, z: -0.8 }, intensity: 0.75 } // like the sun
+ *   { type: "point", position: { x: 0, y: 1, z: 0 }, color: "#ffb070", intensity: 1, range: 3 } // like a bulb
+ *
+ * - `direction` is where the light comes **from** (it doesn't need to be unit length)
+ * - `color` is any CSS color (default white), `intensity` multiplies it (default 1)
+ * - `range`: a point light fades out smoothly and reaches nothing past it
+ *   (default: no fading)
+ * - `enabled: false` turns a light off without removing it
+ *
+ * Lights add up: a face gets the ambient lights, plus each other light
+ * times how much the face turns toward it. Both renderers use at most
+ * `MAX_LIGHTS` directional and point lights (ambient ones don't count).
+ *
+ * The default scene has an ambient light at 0.25 and a directional light
+ * at 0.75, so a face turned right at the light is exactly its own color.
+ */
+
+/** Direction light comes from when the scene doesn't set one: above, left, in front. */
+export const DEFAULT_LIGHT = { x: -0.5, y: 1, z: -0.8 };
+
+/** How bright a face turned fully away from the light still is (0..1). */
+export const DEFAULT_AMBIENT = 0.25;
+
+/** Most directional + point lights the renderers use; extra ones are ignored. */
+export const MAX_LIGHTS = 8;
+
+/**
+ * The default lights: an ambient light at `ambient`, and a white
+ * directional light from `direction` at `1 - ambient`.
+ *
+ * @param {{x:number,y:number,z:number}} [direction=DEFAULT_LIGHT]
+ * @param {number} [ambient=DEFAULT_AMBIENT]
+ * @returns {Object[]} A new list of lights
+ */
+export function defaultLights(direction = DEFAULT_LIGHT, ambient = DEFAULT_AMBIENT) {
+  return [
+    { type: "ambient", color: "#ffffff", intensity: ambient },
+    // The given direction object is kept (so changing it moves the light), the default is copied
+    { type: "directional", direction: direction === DEFAULT_LIGHT ? { ...DEFAULT_LIGHT } : direction, color: "#ffffff", intensity: 1 - ambient },
+  ];
+}
+
+let warnedTooMany = false;
+
+/**
+ * A scene's lights, ready for shading: colors parsed and multiplied by
+ * their intensity, directions made unit length.
+ *
+ * Reads `scene.lights`. A scene-like object without it (only `light` and
+ * `ambient`, like before Trid 0.4) gets the default pair built from those.
+ *
+ * @param {Object} scene
+ * @param {(css:string) => number[]} rgba - Parses a CSS color to [r, g, b, a] in 0..1
+ * @returns {{
+ *   ambient: number[],
+ *   ambientLevel: number,
+ *   lights: { point:boolean, dir:{x,y,z}|null, pos:{x,y,z}|null, color:number[], range:number }[],
+ *   mainDir: {x,y,z},
+ * }} `ambient` is the summed ambient color [r, g, b]; `ambientLevel` its brightest
+ *   channel; `mainDir` the unit direction of the first directional light (for effects)
+ */
+export function sceneLights(scene, rgba) {
+  const list = Array.isArray(scene.lights)
+    ? scene.lights
+    : defaultLights(scene.light ?? DEFAULT_LIGHT, scene.ambient ?? DEFAULT_AMBIENT);
+
+  const ambient = [0, 0, 0];
+  const lights = [];
+  let mainDir = null;
+  for (const l of list) {
+    if (!l || l.enabled === false) continue;
+    const k = l.intensity ?? 1;
+    const c = rgba(l.color ?? "#ffffff");
+    const color = [c[0] * k, c[1] * k, c[2] * k];
+    if (l.type === "ambient") {
+      for (let i = 0; i < 3; i++) ambient[i] += color[i];
+      continue;
+    }
+    if (lights.length >= MAX_LIGHTS) {
+      if (!warnedTooMany) {
+        warnedTooMany = true;
+        console.warn(`Trid: only the first ${MAX_LIGHTS} directional and point lights are used`);
+      }
+      continue;
+    }
+    if (l.type === "point") {
+      const p = l.position ?? { x: 0, y: 0, z: 0 };
+      lights.push({ point: true, dir: null, pos: { x: p.x, y: p.y, z: p.z }, color, range: l.range > 0 ? l.range : 0 });
+    } else {
+      const dir = unit(l.direction ?? DEFAULT_LIGHT);
+      mainDir ??= dir;
+      lights.push({ point: false, dir, pos: null, color, range: 0 });
+    }
+  }
+  return {
+    ambient,
+    ambientLevel: Math.max(...ambient),
+    lights,
+    mainDir: mainDir ?? unit(DEFAULT_LIGHT),
+  };
+}
+
+/**
+ * The light reaching a point, as [r, g, b] (can go above 1).
+ * The same math as the WebGL renderer's shader.
+ *
+ * @param {ReturnType<typeof sceneLights>} L - From `sceneLights`
+ * @param {{x,y,z}} n - Unit normal, world space
+ * @param {{x,y,z}} p - World position (for point lights)
+ * @returns {number[]}
+ */
+export function lightAt(L, n, p) {
+  const c = L.ambient.slice();
+  for (const l of L.lights) {
+    let d = l.dir, fade = 1;
+    if (l.point) {
+      const dx = l.pos.x - p.x, dy = l.pos.y - p.y, dz = l.pos.z - p.z;
+      const dist = Math.hypot(dx, dy, dz) || 1e-6;
+      d = { x: dx / dist, y: dy / dist, z: dz / dist };
+      fade = rangeFade(dist, l.range);
+    }
+    const k = Math.max(0, n.x * d.x + n.y * d.y + n.z * d.z) * fade;
+    if (k <= 0) continue;
+    c[0] += l.color[0] * k;
+    c[1] += l.color[1] * k;
+    c[2] += l.color[2] * k;
+  }
+  return c;
+}
+
+/**
+ * The single numbers effects get, from the light at a point:
+ * - `light`: its brightness (brightest channel)
+ * - `diffuse`: how much of it comes from the lights rather than the
+ *   ambient, 0..1 (with one light: how much the point faces it)
+ *
+ * @param {number[]} color - From `lightAt`
+ * @param {number} ambientLevel - From `sceneLights`
+ */
+export function lightLevels(color, ambientLevel) {
+  const light = Math.max(color[0], color[1], color[2]);
+  const diffuse = Math.min(1, Math.max(0, (light - ambientLevel) / Math.max(1 - ambientLevel, 1e-4)));
+  return { light, diffuse };
+}
+
+/** How much of a point light reaches `dist` away: 1 up close, 0 at `range` (0 = no fading). */
+export function rangeFade(dist, range) {
+  if (!(range > 0)) return 1;
+  const k = Math.min(1, Math.max(0, 1 - (dist * dist) / (range * range)));
+  return k * k;
+}
+
+function unit(v) {
+  const len = Math.hypot(v.x, v.y, v.z) || 1;
+  return { x: v.x / len, y: v.y / len, z: v.z / len };
+}