sprite-machine 0.1.0

package/src/gltf.js

@@ -0,0 +1,256 @@
+// ---------------------------------------------------------------------------
+// A glTF 2.0 BINARY writer for one textured mesh — what File → Export 3D
+// Model… hands over — and its reader (the tests' and the drive's). Pure:
+// typed arrays and a PNG in, bytes out; no THREE (model.js reads the
+// arrays off the mesh). One node, one mesh, one primitive, one
+// material, one texture: the model and its skin (skin.js) sampled
+// NEAREST both ways with clamped wrap — the hard texel is part of the file
+// — under a metallic-roughness material (metalness 0, roughness 1, the 3D
+// View's) or, asked for, the KHR_materials_unlit extension: the paint
+// exact under no light.
+//
+// Why glb: every engine's first-party importer reads it, its material IS
+// three's MeshStandardMaterial, and a browser gives one download per
+// gesture — a .gltf is three files, or one inflated by base64. Why a
+// writer of our own: three's GLTFExporter encodes a texture by drawing it
+// into a canvas and reading it back, the readback privacy browsers
+// perturb; this one takes the PNG as bytes (png-encode.js), so the skin
+// lands verbatim. Its subset is small enough to own, like the zip writer.
+//
+// The layout (the spec's, little-endian): a 12-byte header (the magic
+// 'glTF', version 2, the file's length), a JSON chunk padded with spaces to
+// four bytes, a BIN chunk padded with zeros holding the positions, normals,
+// UVs, indices and the PNG, each in its own 4-aligned bufferView. Positions
+// are baked in the caller's units (the scale — the reader's meters per
+// stage unit — applied here, so the accessor's min/max are the real extent
+// and the node carries no transform). UVs pass through: glTF's v = 0 is the
+// image's TOP row, and the skin's texel row 0 IS v = 0 (a DataTexture,
+// flipY false), so there is nothing to flip. The winding is CCW, three's.
+// ---------------------------------------------------------------------------
+
+const MAGIC = 0x46546c67; // 'glTF'
+const VERSION = 2;
+const CHUNK_JSON = 0x4e4f534a; // 'JSON'
+const CHUNK_BIN = 0x004e4942; // 'BIN\0'
+const FLOAT = 5126;
+const USHORT = 5123;
+const UINT = 5125;
+const ARRAY_BUFFER = 34962;
+const ELEMENT_ARRAY_BUFFER = 34963;
+const NEAREST = 9728;
+const CLAMP_TO_EDGE = 33071;
+const TRIANGLES = 4;
+
+const pad4 = (n) => (n + 3) & ~3;
+
+/**
+ * The model to write: `position` / `normal` / `uv` are per-vertex triples,
+ * triples and pairs (stage units, unit length, [0, 1]); `index` three vertex
+ * indices per triangle, CCW; `scale` a factor onto every position (1);
+ * `image` the skin as an encoded PNG, or null for a flat `color` (the
+ * material's base color, linear RGB 0..1); `unlit` puts KHR_materials_unlit
+ * on the material; `generator` and `extras` land on the asset.
+ * @typedef {{
+ *   name: string,
+ *   position: ArrayLike<number>,
+ *   normal: ArrayLike<number>,
+ *   uv: ArrayLike<number>,
+ *   index: ArrayLike<number>,
+ *   scale?: number,
+ *   image?: {bytes: Uint8Array, mimeType?: string}|null,
+ *   color?: ArrayLike<number>|null,
+ *   unlit?: boolean,
+ *   generator?: string,
+ *   extras?: object,
+ * }} GlbModel
+ */
+
+/**
+ * @param {GlbModel} model
+ * @returns {Uint8Array} the .glb file
+ */
+export function glbFromModel(model) {
+  const { name, position, normal, uv, index } = model;
+  const scale = model.scale ?? 1;
+  const n = position.length / 3;
+  if (!Number.isInteger(n) || n < 1)
+    throw new Error('gltf: positions must be xyz triples');
+  if (normal.length !== n * 3) throw new Error('gltf: one normal per vertex');
+  if (uv.length !== n * 2) throw new Error('gltf: one uv per vertex');
+  if (index.length % 3 !== 0 || index.length < 3)
+    throw new Error('gltf: indices come in triangles');
+
+  // The vertex buffers — positions scaled, with their extent.
+  const pos = new Float32Array(n * 3);
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < n * 3; i++) {
+    const v = position[i] * scale;
+    pos[i] = v;
+    const k = i % 3;
+    if (v < min[k]) min[k] = v;
+    if (v > max[k]) max[k] = v;
+  }
+  // Float32 rounding: the accessor's bounds must contain the stored values.
+  for (let k = 0; k < 3; k++) {
+    min[k] = Math.fround(min[k]);
+    max[k] = Math.fround(max[k]);
+  }
+  const nrm = Float32Array.from(normal);
+  const tex = Float32Array.from(uv);
+  const wide = n > 65535;
+  const idx = wide ? Uint32Array.from(index) : Uint16Array.from(index);
+
+  // The BIN chunk: each view at a 4-aligned offset.
+  /** @type {{bytes: Uint8Array, target?: number}[]} */
+  const views = [
+    { bytes: new Uint8Array(pos.buffer), target: ARRAY_BUFFER },
+    { bytes: new Uint8Array(nrm.buffer), target: ARRAY_BUFFER },
+    { bytes: new Uint8Array(tex.buffer), target: ARRAY_BUFFER },
+    { bytes: new Uint8Array(idx.buffer), target: ELEMENT_ARRAY_BUFFER },
+  ];
+  if (model.image) views.push({ bytes: model.image.bytes });
+  const bufferViews = [];
+  let binLength = 0;
+  for (const v of views) {
+    const view = { buffer: 0, byteOffset: binLength, byteLength: v.bytes.length };
+    if (v.target) view.target = v.target;
+    bufferViews.push(view);
+    binLength += pad4(v.bytes.length);
+  }
+  const bin = new Uint8Array(binLength);
+  views.forEach((v, i) => bin.set(v.bytes, bufferViews[i].byteOffset));
+
+  const material = {
+    name,
+    pbrMetallicRoughness: {
+      ...(model.image
+        ? { baseColorTexture: { index: 0 } }
+        : {
+            baseColorFactor: Array.from(model.color ?? [1, 1, 1])
+              .slice(0, 3)
+              .concat(1),
+          }),
+      metallicFactor: 0,
+      roughnessFactor: 1,
+    },
+  };
+  if (model.unlit) material.extensions = { KHR_materials_unlit: {} };
+
+  const json = {
+    asset: {
+      version: '2.0',
+      ...(model.generator ? { generator: model.generator } : {}),
+      ...(model.extras ? { extras: model.extras } : {}),
+    },
+    ...(model.unlit ? { extensionsUsed: ['KHR_materials_unlit'] } : {}),
+    scene: 0,
+    scenes: [{ nodes: [0] }],
+    nodes: [{ mesh: 0, name }],
+    meshes: [
+      {
+        name,
+        primitives: [
+          {
+            attributes: { POSITION: 0, NORMAL: 1, TEXCOORD_0: 2 },
+            indices: 3,
+            material: 0,
+            mode: TRIANGLES,
+          },
+        ],
+      },
+    ],
+    materials: [material],
+    ...(model.image
+      ? {
+          textures: [{ sampler: 0, source: 0, name: `${name} skin` }],
+          samplers: [
+            {
+              magFilter: NEAREST,
+              minFilter: NEAREST,
+              wrapS: CLAMP_TO_EDGE,
+              wrapT: CLAMP_TO_EDGE,
+            },
+          ],
+          images: [
+            {
+              name: `${name} skin`,
+              mimeType: model.image.mimeType ?? 'image/png',
+              bufferView: 4,
+            },
+          ],
+        }
+      : {}),
+    accessors: [
+      { bufferView: 0, componentType: FLOAT, count: n, type: 'VEC3', min, max },
+      { bufferView: 1, componentType: FLOAT, count: n, type: 'VEC3' },
+      { bufferView: 2, componentType: FLOAT, count: n, type: 'VEC2' },
+      {
+        bufferView: 3,
+        componentType: wide ? UINT : USHORT,
+        count: idx.length,
+        type: 'SCALAR',
+      },
+    ],
+    bufferViews,
+    buffers: [{ byteLength: binLength }],
+  };
+
+  // The file: header, the JSON chunk (space-padded), the BIN chunk (zero-padded).
+  const jsonBytes = new TextEncoder().encode(JSON.stringify(json));
+  const jsonLength = pad4(jsonBytes.length);
+  const total = 12 + 8 + jsonLength + 8 + binLength;
+  const out = new Uint8Array(total);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, MAGIC, true);
+  v.setUint32(4, VERSION, true);
+  v.setUint32(8, total, true);
+  v.setUint32(12, jsonLength, true);
+  v.setUint32(16, CHUNK_JSON, true);
+  out.set(jsonBytes, 20);
+  out.fill(0x20, 20 + jsonBytes.length, 20 + jsonLength);
+  const binAt = 20 + jsonLength;
+  v.setUint32(binAt, binLength, true);
+  v.setUint32(binAt + 4, CHUNK_BIN, true);
+  out.set(bin, binAt + 8);
+  return out;
+}
+
+/**
+ * Read a glb back: its parsed JSON and its BIN chunk (a view into `bytes`).
+ * The writer's mirror — tests and the drive read the export through it.
+ * Throws on anything but a version-2 glb with a JSON chunk first.
+ * @param {Uint8Array} bytes
+ * @returns {{json: any, bin: Uint8Array}}
+ */
+export function glbParts(bytes) {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length < 20 || v.getUint32(0, true) !== MAGIC)
+    throw new Error('not a glb: bad magic');
+  if (v.getUint32(4, true) !== VERSION) throw new Error('not a glb 2');
+  if (v.getUint32(8, true) !== bytes.length)
+    throw new Error('glb: length disagrees with the file');
+  const jsonLength = v.getUint32(12, true);
+  if (v.getUint32(16, true) !== CHUNK_JSON)
+    throw new Error('glb: the first chunk is not JSON');
+  const json = JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + jsonLength)));
+  let bin = new Uint8Array(0);
+  const binAt = 20 + jsonLength;
+  if (binAt + 8 <= bytes.length && v.getUint32(binAt + 4, true) === CHUNK_BIN) {
+    const binLength = v.getUint32(binAt, true);
+    bin = bytes.subarray(binAt + 8, binAt + 8 + binLength);
+  }
+  return { json, bin };
+}
+
+/**
+ * A bufferView's bytes out of a read glb (a reader convenience).
+ * @param {{json: any, bin: Uint8Array}} parts  @param {number} index
+ */
+export function glbViewBytes(parts, index) {
+  const view = parts.json.bufferViews[index];
+  return parts.bin.subarray(
+    view.byteOffset ?? 0,
+    (view.byteOffset ?? 0) + view.byteLength
+  );
+}

