@nakednous/host 0.0.5 → 0.0.8

package/README.md

@@ -79,10 +79,11 @@ dependency first and an options object last, and registers with the context so
 | `host.handle(opts)` | `Handle` — a draggable core constraint (`SPHERE` · `PLANE` · `AXIS` · `DIAL` · `VIEW`, or a contract object); `update()`, `value(out, opts)`, snap, hover, cancel, `from` |
 | `host.router(handles, opts)` | `PointerRouter` — one shared pick over overlapping handles, nearest proxy wins; shared hover |
 | `host.cameraHelm(cam, opts)` · `host.poseHelm(opts)` | a core `PoseHelm` on the players: body-fly a camera state, or integrate into a pose in `WORLD` · `EYE` · `SELF` · a mat4 and `bind()` a target |
-| `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe |
+| `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe. `add(depth)` — the transport panel's `+` — authors where the camera is looking: a pose track places the pose at the centre of the installed camera's frustum, `depth` `0`…`1` from the near plane to the far one, aimed along that camera (the view bag's matrices; never deduplicated), a camera track captures its camera state, a placement depth being nothing a camera keyframe could use. `remove()` — the transport panel's `−` — retracts the last keyframe, one per call; `remove(i)` is the core track's own |
 | `host.hid(opts)` · `host.gamepad(opts)` | rate streams — `lin[3]` / `ang[3]` in raw device units, `bind(helm)` feeds it each tick; `available`, `connected` |
 | `host.image(url)` · `host.video(opts)` · `host.raster(draw, w, h)` | texture sources — an `ImageBitmap`, a hidden `<video>` from a file or the camera with a `ready` promise, a Canvas2D drawing |
-| `host.model(url)` | an OBJ model as arrays — `{ position, normal?, texcoord?, indices }`, what twgl's `createBufferInfoFromArrays` takes; host's own parser (fan-triangulated faces, one vertex per distinct position / uv / normal triple), materials ignored |
+| `host.mesh(url, opts)` | one mesh — the arrays shape `{ position, indices, normal?, tangent?, texcoord?, color?, joints?, weights? }` with its `bounds` `{ min, max, center, diag }` beside them — from an OBJ file, a one-part glTF 2.0 file (`.glb`, `.gltf`), or any format through `{ parse: (arrayBuffer) => arrays }`; what a bridge's buffer upload takes as it is, and `size / mesh.bounds.diag` fits any file to `size`. A file of several parts rejects, naming `model`. `{ format }` when the URL does not say. **`normals`**: left out, the file's normals are kept and a mesh without any gets smooth ones; `'smooth'` always recomputes them, summed per position, so a faceted file or a texture seam smooths too; `'flat'` always recomputes them on the flattened mesh (every triangle owning its vertices: more vertices, indices counting up); `false` computes nothing. The procedure, its limits and sources are tree's `mesh` module's; glTF viewers compute flat normals for a file without any — here that is `'flat'` |
+| `host.model(url, opts)` | a model with its structure — `{ parts: [{ name, node, skin, mesh, targets, color }], nodes: { names, parents, rest }, skins: [{ name, joints, inverseBind }], clips: [{ name, duration, channels }] }` — what a rig, morph targets or animation need. A part's `mesh` is as `host.mesh` returns it, in the part's own space; `targets` are morph deltas; nodes come parents first with a rest pose, and with `skins` and `clips` feed tree's `clipSample` · `poseBlend` · `poseWorld` · `jointPalette` as they are. Same options; `'flat'` flattens each part's morph targets with its mesh. An OBJ file is one white part under one identity node. host's own parsers: no textures, cameras, sparse accessors or compressed geometry |
 | `host.labels` · `host.hasLabels` | the label layer, created on first access — `set(id, text, x, y, z, opts)` at a world anchor, `setScreen(id, text, sx, sy, opts)` in canvas px, `{ frame: true }` for a label that lives one frame, `tick()`; `hasLabels` probes without creating |
 | `host.orbit(cam, opts)` | the fall-through gesture — one pointer orbits, two pan and dolly, the wheel dollies; `damping` in seconds (default 0.2; 0 exact) makes the camera trail the gesture and complete it after release; `update(dt)` reports whether the camera moved; the vertical sense follows the bag's projection (y-up GL, y-flipped p5) |
 | `host.tick(dt)` | external-loop mode: tick the players; the caller flushes the pointer once its consumers ran |
@@ -91,7 +92,7 @@ dependency first and an options object last, and registers with the context so
 The module-level functions behind the methods are exported too (`createView`, `createPointer`,
 `createPlayers`, `createLoop`, `observeCanvas`, `Handle`, `PointerRouter`, `cameraHelm`,
 `poseHelm`, `helmBasis`, `poseTrack`, `cameraTrack`, `TrackHandles`, `createHid`,
-`createGamepad`, `decodeSpaceNavigator`, `loadImage`, `createVideo`, `raster`, `loadModel`, `createLabels`,
+`createGamepad`, `decodeSpaceNavigator`, `loadImage`, `createVideo`, `raster`, `loadMesh`, `loadModel`, `createLabels`,
 `createOrbit`), so an adapter can compose them on its own context.
 
 ---
@@ -154,6 +155,15 @@ npm run build     # rollup → dist/index.js
 
 ---
 
+## Acknowledgements
+
+- [glTF 2.0](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) (Khronos Group) — the format `host/gltf` reads: the GLB container, accessors and buffer views, skins, morph targets, animations.
+- Wavefront OBJ — the format `host/obj` reads.
+- [three.js](https://threejs.org/) — the orbit's damping follows the shape of its `OrbitControls`, made time-based.
+- [twgl](https://twgljs.org/) — the arrays shape a model's meshes arrive in.
+
+Both parsers are host's own; no third-party code ships in the package.
+
 ## License
 
 AGPL-3.0-only  

package/dist/index.js

@@ -1,4 +1,4 @@
-import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
+import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, NDC, mat4ToTransform, meshBounds, meshFlatten, meshNormals, meshGroups, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
 
 /**
  * @file The view bag — the matrices every pick, solve, label and orbit reads.
@@ -1300,11 +1300,69 @@ function poseHelm(host, opts) {
  * either decorates the track with TrackHandles: one VIEW handle per
  * draggable keyframe field (pos / eye / center), an optional rot DIAL per
  * keyframe about a declared axis, all on one router.
+ *
+ * add(depth) — the transport panel's + button, which passes its depth slider
+ * (ui's contract) — authors a keyframe where the camera is looking: on a pose
+ * track the pose lands at the centre of the installed camera's frustum at
+ * that depth, aimed along the camera's own eye frame; on a camera track the
+ * camera state is captured, the depth having nothing to place. A panel whose
+ * depth row is hidden passes no depth, which reads the panel's default, 0.5.
+ * The frame is the host's view bag — the matrices the last setCamera
+ * installed — so the placement is the same on every bridge and needs no
+ * renderer here. remove() is the panel's −: no argument retracts the last
+ * keyframe, one per call, an index staying the core track's own remove.
  */
 
 
+// ── Placement — the + button's depth ───────────────────────────────────────
+//
+// The transport panel hands add() a depth in [0, 1] and expects a keyframe in
+// front of the camera. Writer-free placement: unproject the frustum's centre
+// through the view bag's P · V inverse and aim the pose along the bag's eye
+// frame (E = V⁻¹, its columns right / up / back). The depth is NDC-linear, as
+// the p5 transport's was — 0 the near plane's centre, 1 the far plane's — so
+// every bridge's own ndcZMin maps it without the caller knowing the API.
+
+const _at  = [0, 0, 0];   // the unprojected frustum centre
+const _dir = [0, 0, 0];   // the camera's forward
+const _up  = [0, 0, 0];   // the camera's up
+
+/**
+ * Append a pose at the centre of the installed camera's frustum, `depth` of
+ * the way from the near plane to the far one.
+ *
+ * @param {object} host
+ * @param {function} add    The track's core add, already bound.
+ * @param {number} [depth]  NDC-linear depth in [0, 1]; clamped, absent or NaN
+ *                          reads the panel's own default, 0.5.
+ * @returns {boolean} false when no camera is installed (a stale view bag).
+ */
+function _addInFront(host, add, depth) {
+  const view = host.view;
+  if (!view || view.stale) return false;
+  const d    = Number.isFinite(depth) ? (depth < 0 ? 0 : depth > 1 ? 1 : depth) : 0.5;
+  const ndcZ = view.ndcZMin + d * (1 - view.ndcZMin);
+  mapLocation(_at, 0, 0, ndcZ, NDC, WORLD, view, view.vp, view.ndcZMin);
+  const e = view.mat4Eye;                        // columns: right · up · back · eye
+  _dir[0] = -e[8];  _dir[1] = -e[9];  _dir[2] = -e[10];
+  _up[0]  =  e[4];  _up[1]  =  e[5];  _up[2]  =  e[6];
+  add({ pos: [_at[0], _at[1], _at[2]], rot: { dir: _dir, up: _up } }, { deduplicate: false });
+  return true;
+}
+
 // ── Players ────────────────────────────────────────────────────────────────
 
+// remove(): the panel's −, retracting the last authored keyframe — one per
+// click, either kind of track. An index stays the core track's own remove, so
+// a caller editing by index is unaffected; an empty track removes nothing.
+function _wireRemove(track) {
+  const coreRemove = track.remove.bind(track);
+  track.remove = function (index) {
+    return coreRemove(index == null ? track.keyframes.length - 1 : index);
+  };
+  return track;
+}
+
 function _wirePoseTrack(host, track) {
   let player = null;
   track._onActivate = () => {
@@ -1324,8 +1382,22 @@ function poseTrack(host, opts) {
   const o = opts || {};
   const track = new PoseTrack();
   _wirePoseTrack(host, track);
+
+  // add(depth): the transport's + (see the module header). A spec, or an array
+  // of specs, is the core track's own; no argument — the panel with its depth
+  // row hidden — places at the panel's default depth, 0.5.
+  const coreAdd = track.add.bind(track);
+  let warned = false;
+  track.add = function (spec, addOpts) {
+    if (spec != null && typeof spec !== 'number') return coreAdd(spec, addOpts);
+    if (!_addInFront(host, coreAdd, spec) && !warned) {
+      warned = true;
+      console.warn('[host] poseTrack: add(depth) places a pose against the installed camera, and the view bag is stale — no keyframe added. Call the bridge\'s setCamera first.');
+    }
+  };
+
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, false);
-  return track;
+  return _wireRemove(track);
 }
 
 /**
@@ -1344,7 +1416,9 @@ function cameraTrack(host, cam, opts) {
 
   const coreAdd = track.add.bind(track);
   track.add = function (spec, addOpts) {
-    if (spec == null) {
+    // No spec, or the transport panel's depth: a camera keyframe *is* the
+    // camera, so there is nothing a placement depth could move — capture.
+    if (spec == null || typeof spec === 'number') {
       if (!state) return;
       spec = state;
     } else if (Array.isArray(spec)) {
@@ -1373,7 +1447,7 @@ function cameraTrack(host, cam, opts) {
   track._onDeactivate = () => { host.players.remove(player); apply(); };
 
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, true);
-  return track;
+  return _wireRemove(track);
 }
 
 // ── TrackHandles ───────────────────────────────────────────────────────────
@@ -1923,12 +1997,203 @@ function parseObj(text) {
 }
 
 /**
- * @file Media sources — images, video and Canvas2D rasters for a bridge's textures, OBJ models for its buffers.
+ * @file glTF 2.0 → meshes in the arrays shape, the node hierarchy, skins and animation clips.
+ * @module host/gltf
+ * @license AGPL-3.0-only
+ *
+ * The format is glTF 2.0 (Khronos Group): a JSON document plus binary buffers,
+ * or both in one GLB container. parseGlb splits a container; parseGltf reads
+ * the document over its buffers into what a bridge uploads and what tree's
+ * skin functions (clipSample, poseWorld, jointPalette) take as they are.
+ *
+ * Read: triangle primitives (POSITION, NORMAL, TANGENT, TEXCOORD_0, JOINTS_0,
+ * WEIGHTS_0, indices), morph targets (POSITION and NORMAL deltas), the
+ * material's base colour factor, nodes, skins, animations. Normalised integer
+ * accessors arrive as floats; interleaved views are unpacked. Not read:
+ * textures, cameras, other primitive modes, sparse accessors and compressed
+ * geometry (Draco, meshopt) — the last two throw.
+ *
+ * Nodes are re-indexed parents first, and every node index in the result
+ * (a mesh's, a skin's joints, a channel's) is the new one.
+ */
+
+
+const GLB_MAGIC = 0x46546C67, CHUNK_JSON = 0x4E4F534A, CHUNK_BIN = 0x004E4942;
+
+const COMPONENTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
+const TYPES = {
+  5120: Int8Array, 5121: Uint8Array, 5122: Int16Array, 5123: Uint16Array, 5125: Uint32Array, 5126: Float32Array,
+};
+const NORMALISED = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };
+const ATTRIBUTES = {
+  POSITION: 'position', NORMAL: 'normal', TANGENT: 'tangent', TEXCOORD_0: 'texcoord',
+  JOINTS_0: 'joints', WEIGHTS_0: 'weights',
+};
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+
+/**
+ * Split a GLB container into its JSON document and binary chunk.
+ * @param {ArrayBuffer} buffer
+ * @returns {{ json:object, bin:ArrayBuffer|null }}
+ */
+function parseGlb(buffer) {
+  const view = new DataView(buffer);
+  if (view.getUint32(0, true) !== GLB_MAGIC) throw new Error('[host] gltf: not a GLB container.');
+  if (view.getUint32(4, true) !== 2) throw new Error('[host] gltf: GLB version ' + view.getUint32(4, true) + ', 2 expected.');
+  const end = Math.min(view.getUint32(8, true), buffer.byteLength);
+  let json = null, bin = null;
+  for (let at = 12; at + 8 <= end;) {
+    const length = view.getUint32(at, true), type = view.getUint32(at + 4, true);
+    const start = at + 8;
+    if (type === CHUNK_JSON) json = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, start, length)));
+    else if (type === CHUNK_BIN && !bin) bin = buffer.slice(start, start + length);
+    at = start + length + (-length & 3);
+  }
+  if (!json) throw new Error('[host] gltf: GLB without a JSON chunk.');
+  return { json, bin };
+}
+
+/**
+ * Read a glTF document over its buffers.
+ *
+ * A part is one triangle primitive under one node: `mesh` in the
+ * arrays shape (position, normal?, tangent?, texcoord?, joints?, weights?,
+ * indices), `targets` its morph targets as delta arrays, `color` the
+ * material's base colour factor, `node` the node it hangs from and `skin` its
+ * skin's index or −1. A rigid mesh draws under its node's world matrix; a
+ * skinned one under its skin's joint palette.
+ *
+ * @param {object} json  The glTF document.
+ * @param {ArrayBuffer[]} buffers  One per `json.buffers` entry.
+ * @returns {{ parts:{ name:string, node:number, skin:number, mesh:object,
+ *                      targets:{ name:string, position?:object, normal?:object }[], color:number[] }[],
+ *             nodes:{ names:string[], parents:Int32Array, rest:Float32Array },
+ *             skins:{ name:string, joints:Uint16Array, inverseBind:Float32Array }[],
+ *             clips:{ name:string, duration:number, channels:object[] }[] }}
+ *          nodes.rest: the rest pose, ten numbers per node (translation, rotation
+ *          [x,y,z,w], scale). A clip channel: { node, path, interp, times, values }.
+ */
+function parseGltf(json, buffers) {
+  for (const ext of json.extensionsRequired || []) {
+    if (/draco|meshopt/i.test(ext)) throw new Error('[host] gltf: ' + ext + ' is not supported.');
+  }
+  const cache = new Map();
+
+  const accessor = (index) => {
+    if (cache.has(index)) return cache.get(index);
+    const a = json.accessors[index];
+    if (a.sparse) throw new Error('[host] gltf: sparse accessors are not supported.');
+    const n = COMPONENTS[a.type], Type = TYPES[a.componentType], scale = a.normalized && NORMALISED[a.componentType];
+    const data = new (scale ? Float32Array : Type)(a.count * n);
+    if (a.bufferView !== undefined) {
+      const bv = json.bufferViews[a.bufferView];
+      const base = (bv.byteOffset || 0) + (a.byteOffset || 0), size = Type.BYTES_PER_ELEMENT;
+      const stride = bv.byteStride || n * size;
+      const view = new DataView(buffers[bv.buffer]);
+      const get = {
+        5120: 'getInt8', 5121: 'getUint8', 5122: 'getInt16', 5123: 'getUint16', 5125: 'getUint32', 5126: 'getFloat32',
+      }[a.componentType];
+      for (let i = 0; i < a.count; i++) {
+        for (let c = 0; c < n; c++) {
+          const v = view[get](base + i * stride + c * size, true);
+          data[i * n + c] = scale ? Math.max(v / scale, -1) : v;
+        }
+      }
+    }
+    const out = { numComponents: n, data };
+    cache.set(index, out);
+    return out;
+  };
+
+  // nodes, parents first
+  const src = json.nodes || [], parentOf = new Array(src.length).fill(-1);
+  src.forEach((node, i) => { for (const c of node.children || []) parentOf[c] = i; });
+  const order = [], remap = new Array(src.length).fill(-1);
+  const visit = (i) => { remap[i] = order.length; order.push(i); for (const c of src[i].children || []) visit(c); };
+  src.forEach((_, i) => { if (parentOf[i] < 0) visit(i); });
+
+  const names = [], parents = new Int32Array(order.length), rest = new Float32Array(order.length * 10);
+  const xf = { pos: [0, 0, 0], rot: [0, 0, 0, 1], scl: [1, 1, 1] };
+  order.forEach((old, i) => {
+    const node = src[old];
+    names.push(node.name || '');
+    parents[i] = parentOf[old] < 0 ? -1 : remap[parentOf[old]];
+    let t = node.translation || [0, 0, 0], r = node.rotation || [0, 0, 0, 1], s = node.scale || [1, 1, 1];
+    if (node.matrix) { mat4ToTransform(xf, node.matrix); t = xf.pos; r = xf.rot; s = xf.scl; }
+    rest.set(t, i * 10); rest.set(r, i * 10 + 3); rest.set(s, i * 10 + 7);
+  });
+
+  // parts: one per triangle primitive per node
+  const primitives = (json.meshes || []).map((mesh) => {
+    const out = [];
+    for (const prim of mesh.primitives) {
+      if ((prim.mode ?? 4) !== 4 || prim.attributes.POSITION === undefined) continue;
+      const arrays = {};
+      for (const [semantic, key] of Object.entries(ATTRIBUTES)) {
+        if (prim.attributes[semantic] !== undefined) arrays[key] = accessor(prim.attributes[semantic]);
+      }
+      const count = arrays.position.data.length / 3;
+      const data = prim.indices !== undefined
+        ? Uint32Array.from(accessor(prim.indices).data)
+        : Uint32Array.from({ length: count }, (_, i) => i);
+      arrays.indices = { numComponents: 3, data };
+      const targetNames = (mesh.extras && mesh.extras.targetNames) || [];
+      const targets = (prim.targets || []).map((target, i) => {
+        const t = { name: targetNames[i] || '' };
+        if (target.POSITION !== undefined) t.position = accessor(target.POSITION);
+        if (target.NORMAL !== undefined) t.normal = accessor(target.NORMAL);
+        return t;
+      });
+      const material = prim.material !== undefined ? json.materials[prim.material] : null;
+      const pbr = material && material.pbrMetallicRoughness;
+      out.push({ arrays, targets, color: (pbr && pbr.baseColorFactor ? pbr.baseColorFactor : [1, 1, 1, 1]).slice() });
+    }
+    return { name: mesh.name || '', primitives: out };
+  });
+
+  const parts = [];
+  order.forEach((old, i) => {
+    const node = src[old];
+    if (node.mesh === undefined) return;
+    const mesh = primitives[node.mesh];
+    for (const p of mesh.primitives) {
+      parts.push({ name: mesh.name || names[i], node: i, skin: node.skin ?? -1, mesh: p.arrays, targets: p.targets, color: p.color });
+    }
+  });
+
+  const skins = (json.skins || []).map((skin) => {
+    const joints = Uint16Array.from(skin.joints, j => remap[j]);
+    const inverseBind = skin.inverseBindMatrices !== undefined
+      ? Float32Array.from(accessor(skin.inverseBindMatrices).data)
+      : Float32Array.from({ length: joints.length * 16 }, (_, k) => IDENTITY[k % 16]);
+    return { name: skin.name || '', joints, inverseBind };
+  });
+
+  const clips = (json.animations || []).map((anim) => {
+    let duration = 0;
+    const channels = [];
+    for (const ch of anim.channels) {
+      if (ch.target.node === undefined) continue;
+      const sampler = anim.samplers[ch.sampler];
+      const times = accessor(sampler.input).data, values = accessor(sampler.output).data;
+      if (times.length) duration = Math.max(duration, times[times.length - 1]);
+      channels.push({ node: remap[ch.target.node], path: ch.target.path, interp: sampler.interpolation || 'LINEAR', times, values });
+    }
+    return { name: anim.name || '', duration, channels };
+  });
+
+  return { parts, nodes: { names, parents, rest }, skins, clips };
+}
+
+/**
+ * @file Media sources — images, video and Canvas2D rasters for a bridge's textures, models for its buffers.
  * @module host/media
  * @license AGPL-3.0-only
  *
- * A model arrives as arrays for a bridge's buffer upload: loadModel fetches an
- * OBJ file and parses it (host/obj).
+ * A mesh arrives as arrays for a bridge's buffer upload, its bounds beside
+ * them: loadMesh. A model keeps a file's structure — parts, hierarchy, skins,
+ * clips: loadModel. Both read OBJ (host/obj) and glTF 2.0 (host/gltf), or
+ * another format through a parser the caller passes.
  *
  * What a texture upload reads from: an ImageBitmap fetched from a URL, a
  * hidden <video> element from a file or the user's camera, a bitmap drawn
@@ -1955,26 +2220,151 @@ async function loadImage(url, opts) {
   return o.bitmap ? createImageBitmap(blob, o.bitmap) : createImageBitmap(blob);
 }
 
+const _ONE_NODE = () => ({ names: [''], parents: Int32Array.of(-1), rest: Float32Array.of(0, 0, 0, 0, 0, 0, 1, 1, 1, 1) });
+const _part = (mesh) => ({ name: '', node: 0, skin: -1, mesh, targets: [], color: [1, 1, 1, 1] });
+
+// A morph target's deltas expanded through its mesh's indices; a target carries no indices of its own.
+function _flatTarget(target, indices) {
+  const flat = meshFlatten(target, indices);
+  delete flat.indices;
+  return flat;
+}
+
+// The normals option applied to every part, then each mesh's bounds; parts sharing a mesh share the result.
+//   undefined / true  the file's normals; smooth ones where a mesh has none
+//   'smooth'          always recomputed, summed per position (tree's meshGroups), so a faceted file smooths
+//   'flat'            always recomputed on the flattened mesh (tree's meshFlatten), morph targets flattened with it
+//   false             nothing computed
+function _finish(model, o) {
+  const mode = o.normals === undefined || o.normals === true ? 'fill' : o.normals;
+  if (mode !== 'fill' && mode !== 'smooth' && mode !== 'flat' && mode !== false) {
+    throw new Error("[host] model: normals is one of 'smooth', 'flat', false, or left out.");
+  }
+  const done = new Map();
+  for (const part of model.parts) {
+    const source = part.mesh;
+    if (done.has(source)) {
+      part.mesh = done.get(source);
+      if (mode === 'flat') part.targets = part.targets.map(t => _flatTarget(t, source.indices.data));
+      continue;
+    }
+    let mesh = source;
+    const bounds = meshBounds({ min: [0, 0, 0], max: [0, 0, 0], center: [0, 0, 0], diag: 0 }, mesh.position.data);
+    if (mode === 'flat') {
+      mesh = meshFlatten(source);
+      const p = mesh.position.data;
+      mesh.normal = { numComponents: 3, data: meshNormals(new Float32Array(p.length), p, mesh.indices.data) };
+      part.targets = part.targets.map(t => _flatTarget(t, source.indices.data));
+    } else if (mode === 'smooth' || (mode === 'fill' && !mesh.normal)) {
+      const p = mesh.position.data;
+      const groups = meshGroups(new Int32Array(p.length / 3), p, 1e-6 * bounds.diag);
+      mesh.normal = { numComponents: 3, data: meshNormals(new Float32Array(p.length), p, mesh.indices.data, { groups }) };
+    }
+    mesh.bounds = bounds;
+    done.set(source, mesh);
+    part.mesh = mesh;
+  }
+  return model;
+}
+
+// Fetch and parse into the model shape, before the normals and bounds.
+async function _load(url, o, what) {
+  const get = async (at, init) => {
+    const res = await fetch(at, init);
+    if (!res.ok) throw new Error('[host] ' + what + ': ' + at + ' → ' + res.status);
+    return res;
+  };
+  if (typeof o.parse === 'function') {
+    const mesh = await o.parse(await (await get(url, o.fetch)).arrayBuffer());
+    return { parts: [_part(mesh)], nodes: _ONE_NODE(), skins: [], clips: [] };
+  }
+  const format = (o.format || (/\.(\w+)(?:[?#].*)?$/.exec(url) || [])[1] || '').toLowerCase();
+  if (format !== 'obj' && format !== 'glb' && format !== 'gltf') {
+    throw new Error('[host] ' + what + ': ' + url + ' → unknown format; opts.format is one of obj, glb, gltf, or pass opts.parse.');
+  }
+  const res = await get(url, o.fetch);
+  if (format === 'obj') return { parts: [_part(parseObj(await res.text()))], nodes: _ONE_NODE(), skins: [], clips: [] };
+  if (format === 'glb') {
+    const { json, bin } = parseGlb(await res.arrayBuffer());
+    return parseGltf(json, [bin]);
+  }
+  const json = await res.json();
+  const base = typeof location !== 'undefined' ? new URL(url, location.href) : url;
+  const resolve = (uri) => {
+    if (/^data:/.test(uri)) return uri;
+    try { return String(new URL(uri, base)); } catch (e) { return url.replace(/[^/]*$/, '') + uri; }
+  };
+  const buffers = await Promise.all((json.buffers || []).map(async b => (await get(resolve(b.uri), o.fetch)).arrayBuffer()));
+  return parseGltf(json, buffers);
+}
+
+/**
+ * Fetch a mesh: one object in the arrays shape — position, indices, and
+ * normal, tangent, texcoord, color, joints, weights when the file carries them
+ * — with `bounds`, its extent `{ min, max, center, diag }`, beside them. A
+ * bridge's buffer upload takes it as it is; `size / mesh.bounds.diag` is the
+ * scale that fits any file to `size`.
+ *
+ * Formats: OBJ (host/obj), and glTF 2.0 as `.glb` or `.gltf` (host/gltf) when
+ * the file holds one part. A file of several parts rejects, naming loadModel:
+ * a mesh is never silently the first of many. `opts.parse` reads any other
+ * format: it receives the fetched ArrayBuffer and returns the arrays shape.
+ *
+ * Normals. Left out, the option keeps the file's normals and gives smooth
+ * ones to a mesh that has none. 'smooth' always recomputes them, summed per
+ * position, so a file that arrives faceted or cut along a texture seam
+ * smooths too. 'flat' always recomputes them on the flattened mesh — every
+ * triangle owning its vertices, so the vertex count grows and the indices
+ * count up. false computes nothing. The procedure, its limits (no crease
+ * angle; grouping by grid cell, at 1e-6 of the bounds' diagonal) and its
+ * sources are tree/mesh's. glTF viewers compute flat normals for a file
+ * without any; here that is `normals: 'flat'`.
+ *
+ * @param {string} url
+ * @param {{ fetch?:object, format?:string, parse?:function(ArrayBuffer):object,
+ *           normals?:'smooth'|'flat'|false }} [opts]  fetch: the fetch init. format: 'obj' |
+ *        'glb' | 'gltf' when the URL's extension does not say. parse: a parser for another
+ *        format. normals: as above.
+ * @returns {Promise<object>} The mesh.
+ */
+async function loadMesh(url, opts) {
+  const o = opts || {};
+  const model = await _load(url, o, 'mesh');
+  if (model.parts.length !== 1) {
+    throw new Error('[host] mesh: ' + url + ' → ' + model.parts.length + ' parts; loadModel keeps them apart.');
+  }
+  return _finish(model, o).parts[0].mesh;
+}
+
 /**
- * Fetch an OBJ model into the arrays shape: position and indices, plus normal
- * and texcoord when the file carries them. twgl's createBufferInfoFromArrays
- * takes the result as it is.
+ * Fetch a model with its structure — what a rig, morph targets or animation
+ * need; a single mesh is loadMesh's:
  *
- * Faces are triangulated and each distinct position / uv / normal triple
- * becomes one vertex. Materials are ignored.
+ *   { parts: [{ name, node, skin, mesh, targets, color }], nodes, skins, clips }
+ *
+ * A part is one triangle primitive under one node: `mesh` as loadMesh returns
+ * it (the arrays shape with `bounds`, in the part's own space), `targets` its
+ * morph targets as delta arrays, `color` its base colour [r, g, b, a], `node`
+ * the node it hangs from and `skin` its skin's index or −1. `nodes` is the
+ * hierarchy `{ names, parents, rest }`, parents first, `rest` a pose of ten
+ * numbers per node; `skins` are `{ name, joints, inverseBind }` and `clips`
+ * `{ name, duration, channels }` — what tree's clipSample, poseWorld and
+ * jointPalette take. A rigid part draws under its node's world matrix, a
+ * skinned one under its skin's joint palette. An OBJ file is one white part
+ * under one identity node.
+ *
+ * The options are loadMesh's; `normals` applies to every part, 'flat'
+ * flattening each part's morph targets with its mesh.
  *
  * @param {string} url
- * @param {{ fetch?:object }} [opts]  fetch: the fetch init (credentials, mode, …).
- * @returns {Promise<{ position:{numComponents:number,data:Float32Array},
- *                     normal?:{numComponents:number,data:Float32Array},
- *                     texcoord?:{numComponents:number,data:Float32Array},
- *                     indices:{numComponents:number,data:Uint32Array} }>}
+ * @param {{ fetch?:object, format?:string, parse?:function(ArrayBuffer):object,
+ *           normals?:'smooth'|'flat'|false }} [opts]
+ * @returns {Promise<{ parts:object[], nodes:{ names:string[], parents:Int32Array, rest:Float32Array },
+ *                     skins:object[], clips:object[] }>}
  */
 async function loadModel(url, opts) {
   const o = opts || {};
-  const res = await fetch(url, o.fetch);
-  if (!res.ok) throw new Error('[host] model: ' + url + ' → ' + res.status);
-  return parseObj(await res.text());
+  return _finish(await _load(url, o, 'model'), o);
 }
 
 /**
@@ -2478,7 +2868,7 @@ function createOrbit(host, cam, opts) {
  *   host.cameraHelm(cam, opts) · host.poseHelm(opts)
  *   host.poseTrack(opts) · host.cameraTrack(cam, opts)
  *   host.hid(opts) · host.gamepad(opts)
- *   host.image(url) · host.video(opts) · host.raster(draw, w, h) · host.model(url)
+ *   host.image(url) · host.video(opts) · host.raster(draw, w, h) · host.mesh(url) · host.model(url)
  *   host.labels        // the DOM label layer, created on first access
  *   host.orbit(cam, opts)
  *   host.tick(dt)      // external-loop mode
@@ -2573,7 +2963,9 @@ function createHost(canvas, opts) {
     video(opts) { return host.register(createVideo(opts)); },
     /** Draw through a 2D context into a texture source — see host/media. */
     raster(draw, w, h, opts) { return raster(draw, w, h, opts); },
