@nayan-ui/engine 0.0.0-stage → 1.0.0-beta.3

package/lib/module/assets/shape.js

@@ -0,0 +1,926 @@
+"use strict";
+
+// Custom shapes: 2D vector paths, and solids built from them (extrusions, lathes, tubes, merged
+// parts) that draw, collide and pick like loaded models.
+import NativeEngine from '../native/NativeNayanEngine';
+import { Builder, meshInfo, registerMesh, VERTEX_FLOATS } from "../render/meshes.js";
+import { SHAPE_MESH } from "../types.js";
+import { nativeGeometry } from "./model.js";
+const TAU = Math.PI * 2;
+/** Line segments per curve, arc or circle quarter when a path is flattened. */
+const CURVE_STEPS = 12;
+
+/**
+ * A 2D outline, built like an SVG path: x right, y down. Solids made from it
+ * (`extrude`, `lathe`) are flipped upright, so a path drawn the way it looks on screen stands the
+ * same way in the world. Coordinates are in world units: a 1 x 1 path makes a 1 unit wide shape.
+ *
+ * ```ts
+ * const heart = Path.fromSVG("M0.5 0.9 C0 0.5 0 0.1 0.25 0.1 C0.4 0.1 0.5 0.25 0.5 0.3 C0.5 0.25 0.6 0.1 0.75 0.1 C1 0.1 1 0.5 0.5 0.9 Z");
+ * const star = new Path().addStar(0, 0, 0.5, 0.22, 5);
+ * ```
+ */
+export class Path {
+  contours = [];
+  start = [0, 0];
+  last = [0, 0];
+  get current() {
+    let c = this.contours[this.contours.length - 1];
+    if (!c || c.closed) {
+      c = {
+        points: [[...this.last]],
+        closed: false
+      };
+      this.start = [...this.last];
+      this.contours.push(c);
+    }
+    return c;
+  }
+  add(x, y) {
+    this.current.points.push([x, y]);
+    this.last = [x, y];
+  }
+
+  /** Starts a new contour at (x, y). */
+  moveTo(x, y) {
+    const c = this.contours[this.contours.length - 1];
+    if (c && !c.closed && c.points.length === 1) this.contours.pop(); // a moveTo replaces a lone point
+    this.contours.push({
+      points: [[x, y]],
+      closed: false
+    });
+    this.start = [x, y];
+    this.last = [x, y];
+    return this;
+  }
+  lineTo(x, y) {
+    this.add(x, y);
+    return this;
+  }
+
+  /** A quadratic Bézier through control point (cx, cy) to (x, y). */
+  quadraticTo(cx, cy, x, y) {
+    const [x0, y0] = this.last;
+    for (let i = 1; i <= CURVE_STEPS; i++) {
+      const t = i / CURVE_STEPS;
+      const u = 1 - t;
+      this.add(u * u * x0 + 2 * u * t * cx + t * t * x, u * u * y0 + 2 * u * t * cy + t * t * y);
+    }
+    return this;
+  }
+
+  /** A cubic Bézier through control points (c1x, c1y) and (c2x, c2y) to (x, y). */
+  cubicTo(c1x, c1y, c2x, c2y, x, y) {
+    const [x0, y0] = this.last;
+    for (let i = 1; i <= CURVE_STEPS; i++) {
+      const t = i / CURVE_STEPS;
+      const u = 1 - t;
+      const a = u * u * u;
+      const b = 3 * u * u * t;
+      const c = 3 * u * t * t;
+      const d = t * t * t;
+      this.add(a * x0 + b * c1x + c * c2x + d * x, a * y0 + b * c1y + c * c2y + d * y);
+    }
+    return this;
+  }
+
+  /**
+   * An elliptical arc to (x, y), as in SVG's `A` command: radii rx, ry, the ellipse turned `rotation`
+   * radians, and the flags choosing which of the four possible arcs.
+   */
+  arcTo(rx, ry, rotation, largeArc, sweep, x, y) {
+    const [x0, y0] = this.last;
+    rx = Math.abs(rx);
+    ry = Math.abs(ry);
+    if (rx < 1e-9 || ry < 1e-9 || x0 === x && y0 === y) return this.lineTo(x, y);
+    // Endpoint to center parameterization (SVG implementation notes, F.6.5).
+    const cos = Math.cos(rotation);
+    const sin = Math.sin(rotation);
+    const dx = (x0 - x) / 2;
+    const dy = (y0 - y) / 2;
+    const x1 = cos * dx + sin * dy;
+    const y1 = -sin * dx + cos * dy;
+    const grow = x1 * x1 / (rx * rx) + y1 * y1 / (ry * ry);
+    if (grow > 1) {
+      rx *= Math.sqrt(grow);
+      ry *= Math.sqrt(grow);
+    }
+    const num = rx * rx * ry * ry - rx * rx * y1 * y1 - ry * ry * x1 * x1;
+    const den = rx * rx * y1 * y1 + ry * ry * x1 * x1;
+    const k = (largeArc === sweep ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+    const cx1 = k * rx * y1 / ry;
+    const cy1 = -k * ry * x1 / rx;
+    const cx = cos * cx1 - sin * cy1 + (x0 + x) / 2;
+    const cy = sin * cx1 + cos * cy1 + (y0 + y) / 2;
+    const angle = (ux, uy, vx, vy) => Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+    const start = angle(1, 0, (x1 - cx1) / rx, (y1 - cy1) / ry);
+    let delta = angle((x1 - cx1) / rx, (y1 - cy1) / ry, (-x1 - cx1) / rx, (-y1 - cy1) / ry);
+    if (!sweep && delta > 0) delta -= TAU;
+    if (sweep && delta < 0) delta += TAU;
+    const steps = Math.max(2, Math.ceil(Math.abs(delta) / (Math.PI / 2) * CURVE_STEPS));
+    for (let i = 1; i <= steps; i++) {
+      const t = start + delta * i / steps;
+      const ex = rx * Math.cos(t);
+      const ey = ry * Math.sin(t);
+      if (i === steps) this.add(x, y);else this.add(cos * ex - sin * ey + cx, sin * ex + cos * ey + cy);
+    }
+    return this;
+  }
+
+  /** Closes the current contour back to its first point. */
+  close() {
+    const c = this.contours[this.contours.length - 1];
+    if (c && !c.closed) {
+      c.closed = true;
+      this.last = [...this.start];
+    }
+    return this;
+  }
+
+  /** A closed polygon through `points`. */
+  addPolygon(points, close = true) {
+    if (!points.length) return this;
+    this.moveTo(points[0][0], points[0][1]);
+    for (let i = 1; i < points.length; i++) this.lineTo(points[i][0], points[i][1]);
+    return close ? this.close() : this;
+  }
+  addRect(x, y, width, height) {
+    return this.addPolygon([[x, y], [x + width, y], [x + width, y + height], [x, y + height]]);
+  }
+
+  /** A rectangle with corners rounded by `radius` (or [rx, ry]). */
+  addRoundedRect(x, y, width, height, radius) {
+    let [rx, ry] = typeof radius === 'number' ? [radius, radius] : radius;
+    rx = Math.min(Math.abs(rx), width / 2);
+    ry = Math.min(Math.abs(ry), height / 2);
+    if (rx < 1e-9 || ry < 1e-9) return this.addRect(x, y, width, height);
+    return this.moveTo(x + rx, y).lineTo(x + width - rx, y).arcTo(rx, ry, 0, false, true, x + width, y + ry).lineTo(x + width, y + height - ry).arcTo(rx, ry, 0, false, true, x + width - rx, y + height).lineTo(x + rx, y + height).arcTo(rx, ry, 0, false, true, x, y + height - ry).lineTo(x, y + ry).arcTo(rx, ry, 0, false, true, x + rx, y).close();
+  }
+
+  /** An ellipse filling the box. */
+  addOval(x, y, width, height) {
+    const rx = width / 2;
+    const ry = height / 2;
+    const cx = x + rx;
+    const cy = y + ry;
+    const steps = CURVE_STEPS * 4;
+    const points = [];
+    for (let i = 0; i < steps; i++) {
+      const t = i / steps * TAU;
+      points.push([cx + Math.cos(t) * rx, cy + Math.sin(t) * ry]);
+    }
+    return this.addPolygon(points);
+  }
+  addCircle(cx, cy, radius) {
+    return this.addOval(cx - radius, cy - radius, radius * 2, radius * 2);
+  }
+
+  /** A star with `points` tips at `outer` radius and notches at `inner`, the first tip pointing up. */
+  addStar(cx, cy, outer, inner, points = 5) {
+    const corners = [];
+    for (let i = 0; i < points * 2; i++) {
+      const r = i % 2 ? inner : outer;
+      const t = -Math.PI / 2 + i / (points * 2) * TAU;
+      corners.push([cx + Math.cos(t) * r, cy + Math.sin(t) * r]);
+    }
+    return this.addPolygon(corners);
+  }
+
+  /** A regular polygon with `sides` corners, the first pointing up. */
+  addRegularPolygon(cx, cy, radius, sides) {
+    const corners = [];
+    for (let i = 0; i < sides; i++) {
+      const t = -Math.PI / 2 + i / sides * TAU;
+      corners.push([cx + Math.cos(t) * radius, cy + Math.sin(t) * radius]);
+    }
+    return this.addPolygon(corners);
+  }
+
+  /**
+   * Parses SVG path data (`d`): M L H V C S Q T A Z, absolute and relative. Paste paths from Figma,
+   * Illustrator or any icon set (scale them with `fit` on the shape, or `transform` here).
+   */
+  static fromSVG(d) {
+    const path = new Path();
+    const token = /[a-zA-Z]|[-+]?(?:\d*\.\d+|\d+\.?)(?:[eE][-+]?\d+)?/g;
+    if (d.replace(token, '').replace(/[\s,]/g, '')) throw new Error('Path.fromSVG: invalid character in path data');
+    const tokens = d.match(token) ?? [];
+    let i = 0;
+    let command = '';
+    let [x, y] = [0, 0];
+    let control = null; // the last curve's second control point, for S and T
+    let lastType = '';
+    const num = () => {
+      const t = tokens[i++];
+      if (t === undefined || /^[a-zA-Z]$/.test(t) || !Number.isFinite(Number(t))) throw new Error(`Path.fromSVG: expected a number near "${t ?? 'the end'}"`);
+      return parseFloat(t);
+    };
+    const flag = () => num() !== 0;
+    while (i < tokens.length) {
+      if (/^[a-zA-Z]$/.test(tokens[i])) command = tokens[i++];else if (!command) throw new Error('Path.fromSVG: the path must start with a command');
+      const rel = command === command.toLowerCase();
+      const ox = rel ? x : 0;
+      const oy = rel ? y : 0;
+      switch (command.toUpperCase()) {
+        case 'M':
+          x = ox + num();
+          y = oy + num();
+          path.moveTo(x, y);
+          command = rel ? 'l' : 'L'; // further pairs are lines
+          control = null;
+          break;
+        case 'L':
+          x = ox + num();
+          y = oy + num();
+          path.lineTo(x, y);
+          control = null;
+          break;
+        case 'H':
+          x = ox + num();
+          path.lineTo(x, y);
+          control = null;
+          break;
+        case 'V':
+          y = oy + num();
+          path.lineTo(x, y);
+          control = null;
+          break;
+        case 'C':
+          {
+            const c1 = [ox + num(), oy + num()];
+            const c2 = [ox + num(), oy + num()];
+            x = ox + num();
+            y = oy + num();
+            path.cubicTo(c1[0], c1[1], c2[0], c2[1], x, y);
+            control = c2;
+            break;
+          }
+        case 'S':
+          {
+            const c1 = control && 'CS'.includes(lastType) ? [2 * x - control[0], 2 * y - control[1]] : [x, y];
+            const c2 = [ox + num(), oy + num()];
+            x = ox + num();
+            y = oy + num();
+            path.cubicTo(c1[0], c1[1], c2[0], c2[1], x, y);
+            control = c2;
+            break;
+          }
+        case 'Q':
+          {
+            const c = [ox + num(), oy + num()];
+            x = ox + num();
+            y = oy + num();
+            path.quadraticTo(c[0], c[1], x, y);
+            control = c;
+            break;
+          }
+        case 'T':
+          {
+            const c = control && 'QT'.includes(lastType) ? [2 * x - control[0], 2 * y - control[1]] : [x, y];
+            x = ox + num();
+            y = oy + num();
+            path.quadraticTo(c[0], c[1], x, y);
+            control = c;
+            break;
+          }
+        case 'A':
+          {
+            const rx = num();
+            const ry = num();
+            const rotation = num() * Math.PI / 180;
+            const large = flag();
+            const sweep = flag();
+            x = ox + num();
+            y = oy + num();
+            path.arcTo(rx, ry, rotation, large, sweep, x, y);
+            control = null;
+            break;
+          }
+        case 'Z':
+          path.close();
+          [x, y] = path.last;
+          control = null;
+          break;
+        default:
+          throw new Error(`Path.fromSVG: unknown command "${command}"`);
+      }
+      lastType = command.toUpperCase();
+      // Z takes no arguments. A following number must fail instead of repeating Z forever.
+      if (lastType === 'Z') command = '';
+    }
+    return path;
+  }
+
+  /** A copy moved by (dx, dy) and scaled by sx, sy (about the origin, before moving). */
+  transform(sx, sy = sx, dx = 0, dy = 0) {
+    const out = new Path();
+    out.contours = this.contours.map(c => ({
+      closed: c.closed,
+      points: c.points.map(([x, y]) => [x * sx + dx, y * sy + dy])
+    }));
+    out.start = [this.start[0] * sx + dx, this.start[1] * sy + dy];
+    out.last = [this.last[0] * sx + dx, this.last[1] * sy + dy];
+    return out;
+  }
+
+  /** The flattened contours (curves turned into points), y down as drawn. */
+  toContours() {
+    return this.contours.filter(c => c.points.length > 1).map(c => c.points.map(p => [p[0], p[1]]));
+  }
+
+  /** [minX, minY, maxX, maxY], or undefined for an empty path. */
+  bounds() {
+    let minX = Infinity,
+      minY = Infinity,
+      maxX = -Infinity,
+      maxY = -Infinity;
+    let found = false;
+    for (const contour of this.contours) for (const [x, y] of contour.points) {
+      found = true;
+      minX = Math.min(minX, x);
+      minY = Math.min(minY, y);
+      maxX = Math.max(maxX, x);
+      maxY = Math.max(maxY, y);
+    }
+    return found ? [minX, minY, maxX, maxY] : undefined;
+  }
+}
+
+// ── Geometry ─────────────────────────────────────────────────────────────
+
+/**
+ * Shape geometry, before it's registered: 11 floats per vertex (position, normal, color, uv) and
+ * triangle indices. Builders return it; `merge` combines it; `createShape` turns it into a mesh.
+ */
+
+const native = () => {
+  if (!NativeEngine) throw new Error('shapes: the native core is not linked into this build');
+  if (typeof NativeEngine.meshCreate !== 'function') throw new Error("shapes: this app's native core predates custom shapes: rebuild it");
+  return NativeEngine;
+};
+
+/** Sets every vertex's color (vertex colors multiply the entity's color). */
+function paint(g, color) {
+  if (!color) return g;
+  for (let v = 0; v < g.vertices.length; v += VERTEX_FLOATS) {
+    g.vertices[v + 6] = color[0];
+    g.vertices[v + 7] = color[1];
+    g.vertices[v + 8] = color[2];
+  }
+  return g;
+}
+const fromBuilder = b => ({
+  vertices: new Float32Array(b.vertices),
+  indices: new Uint32Array(b.indices)
+});
+
+/** A built-in shape's geometry (unit-sized, centered), to `merge` with others. */
+export function shapeGeometry(shape, options = {}) {
+  const info = meshInfo(SHAPE_MESH[shape]);
+  if (!info) throw new Error(`shapeGeometry: no geometry for "${shape}" (await warmUpEngine() first on the web)`);
+  return paint({
+    vertices: info.geometry.vertices.slice(),
+    indices: info.geometry.indices.slice()
+  }, options.color);
+}
+/**
+ * A 2D path filled and pushed into a solid, facing +Z: badges, coins, leaves, hearts, stars, logos,
+ * fruit slices. Holes follow the fill rule. Textures map across the front face.
+ */
+export function extrude(path, options = {}) {
+  const contours = path.toContours();
+  const counts = contours.map(c => c.length);
+  const points = new Float32Array(counts.reduce((a, b) => a + b, 0) * 2);
+  let k = 0;
+  for (const c of contours) {
+    for (const [x, y] of c) {
+      points[k++] = x;
+      points[k++] = -y; // y down in the path, up in the world
+    }
+  }
+  const depth = options.depth ?? 0.2;
+  const vertices = new Float32Array(native().pathExtrude(points.buffer, counts, depth, options.fillRule === 'evenodd'));
+  if (!vertices.length) throw new Error('extrude: the path encloses no area');
+  const indices = new Uint32Array(vertices.length / VERTEX_FLOATS);
+  for (let i = 0; i < indices.length; i++) indices[i] = i;
+  return paint({
+    vertices,
+    indices
+  }, options.color);
+}
+
+/** Where a color function is asked about: `u` around (0..1), `v` along (0..1), and the surface there. */
+
+/** A flat color, or one per point of the surface: blushes, stripes, speckles, spots. */
+
+/** A flat color, or one per point of a round face: `r` from its center (0) to its rim (1), `angle` around it. */
+
+/** Colors each vertex by `fn` of its surface point (u, v read from the texture coordinates). */
+function paintBy(g, color) {
+  if (typeof color !== 'function') return paint(g, color);
+  const v = g.vertices;
+  for (let i = 0; i < v.length; i += VERTEX_FLOATS) {
+    const c = color({
+      u: v[i + 9],
+      v: v[i + 10],
+      position: [v[i], v[i + 1], v[i + 2]],
+      normal: [v[i + 3], v[i + 4], v[i + 5]]
+    });
+    v[i + 6] = c[0];
+    v[i + 7] = c[1];
+    v[i + 8] = c[2];
+  }
+  return g;
+}
+
+/**
+ * Recolors geometry point by point (in place, and returned): two-tone leaves, painted tips, stripes on
+ * an extrusion. `u` and `v` are the texture coordinates there.
+ */
+export function recolor(geometry, color) {
+  return paintBy(geometry, color);
+}
+
+/**
+ * A round face: a polar grid of `rings` x `segments` around `center` in the plane spanned by unit
+ * vectors `x` and `y` (radius `radius(angle)` toward the rim), facing `normal`, swept `sweep` radians.
+ */
+function roundFace(center, x, y, normal, radius, sweep, segments, rings, color) {
+  const b = new Builder();
+  b.grid(rings, segments, (u, v) => {
+    const a = u * sweep;
+    const r = radius(u) * v;
+    const [c, s] = [Math.cos(a) * r, Math.sin(a) * r];
+    return [[center[0] + x[0] * c + y[0] * s, center[1] + x[1] * c + y[1] * s, center[2] + x[2] * c + y[2] * s], normal];
+  });
+  const g = facingOutward(fromBuilder(b));
+  const vs = g.vertices;
+  for (let i = 0; i < vs.length; i += VERTEX_FLOATS) {
+    const a = vs[i + 9] * sweep;
+    const r = vs[i + 10];
+    // Texture coordinates across the face, like a disc's.
+    vs[i + 9] = 0.5 + Math.cos(a) * r / 2;
+    vs[i + 10] = 0.5 + Math.sin(a) * r / 2;
+    if (typeof color === 'function') {
+      const c = color(r, a);
+      vs[i + 6] = c[0];
+      vs[i + 7] = c[1];
+      vs[i + 8] = c[2];
+    }
+  }
+  return typeof color === 'function' ? g : paint(g, color);
+}
+
+/** Whether a typed array covers its whole ArrayBuffer (so the native passes can take the buffer). */
+const whole = a => a.byteOffset === 0 && a.byteLength === a.buffer.byteLength;
+
+/** The Rust geometry passes, if this app's native core has them and the arrays can be handed over. */
+const nativeGeometry3 = g => NativeEngine && typeof NativeEngine.geometryPlace === 'function' && whole(g.vertices) && whole(g.indices) ? NativeEngine : null;
+
+/**
+ * Recomputes corner-angle-weighted normals in place, welding UV seams and poles at 1e-5 units.
+ * Uses Rust when available. Call on a sculpted surface before merging caps or other hard edges:
+ * coincident vertices share a normal. Degenerate faces leave the original normals intact.
+ */
+export function smoothNormals(g) {
+  const n = nativeGeometry3(g);
+  if (n) {
+    n.geometrySmoothNormals(g.vertices.buffer, g.indices.buffer);
+    return g;
+  }
+  const v = g.vertices;
+  const key = i => `${Math.round(v[i * VERTEX_FLOATS] * 1e5)},${Math.round(v[i * VERTEX_FLOATS + 1] * 1e5)},${Math.round(v[i * VERTEX_FLOATS + 2] * 1e5)}`;
+  const sums = new Map();
+  const keys = [];
+  for (let i = 0; i < v.length / VERTEX_FLOATS; i++) keys.push(key(i));
+  const idx = g.indices;
+  for (let t = 0; t + 2 < idx.length; t += 3) {
+    if (idx[t] >= keys.length || idx[t + 1] >= keys.length || idx[t + 2] >= keys.length) continue;
+    const [a, b, c] = [idx[t] * VERTEX_FLOATS, idx[t + 1] * VERTEX_FLOATS, idx[t + 2] * VERTEX_FLOATS];
+    const e1 = [v[b] - v[a], v[b + 1] - v[a + 1], v[b + 2] - v[a + 2]];
+    const e2 = [v[c] - v[a], v[c + 1] - v[a + 1], v[c + 2] - v[a + 2]];
+    const f = [e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0]];
+    const length = Math.hypot(f[0], f[1], f[2]);
+    if (length === 0 || !Number.isFinite(length)) continue;
+    for (let corner = 0; corner < 3; corner++) {
+      const i = idx[t + corner];
+      const next = idx[t + (corner + 1) % 3] * VERTEX_FLOATS;
+      const previous = idx[t + (corner + 2) % 3] * VERTEX_FLOATS;
+      let dot = 0;
+      for (let axis = 0; axis < 3; axis++) {
+        const origin = v[i * VERTEX_FLOATS + axis];
+        dot += (v[next + axis] - origin) * (v[previous + axis] - origin);
+      }
+      const weight = Math.atan2(length, dot) / length;
+      const k = keys[i];
+      const sum = sums.get(k) ?? [0, 0, 0];
+      sum[0] += f[0] * weight;
+      sum[1] += f[1] * weight;
+      sum[2] += f[2] * weight;
+      sums.set(k, sum);
+    }
+  }
+  for (let i = 0; i < keys.length; i++) {
+    const n = sums.get(keys[i]);
+    const len = n ? Math.hypot(n[0], n[1], n[2]) : 0;
+    if (len > 1e-12) v.set([n[0] / len, n[1] / len, n[2] / len], i * VERTEX_FLOATS + 3);
+  }
+  return g;
+}
+
+/**
+ * Spins a profile around the vertical axis, like a potter's wheel: fruit (apples, oranges, lemons,
+ * pears, cherries), vases, bottles, bowls, chess pieces, spinning tops. The profile is a `Path`
+ * (x = distance from the axis, y down, as drawn) or [radius, height] points (y up), top to bottom.
+ * Open ends away from the axis are capped. With `sweep` < TAU the cut faces are closed too.
+ */
+export function lathe(profile, options = {}) {
+  let points = profile instanceof Path ? (profile.toContours()[0] ?? []).map(([x, y]) => [Math.abs(x), -y]) : profile.map(([r, y]) => [Math.abs(r), y]);
+  points = points.filter((p, i) => i === 0 || Math.hypot(p[0] - points[i - 1][0], p[1] - points[i - 1][1]) > 1e-9);
+  if (points.length < 2) throw new Error('lathe: the profile needs at least two points');
+  if (points[0][1] < points[points.length - 1][1]) points.reverse(); // top to bottom
+  const segments = Math.max(3, Math.round(options.segments ?? 32));
+  const sweep = Math.min(TAU, Math.max(1e-3, options.sweep ?? TAU));
+  const full = sweep >= TAU - 1e-6;
+  const last = points.length - 1;
+
+  // Profile normals in the (radius, height) plane: the average of the neighbouring edges', turned outward.
+  const edge = i => {
+    const a = points[Math.max(0, i)];
+    const b = points[Math.min(last, i + 1)];
+    const len = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1;
+    return [(a[1] - b[1]) / len, (b[0] - a[0]) / len]; // going down the profile, outward is to the left
+  };
+  const normals = points.map(([r], i) => {
+    // On the axis the surface is a pole: straight up at the top, down at the bottom.
+    if (r < 1e-6 && (i === 0 || i === last)) return [0, i === 0 ? 1 : -1];
+    const e1 = edge(i - 1);
+    const e2 = edge(i);
+    const n = i === 0 ? e2 : i === last ? e1 : [e1[0] + e2[0], e1[1] + e2[1]];
+    const len = Math.hypot(n[0], n[1]) || 1;
+    return [n[0] / len, n[1] / len];
+  });
+  const b = new Builder();
+  const displace = options.displace;
+  // a = u * sweep around the axis; the same orientation as the built-in sphere, so faces point outward.
+  b.grid(last, segments, (u, v) => {
+    const i = Math.round(v * last);
+    const a = u * sweep;
+    const [r, y] = points[i];
+    const [nr, ny] = normals[i];
+    const n = [nr * Math.cos(a), ny, -nr * Math.sin(a)];
+    // The seam and the poles must move together, or the surface tears.
+    const d = displace ? displace(r < 1e-6 || full && u === 1 ? 0 : u, v) : 0;
+    return [[r * Math.cos(a) + n[0] * d, y + n[1] * d, -r * Math.sin(a) + n[2] * d], n];
+  });
+  const parts = [{
+    geometry: paintBy(displace ? smoothNormals(fromBuilder(b)) : fromBuilder(b), options.color)
+  }];
+
+  // Ends away from the axis: flat round faces (part of a circle when the sweep is partial).
+  const capColor = options.capColor ?? (typeof options.color === 'function' ? undefined : options.color);
+  const rings = Math.max(1, Math.round(options.capRings ?? (typeof capColor === 'function' ? 12 : 1)));
+  for (const [i, facing] of [[0, 1], [last, -1]]) {
+    const [r, y] = points[i];
+    if (r < 1e-6) continue;
+    parts.push({
+      geometry: roundFace([0, y, 0], [1, 0, 0], [0, 0, -1], [0, facing, 0], () => r, sweep, segments, rings, capColor)
+    });
+  }
+  if (full) return parts.length > 1 ? merge(parts) : parts[0].geometry;
+
+  // The cut: the region between the profile and the axis, laid into the planes at a = 0 and a = sweep.
+  // A profile whose height only falls gets a grid (so a color function has points to work with);
+  // one that turns back (a dimple) is filled exactly by the core.
+  const cutColor = options.cutColor ?? (typeof options.color === 'function' ? undefined : options.color);
+  const falling = points.every((p, i) => i === 0 || p[1] <= points[i - 1][1] + 1e-9);
+  let face;
+  if (falling) {
+    const g = new Builder();
+    const steps = Math.max(1, Math.round(options.cutSteps ?? (typeof cutColor === 'function' ? 12 : 1)));
+    g.grid(last, steps, (u, v) => {
+      const [r, y] = points[Math.round(v * last)];
+      return [[u * r, y, 0], [0, 0, 1]];
+    });
+    face = facingOutward(fromBuilder(g));
+  } else {
+    face = extrude(new Path().addPolygon([[0, -points[0][1]], ...points.map(([r, y]) => [r, -y]), [0, -points[last][1]]]), {
+      depth: 0
+    });
+  }
+  if (typeof cutColor === 'function') {
+    const widest = Math.max(...points.map(p => p[0]), 1e-6);
+    const skinAt = y => {
+      // The profile's radius at height y (for r from the axis to the skin).
+      let best = 0;
+      for (let i = 0; i < last; i++) {
+        const [r0, y0] = points[i];
+        const [r1, y1] = points[i + 1];
+        if ((y - y0) * (y - y1) <= 0 && y0 !== y1) best = Math.max(best, r0 + (y - y0) / (y1 - y0) * (r1 - r0));
+      }
+      return best || widest;
+    };
+    const fv = face.vertices;
+    for (let i = 0; i < fv.length; i += VERTEX_FLOATS) {
+      const c = cutColor(Math.min(1, fv[i] / skinAt(fv[i + 1])), fv[i + 1]);
+      fv.set(c.slice(0, 3), i + 6);
+    }
+  } else {
+    paint(face, cutColor);
+  }
+  const cut = (angle, flip) => {
+    const g = {
+      vertices: face.vertices.slice(),
+      indices: face.indices.slice()
+    };
+    const [c, s] = [Math.cos(angle), Math.sin(angle)];
+    const n = angle === 0 ? [0, 0, 1] : [-s, 0, -c];
+    for (let v = 0; v < g.vertices.length; v += VERTEX_FLOATS) {
+      const r = g.vertices[v];
+      g.vertices[v] = r * c;
+      g.vertices[v + 2] = -r * s;
+      g.vertices.set(n, v + 3);
+    }
+    if (flip) for (let t = 0; t < g.indices.length; t += 3) [g.indices[t + 1], g.indices[t + 2]] = [g.indices[t + 2], g.indices[t + 1]];
+    return g;
+  };
+  return merge([...parts, {
+    geometry: cut(0, false)
+  }, {
+    geometry: cut(sweep, true)
+  }]);
+}
+/**
+ * A tube along a smooth curve through `points`: bananas, stems, chillies, worms, snakes, ropes,
+ * pipes, tentacles, candy canes.
+ */
+export function tube(points, options = {}) {
+  if (points.some(p => p.some(v => !Number.isFinite(v)))) throw new Error('tube: points must be finite');
+  const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+  points = points.filter((p, i) => i === 0 || distance(p, points[i - 1]) > 1e-9);
+  const closed = options.closed ?? false;
+  if (closed && points.length > 1 && distance(points[0], points[points.length - 1]) < 1e-9) points = points.slice(0, -1);
+  if (points.length < (closed ? 3 : 2)) throw new Error(`tube: needs at least ${closed ? 'three' : 'two'} distinct points`);
+  const radius = typeof options.radius === 'function' ? options.radius : () => options.radius ?? 0.1;
+  const shape = options.shape ?? (() => 1);
+  const sides = Math.max(3, Math.round(options.sides ?? 12));
+  const steps = Math.max(1, Math.round(options.smoothness ?? 8));
+
+  // Catmull-Rom through the points.
+  const p = i => points[closed ? (i + points.length) % points.length : Math.max(0, Math.min(points.length - 1, i))];
+  const curve = [];
+  for (let i = 0; i < points.length - (closed ? 0 : 1); i++) {
+    const [a, b, c, d] = [p(i - 1), p(i), p(i + 1), p(i + 2)];
+    for (let s = 0; s < steps; s++) {
+      const t = s / steps;
+      const t2 = t * t;
+      const t3 = t2 * t;
+      const coordinate = k => 0.5 * (2 * b[k] + (-a[k] + c[k]) * t + (2 * a[k] - 5 * b[k] + 4 * c[k] - d[k]) * t2 + (-a[k] + 3 * b[k] - 3 * c[k] + d[k]) * t3);
+      curve.push([coordinate(0), coordinate(1), coordinate(2)]);
+    }
+  }
+  curve.push(p(closed ? 0 : points.length - 1));
+  const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+  const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+  const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+  const norm = a => {
+    const l = Math.hypot(a[0], a[1], a[2]) || 1;
+    return [a[0] / l, a[1] / l, a[2] / l];
+  };
+  const last = curve.length - 1;
+  const tangents = curve.map((_, i) => {
+    let delta = sub(curve[closed && i === last ? 1 : Math.min(last, i + 1)], curve[closed && i === 0 ? last - 1 : Math.max(0, i - 1)]);
+    // A reversing curve has no central derivative. Use its incoming/outgoing segment instead.
+    if (Math.hypot(...delta) < 1e-9) delta = i > 0 ? sub(curve[i], curve[i - 1]) : sub(curve[1], curve[0]);
+    return norm(delta);
+  });
+  if (closed) tangents[last] = tangents[0];
+  // Minimal rotations between tangents: projecting the previous normal onto the next plane
+  // collapses at right-angle bends and adds unwanted twist to curls.
+  const t0 = tangents[0];
+  let normal = norm(cross(t0, Math.abs(t0[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0]));
+  let previous = t0;
+  const frames = [];
+  for (const t of tangents) {
+    const axis = cross(previous, t);
+    const cosine = Math.max(-1, Math.min(1, dot(previous, t)));
+    if (cosine > -1 + 1e-8) {
+      const turn = cross(axis, normal);
+      const second = cross(axis, turn);
+      normal = [normal[0] + turn[0] + second[0] / (1 + cosine), normal[1] + turn[1] + second[1] / (1 + cosine), normal[2] + turn[2] + second[2] / (1 + cosine)];
+    }
+    // At a reversal, a half turn about the normal retains it and reverses the binormal.
+    const projection = dot(normal, t);
+    normal = norm(sub(normal, [t[0] * projection, t[1] * projection, t[2] * projection]));
+    frames.push([normal, cross(t, normal)]);
+    previous = t;
+  }
+  if (closed) {
+    const end = frames[last][0],
+      start = frames[0][0];
+    const correction = Math.atan2(dot(t0, cross(end, start)), dot(end, start));
+    const lengths = [0];
+    for (let i = 1; i <= last; i++) lengths.push(lengths[i - 1] + distance(curve[i], curve[i - 1]));
+    for (let i = 1; i <= last; i++) {
+      const angle = correction * lengths[i] / lengths[last];
+      const [n, bn] = frames[i];
+      const c = Math.cos(angle),
+        s = Math.sin(angle);
+      const corrected = [n[0] * c + bn[0] * s, n[1] * c + bn[1] * s, n[2] * c + bn[2] * s];
+      frames[i] = [corrected, cross(tangents[i], corrected)];
+    }
+    frames[last] = frames[0];
+  }
+  const b = new Builder();
+  const ring = curve.map((c, i) => {
+    const r = Math.max(0, radius(closed && i === last ? 0 : i / last));
+    const [n, bn] = frames[i];
+    const first = b.vertices.length / VERTEX_FLOATS;
+    for (let j = 0; j <= sides; j++) {
+      const a = (j === sides ? 0 : j / sides) * TAU;
+      const cosine = Math.cos(a),
+        sine = Math.sin(a);
+      const dir = [cosine * n[0] + sine * bn[0], cosine * n[1] + sine * bn[1], cosine * n[2] + sine * bn[2]];
+      const rj = r * shape(j === sides ? 0 : j / sides);
+      b.vertex([c[0] + dir[0] * rj, c[1] + dir[1] * rj, c[2] + dir[2] * rj], dir, j / sides, i / (curve.length - 1));
+    }
+    return {
+      first,
+      r
+    };
+  });
+  for (let i = 0; i < ring.length - 1; i++) {
+    for (let j = 0; j < sides; j++) {
+      const a = ring[i].first + j;
+      const c = ring[i + 1].first + j;
+      b.indices.push(a, a + 1, c, a + 1, c + 1, c);
+    }
+  }
+  let side = facingOutward(fromBuilder(b));
+  // Taper changes the longitudinal component too; radial normals only describe a cylinder.
+  if (options.shape || typeof options.radius === 'function') side = smoothNormals(side);
+  const parts = [{
+    geometry: paintBy(side, options.color)
+  }];
+  if (!closed && (options.caps ?? true)) {
+    const capColor = options.capColor ?? (typeof options.color === 'function' ? undefined : options.color);
+    const rings = typeof capColor === 'function' ? 8 : 1;
+    for (const [i, facing] of [[0, -1], [ring.length - 1, 1]]) {
+      const {
+        r
+      } = ring[i];
+      if (r < 1e-6) continue;
+      const t = tangents[i];
+      const [fn, fb] = frames[i];
+      parts.push({
+        geometry: roundFace(curve[i], fn, fb, [t[0] * facing, t[1] * facing, t[2] * facing], u => r * shape(u === 1 ? 0 : u), TAU, sides, rings, capColor)
+      });
+    }
+  }
+  return parts.length > 1 ? merge(parts) : parts[0].geometry;
+}
+
+/** Flips triangles whose winding disagrees with their vertex normals (so back-face culling keeps them). */
+function facingOutward(g) {
+  const native = nativeGeometry3(g);
+  if (native) {
+    native.geometryFaceOutward(g.vertices.buffer, g.indices.buffer);
+    return g;
+  }
+  const v = g.vertices;
+  const at = (i, k) => v[g.indices[i] * VERTEX_FLOATS + k];
+  for (let t = 0; t < g.indices.length; t += 3) {
+    const e1 = [0, 1, 2].map(k => at(t + 1, k) - at(t, k));
+    const e2 = [0, 1, 2].map(k => at(t + 2, k) - at(t, k));
+    const face = [e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0]];
+    const n = [0, 1, 2].map(k => at(t, k + 3) + at(t + 1, k + 3) + at(t + 2, k + 3));
+    if (face[0] * n[0] + face[1] * n[1] + face[2] * n[2] < 0) {
+      [g.indices[t + 1], g.indices[t + 2]] = [g.indices[t + 2], g.indices[t + 1]];
+    }
+  }
+  return g;
+}
+/**
+ * Bakes parts into one geometry, each scaled, rotated, moved and colored. One mesh draws in one
+ * instanced call and moves, spins and slices as one entity.
+ */
+export function merge(parts) {
+  const vertexCount = parts.reduce((n, p) => n + p.geometry.vertices.length, 0);
+  const indexCount = parts.reduce((n, p) => n + p.geometry.indices.length, 0);
+  const vertices = new Float32Array(vertexCount);
+  const indices = new Uint32Array(indexCount);
+  let vo = 0;
+  let io = 0;
+  for (const part of parts) {
+    const [px, py, pz] = part.position ?? [0, 0, 0];
+    const s = part.scale ?? 1;
+    const [sx, sy, sz] = typeof s === 'number' ? [s, s, s] : s;
+    const [qx, qy, qz, qw] = part.rotation ?? [0, 0, 0, 1];
+    const fast = nativeGeometry3(part.geometry);
+    if (fast) {
+      const c = part.color ?? [1, 1, 1];
+      const placement = [px, py, pz, qx, qy, qz, qw, sx, sy, sz, c[0], c[1], c[2]];
+      fast.geometryPlace(part.geometry.vertices.buffer, part.geometry.indices.buffer, placement, vo / VERTEX_FLOATS, vertices.buffer, vo, indices.buffer, io);
+      vo += part.geometry.vertices.length;
+      io += part.geometry.indices.length;
+      continue;
+    }
+    const rotate = (x, y, z) => {
+      // v + 2w(q x v) + 2(q x (q x v))
+      const tx = 2 * (qy * z - qz * y);
+      const ty = 2 * (qz * x - qx * z);
+      const tz = 2 * (qx * y - qy * x);
+      return [x + qw * tx + (qy * tz - qz * ty), y + qw * ty + (qz * tx - qx * tz), z + qw * tz + (qx * ty - qy * tx)];
+    };
+    const src = part.geometry.vertices;
+    const first = vo / VERTEX_FLOATS;
+    for (let v = 0; v < src.length; v += VERTEX_FLOATS) {
+      const p = rotate(src[v] * sx, src[v + 1] * sy, src[v + 2] * sz);
+      // Normals scale inversely (a squashed sphere's normals tilt toward its flat sides).
+      const n = rotate(src[v + 3] / sx, src[v + 4] / sy, src[v + 5] / sz);
+      const len = Math.hypot(n[0], n[1], n[2]);
+      const o = vo + v;
+      vertices[o] = p[0] + px;
+      vertices[o + 1] = p[1] + py;
+      vertices[o + 2] = p[2] + pz;
+      // Zero normals (camera-facing sprites) stay zero.
+      vertices[o + 3] = len > 0 ? n[0] / len : 0;
+      vertices[o + 4] = len > 0 ? n[1] / len : 0;
+      vertices[o + 5] = len > 0 ? n[2] / len : 0;
+      const c = part.color ?? [1, 1, 1];
+      vertices[o + 6] = src[v + 6] * c[0];
+      vertices[o + 7] = src[v + 7] * c[1];
+      vertices[o + 8] = src[v + 8] * c[2];
+      vertices[o + 9] = src[v + 9];
+      vertices[o + 10] = src[v + 10];
+    }
+    const mirrored = sx * sy * sz < 0; // turns triangles inside out: flip them back
+    const si = part.geometry.indices;
+    for (let t = 0; t < si.length; t += 3) {
+      indices[io + t] = si[t] + first;
+      indices[io + t + 1] = si[t + (mirrored ? 2 : 1)] + first;
+      indices[io + t + 2] = si[t + (mirrored ? 1 : 2)] + first;
+    }
+    vo += src.length;
+    io += si.length;
+  }
+  return {
+    vertices,
+    indices
+  };
+}
+/**
+ * Registers geometry as a mesh: pass the result as an entity's `mesh` (or a burst's), with any
+ * `texture`, physics and picking. Colliders default to a box holding the shape. Mesh ids are
+ * shared by models, fonts and shapes (about 4,080) and live for the whole app. Equal geometry/options
+ * automatically reuse preparation and registration; input buffers may still be edited for a later
+ * call. Material variants remain independent. Build geometry during scene setup, outside onUpdate.
+ *
+ * ```ts
+ * const orange = createShape(lathe(orangeProfile, { color: [1, 0.55, 0.1] }), { fit: 1, shine: 0.3 });
+ * world.spawn({ mesh: orange, position: [0, 2, 0], physics: "dynamic" });
+ * ```
+ */
+export function createShape(geometry, options = {}) {
+  const core = native();
+  if (typeof core.shapePrepare !== 'function') throw new Error("createShape: rebuild the app with the engine's Rust asset preparation");
+  const mesh = core.shapePrepare(geometry.vertices.byteOffset === 0 && geometry.vertices.byteLength === geometry.vertices.buffer.byteLength ? geometry.vertices.buffer : geometry.vertices.slice().buffer, geometry.indices.byteOffset === 0 && geometry.indices.byteLength === geometry.indices.buffer.byteLength ? geometry.indices.buffer : geometry.indices.slice().buffer, prepareOptions(options));
+  if (mesh < 0) throw new Error(`createShape: ${core.loadError()}`);
+  return preparedModel(mesh, options.shine ?? 0);
+}
+
+/** Only small handle metadata stays in JS; native/WASM owns the expensive preparation cache. */
+const preparedModels = new Map();
+export function preparedModel(mesh, shine) {
+  const cached = preparedModels.get(mesh);
+  if (cached) return cached;
+  let geometry;
+  registerMesh(mesh, {
+    // Only advanced CPU geometry queries materialize a JS/WASM copy; drawing stays in Rust.
+    get geometry() {
+      return geometry ??= nativeGeometry(mesh);
+    },
+    shine: Math.max(0, Math.min(1, shine))
+  }, false);
+  const [x, y, z] = native().modelSize(mesh);
+  const model = {
+    id: mesh,
+    size: [x, y, z]
+  };
+  preparedModels.set(mesh, model);
+  return model;
+}
+export function prepareOptions(options) {
+  const opt = options.optimize === true ? {} : options.optimize || null;
+  return JSON.stringify({
+    center: options.center ?? true,
+    fit: options.fit ?? 0,
+    shine: Math.max(0, Math.min(1, options.shine ?? 0)),
+    optimize: opt && {
+      ratio: opt.ratio ?? 1,
+      error: opt.error ?? 0.001,
+      lockBorders: opt.lockBorders ?? true
+    }
+  });
+}
+//# sourceMappingURL=shape.js.map