package/src/index.js

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// The engine's public surface — what `import … from 'sprite-machine'` gives:
+// the pipeline (ingest → carve → colorize), the mesher (regions, wedges, the
+// T-junction repair, the skin), the atlas's slicing and resizing, the file
+// formats (PNG chunks, the PNG encoder, glb) and the vocabularies. Explicit
+// names, never `export *`: two modules re-exporting one name through a star
+// would silently export neither. The headless entry is model.js; the Node
+// adapter (a PNG's pixels in, a glb file out) is `sprite-machine/node`.
+// ---------------------------------------------------------------------------
+
+export {
+  packRGBA,
+  unpackRGBA,
+  flip,
+  applyTransform,
+  ingestSprite,
+  placeView,
+} from './ingest.js';
+export {
+  voxIndex,
+  unvoxIndex,
+  reconcileDims,
+  gridViews,
+  carve,
+  extractSurface,
+} from './carve.js';
+export { buildPalette, makeSnapper, colorize } from './colorize.js';
+export { buildVoxels } from './pipeline.js';
+export {
+  VIEW_TO_FACE,
+  FACE_TO_VIEW,
+  FACE_NORMAL,
+  FACE_KEYS,
+  FACE_INDEX,
+  AXIS_INDEX,
+  faceKeyOf,
+  FACE_AXIS,
+  FACE_OPPOSITE,
+  VIEWS,
+  VIEW_NAMES,
+  VIEW_DISPLAY_ORDER,
+  VIEW_FRONT_EDGE,
+  VIEW_OPPOSITE,
+  MIRROR_AXIS,
+  VIEW_AXES,
+  VIEW_IMAGE_AXES,
+} from './views.js';
+export { FACE_GEO, idxFor, pointOf } from './faces.js';
+export {
+  DEFAULT_ATLAS_LAYOUT,
+  TILE_MIN,
+  TILE_MAX,
+  clampTile,
+  layoutSize,
+  deriveTileSize,
+  isBlank,
+  contentBounds,
+  validateSheet,
+  sliceAtlas,
+  blitTile,
+  resizeTileTo,
+  resizeTile,
+  splitLow,
+  resizeAtlas,
+  cellOf,
+} from './atlas.js';
+export { traceRegions, planeKey, faceRegions } from './regions.js';
+export { eliminateTJunctions } from './t-junction.js';
+export { bakeSkin, uvOfLattice, swatchUV } from './skin.js';
+export { skinTexture, finishVoxelMesh } from './mesh-util.js';
+export { wedgeMesh } from './wedge-mesh.js';
+export {
+  PNG_SIGNATURE,
+  isPng,
+  crc32,
+  readChunks,
+  buildChunk,
+  readTextChunks,
+  setTextChunks,
+} from './png-chunks.js';
+export { adler32, zlibStored, encodePng } from './png-encode.js';
+export { glbFromModel, glbParts, glbViewBytes } from './gltf.js';
+export { computeDiag } from './diag.js';
+export { DEFAULT_MIRROR, DEFAULT_WORLD_SIZE } from './constants.js';
+export { buildModel, modelToGlb } from './model.js';

