@solidrt/3d 0.0.46

package/AGENTS.md

@@ -0,0 +1,114 @@
+# @solidrt/3d - agent notes
+
+A retained 3D scene graph above `@solidrt/core/gpu`. Meshes, materials and
+a camera compile to ONE depth-buffered draw target (`createDrawTarget` +
+one `addDraw` entry per mesh); the scene's output is an ordinary texture
+id composited as a `<texture>` leaf, so it takes layout, transforms,
+blendMode and pointer events like any element. Design rationale:
+`okf/research/scene-graph-3d.md` in the repo.
+
+## The model
+
+- Two layers. The imperative core is Solid-free: `createScene`,
+  `createMesh(geometry, material)`, `add`/`remove`, `setTransform`,
+  `setVisible` - plain objects with dirty flags, batched to a microtask,
+  one `setDrawParams` (the uModel matrix) per changed mesh and ONE
+  `setTargetParams` (the shared uViewProj) per camera change, however many
+  meshes. The component
+  face (`Scene`/`Group`/`Mesh`/`PerspectiveCamera`) syncs props into that
+  core over context and renders nothing itself.
+- Rendering is the runtime's. The target is `render: "auto"`: it
+  re-renders when entries change, so a STATIC scene costs zero passes and
+  the library registers no frame loop. Continuous animation is the app's
+  own `onFrame` writing a signal (declarative) or `setTransform` on a
+  `ref`-grabbed node (the frame-rate escape hatch - signals carry
+  structure, per-frame motion goes straight to the scene).
+- One vertex layout everywhere: `aPos` vec3 + `aNormal` vec3 + `aUV` vec2,
+  uint16-indexed. Geometry GPU buffers are lazy, shared, and app-lifetime
+  (owner-scoped free would break sharing); `disposeGeometry` frees them.
+- Materials dedupe hard: one program + one pipeline per material CLASS
+  (unlit color, unlit map), `depth: true` + `cull: "back"`; an instance is
+  just per-entry uniforms (`uColor`) and bindings (`uMap`).
+
+## Components
+
+| Component | Props |
+| --- | --- |
+| `Scene` | `width`, `height` (target pixels), `clearColor?`, `label?`, `ref?(scene)` |
+| `Group` | `position?`, `rotation?` (Euler radians, x-y-z order), `scale?` (number = uniform), `visible?`, `ref?(node)` |
+| `Mesh` | `geometry`, `material`, transforms as Group, `ref?(mesh)` |
+| `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` |
+
+Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
+distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
+zoomSpeed? })` - drag-to-rotate, wheel-to-zoom, optional auto-orbit. Spread
+`orbit.handlers` onto the input-owning element, call `orbit.update(dt)`
+from your onFrame (no frame loop of its own), and use its return - true
+when the pose changed - to gate per-frame dependents like a `uCamPos`
+write. `orbiting()` is reactive (HUD-safe); the pose is plain state via
+`pose()`/`set()` (also the debug-command shape). It drives position and
+target only; fov/near/far stay on scene.setCamera. In a component tree,
+reach the scene via `<Scene ref>` or useScene().
+
+Geometry: `box(w?, h?, d?)`, `plane(w?, h?)` (XY, faces +z - rotate
+`[-Math.PI/2, 0, 0]` for a floor), `sphere(radius?, wSeg?, hSeg?)`,
+`torusKnot(radius?, tube?, tubularSeg?, radialSeg?, p?, q?)` (standing
+y-up, unlike Three's z-up).
+Materials:
+
+- `unlit({ color?, map? })` - straight `[r, g, b, a?]` 0..1, premultiplied
+  internally.
+- `shaderMaterial({ vertex, fragment, params?, textures?, depth?,
+  depthWrite?, blend?, cull?, topology?, label? })` - your own GLSL, the
+  custom-look escape hatch. The vertex stage MUST declare and use BOTH
+  `uniform mat4 uModel` (the mesh's world matrix, per entry) and
+  `uniform mat4 uViewProj` (the camera, shared target-level params) -
+  transform with `uViewProj * uModel * vec4(aPos, 1.0)`; attributes come
+  from the shared layout by name; sources without
+  `#version` get the standard pipeline preamble. App-driven uniforms
+  beyond uModel/uViewProj: seed via `params`, then write per mesh with
+  `setMeshParams(mesh, { name: value })` (validated names; values persist
+  across entry rebuilds; frame-rate-safe like setTransform).
+
+## Traps
+
+- The y-down clip flip is baked into `perspective()`; scene code and
+  geometry are plain y-up right-handed, and CCW-outward winding culls
+  correctly with `cull: "back"`. Do NOT negate y anywhere else, and do not
+  "fix" the negated row of `perspective()` - both would mirror the winding
+  and show mesh interiors.
+- `visible: false` keeps the entry, drawn with `instanceCount: 0` (a
+  cheap off switch). Hidden meshes skip uModel writes; the fresh matrix is
+  written on unhide.
+- Alpha does not blend in v1: pipelines are opaque (`blend: "none"`), a
+  translucent color overwrites. Transparency waits on blend factors +
+  sorting (research note, staging step 4).
+- Rotation is Euler radians applied x, then y, then z. No quaternions in
+  v1.
+- Transforms have ONE write path: `setTransform`/`setVisible` (or the
+  props that call them). Mutating `node.position` directly does not sync.
+- A camera change is ONE `setTargetParams` write (uViewProj is target
+  state), independent of mesh count - never reintroduce per-mesh camera
+  writes. Scene scale honestly: hundreds to a
+  few thousand objects, bounded by the interpreter, not the GPU.
+- Entry rebuild order: `setGeometry`/`setMaterial` re-add the entry at the
+  list END. Irrelevant while everything is opaque + depth-tested; revisit
+  when transparency lands.
+- `useScene()`/`Group`/`Mesh` throw outside `<Scene>` (default-less
+  context).
+- A `shaderMaterial` INSTANCE is the pipeline handle: identical sources
+  compile twice - no dedupe by source value (deliberate; hidden
+  content-keyed caches are the anti-pattern the GPU layer avoids). Create
+  one per look at app scope, share across meshes, `dispose()` when done
+  for good.
+- A shaderMaterial vertex stage without `uniform mat4 uModel` (declared
+  AND used) throws at mesh attach - the scene seeds uModel on every entry
+  and the engine rejects unknown uniform names. One without `uViewProj`
+  also throws at attach when it is the scene's ONLY material class: after
+  the first camera sync, _attach re-issues the shared uViewProj (same
+  value, one write) so the coverage error lands at add() instead of
+  inside a later camera-sync microtask. Only the very first attach (no
+  camera sync yet) reports it asynchronously, from the sync that attach
+  schedules. With other declaring materials present it silently ignores
+  the camera instead (partial coverage is legal). Declare and use both,
+  always.

