phoria2 1.1.0 → 1.3.0

package/schema/scene.schema.json

@@ -102,6 +102,10 @@
           "properties": {
             "type": {
               "const": "points"
+            },
+            "sort": {
+              "type": "boolean",
+              "description": "Draw the points furthest first each frame, for soft points that cover what is behind them."
             }
           },
           "unevaluatedProperties": false
@@ -113,6 +117,15 @@
           "properties": {
             "type": {
               "const": "lines"
+            },
+            "arrows": {
+              "enum": ["none", "start", "end", "both"],
+              "description": "Arrowheads at the ends of each chain of joined segments."
+            },
+            "arrowSize": {
+              "type": "number",
+              "description": "Arrowhead length in pixels; 0 sizes them from the material's width.",
+              "minimum": 0
             }
           },
           "unevaluatedProperties": false
@@ -202,6 +215,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 +345,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 +490,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
             }
           ]
         },
@@ -898,6 +929,20 @@
           "description": "Lines: width in pixels.",
           "minimum": 0
         },
+        "dash": {
+          "type": "number",
+          "description": "Lines: dashed, with dashes this long in the model's units; 0 is solid.",
+          "minimum": 0
+        },
+        "gap": {
+          "type": "number",
+          "description": "Lines: the gaps between dashes; 0 is as long as the dashes.",
+          "minimum": 0
+        },
+        "dashOffset": {
+          "type": "number",
+          "description": "Lines: moves the dashes along the lines - animate it for flow."
+        },
         "alphaTest": {
           "type": "number",
           "description": "Cut-outs: drop pixels with less alpha.",
@@ -1262,6 +1307,27 @@
                 "type": "number"
               }
             },
+            "sizes": {
+              "type": "array",
+              "description": "Points: one per vertex, a multiple of the material's size.",
+              "items": {
+                "type": "number"
+              }
+            },
+            "opacities": {
+              "type": "array",
+              "description": "Points: one per vertex, 0-1, times the material's opacity.",
+              "items": {
+                "type": "number"
+              }
+            },
+            "angles": {
+              "type": "array",
+              "description": "Points: one per vertex, radians anticlockwise on screen.",
+              "items": {
+                "type": "number"
+              }
+            },
             "indices": {
               "type": "array",
               "items": {

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)
     }
   }
 

package/src/Raycaster.js

@@ -10,6 +10,7 @@ import { BVH_MIN_TRIANGLES, bvhOf, walk } from './geometry/bvh.js'
 /** @import { InstancedMesh, Lines, Mesh, Points } from './scene/drawables.js' */
 
 /** The section plane cutting what is being tested: world plane, and whether its cut faces are filled. @typedef {{ plane: Float32Array, cap: boolean }} Cut */
+/** @internal A surface ready for many rays: a mesh or one instance, with its world matrix and bounding sphere. @typedef {{ node: any, world: Float32Array, instance: number | null, cut: Cut | null, x: number, y: number, z: number, radius: number }} Solid */
 
 // Nodes are told apart by markers (drawMode, instanceMatrices) rather than instanceof, so picking
 // doesn't pull every node class into an app's bundle.
@@ -119,6 +120,63 @@ export class Raycaster {
     return hits.filter((h) => h.distance >= this.near && h.distance <= this.far).sort((x, y) => x.distance - y.distance)
   }
 