package/src/ingest.js

@@ -0,0 +1,150 @@
+// ---------------------------------------------------------------------------
+// Ingest: sprite image -> occupancy + color typed arrays, at NATIVE size — the
+// tile is NOT cropped. No THREE / no DOM here so it runs unchanged in Node tests.
+//
+// Strict registration: a tile is a literal slice of the voxel lattice, so texel
+// (u,v) maps 1:1 to a fixed lattice line. We deliberately do NOT crop to the
+// alpha bounding box — where a pixel sits inside its tile IS its position in the
+// object, and must line up across faces (a FRONT pixel only survives the carve
+// where the SIDE covers its row and the TOP covers its column). Cropping would
+// throw that registration away.
+//
+// Input shape is ImageData-compatible: { width, height, data } where data is an
+// RGBA byte array (canvas.getImageData().data in the browser; a plain array in
+// tests). Output packs color as a Uint32 (bytes r,g,b,a, little-endian).
+// ---------------------------------------------------------------------------
+
+// Sprites are assumed to be HARD pixel art: every texel is either fully opaque
+// or fully transparent, no partial coverage. A pixel counts as solid at alpha
+// >= 128 — the 50%-coverage midpoint, robust to privacy-browser canvas farbling
+// that perturbs a 0/255 alpha by ±1 (see the wedge-mesh farbling note).
+const ALPHA_SOLID = 128;
+
+export const packRGBA = (r, g, b, a = 255) =>
+  ((r & 255) | ((g & 255) << 8) | ((b & 255) << 16) | ((a & 255) << 24)) >>> 0;
+
+export const unpackRGBA = (v) => ({
+  r: v & 255,
+  g: (v >>> 8) & 255,
+  b: (v >>> 16) & 255,
+  a: (v >>> 24) & 255,
+});
+
+function rot90cw(img) {
+  const { width: W, height: H, data } = img;
+  const nW = H,
+    nH = W;
+  const out = new Uint8ClampedArray(nW * nH * 4);
+  for (let dy = 0; dy < nH; dy++) {
+    for (let dx = 0; dx < nW; dx++) {
+      const sx = dy,
+        sy = H - 1 - dx;
+      const s = (sy * W + sx) * 4;
+      const d = (dy * nW + dx) * 4;
+      out[d] = data[s];
+      out[d + 1] = data[s + 1];
+      out[d + 2] = data[s + 2];
+      out[d + 3] = data[s + 3];
+    }
+  }
+  return { width: nW, height: nH, data: out };
+}
+
+// Axis-flip blit: mirror an image horizontally (flipX) and/or vertically (flipY).
+// Exported so derive.js's display-only mirrorImage reuses one flip implementation.
+// A no-op (both false) returns the SAME object; any flip returns a fresh copy.
+export function flip(img, flipX, flipY) {
+  if (!flipX && !flipY) return img;
+  const { width: W, height: H, data } = img;
+  const out = new Uint8ClampedArray(W * H * 4);
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const sx = flipX ? W - 1 - x : x;
+      const sy = flipY ? H - 1 - y : y;
+      const s = (sy * W + sx) * 4;
+      const d = (y * W + x) * 4;
+      out[d] = data[s];
+      out[d + 1] = data[s + 1];
+      out[d + 2] = data[s + 2];
+      out[d + 3] = data[s + 3];
+    }
+  }
+  return { width: W, height: H, data: out };
+}
+
+/**
+ * Reorient a sprite so it matches the pipeline's view conventions. Applied
+ * before ingest. `rot` is quarter-turns clockwise (0-3); flips run after rot.
+ * @param {{width,height,data}} img
+ * @param {{rot?:number, flipX?:boolean, flipY?:boolean}} t
+ */
+export function applyTransform(img, t = {}) {
+  let out = img;
+  const rot = (((t.rot || 0) % 4) + 4) % 4;
+  for (let i = 0; i < rot; i++) out = rot90cw(out);
+  return flip(out, !!t.flipX, !!t.flipY);
+}
+
+/**
+ * Ingest a sprite at NATIVE size — occupancy/color for the WHOLE tile, no crop.
+ * The tile's own dimensions become the view's dimensions, so its texels register
+ * 1:1 against the other faces. A fully transparent tile has nothing to constrain
+ * and returns null (treated as absent — the mirror partner colors it).
+ * @param {{width:number,height:number,data:ArrayLike<number>}} img
+ * @returns {{w:number,h:number,occ:Uint8Array,rgb:Uint32Array} | null}
+ */
+export function ingestSprite(img) {
+  const { width: W, height: H, data } = img;
+  if (!(W > 0) || !(H > 0) || !data || data.length < W * H * 4) {
+    throw new Error(
+      `ingestSprite: expected {width>0, height>0, data.length>=w*h*4}, got ` +
+        `${W}×${H} with ${data ? data.length : 'no'} bytes.`
+    );
+  }
+  const occ = new Uint8Array(W * H);
+  const rgb = new Uint32Array(W * H);
+  let any = false;
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const si = (y * W + x) * 4;
+      if (data[si + 3] >= ALPHA_SOLID) {
+        const di = y * W + x;
+        occ[di] = 1;
+        rgb[di] = packRGBA(data[si], data[si + 1], data[si + 2], 255);
+        any = true;
+      }
+    }
+  }
+  if (!any) return null; // fully transparent -> absent (mirror-filled)
+  return { w: W, h: H, occ, rgb };
+}
+
+/**
+ * Copy a view into a (targetW,targetH) grid buffer at NATIVE scale — no
+ * resampling — with its (0,0) texel at (offX,offY). Under strict registration
+ * gridViews passes offX=offY=0, so for a well-formed (uniform-tile) sheet every
+ * view already equals the grid on the axes it constrains and this is the exact
+ * fast-path identity copy below. It stays general only to pad the degenerate
+ * case where a malformed sheet gives views of unequal size (origin-anchored,
+ * far end left empty); the bounds guards keep that from indexing out of range.
+ * @returns {{occ:Uint8Array, rgb:Uint32Array}}
+ */
+export function placeView(view, targetW, targetH, offX, offY) {
+  const { w, h, occ, rgb } = view;
+  if (w === targetW && h === targetH) return { occ, rgb }; // exact fit (offX/offY==0)
+  const outOcc = new Uint8Array(targetW * targetH);
+  const outRgb = new Uint32Array(targetW * targetH);
+  for (let sy = 0; sy < h; sy++) {
+    const ty = sy + offY;
+    if (ty < 0 || ty >= targetH) continue;
+    for (let sx = 0; sx < w; sx++) {
+      const tx = sx + offX;
+      if (tx < 0 || tx >= targetW) continue;
+      const di = ty * targetW + tx;
+      const si = sy * w + sx;
+      outOcc[di] = occ[si];
+      outRgb[di] = rgb[si];
+    }
+  }
+  return { occ: outOcc, rgb: outRgb };
+}

