@es3d/es3d 0.0.0-stage → 1.0.1

package/src/format/xml-tokenizer.js

@@ -0,0 +1,237 @@
+// Tokenizer for the ES3D markup syntax (an XML subset).
+//
+// A hand written, allocation-light scanner: the parser pulls tokens one at a
+// time with next(). Every token carries character offsets so the parser and
+// validator can report exact line/column positions and the editor can perform
+// lossless text edits.
+
+import { Diagnostic, ES3DError } from './errors.js';
+
+export const Tok = Object.freeze({
+  OPEN: 'open', // <name
+  ATTR: 'attr', // name="value"
+  OPEN_END: 'openEnd', // > or />
+  CLOSE: 'close', // </name>
+  TEXT: 'text',
+  COMMENT: 'comment',
+  CDATA: 'cdata',
+  PI: 'pi', // <?xml ... ?>
+  DOCTYPE: 'doctype',
+  EOF: 'eof',
+});
+
+const LT = 60;
+const GT = 62;
+const SLASH = 47;
+const EQ = 61;
+const DQ = 34;
+const SQ = 39;
+const BANG = 33;
+const QM = 63;
+const AMP = 38;
+
+function isSpace(c) {
+  return c === 32 || c === 10 || c === 9 || c === 13;
+}
+
+function isNameStart(c) {
+  return (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95 || c === 58 || c > 127;
+}
+
+function isNameChar(c) {
+  return isNameStart(c) || (c >= 48 && c <= 57) || c === 45 || c === 46;
+}
+
+const NAMED_ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** Decode XML entity references; reports bad references with exact offsets. */
+export function decodeEntities(raw, baseOffset, fail) {
+  if (raw.indexOf('&') < 0) return raw;
+  let out = '';
+  let i = 0;
+  while (i < raw.length) {
+    const amp = raw.indexOf('&', i);
+    if (amp < 0) {
+      out += raw.slice(i);
+      break;
+    }
+    out += raw.slice(i, amp);
+    const semi = raw.indexOf(';', amp);
+    if (semi < 0 || semi - amp > 12) {
+      fail('E_BAD_ENTITY', "Unescaped '&'. Write '&amp;' for a literal ampersand.", baseOffset + amp, 1);
+    }
+    const name = raw.slice(amp + 1, semi);
+    let ch;
+    if (name[0] === '#') {
+      const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+      if (!Number.isFinite(code) || code < 0 || code > 0x10ffff) {
+        fail('E_BAD_ENTITY', `Invalid character reference '&${name};'.`, baseOffset + amp, semi - amp + 1);
+      }
+      ch = String.fromCodePoint(code);
+    } else {
+      ch = NAMED_ENTITIES[name];
+      if (ch === undefined) {
+        fail('E_BAD_ENTITY', `Unknown entity '&${name};'. Only &lt; &gt; &amp; &quot; &apos; and numeric references are allowed.`, baseOffset + amp, semi - amp + 1);
+      }
+    }
+    out += ch;
+    i = semi + 1;
+  }
+  return out;
+}
+
+export class XmlTokenizer {
+  constructor(text, lineIndex = null) {
+    this.s = text;
+    this.i = 0;
+    this.inTag = false;
+    this.lineIndex = lineIndex;
+    this.n = text.length;
+    // Skip a UTF-8 byte order mark.
+    if (text.charCodeAt(0) === 0xfeff) this.i = 1;
+  }
+
+  fail(code, message, offset, length = 1, extra = {}) {
+    const d = new Diagnostic({ code, message, offset, length, ...extra });
+    d.locate(this.lineIndex);
+    throw new ES3DError([d], this.lineIndex);
+  }
+
+  next() {
+    return this.inTag ? this.nextInTag() : this.nextContent();
+  }
+
+  nextContent() {
+    const s = this.s;
+    const start = this.i;
+    if (start >= this.n) return { type: Tok.EOF, start, end: start };
+    if (s.charCodeAt(start) !== LT) {
+      let end = s.indexOf('<', start);
+      if (end < 0) end = this.n;
+      this.i = end;
+      const raw = s.slice(start, end);
+      return { type: Tok.TEXT, raw, text: null, start, end };
+    }
+    const c1 = s.charCodeAt(start + 1);
+    if (c1 === BANG) {
+      if (s.startsWith('<!--', start)) {
+        const end = s.indexOf('-->', start + 4);
+        if (end < 0) this.fail('E_UNTERMINATED_COMMENT', "Unterminated comment: missing '-->'.", start, 4);
+        this.i = end + 3;
+        return { type: Tok.COMMENT, text: s.slice(start + 4, end), start, end: end + 3 };
+      }
+      if (s.startsWith('<![CDATA[', start)) {
+        const end = s.indexOf(']]>', start + 9);
+        if (end < 0) this.fail('E_UNTERMINATED_CDATA', "Unterminated CDATA section: missing ']]>'.", start, 9);
+        this.i = end + 3;
+        return { type: Tok.CDATA, text: s.slice(start + 9, end), start, end: end + 3 };
+      }
+      if (s.startsWith('<!DOCTYPE', start) || s.startsWith('<!doctype', start)) {
+        const end = s.indexOf('>', start);
+        if (end < 0) this.fail('E_UNTERMINATED_DOCTYPE', "Unterminated DOCTYPE: missing '>'.", start, 9);
+        this.i = end + 1;
+        return { type: Tok.DOCTYPE, start, end: end + 1 };
+      }
+      this.fail('E_SYNTAX', "Unexpected '<!'. Comments are written <!-- like this -->.", start, 2);
+    }
+    if (c1 === QM) {
+      const end = s.indexOf('?>', start + 2);
+      if (end < 0) this.fail('E_UNTERMINATED_PI', "Unterminated processing instruction: missing '?>'.", start, 2);
+      this.i = end + 2;
+      let j = start + 2;
+      while (j < end && isNameChar(s.charCodeAt(j))) j++;
+      return { type: Tok.PI, target: s.slice(start + 2, j), start, end: end + 2 };
+    }
+    if (c1 === SLASH) {
+      const nameStart = start + 2;
+      let j = nameStart;
+      if (!isNameStart(s.charCodeAt(j))) this.fail('E_SYNTAX', "Expected an element name after '</'.", j, 1);
+      while (j < this.n && isNameChar(s.charCodeAt(j))) j++;
+      const nameEnd = j;
+      while (j < this.n && isSpace(s.charCodeAt(j))) j++;
+      if (s.charCodeAt(j) !== GT) this.fail('E_SYNTAX', `Expected '>' to finish closing tag </${s.slice(nameStart, nameEnd)}>.`, j, 1);
+      this.i = j + 1;
+      return { type: Tok.CLOSE, name: s.slice(nameStart, nameEnd), start, end: j + 1, nameStart, nameEnd };
+    }
+    const nameStart = start + 1;
+    if (!isNameStart(c1)) {
+      this.fail('E_SYNTAX', "Unexpected '<'. Element names must start with a letter; write '&lt;' for a literal '<'.", start, 1);
+    }
+    let j = nameStart + 1;
+    while (j < this.n && isNameChar(s.charCodeAt(j))) j++;
+    this.i = j;
+    this.inTag = true;
+    return { type: Tok.OPEN, name: s.slice(nameStart, j), start, nameStart, nameEnd: j };
+  }
+
+  nextInTag() {
+    const s = this.s;
+    let i = this.i;
+    const hadSpace = i < this.n && isSpace(s.charCodeAt(i));
+    while (i < this.n && isSpace(s.charCodeAt(i))) i++;
+    if (i >= this.n) this.fail('E_UNEXPECTED_EOF', "Unexpected end of file inside a tag: missing '>'.", i, 0);
+    const c = s.charCodeAt(i);
+    if (c === GT) {
+      this.i = i + 1;
+      this.inTag = false;
+      return { type: Tok.OPEN_END, selfClosing: false, start: i, end: i + 1 };
+    }
+    if (c === SLASH) {
+      if (s.charCodeAt(i + 1) !== GT) this.fail('E_SYNTAX', "Expected '/>' to close the tag.", i, 1);
+      this.i = i + 2;
+      this.inTag = false;
+      return { type: Tok.OPEN_END, selfClosing: true, start: i, end: i + 2 };
+    }
+    if (!isNameStart(c)) {
+      if (c === DQ || c === SQ) this.fail('E_SYNTAX', 'Unexpected quoted value: an attribute name is missing.', i, 1);
+      if (c === LT) this.fail('E_SYNTAX', "Unexpected '<': the previous tag is missing its '>'.", i, 1);
+      this.fail('E_SYNTAX', `Unexpected character '${s[i]}' in tag.`, i, 1);
+    }
+    if (!hadSpace) this.fail('E_SYNTAX', 'Attributes must be separated by whitespace.', i, 1);
+    const nameStart = i;
+    while (i < this.n && isNameChar(s.charCodeAt(i))) i++;
+    const nameEnd = i;
+    const name = s.slice(nameStart, nameEnd);
+    while (i < this.n && isSpace(s.charCodeAt(i))) i++;
+    if (s.charCodeAt(i) !== EQ) {
+      this.fail('E_SYNTAX', `Attribute '${name}' has no value. Write ${name}="...".`, nameStart, nameEnd - nameStart);
+    }
+    i++;
+    while (i < this.n && isSpace(s.charCodeAt(i))) i++;
+    const q = s.charCodeAt(i);
+    if (q !== DQ && q !== SQ) {
+      this.fail('E_UNQUOTED_ATTRIBUTE', `The value of attribute '${name}' must be quoted.`, i, 1, { hint: `Write ${name}="value".` });
+    }
+    const valueStart = i + 1;
+    const close = s.indexOf(q === DQ ? '"' : "'", valueStart);
+    if (close < 0) {
+      this.fail('E_UNTERMINATED_ATTRIBUTE', `Unterminated value for attribute '${name}': missing closing quote.`, i, 1);
+    }
+    const lt = s.indexOf('<', valueStart);
+    if (lt >= 0 && lt < close) {
+      this.fail('E_UNTERMINATED_ATTRIBUTE', `Unterminated value for attribute '${name}': found '<' before the closing quote.`, i, 1);
+    }
+    this.i = close + 1;
+    const raw = s.slice(valueStart, close);
+    let value = raw;
+    let decoded = false;
+    if (raw.indexOf('&') >= 0) {
+      value = decodeEntities(raw, valueStart, (code, msg, off, len) => this.fail(code, msg, off, len));
+      decoded = true;
+    }
+    return {
+      type: Tok.ATTR,
+      name,
+      nameStart,
+      nameEnd,
+      value,
+      valueStart,
+      valueEnd: close,
+      quote: q === DQ ? '"' : "'",
+      decoded,
+    };
+  }
+}
+
+// keeps the tokenizer's hidden class alive between documents (see MeshBuilder.shapeKeeper)
+XmlTokenizer.shapeKeeper = new XmlTokenizer('', null);

package/src/geometry/contour.js

@@ -0,0 +1,86 @@
+// Per-vertex data for 2D contours shared by the extrusion, sweep and revolve
+// generators: edge normals, smoothed vertex normals, miter (inset) vectors and
+// cumulative arc length. Contours are oriented with the filled side on the
+// left, so the right-hand perpendicular of an edge is its outward normal.
+
+const MAX_MITER = 4;
+
+export function contourFrames(points, smooth, closed = true) {
+  const n = points.length / 2;
+  const edges = closed ? n : n - 1;
+  const edgeN = new Float64Array(edges * 2);
+  for (let i = 0; i < edges; i++) {
+    const j = (i + 1) % n;
+    const dx = points[j * 2] - points[i * 2];
+    const dy = points[j * 2 + 1] - points[i * 2 + 1];
+    const l = Math.hypot(dx, dy) || 1;
+    edgeN[i * 2] = dy / l;
+    edgeN[i * 2 + 1] = -dx / l;
+  }
+  const vertN = new Float64Array(n * 2);
+  const miter = new Float64Array(n * 2);
+  const corner = new Uint8Array(n);
+  for (let i = 0; i < n; i++) {
+    const hasPrev = closed || i > 0;
+    const hasNext = closed || i < n - 1;
+    const pe = hasPrev ? (i - 1 + edges) % edges : -1;
+    const ne = hasNext ? i % edges : -1;
+    let ax, ay, bx, by;
+    if (pe >= 0) {
+      ax = edgeN[pe * 2];
+      ay = edgeN[pe * 2 + 1];
+    }
+    if (ne >= 0) {
+      bx = edgeN[ne * 2];
+      by = edgeN[ne * 2 + 1];
+    }
+    if (pe < 0) {
+      ax = bx;
+      ay = by;
+    }
+    if (ne < 0) {
+      bx = ax;
+      by = ay;
+    }
+    let mx = ax + bx, my = ay + by;
+    let ml = Math.hypot(mx, my);
+    if (ml < 1e-9) {
+      mx = ax;
+      my = ay;
+      ml = 1;
+    }
+    mx /= ml;
+    my /= ml;
+    vertN[i * 2] = mx;
+    vertN[i * 2 + 1] = my;
+    const cosHalf = Math.max(mx * ax + my * ay, 1 / MAX_MITER);
+    miter[i * 2] = mx / cosHalf;
+    miter[i * 2 + 1] = my / cosHalf;
+    corner[i] = smooth && smooth[i] ? 0 : 1;
+  }
+  const arc = new Float64Array(n + 1);
+  for (let i = 1; i <= n; i++) {
+    if (!closed && i === n) {
+      arc[i] = arc[i - 1];
+      break;
+    }
+    const a = (i - 1) % n, b = i % n;
+    arc[i] = arc[i - 1] + Math.hypot(points[b * 2] - points[a * 2], points[b * 2 + 1] - points[a * 2 + 1]);
+  }
+  return { n, edges, edgeN, vertN, miter, corner, arc, length: arc[closed ? n : n - 1] };
+}
+
+/** Bounds of a set of 2D point arrays. */
+export function bounds2(list) {
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const pts of list) {
+    for (let i = 0; i < pts.length; i += 2) {
+      const x = pts[i], y = pts[i + 1];
+      if (x < minX) minX = x;
+      if (y < minY) minY = y;
+      if (x > maxX) maxX = x;
+      if (y > maxY) maxY = y;
+    }
+  }
+  return { minX, minY, maxX, maxY, size: Math.max(maxX - minX, maxY - minY) || 1 };
+}