-    /** Fetch an OBJ model into the arrays shape — see host/media. */
+    /** Fetch one mesh — the arrays shape with its bounds — from an OBJ or glTF file, or any format through opts.parse — see host/media. */
+    mesh(url, opts) { return loadMesh(url, opts); },
+    /** Fetch a model with its structure: parts, nodes, skins, clips — see host/media. */
     model(url, opts) { return loadModel(url, opts); },
     /**
      * The label layer — see host/labels. Created on first access, so a
@@ -2630,5 +3022,5 @@ function createHost(canvas, opts) {
   return host;
 }
 
-export { GAMEPAD_MAP, HID_FILTERS, Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createGamepad, createHid, createHost, createLabels, createLoop, createOrbit, createPlayers, createPointer, createVideo, createView, decodeSpaceNavigator, helmBasis, isConstraint, loadImage, loadModel, measureCanvas, observeCanvas, poseHelm, poseTrack, raster, validConstraint };
+export { GAMEPAD_MAP, HID_FILTERS, Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createGamepad, createHid, createHost, createLabels, createLoop, createOrbit, createPlayers, createPointer, createVideo, createView, decodeSpaceNavigator, helmBasis, isConstraint, loadImage, loadMesh, loadModel, measureCanvas, observeCanvas, poseHelm, poseTrack, raster, validConstraint };
 //# sourceMappingURL=index.js.map