phoria2 1.1.0 → 1.3.0

package/dist/types/scene/drawables.d.ts

@@ -4,7 +4,7 @@ import type { Geometry } from '../geometry/Geometry.js';
 import type { Material, MaterialOptions } from '../material/Material.js';
 import type { GeometryOptions } from '../geometry/Geometry.js';
 import type { NodeOptions } from './Node.js';
-import type { ColorInput, Vec3Input } from '../types.js';
+import type { ColorInput, QuatInput, Vec3Input } from '../types.js';
 export type DrawableOptions = NodeOptions & {
     geometry: Geometry | GeometryOptions;
     material?: Material | MaterialOptions;
@@ -52,6 +52,11 @@ export type LabelPlacement = {
      * the edge and up or down (default null: by its point)
      */
     edge?: 'left' | 'right' | null;
+    /**
+     * show the label only when zoomed in this far: at least this many CSS pixels to
+     * one world unit, at the label's point - details that appear as you come closer (default 0: always)
+     */
+    minScale?: number;
 };
 export type LabelPlace = 'center' | 'above' | 'below' | 'left' | 'right';
 export type InstanceLabels = Omit<LabelPlacement, 'priority'> & {
@@ -64,7 +69,7 @@ export type InstanceLabels = Omit<LabelPlacement, 'priority'> & {
 /** @import { Material, MaterialOptions } from '../material/Material.js' */
 /** @import { GeometryOptions } from '../geometry/Geometry.js' */
 /** @import { NodeOptions } from './Node.js' */
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 /**
  * @typedef {NodeOptions & {
  *   geometry: Geometry | GeometryOptions,
@@ -95,10 +100,13 @@ export type InstanceLabels = Omit<LabelPlacement, 'priority'> & {
  * @property {'left' | 'right' | null} [edge] set the label at the view's left or right edge, level with its
  *   point - callouts in a column down the side of a diagram, with leader: true. offset then moves it in from
  *   the edge and up or down (default null: by its point)
+ * @property {number} [minScale] show the label only when zoomed in this far: at least this many CSS pixels to
+ *   one world unit, at the label's point - details that appear as you come closer (default 0: always)
  */
 /** @typedef {'center' | 'above' | 'below' | 'left' | 'right'} LabelPlace */
 /**
- * One label per instance or point, from its row of data.
+ * One label per instance or point, from its row of data - or a list of these, for several each (a symbol
+ * always, its details when zoomed in).
  * @typedef {Omit<LabelPlacement, 'priority'> & {
  *   text: (datum: any, index: number) => string | number | null | undefined,
  *   priority?: number | ((datum: any, index: number) => number),
@@ -109,10 +117,12 @@ export type InstanceLabels = Omit<LabelPlacement, 'priority'> & {
  * label the point itself.
  */
 export declare const LABEL_PLACES: LabelPlace[];
-/** @param {string} owner @param {unknown} v @returns {(InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }) | null} */
-declare function instanceLabels(owner: string, v: unknown): (InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & {
+export type CheckedLabels = InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & {
     priority: number | ((datum: any, index: number) => number);
-}) | null;
+};
+/** @typedef {InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }} CheckedLabels */
+/** @param {string} owner @param {unknown} v @returns {CheckedLabels | CheckedLabels[] | null} */
+declare function instanceLabels(owner: string, v: unknown): CheckedLabels | CheckedLabels[] | null;
 /** Base for nodes with geometry and a material: Mesh, InstancedMesh, Points and Lines. */
 export declare class Drawable extends Node {
     #private;
@@ -157,7 +167,10 @@ export type InstanceOptions = {
      * Euler angles in radians, XYZ order
      */
     rotation?: Vec3Input | Euler;
-    quaternion?: ArrayLike<number>;
+    /**
+     * [x, y, z, w] or { x, y, z, w } - as physics engines give them
+     */
+    quaternion?: QuatInput;
     scale?: Vec3Input | number;
     /**
      * multiplies the material colour
@@ -166,7 +179,8 @@ export type InstanceOptions = {
 };
 /**
  * Many copies of one geometry and material, drawn together. Set each copy with setInstance().
- * Picking reports which instance was hit.
+ * Picking reports which instance was hit. An instance scaled to 0 is hidden - it draws nothing, and
+ * framing, culling, shadows and labels leave it out - so a pool of instances can keep spares.
  */
 export declare class InstancedMesh extends Mesh {
     #private;
@@ -178,11 +192,11 @@ export declare class InstancedMesh extends Mesh {
     instanceMatrices: Float32Array;
     /** Linear rgb per instance, or null until a colour is set. @type {Float32Array | null} */
     instanceColors: Float32Array | null;
-    /** A label per instance, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+    /** A label per instance from its row of data - or a list of them, several per instance. @type {ReturnType<typeof instanceLabels>} */
     labels: ReturnType<typeof instanceLabels>;
     /**
      * @param {DrawableOptions & { count?: number, instances?: InstanceOptions[], instanceMatrices?: ArrayLike<number>,
-     *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | null }} options count defaults to the number
+     *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | InstanceLabels[] | null }} options count defaults to the number
      *   of instances or rows of data; instanceMatrices/instanceColors are raw data, as toJSON() writes
      */
     constructor(options: DrawableOptions & {
@@ -190,7 +204,7 @@ export declare class InstancedMesh extends Mesh {
         instances?: InstanceOptions[];
         instanceMatrices?: ArrayLike<number>;
         instanceColors?: ArrayLike<number>;
-        labels?: InstanceLabels | null;
+        labels?: InstanceLabels | InstanceLabels[] | null;
     });
     /**
      * Set an instance's transform and optional colour. Unset transform parts default to identity.
@@ -222,21 +236,42 @@ export declare class InstancedMesh extends Mesh {
 export declare class Points extends Drawable {
     static type: string;
     static get OPTIONS(): string[];
-    /** A label per point, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+    /** A label per point from its row of data - or a list of them, several per point. @type {ReturnType<typeof instanceLabels>} */
     labels: ReturnType<typeof instanceLabels>;
-    /** @param {DrawableOptions & { labels?: InstanceLabels | null }} options */
+    /**
+     * Draw the points back to front, furthest first, each frame - for soft points that cover what is
+     * behind them (smoke, with blending 'normal'), which then layer the right way round. Drawn as squares.
+     */
+    sort: boolean;
+    /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null, sort?: boolean }} options */
     constructor(options: DrawableOptions & {
-        labels?: InstanceLabels | null;
+        labels?: InstanceLabels | InstanceLabels[] | null;
+        sort?: boolean;
     });
     /** @returns {'points'} */
     get drawMode(): 'points';
 }
+export type LinesOptions = DrawableOptions & {
+    arrows?: 'none' | 'start' | 'end' | 'both';
+    arrowSize?: number;
+};
+/**
+ * @typedef {DrawableOptions & { arrows?: 'none' | 'start' | 'end' | 'both', arrowSize?: number }} LinesOptions
+ */
 /**
  * Line segments: indices (or consecutive vertices) in pairs. Width is in pixels and works on
- * every platform. edges(geometry) makes a wireframe of any geometry.
+ * every platform. edges(geometry) makes a wireframe of any geometry. Segments each starting where
+ * the one before ended make a chain - a polyline - which dashes run on along and arrowheads finish.
  */
 export declare class Lines extends Drawable {
     static type: string;
+    static get OPTIONS(): string[];
+    /** Arrowheads at the ends of each chain: at its 'start', its 'end', 'both' or 'none'. @type {'none' | 'start' | 'end' | 'both'} */
+    arrows: 'none' | 'start' | 'end' | 'both';
+    /** Arrowhead length in pixels; 0 sizes them from the material's width. */
+    arrowSize: number;
+    /** @param {LinesOptions} options */
+    constructor(options: LinesOptions);
     /** @returns {'lines'} */
     get drawMode(): 'lines';
 }
@@ -261,6 +296,8 @@ export declare class Label extends Node {
         pointer: string;
         anchor: string;
         zIndex: string;
+        minZoom: string;
+        lod: string;
         collision: string;
     };
     text: string;
@@ -280,6 +317,8 @@ export declare class Label extends Node {
     leader: boolean;
     /** Set at the view's left or right edge, level with its point, or null for by its point. @type {'left' | 'right' | null} */
     edge: 'left' | 'right' | null;
+    /** Shown only when zoomed in this far: CSS pixels to one world unit at its point; 0 for always. */
+    minScale: number;
     /** @param {LabelOptions} options */
     constructor(options: LabelOptions);
 }

package/dist/types/scene/lights.d.ts

@@ -1,8 +1,9 @@
 import { Color } from '../value/Color.js';
 import { Vec3 } from '../value/Vec3.js';
+import { Box3 } from '../value/Box3.js';
 import { Node } from './Node.js';
 import type { NodeOptions } from './Node.js';
-import type { ColorInput, Vec3Input } from '../types.js';
+import type { Box3Input, ColorInput, Vec3Input } from '../types.js';
 export type LightOptions = NodeOptions & {
     color?: ColorInput;
     intensity?: number;
@@ -87,13 +88,26 @@ declare class AimedLight extends Light {
 }
 /** Parallel light from far away, like the sun. Position only matters for its shadow. */
 export declare class DirectionalLight extends AimedLight {
+    #private;
     static type: string;
     static get OPTIONS(): string[];
     castShadow: boolean;
-    /** @param {AimedLightOptions & { castShadow?: boolean }} [options] */
+    /** @param {AimedLightOptions & { castShadow?: boolean, shadowBounds?: Box3Input | null }} [options] */
     constructor(options?: AimedLightOptions & {
         castShadow?: boolean;
+        shadowBounds?: Box3Input | null;
     });
+    /**
+     * The part of the world, in world units, that has shadows - or null (the default) to follow
+     * whatever casts them. The shadow map is fitted to what casts every frame, so one caster flung far
+     * off spreads its texels over everything and every shadow blurs; set the area where things happen
+     * and its shadows stay sharp. Casters outside it still shadow it, from wherever they stand.
+     * Assigning copies.
+     * @returns {Box3 | null}
+     */
+    get shadowBounds(): Box3 | null;
+    /** @param {Box3Input | null} v */
+    set shadowBounds(v: Box3Input | null);
 }
 /** Light from a point in all directions, falling off with the square of the distance. */
 export declare class PointLight extends Light {

package/dist/types/shadow.d.ts

@@ -25,9 +25,10 @@ export type ShadowFit = {
  * @param {Box3[]} casters world bounds
  * @param {Box3[]} receivers world bounds
  * @param {number} [size] map size in texels
+ * @param {Box3 | null} [area] the light's shadowBounds: the map covers this across, whatever casts
  * @returns {ShadowFit | null}
  */
-export declare function fitShadow(direction: ArrayLike<number>, casters: Box3[], receivers: Box3[], size?: number): ShadowFit | null;
+export declare function fitShadow(direction: ArrayLike<number>, casters: Box3[], receivers: Box3[], size?: number, area?: Box3 | null): ShadowFit | null;
 /** Spot shadows' map: four tiles of half its size, one a light. */
 export declare const SPOT_ATLAS_SIZE = 2048;
 export declare const SPOT_TILES = 4;

package/dist/types/types.d.ts

@@ -7,12 +7,26 @@ export type XYZ = {
     z: number;
 };
 export type Vec3Input = Vec3Like | XYZ;
+export type XYZW = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+export type QuatInput = ArrayLike<number> | XYZW;
+export type Box3Input = import('./value/Box3.js').Box3 | {
+    min: Vec3Input;
+    max: Vec3Input;
+};
 export type ColorInput = string | number | number[] | Float32Array | import('./value/Color.js').Color;
 /** @typedef {Float32Array | number[]} Vec2Like */
 /** @typedef {Float32Array | number[]} Vec3Like */
 /** @typedef {Float32Array | number[]} Vec4Like */
 /** A position or direction as an object literal. @typedef {{ x: number, y: number, z: number }} XYZ */
 /** A vector as accepted on input: [x, y, z], { x, y, z } or a Vec3. @typedef {Vec3Like | XYZ} Vec3Input */
+/** A quaternion as an object literal - as physics engines such as Rapier return them. @typedef {{ x: number, y: number, z: number, w: number }} XYZW */
+/** A rotation quaternion as accepted on input: [x, y, z, w], { x, y, z, w } or a Quat. @typedef {ArrayLike<number> | XYZW} QuatInput */
+/** A box as accepted on input: a Box3, or its lowest and highest corners. @typedef {import('./value/Box3.js').Box3 | { min: Vec3Input, max: Vec3Input }} Box3Input */
 /**
  * A colour as accepted on input, in sRGB: '#ff8800', '#f80', 0xff8800, 'rgb(255 136 0)',
  * 'hsl(32 100% 50%)', a CSS colour name, or [r, g, b] with components 0-1.

package/dist/types/value/Color.d.ts

@@ -1,8 +1,4 @@
 import type { ColorInput } from '../types.js';
-/**
- * An RGB colour. Input is sRGB, as everywhere in phoria2; the components are stored **linear**,
- * ready for lighting maths. `toJSON()` gives sRGB '#rrggbb' back.
- */
 export declare class Color extends Float32Array {
     #private;
     0: any;

package/dist/types/value/Quat.d.ts

@@ -1,3 +1,5 @@
+import type { QuatInput } from '../types.js';
+/** @import { QuatInput } from '../types.js' */
 /**
  * A rotation quaternion [x, y, z, w]: a Float32Array(4) with accessors and chainable methods.
  * A node's quaternion and its Euler `rotation` keep each other in sync through these setters;
@@ -44,8 +46,8 @@ export declare class Quat extends Float32Array {
      */
     /** @param {number | ArrayLike<number>} x @param {number} [y] @param {number} [z] @param {number} [w] */
     set(array: ArrayLike<number>, offset?: number): void;
-    /** @param {ArrayLike<number>} q [x, y, z, w] @param {string} [owner] @returns {this} */
-    copy(q: ArrayLike<number>, owner?: string): this;
+    /** @param {QuatInput} q [x, y, z, w], or { x, y, z, w } as physics engines give them @param {string} [owner] @returns {this} */
+    copy(q: QuatInput, owner?: string): this;
     /** @returns {Quat} */
     clone(): Quat;
     /** @returns {this} */

package/dist/types/webgl/resources.d.ts

@@ -101,8 +101,8 @@ export declare class Resources {
         count: number;
     } | null, withTangents?: boolean): number;
     /**
-     * Vertex array for Lines: one instance per segment with its two endpoints (and colours),
-     * expanded to a screen-space quad in the vertex shader.
+     * Vertex array for Lines: one instance per segment with its two endpoints (and colours) and where
+     * it is along its chain, expanded to a screen-space quad - and arrowheads - in the vertex shader.
      * @param {Geometry} geometry
      * @returns {MeshBuffers}
      */
@@ -119,6 +119,16 @@ export declare class Resources {
      * @param {object} owner @param {Scene} scene
      */
     release(owner: object, scene: Scene): void;
+    /**
+     * Vertex array for points drawn as squares: one instance a point - its position, colour, size,
+     * opacity, angle and index - over the corner strip lines use. Given a model-view matrix, the points
+     * go back to front (furthest first) - re-sorted every call, as the camera may have moved; without
+     * one, in their own order; with undefined, in whatever order they were last sent (picking, which
+     * reads each point's index and doesn't mind).
+     * @param {Geometry} geometry @param {ArrayLike<number> | null} [modelView]
+     * @returns {MeshBuffers}
+     */
+    sprites(geometry: Geometry, modelView?: ArrayLike<number> | null): MeshBuffers;
     /** Forget everything - after a lost context, when every GL object is already gone. */
     reset(): void;
 }

package/dist/types/webgl/shaders.d.ts

@@ -8,11 +8,16 @@ export declare const ATTRIBUTES: {
     instanceColor: number;
     tangent: number;
     uv2: number;
+    pointSize: number;
+    pointOpacity: number;
+    pointAngle: number;
+    pointIndex: number;
     segmentStart: number;
     segmentEnd: number;
     segmentColorStart: number;
     segmentColorEnd: number;
     corner: number;
+    segmentInfo: number;
 };
 export declare const CLIP = "\n#ifdef CLIP\nuniform vec4 uClipPlane; // world space, unit normal: cut away where dot(n, p) + d > 0\nvoid clipAway(vec3 p) {\n  if (dot(uClipPlane.xyz, p) + uClipPlane.w > 0.0) discard;\n}\n#else\nvoid clipAway(vec3 p) {}\n#endif\n";
 export declare const FOG = "\n#ifdef FOG\nuniform vec3 uFogColor;   // linear\nuniform vec2 uFogRange;   // linear fog: near, far\nuniform float uFogDensity; // exponential fog\nin float vFogDepth;\nvec3 fogged(vec3 c) {\n#ifdef FOG_LINEAR\n  float f = clamp((vFogDepth - uFogRange.x) / max(uFogRange.y - uFogRange.x, 1e-4), 0.0, 1.0);\n#else\n  float d = uFogDensity * vFogDepth;\n  float f = 1.0 - exp(-d * d);\n#endif\n#ifdef FOG_ADD\n  return c * (1.0 - f);\n#elif defined(FOG_MULTIPLY)\n  // a filter in the fog fades to white, which leaves what is behind it as it was\n  return mix(c, vec3(1.0), f);\n#else\n  return mix(c, uFogColor, f);\n#endif\n}\n#else\nvec3 fogged(vec3 c) { return c; }\n#endif\n";
@@ -22,8 +27,8 @@ export declare const EQUIRECT = "\nvec2 equirectUv(vec3 d) {\n  return vec2(atan
 export declare const FULLSCREEN_VERTEX = "\nout vec2 vUv;\nvoid main() {\n  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n  vUv = p;\n  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
 export declare const TONE_MAP = "\nuniform float uExposure;\nuniform int uToneMapping;    // 0 none, 1 aces, 2 neutral\n\nvec3 toneMap(vec3 c) {\n  c *= uExposure;\n  if (uToneMapping == 1) {\n    // ACES filmic, Narkowicz's fit\n    c = clamp((c * (2.51 * c + 0.03)) / (c * (2.43 * c + 0.59) + 0.14), 0.0, 1.0);\n  } else if (uToneMapping == 2) {\n    // Khronos PBR Neutral\n    float x = min(c.r, min(c.g, c.b));\n    float offset = x < 0.08 ? x - 6.25 * x * x : 0.04;\n    c -= offset;\n    float peak = max(c.r, max(c.g, c.b));\n    if (peak > 0.8) {\n      float d = 0.2;\n      float newPeak = 1.0 - d * d / (peak + d - 0.8);\n      c *= newPeak / peak;\n      float g = 1.0 - 1.0 / (0.15 * (peak - newPeak) + 1.0);\n      c = mix(c, vec3(newPeak), g);\n    }\n  }\n  return c;\n}\n";
 export declare const MESH_VERTEX = "\nlayout(location = 0) in vec3 position;\nlayout(location = 1) in vec3 normal;\nlayout(location = 2) in vec2 uv;\nlayout(location = 3) in vec3 color;\n#ifdef INSTANCED\nlayout(location = 4) in mat4 instanceMatrix;\nlayout(location = 8) in vec3 instanceColor;\n#endif\n#ifdef ANISOTROPY\nlayout(location = 9) in vec4 tangent;\nout vec4 vTangent;\n#endif\n#ifdef UV2\nlayout(location = 10) in vec2 uv2;\nout vec2 vUv2;\n#endif\n\nuniform mat4 uModel;\nuniform mat3 uNormalMatrix;\nuniform mat4 uViewProjection;\nuniform int uHighlightIndex; // -2 none, -1 the whole node, otherwise the instance\n#ifdef FOG\nuniform mat4 uView;\nout float vFogDepth;\n#endif\n\nout vec3 vWorldPosition;\nout vec3 vNormal;\nout vec2 vUv;\nout vec3 vColor;\nflat out float vHighlight;\n#ifdef TRIPLANAR\n// the mesh's own space, so projected maps stay on it as it moves; and how its normals turn into the world\nout vec3 vObjectPosition;\nout vec3 vObjectNormal;\nout mat3 vObjectToWorld;\n#endif\n#ifdef PICK\nflat out uint vPickElement; // which instance, point or segment, for GPU picking\n#endif\n\n\nvec3 srgbToLinear(vec3 c) {\n  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n}\nvec3 linearToSrgb(vec3 c) {\n  c = clamp(c, 0.0, 1.0);\n  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n}\n\n\n// Matrices times vectors only - a matrix times a matrix per vertex is four times the work, and\n// with 100,000 instances the vertex stage is most of the frame.\nvoid main() {\n  vColor = vec3(1.0);\n  vHighlight = uHighlightIndex == -1 ? 1.0 : 0.0;\n#ifdef INSTANCED\n  vec4 local = instanceMatrix * vec4(position, 1.0);\n  // the instance's normal matrix as its cofactor: the inverse transpose up to scale, from three\n  // cross products, flipped back for mirroring transforms\n  mat3 m = mat3(instanceMatrix);\n  mat3 instanceNormal = mat3(cross(m[1], m[2]), cross(m[2], m[0]), cross(m[0], m[1])) * sign(dot(m[0], cross(m[1], m[2])));\n  vec3 n = instanceNormal * normal;\n  vColor *= instanceColor;\n  if (gl_InstanceID == uHighlightIndex) vHighlight = 1.0;\n#else\n  vec4 local = vec4(position, 1.0);\n  vec3 n = normal;\n#endif\n#ifdef VERTEX_COLORS\n  vColor *= srgbToLinear(color);\n#endif\n  vec4 world = uModel * local;\n  vWorldPosition = world.xyz;\n  vNormal = uNormalMatrix * n;\n  vUv = uv;\n#ifdef UV2\n  vUv2 = uv2;\n#endif\n#ifdef ANISOTROPY\n  // a direction along the surface, so it turns as the model does\n#ifdef INSTANCED\n  vTangent = vec4(mat3(uModel) * (m * tangent.xyz), tangent.w);\n#else\n  vTangent = vec4(mat3(uModel) * tangent.xyz, tangent.w);\n#endif\n#endif\n#ifdef TRIPLANAR\n  vObjectPosition = position;\n  vObjectNormal = normal;\n#ifdef INSTANCED\n  vObjectToWorld = uNormalMatrix * instanceNormal;\n#else\n  vObjectToWorld = uNormalMatrix;\n#endif\n#endif\n  gl_Position = uViewProjection * world;\n#ifdef FOG\n  vFogDepth = -(uView * world).z;\n#endif\n#ifdef PICK\n  vPickElement = uint(gl_InstanceID);\n#endif\n}\n";
-export declare const POINTS_VERTEX = "\nlayout(location = 0) in vec3 position;\nlayout(location = 3) in vec3 color;\n\nuniform mat4 uModel;\nuniform mat4 uView;\nuniform mat4 uProjection;\nuniform float uSize;        // pixels (with the pixel ratio applied), or world units when attenuated\nuniform float uScale;       // projection focal term x half the buffer height: world size -> pixels at depth 1\nuniform int uHighlightIndex; // -2 none, -1 every point, otherwise the point\n\nout vec3 vColor;\nflat out float vHighlight;\n#ifdef PICK\nflat out uint vPickElement; // which instance, point or segment, for GPU picking\n#endif\n#ifdef FOG\nout float vFogDepth;\n#endif\n\n\nvec3 srgbToLinear(vec3 c) {\n  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n}\nvec3 linearToSrgb(vec3 c) {\n  c = clamp(c, 0.0, 1.0);\n  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n}\n\n\nvoid main() {\n  vec4 viewPosition = uView * (uModel * vec4(position, 1.0));\n  gl_Position = uProjection * viewPosition;\n#ifdef FOG\n  vFogDepth = -viewPosition.z;\n#endif\n#ifdef SIZE_ATTENUATION\n  // perspective shrinks with distance; an orthographic projection (w row 0, 0, 0, 1) doesn't\n  float depth = uProjection[3][3] == 1.0 ? 1.0 : max(-viewPosition.z, 1e-4);\n  gl_PointSize = uSize * uScale / depth;\n#else\n  gl_PointSize = uSize;\n#endif\n  vColor = vec3(1.0);\n#ifdef VERTEX_COLORS\n  vColor = srgbToLinear(color);\n#endif\n  vHighlight = uHighlightIndex == -1 || gl_VertexID == uHighlightIndex ? 1.0 : 0.0;\n#ifdef PICK\n  vPickElement = uint(gl_VertexID);\n#endif\n}\n";
-export declare const LINES_VERTEX = "\nlayout(location = 0) in vec3 segmentStart;\nlayout(location = 1) in vec3 segmentEnd;\nlayout(location = 2) in vec3 segmentColorStart;\nlayout(location = 3) in vec3 segmentColorEnd;\nlayout(location = 4) in vec2 corner; // x: 0 at start, 1 at end; y: -1 or 1 across\n\nuniform mat4 uModel;\nuniform mat4 uView;\nuniform mat4 uProjection;\nuniform vec2 uResolution;   // drawing buffer size in pixels\nuniform float uWidth;       // pixels, already scaled by the pixel ratio\nuniform float uNear;\n\nout vec3 vColor;\n#ifdef PICK\nflat out uint vPickElement; // which instance, point or segment, for GPU picking\n#endif\n#ifdef FOG\nout float vFogDepth;\n#endif\n\n\nvec3 srgbToLinear(vec3 c) {\n  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n}\nvec3 linearToSrgb(vec3 c) {\n  c = clamp(c, 0.0, 1.0);\n  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n}\n\n\nvoid main() {\n  vec4 a = uView * (uModel * vec4(segmentStart, 1.0));\n  vec4 b = uView * (uModel * vec4(segmentEnd, 1.0));\n  // clip the segment to the near plane so lines passing behind the camera stay correct\n  float clipZ = -uNear;\n  if (a.z > clipZ && b.z > clipZ) {\n    gl_Position = vec4(2.0, 2.0, 2.0, 1.0); // wholly behind: off screen\n    return;\n  }\n  if (a.z > clipZ) a = mix(a, b, (clipZ - a.z) / (b.z - a.z));\n  if (b.z > clipZ) b = mix(b, a, (clipZ - b.z) / (a.z - b.z));\n\n  vec4 ca = uProjection * a;\n  vec4 cb = uProjection * b;\n  vec2 sa = ca.xy / ca.w * uResolution * 0.5;\n  vec2 sb = cb.xy / cb.w * uResolution * 0.5;\n  vec2 dir = sb - sa;\n  float len = length(dir);\n  dir = len > 0.0 ? dir / len : vec2(1.0, 0.0);\n  vec2 normal = vec2(-dir.y, dir.x);\n\n  vec4 clip = mix(ca, cb, corner.x);\n#ifdef FOG\n  vFogDepth = -mix(a.z, b.z, corner.x);\n#endif\n  // extend past each end by half the width so joins look continuous\n  vec2 offset = normal * corner.y * uWidth * 0.5 + dir * (corner.x * 2.0 - 1.0) * uWidth * 0.5;\n  clip.xy += offset / (uResolution * 0.5) * clip.w;\n  gl_Position = clip;\n#ifdef PICK\n  vPickElement = uint(gl_InstanceID);\n#endif\n\n  vColor = vec3(1.0);\n#ifdef VERTEX_COLORS\n  vColor = srgbToLinear(mix(segmentColorStart, segmentColorEnd, corner.x));\n#endif\n}\n";
+export declare const POINTS_VERTEX = "\nlayout(location = 0) in vec3 position;\nlayout(location = 3) in vec3 color;\n#ifdef SPRITES\n// each point a square: one instance a point, drawn as a strip over the corners (along 0-1, across -1-1)\nlayout(location = 4) in vec2 corner;\nlayout(location = 11) in float pointSize;\nlayout(location = 12) in float pointOpacity;\nlayout(location = 13) in float pointAngle;\nlayout(location = 14) in float pointIndex;\nuniform vec2 uResolution;   // drawing buffer size in pixels\nout vec2 vUv;\nout float vOpacity;\n#endif\n\nuniform mat4 uModel;\nuniform mat4 uView;\nuniform mat4 uProjection;\nuniform float uSize;        // pixels (with the pixel ratio applied), or world units when attenuated\nuniform float uScale;       // projection focal term x half the buffer height: world size -> pixels at depth 1\nuniform int uHighlightIndex; // -2 none, -1 every point, otherwise the point\n\nout vec3 vColor;\nflat out float vHighlight;\n#ifdef PICK\nflat out uint vPickElement; // which instance, point or segment, for GPU picking\n#endif\n#ifdef FOG\nout float vFogDepth;\n#endif\n\n\nvec3 srgbToLinear(vec3 c) {\n  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n}\nvec3 linearToSrgb(vec3 c) {\n  c = clamp(c, 0.0, 1.0);\n  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n}\n\n\nvoid main() {\n  vec4 viewPosition = uView * (uModel * vec4(position, 1.0));\n#ifdef SPRITES\n  // the square's corner, turned by the point's angle: the texture turns with it\n  vec2 c = vec2(corner.x * 2.0 - 1.0, corner.y);\n  float s = sin(pointAngle), k = cos(pointAngle);\n  vec2 turned = vec2(c.x * k - c.y * s, c.x * s + c.y * k);\n  float size = uSize * pointSize;\n#ifdef SIZE_ATTENUATION\n  // world units: the square sits in the view, facing the camera\n  viewPosition.xy += turned * size * 0.5;\n  gl_Position = uProjection * viewPosition;\n#else\n  // pixels: the square is laid out on the screen\n  gl_Position = uProjection * viewPosition;\n  gl_Position.xy += turned * size / uResolution * gl_Position.w;\n#endif\n  // the image upright on the square, its top at the top, as a point's is\n  vUv = vec2(c.x * 0.5 + 0.5, 0.5 - c.y * 0.5);\n  vOpacity = pointOpacity;\n  int self = int(pointIndex + 0.5);\n#else\n  gl_Position = uProjection * viewPosition;\n  int self = gl_VertexID;\n#endif\n#ifdef FOG\n  vFogDepth = -viewPosition.z;\n#endif\n#ifdef SPRITES\n#elif defined(SIZE_ATTENUATION)\n  // perspective shrinks with distance; an orthographic projection (w row 0, 0, 0, 1) doesn't\n  float depth = uProjection[3][3] == 1.0 ? 1.0 : max(-viewPosition.z, 1e-4);\n  gl_PointSize = uSize * uScale / depth;\n#else\n  gl_PointSize = uSize;\n#endif\n  vColor = vec3(1.0);\n#ifdef VERTEX_COLORS\n  vColor = srgbToLinear(color);\n#endif\n  vHighlight = uHighlightIndex == -1 || self == uHighlightIndex ? 1.0 : 0.0;\n#ifdef PICK\n  vPickElement = uint(self);\n#endif\n}\n";
+export declare const LINES_VERTEX = "\nlayout(location = 0) in vec3 segmentStart;\nlayout(location = 1) in vec3 segmentEnd;\nlayout(location = 2) in vec3 segmentColorStart;\nlayout(location = 3) in vec3 segmentColorEnd;\n// the distance along its chain (segments joined end to start) where it starts, in the model's\n// units; 1 if it starts a chain; 1 if it ends one\nlayout(location = 5) in vec3 segmentInfo;\n\nuniform mat4 uModel;\nuniform mat4 uView;\nuniform mat4 uProjection;\nuniform vec2 uResolution;   // drawing buffer size in pixels\nuniform float uWidth;       // pixels, already scaled by the pixel ratio\nuniform float uNear;\nuniform int uArrows;        // arrowheads: 1 at the start of each chain, 2 at its end, 3 at both\nuniform float uArrowSize;   // their length in pixels, scaled by the pixel ratio\n\n// six vertices an instance make the segment's quad, as two triangles - x: 0 at its start, 1 at its\n// end; y: -1 or 1 across - and six more its two arrowheads, drawn only when asked for\nconst vec2 QUAD[6] = vec2[6](vec2(0.0, -1.0), vec2(0.0, 1.0), vec2(1.0, -1.0), vec2(1.0, -1.0), vec2(0.0, 1.0), vec2(1.0, 1.0));\n\nout vec3 vColor;\n#ifdef DASHED\nout float vDistance;        // along the chain, in the model's units\nflat out float vArrow;      // 1 on an arrowhead, which is never dashed\n#endif\n#ifdef PICK\nflat out uint vPickElement; // which instance, point or segment, for GPU picking\n#endif\n#ifdef FOG\nout float vFogDepth;\n#endif\n\n\nvec3 srgbToLinear(vec3 c) {\n  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n}\nvec3 linearToSrgb(vec3 c) {\n  c = clamp(c, 0.0, 1.0);\n  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n}\n\n\nvoid main() {\n  vec4 a = uView * (uModel * vec4(segmentStart, 1.0));\n  vec4 b = uView * (uModel * vec4(segmentEnd, 1.0));\n  // clip the segment to the near plane so lines passing behind the camera stay correct\n  float clipZ = -uNear;\n  if (a.z > clipZ && b.z > clipZ) {\n    gl_Position = vec4(2.0, 2.0, 2.0, 1.0); // wholly behind: off screen\n    return;\n  }\n  if (a.z > clipZ) a = mix(a, b, (clipZ - a.z) / (b.z - a.z));\n  if (b.z > clipZ) b = mix(b, a, (clipZ - b.z) / (a.z - b.z));\n\n  vec4 ca = uProjection * a;\n  vec4 cb = uProjection * b;\n  vec2 sa = ca.xy / ca.w * uResolution * 0.5;\n  vec2 sb = cb.xy / cb.w * uResolution * 0.5;\n  vec2 dir = sb - sa;\n  float len = length(dir);\n  dir = len > 0.0 ? dir / len : vec2(1.0, 0.0);\n  vec2 normal = vec2(-dir.y, dir.x);\n\n  bool arrowStart = (uArrows & 1) != 0 && segmentInfo.y > 0.5;\n  bool arrowEnd = (uArrows & 2) != 0 && segmentInfo.z > 0.5;\n  float along, arrow = 0.0;\n  vec2 offset;\n  if (gl_VertexID < 6) {\n    vec2 c = QUAD[gl_VertexID];\n    along = c.x;\n    // past each end by half the width so joins look continuous - or short of it, under an arrowhead\n    float startOut = arrowStart ? -uArrowSize * 0.8 : uWidth * 0.5;\n    float endOut = arrowEnd ? -uArrowSize * 0.8 : uWidth * 0.5;\n    offset = normal * c.y * uWidth * 0.5 + dir * (along > 0.5 ? endOut : -startOut);\n  } else {\n    // an arrowhead: its tip on the chain's end, pointing out along the segment\n    int which = (gl_VertexID - 6) / 3, k = gl_VertexID - 6 - which * 3;\n    if (which == 0 ? !arrowStart : !arrowEnd) {\n      gl_Position = vec4(2.0, 2.0, 2.0, 1.0);\n      return;\n    }\n    along = float(which);\n    vec2 d = which == 1 ? dir : -dir;\n    float wing = uArrowSize * 0.45;\n    offset = k == 0 ? vec2(0.0) : -d * uArrowSize + normal * (k == 1 ? wing : -wing);\n    arrow = 1.0;\n  }\n\n  vec4 clip = mix(ca, cb, along);\n#ifdef FOG\n  vFogDepth = -mix(a.z, b.z, along);\n#endif\n  clip.xy += offset / (uResolution * 0.5) * clip.w;\n  gl_Position = clip;\n#ifdef DASHED\n  vDistance = segmentInfo.x + length(segmentEnd - segmentStart) * along;\n  vArrow = arrow;\n#endif\n#ifdef PICK\n  vPickElement = uint(gl_InstanceID);\n#endif\n\n  vColor = vec3(1.0);\n#ifdef VERTEX_COLORS\n  vColor = srgbToLinear(mix(segmentColorStart, segmentColorEnd, along));\n#endif\n}\n";
 export type ShaderKind = 'mesh' | 'points' | 'lines';
 /**
  * Vertex and fragment source for a kind of drawable, or a pass's own pair, with a set of feature defines.

package/llms-full.txt

@@ -114,9 +114,13 @@ const view = new View({ canvas: '#c', orbit: true })
 | `autoLight` | `true` | light a scene that has no lights (a chart needs none of its own); `false` to leave it dark |
 | `pixelRatio` | `min(devicePixelRatio, 2)` | |
 | `context` | `'auto'` | WebGL context: own for the first four views on a page, then one shared context - so a page can hold any number of views |
+| `keyboard` | `false` | `true` or `{ label: (hit) => text }`: use without a pointer, with a screen reader - see Interaction |
+| `description` | none | what the view shows, for screen readers (the canvas's label); made from the scene when `keyboard` is on |
+| `reducedMotion` | `'auto'` | as the system's reduced-motion setting: `frame()` jumps rather than glides, auto-rotation holds, charts change at once. `true` or `false` to choose |
 
 Members: `view.scene`, `view.camera` (assign a camera or a preset name to switch), `view.controls`
-(the orbit control), `view.renderer`, `view.width`, `view.height`.
+(the orbit control), `view.renderer`, `view.width`, `view.height`, `view.description`, `view.reducedMotion`
+(true or false as it stands - check it for motion of your own, such as a timeline; set `'auto'`, true or false).
 
 Methods:
 
@@ -135,6 +139,8 @@ Methods:
 - `on('click' | 'hover', (hit, event) => ...)` - see Interaction. Returns an unsubscribe function.
 - `tooltip(fn)` - set the tooltip function later.
 - `pick(x, y)` / `pick(event)` - the hit under a canvas position; `pickAll` for every hit.
+- `pickArea(area)` - every hit inside a box `{ x, y, width, height }` or a lasso of `[x, y]` points
+  (CSS pixels), nearest first - see Interaction.
 - `rayAt(x, y)` / `rayAt(event)` - the world `Ray` through a canvas position, for placing things:
   `ray.at(ray.intersectPlane([0, 1, 0], [0, 0, 0]))` is the point on the floor under the pointer
   (`intersectPlane` returns null when the ray runs along the plane or away from it).
@@ -164,7 +170,7 @@ something changes):
 ## Scene graph
 
 Everything in a scene is a node. Node options (all optional): `name`, `position`, `rotation`
-(Euler XYZ radians, `[x, y, z]`), `quaternion`, `scale` (number or `[x, y, z]`), `visible`,
+(Euler XYZ radians, `[x, y, z]`), `quaternion` (`[x, y, z, w]` or `{ x, y, z, w }`), `scale` (number or `[x, y, z]`), `visible`,
 `pickable` (default true), `userData`, `children`, `onUpdate`, `clip` (a section plane - see
 Cutaways), plus the interaction options below.
 
@@ -218,6 +224,24 @@ new Lines({ geometry: edges(box(2)), material: { color: '#333', width: 2 } })
 new Label({ text: 'Rack A1', position: [0, 2, 0], className: 'my-label', place: 'above' })
 ```
 
+**Lines** dashed and with arrowheads - flow and direction in network diagrams. Dashes are material
+options in the model's units: `dash` (0 is solid), `gap` (0 is the dash's length) and `dashOffset`,
+which moves them along - animate it for traffic. Arrowheads are Lines options: `arrows: 'start' |
+'end' | 'both'` puts them at the ends of each chain (segments each starting where the one before
+ended - a polyline is one chain, separate links are one each), `arrowSize` in pixels (0, the default,
+sizes them from the width). The dashes run on along a chain, and arrowheads are never dashed.
+
+```js
+const flow = view.scene.add(new Lines({ geometry: links, arrows: 'end', material: { color: '#4cc9f0', width: 2, dash: 0.3, gap: 0.15 } }))
+view.start((dt) => { flow.material.dashOffset += dt * 0.8 })   // traffic moving along each link
+```
+
+**Points** each their own size, opacity or angle: give the geometry `sizes` (multiples of the material's
+`size`), `opacities` (0-1) or `angles` (radians, turning the point's `map`), one per vertex. Such points
+are drawn as camera-facing squares, so any size works and they stay whole at the edge of the view.
+`sort: true` draws them furthest first each frame - for soft points with `blending: 'normal'`
+(smoke, cloud) that would otherwise layer wrongly; with additive blending order doesn't matter.
+
 **InstancedMesh** - many copies of one geometry in one draw call, for bars, racks, nodes:
 
 ```js
@@ -229,7 +253,11 @@ bars.setColor(3, 'red')
 `setInstance(i, { position, rotation, quaternion, scale, color })`. An instance's `color` multiplies the
 material's colour, which is white unless you set one - so the instance colour shows as given. `count` defaults to the number
 of rows in `data`. For very large data, write `bars.instanceMatrices` (16 numbers per instance,
-column-major) directly and call `bars.needsUpdate()`.
+column-major) directly and call `bars.needsUpdate()`. An instance scaled to 0 is hidden: it draws
+nothing, and bounds, framing, shadows and labels leave it out - so a pool can keep spare instances.
+Positions and quaternions also take `{ x, y, z }` and `{ x, y, z, w }`, as physics engines return
+them, so a physics bridge is one line a body:
+`bricks.setInstance(i, { position: body.translation(), quaternion: body.rotation() })`.
 
 **Labels** are HTML elements pinned to 3D points (style them with CSS). Options: `text`, `position`,
 `className`, `place` (`'center'` | `'above'` | `'below'` | `'left'` | `'right'`), `offset` ([x, y]
@@ -237,7 +265,8 @@ pixels), `priority` (higher wins when labels overlap), `overlap` (`'hide'` | `'d
 a label does when covered), `occlude` (true: counts as covered when geometry is in front), `leader`
 (true: a line from the point to the label, with a dot on the point - for callouts), `edge` (`'left'` |
 `'right'`: set the label at that edge of the view, level with its point - callouts in a column, with
-`leader: true`; `offset` then moves it in and up or down).
+`leader: true`; `offset` then moves it in and up or down), `minScale` (show it only when zoomed in this
+far - below).
 
 A label answers the pointer when it has handlers: a Label with its own `onClick` or `onHover` is
 clicked and hovered like a mesh (`new Label({ text: 'Mantle', onClick: () => show('mantle') })` - a
@@ -250,6 +279,21 @@ clicking that bar, with the same hit. Other labels let the pointer through to th
 new InstancedMesh({ geometry: box(1), data: rows, labels: { text: (row) => row.name, place: 'above', priority: (row) => row.alert ? 2 : 0 } })
 ```
 
+**Labels by zoom level**: `minScale` on any label shows it only when the view is zoomed in at least that
+far - that many CSS pixels to one world unit, at the label's point (perspective or orthographic alike).
+Until then it takes no part in the layout, so it can't push other labels out. `labels` can also be a
+list, several labels per instance - the short one always, the details as you come closer:
+
+```js
+new InstancedMesh({ geometry: box(1), data: elements, labels: [
+  { text: (e) => e.symbol, place: 'center', className: 'symbol' },
+  { text: (e) => e.name, place: 'below', className: 'name', minScale: 45 },
+] })
+```
+
+Pick `minScale` by looking: at the zoom where the details should appear, a world unit spans that many
+pixels (a 1-unit tile drawn 60 px wide is 60). `view.explain()` counts the labels still waiting.
+
 ## Geometry
 
 Generators return a `Geometry`; each takes one options object (a number is the main size):
@@ -287,7 +331,9 @@ extrude({
 
 Your own: `new Geometry({ positions, normals?, uvs?, uvs2?, colors?, indices? })` - flat arrays, xyz per
 vertex; `colors` are rgb 0-1 per vertex (use `material: { vertexColors: true }`); `uvs2` is a second UV
-set, for baked occlusion and light maps (below).
+set, for baked occlusion and light maps (below). To animate one - cloth, a wave, a morph - write
+`geometry.positions` in place and call `geometry.needsUpdate()` each frame; normals you didn't give are
+worked out again to follow the shape.
 
 ## Materials
 
@@ -335,7 +381,10 @@ unless its `colorSpace` was set on purpose - `normalMap: await loadTexture('n.pn
 
 **Canvas and video textures**: a texture's `image` can be a canvas - draw on it, then call
 `texture.needsUpdate()` - or a `<video>`, whose frames upload by themselves while it plays, with
-nothing to call. `new Texture({ url: 'promo.mp4' })` (or .webm, .ogv, .mov, .m4v) makes the video
+nothing to call. For a big canvas drawn on a little at a time (paint, a map being revealed), say what
+changed - `texture.needsUpdate({ x, y, width, height })`, in the canvas's pixels from its top left -
+and only that rectangle is sent, rather than the whole canvas every frame (several calls before a
+frame add up). `new Texture({ url: 'promo.mp4' })` (or .webm, .ogv, .mov, .m4v) makes the video
 for you, muted and looping so browsers let it start by itself; `texture.image` is that `<video>` -
 pause, seek or unmute it as any other. A browser that blocks autoplay leaves it on its first frame
 until `texture.image.play()` from a click. Video textures make no mipmaps (they would be remade
@@ -425,7 +474,7 @@ on top, as with UVs (animate `offset` to scroll a pattern). 0 (the default) uses
 |---|---|
 | `AmbientLight` | `color`, `intensity` |
 | `HemisphereLight` | `sky`, `ground`, `intensity` |
-| `DirectionalLight` | `color`, `intensity`, `direction` (the way it travels, e.g. `[-1, -2, -1]`), `castShadow` |
+| `DirectionalLight` | `color`, `intensity`, `direction` (the way it travels, e.g. `[-1, -2, -1]`), `castShadow`, `shadowBounds` |
 | `PointLight` | `color`, `intensity`, `position`, `range` - inverse-square falloff, so intensity ~ distance squared (30 lights things ~5 m away); `castShadow` |
 | `SpotLight` | point light options plus `direction`, `angle`, `penumbra`, `castShadow` |
 
@@ -443,7 +492,9 @@ meshes opt in with `castShadow` and `receiveShadow`. No shadow camera to set up.
 lamp - anything whose bounds hold the light - doesn't block it, so a lamp's shade can cast shadows of
 its own. A point light casts all round, and everything that casts blocks it, around it too: a candle in
 a lantern or a carved pumpkin lights the room only through the openings. Give a bulb or flame mesh
-drawn at the light `castShadow: false`.
+drawn at the light `castShadow: false`. The directional shadow is fitted to whatever casts, every
+frame; when things fly far off, give the light `shadowBounds: { min: [x, y, z], max: [x, y, z] }` -
+the world area that gets shadows - so the map stays sharp there.
 
 ```js
 scene.add(new PointLight({ position: [0, 0.1, 0], intensity: 0.5, range: 4, castShadow: true }))  // a candle in a jack-o'-lantern
@@ -469,6 +520,9 @@ and `target` yourself; the orbit always turns about wherever the target is.
   press or the wheel takes over.
 - **Back to the start**: `view.frame(undefined, { direction: 'perspective', duration: 0.6 })`
   (or the preset the view started with).
+- **Where framing would go**: `view.framing(target, { padding, direction })` returns
+  `{ position, target, height? }` without moving the camera - for a camera that eases after
+  something that keeps changing size (`camera.position.lerp(aim.position, 0.1)`, the same for target).
 - **Follow something that moves** - move the camera and its target by as much as it moved, so the
   view keeps its angle and the user can still orbit round it:
 
@@ -506,6 +560,16 @@ view.on('hover', (hit) => show(hit?.datum))                 // fires when the th
 - The **nearest surface** under the pointer is the hit - a link drawn over a site's top wins the
   hover there. To let one kind of thing through, give it `pickable: false`; to choose among
   everything under the pointer, `view.pickAll(event)` lists every hit, nearest first.
+- **Selecting an area** - `view.pickArea({ x, y, width, height })` (width and height may be negative,
+  as a drag up or left makes them) or `view.pickArea([[x, y], ...])` for a lasso: a hit for each point,
+  instance and line segment whose place on screen is inside, and each mesh whose middle is. Places, not
+  surfaces: what is hidden behind other things is found too, so a box over a scatter takes that whole
+  region. Hidden, unpickable and zero-scale instances are left out. Turn `view.controls.enabled` off
+  while the user drags out the area.
+
+  ```js
+  const chosen = view.pickArea({ x: 40, y: 30, width: 200, height: 120 }).map((h) => h.datum)
+  ```
 - **Rays of your own** - line of sight, what's below a dropped object, picking in tests: a
   `Raycaster` finds what any ray hits, on the CPU. Set `raycaster.ray.origin` and `.direction`, or aim
   it with `setFromCamera([x, y], camera)` (-1 to 1, y up); `intersect(nodeOrNodes)` returns hits,
@@ -524,7 +588,8 @@ view.on('hover', (hit) => show(hit?.datum))                 // fires when the th
   children. A node's `highlight` is the colour for its subtree; it tints the mesh, instance or point
   under the pointer. Add `highlightWhole: true` to tint the whole subtree as one thing (a piece of
   furniture, a machine) whichever part is hovered. Without the View's `highlight`, only nodes with
-  their own highlight light up - leave it off to keep floors and walls plain.
+  their own highlight light up - leave it off to keep floors and walls plain, or keep it and give
+  those `highlight: false` (`null` means "the View's").
 - `onHover` and `onClick` are the app's own handler for a node; to add more without replacing it
   (an add-on, a second concern), `node.on('hover' | 'click', fn)` - it returns a function that stops
   listening. Both run. A drag has one handler, `onDrag`: one thing moves a node at a time.
@@ -549,6 +614,22 @@ chair.onDrag = (drag) => {
   corners - as the canvas is; `outlineAntialias: false` on the View (or `view.renderer.outlineAntialias =
   false`, any time) draws them in hard pixel steps instead.
 - `view.controls.cancel()` lets go of the orbit gesture in progress, for apps that take over a press.
+- **Keyboard and screen readers**: `keyboard: true` on the View makes the canvas a stop in the page's
+  tab order. The arrow keys (and Home, End, PageUp, PageDown) step through what can be hovered or
+  clicked, in scene order and each mesh's instances in order: each instance, point, surface grid
+  point (a mesh with a row per vertex) or row of data under a node with its own `tooltip`, `onClick`,
+  `onHover`, `onDrag` or `highlight` - and, when the View has a tooltip or handlers itself, each one
+  with data. A mesh with no rows is a stop when it has a name or a handler of its own. A
+  `highlightWhole` subtree is one stop. Lines with a row per segment (a network's links) are a stop
+  per segment, after everything else. The one stepped to is shown as hovering would show it - tint (`#ffcc00` when no highlight
+  is set), tooltip, hover handlers - and Enter or Space clicks it (the handler's event is null);
+  Escape leaves it, and moving the pointer takes over. A screen reader hears each one: the tooltip's
+  text, else its data, else its name, with "3 of 12" - or `keyboard: { label: (hit) => text }`. The
+  canvas is labelled with `description`, or from the scene: each chart's `summary()` ("Sales: bar
+  chart of 12 rows by month, sales"), else "3D view of 12 items".
+- **Reduced motion**: `reducedMotion` follows the system's setting by default. When on, `frame()`
+  with a `duration` jumps, `autoRotate` holds, and chart transitions and flowing links settle at
+  once. Motion of your own (a `Timeline`, `onUpdate` spin) can check `view.reducedMotion`.
 
 ## Charts: `phoria2/charts`
 
@@ -600,7 +681,8 @@ A chart is a node with axes, ticks, grid walls, a legend and tooltips built in.
   in it as a wrapping row, so give it no fixed height). Categories get swatches that click to hide
   and show; a number colour gets a key - a ramp, highest at the top, with values marked up its side,
   `ticks` as on an axis),
-  `theme: 'dark' | 'light'`, `title`, `transition: false | { duration, ease }`,
+  `theme: 'dark' | 'light'`, `title`, `description` (what a screen reader hears for it; else `chart.summary()`
+  makes one from the title and channels), `transition: false | { duration, ease }`,
   `overlap: 'dim' | 'hide' | 'show'` (labels), `highlight` (a colour, false, or for networks
   `'neighbours'` - the default, lighting the node's links and linked nodes - or `'node'`, the node alone), and node options (`position`, ...).
 - **Surfaces**: one row per grid point - `x` and `z` are the grid (numbers or categories), `y` the
@@ -758,6 +840,20 @@ second), `follow` (a node whose position is the origin each frame - a trail), `o
 default material is small additive points. `burst(count, spawnOptions)`, `clear()`, `set(options)`,
 `count`.
 
+How particles look over their lives: `size` (a multiple of the material's size, or a list each particle
+goes through - `[0.5, 3]` billows), `sizeSpread` (each one's size varies by up to this share, 0-1),
+`opacity` (0-1, or a list - `[0, 1, 0]` fades in and out) and `spin` (radians per second: a number
+either way, or `[min, max]`; spinning particles start at a random angle). For smoke, a soft `map`,
+`blending: 'normal'` and `sort: true`:
+
+```js
+const smoke = view.scene.add(new Emitter({
+  rate: 40, velocity: [0, 1.5, 0], velocitySpread: 0.4, lifetime: [3, 5], color: ['#777', '#333'],
+  size: [0.6, 4], sizeSpread: 0.3, opacity: [0, 0.6, 0], spin: 0.5, sort: true,
+  material: { map: puff, size: 1, blending: 'normal' },
+}))
+```
+
 `Body` moves any node: `node.onUpdate(new Body({ velocity, gravity, drag }).update)`;
 `body.impulse([x, y, z])` kicks it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoria2",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Small, friendly 3D for the web - a WebGL 2 renderer with charts, labels, picking, particles and glTF",
   "keywords": [
     "3d",
@@ -85,10 +85,13 @@
     "plugin": "node scripts/plugin.mjs"
   },
   "devDependencies": {
+    "@dimforge/rapier3d-compat": "^0.21.0",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.3.0",
     "gl-matrix": "^3.4.4",
     "globals": "^17.6.0",
+    "manifold-3d": "^3.5.4",
+    "recast-navigation": "^0.44.0",
     "three": "0.186.1",
     "typescript": "^7.0.2",
     "vite": "^8.0.12",