+  /** @internal
+   * The solid surfaces of a frame's draw list, ready for many rays: each mesh and each instance with its
+   * world matrix and bounding sphere worked out once, rather than once per ray - for label occlusion,
+   * which casts a ray per label.
+   * @param {{ node: Node, worldMatrix: Float32Array, instances: { count: number, instanceMatrices: Float32Array } | null, clip: { plane: Float32Array, cap: unknown } | null }[]} items
+   * @returns {Solid[]}
+   */
+  static solids(items) {
+    /** @type {Solid[]} */
+    const out = []
+    for (const item of items) {
+      const n = /** @type {any} */ (item.node)
+      if (n.drawMode !== 'triangles' || !n.geometry.vertexCount) continue
+      const box = n.geometry.bounds, center = box.getCenter(), radius = box.getRadius()
+      const cut = item.clip ? { plane: item.clip.plane, cap: !!item.clip.cap } : null
+      /** @param {Float32Array} world @param {number | null} instance */
+      const add = (world, instance) => {
+        const c = center.clone().applyMatrix4(world)
+        const scale = Math.max(Math.hypot(world[0], world[1], world[2]), Math.hypot(world[4], world[5], world[6]), Math.hypot(world[8], world[9], world[10]))
+        out.push({ node: n, world, instance, cut, x: c[0], y: c[1], z: c[2], radius: radius * scale })
+      }
+      if (item.instances) {
+        for (let i = 0; i < item.instances.count; i++) {
+          add(mat4.multiply(new Float32Array(16), item.worldMatrix, item.instances.instanceMatrices.subarray(i * 16, i * 16 + 16)), i)
+        }
+      } else add(Float32Array.from(item.worldMatrix), null)
+    }
+    return out
+  }
+
+  /** @internal
+   * Whether the ray meets any of these solids nearer than `distance` - the first one found settles it,
+   * so nothing is sorted. One node, or one instance of it, can be left out: what a label is on.
+   * @param {Solid[]} solids from Raycaster.solids() @param {number} distance
+   * @param {Node | null} [skip] @param {number | null} [skipInstance] null for the whole node
+   * @returns {boolean}
+   */
+  blocked(solids, distance, skip = null, skipInstance = null) {
+    const o = this.ray.origin, d = this.ray.direction
+    /** @type {Hit[]} */
+    const hits = []
+    for (const s of solids) {
+      if (s.node === skip && (skipInstance === null || s.instance === skipInstance)) continue
+      // its bounding sphere first: missed, or wholly beyond the distance or behind the ray, it can't block
+      const ox = s.x - o[0], oy = s.y - o[1], oz = s.z - o[2]
+      const along = ox * d[0] + oy * d[1] + oz * d[2]
+      const off = ox * ox + oy * oy + oz * oz - along * along, r2 = s.radius * s.radius
+      if (off > r2) continue
+      const half = Math.sqrt(r2 - off)
+      if (along - half > distance || along + half < 0) continue
+      hits.length = 0
+      this.#mesh(s.node, s.world, s.instance, hits, s.cut)
+      if (hits.length && hits[0].distance < distance) return true
+    }
+    return false
+  }
+
   /** @internal
    * Where the ray meets one instance, point or segment of a drawable - the CPU half of GPU picking,
    * which finds what is under the pointer and leaves the exact point, face and uv to this.

package/src/View.js

@@ -4,6 +4,7 @@ import { DRAG_START, OrbitControl } from './OrbitControl.js'
 import { cameraPreset, fitPoints, framingScale, presetDirection } from './presets.js'
 import { EASES } from './ease.js'
 import { Raycaster } from './Raycaster.js'
+import { pickArea } from './area.js'
 import { ChangeWatch } from './watch.js'
 import { Box3 } from './value/Box3.js'
 import { Color } from './value/Color.js'
@@ -27,6 +28,7 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
 /** @import { CameraOptions } from './scene/cameras.js' */
 /** @import { ColorInput, Vec3Input } from './types.js' */
 /** @import { Node } from './scene/Node.js' */
