phoria2 1.0.0 → 1.2.0

package/src/geometry/Geometry.js

@@ -6,11 +6,13 @@ import { checkOptions, describe, fail } from '../validate.js'
  * @property {ArrayLike<number>} positions xyz per vertex
  * @property {ArrayLike<number>} [normals] xyz per vertex; computed (smooth) when missing
  * @property {ArrayLike<number>} [uvs] uv per vertex - glTF convention, (0, 0) is the image's top left
+ * @property {ArrayLike<number>} [uvs2] a second uv per vertex, for maps that need every surface on its own
+ *   patch of texture - baked occlusion and light maps (a texture's uvSet: 1 reads it)
  * @property {ArrayLike<number>} [colors] rgb per vertex, sRGB 0-1 like every colour input
  * @property {ArrayLike<number>} [indices] vertex indices; triangles for meshes, pairs for lines
  */
 
-const OPTIONS = ['positions', 'normals', 'uvs', 'colors', 'indices']
+const OPTIONS = ['positions', 'normals', 'uvs', 'uvs2', 'colors', 'indices']
 
 /**
  * Vertex data: flat typed arrays plus an optional index. Generators such as box() and sphere()
@@ -21,6 +23,7 @@ export class Geometry {
   static OPTIONS = OPTIONS
   /** @type {Float32Array} */ positions
   /** @type {Float32Array | null} */ uvs = null
+  /** A second UV set, for baked occlusion and light maps. @type {Float32Array | null} */ uvs2 = null
   /** @type {Float32Array | null} */ colors = null
   /** @type {Uint16Array | Uint32Array | null} */ indices = null
 
@@ -42,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>} */
@@ -55,6 +60,7 @@ export class Geometry {
     const n = this.vertexCount
     if (options.normals) this.#normals = toFloat32('normals', options.normals, 3, n)
     if (options.uvs) this.uvs = toFloat32('uvs', options.uvs, 2, n)
+    if (options.uvs2) this.uvs2 = toFloat32('uvs2', options.uvs2, 2, n)
     if (options.colors) this.colors = toFloat32('colors', options.colors, 3, n)
     if (options.indices) {
       // -1: no indices at all refer to no vertex, so an empty geometry can say so
@@ -71,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. */
@@ -117,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()
   }
 
@@ -172,6 +189,7 @@ export class Geometry {
       positions: this.positions,
       normals: this.#normals ?? undefined,
       uvs: this.uvs ?? undefined,
+      uvs2: this.uvs2 ?? undefined,
       colors: this.colors ?? undefined,
       indices: this.indices ?? undefined,
     })
@@ -198,6 +216,7 @@ export class Geometry {
     const json = { positions: Array.from(this.positions) }
     if (this.#normals) json.normals = Array.from(this.#normals)
     if (this.uvs) json.uvs = Array.from(this.uvs)
+    if (this.uvs2) json.uvs2 = Array.from(this.uvs2)
     if (this.colors) json.colors = Array.from(this.colors)
     if (this.indices) json.indices = Array.from(this.indices)
     return json
@@ -221,6 +240,7 @@ export class Geometry {
     }
     this.positions = /** @type {Float32Array} */ (expand(this.positions, 3))
     this.uvs = expand(this.uvs, 2)
+    this.uvs2 = expand(this.uvs2, 2)
     this.colors = expand(this.colors, 3)
     this.indices = null
     this.source = null

package/src/gltf/load.js

@@ -25,7 +25,8 @@ import { Animation } from './Animation.js'
  */
 
 const SUPPORTED = new Set(['KHR_materials_emissive_strength', 'KHR_texture_transform', 'KHR_lights_punctual',
-  'KHR_materials_unlit', 'KHR_mesh_quantization'])
+  'KHR_materials_unlit', 'KHR_mesh_quantization', 'KHR_materials_transmission', 'KHR_materials_clearcoat', 'KHR_materials_sheen',
+  'KHR_materials_ior', 'KHR_materials_specular', 'KHR_materials_anisotropy', 'KHR_materials_diffuse_transmission'])
 const COMPRESSION = new Set(['KHR_draco_mesh_compression', 'EXT_meshopt_compression', 'KHR_texture_basisu'])
 
 const COMPONENTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 }
