3draft 26.11.2005 → 26.11.3001

package/APP.md

@@ -0,0 +1,89 @@
+# 3Draft viewer: how to use it
+
+The viewer is the human side of 3Draft: a person and an AI look at, and edit, the same scene. The engine is described in the [README](README.md); this page is only about the app.
+
+```sh
+npm run app     # http://localhost:5173/app/   (repo only, not in the npm package)
+```
+
+It is one file, `app/index.html`, plus a dependency-free static server (`app/serve.js`, localhost only). The same page is published as a Claude artifact, where the scene lives in a shared database. When the MCP server serves it, everything the AI builds appears live.
+
+## 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 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.
+- **Footer:** yaw, pitch, fly speed, which code answers picking (`pick hexaw` = the WebAssembly kernel), object count, live link, and the face under the cross.
+
+## Keys
+
+| key | does |
+| --- | --- |
+| `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 |
+| `/` | 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 |
+| `V` | Spider bar: the first `V` remembers a surface point, the second joins the two with a thin prism. `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 |
+| `P` | show / hide the material palette |
+| `Shift` + press | paint the face under the cross with the selected material (palette must be on) |
+| `Shift` + double click | paint the whole object |
+| `O` | boolean (see below) |
+| `H` | move gizmo (see below) |
+| `E` | edges and points on / off (also the `Edges` button) |
+| `G`, `L` | SVG / WebGPU, turn the light |
+| `?` | show / hide these shortcuts under the view (hidden at the start; also the `Keys` button) |
+
+## Moving an object: the gizmo (`H`)
+
+There is one gizmo at a time, and `H` cycles through three states:
+
+1. **First `H`**: the gizmo appears on the object under the cross, on the world axes (x red, y green, z blue).
+2. **Second `H`**: it turns to the object's own axes. Objects carry no transform, so these come from the shape: y stays up, x and z follow the turn around y that fits the footprint best (an object that already lines up with the world axes looks the same in both states).
+3. **Third `H`**: the gizmo goes away.
+
+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.
+
+## Boolean operations (`O`)
+
+Press `O` over an object: it gets an orange box. Press `O` over another one (green box): a small question asks which operation to run.
+
+| key | operation |
+| --- | --- |
+| `1` | union |
+| `2` | A − B (A is the orange one) |
+| `3` | B − A |
+| `4` | intersect |
+| `5`, `Esc` | cancel |
+
+The result is a new object named like `A-B` and it replaces both operands; `U` brings the two originals back and removes the result. `O` over empty space forgets a marked object.
+
+The math is the engine's `boolean(a, b, op)` (README, part 1). Both objects must be **closed solids with outward faces**. An open shell, such as a wall without thickness, is refused with the reason in the dialog. With messy data (coincident faces) the result can come out open; the engine's `validate` says so.
+
+## Materials (`P`)
+
+Twelve starting materials: plaster, sand, wood, dark wood, concrete, slate, grass, brick, steel, gold, glass, lamp. Pick one, then `Shift`+press to paint a face or `Shift`+double click for the whole object.
+
+For the selected material there are four sliders (`metal`, `rough`, `alpha`, `emit`) 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).
+
+## Phone
+
+Four round buttons cover the main actions: travel, place, delete, and the view mode. Drag rotates; the cross aims at the middle of the screen.
+
+## One object model and the database
+
+Objects that come from outside (the database, the MCP server) and objects made in the app are the same thing: `{ id, name, mesh }`. Painting, deleting, isolating, booleans, moving and undo work on all of them, whoever made them. With the artifact database every change is written back, so the AI sees what the person did.
+
+Collections:
+
+- `objects`: one document per object, `{ name, mesh }`, at most 256 KiB each.
+- `palette`: one document per material, `{ color, metal, rough, alpha, emit, order }`.
+
+Undo is a per-session stack in the page; it does not reach back past a reload.

package/README.md

@@ -2,254 +2,120 @@
 
 Minimalist AI first 3D engine.
 
-> Status: **pre-alpha**. The `0.0.x` releases reserve the package name and
-> pin down the direction; the engine itself is built step by step in this repo.
+> Status: **pre-alpha**. The engine is built step by step in this repo.
 
 ```sh
 npm install 3draft
 ```
 
-## Usage (v0.1: points, edges, flat faces, SVG)
+The README has three parts: [1. the engine](#1-the-engine), [2. the viewer app](#2-the-viewer-app) and [3. how the engine and an LLM work together](#3-engine-and-llm).
 
-```js
-import { writeFileSync } from 'node:fs';
-import { box, merge, renderSheet, renderViews } from '3draft';
+---
 
-const table = merge(
-  box({ size: [2, 0.15, 1.2], at: [0, 0.925, 0], color: '#c8a27a' }),
-  box({ size: [0.15, 0.85, 0.15], at: [-0.85, 0.425, -0.45], color: '#8a6a4a' }),
-  // ...more legs
-);
+## 1. The engine
 
-writeFileSync('table.svg', renderSheet(table)); // 2x2 sheet
+A model is plain data, so a human, a program and an LLM can all read and write it:
 
-for (const { name, svg } of renderViews(table)) {
-  // one after another: 'front', 'side', 'top', 'persp'
-  writeFileSync(`table.${name}.svg`, svg);
-}
+```js
+const mesh = {
+  positions: [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]], // Vec3[], y is up
+  faces: [{ v: [0, 1, 2, 3], color: '#c8a27a', mat: 'wood' }], // CCW seen from outside, planar, convex
+};
 ```
 
-`npm run example` writes the table above to `examples/out/`:
+A scene is a list of objects `{ id, name, mesh }`. One mesh can hold many differently coloured faces (`examples/cessna.js` is one mesh with 9 colours).
 
-![table sheet](examples/out/table.sheet.svg)
+### Rendering
 
-Views: `front` (eye on +z), `side` (eye on +x), `top` (eye on +y), all
-orthographic with the same scale, and a perspective `persp` view. Every
-`<polygon>` carries `data-face` and `data-depth`, every `<circle>` carries
-`data-v`, so the output can be inspected as plain text.
+```js
+import { box, merge, renderSheet, renderView, orbit, createGpu } from '3draft';
 
