3draft 0.0.1 → 26.11.1013

package/README.md

@@ -9,12 +9,167 @@ Minimalist AI first 3D engine.
 npm install 3draft
 ```
 
+## Usage (v0.1: points, edges, flat faces, SVG)
+
 ```js
-import { info } from '3draft';
+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
+);
+
+writeFileSync('table.svg', renderSheet(table)); // 2x2 sheet
 
-console.log(info());
+for (const { name, svg } of renderViews(table)) {
+  // one after another: 'front', 'side', 'top', 'persp'
+  writeFileSync(`table.${name}.svg`, svg);
+}
 ```
 
+`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.
+
+### 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`.
+
+```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 });
+```
+
+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.
+
+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.
+
+### Placing things
+
+`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.
+
+### WebGPU view
+
+`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):
+
+```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 },
+});
+```
+
+`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.
+
+### 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.
+
+```sh
+# Claude Code
+claude mcp add 3draft -- node /absolute/path/to/3Draft/mcp/server.js
+```
+
+```json
+{ "mcpServers": { "3draft": { "command": "node", "args": ["/absolute/path/to/3Draft/mcp/server.js"] } } }
+```
+
+(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 |
+
+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)
+
+```sh
+npm run app     # http://localhost:5173/app/
+```
+
+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/`).
+
+## 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.js` (`node scripts/bump.js --dry` only prints it).
+
 ## Idea
 
 - **One material, one palette texture.** Every face's UV points at a single

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3draft",
-  "version": "0.0.1",
+  "version": "26.11.1013",
   "description": "Minimalist AI first 3D engine: palette-texture, WASM core, WebGPU/WebGL2 renderer.",
   "type": "module",
   "main": "./src/index.js",
