3draft 0.0.1 → 26.11.1013

package/src/index.d.ts

@@ -1,6 +1,204 @@
 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;

package/src/index.js

@@ -1,9 +1,22 @@
 // 3Draft: minimalist AI first 3D engine.
-// Early placeholder release: the real engine (palette-texture meshes,
-// WASM core, WebGPU/WebGL2 renderer, SVG preview) is built on top of this.
+// 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 = '0.0.1';
+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 = () => ({

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

package/src/order.js

@@ -0,0 +1,94 @@
+// Back-to-front painting order, Newell-Sancha style.
+//
+// Faces that overlap on screen are ordered by plane tests: face A can be painted
+// after face B when A lies wholly on the eye side of B's plane, or when B lies
+// wholly behind A's plane. The resulting "paint this first" relations are then
+// sorted topologically. Centroid depth only breaks ties, and orders faces that
+// cannot be compared (intersecting solids, cycles) as well as before.
+
+import { dot, sub } from './vec.js';
+
+const PLANE_EPS = 1e-6; // plane test tolerance, world units
+const PX = 0.01; // overlaps thinner than this are treated as touching
+
+// Do two convex screen polygons overlap by more than a sliver? (separating axis test)
+const overlaps = (a, b) => {
+  for (const poly of [a, b]) {
+    for (let i = 0; i < poly.length; i++) {
+      const p = poly[i];
+      const q = poly[(i + 1) % poly.length];
+      const nx = q.y - p.y;
+      const ny = p.x - q.x;
+      const length = Math.hypot(nx, ny);
+      if (!length) continue;
+      let minA = Infinity;
+      let maxA = -Infinity;
+      let minB = Infinity;
+      let maxB = -Infinity;
+      for (const v of a) {
+        const d = (v.x * nx + v.y * ny) / length;
+        if (d < minA) minA = d;
+        if (d > maxA) maxA = d;
+      }
+      for (const v of b) {
+        const d = (v.x * nx + v.y * ny) / length;
+        if (d < minB) minB = d;
+        if (d > maxB) maxB = d;
+      }
+      if (maxA <= minB + PX || maxB <= minA + PX) return false;
+    }
+  }
+  return true;
+};
+
+// Signed distances of points to a face's plane, positive on the eye side.
+const distances = (points, face) => points.map((v) => dot(face.n, sub(v, face.p)) * face.eye);
+
+/**
+ * Items need: { i, world, screen, n, p, eye, depth }
+ *   world  face points in world space      screen  the same, projected { x, y }
+ *   n, p   unit normal and a point on it   eye     +1 if the face faces the camera, else -1
+ *   depth  mean depth, used for ties       i       face index, used for ties
+ */
+export const paintOrder = (items) => {
+  const count = items.length;
+  const after = items.map(() => []);
+  const waiting = new Array(count).fill(0);
+  const link = (first, second) => {
+    after[first].push(second);
+    waiting[second] += 1;
+  };
+
+  for (let i = 0; i < count; i++) {
+    for (let j = i + 1; j < count; j++) {
+      const A = items[i];
+      const B = items[j];
+      if (!overlaps(A.screen, B.screen)) continue;
+      const a = distances(A.world, B); // A against B's plane
+      const b = distances(B.world, A); // B against A's plane
+      const aAfterB = a.every((d) => d >= -PLANE_EPS) || b.every((d) => d <= PLANE_EPS);
+      const bAfterA = b.every((d) => d >= -PLANE_EPS) || a.every((d) => d <= PLANE_EPS);
+      if (aAfterB && !bAfterA) link(j, i);
+      else if (bAfterA && !aAfterB) link(i, j);
+    }
+  }
+
+  const farther = (x, y) =>
+    items[x].depth > items[y].depth || (items[x].depth === items[y].depth && items[x].i < items[y].i);
+  const done = new Array(count).fill(false);
+  const out = [];
+  while (out.length < count) {
+    let best = -1;
+    for (let k = 0; k < count; k++) {
+      if (!done[k] && waiting[k] === 0 && (best < 0 || farther(k, best))) best = k;
+    }
+    if (best < 0) {
+      // a cycle: take the farthest face that is left
+      for (let k = 0; k < count; k++) if (!done[k] && (best < 0 || farther(k, best))) best = k;
+    }
+    done[best] = true;
+    out.push(items[best]);
+    for (const k of after[best]) waiting[k] -= 1;
+  }
+  return out;
+};

package/src/pick.js

@@ -0,0 +1,83 @@
+// Surface sensing: what is under a screen pixel, and a marker that lies on it.
+// Picking casts a real ray against the face geometry, so it is exact even where
+// the painter-sorted drawing is not.
+
+import { add, cross, dot, norm, scale, sub } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { ray } from './camera.js';
+
+const EPS = 1e-9;
+
+// Moller-Trumbore ray/triangle test. Distance along the ray, or null.
+const hitTriangle = (o, d, a, b, c) => {
+  const e1 = sub(b, a);
+  const e2 = sub(c, a);
+  const h = cross(d, e2);
+  const det = dot(e1, h);
+  if (Math.abs(det) < EPS) return null;
+  const inv = 1 / det;
+  const s = sub(o, a);
+  const u = inv * dot(s, h);
+  if (u < 0 || u > 1) return null;
+  const q = cross(s, e1);
+  const v = inv * dot(d, q);
+  if (v < 0 || u + v > 1) return null;
+  const t = inv * dot(e2, q);
+  return t > EPS ? t : null;
+};
+
+/**
+ * The nearest surface under panel pixel (x, y), or null.
+ * { face, distance, point, normal, front, color }
+ * `normal` is a unit vector facing the camera; `front` tells whether the face
+ * itself faces the camera (always true while `cull` is on). Faces are assumed
+ * convex and planar.
+ */
+export const pick = (mesh, cam, x, y, { cull = true } = {}) => {
+  const { origin, dir } = ray(cam, x, y);
+  let best = null;
+  mesh.faces.forEach((face, i) => {
+    const pts = face.v.map((k) => mesh.positions[k]);
+    const outward = norm(faceNormal(pts));
+    const front = dot(outward, dir) < 0;
+    if (cull && !front) return;
+    for (let j = 1; j < pts.length - 1; j++) {
+      const t = hitTriangle(origin, dir, pts[0], pts[j], pts[j + 1]);
+      if (t !== null && (!best || t < best.distance)) {
+        best = {
+          face: i,
+          distance: t,
+          point: add(origin, scale(dir, t)),
+          normal: front ? outward : scale(outward, -1),
+          front,
+          color: face.color,
+        };
+      }
+    }
+  });
+  return best;
+};
+
+/**
+ * A target cross lying flat on the picked surface (perpendicular to its
+ * normal): four arms with a gap in the middle and a ring, as 3D polylines.
+ * It is aligned to the first edge of the face, so it turns with the object.
+ * `radius` is the ring radius in world units.
+ */
+export const crosshair = (mesh, hit, radius = 0.1) => {
+  const [a, b] = mesh.faces[hit.face].v;
+  const t1 = norm(sub(mesh.positions[b], mesh.positions[a]));
+  const t2 = norm(cross(hit.normal, t1));
+  const at = (p, q) => add(hit.point, add(scale(t1, p * radius), scale(t2, q * radius)));
+  const ring = Array.from({ length: 33 }, (_, i) => {
+    const angle = (i / 32) * 2 * Math.PI;
+    return at(Math.cos(angle), Math.sin(angle));
+  });
+  return [
+    [at(-1.7, 0), at(-0.4, 0)],
+    [at(0.4, 0), at(1.7, 0)],
+    [at(0, -1.7), at(0, -0.4)],
+    [at(0, 0.4), at(0, 1.7)],
+    ring,
+  ];
+};

package/src/place.js

@@ -0,0 +1,23 @@
+// Putting things down on surfaces.
+
+import { add, cross, norm, scale, sub } from './vec.js';
+import { box } from './mesh.js';
+
+/**
+ * A square prism standing on the picked surface: its base lies on the surface,
+ * centered at the hit point, and it rises along the surface normal. Its sides
+ * line up with the first edge of the face. The height is `3 * base` unless given.
+ * Returns a new mesh; merge() it into the scene.
+ */
+export const standOn = (mesh, hit, { base = 0.15, height = 3 * base, color = '#c8c8c8' } = {}) => {
+  const [a, b] = mesh.faces[hit.face].v;
+  const ex = norm(sub(mesh.positions[b], mesh.positions[a]));
+  const ey = hit.normal;
+  const ez = cross(ex, ey);
+  return box({
+    size: [base, height, base],
+    at: add(hit.point, scale(ey, height / 2)),
+    axes: [ex, ey, ez],
+    color,
+  });
+};

package/src/svg.js

@@ -0,0 +1,119 @@
+// Flat SVG preview: points, edges, faces. No shading, no textures.
+// Faces are painted far to near (see order.js), back faces culled. The polygon stroke
+// is the edge layer, so hidden edges stay hidden. Output is deterministic.
+
+import { sub, dot, norm } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { paintOrder } from './order.js';
+import { VIEW_ORDER, makeCamera, project } from './camera.js';
+
+const defaults = {
+  size: 400,
+  cull: true,
+  points: true,
+  stroke: '#1d1d1f',
+  pointColor: '#d6336c',
+  background: '#fafafa',
+};
+
+const num = (n) => String(Math.round(n * 100) / 100 + 0); // +0 turns -0 into 0
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+
+const panel = (mesh, view, o, x = 0, y = 0) => {
+  const cam = makeCamera(view, mesh, o.size, o.fit);
+  const name = esc(cam.name);
+  const proj = mesh.positions.map((p) => project(cam, p));
+  const items = [];
+
+  mesh.faces.forEach((face, i) => {
+    const world = face.v.map((k) => mesh.positions[k]);
+    const screen = face.v.map((k) => proj[k]);
+    if (screen.some((s) => s.depth <= 0.01)) return; // behind the camera
+    const dir = cam.ortho ? cam.f : sub(world[0], cam.eye);
+    const normal = faceNormal(world);
+    const facing = dot(normal, dir) < 0;
+    if (o.cull && !facing) return; // back face
+    items.push({
+      i,
+      vs: face.v,
+      world,
+      screen,
+      n: norm(normal),
+      p: world[0],
+      eye: facing ? 1 : -1,
+      color: face.color ?? '#c8c8c8',
+      depth: screen.reduce((s, p) => s + p.depth, 0) / screen.length,
+      pts: screen.map((p) => `${num(p.x)},${num(p.y)}`).join(' '),
+    });
+  });
+
+  const ordered = paintOrder(items); // far to near
+
+  // A point is drawn right after the nearest painted face that holds it, so
+  // faces painted later (closer to the camera) still cover it.
+  const last = new Map();
+  ordered.forEach((it, idx) => it.vs.forEach((k) => last.set(k, idx)));
+
+  const body = ordered.flatMap((it, idx) => {
+    const polygon =
+      `<polygon data-face="${it.i}" data-depth="${num(it.depth)}" points="${it.pts}" ` +
+      `fill="${it.color}" stroke="${o.stroke}" stroke-width="1.5" stroke-linejoin="round"/>`;
+    const dots = o.points
+      ? it.vs
+          .filter((k) => last.get(k) === idx)
+          .sort((a, b) => a - b)
+          .map(
+            (k) =>
+              `<circle data-v="${k}" cx="${num(proj[k].x)}" cy="${num(proj[k].y)}" r="3" fill="${o.pointColor}"/>`,
+          )
+      : [];
+    return [polygon, ...dots];
+  });
+
+  // 3D polylines (e.g. a surface cursor) drawn on top of everything else.
+  const marks = (o.marks ?? []).flatMap((m) =>
+    m.lines.flatMap((line) => {
+      const pts = line.map((p) => project(cam, p));
+      if (pts.some((p) => p.depth <= 0.01)) return [];
+      return [
+        `<polyline data-mark="${esc(m.name ?? 'mark')}" points="${pts.map((p) => `${num(p.x)},${num(p.y)}`).join(' ')}" ` +
+          `fill="none" stroke="${m.color ?? '#0b7285'}" stroke-width="${m.width ?? 2}" ` +
+          `stroke-linecap="round" stroke-linejoin="round"/>`,
+      ];
+    }),
+  );
+
+  return [
+    `<g data-view="${name}" transform="translate(${x} ${y})">`,
+    `<rect width="${o.size}" height="${o.size}" fill="${o.background}" stroke="#cfcfd4"/>`,
+    `<text x="10" y="20" font-family="monospace" font-size="13" fill="#555">${name}</text>`,
+    ...body,
+    ...marks,
+    '</g>',
+  ].join('\n');
+};
+
+const root = (w, h, body) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="${w}" height="${h}">\n${body}\n</svg>\n`;
+
+/**
+ * One standalone SVG for a single view: 'front' | 'side' | 'top' | 'persp',
+ * or a custom { dir, up, ortho, name? } spec.
+ */
+export const renderView = (mesh, view, opts = {}) => {
+  const o = { ...defaults, ...opts };
+  return root(o.size, o.size, panel(mesh, view, o));
+};
+
+/** The four views one after another: [{ name, svg }, ...]. */
+export const renderViews = (mesh, opts = {}) =>
+  VIEW_ORDER.map((name) => ({ name, svg: renderView(mesh, name, opts) }));
+
+/** All four views on one 2x2 sheet: front, side / top, persp. */
+export const renderSheet = (mesh, opts = {}) => {
+  const o = { ...defaults, ...opts };
+  const body = VIEW_ORDER.map((name, i) =>
+    panel(mesh, name, o, (i % 2) * o.size, Math.floor(i / 2) * o.size),
+  ).join('\n');
+  return root(o.size * 2, o.size * 2, body);
+};