package/src/mesh-util.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// Shared helpers for the wedge mesh builder (wedge-mesh.js), and the ONE place
+// THREE meets the skin: the texture the pure bake (skin.js) becomes, and the
+// framing + material the builder finishes with. (The plain voxel builder that
+// once shared them, mesh.js, went with the test trim of Sep 5 2026 — dead
+// code with no consumer; the vertex-color linearizer went with the skin on
+// Sep 7 2026 — the GPU's sampler decodes sRGB now, where the CPU used to.)
+// ---------------------------------------------------------------------------
+
+import * as THREE from 'three';
+import { unpackRGBA } from './ingest.js';
+
+/**
+ * The skin as a texture. DataTexture's constructor already states the skin's
+ * sampling contract — nearest filtering both ways, no mipmaps, flipY false
+ * (texel row 0 is v = 0, the bake's orientation), unpackAlignment 1 — those
+ * are the class's own defaults, named here as documentation, never restated
+ * as a correction. The bytes are sRGB, so the texture says so and the
+ * sampler decodes them on the way to the renderers' sRGB output.
+ * @param {import('./skin.js').Skin} skin
+ * @returns {THREE.DataTexture}
+ */
+export function skinTexture(skin) {
+  const tex = new THREE.DataTexture(skin.data, skin.width, skin.height, THREE.RGBAFormat);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+/**
+ * Shared final assembly: center the geometry on X/Z, leave Y exactly as
+ * authored (no ground-rest — the Y translate is a hard 0; where the object
+ * sits vertically is wherever the artist painted it, see carve.js), compute
+ * bounds, and wrap it in the standard flat-shaded material with shadows on —
+ * the skin as its `map`, or, with no map (flat mode), one packed `color`
+ * (sRGB bytes) as its albedo.
+ * @param {THREE.BufferGeometry} geo
+ * @param {{nx:number, nz:number, s:number, map?:THREE.Texture|null, color?:number|null,
+ *          userData?:Record<string,unknown>}} opts
+ * @returns {THREE.Mesh}
+ */
+export function finishVoxelMesh(
+  geo,
+  { nx, nz, s, map = null, color = null, userData = {} }
+) {
+  geo.translate((-nx * s) / 2, 0, (-nz * s) / 2); // center X/Z; Y left as authored
+  geo.computeBoundingBox();
+  geo.computeBoundingSphere();
+
+  const mat = new THREE.MeshStandardMaterial({
+    flatShading: true,
+    metalness: 0,
+    roughness: 1,
+    ...(map ? { map } : {}),
+  });
+  if (!map && color != null) {
+    const { r, g, b } = unpackRGBA(color);
+    mat.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+  }
+  const mesh = new THREE.Mesh(geo, mat);
+  mesh.castShadow = true;
+  mesh.receiveShadow = true;
+  Object.assign(mesh.userData, userData);
+  return mesh;
+}

package/src/model.js

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// The headless entry: a sheet's pixels → the model → a glb. What File →
+// Export 3D Model… does in the app, with no app around it — a Node script at
+// a project's startup, a build step, or a three.js page that wants the mesh
+// itself and no file at all.
+//
+// `buildModel` runs the whole chain — slice the 3×2 atlas, ingest, carve,
+// colorize, the low-poly wedge mesh with its skin — and hands back the
+// THREE.Mesh at ONE UNIT PER VOXEL: a position is a lattice coordinate, the
+// natural unit for a model whose author painted it texel by texel (the app's
+// stage scales the same mesh to its own world size; DEFAULT_WORLD_SIZE is
+// that stage's business). `modelToGlb` writes it as the glb the app exports,
+// so the export dialog and this path are one function: the mesh's buffers,
+// the skin encoded from bytes (never a canvas), the scale from the model's
+// units to glTF's meters, and the `sprite-machine` extras. Both are
+// synchronous and pure; a consumer that wants them off a main thread wraps
+// them in a worker or a child process.
+// ---------------------------------------------------------------------------
+
+import { sliceAtlas, validateSheet } from './atlas.js';
+import { buildVoxels } from './pipeline.js';
+import { wedgeMesh } from './wedge-mesh.js';
+import { encodePng } from './png-encode.js';
+import { glbFromModel } from './gltf.js';
+import { VIEW_NAMES } from './views.js';
+
+/**
+ * A built model: the mesh, the lattice it was carved on, and the mesh's
+ * units per voxel (1 from `buildModel`; the app's stage passes its own).
+ * @typedef {{
+ *   mesh: import('three').Mesh,
+ *   dims: {nx:number, ny:number, nz:number},
+ *   unitsPerVoxel: number,
+ *   triangles: number,
+ *   warnings: string[],
+ * }} Model
+ */
+
+/**
+ * Build the model of a 3×2 sprite sheet.
+ * @param {{width:number, height:number, data:ArrayLike<number>}} sheet
+ *   the atlas's RGBA pixels (an ImageData, or the same shape)
+ * @param {{transforms?: Record<string, {rot?:number, flipX?:boolean, flipY?:boolean}>}} [opts]
+ *   per-view reorientation, the document's `sprite-machine:transforms` chunk
+ * @returns {Model}  the mesh at one unit per voxel
+ * @throws on a sheet that is not a sheet, or one with no painted view
+ */
+export function buildModel(sheet, { transforms = {} } = {}) {
+  const bad = validateSheet(sheet);
+  if (bad) throw new Error(`buildModel: ${bad}`);
+  const sliced = sliceAtlas(sheet);
+  /** @type {Record<string, {width:number, height:number, data:ArrayLike<number>}|null>} */
+  const rawViews = {};
+  let provided = 0;
+  for (const n of VIEW_NAMES) {
+    rawViews[n] = sliced.views[n] || null;
+    if (rawViews[n]) provided++;
+  }
+  if (provided === 0) throw new Error('buildModel: the sheet has no painted view.');
+  const result = buildVoxels(rawViews, { transforms });
+  const { nx, ny, nz } = result.dims;
+  const mesh = wedgeMesh(result, { worldSize: Math.max(nx, ny, nz) });
+  return {
+    mesh,
+    dims: result.dims,
+    unitsPerVoxel: 1,
+    triangles: Number(mesh.userData.triangles) || 0,
+    warnings: [...sliced.warnings, ...(result.warnings || [])],
+  };
+}
+
+/**
+ * The model as a glb: its buffers at the given scale, its skin embedded (or,
+ * with no map, the material's flat color) behind a NEAREST sampler.
+ * @param {{mesh: import('three').Mesh, dims: {nx:number, ny:number, nz:number}, unitsPerVoxel?: number}} model
+ * @param {{name: string, voxelsPerMeter?: number, unlit?: boolean, generator?: string}} opts
+ *   `voxelsPerMeter` is the reader's scale (10: a 40-voxel car is 4 m long);
+ *   `unlit` puts KHR_materials_unlit on the material; `generator` names the
+ *   writer in the asset
+ * @returns {Uint8Array}  the .glb file
+ */
+export function modelToGlb(
+  model,
+  { name, voxelsPerMeter = 10, unlit = false, generator }
+) {
+  const { mesh, dims } = model;
+  const unitsPerVoxel = model.unitsPerVoxel ?? 1;
+  const geo = mesh.geometry;
+  const material = /** @type {import('three').MeshStandardMaterial} */ (mesh.material);
+  const map = material.map;
+  return glbFromModel({
+    name,
+    position: geo.attributes.position.array,
+    normal: geo.attributes.normal.array,
+    uv: geo.attributes.uv.array,
+    index: geo.index.array,
+    scale: 1 / (unitsPerVoxel * voxelsPerMeter),
+    image: map ? { bytes: encodePng(map.image) } : null,
+    color: map ? null : material.color.toArray(),
+    unlit,
+    generator,
+    extras: { 'sprite-machine': { voxelsPerMeter, dims: { ...dims } } },
+  });
+}