@solidrt/3d 0.0.56 → 0.0.58

package/src/geometry.ts

@@ -21,7 +21,7 @@
 // array math (the check rig checks/geometry-check.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
-import type { VertexAttribute } from "@solidrt/core/gpu"
+import type { Topology, VertexAttribute } from "@solidrt/core/gpu"
 import { add, compose, cross, mat4, normalize, normalMatrix, sub, updateRotation, updateScale } from "./math.ts"
 import type { Quat, TransformUpdate, Vec2, Vec3 } from "./math.ts"
 
@@ -50,7 +50,10 @@ export const VERTEX_LAYOUTS: Record<"standard" | "colored" | "skinned", VertexAt
  * format before packing). */
 export const STANDARD_FLOATS = 8
 
-const FORMAT_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
+/** Floats per attribute format: the vertex vocabulary itself, so it is
+ * also the list a declared format must be one of (vertex attributes and
+ * instance attributes both). */
+export const FORMAT_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
 
 /** The attribute list of a layout (a preset name resolves to its list). */
 export function layoutAttributes(layout?: VertexLayout): VertexAttribute[] {
@@ -123,7 +126,35 @@ export function validateGeometry(geometry: Geometry): void {
       name + ": " + geometry.vertices.length + " vertex floats is not a whole number of " + stride + "-float (" + layoutKey(layout) + ") vertices",
     )
   }
-  if (geometry.indices.length === 0) throw new Error(name + ": no indices")
+  let topology = geometryTopology(geometry)
+  let count = geometry.indices.length
+  // Lines and points may be empty: a feature-edge pass over a smooth
+  // closed shape has nothing to draw, and that is a result, not a bug.
+  switch (topology) {
+    case "triangles":
+      if (count === 0) throw new Error(name + ": no indices")
+      if (count % 3 !== 0) throw new Error(name + ": " + count + " indices is not a whole number of triangles")
+      break
+    case "lines":
+      if (count % 2 !== 0) throw new Error(name + ": " + count + " indices is not a whole number of lines")
+      break
+    case "line-strip":
+      if (count < 2) throw new Error(name + ": a line strip needs at least 2 indices")
+      break
+    case "triangle-strip":
+      if (count < 3) throw new Error(name + ": a triangle strip needs at least 3 indices")
+      break
+    case "points":
+      break
+    default:
+      throw new Error(name + ": unknown topology '" + String(topology) + "'")
+  }
+}
+
+/** The geometry's topology with the default applied: what its indices
+ * list, "triangles" unless it says otherwise. */
+export function geometryTopology(geometry: Geometry): Topology {
+  return geometry.topology ?? "triangles"
 }
 
 /** The options every generator shares (each generator's own options type
@@ -194,6 +225,20 @@ export type Geometry = {
   /** The array type picks the draw's index format: Uint32Array past 64k
    * vertices. */
   indices: Uint16Array | Uint32Array
+  /** What the indices describe; absent means "triangles". The index
+   * buffer and the primitive it lists travel together (Godot's surface
+   * primitive, Unity's Mesh.SetIndices topology, Three's Line/Points
+   * object types over one BufferGeometry): the material draws whatever
+   * topology its geometry carries, one pipeline per (layout, topology)
+   * pair. Only a triangle list gets the picking shape - a lines, points
+   * or strip geometry picks (and collides) by its bounds box, the tier a
+   * sprite or an instanced mesh is at, so hits carry no face/uv. Lines
+   * are one pixel wide on GL ES whatever the display density. A lines
+   * or points geometry may have no indices at all (it then draws
+   * nothing; the other topologies reject that at add()).
+   * wireframeGeometry/edgesGeometry build "lines" over a triangle
+   * geometry's own vertices. */
+  topology?: Topology
   /** Vertex layout; absent means "standard". Must match the material's
    * layout - the scene rejects a mismatched pair at add(). */
   layout?: VertexLayout
