3draft 26.11.1013 → 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,193 +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/`:
-
-![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.
+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).
 
-### Surfaces: what is under the cursor
-
-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`.
+### Rendering
 
 ```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
+import { box, merge, renderSheet, renderView, orbit, createGpu } from '3draft';
 
-const marks = hit ? [{ name: 'cursor', lines: crosshair(mesh, hit, 0.08) }] : [];
-const svg = renderView(mesh, 'persp', { marks });
+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 });
 ```
 
-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.
+![table sheet](examples/out/table.sheet.svg)
 
-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.
+- **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.
 
-### Placing things
+### Materials
 
-`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 along the cursor ray to a random distance, animated. The viewer starts empty (no table) and lays out only what you place. D deletes the prism under the cross. 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.
+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.
 
-### WebGPU view
+| 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 |
 
-`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):
+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.
 
-```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 },
-});
-```
+### Surfaces, picking, editing
 
-`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.
+- `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.
 
-### MCP server: let an AI build the models
+### TypeScript and `|>`
 
-`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.
-
-```sh
-# Claude Code
-claude mcp add 3draft -- node /absolute/path/to/3Draft/mcp/server.js
-```
+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.
 
-```json
-{ "mcpServers": { "3draft": { "command": "node", "args": ["/absolute/path/to/3Draft/mcp/server.js"] } } }
+```ts
+const dir = spec.dir |> norm |> times(dist) |> plus(center); // the right side is a function
 ```
 
