@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/required.d.ts

@@ -0,0 +1,2 @@
+/** Narrow a language/API lookup at the point where its presence is an invariant. */
+export declare function requireValue<T>(value: T, message?: string): NonNullable<T>;

package/dist/required.js

@@ -0,0 +1,6 @@
+/** Narrow a language/API lookup at the point where its presence is an invariant. */
+export function requireValue(value, message = "Required value is missing") {
+    if (value === null || value === undefined)
+        throw new Error(message);
+    return value;
+}

package/dist/shapes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Schema 0.3 primitives. The legacy MeshBuilder primitives keep their historical output; these
+ * generators add sided round shapes, spheres, cones, wedges, lathes and extrusions. Every polygon
+ * is emitted through MeshBuilder.face, which owns flat normals and outward winding.
+ */
+import type { MeshData, Transform, Vec3 } from "./types.js";
+import { MeshBuilder } from "./compat.js";
+import { dot } from "./math.js";
+export declare const DEFAULT_SIDES = 16;
+export declare const DEFAULT_SPHERE_SIDES = 12;
+export declare const MIN_SIDES = 3;
+export declare const MAX_SIDES = 32;
+export declare function frustum(m: MeshBuilder, sides: number, bottom: number, top: number, height: number, color: number): void;
+export declare function cone(m: MeshBuilder, sides: number, radius: number, height: number, color: number): void;
+/** Bottom-centered ellipsoid spanning width × height × depth, with `sides` meridians. */
+export declare function ellipsoid(m: MeshBuilder, sides: number, w: number, h: number, d: number, color: number): void;
+/**
+ * Right triangular prism. The bottom (y = 0) and back (z = +depth/2) faces are full rectangles; the
+ * slope rises from the front-bottom edge to the back-top edge.
+ */
+export declare function wedge(m: MeshBuilder, w: number, h: number, d: number, color: number): void;
+/**
+ * A lathe profile oriented so the material lies to the left of its direction (counterclockwise in the
+ * radius–height plane once the open ends are joined along the axis). `closed` profiles repeat their
+ * first point at the end and have no caps.
+ */
+export declare function orientProfile(profile: [number, number][]): {
+    points: [number, number][];
+    closed: boolean;
+};
+/**
+ * True when two non-adjacent profile segments touch or cross, or two segments that share a point
+ * (consecutive ones, and the closing pair of a ring) fold back over each other.
+ */
+export declare function profileSelfIntersects(profile: [number, number][], closed: boolean): boolean;
+/**
+ * Surface of revolution about +Y from a profile of [radius, y] points. The profile may rise and fall
+ * (bowls, cups, rims); it is oriented so its material lies to the left. An open end away from the axis
+ * is capped when the material lies toward the axis there; a closed profile (first point repeated last)
+ * is a ring with no caps.
+ */
+export declare function lathe(m: MeshBuilder, sides: number, input: [number, number][], color: number): void;
+/** Signed area in the X-Z plane (positive when the outline turns from +X toward +Z). */
+export declare const outlineArea: (outline: [number, number][]) => number;
+/** True when two non-adjacent outline edges touch or cross, or a vertex repeats. */
+export declare function outlineSelfIntersects(outline: [number, number][]): boolean;
+/** Prism from a simple X-Z outline, from y = 0 to y = height. */
+export declare function extrude(m: MeshBuilder, input: [number, number][], height: number, color: number): void;
+/**
+ * Ring in the local Y-Z plane (axis along X) with `sides` segments around the ring and six around its
+ * cross-section. Sixteen sides reproduce the legacy coil exactly; the compiler uses the legacy builder then.
+ */
+export declare function coil(m: MeshBuilder, sides: number, radius: number, thickness: number, color: number): void;
+/**
+ * The 16-sided coil with the legacy builder's exact vertex arithmetic. Only the interior reference that
+ * orients each face differs (the centerline chord midpoint), so coils the legacy builder wound correctly
+ * are byte-identical, and coils thinner than about 2% of their radius are no longer partly inside out.
+ * The raw compatibility builder keeps its historical output.
+ */
+export declare function legacyCoil(m: MeshBuilder, radius: number, thickness: number, color: number): void;
+/** Orient a +Y-aligned local mesh along a → b with the legacy tube/beam frame. */
+export declare function alongSegment(part: MeshData, a: Vec3, b: Vec3, target: MeshBuilder): void;
+/** cos/sin of degrees: exact at multiples of 90°, correctly rounded constants at multiples of 30° and 45°. */
+export declare function cosSin(degrees: number): [number, number];
+export declare function axisRotation(axis: "x" | "y" | "z", degrees: number): Transform;
+/** Extrinsic X, then Y, then Z rotation about the local origin: R = Rz · Ry · Rx. */
+export declare function eulerRotation(x: number, y: number, z: number): Transform;
+export declare const isIdentity: (m: Transform) => boolean;
+/** Apply a rotation (and translation) to mesh positions and normals in place. */
+export declare function transformMesh(mesh: MeshData, m: Transform): MeshData;
+export { dot };