-### Surfaces: what is under the cursor
+const table = merge(
+  box({ size: [2, 0.15, 1.2], at: [0, 0.925, 0], color: '#c8a27a' }),
+  box({ size: [0.15, 0.85, 0.15], at: [-0.85, 0.425, -0.45], color: '#8a6a4a' }),
+);
+renderSheet(table);                           // SVG: front, side, top, persp on one sheet
+renderView(table, 'persp', { occlude: true }); // one view, only what is seen
+const gpu = await createGpu(canvas);          // WebGPU, same camera, same pixels
+gpu.render(table, orbit({ yaw: -0.6, pitch: 0.45 }), { size: 600 });
+```
 
-The engine senses surfaces, not just pixels. `pick` casts a real ray from a
-screen pixel into the geometry and returns the face, the hit point, the
-surface normal and the distance. `crosshair` builds a target cross that lies
-flat on that surface (perpendicular to its normal), aligned to the face, so it
-turns with the object. Marks are drawn on top by `renderView`.
+![table sheet](examples/out/table.sheet.svg)
 
-```js
-import { makeCamera, pick, crosshair, renderView } from '3draft';
+- **SVG** is the deterministic preview (the same calls give the same text). Every `<polygon>` has `data-face` and `data-depth`, every `<circle>` has `data-v`. `occlude: true` paints into a small depth buffer first and sends only the faces and points that are seen (on the 5000-face house: 2793 -> about 680 polygons, 802 KB -> 175 KB, same picture).
+- **WebGPU** draws the same scene through the same camera (`viewProjection` is tested to hit the same pixels as `project`), with one shader, one light, alpha-to-coverage transparency and instancing.
+- Cameras: `front`, `side`, `top` (orthographic) and `persp`; `orbit({ yaw, pitch })` is a turntable; any `{ dir, up, ortho }` works.
+- Faces are painter-sorted with plane tests; interpenetrating solids can show artifacts, hidden edges are not drawn, back-face culling assumes closed CCW meshes.
 
-const cam = makeCamera('persp', mesh, 400);
-const hit = pick(mesh, cam, x, y); // { face, point, normal, distance, color } or null
+### Materials
 
-const marks = hit ? [{ name: 'cursor', lines: crosshair(mesh, hit, 0.08) }] : [];
-const svg = renderView(mesh, 'persp', { marks });
-```
+The palette is data: `{ name: { color, metal, rough, alpha, emit } }`. A face points at an entry with `face.mat`; its `color` stays as the fallback. Editing an entry changes every face made of it.
 
-Picking uses the geometry, not the painter's drawing order, so it stays exact
-where the drawing has artifacts. `ray(cam, x, y)` is the inverse of
-`project`. The viewer shows the cross under the pointer and reads out the face
-and its object-space normal.
+| field | meaning | drawn as |
+|---|---|---|
+| `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 | alpha-to-coverage, one pass, no sorting (SVG: `fill-opacity`, and a see-through face hides nothing) |
+| `emit` 0..1 | lit ... glowing | the colour shows unshaded |
 
-Any camera works: `renderView(mesh, { dir, up, ortho, name })` takes a custom
-view, `rotate(mesh, { yaw, pitch })` turns the mesh, and `{ fit: bounds(mesh) }`
-keeps the framing fixed while it moves.
+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.
 
-### Placing things
+### Surfaces, picking, editing
 
