trid3d 0.5.0 → 0.7.0

package/README.md

@@ -4,31 +4,31 @@
 
 <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).
+- **Lights and shadows** — ambient, directional and point lights, with colors and intensities, as many as you need (up to 8 at once besides ambient). A directional light can cast soft shadows (a shadow map with WebGL, ground shadows on the canvas).
 - **Textures** — images, canvases or videos on faces, with texture coordinates from built-in shapes and OBJ files, or made from the shape (planar, box, sphere and cylinder mapping). Repeat, offset and rotate them, or give each face its own material. Or paint one in code: wood, marble, bricks and more, all seamless.
 - **Effects** — stack shader effects like toon, rim and edge glow, gradients and fog on a material, or write your own in GLSL.
-- **Post effects** — bloom, vignette, color grading and film grain over the whole picture, or your own full-screen shaders (several passes if needed).
+- **Post effects** — bloom, vignette, color grading, film grain and cartoon outlines over the whole picture, or your own full-screen shaders (several passes if needed, reading the scene's depth and normals if wanted).
 - **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.
-- **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.
+- **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 selection outline, 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.
 
 ## Install
@@ -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.7/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,23 @@ 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, shadows, 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.6 to 0.7
+
+Nothing changes for existing scenes: shadows, outlines and the selection outline are all off until asked for. Only names Trid now uses itself could clash with yours:
+
+- In **post effect GLSL**, `Frame` has two more fields (`f.near`, `f.far`), and the uniforms `uNear`, `uFar`, `uGeometry`, `uGeoNear` and `uGeoRange` are taken. A post effect declaring its own uniform with one of those names needs to rename it.
+- In **material effect GLSL**, the functions `tridShadow` and `tridShadowDepth` and the uniforms starting with `uShadow` (plus `uReceive`) are taken. Effect uniforms are renamed by Trid, so only helper functions with those names would clash.
+
+### 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.
@@ -135,7 +157,8 @@ Uses Node's built-in test runner (Node 21+), so there's nothing to install. The
 
 Roughly in order:
 
-- **More import and export formats** — STL; basic glTF later
-- **More tools** — a selection outline
-- **More post effects** — outlines (from depth), antialiasing (FXAA)
+- **More shadows** — point lights casting shadows, and several lights at once
+- **Combining shapes** — union, subtract and intersect meshes (CSG)
 - **More tests** — the canvas renderer's drawing and the remaining math functions
+- **More import and export formats** — STL; basic glTF later
+- **More post effects** — antialiasing (FXAA)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.5.0",
+  "version": "0.7.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;
@@ -164,6 +164,10 @@ export interface SceneObjectInput {
   hoverable?: boolean;
   /** Set to false so `pick` / `pickHit` never find this object or its children (helpers like a grid) */
   pickable?: boolean;
+  /** Set to false so this object (and its children) casts no shadow */
+  castShadow?: boolean;
+  /** Set to false so no shadow falls on this object (and its children) */
+  receiveShadow?: boolean;
 }
 
 /**
@@ -192,8 +196,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 +225,7 @@ export class Scene {
 
   canvas: HTMLCanvasElement;
   ctx: CanvasRenderingContext2D;
-  background: string;
+  background: string | null;
   color: string;
   lineWidth: number;
   camera: Camera;
@@ -459,8 +463,35 @@ export interface DirectionalLight {
   color?: string;
   intensity?: number;
   enabled?: boolean;
+  /** Cast shadows (the first directional light with it does): true, or settings */
+  shadows?: boolean | ShadowOptions;
 }
 
