3draft 0.0.0-stage → 26.11.1013

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 };
+};

package/src/index.d.ts

@@ -0,0 +1,209 @@
+export const name: '3draft';
+export const version: string;
+
+export type Vec3 = [number, number, number];
+
+export interface Face {
+  /** Point indices, CCW seen from outside. */
+  v: number[];
+  color?: string;
+}
+
+export interface Mesh {
+  positions: Vec3[];
+  faces: Face[];
+}
+
+export interface BoxOptions {
+  size?: Vec3;
+  at?: Vec3;
+  color?: string;
+  /** Orthonormal local x/y/z axes (default: the world axes). */
+  axes?: [Vec3, Vec3, Vec3];
+}
+
+export function box(options?: BoxOptions): Mesh;
+/** Prism from a convex footprint [[x, z], ...] (any winding), extruded up from `y` by `height`. */
+export function extrude(options: { polygon: [number, number][]; height?: number; y?: number; color?: string }): Mesh;
+export function merge(...meshes: Mesh[]): Mesh;
+/** Turntable rotation (radians): yaw around Y, then pitch around X, around `center`. */
+export function rotate(mesh: Mesh, angles?: { yaw?: number; pitch?: number }, center?: Vec3): Mesh;
+export function bounds(mesh: Mesh): { center: Vec3; radius: number };
+export function faceNormal(points: Vec3[]): Vec3;
+export function faceCenter(points: Vec3[]): Vec3;
+
+export type ViewName = 'front' | 'side' | 'top' | 'persp';
+export const VIEW_ORDER: readonly ViewName[];
+
+/** Custom camera: `dir` points from the target towards the eye. */
+export interface ViewSpec {
+  dir: Vec3;
+  up: Vec3;
+  ortho?: boolean;
+  name?: string;
+}
+
+export interface Fit {
+  center: Vec3;
+  radius: number;
+}
+
+export interface Camera {
+  name: string;
+  eye: Vec3;
+  f: Vec3;
+  r: Vec3;
+  u: Vec3;
+  ortho: boolean;
+  k: number;
+  size: number;
+}
+
+export function makeCamera(view: ViewName | ViewSpec, mesh: Mesh, size: number, fit?: Fit): Camera;
+export function project(camera: Camera, p: Vec3): { x: number; y: number; depth: number };
+
+/** Ray through a panel pixel, the inverse of `project`. `dir` is a unit vector. */
+export function ray(camera: Camera, x: number, y: number): { origin: Vec3; dir: Vec3 };
+
+export interface Hit {
+  /** Index into `mesh.faces`. */
+  face: number;
+  /** Distance along the ray. */
+  distance: number;
+  point: Vec3;
+  /** Unit normal, facing the camera. */
+  normal: Vec3;
+  /** Whether the face itself faces the camera. */
+  front: boolean;
+  color?: string;
+}
+
+/** The nearest surface under panel pixel (x, y), or null. */
+export function pick(
+  mesh: Mesh,
+  camera: Camera,
+  x: number,
+  y: number,
+  options?: { cull?: boolean },
+): Hit | null;
+
+/** A target cross lying on the picked surface: 4 arms and a ring, as 3D polylines. */
+export function crosshair(mesh: Mesh, hit: Hit, radius?: number): Vec3[][];
+
+/** 3D polylines drawn on top of the view. */
+export interface Mark {
+  name?: string;
+  lines: Vec3[][];
+  color?: string;
+  width?: number;
+}
+
+/** '26.11.1001' -> '26.11.01.001' */
+/** Turntable as a camera: the object stays put, the eye orbits (radians). */
+export function orbit(angles?: { yaw?: number; pitch?: number; ortho?: boolean; name?: string }): ViewSpec;
+
+export interface StandOptions {
+  /** Square base edge (default 0.15). */
+  base?: number;
+  /** Height (default 3 x base). */
+  height?: number;
+  color?: string;
+}
+/** A prism standing on the picked surface, along its normal. */
+export function standOn(mesh: Mesh, hit: Hit, options?: StandOptions): Mesh;
+
+/** Back-to-front paint order of projected faces (plane tests; depth fallback on cycles). */
+export function paintOrder(items: unknown[]): number[];
+
+export interface GpuLight {
+  /** Direction towards the light, world space. */
+  direction?: Vec3;
+  /** Hemisphere ambient colors (rgb 0..1): up and down. */
+  sky?: Vec3;
+  ground?: Vec3;
+}
+export interface GpuMaterial {
+  ambient?: number;
+  diffuse?: number;
+  specular?: number;
+  shininess?: number;
+}
+export interface GpuRenderOptions {
+  /** CSS pixels, the canvas becomes size x size (times dpr in device pixels). */
+  size?: number;
+  fit?: Fit;
+  /** Clear color, rgb 0..1. */
+  background?: Vec3;
+  light?: GpuLight;
+  material?: GpuMaterial;
+  dpr?: number;
+}
+export interface Gpu {
+  render(mesh: Mesh, view: ViewName | ViewSpec, options?: GpuRenderOptions): void;
+  /** Same frame, drawn offscreen and read back as RGBA (tests, thumbnails). */
+  pixels(mesh: Mesh, view: ViewName | ViewSpec, options?: GpuRenderOptions): Promise<{ width: number; height: number; data: Uint8ClampedArray }>;
+  destroy(): void;
+}
+/** WebGPU renderer on a canvas; rejects when WebGPU is unavailable. Same camera as the SVG renderer. */
+export function createGpu(canvas: HTMLCanvasElement, options?: { sampleCount?: number }): Promise<Gpu>;
+/** Column-major 4x4 matrix mapping world points to the same pixels as project(). */
+export function viewProjection(camera: Camera, near?: number, far?: number): Float32Array;
+/** Triangle list: position(3) normal(3) color(3) per vertex. */
+export function buildVertices(mesh: Mesh): Float32Array;
+export const defaultLight: Required<GpuLight>;
+export const defaultMaterial: Required<GpuMaterial>;
+
+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[];
+}
+/** Geometry checks: closed shell, CCW from outside, planar, convex faces. */
+export function validate(mesh: Mesh): Validation;
+
+/** Extrude / taper / inset / dent a face; returns the new mesh, the cap face index and the new side quads. */
+export function extrudeFace(mesh: Mesh, face: number, options?: { distance?: number; scale?: number; color?: string }): { mesh: Mesh; cap: number; sides: number[] };
+export function moveVertices(mesh: Mesh, indices: number[], delta: Vec3): Mesh;
+
+export function displayVersion(version: string): string;
+
+export interface RenderOptions {
+  /** Panel size in px (default 400). */
+  size?: number;
+  /** Drop back-facing faces (default true). */
+  cull?: boolean;
+  /** Draw the vertices as circles (default true). */
+  points?: boolean;
+  stroke?: string;
+  pointColor?: string;
+  background?: string;
+  /** Keep the camera target/framing fixed while the mesh moves. */
+  fit?: Fit;
+  /** 3D polylines drawn on top, e.g. the surface cursor. */
+  marks?: Mark[];
+}
+
+export function renderView(mesh: Mesh, view: ViewName | ViewSpec, options?: RenderOptions): string;
+export function renderViews(mesh: Mesh, options?: RenderOptions): { name: ViewName; svg: string }[];
+export function renderSheet(mesh: Mesh, options?: RenderOptions): string;
+
+export interface Info {
+  name: string;
+  version: string;
+  stage: 'pre-alpha';
+  goals: string[];
+}
+
+export function info(): Info;

