phoria2 1.1.0 → 1.2.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

@@ -27,6 +27,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 +66,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 +101,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 +174,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 +249,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 +270,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 +349,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 +467,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 +482,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 +521,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 +564,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 +592,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.
@@ -774,6 +878,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 +959,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 +977,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 +1019,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 +1045,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 +1067,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 +1125,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 +1151,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 +1174,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 +1262,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]) => {

package/src/charts/Chart.js

@@ -118,6 +118,22 @@ export class Chart extends Group {
     return `Chart (${s.mark}): ${shown} of ${s.rows.length} rows shown${axes.length ? `; ${axes.join(', ')}` : ''}${s.links.length ? `; ${s.links.length} links` : ''}`
   }
 
+  /**
+   * One sentence about this chart for screen readers - the spec's description, or its title and what
+   * it shows: "Sales by month: bar chart of 12 rows by Month, Sales". A View with keyboard: true labels
+   * its canvas with this.
+   * @returns {string}
+   */
+  summary() {
+    const s = /** @type {ReturnType<typeof normalise>} */ (this.#spec), o = /** @type {any} */ (s.options)
+    if (o.description) return String(o.description)
+    // each field once, though it may set more than one channel (z and colour by region)
+    const by = [...new Set(['x', 'y', 'z', 'color', 'size'].map((k) => /** @type {any} */ (s.channels)[k]).filter((c) => c?.field).map((c) => c.title))]
+    const count = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`
+    const what = `${s.mark} chart of ${count(s.rows.length, 'row')}${by.length ? ` by ${by.join(', ')}` : ''}${s.links.length ? ` and ${count(s.links.length, 'link')}` : ''}`
+    return o.title ? `${o.title}: ${what}` : what
+  }
+
   /** @internal @returns {Record<string, unknown>} */
   jsonOptions() {
     return { ...this.#input }
@@ -305,14 +321,16 @@ export class Chart extends Group {
 
   /** @param {number} dt */
   #step(dt) {
-    this.#mark?.tick?.(dt)
+    // with motion reduced (the View's reducedMotion), flows stand still and a change shows at once
+    const still = /** @type {any} */ (this.root).motionReduced === true
+    if (!still) this.#mark?.tick?.(dt)
     const tw = this.#tween
     if (!tw) return
     const o = this.#input.transition ?? {}
     const duration = o.duration ?? 0.5
     const ease = EASES[o.ease ?? 'out']
     if (!ease) fail('chart()', `transition ease '${o.ease}' - expected ${Object.keys(EASES).map((e) => `'${e}'`).join(', ')}`)
-    tw.t = Math.min(1, tw.t + dt / duration)
+    tw.t = still ? 1 : Math.min(1, tw.t + dt / duration)
     const k = ease(tw.t)
     const state = new Float32Array(tw.from.length)
     for (let i = 0; i < state.length; i++) state[i] = tw.from[i] + (tw.to[i] - tw.from[i]) * k

package/src/explain.js

@@ -22,7 +22,7 @@ import { Box3 } from './value/Box3.js'
  * @property {boolean} autoLight
  * @property {boolean} contextLost
  * @property {boolean} [sharedContext] drawn with the page's shared WebGL context
- * @property {{ hover: number, click: number, tooltip: boolean, highlight: boolean }} interaction
+ * @property {{ hover: number, click: number, tooltip: boolean, highlight: boolean, keyboard?: boolean, reducedMotion?: boolean, description?: string | null }} interaction
  * @property {string[]} [notes] lines from nodes that describe themselves, such as charts
  */
 
@@ -115,7 +115,7 @@ export function explain(info) {
 
   if (info.labels && info.labels.total) {
     const s = info.labels
-    lines.push(`Labels: ${s.shown} shown, ${s.dimmed ? `${s.dimmed} dimmed (covered by labels or geometry), ` : ''}${s.overlapped} hidden by overlap, ${s.occluded} hidden behind geometry, ${s.offscreen} off screen`)
+    lines.push(`Labels: ${s.shown} shown, ${s.dimmed ? `${s.dimmed} dimmed (covered by labels or geometry), ` : ''}${s.overlapped} hidden by overlap, ${s.occluded} hidden behind geometry, ${s.offscreen} off screen${s.zoomedOut ? `, ${s.zoomedOut} waiting to be zoomed in to (minScale)` : ''}`)
     if (s.overlapped > s.shown * 3) warnings.push(`${s.overlapped} labels are hidden by overlap - give the important ones a higher priority, label fewer things, or use overlap: 'dim' or 'show'`)
     if (s.offscreen === s.total) warnings.push('every label is off screen - check their positions, or call view.frame()')
   }
@@ -125,6 +125,10 @@ export function explain(info) {
     lines.push(`Interaction: ${[ix.hover && plural(ix.hover, 'hover handler'), ix.click && plural(ix.click, 'click handler'),
       ix.tooltip && 'tooltip', ix.highlight && 'hover highlight'].filter(Boolean).join(', ')}`)
   }
+  if (ix.keyboard || ix.reducedMotion || ix.description) {
+    lines.push(`Accessibility: ${[ix.keyboard && 'keyboard (arrow keys step through what can be hovered)', ix.reducedMotion && 'reduced motion',
+      ix.description && `described as "${ix.description}"`].filter(Boolean).join(', ')}`)
+  }
 
   if (info.width < 2 || info.height < 2) warnings.unshift(`the canvas is ${info.width} x ${info.height} - give it a size in the page (CSS width and height)`)
   if (info.contextLost) warnings.unshift('the WebGL context is lost - nothing draws until the browser restores it')