@solidrt/3d 0.0.58 → 0.0.60

package/examples/instanced.tsx

@@ -1,5 +1,5 @@
 // Instanced meshes: one draw entry covering a whole population. A material
-// class declares `instanceAttributes`, createRecordMesh (here via the
+// class declares `instanceBuffers`, createRecordMesh (here via the
 // <RecordMesh> component) supplies one interleaved record per instance,
 // and the vertex stage reads each record through the matching `in`
 // variables. Two meshes share the one class: 400 scattered "rocks" and a
@@ -9,9 +9,12 @@
 //
 // setRecordCount is the population dial (the pines breathe); records are
 // data, not matrices - position/scale/tint here, whatever your shader
-// wants in general. The explicit `bounds` cover the scatter so picking
-// still works (one conservative box around the population; omit bounds and
-// the mesh simply never picks).
+// wants in general. The record layout is any vertex layout: the tint is
+// a unorm8x4, four bytes where four floats would be sixteen, written as
+// 0..1 values through the same attribute accessor a geometry channel
+// uses. The explicit `bounds` cover the scatter so picking still works
+// (one conservative box around the population; omit bounds and the mesh
+// simply never picks).
 //
 // The fleets CAST: the class declares `shadowVertex` - its vertex stage
 // reduced to the position math, instance placement included - and with it
@@ -22,29 +25,33 @@
 //
 // The fleets are also lit, shadowed and fogged exactly like the ground,
 // with no lighting code of their own: the class pairs its instanced
-// vertex stage with the stock `litFragment` (the fragment `lit` compiles),
+// vertex stage with the stock `phongFragment` (the fragment `phong` compiles),
 // which is the first tier of custom looks - a vertex stage that writes
 // the lit varyings gets the whole scene for free. The per-instance tint
 // rides the `vertexColors` path as vColor.
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
 import { glsl } from "@solidrt/core/gpu"
 import {
+  attributeAccess,
   box,
   cone,
   DirectionalLight,
   Group,
   HemisphereLight,
+  layoutStride,
   RecordMesh,
-  lit,
+  phong,
   Mesh,
   PerspectiveCamera,
   plane,
   Scene,
   setRecordCount,
   shaderMaterialClass,
+  vertexView,
 } from "@solidrt/3d"
 import type { RecordMeshNode } from "@solidrt/3d"
-import { litFragment } from "@solidrt/3d/glsl"
+import type { VertexAttribute } from "@solidrt/core/gpu"
+import { phongFragment } from "@solidrt/3d/glsl"
 
 // The lit varyings (vWorldPos, vNormal, vUv, and vColor for the tint), as
 // LIT_VERTEX writes them, from an instanced placement.
@@ -54,7 +61,7 @@ const INSTANCE_VERTEX = glsl`
   in vec2 aUV;
   in vec3 iPos;
   in float iScale;
-  in vec3 iTint;
+  in vec4 iTint;
   out vec3 vWorldPos;
   out vec3 vNormal;
   out vec2 vUv;
@@ -69,7 +76,7 @@ const INSTANCE_VERTEX = glsl`
     vWorldPos = world.xyz;
     vNormal = mat3(uNormal) * aNormal;
     vUv = aUV;