-(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 |
+Put arrow functions in parentheses (`x |> ((v) => v + 1)`) and wrap a pipeline in parentheses next to `+` and `-`.
 
-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
+---
 
-- 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.
-
-## Viewer app (repo only, not part of the npm package)
+## 2. The viewer app
 
 ```sh
-npm run app     # http://localhost:5173/app/
+npm run app     # http://localhost:5173/app/   (repo only, not in the npm package)
 ```
 
-Drag to rotate the view, double click to reset. G switches between the SVG and the WebGPU view, L turns the light (WebGPU). A
-target cross follows the pointer and lies on the surface under it. It is a
-single `app/index.html` plus a dependency-free static server
-(`app/serve.js`, localhost only, serves `app/`, `src/` and `examples/`).
+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.
 
-## Versioning
+**How to use it, all keys and the database layout: [APP.md](APP.md).**
 
-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`   |
+## 3. Engine and LLM
 
-`npm run bump` sets the next version for today's date in `package.json` and
-`src/index.js` (`node scripts/bump.js --dry` only prints it).
+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:
 
-## Idea
+- **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.
 
-- **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.
+Y is up, the ground is y = 0, faces are counter-clockwise seen from outside.
 
-## Roadmap
+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).
 
-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
+---
+
+## Develop, version, license
+
+```bash
+npm run build        # src/*.ts -> dist/ (|> desugared, type checked)
+npm test             # builds, then runs every test
+npm run build:check  # fails when dist/ is out of date
+npm run app          # the viewer
+```
 
-## 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

package/dist/camera.d.ts

@@ -0,0 +1,29 @@
+import type { Camera, Fit, Mesh, Vec3, ViewName, ViewSpec } from './types.js';
+export declare const VIEW_ORDER: readonly ViewName[];
+/**
+ * `fit` = { center, radius, dist? } overrides the target and framing (perspective views only use `dist`). Use it when the
+ * mesh moves (e.g. rotates) so the camera keeps looking at the same spot.
+ */
+export declare const makeCamera: (view: ViewName | ViewSpec, mesh: Mesh, size: number, fit?: Fit) => Camera;
+/**
+ * Turntable rotation as a camera: the view you get from rotate(mesh, { yaw, pitch })
+ * with a fixed camera, but the mesh stays where it is. Picks and marks are then
+ * in object space.
+ */
+export declare const orbit: ({ yaw, pitch, ortho, name }?: {
+    yaw?: number;
+    pitch?: number;
+    ortho?: boolean;
+    name?: string;
+}) => ViewSpec;
+/** Ray through panel pixel (x, y), the inverse of project(): { origin, dir } in world space, dir is a unit vector. */
+export declare const ray: (cam: Camera, x: number, y: number) => {
+    origin: Vec3;
+    dir: Vec3;
+};
+/** World point -> { x, y } in panel pixels (y down) and depth along the view direction. */
+export declare const project: (cam: Camera, p: Vec3) => {
+    x: number;
+    y: number;
+    depth: number;
+};

package/dist/camera.js

@@ -0,0 +1,68 @@
+// Four named views, all looking at the mesh bounding-box center.
+// front / side / top are orthographic (same scale), persp is a perspective view.
+// A view can also be a custom spec: { dir, up, ortho, name? } where `dir` is the
+// direction from the target towards the eye.
+import { add, cross, dot, norm, scale, plus, minus, times } from './vec.js';
+import { bounds } from './mesh.js';
+export const VIEW_ORDER = ['front', 'side', 'top', 'persp'];
+const FOV = (35 * Math.PI) / 180;
+const VIEWS = {
+    front: { dir: [0, 0, 1], up: [0, 1, 0], ortho: true }, // eye on +z
+    side: { dir: [1, 0, 0], up: [0, 1, 0], ortho: true }, // eye on +x
+    top: { dir: [0, 1, 0], up: [0, 0, -1], ortho: true }, // eye on +y, -z is screen-up
+    persp: { dir: norm([1, 0.8, 1.2]), up: [0, 1, 0], ortho: false },
+};
+/**
+ * `fit` = { center, radius, dist? } overrides the target and framing (perspective views only use `dist`). Use it when the
+ * mesh moves (e.g. rotates) so the camera keeps looking at the same spot.
+ */
+export const makeCamera = (view, mesh, size, fit) => {
+    const spec = typeof view === 'string' ? VIEWS[view] : view;
+    if (!spec)
+        throw new Error(`unknown view: ${view}`);
+    const name = typeof view === 'string' ? view : (view.name ?? 'custom');
+    const ortho = Boolean(spec.ortho);
+    const { center, radius } = fit ?? bounds(mesh);
+    const r0 = radius || 1;
+    const dist = ortho ? r0 * 4 : (fit?.dist ?? (r0 * 1.25) / Math.sin(FOV / 2)); // fit.dist: eye distance override (a first-person eye sits almost on the center)
+    const eye = plus(center)(times(dist)(norm(spec.dir)));
+    const f = norm(minus(eye)(center)); // forward
+    const r = norm(cross(f, spec.up)); // right
+    const u = cross(r, f); // up
+    const k = ortho ? ((size / 2) * 0.8) / r0 : size / 2 / Math.tan(FOV / 2);
+    return { name, eye, f, r, u, ortho, k, size };
+};
+/**
+ * Turntable rotation as a camera: the view you get from rotate(mesh, { yaw, pitch })
+ * with a fixed camera, but the mesh stays where it is. Picks and marks are then
+ * in object space.
+ */
+export const orbit = ({ yaw = 0, pitch = 0, ortho = false, name = 'orbit' } = {}) => {
+    const cy = Math.cos(yaw);
+    const sy = Math.sin(yaw);
+    const cp = Math.cos(pitch);
+    const sp = Math.sin(pitch);
+    return { name, ortho, dir: [-sy * cp, sp, cy * cp], up: [sy * sp, cp, -cy * sp] };
+};
+/** Ray through panel pixel (x, y), the inverse of project(): { origin, dir } in world space, dir is a unit vector. */
+export const ray = (cam, x, y) => {
+    const nx = (x - cam.size / 2) / cam.k;
+    const ny = -(y - cam.size / 2) / cam.k;
+    const lateral = plus(scale(cam.u, ny))(scale(cam.r, nx));
+    return cam.ortho
+        ? { origin: add(cam.eye, lateral), dir: cam.f }
+        : { origin: cam.eye, dir: norm(plus(lateral)(cam.f)) };
+};
+/** World point -> { x, y } in panel pixels (y down) and depth along the view direction. */
+export const project = (cam, p) => {
+    const d = minus(cam.eye)(p);
+    const cx = dot(d, cam.r);
+    const cy = dot(d, cam.u);
+    const depth = dot(d, cam.f);
+    const w = cam.ortho ? 1 : depth;
+    return {
+        x: cam.size / 2 + (cx / w) * cam.k,
+        y: cam.size / 2 - (cy / w) * cam.k,
+        depth,
+    };
+};

package/dist/check.d.ts

@@ -0,0 +1,24 @@
+import type { Mesh } from './types.js';
+export interface Validation {
+    vertices: number;
+    faces: number;
+    /** Every edge is shared by two faces, wound consistently. */
+    closed: boolean;
+    openEdges: number;
+    /** Signed volume; null unless closed. */
+    volume: number | null;
+    /** Closed, but the faces point inward. */
+    inside_out: boolean;
+    degenerateFaces: number[];
+    nonPlanarFaces: number[];
+    nonConvexFaces: number[];
+    ok: boolean;
+    /** Plain-text findings. */
+    notes: string[];
+}
+/**
+ * { vertices, faces, closed, openEdges, volume, inside_out, degenerateFaces,
+ *   nonPlanarFaces, nonConvexFaces, ok, notes }
+ * `volume` and `inside_out` only mean something for a closed mesh.
+ */
+export declare const validate: (mesh: Mesh) => Validation;

package/dist/check.js

@@ -0,0 +1,83 @@
+// Model checks an AI can read as text: is the mesh closed, are the faces CCW from
+// outside, planar and convex (picking and the painter assume that).
+import { sub, dot, cross, len, norm } from './vec.js';
+import { faceNormal, bounds } from './mesh.js';
+/**
+ * { vertices, faces, closed, openEdges, volume, inside_out, degenerateFaces,
+ *   nonPlanarFaces, nonConvexFaces, ok, notes }
+ * `volume` and `inside_out` only mean something for a closed mesh.
+ */
+export const validate = (mesh) => {
+    const { positions, faces } = mesh;
+    const size = bounds(mesh).radius || 1;
+    const degenerate = [];
+    const nonPlanar = [];
+    const nonConvex = [];
+    const directed = new Map();
+    let volume = 0;
+    faces.forEach((face, i) => {
+        const pts = face.v.map((k) => positions[k]);
+        const m = pts.length;
+        const n = faceNormal(pts);
+        const area2 = len(n);
+        if (area2 < 1e-12 * size * size) {
+            degenerate.push(i);
+            return;
+        }
+        const unit = norm(n);
+        if (Math.max(...pts.map((p) => Math.abs(dot(sub(p, pts[0]), unit)))) > 1e-6 * size)
+            nonPlanar.push(i);
+        for (let j = 0; j < m; j++) {
+            const a = pts[j];
+            const b = pts[(j + 1) % m];
+            const c = pts[(j + 2) % m];
+            if (dot(cross(sub(b, a), sub(c, b)), unit) < -1e-9 * size * size) {
+                nonConvex.push(i);
+                break;
+            }
+        }
+        for (let j = 0; j < m; j++) {
+            const key = `${face.v[j]},${face.v[(j + 1) % m]}`;
+            directed.set(key, (directed.get(key) ?? 0) + 1);
+        }
+        for (let j = 1; j < m - 1; j++)
+            volume += dot(pts[0], cross(pts[j], pts[j + 1])) / 6;
+    });
+    let open = 0;
+    let repeated = 0;
+    for (const [key, count] of directed) {
+        const [a, b] = key.split(',');
+        if (count > 1)
+            repeated += 1;
+        if (!directed.has(`${b},${a}`))
+            open += 1;
+    }
+    const closed = faces.length > 0 && open === 0 && repeated === 0;
+    const insideOut = closed && volume < 0;
+    const notes = [];
+    if (degenerate.length)
+        notes.push(`degenerate faces (no area): ${degenerate.join(', ')}`);
+    if (nonPlanar.length)
+        notes.push(`non-planar faces: ${nonPlanar.join(', ')}`);
+    if (nonConvex.length)
+        notes.push(`non-convex faces (picking and painting assume convex): ${nonConvex.join(', ')}`);
+    if (repeated)
+        notes.push(`${repeated} edge(s) are used twice in the same direction: faces are wound inconsistently`);
+    if (open)
+        notes.push(`${open} open edge(s): the mesh is not closed (fine for a surface, e.g. a missing bottom)`);
+    if (insideOut)
+        notes.push('the faces point inward: reverse the vertex order of every face');
+    return {
+        vertices: positions.length,
+        faces: faces.length,
+        closed,
+        openEdges: open,
+        volume: closed ? Math.round(volume * 1e9) / 1e9 : null,
+        inside_out: insideOut,
+        degenerateFaces: degenerate,
+        nonPlanarFaces: nonPlanar,
+        nonConvexFaces: nonConvex,
+        ok: !degenerate.length && !nonPlanar.length && !nonConvex.length && !repeated && !insideOut,
+        notes,
+    };
+};

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;