@solidrt/3d 0.0.46 → 0.0.47

package/src/geometry.ts

@@ -1,6 +1,11 @@
-// 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
+// Geometry: interleaved vertex data in one of two named layouts - the
+// "standard" position vec3, normal vec3, uv vec2 (8 floats per vertex)
+// every generator emits, and "colored", which appends an aColor vec4
+// (12 floats, derived with withColors) as the per-vertex data channel for
+// custom materials (tint, baked AO, any four scalars) - plus
+// indices, uint16 or uint32 (the generators here emit uint16; hand-built
+// geometry past 64k vertices uses a Uint32Array and the draw entry follows
+// the array type). 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
@@ -14,29 +19,53 @@
 // 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 type { BufferId, IndexFormat, VertexAttribute } from "@solidrt/core/gpu"
 import { add, cross, normalize, sub } from "./math.ts"
-import type { Vec3 } from "./math.ts"
+import type { Vec2, Vec3, Vec4 } from "./math.ts"
 
-export const VERTEX_LAYOUT: VertexAttribute[] = [
+export type VertexLayout = "standard" | "colored"
+
+const STANDARD_ATTRIBUTES: VertexAttribute[] = [
   { name: "aPos", format: "vec3" },
   { name: "aNormal", format: "vec3" },
   { name: "aUV", format: "vec2" },
 ]
+
+/** The pipeline attribute list for each named layout. A deliberately small
+ * set (not an open per-geometry model): every layout shares the standard
+ * prefix, so one shader vocabulary serves all of them. */
+export const VERTEX_LAYOUTS: Record<VertexLayout, VertexAttribute[]> = {
+  standard: STANDARD_ATTRIBUTES,
+  colored: [...STANDARD_ATTRIBUTES, { name: "aColor", format: "vec4" }],
+}
+
+/** Floats per vertex in the "standard" layout (what every generator emits). */
 export const FLOATS_PER_VERTEX = 8
+const COLORED_FLOATS = 12
 
 export type Geometry = {
-  /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex. */
+  /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex, plus color.rgba
+   * in the "colored" layout. */
   vertices: Float32Array
-  indices: Uint16Array
+  /** The array type picks the draw's index format: Uint32Array past 64k
+   * vertices. */
+  indices: Uint16Array | Uint32Array
+  /** Vertex layout; absent means "standard". Must match the material's
+   * layout - the scene rejects a mismatched pair at add(). */
+  layout?: VertexLayout
   /** 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 } {
+/** The geometry's GPU buffers, created on first use and cached on it,
+ * plus the index format the draw entry must bind them with. */
+export function geometryBuffers(geometry: Geometry): {
+  buffer: BufferId
+  index: BufferId
+  indexFormat: IndexFormat
+} {
   let buffer = geometry._buffer
   let index = geometry._index
   if (buffer === undefined || index === undefined) {
@@ -51,7 +80,7 @@ export function geometryBuffers(geometry: Geometry): { buffer: BufferId; index:
     geometry._buffer = buffer
     geometry._index = index
   }
-  return { buffer, index }
+  return { buffer, index, indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16" }
 }
 
 /**
@@ -66,6 +95,106 @@ export function disposeGeometry(geometry: Geometry): void {
   geometry._index = undefined
 }
 
+/** Per-vertex aColor values for withColors/fillColors: a flat 4-per-vertex
+ * array, or a callback deriving each vertex's vec4 from the vertex data. */
+export type ColorFill = ArrayLike<number> | ((index: number, pos: Vec3, normal: Vec3, uv: Vec2) => Vec4)
+
+/**
+ * Derive a "colored"-layout geometry from a standard one: the same
+ * positions, normals, uvs and indices, plus an aColor vec4 per vertex -
+ * the data channel for materials whose vertex stage reads `in vec4 aColor`
+ * (a tint, baked ambient occlusion, any four scalars; the name is the
+ * standard vocabulary, the contents are yours). The callback form receives
+ * each vertex's position, normal and uv - what a baker wants. The source
+ * geometry is untouched and its GPU buffers stay independent.
+ */
+export function withColors(geometry: Geometry, fill: ColorFill, label?: string): Geometry {
+  if (geometry.layout === "colored") {
+    throw new Error("withColors: geometry already carries an aColor channel")
+  }
+  if (geometry.vertices.length % FLOATS_PER_VERTEX !== 0) {
+    throw new Error("withColors: vertex data is not a whole number of standard-layout vertices")
+  }
+  let count = geometry.vertices.length / FLOATS_PER_VERTEX
+  if (typeof fill !== "function" && fill.length !== count * 4) {
+    throw new Error("withColors: fill has " + fill.length + " floats, expected 4 per vertex (" + count * 4 + ")")
+  }
+  let src = geometry.vertices
+  let out = new Float32Array(count * COLORED_FLOATS)
+  for (let i = 0; i < count; i++) {
+    let s = i * FLOATS_PER_VERTEX
+    let d = i * COLORED_FLOATS
+    for (let k = 0; k < FLOATS_PER_VERTEX; k++) out[d + k] = src[s + k]!
+  }
+  fillColors(out, fill)
+  return {
+    vertices: out,
+    indices: geometry.indices,
+    layout: "colored",
+    label: label ?? (geometry.label ? geometry.label + "-colored" : undefined),
+  }
+}
+
+/**
+ * The in-place primitive under withColors: write the aColor slots of a
+ * colored-layout interleave you already own - the hook for a merging
+ * builder baking colors over its packed buffer (the pos/normal/uv the
+ * callback receives are read from the buffer itself, so a packer that
+ * bakes transforms while writing hands the baker world-space vertices).
+ * Fills vertices [first, first + count) - count defaults to the rest of
+ * the buffer - and `fill` indexes relative to `first`, so a per-part
+ * callback works unchanged for both APIs. Returns `vertices`.
+ *
+ * This trusts the buffer to BE colored-layout data - a bare array carries
+ * no layout tag, so only the arithmetic is checked. The Geometry-level
+ * withColors stays the checked path.
+ */
+export function fillColors(vertices: Float32Array, fill: ColorFill, first = 0, count?: number): Float32Array {
+  if (vertices.length % COLORED_FLOATS !== 0) {
+    throw new Error("fillColors: vertex data is not a whole number of colored-layout vertices")
+  }
+  let total = vertices.length / COLORED_FLOATS
+  let n = count ?? total - first
+  if (!Number.isInteger(first) || !Number.isInteger(n) || first < 0 || n < 0 || first + n > total) {
+    throw new Error("fillColors: range [" + first + ", " + (first + n) + ") is outside the buffer's " + total + " vertices")
+  }
+  let fn = typeof fill === "function" ? fill : null
+  if (!fn && fill.length !== n * 4) {
+    throw new Error("fillColors: fill has " + fill.length + " floats, expected 4 per vertex (" + n * 4 + ")")
+  }
+  for (let i = 0; i < n; i++) {
+    let d = (first + i) * COLORED_FLOATS
+    let c: Vec4 = fn
+      ? fn(i, [vertices[d]!, vertices[d + 1]!, vertices[d + 2]!], [vertices[d + 3]!, vertices[d + 4]!, vertices[d + 5]!], [vertices[d + 6]!, vertices[d + 7]!])
+      : [(fill as ArrayLike<number>)[i * 4]!, (fill as ArrayLike<number>)[i * 4 + 1]!, (fill as ArrayLike<number>)[i * 4 + 2]!, (fill as ArrayLike<number>)[i * 4 + 3]!]
+    vertices[d + 8] = c[0]
+    vertices[d + 9] = c[1]
+    vertices[d + 10] = c[2]
+    vertices[d + 11] = c[3]
+  }
+  return vertices
+}
+
+// Indices for a row-major (cellRows + 1) x (cellCols + 1) vertex grid: two
+// CCW triangles per cell, split across the row0col0-row1col1 diagonal -
+// the one quad pattern every grid generator here shares (rows run along
+// the surface, columns around, same handedness everywhere). A collapsed
+// first/last vertex row (sphere pole, cone apex) skips its zero-area
+// triangle per cell.
+function gridIndices(cellRows: number, cellCols: number, skipFirst = false, skipLast = false): number[] {
+  let cols = cellCols + 1
+  let out: number[] = []
+  for (let r = 0; r < cellRows; r++) {
+    for (let c = 0; c < cellCols; c++) {
+      let r0 = r * cols + c
+      let r1 = r0 + cols
+      if (!skipFirst || r > 0) out.push(r0 + 1, r0, r1 + 1)
+      if (!skipLast || r < cellRows - 1) out.push(r0, r1, r1 + 1)
+    }
+  }
+  return out
+}
+
 /** 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
@@ -174,30 +303,165 @@ export function torusKnot(
     }
   }
 
-  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
+  let indices = new Uint16Array(gridIndices(tubularSegments, radialSegments))
+
+  return { vertices, indices, label }
+}
+
+/**
+ * A capped cylinder on the y axis, centered on the origin. Different top
+ * and bottom radii make it a truncated cone (`cone()` is the zero-top
+ * case); side normals tilt with the taper. Side UVs: u around the
+ * circumference, v 0 at the top to 1 at the bottom; caps get a planar
+ * disc map. A zero radius skips that cap and the degenerate side
+ * triangles at the apex.
+ */
+export function cylinder(
+  radiusTop = 0.5,
+  radiusBottom = 0.5,
+  height = 1,
+  radialSegments = 24,
+  label?: string,
+): Geometry {
+  let h = height / 2
+  let cols = radialSegments + 1
+  let verts: number[] = []
+  // Side normal: perpendicular to the slant line in the (radial, y) plane.
+  let slant = Math.hypot(height, radiusBottom - radiusTop) || 1
+  let nr = height / slant
+  let ny = (radiusBottom - radiusTop) / slant
+  let rows = [
+    { r: radiusTop, y: h, v: 0 },
+    { r: radiusBottom, y: -h, v: 1 },
+  ]
+  for (let row of rows) {
+    for (let ix = 0; ix < cols; ix++) {
+      let u = ix / radialSegments
+      let phi = u * Math.PI * 2
+      let dx = -Math.cos(phi)
+      let dz = Math.sin(phi)
+      verts.push(row.r * dx, row.y, row.r * dz, nr * dx, ny, nr * dz, u, row.v)
+    }
+  }
+  let indices = gridIndices(1, radialSegments, radiusTop <= 0, radiusBottom <= 0)
+  // Caps fan around a center vertex; the planar UV map has no seam, so the
+  // ring wraps with modulo instead of duplicating a column.
+  let cap = (r: number, y: number, up: number) => {
+    let base = verts.length / FLOATS_PER_VERTEX
+    verts.push(0, y, 0, 0, up, 0, 0.5, 0.5)
+    for (let i = 0; i < radialSegments; i++) {
+      let phi = (i / radialSegments) * Math.PI * 2
+      let x = -Math.cos(phi) * r
+      let z = Math.sin(phi) * r
+      verts.push(x, y, z, 0, up, 0, 0.5 + x / (2 * r), 0.5 + (up > 0 ? z : -z) / (2 * r))
+    }
+    for (let i = 0; i < radialSegments; i++) {
+      let j = (i + 1) % radialSegments
+      if (up > 0) indices.push(base, base + 1 + i, base + 1 + j)
+      else indices.push(base, base + 1 + j, base + 1 + i)
     }
   }
+  if (radiusTop > 0) cap(radiusTop, h, 1)
+  if (radiusBottom > 0) cap(radiusBottom, -h, -1)
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
 
+/** A capped cone on the y axis, centered on the origin: `cylinder()` with
+ * a zero top radius (each apex vertex carries its column's side normal, so
+ * the surface shades smoothly around). */
+export function cone(radius = 0.5, height = 1, radialSegments = 24, label?: string): Geometry {
+  return cylinder(0, radius, height, radialSegments, label)
+}
+
+/**
+ * A torus lying flat, centered on the origin: the ring lies in the XZ
+ * plane with the hole on the y axis - the y-up orientation torusKnot also
+ * uses (Three's equivalent stands in XY). Signature order is Three's:
+ * radialSegments subdivides the tube cross-section, tubularSegments the
+ * ring. UVs: u 0..1 around the ring, v 0..1 around the tube, seam
+ * row/column duplicated like torusKnot.
+ */
+export function torus(
+  radius = 0.5,
+  tube = 0.2,
+  radialSegments = 12,
+  tubularSegments = 32,
+  label?: string,
+): Geometry {
+  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 phi = (i / tubularSegments) * Math.PI * 2
+    let dx = -Math.cos(phi)
+    let dz = Math.sin(phi)
+    for (let j = 0; j < cols; j++) {
+      let psi = (j / radialSegments) * Math.PI * 2
+      let cp = Math.cos(psi)
+      let sp = Math.sin(psi)
+      let r = radius + tube * cp
+      vertices[at] = r * dx
+      vertices[at + 1] = tube * sp
+      vertices[at + 2] = r * dz
+      vertices[at + 3] = cp * dx
+      vertices[at + 4] = sp
+      vertices[at + 5] = cp * dz
+      vertices[at + 6] = i / tubularSegments
+      vertices[at + 7] = j / radialSegments
+      at += FLOATS_PER_VERTEX
+    }
+  }
+  let indices = new Uint16Array(gridIndices(tubularSegments, radialSegments))
   return { vertices, indices, label }
 }
 
+/**
+ * A disc in the XY plane facing +z, centered on the origin (rotate flat
+ * like plane()). UVs are the planar map of the disc inscribed in the unit
+ * square.
+ */
+export function circle(radius = 0.5, segments = 32, label?: string): Geometry {
+  let verts: number[] = [0, 0, 0, 0, 0, 1, 0.5, 0.5]
+  let indices: number[] = []
+  for (let i = 0; i < segments; i++) {
+    let a = (i / segments) * Math.PI * 2
+    let c = Math.cos(a)
+    let s = Math.sin(a)
+    verts.push(radius * c, radius * s, 0, 0, 0, 1, 0.5 + c * 0.5, 0.5 - s * 0.5)
+  }
+  for (let i = 0; i < segments; i++) {
+    indices.push(0, 1 + i, 1 + ((i + 1) % segments))
+  }
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
+
+/**
+ * A flat annulus in the XY plane facing +z, centered on the origin. UVs
+ * are the planar map of the OUTER disc, so a ring textures like the
+ * matching circle() with the middle cut out.
+ */
+export function ring(innerRadius = 0.25, outerRadius = 0.5, segments = 32, label?: string): Geometry {
+  let verts: number[] = []
+  let indices: number[] = []
+  for (let i = 0; i < segments; i++) {
+    let a = (i / segments) * Math.PI * 2
+    let c = Math.cos(a)
+    let s = Math.sin(a)
+    for (let r of [innerRadius, outerRadius]) {
+      verts.push(r * c, r * s, 0, 0, 0, 1, 0.5 + (r * c) / (2 * outerRadius), 0.5 - (r * s) / (2 * outerRadius))
+    }
+  }
+  for (let i = 0; i < segments; i++) {
+    let j = (i + 1) % segments
+    indices.push(i * 2, i * 2 + 1, j * 2 + 1, i * 2, j * 2 + 1, j * 2)
+  }
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(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
@@ -212,16 +476,7 @@ export function sphere(radius = 0.5, widthSegments = 24, heightSegments = 16, la
       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)
-    }
-  }
+  // Both pole rows are collapsed to the pole point.
+  let indices = gridIndices(heightSegments, widthSegments, true, true)
   return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
 }

package/src/glsl.ts

@@ -0,0 +1,112 @@
+// The exported lighting GLSL: string constants an app composes into its
+// own shaderMaterial sources with plain template literals - the same
+// pieces the package's future lit materials will be built from, so a
+// custom material never becomes second-class (no preprocessor, no include
+// resolver; the policy is argued in okf/research/3d-differentiators.md).
+//
+// The light-model functions are PURE: normals, view vectors, light
+// directions, colors and exponents all arrive as arguments, so these
+// constants pin nothing but function names. The LIT_VERTEX pair are the
+// deliberate exception - they pin the standard varying interface
+// (vWorldPos, vNormal, vUv, plus vColor on the colored variant) and
+// consume the standard uniform set (uModel, uViewProj, uNormal);
+// fragments written against those names compose with them directly. All directions are expected normalized;
+// every function returns its raw term, weighting and color belong to the
+// caller.
+
+import { glsl } from "@solidrt/core/gpu"
+
+/**
+ * The standard lit vertex stage: clip position via uViewProj * uModel,
+ * with world position, world normal (via `mat3(uNormal)`, correct under
+ * non-uniform scale) and UV as varyings:
+ *
+ *   in vec3 vWorldPos; in vec3 vNormal; in vec2 vUv;
+ *
+ * Pair it with your own fragment; the view vector there is
+ * `normalize(uCamPos - vWorldPos)`.
+ */
+export const LIT_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec2 aUV;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform mat4 uNormal;
+  out vec3 vWorldPos;
+  out vec3 vNormal;
+  out vec2 vUv;
+
+  void main() {
+    vec4 world = uModel * vec4(aPos, 1.0);
+    gl_Position = uViewProj * world;
+    vWorldPos = world.xyz;
+    vNormal = mat3(uNormal) * aNormal;
+    vUv = aUV;
+  }
+`
+
+/**
+ * LIT_VERTEX for "colored"-layout geometry: the same interface plus the
+ * per-vertex aColor vec4 forwarded raw as `in vec4 vColor` - what it means
+ * (a tint, baked AO in one channel, anything) is the fragment's business.
+ * Using this constant opts the material into the colored layout (its
+ * meshes need withColors() geometry), because shaderMaterial detects
+ * aColor in the vertex source.
+ */
+export const LIT_VERTEX_COLORED = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec2 aUV;
+  in vec4 aColor;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform mat4 uNormal;
+  out vec3 vWorldPos;
+  out vec3 vNormal;
+  out vec2 vUv;
+  out vec4 vColor;
+
+  void main() {
+    vec4 world = uModel * vec4(aPos, 1.0);
+    gl_Position = uViewProj * world;
+    vWorldPos = world.xyz;
+    vNormal = mat3(uNormal) * aNormal;
+    vUv = aUV;
+    vColor = aColor;
+  }
+`
+
+/** `vec3 hemisphere(vec3 n, vec3 sky, vec3 ground)` - ambient from a
+ * sky/ground gradient by the normal's vertical tilt: sky straight up,
+ * ground bounce straight down. */
+export const HEMISPHERE = glsl`
+  vec3 hemisphere(vec3 n, vec3 sky, vec3 ground) {
+    return mix(ground, sky, n.y * 0.5 + 0.5);
+  }
+`
+
+/** `float lambert(vec3 n, vec3 l)` - the diffuse term for a directional
+ * light pointing TOWARD the light (multiply by your light color). */
+export const LAMBERT = glsl`
+  float lambert(vec3 n, vec3 l) {
+    return max(dot(n, l), 0.0);
+  }
+`
+
+/** `float blinnSpecular(vec3 n, vec3 v, vec3 l, float shininess)` - the
+ * Blinn-Phong highlight from the half vector between view and light;
+ * shininess runs from wide matte sheen (~8) to tight mirror dot (~150). */
+export const BLINN_SPECULAR = glsl`
+  float blinnSpecular(vec3 n, vec3 v, vec3 l, float shininess) {
+    return pow(max(dot(n, normalize(l + v)), 0.0), shininess);
+  }
+`
+
+/** `float fresnel(vec3 n, vec3 v, float power)` - the grazing-angle rim
+ * weight (1 at silhouettes, 0 face-on); typical power 3 to 5. */
+export const FRESNEL = glsl`
+  float fresnel(vec3 n, vec3 v, float power) {
+    return pow(1.0 - max(dot(n, v), 0.0), power);
+  }
+`

package/src/index.ts

@@ -7,13 +7,15 @@
 
 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 { box, circle, cone, cylinder, disposeGeometry, fillColors, plane, ring, sphere, torus, torusKnot, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
+export type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
+export { extrude, fillet, lathe, roundRect, shape, triangulate } from "./profile.ts"
+export type { Profile, ProfilePoint } from "./profile.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"
+export { compose, copy, identity, lookAt, mat4, multiply, normalMatrix, perspective } from "./math.ts"
+export type { Mat4, Vec2, Vec3 } from "./math.ts"

package/src/material.ts

@@ -36,7 +36,8 @@ import type {
   TextureId,
   Topology,
 } from "@solidrt/core/gpu"
-import { VERTEX_LAYOUT } from "./geometry.ts"
+import { VERTEX_LAYOUTS } from "./geometry.ts"
+import type { VertexLayout } from "./geometry.ts"
 
 export type Material = {
   /** The pipeline this material draws with (lazily created). */
@@ -45,6 +46,15 @@ export type Material = {
   params: ShaderParams
   /** Per-entry sampler bindings, when the material samples textures. */
   textures?: Record<string, TextureId>
+  /** True when the vertex stage declares `uNormal`: the scene then writes
+   * the world matrix's inverse-transpose alongside uModel for meshes using
+   * this material (set automatically by shaderMaterial). */
+  normalMatrix?: boolean
+  /** The vertex layout the pipeline is built for; absent means "standard".
+   * shaderMaterial sets "colored" when the vertex stage reads `aColor`. A
+   * mesh whose geometry layout differs is rejected at add() - the strides
+   * disagree, so a mismatch would render garbage, not just miss a channel. */
+  layout?: VertexLayout
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -97,7 +107,7 @@ function pipelineFor(kind: "color" | "map"): RenderPipelineId {
   })
   let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + kind })
   let pipeline = createRenderPipeline(program, {
-    attributes: VERTEX_LAYOUT,
+    attributes: VERTEX_LAYOUTS.standard,
     depth: true,
     cull: "back",
     label: "scene-unlit-" + kind,
@@ -140,13 +150,24 @@ export type ShaderMaterialOptions = {
    * mesh's world matrix, written per entry whenever the mesh moves) and
    * `uniform mat4 uViewProj` (the camera's view-projection, shared by the
    * whole scene target and written once per camera move) - transform with
-   * `uViewProj * uModel * vec4(aPos, 1.0)`. Declare any of the shared
+   * `uViewProj * uModel * vec4(aPos, 1.0)`; a source mentioning neither
+   * throws right here. The rest of the standard uniform set is opt-in by
+   * declare-and-use: `uniform mat4 uNormal` (either stage) receives the
+   * world inverse-transpose beside uModel - take `mat3(uNormal)` for
+   * normals, correct under non-uniform scale - and `uniform vec3 uCamPos`
+   * the camera's world position, shared like uViewProj (the specular /
+   * fresnel view vector: `uCamPos - worldPos`). Declare any of the
    * layout's `in` attributes (aPos vec3, aNormal vec3, aUV vec2);
-   * undeclared ones are skipped.
+   * undeclared ones are skipped. Reading `in vec4 aColor` opts the
+   * material into the "colored" 12-float layout - the per-vertex data
+   * channel (tint, baked AO, any four scalars); its meshes then need
+   * withColors() geometry, and a layout mismatch throws at add().
+   * `@solidrt/3d/glsl` exports a standard
+   * vertex stage and lighting pieces built on exactly this contract.
    */
   vertex: string
   fragment: string
-  /** Uniform seeds beyond uModel/uViewProj; update per mesh later with
+  /** Uniform seeds beyond the standard set; update per mesh later with
    * setMeshParams. */
   params?: ShaderParams
   textures?: Record<string, TextureId>
@@ -171,9 +192,25 @@ export type ShaderMaterialOptions = {
  * and `dispose()` it if the app is done with the look for good.
  */
 export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+  // The standard-set contract, checked where the mistake is made: a vertex
+  // stage that never mentions the matrices cannot place meshes, and with
+  // shared params skipping undeclared names the omission would otherwise
+  // surface as a silently untransformed render, not an error.
+  for (let name of ["uModel", "uViewProj"]) {
+    if (!new RegExp("\\b" + name + "\\b").test(opts.vertex)) {
+      throw new Error(
+        "shaderMaterial vertex stage must declare and use '" + name + "' (see the standard uniform set in AGENTS.md)",
+      )
+    }
+  }
   let program: ProgramId | undefined
   let pipeline: RenderPipelineId | undefined
+  // Attributes live in the vertex stage only, so unlike the uNormal scan
+  // there is nothing to look for in the fragment source.
+  let layout: VertexLayout = /\baColor\b/.test(opts.vertex) ? "colored" : "standard"
   return {
+    normalMatrix: /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment),
+    layout,
     pipeline() {
       if (pipeline === undefined) {
         let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
@@ -182,7 +219,7 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
         destroyShader(vs)
         destroyShader(fs)
         pipeline = createRenderPipeline(program, {
-          attributes: VERTEX_LAYOUT,
+          attributes: VERTEX_LAYOUTS[layout],
           depth: opts.depth ?? true,
           depthWrite: opts.depthWrite,
           blend: opts.blend,