@things-factory/figure-service 10.1.147 → 10.1.150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.147",
+  "version": "10.1.150",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,18 +25,18 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.5.0",
+    "@hatiolab/figure-model": "^0.5.2",
     "@operato/typeorm-history": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.129",
-    "@things-factory/attachment-base": "^10.1.147",
-    "@things-factory/auth-base": "^10.1.147",
-    "@things-factory/env": "^10.1.20",
-    "@things-factory/setting-base": "^10.1.147",
-    "@things-factory/shell": "^10.1.147",
+    "@things-factory/ai-client-base": "^10.1.149",
+    "@things-factory/attachment-base": "^10.1.150",
+    "@things-factory/auth-base": "^10.1.150",
+    "@things-factory/env": "^10.1.149",
+    "@things-factory/setting-base": "^10.1.150",
+    "@things-factory/shell": "^10.1.150",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "jszip": "^3.10.1",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "df93dddb6ac19a27c32fad21e29ca0ce02d08eb6"
+  "gitHead": "39c135863f5f7455dcd80b8907550a1c91a86118"
 }

package/server/routers/figure-mesh-router.ts

@@ -0,0 +1,59 @@
+import Router from 'koa-router'
+
+import { checkPermission } from '@things-factory/auth-base'
+import { getRepository } from '@things-factory/shell'
+
+import { meshAttachmentOf } from '../service/figure/figure-mesh-store.js'
+import { GLB_MIMETYPE } from '../service/figure/figure-glb.js'
+import { thumbnailFiles, type ThumbnailFiles } from '../service/figure/figure-thumbnail-store.js'
+
+/**
+ * A mesh part's file, by its hash (ADR-0129 decision 8): what the modeller and a board draw a mesh part from, on the
+ * server that authored it. A board server serves its own copy at `/figure-library-file/:hash`.
+ *
+ * The same door as a figure query, and the same scope: this domain's files and its parent's, whose figures it reads.
+ * The content is its hash, so it never changes: cached privately for as long as a browser keeps anything.
+ */
+export const figureMeshRouter = new Router()
+
+figureMeshRouter.get('/figure-mesh/:hash', async (context, next) => {
+  const { domain, user, unsafeIP, prohibitedPrivileges } = context.state
+  const allowed = await checkPermission({ category: 'figure', privilege: 'query', owner: true }, user, domain, unsafeIP, prohibitedPrivileges)
+  if (!allowed) {
+    context.status = 403
+    return
+  }
+  await sendFigureMesh(context, next, context.params.hash, domain)
+})
+
+/** The file of a mesh part the caller may read. Exported for tests, which give their own `files`. */
+export async function sendFigureMesh(
+  context: any,
+  next: () => Promise<any>,
+  hash: string,
+  domain: { id: string; parentId?: string },
+  files: ThumbnailFiles = thumbnailFiles()
+): Promise<void> {
+  if (!/^[0-9a-f]{64}$/.test(hash)) {
+    context.status = 404
+    return
+  }
+  const kept = await meshAttachmentOf({ getRepository }, [domain.id, domain.parentId].filter(Boolean) as string[], hash)
+  if (!kept) {
+    context.status = 404
+    return
+  }
+  const ours = () => {
+    context.type = GLB_MIMETYPE
+    context.set('Cache-Control', 'private, max-age=31536000, immutable')
+    context.set('ETag', `"${hash}"`)
+  }
+  ours()
+  context.status = 200
+  if (context.fresh) {
+    context.status = 304
+    return
+  }
+  await files.send(context, kept.path!, next)
+  ours()
+}

package/server/routes.ts

@@ -3,6 +3,7 @@ import { getRoutePrefixForDomainType } from '@things-factory/shell'
 
 import { figureThumbnailRouter } from './routers/figure-thumbnail-router.js'
 import { figurePackageRouter } from './routers/figure-package-router.js'