package/src/geometry/extrude.js

@@ -0,0 +1,175 @@
+// Flat fills and extrusions of 2D regions.
+//
+// extrude: caps are the triangulated regions (front at z = depth facing +Z,
+// back at z = 0 facing -Z); side walls follow the contours where the fill
+// state changes. An optional quarter-circle bevel insets the caps by `bevel`
+// so the silhouette of the 2D path is kept at the widest point.
+
+import { Mesh, MeshBuilder } from './mesh.js';
+import { triangulateRegion } from '../path/shapes.js';
+import { contourFrames, bounds2 } from './contour.js';
+import { extrudeWasm } from '../wasm/kernels.js';
+
+function regionBounds(regions) {
+  const lists = [];
+  for (const r of regions) {
+    lists.push(r.outer.points);
+    for (const h of r.holes) lists.push(h.points);
+  }
+  return bounds2(lists);
+}
+
+/** Warn about a triangulation that does not cover its region (self-intersecting input). */
+export function reportTriangulation(error, report) {
+  if (error > 0.01 && report) {
+    report('warning', 'W_SELF_INTERSECTION', `A filled contour appears to be self-intersecting; the triangulation covers ${(100 * (1 - error)).toFixed(1)}% of the expected area.`);
+  }
+}
+
+/** Triangulate regions once; reports malformed (self-intersecting) input. */
+export function triangulateRegions(regions, report) {
+  const out = [];
+  for (const r of regions) {
+    const t = triangulateRegion(r);
+    reportTriangulation(t.error, report);
+    out.push({ region: r, ...t });
+  }
+  return out;
+}
+
+/** Flat double-sided fill in the XY plane (normal +Z). */
+export function flatMesh(regions, report) {
+  const tris = triangulateRegions(regions, report);
+  let vertices = 0, indices = 0;
+  for (const t of tris) {
+    vertices += t.positions.length / 2;
+    indices += t.indices.length;
+  }
+  const b = new MeshBuilder('triangles', vertices, indices);
+  const bb = regionBounds(regions);
+  for (const t of tris) {
+    const base = b.vertexCount;
+    const p = t.positions;
+    for (let i = 0; i < p.length; i += 2) {
+      b.vertex(p[i], p[i + 1], 0, 0, 0, 1, (p[i] - bb.minX) / bb.size, (p[i + 1] - bb.minY) / bb.size);
+    }
+    const idx = t.indices;
+    for (let i = 0; i < idx.length; i += 3) b.tri(base + idx[i], base + idx[i + 1], base + idx[i + 2]);
+  }
+  return b.build();
+}
+
+/**
+ * Inset positions of a contour: p - a * miter (a = 0 for contours that are not walls).
+ */
+function insetPoints(contour, amount) {
+  const pts = contour.points;
+  if (!amount || contour.isWall === false) return pts;
+  const f = contourFrames(pts, contour.smooth, true);
+  const out = new Float64Array(pts.length);
+  for (let i = 0; i < pts.length; i += 2) {
+    out[i] = pts[i] - f.miter[i] * amount;
+    out[i + 1] = pts[i + 1] - f.miter[i + 1] * amount;
+  }
+  return out;
+}
+
+/** Profile rings (back to front) for a straight or bevelled wall. */
+function wallProfile(depth, bevel, segs) {
+  const rings = [];
+  if (!(bevel > 0)) {
+    rings.push({ inset: 0, z: 0, nr: 1, nz: 0 }, { inset: 0, z: depth, nr: 1, nz: 0 });
+    return rings;
+  }
+  for (let k = 0; k <= segs; k++) {
+    const phi = (k / segs) * (Math.PI / 2);
+    rings.push({ inset: bevel * (1 - Math.sin(phi)), z: bevel * (1 - Math.cos(phi)), nr: Math.sin(phi), nz: -Math.cos(phi) });
+  }
+  for (let k = segs; k >= 0; k--) {
+    const phi = (k / segs) * (Math.PI / 2);
+    const ring = { inset: bevel * (1 - Math.sin(phi)), z: depth - bevel * (1 - Math.cos(phi)), nr: Math.sin(phi), nz: Math.cos(phi) };
+    // the straight section starts where the back bevel ends
+    if (k === segs && Math.abs(ring.z - rings[rings.length - 1].z) < 1e-12) continue;
+    rings.push(ring);
+  }
+  return rings;
+}
+
+/**
+ * @param {{regions: object[], walls: object[]}} shape from buildRegions (contours carry `smooth` and `isWall`)
+ * @param {{depth:number, bevel?:number, bevelSegments?:number, center?:boolean}} o
+ */
+export function extrudeMesh(shape, o, report) {
+  const depth = o.depth;
+  const bevel = Math.min(o.bevel || 0, depth / 2);
+  const segs = o.bevelSegments || 3;
+  const z0 = o.center ? -depth / 2 : 0;
+  const bb = regionBounds(shape.regions);
+  const S = bb.size;
+  const rings = wallProfile(depth, bevel, segs);
+  const w = extrudeWasm(shape, bevel, rings, z0, z0 + depth, bb.minX, bb.minY, S);
+  if (w) {
+    for (const e of w.errors) reportTriangulation(e, report);
+    return new Mesh({ positions: w.positions, normals: w.normals, uvs: w.uvs, indices: w.indices, kind: 'triangles' });
+  }
+
+  // caps: the inset contours are triangulated directly (re-using the original
+  // triangulation with moved vertices can flip long thin triangles)
+  const capRegions = shape.regions.map((r) => ({
+    outer: { ...r.outer, points: insetPoints(r.outer, bevel) },
+    holes: r.holes.map((h) => ({ ...h, points: insetPoints(h, bevel) })),
+  }));
+  const caps = triangulateRegions(capRegions, report);
+  const walls = shape.walls.map((c) => ({ pts: c.points, f: contourFrames(c.points, c.smooth, true) }));
+  // count first, so the mesh is allocated once at its final size
+  let vertices = 0, indices = 0;
+  for (const t of caps) {
+    vertices += t.positions.length;
+    indices += 2 * t.indices.length;
+  }
+  for (const { f } of walls) {
+    vertices += f.n * rings.length * 2;
+    indices += f.n * (rings.length - 1) * 6;
+  }
+  const b = new MeshBuilder('triangles', vertices, indices);
+  for (const t of caps) {
+    const flat = t.positions;
+    const idx = t.indices;
+    for (const [z, nz] of [[z0 + depth, 1], [z0, -1]]) {
+      const base = b.vertexCount;
+      for (let i = 0; i < flat.length; i += 2) {
+        b.vertex(flat[i], flat[i + 1], z, 0, 0, nz, (flat[i] - bb.minX) / S, (flat[i + 1] - bb.minY) / S);
+      }
+      for (let i = 0; i < idx.length; i += 3) {
+        if (nz > 0) b.tri(base + idx[i], base + idx[i + 1], base + idx[i + 2]);
+        else b.tri(base + idx[i], base + idx[i + 2], base + idx[i + 1]);
+      }
+    }
+  }
+
+  // walls
+  for (const { pts, f } of walls) {
+    const n = f.n;
+    for (let e = 0; e < n; e++) {
+      const i0 = e, i1 = (e + 1) % n;
+      // normal at each end of the edge: the edge's own at corners, else the vertex's
+      const n0x = f.corner[i0] ? f.edgeN[e * 2] : f.vertN[i0 * 2], n0y = f.corner[i0] ? f.edgeN[e * 2 + 1] : f.vertN[i0 * 2 + 1];
+      const n1x = f.corner[i1] ? f.edgeN[e * 2] : f.vertN[i1 * 2], n1y = f.corner[i1] ? f.edgeN[e * 2 + 1] : f.vertN[i1 * 2 + 1];
+      const u0 = f.arc[e] / S, u1 = f.arc[e + 1] / S;
+      let prevA = -1, prevB = -1;
+      for (const ring of rings) {
+        const ax = pts[i0 * 2] - f.miter[i0 * 2] * ring.inset;
+        const ay = pts[i0 * 2 + 1] - f.miter[i0 * 2 + 1] * ring.inset;
+        const bx = pts[i1 * 2] - f.miter[i1 * 2] * ring.inset;
+        const by = pts[i1 * 2 + 1] - f.miter[i1 * 2 + 1] * ring.inset;
+        const z = z0 + ring.z;
+        const a = b.vertex(ax, ay, z, n0x * ring.nr, n0y * ring.nr, ring.nz, u0, ring.z / S);
+        const c = b.vertex(bx, by, z, n1x * ring.nr, n1y * ring.nr, ring.nz, u1, ring.z / S);
+        if (prevA >= 0) b.quad(prevA, prevB, c, a);
+        prevA = a;
+        prevB = c;
+      }
+    }
+  }
+  return b.build();
+}