+/** Shadow settings of a directional light. */
+export interface ShadowOptions {
+  /** Shadow map width in pixels (WebGL, default 2048). Bigger: sharper, slower */
+  size?: number;
+  /** Edge blur, in shadow map pixels (default 1.5; 0 = sharp) */
+  softness?: number;
+  /** Raise if lit surfaces get speckles; too high and shadows come loose (default 1) */
+  bias?: number;
+  /** Floor height for the canvas renderer's ground shadows (default: found) */
+  ground?: number;
+}
+
+/** Settings used for `shadows: true`. */
+export const DEFAULT_SHADOWS: Readonly<Required<Omit<ShadowOptions, "ground">> & { ground: null }>;
+/** A light's shadow settings, defaults filled in. */
+export function shadowOptions(value: boolean | ShadowOptions): Required<Omit<ShadowOptions, "ground">> & { ground: number | null };
+/** False when the object or one of its groups sets `key` to false. */
+export function shadowFlag(obj: SceneObject, key: "castShadow" | "receiveShadow"): boolean;
+/** The shadow map's box around casting objects (`matrix`: world → -1..1, column-major). */
+export function shadowFrame(casters: SceneObject[], dir: Vec3): { matrix: Float32Array; radius: number } | null;
+/** The floor height for ground shadows: where receivers have the most area of upward flat faces. */
+export function findGround(receivers: SceneObject[]): number | null;
+/** A world polygon's part above `ground`, flattened onto it along the light (`dir`: where it comes from). */
+export function flattenOnGround(pts: Vec3[], dir: Vec3, ground: number): Vec3[];
+
 /** Light from a point, like a bulb. */
 export interface PointLight {
   type: "point";
@@ -490,6 +521,8 @@ export interface SceneLights {
   lights: { point: boolean; dir: Vec3 | null; pos: Vec3 | null; color: [number, number, number]; range: number }[];
   /** Unit direction of the first directional light */
   mainDir: Vec3;
+  /** The light casting shadows (`index` in `lights`) and its settings, or null */
+  shadow: ({ index: number; dir: Vec3 } & Required<Omit<ShadowOptions, "ground">> & { ground: number | null }) | null;
 }
 
 /** A scene's lights, colors parsed and multiplied by intensity, directions unit length. */
@@ -704,6 +737,10 @@ export interface PostFrame {
   canvas: HTMLCanvasElement;
   /** Turns a uniform value (CSS color, array) into RGBA 0..1 */
   rgba(value: UniformValue): RGBA;
+  /** The camera's near distance */
+  near: number;
+  /** The camera's far distance */
+  far: number;
 }
 
 /** One pass of a post effect. */
@@ -727,8 +764,46 @@ export interface PostEffect<U extends Record<string, UniformValue> = Record<stri
   uniforms?: U;
   /** Set to false to turn it off without removing it */
   enabled?: boolean;
+  /** Also read the scene's depth and normals (WebGL): GLSL gets `depthAt(uv)`, `normalAt(uv)` and `maskAt(uv)` */
+  geometry?: boolean;
+  /** With `geometry`: the objects `maskAt` is 1 on (children included). Default: all */
+  objects?: SceneObject[];
+  /** Canvas renderer: draw the meshes' silhouettes and creases as lines, using `uColor`, `uWidth` and `uCreaseAngle` */
+  contour?: boolean;
 }
 
