3draft 26.11.4010 → 26.11.5001

package/APP.md

@@ -10,7 +10,7 @@ It is one file, `app/index.html`, plus a dependency-free static server (`app/ser
 
 ## The view
 
-- **Starting view: WebGPU.** If WebGPU is unavailable, or the GPU device is lost, the app falls back to SVG by itself and says so in the footer (`G` or the `WebGPU` button switches by hand). SVG shows colour and transparency only; WebGPU also shows metal, roughness and emission. The **filmic look** (`C`) adds linear light, Fresnel and tone mapping, so highlights roll off softly and `lamp`-like materials glow; switch it off for the plain flat look.
+- **Starting view: WebGPU.** If WebGPU is unavailable, or the GPU device is lost, the app falls back to SVG by itself and says so in the footer (`G` or the `WebGPU` button switches by hand). SVG shows colour and transparency only; WebGPU also shows metal, roughness and emission. The **filmic look** (`C`) adds linear light, Fresnel and tone mapping, so highlights roll off softly and `lamp`-like materials glow; switch it off for the plain flat look. **Smooth** (`N`) shades faces that meet at less than 40 degrees as one round surface (box corners stay sharp), and **Studio** (`K`) lights the model with a key, a fill and a rim light that follow the camera; both are on at the start (WebGPU view only). The palette's `soft` slider gives a material skin-like light: it wraps round the form, with a warm band where light turns to shade.
 - **The drawing fills the stage.** On a desktop it covers the whole area; on a phone it is a little larger than the short side.
 - **Drag** rotates, **double click** resets the view, the arrow keys rotate too.
 - **The cross** follows the pointer and lies on the surface under it. The cursor is always a cross. On a phone, with no mouse, it aims at the middle.
@@ -22,10 +22,10 @@ It is one file, `app/index.html`, plus a dependency-free static server (`app/ser
 | --- | --- |
 | `w a s d r f` | fly: forward, left, back, right, up, down. Every press is a speed step; the opposite key slows down |
 | `Space` | stop moving (all speeds to zero) |
-| `T` | fly to the object under the cross. Over nothing, or when too close or inside a model: out to the nearest object |
+| `T` | target the object under the cross (see Target mode); with no target, `T` over empty space targets the nearest object. `Tab` next target (the first one when none), `Esc` let go |
 | `/` | show only the object under the cross; again: the whole scene, and the camera flies back to where it was |
 | `M` | place a prism on the surface under the cross, or shoot one into empty space. **In isolated mode (`/`) it fires a bullet** instead: a prism that starts at the camera point and flies along the ray through the cursor, so its long axis is always the view direction and you always see its back; if it hits the isolated object it sinks half its length and carves that part out (A − B, the cut is made of the selected material, `U` undoes it); if it misses it flies on to 4 times the camera-to-model distance and vanishes. Only the closed parts of the model are carved; open parts are ignored (see the health check below). A carve never leaves a crack: if the result would not be a closed solid it is retried with a hair's shift, and if that fails too the model stays as it was (the note "left as it was" shows). |
-| `Tab` | edit mode on the object under the cross / off (see below) |
+| `Q` | edit mode on the object under the cross / off (see below) |
 | `V` | Spider bar (in edit mode: draw a line): the first `V` remembers a surface point, the second joins the two with a thin prism (a quarter of the base of a placed one) made of the selected material. `V` over empty space forgets the first point |
 | `X`, `Delete` | delete the object under the cross |
 | `U`, `Backspace` | undo: placing, deleting, painting, booleans and moves, one step at a time |
@@ -37,6 +37,8 @@ It is one file, `app/index.html`, plus a dependency-free static server (`app/ser
 | `H` | move gizmo (see below) |
 | `E` | edges and points on / off (also the `Edges` button) |
 | `C` | filmic look on / off (also the `Filmic` button; on at the start, WebGPU view only) |
+| `N` | smooth shading on / off (the `Smooth` button; on at the start, WebGPU view only) |
+| `K` | studio light (key, fill, rim; follows the camera) on / off (the `Studio` button; on at the start, WebGPU view only) |
 | `G`, `L` | SVG / WebGPU, turn the light |
 | `?` | show / hide these shortcuts under the view (hidden at the start; also the `Keys` button) |
 
@@ -55,9 +57,9 @@ There is one gizmo at a time, and `H` cycles through three states:
 
 Drag one of the arrows to slide the object along that axis; the arrow thickens under the pointer. While dragging only the picture changes; one write goes to the database when you let go, and one `U` takes the whole drag back.
 
-## Edit mode: drawing on a model (`Tab`)
+## Edit mode: drawing on a model (`Q`)
 
-The idea: there is a base model, and you refine or extend it by drawing lines on it. Put the cross on an object and press `Tab`. A red bar at the top says which object is being edited. Its vertices show as small grey crosses.
+The idea: there is a base model, and you refine or extend it by drawing lines on it. Put the cross on an object and press `Q`. A red bar at the top says which object is being edited. Its vertices show as small grey crosses.
 
 - **`V` draws a line.** The first `V` takes a point, the next `V` joins it to the new one, and the chain goes on from there. A point is either an existing vertex (the pointer **snaps** to vertices; a white cross shows which) or a new vertex put on the surface under the cross. On a face it splits the face into triangles, on an edge it goes into both faces, so the surface never cracks.
 - **Two points on one face cut it.** The line becomes a real edge of the mesh: the surface gets detail exactly where you drew.
@@ -71,7 +73,7 @@ The idea: there is a base model, and you refine or extend it by drawing lines on
   - `V` goes back to drawing (and drops the selection); `Esc` does the same.
 - **`B` turns the spider bars into lines.** The prisms made with `V` in object mode (they are objects named `bar`) become lines on the edited object: each end snaps to a vertex that is close, or is put on the surface if it is near it, or stays a free point. The bars are removed (one `U` brings them back). So a plan sketched as bars can be worked on as a wire.
 - **`X`** removes the lines at the selected point or line (or the last line); the points stay. `U` undoes every step, one key press at a time.
-- **`Esc`** stops the line you are drawing; then it leaves a move mode back to drawing; then it leaves edit mode (so does `Tab`). The lines are only shown in edit mode.
+- **`Esc`** stops the line you are drawing; then it leaves a move mode back to drawing; then it leaves edit mode (so does `Q`). The lines are only shown in edit mode.
 
 The lines live next to the mesh as `wire: [[a, b], ...]` (vertex pairs) in the object's document, so the AI sees them too. The geometry is in the engine (README part 1): `insertVertex`, `cutFace`, `moveVertex`, `moveVertexSet`, `fillLoop`, `addLine`, `findLoop`.
 
@@ -99,11 +101,18 @@ Twelve starting materials: plaster, sand, wood, dark wood, concrete, slate, gras
 
 **Pick material (`I`, or the `pick` button):** the eyedropper. `I` takes the material of the face under the cross. The `pick` button arms it, and the next click on a surface takes it (`Esc` cancels). The palette opens and that material is selected, so you can read its sliders or paint with it right away. A face that has only a colour selects the material with that colour, or starts a new material from it.
 
-For the selected material there are four sliders (`metal`, `rough`, `alpha`, `emit`, 0 to 5) and a colour; `+ new` copies it as a new material. A painted face stores the material **name**, so editing a material changes every face made of it.
+For the selected material there are five sliders (`metal`, `rough`, `alpha`, `soft`, 0 to 1, and `emit`, 0 to 5) and a colour; `+ new` copies it as a new material. A painted face stores the material **name**, so editing a material changes every face made of it.
 
 ## Isolating, travelling
 
-`/` hides everything but the object under the cross and frames it. The camera pose from before is remembered and restored when you leave. `T` flies the camera to the object under the cross (nothing under it: out to the nearest object, which also gets you out of a model you are inside).
+`/` hides everything but the object under the cross and frames it. The camera pose from before is remembered and restored when you leave. 
+### Target mode
+
+The HUD in the top left corner shows the object under the cross (name, distance, face count) and the target.
+
+- `T` on an object **targets** it: the camera turns to face it and from then on moves on an imaginary sphere round it, always looking at its centre. `A`/`D` swing it sideways, `R`/`F` up and down (speed levels, like everywhere), `W`/`S` change the distance (`W` stops at the object's surface), and dragging the mouse turns it over the same sphere.
+- `T` on another object re-targets; `T` on the target or over empty space brings the camera back onto the target. There is no travel: `W` flies there.
+- `Tab` switches to the next object (`Shift+Tab`: previous). `Space` only sets the speed to zero. `Esc` lets go, and the camera then stays exactly where it is.
 
 ## Phone
 

package/README.md

@@ -56,18 +56,21 @@ The palette is data: `{ name: { color, metal, rough, alpha, emit } }`. A face po
 | `metal` 0..1 | paint ... metal | reflects sky and ground, tinted; strong highlight |
 | `rough` 0..1 | mirror ... matte | widens the highlight, blurs the reflection |
 | `alpha` 1..0 | solid ... invisible | blended in a second pass, far to near (SVG: `fill-opacity`, and a see-through face hides nothing) |
+| `soft` 0..1 | hard ... soft | skin-like light: it wraps round the form, and a warm scattered band shows where light turns to shade (WebGPU) |
 | `emit` 0..5 | lit ... glowing | up to 1 the colour fades to unshaded; above 1 (with `tonemap`) it is a light source, that many times brighter |
 
 Pass the palette to the renderers: `renderView(mesh, view, { palette })`, `gpu.render(mesh, view, { palette })` (a new object when an entry changes). SVG shows colour and alpha only.
 
 `gpu.render(mesh, view, { tonemap: true })` switches on a filmic look: lighting in linear colour, HDR light, Fresnel on the edges, ACES tone mapping, and `emit` that really glows above white (`tonemap: { exposure, emit }` to tune; off by default, so the plain look stays the same).
 
+`smooth: true` (or a crease angle in degrees, default 40) shades by corner normals: faces that meet at a shallow angle share their normals, so a faceted surface looks round, and a 90 degree box corner stays sharp (`cornerNormals(mesh, degrees)` is the pure helper). `studio: true` replaces the single sun with three lights that follow the camera: key (upper left), fill (right, softer) and a rim light from behind that edges the shape (`studio: { fill, rim }` to tune). Both are off by default.
+
 ### Surfaces, picking, editing
 
 - `pick(mesh, camera, x, y)` casts a real ray: face, point, normal, distance. `ray` is the inverse of `project`; `crosshair` builds a cross lying on the surface; `standOn` returns a prism standing on a picked surface.
 - `validate(mesh)` returns text notes: closed shell, winding, planar and convex faces. `extrudeFace`, `moveVertices`, `extrude`, `rotate`, `merge`, `bounds` shape meshes.
 - `boolean(a, b, op)` (also `union`, `subtract`, `intersect`) is solid modelling on BSP trees: faces are split by planes, so the result stays convex and planar. Both operands must be closed with outward faces; an open shell (a wall without thickness) is refused with the reason. With `{ strict: false }` the parts that are not closed solids are left out of the calculation instead (a union keeps them as they are, a subtract keeps those of `a`); `health(mesh)` is the check behind it: the connected parts, which are closed, and how many faces a boolean can work with. Face colours and materials are kept; cut faces take the colour of the cutting solid. The result is welded and T-junctions are repaired. A solid stays a solid: a result that is not a closed, consistently wound solid (numerical trouble with coincident faces) is thrown away and the operation is repeated with the second operand nudged by a tiny amount; if no try is sound it throws and the caller keeps the original.
-- **Drawing on a mesh** (`wire.ts`): `insertVertex(mesh, face, point)` puts a vertex on a surface (inside a face it makes a triangle fan, on an edge it joins both faces), `cutFace(mesh, a, b)` cuts a face along a line between two of its vertices, `moveVertex(mesh, i, to)` moves one (polygons that use it become triangles, so faces stay planar), `fillLoop(mesh, loop)` closes a loop of vertices into a face, `addLine` and `findLoop` keep the wire (a list of vertex pairs). These are what the viewer's edit mode (`Tab`, see [APP.md](APP.md)) uses.
+- **Drawing on a mesh** (`wire.ts`): `insertVertex(mesh, face, point)` puts a vertex on a surface (inside a face it makes a triangle fan, on an edge it joins both faces), `cutFace(mesh, a, b)` cuts a face along a line between two of its vertices, `moveVertex(mesh, i, to)` moves one (polygons that use it become triangles, so faces stay planar), `fillLoop(mesh, loop)` closes a loop of vertices into a face, `addLine` and `findLoop` keep the wire (a list of vertex pairs). These are what the viewer's edit mode (`Q`, see [APP.md](APP.md)) uses.
 - **HEXAW kernel.** The picking hot loop is also written in [HEXAW](https://github.com/Pengeszikra/hexaw) (`kernel/pick.hexaw`, 569 bytes of WebAssembly). `initKernel()` starts it; `kernel.pick` returns exactly what `pick` returns, 0.14 ms instead of 1.7 ms on 7200 faces. The module is embedded as base64 (`src/kernel-bytes.ts`), so the engine needs neither HEXAW nor a fetch at runtime. `npm run kernel` re-assembles it.
 
 ### TypeScript and `|>`
@@ -92,6 +95,60 @@ A single `app/index.html` plus a dependency-free static server. Person and AI wo
 
 **How to use it, all keys and the database layout: [APP.md](APP.md).**
 
+### Keys
+
+**Moving and looking**
+
+| Key | What it does |
+|---|---|
+| drag | turns the view (in target mode: moves the camera over the sphere round the target) |
+| arrow keys | turn the view in steps |
+| `W` / `S` | forward / back: speed levels, every press is one step more or less |
+| `A` / `D` | left / right (speed levels) |
+| `R` / `F` | up / down (speed levels) |
+| `Space` | speed to zero (the target stays) |
+| `/` | show only the model under the cross; again: the whole scene |
+
+**Target mode**
+
+| Key | What it does |
+|---|---|
+| `T` | target the object under the cross; with a target: another object re-targets, the target itself or empty space brings the camera back onto it; with no target over empty space: the nearest object |
+| `Tab` / `Shift+Tab` | next / previous target (the first one when there is none) |
+| `Esc` | let go; the camera stays where it is |
+| `A D R F`, `W S`, drag | swing round the target, closer or farther (`W` stops at the surface) |
+
+**Editing and objects**
+
+| Key | What it does |
+|---|---|
+| `Q` | edit mode on / off |
+| `V` | spider bar between two points; in edit mode: draw a line |
+| `Enter` | edit mode: close a loop into a face |
+| `B` | edit mode: turn the old `V` bars into lines |
+| `1` / `2` / `3` | edit mode: move points / lines / faces |
+| `M` | put a prism down; in isolated mode: shoot it (it carves) |
+| `O` | boolean: mark two objects, then pick the operation |
+| `X` | delete the object under the cross |
+| `H` | move gizmo: 1st world axes, 2nd own axes, 3rd off |
+| `U` / `Backspace` | undo |
+
+**Material and look**
+
+| Key | What it does |
+|---|---|
+| `P` | material palette (Shift+click paints a face, Shift+double click the whole object) |
+| `I` | pick the material under the cross |
+| `G` | SVG / WebGPU view |
+| `C` | filmic look |
+| `N` | smooth shading |
+| `K` | studio light |
+| `L` | turn the light |
+| `E` | edges and points on / off |
+| `?` | show / hide the key hints |
+
+In edit mode `Esc` first stops the line being drawn, then leaves a move mode, then leaves edit mode (and keeps the target).
+
 ---
 
 ## 3. Engine and LLM
@@ -106,7 +163,7 @@ The engine is small enough to read whole (about 2000 lines) and everything it wo
 
 Y is up, the ground is y = 0, faces are counter-clockwise seen from outside.
 
-Examples: `examples/table.js`, `examples/bridge.js` (50 named objects), `examples/cessna.js` (one mesh, 9 colours), and `examples/house.js` (a house converted from Blender with `tools/blend/`, 45 objects, approximate colours).
+Examples: `examples/table.js`, `examples/bridge.js` (50 named objects), `examples/cessna.js` (one mesh, 9 colours), and `examples/head.js` (a stylized head: 7 objects with their own palette, soft skin; try N and K), and `examples/house.js` (a house converted from Blender with `tools/blend/`, 45 objects, approximate colours).
 
 ---
 

package/dist/gpu.d.ts

@@ -39,6 +39,19 @@ export interface GpuRenderOptions {
         exposure?: number;
         emit?: number;
     };
+    /**
+     * Smooth shading: faces that meet at an angle smaller than this (degrees; `true` = 40) share their normals, so a curved
+     * surface made of flat faces looks round and sharper corners stay crisp. Off by default (every face flat).
+     */
+    smooth?: boolean | number;
+    /**
+     * Studio light: three lights that follow the camera instead of one fixed sun: a key light (upper left), a fill light
+     * (right, softer) and a rim light from behind that edges the shape. Off by default.
+     */
+    studio?: boolean | {
+        fill?: number;
+        rim?: number;
+    };
 }
 /** One copy of a prototype: its position, orthonormal frame and color. */
 export interface Instance {
@@ -64,8 +77,19 @@ export interface Gpu {
  * like camera.project(): the same pixels, plus a depth between near and far.
  */
 export declare const viewProjection: (cam: Camera, near?: number, far?: number) => Float32Array;
-/** Triangle list for the GPU: flat face normals, face colors and materials. Float32Array, 13 floats per vertex. */
-export declare const buildVertices: (mesh: Mesh, palette?: Palette) => Float32Array;
+/**
+ * Smooth shading: a normal for every corner of every face. The faces that meet at a point (welded by position, so a
+ * crack in the indices does not break it) are averaged, weighted by area, but only those within `crease` degrees of
+ * this face: a 90 degree box corner stays sharp, a faceted fuselage becomes round.
+ */
+export declare const cornerNormals: (mesh: Mesh, crease: number) => Vec3[][];
+/**
+ * Triangle list for the GPU: face normals (flat, or smoothed with `smooth` degrees), face colors and materials.
+ * Float32Array, 14 floats per vertex.
+ */
+export declare const buildVertices: (mesh: Mesh, palette?: Palette, { smooth }?: {
+    smooth?: number;
+}) => Float32Array;
 /**
  * Per-instance data for drawInstances: one entry { at, axes: [ex, ey, ez], color } per copy of a
  * prototype mesh (modelled around the origin). Float32Array, 15 floats per instance.
@@ -80,7 +104,8 @@ export declare const defaultMaterial: Required<GpuMaterial>;
  * prototype mesh, data from buildInstances; drawn after the mesh), background [r,g,b] 0..1,
  * light { direction, sky, ground }, material { ambient, diffuse, specular, shininess }, dpr.
  */
-export declare const createGpu: (canvas: HTMLCanvasElement, { sampleCount }?: {
+export declare const createGpu: (canvas: HTMLCanvasElement, { sampleCount, onError }?: {
     sampleCount?: number;
+    onError?: (message: string) => void;
 }) => Promise<Gpu>;
 export {};

package/dist/gpu.js

@@ -3,10 +3,10 @@
 // the cross marks and the framing all stay valid. The pure helpers (viewProjection,
 // buildVertices) need no GPU and are unit tested; createGpu() needs a browser.
 import { dot, norm } from './vec.js';
-import { faceNormal } from './mesh.js';
+import { bounds, faceNormal } from './mesh.js';
 import { makeCamera } from './camera.js';
 import { surfaceOf } from './material.js';
-const FLOATS = 13; // position(3) normal(3) color(3) material(4: metal, rough, alpha, emit)
+const FLOATS = 14; // position(3) normal(3) color(3) material(4: metal, rough, alpha, emit) soft(1)
 /**
  * Column-major 4x4 matrix (for WebGPU, z in 0..1) that maps world points exactly
  * like camera.project(): the same pixels, plus a depth between near and far.
@@ -29,26 +29,60 @@ const rgb = (color) => {
         return [0.78, 0.78, 0.78];
     return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
 };
-/** Triangle list for the GPU: flat face normals, face colors and materials. Float32Array, 13 floats per vertex. */
-export const buildVertices = (mesh, palette) => {
+/**
+ * Smooth shading: a normal for every corner of every face. The faces that meet at a point (welded by position, so a
+ * crack in the indices does not break it) are averaged, weighted by area, but only those within `crease` degrees of
+ * this face: a 90 degree box corner stays sharp, a faceted fuselage becomes round.
+ */
+export const cornerNormals = (mesh, crease) => {
+    const cosC = Math.cos((crease * Math.PI) / 180);
+    const area = mesh.faces.map((f) => faceNormal(f.v.map((k) => mesh.positions[k]))); // length = area
+    const unit = area.map((n) => (Math.hypot(...n) > 0 ? norm(n) : [0, 1, 0]));
+    const q = (bounds(mesh).radius || 1) * 1e-6;
+    const key = (p) => `${Math.round(p[0] / q)},${Math.round(p[1] / q)},${Math.round(p[2] / q)}`;
+    const at = new Map();
+    mesh.faces.forEach((f, i) => f.v.forEach((k) => {
+        const id = key(mesh.positions[k]);
+        const list = at.get(id) ?? [];
+        if (list[list.length - 1] !== i)
+            list.push(i);
+        at.set(id, list);
+    }));
+    return mesh.faces.map((f, i) => f.v.map((k) => {
+        const sum = [0, 0, 0];
+        for (const j of at.get(key(mesh.positions[k])) ?? []) {
+            if (dot(unit[i], unit[j]) < cosC)
+                continue;
+            for (let c = 0; c < 3; c++)
+                sum[c] += area[j][c];
+        }
+        return Math.hypot(...sum) > 0 ? norm(sum) : unit[i];
+    }));
+};
+/**
+ * Triangle list for the GPU: face normals (flat, or smoothed with `smooth` degrees), face colors and materials.
+ * Float32Array, 14 floats per vertex.
+ */
+export const buildVertices = (mesh, palette, { smooth = 0 } = {}) => {
     let tris = 0;
     for (const f of mesh.faces)
         tris += Math.max(0, f.v.length - 2);
     const out = new Float32Array(tris * 3 * FLOATS);
+    const corners = smooth > 0 ? cornerNormals(mesh, smooth) : null;
     let o = 0;
-    for (const face of mesh.faces) {
+    mesh.faces.forEach((face, fi) => {
         const pts = face.v.map((k) => mesh.positions[k]);
-        const n = norm(faceNormal(pts));
+        const flat = norm(faceNormal(pts));
         const s = surfaceOf(face, palette);
         const c = rgb(s.color);
         const mat = [s.metal, s.rough, s.alpha, s.emit];
         for (let j = 1; j < pts.length - 1; j++) {
-            for (const p of [pts[0], pts[j], pts[j + 1]]) {
-                out.set([...p, ...n, ...c, ...mat], o);
+            for (const k of [0, j, j + 1]) {
+                out.set([...pts[k], ...(corners ? corners[fi][k] : flat), ...c, ...mat, s.soft], o);
                 o += FLOATS;
             }
         }
-    }
+    });
     return out;
 };
 const INSTANCE_FLOATS = 15; // at(3) ex(3) ey(3) ez(3) color(3)
@@ -71,17 +105,20 @@ struct U {
   ground : vec4<f32>,
   eye : vec4<f32>,
   mat : vec4<f32>,     // ambient, diffuse, specular, shininess
-  fx : vec4<f32>,      // filmic (0 or 1), exposure, emission gain
+  fx : vec4<f32>,      // filmic (0 or 1), exposure, emission gain, studio (0 or 1)
+  fill : vec4<f32>,    // studio: xyz direction towards the fill light, w intensity
+  rim : vec4<f32>,     // studio: xyz direction towards the rim light, w intensity
 };
 @group(0) @binding(0) var<uniform> u : U;
 
-struct VIn { @location(0) pos : vec3<f32>, @location(1) nrm : vec3<f32>, @location(2) col : vec3<f32>, @location(8) mat : vec4<f32> };
+struct VIn { @location(0) pos : vec3<f32>, @location(1) nrm : vec3<f32>, @location(2) col : vec3<f32>, @location(8) mat : vec4<f32>, @location(9) soft : f32 };
 struct VOut {
   @builtin(position) p : vec4<f32>,
   @location(0) n : vec3<f32>,
   @location(1) c : vec3<f32>,
   @location(2) w : vec3<f32>,
   @location(3) m : vec4<f32>,   // metal, rough, alpha, emit
+  @location(4) s : f32,         // soft
 };
 
 @vertex fn vs(i : VIn) -> VOut {
@@ -91,6 +128,7 @@ struct VOut {
   o.c = i.col;
   o.w = i.pos;
   o.m = i.mat;
+  o.s = i.soft;
   return o;
 }
 
@@ -110,6 +148,7 @@ struct IIn {
   o.c = i.col;
   o.w = w;
   o.m = vec4<f32>(0.0, 0.7, 1.0, 0.0);
+  o.s = 0.0;
   return o;
 }
 
@@ -124,16 +163,39 @@ fn aces(x : vec3<f32>) -> vec3<f32> {
   return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3<f32>(0.0), vec3<f32>(1.0));
 }
 
+// Direct light, shared by both looks: x diffuse, y highlight, z scattered light (soft materials).
+// Studio: the key light is u.light (placed by the camera), plus a softer fill and a rim light that only edges the shape.
+fn lights(n : vec3<f32>, v : vec3<f32>, shin : f32, soft : f32) -> vec3<f32> {
+  let key = normalize(u.light.xyz);
+  let ndl = dot(n, key);
+  // soft: the light wraps round the form, and a warm band of scattered light sits where light turns to shade
+  var diff = max((ndl + soft) / (1.0 + soft), 0.0);
+  let h = normalize(key + v);
+  var spec = pow(max(dot(n, h), 0.0), shin) * step(0.0, ndl);
+  let scat = soft * exp(-ndl * ndl * 5.0);
+  if (u.fx.w > 0.5) {
+    diff = diff * 0.85; // three lights add up: the key takes a little less
+    let fl = normalize(u.fill.xyz);
+    diff = diff + max((dot(n, fl) + soft) / (1.0 + soft), 0.0) * u.fill.w;
+    let rl = normalize(u.rim.xyz);
+    let edge = pow(1.0 - max(dot(n, v), 0.0), 2.5);
+    diff = diff + max(dot(n, rl), 0.0) * edge * u.rim.w * 2.0;
+    let rh = normalize(rl + v);
+    spec = spec + pow(max(dot(n, rh), 0.0), shin) * step(0.0, dot(n, rl)) * u.rim.w * 0.6 * edge;
+  }
+  return vec3<f32>(diff, spec, scat);
+}
+
 // The filmic path: the same light model, but in linear colour with HDR light and emission, then tone mapped.
 fn filmic(i : VOut, n : vec3<f32>, l : vec3<f32>, v : vec3<f32>) -> vec4<f32> {
   let metal = i.m.x;
   let rough = i.m.y;
   let albedo = toLinear(i.c);
-  let hemi = mix(toLinear(u.ground.rgb), toLinear(u.sky.rgb), n.y * 0.5 + 0.5) * u.mat.x;
-  let diff = max(dot(n, l), 0.0) * u.mat.y * 1.6;
-  let h = normalize(l + v);
+  let hemi = mix(toLinear(u.ground.rgb), toLinear(u.sky.rgb), n.y * 0.5 + 0.5) * u.mat.x * select(1.0, 0.7, u.fx.w > 0.5);
   let shin = mix(u.mat.w * 7.0, u.mat.w * 0.15, rough);
-  let spec = pow(max(dot(n, h), 0.0), shin) * mix(u.mat.z, 1.0, metal) * mix(1.0, 0.35, rough) * step(0.0, dot(n, l)) * 2.5;
+  let lt = lights(n, v, shin, i.s);
+  let diff = lt.x * u.mat.y * 1.6;
+  let spec = lt.y * mix(u.mat.z, 1.0, metal) * mix(1.0, 0.35, rough) * 2.5;
   let r = reflect(-v, n);
   // Schlick: edges mirror more, metal keeps its tint
   let f0 = mix(vec3<f32>(0.04), albedo, metal);
@@ -144,6 +206,7 @@ fn filmic(i : VOut, n : vec3<f32>, l : vec3<f32>, v : vec3<f32>) -> vec4<f32> {
           + env * fres * (1.0 - rough) * 0.5
           + vec3<f32>(spec) * mix(vec3<f32>(1.0), albedo, metal);
   // emission adds light, so a lamp can go above 1.0 and still keep its colour after tone mapping
+  lit = lit + albedo * vec3<f32>(1.0, 0.38, 0.26) * lt.z * 0.5 * (1.0 - metal); // soft: the warm scattered band
   lit = lit + albedo * i.m.w * u.fx.z;
   return vec4<f32>(toSrgb(aces(lit * u.fx.y)), i.m.z);
 }
@@ -156,18 +219,19 @@ fn filmic(i : VOut, n : vec3<f32>, l : vec3<f32>, v : vec3<f32>) -> vec4<f32> {
   if (u.fx.x > 0.5) { return filmic(i, n, l, v); }
   let metal = i.m.x;
   let rough = i.m.y;
-  let hemi = mix(u.ground.rgb, u.sky.rgb, n.y * 0.5 + 0.5) * u.mat.x;
-  let diff = max(dot(n, l), 0.0) * u.mat.y;
-  let h = normalize(l + v);
+  let hemi = mix(u.ground.rgb, u.sky.rgb, n.y * 0.5 + 0.5) * u.mat.x * select(1.0, 0.7, u.fx.w > 0.5);
   // roughness widens the highlight; metal makes it strong and tinted by the color
   let shin = mix(u.mat.w * 7.0, u.mat.w * 0.15, rough);
-  let spec = pow(max(dot(n, h), 0.0), shin) * mix(u.mat.z, 1.0, metal) * mix(1.0, 0.35, rough) * step(0.0, dot(n, l));
+  let lt = lights(n, v, shin, i.s);
+  let diff = lt.x * u.mat.y;
+  let spec = lt.y * mix(u.mat.z, 1.0, metal) * mix(1.0, 0.35, rough);
   // metal mirrors the sky above and the ground below, blurred by roughness
   let r = reflect(-v, n);
   let env = mix(u.ground.rgb * 1.2, u.sky.rgb * 1.5, smoothstep(-0.25 - rough * 0.5, 0.25 + rough * 0.5, r.y));
   var lit = i.c * (hemi + vec3<f32>(diff)) * (1.0 - metal)
           + i.c * env * metal * (1.0 - 0.6 * rough)
-          + vec3<f32>(spec) * mix(vec3<f32>(1.0), i.c, metal);
+          + vec3<f32>(spec) * mix(vec3<f32>(1.0), i.c, metal)
+          + i.c * vec3<f32>(1.0, 0.38, 0.26) * lt.z * 0.25 * (1.0 - metal);
   lit = mix(lit, i.c * 1.15, min(i.m.w, 1.0)); // the plain look: emit 0..1 fades to flat colour, more does not add
   return vec4<f32>(clamp(lit, vec3<f32>(0.0), vec3<f32>(1.0)), i.m.z);
 }
@@ -179,14 +243,18 @@ fn filmic(i : VOut, n : vec3<f32>, l : vec3<f32>, v : vec3<f32>) -> vec4<f32> {
  * prototype mesh, data from buildInstances; drawn after the mesh), background [r,g,b] 0..1,
  * light { direction, sky, ground }, material { ambient, diffuse, specular, shininess }, dpr.
  */
-export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
+export const createGpu = async (canvas, { sampleCount = 4, onError } = {}) => {
     if (!globalThis.navigator?.gpu)
         throw new Error('WebGPU is not available in this browser');
     const adapter = await navigator.gpu.requestAdapter();
     if (!adapter)
         throw new Error('No WebGPU adapter found');
     const device = await adapter.requestDevice();
-    device.addEventListener('uncapturederror', (e) => console.error('WebGPU:', e.error?.message ?? e));
+    device.addEventListener('uncapturederror', (e) => {
+        const message = String(e.error?.message ?? e);
+        console.error('WebGPU:', message);
+        onError?.(message);
+    });
     device.lost.then((info) => console.error('WebGPU device lost:', info.reason, info.message));
     const context = canvas.getContext('webgpu');
     if (!context)
@@ -194,6 +262,12 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
     const format = navigator.gpu.getPreferredCanvasFormat();
     context.configure({ device, format, alphaMode: 'opaque', });
     const module = device.createShaderModule({ code: SHADER });
+    // shader compile errors are reported to onError too (the browser only logs them to the console)
+    module.getCompilationInfo?.().then((info) => {
+        for (const m of info.messages ?? [])
+            if (m.type === 'error')
+                onError?.(`shader line ${m.lineNum}: ${m.message}`);
+    });
     const meshLayout = {
         arrayStride: FLOATS * 4,
         attributes: [
@@ -201,6 +275,7 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
             { shaderLocation: 1, offset: 12, format: 'float32x3' },
             { shaderLocation: 2, offset: 24, format: 'float32x3' },
             { shaderLocation: 8, offset: 36, format: 'float32x4' },
+            { shaderLocation: 9, offset: 52, format: 'float32' },
         ],
     };
     const instanceLayout = {
@@ -208,8 +283,14 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
         stepMode: 'instance',
         attributes: [3, 4, 5, 6, 7].map((loc, k) => ({ shaderLocation: loc, offset: k * 12, format: 'float32x3' })),
     };
+    // ONE explicit layout for every pipeline: with 'auto' each pipeline gets its own, and a bind group made for one is refused by the others
+    const bindLayout = device.createBindGroupLayout({
+        // visibility 1 | 2 = GPUShaderStage.VERTEX | FRAGMENT
+        entries: [{ binding: 0, visibility: 1 | 2, buffer: { type: 'uniform' } }],
+    });
+    const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindLayout] });
     const make = (entry, buffers, glass = false) => device.createRenderPipeline({
-        layout: 'auto',
+        layout: pipelineLayout,
         vertex: { module, entryPoint: entry, buffers },
         fragment: {
             module,
@@ -235,12 +316,13 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
     const glassPipeline = make('vs', [meshLayout], true);
     // the instanced pipeline reads position and normal only from the prototype (locations 0, 1)
     const instPipeline = make('vsi', [{ ...meshLayout, attributes: meshLayout.attributes.slice(0, 2) }, instanceLayout]);
-    const uniforms = device.createBuffer({ size: 160, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-    const bind = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uniforms } }] });
-    const instBind = device.createBindGroup({ layout: instPipeline.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uniforms } }] });
+    const uniforms = device.createBuffer({ size: 192, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const bind = device.createBindGroup({ layout: bindLayout, entries: [{ binding: 0, resource: { buffer: uniforms } }] });
+    const instBind = device.createBindGroup({ layout: bindLayout, entries: [{ binding: 0, resource: { buffer: uniforms } }] });
     // Geometry that did not change since the last frame is not rebuilt or uploaded again.
     let uploaded = null; // the mesh now in vertexBuffer
     let uploadedPalette; // and the palette it was built with
+    let uploadedSmooth = 0; // and the smoothing
     let vertexCount = 0;
     let protoMesh = null;
     let protoBuffer = null;
@@ -271,14 +353,16 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
         depth = device.createTexture({ size: [n, n], format: 'depth24plus', sampleCount, usage: GPUTextureUsage.RENDER_ATTACHMENT });
         color = sampleCount > 1 ? device.createTexture({ size: [n, n], format, sampleCount, usage: GPUTextureUsage.RENDER_ATTACHMENT }) : null;
     };
-    const draw = (mesh, view, { size = 400, fit, background = [0.98, 0.98, 0.97], light = {}, material = {}, palette, dpr = globalThis.devicePixelRatio || 1, instances, tonemap = false } = {}, readback = false) => {
+    const draw = (mesh, view, { size = 400, fit, background = [0.98, 0.98, 0.97], light = {}, material = {}, palette, dpr = globalThis.devicePixelRatio || 1, instances, tonemap = false, smooth = false, studio = false } = {}, readback = false) => {
         const L = { ...defaultLight, ...light };
         const filmic = tonemap ? { exposure: 1, emit: 2, ...(tonemap === true ? {} : tonemap) } : null;
         const M = { ...defaultMaterial, ...material };
         const cam = makeCamera(view, mesh, size, fit);
         targets(Math.max(1, Math.round(size * dpr)));
-        if (mesh !== uploaded || palette !== uploadedPalette) {
-            const all = buildVertices(mesh, palette);
+        const crease = smooth === true ? 40 : smooth || 0;
+        if (mesh !== uploaded || palette !== uploadedPalette || crease !== uploadedSmooth) {
+            uploadedSmooth = crease;
+            const all = buildVertices(mesh, palette, { smooth: crease });
             // split: solid triangles are drawn first; triangles with alpha < 1 are kept apart and blended afterwards
             const tri = 3 * FLOATS;
             const solid = [];
@@ -346,14 +430,19 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
         }
         if (!glassTris.length)
             glassCount = 0;
-        const u = new Float32Array(40);
+        // studio rig, relative to the camera: key upper left in front, fill from the right, rim from behind and above
+        const rig = (f, r, up) => norm([0, 1, 2].map((k) => -cam.f[k] * f + cam.r[k] * r + cam.u[k] * up));
+        const S = studio ? { fill: 0.4, rim: 1, ...(studio === true ? {} : studio) } : null;
+        const u = new Float32Array(48);
         u.set(viewProjection(cam), 0);
-        u.set([...(norm(L.direction)), 0], 16);
+        u.set([...(S ? rig(0.7, -0.5, 0.6) : norm(L.direction)), 0], 16);
         u.set([...L.sky, 0], 20);
         u.set([...L.ground, 0], 24);
         u.set([...cam.eye, 0], 28);
         u.set([M.ambient, M.diffuse, M.specular, M.shininess], 32);
-        u.set([filmic ? 1 : 0, filmic ? filmic.exposure : 1, filmic ? filmic.emit : 0, 0], 36);
+        u.set([filmic ? 1 : 0, filmic ? filmic.exposure : 1, filmic ? filmic.emit : 0, S ? 1 : 0], 36);
+        u.set([...rig(0.6, 0.8, 0.1), S ? S.fill : 0], 40);
+        u.set([...rig(-0.8, 0.3, 0.5), S ? S.rim : 0], 44);
         device.queue.writeBuffer(uniforms, 0, u);
         const encoder = device.createCommandEncoder();
         const offscreen = readback

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export declare const name: "3draft";
-export declare const version = "26.11.4010";
+export declare const version = "26.11.5001";
 export type { Vec3, Face, Mesh, Axes, ViewName, ViewSpec, Fit, Camera, Hit, Mark } from './types.js';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export type { BoxOptions } from './mesh.js';
@@ -14,7 +14,7 @@ export { standOn } from './place.js';
 export type { StandOptions, Frame } from './place.js';
 export { paintOrder } from './order.js';
 export type { PaintItem } from './order.js';
-export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
+export { createGpu, viewProjection, buildVertices, cornerNormals, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
 export type { Gpu, GpuLight, GpuMaterial, GpuRenderOptions, Instance, Pixels } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
 export type { RenderOptions } from './svg.js';

package/dist/index.js

@@ -4,7 +4,7 @@
 // a target cross that lies on the surface under the cursor. No textures, no
 // shading yet.
 export const name = '3draft';
-export const version = '26.11.4010';
+export const version = '26.11.5001';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export { validate } from './check.js';
 export { boolean, union, subtract, intersect, health } from './csg.js';
@@ -13,7 +13,7 @@ export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
 export { pick, crosshair } from './pick.js';
 export { standOn } from './place.js';
 export { paintOrder } from './order.js';
-export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
+export { createGpu, viewProjection, buildVertices, cornerNormals, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
 export { surfaceOf, DEFAULTS as MATERIAL_DEFAULTS } from './material.js';
 export { displayVersion } from './version.js';

package/dist/material.d.ts

@@ -10,6 +10,8 @@ export interface Material {
     alpha?: number;
     /** 0..5: how much the color glows on its own, unlit. Up to 1 it fades from lit to flat colour; above 1 (WebGPU `tonemap`) it is a light source: that many times brighter. */
     emit?: number;
+    /** 0..1: soft, skin-like light. The light wraps round the form and a warm, scattered band shows where light turns to shade. */
+    soft?: number;
 }
 export type Palette = Record<string, Material>;
 /** What a face is made of, all numbers filled in. */
@@ -19,6 +21,7 @@ export interface Surface {
     rough: number;
     alpha: number;
     emit: number;
+    soft: number;
 }
 export declare const EMIT_MAX = 5;
 export declare const FALLBACK_COLOR = "#c8c8c8";
@@ -27,6 +30,7 @@ export declare const DEFAULTS: {
     readonly rough: 0.7;
     readonly alpha: 1;
     readonly emit: 0;
+    readonly soft: 0;
 };
 /** The surface of a face: its palette entry when it names one, else just its color with default properties. */
 export declare const surfaceOf: (face: Pick<Face, "color" | "mat">, palette?: Palette) => Surface;

package/dist/material.js

@@ -4,7 +4,7 @@
 const clamp = (n, fallback, max = 1) => (typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(max, n)) : fallback);
 export const EMIT_MAX = 5;
 export const FALLBACK_COLOR = '#c8c8c8';
-export const DEFAULTS = { metal: 0, rough: 0.7, alpha: 1, emit: 0 };
+export const DEFAULTS = { metal: 0, rough: 0.7, alpha: 1, emit: 0, soft: 0 };
 /** The surface of a face: its palette entry when it names one, else just its color with default properties. */
 export const surfaceOf = (face, palette) => {
     const m = face.mat !== undefined ? palette?.[face.mat] : undefined;
@@ -14,5 +14,6 @@ export const surfaceOf = (face, palette) => {
         rough: clamp(m?.rough, DEFAULTS.rough),
         alpha: clamp(m?.alpha, DEFAULTS.alpha),
         emit: clamp(m?.emit, DEFAULTS.emit, EMIT_MAX),
+        soft: clamp(m?.soft, DEFAULTS.soft),
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3draft",
-  "version": "26.11.4010",
+  "version": "26.11.5001",
   "description": "Minimalist AI first 3D engine: palette-texture, WASM core, WebGPU/WebGL2 renderer.",
   "type": "module",
   "main": "./dist/index.js",