phoria2 1.1.0 → 1.2.0

package/src/frame.js

@@ -6,6 +6,7 @@ import { Box3 } from './value/Box3.js'
 import { warnOnce } from './validate.js'
 import { fitPointShadow, fitShadow, fitSpotShadow, SPOT_TILES } from './shadow.js'
 import { worldPlane } from './clip.js'
+import { hiddenInstance } from './scene/drawables.js'
 
 /** @import { Scene } from './scene/Scene.js' */
 /** @import { Camera } from './scene/cameras.js' */
@@ -89,6 +90,8 @@ export const LIGHT_LIMITS = { punctual: 4, directional: 2 }
  * @property {[number, number]} ndc [x, y] in -1..1
  * @property {number} depth
  * @property {boolean} visible in front of the camera and inside the view
+ * @property {number} scale how far zoomed in at the point: half the view's height, in world units, is 1 / scale -
+ *   the layer turns it into pixels to one world unit, for minScale
  */
 
 /**
@@ -239,13 +242,13 @@ export function collect(scene, camera) {
           else capped.set(item.clip, [item])
         }
         frame.stats.drawn++
-        if (node.labels) instanceLabels(node, viewProjection, view, frame.labels)
+        if (node.labels) instanceLabels(node, viewProjection, view, projection[5], frame.labels)
       } else {
         frame.stats.culled++
       }
     } else if (node.isLabel) {
       const position = node.worldPosition
-      frame.labels.push({ key: node, node, index: null, text: node.text, style: node, position, ...project(position, viewProjection, view) })
+      frame.labels.push({ key: node, node, index: null, text: node.text, style: node, position, ...project(position, viewProjection, view, projection[5]) })
     } else if (node.lightKind) {
       addLight(/** @type {Light} */ (node))
     }
