@vgpu/render 0.0.1

package/src/domain/mesh.docs.md

@@ -0,0 +1,28 @@
+# Mesh
+
+`Mesh` is a pure geometry value for draw code. It owns a vertex buffer, a vertex count, a vertex
+attribute description, and a bounding box. It does not store transforms or scene hierarchy data.
+
+## `Mesh.box({ device, size })`
+
+`Mesh.box({ device })` returns a unit cube with face normals suitable for flat-shaded lighting. The
+default size is `1`, so the bounding box spans `[-0.5, -0.5, -0.5]` to `[0.5, 0.5, 0.5]`.
+
+Pass `size` to build a cube with a different edge length:
+
+```ts
+const unit = Mesh.box({ device });
+const large = Mesh.box({ device, size: 2 });
+```
+
+The vertex layout is interleaved as `[position, normal]` with two `vec3<f32>` attributes:
+
+- stride: 24 bytes
+- position: offset 0, format `float32x3`
+- normal: offset 12, format `float32x3`
+
+The cube uses 36 vertices: six faces, two triangles per face, and three vertices per triangle. Faces
+do not share vertices, so each face has one constant normal.
+
+Meshes are cached per device and per size. Repeating `Mesh.box({ device, size: 1 })` returns the same
+mesh instance and reuses one GPU vertex buffer for that device.

package/src/domain/orthographic-camera.docs.md

@@ -0,0 +1,22 @@
+# orthographicCamera
+
+Creates a pure camera value for orthographic projection.
+
+Pass the left, right, bottom, top, near, and far planes, plus a world-space `position` and `target`. The optional `up` vector defaults to `[0, 1, 0]`.
+
+```ts
+import { orthographicCamera } from "@vgpu/render";
+
+const camera = orthographicCamera({
+  left: -1,
+  right: 1,
+  bottom: -1,
+  top: 1,
+  near: 0.1,
+  far: 100,
+  position: new Float32Array([0, 0, 5]),
+  target: new Float32Array([0, 0, 0]),
+});
+```
+
+The matrix is computed once as projection times view and stored on `camera.viewProjectionMatrix`.

package/src/domain/perspective-camera.docs.md

@@ -0,0 +1,20 @@
+# perspectiveCamera
+
+Creates a pure camera value for perspective projection.
+
+Pass a vertical field of view in radians, aspect ratio, near and far planes, and a world-space `position` and `target`. The optional `up` vector defaults to `[0, 1, 0]`.
+
+```ts
+import { degToRad, perspectiveCamera } from "@vgpu/render";
+
+const camera = perspectiveCamera({
+  fovYRadians: degToRad(45),
+  aspect: canvas.width / canvas.height,
+  near: 0.1,
+  far: 100,
+  position: new Float32Array([0, 0, 5]),
+  target: new Float32Array([0, 0, 0]),
+});
+```
+
+The matrix is computed once as projection times view and stored on `camera.viewProjectionMatrix`.

package/src/domain/srgb.docs.md

@@ -0,0 +1,11 @@
+# srgb
+
+Converts colors from sRGB into linear RGB.
+
+The input is sRGB: the way humans, design tools, and hex color pickers usually describe colors. The output is linear RGB in the `0..1` range, which is the color space shaders need for lighting math.
+
+```ts
+const baseColor = srgb(0xcc8844);
+```
+
+You can pass a packed hex value such as `0xff6600`, or a three-component sRGB tuple such as `[0.5, 0.5, 0.5]`.

package/src/inspect/inspect-material.docs.md

@@ -0,0 +1,23 @@
+# InspectMaterial
+
+`InspectMaterial` is the low-level material shape used by the inspect sub-export.
+It contains a pipeline, a group-0 bind group layout, and a typed uniform writer.
+
+```ts
+const uniforms = device.createBuffer({
+  size: material.uniformByteSize,
+  usage: ["uniform", "copy_dst"],
+});
+
+material.writeUniforms(uniforms.gpu, 0, {
+  viewProjectionMatrix: camera.viewProjectionMatrix,
+  modelMatrix,
+});
+```
+
+`writeUniforms` writes the shared inspect matrices into the buffer. This keeps
+inspect materials independent from application materials used by `RapidRenderer`.
+
+`InspectMaterialUniformParams` includes `viewProjectionMatrix` and `modelMatrix`.
+Future inspect materials should extend this interface explicitly if they need
+additional uniform inputs.