package/README.md

@@ -0,0 +1,42 @@
+# @solidrt/3d
+
+A retained 3D scene graph for SolidRT: meshes, materials and a camera,
+declared as Solid components, rendered by the runtime into an ordinary
+texture in your UI tree.
+
+```tsx
+import { createSignal, onFrame, render } from "@solidrt/core"
+import { box, Mesh, PerspectiveCamera, Scene, unlit } from "@solidrt/3d"
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 2000))
+  return (
+    <window>
+      <Scene width={720} height={720}>
+        <PerspectiveCamera position={[0, 1.5, 3]} lookAt={[0, 0, 0]} />
+        <Mesh geometry={box()} material={unlit({ color: [0.9, 0.3, 0.3] })} rotation={[0, spin(), 0]} />
+      </Scene>
+    </window>
+  )
+}
+render(() => <App />)
+```
+
+The scene compiles to one depth-buffered GPU draw target: one draw entry
+per mesh, one shared pipeline per material class, cross-mesh occlusion
+from the shared depth buffer. A static scene costs zero GPU passes - the
+runtime re-renders the target only when something changes - and a moved
+mesh costs one uniform write.
+
+There is also an imperative layer underneath (`createScene`, `createMesh`,
+`setTransform`, ...) usable without components, plus a small math module
+(`@solidrt/3d/math`: column-major mat4, perspective, lookAt).
+
+v1 scope: unlit color/textured materials plus `shaderMaterial` (your own
+GLSL as a first-class material), box/plane/sphere geometry, one
+perspective camera with an orbit control (`createOrbitCamera`: drag,
+zoom, auto-orbit). Lights, transparency, model loading and picking are
+staged next - see `okf/research/scene-graph-3d.md` for the roadmap. Full
+usage notes and traps: [AGENTS.md](AGENTS.md); runnable examples:
+[examples/](examples/).

