trid3d 0.5.0 → 0.6.0

package/README.md

@@ -4,20 +4,20 @@
 
 <h1 align="center">Trid</h1>
 
-<p align="center">A small 3D library for the HTML canvas. No dependencies, no build step.</p>
+<p align="center">Model, light and draw 3D on the HTML canvas. No dependencies, no build step.</p>
 
 ---
 
-Trid gives you a scene, a camera, shapes, model loading and mouse/keyboard tools, all in plain ES modules you can drop next to your page.
+Trid gives you a scene, shapes you can model in code, lights, effects, model loading and mouse/keyboard tools, all in plain ES modules you can drop next to your page. See the [docs](https://zachr622.github.io/Trid/) for live demos.
 
 > **Status:** early (0.x): the API can still change between minor versions. See [Upgrading](#upgrading).
 
 ## Features
 
-- **Scene** — holds a canvas, a camera and your objects, and runs the frame loop for you.
+- **Scene** — holds a canvas, a camera, lights and your objects, and runs the frame loop for you. The background can be a color or see-through (`"transparent"`), so a model can float over your page.
 - **Groups** — give any object `children` and they move, turn and scale with it (models made of parts, a moon orbiting a planet).
-- **Shapes** — cubes, boxes (sharp or rounded), spheres, cylinders, cones, tori and planes built in, `lathe` for round shapes and `extrude` for flat ones, or any mesh you define as vertices and edges.
-- **Modeling** — smooth curves through a few points (`spline`), shapes swept along a 3D path (`sweep`: tails, horns, pipes, rails), surfaces through cross-sections (`loft`: bodies, bottles, hulls, heads), subdivision surfaces with creases (`subdivideMesh`: box modeling), shapes that melt together (`blobMesh`: creatures, clay; or any distance field with `sdfMesh`), rounded or cut edges on any mesh (`bevelMesh`), taper, twist, bend and bulge deformers, and mesh cleanup and checks (weld, clean, validate, fix winding).
+- **Shapes** — cubes, boxes (sharp or rounded), spheres, cylinders, cones, tori and planes built in, `lathe` for round shapes (a point on the axis closes it to a tip) and `extrude` for flat ones, or any mesh you define as vertices, faces and edges.
+- **Modeling** — smooth curves through a few points (`spline`), shapes swept along a 3D path (`sweep`: tails, horns, pipes, rails), surfaces through cross-sections (`loft`: bodies, bottles, hulls, heads), subdivision surfaces with creases (`subdivideMesh`: box modeling), shapes that melt together (`blobMesh`: creatures, clay; or any distance field with `sdfMesh`), rounded or cut edges on any mesh (`bevelMesh`), taper, twist, bend and bulge deformers, mesh cleanup and checks (weld, clean, validate, fix winding), and rays, inside tests and distances against meshes and scenes (`meshQuery`, `raycastScene`).
 - **Mesh helpers** — clone, transform, displace, merge and measure meshes; seeded random numbers and smooth noise (`fbm2`, `fbm3`, tileable) for rocks, terrain and procedural textures.
 - **Filled faces** — give an object a `material` to fill and shade its faces, flat or smooth.
 - **Lights** — ambient, directional and point lights, with colors and intensities, as many as you need (up to 8 at once besides ambient).
@@ -27,7 +27,7 @@ Trid gives you a scene, a camera, shapes, model loading and mouse/keyboard tools
 - **Two renderers** — the canvas 2D context by default, or `WebGLRenderer` for exact depth and big models, with the same scene code.
 - **OBJ files** — load models from a URL (with their `.mtl` colors and textures), or let users drop their own `.obj` files on the canvas.
 - **Export** — `scene.screenshot()` and `scene.record()` save images and videos of the canvas; `exportOBJ` / `exportModel` write meshes, objects or whole scenes as OBJ files with their MTL materials and textures.
-- **Camera** — position, yaw, pitch and field of view, with near-plane clipping.
+- **Camera** — position, yaw, pitch and field of view (50° by default), with near-plane clipping.
 - **Tools** — orbit and fly cameras, object dragging, hover highlight, a move / rotate / scale gizmo (with a pivot of your choice), a view axes gizmo, a floor grid, an FPS meter and an OBJ uploader, one line each. Exact picking by triangles, with the hit point and texture coordinates under the mouse. Writing your own is a plain object with a few methods.
 - **Pure math** — every transform and projection step is exported, plus 4×4 matrices and rotations, so you can use the pipeline piece by piece.
 
@@ -41,7 +41,7 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 
 ```html
 <script type="importmap">
-  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.3/trid/index.js" } }
+  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.6/trid/index.js" } }
 </script>
 ```
 
@@ -56,13 +56,22 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 // main.js
 import { Scene, makeShape, OrbitCamera } from "trid3d";
 
-const scene = new Scene(document.getElementById("canvas"), { width: 800, height: 400 });
-const cube = scene.add({ mesh: makeShape("cube"), color: "#E9806E" });              // wireframe
-const ball = scene.add({ mesh: makeShape("sphere"), material: { fill: "#8ab4f8" } }); // filled and shaded
-ball.pos.x = 0.8;
+const scene = new Scene(document.getElementById("canvas"), {
+  width: 800, height: 400,
+  camera: { z: -1.5 }, // a step back
+});
+
+// A cube with rounded edges, filled and smoothly shaded
+const cube = scene.add({
+  mesh: makeShape("cube", { radius: 0.08 }),
+  material: { fill: "#E9806E", smooth: true },
+});
 
 scene.use(new OrbitCamera()); // drag to orbit, scroll to zoom
-scene.start((dt) => (cube.rot.y += dt));
+scene.start((dt) => {
+  cube.rot.x += dt * 0.5;
+  cube.rot.y += dt * 0.35;
+});
 ```
 
 Without a bundler, serve the folder (`python3 -m http.server`) instead of opening the file directly: browsers block module imports from `file://` pages.
@@ -87,7 +96,7 @@ Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.ob
 | `trid/sceneGraph.js` | Groups: `children`, world matrices |
 | `trid/math/` | Transforms, camera directions, projection, matrices, rotations, random numbers and noise |
 | `trid/render/` | Renderers (Canvas 2D, WebGL), lights, effects, post effects, shapes, grids, mesh helpers, procedural textures, drawing, frame loop |
-| `trid/modeling/` | Modeling tools: curves, sweep, loft, subdivision, blobs, bevel, deformers, cleanup |
+| `trid/modeling/` | Modeling tools: curves, sweep, loft, subdivision, blobs, bevel, deformers, cleanup, queries (rays, inside, distance) |
 | `trid/loaders/` | OBJ, MTL and texture loading |
 | `trid/export/` | Screenshots, video recording, OBJ and MTL export |
 | `trid/tools/` | Camera, object, gizmo and overlay tools |
@@ -113,10 +122,16 @@ See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/docs/README.
 npm test
 ```
 
-Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes, mesh helpers, curves, sweeps, lofts, subdivision, blobs, bevels, deformers, mesh cleanup, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, post effects, grids, and the WebGL renderer's GPU memory on a fake WebGL context.
+Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes (lathe poles included), mesh helpers, curves, sweeps, lofts, subdivision, blobs, bevels, deformers, mesh cleanup, mesh and scene queries, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, post effects, grids, the field of view, see-through backgrounds, and the WebGL renderer's GPU memory on a fake WebGL context.
 
 ## Upgrading
 
+### From 0.5 to 0.6
+
+- **The cone's tip is a single point** (a pole), so the cone is closed: `isClosed` and `validateMesh` no longer report a hole there. It has fewer vertices than before (its tip ring of 32 is now 1), and its side faces are triangles. Any `lathe` profile point with `r: 0` works the same way.
+- **The default field of view is 50°** (`DEFAULT_FOV`), instead of 90°. Scenes whose camera has no `fov` look about twice as close, like in most 3D tools. To keep the old view, give the camera `fov: Math.PI / 2`.
+- **`background: null` is see-through**, like `"transparent"` (it used to come out black). `clear()` now empties the canvas before painting the background, so see-through and half see-through backgrounds work; opaque ones look the same.
+
 ### From 0.3 to 0.4
 
 - **Lights are a list**: `scene.lights`. A scene still starts with one directional light and an ambient level, and looks the same. `scene.light` and `scene.ambient` are now shortcuts for the first directional light's direction and the first ambient light's intensity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A small 3D library for the HTML canvas: wireframes, filled and smooth faces, textures and shader effects, drawn with Canvas 2D or WebGL. No dependencies.",
   "keywords": [
     "3d",

package/trid/index.d.ts

@@ -43,7 +43,7 @@ export interface Camera {
   yaw?: number;
   /** Tilt around X in radians, > 0 looks up (default 0) */
   pitch?: number;
-  /** Vertical field of view in radians (default Math.PI / 2) */
+  /** Vertical field of view in radians (default DEFAULT_FOV: 50°) */
   fov?: number;
   /** Near plane distance; closer geometry is clipped (default 0.01) */
   near?: number;
@@ -192,8 +192,8 @@ export interface SceneOptions {
   width?: number;
   /** Sets canvas.height (keeps the current one if omitted) */
   height?: number;
-  /** Clear color (default "#141414") */
-  background?: string;
+  /** Clear color (default "#141414"); "transparent", a see-through rgba() or null: the page shows behind */
+  background?: string | null;
   /** Default wireframe color (default "#ffffff") */
   color?: string;
   /** Default wireframe width (default 3) */
@@ -221,7 +221,7 @@ export class Scene {
 
   canvas: HTMLCanvasElement;
   ctx: CanvasRenderingContext2D;
-  background: string;
+  background: string | null;
   color: string;
   lineWidth: number;
   camera: Camera;
@@ -1426,8 +1426,8 @@ export function worldPerPixel(scene: Scene, depth: number): number;
 // Drawing and the frame loop
 // ---------------------------------------------------------------------------
 
-/** Fills the whole canvas with a color. */
-export function clear(ctx: CanvasRenderingContext2D, w: number, h: number, color: string): void;
+/** Clears the whole canvas, then fills it with a color ("transparent" or null: left see-through). */
+export function clear(ctx: CanvasRenderingContext2D, w: number, h: number, color?: string | null): void;
 /** Draws a square point centered at a screen position. */
 export function point(ctx: CanvasRenderingContext2D, p: Vec2, color: string, size?: number): void;
 /** Draws a line between two screen points. */
@@ -1467,7 +1467,7 @@ export function parseColor(ctx: CanvasRenderingContext2D, color: string): RGBA;
 // Math
 // ---------------------------------------------------------------------------
 
-/** Default vertical field of view (90°). */
+/** Default vertical field of view: 50° (in radians). */
 export const DEFAULT_FOV: number;
 /** Default near plane distance. */
 export const DEFAULT_NEAR: number;
@@ -1951,3 +1951,99 @@ export interface BevelOptions {
  * Edges along an open border stay sharp.
  */
 export function bevelMesh(mesh: Mesh, opts?: BevelOptions): Mesh;
+
+// Modeling: queries (rays, inside, distance)
+
+/** Which faces a ray counts: "both" (default), "front" (hit from outside) or "back" (hit from inside). */
+export type RaySide = "both" | "front" | "back";
+
+export interface RaycastOptions {
+  /** Ignore hits farther than this (default Infinity) */
+  maxDistance?: number;
+  /** Which faces count (default "both") */
+  side?: RaySide;
+}
+
+/** Where a ray met a mesh, in the mesh's own space. */
+export interface MeshHit {
+  point: Vec3;
+  /** Unit normal of the face, pointing out of the mesh (whichever side the ray came from) */
+  normal: Vec3;
+  /** From the ray's origin */
+  distance: number;
+  /** Index in `mesh.faces` */
+  face: number;
+  /** true when the ray met the face from outside */
+  front: boolean;
+  /** The 3 vertex indices of the triangle hit (faces with more corners are fans from their first corner) */
+  triangle: [number, number, number];
+  /** Weights of those vertices at the point (they add up to 1) */
+  barycentric: [number, number, number];
+}
+
+/** The nearest point of a mesh's surface. */
+export type MeshClosest = Omit<MeshHit, "front">;
+
+/** A mesh prepared for many questions (a snapshot: editing the mesh later doesn't change it). */
+export interface MeshQuery {
+  /** Triangles in the query (faces split into fans) */
+  readonly triangleCount: number;
+  /** The mesh's box */
+  readonly bounds: { min: Vec3; max: Vec3 };
+  /** The first place a ray meets the surface, or null. `direction` can be any length but zero */
+  raycast(origin: Vec3, direction: Vec3, opts?: RaycastOptions): MeshHit | null;
+  /** Whether a point is inside (only meaningful for a closed mesh, see `isClosed`) */
+  contains(p: Vec3): boolean;
+  /** The nearest point of the surface, or null when nothing is within `maxDistance` */
+  closest(p: Vec3, opts?: { maxDistance?: number }): MeshClosest | null;
+  /** Distance to the surface (Infinity when nothing is within `maxDistance`) */
+  distance(p: Vec3, maxDistance?: number): number;
+}
+
+/** Prepares a mesh for many ray, inside and distance questions (builds a BVH once). */
+export function meshQuery(mesh: Mesh): MeshQuery;
+
+/** One-off `meshQuery(mesh).raycast(...)`. For many rays on one mesh, keep a `meshQuery`. */
+export function raycastMesh(mesh: Mesh, origin: Vec3, direction: Vec3, opts?: RaycastOptions): MeshHit | null;
+
+/** One-off `meshQuery(mesh).contains(p)`. */
+export function pointInMesh(mesh: Mesh, p: Vec3): boolean;
+
+/** One-off `meshQuery(mesh).distance(p, maxDistance)`. */
+export function distanceToMesh(mesh: Mesh, p: Vec3, maxDistance?: number): number;
+
+/** One-off `meshQuery(mesh).closest(p, opts)`. */
+export function closestPointOnMesh(mesh: Mesh, p: Vec3, opts?: { maxDistance?: number }): MeshClosest | null;
+
+/** Whether a mesh is closed (watertight): every edge, matched by position, shared by exactly two faces. */
+export function isClosed(mesh: Mesh): boolean;
+
+/** What `raycastScene` found: a `MeshHit` in world space, plus the object. */
+export interface SceneHit extends MeshHit {
+  object: SceneObject;
+  /** The object, then its groups up to the top: `[part, group, ..., root]` */
+  path: SceneObject[];
+  /** Where the hit is, in the mesh's own space (`point` is in the world) */
+  local: Vec3;
+}
+
+export interface RaycastSceneOptions extends RaycastOptions {
+  /** Return false to skip an object */
+  filter?: (obj: SceneObject) => boolean;
+  /** Only these objects (and their children) */
+  objects?: SceneObjectInput[];
+}
+
+/**
+ * The first object a ray meets, in world space (the 3D version of `pickHit`).
+ * Hidden objects, `pickable: false` ones and objects without faces are skipped.
+ */
+export function raycastScene(
+  scene: Scene | SceneObjectInput[],
+  origin: Vec3,
+  direction: Vec3,
+  opts?: RaycastSceneOptions,
+): SceneHit | null;
+
+/** Forgets the prepared query `raycastScene` keeps for a mesh (after editing it in place once `dirty` was cleared). */
+export function clearQueryCache(mesh: Mesh): void;

package/trid/index.js

@@ -91,3 +91,6 @@ export { weldVertices, cleanMesh, validateMesh, fixWinding } from "./modeling/cl
 export { subdivideMesh } from "./modeling/subdivide.js";
 export { blobMesh, blobField, sdfMesh } from "./modeling/blobs.js";
 export { bevelMesh } from "./modeling/bevel.js";
+export {
+  meshQuery, raycastMesh, pointInMesh, distanceToMesh, closestPointOnMesh, isClosed, raycastScene, clearQueryCache,
+} from "./modeling/query.js";

package/trid/math/projection.js

@@ -1,3 +1,9 @@
+/**
+ * Default vertical field of view: 50°, a normal lens (like most 3D tools).
+ * Wider shows more but makes everything smaller; set `camera.fov` to change it.
+ */
+export const DEFAULT_FOV = (50 * Math.PI) / 180;
+
 /**
  * Converts normalized device coordinates (-1 to +1)
  * into actual screen (pixel) coordinates.
@@ -36,11 +42,11 @@ export function screen(p, w, h) {
  * - larger z => appears smaller
  *
  * @param {{x:number, y:number, z:number}} p - 3D point (camera space)
- * @param {number} fov - Vertical field of view in radians (default: 90°)
+ * @param {number} fov - Vertical field of view in radians (default: `DEFAULT_FOV`, 50°)
  * @param {number} aspect - Canvas width / height (default: 1)
  * @returns {{x:number, y:number}} 2D projected point
  */
-export function project(p, fov = Math.PI / 2, aspect = 1) {
+export function project(p, fov = DEFAULT_FOV, aspect = 1) {
   const f = 1 / Math.tan(fov / 2);
   return {
     x: (p.x * f) / (p.z * aspect),

package/trid/math/transform.js

@@ -1,4 +1,6 @@
-import { project, screen } from "./projection.js";
+import { project, screen, DEFAULT_FOV } from "./projection.js";
+
+export { DEFAULT_FOV };
 
 /**
  * Camera object. Every field is optional and falls back to its default.
@@ -11,14 +13,11 @@ import { project, screen } from "./projection.js";
  * @property {number} [z=0] - Position on Z
  * @property {number} [yaw=0] - Turn around Y in radians (> 0 turns right)
  * @property {number} [pitch=0] - Tilt around X in radians (> 0 looks up)
- * @property {number} [fov=Math.PI/2] - Vertical field of view in radians
+ * @property {number} [fov=DEFAULT_FOV] - Vertical field of view in radians (default 50°)
  * @property {number} [near=0.01] - Near plane distance; closer geometry is clipped
  * @property {number} [far=1000] - Far distance; farther geometry isn't drawn (WebGL renderer only)
  */
 
-/** Default vertical field of view (90°). */
-export const DEFAULT_FOV = Math.PI / 2;
-
 /** Default near plane distance. */
 export const DEFAULT_NEAR = 0.01;
 

package/trid/modeling/query.js

@@ -0,0 +1,706 @@
+/**
+ * Questions about a mesh's surface, asked in code: where a ray first meets
+ * it, whether a point is inside it, how far a point is from it, and whether
+ * it's closed. Also the same ray question against a whole scene.
+ *
+ *   const q = meshQuery(body);                 // prepared once (a BVH)
+ *   const hit = q.raycast(from, { x: 0, y: 0, z: 1 });
+ *   q.contains(p); q.distance(p); q.closest(p);
+ *
+ * A query is a snapshot: it copies the mesh's triangles when it's made, so
+ * editing the mesh afterwards doesn't change its answers. Make a new one.
+ *
+ * Faces are clockwise from outside (like the built-in shapes), so normals
+ * here point out of the mesh, whichever side a ray comes from.
+ */
+import { invertMat4, determinantMat4, transformPoint, transformDirection, normalMatrix, transformNormal } from "../math/matrix.js";
+import { worldObjects, ancestors } from "../sceneGraph.js";
+import { isPickable } from "../tools/helpers.js";
+import { samePlace } from "./cleanup.js";
+
+/** Most triangles in a BVH leaf */
+const LEAF = 4;
+/** Bins per split when building the BVH (surface area heuristic) */
+const BINS = 12;
+
+const SIDES = ["both", "front", "back"];
+
+/** Odd-looking directions, so rays rarely run exactly along edges (for `contains`) */
+const PROBES = [
+  [0.5383, 0.6412, 0.5468], [-0.7071, 0.1934, 0.6797], [0.2311, -0.8417, -0.4878],
+  [-0.3122, -0.4519, 0.8357], [0.8829, -0.2711, 0.3833], [-0.5867, 0.7713, -0.2467],
+  [0.1471, 0.3378, -0.9296],
+].map(([x, y, z]) => {
+  const l = Math.hypot(x, y, z);
+  return [x / l, y / l, z / l];
+});
+
+const finite = (v) => !!v && Number.isFinite(v.x) && Number.isFinite(v.y) && Number.isFinite(v.z);
+
+function checkPoint(p, what) {
+  if (!finite(p)) throw new Error(`${what} must be a point { x, y, z } of finite numbers`);
+}
+
+function unitDirection(d) {
+  const l = finite(d) ? Math.hypot(d.x, d.y, d.z) : NaN;
+  if (!(l > 0) || !Number.isFinite(l)) throw new Error("A ray needs a direction { x, y, z } that isn't zero");
+  return { x: d.x / l, y: d.y / l, z: d.z / l };
+}
+
+function checkSide(side) {
+  if (!SIDES.includes(side)) throw new Error(`Unknown side "${side}": use "both", "front" or "back"`);
+}
+
+/**
+ * Prepares a mesh for many questions: splits its faces into triangles (fans
+ * from each face's first corner, like `pickHit`) and builds a bounding volume
+ * hierarchy (boxes inside boxes) so each question only looks at the few
+ * triangles near it. Making it costs about as much as one slow question.
+ *
+ * @param {Object} mesh - A mesh with `vertices` and `faces`
+ * @returns {MeshQuery}
+ */
+export function meshQuery(mesh) {
+  return new MeshQuery(mesh);
+}
+
+class MeshQuery {
+  constructor(mesh) {
+    const v = mesh?.vertices ?? [];
+    const corners = [], faceOf = [];
+    (mesh?.faces ?? []).forEach((f, fi) => {
+      if (!Array.isArray(f)) return;
+      for (let i = 1; i + 1 < f.length; i++) {
+        if (!finite(v[f[0]]) || !finite(v[f[i]]) || !finite(v[f[i + 1]])) continue;
+        corners.push(f[0], f[i], f[i + 1]);
+        faceOf.push(fi);
+      }
+    });
+    const n = faceOf.length;
+    const tris = new Float64Array(n * 9);
+    for (let t = 0; t < n; t++) {
+      for (let k = 0; k < 3; k++) {
+        const p = v[corners[t * 3 + k]];
+        tris[t * 9 + k * 3] = p.x;
+        tris[t * 9 + k * 3 + 1] = p.y;
+        tris[t * 9 + k * 3 + 2] = p.z;
+      }
+    }
+    /** Triangles, 9 numbers each (in BVH order after building) */
+    this._tris = tris;
+    this._corners = Int32Array.from(corners);
+    this._faceOf = Int32Array.from(faceOf);
+    /** Number of triangles */
+    this.triangleCount = n;
+    buildBVH(this);
+
+    const b = this._box;
+    this.bounds = n
+      ? { min: { x: b[0], y: b[1], z: b[2] }, max: { x: b[3], y: b[4], z: b[5] } }
+      : { min: { x: 0, y: 0, z: 0 }, max: { x: 0, y: 0, z: 0 } };
+    const size = n ? Math.max(b[3] - b[0], b[4] - b[1], b[5] - b[2]) || 1 : 1;
+    // Tolerances relative to the mesh's size
+    this._minDist = size * 1e-9;
+    this._detEps = size * size * 1e-14;
+    this._edgeEps = 1e-7;
+    this._hit = { t: 0, tri: -1, u: 0, w: 0 };
+    this._near = new Float64Array(5);
+  }
+
+  /**
+   * The first place a ray meets the surface, or null.
+   *
+   * @param {Vec3} origin
+   * @param {Vec3} direction - Any length but zero
+   * @param {{maxDistance?:number, side?:"both"|"front"|"back"}} [opts]
+   *   `side`: "front" only counts faces hit from outside, "back" from inside
+   * @returns {{point, normal, distance, face, front, triangle, barycentric} | null}
+   */
+  raycast(origin, direction, { maxDistance = Infinity, side = "both" } = {}) {
+    checkPoint(origin, "raycast: origin");
+    checkSide(side);
+    const d = unitDirection(direction);
+    if (!this._cast(origin, d, maxDistance, side)) return null;
+    const { t, tri, u, w } = this._hit;
+    return this._describe(tri, u, w, { x: origin.x + d.x * t, y: origin.y + d.y * t, z: origin.z + d.z * t }, t, d);
+  }
+
+  /**
+   * Whether a point is inside. Only meaningful for a closed mesh (see
+   * `isClosed`). Rays are sent in a few directions and their crossings
+   * counted; rays that pass too close to an edge are ignored.
+   *
+   * @param {Vec3} p
+   * @returns {boolean}
+   */
+  contains(p) {
+    checkPoint(p, "contains: the point");
+    const b = this._box;
+    if (!this.triangleCount || p.x < b[0] || p.y < b[1] || p.z < b[2] || p.x > b[3] || p.y > b[4] || p.z > b[5]) return false;
+    let inside = 0, outside = 0, unsureIn = 0, unsureOut = 0;
+    for (const dir of PROBES) {
+      const r = this._crossings(p, dir);
+      if (r.sure) (r.count % 2 ? inside++ : outside++);
+      else (r.count % 2 ? unsureIn++ : unsureOut++);
+      if (inside >= 2 || outside >= 2) break;
+    }
+    if (inside !== outside) return inside > outside;
+    return unsureIn > unsureOut;
+  }
+
+  /**
+   * The nearest point of the surface, or null when there's none within `maxDistance`.
+   *
+   * @param {Vec3} p
+   * @param {{maxDistance?:number}} [opts]
+   * @returns {{point, normal, distance, face, triangle, barycentric} | null}
+   */
+  closest(p, { maxDistance = Infinity } = {}) {
+    checkPoint(p, "closest: the point");
+    const found = this._nearest(p, maxDistance);
+    if (found < 0) return null;
+    const c = this._near;
+    const w1 = c[3], w2 = c[4];
+    const point = { x: c[0], y: c[1], z: c[2] };
+    return this._describe(found, w1, w2, point, Math.hypot(p.x - c[0], p.y - c[1], p.z - c[2]), null);
+  }
+
+  /**
+   * Distance from a point to the surface (Infinity when nothing is within `maxDistance`).
+   *
+   * @param {Vec3} p
+   * @param {number} [maxDistance=Infinity] - Stop looking past this (faster)
+   * @returns {number}
+   */
+  distance(p, maxDistance = Infinity) {
+    checkPoint(p, "distance: the point");
+    const found = this._nearest(p, maxDistance);
+    if (found < 0) return Infinity;
+    const c = this._near;
+    return Math.hypot(p.x - c[0], p.y - c[1], p.z - c[2]);
+  }
+
+  /** Unit normal of triangle `tri`, pointing out (clockwise faces). */
+  _normal(tri) {
+    const q = this._tris, i = tri * 9;
+    const e1x = q[i + 3] - q[i], e1y = q[i + 4] - q[i + 1], e1z = q[i + 5] - q[i + 2];
+    const e2x = q[i + 6] - q[i], e2y = q[i + 7] - q[i + 1], e2z = q[i + 8] - q[i + 2];
+    const nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
+    const l = Math.hypot(nx, ny, nz) || 1;
+    return { x: nx / l, y: ny / l, z: nz / l };
+  }
+
+  _describe(tri, u, w, point, distance, dir) {
+    const normal = this._normal(tri);
+    const out = {
+      point,
+      normal,
+      distance,
+      face: this._faceOf[tri],
+      triangle: [this._corners[tri * 3], this._corners[tri * 3 + 1], this._corners[tri * 3 + 2]],
+      barycentric: [1 - u - w, u, w],
+    };
+    if (dir) out.front = dir.x * normal.x + dir.y * normal.y + dir.z * normal.z < 0;
+    return out;
+  }
+
+  /**
+   * First hit of the ray o + t·d (d any length), 0 < t < maxT in units of d.
+   * Fills `this._hit` and returns true when something is hit.
+   */
+  _cast(o, d, maxT, side) {
+    if (!this.triangleCount) return false;
+    const dl = Math.hypot(d.x, d.y, d.z);
+    const minT = this._minDist / dl, detEps = this._detEps * dl;
+    const sign = side === "front" ? 1 : side === "back" ? -1 : 0;
+    const ix = 1 / d.x, iy = 1 / d.y, iz = 1 / d.z;
+    const box = this._box, first = this._first, count = this._count, tris = this._tris, stack = this._stack;
+    const hit = this._hit;
+    let best = maxT, found = -1, bu = 0, bw = 0;
+    let top = 0;
+    if (enter(box, 0, o, ix, iy, iz, best) === Infinity) return false;
+    stack[top++] = 0;
+    while (top) {
+      const node = stack[--top];
+      const n = count[node];
+      if (n > 0) {
+        for (let k = first[node], end = first[node] + n; k < end; k++) {
+          const i = k * 9;
+          const e1x = tris[i + 3] - tris[i], e1y = tris[i + 4] - tris[i + 1], e1z = tris[i + 5] - tris[i + 2];
+          const e2x = tris[i + 6] - tris[i], e2y = tris[i + 7] - tris[i + 1], e2z = tris[i + 8] - tris[i + 2];
+          const px = d.y * e2z - d.z * e2y, py = d.z * e2x - d.x * e2z, pz = d.x * e2y - d.y * e2x;
+          const det = e1x * px + e1y * py + e1z * pz;
+          // det > 0: the ray meets the face from outside
+          if (Math.abs(det) <= detEps || det * sign < 0) continue;
+          const inv = 1 / det;
+          const sx = o.x - tris[i], sy = o.y - tris[i + 1], sz = o.z - tris[i + 2];
+          const u = (sx * px + sy * py + sz * pz) * inv;
+          if (u < 0 || u > 1) continue;
+          const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;
+          const w = (d.x * qx + d.y * qy + d.z * qz) * inv;
+          if (w < 0 || u + w > 1) continue;
+          const t = (e2x * qx + e2y * qy + e2z * qz) * inv;
+          if (t > minT && t < best) {
+            best = t;
+            found = k;
+            bu = u;
+            bw = w;
+          }
+        }
+      } else {
+        // Visit the nearer child first; skip boxes past the best hit
+        const a = first[node], b = a + 1;
+        const ta = enter(box, a * 6, o, ix, iy, iz, best), tb = enter(box, b * 6, o, ix, iy, iz, best);
+        if (ta <= tb) {
+          if (tb !== Infinity) stack[top++] = b;
+          if (ta !== Infinity) stack[top++] = a;
+        } else {
+          if (ta !== Infinity) stack[top++] = a;
+          stack[top++] = b;
+        }
+      }
+    }
+    if (found < 0) return false;
+    hit.t = best;
+    hit.tri = found;
+    hit.u = bu;
+    hit.w = bw;
+    return true;
+  }
+
+  /** How many faces a ray from p crosses, and whether every crossing was clear of edges. */
+  _crossings(p, [dx, dy, dz]) {
+    const tris = this._tris, box = this._box, first = this._first, count = this._count, stack = this._stack;
+    const ix = 1 / dx, iy = 1 / dy, iz = 1 / dz, minT = this._minDist, eps = this._edgeEps, detEps = this._detEps;
+    let hits = 0, sure = true, top = 0;
+    stack[top++] = 0;
+    while (top) {
+      const node = stack[--top];
+      if (enter(box, node * 6, p, ix, iy, iz, Infinity) === Infinity) continue;
+      const n = count[node];
+      if (n === 0) {
+        stack[top++] = first[node];
+        stack[top++] = first[node] + 1;
+        continue;
+      }
+      for (let k = first[node], end = first[node] + n; k < end; k++) {
+        const i = k * 9;
+        const e1x = tris[i + 3] - tris[i], e1y = tris[i + 4] - tris[i + 1], e1z = tris[i + 5] - tris[i + 2];
+        const e2x = tris[i + 6] - tris[i], e2y = tris[i + 7] - tris[i + 1], e2z = tris[i + 8] - tris[i + 2];
+        const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;
+        const det = e1x * px + e1y * py + e1z * pz;
+        if (Math.abs(det) <= detEps) continue;
+        const inv = 1 / det;
+        const sx = p.x - tris[i], sy = p.y - tris[i + 1], sz = p.z - tris[i + 2];
+        const u = (sx * px + sy * py + sz * pz) * inv;
+        if (u < -eps || u > 1 + eps) continue;
+        const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;
+        const w = (dx * qx + dy * qy + dz * qz) * inv;
+        if (w < -eps || u + w > 1 + eps) continue;
+        const t = (e2x * qx + e2y * qy + e2z * qz) * inv;
+        if (t <= -minT) continue;
+        // Near an edge or the start point: this ray can't be trusted
+        if (u < eps || w < eps || u + w > 1 - eps || t <= minT) sure = false;
+        if (t > minT && u >= 0 && w >= 0 && u + w <= 1) hits++;
+      }
+    }
+    return { count: hits, sure };
+  }
+
+  /** Nearest triangle to p within maxDist (its closest point in `this._near`), or -1. */
+  _nearest(p, maxDist) {
+    if (!this.triangleCount) return -1;
+    const box = this._box, first = this._first, count = this._count, tris = this._tris, stack = this._stack;
+    const near = this._near, tmp = new Float64Array(5);
+    let best2 = maxDist === Infinity ? Infinity : maxDist * maxDist, found = -1, top = 0;
+    if (boxDist2(box, 0, p) > best2) return -1;
+    stack[top++] = 0;
+    while (top) {
+      const node = stack[--top];
+      if (boxDist2(box, node * 6, p) > best2) continue;
+      const n = count[node];
+      if (n > 0) {
+        for (let k = first[node], end = first[node] + n; k < end; k++) {
+          const d2 = closestOnTriangle(tris, k * 9, p, tmp);
+          if (d2 <= best2) {
+            best2 = d2;
+            found = k;
+            near.set(tmp);
+          }
+        }
+      } else {
+        const a = first[node], b = a + 1;
+        const da = boxDist2(box, a * 6, p), db = boxDist2(box, b * 6, p);
+        // Push the farther first, so the nearer is looked at first
+        if (da <= db) {
+          if (db <= best2) stack[top++] = b;
+          if (da <= best2) stack[top++] = a;
+        } else {
+          if (da <= best2) stack[top++] = a;
+          if (db <= best2) stack[top++] = b;
+        }
+      }
+    }
+    return found;
+  }
+}
+
+/**
+ * Builds the BVH on `q`, sorting its triangles so each leaf's are together.
+ * Nodes: `_box` (6 numbers each), `_count` (> 0 for a leaf: its triangles
+ * from `_first`; 0 for an inner node: its children are `_first` and `_first + 1`).
+ */
+function buildBVH(q) {
+  const n = q.triangleCount, src = q._tris;
+  const triBox = new Float64Array(n * 6), cen = new Float64Array(n * 3);
+  for (let t = 0; t < n; t++) {
+    for (let a = 0; a < 3; a++) {
+      const x = src[t * 9 + a], y = src[t * 9 + 3 + a], z = src[t * 9 + 6 + a];
+      const lo = Math.min(x, y, z), hi = Math.max(x, y, z);
+      triBox[t * 6 + a] = lo;
+      triBox[t * 6 + 3 + a] = hi;
+      cen[t * 3 + a] = (lo + hi) / 2;
+    }
+  }
+  const order = new Int32Array(n);
+  for (let t = 0; t < n; t++) order[t] = t;
+
+  const maxNodes = Math.max(1, 2 * n - 1);
+  const box = new Float64Array(maxNodes * 6), first = new Int32Array(maxNodes), count = new Int32Array(maxNodes);
+  let nodes = 1, depth = 1;
+  const binCount = new Int32Array(BINS), binBox = new Float64Array(BINS * 6);
+  const rightArea = new Float64Array(BINS), rightCount = new Int32Array(BINS);
+
+  const work = [[0, 0, n, 1]];
+  while (work.length) {
+    const [node, start, end, level] = work.pop();
+    depth = Math.max(depth, level);
+    // Node box and centroid box
+    const k = node * 6;
+    box.fill(Infinity, k, k + 3);
+    box.fill(-Infinity, k + 3, k + 6);
+    let cminx = Infinity, cminy = Infinity, cminz = Infinity, cmaxx = -Infinity, cmaxy = -Infinity, cmaxz = -Infinity;
+    for (let i = start; i < end; i++) {
+      const t = order[i];
+      for (let a = 0; a < 3; a++) {
+        if (triBox[t * 6 + a] < box[k + a]) box[k + a] = triBox[t * 6 + a];
+        if (triBox[t * 6 + 3 + a] > box[k + 3 + a]) box[k + 3 + a] = triBox[t * 6 + 3 + a];
+      }
+      const cx = cen[t * 3], cy = cen[t * 3 + 1], cz = cen[t * 3 + 2];
+      if (cx < cminx) cminx = cx;
+      if (cy < cminy) cminy = cy;
+      if (cz < cminz) cminz = cz;
+      if (cx > cmaxx) cmaxx = cx;
+      if (cy > cmaxy) cmaxy = cy;
+      if (cz > cmaxz) cmaxz = cz;
+    }
+    const size = end - start;
+    if (size <= LEAF) {
+      first[node] = start;
+      count[node] = size;
+      continue;
+    }
+
+    // Split along the longest side of the centroids' box
+    const ex = cmaxx - cminx, ey = cmaxy - cminy, ez = cmaxz - cminz;
+    const axis = ex >= ey && ex >= ez ? 0 : ey >= ez ? 1 : 2;
+    const lo = axis === 0 ? cminx : axis === 1 ? cminy : cminz;
+    const extent = axis === 0 ? ex : axis === 1 ? ey : ez;
+    let mid = -1;
+    if (extent > 0) {
+      // Surface area heuristic over BINS bins
+      const scale = BINS / extent;
+      const binOf = (t) => Math.min(BINS - 1, Math.floor((cen[t * 3 + axis] - lo) * scale));
+      binCount.fill(0);
+      for (let b = 0; b < BINS; b++) {
+        binBox.fill(Infinity, b * 6, b * 6 + 3);
+        binBox.fill(-Infinity, b * 6 + 3, b * 6 + 6);
+      }
+      for (let i = start; i < end; i++) {
+        const t = order[i], b = binOf(t);
+        binCount[b]++;
+        for (let a = 0; a < 3; a++) {
+          if (triBox[t * 6 + a] < binBox[b * 6 + a]) binBox[b * 6 + a] = triBox[t * 6 + a];
+          if (triBox[t * 6 + 3 + a] > binBox[b * 6 + 3 + a]) binBox[b * 6 + 3 + a] = triBox[t * 6 + 3 + a];
+        }
+      }
+      // Areas from the right, then sweep from the left
+      const acc = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+      let c = 0;
+      for (let b = BINS - 1; b > 0; b--) {
+        grow(acc, binBox, b * 6);
+        c += binCount[b];
+        rightArea[b] = c ? area(acc) : 0;
+        rightCount[b] = c;
+      }
+      acc.splice(0, 6, Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity);
+      c = 0;
+      let bestCost = Infinity, bestBin = -1;
+      for (let b = 1; b < BINS; b++) {
+        grow(acc, binBox, (b - 1) * 6);
+        c += binCount[b - 1];
+        if (!c || !rightCount[b]) continue;
+        const cost = area(acc) * c + rightArea[b] * rightCount[b];
+        if (cost < bestCost) {
+          bestCost = cost;
+          bestBin = b;
+        }
+      }
+      if (bestBin > 0) {
+        // Partition: bins below bestBin to the left
+        let i = start, j = end - 1;
+        while (i <= j) {
+          if (binOf(order[i]) < bestBin) i++;
+          else {
+            const s = order[i];
+            order[i] = order[j];
+            order[j--] = s;
+          }
+        }
+        mid = i;
+      }
+    }
+    // All centroids at one place, or no useful split: cut the list in half
+    if (mid <= start || mid >= end) mid = (start + end) >> 1;
+
+    const left = nodes;
+    nodes += 2;
+    first[node] = left;
+    count[node] = 0;
+    work.push([left + 1, mid, end, level + 1], [left, start, mid, level + 1]);
+  }
+
+  // Triangles in leaf order, so leaves read them in a row
+  const tris = new Float64Array(n * 9), corners = new Int32Array(n * 3), faceOf = new Int32Array(n);
+  for (let i = 0; i < n; i++) {
+    const t = order[i];
+    tris.set(src.subarray(t * 9, t * 9 + 9), i * 9);
+    corners.set(q._corners.subarray(t * 3, t * 3 + 3), i * 3);
+    faceOf[i] = q._faceOf[t];
+  }
+  q._tris = tris;
+  q._corners = corners;
+  q._faceOf = faceOf;
+  q._box = box.subarray(0, nodes * 6);
+  q._first = first.subarray(0, nodes);
+  q._count = count.subarray(0, nodes);
+  // An empty mesh: one empty leaf whose box nothing enters
+  if (!n) q._box.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+  q._stack = new Int32Array(depth * 2 + 2);
+}
+
+function grow(acc, b, k) {
+  for (let a = 0; a < 3; a++) {
+    if (b[k + a] < acc[a]) acc[a] = b[k + a];
+    if (b[k + 3 + a] > acc[3 + a]) acc[3 + a] = b[k + 3 + a];
+  }
+}
+
+function area(b) {
+  const x = b[3] - b[0], y = b[4] - b[1], z = b[5] - b[2];
+  return x * y + y * z + z * x;
+}
+
+/** Where the ray o + t·(1/inv) enters box k, within [0, far]; Infinity if it doesn't. */
+function enter(box, k, o, ix, iy, iz, far) {
+  let t0 = 0, t1 = far;
+  const lx = box[k], ly = box[k + 1], lz = box[k + 2], hx = box[k + 3], hy = box[k + 4], hz = box[k + 5];
+  if (ix === Infinity || ix === -Infinity) {
+    if (o.x < lx || o.x > hx) return Infinity;
+  } else {
+    let a = (lx - o.x) * ix, b = (hx - o.x) * ix;
+    if (a > b) [a, b] = [b, a];
+    if (a > t0) t0 = a;
+    if (b < t1) t1 = b;
+  }
+  if (iy === Infinity || iy === -Infinity) {
+    if (o.y < ly || o.y > hy) return Infinity;
+  } else {
+    let a = (ly - o.y) * iy, b = (hy - o.y) * iy;
+    if (a > b) [a, b] = [b, a];
+    if (a > t0) t0 = a;
+    if (b < t1) t1 = b;
+  }
+  if (iz === Infinity || iz === -Infinity) {
+    if (o.z < lz || o.z > hz) return Infinity;
+  } else {
+    let a = (lz - o.z) * iz, b = (hz - o.z) * iz;
+    if (a > b) [a, b] = [b, a];
+    if (a > t0) t0 = a;
+    if (b < t1) t1 = b;
+  }
+  // A little slack, so rays along a box's face aren't lost to rounding
+  return t0 <= t1 * (1 + 1e-12) + 1e-12 ? t0 : Infinity;
+}
+
+/** Squared distance from p to box k (0 inside). */
+function boxDist2(box, k, p) {
+  const dx = Math.max(box[k] - p.x, 0, p.x - box[k + 3]);
+  const dy = Math.max(box[k + 1] - p.y, 0, p.y - box[k + 4]);
+  const dz = Math.max(box[k + 2] - p.z, 0, p.z - box[k + 5]);
+  return dx * dx + dy * dy + dz * dz;
+}
+
+/**
+ * Closest point on the triangle at `i` to p (Ericson's method): writes
+ * x, y, z and the weights of the 2nd and 3rd corners into `out`, returns
+ * the squared distance.
+ */
+function closestOnTriangle(q, i, p, out) {
+  const ax = q[i], ay = q[i + 1], az = q[i + 2];
+  const abx = q[i + 3] - ax, aby = q[i + 4] - ay, abz = q[i + 5] - az;
+  const acx = q[i + 6] - ax, acy = q[i + 7] - ay, acz = q[i + 8] - az;
+  const apx = p.x - ax, apy = p.y - ay, apz = p.z - az;
+  const d1 = abx * apx + aby * apy + abz * apz, d2 = acx * apx + acy * apy + acz * apz;
+  let v, w;
+  if (d1 <= 0 && d2 <= 0) {
+    v = 0; w = 0;
+  } else {
+    const bpx = p.x - q[i + 3], bpy = p.y - q[i + 4], bpz = p.z - q[i + 5];
+    const d3 = abx * bpx + aby * bpy + abz * bpz, d4 = acx * bpx + acy * bpy + acz * bpz;
+    const cpx = p.x - q[i + 6], cpy = p.y - q[i + 7], cpz = p.z - q[i + 8];
+    const d5 = abx * cpx + aby * cpy + abz * cpz, d6 = acx * cpx + acy * cpy + acz * cpz;
+    const vc = d1 * d4 - d3 * d2, vb = d5 * d2 - d1 * d6, va = d3 * d6 - d5 * d4;
+    if (d3 >= 0 && d4 <= d3) {
+      v = 1; w = 0;
+    } else if (d6 >= 0 && d5 <= d6) {
+      v = 0; w = 1;
+    } else if (vc <= 0 && d1 >= 0 && d3 <= 0) {
+      v = d1 / (d1 - d3); w = 0;
+    } else if (vb <= 0 && d2 >= 0 && d6 <= 0) {
+      v = 0; w = d2 / (d2 - d6);
+    } else if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) {
+      w = (d4 - d3) / (d4 - d3 + (d5 - d6)); v = 1 - w;
+    } else {
+      const den = 1 / (va + vb + vc);
+      v = vb * den; w = vc * den;
+    }
+  }
+  const x = ax + abx * v + acx * w, y = ay + aby * v + acy * w, z = az + abz * v + acz * w;
+  out[0] = x; out[1] = y; out[2] = z; out[3] = v; out[4] = w;
+  return (p.x - x) ** 2 + (p.y - y) ** 2 + (p.z - z) ** 2;
+}
+
+// One-off questions: each builds a query and throws it away. For many
+// questions on one mesh, use meshQuery.
+
+/** The first place a ray meets a mesh, or null. Same as `meshQuery(mesh).raycast(...)`. */
+export function raycastMesh(mesh, origin, direction, opts) {
+  return meshQuery(mesh).raycast(origin, direction, opts);
+}
+
+/** Whether a point is inside a closed mesh. Same as `meshQuery(mesh).contains(p)`. */
+export function pointInMesh(mesh, p) {
+  return meshQuery(mesh).contains(p);
+}
+
+/** Distance from a point to a mesh's surface. Same as `meshQuery(mesh).distance(p, maxDistance)`. */
+export function distanceToMesh(mesh, p, maxDistance) {
+  return meshQuery(mesh).distance(p, maxDistance);
+}
+
+/** The nearest point of a mesh's surface. Same as `meshQuery(mesh).closest(p, opts)`. */
+export function closestPointOnMesh(mesh, p, opts) {
+  return meshQuery(mesh).closest(p, opts);
+}
+
+/**
+ * Whether a mesh is closed (watertight): every edge, matched by vertex
+ * position (texture seams split vertices), is shared by exactly two faces.
+ * Only a closed mesh has an inside.
+ *
+ * @param {Object} mesh
+ * @returns {boolean}
+ */
+export function isClosed(mesh) {
+  const v = mesh?.vertices ?? [];
+  if (!mesh?.faces?.length || !v.length) return false;
+  let size = 0;
+  for (const p of v) if (finite(p)) size = Math.max(size, Math.abs(p.x), Math.abs(p.y), Math.abs(p.z));
+  const same = samePlace(v, (size || 1) * 1e-7);
+  const edges = new Map();
+  for (const f of mesh.faces) {
+    if (!Array.isArray(f)) return false;
+    for (let i = 0; i < f.length; i++) {
+      const a = same[f[i]], b = same[f[(i + 1) % f.length]];
+      if (a === undefined || b === undefined) return false;
+      if (a === b) continue; // a collapsed edge (a sphere's poles)
+      const key = a < b ? `${a},${b}` : `${b},${a}`;
+      edges.set(key, (edges.get(key) ?? 0) + 1);
+    }
+  }
+  if (!edges.size) return false;
+  for (const n of edges.values()) if (n !== 2) return false;
+  return true;
+}
+
+// Scene rays
+
+/** Prepared queries for meshes in scenes, rebuilt when a mesh changes. */
+const cache = new WeakMap();
+
+function cachedQuery(mesh) {
+  const c = cache.get(mesh);
+  if (c && !mesh.dirty && c.vertices === mesh.vertices && c.faces === mesh.faces
+    && c.vertexCount === mesh.vertices.length && c.faceCount === mesh.faces.length) return c.query;
+  const query = meshQuery(mesh);
+  cache.set(mesh, { query, vertices: mesh.vertices, faces: mesh.faces, vertexCount: mesh.vertices.length, faceCount: mesh.faces.length });
+  return query;
+}
+
+/**
+ * Forgets the prepared query `raycastScene` keeps for a mesh, so the next
+ * ray rebuilds it. Needed only after changing a mesh's vertices in place
+ * once a renderer has already cleared its `dirty` flag.
+ *
+ * @param {Object} mesh
+ */
+export function clearQueryCache(mesh) {
+  if (mesh) cache.delete(mesh);
+}
+
+/**
+ * The first object a ray meets in a scene, in world space: the 3D version
+ * of `pickHit`. Each object's position, rotation, scale and groups are
+ * taken into account. Hidden objects, objects with `pickable: false` and
+ * objects without faces are skipped.
+ *
+ * Each mesh's query is prepared once and kept until the mesh changes
+ * (new arrays, a different count, or `mesh.dirty`).
+ *
+ * @param {Object} scene - A Scene, or a list of objects
+ * @param {Vec3} origin - In the world
+ * @param {Vec3} direction - In the world, any length but zero
+ * @param {Object} [opts]
+ * @param {(obj:Object) => boolean} [opts.filter] - Return false to skip an object
+ * @param {number} [opts.maxDistance=Infinity]
+ * @param {"both"|"front"|"back"} [opts.side="both"]
+ * @param {Object[]} [opts.objects] - Only these objects (and their children)
+ * @returns {Object|null} The hit: object, path, point, local, normal, distance, face, front, triangle, barycentric
+ */
+export function raycastScene(scene, origin, direction, { filter = () => true, maxDistance = Infinity, side = "both", objects } = {}) {
+  checkPoint(origin, "raycastScene: origin");
+  checkSide(side);
+  const d = unitDirection(direction);
+  let best = maxDistance, hit = null;
+  for (const object of worldObjects(objects ?? scene)) {
+    const mesh = object.mesh;
+    if (!mesh?.faces?.length || !Array.isArray(mesh.vertices) || !isPickable(object) || !filter(object)) continue;
+    const world = object.world;
+    if (!(Math.abs(determinantMat4(world)) > 1e-18)) continue; // scaled to nothing
+    const inv = invertMat4(world);
+    // The ray in the mesh's space; t stays the world distance since d is unit length
+    const lo = transformPoint(inv, origin), ld = transformDirection(inv, d);
+    const q = cachedQuery(mesh);
+    if (!q._cast(lo, ld, best, side)) continue;
+    const { t, tri, u, w } = q._hit;
+    best = t;
+    hit = { object, world, q, tri, u, w, t, lo, ld };
+  }
+  if (!hit) return null;
+  const { object, world, q, tri, u, w, t, lo, ld } = hit;
+  const local = { x: lo.x + ld.x * t, y: lo.y + ld.y * t, z: lo.z + ld.z * t };
+  const out = q._describe(tri, u, w, { x: origin.x + d.x * t, y: origin.y + d.y * t, z: origin.z + d.z * t }, t, ld);
+  out.normal = transformNormal(normalMatrix(world), out.normal);
+  return { object, path: ancestors(object), local, ...out };
+}

package/trid/render/canvasRenderer.js

@@ -125,7 +125,7 @@ export class CanvasRenderer {
     // For effects
     const camPos = { x: camera.x ?? 0, y: camera.y ?? 0, z: camera.z ?? 0 };
     const time = (performance.now() - this._start) / 1000;
-    const background = this._rgba(ctx, scene.background);
+    const background = this._rgba(ctx, scene.background ?? "transparent");
 
     for (const obj of drawn) {
       const mats = materialsOf(obj);

package/trid/render/draw.js

@@ -2,19 +2,29 @@ import { localToWorld, worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } f
 import { transformPoint } from "../math/matrix.js";
 
 /**
- * Clears the entire canvas with a solid background color.
+ * Clears the entire canvas, then paints it with a background color.
  * This should usually be called once per frame before drawing.
  *
+ * A see-through color (`"transparent"`, or `rgba(...)` with an alpha below 1),
+ * or no color (`null`), lets the page behind the canvas show through.
+ *
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
  * @param {number} w - Canvas width
  * @param {number} h - Canvas height
- * @param {string} color - Background color (CSS color)
+ * @param {string|null} [color] - Background color (CSS color); none: left see-through
  */
 export function clear(ctx, w, h, color) {
+  ctx.clearRect(0, 0, w, h);
+  if (!isVisible(color)) return;
   ctx.fillStyle = color;
   ctx.fillRect(0, 0, w, h);
 }
 
+/** Whether a background color paints anything (not null, empty or "transparent"). */
+function isVisible(color) {
+  return color != null && color !== "" && String(color).trim().toLowerCase() !== "transparent";
+}
+
 /**
  * Draws a square point centered at a given 2D position.
  * Useful for debugging or drawing vertices.

package/trid/render/post.js

@@ -91,7 +91,7 @@ export function runCanvasPost(scene, list, start) {
     canvas,
     rgba: (v) => (typeof v === "string" ? parseColor(ctx, v).map((x, i) => (i < 3 ? x / 255 : x)) : v),
   };
-  frame.background = frame.rgba(scene.background ?? "#000000");
+  frame.background = frame.rgba(scene.background ?? "transparent");
   for (const e of effects) {
     ctx.save();
     try {

package/trid/render/shapes.js

@@ -249,6 +249,9 @@ function sphereWire(radius = 0.35, rings = 10, segments = 16) {
   return { vertices, edges, faces, uvs, faceUVs };
 }
 
+/** Profile points closer to the axis than this are poles (one vertex). */
+const POLE = 1e-9;
+
 /**
  * Spins a profile around the Y axis: vases, bottles, cups, columns, chess
  * pieces. Cylinders, cones and tori are built with it.
@@ -256,6 +259,9 @@ function sphereWire(radius = 0.35, rings = 10, segments = 16) {
  * Walk the profile so the outside is on its right in the (r, y) plane:
  * bottom to top for a vase. Faces are clockwise as seen from outside.
  *
+ * A point on the axis (`r: 0`) is a pole: one vertex, with triangles around
+ * it, like a cone's tip or the closed end of a spinning top.
+ *
  * Texture coordinates: u goes around, v follows the profile's length.
  * Caps map the texture as a disc. Edges are the profile's rings plus one
  * line along the profile per segment.
@@ -292,52 +298,67 @@ export function lathe(profile, { segments = 32, capBottom = false, capTop = fals
   }
   const total = lengths[lengths.length - 1] || 1;
 
-  for (const p of profile) {
-    for (let s = 0; s < segments; s++) {
-      const t = (s / segments) * Math.PI * 2;
-      vertices.push({ x: Math.cos(t) * p.r, y: p.y, z: Math.sin(t) * p.r });
+  // One ring of vertices per profile point, or a single vertex for a pole (on the axis)
+  const pole = profile.map((p) => !(Math.abs(p.r) > POLE));
+  const start = [];
+  for (const [r, p] of profile.entries()) {
+    start.push(vertices.length);
+    if (pole[r]) vertices.push({ x: 0, y: p.y, z: 0 });
+    else {
+      for (let s = 0; s < segments; s++) {
+        const t = (s / segments) * Math.PI * 2;
+        vertices.push({ x: Math.cos(t) * p.r, y: p.y, z: Math.sin(t) * p.r });
+      }
     }
   }
+  const at = (r, s) => (pole[r] ? start[r] : start[r] + (s % segments));
 
   const rows = pts.length - 1;
   for (let r = 0; r < rows; r++) {
-    const a = r * segments;
-    const b = ((r + 1) % profile.length) * segments;
+    const next = (r + 1) % profile.length;
+    if (pole[r] && pole[next]) continue; // along the axis: nothing to draw
     for (let s = 0; s < segments; s++) {
-      const s1 = (s + 1) % segments;
-      faces.push([a + s, b + s, b + s1, a + s1]);
-      const u0 = s / segments, u1 = (s + 1) / segments;
+      const u0 = s / segments, u1 = (s + 1) / segments, um = (u0 + u1) / 2;
       const v0 = lengths[r] / total, v1 = lengths[r + 1] / total;
-      faceUVs.push([uv(u0, v0), uv(u0, v1), uv(u1, v1), uv(u1, v0)]);
+      // Next to a pole, a triangle; its corner there sits in the middle of u
+      if (pole[r]) {
+        faces.push([at(r, s), at(next, s), at(next, s + 1)]);
+        faceUVs.push([uv(um, v0), uv(u0, v1), uv(u1, v1)]);
+      } else if (pole[next]) {
+        faces.push([at(r, s), at(next, s), at(r, s + 1)]);
+        faceUVs.push([uv(u0, v0), uv(um, v1), uv(u1, v0)]);
+      } else {
+        faces.push([at(r, s), at(next, s), at(next, s + 1), at(r, s + 1)]);
+        faceUVs.push([uv(u0, v0), uv(u0, v1), uv(u1, v1), uv(u1, v0)]);
+      }
     }
   }
 
-  // Rings (skipped where the profile touches the axis) and lines along the profile
+  // Rings (none at a pole) and lines along the profile
   profile.forEach((p, r) => {
-    if (p.r > 1e-5) edges.push(Array.from({ length: segments }, (_, s) => r * segments + s));
+    if (!pole[r]) edges.push(Array.from({ length: segments }, (_, s) => at(r, s)));
   });
   for (let s = 0; s < segments; s++) {
-    if (closed && profile.length > 2) edges.push(profile.map((_, r) => r * segments + s));
-    else for (let r = 0; r < profile.length - 1; r++) edges.push([r * segments + s, (r + 1) * segments + s]);
+    if (closed && profile.length > 2) edges.push(profile.map((_, r) => at(r, s)));
+    else for (let r = 0; r < profile.length - 1; r++) if (!(pole[r] && pole[r + 1])) edges.push([at(r, s), at(r + 1, s)]);
   }
 
   const disc = (s) => {
     const t = (s / segments) * Math.PI * 2;
     return uv(0.5 + Math.cos(t) * 0.5, 0.5 + Math.sin(t) * 0.5);
   };
-  if (capBottom && !closed && profile[0].r > 0) {
+  if (capBottom && !closed && !pole[0]) {
     const c = vertices.push({ x: 0, y: profile[0].y, z: 0 }) - 1;
     for (let s = 0; s < segments; s++) {
-      faces.push([c, s, (s + 1) % segments]);
+      faces.push([c, at(0, s), at(0, s + 1)]);
       faceUVs.push([uv(0.5, 0.5), disc(s), disc(s + 1)]);
     }
   }
   const last = profile.length - 1;
-  if (capTop && !closed && profile[last].r > 0) {
+  if (capTop && !closed && !pole[last]) {
     const c = vertices.push({ x: 0, y: profile[last].y, z: 0 }) - 1;
-    const a = last * segments;
     for (let s = 0; s < segments; s++) {
-      faces.push([c, a + (s + 1) % segments, a + s]);
+      faces.push([c, at(last, s + 1), at(last, s)]);
       faceUVs.push([uv(0.5, 0.5), disc(s + 1), disc(s)]);
     }
   }
@@ -350,11 +371,9 @@ function cylinder(r = 0.3, h = 0.8, segments = 32) {
   return lathe([{ r, y: -h / 2 }, { r, y: h / 2 }], { segments, capBottom: true, capTop: true });
 }
 
-/** A cone along Y with its tip up, or a tapered cylinder when `rTop` > 0. */
+/** A cone along Y with its tip up (a single point, so it's closed), or a tapered cylinder when `rTop` > 0. */
 function cone(r = 0.35, h = 0.8, segments = 32, rTop = 0) {
-  // A tiny top ring keeps the tip's faces non-degenerate for UVs and normals
-  const profile = [{ r, y: -h / 2 }, { r: rTop > 0 ? rTop : 1e-6, y: h / 2 }];
-  return lathe(profile, { segments, capBottom: true, capTop: rTop > 0 });
+  return lathe([{ r, y: -h / 2 }, { r: rTop > 0 ? rTop : 0, y: h / 2 }], { segments, capBottom: true, capTop: rTop > 0 });
 }
 
 /** A ring in the XZ plane: `R` from the center to the middle of the tube. */

package/trid/render/webglRenderer.js

@@ -343,7 +343,7 @@ export class WebGLRenderer {
     // Post effects: the ones with GLSL run here, canvas-only ones after the copy
     const post = activePost(scene.post);
     const gpuPost = post.filter((e) => postPasses(e).length);
-    const background = this._color(ctx, scene.background);
+    const background = this._color(ctx, scene.background ?? "transparent");
     if (gpuPost.length) {
       // Into a texture, on the scene's background so effects see the whole picture
       gl.bindFramebuffer(gl.FRAMEBUFFER, this._sceneTarget(w, h));

package/trid/scene.js

@@ -37,7 +37,7 @@ export class Scene {
    * @param {Object} [opts]
    * @param {number} [opts.width] - Sets canvas.width (keeps the current one if omitted)
    * @param {number} [opts.height] - Sets canvas.height (keeps the current one if omitted)
-   * @param {string} [opts.background="#141414"] - Clear color
+   * @param {string|null} [opts.background="#141414"] - Clear color; "transparent" or null: see-through, the page shows behind
    * @param {string} [opts.color="#ffffff"] - Default wireframe color
    * @param {number} [opts.lineWidth=3] - Default wireframe width
    * @param {import("./math/transform.js").Camera} [opts.camera={ z: -1 }] - Camera