package/dist/shapes.js

@@ -0,0 +1,396 @@
+import { requireValue } from "./required.js";
+import { MeshBuilder } from "./compat.js";
+import { add, applyPoint, applyVector, compose, cross, dot, normalize, scale, sub } from "./math.js";
+export const DEFAULT_SIDES = 16;
+export const DEFAULT_SPHERE_SIDES = 12;
+export const MIN_SIDES = 3;
+export const MAX_SIDES = 32;
+/** Angle n of a regular polygon. For 16 sides this equals the legacy n·π/8 exactly. */
+const angle = (n, sides) => (n * 2 * Math.PI) / sides;
+const ring = (sides, radius, y) => {
+    const points = [];
+    for (let n = 0; n < sides; n++) {
+        const a = angle(n, sides);
+        points.push([Math.cos(a) * radius, y, Math.sin(a) * radius]);
+    }
+    return points;
+};
+/** A point just inside a planar face whose outward normal is `outward`. */
+const inside = (points, outward) => {
+    let c = [0, 0, 0];
+    for (const p of points)
+        c = add(c, p);
+    return sub(scale(c, 1 / points.length), outward);
+};
+export function frustum(m, sides, bottom, top, height, color) {
+    const center = [0, height / 2, 0], a = ring(sides, bottom, 0), b = ring(sides, top, height);
+    m.face(a, color, center);
+    m.face(b, color, center);
+    for (let n = 0; n < sides; n++)
+        m.face([
+            requireValue(a[n]),
+            requireValue(a[(n + 1) % sides]),
+            requireValue(b[(n + 1) % sides]),
+            requireValue(b[n]),
+        ], color, center);
+}
+export function cone(m, sides, radius, height, color) {
+    const base = ring(sides, radius, 0), apex = [0, height, 0], center = [0, height / 4, 0];
+    m.face(base, color, center);
+    for (let n = 0; n < sides; n++)
+        m.face([requireValue(base[n]), requireValue(base[(n + 1) % sides]), apex], color, center);
+}
+/** Bottom-centered ellipsoid spanning width × height × depth, with `sides` meridians. */
+export function ellipsoid(m, sides, w, h, d, color) {
+    const rings = Math.max(2, Math.floor(sides / 2)), center = [0, h / 2, 0];
+    const at = (k, n) => {
+        const phi = (k * Math.PI) / rings, a = angle(n, sides), r = Math.sin(phi);
+        return [Math.cos(a) * r * (w / 2), (1 - Math.cos(phi)) * (h / 2), Math.sin(a) * r * (d / 2)];
+    };
+    for (let k = 0; k < rings; k++)
+        for (let n = 0; n < sides; n++) {
+            const next = (n + 1) % sides;
+            if (k === 0)
+                m.face([[0, 0, 0], at(1, next), at(1, n)], color, center);
+            else if (k === rings - 1)
+                m.face([at(k, n), at(k, next), [0, h, 0]], color, center);
+            else
+                m.face([at(k, n), at(k, next), at(k + 1, next), at(k + 1, n)], color, center);
+        }
+}
+/**
+ * Right triangular prism. The bottom (y = 0) and back (z = +depth/2) faces are full rectangles; the
+ * slope rises from the front-bottom edge to the back-top edge.
+ */
+export function wedge(m, w, h, d, color) {
+    const x = w / 2, z = d / 2, center = [0, h / 3, z / 3];
+    const fl = [-x, 0, -z], fr = [x, 0, -z], bl = [-x, 0, z], br = [x, 0, z], tl = [-x, h, z], tr = [x, h, z];
+    m.face([fl, fr, br, bl], color, center);
+    m.face([bl, br, tr, tl], color, center);
+    m.face([fl, tl, tr, fr], color, center);
+    m.face([fl, bl, tl], color, center);
+    m.face([fr, tr, br], color, center);
+}
+/**
+ * A lathe profile oriented so the material lies to the left of its direction (counterclockwise in the
+ * radius–height plane once the open ends are joined along the axis). `closed` profiles repeat their
+ * first point at the end and have no caps.
+ */
+export function orientProfile(profile) {
+    const n = profile.length, closed = n >= 4 &&
+        requireValue(profile[0])[0] === requireValue(profile[n - 1])[0] &&
+        requireValue(profile[0])[1] === requireValue(profile[n - 1])[1];
+    const loop = closed
+        ? profile.slice(0, -1)
+        : [...profile, [0, requireValue(profile[n - 1])[1]], [0, requireValue(profile[0])[1]]];
+    let area = 0;
+    for (let i = 0; i < loop.length; i++) {
+        const [r0, y0] = requireValue(loop[i]), [r1, y1] = requireValue(loop[(i + 1) % loop.length]);
+        area += r0 * y1 - r1 * y0;
+    }
+    return { points: area < 0 ? [...profile].reverse() : profile, closed };
+}
+/**
+ * True when two non-adjacent profile segments touch or cross, or two segments that share a point
+ * (consecutive ones, and the closing pair of a ring) fold back over each other.
+ */
+export function profileSelfIntersects(profile, closed) {
+    const segments = profile.length - 1;
+    // p → shared → q retraces itself when the three points are collinear and p, q lie on the same side.
+    const foldsBack = (p, shared, q) => Math.abs(cross2(shared, p, q)) < 1e-12 &&
+        (p[0] - shared[0]) * (q[0] - shared[0]) + (p[1] - shared[1]) * (q[1] - shared[1]) > 0;
+    for (let i = 0; i + 1 < segments; i++)
+        if (foldsBack(requireValue(profile[i]), requireValue(profile[i + 1]), requireValue(profile[i + 2])))
+            return true;
+    if (closed &&
+        segments >= 2 &&
+        foldsBack(requireValue(profile[segments - 1]), requireValue(profile[0]), requireValue(profile[1])))
+        return true;
+    for (let i = 0; i < segments; i++)
+        for (let j = i + 2; j < segments; j++) {
+            if (closed && i === 0 && j === segments - 1)
+                continue;
+            if (segmentsTouch(requireValue(profile[i]), requireValue(profile[i + 1]), requireValue(profile[j]), requireValue(profile[j + 1])))
+                return true;
+        }
+    return false;
+}
+function segmentsTouch(a, b, c, d) {
+    const d1 = cross2(c, d, a), d2 = cross2(c, d, b), d3 = cross2(a, b, c), d4 = cross2(a, b, d);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0)))
+        return true;
+    const on = (p, q, r) => Math.min(q[0], r[0]) - 1e-12 <= p[0] &&
+        p[0] <= Math.max(q[0], r[0]) + 1e-12 &&
+        Math.min(q[1], r[1]) - 1e-12 <= p[1] &&
+        p[1] <= Math.max(q[1], r[1]) + 1e-12;
+    return ((Math.abs(d1) < 1e-12 && on(a, c, d)) ||
+        (Math.abs(d2) < 1e-12 && on(b, c, d)) ||
+        (Math.abs(d3) < 1e-12 && on(c, a, b)) ||
+        (Math.abs(d4) < 1e-12 && on(d, a, b)));
+}
+/**
+ * Surface of revolution about +Y from a profile of [radius, y] points. The profile may rise and fall
+ * (bowls, cups, rims); it is oriented so its material lies to the left. An open end away from the axis
+ * is capped when the material lies toward the axis there; a closed profile (first point repeated last)
+ * is a ring with no caps.
+ */
+export function lathe(m, sides, input, color) {
+    const { points: profile, closed } = orientProfile(input);
+    const point = (r, y, n) => {
+        const a = angle(n, sides);
+        return [Math.cos(a) * r, y, Math.sin(a) * r];
+    };
+    for (let i = 0; i + 1 < profile.length; i++) {
+        const [r0, y0] = requireValue(profile[i]), [r1, y1] = requireValue(profile[i + 1]);
+        if (r0 === 0 && r1 === 0)
+            continue;
+        // Outward 2D profile normal: the tangent (dr, dy) turned clockwise.
+        const nr = y1 - y0, ny = -(r1 - r0);
+        for (let n = 0; n < sides; n++) {
+            const mid = angle(n + 0.5, sides), outward = normalize([nr * Math.cos(mid), ny, nr * Math.sin(mid)]);
+            const points = r0 === 0
+                ? [point(0, y0, 0), point(r1, y1, n + 1), point(r1, y1, n)]
+                : r1 === 0
+                    ? [point(r0, y0, n), point(r0, y0, n + 1), point(0, y1, 0)]
+                    : [point(r0, y0, n), point(r0, y0, n + 1), point(r1, y1, n + 1), point(r1, y1, n)];
+            m.face(points, color, inside(points, outward));
+        }
+    }
+    if (closed)
+        return;
+    const cap = (at, dr, dy, start) => {
+        if (at[0] <= 0)
+            return;
+        // The material lies to the left of the profile direction; cap only where it lies toward the axis.
+        const facing = start
+            ? dy > 0 || (dy === 0 && dr > 0)
+                ? -1
+                : dy === 0
+                    ? 1
+                    : 0
+            : dy > 0 || (dy === 0 && dr < 0)
+                ? 1
+                : dy === 0
+                    ? -1
+                    : 0;
+        if (!facing)
+            return;
+        const disc = ring(sides, at[0], at[1]);
+        m.face(disc, color, inside(disc, [0, facing, 0]));
+    };
+    const n = profile.length, [r0, y0] = requireValue(profile[0]), [r1, y1] = requireValue(profile[1]), [ra, ya] = requireValue(profile[n - 2]), [rb, yb] = requireValue(profile[n - 1]);
+    cap([r0, y0], r1 - r0, y1 - y0, true);
+    cap([rb, yb], rb - ra, yb - ya, false);
+}
+const cross2 = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+/** Signed area in the X-Z plane (positive when the outline turns from +X toward +Z). */
+export const outlineArea = (outline) => {
+    let area = 0;
+    for (let i = 0; i < outline.length; i++) {
+        const [x0, z0] = requireValue(outline[i]), [x1, z1] = requireValue(outline[(i + 1) % outline.length]);
+        area += x0 * z1 - x1 * z0;
+    }
+    return area / 2;
+};
+/** True when two non-adjacent outline edges touch or cross, or a vertex repeats. */
+export function outlineSelfIntersects(outline) {
+    const n = outline.length, seg = (i) => [requireValue(outline[i]), requireValue(outline[(i + 1) % n])];
+    const onSegment = (p, a, b) => Math.min(a[0], b[0]) - 1e-12 <= p[0] &&
+        p[0] <= Math.max(a[0], b[0]) + 1e-12 &&
+        Math.min(a[1], b[1]) - 1e-12 <= p[1] &&
+        p[1] <= Math.max(a[1], b[1]) + 1e-12;
+    for (let i = 0; i < n; i++)
+        for (let j = i + 1; j < n; j++) {
+            const [a, b] = seg(i), [c, d] = seg(j);
+            if (j === i + 1 || (i === 0 && j === n - 1)) {
+                // Adjacent edges share one vertex; they must not fold back over each other.
+                const shared = j === i + 1 ? b : a, p = j === i + 1 ? a : b, q = j === i + 1 ? d : c;
+                if (Math.abs(cross2(shared, p, q)) < 1e-12 &&
+                    (p[0] - shared[0]) * (q[0] - shared[0]) + (p[1] - shared[1]) * (q[1] - shared[1]) > 0)
+                    return true;
+                continue;
+            }
+            const d1 = cross2(c, d, a), d2 = cross2(c, d, b), d3 = cross2(a, b, c), d4 = cross2(a, b, d);
+            if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0)))
+                return true;
+            if ((Math.abs(d1) < 1e-12 && onSegment(a, c, d)) ||
+                (Math.abs(d2) < 1e-12 && onSegment(b, c, d)) ||
+                (Math.abs(d3) < 1e-12 && onSegment(c, a, b)) ||
+                (Math.abs(d4) < 1e-12 && onSegment(d, a, b)))
+                return true;
+        }
+    return false;
+}
+/** Ear-clipping triangulation of a simple polygon with positive area (counterclockwise in X-Z). */
+function triangulate(outline) {
+    const remaining = outline.map((_, i) => i), triangles = [];
+    const contains = (p, a, b, c) => cross2(a, b, p) >= 0 && cross2(b, c, p) >= 0 && cross2(c, a, p) >= 0;
+    let guard = outline.length * outline.length;
+    while (remaining.length > 3 && guard-- > 0) {
+        let clipped = false;
+        for (let k = 0; k < remaining.length; k++) {
+            const ia = requireValue(remaining[(k + remaining.length - 1) % remaining.length]), ib = requireValue(remaining[k]), ic = requireValue(remaining[(k + 1) % remaining.length]), a = requireValue(outline[ia]), b = requireValue(outline[ib]), c = requireValue(outline[ic]);
+            if (cross2(a, b, c) <= 1e-15)
+                continue;
+            if (remaining.some((i) => i !== ia && i !== ib && i !== ic && contains(requireValue(outline[i]), a, b, c)))
+                continue;
+            triangles.push([ia, ib, ic]);
+            remaining.splice(k, 1);
+            clipped = true;
+            break;
+        }
+        if (!clipped)
+            break;
+    }
+    if (remaining.length === 3)
+        triangles.push([requireValue(remaining[0]), requireValue(remaining[1]), requireValue(remaining[2])]);
+    else
+        throw new RangeError("Outline could not be triangulated");
+    return triangles;
+}
+/** Prism from a simple X-Z outline, from y = 0 to y = height. */
+export function extrude(m, input, height, color) {
+    const outline = outlineArea(input) > 0 ? input : [...input].reverse(), n = outline.length;
+    for (const [a, b, c] of triangulate(outline)) {
+        const tri = (y) => [a, b, c].map((i) => [requireValue(outline[i])[0], y, requireValue(outline[i])[1]]);
+        const bottom = tri(0), top = tri(height);
+        m.face(bottom, color, inside(bottom, [0, -1, 0]));
+        m.face(top, color, inside(top, [0, 1, 0]));
+    }
+    for (let i = 0; i < n; i++) {
+        const [x0, z0] = requireValue(outline[i]), [x1, z1] = requireValue(outline[(i + 1) % n]), 
+        // Positive area turns from +X toward +Z, so the outward side of each edge is its clockwise normal.
+        outward = normalize([z1 - z0, 0, -(x1 - x0)]), quad = [
+            [x0, 0, z0],
+            [x1, 0, z1],
+            [x1, height, z1],
+            [x0, height, z0],
+        ];
+        m.face(quad, color, inside(quad, outward));
+    }
+}
+/**
+ * Ring in the local Y-Z plane (axis along X) with `sides` segments around the ring and six around its
+ * cross-section. Sixteen sides reproduce the legacy coil exactly; the compiler uses the legacy builder then.
+ */
+export function coil(m, sides, radius, thickness, color) {
+    const point = (a, b) => [
+        Math.sin(b) * thickness,
+        Math.cos(a) * (radius + Math.cos(b) * thickness),
+        Math.sin(a) * (radius + Math.cos(b) * thickness),
+    ];
+    for (let n = 0; n < sides; n++)
+        for (let k = 0; k < 6; k++) {
+            const a = angle(n, sides), b = (k * Math.PI) / 3, nextA = angle(n + 1, sides), nextB = b + Math.PI / 3;
+            // Midpoint of the centerline chord: inside the segment at any side count and thickness.
+            m.face([point(a, b), point(nextA, b), point(nextA, nextB), point(a, nextB)], color, [
+                0,
+                ((Math.cos(a) + Math.cos(nextA)) / 2) * radius,
+                ((Math.sin(a) + Math.sin(nextA)) / 2) * radius,
+            ]);
+        }
+}
+/**
+ * The 16-sided coil with the legacy builder's exact vertex arithmetic. Only the interior reference that
+ * orients each face differs (the centerline chord midpoint), so coils the legacy builder wound correctly
+ * are byte-identical, and coils thinner than about 2% of their radius are no longer partly inside out.
+ * The raw compatibility builder keeps its historical output.
+ */
+export function legacyCoil(m, radius, thickness, color) {
+    const point = (a, b) => [
+        0 + Math.sin(b) * thickness,
+        0 + Math.cos(a) * (radius + Math.cos(b) * thickness),
+        0 + Math.sin(a) * (radius + Math.cos(b) * thickness),
+    ];
+    for (let n = 0; n < 16; n++)
+        for (let k = 0; k < 6; k++) {
+            const a = (n * Math.PI) / 8, b = (k * Math.PI) / 3, nextA = a + Math.PI / 8, nextB = b + Math.PI / 3;
+            m.face([point(a, b), point(nextA, b), point(nextA, nextB), point(a, nextB)], color, [
+                0,
+                0 + ((Math.cos(a) + Math.cos(nextA)) / 2) * radius,
+                0 + ((Math.sin(a) + Math.sin(nextA)) / 2) * radius,
+            ]);
+        }
+}
+/** Orient a +Y-aligned local mesh along a → b with the legacy tube/beam frame. */
+export function alongSegment(part, a, b, target) {
+    const up = normalize(sub(b, a)), right = normalize(cross(Math.abs(up[2]) < 0.9 ? [0, 0, 1] : [1, 0, 0], up)), forward = cross(right, up), mesh = target.mesh, first = mesh.positions.length / 3;
+    for (let n = 0; n < part.positions.length; n += 3)
+        for (const [input, output, translate] of [
+            [part.positions, mesh.positions, true],
+            [part.normals, mesh.normals, false],
+        ])
+            for (let c = 0; c < 3; c++)
+                output.push((translate ? requireValue(a[c]) : 0) +
+                    requireValue(right[c]) * requireValue(input[n]) +
+                    requireValue(up[c]) * requireValue(input[n + 1]) +
+                    requireValue(forward[c]) * requireValue(input[n + 2]));
+    mesh.colors.push(...part.colors);
+    mesh.indices.push(...part.indices.map((i) => i + first));
+}
+/* ------------------------------------------------------------------ rotations */
+const EXACT = {
+    0: [1, 0],
+    30: [Math.sqrt(3) / 2, 0.5],
+    45: [Math.SQRT1_2, Math.SQRT1_2],
+    60: [0.5, Math.sqrt(3) / 2],
+    90: [0, 1],
+};
+/** cos/sin of degrees: exact at multiples of 90°, correctly rounded constants at multiples of 30° and 45°. */
+export function cosSin(degrees) {
+    let d = degrees % 360;
+    if (d < 0)
+        d += 360;
+    const quadrant = Math.floor(d / 90), rest = d - quadrant * 90;
+    // Reduce to the first quadrant so that θ and θ + 90° use the same libm values.
+    const [c, s] = EXACT[rest] ?? [Math.cos((rest * Math.PI) / 180), Math.sin((rest * Math.PI) / 180)];
+    // Rotate the first-quadrant value by quadrant × 90°.
+    const value = [
+        [c, s],
+        [-s, c],
+        [-c, -s],
+        [s, -c],
+    ][quadrant];
+    return [value[0] === 0 ? 0 : value[0], value[1] === 0 ? 0 : value[1]];
+}
+export function axisRotation(axis, degrees) {
+    const [c, s] = cosSin(degrees), ns = s === 0 ? 0 : -s;
+    if (axis === "x")
+        return [1, 0, 0, 0, 0, c, ns, 0, 0, s, c, 0];
+    if (axis === "y")
+        return [c, 0, s, 0, 0, 1, 0, 0, ns, 0, c, 0];
+    return [c, ns, 0, 0, s, c, 0, 0, 0, 0, 1, 0];
+}
+/** Extrinsic X, then Y, then Z rotation about the local origin: R = Rz · Ry · Rx. */
+export function eulerRotation(x, y, z) {
+    return compose(axisRotation("z", z), compose(axisRotation("y", y), axisRotation("x", x)));
+}
+export const isIdentity = (m) => m[0] === 1 &&
+    m[1] === 0 &&
+    m[2] === 0 &&
+    m[4] === 0 &&
+    m[5] === 1 &&
+    m[6] === 0 &&
+    m[8] === 0 &&
+    m[9] === 0 &&
+    m[10] === 1;
+/** Apply a rotation (and translation) to mesh positions and normals in place. */
+export function transformMesh(mesh, m) {
+    for (let i = 0; i < mesh.positions.length; i += 3) {
+        const p = applyPoint(m, [
+            requireValue(mesh.positions[i]),
+            requireValue(mesh.positions[i + 1]),
+            requireValue(mesh.positions[i + 2]),
+        ]), n = applyVector(m, [
+            requireValue(mesh.normals[i]),
+            requireValue(mesh.normals[i + 1]),
+            requireValue(mesh.normals[i + 2]),
+        ]);
+        for (let c = 0; c < 3; c++) {
+            mesh.positions[i + c] = requireValue(p[c]);
+            mesh.normals[i + c] = requireValue(n[c]);
+        }
+    }
+    return mesh;
+}
+export { dot };