package/examples/README.md

@@ -0,0 +1,9 @@
+# @solidrt/3d examples
+
+One concept per file; run with `bunx srt run <file>` from an app that
+depends on `@solidrt/3d` (or in-repo from the package directory).
+
+- `scene-basic.tsx` - the whole v1 surface: a `<Scene>` composited as a
+  texture leaf, `<PerspectiveCamera>`, a ground plane, a spinning
+  `<Group>` of unlit meshes with real depth-buffer occlusion, geometry
+  and pipeline sharing, and the one-signal onFrame drive.

package/examples/scene-basic.tsx

@@ -0,0 +1,53 @@
+// A minimal scene: unlit meshes with real cross-mesh occlusion (one shared
+// depth buffer), a spinning group, and a fixed camera. One onFrame loop
+// drives one signal; the library keeps every draw entry's uModel (and the
+// scene target's shared uViewProj) in step.
+// The sphere orbits with the group, crossing behind and in front of the
+// tall box - that alternation is the depth buffer at work, not draw order.
+//
+// NOTE a registered onFrame keeps the client presenting every vsync -
+// right for a continuously animating scene, wrong for a static one (a
+// static scene costs zero passes; drop the onFrame and it idles).
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, Group, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
+
+const SIZE = 720
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 2000))
+
+  // Geometries and materials are plain values, shared freely: both boxes
+  // use one cube geometry (one vertex/index buffer pair on the GPU), and
+  // every mesh here shares the one unlit-color pipeline.
+  let cube = box()
+  let floor = plane(6, 6, "floor")
+  let ball = sphere(0.35)
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="scene-basic">
+          <PerspectiveCamera fov={55} position={[0, 1.6, 3.6]} lookAt={[0, 0.3, 0]} />
+          <Mesh
+            geometry={floor}
+            material={unlit({ color: [0.16, 0.17, 0.22] })}
+            rotation={[-Math.PI / 2, 0, 0]}
+          />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={cube} material={unlit({ color: [0.85, 0.3, 0.3] })} position={[0, 0.5, 0]} />
+            <Mesh
+              geometry={cube}
+              material={unlit({ color: [0.9, 0.8, 0.35] })}
+              position={[-1.1, 0.7, 0]}
+              scale={[0.5, 1.4, 0.5]}
+            />
+            <Mesh geometry={ball} material={unlit({ color: [0.35, 0.65, 0.9] })} position={[1.1, 0.35, 0]} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@solidrt/3d",
+  "version": "0.0.46",
+  "license": "MIT",
+  "author": "Antoine van Wel",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./math": "./src/math.ts"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "AGENTS.md"
+  ],
+  "peerDependencies": {
+    "@solidjs/signals": "2.0.0-beta.31",
+    "@solidrt/core": "0.0.46"
+  }
+}

package/src/components.tsx