package/src/inspect/mesh-to-wireframe.docs.md

@@ -0,0 +1,29 @@
+# meshToWireframe
+
+`meshToWireframe(mesh, device)` converts a readable triangle-list `Mesh` into a
+line-list index buffer with duplicate edges removed by endpoint position.
+
+```ts
+import { meshToWireframe } from "@vgpu/render/inspect";
+
+const wireframe = await meshToWireframe(readableMesh, device);
+
+// wireframe.vertexBuffer is readableMesh.vertexBuffer
+// wireframe.indexBuffer contains two indices per line segment
+```
+
+The source mesh's vertex buffer must be created with `GPUBufferUsage.COPY_SRC`
+so `meshToWireframe` can read back vertex positions. If the buffer is not
+readable, the function throws `VGPU-CORE-INVALID-USAGE`; `Mesh.box` currently
+does not satisfy this contract.
+
+Endpoints are quantized to a `1e-6` grid before comparison. Meshes with distinct
+features below that scale may have edges incorrectly merged, so author debug
+geometry at a larger scale or use a precomputed wireframe for tiny details.
+
+Coplanar triangle diagonals are omitted by comparing triangle face normals, so a
+readable unit-box triangle list produces 12 line segments and 24 indices.
+
+The returned `indexBuffer` is a raw `GPUBuffer`. Callers own its lifetime and
+should call `indexBuffer.destroy()` when done, or rely on `device.destroy()` to
+clean up at teardown.

package/src/inspect/normal-debug-material.docs.md

@@ -0,0 +1,26 @@
+# normalDebugMaterial
+
+Renders each fragment colored by its surface normal, which is useful for
+verifying mesh normals visually during development.
+
+```ts
+import { Mesh } from "@vgpu/render";
+import { normalDebugMaterial } from "@vgpu/render/inspect";
+
+const mesh = Mesh.box({ device });
+const material = normalDebugMaterial({ device });
+```
+
+Each fragment outputs `(normal + 1) / 2` as RGB, mapping the unit-cube normal
+range `[-1, +1]³` to `[0, 1]³`. A face whose normal points along +X reads pure
+red; +Y reads pure green; +Z reads pure blue. Reverse directions read cyan,
+magenta, and yellow.
+
+The pipeline uses `triangle-list` topology with depth testing and back-face
+culling. Default `targetFormat` is `'bgra8unorm-srgb'`; use
+`'rgba8unorm-srgb'` on platforms that require it.
+
+Normals are passed through in object space. Applying a rotation in `modelMatrix`
+rotates the visualized colors with the geometry, which is the intended behavior
+for this inspector. A normal matrix is not applied; this is a development
+visualization, not a lighting pass.

package/src/inspect/wireframe-material.docs.md

@@ -0,0 +1,22 @@
+# wireframeMaterial
+
+`wireframeMaterial` renders a mesh as line segments, which is useful for
+visualizing geometry edges during development.
+
+```ts
+import { meshToWireframe, wireframeMaterial } from "@vgpu/render/inspect";
+
+const wireframe = await meshToWireframe(readableMesh, device);
+const material = wireframeMaterial({ device, color: [1, 1, 1] });
+```
+
+The pipeline uses `line-list` topology with depth testing on and no back-face
+culling. It expects the same interleaved position and normal vertex layout as the
+source mesh passed to `meshToWireframe`.
+
+`color` defaults to `[1, 1, 1]` in linear RGB. `targetFormat` defaults to
+`'bgra8unorm-srgb'`; use `'rgba8unorm-srgb'` on platforms that require it.
+
+The returned `InspectMaterial` is for low-level draws. Pair it with
+`meshToWireframe`, bind a uniform buffer at group 0, then issue an indexed
+line-list draw.

package/src/rapid-renderer.docs.md

@@ -0,0 +1,18 @@
+# RapidRenderer
+
+`RapidRenderer` submits one draw to a target view. The renderer binds a material,
+optionally binds a mesh, then draws either `vertexCount` or `mesh.vertexCount`.
+
+```ts
+material.writeUniforms({ viewProjection, model, cameraPosition, light });
+await renderer.draw({ material, mesh, target, depthTarget });
+await renderer.draw({ material, pipeline, target, vertexCount: 3 });
+```
+
+`material` is required. `pipeline` is an optional override; otherwise the renderer
+uses `material.pipeline`. Call `material.writeUniforms()` before `draw()` when the
+material has uniforms. The renderer does not write camera, transform, light, or
+material parameters.
+
+`clearValue` defaults to opaque black. `depthTarget` is optional. `renderer.gpu`
+returns the raw `GPUDevice`. `draw()` resolves after command submission.