-`orbit({ yaw, pitch })` is a turntable as a camera, so the scene stays in object
-space and picks stay valid. `standOn(mesh, hit, { base, height, color })`
-returns a prism standing on the picked surface along its normal (height
-defaults to 3 x base). In the viewer, Space puts one down under the cross and
-Backspace takes the last one back. Over empty space Space shoots the prism out under the cursor to a random distance, animated, flying exactly along the camera axis (it lies along that axis like a bullet). The viewer starts empty (no table) and lays out only what you place. X deletes the prism under the cross. V is the Spider bar: the first V remembers the surface point under the cross, the second joins the two points with a thin prism (half the base of a shot prism, a darker brown); V over empty space forgets a pending first point. T flies the camera straight to the front of the object under the cross without turning it; T over nothing sets the speed to zero. W A S D R F fly: every press is a speed step along that axis (the speed grows faster than the level: 1, 2.7, 5.6, 9.9 ...) (w w w = speed 3 forward, s s s brings it back to a stop), R and F go up and down. While Shift is held the view turns towards the pointer, faster the farther the pointer is from the middle. H toggles edges and points. T flies the camera, animated, to the object under the cross and in front of the surface you point at (the whole scene is framed again when T is pressed over nothing, or with Reset view). Prisms get a random wood brown. On a phone or tablet the stage fills the screen with no text: drag orbits, and four round translucent buttons do T, Space, D and the SVG/WebGPU switch (the cross starts in the middle and stays where you last touched).
+- `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. Face colours and materials are kept; cut faces take the colour of the cutting solid. The result is welded and T-junctions are repaired; on messy data (coincident faces) it can still come out open, so check `validate`.
+- **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.
 
-### WebGPU view
+### TypeScript and `|>`
 
-`createGpu(canvas)` returns a WebGPU renderer that draws the same scene through
-the same camera as the SVG renderer, so picking, framing and the cross marks stay
-valid. Faces are flat colored (the face color is the albedo) and lit by one
-material (`ambient`, `diffuse`, `specular`, `shininess`) and one global light
-(hemisphere ambient plus one directional light):
+The source is TypeScript (`src/*.ts`) with the F# style pipeline operator, `value |> fn` ([why](https://dev.to/pengeszikra/pipeline-operator-great-again-1cbn)). `npm run build` rewrites every `|>` into plain calls (`scripts/pipe.mjs`: `a |> f |> g(1)` becomes `g(1)(f(a))`) and lets `tsc` check and emit `dist/`, which is committed, so a clone runs without a build.
 
-```js
-import { createGpu, orbit } from '3draft';
-const gpu = await createGpu(canvas);          // rejects when WebGPU is missing
-gpu.render(mesh, orbit({ yaw, pitch }), {
-  size: 600,                                  // CSS px; the canvas is made size x size x dpr
-  fit,                                        // keep the framing fixed, as with SVG
-  light: { direction: [0.5, 0.8, 0.6] },
-  material: { diffuse: 0.8 },
-});
+```ts
+const dir = spec.dir |> norm |> times(dist) |> plus(center); // the right side is a function
 ```
 
-`viewProjection(camera)` is the matrix behind it; it is unit tested to land every
-point on the same pixel as `project()`. `gpu.pixels(...)` draws the same frame
-offscreen and reads it back as RGBA.
+Put arrow functions in parentheses (`x |> ((v) => v + 1)`) and wrap a pipeline in parentheses next to `+` and `-`.
 
-### MCP server: let an AI build the models
+---
 
-`mcp/server.js` is an MCP server (stdio, no dependencies) that holds a scene of
-named objects and edits it through tool calls. The AI looks at the SVG preview,
-fixes what is wrong and renders again, so it never needs a screenshot.
+## 2. The viewer app
 
 ```sh
-# Claude Code
-claude mcp add 3draft -- node /absolute/path/to/3Draft/mcp/server.js
+npm run app     # http://localhost:5173/app/   (repo only, not in the npm package)
 ```
 
-```json
-{ "mcpServers": { "3draft": { "command": "node", "args": ["/absolute/path/to/3Draft/mcp/server.js"] } } }
-```
+A single `app/index.html` plus a dependency-free static server. Person and AI work on the same scene: objects loaded from outside and objects made in the viewer are one model, `{ id, name, mesh }`. WebGPU view with an SVG fallback, a cross cursor on the surface, flying, materials, booleans, a move gizmo, isolate, travel, undo. It is also published as a Claude artifact whose shared database is the scene.
 
-(that JSON goes into `claude_desktop_config.json` for Claude Desktop.)
-
-**Live viewer.** The same process serves the viewer and pushes every change to it
-(Server-Sent Events). Ask the AI for the `viewer` tool's URL (default
-`http://localhost:5173/app/`, next free port if that is taken, `3DRAFT_PORT` to
-change it, `3DRAFT_LIVE=0` to turn it off), open it in a browser and watch the
-model grow while the AI builds. The view re-frames to the scene; the objects are
-read-only in the viewer, but you can still rotate, switch to WebGPU, and place or
-delete your own prisms on top. Loopback only, other `Host` headers are refused.
-
-| tool | what it does |
-| --- | --- |
-| `add_box`, `add_extrusion`, `add_mesh` | boxes, prisms from a convex footprint, raw faces |
-| `transform`, `recolor`, `remove`, `clear` | scale / rotate Y / move, colors, deleting |
-| `get_mesh`, `extrude_face`, `move_vertices` | shape an object: push, taper, inset or dent a face, move vertices |
-| `list`, `inspect` | objects and bounds; closed shell, winding, planar and convex faces, as text notes |
-| `render` | SVG: a 2x2 sheet (front, side, top, persp) or one view, also `orbit` with yaw/pitch |
-| `pick` | pixel of a render -> object, face, 3D point, normal |
-| `export`, `import` | scene as JSON, optionally a `.json` file under the working directory |
-| `viewer` | URL of the live viewer |
+**How to use it, all keys and the database layout: [APP.md](APP.md).**
 
-Y is up, the ground is y = 0, faces are counter-clockwise seen from outside.
-Everything is deterministic, so the same calls give the same SVG.
+---
 
-### Known limitations
+## 3. Engine and LLM
 
-- Faces are painter-sorted with plane tests (Newell-Sancha style), which is
-  exact for solids that touch or stand on each other. Interpenetrating solids
-  and cyclic overlaps fall back to center depth and can show artifacts; a
-  face-splitting pass is planned.
-- Edges are the polygon outlines, so hidden edges are not drawn.
-- Back-face culling assumes closed meshes with CCW faces seen from outside.
+The engine is small enough to read whole (about 2000 lines) and everything it works with is text: meshes, palettes and scenes are JSON, previews are SVG, reports are sentences. That is the interface for an LLM:
 
-## TypeScript and the `|>` pipeline operator
+- **Look.** The LLM renders a model to SVG and reads it (or the numbers in it), without a screenshot. `occlude` keeps the text small.
+- **Check.** `validate` / `inspect` say in words what is wrong (open shell, inside-out faces, a non-planar face, which one), so the next edit is targeted.
+- **Edit.** The same data goes back in: write documents, call tools, render again. Output is deterministic, so a change in the picture is a change in the model.
+- **MCP server.** `mcp/server.js` (stdio, no dependencies) holds a scene of named objects and exposes it as tools: `add_box`, `add_extrusion`, `add_mesh`, `transform`, `boolean`, `recolor`, `remove`, `clear`, `get_mesh`, `extrude_face`, `move_vertices`, `list`, `inspect`, `render`, `pick`, `export`, `import`, `viewer`. It also serves the viewer and pushes every change to it, so a person watches the model grow. `claude mcp add 3draft -- node /absolute/path/to/3Draft/mcp/server.js`
+- **Shared database.** In the artifact, the LLM and the person edit the same `objects` and `palette` collections, so either side can start from what the other made.
 
-The engine is written in TypeScript (`src/*.ts`) with the F# style pipeline operator, `value |> fn`
-(see [Pipeline operator great again](https://dev.to/pengeszikra/pipeline-operator-great-again-1cbn)).
-Neither `tsc` nor Node understands `|>` yet, so `npm run build` (`scripts/build.mjs`) first rewrites
-every `|>` into plain calls (`scripts/pipe.mjs`, `a |> f |> g(1)` becomes `g(1)(f(a))`) and then lets the
-TypeScript compiler type check and emit `dist/*.js` and `dist/*.d.ts`.
+Y is up, the ground is y = 0, faces are counter-clockwise seen from outside.
 
-```ts
-const t1 = mesh.positions[b] |> minus(mesh.positions[a]) |> norm;   // the right side is a function
-const dir = spec.dir |> norm |> times(dist) |> plus(center);          // curried helpers: plus, minus, times
-```
+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).
 
-- The right side must evaluate to a function; put an arrow function in parentheses: `x |> ((v) => v + 1)`.
-- `|>` binds like `>>>` while it is parsed, so wrap a pipeline in parentheses next to `+`, `-` and friends.
-- `dist/` is committed: the viewer, the examples, the MCP server and the npm package use the built JavaScript, so a
-  clone runs without a build. `npm run build:check` fails when `dist/` is out of date, `npm test` builds first.
-- The compiler is a dev dependency (`typescript`); `TYPESCRIPT=/path/to/typescript.js` points the build at another copy.
+---
 
-## Develop
+## Develop, version, license
 
 ```bash
 npm run build        # src/*.ts -> dist/ (|> desugared, type checked)
-npm test             # builds, then runs every test (dist, examples, mcp, scripts)
+npm test             # builds, then runs every test
 npm run build:check  # fails when dist/ is out of date
-npm run kernel       # re-assemble kernel/pick.hexaw (needs the hexaw repo next to this one)
-npm run app          # the viewer, http://localhost:5173/app/
+npm run app          # the viewer
 ```
 
-Edit `src/*.ts`, never `dist/`: it is generated and committed so that a clone runs without a build.
-
-## Viewer app (repo only, not part of the npm package)
-
-```sh
-npm run app     # http://localhost:5173/app/
-```
-
-Drag to rotate the view, double click to reset. A target cross follows the pointer and lies on the surface under it.
-
-| key | does |
-| --- | --- |
-| `w a s d r f` | fly: forward, left, back, right, up, down; every press is a speed step (an accelerating curve), the opposite key slows down |
-| `Shift` | steer towards the pointer while flying |
-| `Space` | place a prism on the surface (or shoot one into empty space) |
-| `V` | Spider bar: two surface points joined by a thin brown prism; `V` over empty space forgets the first point |
-| `T` | travel to the target (a straight flight); `T` over nothing stops and zeroes the speed |
-| `X`, `Backspace` | delete the prism under the cross, undo |
-| `H`, `G`, `L` | edges, SVG / WebGPU view, light |
-
-On a phone the four round buttons do the same. The viewer picks with the HEXAW kernel (the footer shows `pick hexaw`). It is a
-single `app/index.html` plus a dependency-free static server
-(`app/serve.js`, localhost only, serves `app/`, `dist/` and `examples/`).
-
-## Versioning
-
-Date based, written `YY.MM.DD.NNN`. npm needs valid semver (three numbers, no
-leading zeros), so the published form is `YY.M.DNNN` where the last number is
-day * 1000 + build:
-
-| readable       | package version |
-| -------------- | --------------- |
-| `26.11.01.001` | `26.11.1001`    |
-| `26.11.01.002` | `26.11.1002`    |
-| `26.11.15.012` | `26.11.15012`   |
-
-`npm run bump` sets the next version for today's date in `package.json` and
-`src/index.ts` (`node scripts/bump.js --dry` only prints it).
-
-## Idea
-
-- **One material, one palette texture.** Every face's UV points at a single
-  texel of a small palette texture, so a whole scene is one pipeline, one bind
-  group and instanced draw calls.
-- **Thin WASM core.** Transforms, culling and animation live in a WASM module
-  (HEXAW and/or Rust) behind a small, documented ABI. JS only uploads buffers.
-- **WebGPU first, WebGL2 fallback** behind a minimal `Renderer` interface.
-- **AI first.** A deterministic SVG preview and structured `inspect` reports
-  (plus an MCP server) let an AI build and verify models from text.
-
-## Roadmap
-
-1. ABI description + reference JS kernel + spinning instanced cube
-2. SVG/PNG preview renderer and MCP `render` / `inspect`
-3. Text modelling language + palette/UV validator
-4. HEXAW kernel next to the JS reference, with differential tests
-5. Rust core only if the logic outgrows HEXAW
-
-## License
+Edit `src/*.ts`, never `dist/`. Versions are date based, `YY.MM.DD.NNN`, published as semver `YY.M.DNNN` (`26.11.01.002` is `26.11.1002`); `npm run bump` sets the next one.
 
 MIT
-
-## Examples
-
-- `examples/table.js`: the table demo (`npm run example`).
-- `examples/bridge.js`: a stone arch bridge of 50 named objects (`npm run bridge`). It writes `examples/bridge.scene.json`, a scene file you can load with the MCP `import` tool (`path: "examples/bridge.scene.json"`).
-- `examples/cessna.js`: a small Cessna as ONE mesh with 9 face colours (single flat material, colour per face): lofted closed parts (fuselage, high wing, tail, struts, gear, spinner, propeller) merged into one mesh. `node examples/cessna.js` checks it and writes `examples/cessna.scene.json` (one object, loadable with the MCP `import` tool) and `examples/out/cessna.svg`.
-
-## HEXAW kernel
-
-The picking hot loop (ray against every triangle, Moller-Trumbore, the same arithmetic as `src/pick.ts`) is also written in
-[HEXAW](https://github.com/Pengeszikra/hexaw), the byte-visible WebAssembly assembly dialect:
-
-- `kernel/pick.hexaw` is the source (569 bytes of WebAssembly once assembled).
-- `npm run kernel` assembles it with `hexaw-core.js` (found through `HEXAW_CORE`, a checkout next to this repo, or the `hexaw` package) and writes `src/kernel-bytes.ts`, the module as base64 (then `npm run build` carries it into `dist/`). The engine needs neither HEXAW nor a file fetch at runtime. `node scripts/build-kernel.mjs --check` fails when the generated file is out of date.
-- `initKernel()` starts it; `kernel.pick(mesh, camera, x, y)` returns exactly what `pick()` returns. The mesh is copied into the kernel's linear memory once for as long as it is the same object.
-- The viewer uses the kernel as soon as it has started (the footer shows `pick hexaw`), and plain `pick()` before that.
-- Measured on 1200 prisms (7200 faces): 1.7 ms per pick in JavaScript, 0.14 ms with the kernel.
-
-The kernel exports its linear memory (`EXPM "memory"`, needs hexaw with JS-compatible memory), so the mesh is written straight into it with `Float64Array` / `Int32Array` views and the distance is read back from address 0; the former `setf`/`seti`/`getf`/`grow`/`size` helper functions are gone.

package/dist/csg.d.ts

@@ -0,0 +1,10 @@
+import type { Mesh } from './types.js';
+export type BooleanOp = 'union' | 'subtract' | 'intersect';
+/**
+ * Boolean of two closed solids (outward CCW faces): 'union', 'subtract' (a minus b) or 'intersect'.
+ * Throws with a reason when an input is open or inside out.
+ */
+export declare const boolean: (a: Mesh, b: Mesh, op: BooleanOp) => Mesh;
+export declare const union: (a: Mesh, b: Mesh) => Mesh;
+export declare const subtract: (a: Mesh, b: Mesh) => Mesh;
+export declare const intersect: (a: Mesh, b: Mesh) => Mesh;