@@ -0,0 +1,148 @@
+// The Solid face: PascalCase components over context, syncing the retained
+// scene (scene.ts) - no new intrinsic elements, no renderer changes. Props
+// follow the Solid 2.0 model (reactive values, no destructuring); effects
+// write into the retained nodes and the runtime's dirty flush renders.
+// Anything moving at frame rate can bypass the declarative layer: grab the
+// node with `ref` and call setTransform from onFrame - signals carry
+// structure and slow state, per-frame motion goes straight to the scene.
+
+import { createContext, createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { ParentComponent, VoidComponent } from "@solidrt/core"
+import {
+  add,
+  createGroup,
+  createMesh,
+  createScene,
+  remove,
+  setGeometry,
+  setMaterial,
+  setTransform,
+  setVisible,
+} from "./scene.ts"
+import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode } from "./scene.ts"
+import type { Geometry } from "./geometry.ts"
+import type { Material } from "./material.ts"
+import type { Vec3 } from "./math.ts"
+
+type SceneCtx = { scene: SceneHandle; parent: SceneNode }
+let SceneContext = createContext<SceneCtx>()
+
+/**
+ * The enclosing scene and parent node - the imperative escape hatch inside
+ * a component subtree (throws outside a `<Scene>`).
+ */
+export function useScene(): SceneCtx {
+  return useContext(SceneContext)
+}
+
+export type TransformProps = {
+  position?: Vec3
+  /** Euler radians, applied x then y then z. */
+  rotation?: Vec3
+  scale?: Vec3 | number
+  visible?: boolean
+}
+
+function syncNode(node: SceneNode, props: TransformProps): void {
+  createEffect(
+    () => [props.position, props.rotation, props.scale, props.visible] as const,
+    ([position, rotation, scale, visible]) => {
+      setTransform(node, { position, rotation, scale })
+      setVisible(node, visible !== false)
+    },
+  )
+}
+
+export type SceneProps = {
+  width: number
+  height: number
+  clearColor?: [number, number, number, number]
+  label?: string
+  ref?: (scene: SceneHandle) => void
+}
+
+/**
+ * Owns a draw target and composites it as an ordinary `<texture>` leaf, so
+ * the output takes layout, transforms, blendMode, and pointer events like
+ * any element. Children (Mesh/Group/PerspectiveCamera) render nothing
+ * themselves - they populate the retained scene through context.
+ */
+export let Scene: ParentComponent<SceneProps> = props => {
+  let scene = untrack(() =>
+    createScene(props.width, props.height, { clearColor: props.clearColor, label: props.label }),
+  )
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => scene.setSize(w, h),
+  )
+  untrack(() => props.ref)?.(scene)
+  return (
+    <SceneContext value={{ scene, parent: scene.root }}>
+      <texture src={scene.texture} width={props.width} height={props.height} />
+      {props.children}
+    </SceneContext>
+  )
+}
+
+/** A transform node: children inherit its position/rotation/scale. */
+export let Group: ParentComponent<TransformProps & { ref?: (node: SceneNode) => void }> = props => {
+  let ctx = useContext(SceneContext)
+  let node = createGroup()
+  add(ctx.parent, node)
+  syncNode(node, props)
+  untrack(() => props.ref)?.(node)
+  onCleanup(() => remove(node))
+  return <SceneContext value={{ scene: ctx.scene, parent: node }}>{props.children}</SceneContext>
+}
+
+export type MeshProps = TransformProps & {
+  geometry: Geometry
+  material: Material
+  ref?: (mesh: MeshNode) => void
+}
+
+/** One draw entry: geometry drawn with a material at a transform. */
+export let Mesh: VoidComponent<MeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createMesh(props.geometry, props.material))
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  syncNode(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => remove(mesh))
+  return null
+}
+
+export type PerspectiveCameraProps = {
+  /** Vertical field of view in DEGREES (default 60). */
+  fov?: number
+  near?: number
+  far?: number
+  position?: Vec3
+  lookAt?: Vec3
+  up?: Vec3
+}
+
+/**
+ * Drives the scene's camera from props (the scene has a default camera, so
+ * this component is optional). The camera is scene state, not a tree node:
+ * to orbit it, update `position`/`lookAt`.
+ */
+export let PerspectiveCamera: VoidComponent<PerspectiveCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  createEffect(
+    () => [props.fov, props.near, props.far, props.position, props.lookAt, props.up] as const,
+    ([fov, near, far, position, lookAt, up]) =>
+      ctx.scene.setCamera({ fov, near, far, position, target: lookAt, up }),
+  )
+  return null
+}