package/src/uniform-pool.docs.md

@@ -0,0 +1,60 @@
+# UniformPool
+
+`UniformPool` stages per-draw uniform bytes in CPU memory and uploads them to a
+WebGPU uniform buffer at the frame boundary. Each `push()` returns the dynamic
+offset, in bytes, to pass when binding the slot for a draw.
+
+## Slots
+
+`pool.alloc(layout)` returns a `UniformSlot<T>` with:
+
+- `slot.gpu`: the underlying `GPUBuffer` used by the pool.
+- `slot.bindGroup`: a real `GPUBindGroup` with a dynamic uniform-buffer binding.
+- `slot.bindGroupLayout`: a real `GPUBindGroupLayout` whose binding uses
+  `hasDynamicOffset: true`.
+- `slot.stride`: `layout.size` padded up to the device's uniform-buffer offset
+  alignment.
+
+All slots allocated by one pool share the same backing `GPUBuffer`. Each slot
+has its own bind group so callers can bind the slot once and vary only the
+dynamic offset returned by `push()` or `pushBytes()`.
+
+## Pipeline layout sharing
+
+A layout may provide a pre-built bind group layout:
+
+```ts
+const slot = pool.alloc({
+  size,
+  bindGroupLayout: material.bindGroupLayout,
+  encode(value, dst, byteOffset) {
+    // write uniform bytes
+  },
+});
+```
+
+When `bindGroupLayout` is provided, the slot reuses it instead of creating a new
+layout. Use this when a pipeline already owns the bind group layout that will
+consume the slot's bind group.
+
+## Frame uploads
+
+`push(value)` and `pushBytes(bytes)` write into the pool's CPU mirror only. They
+do not call WebGPU immediately. `endFrame()` uploads pending bytes with
+`device.gpu.queue.writeBuffer(pool.gpu, 0, pool.cpuMirror, 0, pool.usedBytes)`.
+
+Calling `endFrame()` on a clean pool is a no-op. If more values are pushed after
+`endFrame()`, a later `endFrame()` uploads the updated CPU mirror again.
+
+## Submit readiness
+
+Call `endFrame()` before submitting command buffers that read data from the
+pool. `assertReadyForSubmit(opName)` checks this invariant. If there are pending
+pushes that have not been uploaded, it throws `VGPU-CORE-INVALID-USAGE` with:
+
+```txt
+UniformPool has unflushed pushes; call endFrame() before submitting.
+```
+
+Renderers should call `assertReadyForSubmit()` immediately before
+`queue.submit()`.

package/src/utils/canvas-mouse-tracker.docs.md

@@ -0,0 +1,13 @@
+# canvasMouseTracker
+
+Tracks the latest pointer position over a canvas. Use it when a render loop needs the mouse position without storing event handlers in your app code.
+
+```ts
+const mouse = canvasMouseTracker({ canvas, normalize: true });
+function draw() {
+  const [x, y] = mouse.position;
+  material.writeUniforms({ mouse: [x, y] });
+}
+```
+
+Call `dispose()` when the canvas is removed.

package/src/utils/canvas-resolution.docs.md

@@ -0,0 +1,13 @@
+# canvasResolution
+
+Reads the drawing size of a canvas. Use it when shaders or render targets need the current canvas width and height.
+
+```ts
+const size = canvasResolution(canvas, { observe: true });
+function draw() {
+  material.writeUniforms({ resolution: [size.width, size.height] });
+  renderer.draw({ target, material, mesh });
+}
+```
+
+Call `dispose()` to stop observing size changes.

package/src/utils/frame-clock.docs.md

@@ -0,0 +1,14 @@
+# frameClock
+
+Measures elapsed time and frame delta in seconds. Use it in animation loops that need stable time values and pause support.
+
+```ts
+const clock = frameClock();
+function frame() {
+  const time = clock.now();
+  const dt = clock.delta();
+  update(time, dt);
+}
+```
+
+Use `pause()`, `resume()`, and `reset()` to control the clock.