trid3d 0.1.1 → 0.3.0

package/trid/index.d.ts

@@ -56,10 +56,11 @@ export interface Camera {
  *
  * An edge with 2 indices is a single segment; with 3 or more it's a closed loop.
  * Faces are clockwise as seen from their front.
+ * Without `edges`, an object with no material draws the outline of each face.
  */
 export interface Mesh {
   vertices: Vec3[];
-  edges: number[][];
+  edges?: number[][];
   faces?: number[][];
   /** Per-corner normals, used by smooth shading */
   normals?: Vec3[];
@@ -69,6 +70,11 @@ export interface Mesh {
   uvs?: UV[];
   /** For each face, the index into `uvs` of each corner (null: none for that face) */
   faceUVs?: (number[] | null)[];
+  /**
+   * For each face, which entry of the object's material list it uses
+   * (when `material` is a list). Built-in cubes and boxes number their sides 0 to 5.
+   */
+  faceMaterials?: number[];
   /** Set after changing the mesh in place so renderers rebuild their caches */
   dirty?: boolean;
 }
@@ -100,24 +106,56 @@ export interface Material {
   smooth?: boolean | number;
   /** Image drawn on the faces (needs texture coordinates). `fill` tints it. */
   texture?: TextureSource;
+  /**
+   * Read the texture again every frame (default: only videos). For a canvas redrawn every
+   * frame; for one redrawn now and then, call `updateTexture(canvas)` instead.
+   */
+  liveTexture?: boolean;
   /** Keep texture pixels sharp instead of smoothing them (default false) */
   pixelated?: boolean;
   /** Effects applied in order, like `[toon(), rim()]` */
   effects?: Effect[];
+  /** Where texture coordinates come from: the mesh's own ("uv", default) or made from its shape */
+  mapping?: Mapping;
+  /** How many times the texture repeats across (default 1) */
+  textureRepeat?: number | UV;
+  /** Moves the texture; 1 is its whole width or height */
+  textureOffset?: UV;
+  /** Turns the texture around its center, in radians */
+  textureRotation?: number;
 }
 
-/** What you pass to `scene.add`. Missing transform fields get defaults. */
+/** Ways to make texture coordinates from a mesh's shape. */
+export type MappingType = "uv" | "planar" | "box" | "sphere" | "cylinder";
+
+/**
+ * A texture mapping: a type, or a type with an axis. `axis` is the projection
+ * direction for "planar" (default "z") and the wrap axis for "sphere" and "cylinder" (default "y").
+ */
+export type Mapping = MappingType | { type: MappingType; axis?: "x" | "y" | "z" };
+
+/**
+ * What you pass to `scene.add`. Missing transform fields get defaults.
+ * Give it `children` to make a group (and leave out `mesh` for a group that only holds them).
+ */
 export interface SceneObjectInput {
-  mesh: Mesh;
+  /** What's drawn. Leave it out for a group that only holds `children` */
+  mesh?: Mesh;
   pos?: Vec3;
   rot?: Vec3;
   scale?: Vec3;
+  /** Objects placed relative to this one: they move, turn and scale with it. Read every frame */
+  children?: SceneObjectInput[];
+  /** Set to false to hide this object and everything under it (default true) */
+  visible?: boolean;
+  /** A name, used by `exportOBJ` and handy for finding objects */
+  name?: string;
   /** Wireframe color (default: the scene's color) */
   color?: string;
   /** Wireframe width (default: the scene's lineWidth) */
   lineWidth?: number;
-  /** Draw faces instead of only lines */
-  material?: Material;
+  /** Draw faces instead of only lines. A list gives each group of faces its own (see `Mesh.faceMaterials`) */
+  material?: Material | Material[];
   /** Set to false to make `DragObject` ignore this object */
   draggable?: boolean;
   /** Set to false to make `HoverHighlight` ignore this object */
@@ -128,7 +166,12 @@ export interface SceneObjectInput {
  * An object in a scene, after `scene.add` filled in its transform.
  * Extra fields you add (like `{ mesh, name: "box" }`) are kept in the type.
  */
-export type SceneObject<T extends SceneObjectInput = SceneObjectInput> = T & Transform;
+export type SceneObject<T extends SceneObjectInput = SceneObjectInput> = T & Transform & {
+  /** The group it's a child of, or null at the top. Kept up to date by the scene (not enumerable) */
+  parent: SceneObject | null;
+  /** World matrix from the last frame: parents' transforms × its own (not enumerable). See `worldMatrix` */
+  world: Mat4;
+};
 
 // ---------------------------------------------------------------------------
 // Scene
@@ -191,6 +234,10 @@ export class Scene {
   start(update?: (dt: number, time: number, scene: Scene) => void): this;
   /** Stops the frame loop. The last frame stays on the canvas. */
   stop(): void;
+  /** Draws a new frame and returns it as an image file. The page's canvas doesn't change. */
+  screenshot(opts?: ScreenshotOptions): Promise<Blob>;
+  /** Starts recording the canvas as a video. */
+  record(opts?: RecordOptions): Recording;
   /** Stops the loop, removes every tool and frees the renderer's resources. */
   destroy(): void;
   /** Whether the frame loop is running. */
@@ -202,30 +249,139 @@ export class Scene {
 // ---------------------------------------------------------------------------
 
 export interface ShapeOptions {
-  /** Cube size (default 0.5) */
+  /** Cube size, or plane width (default 0.5 cube, 1 plane) */
   size?: number;
   /** Box width (default 0.6) */
   w?: number;
-  /** Box height (default 0.6) */
+  /** Box height (default 0.6), or cylinder / cone height (default 0.8) */
   h?: number;
   /** Box depth (default 0.6) */
   d?: number;
-  /** Sphere radius (default 0.45) */
+  /** Radius: sphere (0.45), cylinder (0.3), cone base (0.35) */
   r?: number;
   /** Sphere latitude bands (default 12) */
   rings?: number;
-  /** Sphere points per ring (default 24) */
+  /** Points around: sphere (24), cylinder / cone (32), torus (48) */
   segments?: 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) */
+  R?: number;
+  /** Torus tube radius (default 0.12) */
+  tube?: number;
+  /** Torus points around the tube (default 20) */
+  tubeSegments?: number;
+  /** Plane cells per side (default 8) */
+  div?: number;
+  /** Plane: lifts each vertex, for terrain */
+  height?: (x: number, z: number) => number;
 }
 
-export type ShapeKind = "cube" | "box" | "sphere";
+export type ShapeKind = "cube" | "box" | "sphere" | "cylinder" | "cone" | "torus" | "plane";
 
-/** Creates a built-in mesh (with faces and texture coordinates). */
+/**
+ * Creates a built-in mesh (with edges, faces and texture coordinates), centered
+ * on the origin. Cylinders, cones and tori stand along Y; the plane lies in XZ facing +Y.
+ */
 export function makeShape(kind: ShapeKind, opts?: ShapeOptions): Mesh;
 
+/** A point of a `lathe` profile: distance from the Y axis and height. */
+export interface ProfilePoint {
+  r: number;
+  y: number;
+}
+
+export interface LatheOptions {
+  /** Points around the axis (default 32) */
+  segments?: number;
+  /** Close the bottom with a flat cap (default false) */
+  capBottom?: boolean;
+  /** Close the top with a flat cap (default false) */
+  capTop?: boolean;
+  /** The profile's last point joins its first, for torus-like shapes (default false) */
+  closed?: boolean;
+}
+
+/**
+ * Spins a profile around the Y axis (vases, bottles, columns, chess pieces).
+ * Walk the profile so the outside is on its right: bottom to top for a vase.
+ */
+export function lathe(profile: ProfilePoint[], opts?: LatheOptions): Mesh;
+
+/** A 2D point (x right, y up). */
+export interface Point2 {
+  x: number;
+  y: number;
+}
+
+/**
+ * Turns a flat outline in the XY plane into a solid `depth` thick along Z
+ * (default 0.2), centered on the origin. Either direction, concave is fine, no holes.
+ */
+export interface ExtrudeOptions {
+  /** How much the edges between sides and front / back are cut, up to half the depth (default 0) */
+  bevel?: number;
+  /** Steps around a bevel: 1 = flat chamfer, more = rounded (default 1) */
+  bevelSegments?: number;
+  /** Size of the back compared to the front, around the outline's middle (default 1) */
+  taper?: number;
+}
+
+export function extrude(outline: Point2[], depth?: number, opts?: ExtrudeOptions): Mesh;
+
+/** Cuts a counter-clockwise polygon into counter-clockwise triangles (ear clipping). */
+export function triangulate(pts: Point2[]): number[][];
+
 /** Scales a mesh's vertices in place. Returns the same mesh. */
 export function scaleMesh<M extends { vertices: Vec3[] }>(mesh: M, sx?: number, sy?: number, sz?: number): M;
 
+/** A transform to bake into a mesh; parts left out change nothing. A scene object fits. */
+export interface MeshTransform {
+  pos?: Partial<Vec3>;
+  rot?: Partial<Vec3>;
+  scale?: Partial<Vec3>;
+}
+
+/** Deep copy of a mesh (vertices, edges, faces, UVs, normals, materials). */
+export function cloneMesh<M extends Mesh>(mesh: M): M;
+
+/**
+ * Bakes a transform into a mesh's vertices, in place (scale, rotate X→Y→Z, move).
+ * Normals turn with it; a mirroring scale reverses the faces. Returns the same mesh.
+ */
+export function transformMesh<M extends Mesh>(mesh: M, transform: MeshTransform): M;
+
+/**
+ * Moves every vertex to `fn(vertex, index)`, in place. Removes the mesh's own normals
+ * (they no longer fit), so the renderers compute new ones. Returns the same mesh.
+ */
+export function displaceMesh<M extends Mesh>(mesh: M, fn: (v: Vec3, index: number) => Vec3): M;
+
+export interface MergeOptions {
+  /** Faces of the i-th mesh use material i (default false: keep each mesh's faceMaterials) */
+  materialPerMesh?: boolean;
+}
+
+/**
+ * Joins meshes into a new one, keeping faces, edges, UVs, normals and materials.
+ * Scene objects in the list are merged where they stand (transform baked in).
+ */
+export function mergeMeshes(items: (Mesh | SceneObjectInput)[], opts?: MergeOptions): Mesh;
+
+/** A box around some geometry. */
+export interface Bounds {
+  min: Vec3;
+  max: Vec3;
+  center: Vec3;
+  size: Vec3;
+}
+
+/**
+ * The box around a mesh, a scene object, a list of them or a Scene (objects measured
+ * where they stand). Null when there are no vertices.
+ */
+export function meshBounds(input: Mesh | SceneObjectInput | (Mesh | SceneObjectInput)[] | Scene): Bounds | null;
+
 // ---------------------------------------------------------------------------
 // Renderers
 // ---------------------------------------------------------------------------
@@ -237,6 +393,9 @@ export const DEFAULT_AMBIENT: number;
 /** Default far distance (WebGL renderer). */
 export const DEFAULT_FAR: number;
 
+/** An object's materials as a list, or null when it's a wireframe. */
+export function materialsOf(obj: { material?: Material | Material[] }): Material[] | null;
+
 export interface CanvasRendererOptions {
   /**
    * Split faces bigger than this fraction of their mesh's size (like 0.05)
@@ -255,6 +414,8 @@ export class CanvasRenderer implements Renderer {
 export interface WebGLRendererOptions {
   /** Smooth edges (default true) */
   antialias?: boolean;
+  /** Free meshes and textures not drawn for this many frames (default 300, about 5 s). Infinity: never */
+  releaseAfter?: number;
 }
 
 /** Draws a scene with WebGL and a depth buffer. */
@@ -266,7 +427,13 @@ export class WebGLRenderer implements Renderer {
   /** The hidden canvas WebGL draws on. */
   canvas: HTMLCanvasElement;
   gl: WebGLRenderingContext | WebGL2RenderingContext;
+  /** Frames a mesh or texture can go undrawn before it's freed (Infinity: never). */
+  releaseAfter: number;
+  /** What's on the graphics card right now. */
+  readonly memory: { meshes: number; buffers: number; textures: number };
   render(scene: Scene): void;
+  /** Frees a mesh's buffers or a texture now; it's sent again if drawn again. */
+  release(item: Mesh | TextureSource): void;
   /** Frees the graphics card memory. The renderer can't be used afterwards. */
   dispose(): void;
 }
@@ -394,6 +561,41 @@ export function uniformType(value: unknown): "float" | "vec2" | "vec3" | "vec4"
 /** The GLSL declaration of `Surface`, shared by every effect. */
 export const SURFACE_GLSL: string;
 
+// ---------------------------------------------------------------------------
+// Texture mapping
+// ---------------------------------------------------------------------------
+
+/** Texture coordinates for every face corner. */
+export interface MeshUVs {
+  uvs: UV[];
+  faceUVs: number[][];
+}
+
+/** The mapping types. */
+export const MAPPINGS: readonly MappingType[];
+
+/** Texture coordinates made from a mesh's shape. The mesh isn't changed. */
+export function computeUVs(mesh: Mesh, mapping: Mapping): MeshUVs;
+
+/** Replaces a mesh's texture coordinates with ones made from its shape, in place. */
+export function mapUVs<M extends Mesh>(mesh: M, mapping: Mapping): M & MeshUVs;
+
+/** The texture coordinates a renderer uses for a mesh and mapping (cached). */
+export function uvsFor(mesh: Mesh, mapping?: Mapping): { uvs?: UV[]; faceUVs?: (number[] | null)[] };
+
+/** A material's repeat, offset and rotation as [a, b, c, d, e, f], or null when they change nothing. */
+export function uvTransform(material: Material): [number, number, number, number, number, number] | null;
+
+/** Applies a `uvTransform` matrix to one texture coordinate. */
+export function applyUVTransform(m: number[] | null, uv: UV): UV;
+export function applyUVTransform(m: number[] | null, uv: UV | null): UV | null;
+
+/** A mapping as `{ type, axis }`. Throws for an unknown type or axis. */
+export function mappingOf(mapping?: Mapping): { type: MappingType; axis?: "x" | "y" | "z" };
+
+/** A short string naming a mapping, for caches ("" for "uv"). */
+export function mappingKey(mapping?: Mapping): string;
+
 // ---------------------------------------------------------------------------
 // Normals
 // ---------------------------------------------------------------------------
@@ -417,12 +619,35 @@ export function newell(pts: Vec3[]): Vec3;
 /** A mesh loaded from an OBJ file. Always has faces. */
 export interface ObjMesh extends Mesh {
   faces: number[][];
+  /** Material names from `usemtl` lines, in the order they first appear */
+  materialNames?: string[];
+  /** The .mtl file the OBJ names (`mtllib`) */
+  mtllib?: string;
+  /** With `loadOBJ(url, { materials: true })`: one material per `materialNames` entry, from the .mtl file */
+  materials?: Material[];
 }
 
 export interface ObjOptions {
   /** Center the model and scale it so its largest side is this long */
   fit?: number;
+  /** `loadOBJ` only: also load the .mtl file and its textures into `mesh.materials` (default false) */
+  materials?: boolean;
+}
+
+/** A material from an MTL file. */
+export interface MtlMaterial {
+  name: string;
+  /** "#rrggbb" from `Kd`, or "rgba(...)" when see-through */
+  fill?: string;
+  /** From `d` / `Tr`, 0 to 1 */
+  opacity?: number;
+  /** The texture's file name (`map_Kd`), relative to the .mtl file */
+  textureFile?: string;
 }
+/** Parses the text of an MTL file: materials by name. */
+export function parseMTL(text: string): Record<string, MtlMaterial>;
+/** The materials of a parsed OBJ from its .mtl file (one per `materialNames` entry), textures loaded. */
+export function loadMaterials(mesh: ObjMesh, base: URL | string): Promise<Material[]>;
 
 /** Parses the text of an OBJ file. */
 export function parseOBJ(text: string, opts?: ObjOptions): ObjMesh;
@@ -441,8 +666,118 @@ export function loadTexture(url: string): Promise<HTMLImageElement>;
 export function textureReady(src: TextureSource | null | undefined): boolean;
 /** Pixel size of a texture source. */
 export function textureSize(src: TextureSource): { w: number; h: number };
-/** Whether a source can change over time (canvas, video). */
-export function textureIsLive(src: TextureSource): boolean;
+/** Whether a texture is read again every frame: videos, or any source whose material has `liveTexture: true`. */
+export function textureIsLive(src: TextureSource, material?: { liveTexture?: boolean }): boolean;
+/**
+ * Tells the renderers a texture changed (call it after drawing on a canvas used as a texture):
+ * it's read again once, on the next frame. Canvases are otherwise read only once.
+ */
+export function updateTexture(src: TextureSource): void;
+/** How many times `updateTexture` was called for a source (0 when never). */
+export function textureVersion(src: TextureSource): number;
+
+// ---------------------------------------------------------------------------
+// Exporting
+// ---------------------------------------------------------------------------
+
+export interface ExportOBJOptions {
+  /**
+   * Write texture coordinates (default true). For an object whose material has a
+   * `mapping` or texture repeat/offset/rotation, the coordinates it's drawn with are written.
+   */
+  uvs?: boolean;
+  /** Write the mesh's normals when it has them (default true) */
+  normals?: boolean;
+  /** Write edges that aren't the side of a face as lines (default true) */
+  lines?: boolean;
+  /** Decimals kept in numbers (default 6) */
+  precision?: number;
+  /** Comment at the top of the file; "" for none (default "Exported by Trid") */
+  header?: string;
+  /** Link this .mtl file and name every material (the names `exportMTL` writes) */
+  mtllib?: string;
+}
+
+/** A material description for `exportMTL`. */
+export interface MtlDescription {
+  name: string;
+  fill?: string;
+  opacity?: number;
+  /** Texture file name */
+  texture?: string;
+}
+
+/** The materials an export names, with each texture's file name. */
+export function objMaterials(
+  input: OBJExportable | OBJExportable[] | Scene,
+  opts?: { textureFile?: (name: string, texture: TextureSource) => string },
+): { name: string; material: Material | null; texture: TextureSource | null; file: string | null }[];
+/** Writes an MTL file: for what `exportOBJ` takes (same names), or for plain descriptions. */
+export function exportMTL(
+  input: OBJExportable | OBJExportable[] | Scene | MtlDescription[],
+  opts?: { textureFile?: (name: string, texture: TextureSource) => string; header?: string },
+): string;
+/** A texture image as a PNG (or other) file. */
+export function textureToBlob(src: TextureSource, type?: string): Promise<Blob>;
+/** Every file of a model: name.obj, name.mtl and one PNG per texture. */
+export function exportModel(
+  input: OBJExportable | OBJExportable[] | Scene,
+  opts?: { name?: string; obj?: ExportOBJOptions },
+): Promise<{ name: string; data: string | Blob }[]>;
+
+/** Something exportOBJ can write: a mesh, or an object placed in a scene. */
+export type OBJExportable = Mesh | (SceneObjectInput & Partial<Transform> & { name?: string });
+
+/**
+ * Writes meshes as the text of an OBJ file. Objects are written where they are
+ * in the scene; a list or a Scene gives one `o` per object.
+ */
+export function exportOBJ(input: OBJExportable | OBJExportable[] | Scene, opts?: ExportOBJOptions): string;
+
+export interface ScreenshotOptions {
+  /** "image/png" (default), "image/jpeg" or "image/webp" */
+  type?: string;
+  /** For JPEG and WebP, from 0 to 1 (default 0.92) */
+  quality?: number;
+  /** Image width in pixels (default: the canvas's) */
+  width?: number;
+  /** Image height in pixels (default: the canvas's) */
+  height?: number;
+  /** Include what tools draw on top (default true) */
+  tools?: boolean;
+}
+
+export interface RecordOptions {
+  /** Frames per second (default 60) */
+  fps?: number;
+  /** Video format, like "video/webm" (default: the best one the browser has) */
+  type?: string;
+  /** Quality: higher is sharper and bigger (default 8,000,000) */
+  bitsPerSecond?: number;
+  /** Stop by itself after this many seconds */
+  duration?: number;
+}
+
+/** A video being recorded. */
+export interface Recording {
+  /** The video format being recorded */
+  readonly type: string;
+  /** Whether it's still recording */
+  readonly recording: boolean;
+  /** Resolves with the video once recording stops */
+  readonly done: Promise<Blob>;
+  /** Stops recording; resolves with the video */
+  stop(): Promise<Blob>;
+}
+
+/** Draws a new frame of a scene and returns it as an image file. */
+export function screenshot(scene: Scene, opts?: ScreenshotOptions): Promise<Blob>;
+
+/** Records a scene's canvas as a video. Throws if the browser can't. */
+export function record(scene: Scene, opts?: RecordOptions): Recording;
+
+/** Saves a file or text in the browser's downloads. */
+export function download(data: Blob | string | Promise<Blob | string>, filename: string): Promise<void>;
 
 // ---------------------------------------------------------------------------
 // Tools
@@ -529,6 +864,12 @@ export interface OrbitCameraOptions {
   pan?: boolean;
   /** Allow zooming (default true) */
   zoom?: boolean;
+  /** Turn around the target on its own, paused while dragging (default false) */
+  autoRotate?: boolean;
+  /** Auto-rotate speed in radians per second; negative turns the other way (default 0.5) */
+  autoRotateSpeed?: number;
+  /** Seconds to wait after a drag before auto-rotating again (default 0) */
+  autoRotateDelay?: number;
 }
 
 /** Mouse camera controls that turn around a target point. */
@@ -548,9 +889,14 @@ export class OrbitCamera implements Tool {
   rotate: boolean;
   pan: boolean;
   zoom: boolean;
+  autoRotate: boolean;
+  autoRotateSpeed: number;
+  autoRotateDelay: number;
   blockContextMenu: boolean;
   /** Places the camera from the target, distance, yaw and pitch. */
   apply(camera: Camera): void;
+  /** Restarts the auto-rotate wait, as if the user had just dragged (for tools that turn the camera). */
+  holdAutoRotate(): void;
   attach(scene: Scene): void;
   pointerDown(e: ToolPointerEvent): boolean;
   pointerMove(e: ToolPointerEvent, scene: Scene): void;
@@ -589,6 +935,10 @@ export interface DragObjectOptions {
   button?: number;
   /** Which objects can be dragged (default: those without `draggable: false`) */
   filter?: (obj: SceneObject) => boolean;
+  /** Pick by triangles instead of bounding boxes (default false, see `pickHit`) */
+  exact?: boolean;
+  /** Drag the top-level object (the whole group) of what was clicked (default false) */
+  root?: boolean;
   /** Called when an object is picked */
   onPick?: (obj: SceneObject) => void;
   /** Called each time the object moves */
@@ -602,6 +952,8 @@ export class DragObject implements Tool {
   constructor(opts?: DragObjectOptions);
   button: number;
   filter: (obj: SceneObject) => boolean;
+  exact: boolean;
+  root: boolean;
   onPick?: (obj: SceneObject) => void;
   onMove?: (obj: SceneObject) => void;
   onDrop?: (obj: SceneObject) => void;
@@ -618,6 +970,8 @@ export interface HoverHighlightOptions {
   color?: string;
   /** Which objects can be highlighted (default: those without `hoverable: false`) */
   filter?: (obj: SceneObject) => boolean;
+  /** Pick by triangles instead of bounding boxes (default false, see `pickHit`) */
+  exact?: boolean;
   /** Called when the hovered object changes */
   onChange?: (obj: SceneObject | null) => void;
 }
@@ -627,6 +981,7 @@ export class HoverHighlight implements Tool {
   constructor(opts?: HoverHighlightOptions);
   color: string;
   filter: (obj: SceneObject) => boolean;
+  exact: boolean;
   onChange?: (obj: SceneObject | null) => void;
   /** The object under the pointer, or null. */
   hovered: SceneObject | null;
@@ -694,6 +1049,97 @@ export class ObjUploader implements Tool {
   draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
 }
 
+export interface ViewGizmoOptions {
+  /** Camera controls to turn (default: the scene's first OrbitCamera). Without one, it only shows the axes */
+  orbit?: OrbitCamera;
+  /** Where it sits (default "top-right") */
+  corner?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  /** Radius in CSS pixels (default 42) */
+  size?: number;
+  /** Distance from the canvas corner in CSS pixels (default 14) */
+  margin?: number | { x: number; y: number };
+  /** Seconds the camera takes to turn to a clicked axis (default 0.35) */
+  duration?: number;
+}
+
+/**
+ * The X, Y, Z axes in a corner, turning with the camera; click one to look along it.
+ * Add it after the OrbitCamera.
+ */
+export class ViewGizmo implements Tool {
+  constructor(opts?: ViewGizmoOptions);
+  orbit: OrbitCamera | null;
+  corner: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  size: number;
+  margin: { x: number; y: number };
+  duration: number;
+  /** Hide or show the gizmo without removing the tool. */
+  visible: boolean;
+  /** Whether a canvas pixel is on the gizmo (as last drawn). */
+  contains(x: number, y: number): boolean;
+  /** Turns the camera smoothly to look at its target from `dir` ({ x: 0, y: 1, z: 0 }: from above). */
+  lookAlong(dir: Vec3): void;
+  attach(scene: Scene): void;
+  detach(): void;
+  pointerDown(e: ToolPointerEvent): boolean;
+  update(dt: number, scene: Scene): void;
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
+}
+
+export type TransformMode = "move" | "rotate" | "scale";
+
+/** A move, rotate or scale in world space, as `TransformGizmo` reports it. */
+export type TransformOp =
+  | { mode: "move"; delta: Vec3 }
+  /** A right-handed turn of `angle` radians around the unit `axis`, about `center` */
+  | { mode: "rotate"; axis: Vec3; angle: number; center: Vec3 }
+  /** `factor` about `center`: uniform when `axis` is null, otherwise along that unit axis */
+  | { mode: "scale"; axis: Vec3 | null; factor: number; center: Vec3 };
+
+export interface TransformGizmoOptions {
+  /** Default "move" */
+  mode?: TransformMode;
+  /** Objects it edits (default none) */
+  targets?: SceneObject[];
+  /** Handle length in CSS pixels (default 70) */
+  size?: number;
+  /** Change the targets' transforms while dragging (default true) */
+  apply?: boolean;
+  /** A handle was grabbed */
+  onGrab?: (targets: SceneObject[]) => void;
+  /** While dragging: the operation since the grab */
+  onChange?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** On release: the whole operation */
+  onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+}
+
+/**
+ * Move arrows, rotate rings or scale handles on one or more objects, around their
+ * shared center. Add it after the camera tool.
+ */
+export class TransformGizmo implements Tool {
+  constructor(opts?: TransformGizmoOptions);
+  mode: TransformMode;
+  targets: SceneObject[];
+  size: number;
+  apply: boolean;
+  onGrab?: (targets: SceneObject[]) => void;
+  onChange?: (op: TransformOp, targets: SceneObject[]) => void;
+  onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** Hide the handles (and ignore clicks) without removing the tool. */
+  visible: boolean;
+  /** True while a handle is being dragged. */
+  readonly dragging: boolean;
+  /** Middle of the targets' bounding box in world space, or null. */
+  center(): Vec3 | null;
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
+  pointerDown(e: ToolPointerEvent, scene: Scene): boolean;
+  pointerMove(e: ToolPointerEvent, scene: Scene): void;
+  pointerUp(): void;
+  pointerLeave(scene: Scene): void;
+  detach(scene: Scene): void;
+}
+
 export interface ScreenBox {
   minX: number;
   minY: number;
@@ -706,9 +1152,31 @@ export function pick(
   scene: Scene,
   x: number,
   y: number,
-  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number },
+  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number; exact?: boolean },
 ): SceneObject | null;
 
+/** What `pickHit` found. */
+export interface PickHit {
+  object: SceneObject;
+  /** Index in `mesh.faces`, or -1 for a line of a wireframe */
+  face: number;
+  /** Distance in front of the camera */
+  depth: number;
+  /** The object, then its groups up to the top: `[part, group, ..., root]` */
+  path: SceneObject[];
+}
+
+/**
+ * Exact picking: the nearest object whose triangles (or, without faces, lines
+ * within `padding` pixels) are under a canvas pixel.
+ */
+export function pickHit(
+  scene: Scene,
+  x: number,
+  y: number,
+  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number; objects?: SceneObject[] },
+): PickHit | null;
+
 /** Screen-space bounding box of an object, or null if it's all behind the camera. */
 export function screenBounds(scene: Scene, obj: SceneObject): ScreenBox | null;
 
@@ -742,9 +1210,13 @@ export function drawInstance(
   h: number,
   color: string,
   lineWidth?: number,
+  /** World matrix to place it with (e.g. `obj.world` inside a group); default: its own transform */
+  world?: Mat4,
 ): void;
 /** Turns edge definitions into pairs of vertex indices. */
-export function edgeSegments(edges: number[][]): Generator<[number, number]>;
+export function edgeSegments(edges?: number[][]): Generator<[number, number]>;
+/** The lines a wireframe draws for a mesh: its `edges`, or its face outlines when it has none. */
+export function wireEdges(mesh: { edges?: number[][]; faces?: number[][] }): number[][];
 
 /** Runs `update` every animation frame. Returns a function that stops it. */
 export function loop(update: (dt: number, time: number) => void, opts?: { maxDt?: number }): () => void;
@@ -781,3 +1253,145 @@ export function rotateXYZ(p: Vec3, rot: Vec3): Vec3;
 export function project(p: Vec3, fov?: number, aspect?: number): Vec2;
 /** Normalized coordinates to canvas pixels. */
 export function screen(p: Vec2, w: number, h: number): Vec2;
+
+// ---------------------------------------------------------------------------
+// Rotations
+// ---------------------------------------------------------------------------
+
+/** 3×3 matrix, row-major (m[row][col]), applied as M · v. */
+export type Mat3 = [[number, number, number], [number, number, number], [number, number, number]];
+
+/** The matrix `rotateXYZ(p, rot)` applies. */
+export function matFromEuler(rot: Vec3): Mat3;
+/** Angles for `rotateXYZ` (an object's `rot`) from a rotation matrix; the inverse of `matFromEuler`. */
+export function eulerFromMat(m: Mat3): Vec3;
+/** A right-handed turn of `angle` radians around a unit `axis`. */
+export function matFromAxisAngle(axis: Vec3, angle: number): Mat3;
+/** Matrix product a · b (b is applied first). */
+export function mulMat(a: Mat3, b: Mat3): Mat3;
+/** m · v */
+export function mulVec(m: Mat3, v: Vec3): Vec3;
+/** Applies a world-space move / rotate / scale to a transform and returns the new one. */
+export function applyTransformOp(t: Transform, op: TransformOp): Transform;
+
+// ---------------------------------------------------------------------------
+// Procedural textures
+// ---------------------------------------------------------------------------
+
+export type TextureStyle = "noise" | "marble" | "wood" | "bricks" | "checker" | "bark" | "spots" | "stripes" | "solid";
+/** The built-in styles of `makeTexture`. */
+export const TEXTURE_STYLES: TextureStyle[];
+
+export interface MakeTextureOptions {
+  /** Width and height in pixels (default 256) */
+  size?: number;
+  /** [first, second]: hex, rgb() / rgba(), CSS names or [r, g, b, a?] (default: suits the style) */
+  colors?: (string | number[])[];
+  /** How many times the pattern repeats across, a whole number (default 4) */
+  scale?: number;
+  /** Another whole number gives another texture of the same style (default 0) */
+  seed?: number;
+  /** Fine speckles on top, 0 to 1 (default 0) */
+  grain?: number;
+  /** Paint into this canvas instead of a new one (calls `updateTexture` for you) */
+  canvas?: HTMLCanvasElement | OffscreenCanvas;
+}
+
+/**
+ * Paints a seamless procedural texture on a canvas. `style` is a built-in style, or
+ * `(u, v) => t` (0: first color, 1: second).
+ */
+export function makeTexture(
+  style?: TextureStyle | ((u: number, v: number) => number),
+  opts?: MakeTextureOptions,
+): HTMLCanvasElement | OffscreenCanvas;
+/** The pixels of a procedural texture (RGBA, top row first), without a canvas. */
+export function texturePixels(
+  style?: TextureStyle | ((u: number, v: number) => number),
+  opts?: Omit<MakeTextureOptions, "canvas">,
+): { width: number; height: number; data: Uint8ClampedArray };
+/** [r, g, b, a] (0..255, a 0..1) from a color string or array. */
+export function colorBytes(color: string | number[]): [number, number, number, number];
+
+// ---------------------------------------------------------------------------
+// Groups (scene graph)
+// ---------------------------------------------------------------------------
+
+/**
+ * Every visible object of a scene (or of objects and their subtrees), parents first,
+ * with `parent` and `world` set. Groups without a mesh are included.
+ */
+export function worldObjects(input: Scene | SceneObjectInput | SceneObjectInput[]): SceneObject[];
+/** An object's world matrix right now, from its transform and its parents'. */
+export function worldMatrix(obj: SceneObjectInput): Mat4;
+/** Where an object's origin is in the world right now. */
+export function worldPosition(obj: SceneObjectInput): Vec3;
+/** The chain from an object up to the top: `[obj, parent, ..., root]`. */
+export function ancestors(obj: SceneObject): SceneObject[];
+/**
+ * Calls `fn(obj, world, parent)` for every visible object under some roots, parents first,
+ * without changing anything. `baseOf(root)` is the matrix a root goes under (null: none).
+ */
+export function forEachPlaced(
+  roots: SceneObjectInput[],
+  baseOf: (root: SceneObjectInput) => Mat4 | null,
+  fn: (obj: SceneObjectInput, world: Mat4, parent: SceneObjectInput | null) => void,
+): void;
+
+// ---------------------------------------------------------------------------
+// Matrices
+// ---------------------------------------------------------------------------
+
+/** 4×4 transform matrix, 16 numbers in column-major order (`m[col * 4 + row]`), like WebGL. */
+export type Mat4 = number[];
+
+/** The identity matrix. */
+export function identityMat4(): Mat4;
+/** The matrix of a transform: scale, rotate X → Y → Z, then move. */
+export function mat4FromTransform(t: MeshTransform): Mat4;
+/** a · b (b applied first): a child's world matrix is `mulMat4(parentWorld, childLocal)`. */
+export function mulMat4(a: Mat4, b: Mat4): Mat4;
+/** Inverse of a transform matrix (identity if it flattens space). */
+export function invertMat4(m: Mat4): Mat4;
+/** Determinant of the 3×3 part: < 0 when the matrix mirrors. */
+export function determinantMat4(m: Mat4): number;
+/** A point through a matrix. */
+export function transformPoint(m: Mat4, p: Vec3): Vec3;
+/** A direction or offset through a matrix (not moved). */
+export function transformDirection(m: Mat4, v: Vec3): Vec3;
+/** The 3×3 normal matrix (inverse transpose), column-major. */
+export function normalMatrix(m: Mat4): number[];
+/** A normal through a normal matrix, unit length. */
+export function transformNormal(nm: number[], n: Vec3): Vec3;
+/** A world-space `TransformOp` in a parent's space, for objects inside groups. */
+export function transformOpToLocal(op: TransformOp, parentWorld: Mat4): TransformOp;
+
+// ---------------------------------------------------------------------------
+// Random numbers and noise
+// ---------------------------------------------------------------------------
+
+/** A seeded random generator (mulberry32): each call returns the next number in [0, 1). */
+export function rng(seed?: number): () => number;
+
+export interface NoiseOptions {
+  /** Whole number; another seed gives other noise (default 0) */
+  seed?: number;
+  /** Repeat every this many units, a whole number, for seamless textures (default 0: never) */
+  period?: number;
+}
+
+export interface FbmOptions extends NoiseOptions {
+  /** Layers of detail (default 5) */
+  octaves?: number;
+  /** Strength of each layer compared to the one before (default 0.5) */
+  gain?: number;
+}
+
+/** Smooth 2D value noise in [0, 1). */
+export function noise2(x: number, y: number, opts?: NoiseOptions): number;
+/** Smooth 3D value noise in [0, 1). */
+export function noise3(x: number, y: number, z: number, opts?: NoiseOptions): number;
+/** Fractal 2D noise: octaves of noise2, each twice as fine. About [0, 1), averaging 0.5. */
+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;