@@ -266,6 +267,7 @@ class Builder {
     const options = { positions: this.#accessor(a.POSITION) }
     if (a.NORMAL !== undefined) options.normals = this.#accessor(a.NORMAL)
     if (a.TEXCOORD_0 !== undefined) options.uvs = this.#accessor(a.TEXCOORD_0)
+    if (a.TEXCOORD_1 !== undefined) options.uvs2 = this.#accessor(a.TEXCOORD_1)
     if (a.COLOR_0 !== undefined) options.colors = srgbColors(/** @type {Float32Array} */ (this.#accessor(a.COLOR_0)), COMPONENTS[this.json.accessors[a.COLOR_0].type])
     if (p.indices !== undefined) options.indices = this.#accessor(p.indices, true)
     const geometry = new Geometry(options)
@@ -364,6 +366,43 @@ class Builder {
     }
     material.emissiveIntensity = m.extensions?.KHR_materials_emissive_strength?.emissiveStrength ?? 1
     if (m.extensions?.KHR_materials_unlit) material.unlit = true
+    // glass, clear coat, cloth, reflectance, brushed metal and translucency, by their factors - their
+    // own textures aren't read
+    const clamp = (/** @type {number} */ v) => Math.min(Math.max(v, 0), 1)
+    const x = m.extensions ?? {}
+    const transmission = x.KHR_materials_transmission, coat = x.KHR_materials_clearcoat, sheen = x.KHR_materials_sheen
+    if (transmission) material.transmission = clamp(transmission.transmissionFactor ?? 0)
+    if (coat) {
+      material.clearcoat = clamp(coat.clearcoatFactor ?? 0)
+      material.clearcoatRoughness = clamp(coat.clearcoatRoughnessFactor ?? 0)
+    }
+    if (sheen) {
+      const c = sheen.sheenColorFactor ?? [0, 0, 0]
+      // glTF's sheen is its colour alone: black is none
+      if (Math.max(c[0], c[1], c[2]) > 0) {
+        material.sheen = 1
+        material.sheenColor.setLinear(c[0], c[1], c[2])
+      }
+      material.sheenRoughness = clamp(sheen.sheenRoughnessFactor ?? 0)
+    }
+    if (x.KHR_materials_ior?.ior >= 1) material.ior = x.KHR_materials_ior.ior
+    const specular = x.KHR_materials_specular
+    if (specular) {
+      material.specularIntensity = clamp(specular.specularFactor ?? 1)
+      const c = specular.specularColorFactor ?? [1, 1, 1]
+      material.specularColor.setLinear(c[0], c[1], c[2])
+    }
+    const brushed = x.KHR_materials_anisotropy
+    if (brushed) {
+      material.anisotropy = clamp(brushed.anisotropyStrength ?? 0)
+      material.anisotropyRotation = brushed.anisotropyRotation ?? 0
+    }
+    const translucent = x.KHR_materials_diffuse_transmission
+    if (translucent) {
+      material.translucency = clamp(translucent.diffuseTransmissionFactor ?? 0)
+      const c = translucent.diffuseTransmissionColorFactor ?? [1, 1, 1]
+      material.translucencyColor.setLinear(c[0], c[1], c[2])
+    }
     if (m.alphaMode === 'BLEND') {
       material.opacity = base[3]
       material.transparent = true
@@ -390,10 +429,12 @@ class Builder {
    */
   #texture(info, colorSpace) {
     const transform = info.extensions?.KHR_texture_transform
-    const texCoord = transform?.texCoord ?? info.texCoord ?? 0
-    if (texCoord !== 0) warnOnce(this.model, 'textures on a second UV set (TEXCOORD_1) are drawn with the first')
-    if (transform?.rotation) warnOnce(this.model, "rotated texture transforms (KHR_texture_transform rotation) aren't supported - drawn unrotated")
-    const key = JSON.stringify([info.index, colorSpace, transform?.offset, transform?.scale])
+    let texCoord = transform?.texCoord ?? info.texCoord ?? 0
+    if (texCoord > 1) {
+      warnOnce(this.model, `textures on a third UV set or later (TEXCOORD_${texCoord}) are drawn with the first`)
+      texCoord = 0
+    }
+    const key = JSON.stringify([info.index, colorSpace, transform?.offset, transform?.scale, transform?.rotation, texCoord])
     const cached = this.#textures.get(key)
     if (cached) return cached
 
@@ -420,6 +461,8 @@ class Builder {
       flipY: false,
       repeat: transform?.scale ?? [1, 1],
       offset: transform?.offset ?? [0, 0],
+      rotation: transform?.rotation ?? 0,
+      uvSet: texCoord,
     })
     this.#textures.set(key, texture)
     return texture
@@ -538,5 +581,6 @@ function lineList(g, mode) {
 function withIndices(g, indices, triangles) {
   // only normals the file gave - reading g.normals would work them out from the strip's own indices,
   // taken as a triangle list; the new geometry works them out from its real triangles instead
-  return new Geometry({ positions: g.positions, normals: triangles && g.hasNormals ? g.normals : undefined, uvs: g.uvs ?? undefined, colors: g.colors ?? undefined, indices })
+  return new Geometry({ positions: g.positions, normals: triangles && g.hasNormals ? g.normals : undefined, uvs: g.uvs ?? undefined, uvs2: g.uvs2 ?? undefined,
+    colors: g.colors ?? undefined, indices })
 }

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