3draft 26.11.2005 → 26.11.4010

package/APP.md

@@ -0,0 +1,121 @@
+# 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 **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.
+- **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. **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) |
+| `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 |
+| `P` | show / hide the material palette |
+| `I` | pick material: the material of the face under the cross becomes the selected one |
+| `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) |
+| `C` | filmic look on / off (also the `Filmic` 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) |
+
+## Clear and example models
+
+- **`Clear`** (footer) removes every object in the scene. It is one undo step: `U` brings them all back.
+- **`+ Example…`** (the drop-down in the footer) adds a ready-made model to the scene: the house (the Blender import, 45 objects), the Cessna, the stone bridge or the table. It is placed beside what is already there, on its +x side, and the view frames everything. One `U` removes the whole example again. Examples are normal objects after that: paint, move, boolean and delete them like any other.
+
+## 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.
+
+## Edit mode: drawing on a model (`Tab`)
+
+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.
+
+- **`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.
+- **Points in the air extend the model.** With a line in progress, `V` over empty space puts the next point on the plane that faces the camera through the last point. So you can draw a new part out from the model, and lines that end on existing vertices are attached to it.
+- **`Enter` closes a loop into a face.** The shortest closed loop (up to 8 lines) through the last line becomes a face with the selected material, wound away from the middle of the object. A loop of 4 or more becomes triangles, so faces stay flat.
+- **Nothing moves by default** (and never while you draw with `V`). Moving is Blender-style, with a key per mode, and every drag is one `U` step:
+  - `1` **move points:** hover a vertex (white cross), drag it.
+  - `2` **move lines:** hover an edge or a line (white), drag it; both ends move.
+  - `3` **move faces:** hover a face (white outline), drag it; all its vertices move together and the face stays flat.
+  - The drag slides in the plane that faces the camera. A selected point, line or face (orange) also gets a gizmo: drag an arrow to move along one axis. Everything that uses the moved vertices follows: lines, faces and the base surface, so this is how you reshape the original model. A polygon that gets only some of its vertices moved turns into triangles.
+  - `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.
+
+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`.
+
+Limits for now: a face made from a non-flat or non-convex loop is only as good as its triangle fan, there is no mirror yet, and the lines are not deformation weights (a surface does not bend around a moved vertex, it just follows the vertices that are in the mesh).
+
+## 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). Only closed parts are calculated: a part that is not a closed solid (a surface, a box without a bottom) is left out, and a union keeps it as it is. The status line under the picture is the **health check** of the object under the cross: `solid`, `N of M parts closed · K faces open`, or `no closed part`. Each object needs at least one **closed solid with outward faces**; with none, the reason shows 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.
+
+**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.
+
+## 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,123 @@
 
 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).
+
+---
+
+## 1. The engine
+
+A model is plain data, so a human, a program and an LLM can all read and write it:
 
 ```js
-import { writeFileSync } from 'node:fs';
-import { box, merge, renderSheet, renderViews } from '3draft';
+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
+};
+```
+
+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).
+
+### Rendering
+
+```js
+import { box, merge, renderSheet, renderView, orbit, createGpu } 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
 );
-
-writeFileSync('table.svg', renderSheet(table)); // 2x2 sheet
-
-for (const { name, svg } of renderViews(table)) {
-  // one after another: 'front', 'side', 'top', 'persp'
-  writeFileSync(`table.${name}.svg`, svg);
-}
+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 });
 ```
 
-`npm run example` writes the table above to `examples/out/`:
-
 ![table sheet](examples/out/table.sheet.svg)
 
-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.
+- **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, real alpha blending (see-through faces in a second pass, sorted far to near) 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.
 
-### Surfaces: what is under the cursor
+### Materials
 
-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`.
+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.
 
-```js
-import { makeCamera, pick, crosshair, renderView } from '3draft';
-
-const cam = makeCamera('persp', mesh, 400);
-const hit = pick(mesh, cam, x, y); // { face, point, normal, distance, color } or null
-
-const marks = hit ? [{ name: 'cursor', lines: crosshair(mesh, hit, 0.08) }] : [];
-const svg = renderView(mesh, 'persp', { marks });
-```
+| 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 | blended in a second pass, far to near (SVG: `fill-opacity`, and a see-through face hides nothing) |
+| `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 |
 
-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.
+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.
 
-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.
+`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).
 
-### 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. 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.
+- **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,35 @@
+import type { Mesh } from './types.js';
+export type BooleanOp = 'union' | 'subtract' | 'intersect';
+/** One connected piece of a mesh (faces joined by shared edges). */
+export interface Part {
+    /** Indices into mesh.faces. */
+    faces: number[];
+    closed: boolean;
+    insideOut: boolean;
+    openEdges: number;
+}
+export interface Health {
+    parts: Part[];
+    /** Faces in closed, outward parts: the ones a boolean can work with. */
+    usableFaces: number;
+    /** Faces in open (or inside-out) parts: a boolean ignores them. */
+    skippedFaces: number;
+    /** true when at least one part is a closed solid. */
+    hasSolid: boolean;
+    /** true when every part is a closed solid. */
+    allSolid: boolean;
+}
+/** Splits a mesh into connected parts and says which of them are closed solids (the health check). */
+export declare const health: (mesh: Mesh) => Health;
+/**
+ * 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. With `strict: false` the parts that are not closed solids are
+ * left out of the calculation instead (see `health`): a union keeps them as they are, a subtract keeps those of `a`,
+ * an intersect drops them; it throws only when `a` has no closed part at all.
+ */
+export declare const boolean: (a: Mesh, b: Mesh, op: BooleanOp, { strict }?: {
+    strict?: boolean;
+}) => 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;