package/dist/csg.js

@@ -0,0 +1,239 @@
+// Boolean operations on closed solids: union, subtract (a - b) and intersect.
+// A BSP tree per solid (after Evan Wallace's csg.js): polygons are cut by the planes of the other solid
+// and the pieces inside or outside are kept, so every result face stays planar and convex, which is what
+// the rest of the engine assumes. The result is welded and its T-junctions are closed, so it is a closed
+// solid again and can go into the next boolean. Faces keep the color and material of the face they came from;
+// a face cut into a solid by the other one takes the color of the cutting face.
+import { sub, dot, cross, len } from './vec.js';
+import { faceNormal, bounds } from './mesh.js';
+import { validate } from './check.js';
+let CSG_EPS = 1e-6; // set per operation, relative to the size of the two solids
+const unit = (v) => {
+    const l = len(v) || 1;
+    return [v[0] / l, v[1] / l, v[2] / l];
+};
+const polysOf = (mesh) => mesh.faces.flatMap((f) => {
+    const pts = f.v.map((k) => mesh.positions[k]);
+    const n = unit(faceNormal(pts));
+    return len(faceNormal(pts)) < 1e-12 ? [] : [{ pts, n, w: dot(n, pts[0]), color: f.color, mat: f.mat }];
+});
+const flip = (p) => ({ ...p, pts: [...p.pts].reverse(), n: [-p.n[0], -p.n[1], -p.n[2]], w: -p.w });
+/** Cuts `p` by the plane into the four buckets. */
+const splitPoly = (plane, p, cf, cb, front, back) => {
+    const COPLANAR = 0;
+    const FRONT = 1;
+    const BACK = 2;
+    const SPANNING = 3;
+    let type = 0;
+    const types = p.pts.map((q) => {
+        const t = dot(plane.n, q) - plane.w;
+        const k = t < -CSG_EPS ? BACK : t > CSG_EPS ? FRONT : COPLANAR;
+        type |= k;
+        return k;
+    });
+    if (type === COPLANAR)
+        (dot(plane.n, p.n) > 0 ? cf : cb).push(p);
+    else if (type === FRONT)
+        front.push(p);
+    else if (type === BACK)
+        back.push(p);
+    else if (type === SPANNING) {
+        const f = [];
+        const b = [];
+        for (let i = 0; i < p.pts.length; i++) {
+            const j = (i + 1) % p.pts.length;
+            const ti = types[i];
+            const tj = types[j];
+            const vi = p.pts[i];
+            const vj = p.pts[j];
+            if (ti !== BACK)
+                f.push(vi);
+            if (ti !== FRONT)
+                b.push(vi);
+            if ((ti | tj) === SPANNING) {
+                const t = (plane.w - dot(plane.n, vi)) / dot(plane.n, sub(vj, vi));
+                const v = [vi[0] + (vj[0] - vi[0]) * t, vi[1] + (vj[1] - vi[1]) * t, vi[2] + (vj[2] - vi[2]) * t];
+                f.push(v);
+                b.push(v);
+            }
+        }
+        if (f.length >= 3)
+            front.push({ ...p, pts: f });
+        if (b.length >= 3)
+            back.push({ ...p, pts: b });
+    }
+};
+const build = (node, polys) => {
+    if (!polys.length)
+        return;
+    if (!node.plane)
+        node.plane = { n: polys[0].n, w: polys[0].w };
+    const front = [];
+    const back = [];
+    for (const p of polys)
+        splitPoly(node.plane, p, node.polys, node.polys, front, back);
+    if (front.length)
+        build((node.front ??= { plane: null, front: null, back: null, polys: [] }), front);
+    if (back.length)
+        build((node.back ??= { plane: null, front: null, back: null, polys: [] }), back);
+};
+const tree = (polys) => {
+    const node = { plane: null, front: null, back: null, polys: [] };
+    build(node, polys);
+    return node;
+};
+const invert = (node) => {
+    node.polys = node.polys.map(flip);
+    if (node.plane)
+        node.plane = { n: [-node.plane.n[0], -node.plane.n[1], -node.plane.n[2]], w: -node.plane.w };
+    invert0(node);
+};
+const invert0 = (node) => {
+    if (node.front)
+        invert(node.front);
+    if (node.back)
+        invert(node.back);
+    [node.front, node.back] = [node.back, node.front];
+};
+/** The parts of `polys` that are outside the solid of `node`. */
+const clipPolys = (node, polys) => {
+    if (!node.plane)
+        return [...polys];
+    let front = [];
+    let back = [];
+    for (const p of polys)
+        splitPoly(node.plane, p, front, back, front, back);
+    front = node.front ? clipPolys(node.front, front) : front;
+    back = node.back ? clipPolys(node.back, back) : [];
+    return [...front, ...back];
+};
+const clipTo = (node, other) => {
+    node.polys = clipPolys(other, node.polys);
+    if (node.front)
+        clipTo(node.front, other);
+    if (node.back)
+        clipTo(node.back, other);
+};
+const all = (node) => [...node.polys, ...(node.front ? all(node.front) : []), ...(node.back ? all(node.back) : [])];
+/** Polygons to a welded mesh: shared vertices, no sliver faces, T-junctions closed. */
+const toMesh = (polys, scale) => {
+    const cell = scale * 1e-5;
+    const ids = new Map();
+    const positions = [];
+    const weld = (p) => {
+        // look in the neighbouring cells too, so a point on a cell border still finds its twin
+        const base = p.map((c) => Math.round(c / cell));
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dz = -1; dz <= 1; dz++) {
+                    const hit = ids.get(`${base[0] + dx},${base[1] + dy},${base[2] + dz}`);
+                    if (hit !== undefined && len(sub(positions[hit], p)) <= cell * 1.5)
+                        return hit;
+                }
+        ids.set(base.join(','), positions.length);
+        positions.push(p);
+        return positions.length - 1;
+    };
+    let faces = polys.flatMap((p) => {
+        const v = [];
+        for (const q of p.pts) {
+            const k = weld(q);
+            if (v[v.length - 1] !== k)
+                v.push(k);
+        }
+        if (v.length > 1 && v[0] === v[v.length - 1])
+            v.pop();
+        if (v.length < 3)
+            return [];
+        const n = faceNormal(v.map((k) => positions[k]));
+        return len(n) < 1e-9 * scale * scale ? [] : [{ v, color: p.color, mat: p.mat }];
+    });
+    // T-junctions: a vertex lying on the edge of a neighbouring face gets inserted into that edge
+    const used = new Set(faces.flatMap((f) => f.v));
+    const verts = [...used];
+    if (verts.length * faces.length < 6e7) {
+        const tol = scale * 1e-5 * 3;
+        faces = faces.map((f) => {
+            const out = [];
+            for (let i = 0; i < f.v.length; i++) {
+                const a = f.v[i];
+                const b = f.v[(i + 1) % f.v.length];
+                out.push(a);
+                const pa = positions[a];
+                const pb = positions[b];
+                const d = sub(pb, pa);
+                const dl = len(d);
+                if (dl < tol * 4)
+                    continue;
+                const on = [];
+                for (const k of verts) {
+                    if (k === a || k === b)
+                        continue;
+                    const pk = positions[k];
+                    const t = dot(sub(pk, pa), d) / (dl * dl);
+                    if (t <= 0 || t >= 1)
+                        continue;
+                    if (len(cross(sub(pk, pa), d)) / dl <= tol)
+                        on.push({ t, k });
+                }
+                on.sort((x, y) => x.t - y.t);
+                for (const { k } of on)
+                    out.push(k);
+            }
+            return { ...f, v: out };
+        });
+    }
+    return { positions, faces };
+};
+const closedSolid = (name, m) => {
+    const v = validate(m);
+    if (!v.closed)
+        throw new Error(`boolean needs closed solids: ${name} has ${v.openEdges} open edge(s)`);
+    if (v.inside_out)
+        throw new Error(`boolean needs outward faces: ${name} is inside out`);
+};
+/**
+ * Boolean of two closed solids (outward CCW faces): 'union', 'subtract' (a minus b) or 'intersect'.
+ * Throws with a reason when an input is open or inside out.
+ */
+export const boolean = (a, b, op) => {
+    closedSolid('a', a);
+    closedSolid('b', b);
+    const sa = bounds(a);
+    const sb = bounds(b);
+    const scale = Math.max(sa.radius, sb.radius, 1e-9) * 2 + len(sub(sa.center, sb.center));
+    CSG_EPS = scale * 1e-9 * 1000;
+    const A = tree(polysOf(a));
+    const B = tree(polysOf(b));
+    if (op === 'union') {
+        clipTo(A, B);
+        clipTo(B, A);
+        invert(B);
+        clipTo(B, A);
+        invert(B);
+        build(A, all(B));
+    }
+    else if (op === 'subtract') {
+        invert(A);
+        clipTo(A, B);
+        clipTo(B, A);
+        invert(B);
+        clipTo(B, A);
+        invert(B);
+        build(A, all(B));
+        invert(A);
+    }
+    else {
+        invert(A);
+        clipTo(B, A);
+        invert(B);
+        clipTo(A, B);
+        clipTo(B, A);
+        build(A, all(B));
+        invert(A);
+    }
+    return toMesh(all(A), scale);
+};
+export const union = (a, b) => boolean(a, b, 'union');
+export const subtract = (a, b) => boolean(a, b, 'subtract');
+export const intersect = (a, b) => boolean(a, b, 'intersect');

