insomni 0.2.0-alpha.0

package/README.md

@@ -0,0 +1,234 @@
+# insomni
+
+`insomni` is an opinionated 2D WebGPU renderer. It is optimized for data-heavy, interactive scenes — geometry is packed CPU-side into flat float arrays and uploaded to the GPU each frame. SDF-based primitives cover the common cases; complex polygons fall back to `earcut` triangulation.
+
+> **Alpha.** The core rendering loop is stable but some APIs carry known limitations (see [Alpha limitations](#alpha-limitations) below).
+
+## Installation
+
+```
+npm install insomni
+# or
+pnpm add insomni
+```
+
+WebGPU must be available in the environment. Chrome 113+ and Safari 18+ ship it behind no flag.
+
+## Quick start
+
+```ts
+import { initGPU, createRenderer, createLayer, rgba } from "insomni";
+
+// 1. Acquire the GPU device.
+const gpu = await initGPU();
+
+// 2. Build a renderer wired to a canvas element.
+const canvas = document.querySelector("canvas") as HTMLCanvasElement;
+const renderer = createRenderer(gpu, canvas);
+renderer.setBackground(rgba(0.05, 0.06, 0.09, 1));
+
+// 3. Create a layer and push some primitives.
+const scene = createLayer(); // "world" space by default
+
+scene.pushRect({
+  x: 40,
+  y: 36,
+  width: 240,
+  height: 128,
+  fill: rgba(0.13, 0.15, 0.2, 1),
+  cornerRadius: 16,
+});
+scene.pushCircle({ cx: 160, cy: 100, radius: 24, fill: rgba(0.36, 0.7, 1, 1) });
+scene.pushLine({ x1: 40, y1: 170, x2: 280, y2: 170, color: rgba(1, 1, 1, 0.2), width: 1 });
+
+// 4. Render each frame.
+function frame(now: DOMHighResTimeStamp) {
+  renderer.render([scene]);
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+
+// 5. Handle resize.
+window.addEventListener("resize", () => {
+  const dpr = window.devicePixelRatio;
+  renderer.setDpr(dpr);
+  renderer.resize(canvas.clientWidth, canvas.clientHeight);
+});
+
+// 6. Tear down.
+function dispose() {
+  renderer.destroy();
+  gpu.destroy();
+}
+```
+
+## Coordinate spaces
+
+Every `Layer` lives in one of two coordinate spaces, set once at construction:
+
+| Space               | Meaning                                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `"world"` (default) | Camera-transformed world coordinates. Pan, zoom, and `fitCameraToBounds` all apply.                               |
+| `"ui"`              | CSS pixel coordinates fixed to the canvas. Unaffected by the camera. Useful for HUD overlays, axes, and tooltips. |
+
+```ts
+const hud = createLayer({ space: "ui" });
+hud.pushRect({ x: 8, y: 8, width: 120, height: 32, fill: rgba(0, 0, 0, 0.6), cornerRadius: 6 });
+```
+
+## Layer and Group model
+
+**`Layer`** is the universal drawable. It owns a CPU-side pack of shape commands and an optional coordinate space. You create one with `createLayer()`, populate it with `push*` calls, and hand it to `renderer.render([...layers])`. Layer order in the array sets draw order — earlier layers are painted first.
+
+```ts
+const background = createLayer();
+const foreground = createLayer();
+// background is drawn first, foreground on top:
+renderer.render([background, foreground]);
+```
+
+**`Group`** is a lightweight transform container. Any primitive whose `group` field references a `Group` instance is transformed by that group's `transform` matrix at draw time — no CPU repacking needed. Mutating `group.transform` and re-rendering is enough to move, rotate, or scale an entire cluster of shapes as a rigid body.
+
+```ts
+import { createGroup, rotation } from "insomni";
+
+const orbit = createGroup();
+orbit.transform = rotation(Date.now() * 0.001);
+
+layer.pushRect({ x: -20, y: -20, width: 40, height: 40, fill: rgba(1, 0.5, 0), group: orbit });
+layer.pushCircle({ cx: 80, cy: 0, radius: 10, fill: rgba(0, 0.8, 1), group: orbit });
+```
+
+## Dynamic vs. static (cached) layers
+
+By default every layer is **dynamic**: on each frame the CPU pack is re-uploaded to GPU. This is fine for most scenes.
+
+For large, unchanging geometry (grids, axis decorations, terrain) you can bake a layer to a cached RTT texture:
+
+```ts
+// Bake the layer once — runs an MSAA render pass and freezes it into a texture.
+renderer.cacheLayer(grid);
+
+// Every subsequent render() composites the baked texture instead of re-drawing the geometry.
+renderer.render([grid, dynamic]);
+
+// Must be called before re-baking with new content.
+renderer.uncacheLayer(grid);
+grid.clear();
+// ... rebuild grid ...
+renderer.cacheLayer(grid);
+```
+
+`cacheLayer` requires `createRenderer` (not a bare `new Renderer2D`). The bake freezes the world-space camera; a subsequent pan or zoom will NOT re-bake automatically — call `uncacheLayer` + `cacheLayer` to refresh.
+
+## OIT — Order-independent transparency
+
+OIT is **on by default**. Text (MSDF glyphs) and transparent sprites z-interleave with shapes correctly regardless of draw order. The A-buffer composites depth-sorted fragments per pixel at the end of each frame.
+
+When OIT is off (`config: { oit: false }`), glyphs and sprites fall back to a painter-order depth stamp — they will not float unconditionally on top, but they will not depth-sort against transparent geometry either.
+
+You can pass a partial `RendererConfig` to `createRenderer`:
+
+```ts
+const renderer = createRenderer(gpu, canvas, {
+  config: { oit: false }, // disable OIT (saves ~16 MiB of A-buffer memory)
+});
+```
+
+## Primitive push methods
+
+All methods live on `Layer` and return `this` for chaining (except `pushText` which returns glyph metrics):
+
+| Method                      | Shape                                       |
+| --------------------------- | ------------------------------------------- |
+| `pushRect(shape)`           | Axis-aligned rounded rectangle              |
+| `pushCircle(shape)`         | Circle                                      |
+| `pushEllipse(shape)`        | Ellipse                                     |
+| `pushLine(shape)`           | Line segment (alias for `pushSegment`)      |
+| `pushSegment(shape)`        | Line segment                                |
+| `pushCurve(shape)`          | Cubic Bézier curve                          |
+| `pushArc(shape)`            | Arc                                         |
+| `pushTriangle(shape)`       | Single triangle                             |
+| `pushPolygon(shape)`        | Polygon (triangulated via earcut)           |
+| `pushStroke(shape)`         | Analytic SDF stroke path (round joins only) |
+| `pushSprite(sprite)`        | Textured sprite (atlas region)              |
+| `pushText(shape)`           | MSDF glyph text                             |
+| `pushAnchoredString(shape)` | World-anchored, screen-sized text           |
+
+Call `layer.clear()` to reset the pack before rebuilding each frame.
+
+## Camera and resize
+
+```ts
+// Fit the world camera to a bounding box each resize:
+renderer.fitCameraToBounds({ minX: 0, minY: 0, maxX: 800, maxY: 600 }, { padding: 0.9 });
+
+// Manual HiDPI setup:
+renderer.setDpr(window.devicePixelRatio);
+renderer.resize(canvas.clientWidth, canvas.clientHeight);
+```
+
+## Frame timing
+
+Pass `onFrameTiming` in the renderer config to receive per-frame CPU/GPU timing info:
+
+```ts
+const renderer = createRenderer(gpu, canvas, {
+  config: {
+    onFrameTiming: (t) => console.log("frame", t),
+  },
+});
+```
+
+## Device loss
+
+`initGPU` exposes two hooks for GPU error handling:
+
+```ts
+const gpu = await initGPU({
+  onDeviceLost: (info) => {
+    // Notified when device is lost unexpectedly (GPU reset, driver crash, TDR).
+    // insomni does NOT auto-recreate. Tear down your renderer and call initGPU again.
+    console.error("GPU lost:", info.message);
+  },
+  onUncapturedError: (err) => {
+    // Notified for each uncaptured GPU error (validation, out-of-memory).
+    console.error("GPU error:", err);
+  },
+  logger: myLogger, // optional; defaults to console
+});
+```
+
+## SVG export
+
+The SVG backend consumes the same `Layer[]` as `render()`:
+
+```ts
+import { createSVGRenderer } from "insomni";
+
+const svg = createSVGRenderer({ width: renderer.width, height: renderer.height });
+svg.setCamera(renderer.getCamera());
+svg.setBackground(bg);
+svg.render([scene]);
+document.body.appendChild(svg.element());
+```
+
+## Alpha limitations
+
+- **Device-loss recovery is notify-only.** `onDeviceLost` fires but insomni does not auto-recreate the device or rebuild GPU resources. Callers must tear down and call `initGPU` again.
+- **OIT fragment budget is fixed at K=8 per pixel** (configurable up to K=16 via `config.oitFragmentsPerPixel`). Dense overlapping transparent layers will drop the deepest fragments.
+- **Clipping is rectangular scissor only.** There is no stencil-based or path-based clip.
+- **SDF stroke joins are round only.** Passing `join: "miter"` or `join: "bevel"` to `pushStroke` falls back to tessellated polylines.
+- **`cacheLayer` freezes the world-space camera.** A camera move after baking does not re-bake automatically.
+
+## Subpath exports
+
+| Import path          | Contents                                               |
+| -------------------- | ------------------------------------------------------ |
+| `insomni`            | Core renderer, Layer, Group, math, interactions        |
+| `insomni/text-ttf`   | TTF/MSDF text with `loadFont()` (pulls in opentype.js) |
+| `insomni/viewport`   | `createViewport`, `CameraViewport`, pan-bound types    |
+| `insomni/internal`   | Render-debug probes (unstable)                         |
+| `insomni/reactivity` | Reactive primitives (unstable)                         |
+| `insomni/spatial`    | Spatial indexing helpers (unstable)                    |
+| `insomni/particles`  | Particle system (unstable)                             |

package/dist/advanced.d.mts

@@ -0,0 +1,76 @@
+import { a as SpriteBufferLayout, c as TriangleBufferLayout, i as ShapeSchema, l as TriangleSchema, n as CameraSchema, o as SpriteSchema, r as ShapeBufferLayout, s as TextureSamplerLayout, t as CameraLayout } from "./pipeline-DE3a1Pnk.mjs";
+import { Fn as INSTANCE_LAYOUT, In as deriveLayout, Ln as INSTANCE_BYTES, Rn as INSTANCE_FIELDS, Sn as assembleShader, bn as createPipelines, er as SHAPE_BYTES, i as RendererConstructorOptions, ir as SPRITE_FLOATS, nr as SHAPE_ELLIPSE, or as TRIANGLE_FLOATS, rr as SHAPE_RECT, tr as SHAPE_CIRCLE, xn as AssembledShader, yn as Pipelines, zn as INSTANCE_FLOATS } from "./renderer-DzZqd1bY.mjs";
+import tgpu, { TgpuRoot, d } from "typegpu";
+
+//#region src/core/f16.d.ts
+/**
+ * IEEE-754 half-precision (f16) packing helpers. Used to pack per-shape
+ * scalars into the instance vertex buffer — see `pack/uber-pack.ts`.
+ *
+ * Not suitable for large-magnitude world coordinates: f16 has ±65504 range
+ * and sub-pixel precision only up to ~1024.
+ */
+/**
+ * Pack a 32-bit float into its 16-bit half-precision bit pattern.
+ * Rounds ties to even. NaN → canonical quiet NaN. Out-of-range → ±Inf.
+ */
+declare function packF16(value: number): number;
+/** Pack (lo, hi) as a single little-endian u32 — `pack2x16float` equivalent. */
+declare function pack2xF16(lo: number, hi: number): number;
+/**
+ * Pack four components clamped to [0,1] as a little-endian unorm8x4 u32.
+ * Match to WGSL `unpack4x8unorm(value)` which yields `vec4f(r, g, b, a)` with
+ * component 0 in the low byte.
+ */
+declare function packUnorm8x4(r: number, g: number, b: number, a: number): number;
+/** Unpack an IEEE-754 f16 bit pattern into a JS number. Inverse of `packF16`. */
+declare function unpackF16(bits: number): number;
+//#endregion
+//#region src/schema/emit-snippet.d.ts
+/** Options for {@link writeRectInstance}. */
+interface WriteRectInstanceOptions {
+  /**
+   * WGSL name of the `var<storage, read_write>` array the instance is written
+   * into. The array element type MUST be the uber `InstanceStruct` (16-float /
+   * 64 B) — i.e. the same struct `INSTANCE_STRUCT_WGSL` declares. Defaults to
+   * `"instances"`.
+   */
+  array?: string;
+}
+/**
+ * WGSL helper-function source for emitting a v3 rect `Instance` into a storage
+ * array, with a field mapping byte-identical to `kinds/rect.ts`'s `pack()`.
+ *
+ * Emits one function:
+ *
+ * ```wgsl
+ * fn writeRectInstance(
+ *   index: u32,        // element index into the storage array
+ *   center: vec2f,     // rect center (x + halfW, y + halfH)
+ *   halfSize: vec2f,   // (halfW, halfH) = (width, height) * 0.5
+ *   fill: vec4f,       // fill color, components in [0,1]
+ *   stroke: vec4f,     // stroke color, components in [0,1]
+ *   strokeWidth: f32,
+ *   cornerRadius: f32,
+ *   rotation: f32,     // radians; the CALLER normalizes to (-pi, pi] if desired
+ *   order: f32,        // explicit depth (never index-derived)
+ * )
+ * ```
+ *
+ * NOTE the param contract vs the CPU `RectRecord`: this helper takes `center` +
+ * `halfSize` (already halved) rather than top-left `x,y` + full `width,height`,
+ * because a compute kernel typically has the centroid in hand. The CPU packer
+ * does `center = (x + w/2, y + h/2)` / `half = (w/2, h/2)` itself — pass those
+ * precomputed values here and the resulting bytes match. The CPU packer also
+ * wraps `rotation` into `(-pi, pi]`; WGSL `pack2x16float` does not, so the
+ * caller should wrap rotation to match if it needs bit-exact parity for
+ * out-of-range angles (in-range angles are already identical).
+ *
+ * The emitted function reads the field names from {@link INSTANCE_LAYOUT}
+ * (`inst.geom0`, `inst.lane3`, …) so it cannot drift from the schema.
+ *
+ * @param opts.array  Storage-array variable name. Default `"instances"`.
+ */
+declare function writeRectInstance(opts?: WriteRectInstanceOptions): string;
+//#endregion
+export { type AssembledShader, CameraLayout, CameraSchema, INSTANCE_BYTES, INSTANCE_FIELDS, INSTANCE_FLOATS, INSTANCE_LAYOUT, type Pipelines, type RendererConstructorOptions, SHAPE_BYTES, SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_RECT, SPRITE_FLOATS, ShapeBufferLayout, ShapeSchema, SpriteBufferLayout, SpriteSchema, TRIANGLE_FLOATS, TextureSamplerLayout, type TgpuRoot, TriangleBufferLayout, TriangleSchema, type WriteRectInstanceOptions, assembleShader, createPipelines, d, deriveLayout, pack2xF16, packF16, packUnorm8x4, tgpu, unpackF16, writeRectInstance };

package/dist/advanced.mjs

@@ -0,0 +1,81 @@
+import { C as pack2xF16, E as unpackF16, L as INSTANCE_BYTES, R as INSTANCE_FIELDS, T as packUnorm8x4, b as INSTANCE_LAYOUT, d as SHAPE_BYTES, f as SHAPE_CIRCLE, g as TRIANGLE_FLOATS, h as SPRITE_FLOATS, i as createPipelines, m as SHAPE_RECT, p as SHAPE_ELLIPSE, r as assembleShader, w as packF16, x as deriveLayout, z as INSTANCE_FLOATS } from "./assemble-BT3CXbSx.mjs";
+import { c as SpriteBufferLayout, d as TriangleBufferLayout, f as TriangleSchema, l as SpriteSchema, n as CameraLayout, o as ShapeBufferLayout, r as CameraSchema, s as ShapeSchema, u as TextureSamplerLayout } from "./pipeline-BWCAZTKx.mjs";
+import tgpu, { d } from "typegpu";
+//#region src/schema/emit-snippet.ts
+/**
+* WGSL helper-function source for emitting a v3 rect `Instance` into a storage
+* array, with a field mapping byte-identical to `kinds/rect.ts`'s `pack()`.
+*
+* Emits one function:
+*
+* ```wgsl
+* fn writeRectInstance(
+*   index: u32,        // element index into the storage array
+*   center: vec2f,     // rect center (x + halfW, y + halfH)
+*   halfSize: vec2f,   // (halfW, halfH) = (width, height) * 0.5
+*   fill: vec4f,       // fill color, components in [0,1]
+*   stroke: vec4f,     // stroke color, components in [0,1]
+*   strokeWidth: f32,
+*   cornerRadius: f32,
+*   rotation: f32,     // radians; the CALLER normalizes to (-pi, pi] if desired
+*   order: f32,        // explicit depth (never index-derived)
+* )
+* ```
+*
+* NOTE the param contract vs the CPU `RectRecord`: this helper takes `center` +
+* `halfSize` (already halved) rather than top-left `x,y` + full `width,height`,
+* because a compute kernel typically has the centroid in hand. The CPU packer
+* does `center = (x + w/2, y + h/2)` / `half = (w/2, h/2)` itself — pass those
+* precomputed values here and the resulting bytes match. The CPU packer also
+* wraps `rotation` into `(-pi, pi]`; WGSL `pack2x16float` does not, so the
+* caller should wrap rotation to match if it needs bit-exact parity for
+* out-of-range angles (in-range angles are already identical).
+*
+* The emitted function reads the field names from {@link INSTANCE_LAYOUT}
+* (`inst.geom0`, `inst.lane3`, …) so it cannot drift from the schema.
+*
+* @param opts.array  Storage-array variable name. Default `"instances"`.
+*/
+function writeRectInstance(opts = {}) {
+	const arr = opts.array ?? "instances";
+	const O = INSTANCE_LAYOUT.offsets;
+	for (const name of [
+		"geom0",
+		"geom1",
+		"colorBits",
+		"typeFlag",
+		"order",
+		"lane0",
+		"lane1",
+		"lane2",
+		"lane3",
+		"lane4"
+	]) if (!(name in O)) throw new Error(`writeRectInstance: schema missing field "${name}"`);
+	return `
+fn writeRectInstance(
+  index: u32,
+  center: vec2f,
+  halfSize: vec2f,
+  fill: vec4f,
+  stroke: vec4f,
+  strokeWidth: f32,
+  cornerRadius: f32,
+  rotation: f32,
+  order: f32,
+) {
+  var inst: InstanceStruct;
+  inst.geom0 = vec4f(center, 0.0, 0.0);
+  inst.geom1 = vec4f(0.0);
+  inst.colorBits = pack4x8unorm(fill);
+  inst.typeFlag = 0u;
+  inst.order = order;
+  inst.lane0 = pack4x8unorm(stroke);
+  inst.lane1 = pack2x16float(vec2f(rotation, strokeWidth));
+  inst.lane2 = pack2x16float(vec2f(cornerRadius, 0.0));
+  inst.lane3 = pack2x16float(halfSize);
+  inst.lane4 = 0u;
+  ${arr}[index] = inst;
+}`;
+}
+//#endregion
+export { CameraLayout, CameraSchema, INSTANCE_BYTES, INSTANCE_FIELDS, INSTANCE_FLOATS, INSTANCE_LAYOUT, SHAPE_BYTES, SHAPE_CIRCLE, SHAPE_ELLIPSE, SHAPE_RECT, SPRITE_FLOATS, ShapeBufferLayout, ShapeSchema, SpriteBufferLayout, SpriteSchema, TRIANGLE_FLOATS, TextureSamplerLayout, TriangleBufferLayout, TriangleSchema, assembleShader, createPipelines, d, deriveLayout, pack2xF16, packF16, packUnorm8x4, tgpu, unpackF16, writeRectInstance };