package/src/geometry.ts

@@ -0,0 +1,227 @@
+// Geometry: interleaved vertex data in the one layout every scene material
+// shares - position vec3, normal vec3, uv vec2 (8 floats per vertex) - plus
+// uint16 indices. Winding is counter-clockwise seen from outside in the
+// y-up world, which the standard camera rig (perspective() with its baked
+// y flip) presents as the engine's displayed-CCW front faces: every
+// generator here culls correctly with cull: "back". Normals ride along
+// unused by the unlit materials so the layout is ready for lights without
+// a geometry change (inactive attributes are skipped but keep the stride).
+//
+// GPU buffers are created lazily on first use and shared by every mesh and
+// scene drawing the geometry. They are app-lifetime by design - one
+// geometry commonly outlives the component that first drew it, so
+// owner-scoped auto-free would free a buffer other scenes still draw from.
+// disposeGeometry frees them when an app is done with a geometry for good.
+
+import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
+import type { BufferId, VertexAttribute } from "@solidrt/core/gpu"
+import { add, cross, normalize, sub } from "./math.ts"
+import type { Vec3 } from "./math.ts"
+
+export const VERTEX_LAYOUT: VertexAttribute[] = [
+  { name: "aPos", format: "vec3" },
+  { name: "aNormal", format: "vec3" },
+  { name: "aUV", format: "vec2" },
+]
+export const FLOATS_PER_VERTEX = 8
+
+export type Geometry = {
+  /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex. */
+  vertices: Float32Array
+  indices: Uint16Array
+  /** Debug name for the lazily-created GPU buffers. */
+  label?: string
+  _buffer?: BufferId
+  _index?: BufferId
+}
+
+/** The geometry's GPU buffers, created on first use and cached on it. */
+export function geometryBuffers(geometry: Geometry): { buffer: BufferId; index: BufferId } {
+  let buffer = geometry._buffer
+  let index = geometry._index
+  if (buffer === undefined || index === undefined) {
+    buffer = createBuffer(geometry.vertices, {
+      autoFree: false,
+      label: geometry.label ? geometry.label + "-verts" : undefined,
+    })
+    index = createBuffer(geometry.indices, {
+      autoFree: false,
+      label: geometry.label ? geometry.label + "-indices" : undefined,
+    })
+    geometry._buffer = buffer
+    geometry._index = index
+  }
+  return { buffer, index }
+}
+
+/**
+ * Free the geometry's GPU buffers. Draw entries created from them hold
+ * their own reference, so destruction order is safe; the geometry can be
+ * used again afterwards (fresh buffers are created on next use).
+ */
+export function disposeGeometry(geometry: Geometry): void {
+  if (geometry._buffer !== undefined) destroyBuffer(geometry._buffer)
+  if (geometry._index !== undefined) destroyBuffer(geometry._index)
+  geometry._buffer = undefined
+  geometry._index = undefined
+}
+
+/** An axis-aligned box centered on the origin: 24 vertices, 36 indices. */
+export function box(width = 1, height = 1, depth = 1, label?: string): Geometry {
+  let x = width / 2
+  let y = height / 2
+  let z = depth / 2
+  let verts: number[] = []
+  let indices: number[] = []
+  type P = [number, number, number]
+  // Corners a (bottom-left) through d (top-left), CCW seen from outside.
+  let quad = (a: P, b: P, c: P, d: P, n: P) => {
+    let base = verts.length / FLOATS_PER_VERTEX
+    let uv = [[0, 1], [1, 1], [1, 0], [0, 0]]
+    let corners = [a, b, c, d]
+    for (let i = 0; i < 4; i++) {
+      let p = corners[i]!
+      let t = uv[i]!
+      verts.push(p[0], p[1], p[2], n[0], n[1], n[2], t[0]!, t[1]!)
+    }
+    indices.push(base, base + 1, base + 2, base, base + 2, base + 3)
+  }
+  quad([-x, -y, z], [x, -y, z], [x, y, z], [-x, y, z], [0, 0, 1]) // front
+  quad([x, -y, -z], [-x, -y, -z], [-x, y, -z], [x, y, -z], [0, 0, -1]) // back
+  quad([x, -y, z], [x, -y, -z], [x, y, -z], [x, y, z], [1, 0, 0]) // right
+  quad([-x, -y, -z], [-x, -y, z], [-x, y, z], [-x, y, -z], [-1, 0, 0]) // left
+  quad([-x, y, z], [x, y, z], [x, y, -z], [-x, y, -z], [0, 1, 0]) // top
+  quad([-x, -y, -z], [x, -y, -z], [x, -y, z], [-x, -y, z], [0, -1, 0]) // bottom
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
+
+/**
+ * A rectangle in the XY plane facing +z, centered on the origin. For a
+ * ground plane, rotate it flat: `rotation={[-Math.PI / 2, 0, 0]}`.
+ */
+export function plane(width = 1, height = 1, label?: string): Geometry {
+  let x = width / 2
+  let y = height / 2
+  // prettier-ignore
+  let vertices = new Float32Array([
+    -x, -y, 0, 0, 0, 1, 0, 1,
+    x, -y, 0, 0, 0, 1, 1, 1,
+    x, y, 0, 0, 0, 1, 1, 0,
+    -x, y, 0, 0, 0, 1, 0, 0,
+  ])
+  return { vertices, indices: new Uint16Array([0, 1, 2, 0, 2, 3]), label }
+}
+
+/**
+ * A (p,q) torus knot swept into a tube, centered on the origin and standing
+ * y-up: the knot's disc lies in the XZ plane with the weave running
+ * vertically - the orientation a y-up world with XZ floors wants (the
+ * standard-vocabulary divergence: Three's equivalent stands on z). The
+ * tube's (tubularSegments x radialSegments) grid stores each vertex once;
+ * the seam row/column duplicate the first with u/v = 1 (distinct texture
+ * coordinates, so genuinely distinct vertices). UVs: u 0..1 along the knot,
+ * v 0..1 around the tube.
+ */
+export function torusKnot(
+  radius = 1,
+  tube = 0.4,
+  tubularSegments = 64,
+  radialSegments = 8,
+  p = 2,
+  q = 3,
+  label?: string,
+): Geometry {
+  // A point on the knot curve at parameter t (0..2*PI*p).
+  let point = (t: number): Vec3 => {
+    let qp = (q / p) * t
+    let r = radius * (2 + Math.cos(qp)) * 0.5
+    return [r * Math.cos(t), radius * Math.sin(qp) * 0.5, r * Math.sin(t)]
+  }
+
+  let rows = tubularSegments + 1
+  let cols = radialSegments + 1
+  let vertices = new Float32Array(rows * cols * FLOATS_PER_VERTEX)
+  let at = 0
+
+  for (let i = 0; i < rows; i++) {
+    let t = (i / tubularSegments) * Math.PI * 2 * p
+    // A stable frame along the curve: tangent from a finite difference, and
+    // a normal biased away from the axis (P1 + P2), which is well-defined
+    // everywhere on a torus knot and needs no parallel transport.
+    let p1 = point(t)
+    let p2 = point(t + 0.01)
+    let tangent = sub(p2, p1)
+    let bitangent = normalize(cross(tangent, add(p2, p1)))
+    let normal = normalize(cross(bitangent, tangent))
+
+    for (let j = 0; j < cols; j++) {
+      let v = (j / radialSegments) * Math.PI * 2
+      let cv = -Math.cos(v) * tube
+      let sv = Math.sin(v) * tube
+      let x = p1[0] + cv * normal[0] + sv * bitangent[0]
+      let y = p1[1] + cv * normal[1] + sv * bitangent[1]
+      let z = p1[2] + cv * normal[2] + sv * bitangent[2]
+      let n = normalize([x - p1[0], y - p1[1], z - p1[2]])
+      vertices[at] = x
+      vertices[at + 1] = y
+      vertices[at + 2] = z
+      vertices[at + 3] = n[0]
+      vertices[at + 4] = n[1]
+      vertices[at + 5] = n[2]
+      vertices[at + 6] = i / tubularSegments
+      vertices[at + 7] = j / radialSegments
+      at += FLOATS_PER_VERTEX
+    }
+  }
+
+  let indices = new Uint16Array(tubularSegments * radialSegments * 6)
+  let n = 0
+  for (let i = 0; i < tubularSegments; i++) {
+    for (let j = 0; j < radialSegments; j++) {
+      let a = i * cols + j
+      let b = (i + 1) * cols + j
+      let c = (i + 1) * cols + j + 1
+      let d = i * cols + j + 1
+      indices[n++] = a
+      indices[n++] = b
+      indices[n++] = c
+      indices[n++] = a
+      indices[n++] = c
+      indices[n++] = d
+    }
+  }
+
+  return { vertices, indices, label }
+}
+
+/** A UV sphere centered on the origin (poles on the y axis). */
+export function sphere(radius = 0.5, widthSegments = 24, heightSegments = 16, label?: string): Geometry {
+  let verts: number[] = []
+  let indices: number[] = []
+  for (let iy = 0; iy <= heightSegments; iy++) {
+    let v = iy / heightSegments
+    let theta = v * Math.PI
+    let sinT = Math.sin(theta)
+    let cosT = Math.cos(theta)
+    for (let ix = 0; ix <= widthSegments; ix++) {
+      let u = ix / widthSegments
+      let phi = u * Math.PI * 2
+      let nx = -Math.cos(phi) * sinT
+      let ny = cosT
+      let nz = Math.sin(phi) * sinT
+      verts.push(radius * nx, radius * ny, radius * nz, nx, ny, nz, u, v)
+    }
+  }
+  let cols = widthSegments + 1
+  for (let iy = 0; iy < heightSegments; iy++) {
+    for (let ix = 0; ix < widthSegments; ix++) {
+      let a = iy * cols + ix + 1
+      let b = iy * cols + ix
+      let c = (iy + 1) * cols + ix
+      let d = (iy + 1) * cols + ix + 1
+      if (iy !== 0) indices.push(a, b, d)
+      if (iy !== heightSegments - 1) indices.push(b, c, d)
+    }
+  }
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// @solidrt/3d - a retained 3D scene graph above @solidrt/core/gpu.
+// Meshes, materials, and a camera compile to one depth-buffered draw
+// target; the output is an ordinary texture id in the UI tree. Two layers:
+// the imperative core (createScene/createMesh/setTransform - usable
+// without Solid components) and the component face (Scene/Mesh/Group/
+// PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
+
+export { add, createGroup, createMesh, createScene, remove, setGeometry, setMaterial, setMeshParams, setTransform, setVisible } from "./scene.ts"
+export type { CameraUpdate, Mesh as MeshNode, Scene as SceneHandle, SceneNode, SceneOptions, TransformUpdate } from "./scene.ts"
+export { box, disposeGeometry, plane, sphere, torusKnot, FLOATS_PER_VERTEX, VERTEX_LAYOUT } from "./geometry.ts"
+export type { Geometry } from "./geometry.ts"
+export { shaderMaterial, unlit } from "./material.ts"
+export type { Material, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
+export { Group, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
+export type { MeshProps, PerspectiveCameraProps, SceneProps, TransformProps } from "./components.tsx"
+export { createOrbitCamera } from "./orbit.ts"
+export type { OrbitCamera, OrbitCameraOptions, OrbitPose } from "./orbit.ts"
+export { compose, copy, identity, lookAt, mat4, multiply, perspective } from "./math.ts"
+export type { Mat4, Vec3 } from "./math.ts"