package/dist/gpu.d.ts

@@ -1,3 +1,4 @@
+import type { Palette } from './material.js';
 import type { Axes, Camera, Fit, Mesh, Vec3, ViewName, ViewSpec } from './types.js';
 type Handle = any;
 export interface GpuLight {
@@ -21,6 +22,8 @@ export interface GpuRenderOptions {
     background?: Vec3;
     light?: GpuLight;
     material?: GpuMaterial;
+    /** Named materials the faces point at (`face.mat`); pass a new object when an entry changes. */
+    palette?: Palette;
     dpr?: number;
     /** Many copies of one prototype mesh (modelled around the origin), drawn after `mesh`. */
     instances?: {
@@ -52,8 +55,8 @@ 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 and face colors. Float32Array, 9 floats per vertex. */
-export declare const buildVertices: (mesh: Mesh) => 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;
 /**
  * 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.

package/dist/gpu.js

@@ -5,7 +5,8 @@
 import { dot, norm } from './vec.js';
 import { faceNormal } from './mesh.js';
 import { makeCamera } from './camera.js';
-const FLOATS = 9; // position(3) normal(3) color(3)
+import { surfaceOf } from './material.js';
+const FLOATS = 13; // position(3) normal(3) color(3) material(4: metal, rough, alpha, emit)
 /**
  * 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.
@@ -28,8 +29,8 @@ 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 and face colors. Float32Array, 9 floats per vertex. */
-export const buildVertices = (mesh) => {
+/** Triangle list for the GPU: flat face normals, face colors and materials. Float32Array, 13 floats per vertex. */
+export const buildVertices = (mesh, palette) => {
     let tris = 0;
     for (const f of mesh.faces)
         tris += Math.max(0, f.v.length - 2);
@@ -38,10 +39,12 @@ export const buildVertices = (mesh) => {
     for (const face of mesh.faces) {
         const pts = face.v.map((k) => mesh.positions[k]);
         const n = norm(faceNormal(pts));
-        const c = rgb(face.color);
+        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], o);
+                out.set([...p, ...n, ...c, ...mat], o);
                 o += FLOATS;
             }
         }
@@ -71,12 +74,13 @@ struct U {
 };
 @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> };
+struct VIn { @location(0) pos : vec3<f32>, @location(1) nrm : vec3<f32>, @location(2) col : vec3<f32>, @location(8) mat : vec4<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
 };
 
 @vertex fn vs(i : VIn) -> VOut {
@@ -85,6 +89,7 @@ struct VOut {
   o.n = i.nrm;
   o.c = i.col;
   o.w = i.pos;
+  o.m = i.mat;
   return o;
 }
 
@@ -103,6 +108,7 @@ struct IIn {
   o.n = normalize(i.ex) * i.nrm.x + normalize(i.ey) * i.nrm.y + normalize(i.ez) * i.nrm.z;
   o.c = i.col;
   o.w = w;
+  o.m = vec4<f32>(0.0, 0.7, 1.0, 0.0);
   return o;
 }
 
@@ -111,12 +117,22 @@ struct IIn {
   if (!front) { n = -n; }
   let l = normalize(u.light.xyz);
   let v = normalize(u.eye.xyz - i.w);
+  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 spec = pow(max(dot(n, h), 0.0), u.mat.w) * u.mat.z * step(0.0, dot(n, l));
-  let lit = i.c * (hemi + vec3<f32>(diff)) + vec3<f32>(spec);
-  return vec4<f32>(clamp(lit, vec3<f32>(0.0), vec3<f32>(1.0)), 1.0);
+  // 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));
+  // 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);
+  lit = mix(lit, i.c * 1.15, i.m.w);
+  return vec4<f32>(clamp(lit, vec3<f32>(0.0), vec3<f32>(1.0)), i.m.z);
 }
 `;
 /**
@@ -147,6 +163,7 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
             { shaderLocation: 0, offset: 0, format: 'float32x3' },
             { shaderLocation: 1, offset: 12, format: 'float32x3' },
             { shaderLocation: 2, offset: 24, format: 'float32x3' },
+            { shaderLocation: 8, offset: 36, format: 'float32x4' },
         ],
     };
     const instanceLayout = {
@@ -160,7 +177,8 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
         fragment: { module, entryPoint: 'fs', targets: [{ format }] },
         primitive: { topology: 'triangle-list', cullMode: 'none' },
         depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
-        multisample: { count: sampleCount },
+        // the fragment alpha becomes coverage: a half transparent face covers half of the samples (one pass, no sorting)
+        multisample: sampleCount > 1 ? { count: sampleCount, alphaToCoverageEnabled: true } : { count: sampleCount },
     });
     const pipeline = make('vs', [meshLayout]);
     // the instanced pipeline reads position and normal only from the prototype (locations 0, 1)
@@ -170,6 +188,7 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
     const instBind = device.createBindGroup({ layout: instPipeline.getBindGroupLayout(0), 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 vertexCount = 0;
     let protoMesh = null;
     let protoBuffer = null;
@@ -194,13 +213,13 @@ 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 = {}, dpr = globalThis.devicePixelRatio || 1, instances } = {}, readback = false) => {
+    const draw = (mesh, view, { size = 400, fit, background = [0.98, 0.98, 0.97], light = {}, material = {}, palette, dpr = globalThis.devicePixelRatio || 1, instances } = {}, readback = false) => {
         const L = { ...defaultLight, ...light };
         const M = { ...defaultMaterial, ...material };
         const cam = makeCamera(view, mesh, size, fit);
         targets(Math.max(1, Math.round(size * dpr)));
-        if (mesh !== uploaded) {
-            const verts = buildVertices(mesh);
+        if (mesh !== uploaded || palette !== uploadedPalette) {
+            const verts = buildVertices(mesh, palette);
             if (verts.byteLength > capacity) {
                 vertexBuffer?.destroy();
                 capacity = Math.max(verts.byteLength, 4096);
@@ -210,6 +229,7 @@ export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
                 device.queue.writeBuffer(vertexBuffer, 0, verts);
             vertexCount = verts.length / FLOATS;
             uploaded = mesh;
+            uploadedPalette = palette;
         }
         if (instances?.mesh && instances.mesh !== protoMesh) {
             const v = buildVertices(instances.mesh);

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export declare const name: "3draft";
-export declare const version = "26.11.2005";
+export declare const version = "26.11.3001";
 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';
 export { validate } from './check.js';
+export { boolean, union, subtract, intersect } from './csg.js';
+export type { BooleanOp } from './csg.js';
 export type { Validation } from './check.js';
 export { extrudeFace, moveVertices } from './edit.js';
 export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
@@ -16,6 +18,8 @@ export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight,
 export type { Gpu, GpuLight, GpuMaterial, GpuRenderOptions, Instance, Pixels } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
 export type { RenderOptions } from './svg.js';
+export { surfaceOf, DEFAULTS as MATERIAL_DEFAULTS } from './material.js';
+export type { Material, Palette, Surface } from './material.js';
 export { displayVersion } from './version.js';
 export interface Info {
     name: string;

package/dist/index.js

@@ -4,9 +4,10 @@
 // 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.2005';
+export const version = '26.11.3001';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export { validate } from './check.js';
+export { boolean, union, subtract, intersect } from './csg.js';
 export { extrudeFace, moveVertices } from './edit.js';
 export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
 export { pick, crosshair } from './pick.js';
@@ -14,6 +15,7 @@ export { standOn } from './place.js';
 export { paintOrder } from './order.js';
 export { createGpu, viewProjection, buildVertices, 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';
 /** Short, machine-readable description of the current state of the package. */
 export const info = () => ({

package/dist/material.d.ts

@@ -0,0 +1,31 @@
+import type { Face } from './types.js';
+export interface Material {
+    /** #rrggbb. */
+    color: string;
+    /** 0 = paint, 1 = metal (reflects the sky and the ground, tinted by the color). */
+    metal?: number;
+    /** 0 = mirror-like, 1 = matte; widens the highlight. */
+    rough?: number;
+    /** 1 = solid, 0 = invisible. Drawn with alpha-to-coverage: one pass, no sorting. */
+    alpha?: number;
+    /** 0..1: how much the color glows on its own, unlit. */
+    emit?: number;
+}
+export type Palette = Record<string, Material>;
+/** What a face is made of, all numbers filled in. */
+export interface Surface {
+    color: string;
+    metal: number;
+    rough: number;
+    alpha: number;
+    emit: number;
+}
+export declare const FALLBACK_COLOR = "#c8c8c8";
+export declare const DEFAULTS: {
+    readonly metal: 0;
+    readonly rough: 0.7;
+    readonly alpha: 1;
+    readonly emit: 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

@@ -0,0 +1,17 @@
+// Materials are data. A palette is a plain object { name: Material }; a face points at an entry by name
+// (`face.mat`) and keeps its own `color` as a fallback, so a mesh still looks right without the palette.
+// One shader draws all of them; the numbers below are the only knobs.
+const clamp01 = (n, fallback) => (typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : fallback);
+export const FALLBACK_COLOR = '#c8c8c8';
+export const DEFAULTS = { metal: 0, rough: 0.7, alpha: 1, emit: 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;
+    return {
+        color: m?.color ?? face.color ?? FALLBACK_COLOR,
+        metal: clamp01(m?.metal, DEFAULTS.metal),
+        rough: clamp01(m?.rough, DEFAULTS.rough),
+        alpha: clamp01(m?.alpha, DEFAULTS.alpha),
+        emit: clamp01(m?.emit, DEFAULTS.emit),
+    };
+};

package/dist/svg.d.ts

@@ -1,3 +1,4 @@
+import type { Palette } from './material.js';
 import type { Fit, Mark, Mesh, ViewName, ViewSpec } from './types.js';
 export interface RenderOptions {
     /** Panel size in px (default 400). */
@@ -6,6 +7,14 @@ export interface RenderOptions {
     cull?: boolean;
     /** Draw the vertices as circles (default true). */
     points?: boolean;
+    /**
+     * Send only what can be seen (default false). Faces are first painted into a small id buffer, far to
+     * near; a face none of whose pixels survives is covered by nearer ones and is left out, and so is a
+     * point no visible face reaches. The picture stays the same, the SVG gets much smaller.
+     */
+    occlude?: boolean;
+    /** Named materials (`face.mat`). The SVG shows their color and alpha; metal, rough and emit are for the GPU view. */
+    palette?: Palette;
     stroke?: string;
     pointColor?: string;
     background?: string;

package/dist/svg.js

@@ -5,6 +5,74 @@ import { dot, norm, minus } from './vec.js';
 import { faceNormal } from './mesh.js';
 import { paintOrder } from './order.js';
 import { VIEW_ORDER, makeCamera, project } from './camera.js';
+import { surfaceOf } from './material.js';
+/**
+ * Depth-tested scanline fill of one polygon into an id buffer. `w` grows towards the eye (1/depth in a
+ * perspective view, -depth in an orthographic one) and is linear across a planar face on the screen.
+ * A pixel that ties with what is there (coplanar faces) keeps both ids alive for the painter's order.
+ */
+const fill = (ids, zb, size, pts, w, id, alive, solid = true) => {
+    const test = (x, y, v) => {
+        if (x < 0 || y < 0 || x >= size || y >= size)
+            return;
+        const at = y * size + x;
+        const old = zb[at];
+        const tie = Math.abs(v - old) <= 1e-5 * Math.abs(old);
+        if (!solid) {
+            // a see-through face is visible where nothing nearer hides it, and hides nothing itself
+            if (v > old || tie)
+                alive.add(id);
+            return;
+        }
+        if (v > old || tie) {
+            if (tie && ids[at] >= 0)
+                alive.add(ids[at]);
+            zb[at] = Math.max(v, old);
+            ids[at] = id;
+        }
+    };
+    // the outline too: a face thinner than a pixel still shows as a line
+    for (let a = 0; a < pts.length; a++) {
+        const b = (a + 1) % pts.length;
+        const n = Math.ceil(Math.max(Math.abs(pts[b].x - pts[a].x), Math.abs(pts[b].y - pts[a].y)));
+        for (let i = 0; i <= n; i++) {
+            const t = n ? i / n : 0;
+            test(Math.floor(pts[a].x + t * (pts[b].x - pts[a].x)), Math.floor(pts[a].y + t * (pts[b].y - pts[a].y)), w[a] + t * (w[b] - w[a]));
+        }
+    }
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const p of pts)
+        (lo = Math.min(lo, p.y), (hi = Math.max(hi, p.y)));
+    const y0 = Math.max(0, Math.ceil(lo - 0.5));
+    const y1 = Math.min(size - 1, Math.floor(hi - 0.5));
+    const cross = [];
+    for (let y = y0; y <= y1; y++) {
+        const yc = y + 0.5;
+        cross.length = 0;
+        for (let a = 0; a < pts.length; a++) {
+            const b = (a + 1) % pts.length;
+            const p = pts[a];
+            const q = pts[b];
+            if ((p.y <= yc && q.y > yc) || (q.y <= yc && p.y > yc)) {
+                const t = (yc - p.y) / (q.y - p.y);
+                cross.push({ x: p.x + t * (q.x - p.x), w: w[a] + t * (w[b] - w[a]) });
+            }
+        }
+        cross.sort((a, b) => a.x - b.x);
+        for (let k = 0; k + 1 < cross.length; k += 2) {
+            const l = cross[k];
+            const r = cross[k + 1];
+            const x0 = Math.max(0, Math.ceil(l.x - 0.5));
+            const x1 = Math.min(size - 1, Math.floor(r.x - 0.5));
+            const span = r.x - l.x || 1;
+            for (let x = x0; x <= x1; x++) {
+                const v = l.w + ((x + 0.5 - l.x) / span) * (r.w - l.w);
+                test(x, y, v);
+            }
+        }
+    }
+};
 const defaults = {
     size: 400,
     cull: true,
@@ -58,6 +126,7 @@ const panel = (mesh, view, o, x = 0, y = 0) => {
         }
         if (!seen(screen))
             return; // outside the panel
+        const surface = surfaceOf(face, o.palette);
         items.push({
             i,
             vs: face.v,
@@ -66,22 +135,66 @@ const panel = (mesh, view, o, x = 0, y = 0) => {
             n: norm(normal),
             p: world[0],
             eye: facing ? 1 : -1,
-            color: face.color ?? '#c8c8c8',
+            color: surface.color,
+            alpha: surface.alpha,
             depth: screen.reduce((s, p) => s + p.depth, 0) / screen.length,
             pts: screen.map((p) => `${num(p.x)},${num(p.y)}`).join(' '),
         });
     });
-    const ordered = paintOrder(items); // far to near
+    // Occlusion: a depth buffer finds the faces that own a pixel; only those go on to the painter's order.
+    let idBuf = null;
+    let visible = items;
+    if (o.occlude) {
+        const buf = new Int32Array(o.size * o.size).fill(-1);
+        const zb = new Float32Array(o.size * o.size).fill(-Infinity);
+        const alive = new Set();
+        items.forEach((it, idx) => {
+            const w = it.screen.map((p) => (cam.ortho ? -p.depth : 1 / p.depth));
+            fill(buf, zb, o.size, it.screen, w, idx, alive, it.alpha >= 1);
+        });
+        for (const id of buf)
+            if (id >= 0)
+                alive.add(id);
+        const remap = new Map(); // item index -> index among the visible faces
+        visible = items.filter((_, idx) => alive.has(idx) && (remap.set(idx, remap.size), true));
+        idBuf = buf.map((id) => (id < 0 ? -1 : (remap.get(id) ?? -1)));
+    }
+    let ordered = paintOrder(visible); // far to near
+    if (idBuf) {
+        // ids point into `visible`; the painter's order permutes it
+        const at = new Map();
+        visible.forEach((it, n) => at.set(it, n));
+        const perm = new Int32Array(visible.length);
+        ordered.forEach((it, n) => (perm[at.get(it)] = n));
+        idBuf = idBuf.map((id) => (id < 0 ? -1 : perm[id]));
+    }
     // A point is drawn right after the nearest painted face that holds it, so
     // faces painted later (closer to the camera) still cover it.
     const last = new Map();
     ordered.forEach((it, idx) => it.vs.forEach((k) => last.set(k, idx)));
+    // a point is visible when a visible face that holds it owns a pixel at (or right next to) it
+    const reached = (k) => {
+        const px = Math.round(proj[k].x);
+        const py = Math.round(proj[k].y);
+        for (let dy = -1; dy <= 1; dy++) {
+            for (let dx = -1; dx <= 1; dx++) {
+                const x = px + dx;
+                const y = py + dy;
+                if (x < 0 || y < 0 || x >= o.size || y >= o.size)
+                    continue;
+                const id = idBuf[y * o.size + x];
+                if (id >= 0 && ordered[id].vs.includes(k))
+                    return true;
+            }
+        }
+        return false;
+    };
     const body = ordered.flatMap((it, idx) => {
         const polygon = `<polygon data-face="${it.i}" data-depth="${num(it.depth)}" points="${it.pts}" ` +
-            `fill="${it.color}" stroke="${o.stroke}" stroke-width="1.5" stroke-linejoin="round"/>`;
+            `fill="${it.color}"${it.alpha < 1 ? ` fill-opacity="${num(it.alpha)}"` : ''} stroke="${o.stroke}" stroke-width="1.5" stroke-linejoin="round"/>`;
         const dots = o.points
             ? it.vs
-                .filter((k) => last.get(k) === idx && (cam.ortho || proj[k].depth >= NEAR))
+                .filter((k) => last.get(k) === idx && (cam.ortho || proj[k].depth >= NEAR) && (!idBuf || reached(k)))
                 .sort((a, b) => a - b)
                 .map((k) => `<circle data-v="${k}" cx="${num(proj[k].x)}" cy="${num(proj[k].y)}" r="3" fill="${o.pointColor}"/>`)
             : [];

package/dist/types.d.ts

@@ -3,6 +3,8 @@ export interface Face {
     /** Point indices, CCW seen from outside. */
     v: number[];
     color?: string;
+    /** Name of a palette entry (see material.ts); `color` is the fallback. */
+    mat?: string;
 }
 export interface Mesh {
     positions: Vec3[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3draft",
-  "version": "26.11.2005",
+  "version": "26.11.3001",
   "description": "Minimalist AI first 3D engine: palette-texture, WASM core, WebGPU/WebGL2 renderer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,7 @@
     "dist",
     "!dist/**/*.test.*",
     "README.md",
+    "APP.md",
     "LICENSE"
   ],
   "scripts": {