@@ -270,6 +315,7 @@ export function withAttribute(geometry: Geometry, attr: VertexAttribute, fill: A
   return {
     vertices: out,
     indices: geometry.indices,
+    topology: geometry.topology,
     layout,
     label: label ?? (geometry.label ? geometry.label + "-" + attr.name : undefined),
   }
@@ -394,6 +440,7 @@ export function transformGeometry(geometry: Geometry, transform: TransformUpdate
   return {
     vertices: out,
     indices: geometry.indices,
+    topology: geometry.topology,
     layout: geometry.layout,
     label: label ?? (geometry.label ? geometry.label + "-transformed" : undefined),
   }
@@ -403,7 +450,9 @@ export function transformGeometry(geometry: Geometry, transform: TransformUpdate
  * Concatenate geometries into one: vertices appended in order, indices
  * offset to match, uint32 indices past 64k vertices. Every part must share
  * one layout - a mixed list throws, because the strides differ and a merge
- * that picked one would draw garbage, not a mesh missing a channel. The
+ * that picked one would draw garbage, not a mesh missing a channel - and
+ * one list topology (a mixed list throws the same way; strips cannot be
+ * concatenated at all, the seam would join them). The
  * second half of authoring a static scene as data (Three's
  * `BufferGeometryUtils.mergeGeometries`): the result is one draw entry and
  * one uModel write however many parts went in, so only what actually moves
@@ -414,12 +463,17 @@ export function mergeGeometries(parts: Geometry[], label?: string): Geometry {
   let layout = parts[0]!.layout
   let key = layoutKey(layout)
   let stride = layoutStride(layout)
+  let topology = geometryTopology(parts[0]!)
+  if (topology === "line-strip" || topology === "triangle-strip") throw new Error("mergeGeometries: cannot merge " + topology + " geometry")
   let floats = 0
   let indexCount = 0
   for (let part of parts) {
     if (layoutKey(part.layout) !== key) {
       throw new Error("mergeGeometries: mixed layouts (" + key + " and " + layoutKey(part.layout) + ")")
     }
+    if (geometryTopology(part) !== topology) {
+      throw new Error("mergeGeometries: mixed topologies (" + topology + " and " + geometryTopology(part) + ")")
+    }
     if (part.vertices.length % stride !== 0) {
       throw new Error("mergeGeometries: a part's vertex data is not a whole number of " + key + " vertices")
     }
@@ -439,7 +493,134 @@ export function mergeGeometries(parts: Geometry[], label?: string): Geometry {
     vOffset += part.vertices.length
     iOffset += src.length
   }
-  return { vertices, indices, layout, label }
+  return { vertices, indices, topology: parts[0]!.topology, layout, label }
+}
+
+/** Positions closer than this (model units) are one vertex to the edge
+ * builders: a uv seam or a per-face normal split duplicates a position,
+ * and an edge is the same edge whichever copy a triangle names. */
+const WELD_PRECISION = 1e-4
+
+/** Degrees between two faces' normals from which the edge between them
+ * counts as a feature edge in edgesGeometry; under it the faces read as
+ * one smooth surface and the edge stays hidden. Three's default. */
+const EDGES_THRESHOLD_ANGLE = 1
+
+/** One id per vertex, shared by every vertex at the same position (to
+ * WELD_PRECISION) whatever its normal and uv; plus the id count. */
+function weldPositions(geometry: Geometry): { ids: Uint32Array; count: number } {
+  let v = geometry.vertices
+  let stride = layoutStride(geometry.layout)
+  let count = v.length / stride
+  let ids = new Uint32Array(count)
+  let seen = new Map<string, number>()
+  let scale = 1 / WELD_PRECISION
+  for (let i = 0; i < count; i++) {
+    let b = i * stride
+    let key = Math.round(v[b]! * scale) + "," + Math.round(v[b + 1]! * scale) + "," + Math.round(v[b + 2]! * scale)
+    let id = seen.get(key)
+    if (id === undefined) {
+      id = seen.size
+      seen.set(key, id)
+    }
+    ids[i] = id
+  }
+  return { ids, count: seen.size }
+}
+
+/** The edge table of a triangle geometry, welded by position, as a lines
+ * index list: every edge once for `cosThreshold` null, else the feature
+ * edges - those with one face (a border) or whose two faces' normals
+ * dot at or below the threshold. Each edge names the vertex pair of the
+ * first triangle that had it. */
+function edgeIndices(geometry: Geometry, name: string, cosThreshold: number | null): Uint16Array | Uint32Array {
+  if (geometryTopology(geometry) !== "triangles") {
+    throw new Error(name + ": needs a triangle geometry, got " + geometryTopology(geometry))
+  }
+  let v = geometry.vertices
+  let stride = layoutStride(geometry.layout)
+  let weld = weldPositions(geometry)
+  let src = geometry.indices
+  type Edge = { a: number; b: number; nx: number; ny: number; nz: number; faces: number; sharp: boolean }
+  let edges = new Map<number, Edge>()
+  for (let t = 0; t + 2 < src.length; t += 3) {
+    let i0 = src[t]!, i1 = src[t + 1]!, i2 = src[t + 2]!
+    let p0 = i0 * stride, p1 = i1 * stride, p2 = i2 * stride
+    // The face normal, for the feature test.
+    let ux = v[p1]! - v[p0]!, uy = v[p1 + 1]! - v[p0 + 1]!, uz = v[p1 + 2]! - v[p0 + 2]!
+    let wx = v[p2]! - v[p0]!, wy = v[p2 + 1]! - v[p0 + 1]!, wz = v[p2 + 2]! - v[p0 + 2]!
+    let nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx
+    let len = Math.hypot(nx, ny, nz) || 1
+    nx /= len
+    ny /= len
+    nz /= len
+    for (let k = 0; k < 3; k++) {
+      let ia = k === 0 ? i0 : k === 1 ? i1 : i2
+      let ib = k === 0 ? i1 : k === 1 ? i2 : i0
+      let wa = weld.ids[ia]!, wb = weld.ids[ib]!
+      if (wa === wb) continue
+      let key = Math.min(wa, wb) * weld.count + Math.max(wa, wb)
+      let e = edges.get(key)
+      if (e === undefined) {
+        edges.set(key, { a: ia, b: ib, nx, ny, nz, faces: 1, sharp: false })
+      } else {
+        e.faces++
+        if (cosThreshold !== null && !e.sharp && e.nx * nx + e.ny * ny + e.nz * nz <= cosThreshold) e.sharp = true
+      }
+    }
+  }
+  let out: number[] = []
+  for (let e of edges.values()) {
+    if (cosThreshold === null || e.faces === 1 || e.sharp) out.push(e.a, e.b)
+  }
+  return packIndices(out, v.length / stride)
+}
+
+/**
+ * Every edge of a triangle geometry as a "lines" geometry over the SAME
+ * vertices (Three's WireframeGeometry): each triangle's three sides, once
+ * each - edges are matched by position, so a uv seam or a per-face
+ * normal split draws one line, not two on top of each other. The
+ * source's vertex array and layout are shared by reference, and so is
+ * their GPU upload, which makes the wireframe a second index buffer over
+ * the same vertices: a "skinned" part's wireframe draws in its pose
+ * under `unlit({ skinned: true })` with the mesh's own palette, and any
+ * material draws it as lines because the topology rides on the
+ * geometry. Lines are one pixel wide.
+ */
+export function wireframeGeometry(geometry: Geometry, label?: string): Geometry {
+  return {
+    vertices: geometry.vertices,
+    indices: edgeIndices(geometry, "wireframeGeometry", null),
+    topology: "lines",
+    layout: geometry.layout,
+    label: label ?? (geometry.label ? geometry.label + "-wireframe" : undefined),
+  }
+}
+
+/**
+ * The feature edges of a triangle geometry as a "lines" geometry over the
+ * same vertices (Three's EdgesGeometry): an edge draws when its two faces
+ * meet at `thresholdAngle` degrees or more, or when only one face has it
+ * (an open border): the outline that a dense mesh's wireframe, a solid
+ * blob, cannot give. A box draws its twelve edges and no face diagonals
+ * at any threshold; a generated round shape is faceted, so its facet
+ * lines show until the threshold passes its facet angle (360 divided by
+ * the radial segments: a default cylinder loses its side seams and keeps
+ * its two rims from 16 degrees, a default sphere draws nothing from 16).
+ * A smooth closed shape above its facet angle has no edges at all, and
+ * the empty lines geometry that comes back attaches and draws nothing.
+ * Shares vertices, layout and GPU upload with the source like
+ * wireframeGeometry.
+ */
+export function edgesGeometry(geometry: Geometry, thresholdAngle = EDGES_THRESHOLD_ANGLE, label?: string): Geometry {
+  return {
+    vertices: geometry.vertices,
+    indices: edgeIndices(geometry, "edgesGeometry", Math.cos((thresholdAngle * Math.PI) / 180)),
+    topology: "lines",
+    layout: geometry.layout,
+    label: label ?? (geometry.label ? geometry.label + "-edges" : undefined),
+  }
 }
 
 // Indices for a row-major (cellRows + 1) x (cellCols + 1) vertex grid: two

package/src/gltf.ts

@@ -1,9 +1,12 @@
 // glTF 2.0, the subset an app needs to show authored models: the scene's
 // node tree RETAINED - a node table of local TRS with parent links (matrix
 // nodes decomposed; shear dropped), vertices in NODE-LOCAL space, one part
-// per mesh primitive referencing its node - triangles with positions,
-// normals (flat ones generated when absent, per the spec), one UV set and
-// indices, and materials reduced to what lit()/unlit() draw - base color
+// per mesh primitive referencing its node - positions, normals (flat ones
+// generated when absent, per the spec, for triangles), one UV set and
+// indices in the primitive's topology (strips and fans unrolled to
+// triangle lists, a line loop closed into a strip; lines and points keep
+// theirs on the geometry), and materials reduced to what lit()/unlit()
+// draw - base color
 // factor and texture, normal map (with scale), emissive factor and map
 // (KHR_materials_emissive_strength as the intensity), double-sidedness, alpha
 // blending and masking - plus the file's animations as baked clips
@@ -19,8 +22,8 @@
 // bytes in `images`, and uploading is the engine side's job.
 //
 // Outside the subset: Draco/meshopt-compressed meshes and any other
-// required extension throw naming it; non-triangle primitives, sparse
-// accessors and morph targets (the "weights" channel path) are skipped
+// required extension throw naming it; sparse accessors and morph
+// targets (the "weights" channel path) are skipped
 // or ignored; vertex colors, tangents and further UV sets are dropped
 // (the standard layout has no slot for them yet). Skins ARE parsed:
 // joints, inverse binds, and the "skinned" vertex layout.
@@ -30,6 +33,7 @@ import { linearToSrgb } from "./color.ts"
 import type { Mat4, Quat, Vec3 } from "./math.ts"
 import { layoutStride, packGeometry, packIndices, STANDARD_FLOATS } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
+import type { Topology } from "@solidrt/core/gpu"
 
 /** What lit()/unlit() take from a glTF material. */
 export type ModelMaterial = {
@@ -182,7 +186,39 @@ export type UriResolver = (uri: string) => Uint8Array
 const GLB_MAGIC = 0x46546c67
 const CHUNK_JSON = 0x4e4f534a
 const CHUNK_BIN = 0x004e4942
+// glTF primitive modes (the GL enum values).
+const MODE_POINTS = 0
+const MODE_LINES = 1
+const MODE_LINE_LOOP = 2
+const MODE_LINE_STRIP = 3
 const MODE_TRIANGLES = 4
+const MODE_TRIANGLE_STRIP = 5
+const MODE_TRIANGLE_FAN = 6
+
+/** A triangle strip unrolled to a list: triangle t is (t, t+1, t+2),
+ * every odd one with its last two swapped so the winding stays put. */
+function stripTriangles(strip: ArrayLike<number>): number[] {
+  let out: number[] = []
+  for (let t = 0; t + 2 < strip.length; t++) {
+    if (t % 2 === 0) out.push(strip[t]!, strip[t + 1]!, strip[t + 2]!)
+    else out.push(strip[t]!, strip[t + 2]!, strip[t + 1]!)
+  }
+  return out
+}
+
+/** A triangle fan unrolled to a list: every triangle shares the hub. */
+function fanTriangles(fan: ArrayLike<number>): number[] {
+  let out: number[] = []
+  for (let t = 1; t + 1 < fan.length; t++) out.push(fan[0]!, fan[t]!, fan[t + 1]!)
+  return out
+}
+
+/** A line loop as a strip that returns to its first vertex. */
+function closeLoop(loop: ArrayLike<number>): number[] {
+  let out = Array.from(loop)
+  if (loop.length > 0) out.push(loop[0]!)
+  return out
+}
 
 // The spec's alphaCutoff when a MASK material leaves it out.
 const GLTF_ALPHA_CUTOFF = 0.5
@@ -383,8 +419,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   let bounds = new Float32Array([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity])
 
   let emit = (prim: any, name: string, node: number, world: Mat4, skin: number | null): void => {
-    if ((prim.mode ?? MODE_TRIANGLES) !== MODE_TRIANGLES) return
     if (prim.attributes?.POSITION === undefined) return
+    let mode: number = prim.mode ?? MODE_TRIANGLES
     let pos = accessorFloats(prim.attributes.POSITION, name + " POSITION")
     if (pos.elements !== 3) throw new Error("parseGltf: " + name + " POSITION is not VEC3")
     let count = pos.count
@@ -408,17 +444,57 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       weights = w.data
     }
     let stride = skinned ? SKINNED_FLOATS : STANDARD_FLOATS
-    let indices: ArrayLike<number> =
+    let raw: ArrayLike<number> =
       prim.indices !== undefined ? accessorFloats(prim.indices, name + " indices").data : Array.from({ length: count }, (_, i) => i)
-    if (indices.length % 3 !== 0) throw new Error("parseGltf: " + name + " index count is not a multiple of 3")
+    // The primitive's topology, carried on the geometry. Triangle strips
+    // and fans are unrolled to lists (what the winding flip, the
+    // flat-shading un-index and the picking shape expect) and a line
+    // loop, which has no GPU topology, is closed into a strip.
+    let topology: Topology
+    let indices: ArrayLike<number>
+    switch (mode) {
+      case MODE_TRIANGLES:
+        topology = "triangles"
+        indices = raw
+        break
+      case MODE_TRIANGLE_STRIP:
+        topology = "triangles"
+        indices = stripTriangles(raw)
+        break
+      case MODE_TRIANGLE_FAN:
+        topology = "triangles"
+        indices = fanTriangles(raw)
+        break
+      case MODE_LINES:
+        topology = "lines"
+        indices = raw
+        break
+      case MODE_LINE_STRIP:
+        topology = "line-strip"
+        indices = raw
+        break
+      case MODE_LINE_LOOP:
+        topology = "line-strip"
+        indices = closeLoop(raw)
+        break
+      case MODE_POINTS:
+        topology = "points"
+        indices = raw
+        break
+      default:
+        throw new Error("parseGltf: " + name + " has an unknown primitive mode " + mode)
+    }
+    let triangles = topology === "triangles"
+    if (triangles && indices.length % 3 !== 0) throw new Error("parseGltf: " + name + " index count is not a multiple of 3")
 
     // A mirroring chain (negative world determinant at the rest pose)
     // flips the displayed winding, so the index order is flipped here to
     // compensate - cull: "back" keeps the outside. Stored normals stay the
     // authored ones: the runtime's inverse-transpose maps them outward for
     // the flipped winding. Baked from the REST pose; a scale animated
-    // across zero would unbake it, which is pathological.
-    let flip = !skinned && det3(world) < 0
+    // across zero would unbake it, which is pathological. Lines and
+    // points have no winding.
+    let flip = triangles && !skinned && det3(world) < 0
     // Joint boxes need the skin's inverse binds, and skins are built after
     // the walk (their joints are ordinary nodes the walk registers), so
     // the arrays are parked under the FILE's skin index and grown then.
@@ -426,14 +502,18 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
 
     let vertices: Float32Array
     let packedIndices: number[]
-    if (nrm !== null) {
+    if (nrm !== null || !triangles) {
+      // Indexed as authored. Lines and points without normals get zero
+      // ones (there is no face to take one from; nothing lights them).
       vertices = new Float32Array(count * stride)
       for (let i = 0; i < count; i++) writeVertex(vertices, i, pos.data, nrm, uv, i, stride, joints, weights)
-      packedIndices = new Array(indices.length)
-      for (let i = 0; i < indices.length; i += 3) {
-        packedIndices[i] = indices[i]!
-        packedIndices[i + 1] = flip ? indices[i + 2]! : indices[i + 1]!
-        packedIndices[i + 2] = flip ? indices[i + 1]! : indices[i + 2]!
+      packedIndices = Array.from(indices)
+      if (flip) {
+        for (let i = 0; i < packedIndices.length; i += 3) {
+          let b = packedIndices[i + 1]!
+          packedIndices[i + 1] = packedIndices[i + 2]!
+          packedIndices[i + 2] = b
+        }
       }
     } else {
       // No normals: the spec asks for flat shading, which needs one vertex
@@ -508,6 +588,7 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     let geometry: Geometry = skinned
       ? { vertices, indices: packIndices(packedIndices, count), layout: "skinned", label: name }
       : packGeometry(vertices, packedIndices, { label: name })
+    if (!triangles) geometry.topology = topology
     parts.push({ name, node, skin, geometry, material })
   }
 

package/src/index.ts

@@ -6,7 +6,7 @@
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
 export { add, createGroup, getRotation, getTransform, lookAt, remove, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
-export type { SceneNode, ScenePointerEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
+export type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
 export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, removeInstance, setCastShadow, setCulling, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, INSTANCE_FLOATS } from "./mesh.ts"
 export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceSlots, InstanceStyle, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions } from "./mesh.ts"
 export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight, MAX_SHADOWS } from "./light.ts"
@@ -26,15 +26,16 @@ export type {
   SpotShadowOptions,
 } from "./light.ts"
 export { createScene } from "./scene.ts"
-export type { Capsule, EnvironmentOptions, FogOptions, Hit, Impact, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, View, ViewOptions, Volume } from "./scene.ts"
+export { feedPointer } from "./scene-pointer.ts"
+export type { Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
 export { moveAndSlide } from "./collision.ts"
-export type { MoveOptions, MoveResult, MoveScene } from "./collision.ts"
+export type { MoveScene } from "./collision.ts"
 export { equirectToCube, loadEnvironment } from "./environment.ts"
 export { linearColor, linearToSrgb, srgbToLinear } from "./color.ts"
 export type { CameraState, CameraUpdate, OrthoExtent } from "./camera.ts"
 export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
 export { disposeGeometry } from "./geometry-gpu.ts"
-export { box, circle, cone, cylinder, fillAttribute, fillColors, geometryBounds, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, packGeometry, plane, ring, sphere, torus, torusKnot, transformGeometry, validateGeometry, withAttribute, withColors, STANDARD_FLOATS, VERTEX_LAYOUTS } from "./geometry.ts"
+export { box, circle, cone, cylinder, fillAttribute, fillColors, edgesGeometry, geometryBounds, geometryTopology, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, packGeometry, plane, ring, sphere, torus, torusKnot, transformGeometry, validateGeometry, wireframeGeometry, withAttribute, withColors, STANDARD_FLOATS, VERTEX_LAYOUTS } from "./geometry.ts"
 export type { AttributeFill, BoxOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, Geometry, GeometryOptions, PlaneOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"
 export { fillet, roundRect, shape, triangulate } from "./profile.ts"
 export type { Profile, ProfilePoint } from "./profile.ts"
@@ -42,8 +43,9 @@ export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
 export { lit, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
 export type { LitOptions, Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
-export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedMesh, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, useScene } from "./components.tsx"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedMesh, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene } from "./components/index.ts"
 export type {
+  CameraTarget,
   DirectionalLightProps,
   FirstPersonCameraProps,
   HemisphereLightProps,
@@ -55,25 +57,28 @@ export type {
   PointerEventProps,
   PointLightProps,
   RecordMeshProps,
-  SceneInput,
-  SceneInputListener,
+  ScenePointerProps,
   SceneProps,
   SpotLightProps,
   SpriteProps,
   TransformProps,
-} from "./components.tsx"
+  View3dProps,
+} from "./components/index.ts"
 export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
 export type { ModelChannel, ModelClip, ModelData, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
 export { createModel, loadGltf, loadModel } from "./model.ts"
 export type { Model, ModelMaps, ModelOptions } from "./model.ts"
+export { bindSkeleton } from "./skeleton.ts"
 export { createMixer } from "./mixer.ts"
 export type { Mixer, MixerOptions, MixerPlayOptions } from "./mixer.ts"
 export { sampleChannel } from "./clip.ts"
 export { createOrbitCamera } from "./orbit.ts"
-export type { OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
+export type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
 export { createFirstPersonCamera } from "./first-person.ts"
-export type { FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonTarget } from "./first-person.ts"
+export type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonTarget } from "./first-person.ts"
+export { firstPersonActions, firstPersonBindings, orbitActions, orbitBindings } from "./input.ts"
+export type { CameraDevices } from "./input.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the
 // root's lookAt is the scene verb, the same split as `add`.
 export { rayBoxDistance, compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, orthographic, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"

package/src/input.ts

@@ -0,0 +1,79 @@
+// The standard input wiring for the 3d camera controls: the action
+// declarations each control consumes (its axes, by the shared vocabulary)
+// and a preset per control that binds the devices an app hands in. A
+// preset is plain data - the bindings the app could write by hand -
+// applied with `input.bind(orbitBindings({ pointer, gamepad }))` and
+// adjusted afterwards with unbind; nothing binds unless the app says so
+// (ARCHITECTURE.md).
+//
+// Devices are the nouns: `pointer` is the feed of the element showing the
+// scene (`createPointerFeed()`, handed to `<Scene pointer>`), `gamepad` a
+// core gamepad device (`gamepad(0)`, or `gamepad()` for any pad), and
+// `keyboard` the core keyboard device, whose key events reach the map
+// through `input.handlers` spread on the window.
+//
+// Keys and sticks move the CAMERA where a drag moves the content (the
+// stick right orbits the eye to the right; a drag right spins the scene
+// to the right), so the rotate and pan bindings of those devices go
+// through invert() and each axis keeps its one meaning. `look` is the
+// exception by nature: a drag and a stick both turn the eye.
+
+import { invert } from "@solidrt/core/input"
+import type { Binding, GamepadDevice, KeyboardDevice, PointerFeed } from "@solidrt/core"
+
+export type CameraDevices = {
+  pointer?: PointerFeed
+  gamepad?: GamepadDevice
+  keyboard?: KeyboardDevice
+}
+
+/** The orbit control's actions: `rotate`, `zoom`, `pan`. */
+export let orbitActions = { rotate: "vec2", zoom: "axis", pan: "vec2" } as const
+
+/**
+ * The orbit camera's standard bindings: a drag rotates, a Ctrl-drag or a
+ * right-drag pans (the desktop pans, Three's and Blender's; a chorded or
+ * right-button drag feeds only `pan`, never `rotate`), a pinch and the
+ * wheel zoom, two fingers pan; the right stick rotates, the triggers
+ * zoom, the left stick pans; the arrow keys rotate and minus/equals zoom.
+ */
+export function orbitBindings(devices: CameraDevices): Binding[] {
+  let out: Binding[] = []
+  let { pointer, gamepad, keyboard } = devices
+  if (pointer) {
+    out.push(
+      { action: "rotate", source: pointer.drag },
+      { action: "pan", source: pointer.drag("Ctrl") },
+      { action: "pan", source: pointer.drag("Right") },
+      { action: "pan", source: pointer.pan },
+      { action: "zoom", source: pointer.pinch },
+      { action: "zoom", source: pointer.wheel },
+    )
+  }
+  if (gamepad) {
+    out.push({ action: "rotate", source: invert(gamepad.rightStick) }, { action: "zoom", source: gamepad.triggers }, { action: "pan", source: invert(gamepad.leftStick) })
+  }
+  if (keyboard) {
+    out.push({ action: "rotate", source: invert(keyboard.arrows) }, { action: "zoom", source: keyboard.axis("Minus", "Equal") })
+  }
+  return out
+}
+
+/** The first-person control's actions: `look`, `move`, `rise`. */
+export let firstPersonActions = { look: "vec2", move: "vec2", rise: "axis" } as const
+
+/**
+ * The first-person camera's standard bindings: a drag looks around and so
+ * does mouse motion while the pointer is locked (the app locks it: see
+ * examples/first-person.tsx); the right stick looks, the left stick
+ * walks, the shoulders rise and sink in fly mode; WASD and the arrows
+ * walk, Q/E rise and sink.
+ */
+export function firstPersonBindings(devices: CameraDevices): Binding[] {
+  let out: Binding[] = []
+  let { pointer, gamepad, keyboard } = devices
+  if (pointer) out.push({ action: "look", source: pointer.drag }, { action: "look", source: pointer.mouseDelta })
+  if (gamepad) out.push({ action: "look", source: gamepad.rightStick }, { action: "move", source: gamepad.leftStick }, { action: "rise", source: gamepad.shoulders })
+  if (keyboard) out.push({ action: "move", source: keyboard.wasd }, { action: "move", source: keyboard.arrows }, { action: "rise", source: keyboard.axis("KeyQ", "KeyE") })
+  return out
+}