package/src/geometry/gear.js

@@ -0,0 +1,85 @@
+// Involute spur gear outline (module 1); the descriptor scales it by the module.
+//
+// A gear is described by a handful of parameters instead of thousands of
+// vertices: the outline is generated from the involute of the base circle,
+// then handed to the regular extrusion, bevel included if you asked for one.
+// A 2D outline goes in. The generic extrude operator does the rest.
+
+import { gearOutlineWasm } from '../wasm/kernels.js';
+
+const TAU = Math.PI * 2;
+
+function inv(a) {
+  return Math.tan(a) - a;
+}
+
+/**
+ * @returns {{outline: {points: Float64Array, smooth: Uint8Array, closed: true}, outerRadius: number, rootRadius: number}}
+ */
+export function gearOutline(teeth, pressureAngleDeg, flankSamples = 6, arcSamples = 3) {
+  const fast = gearOutlineWasm(teeth, pressureAngleDeg, flankSamples, arcSamples);
+  if (fast) return fast;
+  const N = teeth;
+  const alpha = (pressureAngleDeg * Math.PI) / 180;
+  const rp = N / 2;
+  const rb = rp * Math.cos(alpha);
+  let ra = rp + 1;
+  const rf = rp - 1.25;
+  const psi = Math.PI / (2 * N);
+  const invA = inv(alpha);
+  const half = (r) => {
+    // half tooth angle at radius r (r >= rb)
+    const ar = Math.acos(Math.min(1, rb / r));
+    return psi + invA - inv(ar);
+  };
+  // pointed teeth: shrink the tip radius until the tip keeps some width
+  if (half(ra) < psi * 0.15) {
+    let lo = Math.max(rb, rf), hi = ra;
+    for (let k = 0; k < 40; k++) {
+      const mid = (lo + hi) / 2;
+      if (half(mid) > psi * 0.15) lo = mid;
+      else hi = mid;
+    }
+    ra = lo;
+  }
+  const rStart = Math.max(rb, rf);
+  const pts = [];
+  const smooth = [];
+  const add = (r, a, s) => {
+    pts.push(r * Math.cos(a), r * Math.sin(a));
+    smooth.push(s ? 1 : 0);
+  };
+  const pitchAngle = TAU / N;
+  for (let k = 0; k < N; k++) {
+    const c = k * pitchAngle;
+    const leftRoot = c - half(rStart);
+    const rightRoot = c + half(rStart);
+    const prevRightRoot = c - pitchAngle + half(rStart);
+    // root arc from the previous tooth to this one
+    for (let i = 1; i < arcSamples; i++) {
+      add(rf, prevRightRoot + ((leftRoot - prevRightRoot) * i) / arcSamples, true);
+    }
+    // left flank: radial segment (when the root is inside the base circle) then involute
+    add(rf, leftRoot, false);
+    if (rf < rStart - 1e-9) add(rStart, leftRoot, false);
+    for (let i = 1; i <= flankSamples; i++) {
+      const r = rStart + ((ra - rStart) * i) / flankSamples;
+      add(r, c - half(r), i < flankSamples);
+    }
+    // tip arc
+    const tipL = c - half(ra), tipR = c + half(ra);
+    for (let i = 1; i < arcSamples; i++) add(ra, tipL + ((tipR - tipL) * i) / arcSamples, true);
+    // right flank going down
+    for (let i = flankSamples; i >= 1; i--) {
+      const r = rStart + ((ra - rStart) * i) / flankSamples;
+      add(r, c + half(r), i < flankSamples);
+    }
+    if (rf < rStart - 1e-9) add(rStart, rightRoot, false);
+    add(rf, rightRoot, false);
+  }
+  return {
+    outline: { points: Float64Array.from(pts), smooth: Uint8Array.from(smooth), closed: true },
+    outerRadius: ra,
+    rootRadius: rf,
+  };
+}