package/src/index.js

@@ -0,0 +1,32 @@
+// 3Draft: minimalist AI first 3D engine.
+// Current stage: points, edges and flat faces rendered to deterministic SVG
+// from four fixed cameras, plus surface picking (point, normal, distance) and
+// a target cross that lies on the surface under the cursor. No textures, no
+// shading yet.
+
+export const name = '3draft';
+export const version = '26.11.1013';
+
+export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
+export { validate } from './check.js';
+export { extrudeFace, moveVertices } from './edit.js';
+export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
+export { pick, crosshair } from './pick.js';
+export { standOn } from './place.js';
+export { paintOrder } from './order.js';
+export { createGpu, viewProjection, buildVertices, defaultLight, defaultMaterial } from './gpu.js';
+export { renderView, renderViews, renderSheet } from './svg.js';
+export { displayVersion } from './version.js';
+
+/** Short, machine-readable description of the current state of the package. */
+export const info = () => ({
+  name,
+  version,
+  stage: 'pre-alpha',
+  goals: [
+    'single palette texture, UVs point at one texel per face',
+    'WASM core (HEXAW / Rust) behind a thin ABI',
+    'WebGPU renderer with WebGL2 fallback',
+    'deterministic SVG preview for AI feedback loops',
+  ],
+});

package/src/mesh.js