+/** Cartoon-style lines around objects and along their sharp creases. */
+export function outline(opts?: {
+  color?: string;
+  width?: number;
+  /** Degrees the surface must turn for an inner line (default 40); false = outer lines only */
+  creases?: number | false;
+  /** How readily a jump in distance makes a line (default 1; 0 = none) */
+  depth?: number;
+  /** Only outline these objects (and their children) */
+  objects?: SceneObject[];
+}): PostEffect<{
+  uColor: string;
+  uWidth: number;
+  uCreaseAngle: number;
+  uDepth: number;
+}>;
+
+/** Crease angle `outline()` uses by default, in degrees (40). */
+export const DEFAULT_OUTLINE_CREASE: number;
+
+/** Whether a post effect reads the scene's depth and normals (`geometry: true`, with GLSL). */
+export function wantsGeometry(effect: PostEffect): boolean;
+
+/** The objects an effect's `objects` list covers, children included (null: all). */
+export function maskedObjects(effect: PostEffect): Set<SceneObject> | null;
+
+/** GLSL helpers `depthAt`, `normalAt` and `maskAt`, for effects with `geometry: true`. */
+export const GEOMETRY_GLSL: string;
+
+/** Each edge of a mesh's faces once, with the faces on its sides (`f2` = -1 on an open border). */
+export function meshEdges(mesh: Mesh): { a: number; b: number; f1: number; f2: number }[];
+
 /** Darkens the corners of the picture. */
 export function vignette(opts?: { strength?: number; radius?: number; softness?: number; color?: string }): PostEffect<{
   uStrength: number;
@@ -1323,6 +1398,36 @@ export interface TransformGizmoOptions {
   onChange?: (op: TransformOp, targets: SceneObject[]) => void;
   /** On release: the whole operation */
   onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** Outline the targets, under the handles (default false). Options: see `SelectionOutline` */
+  outline?: boolean | Omit<SelectionOutlineOptions, "targets">;
+}
+
+export interface SelectionOutlineOptions {
+  /** Objects to outline, or a function asked every frame (default none) */
+  targets?: SceneObject[] | (() => SceneObject[]);
+  /** Line color (default "#ffa64d") */
+  color?: string;
+  /** Line width in CSS pixels (default 2) */
+  width?: number;
+  /** Opacity of the outline where the objects are hidden behind others (default 0.35; 0 = not shown) */
+  hidden?: number;
+}
+
+/**
+ * A colored line around selected objects, like a 3D editor's selection. Parts hidden
+ * behind other objects get a faint outline. Add it before tools that draw handles.
+ */
+export class SelectionOutline implements Tool {
+  constructor(opts?: SelectionOutlineOptions);
+  targets: SceneObject[] | (() => SceneObject[]);
+  color: string;
+  width: number;
+  hidden: number;
+  /** Hide the outline without removing the tool. */
+  visible: boolean;
+  /** The objects outlined this frame. */
+  current(): SceneObject[];
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
 }
 
 /**
@@ -1352,6 +1457,8 @@ export class TransformGizmo implements Tool {
   visible: boolean;
   /** True while a handle is being dragged. */
   readonly dragging: boolean;
+  /** The outline around the targets (`outline` option), or null. */
+  outline: SelectionOutline | null;
   /** The pivot in world space, or null when there are no targets. */
   center(): Vec3 | null;
   draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
@@ -1426,8 +1533,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 +1574,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 +2058,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

@@ -19,11 +19,12 @@ export { gridMesh, gridHelper } from "./render/grid.js";
 export { cloneMesh, transformMesh, displaceMesh, mergeMeshes, meshBounds } from "./render/meshUtils.js";
 
 // Renderers
-export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./render/canvasRenderer.js";
+export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf, meshEdges } from "./render/canvasRenderer.js";
 export { WebGLRenderer, DEFAULT_FAR } from "./render/webglRenderer.js";
 
 // Lights
 export { defaultLights, sceneLights, lightAt, lightLevels, rangeFade, MAX_LIGHTS } from "./render/lights.js";
+export { shadowOptions, shadowFlag, shadowFrame, findGround, flattenOnGround, DEFAULT_SHADOWS } from "./render/shadows.js";
 
 // Effects
 export {
@@ -32,7 +33,10 @@ export {
 } from "./render/effects.js";
 
 // Post effects
-export { vignette, bloom, grade, grain, postPasses, activePost, runCanvasPost, FRAME_GLSL } from "./render/post.js";
+export {
+  vignette, bloom, grade, grain, outline, postPasses, activePost, runCanvasPost, wantsGeometry, maskedObjects,
+  FRAME_GLSL, GEOMETRY_GLSL, DEFAULT_OUTLINE_CREASE,
+} from "./render/post.js";
 
 // Procedural textures
 export { makeTexture, texturePixels, colorBytes, TEXTURE_STYLES } from "./render/proceduralTextures.js";
@@ -56,7 +60,7 @@ export { screenshot, record, download } from "./export/capture.js";
 // Tools
 export {
   OrbitCamera, FlyCamera, DragObject, HoverHighlight, FpsMeter, ObjUploader,
-  ViewGizmo, TransformGizmo,
+  ViewGizmo, TransformGizmo, SelectionOutline,
   ToolManager, pick, pickHit, isPickable, screenBounds, worldPerPixel,
 } from "./tools/index.js";
 
@@ -91,3 +95,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;