phoria2 1.1.0 → 1.2.0

package/dist/types/keyboard.d.ts

@@ -0,0 +1,48 @@
+import type { Hit } from './Raycaster.js';
+import type { TooltipContent } from './tooltip.js';
+import type { Node } from './scene/Node.js';
+import type { View } from './View.js';
+export type KeyboardOptions = {
+    /**
+     * what a screen reader says for each thing stepped to (default: the
+     * tooltip's text, then its data, then the node's name)
+     */
+    label?: (hit: Hit) => string;
+};
+export type KeyboardHooks = {
+    /**
+     * show this as hovered, or nothing
+     */
+    focus: (hit: Hit | null) => void;
+    /**
+     * click it
+     */
+    press: (hit: Hit) => void;
+    /**
+     * the tooltip's content for it, if there is a tooltip
+     */
+    tooltip: (hit: Hit) => TooltipContent;
+    /**
+     * does the View itself answer hovers or clicks (a tooltip, handlers)?
+     */
+    viewWide: () => boolean;
+};
+export type Item = {
+    node: Node;
+    index: number | null;
+    whole: Node | null;
+};
+export declare class Keyboard {
+    #private;
+    /** @param {View} view @param {KeyboardHooks} hooks @param {KeyboardOptions} options */
+    constructor(view: View, hooks: KeyboardHooks, options: KeyboardOptions);
+    /**
+     * The canvas's label for screen readers: the View's description, or - when it has none - one made
+     * from the scene: what its charts show, and how many things there are to step through.
+     * @param {string | null} text
+     */
+    setDescription(text: string | null): void;
+    /** Step off whatever was stepped to: the pointer has taken over, or focus has gone. */
+    clear(): void;
+    dispose(): void;
+}

package/dist/types/labels.d.ts

@@ -18,6 +18,10 @@ export type LabelStats = {
      * behind the camera or outside the view
      */
     offscreen: number;
+    /**
+     * hidden because the view isn't zoomed in to their minScale
+     */
+    zoomedOut: number;
 };
 export type Entry = {
     el: HTMLDivElement;

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

@@ -5,7 +5,7 @@ import { Mat4 } from '../value/Mat4.js';
 import { Quat } from '../value/Quat.js';
 import { Vec3 } from '../value/Vec3.js';
 import { Clip } from '../clip.js';
-import type { ColorInput, Vec3Input } from '../types.js';
+import type { ColorInput, QuatInput, Vec3Input } from '../types.js';
 import type { Hit } from '../Raycaster.js';
 import type { Camera } from './cameras.js';
 import type { ClipOptions } from '../clip.js';
@@ -59,9 +59,9 @@ export type NodeOptions = {
      */
     rotation?: Vec3Input | Euler;
     /**
-     * [x, y, z, w] - instead of rotation
+     * [x, y, z, w] or { x, y, z, w } - instead of rotation
      */
-    quaternion?: ArrayLike<number>;
+    quaternion?: QuatInput;
     /**
      * a number scales uniformly
      */
@@ -87,9 +87,10 @@ export type NodeOptions = {
      */
     tooltip?: ((hit: Hit) => any) | null;
     /**
-     * hover tint for this subtree, over the View's
+     * hover tint for this subtree, over the View's; false for none - a
+     * floor or wall left plain under a View that tints everything else (null: the View's)
      */
-    highlight?: ColorInput | null;
+    highlight?: ColorInput | null | false;
     /**
      * hovering any part of this subtree tints all of it, as one thing - a
      * piece of furniture, a machine - rather than just the part under the pointer (default false)
@@ -127,7 +128,7 @@ export type NodeOptions = {
      */
     clip?: ClipOptions | Clip | null;
 };
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 /** @import { Hit } from '../Raycaster.js' */
 /** @import { Camera } from './cameras.js' */
 /** @import { ClipOptions } from '../clip.js' */
@@ -157,7 +158,7 @@ export type NodeOptions = {
  * @property {string} [name]
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion] [x, y, z, w] - instead of rotation
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - instead of rotation
  * @property {Vec3Input | number} [scale] a number scales uniformly
  * @property {boolean} [visible]
  * @property {boolean} [pickable] include in view.pick() (default true)
@@ -167,7 +168,8 @@ export type NodeOptions = {
  * @property {UpdateHandler | UpdateHandler[]} [onUpdate]
  * @property {((hit: Hit) => any) | null} [tooltip] tooltip for anything picked in this subtree; nearer nodes win, and
  *   all win over the View's
- * @property {ColorInput | null} [highlight] hover tint for this subtree, over the View's
+ * @property {ColorInput | null | false} [highlight] hover tint for this subtree, over the View's; false for none - a
+ *   floor or wall left plain under a View that tints everything else (null: the View's)
  * @property {boolean} [highlightWhole] hovering any part of this subtree tints all of it, as one thing - a
  *   piece of furniture, a machine - rather than just the part under the pointer (default false)
  * @property {((hit: Hit | null) => void) | null} [onHover] called as the thing under the pointer in this subtree changes
@@ -244,14 +246,17 @@ export declare class Node {
     set rotation(v: Vec3Input);
     /** Kept in sync with rotation. Assigning copies, normalised. @returns {Quat} */
     get quaternion(): Quat;
-    /** @param {ArrayLike<number>} v */
-    set quaternion(v: ArrayLike<number>);
+    /** @param {QuatInput} v */
+    set quaternion(v: QuatInput);
     /** @param {NodeOptions} [options] */
     constructor(options?: NodeOptions);
-    /** Hover tint for this subtree, over the View's; set any colour, or null. @returns {Color | null} */
-    get highlight(): Color | null;
-    /** @param {ColorInput | null} value */
-    set highlight(value: ColorInput | null);
+    /**
+     * Hover tint for this subtree, over the View's: a colour, false for none, or null to use the View's.
+     * @returns {Color | null | false}
+     */
+    get highlight(): Color | null | false;
+    /** @param {ColorInput | null | false} value */
+    set highlight(value: ColorInput | null | false);
     /**
      * The section plane cutting this subtree, or null. Set { normal, offset, cap }, a Clip or null;
      * move the cut by changing its offset or normal in place.

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,11 +236,11 @@ 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 */
+    /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null }} options */
     constructor(options: DrawableOptions & {
-        labels?: InstanceLabels | null;
+        labels?: InstanceLabels | InstanceLabels[] | null;
     });
     /** @returns {'points'} */
     get drawMode(): 'points';
@@ -261,6 +275,8 @@ export declare class Label extends Node {
         pointer: string;
         anchor: string;
         zIndex: string;
+        minZoom: string;
+        lod: string;
         collision: string;
     };
     text: string;
@@ -280,6 +296,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/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:
 
@@ -164,7 +168,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.
 
@@ -229,7 +233,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 +245,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 +259,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 +311,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
 
@@ -425,7 +451,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 +469,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 +497,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:
 
@@ -524,7 +555,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 +581,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 +648,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoria2",
-  "version": "1.1.0",
+  "version": "1.2.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",

package/schema/scene.schema.json

@@ -202,6 +202,11 @@
                   "type": "null"
                 }
               ]
+            },
+            "minScale": {
+              "type": "number",
+              "description": "Show the label only when zoomed in this far: CSS pixels to one world unit at its point (0, always).",
+              "minimum": 0
             }
           },
           "unevaluatedProperties": false
