trid3d 0.3.1 → 0.5.0

package/trid/index.d.ts

@@ -162,6 +162,8 @@ export interface SceneObjectInput {
   draggable?: boolean;
   /** Set to false to make `HoverHighlight` ignore this object */
   hoverable?: boolean;
+  /** Set to false so `pick` / `pickHit` never find this object or its children (helpers like a grid) */
+  pickable?: boolean;
 }
 
 /**
@@ -198,10 +200,17 @@ export interface SceneOptions {
   lineWidth?: number;
   /** Camera (default { z: -1 }) */
   camera?: Camera;
-  /** Direction light comes from (default: above, left and in front) */
+  /** Direction light comes from (default: above, left and in front). Ignored when `lights` is given */
   light?: Vec3;
-  /** Brightness of faces turned away from the light, 0..1 (default 0.25) */
+  /**
+   * Brightness of faces turned away from the light, 0..1 (default 0.25).
+   * The directional light gets `1 - ambient`. Ignored when `lights` is given
+   */
   ambient?: number;
+  /** Every light, instead of `light` and `ambient` */
+  lights?: Light[];
+  /** Post effects run on the picture, in order (default none) */
+  post?: PostEffect[];
   /** What draws the scene (default: a new CanvasRenderer) */
   renderer?: Renderer;
 }