@@ -0,0 +1,127 @@
+// Mesh = { positions: [[x, y, z], ...], faces: [{ v: [i, j, k, ...], color }] }
+// Faces are CCW when seen from outside. No normals, UVs or textures yet.
+
+import { add, len, scale, sub } from './vec.js';
+
+/** Box: 8 points, 12 edges, 6 quad faces. Axis-aligned unless `axes` turns it. */
+export const box = ({ size = [1, 1, 1], at = [0, 0, 0], color = '#c8c8c8', axes } = {}) => {
+  const [hx, hy, hz] = size.map((s) => s / 2);
+  // `axes` = [ex, ey, ez], an orthonormal right-handed frame (default: x, y, z)
+  const [ex, ey, ez] = axes ?? [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+  const at3 = (x, y, z) => add(at, add(add(scale(ex, x), scale(ey, y)), scale(ez, z)));
+  const positions = [
+    at3(-hx, -hy, -hz), // 0
+    at3(hx, -hy, -hz), // 1
+    at3(hx, hy, -hz), // 2
+    at3(-hx, hy, -hz), // 3
+    at3(-hx, -hy, hz), // 4
+    at3(hx, -hy, hz), // 5
+    at3(hx, hy, hz), // 6
+    at3(-hx, hy, hz), // 7
+  ];
+  const faces = [
+    [4, 5, 6, 7], // +z
+    [1, 0, 3, 2], // -z
+    [1, 2, 6, 5], // +x
+    [0, 4, 7, 3], // -x
+    [3, 7, 6, 2], // +y
+    [0, 1, 5, 4], // -y
+  ].map((v) => ({ v, color }));
+  return { positions, faces };
+};
+
+/** Concatenate meshes into one, re-indexing the faces. */
+export const merge = (...meshes) => {
+  const positions = [];
+  const faces = [];
+  for (const m of meshes) {
+    const offset = positions.length;
+    positions.push(...m.positions);
+    for (const f of m.faces) faces.push({ ...f, v: f.v.map((i) => i + offset) });
+  }
+  return { positions, faces };
+};
+
+/** Bounding box center and bounding sphere radius around that center. */
+export const bounds = (mesh) => {
+  if (!mesh.positions.length) return { center: [0, 0, 0], radius: 0 };
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const p of mesh.positions) {
+    for (let a = 0; a < 3; a++) {
+      if (p[a] < min[a]) min[a] = p[a];
+      if (p[a] > max[a]) max[a] = p[a];
+    }
+  }
+  const center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+  let radius = 0;
+  for (const p of mesh.positions) radius = Math.max(radius, len(sub(p, center)));
+  return { center, radius };
+};
+
+/**
+ * Turntable rotation: yaw around Y first, then pitch around X (radians),
+ * both around `center` (default: bounding-box center). Faces are shared.
+ */
+export const rotate = (mesh, { yaw = 0, pitch = 0 } = {}, center = bounds(mesh).center) => {
+  const cy = Math.cos(yaw);
+  const sy = Math.sin(yaw);
+  const cp = Math.cos(pitch);
+  const sp = Math.sin(pitch);
+  const positions = mesh.positions.map((p) => {
+    const x = p[0] - center[0];
+    const y = p[1] - center[1];
+    const z = p[2] - center[2];
+    const x1 = cy * x + sy * z;
+    const z1 = -sy * x + cy * z;
+    return [x1 + center[0], cp * y - sp * z1 + center[1], sp * y + cp * z1 + center[2]];
+  });
+  return { positions, faces: mesh.faces };
+};
+
+/** Face normal (not normalized) by Newell's method; points CCW => outward. */
+export const faceNormal = (pts) => {
+  const n = [0, 0, 0];
+  for (let i = 0; i < pts.length; i++) {
+    const a = pts[i];
+    const b = pts[(i + 1) % pts.length];
+    n[0] += (a[1] - b[1]) * (a[2] + b[2]);
+    n[1] += (a[2] - b[2]) * (a[0] + b[0]);
+    n[2] += (a[0] - b[0]) * (a[1] + b[1]);
+  }
+  return n;
+};
+
+/** Mean of the face points. */
+export const faceCenter = (pts) => {
+  const s = pts.reduce((acc, p) => add(acc, p), [0, 0, 0]);
+  return [s[0] / pts.length, s[1] / pts.length, s[2] / pts.length];
+};
+
+/**
+ * Prism from a convex footprint: `polygon` is [[x, z], ...] on the ground plane (any
+ * winding), it is extruded up from `y` by `height`. Faces: top, bottom, then one
+ * quad per footprint edge, all CCW from outside.
+ */
+export const extrude = ({ polygon, height = 1, y = 0, color = '#c8c8c8' } = {}) => {
+  if (!Array.isArray(polygon) || polygon.length < 3) throw new Error('polygon needs at least 3 [x, z] points');
+  if (!(height > 0)) throw new Error('height must be positive');
+  let pts = polygon.map((p) => [p[0], p[1]]);
+  const n = pts.length;
+  const turn = (a, b, c) => (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]); // y of edge cross, + is CCW from above
+  let area = 0;
+  for (let i = 0; i < n; i++) area += pts[i][1] * pts[(i + 1) % n][0] - pts[i][0] * pts[(i + 1) % n][1];
+  if (Math.abs(area) < 1e-12) throw new Error('polygon has no area');
+  if (area < 0) pts = pts.reverse();
+  for (let i = 0; i < n; i++) {
+    if (turn(pts[i], pts[(i + 1) % n], pts[(i + 2) % n]) < -1e-12) throw new Error('polygon must be convex');
+  }
+  const positions = [...pts.map(([x, z]) => [x, y, z]), ...pts.map(([x, z]) => [x, y + height, z])];
+  const ring = [...Array(n).keys()];
+  const faces = [
+    { v: ring.map((i) => n + i), color },
+    { v: [...ring].reverse(), color },
+    ...ring.map((i) => ({ v: [i, (i + 1) % n, n + ((i + 1) % n), n + i], color })),
+  ];
+  return { positions, faces };
+};