@@ -327,6 +332,16 @@
             },
             "castShadow": {
               "type": "boolean"
+            },
+            "shadowBounds": {
+              "type": ["object", "null"],
+              "description": "The part of the world, in world units, that has shadows; null (the default) follows what casts.",
+              "required": ["min", "max"],
+              "properties": {
+                "min": { "$ref": "#/$defs/vec3" },
+                "max": { "$ref": "#/$defs/vec3" }
+              },
+              "additionalProperties": false
             }
           },
           "unevaluatedProperties": false
@@ -462,13 +477,16 @@
           "description": "Anything of your own."
         },
         "highlight": {
-          "description": "Hover tint for this subtree, or null for none.",
+          "description": "Hover tint for this subtree; false for none, null to use the View's.",
           "anyOf": [
             {
               "$ref": "#/$defs/color"
             },
             {
               "type": "null"
+            },
+            {
+              "const": false
             }
           ]
         },

package/src/OrbitControl.js

@@ -255,8 +255,12 @@ export class OrbitControl {
     this.target.add(move)
   }
 
-  /** Apply inertia and auto-rotate; the View calls this each frame. @param {number} dt seconds */
-  update(dt) {
+  /**
+   * Apply inertia and auto-rotate; the View calls this each frame.
+   * @param {number} dt seconds
+   * @param {boolean} [still] hold auto-rotation - the View passes its reducedMotion
+   */
+  update(dt, still = false) {
     if (!this.enabled) return
     if (this.#pointers.size === 0) {
       const v = this.#velocity
@@ -267,7 +271,7 @@ export class OrbitControl {
         v.yaw *= keep
         v.pitch *= keep
       }
-      if (this.autoRotate) this.rotate(-(this.autoRotate === true ? 0.5 : this.autoRotate) * dt, 0)
+      if (this.autoRotate && !still) this.rotate(-(this.autoRotate === true ? 0.5 : this.autoRotate) * dt, 0)
     }
   }