@@ -216,7 +225,19 @@ export class Scene {
   color: string;
   lineWidth: number;
   camera: Camera;
-  light: Vec3;
+  /** Every light. Edit it freely; it's read every frame */
+  lights: Light[];
+  /** Post effects, run in order on the picture before tools draw */
+  post: PostEffect[];
+  /**
+   * Shortcut for the first directional light's direction (null if there's none).
+   * Setting it when there's none adds one.
+   */
+  light: Vec3 | null;
+  /**
+   * Shortcut for the first ambient light's intensity (0 if there's none).
+   * Setting it when there's none adds one; the directional light keeps its intensity.
+   */
   ambient: number;
   renderer: Renderer;
   objects: SceneObject[];
@@ -263,8 +284,10 @@ export interface ShapeOptions {
   r?: number;
   /** Sphere latitude bands (default 12) */
   rings?: number;
-  /** Points around: sphere (24), cylinder / cone (32), torus (48) */
+  /** Points around: sphere (24), cylinder / cone (32), torus (48); rows per rounded edge of a cube / box with `radius` (4) */
   segments?: number;
+  /** Cube / box: round the edges and corners by this much (default 0: sharp) */
+  radius?: number;
   /** Cone top radius: 0 = pointed, > 0 = tapered cylinder (default 0) */
   rTop?: number;
   /** Torus: distance from the center to the middle of the tube (default 0.35) */
@@ -384,6 +407,106 @@ export interface Bounds {
  */
 export function meshBounds(input: Mesh | SceneObjectInput | (Mesh | SceneObjectInput)[] | Scene): Bounds | null;
 
+export type GridPlane = "xz" | "xy" | "yz";
+
+/** A square grid of lines centered on the origin, as a line-only mesh. */
+export function gridMesh(opts?: { size?: number; divisions?: number; plane?: GridPlane }): Mesh;
+
+export interface GridHelperOptions {
+  /** Width of the whole grid (default 4) */
+  size?: number;
+  /** Cells along each side (default 40) */
+  divisions?: number;
+  /** A major line every this many cells, 0 for none (default 10) */
+  major?: number;
+  /** The plane it lies in (default "xz", a floor) */
+  plane?: GridPlane;
+  /** Minor lines (default "rgba(255, 255, 255, 0.12)") */
+  color?: string;
+  /** Major lines (default "rgba(255, 255, 255, 0.25)") */
+  majorColor?: string;
+  /** Draw the axes through the origin (default true), or their colors like `{ x: "#f00" }` */
+  axes?: boolean | { x?: string; y?: string; z?: string };
+  /** Fade toward the edge (default true); a number is where the fade starts (0 = center, 1 = edge) */
+  fade?: boolean | number;
+  /** Line width in pixels (default 1) */
+  lineWidth?: number;
+}
+
+/** A floor grid with major lines, colored axes and a fade: a group to `scene.add`, never picked. */
+export function gridHelper(opts?: GridHelperOptions): SceneObjectInput & { pickable: false; children: SceneObjectInput[] };
+
+// ---------------------------------------------------------------------------
+// Lights
+// ---------------------------------------------------------------------------
+
+/** Light from everywhere: lights every side of every face the same. */
+export interface AmbientLight {
+  type: "ambient";
+  /** Any CSS color (default white) */
+  color?: string;
+  /** Multiplies the color (default 1) */
+  intensity?: number;
+  /** Set to false to turn it off without removing it */
+  enabled?: boolean;
+}
+
+/** Light from far away in one direction, like the sun. */
+export interface DirectionalLight {
+  type: "directional";
+  /** Direction light comes from (any length) */
+  direction: Vec3;
+  color?: string;
+  intensity?: number;
+  enabled?: boolean;
+}
+
+/** Light from a point, like a bulb. */
+export interface PointLight {
+  type: "point";
+  /** World position */
+  position: Vec3;
+  color?: string;
+  intensity?: number;
+  /** Fades out smoothly and reaches nothing past this distance (default: no fading) */
+  range?: number;
+  enabled?: boolean;
+}
+
+export type Light = AmbientLight | DirectionalLight | PointLight;
+
+/** Most directional + point lights the renderers use; extra ones are ignored. */
+export const MAX_LIGHTS: number;
+
+/** The default lights: ambient at `ambient`, white directional from `direction` at `1 - ambient`. */
+export function defaultLights(direction?: Vec3, ambient?: number): Light[];
+
+/** A scene's lights ready for shading (used by the renderers). */
+export interface SceneLights {
+  /** Summed ambient color [r, g, b] */
+  ambient: [number, number, number];
+  /** Brightest channel of `ambient` */
+  ambientLevel: number;
+  lights: { point: boolean; dir: Vec3 | null; pos: Vec3 | null; color: [number, number, number]; range: number }[];
+  /** Unit direction of the first directional light */
+  mainDir: Vec3;
+}
+
+/** A scene's lights, colors parsed and multiplied by intensity, directions unit length. */
+export function sceneLights(
+  scene: { lights?: Light[]; light?: Vec3 | null; ambient?: number },
+  rgba: (css: string) => number[],
+): SceneLights;
+
+/** The light reaching a point, [r, g, b] (can go above 1). */
+export function lightAt(lights: SceneLights, normal: Vec3, position: Vec3): [number, number, number];
+
+/** Brightness (brightest channel) and diffuse share (0..1) of a light color. */
+export function lightLevels(color: number[], ambientLevel: number): { light: number; diffuse: number };
+
+/** How much of a point light reaches `dist` away (1 up close, 0 at `range`; range 0 = no fading). */
+export function rangeFade(dist: number, range: number): number;
+
 // ---------------------------------------------------------------------------
 // Renderers
 // ---------------------------------------------------------------------------
@@ -464,13 +587,15 @@ export interface Surface {
   local: Vec3;
   /** Unit direction from the point to the camera */
   view: Vec3;
-  /** Unit direction light comes from */
+  /** Unit direction the scene's first directional light comes from */
   lightDir: Vec3;
-  /** How much the point faces the light (0..1) */
+  /** How much of the light comes from the lights rather than the ambient, 0..1 (one light: how much the point faces it) */
   diffuse: number;
-  /** Brightness Trid used: ambient + (1 - ambient) × diffuse */
+  /** Brightness Trid used (brightest channel of `lightColor`): ambient + (1 - ambient) × diffuse with the default lights */
   light: number;
-  /** The scene's ambient level */
+  /** The light reaching the point, [r, g, b] (every light added up; can go above 1). Trid's color is `base × lightColor` */
+  lightColor: [number, number, number];
+  /** The scene's ambient level (brightest channel) */
   ambient: number;
   /** Distance to the camera */
   depth: number;
@@ -563,6 +688,89 @@ export function uniformType(value: unknown): "float" | "vec2" | "vec3" | "vec4"
 /** The GLSL declaration of `Surface`, shared by every effect. */
 export const SURFACE_GLSL: string;
 
+// ---------------------------------------------------------------------------
+// Post effects
+// ---------------------------------------------------------------------------
+
+/** What a post effect's `canvas` function knows about the picture. */
+export interface PostFrame {
+  width: number;
+  height: number;
+  /** Seconds since the renderer started */
+  time: number;
+  /** The scene's background color */
+  background: RGBA;
+  /** The canvas being changed */
+  canvas: HTMLCanvasElement;
+  /** Turns a uniform value (CSS color, array) into RGBA 0..1 */
+  rgba(value: UniformValue): RGBA;
+}
+
+/** One pass of a post effect. */
+export interface PostPass {
+  /** GLSL defining `vec4 post(vec4 color, Frame f)` */
+  glsl: string;
+  /** Size of this pass's picture, relative to the canvas (default 1) */
+  scale?: number;
+}
+
+/** A shader run on the whole picture after the scene is drawn. */
+export interface PostEffect<U extends Record<string, UniformValue> = Record<string, UniformValue>> {
+  name?: string;
+  /** GLSL defining `vec4 post(vec4 color, Frame f)`: one pass (WebGL renderer) */
+  glsl?: string;
+  /** Instead of `glsl`: passes run in order (each can read the last with `frame(uv)`, the start with `source(uv)`) */
+  passes?: PostPass[];
+  /** Changes the 2D canvas directly: used by the canvas renderer (and by WebGL for effects without GLSL) */
+  canvas?(ctx: CanvasRenderingContext2D, frame: PostFrame, uniforms: U): void;
+  /** Settings read every frame */
+  uniforms?: U;
+  /** Set to false to turn it off without removing it */
+  enabled?: boolean;
+}
+
+/** Darkens the corners of the picture. */
+export function vignette(opts?: { strength?: number; radius?: number; softness?: number; color?: string }): PostEffect<{
+  uStrength: number;
+  uRadius: number;
+  uSoftness: number;
+  uColor: string;
+}>;
+
+/** Glow around the bright parts. */
+export function bloom(opts?: { threshold?: number; strength?: number; radius?: number }): PostEffect<{
+  uThreshold: number;
+  uStrength: number;
+  uRadius: number;
+}>;
+
+/** Brightness, contrast, saturation and a tint, in that order. */
+export function grade(opts?: { brightness?: number; contrast?: number; saturation?: number; tint?: string }): PostEffect<{
+  uBrightness: number;
+  uContrast: number;
+  uSaturation: number;
+  uTint: string;
+}>;
+
+/** Film grain: random noise over the picture. */
+export function grain(opts?: { amount?: number; size?: number; animated?: boolean }): PostEffect<{
+  uAmount: number;
+  uGrain: number;
+  uAnimated: boolean;
+}>;
+
+/** A post effect's passes (empty when it only has a canvas version). */
+export function postPasses(effect: PostEffect): { glsl: string; scale: number }[];
+
+/** The effects of a list that are on. */
+export function activePost(list: PostEffect[] | undefined): PostEffect[];
+
+/** Runs post effects' `canvas` functions on a scene's canvas (used by the renderers). */
+export function runCanvasPost(scene: Scene, list: PostEffect[] | undefined, start: number): void;
+
+/** The GLSL declaration of `Frame` and the `frame` / `source` helpers. */
+export const FRAME_GLSL: string;
+
 // ---------------------------------------------------------------------------
 // Texture mapping
 // ---------------------------------------------------------------------------
@@ -1107,6 +1315,8 @@ export interface TransformGizmoOptions {
   size?: number;
   /** Change the targets' transforms while dragging (default true) */
   apply?: boolean;
+  /** Where the handles sit and what rotate / scale go around (default "bounds") */
+  pivot?: GizmoPivot;
   /** A handle was grabbed */
   onGrab?: (targets: SceneObject[]) => void;
   /** While dragging: the operation since the grab */
@@ -1116,8 +1326,17 @@ export interface TransformGizmoOptions {
 }
 
 /**
- * Move arrows, rotate rings or scale handles on one or more objects, around their
- * shared center. Add it after the camera tool.
+ * Where a `TransformGizmo` puts its handles and turns / scales around:
+ * - `"bounds"`: the middle of the targets' bounding box
+ * - `"origin"`: the targets' origins in the world (averaged)
+ * - a world point (moved along when the gizmo moves the targets)
+ * - a function asked every frame
+ */
+export type GizmoPivot = "bounds" | "origin" | Vec3 | ((targets: SceneObject[]) => Vec3 | null);
+
+/**
+ * Move arrows, rotate rings or scale handles on one or more objects, around a
+ * pivot (default: the middle of their bounding box). Add it after the camera tool.
  */
 export class TransformGizmo implements Tool {
   constructor(opts?: TransformGizmoOptions);
@@ -1125,6 +1344,7 @@ export class TransformGizmo implements Tool {
   targets: SceneObject[];
   size: number;
   apply: boolean;
+  pivot: GizmoPivot;
   onGrab?: (targets: SceneObject[]) => void;
   onChange?: (op: TransformOp, targets: SceneObject[]) => void;
   onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
@@ -1132,7 +1352,7 @@ export class TransformGizmo implements Tool {
   visible: boolean;
   /** True while a handle is being dragged. */
   readonly dragging: boolean;
-  /** Middle of the targets' bounding box in world space, or null. */
+  /** The pivot in world space, or null when there are no targets. */
   center(): Vec3 | null;
   draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
   pointerDown(e: ToolPointerEvent, scene: Scene): boolean;
@@ -1166,8 +1386,25 @@ export interface PickHit {
   depth: number;
   /** The object, then its groups up to the top: `[part, group, ..., root]` */
   path: SceneObject[];
+  /** Where the hit is, in the world */
+  point: Vec3;
+  /** Where the hit is, in the mesh's own space */
+  local: Vec3;
+  /** The 3 vertex indices of the triangle hit (polygons are fans from their first corner); null for a line */
+  triangle: [number, number, number] | null;
+  /** Weights of those vertices at the hit (they add up to 1); null for a line */
+  barycentric: [number, number, number] | null;
+  /** Unit normal of the face hit, in the world, on its front side; null for a line */
+  normal: Vec3 | null;
+  /** Texture coordinates at the hit (the material's mapping, before repeat / offset / rotation); null without any */
+  uv: UV | null;
+  /** Where the texture is read: `uv` with the material's repeat, offset and rotation; null without texture coordinates */
+  textureUV: UV | null;
 }
 
+/** Whether picking can find an object (not when it or a group above it has `pickable: false`). */
+export function isPickable(obj: SceneObjectInput & { parent?: SceneObjectInput | null }): boolean;
+
 /**
  * Exact picking: the nearest object whose triangles (or, without faces, lines
  * within `padding` pixels) are under a canvas pixel.
@@ -1397,3 +1634,320 @@ export function noise3(x: number, y: number, z: number, opts?: NoiseOptions): nu
 export function fbm2(x: number, y: number, opts?: FbmOptions): number;
 /** Fractal 3D noise: octaves of noise3, each twice as fine. About [0, 1), averaging 0.5. */
 export function fbm3(x: number, y: number, z: number, opts?: FbmOptions): number;
+
+// Modeling: curves
+
+export interface SplineOptions {
+  /** Points made between two control points (default 8) */
+  segments?: number;
+  /** The last point joins the first (a loop); the result doesn't repeat the first point (default false) */
+  closed?: boolean;
+  /** 0 = uniform, 0.5 = centripetal: no loops or overshoot (default), 1 = chordal */
+  alpha?: number;
+  /** 0 = smooth (default), 1 = straight lines between the points */
+  tension?: number;
+  /** Instead of `segments`: this many points in all, evenly spaced by length */
+  count?: number;
+  /** Instead of `segments`: points about this far apart, evenly spaced */
+  spacing?: number;
+}
+
+/**
+ * A smooth curve through `points` (Catmull-Rom: it passes through every
+ * point). Works with 2D, 3D and lathe `{ r, y }` points: every number field
+ * of the first point is a coordinate, and the result has the same fields.
+ */
+export function spline<P extends Point2 | Vec3 | ProfilePoint>(points: P[], opts?: SplineOptions): P[];
+
+export interface ResampleOptions {
+  /** Number of points in all */
+  count?: number;
+  /** Distance between points (used when `count` isn't given) */
+  spacing?: number;
+  /** The points form a loop (default false) */
+  closed?: boolean;
+}
+
+/** Points along a polyline, evenly spaced by length. The ends stay where they are. */
+export function resamplePath<P extends Point2 | Vec3 | ProfilePoint>(points: P[], opts?: ResampleOptions): P[];
+
+// Modeling: sweep
+
+/** A size along a path: a number, numbers spread evenly from start to end, or a function of t (0 at the start, 1 at the end). */
+export type SizeAlong = number | number[] | ((t: number) => number);
+
+export interface SweepOptions {
+  /** The cross-section: x to the path's side, y to its "up" (default: a circle of `radius`) */
+  profile?: Point2[];
+  /** The profile is a closed outline (default true); false = an open line, for ribbons, leaves and roads */
+  profileClosed?: boolean;
+  /** Radius of the default circle (default 0.1). Ignored with a `profile` */
+  radius?: SizeAlong;
+  /** Points around the default circle (default 16) */
+  segments?: number;
+  /** Size of the section along the path (default 1). 0 at an end closes it into a point */
+  scale?: SizeAlong;
+  /** Turn of the section from start to end, in radians (default 0). Whole turns on a closed path */
+  twist?: number;
+  /** The path is a loop: its end joins its start (default false) */
+  closed?: boolean;
+  /** Close the ends with flat caps (default true; open paths with closed profiles) */
+  caps?: boolean;
+  /** Keep the section's y pointed this way (roads, rails, frames). Default: carried along the path without spinning */
+  up?: Vec3;
+  /** Stretch the section at sharp corners so the tube keeps its thickness (default true) */
+  miter?: boolean;
+}
+
+/**
+ * Moves a cross-section along a 3D path: tails, horns, tentacles, handles,
+ * pipes, cables, rails. Without `profile`, a round tube of `radius`.
+ * Clockwise faces; uvs: u around the section, v along the path.
+ */
+export function sweep(path: Vec3[], opts?: SweepOptions): Mesh;
+
+// Modeling: loft
+
+/** A 2D section, placed along the loft's axis or path. */
+export interface LoftOutline {
+  /** Closed outline: x to the side, y up (either direction; one point = a tip) */
+  outline: Point2[];
+  /** Where it is: the position on the axis, or 0 (start) to 1 (end) along a path (default: evenly spread) */
+  at?: number;
+  /** Size, the same both ways or per direction (default 1); 0 = a tip */
+  scale?: number | { x?: number; y?: number };
+  /** Turn in its own plane, in radians (default 0) */
+  rotate?: number;
+  /** Move in its own plane (default none) */
+  offset?: Partial<Point2>;
+}
+
+/** A section as a ring of 3D points, used where it is. */
+export interface LoftRing {
+  points: Vec3[];
+}
+
+export interface LoftOptions {
+  /** Straight axis the outlines are placed along (default "z"). x/y of an outline: "z" → X/Y, "y" → X/Z, "x" → Z/Y */
+  axis?: "x" | "y" | "z";
+  /** A 3D path to place the outlines along instead of the axis */
+  path?: Vec3[];
+  /** With `path`: keep the outlines' y pointed this way (default: carried along without spinning) */
+  up?: Vec3;
+  /** The surface loops back to its first section (a closed path, or 3D rings in a loop; default false) */
+  closed?: boolean;
+  /** Close the ends with flat caps (default true) */
+  caps?: boolean;
+  /** Rows between two sections, on average (default 6) */
+  segments?: number;
+  /** Points around each section (default: kept when every section has the same count, else the most any has, at least 24) */
+  points?: number;
+  /** Smooth curves between sections, never past them (default true); false = straight */
+  smooth?: boolean;
+  /** Line sections up so the surface doesn't twist (default true) */
+  align?: boolean;
+}
+
+/**
+ * A surface through cross-sections: bodies, bottles, hulls, car bodies,
+ * heads. Every section is an `outline` (2D, placed along an axis or a path)
+ * or every section is `points` (a 3D ring). Clockwise faces; uvs: u around,
+ * v along. Throws when the two kinds are mixed.
+ */
+export function loft(sections: LoftOutline[] | LoftRing[], opts?: LoftOptions): Mesh;
+
+// Modeling: deformers
+
+export interface AxisRange {
+  /** Axis the effect goes along (default "y") */
+  axis?: "x" | "y" | "z";
+  /** Start of the part that changes: 0 = the mesh's low end on the axis, 1 = its high end (default 0) */
+  from?: number;
+  /** End of the part that changes, same measure (default 1). Past it, the full effect carries on */
+  to?: number;
+  /** A point the axis line goes through (default: the middle of the mesh's box) */
+  center?: Partial<Vec3>;
+}
+
+export interface TaperOptions extends AxisRange {
+  /** Size at the end of the range (default 0.5), or a function of how far into the range (0 to 1) giving the size */
+  amount?: number | ((w: number) => number);
+}
+
+export interface TwistOptions extends AxisRange {
+  /** Turn at the end of the range, in radians (default π/2), or a function of how far into the range (0 to 1) */
+  angle?: number | ((w: number) => number);
+}
+
+export interface BendOptions extends AxisRange {
+  /** Angle of the arc, in radians (default π/2); negative curves the other way */
+  angle?: number;
+  /** Axis it curves toward (default: "z" for a "y" axis, "z" for "x", "y" for "z") */
+  toward?: "x" | "y" | "z";
+}
+
+export interface BulgeOptions {
+  /** Middle of the bulge */
+  center: Vec3;
+  /** Distance where it fades to nothing */
+  radius: number;
+  /** How far the middle moves (default 0.1); negative = a dent */
+  amount?: number;
+  /** "normal": along the surface, works on flat sides (default); "radial": away from `center` (put it inside the part) */
+  mode?: "normal" | "radial";
+}
+
+/** Narrows or widens a mesh along an axis, in place. Returns the same mesh. */
+export function taperMesh<M extends Mesh>(mesh: M, opts?: TaperOptions): M;
+/** Turns a mesh around an axis, more and more along it, in place (same direction as rotateX / Y / Z). Returns the same mesh. */
+export function twistMesh<M extends Mesh>(mesh: M, opts?: TwistOptions): M;
+/** Bends a mesh into an arc along an axis, in place; past the range it goes on straight. Returns the same mesh. */
+export function bendMesh<M extends Mesh>(mesh: M, opts?: BendOptions): M;
+/** Pushes the surface out (or in) around a point, fading at `radius`, in place. Returns the same mesh. */
+export function bulgeMesh<M extends Mesh>(mesh: M, opts: BulgeOptions): M;
+
+// Modeling: cleanup and checks
+
+/**
+ * Merges vertices closer than `epsilon` (default: a ten-millionth of the
+ * mesh's size), in place. Texture coordinates and normals (per corner) are
+ * kept; corners that meet are removed. Returns the same mesh.
+ */
+export function weldVertices<M extends Mesh>(mesh: M, epsilon?: number): M;
+
+export interface CleanOptions {
+  /** Merge vertices at the same place first: true, or the distance (default false) */
+  weld?: boolean | number;
+}
+
+/**
+ * Removes what's broken, in place: faces to missing or bad vertices, repeated
+ * corners, faces with fewer than 3 corners, crossed or of no area, repeated
+ * faces, bad corner lists (set to null), bad edges, and unused vertices,
+ * texture coordinates and normals. Returns the same mesh.
+ */
+export function cleanMesh<M extends Mesh>(mesh: M, opts?: CleanOptions): M;
+
+export interface MeshProblem {
+  /** What's wrong, e.g. "bad-index", "no-area", "turned-face", "inside-out", "open-edge" */
+  kind: string;
+  /** "error": breaks drawing or export; "warning": draws wrong; "info": worth knowing */
+  level: "error" | "warning" | "info";
+  /** A short sentence, with the first few faces / vertices / edges concerned */
+  message: string;
+  faces?: number[];
+  vertices?: number[];
+  edges?: number[];
+}
+
+/** Lists what's wrong with a mesh, without changing it (one entry per kind of problem; empty when fine). */
+export function validateMesh(mesh: Mesh): MeshProblem[];
+
+/**
+ * Turns faces in place so neighbors agree and each piece points outward
+ * (clockwise from outside). Works without welding. Returns the same mesh.
+ */
+export function fixWinding<M extends Mesh>(mesh: M): M;
+
+// Modeling: subdivision
+
+export interface SubdivideOptions {
+  /** Times to subdivide (default 1, at most 6); each level makes about 4 times the faces */
+  levels?: number;
+  /** false: only split the faces, keep the shape (default true) */
+  smooth?: boolean;
+  /** Edges where faces meet sharper than this (degrees) stay hard (default: none) */
+  creaseAngle?: number;
+  /** Edges that stay hard: pairs or polylines of vertex indices, e.g. [[0, 1], [4, 5, 6, 7, 4]] */
+  creases?: number[][];
+  /** "smooth": texture coordinates smoothed with the surface, seams kept (default); "linear": only split */
+  uvs?: "smooth" | "linear";
+}
+
+/**
+ * Smooths a mesh by subdividing it (Catmull-Clark): a rough cage becomes a
+ * smooth surface. Returns a new mesh of quads (the original isn't changed),
+ * welded, with texture coordinates and materials; own normals are dropped.
+ */
+export function subdivideMesh(mesh: Mesh, opts?: SubdivideOptions): Mesh;
+
+// Modeling: blobs (distance fields)
+
+/** How a blob shape joins what's before it: melts in (default), carves it, or keeps only the overlap. */
+export type BlobOp = "add" | "subtract" | "intersect";
+
+interface BlobBase {
+  /** How it joins what's before it (default "add") */
+  op?: BlobOp;
+  /** Same as op: "subtract" */
+  subtract?: boolean;
+  /** How far it melts into what's before it, as a distance (default: the blobMesh / blobField `blend`) */
+  blend?: number;
+}
+
+export type BlobShape = BlobBase & (
+  | { kind: "sphere"; center: Vec3; radius: number }
+  /** Turned by `rot` (radians, X then Y then Z) */
+  | { kind: "ellipsoid"; center: Vec3; radii: Vec3; rot?: Vec3 }
+  /** A capsule between two points; `ra` / `rb` instead of `radius` make a rounded cone */
+  | { kind: "capsule"; a: Vec3; b: Vec3; radius?: number; ra?: number; rb?: number }
+  /** A capped cylinder between two points, edges rounded by `round` */
+  | { kind: "cylinder"; a: Vec3; b: Vec3; radius: number; round?: number }
+  /** A box of `size`, edges rounded by `round`, turned by `rot` */
+  | { kind: "box"; center: Vec3; size: Vec3; round?: number; rot?: Vec3 }
+  /** A ring lying flat in XZ (like makeShape("torus")), turned by `rot` */
+  | { kind: "torus"; center: Vec3; R: number; tube: number; rot?: Vec3 }
+);
+
+export interface SdfMeshOptions {
+  /** Grid cells along the longest side (default 64, 4 to 256); more is finer and slower */
+  resolution?: number;
+  /** "nets": surface nets, even quads (default); "cubes": marching cubes, triangles. Both are watertight */
+  method?: "nets" | "cubes";
+  /** Pull vertices exactly onto the surface (default true) */
+  project?: boolean;
+  /** Normals from the field, for smooth shading (default true) */
+  normals?: boolean;
+  /** Texture mapping for the uvs, as for computeUVs (default "box"); false: none */
+  uvs?: MappingType | Mapping | false;
+  /** Skip grid blocks far from the surface, trusting the field to be about the distance (default true) */
+  sparse?: boolean;
+}
+
+export interface BlobMeshOptions extends Omit<SdfMeshOptions, "sparse"> {
+  /** How far shapes melt into each other, as a distance (default: a tenth of the model's size). A shape's own `blend` wins */
+  blend?: number;
+}
+
+/** One smooth mesh of shapes that melt together (added, subtracted or intersected, in order). */
+export function blobMesh(shapes: BlobShape[], opts?: BlobMeshOptions): Mesh;
+
+/** The distance field of blob shapes (negative inside), to mix with your own math and mesh with sdfMesh. */
+export function blobField(shapes: BlobShape[], opts?: { blend?: number }): (p: Vec3) => number;
+
+/** The surface where `field(p)` is 0 (negative inside), within `bounds`, as a mesh. */
+export function sdfMesh(field: (p: Vec3) => number, bounds: { min: Vec3; max: Vec3 }, opts?: SdfMeshOptions): Mesh;
+
+// Modeling: bevel
+
+export interface BevelOptions {
+  /** Size of the rounding: the radius of the ball rolled along the edges (default: a twentieth of the mesh's size). Shrinks where bevels would overlap */
+  radius?: number;
+  /** Rows across each rounded edge (default 3); 1 = a flat cut (chamfer) */
+  segments?: number;
+  /** Edges where faces meet sharper than this (degrees) are beveled (default 30) */
+  angle?: number;
+  /** "edges": round the edges, corners become pieces of a sphere (default); "vertices": cut only the corners */
+  mode?: "edges" | "vertices";
+  /** Instead of `angle`: the edges to bevel, as pairs or polylines of vertex indices */
+  edges?: number[][];
+  /** With mode "vertices", instead of `angle`: the corners to cut, as vertex indices */
+  vertices?: number[];
+}
+
+/**
+ * Rounds (or cuts flat) the sharp edges of a mesh, like a bevel modifier.
+ * Returns a new mesh, welded, with texture coordinates and materials kept.
+ * Edges along an open border stay sharp.
+ */
+export function bevelMesh(mesh: Mesh, opts?: BevelOptions): Mesh;