+/** @import { Keyboard, KeyboardOptions } from './keyboard.js' */
 
 /**
  * @typedef {'auto' | 'always' | 'manual'} RenderMode
@@ -65,13 +67,23 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
  *   additive points and lines (default off). true for the defaults, or { strength, radius, threshold }
  * @property {boolean} [autoLight] light a scene that has no lights, with one console note (default true)
  * @property {number} [maxDelta] longest frame step in seconds, so a background tab doesn't jump (default 0.1)
+ * @property {'auto' | boolean} [reducedMotion] cut motion short, for people it makes unwell: frame() jumps rather
+ *   than glides, auto-rotation holds, and charts change at once with their flows still. Default 'auto': as the
+ *   system's setting (prefers-reduced-motion), followed as it changes
+ * @property {boolean | KeyboardOptions} [keyboard] use without a pointer: the canvas joins the page's tab order, and
+ *   the arrow keys step through what can be hovered or clicked - each with the hover tint, the tooltip and hover
+ *   handlers - with Enter or Space to click and Escape to leave. A screen reader hears each one. { label: (hit) =>
+ *   text } says what it hears (default: the tooltip's text, the data, or the name). Default false
+ * @property {string | null} [description] what the view shows, for screen readers: the canvas's label. With keyboard
+ *   on and no description, one is made from the scene (charts describe themselves)
  */
 
 /** @typedef {'click' | 'hover'} ViewEvent */
 /** @typedef {(hit: Hit | null, event: PointerEvent | MouseEvent | null) => void} ViewHandler */
 
 const OPTIONS = ['canvas', 'scene', 'camera', 'orbit', 'background', 'renderMode', 'framing', 'highlight', 'tooltip', 'pixelRatio',
-  'antialias', 'outlineAntialias', 'context', 'toneMapping', 'exposure', 'bloom', 'autoLight', 'maxDelta']
+  'antialias', 'outlineAntialias', 'context', 'toneMapping', 'exposure', 'bloom', 'autoLight', 'maxDelta', 'reducedMotion',
+  'keyboard', 'description']
 const FRAMING_OPTIONS = ['keep', 'aspect']
 const HINTS = {
   renderer: 'the View makes its renderer - read it from view.renderer',
@@ -90,6 +102,8 @@ const EVENT_HINTS = {
 }
 // how far the highlight colour is mixed in
 const HIGHLIGHT_AMOUNT = 0.45
+// what the keyboard's focus is tinted with when nothing says otherwise - focus must always show
+const FOCUS_COLOR = Color.fromInput('#ffcc00')
 // views that get a WebGL context of their own before 'auto' starts sharing one
 const OWN_CONTEXTS = 4
 // above this many things to test (instances, triangles, points, segments), picking goes to the
@@ -161,6 +175,15 @@ export class View {
   #tooltipClass = ''
   #tooltipLoading = false
   /** @type {Color | null} */ #highlight = null
+  /** @type {'auto' | boolean} */ #motion = 'auto'
+  // keyboard use: its code loads when asked for; the thing it has stepped to shows as hovered
+  /** @type {Keyboard | null} */ #keyboard = null
+  /** @type {Hit | null} */ #keyFocus = null
+  /** @type {string | null} */ #description = null
+  // the canvas had no role, so describing it gave it one - taken away again with the description
+  #gaveRole = false
+  // the system's prefers-reduced-motion, kept up to date
+  #systemReduced = false
   /** @type {{ x: number, y: number, clientX: number, clientY: number, event: PointerEvent } | null} */ #pointer = null
   #pickPending = false
   // a hover pick is out on the GPU
@@ -227,6 +250,7 @@ export class View {
       this.invalidate()
     }
     if (options.autoLight !== undefined) this.autoLight = !!options.autoLight
+    if (options.reducedMotion !== undefined) this.#setMotion(options.reducedMotion)
     if (options.maxDelta !== undefined) this.maxDelta = checkRange('View', 'maxDelta', options.maxDelta, 0, Infinity, { above: true })
     if (options.renderMode !== undefined) this.renderMode = checkOneOf('View', 'renderMode', options.renderMode, ['auto', 'always', 'manual'])
     if (options.pixelRatio !== undefined) {
@@ -247,6 +271,8 @@ export class View {
     }
     if (options.highlight !== undefined) this.#setHighlight(options.highlight)
     if (options.tooltip !== undefined) this.tooltip(options.tooltip)
+    if (options.description !== undefined) this.description = options.description
+    if (options.keyboard !== undefined && options.keyboard !== false) this.#loadKeyboard(options.keyboard)
     this.#labels = new LabelLayer(this.canvas, {
       interactive: (label) => labelHandlers(label, 'click').length > 0 || labelHandlers(label, 'hover').length > 0,
       on: (type, label, e) => this.#labelPointer(type, label, e),
@@ -324,6 +350,51 @@ export class View {
     this.invalidate()
   }
 
+  /**
+   * Is motion cut short - glides, auto-rotation, chart transitions? Set true or false, or 'auto' (the
+   * default) to follow the system's setting. Read it for motion of your own, such as a timeline.
+   * @returns {boolean}
+   */
+  get reducedMotion() { return this.#motion === 'auto' ? this.#systemReduced : this.#motion }
+  /** @param {'auto' | boolean} v */
+  set reducedMotion(v) { this.#setMotion(v) }
+
+  /** @param {'auto' | boolean} v */
+  #setMotion(v) {
+    if (v !== 'auto' && typeof v !== 'boolean') fail('View', `'reducedMotion' is 'auto' (as the system's setting), true or false, got ${describe(v)}`)
+    this.#motion = v
+    this.invalidate()
+  }
+
+  /**
+   * What the view shows, for screen readers - the canvas's label - or null. With keyboard on and no
+   * description, one is made from the scene.
+   * @returns {string | null}
+   */
+  get description() { return this.#description }
+  /** @param {string | null} v */
+  set description(v) {
+    if (v !== null && typeof v !== 'string') fail('View', `'description' is text for screen readers, or null, got ${describe(v)}`)
+    this.#description = v
+    if (this.#keyboard) {
+      this.#keyboard.setDescription(v)
+      return
+    }
+    const canvas = this.canvas
+    if (v === null) {
+      canvas.removeAttribute('aria-label')
+      if (this.#gaveRole) canvas.removeAttribute('role')
+      this.#gaveRole = false
+      return
+    }
+    canvas.setAttribute('aria-label', v)
+    // a picture, to a screen reader, unless the page has said otherwise
+    if (!canvas.hasAttribute('role')) {
+      canvas.setAttribute('role', 'img')
+      this.#gaveRole = true
+    }
+  }
+
   /** Canvas width in CSS pixels. */
   get width() { return this.#width }
   /** Canvas height in CSS pixels. */
@@ -397,6 +468,7 @@ export class View {
     this.time += dt
     this.#onFrame?.(dt, this.time)
     // the same order as the live loop, so a stepped frame is the frame a user sees
+    this.scene.motionReduced = this.reducedMotion
     this.scene.update(dt, this.time)
     this.#updateControls(dt)
     return this.#render(true)
@@ -411,7 +483,7 @@ export class View {
     if (this.#flight) return this.#fly(dt)
     if (!this.controls) return
     const waiting = this.#autoFrame && samePlace(cameraPlace(this.camera), this.#autoFrameFrom)
-    this.controls.update(dt)
+    this.controls.update(dt, this.reducedMotion)
     if (waiting) this.#autoFrameFrom = cameraPlace(this.camera)
   }
 
@@ -450,8 +522,8 @@ export class View {
     // remember what was drawn - including what drawing changed, such as fitting the camera - so
     // the next frame compares against it and doesn't draw the same picture again
     if (this.renderMode === 'auto') this.#watch.changed(this.scene, this.camera)
-    // things may have moved under a still pointer
-    if (this.#pointer && this.#needsHover()) this.#pickPending = true
+    // things may have moved under a still pointer - or the keyboard's focus moved on screen
+    if ((this.#pointer || this.#keyFocus) && this.#needsHover()) this.#pickPending = true
     return frame
   }
 
@@ -493,43 +565,26 @@ export class View {
    * @param {Node | Box3} [target] (default the scene)
    * @param {{ padding?: number, direction?: CameraPreset | Vec3Input, duration?: number }} [options] padding is
    *   the margin around it, as a fraction of its size: 0 is a tight fit, 0.2 (the default) leaves a fifth.
-   *   duration is in seconds (default 0: straight there); a press or the wheel stops the glide
+   *   duration is in seconds (default 0: straight there); a press or the wheel stops the glide, and with
+   *   reducedMotion it goes straight there
    * @returns {this}
    */
   frame(target = this.scene, { padding = 0.2, direction: towards, duration = 0 } = {}) {
-    if (!(padding >= 0)) fail('View', `frame() padding is the margin around, as a fraction of the size (0.2 = 20%), got ${describe(padding)}`)
-    if (padding >= 1) warnOnce(this, `frame() padding ${padding} leaves a margin of ${Math.round(padding * 100)}% - it is a fraction of the size (0.2 = 20%)`)
     checkRange('View', 'frame() duration', duration, 0)
     const cam = /** @type {any} */ (this.camera)
     const from = placeOf(cam)
     this.#flight = null
-    const direction = towards === undefined ? cam.position.clone().sub(cam.target ?? new Vec3()).normalize()
-      : typeof towards === 'string' ? presetDirection(/** @type {CameraPreset} */ (towards)) : Vec3.fromInput(towards, 'View').normalize()
-    if (towards !== undefined && !(direction.len() > 0)) fail('View', `frame() direction is a preset name or a vector from the target towards the camera, got ${describe(towards)}`)
-    if (direction.len() === 0) direction.set(0, 0.3, 1).normalize()
-    const points = target instanceof Box3 ? corners(target) : this.#drawnPoints(target, direction)
+    const fit = this.#fit('frame', target, padding, towards)
     // an explicit frame replaces the preset camera's fit on the first frame
     this.#autoFrame = false
-    if (!points.length) return this
-    const ortho = cam.constructor.type === 'orthographic-camera'
-    const { center, size } = fitPoints(points, direction, { aspect: cam.aspect, fov: ortho ? undefined : cam.fov, padding })
-    const radius = Math.max(1e-3, ...points.map((p) => Math.hypot(p[0] - center[0], p[1] - center[1], p[2] - center[2])))
-    if (ortho) {
-      cam.height = size
-      cam.position.copy(center).add(direction.clone().multiplyScalar(radius * 4))
-      cam.far = Math.max(cam.far, radius * 10)
-    } else {
-      const distance = size
-      cam.position.copy(center).add(direction.clone().multiplyScalar(distance))
-      // keep the near/far range sensible for the model's size
-      cam.near = Math.max(1e-3, distance / 1000)
-      cam.far = Math.max(cam.far, distance * 10)
-    }
-    cam.target = center
+    if (!fit) return this
+    setPlace(cam, fit.place)
+    cam.near = fit.near ?? cam.near
+    cam.far = Math.max(cam.far, fit.far)
     // framed for the canvas as it is now
     this.#designed = cam.aspect
     this.#applied = 1
-    if (duration > 0) {
+    if (duration > 0 && !this.reducedMotion) {
       // the camera starts where it was and glides there, frame by frame
       this.#flight = { from, to: placeOf(cam), time: 0, duration }
       setPlace(cam, from)
@@ -538,6 +593,56 @@ export class View {
     return this
   }
 
+  /**
+   * Where frame() would put the camera, without moving it: its position, target and - for an
+   * orthographic camera - height, or null when there is nothing to frame. For a camera of your own
+   * that eases after something moving rather than jumping each frame:
+   *
+   *     const aim = view.framing(debris)
+   *     if (aim) {
+   *       view.camera.position.lerp(aim.position, 0.1)
+   *       view.camera.target.lerp(aim.target, 0.1)
+   *     }
+   * @param {Node | Box3} [target] (default the scene)
+   * @param {{ padding?: number, direction?: CameraPreset | Vec3Input }} [options] as frame()
+   * @returns {{ position: Vec3, target: Vec3, height?: number } | null}
+   */
+  framing(target = this.scene, { padding = 0.2, direction } = {}) {
+    const fit = this.#fit('framing', target, padding, direction)
+    if (!fit) return null
+    const { position, target: at, height } = fit.place
+    return height === undefined ? { position, target: at } : { position, target: at, height }
+  }
+
+  /**
+   * The camera's place to frame something, worked out without moving it - for frame() and framing().
+   * @param {string} method its caller, for errors @param {Node | Box3} target @param {number} padding
+   * @param {CameraPreset | Vec3Input | undefined} towards
+   * @returns {{ place: Place, near: number | undefined, far: number } | null}
+   */
+  #fit(method, target, padding, towards) {
+    if (!(padding >= 0)) fail('View', `${method}() padding is the margin around, as a fraction of the size (0.2 = 20%), got ${describe(padding)}`)
+    if (padding >= 1) warnOnce(this, `${method}() padding ${padding} leaves a margin of ${Math.round(padding * 100)}% - it is a fraction of the size (0.2 = 20%)`)
+    const cam = /** @type {any} */ (this.camera)
+    const direction = towards === undefined ? cam.position.clone().sub(cam.target ?? new Vec3()).normalize()
+      : typeof towards === 'string' ? presetDirection(/** @type {CameraPreset} */ (towards)) : Vec3.fromInput(towards, 'View').normalize()
+    if (towards !== undefined && !(direction.len() > 0)) fail('View', `${method}() direction is a preset name or a vector from the target towards the camera, got ${describe(towards)}`)
+    if (direction.len() === 0) direction.set(0, 0.3, 1).normalize()
+    const points = target instanceof Box3 ? corners(target) : this.#drawnPoints(target, direction)
+    if (!points.length) return null
+    const ortho = cam.constructor.type === 'orthographic-camera'
+    const { center, size } = fitPoints(points, direction, { aspect: cam.aspect, fov: ortho ? undefined : cam.fov, padding })
+    const radius = Math.max(1e-3, ...points.map((p) => Math.hypot(p[0] - center[0], p[1] - center[1], p[2] - center[2])))
+    if (ortho) {
+      return { place: { position: center.clone().add(direction.clone().multiplyScalar(radius * 4)), target: center, height: size },
+        near: undefined, far: radius * 10 }
+    }
+    // keep the near/far range sensible for the model's size
+    const distance = size
+    return { place: { position: center.clone().add(direction.clone().multiplyScalar(distance)), target: center },
+      near: Math.max(1e-3, distance / 1000), far: distance * 10 }
+  }
+
   /**
    * One frame of a glide: round the target as it moves, closing the distance evenly, so the picture
    * turns and zooms rather than cutting through what is in view.
@@ -699,6 +804,21 @@ export class View {
     return new Mat4().multiplyMatrices(camera.projectionMatrix, camera.viewMatrix)
   }
 
+  /**
+   * Everything inside an area of the canvas, nearest first: a box `{ x, y, width, height }` or a
+   * lasso of `[x, y]` points, CSS pixels from the canvas's top left. Each point, instance and line
+   * segment is its own hit, found by where it is (a mesh by its middle) - hidden behind others or
+   * not - so a box dragged over a scatter selects that region of it.
+   *
+   *     const picked = view.pickArea({ x: 40, y: 30, width: 200, height: 120 }).map((h) => h.datum)
+   * @param {import('./area.js').PickArea} area
+   * @returns {Hit[]}
+   */
+  pickArea(area) {
+    this.scene.updateWorldTree()
+    return pickArea(this.scene, this.camera, this.#viewProjection(), this.#width, this.#height, area)
+  }
+
   /** Every hit under a canvas position, nearest first. @param {number | MouseEvent} x @param {number} [y] @returns {Hit[]} */
   pickAll(x, y) {
     if (typeof x === 'object') {
@@ -774,6 +894,39 @@ export class View {
     })
   }
 
+  /** @param {true | KeyboardOptions} options */
+  #loadKeyboard(options) {
+    if (options !== true && (typeof options !== 'object' || options === null || Array.isArray(options))) {
+      fail('View', `'keyboard' is true, false or { label: (hit) => text }, got ${describe(options)}`)
+    }
+    const o = options === true ? {} : options
+    checkOptions('View', o, ['label'], { describe: "use 'label: (hit) => text'", text: "use 'label: (hit) => text'" }, 'keyboard')
+    if (o.label !== undefined && typeof o.label !== 'function') fail('View', `keyboard.label is a function (hit) => text, got ${describe(o.label)}`)
+    import('./keyboard.js').then(({ Keyboard }) => {
+      if (this.#disposed) return
+      this.#keyboard = new Keyboard(this, {
+        focus: (hit) => {
+          this.#keyFocus = hit
+          this.#pickPending = true
+          this.invalidate()
+        },
+        press: (hit) => {
+          for (const fn of handlersAbove(hit.node, 'click')) fn(hit)
+          for (const fn of this.#handlers.click) fn(hit, null)
+        },
+        tooltip: (hit) => this.#tooltipFor(hit)?.(hit),
+        viewWide: () => this.#handlers.hover.size > 0 || this.#handlers.click.size > 0 || !!this.#tooltipContent,
+      }, o)
+      this.#keyboard.setDescription(this.#description)
+    })
+  }
+
+  /** Where the keyboard's focus shows - its middle, on screen - in place of the pointer. @param {Hit} hit */
+  #keyAt(hit) {
+    const { x, y } = this.project(hit.point), rect = this.canvas.getBoundingClientRect()
+    return { x, y, clientX: rect.left + x, clientY: rect.top + y, event: null }
+  }
+
   /** The nearest node tooltip above the hit, or the View's. @param {Hit} hit */
   #tooltipFor(hit) {
     for (let n = /** @type {any} */ (hit.node); n; n = n.parent) if (n.tooltip) return n.tooltip
@@ -822,7 +975,8 @@ export class View {
       sharedContext: this.renderer.shared,
       frame, labels: this.#labelStats, bounds: drawn, nodes, autoLight: this.autoLight,
       contextLost: !!this.renderer.gl?.isContextLost?.(),
-      interaction: { hover: this.#handlers.hover.size, click: this.#handlers.click.size, tooltip: !!this.#tooltipContent, highlight: !!this.#highlight },
+      interaction: { hover: this.#handlers.hover.size, click: this.#handlers.click.size, tooltip: !!this.#tooltipContent, highlight: !!this.#highlight,
+        keyboard: !!this.#keyboard, reducedMotion: this.reducedMotion, description: this.canvas.getAttribute?.('aria-label') ?? this.#description },
     })
   }
 
@@ -839,6 +993,8 @@ export class View {
     this.controls?.dispose()
     this.#labels.dispose()
     this.#tooltip?.dispose()
+    this.#keyboard?.dispose()
+    if (this.#description !== null && !this.#keyboard) this.description = null
     this.renderer.dispose(this.scene)
     if (this.#ownContext) ownContexts--
     if (this.#ownCanvas) this.canvas.remove()
@@ -879,6 +1035,7 @@ export class View {
       if (this.#running) {
         this.time += dt
         this.#onFrame?.(dt, this.time)
+        this.scene.motionReduced = this.reducedMotion
         this.scene.update(dt, this.time)
       }
       this.#updateControls(dt)
@@ -904,6 +1061,8 @@ export class View {
     this.#pickPending = false
     if (!this.#needsHover()) return
     const p = this.#pointer
+    // what the keyboard stepped to is shown until the pointer moves
+    if (this.#keyFocus) return this.#setHovered(this.#keyFocus, this.#keyAt(this.#keyFocus))
     if (this.#labelHover) return this.#setHovered(this.#labelHover)
     if (!p || this.#dragging) return this.#setHovered(null)
     const frame = this.#gpuFrame()
@@ -924,9 +1083,11 @@ export class View {
     })
   }
 
-  /** @param {Hit | null} hit */
-  #setHovered(hit) {
-    const p = this.#pointer
+  /**
+   * @param {Hit | null} hit
+   * @param {{ clientX: number, clientY: number, event: PointerEvent | null } | null} [p] where it is shown - the pointer, or the keyboard's focus
+   */
+  #setHovered(hit, p = this.#pointer) {
     const before = this.#hovered
     // the same thing under the pointer: the same node, instance and row of data - a line's segments
     // and a surface's rows are told apart by their data, without a plain mesh changing per triangle
@@ -980,13 +1141,16 @@ export class View {
   /** @param {Hit | null} hit @returns {FrameHighlight | null} */
   #highlightFor(hit) {
     if (!hit) return null
-    // the nearest colour wins, and the nearest highlightWhole is what is tinted as one
+    // the nearest colour wins - or the nearest false, which tints nothing - and the nearest
+    // highlightWhole is what is tinted as one
     let color = null, whole = null
     for (let n = /** @type {any} */ (hit.node); n; n = n.parent) {
       color ??= n.highlight
       whole ??= n.highlightWhole ? n : null
     }
     color ??= this.#highlight
+    // the keyboard's focus always shows
+    if (!color && hit === this.#keyFocus) color = FOCUS_COLOR
     if (!color) return null
     const node = /** @type {any} */ (hit.node)
     if (whole) {
@@ -1003,17 +1167,19 @@ export class View {
   /** @param {FrameDescription} frame */
   #occlude(frame) {
     const labels = /** @type {(import('./frame.js').FrameLabel & { occluded?: boolean })[]} */ (frame.labels)
-    if (!labels.some((l) => l.style.occlude && l.visible)) return
-    // what this frame drew hides what is behind it - the same surfaces the picture shows
+    // a label waiting to be zoomed in to won't show either way, so it needs no ray
+    const halfHeight = this.height / 2
+    const testing = labels.filter((l) => l.style.occlude && l.visible && !(l.style.minScale && l.scale * halfHeight < l.style.minScale))
+    if (!testing.length) return
+    // what this frame drew hides what is behind it - the same surfaces the picture shows, each placed
+    // once for all the rays, which ask only whether anything is nearer than their label
+    const solids = Raycaster.solids([...frame.opaque, ...frame.transparent])
     const raycaster = new Raycaster()
-    const drawn = [...frame.opaque, ...frame.transparent]
-    for (const label of labels) {
-      if (!label.style.occlude || !label.visible) continue
+    for (const label of testing) {
       raycaster.setFromCamera(label.ndc, this.camera)
       const distance = label.position.distanceTo(raycaster.ray.origin)
       // only solid surfaces hide labels, and not the instance or point being labelled
-      const blocker = raycaster.intersectDrawn(drawn).find((h) => !(h.node === label.node && (label.index === null || h.instance === label.index)))
-      label.occluded = !!blocker && blocker.distance < distance * 0.995
+      label.occluded = raycaster.blocked(solids, distance * 0.995, label.node, label.index)
     }
   }
 
@@ -1024,6 +1190,8 @@ export class View {
       return { x: e.clientX - rect.left, y: e.clientY - rect.top, clientX: e.clientX, clientY: e.clientY, event: e }
     }
     const move = (e) => {
+      // the pointer takes over from the keyboard
+      if (this.#keyFocus) this.#keyboard?.clear()
       this.#pointer = at(e)
       const press = this.#press
       if (press && press.id === e.pointerId && !press.moved && Math.hypot(this.#pointer.x - press.x, this.#pointer.y - press.y) >= DRAG_START) press.moved = true
@@ -1110,6 +1278,17 @@ export class View {
       resize.observe(canvas)
       this.#cleanup.push(() => resize.disconnect())
     }
+    // the system's reduced-motion setting, followed as it changes
+    const motion = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)')
+    if (motion) {
+      const follow = () => {
+        this.#systemReduced = motion.matches
+        this.invalidate()
+      }
+      this.#systemReduced = motion.matches
+      motion.addEventListener?.('change', follow)
+      this.#cleanup.push(() => motion.removeEventListener?.('change', follow))
+    }
     // an off-screen view (a dashboard tile scrolled away) does no work at all
     if (typeof IntersectionObserver !== 'undefined') {
       const visible = new IntersectionObserver(([entry]) => {