-    vColor = vec4(iTint, 1.0);
+    vColor = iTint;
   }
 `
 
@@ -87,44 +94,61 @@ const INSTANCE_SHADOW_VERTEX = glsl`
   }
 `
 
-// One record per instance, interleaved in attribute order: 7 floats.
-const STRIDE = 7
+// One record per instance, tightly packed in attribute order: 20 bytes.
+const RECORD: VertexAttribute[] = [
+  { name: "iPos", format: "float32x3" },
+  { name: "iScale", format: "float32" },
+  { name: "iTint", format: "unorm8x4" },
+]
 
-// A deterministic scatter (no per-run surprises when eyeballing).
-function rocks(count: number): Float32Array {
-  let records = new Float32Array(count * STRIDE)
-  let a = 0
+// `count` records of RECORD, filled through the attribute accessors:
+// `place` gives a record's position and scale, `tint` its color, and the
+// codecs pack the bytes (the tint's 0..1 floats become unorm bytes).
+function records(count: number, place: (i: number) => [number, number, number, number], tint: (i: number) => [number, number, number]): ArrayBufferView {
+  let out = vertexView(RECORD, new ArrayBuffer(count * layoutStride(RECORD)))
+  let pos = attributeAccess(out, RECORD, "iPos")!
+  let scale = attributeAccess(out, RECORD, "iScale")!
+  let color = attributeAccess(out, RECORD, "iTint")!
   for (let i = 0; i < count; i++) {
-    a += 2.399963 // golden angle: an even spiral scatter
-    let r = 0.35 + 3.4 * Math.sqrt((i + 0.5) / count)
-    let s = 0.05 + 0.11 * ((i * 7) % 10) / 10
-    let o = i * STRIDE
-    records[o] = Math.cos(a) * r
-    records[o + 1] = s / 2
-    records[o + 2] = Math.sin(a) * r
-    records[o + 3] = s
-    records[o + 4] = 0.55 + 0.3 * ((i * 3) % 5) / 5
-    records[o + 5] = 0.5 + 0.2 * ((i * 11) % 7) / 7
-    records[o + 6] = 0.45
+    let [x, y, z, s] = place(i)
+    pos.set(i, 0, x)
+    pos.set(i, 1, y)
+    pos.set(i, 2, z)
+    scale.set(i, 0, s)
+    let [r, g, b] = tint(i)
+    color.set(i, 0, r)
+    color.set(i, 1, g)
+    color.set(i, 2, b)
+    color.set(i, 3, 1)
   }
-  return records
+  return out
 }
 
-function pines(count: number): Float32Array {
-  let records = new Float32Array(count * STRIDE)
-  for (let i = 0; i < count; i++) {
-    let a = (i / count) * Math.PI * 2
-    let s = 0.5 + 0.25 * ((i * 5) % 8) / 8
-    let o = i * STRIDE
-    records[o] = Math.cos(a) * 2.4
-    records[o + 1] = s / 2
-    records[o + 2] = Math.sin(a) * 2.4
-    records[o + 3] = s
-    records[o + 4] = 0.15
-    records[o + 5] = 0.4 + 0.25 * ((i * 3) % 6) / 6
-    records[o + 6] = 0.2
-  }
-  return records
+// A deterministic scatter (no per-run surprises when eyeballing).
+function rocks(count: number): ArrayBufferView {
+  let a = 0
+  return records(
+    count,
+    i => {
+      a += 2.399963 // golden angle: an even spiral scatter
+      let r = 0.35 + 3.4 * Math.sqrt((i + 0.5) / count)
+      let s = 0.05 + 0.11 * ((i * 7) % 10) / 10
+      return [Math.cos(a) * r, s / 2, Math.sin(a) * r, s]
+    },
+    i => [0.55 + 0.3 * ((i * 3) % 5) / 5, 0.5 + 0.2 * ((i * 11) % 7) / 7, 0.45],
+  )
+}
+
+function pines(count: number): ArrayBufferView {
+  return records(
+    count,
+    i => {
+      let a = (i / count) * Math.PI * 2
+      let s = 0.5 + 0.25 * ((i * 5) % 8) / 8
+      return [Math.cos(a) * 2.4, s / 2, Math.sin(a) * 2.4, s]
+    },
+    i => [0.15, 0.4 + 0.25 * ((i * 3) % 6) / 6, 0.2],
+  )
 }
 
 const PINE_COUNT = 48
@@ -154,7 +178,7 @@ function App() {
             castShadow
             shadow={{ normalBias: 0.02, camera: { near: 1, far: 20 } }}
           />
-          <Mesh geometry={plane({ width: 9, height: 9, label: "meadow" })} material={lit({ color: [0.24, 0.27, 0.24] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Mesh geometry={plane({ width: 9, height: 9, label: "meadow" })} material={phong({ color: [0.24, 0.27, 0.24] })} rotation={[-Math.PI / 2, 0, 0]} />
           <Group rotation={[0, spin(), 0]}>
             <RecordMesh
               geometry={box({ label: "rock" })}
@@ -180,18 +204,14 @@ function App() {
 
 // One class, one compiled pipeline; each mesh gets its own instance() so
 // per-mesh uniforms stay independent. The fragment is the stock lit one,
-// so the instance carries lit's per-entry uniforms: a white base (the
+// so the instance carries phong's per-entry uniforms: a white base (the
 // tint arrives per instance through vColor) and a modest highlight.
 const LOOK = { uColor: [1, 1, 1, 1], uSpecular: 0.25, uShininess: 30 }
 let instancedLook = shaderMaterialClass({
   vertex: INSTANCE_VERTEX,
   shadowVertex: INSTANCE_SHADOW_VERTEX,
-  fragment: litFragment({ vertexColors: true }),
-  instanceAttributes: [
-    { name: "iPos", format: "vec3" },
-    { name: "iScale", format: "f32" },
-    { name: "iTint", format: "vec3" },
-  ],
+  fragment: phongFragment({ vertexColors: true }),
+  instanceBuffers: [{ attributes: RECORD }],
   label: "instanced-look",
 })
 

package/examples/lamps.tsx

@@ -22,7 +22,7 @@
 // intensity ~40 for a bright pool, not ~2. `distance` then windows the
 // falloff to zero so the pool ends instead of trailing off forever.
 import { onFrame, pct, render } from "@solidrt/core"
-import { box, cylinder, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, PointLight, Scene, setTransform, SpotLight, torusKnot } from "@solidrt/3d"
+import { box, cylinder, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, PointLight, Scene, setTransform, SpotLight, torusKnot } from "@solidrt/3d"
 import type { SceneNode } from "@solidrt/3d"
 
 function App() {
@@ -35,9 +35,9 @@ function App() {
     setTransform(orbit, { rotation: [0, tick / 1500, 0] })
   })
 
-  let ground = lit({ color: [0.6, 0.6, 0.62] })
-  let crate = lit({ color: [0.7, 0.55, 0.4] })
-  let gold = lit({ color: [0.9, 0.75, 0.3], specular: 0.6, shininess: 50 })
+  let ground = phong({ color: [0.6, 0.6, 0.62] })
+  let crate = phong({ color: [0.7, 0.55, 0.4] })
+  let gold = phong({ color: [0.9, 0.75, 0.3], specular: 0.6, shininess: 50 })
 
   return (
     <window>

package/examples/lod.tsx

@@ -0,0 +1,125 @@
+// Level of detail: a thousand trees as ONE instanced LOD - three draw
+// entries whatever the spread, each instance drawing the level its own
+// projected size picks - and one hero solid as a `<Lod>` group of three
+// meshes cross-fading between levels. The choice is the spatial core's,
+// per target, after each flush: the camera flies over the field and no
+// per-frame JS touches a single tree.
+//
+// The levels are tinted on purpose (green, olive, blue) so the hand-overs
+// show; a real forest would share one material. Sizes are projected
+// heights as a fraction of the viewport, measured on the sphere around
+// the object's box (half its diagonal, ~2.8 for a tree): under this 60
+// degree camera a tree measures 1.73 * 2.8 / distance, so the thresholds
+// below hand over at roughly 55 and 160 world units. The hero's `fade`
+// widens each of its thresholds into a band where both levels draw with
+// complementary dithers; the forest switches hard, with the core's
+// hysteresis, since instanced levels never fade.
+//
+// Debug: `fly { t }` parks the camera at flight time t (seconds) so a
+// snapshot is deterministic; `state` reports the camera and the tree
+// count.
+import { onFrame, pct, render } from "@solidrt/core"
+import { addInstance, cone, cylinder, DirectionalLight, HemisphereLight, icosahedron, InstancedLod, phong, Lod, Mesh, mergeGeometries, plane, Scene, transformGeometry, useScene } from "@solidrt/3d"
+import type { InstancedMeshNode } from "@solidrt/3d"
+import { registerDebug } from "srt:dev"
+
+const TREES = 1000
+// Half the side of the square field the trees scatter over.
+const FIELD = 110
+// The hand-over sizes of the forest, nearest first (the last is the cull
+// threshold: 0 keeps the far level drawn at any distance).
+const FOREST_SIZES = [0.09, 0.03, 0]
+// The hero's hand-over sizes and its cross-fade band fraction.
+const HERO_SIZES = [0.45, 0.18, 0]
+const HERO_FADE = 0.35
+
+// A tree at three costs: foliage cone over a trunk, 24 / 7 / 3 segments.
+function tree(segments: number): ReturnType<typeof mergeGeometries> {
+  let foliage = transformGeometry(cone({ radius: 1.4, height: 3.2, radialSegments: segments }), { position: [0, 2.4, 0] })
+  let trunk = transformGeometry(cylinder({ radiusTop: 0.22, radiusBottom: 0.3, height: 1.6, radialSegments: Math.max(3, segments >> 1) }), { position: [0, 0.8, 0] })
+  return mergeGeometries([foliage, trunk], "tree-" + segments)
+}
+
+// A deterministic scatter (a small LCG), so every run is the same field.
+function scatter(mesh: InstancedMeshNode): void {
+  let seed = 12345
+  let rand = () => {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff
+    return seed / 0x7fffffff
+  }
+  for (let i = 0; i < TREES; i++) {
+    let x = (rand() * 2 - 1) * FIELD
+    let z = (rand() * 2 - 1) * FIELD
+    // Keep the hero's clearing empty.
+    if (x * x + z * z < 12 * 12) continue
+    let s = 0.7 + rand() * 0.6
+    addInstance(mesh, { position: [x, 0, z], rotation: [0, rand() * Math.PI * 2, 0], scale: [s, s, s] })
+  }
+}
+
+let parked: number | null = null
+let flightTime = 0
+let eye: [number, number, number] = [0, 0, 0]
+
+// The flight: a slow orbit whose radius breathes between the clearing and
+// the field's edge, height following the radius, always looking a little
+// ahead of the hero.
+function flyTo(setCamera: (u: { position: [number, number, number]; target: [number, number, number] }) => void, t: number): void {
+  let radius = 14 + 80 * (0.5 - 0.5 * Math.cos(t * 0.22))
+  let theta = t * 0.18
+  eye = [radius * Math.cos(theta), 5 + radius * 0.22, radius * Math.sin(theta)]
+  setCamera({ position: eye, target: [-8 * Math.sin(theta), 2, 8 * Math.cos(theta)] })
+}
+
+function Flight() {
+  let { viewport } = useScene()
+  flyTo(viewport.setCamera, 0)
+  onFrame(tick => {
+    flightTime = parked ?? tick / 1000
+    flyTo(viewport.setCamera, flightTime)
+  })
+  return null
+}
+
+registerDebug("fly", (args?: Record<string, unknown>) => {
+  parked = typeof args?.t === "number" ? args.t : null
+  return { parked }
+})
+registerDebug("state", () => ({ t: flightTime, eye, trees: TREES }))
+
+function App() {
+  let hi = tree(24)
+  let mid = tree(7)
+  let lo = tree(3)
+  let leafHi = phong({ color: [0.2, 0.55, 0.2], instanced: true })
+  let leafMid = phong({ color: [0.5, 0.55, 0.15], instanced: true })
+  let leafLo = phong({ color: [0.2, 0.35, 0.6], instanced: true })
+  let ground = plane({ width: FIELD * 2.4, height: FIELD * 2.4 })
+  return (
+    <window>
+      <Scene camera={{ fov: 60, near: 0.5, far: 400 }} clearColor={[0.62, 0.74, 0.9, 1]} fog={{ color: [0.62, 0.74, 0.9], near: 120, far: 320 }} label="lod">
+        <Flight />
+        <HemisphereLight sky={[0.7, 0.8, 1]} ground={[0.3, 0.28, 0.22]} intensity={0.9} />
+        <DirectionalLight direction={[-0.5, -1, -0.3]} intensity={1.1} />
+        <Mesh geometry={ground} material={phong({ color: [0.36, 0.42, 0.24] })} rotation={[-Math.PI / 2, 0, 0]} />
+        <InstancedLod
+          capacity={TREES}
+          levels={[
+            { geometry: hi, material: leafHi, size: FOREST_SIZES[0]! },
+            { geometry: mid, material: leafMid, size: FOREST_SIZES[1]! },
+            { geometry: lo, material: leafLo, size: FOREST_SIZES[2]! },
+          ]}
+          label="forest"
+          ref={scatter}
+        />
+        <Lod fade={HERO_FADE} position={[0, 3.5, 0]}>
+          <Mesh lodSize={HERO_SIZES[0]!} geometry={icosahedron({ radius: 3, detail: 3 })} material={phong({ color: [0.9, 0.35, 0.25], specular: 0.6 })} />
+          <Mesh lodSize={HERO_SIZES[1]!} geometry={icosahedron({ radius: 3, detail: 1 })} material={phong({ color: [0.9, 0.6, 0.2], specular: 0.6 })} />
+          <Mesh lodSize={HERO_SIZES[2]!} geometry={icosahedron({ radius: 3, detail: 0 })} material={phong({ color: [0.85, 0.8, 0.3] })} />
+        </Lod>
+      </Scene>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/materials.tsx

@@ -1,4 +1,4 @@
-// The surface maps on lit(), all procedural so the example is
+// The surface maps on phong(), all procedural so the example is
 // self-contained. normalMap bends the lighting per texel with NO tangent
 // channel (the frame comes from screen-space derivatives) - the flat
 // plane and the sphere both show relief from one bump texture.
@@ -12,7 +12,7 @@
 
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
 import { createTexture } from "@solidrt/core/gpu"
-import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, setMeshParams, sphere, withAttribute } from "@solidrt/3d"
+import { box, DirectionalLight, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, setMeshParams, sphere, withAttribute } from "@solidrt/3d"
 import type { MeshNode } from "@solidrt/3d"
 
 // A tangent-space normal map from a procedural height field (a grid of
@@ -108,18 +108,18 @@ function App() {
   })
 
   let bumps = bumpNormalMap()
-  let bumpy = lit({ color: [0.75, 0.5, 0.3], normalMap: bumps, specular: 0.5, shininess: 40 })
-  let flat = lit({ color: [0.75, 0.5, 0.3], specular: 0.5, shininess: 40 })
-  let city = lit({ color: [0.25, 0.28, 0.34], emissiveMap: windowMap() })
-  let striped = lit({ color: [0.2, 0.22, 0.26], specularMap: stripeMap(), shininess: 90 })
-  let belt = lit({ map: chevronMap(), mapTransform: { repeat: [3, 1] } })
+  let bumpy = phong({ color: [0.75, 0.5, 0.3], normalMap: bumps, specular: 0.5, shininess: 40 })
+  let flat = phong({ color: [0.75, 0.5, 0.3], specular: 0.5, shininess: 40 })
+  let city = phong({ color: [0.25, 0.28, 0.34], emissiveMap: windowMap() })
+  let striped = phong({ color: [0.2, 0.22, 0.26], specularMap: stripeMap(), shininess: 90 })
+  let belt = phong({ map: chevronMap(), mapTransform: { repeat: [3, 1] } })
   // The ground carries its own uv2 island (here just the 0..1 plane UVs
   // recomputed from position) and adds the "baked" glow with no light.
-  let groundGeometry = withAttribute(plane({ width: 8, height: 8 }), { name: "aUV2", format: "vec2" }, (_i, pos) => [
+  let groundGeometry = withAttribute(plane({ width: 8, height: 8 }), { name: "aUV2", format: "float32x2" }, (_i, pos) => [
     pos[0] / 8 + 0.5,
     pos[1] / 8 + 0.5,
   ])
-  let ground = lit({ color: [0.45, 0.45, 0.5], lightMap: bakedGlowMap(), lightMapIntensity: 1.5 })
+  let ground = phong({ color: [0.45, 0.45, 0.5], lightMap: bakedGlowMap(), lightMapIntensity: 1.5 })
 
   return (
     <window>

package/examples/morph.tsx

@@ -0,0 +1,174 @@
+// Morph targets (blend shapes): a geometry carries named per-vertex
+// deltas (`withMorphTargets`; a glTF's targets arrive the same way
+// through the loader) and a `morph: true` material displaces its
+// vertices by the weights the mesh owns - `setMorphWeights(mesh, {
+// bulge: 0.7 })` by name, or every weight in target order, or the
+// `morphWeights` prop. The weights live in the spatial core (one write
+// lands at the next flush, a clip's weights track writes the same
+// register), the deltas in one texture per geometry packed sparse by
+// vertex, so a target that moves the top of the blob costs nothing at
+// the bottom. The middle blob morphs, its shadow morphs with it (the
+// depth pass walks the same targets); the left one draws the same
+// geometry under a plain lit material - the base shape, targets
+// ignored; the right one flips between two weight sets through the
+// `morphWeights` prop, and its `transition` declares a `weights` lane,
+// so each flip springs there natively - a write is a target, like a
+// transform write under a transition. The back row is ONE instanced
+// mesh: every `<Instance>` owns its own weights (a row of the
+// population's weights texture, read by the instance index in the
+// shader), so six copies at six blends are one draw entry - and their
+// shadows morph too.
+
+import { createSignal, onCleanup, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { DirectionalLight, geometryAttribute, geometryVertexCount, getMorphNames, getMorphWeights, HemisphereLight, Instance, InstancedMesh, phong, Mesh, PerspectiveCamera, plane, Scene, setMorphWeights, sphere, withMorphTargets } from "@solidrt/3d"
+import type { InstanceNode, MeshNode } from "@solidrt/3d"
+
+// The blob's authored shape: a sphere with two targets - "bulge", a
+// spike growing out of the top half only (the sparse case), and
+// "squash", the whole sphere flattened to half its height. Each target
+// carries NORMAL deltas too, the way a modeller exports them: the
+// normals of the displaced shape (smooth normals recomputed from its
+// faces) minus the base normals. Without them the lighting and the
+// shadow bias would read the base surface on a moved one. Normals
+// blend LINEARLY between targets (every engine's morph rule), which is
+// exact at the targets and an approximation between them: keep deltas
+// modest, as a modeller's blend shapes are, or a half-blended extreme
+// target shows a ragged terminator against its own shadow.
+const RADIUS = 0.6
+const BULGE_REACH = 0.45
+const SQUASH_TO = 0.6
+// The right blob's two poses and how often it flips between them; its
+// spring takes about a second to settle, with a little bounce.
+const POSE_A = { squash: 0.8, bulge: 0.1 }
+const POSE_B = { squash: 0.1, bulge: 0.8 }
+const FLIP_MS = 1800
+const FLIP_SPRING = { duration: 900, bounce: 0.25 }
+// The back row: six instances of one mesh, each at its own blend - the
+// bulge rising left to right, the squash falling.
+const ROW_COUNT = 6
+const ROW_SPACING = 1.1
+const ROW_Z = -2.2
+const ROW_SCALE = 0.7
+
+// Smooth vertex normals of `positions` over the geometry's triangles.
+function smoothNormals(indices: ArrayLike<number>, positions: Float32Array): Float32Array {
+  let normals = new Float32Array(positions.length)
+  for (let t = 0; t + 2 < indices.length; t += 3) {
+    let a = indices[t]! * 3, b = indices[t + 1]! * 3, c = indices[t + 2]! * 3
+    let abx = positions[b]! - positions[a]!, aby = positions[b + 1]! - positions[a + 1]!, abz = positions[b + 2]! - positions[a + 2]!
+    let acx = positions[c]! - positions[a]!, acy = positions[c + 1]! - positions[a + 1]!, acz = positions[c + 2]! - positions[a + 2]!
+    let nx = aby * acz - abz * acy, ny = abz * acx - abx * acz, nz = abx * acy - aby * acx
+    for (let v of [a, b, c]) {
+      normals[v] = normals[v]! + nx
+      normals[v + 1] = normals[v + 1]! + ny
+      normals[v + 2] = normals[v + 2]! + nz
+    }
+  }
+  for (let v = 0; v < normals.length; v += 3) {
+    let len = Math.hypot(normals[v]!, normals[v + 1]!, normals[v + 2]!) || 1
+    normals[v] = normals[v]! / len
+    normals[v + 1] = normals[v + 1]! / len
+    normals[v + 2] = normals[v + 2]! / len
+  }
+  return normals
+}
+
+function blob() {
+  let base = sphere({ radius: RADIUS, label: "blob" })
+  let count = geometryVertexCount(base, "blob")
+  let pos = geometryAttribute(base, "aPos")!
+  let nrm = geometryAttribute(base, "aNormal")!
+  let basePos = new Float32Array(count * 3)
+  let baseNormal = new Float32Array(count * 3)
+  let bulge = new Float32Array(count * 3)
+  let squash = new Float32Array(count * 3)
+  for (let i = 0; i < count; i++) {
+    let y = pos.get(i, 1)
+    for (let k = 0; k < 3; k++) {
+      basePos[i * 3 + k] = pos.get(i, k)
+      baseNormal[i * 3 + k] = nrm.get(i, k)
+    }
+    let up = Math.max(0, y / RADIUS)
+    let reach = BULGE_REACH * up * up
+    for (let k = 0; k < 3; k++) bulge[i * 3 + k] = nrm.get(i, k) * reach
+    squash[i * 3 + 1] = -(1 - SQUASH_TO) * y
+  }
+  // A target's normal deltas: the displaced shape's smooth normals minus
+  // the base's (the sphere's seam vertices are duplicated, so their
+  // recomputed normals differ a little across the seam - fine here).
+  let normalDeltas = (deltas: Float32Array): Float32Array => {
+    let moved = basePos.map((v, i) => v + deltas[i]!)
+    let normals = smoothNormals(base.indices, moved)
+    return normals.map((n, i) => n - baseNormal[i]!)
+  }
+  return withMorphTargets(base, [
+    { name: "bulge", position: bulge, normal: normalDeltas(bulge) },
+    { name: "squash", position: squash, normal: normalDeltas(squash) },
+  ])
+}
+
+function App() {
+  let geometry = blob()
+  let morphing = phong({ color: [0.9, 0.55, 0.3], morph: true, specular: 0.4, shininess: 40 })
+  let plain = phong({ color: [0.35, 0.6, 0.85] })
+  let ground = phong({ color: [0.75, 0.75, 0.72] })
+  let live: MeshNode | undefined
+  let right: MeshNode | undefined
+  let row: InstanceNode[] = []
+  let instanced = phong({ color: [0.45, 0.7, 0.5], morph: true, instanced: true, specular: 0.4, shininess: 40 })
+  let rowWeights = (i: number) => ({ bulge: i / (ROW_COUNT - 1), squash: 1 - i / (ROW_COUNT - 1) })
+  // The per-frame driver, until a debug command pins the weights:
+  // `POST /__control__/debug?name=morph` with `{ "bulge": 1, "squash": 0 }`
+  // (or the MCP call_debug tool) holds the middle blob at a weight set
+  // and reads the weights back (from the core: mid-flight under a
+  // transition); with `"duration": 500` the pin animates there on a
+  // one-off spring; `{ "drive": true }` resumes the driver; `{}` only
+  // reads.
+  let driving = true
+  onFrame(tick => {
+    let t = tick / 1000
+    if (live && driving) setMorphWeights(live, { bulge: (Math.sin(t * 1.7) + 1) / 2, squash: (Math.sin(t * 0.9 + 1) + 1) / 2 })
+  })
+  registerDebug("morph", (args?: { bulge?: number; squash?: number; duration?: number; drive?: boolean }) => {
+    if (!live) return null
+    if (args?.drive === true) driving = true
+    else {
+      let weights: Record<string, number> = {}
+      if (typeof args?.bulge === "number") weights.bulge = args.bulge
+      if (typeof args?.squash === "number") weights.squash = args.squash
+      if (Object.keys(weights).length > 0) {
+        driving = false
+        setMorphWeights(live, weights, typeof args?.duration === "number" ? { duration: args.duration } : undefined)
+      }
+    }
+    return { names: getMorphNames(live), weights: Array.from(getMorphWeights(live)), right: right ? Array.from(getMorphWeights(right)) : null, row: row.map(n => Array.from(getMorphWeights(n))) }
+  })
+  // The right blob's pose flips on a timer; the spring is the node's.
+  let [pose, setPose] = createSignal(POSE_A)
+  let flip = setInterval(() => setPose(p => (p === POSE_A ? POSE_B : POSE_A)), FLIP_MS)
+  onCleanup(() => clearInterval(flip))
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.08, 0.08, 0.11, 1]} samples={4} label="morph">
+          <PerspectiveCamera fov={45} position={[0, 2.4, 5.5]} lookAt={[0, 0.5, 0]} />
+          <HemisphereLight sky={[0.35, 0.38, 0.45]} ground={[0.12, 0.1, 0.08]} />
+          <DirectionalLight position={[-2, 5, -3]} direction={[2, -5, 3]} color={[1, 0.95, 0.85]} intensity={1} castShadow shadow={{ normalBias: 0.02, camera: { near: 1, far: 20 } }} />
+          <Mesh geometry={plane({ width: 8, height: 8 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          <Mesh geometry={geometry} material={plain} position={[-1.8, RADIUS, 0]} castShadow />
+          <Mesh geometry={geometry} material={morphing} position={[0, RADIUS, 0]} castShadow ref={m => (live = m)} />
+          <Mesh geometry={geometry} material={morphing} position={[1.8, RADIUS, 0]} castShadow morphWeights={pose()} transition={{ weights: FLIP_SPRING }} ref={m => (right = m)} />
+          <InstancedMesh geometry={geometry} material={instanced} capacity={ROW_COUNT} castShadow label="morph-row">
+            {Array.from({ length: ROW_COUNT }, (_, i) => (
+              <Instance position={[(i - (ROW_COUNT - 1) / 2) * ROW_SPACING, RADIUS * ROW_SCALE, ROW_Z]} scale={ROW_SCALE} morphWeights={rowWeights(i)} ref={n => (row[i] = n)} />
+            ))}
+          </InstancedMesh>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)