@@ -323,7 +326,7 @@ export function collect(scene, camera) {
   if (items.length && sun >= 0) {
     const light = frame.lights[sun]
     const bounds = (/** @type {any} */ n) => n.expandBounds(new Box3())
-    const fit = fitShadow(/** @type {Vec3} */ (light.direction), items.map((c) => bounds(c.node)), receivers.map(bounds))
+    const fit = fitShadow(/** @type {Vec3} */ (light.direction), items.map((c) => bounds(c.node)), receivers.map(bounds), undefined, /** @type {any} */ (light.node).shadowBounds)
     if (fit) {
       frame.lights.splice(sun, 1)
       frame.lights.unshift(light)
@@ -392,10 +395,22 @@ let nextId = 1
 
 /**
  * Labels for every instance or point that has text, from the node's `labels` option.
- * @param {any} node InstancedMesh or Points @param {Mat4} viewProjection @param {Mat4} view @param {FrameLabel[]} out
+ * @param {any} node InstancedMesh or Points @param {Mat4} viewProjection @param {Mat4} view
+ * @param {number} yScale the projection's vertical scale @param {FrameLabel[]} out
  */
-function instanceLabels(node, viewProjection, view, out) {
-  const { labels, worldMatrix: w } = node
+function instanceLabels(node, viewProjection, view, yScale, out) {
+  // several labels per instance: the first keeps the plain key, so a single set's labels don't change identity
+  if (Array.isArray(node.labels)) {
+    node.labels.forEach((labels, layer) => instanceLabelSet(node, labels, layer, viewProjection, view, yScale, out))
+  } else instanceLabelSet(node, node.labels, 0, viewProjection, view, yScale, out)
+}
+
+/**
+ * @param {any} node @param {any} labels one set of instance labels @param {number} layer its place in the list
+ * @param {Mat4} viewProjection @param {Mat4} view @param {number} yScale @param {FrameLabel[]} out
+ */
+function instanceLabelSet(node, labels, layer, viewProjection, view, yScale, out) {
+  const { worldMatrix: w } = node
   let id = ids.get(node)
   if (id === undefined) ids.set(node, id = nextId++)
   const instanced = 'instanceMatrices' in node
@@ -409,6 +424,8 @@ function instanceLabels(node, viewProjection, view, out) {
   const data = Array.isArray(node.data) ? node.data : null
   const byRow = typeof labels.priority === 'function'
   for (let i = 0; i < n; i++) {
+    // an instance scaled to nothing is hidden, and so is its label
+    if (instanced && hiddenInstance(node.instanceMatrices, i)) continue
     const row = data ? data[i] : null
     const text = labels.text(row, i)
     if (text === null || text === undefined || text === '') continue
@@ -427,7 +444,7 @@ function instanceLabels(node, viewProjection, view, out) {
       w[1] * x + w[5] * y + w[9] * z + w[13],
       w[2] * x + w[6] * y + w[10] * z + w[14])
     const style = byRow ? { ...labels, priority: labels.priority(row, i) } : labels
-    out.push({ key: `${id}:${i}`, node, index: i, text: String(text), style, position, ...project(position, viewProjection, view) })
+    out.push({ key: layer ? `${id}:${i}:${layer}` : `${id}:${i}`, node, index: i, text: String(text), style, position, ...project(position, viewProjection, view, yScale) })
   }
 }
 
@@ -453,10 +470,13 @@ export function toScreen(position, viewProjection) {
  * units, for both kinds of camera (an orthographic one's clip w is always 1).
  * @param {Vec3} position @param {Mat4} viewProjection @param {Mat4} view
  */
-function project(position, viewProjection, view) {
+function project(position, viewProjection, view, yScale) {
   const { ndc, visible } = toScreen(position, viewProjection)
   const depth = -(view[2] * position[0] + view[6] * position[1] + view[10] * position[2] + view[14])
-  return { ndc: /** @type {[number, number]} */ ([ndc[0], ndc[1]]), depth, visible }
+  // clip w at the point: its depth for a perspective camera, 1 for an orthographic one
+  const m = viewProjection
+  const w = m[3] * position[0] + m[7] * position[1] + m[11] * position[2] + m[15]
+  return { ndc: /** @type {[number, number]} */ ([ndc[0], ndc[1]]), depth, visible, scale: w > 0 ? yScale / w : 0 }
 }
 
 // The six planes (a, b, c, d with the normal pointing inwards) of a view-projection matrix.

package/src/geometry/Geometry.js

@@ -45,6 +45,8 @@ export class Geometry {
 
   /** @type {Float32Array | null} */
   #normals = null
+  /** The normals were worked out on first read, rather than given or asked for: they follow the shape. */
+  #autoNormals = false
   /** @type {Box3 | null} */
   #bounds = null
   /** @type {Set<() => void>} */
@@ -75,16 +77,22 @@ export class Geometry {
 
   /**
    * xyz per vertex. Computed (smooth) from the triangles on first read when not supplied, so
-   * points and lines - whose geometry has no triangles - never pay for them.
+   * points and lines - whose geometry has no triangles - never pay for them - and computed again after
+   * needsUpdate(), so they follow positions edited in place. Normals that were supplied, assigned or
+   * made by calling computeNormals() are kept as they are.
    * @type {Float32Array}
    */
   get normals() {
-    if (!this.#normals) this.computeNormals()
+    if (!this.#normals) {
+      this.computeNormals()
+      this.#autoNormals = true
+    }
     return /** @type {Float32Array} */ (this.#normals)
   }
 
   set normals(v) {
     this.#normals = v
+    this.#autoNormals = false
   }
 
   /** True once normals exist, supplied or computed. */
@@ -121,9 +129,14 @@ export class Geometry {
     return this.#bounds ??= new Box3().expandByPositions(this.positions)
   }
 
-  /** Call after editing the arrays in place. It is no longer what its generator made, so toJSON() saves the arrays. @returns {this} */
+  /**
+   * Call after editing the arrays in place. It is no longer what its generator made, so toJSON() saves
+   * the arrays; normals that were worked out on first read are worked out again on the next.
+   * @returns {this}
+   */
   needsUpdate() {
     this.source = null
+    if (this.#autoNormals) this.#normals = null
     return this.#changed()
   }
 

package/src/keyboard.js

@@ -0,0 +1,298 @@
+// Keyboard use of a View, for people who can't use a pointer and for screen readers: the canvas
+// becomes a stop in the page's tab order, and the arrow keys step through what you can act on - each
+// instance, point or node with a tooltip, a handler or data - as hovering would: the hover tint, the
+// tooltip and hover handlers, with Enter or Space as a click. A live region says what each one is.
+// Loaded when a View is given keyboard: true, so apps without it don't carry it.
+import { hiddenInstance } from './scene/drawables.js'
+import { Vec3 } from './value/Vec3.js'
+
+/** @import { Hit } from './Raycaster.js' */
+/** @import { TooltipContent } from './tooltip.js' */
+/** @import { Node } from './scene/Node.js' */
+/** @import { View } from './View.js' */
+
+/**
+ * @typedef {object} KeyboardOptions
+ * @property {(hit: Hit) => string} [label] what a screen reader says for each thing stepped to (default: the
+ *   tooltip's text, then its data, then the node's name)
+ */
+
+/**
+ * What the View lends the keyboard: the hover it shows, the click it runs, and what it says about a hit.
+ * @typedef {object} KeyboardHooks
+ * @property {(hit: Hit | null) => void} focus show this as hovered, or nothing
+ * @property {(hit: Hit) => void} press click it
+ * @property {(hit: Hit) => TooltipContent} tooltip the tooltip's content for it, if there is a tooltip
+ * @property {() => boolean} viewWide does the View itself answer hovers or clicks (a tooltip, handlers)?
+ */
+
+/** @typedef {{ node: Node, index: number | null, whole: Node | null }} Item */
+
+const STYLE = `:where(.phoria-sr-only) { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; border: 0; }`
+// how far PageUp and PageDown jump
+const PAGE = 10
+let ids = 0
+
+export class Keyboard {
+  /** @type {View} */ #view
+  /** @type {KeyboardHooks} */ #hooks
+  /** @type {KeyboardOptions} */ #options
+  /** The item stepped to, or null. @type {Item | null} */ #at = null
+  /** @type {HTMLDivElement} */ #say
+  /** @type {HTMLDivElement} */ #help
+  /** Attributes the canvas had before, put back on dispose. @type {[string, string | null][]} */ #before
+  #description = ''
+  #auto = true
+  /** @type {(() => void)[]} */ #cleanup = []
+
+  /** @param {View} view @param {KeyboardHooks} hooks @param {KeyboardOptions} options */
+  constructor(view, hooks, options) {
+    this.#view = view
+    this.#hooks = hooks
+    this.#options = options
+    if (!document.getElementById('phoria-sr-style')) {
+      const style = document.createElement('style')
+      style.id = 'phoria-sr-style'
+      style.textContent = STYLE
+      document.head.prepend(style)
+    }
+    const canvas = view.canvas, id = `phoria-keys-${++ids}`
+    // what a screen reader says as you step: politely, after what it's saying already
+    this.#say = document.createElement('div')
+    this.#say.className = 'phoria-sr-only'
+    this.#say.setAttribute('aria-live', 'polite')
+    this.#say.setAttribute('aria-atomic', 'true')
+    // how to use it, read once the canvas has focus
+    this.#help = document.createElement('div')
+    this.#help.className = 'phoria-sr-only'
+    this.#help.id = id
+    canvas.after(this.#say, this.#help)
+    this.#before = ['tabindex', 'role', 'aria-roledescription', 'aria-label', 'aria-describedby'].map((a) => [a, canvas.getAttribute(a)])
+    if (!canvas.hasAttribute('tabindex')) canvas.tabIndex = 0
+    canvas.setAttribute('role', 'application')
+    canvas.setAttribute('aria-roledescription', '3D view')
+    canvas.setAttribute('aria-describedby', id)
+
+    const keydown = (/** @type {KeyboardEvent} */ e) => this.#key(e)
+    const blur = () => this.clear()
+    const focus = () => this.#describe()
+    canvas.addEventListener('keydown', keydown)
+    canvas.addEventListener('blur', blur)
+    canvas.addEventListener('focus', focus)
+    this.#cleanup.push(() => {
+      canvas.removeEventListener('keydown', keydown)
+      canvas.removeEventListener('blur', blur)
+      canvas.removeEventListener('focus', focus)
+    })
+    this.#describe()
+  }
+
+  /**
+   * 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) {
+    this.#auto = text === null
+    this.#description = text ?? ''
+    this.#describe()
+  }
+
+  #describe() {
+    const count = this.#items().length
+    const label = this.#auto ? autoDescription(this.#view.scene, count) : this.#description
+    this.#view.canvas.setAttribute('aria-label', label)
+    this.#help.textContent = count
+      ? `Use the arrow keys to move between ${count === 1 ? 'the one item' : `${count} items`}, Enter to select, Escape to leave.`
+      : 'Nothing here can be selected.'
+  }
+
+  /** Step off whatever was stepped to: the pointer has taken over, or focus has gone. */
+  clear() {
+    if (!this.#at) return
+    this.#at = null
+    this.#hooks.focus(null)
+  }
+
+  /** @param {KeyboardEvent} e */
+  #key(e) {
+    if (e.altKey || e.ctrlKey || e.metaKey) return
+    const items = this.#items()
+    let i = this.#at ? items.findIndex((it) => same(it, /** @type {Item} */ (this.#at))) : -1
+    switch (e.key) {
+      case 'ArrowRight': case 'ArrowDown': i = i < 0 ? 0 : Math.min(items.length - 1, i + 1); break
+      case 'ArrowLeft': case 'ArrowUp': i = i < 0 ? items.length - 1 : Math.max(0, i - 1); break
+      case 'PageDown': i = Math.min(items.length - 1, Math.max(0, i) + PAGE); break
+      case 'PageUp': i = Math.max(0, i - PAGE); break
+      case 'Home': i = 0; break
+      case 'End': i = items.length - 1; break
+      case 'Enter': case ' ':
+        if (!this.#at || i < 0) return
+        e.preventDefault()
+        this.#hooks.press(hitOf(items[i]))
+        return
+      case 'Escape':
+        if (!this.#at) return
+        e.preventDefault()
+        this.clear()
+        this.#say.textContent = ''
+        return
+      default: return
+    }
+    // the arrows and paging keys are the view's while it has focus, not the page's to scroll
+    e.preventDefault()
+    if (!items.length) {
+      this.#say.textContent = 'Nothing here can be selected.'
+      return
+    }
+    this.#at = items[i]
+    const hit = hitOf(items[i])
+    this.#hooks.focus(hit)
+    this.#say.textContent = `${this.#options.label?.(hit) ?? this.#textOf(hit)}. ${i + 1} of ${items.length}`
+  }
+
+  /** What to say about a hit: the tooltip's text, its data, or its node's name. @param {Hit} hit @returns {string} */
+  #textOf(hit) {
+    const tip = textOfContent(this.#hooks.tooltip(hit))
+    if (tip) return tip
+    const datum = hit.datum
+    if (datum !== null && datum !== undefined) {
+      if (typeof datum !== 'object') return String(datum)
+      const parts = Object.entries(datum).filter(([, v]) => v === null || typeof v !== 'object').slice(0, 4).map(([k, v]) => `${k}: ${format(v)}`)
+      if (parts.length) return parts.join(', ')
+    }
+    for (let n = /** @type {Node | null} */ (hit.node); n; n = n.parent) if (n.name) return n.name
+    return 'Item'
+  }
+
+  /**
+   * What can be stepped to, in scene order and each mesh's instances in order: everything visible and
+   * pickable in a subtree with its own tooltip, handlers, drag or tint - and, when the View answers
+   * hovers or clicks itself, each thing with data or a name. A highlightWhole subtree is one item, and
+   * a surface - a mesh with a row of data per vertex - is a stop per vertex, as picking gives its rows.
+   * Lines with a row per segment - a network's links - are a stop per segment, after everything else:
+   * the things first, then what joins them. Something with no row and no name of its own is a stop
+   * only when it has a handler or tooltip itself, not one it shares with the subtree it's in.
+   * @returns {Item[]}
+   */
+  #items() {
+    /** @type {Item[]} */
+    const items = [], links = []
+    const viewWide = this.#hooks.viewWide()
+    /** @type {Set<Node>} */
+    const wholes = new Set()
+    /** @param {any} n @param {boolean} own @param {Node | null} whole */
+    const walk = (n, own, whole) => {
+      if (!n.visible || n.pickable === false) return
+      const direct = !!(n.tooltip || n.onDrag || n.highlight || n.handlersFor('click').length || n.handlersFor('hover').length)
+      own ||= direct
+      whole = n.highlightWhole ? n : whole
+      if (n.isDrawable) {
+        if (whole) {
+          if ((own || viewWide) && !wholes.has(whole)) {
+            wholes.add(whole)
+            items.push({ node: n, index: null, whole })
+          }
+        } else if ('instanceMatrices' in n) {
+          for (let i = 0; i < n.count; i++) {
+            if (!hiddenInstance(n.instanceMatrices, i) && (own || (viewWide && n.datumAt(i) !== null))) items.push({ node: n, index: i, whole: null })
+          }
+        } else if ((n.drawMode === 'points' && Array.isArray(n.data)) || perVertex(n)) {
+          for (let i = 0; i < n.data.length; i++) if (own || viewWide) items.push({ node: n, index: i, whole: null })
+        } else if (n.drawMode === 'lines' && Array.isArray(n.data)) {
+          for (let i = 0; i < n.data.length; i++) if (own || viewWide) links.push({ node: n, index: i, whole: null })
+        } else if (direct || ((own || viewWide) && (n.name || n.datumAt(null) !== null))) items.push({ node: n, index: null, whole: null })
+      }
+      for (const c of n.children) walk(c, own, whole)
+    }
+    walk(this.#view.scene, false, null)
+    return items.concat(links)
+  }
+
+  dispose() {
+    for (const fn of this.#cleanup) fn()
+    const canvas = this.#view.canvas
+    for (const [name, value] of this.#before) {
+      if (value === null) canvas.removeAttribute(name)
+      else canvas.setAttribute(name, value)
+    }
+    this.#say.remove()
+    this.#help.remove()
+  }
+}
+
+/** @param {Item} a @param {Item} b */
+const same = (a, b) => a.node === b.node && a.index === b.index
+
+/** A surface: a mesh of triangles with a row of data for each vertex. @param {any} n */
+const perVertex = (n) => n.drawMode === 'triangles' && !('instanceMatrices' in n) && Array.isArray(n.data) && n.data.length === n.geometry.vertexCount
+
+/**
+ * A hit on an item, as the pointer would make over its middle.
+ * @param {Item} item @returns {Hit}
+ */
+function hitOf({ node, index, whole }) {
+  const d = /** @type {any} */ (node)
+  const points = index !== null && d.drawMode === 'points', vertex = index !== null && perVertex(d)
+  const segment = index !== null && d.drawMode === 'lines'
+  /** @type {Vec3} */
+  let point
+  if (whole) point = whole.bounds.getCenter()
+  else if (index !== null && 'instanceMatrices' in d) {
+    // the middle of the geometry, through the instance's matrix and then the mesh's
+    node.updateWorld()
+    const local = d.geometry.bounds.getCenter()
+    point = through(d.worldMatrix, through(d.instanceMatrices.subarray(index * 16, index * 16 + 16), local))
+  } else if (points || vertex) {
+    const p = d.geometry.positions
+    node.updateWorld()
+    point = through(d.worldMatrix, new Vec3(p[index * 3], p[index * 3 + 1], p[index * 3 + 2]))
+  } else if (segment) {
+    // the middle of the segment: its two ends, by index when the lines have them
+    const p = d.geometry.positions, idx = d.geometry.indices
+    const a = idx ? idx[index * 2] : index * 2, b = idx ? idx[index * 2 + 1] : index * 2 + 1
+    node.updateWorld()
+    point = through(d.worldMatrix, new Vec3((p[a * 3] + p[b * 3]) / 2, (p[a * 3 + 1] + p[b * 3 + 1]) / 2, (p[a * 3 + 2] + p[b * 3 + 2]) / 2))
+  } else point = node.bounds.getCenter()
+  // a surface's vertex is no face or instance - its row is the datum, as a pointer over it finds
+  return { node, point, distance: 0, normal: null, face: points || segment ? index : null, instance: index !== null && !points && !vertex && !segment ? index : null,
+    uv: null, datum: vertex ? d.data[index] ?? null : d.datumAt?.(index) ?? null }
+}
+
+/** A point through a 4x4 matrix (column-major). @param {ArrayLike<number>} m @param {Vec3} p @returns {Vec3} */
+function through(m, p) {
+  const [x, y, z] = p
+  return new Vec3(m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14])
+}
+
+/** The text of a tooltip's content, for a screen reader. @param {TooltipContent} content @returns {string} */
+function textOfContent(content) {
+  if (content === null || content === undefined || content === false || content === '') return ''
+  if (typeof content === 'string' || typeof content === 'number') return String(content).replace(/\s*\n\s*/g, ', ')
+  if (typeof globalThis.Node !== 'undefined' && content instanceof globalThis.Node) return (content.textContent ?? '').trim()
+  if (typeof content === 'object') {
+    const c = /** @type {{ title?: string, rows?: Record<string, unknown> | Array<[string, unknown]> }} */ (content)
+    const rows = c.rows ? (Array.isArray(c.rows) ? c.rows : Object.entries(c.rows)).map(([k, v]) => `${k}: ${format(v)}`) : []
+    return [c.title, ...rows].filter((s) => s !== undefined && s !== '').join(', ')
+  }
+  return ''
+}
+
+/** @param {unknown} v */
+const format = (v) => (typeof v === 'number' ? v.toLocaleString() : String(v))
+
+/**
+ * A label for the canvas made from the scene: each chart's summary, or how many things there are.
+ * @param {Node} scene @param {number} count @returns {string}
+ */
+function autoDescription(scene, count) {
+  /** @type {string[]} */
+  const parts = []
+  scene.traverse((n) => {
+    const summary = /** @type {any} */ (n).summary
+    if (n !== scene && n.visible && typeof summary === 'function') parts.push(summary.call(n))
+  })
+  if (!parts.length) parts.push(count ? `3D view of ${count === 1 ? 'one item' : `${count} items`}` : '3D view')
+  return parts.join('. ')
+}

package/src/labels.js

@@ -14,6 +14,7 @@ import { alignColumns, layoutLabels, leaderEnd, placeBox, stackColumns } from '.
  * @property {number} dimmed drawn faint because a higher-priority label or geometry was in front (overlap: 'dim')
  * @property {number} occluded hidden because geometry was in front (overlap: 'hide')
  * @property {number} offscreen behind the camera or outside the view
+ * @property {number} zoomedOut hidden because the view isn't zoomed in to their minScale
  */
 
 /** @typedef {{ el: HTMLDivElement, text: string, className: string, width: number, height: number, showing: boolean, leader: SVGGElement | null, color: string, rule: number, label: FrameLabel | null, interactive: boolean }} Entry */
@@ -67,7 +68,7 @@ export class LabelLayer {
    */
   update(labels, overlays = []) {
     /** @type {LabelStats} */
-    const stats = { total: labels.length, shown: 0, overlapped: 0, dimmed: 0, occluded: 0, offscreen: 0 }
+    const stats = { total: labels.length, shown: 0, overlapped: 0, dimmed: 0, occluded: 0, offscreen: 0, zoomedOut: 0 }
     this.shown = []
     this.leaders = []
     if (!labels.length && !this.#elements.size && !overlays.length && !this.#overlays.size && !this.#root) return stats
@@ -83,6 +84,8 @@ export class LabelLayer {
     for (const label of labels) {
       seen.add(label.key)
       if (!label.visible) stats.offscreen++
+      // details for closer up: until then they take no part, so they can't push other labels out
+      else if (label.style.minScale && label.scale * rect.height / 2 < label.style.minScale) stats.zoomedOut++
       else if (label.occluded && label.style.overlap === 'hide') stats.occluded++
       else active.push({ label, entry: this.#entry(label, root) })
     }

package/src/scene/Node.js

@@ -10,7 +10,7 @@ import { Vec3 } from '../value/Vec3.js'
 import { checkOptions, describe, fail } from '../validate.js'
 import { Clip } from '../clip.js'
 
-/** @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' */
@@ -44,7 +44,7 @@ import { Clip } from '../clip.js'
  * @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)
@@ -54,7 +54,8 @@ import { Clip } from '../clip.js'
  * @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
@@ -136,7 +137,7 @@ export class Node {
   onDrag = null
   /** @type {Outline | null} */
   #outline = null
-  /** @type {Color | null} */
+  /** @type {Color | null | false} */
   #highlight = null
   /** Hovering any part of this subtree tints all of it, not just the part under the pointer. */
   highlightWhole = false
@@ -164,7 +165,7 @@ export class Node {
   set rotation(v) { this.#rotation.copy(/** @type {any} */ (v), this.constructor.name) }
   /** Kept in sync with rotation. Assigning copies, normalised. @returns {Quat} */
   get quaternion() { return this.#quaternion }
-  /** @param {ArrayLike<number>} v */
+  /** @param {QuatInput} v */
   set quaternion(v) { this.#quaternion.copy(v, this.constructor.name).normalize() }
 
   /** @param {NodeOptions} [options] */
@@ -191,7 +192,7 @@ export class Node {
       if (typeof fn !== 'function') fail(owner, `'${key}' must be a function, got ${describe(fn)}`)
       this[key] = fn
     }
-    if (options.highlight != null) this.#highlight = Color.fromInput(options.highlight, owner)
+    if (options.highlight != null) this.#setHighlight(options.highlight, owner)
     if (options.highlightWhole !== undefined) {
       if (typeof options.highlightWhole !== 'boolean') fail(owner, `'highlightWhole' must be true or false, got ${describe(options.highlightWhole)}`)
       this.highlightWhole = options.highlightWhole
@@ -201,14 +202,23 @@ export class Node {
     if (options.children) for (const child of options.children) this.add(child)
   }
 
-  /** Hover tint for this subtree, over the View's; set any colour, or null. @returns {Color | 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() {
     return this.#highlight
   }
 
-  /** @param {ColorInput | null} value */
+  /** @param {ColorInput | null | false} value */
   set highlight(value) {
-    this.#highlight = value == null ? null : Color.fromInput(value, this.constructor.name)
+    this.#setHighlight(value, this.constructor.name)
+  }
+
+  /** @param {ColorInput | null | false | true} value @param {string} owner */
+  #setHighlight(value, owner) {
+    if (value === true) fail(owner, "'highlight' is a colour, false for no tint, or null to use the View's - got true")
+    this.#highlight = value == null ? null : value === false ? false : Color.fromInput(value, owner)
   }
 
   /**
@@ -612,6 +622,7 @@ export class Node {
     if (!this.pickable) json.pickable = false
     if (!this.matrixAutoUpdate) json.matrixAutoUpdate = false
     if (this.highlight) json.highlight = this.highlight.getStyle()
+    else if (this.highlight === false) json.highlight = false
     if (this.highlightWhole) json.highlightWhole = true
     if (this.#clip) json.clip = this.#clip.toJSON()
     if (this.#outline) json.outline = { color: this.#outline.color.getStyle(), width: this.#outline.width }

package/src/scene/Scene.js

@@ -44,6 +44,8 @@ export class Scene extends Node {
   environmentIntensity = 1
   /** 0-1: how blurred a panorama background is drawn - a soft backdrop that doesn't compete. */
   backgroundBlur = 0
+  /** @internal Set by the View drawing it, from its reducedMotion: charts' transitions and flows stand still. */
+  motionReduced = false
   /** @type {Fog | null} */
   #fog = null
 

package/src/scene/cameras.js

@@ -20,7 +20,10 @@ const tmp3 = new Float32Array(9)
 export function aimAt(node, target) {
   if (node.position.equals(target, 1e-9)) return
   const dir = target.clone().sub(node.position).normalize()
-  const up = Math.abs(dir[1]) > 0.9999 ? [0, 0, -1] : UP
+  // world up keeps the picture upright, and turns it smoothly with the view right up to straight up
+  // or down - the orbit stops a thousandth of a radian short. Only within a hair of exactly vertical
+  // (the 'top' preset's view), where up would no longer say which way the screen faces, is north up
+  const up = Math.hypot(dir[0], dir[2]) < 5e-4 ? [0, 0, -1] : UP
   mat4.targetTo(tmp, node.position, target, up)
   const q = quat.normalize(new Float32Array(4), quat.fromMat3(new Float32Array(4), mat3.fromMat4(tmp3, tmp)))
   node.quaternion.copy(q)