+import { figureMeshRouter } from './routers/figure-mesh-router.js'
 
 /**
  * 도메인 경로가 주소에 들어가는 배치인가.
@@ -20,8 +21,10 @@ process.on('bootstrap-module-domain-private-route' as any, (app, domainPrivateRo
       figureThumbnailRouter.allowedMethods()
     )
     domainPrivateRouter.use(`/${getRoutePrefixForDomainType()}/:domain`, figurePackageRouter.routes(), figurePackageRouter.allowedMethods())
+    domainPrivateRouter.use(`/${getRoutePrefixForDomainType()}/:domain`, figureMeshRouter.routes(), figureMeshRouter.allowedMethods())
   } else {
     domainPrivateRouter.use('', figureThumbnailRouter.routes(), figureThumbnailRouter.allowedMethods())
     domainPrivateRouter.use('', figurePackageRouter.routes(), figurePackageRouter.allowedMethods())
+    domainPrivateRouter.use('', figureMeshRouter.routes(), figureMeshRouter.allowedMethods())
   }
 })

package/server/service/figure/figure-glb.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Reading a GLB on upload (ADR-0129 decision 6): what a board can draw, and the numbers a mesh part carries.
+ * The files are made here, from their JSON: glTF requires every POSITION accessor to state its min and max, which is all
+ * the reader reads.
+ */
+import { GlbRefusal, eulerOfRotation, readGlb } from './figure-glb'
+
+/** A binary glTF: the JSON chunk, padded to four bytes, and an empty binary chunk. */
+function glb(json: unknown, { version = 2 }: { version?: number } = {}): Uint8Array {
+  let text = JSON.stringify(json)
+  while (text.length % 4) text += ' '
+  const body = new TextEncoder().encode(text)
+  const out = new Uint8Array(12 + 8 + body.length + 8)
+  const view = new DataView(out.buffer)
+  view.setUint32(0, 0x46546c67, true)
+  view.setUint32(4, version, true)
+  view.setUint32(8, out.length, true)
+  view.setUint32(12, body.length, true)
+  view.setUint32(16, 0x4e4f534a, true)
+  out.set(body, 20)
+  view.setUint32(20 + body.length, 0, true)
+  view.setUint32(24 + body.length, 0x004e4942, true)
+  return out
+}
+
+/* A crane: a base (a 2 m × 0.5 m × 0.4 m box, its own origin at its centre) and a hoist below it, a 0.2 m cube with 12
+   triangles in two primitives, turned 90° about Y and standing 1 m along X. */
+const quarterY = [0, Math.SQRT1_2, 0, Math.SQRT1_2]
+const crane = (over: Record<string, unknown> = {}) => ({
+  asset: { version: '2.0' },
+  scene: 0,
+  scenes: [{ nodes: [0] }],
+  nodes: [
+    { name: 'base', mesh: 0, children: [1] },
+    { name: 'hoist', mesh: 1, translation: [1, -0.5, 0], rotation: quarterY }
+  ],
+  meshes: [{ primitives: [{ attributes: { POSITION: 0 }, indices: 1 }] }, { primitives: [{ attributes: { POSITION: 2 } }, { attributes: { POSITION: 2 } }] }],
+  accessors: [
+    { count: 24, min: [-1, -0.25, -0.2], max: [1, 0.25, 0.2] },
+    { count: 36 },
+    { count: 18, min: [-0.1, -0.1, -0.1], max: [0.3, 0.1, 0.1] }
+  ],
+  buffers: [{ byteLength: 0 }],
+  ...over
+})
+
+describe('reading a GLB on upload', () => {
+  it('counts the whole file: its bounds in mm, its triangles and its primitives', () => {
+    const summary = readGlb(glb(crane()))
+    expect(summary.triangles).toBe(12 + 6 + 6)
+    expect(summary.primitives).toBe(3)
+    expect(summary.unit).toBe('m')
+    /* The hoist turned a quarter about Y reaches from 0.9 to 1.1 along X and from −0.3 to 0.1 along Z. */
+    expect(summary.bounds).toEqual({ min: { x: -1000, y: -600, z: -300 }, max: { x: 1100, y: 250, z: 200 } })
+  })
+
+  it('lists each node in its own frame, and where it stands in the file', () => {
+    const [base, hoist] = readGlb(glb(crane())).nodes
+    expect(base).toMatchObject({ index: 0, name: 'base', parent: null, triangles: 24, primitives: 3, position: { x: 0, y: 0, z: 0 } })
+    expect(base!.bounds).toEqual({ min: { x: -1000, y: -600, z: -300 }, max: { x: 1100, y: 250, z: 200 } })
+    /* The hoist in its own frame is not turned, and is not re-centred: its origin is where the file put it. */
+    expect(hoist).toMatchObject({ index: 1, name: 'hoist', parent: 0, triangles: 12, primitives: 2, position: { x: 1000, y: -500, z: 0 }, rotation: { x: 0, y: 90, z: 0 } })
+    expect(hoist!.bounds).toEqual({ min: { x: -100, y: -100, z: -100 }, max: { x: 300, y: 100, z: 100 } })
+  })
+
+  it('offers no frame for a node that shears or mirrors, and no part for one without a mesh', () => {
+    const sheared = readGlb(glb(crane({ nodes: [{ name: 'base', mesh: 0, children: [1], matrix: [1, 0, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] }, { name: 'hoist', mesh: 1 }] })))
+    expect(sheared.nodes[0]!.refused).toBe('sheared')
+    const mirrored = readGlb(glb(crane({ nodes: [{ name: 'base', mesh: 0, children: [1], scale: [-1, 1, 1] }, { name: 'hoist', mesh: 1 }] })))
+    expect(mirrored.nodes[0]!.refused).toBe('sheared')
+    const empty = readGlb(glb(crane({ nodes: [{ name: 'base', mesh: 0, children: [1] }, { name: 'hoist', mesh: 1 }, { name: 'marker' }] })))
+    expect(empty.nodes[2]!.refused).toBe('no-mesh')
+  })
+
+  it('a strip and a fan are counted as they draw; lines and points draw no triangles', () => {
+    const one = (mode: number, count: number) =>
+      readGlb(glb(crane({ nodes: [{ mesh: 0 }], meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode }] }], accessors: [{ count, min: [0, 0, 0], max: [1, 1, 1] }] }))).triangles
+    expect(one(5, 10)).toBe(8)
+    expect(one(6, 10)).toBe(8)
+    expect(one(1, 10)).toBe(0)
+  })
+
+  it('refuses what a board cannot draw as it is, by name', () => {
+    const code = (bytes: Uint8Array) => {
+      try {
+        readGlb(bytes)
+      } catch (e) {
+        return e instanceof GlbRefusal ? e.code : String(e)
+      }
+      return 'read'
+    }
+    expect(code(new TextEncoder().encode('{"asset":{"version":"2.0"}}'))).toBe('GLB_NOT_BINARY')
+    expect(code(glb(crane(), { version: 1 }))).toBe('GLB_VERSION')
+    expect(code(glb(crane({ extensionsRequired: ['KHR_draco_mesh_compression'] })))).toBe('GLB_EXTENSION')
+    expect(code(glb(crane({ extensionsRequired: ['EXT_meshopt_compression'] })))).toBe('read')
+    expect(code(glb(crane({ buffers: [{ uri: 'crane.bin', byteLength: 10 }] })))).toBe('GLB_EXTERNAL')
+    expect(code(glb(crane({ images: [{ uri: 'paint.png' }] })))).toBe('GLB_EXTERNAL')
+    expect(code(glb(crane({ meshes: [], nodes: [{ name: 'empty' }] })))).toBe('GLB_NO_MESH')
+    expect(code(glb(crane({ accessors: [{ count: 3 }, { count: 3 }, { count: 3 }] })))).toBe('GLB_UNREADABLE')
+    const cut = glb(crane())
+    expect(code(cut.subarray(0, cut.length - 4))).toBe('GLB_UNREADABLE')
+  })
+
+  it('turns a rotation into degrees in the order rigid@1 turns them', () => {
+    const rx = (a: number) => [[1, 0, 0], [0, Math.cos(a), -Math.sin(a)], [0, Math.sin(a), Math.cos(a)]]
+    const ry = (a: number) => [[Math.cos(a), 0, Math.sin(a)], [0, 1, 0], [-Math.sin(a), 0, Math.cos(a)]]
+    const rz = (a: number) => [[Math.cos(a), -Math.sin(a), 0], [Math.sin(a), Math.cos(a), 0], [0, 0, 1]]
+    const m = (a: number[][], b: number[][]) => a.map((row, i) => b[0]!.map((_, k) => row.reduce((s, v, j) => s + v * b[j]![k]!, 0)))
+    const d = Math.PI / 180
+    expect(eulerOfRotation(m(m(rx(30 * d), ry(20 * d)), rz(-45 * d)))).toEqual({ x: 30, y: 20, z: -45 })
+  })
+})

