@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to `@ludic-labs/assembly` (previously `@victorqueiroz/ludic-assembly`). Qualification evidence for each release is in `qualification/`; benchmark outcomes and visual acceptance are recorded separately.
+
+## Unreleased
+
+- Publish the package publicly under `@ludic-labs/assembly`; installation no longer requires GitHub Packages credentials. The license is unchanged.
+- Automatically publish tested `main` revisions through npm trusted publishing. New revisions advance the stable patch unless the source declares a higher version; rerunning an already published revision is a no-op.
+- Add three editable SVG effects: aurora ribbon, ember fountain and arcane shield. The homepage and Waygate page offer still previews, opt-in motion, source editing and animated SVG downloads.
+- Remove the Pixel sprites promotion and navigation link from the homepage; its documentation remains available at `/sprites/`.
+
+## 0.4.0 — 2026-11-05
+
+### Added
+
+- `@victorqueiroz/ludic-assembly/sprite` entry point and the `pixel-sprite/0.1` notation, a JSON form of pixel art that models write, read and edit: palettes of named ramps, cels built from ordered layers (literal `pixels` rows, shapes, stamps, components, `silhouette`, `shade`, `outline`, `bevel`, `speck`, `mirror`, `recolor`, `repaint`, `move`, recipes), animations and a part for every pixel (`pickSprite`). Views project a 3D asset at one density into a layout guide (part boxes, masks, depth, light tones; cutaways with `hide`, door states with `pose`) that the compiler checks drawings against. `spriteBrief` writes the guide as a Markdown brief for a model; `decompileSprite` turns existing pixel art into an equivalent structured document. Host-independent, deterministic, typed, with structured `SPRITE_*` diagnostics and budgets. Schemas: `/schema/pixel-sprite-0.1` and `/schema/pixel-sprite-scene-0.1`. Model-facing guide: [`docs/sprite.md`](docs/sprite.md) (served as `/sprite.md`).
+- Sprite scenes (`pixel-sprite-scene/0.1`): placements of gallery or scene-local assets drawn by sprite documents, one shared palette derived from the placed materials, per-placement views from the scene camera and yaw, cutaway views, door states, composition by per-pixel 3D depth (`composeSpriteScene`), picking by placement and part (`pickScene`) and a footprint report of alignment and draw order (`spriteSceneFootprint`).
+- `/pixel`: images report per-pixel depth (`image.depth`), used to composite 2D layers over a render.
+- Documentation: a pixel sprites page with a live corner kitchen (17 placements, two views, opening doors, picking; drawn by Codex, by Claude, by a guided image model brought into the notation, and by a machine baseline) and the measured comparison of notation authors and cheap image models. The kitchen's scene-local assets are public examples in `examples/scenes/kitchen/`.
+- Experimental `@victorqueiroz/ludic-assembly/pixel` entry point (`pixel-profile/0.1`). `renderPixelArt` draws a compiled asset, or a scene from `composePixelScene`, straight to a logical pixel grid at a fixed density. It uses derived hue-shifted ramps, banded camera-relative light, coloured or dark outlines, inner lines decided per pair of parts, feature accents, sub-pixel face suppression and a palette capped across all views. Also: 2:1 dimetric and top-down camera presets, `scene`/`fantasy`/`arcade` presets from an itch.io style survey, UV-free surface patterns (`stripes`, `checker`, `grid`, `bricks`) evaluated in each asset's own frame, `pickPixel` and structured `PIXEL_*` diagnostics and budgets. No owner visual acceptance; no live or animated renderer.
+- Documentation: the pixel art section renders every gallery asset with the pixel renderer instead of downscaling its thumbnail, and adds a village scene composed only of gallery assets (`examples/scenes/village-corner.json`), shown from five cameras and in three profiles. `npm run test:browser` checks it in Chromium, Firefox and WebKit.
+- Initial `svg-asset/0.1` notation and isolated `/svg` entry point: parameterized SVG paths and primitives, scoped symbols, repeats, paint definitions, deterministic clips/particles, static and sampled animated SVG export. Includes a versioned schema, CLI frame export, original character/interior/effect examples, a local authoring preview and browser pixel qualification. This is a new 2D contract, separate from the existing assembly schema versions; visual acceptance and publication remain separate.
+- Add Ember’s Waygate to the documentation: a complete platform game using the SVG notation examples, a freestanding C++23/CMake WebAssembly runtime and a WebGL 1.0 atlas renderer. Includes an asset atelier, keyboard and pointer controls, pause/restart, context recovery, source provenance and native/browser qualification.
+- Experimental `@victorqueiroz/ludic-assembly/export` entry point: `exportGLB` writes a deterministic static binary glTF 2.0 of a compiled or posed asset or a small scene (stable instance IDs as node names, per-material base colors, untinted vertex colors, units recorded and never converted, a root turn to glTF's +Z front), and `bakeScene` renders a transparent square image with the preview rasterizer. Rigs and clips are not exported.
+- Browser previews: `snapshot()` returns the shown scene, camera, framing and clip frame.
+- Browser previews: a `camera` getter; vertical drags tilt the view; arrow keys orbit a focused preview (Shift for finer steps) and Home restores the initial view. Only the first pointer and the primary mouse button orbit.
+- Documentation: Markdown routes for LLMs and coding agents. `/llms.txt` indexes the site, `/llms-full.txt` combines the quick start, guide, API reference, gallery catalog and city notes, and every page has a Markdown twin (`/index.md`, `/guide.md`, `/city.md`, `/gallery.md`, `/gallery/<id>.md` with the asset's full definition), linked from its HTML head. `npm run test:llms` checks structure, links and parity with the HTML.
+- Documentation: the home page starts newcomers in one step (install command, a browser module that renders a gallery asset, a prompt for coding agents, or direct export), with a live preview running the same calls and the full gallery below. The walkthrough moved to `/guide/`; old home page fragments redirect there.
+- Documentation: every live example exports its source JSON (where it has one), a GLB of the shown mesh and a 1024 × 1024 PNG of the current view. GLB and PNG are disabled while an edited description is invalid.
+
+### Changed
+
+- Browser previews: dragging grabs the model, so it turns in the direction of the drag; it previously turned the opposite way. The playable city's orbit follows the same convention.
+- Gallery: the crab's claws are rebuilt as curved, toothed fixed and movable fingers held across its face, hinged so "Snap the claws" visibly opens and closes each pincer.
+
+### Fixed
+
+- Documentation previews keep the reader's dragged view when a clip changes, and "Rotate 45°" turns from the current view instead of a stale copy.
+
+## 0.3.0 — 2026-11-04
+
+### Added
+
+- **Schema `asset-assembly/0.3`**, a superset of 0.2:
+  - part `rotation` in degrees (X, then Y, then Z about fixed axes); bounds and anchors come from the rotated geometry; quarter turns are exact;
+  - part `array`: `line` (any step vector), `grid` (counts per axis) and `radial` (axis, start, sweep, optional orientation), with stable `part/0…n−1` instance IDs;
+  - primitives `sphere`, `ellipsoid`, `cone`, `wedge`, `lathe` (profiles that may rise, fall or close into rings) and `extrude` (concave outlines), plus `sides` (3–32) on `cylinder`, `funnel` and `tube`;
+  - continuous DOFs that loop after whole turns, for wheels, rotors and clock hands;
+  - joints copied per array instance (`joint/0…n−1`), with axes that turn with radially oriented copies;
+  - diagnostics `INVALID_ROTATION`, `SELF_INTERSECTING_OUTLINE`, `SELF_INTERSECTING_PROFILE` and `JOINT_ARRAY_MISMATCH`, and `UNSUPPORTED_COMBINATION` for arrays with corner repetition or mirrored sides.
+- Structural schema `schemas/asset-assembly-0.3.schema.json`, exported as `@victorqueiroz/ludic-assembly/schema/asset-assembly-0.3`.
+- `posedMesh(asset, pose, tint?)`: the mesh of `meshForAsset(poseAsset(…))` without building posed instances.
+- Preview playback: a bounded cache of rendered looping frames (`frameCacheBytes`) and automatic suspension off-screen or in hidden documents (`pauseWhenHidden`, `suspended`).
+- Documentation gallery: 100 original assets across ten categories, each with a live page (orbit, accent color, parameters, motion clips and editable JSON with diagnostics), deterministic thumbnails and category, feature and text filters. `tools/check-gallery.mjs` validates gallery entries; `tools/render-asset.mjs` renders review sheets.
+- Preregistered schema 0.3 LLM qualification (`benchmarks/protocol-0.3.json`): relational 0.3 authoring 72.1% correct on the first try against 60.8% for an expanded form of the same schema (+11.3 points, paired 95% interval 3.8 to 19.2), 83.8% after one bounded repair, with 0.74× the tokens. The advantage comes from two of three model families.
+
+### Changed
+
+- The CPU rasterizer is about 3.5–4× faster with byte-identical output.
+- Motion joint references and the motion-set 0.1 structural schema accept array copy indices (`roller/3`); every previously valid motion set is unchanged.
+- The schema generator rewrites a schema file only when its content changes.
+- Validators no longer coerce enumerated fields. A non-string `units`, shape or placement `type`, radial `axis`, slot option, clip `interpolation`, `symmetry` or `solve`, or grounding `type` is now a diagnostic. Previously `["meters"]` was accepted, and a value such as `{"toString":null}` threw instead of producing a diagnostic.
+
+### Fixed
+
+- Compiled coils thinner than about 2% of their radius were partly wound inward; they now face outward. Every other coil is byte-identical, and the raw `MeshBuilder.coil` from `/compat` keeps its historical output.
+
+### Compatibility
+
+Schema 0.1 and 0.2 descriptions compile to the same meshes, bakes and hashes as in 0.2.0, except the thin coils above, which were partly inside out; 0.3 fields fail as unknown in older schemas.
+
+## 0.2.0 — 2026-11-03
+
+Characters: schema `asset-assembly/0.2` (joints, mirrored sides, slots, identities, states and limbs), `motion-set/0.1` (poses, expressions, clips, contacts, grounding, travel and the planted-foot solve), `bakeClip`, preview playback and `fromLegacyRig`. Passed the preregistered character qualification with narrow margins.
+
+## 0.1.0 — 2026-11-02
+
+Schema `asset-assembly/0.1`: declarative static assemblies with named parts, anchors, attachments and corner repetition; deterministic compilation, structured diagnostics, CPU bakes, browser previews and the compatibility builder. Passed the preregistered static-asset qualification.

package/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) 2026 Victor Queiroz. All rights reserved.
+Private software. No license to redistribute is granted.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# Ludic Assembly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic declarative low-poly assets: TypeScript/JSON specifications, named parts and anchors, material layers, CPU bakes and live browser previews.
+
+**Continuing the research in a new session? Start with [the research handoff](docs/research/README.md).** It records the preferred C source, achievements, open gates, review packet and bounded next-session deliverables. The stable library and the private experiments have separate status.
+
+- Private repository: https://github.com/VictorQueiroz/ludic-assembly
+- Live documentation: https://libraries.ludic-assembly.victorqueiroz.dev/ (one-step start and gallery), with [the guide](https://libraries.ludic-assembly.victorqueiroz.dev/guide/) and, for LLMs and coding agents, [llms.txt](https://libraries.ludic-assembly.victorqueiroz.dev/llms.txt) and [llms-full.txt](https://libraries.ludic-assembly.victorqueiroz.dev/llms-full.txt)
+- Package: `@ludic-labs/assembly`, published publicly on [npm](https://www.npmjs.com/package/@ludic-labs/assembly).
+- [API and installation](docs/api.md)
+- [SVG Asset Notation 0.1](docs/svg/README.md): a separate research-informed 2D construction language, with characters, interiors, effects, animation, schema, exports and a local authoring gallery. Initial version; owner visual acceptance is separate.
+- [Research library](docs/research/papers.md), [proposed 3D and SVG editing direction](docs/research/editable-assets-proposal.md), and [visual references for owner rating](docs/research/visual-review.md).
+- [Camera-independent fox animation and derived SVG views](docs/research/camera-independent-fox-proposal.md), with a private compiler-backed turntable and idle experiment, capability audit and remaining gait plan.
+- [Organic fox surface experiment](experiments/fox-organic/README.md), testing richer anatomy and layered fur after the primitive fox fell short of the visual target.
+- [Drawing construction, proportions and gaze](docs/research/construction-and-gaze-proposal.md), with primary literature, an executed facial landmark audit and a general-purpose construction proposal.
+- [Head calibration pilot](experiments/fox-head-calibration/README.md), implementing private construction graphs, bounded eye geometry, gaze/proportion boards and non-fox fixtures for visual review.
+- [Guided surface-covering pilot](experiments/surface-covering-study/README.md), comparing beard treatments with reusable surface guides, a foliage fixture, SVG measurements and unreviewed full-fox motion previews.
+- [C vector/motion outcomes](experiments/fox-vector-motion/README.md) and [bounded batch / Vast.ai execution plan](docs/research/batch-rendering-and-vast-proposal.md), documenting visibility fixes, export tradeoffs, resource measurements and planned remote execution.
+- [Qualified repair protocol](benchmarks/protocol-repair.json) and [initial unassisted protocol](benchmarks/protocol.json); [character protocol](benchmarks/protocol-character.json); [schema 0.3 protocol](benchmarks/protocol-0.3.json)
+- [Gallery authoring guide](examples/gallery/AUTHORING.md): the contract, conventions and quality bar for the documentation assets.
+- [Schema roadmap from gallery authoring](docs/roadmap.md): limitations reported by the gallery authors, what 0.3 changed and candidate work.
+
+Schema 0.1 is the static assembly contract; schema 0.2 and motion-set 0.1 add characters in version 0.2.0; schema 0.3 adds rotations, line/grid/radial arrays, spheres, cones, wedges, lathes, extrusions, continuous and per-instance joints in version 0.3.0; version 0.4.0 adds the `pixel-sprite/0.1` notation (`/sprite`), the initial `svg-asset/0.1` notation (`/svg`) and the experimental `/pixel` and `/export` entry points ([changelog](CHANGELOG.md)). [Qualification](qualification/report.json) records implementation checks, model-comparison results and earlier failed attempts. Results cover the published corpus and model aliases; visual acceptance is recorded separately.
+
+```sh
+npm ci
+npm run lint
+npm run typecheck
+npm test
+npm run build:docs
+npm run test:browser
+node tools/check-gallery.mjs            # gallery contract checks
+```
+
+The documentation uses React 19, TypeScript 7 and Vite. After the first documentation build, `npm run dev`
+serves the same pre-rendered routes with Vite hot updates. Every page has its own canonical metadata and
+social image; gallery thumbnails come from a deterministic antialiased render of that asset. Every page
+also has a Markdown twin for LLMs and agents, indexed by `/llms.txt`. See
+[the documentation architecture and development checks](docs/documentation.md).
+
+Schema 0.3 passed its preregistered LLM qualification: relational authoring is 72.1% correct on the first try against 60.8% for an expanded form of the same schema with absolute coordinates (+11.3 points, paired 95% interval 3.8 to 19.2), 83.8% after one bounded repair, with 0.74× the tokens. The advantage comes from two of three model families; the third was perfect with the expanded form, and its relational failures were all one stray closing delimiter. See [the report](qualification/benchmarks/schema-v3-qualification-v1.json).
+
+Characters (`asset-assembly/0.2`, `motion-set/0.1`) add joints, mirrored sides, identities with swappable face parts, face states and expressions, verified motion clips and a planted-foot solve, with a six-step live guide in the documentation. They passed the preregistered character qualification with narrow margins; owner visual acceptance is pending. See the [API section](docs/api.md#characters-identities-and-motion-schema-02) and the [design record](docs/research/character-proposal.md).
+
+Core has no runtime dependencies on host applications, React, Node or the DOM. Optional `/browser`, `/bake` and `/compat` entry points isolate integration concerns; the experimental `/export` entry point writes deterministic static GLB files and transparent scene images. The experimental `/pixel` entry point renders the same compiled assets, or scenes composed from them, as fixed-density pixel art with derived palettes, outlines and surface patterns that need no texture coordinates; see the [API section](docs/api.md#pixel-art-experimental). The `/sprite` entry point is a notation for pixel art that language models write and edit (`pixel-sprite/0.1`): exact pixels with named parts, drawn per view on a layout guide projected from a 3D asset, and composed into scenes with one grid, one palette and picking; see the [notation guide](docs/sprite.md) and the [API section](docs/api.md#pixel-sprites-sprite). Fixed production assets may be compiled offline; interactive examples compile in the browser without any model or network request.
+
+The documentation gallery contains 108 original assets written in the asset language (`examples/gallery/`), each with its own live page, and six owner-authorized exported production meshes, each with an individual live preview. Every live example exports its source JSON (where it has one), a GLB of the shown mesh and a PNG of the current view. Source provenance is retained in the private research archive. Consumers build from this repository alone.
+
+Copyright © 2026 Victor Queiroz. All rights reserved.
+
+The [playable city](https://libraries.ludic-assembly.victorqueiroz.dev/city/) combines 46 gallery asset types in an experimental WebGL 1.0 / C++23 WebAssembly game. See [build requirements, controls and measurement limits](demos/city/README.md). Documentation builds require CMake, Ninja, Clang with WebAssembly support and wasm-ld.

package/dist/bake.d.ts

@@ -0,0 +1,80 @@
+import type { CompiledAsset, CompiledClip, MeshData, Vec3 } from "./types.js";
+export declare const BAKE_VERSION = 1;
+export declare const BAKE_PPU = 128;
+export interface CameraBasis {
+    back: Vec3;
+    right: Vec3;
+    up: Vec3;
+}
+export declare const fixedBasis: CameraBasis;
+export interface BakedFrame {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    depthMin: number;
+    depthMax: number;
+    color: Uint8Array;
+    depth: Uint8Array;
+}
+/** Integer projected-pixel bounds: +X is right and +Y is up, before canvas translation. */
+export interface BakeViewport {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Deterministic orthographic triangle rasterizer shared by bakes and browser previews. */
+export declare function bakeMesh(mesh: MeshData, ppu?: number, samples?: number, basis?: CameraBasis, viewport?: BakeViewport | null): BakedFrame;
+export declare function sampleDepth(frame: BakedFrame, x: number, y: number): number;
+export declare function bakeAsset(asset: CompiledAsset, camera?: {
+    basis?: CameraBasis;
+    ppu?: number;
+    samples?: number;
+    tint?: string;
+}): {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    depthMin: number;
+    depthMax: number;
+    color: Uint8Array;
+    depth: Uint8Array;
+    sourceHash: string;
+    bakeVersion: number;
+    units: "meters" | "tiles";
+};
+/**
+ * Bake every frame of a compiled clip at an integer frame rate. Looping clips yield
+ * round(duration × fps) frames (the closing frame repeats the first and is omitted); others add the end
+ * frame. Each frame keeps its projected `left`/`top`, so frames align when composited into a strip.
+ * Root travel is reported per frame and never baked into the image.
+ */
+export declare function bakeClip(asset: CompiledAsset, clip: CompiledClip, options?: {
+    fps?: number;
+    basis?: CameraBasis;
+    ppu?: number;
+    samples?: number;
+    tint?: string;
+    face?: CompiledClip;
+}): {
+    clip: string;
+    fps: number;
+    frames: {
+        width: number;
+        height: number;
+        left: number;
+        top: number;
+        depthMin: number;
+        depthMax: number;
+        color: Uint8Array;
+        depth: Uint8Array;
+        frame: number;
+        phase: number;
+        travel: Vec3;
+    }[];
+    sourceHash: string;
+    bakeVersion: number;
+    units: "meters" | "tiles";
+};

package/dist/bake.js

@@ -0,0 +1,214 @@
+import { requireValue } from "./required.js";
+import { dot, normalize, cross } from "./math.js";
+import { meshForAsset } from "./mesh.js";
+import { posedMesh, samplePose } from "./motion.js";
+export const BAKE_VERSION = 1;
+export const BAKE_PPU = 128;
+export const fixedBasis = (() => {
+    // Preserve the original camera arithmetic for byte-identical legacy bakes.
+    const yaw = Math.atan2(24, -26), pitch = Math.atan2(28, Math.hypot(24, 26)), radius = Math.hypot(24, 28, 26);
+    const back = normalize([
+        14 + Math.sin(yaw) * Math.cos(pitch) * radius - 14,
+        Math.sin(pitch) * radius,
+        10 + Math.cos(yaw) * Math.cos(pitch) * radius - 10,
+    ]);
+    const right = normalize(cross([0, 1, 0], back));
+    return { back, right, up: cross(back, right) };
+})();
+/** Matches the native device's unshadowed material lighting and colour transform. */
+const sunDirection = normalize([-35, 60, -35]);
+const ambientLow = [0.36, 0.43, 0.39];
+const ambientHigh = [0.94, 0.96, 0.86];
+const sunColor = [1.35, 1.22, 1.04];
+function shade(mesh, at, output) {
+    const normal = mesh.normals, sun = Math.max(0, requireValue(normal[at]) * sunDirection[0] +
+        requireValue(normal[at + 1]) * sunDirection[1] +
+        requireValue(normal[at + 2]) * sunDirection[2]);
+    for (let c = 0; c < 3; c++) {
+        const t = requireValue(normal[at + 1]) * 0.5 + 0.5;
+        const ambient = requireValue(ambientLow[c]) * (1 - t) + requireValue(ambientHigh[c]) * t;
+        const lit = requireValue(mesh.colors[at + c]) * (ambient + sun * requireValue(sunColor[c]));
+        output[at + c] = Math.round(255 *
+            Math.max(0, Math.min(1, (lit * (2.51 * lit + 0.03)) / (lit * (2.43 * lit + 0.59) + 0.14))) **
+                (1 / 2.2));
+    }
+}
+/** Deterministic orthographic triangle rasterizer shared by bakes and browser previews. */
+export function bakeMesh(mesh, ppu = BAKE_PPU, samples = 2, basis = fixedBasis, viewport = null) {
+    if (!mesh.positions.length || mesh.positions.some((v) => !Number.isFinite(v)))
+        throw new RangeError("Bake requires finite nonempty geometry");
+    if (!Number.isFinite(ppu) || ppu <= 0 || !Number.isInteger(samples) || samples < 1 || samples > 4)
+        throw new RangeError("Invalid bake resolution");
+    if (viewport &&
+        (viewport.width < 1 ||
+            viewport.height < 1 ||
+            ![
+                viewport.left,
+                viewport.top,
+                viewport.width,
+                viewport.height,
+                viewport.left + viewport.width,
+                viewport.top - viewport.height,
+            ].every(Number.isSafeInteger)))
+        throw new RangeError("Bake viewport requires safe integer bounds and positive dimensions");
+    const axes = [basis.right, basis.up, basis.back];
+    if (axes.some((v) => v.length !== 3 || v.some((n) => !Number.isFinite(n)) || Math.abs(Math.hypot(...v) - 1) > 1e-6) ||
+        Math.abs(dot(basis.right, basis.up)) > 1e-6 ||
+        Math.abs(dot(basis.right, basis.back)) > 1e-6 ||
+        Math.abs(dot(basis.up, basis.back)) > 1e-6)
+        throw new RangeError("Bake camera basis must be finite and orthonormal");
+    if (mesh.positions.length % 3 ||
+        mesh.normals.length !== mesh.positions.length ||
+        mesh.colors.length !== mesh.positions.length ||
+        mesh.indices.length % 3 ||
+        mesh.indices.some((i) => !Number.isInteger(i) || i < 0 || i >= mesh.positions.length / 3))
+        throw new RangeError("Invalid bake mesh attributes or indices");
+    // Keep projections and screen coordinates in doubles. Float32 changes coverage/depth bytes.
+    const vertices = new Float64Array(mesh.positions.length);
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    for (let n = 0; n < mesh.positions.length; n += 3) {
+        const x = requireValue(mesh.positions[n]), y = requireValue(mesh.positions[n + 1]), z = requireValue(mesh.positions[n + 2]);
+        vertices[n] = x * basis.right[0] + y * basis.right[1] + z * basis.right[2];
+        vertices[n + 1] = x * basis.up[0] + y * basis.up[1] + z * basis.up[2];
+        vertices[n + 2] = x * basis.back[0] + y * basis.back[1] + z * basis.back[2];
+        for (let axis = 0; axis < 3; axis++) {
+            min[axis] = Math.min(requireValue(min[axis]), requireValue(vertices[n + axis]));
+            max[axis] = Math.max(requireValue(max[axis]), requireValue(vertices[n + axis]));
+        }
+    }
+    const left = Math.floor(min[0] * ppu - 3) / ppu;
+    const right = Math.ceil(max[0] * ppu + 3) / ppu;
+    const bottom = Math.floor(min[1] * ppu - 3) / ppu;
+    const top = Math.ceil(max[1] * ppu + 3) / ppu;
+    const fullWidth = Math.round((right - left) * ppu), fullHeight = Math.round((top - bottom) * ppu), pixelLeft = Math.round(left * ppu), pixelTop = Math.round(top * ppu), startX = viewport ? Math.max(0, viewport.left - pixelLeft) : 0, startY = viewport ? Math.max(0, pixelTop - viewport.top) : 0, endX = viewport ? Math.min(fullWidth, viewport.left + viewport.width - pixelLeft) : fullWidth, endY = viewport ? Math.min(fullHeight, pixelTop - viewport.top + viewport.height) : fullHeight, width = Math.max(0, endX - startX), height = Math.max(0, endY - startY), outputLeft = viewport ? left + startX / ppu : left, outputTop = viewport ? top - startY / ppu : top;
+    const depthMin = min[2] - 0.001, depthMax = max[2] + 0.001;
+    if (!width || !height)
+        return {
+            width: 0,
+            height: 0,
+            left: outputLeft,
+            top: outputTop,
+            depthMin,
+            depthMax,
+            color: new Uint8Array(0),
+            depth: new Uint8Array(0),
+        };
+    if (width * height * samples * samples > 16_777_216)
+        throw new RangeError("Bake pixel budget exceeded");
+    const sw = width * samples, sh = height * samples, sampleX = startX * samples, sampleY = startY * samples, zbuf = new Float64Array(sw * sh).fill(-Infinity), rgb = new Uint8Array(sw * sh * 3);
+    for (let n = 0; n < vertices.length; n += 3) {
+        vertices[n] = (requireValue(vertices[n]) - left) * ppu * samples;
+        vertices[n + 1] = (top - requireValue(vertices[n + 1])) * ppu * samples;
+    }
+    const shaded = new Uint8Array(mesh.positions.length), hasShade = new Uint8Array(mesh.positions.length / 3);
+    for (let n = 0; n < mesh.indices.length; n += 3) {
+        const id = requireValue(mesh.indices[n]), ai = id * 3, normal = mesh.normals;
+        if (requireValue(normal[ai]) * basis.back[0] +
+            requireValue(normal[ai + 1]) * basis.back[1] +
+            requireValue(normal[ai + 2]) * basis.back[2] <=
+            0)
+            continue;
+        const bi = requireValue(mesh.indices[n + 1]) * 3, ci = requireValue(mesh.indices[n + 2]) * 3, ax = requireValue(vertices[ai]), ay = requireValue(vertices[ai + 1]), az = requireValue(vertices[ai + 2]), bx = requireValue(vertices[bi]), by = requireValue(vertices[bi + 1]), bz = requireValue(vertices[bi + 2]), cx = requireValue(vertices[ci]), cy = requireValue(vertices[ci + 1]), cz = requireValue(vertices[ci + 2]);
+        const area = (cx - ax) * (by - ay) - (cy - ay) * (bx - ax);
+        if (Math.abs(area) < 1e-10)
+            continue;
+        if (!hasShade[id]) {
+            shade(mesh, ai, shaded);
+            hasShade[id] = 1;
+        }
+        const red = requireValue(shaded[ai]), green = requireValue(shaded[ai + 1]), blue = requireValue(shaded[ai + 2]), firstY = Math.max(sampleY, Math.floor(Math.min(ay, by, cy))), lastY = Math.min(sampleY + sh, Math.ceil(Math.max(ay, by, cy))), firstX = Math.max(sampleX, Math.floor(Math.min(ax, bx, cx))), lastX = Math.min(sampleX + sw, Math.ceil(Math.max(ax, bx, cx))), cbY = cy - by, cbX = cx - bx, acY = ay - cy, acX = ax - cx;
+        for (let y = firstY; y < lastY; y++) {
+            const sampleCenterY = y + 0.5, uY = (sampleCenterY - by) * cbX, vY = (sampleCenterY - cy) * acX, row = (y - sampleY) * sw;
+            for (let x = firstX; x < lastX; x++) {
+                // Do not increment edges or multiply by reciprocal area: rounding is observable.
+                const u = ((x + 0.5 - bx) * cbY - uY) / area, v = ((x + 0.5 - cx) * acY - vY) / area, w = 1 - u - v;
+                if (u < -1e-9 || v < -1e-9 || w < -1e-9)
+                    continue;
+                const d = u * az + v * bz + w * cz, at = x - sampleX + row;
+                if (d > requireValue(zbuf[at])) {
+                    zbuf[at] = d;
+                    rgb[at * 3] = red;
+                    rgb[at * 3 + 1] = green;
+                    rgb[at * 3 + 2] = blue;
+                }
+            }
+        }
+    }
+    const color = new Uint8Array(width * height * 4), depth = new Uint8Array(color.length);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            let coverage = 0, d = -Infinity;
+            let red = 0, green = 0, blue = 0;
+            for (let sy = 0; sy < samples; sy++)
+                for (let sx = 0; sx < samples; sx++) {
+                    const at = x * samples + sx + (y * samples + sy) * sw;
+                    if (!Number.isFinite(zbuf[at]))
+                        continue;
+                    coverage++;
+                    d = Math.max(d, requireValue(zbuf[at]));
+                    red += requireValue(rgb[at * 3]);
+                    green += requireValue(rgb[at * 3 + 1]);
+                    blue += requireValue(rgb[at * 3 + 2]);
+                }
+            if (!coverage)
+                continue;
+            const o = (x + y * width) * 4, q = Math.round(((d - depthMin) / (depthMax - depthMin)) * 65535);
+            color[o] = Math.round(red / coverage);
+            color[o + 1] = Math.round(green / coverage);
+            color[o + 2] = Math.round(blue / coverage);
+            color[o + 3] = Math.round((255 * coverage) / (samples * samples));
+            depth[o] = q >> 8;
+            depth[o + 1] = q & 255;
+            depth[o + 2] = 0;
+            depth[o + 3] = 255;
+        }
+    return { width, height, left: outputLeft, top: outputTop, depthMin, depthMax, color, depth };
+}
+export function sampleDepth(frame, x, y) {
+    const o = (x + y * frame.width) * 4;
+    return (frame.depthMin +
+        ((requireValue(frame.depth[o]) * 256 + requireValue(frame.depth[o + 1])) / 65535) *
+            (frame.depthMax - frame.depthMin));
+}
+export function bakeAsset(asset, camera = {}) {
+    return {
+        ...bakeMesh(meshForAsset(asset, camera.tint), camera.ppu ?? BAKE_PPU, camera.samples ?? 2, camera.basis ?? fixedBasis),
+        sourceHash: asset.sourceHash,
+        bakeVersion: BAKE_VERSION,
+        units: asset.units,
+    };
+}
+/**
+ * Bake every frame of a compiled clip at an integer frame rate. Looping clips yield
+ * round(duration × fps) frames (the closing frame repeats the first and is omitted); others add the end
+ * frame. Each frame keeps its projected `left`/`top`, so frames align when composited into a strip.
+ * Root travel is reported per frame and never baked into the image.
+ */
+export function bakeClip(asset, clip, options = {}) {
+    const fps = options.fps ?? 12;
+    if (!Number.isInteger(fps) || fps < 1 || fps > 120)
+        throw new RangeError("Bake fps must be an integer 1–120");
+    const span = Math.max(1, Math.round(clip.duration * fps)), count = clip.loop ? span : span + 1;
+    if (count > 600)
+        throw new RangeError("Clip bake exceeds 600 frames");
+    const frames = [];
+    for (let frame = 0; frame < count; frame++) {
+        const pose = samplePose(asset, clip, clip.loop ? { frame, fps } : { phase: frame / span }, {
+            face: options.face,
+        });
+        frames.push({
+            ...bakeMesh(posedMesh(asset, pose, options.tint), options.ppu ?? BAKE_PPU, options.samples ?? 2, options.basis ?? fixedBasis),
+            frame,
+            phase: pose.phase,
+            travel: pose.travel,
+        });
+    }
+    return {
+        clip: clip.name,
+        fps,
+        frames,
+        sourceHash: asset.sourceHash,
+        bakeVersion: BAKE_VERSION,
+        units: asset.units,
+    };
+}

package/dist/browser.d.ts

@@ -0,0 +1,89 @@
+import type { Bounds, CompiledAsset, CompiledClip, MeshData, SampledPose, Vec3 } from "./types.js";
+import { meshForAsset } from "./mesh.js";
+export declare const assetMesh: typeof meshForAsset;
+export interface PreviewOptions {
+    size?: number;
+    yaw?: number;
+    pitch?: number;
+    maxTriangles?: number;
+    /** Rendered looping frames retained per preview, in bytes. Zero disables caching. */
+    frameCacheBytes?: number;
+    /** Suspend automatic playback outside the viewport or in a hidden document (default true). */
+    pauseWhenHidden?: boolean;
+    onPick?: (instanceId: string | null) => void;
+    /** Playback: called after each rendered clip frame. */
+    onFrame?: (frame: number, pose: SampledPose) => void;
+}
+/** Static assets drawn with a playing clip, e.g. the furniture a character sits on. */
+export interface PreviewProp {
+    asset: CompiledAsset;
+    tint?: string;
+    offset?: Vec3;
+}
+export interface PlayOptions {
+    tint?: string;
+    /** Integer sampling rate; frames are sampled at frame / fps seconds. */
+    fps?: number;
+    /** Translation applied to the posed asset, e.g. a seat anchor from seatOn. */
+    offset?: Vec3;
+    props?: PreviewProp[];
+    /** Start paused on the first frame when false. Respect prefers-reduced-motion in the host page. */
+    autoplay?: boolean;
+    /** A face-only clip or expression overlaid on the body clip (see samplePose). */
+    face?: CompiledClip;
+    /** World bounds to frame instead of the clip's sampled bounds, e.g. a close-up of the head. */
+    fit?: Bounds;
+}
+/** What a preview draws: the shown asset (posed during playback), then its props. */
+export interface PreviewSnapshot {
+    /** Empty when nothing is loaded or a raw mesh was set with setMesh. */
+    scene: PreviewProp[];
+    camera: {
+        yaw: number;
+        pitch: number;
+    };
+    /** Bounds the playing clip is framed to: its explicit `fit`, or the union of its sampled bounds. */
+    fit?: Bounds;
+    /** Playing or paused clip and its integer frame. */
+    clip?: string;
+    frame?: number;
+}
+/**
+ * A CPU preview with optional scheduled clip playback. Call dispose when removed.
+ *
+ * Dragging grabs the model: it turns with the pointer horizontally and tilts vertically. When the
+ * canvas has focus, arrow keys orbit the same way (Shift for finer steps) and Home restores the
+ * initial view.
+ */
+export declare function createPreview(canvas: HTMLCanvasElement, options?: PreviewOptions): {
+    setAsset(value: CompiledAsset, shownTint?: string): void;
+    setMesh(value: MeshData): void;
+    /** Recolor the current asset without restarting its pose, framing or playback clock. */
+    setTint(value?: string | null): void;
+    setCamera(value: {
+        yaw: number;
+        pitch?: number;
+    }): void;
+    /** The current camera, including any orbit from dragging or the keyboard. */
+    readonly camera: {
+        yaw: number;
+        pitch: number;
+    };
+    pick: (x: number, y: number) => string | null;
+    /** The current frame's scene and camera, e.g. for `exportGLB` or `bakeScene` from `/export`. */
+    snapshot(): PreviewSnapshot;
+    /**
+     * Play a compiled clip of a rigged asset. Framing is fixed to the union of sampled
+     * bounds, travel is not applied (the clip plays in place), and frames are scheduled only while playing.
+     */
+    play(source: CompiledAsset, clip: CompiledClip, play?: PlayOptions): void;
+    pause(): void;
+    resume(): void;
+    /** Show one integer frame of the playing clip; playback continues from it if it was running. */
+    seek(n: number): void;
+    readonly playing: boolean;
+    readonly suspended: boolean;
+    readonly frame: number | undefined;
+    dispose(): void;
+    readonly disposed: boolean;
+};