3draft 26.11.2005 → 26.11.4010

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export declare const name: "3draft";
-export declare const version = "26.11.2005";
+export declare const version = "26.11.4010";
 export type { Vec3, Face, Mesh, Axes, ViewName, ViewSpec, Fit, Camera, Hit, Mark } from './types.js';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export type { BoxOptions } from './mesh.js';
 export { validate } from './check.js';
+export { boolean, union, subtract, intersect, health } from './csg.js';
+export type { BooleanOp, Health, Part } from './csg.js';
 export type { Validation } from './check.js';
 export { extrudeFace, moveVertices } from './edit.js';
 export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
@@ -16,6 +18,8 @@ export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight,
 export type { Gpu, GpuLight, GpuMaterial, GpuRenderOptions, Instance, Pixels } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
 export type { RenderOptions } from './svg.js';
+export { surfaceOf, DEFAULTS as MATERIAL_DEFAULTS } from './material.js';
+export type { Material, Palette, Surface } from './material.js';
 export { displayVersion } from './version.js';
 export interface Info {
     name: string;
@@ -27,3 +31,5 @@ export interface Info {
 export declare const info: () => Info;
 export { initKernel } from './kernel.js';
 export type { Kernel } from './kernel.js';
+export { insertVertex, cutFace, moveVertex, fillLoop, addLine, findLoop, nearestSurface, wireFromSegments, moveVertexSet } from './wire.js';
+export type { Wire } from './wire.js';

package/dist/index.js

@@ -4,9 +4,10 @@
 // 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.2005';
+export const version = '26.11.4010';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export { validate } from './check.js';
+export { boolean, union, subtract, intersect, health } from './csg.js';
 export { extrudeFace, moveVertices } from './edit.js';
 export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
 export { pick, crosshair } from './pick.js';
@@ -14,6 +15,7 @@ export { standOn } from './place.js';
 export { paintOrder } from './order.js';
 export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
+export { surfaceOf, DEFAULTS as MATERIAL_DEFAULTS } from './material.js';
 export { displayVersion } from './version.js';
 /** Short, machine-readable description of the current state of the package. */
 export const info = () => ({
@@ -28,3 +30,4 @@ export const info = () => ({
     ],
 });
 export { initKernel } from './kernel.js';
+export { insertVertex, cutFace, moveVertex, fillLoop, addLine, findLoop, nearestSurface, wireFromSegments, moveVertexSet } from './wire.js';

package/dist/material.d.ts

@@ -0,0 +1,32 @@
+import type { Face } from './types.js';
+export interface Material {
+    /** #rrggbb. */
+    color: string;
+    /** 0 = paint, 1 = metal (reflects the sky and the ground, tinted by the color). */
+    metal?: number;
+    /** 0 = mirror-like, 1 = matte; widens the highlight. */
+    rough?: number;
+    /** 1 = solid, 0 = invisible. Blended over what is behind it (WebGPU: a second pass, far to near). */
+    alpha?: number;
+    /** 0..5: how much the color glows on its own, unlit. Up to 1 it fades from lit to flat colour; above 1 (WebGPU `tonemap`) it is a light source: that many times brighter. */
+    emit?: number;
+}
+export type Palette = Record<string, Material>;
+/** What a face is made of, all numbers filled in. */
+export interface Surface {
+    color: string;
+    metal: number;
+    rough: number;
+    alpha: number;
+    emit: number;
+}
+export declare const EMIT_MAX = 5;
+export declare const FALLBACK_COLOR = "#c8c8c8";
+export declare const DEFAULTS: {
+    readonly metal: 0;
+    readonly rough: 0.7;
+    readonly alpha: 1;
+    readonly emit: 0;
+};
+/** The surface of a face: its palette entry when it names one, else just its color with default properties. */
+export declare const surfaceOf: (face: Pick<Face, "color" | "mat">, palette?: Palette) => Surface;

package/dist/material.js

@@ -0,0 +1,18 @@
+// Materials are data. A palette is a plain object { name: Material }; a face points at an entry by name
+// (`face.mat`) and keeps its own `color` as a fallback, so a mesh still looks right without the palette.
+// One shader draws all of them; the numbers below are the only knobs.
+const clamp = (n, fallback, max = 1) => (typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(max, n)) : fallback);
+export const EMIT_MAX = 5;
+export const FALLBACK_COLOR = '#c8c8c8';
+export const DEFAULTS = { metal: 0, rough: 0.7, alpha: 1, emit: 0 };
+/** The surface of a face: its palette entry when it names one, else just its color with default properties. */
+export const surfaceOf = (face, palette) => {
+    const m = face.mat !== undefined ? palette?.[face.mat] : undefined;
+    return {
+        color: m?.color ?? face.color ?? FALLBACK_COLOR,
+        metal: clamp(m?.metal, DEFAULTS.metal),
+        rough: clamp(m?.rough, DEFAULTS.rough),
+        alpha: clamp(m?.alpha, DEFAULTS.alpha),
+        emit: clamp(m?.emit, DEFAULTS.emit, EMIT_MAX),
+    };
+};

package/dist/svg.d.ts

@@ -1,3 +1,4 @@
+import type { Palette } from './material.js';
 import type { Fit, Mark, Mesh, ViewName, ViewSpec } from './types.js';
 export interface RenderOptions {
     /** Panel size in px (default 400). */
@@ -6,6 +7,14 @@ export interface RenderOptions {
     cull?: boolean;
     /** Draw the vertices as circles (default true). */
     points?: boolean;
+    /**
+     * Send only what can be seen (default false). Faces are first painted into a small id buffer, far to
+     * near; a face none of whose pixels survives is covered by nearer ones and is left out, and so is a
+     * point no visible face reaches. The picture stays the same, the SVG gets much smaller.
+     */
+    occlude?: boolean;
+    /** Named materials (`face.mat`). The SVG shows their color and alpha; metal, rough and emit are for the GPU view. */
+    palette?: Palette;
     stroke?: string;
     pointColor?: string;
     background?: string;

package/dist/svg.js

@@ -5,6 +5,74 @@ import { dot, norm, minus } from './vec.js';
 import { faceNormal } from './mesh.js';
 import { paintOrder } from './order.js';
 import { VIEW_ORDER, makeCamera, project } from './camera.js';
+import { surfaceOf } from './material.js';
+/**
+ * Depth-tested scanline fill of one polygon into an id buffer. `w` grows towards the eye (1/depth in a
+ * perspective view, -depth in an orthographic one) and is linear across a planar face on the screen.
+ * A pixel that ties with what is there (coplanar faces) keeps both ids alive for the painter's order.
+ */
+const fill = (ids, zb, size, pts, w, id, alive, solid = true) => {
+    const test = (x, y, v) => {
+        if (x < 0 || y < 0 || x >= size || y >= size)
+            return;
+        const at = y * size + x;
+        const old = zb[at];
+        const tie = Math.abs(v - old) <= 1e-5 * Math.abs(old);
+        if (!solid) {
+            // a see-through face is visible where nothing nearer hides it, and hides nothing itself
+            if (v > old || tie)
+                alive.add(id);
+            return;
+        }
+        if (v > old || tie) {
+            if (tie && ids[at] >= 0)
+                alive.add(ids[at]);
+            zb[at] = Math.max(v, old);
+            ids[at] = id;
+        }
+    };
+    // the outline too: a face thinner than a pixel still shows as a line
+    for (let a = 0; a < pts.length; a++) {
+        const b = (a + 1) % pts.length;
+        const n = Math.ceil(Math.max(Math.abs(pts[b].x - pts[a].x), Math.abs(pts[b].y - pts[a].y)));
+        for (let i = 0; i <= n; i++) {
+            const t = n ? i / n : 0;
+            test(Math.floor(pts[a].x + t * (pts[b].x - pts[a].x)), Math.floor(pts[a].y + t * (pts[b].y - pts[a].y)), w[a] + t * (w[b] - w[a]));
+        }
+    }
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const p of pts)
+        (lo = Math.min(lo, p.y), (hi = Math.max(hi, p.y)));
+    const y0 = Math.max(0, Math.ceil(lo - 0.5));
+    const y1 = Math.min(size - 1, Math.floor(hi - 0.5));
+    const cross = [];
+    for (let y = y0; y <= y1; y++) {
+        const yc = y + 0.5;
+        cross.length = 0;
+        for (let a = 0; a < pts.length; a++) {
+            const b = (a + 1) % pts.length;
+            const p = pts[a];
+            const q = pts[b];
+            if ((p.y <= yc && q.y > yc) || (q.y <= yc && p.y > yc)) {
+                const t = (yc - p.y) / (q.y - p.y);
+                cross.push({ x: p.x + t * (q.x - p.x), w: w[a] + t * (w[b] - w[a]) });
+            }
+        }
+        cross.sort((a, b) => a.x - b.x);
+        for (let k = 0; k + 1 < cross.length; k += 2) {
+            const l = cross[k];
+            const r = cross[k + 1];
+            const x0 = Math.max(0, Math.ceil(l.x - 0.5));
+            const x1 = Math.min(size - 1, Math.floor(r.x - 0.5));
+            const span = r.x - l.x || 1;
+            for (let x = x0; x <= x1; x++) {
+                const v = l.w + ((x + 0.5 - l.x) / span) * (r.w - l.w);
+                test(x, y, v);
+            }
+        }
+    }
+};
 const defaults = {
     size: 400,
     cull: true,
@@ -58,6 +126,7 @@ const panel = (mesh, view, o, x = 0, y = 0) => {
         }
         if (!seen(screen))
             return; // outside the panel
+        const surface = surfaceOf(face, o.palette);
         items.push({
             i,
             vs: face.v,
@@ -66,22 +135,66 @@ const panel = (mesh, view, o, x = 0, y = 0) => {
             n: norm(normal),
             p: world[0],
             eye: facing ? 1 : -1,
-            color: face.color ?? '#c8c8c8',
+            color: surface.color,
+            alpha: surface.alpha,
             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
+    // Occlusion: a depth buffer finds the faces that own a pixel; only those go on to the painter's order.
+    let idBuf = null;
+    let visible = items;
+    if (o.occlude) {
+        const buf = new Int32Array(o.size * o.size).fill(-1);
+        const zb = new Float32Array(o.size * o.size).fill(-Infinity);
+        const alive = new Set();
+        items.forEach((it, idx) => {
+            const w = it.screen.map((p) => (cam.ortho ? -p.depth : 1 / p.depth));
+            fill(buf, zb, o.size, it.screen, w, idx, alive, it.alpha >= 1);
+        });
+        for (const id of buf)
+            if (id >= 0)
+                alive.add(id);
+        const remap = new Map(); // item index -> index among the visible faces
+        visible = items.filter((_, idx) => alive.has(idx) && (remap.set(idx, remap.size), true));
+        idBuf = buf.map((id) => (id < 0 ? -1 : (remap.get(id) ?? -1)));
+    }
+    let ordered = paintOrder(visible); // far to near
+    if (idBuf) {
+        // ids point into `visible`; the painter's order permutes it
+        const at = new Map();
+        visible.forEach((it, n) => at.set(it, n));
+        const perm = new Int32Array(visible.length);
+        ordered.forEach((it, n) => (perm[at.get(it)] = n));
+        idBuf = idBuf.map((id) => (id < 0 ? -1 : perm[id]));
+    }
     // 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)));
+    // a point is visible when a visible face that holds it owns a pixel at (or right next to) it
+    const reached = (k) => {
+        const px = Math.round(proj[k].x);
+        const py = Math.round(proj[k].y);
+        for (let dy = -1; dy <= 1; dy++) {
+            for (let dx = -1; dx <= 1; dx++) {
+                const x = px + dx;
+                const y = py + dy;
+                if (x < 0 || y < 0 || x >= o.size || y >= o.size)
+                    continue;
+                const id = idBuf[y * o.size + x];
+                if (id >= 0 && ordered[id].vs.includes(k))
+                    return true;
+            }
+        }
+        return false;
+    };
     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"/>`;
+            `fill="${it.color}"${it.alpha < 1 ? ` fill-opacity="${num(it.alpha)}"` : ''} stroke="${o.stroke}" stroke-width="1.5" stroke-linejoin="round"/>`;
         const dots = o.points
             ? it.vs
-                .filter((k) => last.get(k) === idx && (cam.ortho || proj[k].depth >= NEAR))
+                .filter((k) => last.get(k) === idx && (cam.ortho || proj[k].depth >= NEAR) && (!idBuf || reached(k)))
                 .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}"/>`)
             : [];

package/dist/types.d.ts

@@ -3,6 +3,8 @@ export interface Face {
     /** Point indices, CCW seen from outside. */
     v: number[];
     color?: string;
+    /** Name of a palette entry (see material.ts); `color` is the fallback. */
+    mat?: string;
 }
 export interface Mesh {
     positions: Vec3[];

package/dist/wire.d.ts

@@ -0,0 +1,57 @@
+import type { Mesh, Vec3, Face } from './types.js';
+/** Lines drawn on / off a mesh: pairs of vertex indices. */
+export type Wire = [number, number][];
+/**
+ * Puts a vertex at `point`, which lies on face `face`. On an existing vertex it returns that one; on an edge it is
+ * added to both faces that share the edge (no crack); inside the face it splits the face into triangles around it.
+ * { mesh, index }
+ */
+export declare const insertVertex: (mesh: Mesh, face: number, point: Vec3) => {
+    mesh: Mesh;
+    index: number;
+};
+/**
+ * Cuts the face that holds vertices `a` and `b` (not next to each other) along the line a-b: two convex faces.
+ * `cut` is false when no face holds both, or they are already neighbours on every face.
+ */
+export declare const cutFace: (mesh: Mesh, a: number, b: number) => {
+    mesh: Mesh;
+    cut: boolean;
+};
+/** Moves vertex `i` to `to`. Polygons that use it become triangles, so every face stays planar. */
+export declare const moveVertex: (mesh: Mesh, i: number, to: Vec3) => Mesh;
+/**
+ * A face from a closed loop of vertices. It is wound to point away from `awayFrom` (default: the middle of the
+ * mesh), which is what a patch closing a gap in a surface wants; 4 or more vertices become a fan of triangles.
+ */
+export declare const fillLoop: (mesh: Mesh, loop: number[], face?: Partial<Face>, awayFrom?: Vec3) => Mesh;
+/** Adds the line a-b (not twice, not a point). */
+export declare const addLine: (wire: Wire, a: number, b: number) => Wire;
+/**
+ * The shortest closed loop of lines through line [a, b], at most `max` vertices: [a, ..., b], or null.
+ * Close it with fillLoop.
+ */
+export declare const findLoop: (wire: Wire, [a, b]: [number, number], max?: number) => number[] | null;
+/**
+ * The surface point of the mesh nearest to `p`, if it is within `tolerance`: { face, point } (point lies on the face),
+ * otherwise null. For placing a point that was drawn near a surface on the surface.
+ */
+export declare const nearestSurface: (mesh: Mesh, p: Vec3, tolerance: number) => {
+    face: number;
+    point: Vec3;
+} | null;
+/**
+ * Turns line segments (pairs of points) into wire on the mesh: each end becomes a vertex (an existing one within
+ * `tolerance`, a new one on the surface when it is near it, otherwise a free point in the air), each segment a line,
+ * and two ends on one face cut that face. Returns the new mesh and wire.
+ */
+export declare const wireFromSegments: (mesh: Mesh, wire: Wire, segments: [Vec3, Vec3][], tolerance: number) => {
+    mesh: Mesh;
+    wire: Wire;
+};
+/**
+ * Moves several vertices at once: `moves` is [[index, newPosition], ...]. A polygon whose vertices all moved by the
+ * same step (a face dragged as a whole) stays as it is; any other polygon that uses a moved vertex becomes triangles,
+ * so every face stays planar.
+ */
+export declare const moveVertexSet: (mesh: Mesh, moves: [number, Vec3][]) => Mesh;

package/dist/wire.js

@@ -0,0 +1,244 @@
+// Drawing on a mesh: put a vertex on a surface, cut a face along a line between two vertices,
+// move a vertex, close a loop of lines into a face. The wire is a list of [a, b] vertex pairs next to the mesh:
+// its ends are ordinary mesh vertices, so moving a vertex moves every line (and every face) that uses it.
+// Faces stay convex and planar: a vertex placed inside a face splits it into triangles, a cut splits a convex
+// polygon into two convex ones, and a moved vertex turns the polygons it touches into triangles.
+import { sub, add, scale, dot, len } from './vec.js';
+import { faceNormal, bounds } from './mesh.js';
+const sizeOf = (mesh) => bounds(mesh).radius || 1;
+/** Distance from `p` to the segment a-b, and where along it (0..1). */
+const toSegment = (p, a, b) => {
+    const ab = sub(b, a);
+    const l2 = dot(ab, ab) || 1;
+    const t = Math.max(0, Math.min(1, dot(sub(p, a), ab) / l2));
+    return { distance: len(sub(p, add(a, scale(ab, t)))), t };
+};
+const withFaces = (mesh, faces, positions = mesh.positions) => ({ ...mesh, positions, faces });
+/**
+ * Puts a vertex at `point`, which lies on face `face`. On an existing vertex it returns that one; on an edge it is
+ * added to both faces that share the edge (no crack); inside the face it splits the face into triangles around it.
+ * { mesh, index }
+ */
+export const insertVertex = (mesh, face, point) => {
+    const eps = 1e-6 * sizeOf(mesh);
+    const f = mesh.faces[face];
+    const { positions } = mesh;
+    for (const v of f.v)
+        if (len(sub(positions[v], point)) <= eps * 10)
+            return { mesh, index: v };
+    const index = positions.length;
+    const next = [...positions, point];
+    const m = f.v.length;
+    for (let j = 0; j < m; j++) {
+        const a = f.v[j];
+        const b = f.v[(j + 1) % m];
+        if (toSegment(point, positions[a], positions[b]).distance > eps * 10)
+            continue;
+        // on the edge a-b: every face holding that edge (same positions, either direction) gets the new vertex
+        const faces = mesh.faces.map((g, gi) => {
+            const n = g.v.length;
+            for (let k = 0; k < n; k++) {
+                const p = positions[g.v[k]];
+                const q = positions[g.v[(k + 1) % n]];
+                const same = (len(sub(p, positions[a])) <= eps && len(sub(q, positions[b])) <= eps) || (len(sub(p, positions[b])) <= eps && len(sub(q, positions[a])) <= eps);
+                if (same)
+                    return { ...g, v: [...g.v.slice(0, k + 1), index, ...g.v.slice(k + 1)] };
+            }
+            return gi === face ? g : g;
+        });
+        return { mesh: withFaces(mesh, faces, next), index };
+    }
+    // inside: a fan of triangles around the new vertex, same side as the face
+    const fan = f.v.map((v, j) => ({ ...f, v: [v, f.v[(j + 1) % m], index] }));
+    return { mesh: withFaces(mesh, [...mesh.faces.slice(0, face), ...fan, ...mesh.faces.slice(face + 1)], next), index };
+};
+/**
+ * Cuts the face that holds vertices `a` and `b` (not next to each other) along the line a-b: two convex faces.
+ * `cut` is false when no face holds both, or they are already neighbours on every face.
+ */
+export const cutFace = (mesh, a, b) => {
+    for (let fi = 0; fi < mesh.faces.length; fi++) {
+        const f = mesh.faces[fi];
+        const ia = f.v.indexOf(a);
+        const ib = f.v.indexOf(b);
+        if (ia < 0 || ib < 0)
+            continue;
+        const m = f.v.length;
+        if ((ia - ib + m) % m === 1 || (ib - ia + m) % m === 1)
+            continue;
+        const walk = (from, to) => {
+            const out = [f.v[from]];
+            for (let k = from; k !== to;) {
+                k = (k + 1) % m;
+                out.push(f.v[k]);
+            }
+            return out;
+        };
+        const faces = [...mesh.faces.slice(0, fi), { ...f, v: walk(ia, ib) }, { ...f, v: walk(ib, ia) }, ...mesh.faces.slice(fi + 1)];
+        return { mesh: withFaces(mesh, faces), cut: true };
+    }
+    return { mesh, cut: false };
+};
+/** Moves vertex `i` to `to`. Polygons that use it become triangles, so every face stays planar. */
+export const moveVertex = (mesh, i, to) => {
+    const positions = mesh.positions.map((p, k) => (k === i ? to : p));
+    const faces = [];
+    for (const f of mesh.faces) {
+        if (f.v.length <= 3 || !f.v.includes(i))
+            faces.push(f);
+        else
+            for (let j = 1; j < f.v.length - 1; j++)
+                faces.push({ ...f, v: [f.v[0], f.v[j], f.v[j + 1]] });
+    }
+    return withFaces(mesh, faces, positions);
+};
+/**
+ * A face from a closed loop of vertices. It is wound to point away from `awayFrom` (default: the middle of the
+ * mesh), which is what a patch closing a gap in a surface wants; 4 or more vertices become a fan of triangles.
+ */
+export const fillLoop = (mesh, loop, face = {}, awayFrom = bounds(mesh).center) => {
+    if (loop.length < 3)
+        return mesh;
+    const pts = loop.map((v) => mesh.positions[v]);
+    const centre = scale(pts.reduce((s, p) => add(s, p), [0, 0, 0]), 1 / pts.length);
+    const ordered = dot(faceNormal(pts), sub(centre, awayFrom)) >= 0 ? loop : [...loop].reverse();
+    const out = [];
+    for (let j = 1; j < ordered.length - 1; j++)
+        out.push({ ...face, v: [ordered[0], ordered[j], ordered[j + 1]] });
+    return withFaces(mesh, [...mesh.faces, ...out]);
+};
+/** Adds the line a-b (not twice, not a point). */
+export const addLine = (wire, a, b) => (a === b || wire.some(([p, q]) => (p === a && q === b) || (p === b && q === a)) ? wire : [...wire, [a, b]]);
+/**
+ * The shortest closed loop of lines through line [a, b], at most `max` vertices: [a, ..., b], or null.
+ * Close it with fillLoop.
+ */
+export const findLoop = (wire, [a, b], max = 8) => {
+    const near = new Map();
+    for (const [p, q] of wire) {
+        if ((p === a && q === b) || (p === b && q === a))
+            continue; // not through the line itself
+        near.set(p, [...(near.get(p) ?? []), q]);
+        near.set(q, [...(near.get(q) ?? []), p]);
+    }
+    const from = new Map([[a, -1]]);
+    const queue = [a];
+    for (let head = 0; head < queue.length; head++) {
+        const v = queue[head];
+        if (v === b)
+            break;
+        for (const w of near.get(v) ?? [])
+            if (!from.has(w))
+                (from.set(w, v), queue.push(w));
+    }
+    if (!from.has(b))
+        return null;
+    const path = [];
+    for (let v = b; v !== -1; v = from.get(v))
+        path.unshift(v);
+    return path.length <= max ? path : null;
+};
+/** The point of triangle a-b-c closest to p (Ericson, Real-Time Collision Detection). */
+const closestOnTriangle = (p, a, b, c) => {
+    const ab = sub(b, a);
+    const ac = sub(c, a);
+    const ap = sub(p, a);
+    const d1 = dot(ab, ap);
+    const d2 = dot(ac, ap);
+    if (d1 <= 0 && d2 <= 0)
+        return a;
+    const bp = sub(p, b);
+    const d3 = dot(ab, bp);
+    const d4 = dot(ac, bp);
+    if (d3 >= 0 && d4 <= d3)
+        return b;
+    const vc = d1 * d4 - d3 * d2;
+    if (vc <= 0 && d1 >= 0 && d3 <= 0)
+        return add(a, scale(ab, d1 / (d1 - d3)));
+    const cp = sub(p, c);
+    const d5 = dot(ab, cp);
+    const d6 = dot(ac, cp);
+    if (d6 >= 0 && d5 <= d6)
+        return c;
+    const vb = d5 * d2 - d1 * d6;
+    if (vb <= 0 && d2 >= 0 && d6 <= 0)
+        return add(a, scale(ac, d2 / (d2 - d6)));
+    const va = d3 * d6 - d5 * d4;
+    if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0)
+        return add(b, scale(sub(c, b), (d4 - d3) / (d4 - d3 + (d5 - d6))));
+    const denom = 1 / (va + vb + vc);
+    return add(a, add(scale(ab, vb * denom), scale(ac, vc * denom)));
+};
+/**
+ * The surface point of the mesh nearest to `p`, if it is within `tolerance`: { face, point } (point lies on the face),
+ * otherwise null. For placing a point that was drawn near a surface on the surface.
+ */
+export const nearestSurface = (mesh, p, tolerance) => {
+    let best = null;
+    mesh.faces.forEach((f, face) => {
+        const pts = f.v.map((v) => mesh.positions[v]);
+        for (let j = 1; j < pts.length - 1; j++) {
+            const q = closestOnTriangle(p, pts[0], pts[j], pts[j + 1]);
+            const d = len(sub(q, p));
+            if (d <= tolerance && (!best || d < best.d))
+                best = { face, point: q, d };
+        }
+    });
+    return best ? { face: best.face, point: best.point } : null;
+};
+/**
+ * Turns line segments (pairs of points) into wire on the mesh: each end becomes a vertex (an existing one within
+ * `tolerance`, a new one on the surface when it is near it, otherwise a free point in the air), each segment a line,
+ * and two ends on one face cut that face. Returns the new mesh and wire.
+ */
+export const wireFromSegments = (mesh, wire, segments, tolerance) => {
+    let m = mesh;
+    let w = wire;
+    const vertexAt = (p) => {
+        const near = m.positions.findIndex((q) => len(sub(q, p)) <= tolerance);
+        if (near >= 0)
+            return near;
+        const s = nearestSurface(m, p, tolerance);
+        if (s) {
+            const r = insertVertex(m, s.face, s.point);
+            m = r.mesh;
+            return r.index;
+        }
+        m = { ...m, positions: [...m.positions, p] };
+        return m.positions.length - 1;
+    };
+    for (const [a, b] of segments) {
+        const ia = vertexAt(a);
+        const ib = vertexAt(b);
+        if (ia === ib)
+            continue;
+        w = addLine(w, ia, ib);
+        m = cutFace(m, ia, ib).mesh;
+    }
+    return { mesh: m, wire: w };
+};
+/**
+ * Moves several vertices at once: `moves` is [[index, newPosition], ...]. A polygon whose vertices all moved by the
+ * same step (a face dragged as a whole) stays as it is; any other polygon that uses a moved vertex becomes triangles,
+ * so every face stays planar.
+ */
+export const moveVertexSet = (mesh, moves) => {
+    const to = new Map(moves);
+    const positions = mesh.positions.map((p, k) => to.get(k) ?? p);
+    const step = (v) => sub(positions[v], mesh.positions[v]);
+    const faces = [];
+    for (const f of mesh.faces) {
+        if (f.v.length <= 3 || !f.v.some((v) => to.has(v))) {
+            faces.push(f);
+            continue;
+        }
+        const first = step(f.v[0]);
+        const rigid = f.v.every((v) => len(sub(step(v), first)) < 1e-9 * (bounds(mesh).radius || 1));
+        if (rigid)
+            faces.push(f);
+        else
+            for (let j = 1; j < f.v.length - 1; j++)
+                faces.push({ ...f, v: [f.v[0], f.v[j], f.v[j + 1]] });
+    }
+    return withFaces(mesh, faces, positions);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3draft",
-  "version": "26.11.2005",
+  "version": "26.11.4010",
   "description": "Minimalist AI first 3D engine: palette-texture, WASM core, WebGPU/WebGL2 renderer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,7 @@
     "dist",
     "!dist/**/*.test.*",
     "README.md",
+    "APP.md",
     "LICENSE"
   ],
   "scripts": {