package/dist/sprite-brief.d.ts

@@ -0,0 +1,5 @@
+import type { AssetSpec, CompiledAsset } from "./types.js";
+import type { SpriteView } from "./sprite-types.js";
+export declare function spriteBrief(ref: string, spec: AssetSpec, asset: CompiledAsset, views: Record<string, SpriteView>, { motion }?: {
+    motion?: unknown;
+}): string;

package/dist/sprite-brief.js

@@ -0,0 +1,47 @@
+import { layoutGuide, posedAsset } from "./sprite-guide.js";
+import { requireValue } from "./required.js";
+const LETTERS = [..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"];
+export function spriteBrief(ref, spec, asset, views, { motion = null } = {}) {
+    const out = [`# Brief: ${ref}`, ""];
+    out.push("Draw this asset in pixel-sprite/0.1. Every view below shares one density, so sizes agree across views.", "Coordinates are [x, y] from the canvas top-left; boxes are [x, y, w, h].", "");
+    out.push("## Parts and materials", "", "| part | material | colour |", "| --- | --- | --- |");
+    for (const [name, part] of Object.entries(spec.parts ?? {}))
+        out.push(`| ${name} | ${part.material ?? "–"} | ${spec.materials?.[part.material]?.color ?? "–"} |`);
+    out.push("");
+    for (const [name, view] of Object.entries(views)) {
+        const g = layoutGuide(posedAsset(asset, motion, view.pose ?? null), view);
+        out.push(`## View \`${name}\``, "", `Camera ${JSON.stringify(view.camera)}, ${view.pixelsPerMetre} px/m${view.pose ? `, pose: clip \`${view.pose.clip}\` at phase ${view.pose.phase}` : ""}. Canvas ${g.width}×${g.height} (use \`"view": "${name}"\`; the cel gets this size).`, "");
+        if (g.cut.length)
+            out.push(`Cut away in this view (do not draw): ${g.cut.join(", ")}.`, "");
+        const visible = Object.entries(g.parts).filter(([, p]) => !p.instance && p.area > 0);
+        visible.sort((a, b) => (a[1].depth ?? 0) - (b[1].depth ?? 0));
+        const letter = new Map(visible.map(([n], i) => [n, LETTERS[i] ?? "?"]));
+        out.push("| map | part | box | visible px | depth (0 = nearest) |", "| --- | --- | --- | ---: | ---: |");
+        for (const [n, p] of visible)
+            out.push(`| ${letter.get(n)} | ${n} | ${JSON.stringify(p.bbox)} | ${p.area} | ${p.depth} |`);
+        const small = Object.entries(g.parts).filter(([, p]) => !p.instance && p.subpixel);
+        if (small.length)
+            out.push("", `Too small to show at this density (draw them anyway if they matter, e.g. eyes): ${small.map(([n, p]) => `${n} near ${JSON.stringify(p.bbox.slice(0, 2))}`).join(", ")}.`);
+        const occluded = g.hidden.filter((n) => !g.cut.includes(n));
+        if (occluded.length)
+            out.push("", `Hidden behind other parts in this view: ${occluded.join(", ")}.`);
+        const sided = Object.entries(g.parts).filter(([, p]) => p.instance && p.area > 0);
+        if (sided.length)
+            out.push("", `Instances: ${sided.map(([n, p]) => `${n} ${JSON.stringify(p.bbox)}`).join(", ")}.`);
+        out.push("", "Part map (`.` empty):", "", "```");
+        for (let y = 0; y < g.height; y++) {
+            let row = "";
+            for (let x = 0; x < g.width; x++) {
+                const o = requireValue(g.owners[y * g.width + x]);
+                row += o < 0 ? "." : (letter.get(partNameOf(g, o) ?? "") ?? "?");
+            }
+            out.push(row);
+        }
+        out.push("```", "");
+    }
+    return out.join("\n");
+}
+function partNameOf(g, o) {
+    // Instance ids look like "foot/left" or "bolts/3"; the part is the first segment.
+    return requireValue(g.instances[o]).split("/")[0];
+}

package/dist/sprite-compiler.d.ts

@@ -0,0 +1,62 @@
+import type { SpriteDocument, SpriteResult, SpritePoint, SpriteColour, CompileSpriteOptions } from "./sprite-types.js";
+export declare const SPRITE_FORMAT = "pixel-sprite/0.1";
+export declare const SPRITE_LIMITS: Readonly<{
+    dimension: 1024;
+    cels: 4096;
+    layers: 512;
+    expandedOperations: 8192;
+    pixels: 16777216;
+    sceneDimension: 2048;
+    stamps: 256;
+    colors: 4096;
+    specks: 4096;
+}>;
+/** Reserved colour reference: paint transparent. */
+export declare const CLEAR = "clear";
+/** Predefined key in `pixels` rows and stamps: leave the pixel unchanged. */
+export declare const SKIP_KEY = ".";
+/** Guide parts smaller than this many pixels are not required in a view. */
+export declare const GUIDE_MIN_AREA = 3;
+/** Bounding-box overlap below which an authored part is reported as drifting from its guide. */
+export declare const GUIDE_MIN_IOU = 0.35;
+/** Escapes a document key for use as a JSON Pointer segment. */
+export declare const ptr: (key: unknown) => string;
+export declare function parseHex(hex: unknown): SpriteColour | null;
+export declare function toHex([r, g, b, a]: readonly [number, number, number, number]): string;
+export declare function rgbToOklab([r, g, b]: readonly [number, number, number, ...number[]]): [
+    number,
+    number,
+    number
+];
+export declare class SpriteCanvas {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    owners: Int32Array;
+    constructor(width: number, height: number);
+    clone(): SpriteCanvas;
+    inside(x: number, y: number): boolean;
+    opaque(x: number, y: number): boolean;
+    owner(x: number, y: number): number;
+    color(x: number, y: number): SpriteColour;
+    /** Paints one pixel; CLEAR erases it. Returns false when outside the canvas. */
+    set(x: number, y: number, c: SpriteColour | typeof CLEAR, owner?: number | null): boolean;
+    flip(axis: "x" | "y" | "xy"): SpriteCanvas;
+}
+/** Deterministic 32-bit PRNG (mulberry32). */
+export declare function mulberry32(seed: number): () => number;
+/** Integer points of a Bresenham segment, inclusive. */
+export declare function bresenham([x0, y0]: SpritePoint, [x1, y1]: SpritePoint): SpritePoint[];
+/**
+ * Compiles a pixel-sprite/0.1 document.
+ * `SPRITE_GUIDE_HIDDEN_REF` is an error for referencing an occluded guide part;
+ * `SPRITE_GUIDE_HIDDEN` warns about an authored drawing of such a part.
+ * Every user key in diagnostic paths is JSON Pointer escaped. Expanded recipes
+ * retain their calling path: /cels/<cel>/layers/<i>/recipe(<name>)/<j>.
+ * Resolver failures always emit an error, even if they also carry warnings.
+ */
+export declare function compileSprite(doc: SpriteDocument, options?: CompileSpriteOptions): SpriteResult;
+/** Maps every opaque pixel to the nearest palette colour in OKLab. */
+export declare function snapToPalette(canvas: Pick<SpriteCanvas, "width" | "height" | "rgba" | "owners">, colors: readonly SpriteColour[]): void;
+/** Part under a pixel of a compiled cel, or null. */
+export declare function pickSprite(result: SpriteResult, celId: string, x: number, y: number): string | null;