package/server/service/figure/figure-glb.ts

@@ -0,0 +1,251 @@
+/*
+ * What a GLB file holds, read on upload (ADR-0129 decision 6): whether it is a glTF 2.0 binary the board can draw, and
+ * the numbers a mesh part carries -- its bounds in mm, its triangles, its primitives -- for the whole file and for each
+ * node of it. The kernel never reads the file (figure-model `mesh@1`, contract §13); these numbers come from here.
+ *
+ * Nothing is decoded but the JSON chunk. glTF requires every POSITION accessor to carry its min and max, so the bounds
+ * are those corners carried through the node transforms; a compressed buffer (Meshopt) keeps them too.
+ *
+ * A node's frame is its place in the file: its world translation and rotation, in the file's root frame. A part made
+ * from a node stands there (its position and rotation), turns about the node's origin, and is drawn with the node's
+ * world scale kept in the drawing. A node whose world transform shears or mirrors has no such frame and is not offered.
+ */
+
+import { FIGURE_MESH_CONTENT_TYPE, FIGURE_MESH_MAX_BYTES } from '@hatiolab/figure-model'
+
+/* The package contract's rule (figure-model): the same type and limit a board server holds an import to. */
+export const GLB_MIMETYPE = FIGURE_MESH_CONTENT_TYPE
+/** The largest file kept, in bytes. A board downloads it for every figure that draws it. */
+export const GLB_MAX_BYTES = FIGURE_MESH_MAX_BYTES
+
+/** The extensions a board can draw: Meshopt's decoder ships with the loader. Draco and KTX2 wait (ADR-0129 Q4). */
+const DRAWABLE_EXTENSIONS = new Set(['EXT_meshopt_compression', 'KHR_mesh_quantization', 'KHR_materials_emissive_strength', 'KHR_texture_transform'])
+
+export type Box = { min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number } }
+
+export interface GlbNode {
+  /** Its place in the file's node list: what a mesh part names it by. */
+  index: number
+  name: string
+  parent: number | null
+  /** The node's subtree, in its own frame, in mm; none when it holds no mesh. */
+  bounds: Box | null
+  triangles: number
+  primitives: number
+  /** Where the node stands in the file's root frame: what a part made from it is placed at. */
+  position: { x: number; y: number; z: number }
+  rotation: { x: number; y: number; z: number }
+  /** Why it cannot be a part, when it cannot. */
+  refused?: 'no-mesh' | 'sheared'
+}
+
+export interface GlbSummary {
+  /** The whole file in its root frame, in mm. */
+  bounds: Box
+  triangles: number
+  primitives: number
+  unit: 'm'
+  nodes: GlbNode[]
+  extensions: string[]
+}
+
+export class GlbRefusal extends Error {
+  constructor(
+    readonly code:
+      | 'GLB_NOT_BINARY'
+      | 'GLB_VERSION'
+      | 'GLB_UNREADABLE'
+      | 'GLB_EXTERNAL'
+      | 'GLB_EXTENSION'
+      | 'GLB_NO_MESH'
+      | 'GLB_TOO_LARGE',
+    message: string,
+    /** What a screen says it with: the extensions it needs, the most bytes kept. */
+    readonly params: Record<string, string | number> = {}
+  ) {
+    super(message)
+    this.name = 'GlbRefusal'
+  }
+}
+
+type M4 = number[] // column-major, as glTF writes it
+const IDENTITY: M4 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+const mul = (a: M4, b: M4): M4 => {
+  const out = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) for (let k = 0; k < 4; k++) out[c * 4 + r] += a[k * 4 + r]! * b[c * 4 + k]!
+  return out
+}
+const apply = (m: M4, p: [number, number, number]): [number, number, number] => [
+  m[0]! * p[0] + m[4]! * p[1] + m[8]! * p[2] + m[12]!,
+  m[1]! * p[0] + m[5]! * p[1] + m[9]! * p[2] + m[13]!,
+  m[2]! * p[0] + m[6]! * p[1] + m[10]! * p[2] + m[14]!
+]
+function local(node: any): M4 {
+  if (Array.isArray(node.matrix) && node.matrix.length === 16) return node.matrix.map(Number)
+  const [tx, ty, tz] = node.translation ?? [0, 0, 0]
+  const [qx, qy, qz, qw] = node.rotation ?? [0, 0, 0, 1]
+  const [sx, sy, sz] = node.scale ?? [1, 1, 1]
+  const r = [
+    1 - 2 * (qy * qy + qz * qz), 2 * (qx * qy + qz * qw), 2 * (qx * qz - qy * qw),
+    2 * (qx * qy - qz * qw), 1 - 2 * (qx * qx + qz * qz), 2 * (qy * qz + qx * qw),
+    2 * (qx * qz + qy * qw), 2 * (qy * qz - qx * qw), 1 - 2 * (qx * qx + qy * qy)
+  ]
+  return [r[0]! * sx, r[1]! * sx, r[2]! * sx, 0, r[3]! * sy, r[4]! * sy, r[5]! * sy, 0, r[6]! * sz, r[7]! * sz, r[8]! * sz, 0, tx, ty, tz, 1]
+}
+
+/**
+ * A world matrix as translation and rotation, the scale left in the drawing. Undefined when its axes are not square to
+ * each other (a shear) or it mirrors: there is no frame to stand a part in.
+ */
+function frameOf(m: M4): { rotation: number[][]; translation: [number, number, number]; inverse: M4 } | undefined {
+  const cols = [0, 1, 2].map(c => [m[c * 4]!, m[c * 4 + 1]!, m[c * 4 + 2]!])
+  const len = cols.map(c => Math.hypot(...c))
+  if (len.some(l => !(l > 1e-12))) return undefined
+  const unit = cols.map((c, i) => c.map(v => v / len[i]!))
+  const dot = (a: number[], b: number[]) => a[0]! * b[0]! + a[1]! * b[1]! + a[2]! * b[2]!
+  if (Math.abs(dot(unit[0]!, unit[1]!)) > 1e-6 || Math.abs(dot(unit[0]!, unit[2]!)) > 1e-6 || Math.abs(dot(unit[1]!, unit[2]!)) > 1e-6) return undefined
+  const [a, b, c] = unit as [number[], number[], number[]]
+  const det = a[0]! * (b[1]! * c[2]! - b[2]! * c[1]!) - b[0]! * (a[1]! * c[2]! - a[2]! * c[1]!) + c[0]! * (a[1]! * b[2]! - a[2]! * b[1]!)
+  if (det < 0) return undefined
+  /* rotation rows: R[r][c] = unit[c][r] */
+  const rotation = [0, 1, 2].map(r => [0, 1, 2].map(col => unit[col]![r]!))
+  const translation: [number, number, number] = [m[12]!, m[13]!, m[14]!]
+  /* The inverse of the rigid part: Rᵀ and −Rᵀt. */
+  const inv: M4 = [...IDENTITY]
+  for (let r = 0; r < 3; r++) for (let col = 0; col < 3; col++) inv[col * 4 + r] = rotation[col]![r]!
+  for (let r = 0; r < 3; r++) inv[12 + r] = -(rotation[0]![r]! * translation[0] + rotation[1]![r]! * translation[1] + rotation[2]![r]! * translation[2])
+  return { rotation, translation, inverse: inv }
+}
+
+/** A rotation as degrees about X, Y and Z in the order `rigid@1` turns them (Rx · Ry · Rz). */
+export function eulerOfRotation(r: number[][]): { x: number; y: number; z: number } {
+  const deg = (a: number) => {
+    const d = Math.round(((a * 180) / Math.PI) * 1e6) / 1e6
+    return d === 0 ? 0 : d
+  }
+  const sy = Math.max(-1, Math.min(1, r[0]![2]!))
+  const y = Math.asin(sy)
+  if (Math.abs(sy) < 1 - 1e-9) return { x: deg(Math.atan2(-r[1]![2]!, r[2]![2]!)), y: deg(y), z: deg(Math.atan2(-r[0]![1]!, r[0]![0]!)) }
+  /* About Y by a quarter turn: X and Z turn about one axis and only their sum counts; Z is taken as 0. */
+  return { x: deg(Math.atan2(r[2]![1]!, r[1]![1]!)), y: deg(y), z: 0 }
+}
+
+const TO_MM = 1000
+const empty = (): Box => ({ min: { x: Infinity, y: Infinity, z: Infinity }, max: { x: -Infinity, y: -Infinity, z: -Infinity } })
+const grow = (box: Box, p: [number, number, number]) => {
+  box.min = { x: Math.min(box.min.x, p[0]), y: Math.min(box.min.y, p[1]), z: Math.min(box.min.z, p[2]) }
+  box.max = { x: Math.max(box.max.x, p[0]), y: Math.max(box.max.y, p[1]), z: Math.max(box.max.z, p[2]) }
+}
+const round = (v: number) => {
+  const r = Math.round(v * 1e6) / 1e6
+  return r === 0 ? 0 : r
+}
+const inMm = (box: Box): Box => ({
+  min: { x: round(box.min.x * TO_MM), y: round(box.min.y * TO_MM), z: round(box.min.z * TO_MM) },
+  max: { x: round(box.max.x * TO_MM), y: round(box.max.y * TO_MM), z: round(box.max.z * TO_MM) }
+})
+
+/** Reads a GLB's JSON chunk, and refuses one a board cannot draw as it is. */
+function jsonOf(bytes: Uint8Array): any {
+  if (bytes.length > GLB_MAX_BYTES) throw new GlbRefusal('GLB_TOO_LARGE', `the file is ${bytes.length} bytes; the most kept is ${GLB_MAX_BYTES}`, { max: Math.round(GLB_MAX_BYTES / 1024 / 1024) })
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (bytes.length < 20 || view.getUint32(0, true) !== 0x46546c67) throw new GlbRefusal('GLB_NOT_BINARY', 'not a binary glTF (.glb) file')
+  if (view.getUint32(4, true) !== 2) throw new GlbRefusal('GLB_VERSION', `glTF ${view.getUint32(4, true)}; only glTF 2.0 is read`)
+  if (view.getUint32(8, true) !== bytes.length) throw new GlbRefusal('GLB_UNREADABLE', 'the file is cut short or has bytes past its end')
+  const length = view.getUint32(12, true)
+  if (view.getUint32(16, true) !== 0x4e4f534a || 20 + length > bytes.length) throw new GlbRefusal('GLB_UNREADABLE', 'its first chunk is not its JSON')
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + length)))
+  } catch {
+    throw new GlbRefusal('GLB_UNREADABLE', 'its JSON chunk is not JSON')
+  }
+}
+
+export function readGlb(bytes: Uint8Array): GlbSummary {
+  const gltf = jsonOf(bytes)
+  if (String(gltf?.asset?.version ?? '').split('.')[0] !== '2') throw new GlbRefusal('GLB_VERSION', `glTF ${gltf?.asset?.version}; only glTF 2.0 is read`)
+  const required: string[] = Array.isArray(gltf.extensionsRequired) ? gltf.extensionsRequired : []
+  const undrawable = required.filter(e => !DRAWABLE_EXTENSIONS.has(e))
+  if (undrawable.length) throw new GlbRefusal('GLB_EXTENSION', `a board cannot draw it yet: it needs ${undrawable.join(', ')}`, { extensions: undrawable.join(', ') })
+  /* Self-contained: one buffer, the file's own; no file beside it. */
+  if ((gltf.buffers ?? []).some((b: any) => b?.uri !== undefined)) throw new GlbRefusal('GLB_EXTERNAL', 'it reads a buffer from another file')
+  if ((gltf.images ?? []).some((i: any) => i?.uri !== undefined && !String(i.uri).startsWith('data:')))
+    throw new GlbRefusal('GLB_EXTERNAL', 'it reads a picture from another file')
+
+  const nodes: any[] = Array.isArray(gltf.nodes) ? gltf.nodes : []
+  const meshes: any[] = Array.isArray(gltf.meshes) ? gltf.meshes : []
+  const accessors: any[] = Array.isArray(gltf.accessors) ? gltf.accessors : []
+  const parent = new Array<number | null>(nodes.length).fill(null)
+  nodes.forEach((n, i) => (Array.isArray(n?.children) ? n.children : []).forEach((c: number) => (parent[c] = i)))
+
+  /* World matrices, from the roots of the scene shown (or every root, when none is named). */
+  const world = new Array<M4 | undefined>(nodes.length)
+  const scene = gltf.scenes?.[gltf.scene ?? 0]
+  const roots: number[] = Array.isArray(scene?.nodes) ? scene.nodes : nodes.map((_, i) => i).filter(i => parent[i] === null)
+  const visit = (i: number, above: M4) => {
+    if (world[i]) throw new GlbRefusal('GLB_UNREADABLE', `node ${i} is reached twice: the nodes are not a tree`)
+    world[i] = mul(above, local(nodes[i]))
+    for (const c of nodes[i]?.children ?? []) visit(c, world[i]!)
+  }
+  roots.forEach(i => visit(i, IDENTITY))
+
+  /* What one primitive costs and where it reaches, in its mesh's own space. */
+  const primitive = (p: any) => {
+    const position = accessors[p?.attributes?.POSITION]
+    if (!position || !Array.isArray(position.min) || !Array.isArray(position.max))
+      throw new GlbRefusal('GLB_UNREADABLE', 'a primitive has no POSITION with its min and max')
+    const count = p.indices !== undefined ? Number(accessors[p.indices]?.count) : Number(position.count)
+    const mode = p.mode ?? 4
+    const triangles = mode === 4 ? Math.floor(count / 3) : mode === 5 || mode === 6 ? Math.max(count - 2, 0) : 0
+    const [x0, y0, z0] = position.min.map(Number)
+    const [x1, y1, z1] = position.max.map(Number)
+    const corners: Array<[number, number, number]> = [x0, x1].flatMap(x => [y0, y1].flatMap(y => [z0, z1].map(z => [x, y, z] as [number, number, number])))
+    return { triangles, corners }
+  }
+
+  const drawn = (i: number) => (nodes[i]?.mesh !== undefined ? meshes[nodes[i].mesh]?.primitives ?? [] : [])
+  const subtree = (i: number): number[] => [i, ...(nodes[i]?.children ?? []).flatMap((c: number) => subtree(c))]
+
+  const whole = empty()
+  let triangles = 0,
+    primitives = 0
+  for (let i = 0; i < nodes.length; i++) {
+    if (!world[i]) continue
+    for (const p of drawn(i)) {
+      const one = primitive(p)
+      triangles += one.triangles
+      primitives++
+      for (const c of one.corners) grow(whole, apply(world[i]!, c))
+    }
+  }
+  if (!primitives) throw new GlbRefusal('GLB_NO_MESH', 'it holds no mesh to draw')
+
+  const listed: GlbNode[] = nodes.map((n, i) => {
+    const frame = world[i] ? frameOf(world[i]!) : undefined
+    const below = subtree(i).filter(k => world[k])
+    const box = empty()
+    let t = 0,
+      p = 0
+    for (const k of below)
+      for (const prim of drawn(k)) {
+        const one = primitive(prim)
+        t += one.triangles
+        p++
+        if (frame) for (const c of one.corners) grow(box, apply(mul(frame.inverse, world[k]!), c))
+      }
+    const position = frame ? { x: round(frame.translation[0] * TO_MM), y: round(frame.translation[1] * TO_MM), z: round(frame.translation[2] * TO_MM) } : { x: 0, y: 0, z: 0 }
+    return {
+      index: i,
+      name: typeof n?.name === 'string' ? n.name : `node ${i}`,
+      parent: parent[i]!,
+      bounds: p && frame ? inMm(box) : null,
+      triangles: t,
+      primitives: p,
+      position,
+      rotation: frame ? eulerOfRotation(frame.rotation) : { x: 0, y: 0, z: 0 },
+      ...(!p ? { refused: 'no-mesh' as const } : !frame ? { refused: 'sheared' as const } : {})
+    }
+  })
+
+  return { bounds: inMm(whole), triangles, primitives, unit: 'm', nodes: listed, extensions: Array.isArray(gltf.extensionsUsed) ? gltf.extensionsUsed : [] }
+}