@@ -19,10 +19,15 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "mcp": "node mcp/server.js",
+    "example": "node examples/table.js",
+    "app": "node app/serve.js",
+    "bump": "node scripts/bump.js"
   },
   "keywords": [
     "3d",
+    "svg",
     "webgpu",
     "webgl2",
     "wasm",

package/src/camera.js

@@ -0,0 +1,75 @@
+// 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, sub } 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 } overrides the target and framing. 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 : (r0 * 1.25) / Math.sin(FOV / 2);
+  const eye = add(center, scale(norm(spec.dir), dist));
+  const f = norm(sub(center, eye)); // 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 = add(scale(cam.r, nx), scale(cam.u, ny));
+  return cam.ortho
+    ? { origin: add(cam.eye, lateral), dir: cam.f }
+    : { origin: cam.eye, dir: norm(add(cam.f, lateral)) };
+};
+
+/** World point -> { x, y } in panel pixels (y down) and depth along the view direction. */
+export const project = (cam, p) => {
+  const d = sub(p, cam.eye);
+  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/src/check.js

@@ -0,0 +1,79 @@
+// 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/src/edit.js

@@ -0,0 +1,47 @@
+// Shaping an existing mesh: the topology edits a modeller does by hand.
+// Both functions return a NEW mesh; faces stay CCW from outside and closed meshes stay closed.
+
+import { add, sub, scale as mul, norm } from './vec.js';
+import { faceNormal, faceCenter } from './mesh.js';
+
+/**
+ * Extrude a face: it is replaced (same index) by a copy moved `distance` along its
+ * normal and scaled by `scale` about its center, and one quad per edge joins the two.
+ *   distance > 0, scale 1      a prism out of the face
+ *   distance > 0, scale < 1    a taper (roof, spire, frustum)
+ *   distance 0,   scale < 1    an inset (a panel, a window frame)
+ *   distance < 0               a dent into the solid (a niche, a door recess)
+ * The new quads are appended after the existing faces; `color` recolors the cap and
+ * the quads, otherwise they keep the face color.
+ * Returns { mesh, cap, sides } with the index of the cap face and the new quad indices.
+ */
+export const extrudeFace = (mesh, index, { distance = 0, scale = 1, color } = {}) => {
+  const face = mesh.faces[index];
+  if (!face) throw new Error(`no face ${index}: this mesh has ${mesh.faces.length} faces`);
+  if (!(scale > 0)) throw new Error('scale must be positive');
+  if (distance === 0 && scale === 1) throw new Error('nothing to do: give a distance or a scale other than 1');
+  const pts = face.v.map((k) => mesh.positions[k]);
+  const n = norm(faceNormal(pts));
+  const c = faceCenter(pts);
+  const moved = pts.map((p) => add(add(c, mul(sub(p, c), scale)), mul(n, distance)));
+  const base = mesh.positions.length;
+  const m = pts.length;
+  const tint = color ?? face.color;
+  const faces = mesh.faces.map((f, i) => (i === index ? { ...f, v: moved.map((_, j) => base + j), color: tint } : f));
+  const sides = [];
+  for (let i = 0; i < m; i++) {
+    sides.push(faces.length);
+    faces.push({ v: [face.v[i], face.v[(i + 1) % m], base + ((i + 1) % m), base + i], color: tint });
+  }
+  return { mesh: { positions: [...mesh.positions, ...moved], faces }, cap: index, sides };
+};
+
+/** Move the vertices at `indices` by `delta` [dx, dy, dz]. Faces keep their vertices, so faces may stop being planar: check with validate(). */
+export const moveVertices = (mesh, indices, delta) => {
+  const set = new Set();
+  for (const i of indices) {
+    if (!Number.isInteger(i) || i < 0 || i >= mesh.positions.length) throw new Error(`vertex ${i} does not exist: this mesh has ${mesh.positions.length} vertices`);
+    set.add(i);
+  }
+  return { ...mesh, positions: mesh.positions.map((p, i) => (set.has(i) ? add(p, delta) : p)) };
+};

package/src/gpu.js

@@ -0,0 +1,252 @@
+// WebGPU renderer: flat-colored faces, one simple lit material, one global light.
+// It draws the same scene through the same camera as the SVG renderer, so picking,
+// the cross marks and the framing all stay valid. The pure helpers (viewProjection,
+// buildVertices) need no GPU and are unit tested; createGpu() needs a browser.
+
+import { sub, dot, norm } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { makeCamera } from './camera.js';
+
+const FLOATS = 9; // position(3) normal(3) color(3)
+
+/**
+ * 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.
+ */
+export const viewProjection = (cam, near = 0.1, far = 1000) => {
+  const kk = cam.k / (cam.size / 2);
+  const row = (v, s) => [v[0] * s, v[1] * s, v[2] * s, -dot(v, cam.eye) * s];
+  const a = cam.ortho ? 1 / (far - near) : far / (far - near);
+  const zr = row(cam.f, a);
+  zr[3] -= a * near;
+  const rows = [row(cam.r, kk), row(cam.u, kk), zr, cam.ortho ? [0, 0, 0, 1] : row(cam.f, 1)];
+  const m = new Float32Array(16);
+  rows.forEach((r, i) => r.forEach((v, j) => (m[j * 4 + i] = v)));
+  return m;
+};
+
+const rgb = (color) => {
+  const h = String(color ?? '').replace('#', '');
+  const full = h.length === 3 ? [...h].map((c) => c + c).join('') : h;
+  if (!/^[0-9a-f]{6}$/i.test(full)) 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) => {
+  let tris = 0;
+  for (const f of mesh.faces) tris += Math.max(0, f.v.length - 2);
+  const out = new Float32Array(tris * 3 * FLOATS);
+  let o = 0;
+  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);
+    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);
+        o += FLOATS;
+      }
+    }
+  }
+  return out;
+};
+
+export const defaultLight = { direction: norm([0.5, 0.8, 0.6]), sky: [1, 0.97, 0.92], ground: [0.42, 0.38, 0.36] };
+export const defaultMaterial = { ambient: 0.62, diffuse: 0.78, specular: 0.2, shininess: 30 };
+
+const SHADER = /* wgsl */ `
+struct U {
+  vp : mat4x4<f32>,
+  light : vec4<f32>,   // xyz: direction towards the light
+  sky : vec4<f32>,
+  ground : vec4<f32>,
+  eye : vec4<f32>,
+  mat : vec4<f32>,     // ambient, diffuse, specular, shininess
+};
+@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 VOut {
+  @builtin(position) p : vec4<f32>,
+  @location(0) n : vec3<f32>,
+  @location(1) c : vec3<f32>,
+  @location(2) w : vec3<f32>,
+};
+
+@vertex fn vs(i : VIn) -> VOut {
+  var o : VOut;
+  o.p = u.vp * vec4<f32>(i.pos, 1.0);
+  o.n = i.nrm;
+  o.c = i.col;
+  o.w = i.pos;
+  return o;
+}
+
+@fragment fn fs(i : VOut, @builtin(front_facing) front : bool) -> @location(0) vec4<f32> {
+  var n = normalize(i.n);
+  if (!front) { n = -n; }
+  let l = normalize(u.light.xyz);
+  let v = normalize(u.eye.xyz - i.w);
+  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);
+}
+`;
+
+/**
+ * Sets up WebGPU on a canvas. Rejects when WebGPU is not available.
+ * Returns { render(mesh, view, options), destroy() }.
+ * render options: size (CSS px, the canvas is made size x size), fit, background [r,g,b] 0..1,
+ * light { direction, sky, ground }, material { ambient, diffuse, specular, shininess }, dpr.
+ */
+export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
+  if (!globalThis.navigator?.gpu) throw new Error('WebGPU is not available in this browser');
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error('No WebGPU adapter found');
+  const device = await adapter.requestDevice();
+  device.addEventListener('uncapturederror', (e) => console.error('WebGPU:', e.error?.message ?? e));
+  device.lost.then((info) => console.error('WebGPU device lost:', info.reason, info.message));
+  const context = canvas.getContext('webgpu');
+  if (!context) throw new Error('Could not get a WebGPU canvas context');
+  const format = navigator.gpu.getPreferredCanvasFormat();
+  context.configure({ device, format, alphaMode: 'opaque', });
+
+  const module = device.createShaderModule({ code: SHADER });
+  const pipeline = device.createRenderPipeline({
+    layout: 'auto',
+    vertex: {
+      module,
+      entryPoint: 'vs',
+      buffers: [
+        {
+          arrayStride: FLOATS * 4,
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+            { shaderLocation: 1, offset: 12, format: 'float32x3' },
+            { shaderLocation: 2, offset: 24, format: 'float32x3' },
+          ],
+        },
+      ],
+    },
+    fragment: { module, entryPoint: 'fs', targets: [{ format }] },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
+    multisample: { count: sampleCount },
+  });
+  const uniforms = device.createBuffer({ size: 144, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+  const bind = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uniforms } }] });
+
+  let vertexBuffer = null;
+  let capacity = 0;
+  let px = 0;
+  let depth = null;
+  let color = null;
+
+  const targets = (n) => {
+    if (n === px) return;
+    px = n;
+    canvas.width = n;
+    canvas.height = n;
+    depth?.destroy();
+    color?.destroy();
+    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 } = {}, 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)));
+
+    const verts = buildVertices(mesh);
+    if (verts.byteLength > capacity) {
+      vertexBuffer?.destroy();
+      capacity = Math.max(verts.byteLength, 4096);
+      vertexBuffer = device.createBuffer({ size: capacity, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+    }
+    if (verts.byteLength) device.queue.writeBuffer(vertexBuffer, 0, verts);
+
+    const u = new Float32Array(36);
+    u.set(viewProjection(cam), 0);
+    u.set([...norm(L.direction), 0], 16);
+    u.set([...L.sky, 0], 20);
+    u.set([...L.ground, 0], 24);
+    u.set([...cam.eye, 0], 28);
+    u.set([M.ambient, M.diffuse, M.specular, M.shininess], 32);
+    device.queue.writeBuffer(uniforms, 0, u);
+
+    const encoder = device.createCommandEncoder();
+    const offscreen = readback
+      ? device.createTexture({ size: [px, px], format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC })
+      : null;
+    const target = (offscreen ?? context.getCurrentTexture()).createView();
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [
+        {
+          view: color ? color.createView() : target,
+          resolveTarget: color ? target : undefined,
+          clearValue: { r: background[0], g: background[1], b: background[2], a: 1 },
+          loadOp: 'clear',
+          storeOp: color ? 'discard' : 'store',
+        },
+      ],
+      depthStencilAttachment: { view: depth.createView(), depthClearValue: 1, depthLoadOp: 'clear', depthStoreOp: 'discard' },
+    });
+    if (verts.byteLength) {
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bind);
+      pass.setVertexBuffer(0, vertexBuffer);
+      pass.draw(verts.length / FLOATS);
+    }
+    pass.end();
+    if (!offscreen) {
+      device.queue.submit([encoder.finish()]);
+      return null;
+    }
+    const row = Math.ceil((px * 4) / 256) * 256;
+    const out = device.createBuffer({ size: row * px, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    encoder.copyTextureToBuffer({ texture: offscreen }, { buffer: out, bytesPerRow: row }, [px, px]);
+    device.queue.submit([encoder.finish()]);
+    return out.mapAsync(GPUMapMode.READ).then(() => {
+      const raw = new Uint8Array(out.getMappedRange());
+      const data = new Uint8ClampedArray(px * px * 4);
+      const swap = format.startsWith('bgra');
+      for (let y = 0; y < px; y++) {
+        for (let x = 0; x < px; x++) {
+          const i = y * row + x * 4;
+          const o = (y * px + x) * 4;
+          data[o] = raw[i + (swap ? 2 : 0)];
+          data[o + 1] = raw[i + 1];
+          data[o + 2] = raw[i + (swap ? 0 : 2)];
+          data[o + 3] = 255;
+        }
+      }
+      out.unmap();
+      out.destroy();
+      offscreen.destroy();
+      return { width: px, height: px, data };
+    });
+  };
+
+  /** Draws a frame onto the canvas. */
+  const render = (mesh, view, options) => {
+    draw(mesh, view, options);
+  };
+  /** Draws a frame into an offscreen texture and reads it back: Promise<{ width, height, data: RGBA }>. */
+  const pixels = (mesh, view, options) => draw(mesh, view, options, true);
+
+  const destroy = () => {
+    vertexBuffer?.destroy();
+    depth?.destroy();
+    color?.destroy();
+    uniforms.destroy();
+    device.destroy();
+  };
+
+  return { render, pixels, destroy, device, adapter };
+};