sprite-machine 0.1.0 → 0.2.0

package/src/constants.js

@@ -1,20 +1,15 @@
-// ---------------------------------------------------------------------------
-// The engine's defaults. Centralized so the pipeline, the mesher and every
-// consumer can never drift on what "the defaults" are. Import and spread
-// (`{ ...DEFAULT_MIRROR }`) rather than mutating these objects in place.
-// (The editor's palettes, which shared this file before the engine became a
-// package, are the app's src/lib/palette.js.)
-// ---------------------------------------------------------------------------
+// Engine defaults. Treat them as read-only and copy with a spread
+// (`{ ...DEFAULT_MIRROR }`).
 
 /**
- * Per-axis mirror-fill: a face with no view of its own is always filled from the
- * mirrored opposite view. On for every axis — objects are treated as symmetric,
- * so a half-drawn sheet (e.g. no LEFT/BACK/BOTTOM) still colors every face.
+ * Per-axis mirror-fill: a face with no view of its own is colored from the
+ * mirrored opposite view. On for every axis, so a half-drawn sheet still colors
+ * every face.
  */
 export const DEFAULT_MIRROR = { x: true, y: true, z: true };
 
 /**
- * World-space size the largest grid axis is scaled to fill — the app's stage
- * units. A headless build (model.js) uses one unit per voxel instead.
+ * World-space size the largest grid axis is scaled to, in the app's stage units.
+ * model.js uses one unit per voxel.
  */
 export const DEFAULT_WORLD_SIZE = 2.5;

package/src/diag.js

@@ -1,24 +1,17 @@
-// ---------------------------------------------------------------------------
-// Geometry self-check — a dev probe (the app reads it under ?diag=1; a
-// consumer can read it off any built mesh). Watertightness via
-// position-based edge parity + a per-face normal histogram: a closed surface
-// uses every undirected edge exactly twice; edges used an odd number of times
-// are boundaries — a genuine hole in a mesh that should be closed.
-//
-// MODE MATTERS: a nonzero boundary/odd count is only a "hole" for a mesh that
-// claims to be watertight. The low-poly (wedge) mesh is — its T-junctions are
-// repaired (t-junction.js) — but the greedy-voxel mesh (low-poly OFF) deliberately
-// leaves its step-riser T-junctions unrepaired, so it reports nonzero boundary/odd
-// edges as EXPECTED artifacts, not holes. main.js tags the ?diag=1 title with the
-// mode so the two conditions aren't conflated. This function just counts; it never
-// asserts watertightness on its own.
-// ---------------------------------------------------------------------------
+// Geometry self-check for development (the app's ?diag=1). Edges are matched by
+// vertex position. A closed surface uses every undirected edge exactly twice, so
+// edges used an odd number of times are boundaries. Also returns a histogram of
+// triangle normals by axis.
 
-/** @param {import('three').BufferGeometry} geo */
-export function computeDiag(geo) {
-  const pos = geo.attributes.position.array;
-  const nrm = geo.attributes.normal.array;
-  const idx = geo.index ? geo.index.array : null;
+/**
+ * @param {{position:ArrayLike<number>, normal:ArrayLike<number>,
+ *          index?:ArrayLike<number>|null}} geometry
+ *   flat triangle buffers, non-indexed when index is null
+ */
+export function computeDiag(geometry) {
+  const pos = geometry.position;
+  const nrm = geometry.normal;
+  const idx = geometry.index ?? null;
   const triCount = idx ? idx.length / 3 : pos.length / 9;
   const key = (i) => {
     const x = Math.round(pos[i * 3] * 1e4);

package/src/faces.js

@@ -1,27 +1,15 @@
-// ---------------------------------------------------------------------------
-// The face vocabulary's GEOMETRY: for each face key, the axes its plane spans
-// (A, B — the tangent frame every 2D read of a face uses: the regions, the
-// skin's charts and the UV read) and the axis it faces along (N), plus the two
-// lattice reads built on them — a tangent coordinate's voxel index (idxFor)
-// and its 3D point (pointOf). Pure, no THREE, Node-testable.
+// Face geometry: each face key's tangent axes (A, B) and normal axis (N), and the
+// lattice lookups idxFor (tangent coords to voxel index) and pointOf (tangent
+// coords to a 3D point).
 //
-// A face's plane sits at slice s along N: at s for a negative face (the
-// voxel's near side), at s + 1 for a positive one. Tangent (a, b) is the
-// voxel's own A/B coordinate, so the unit square [a, a+1] × [b, b+1] on the
-// plane IS that voxel's face, and a texel per face is a texel per unit
-// square — the skin's orientation rule, stated once (skin.js).
-//
-// Until Sep 7 2026 this module also merged faces into greedy rectangles
-// (culledQuads / greedyQuads); the mesher traces coplanar REGIONS now
-// (regions.js) — a rectangle being the region with four corners — so the quad
-// builders went with their last consumer.
-// ---------------------------------------------------------------------------
+// A face's plane at slice s sits at s along N for a negative face and at s + 1 for
+// a positive one. Tangent (a, b) is the voxel's own A/B coordinate, so the unit
+// square [a, a+1] × [b, b+1] on the plane is that voxel's face.
 
 import { voxIndex } from './carve.js';
 import { FACE_NORMAL, AXIS_INDEX } from './views.js';
 
-// Per-face tangent axes and the normal axis. The outward normal is read from
-// the shared FACE_NORMAL (views.js), not restated here.
+// The outward normal's sign is in FACE_NORMAL.
 export const FACE_GEO = {
   px: { N: 'x', A: 'y', B: 'z' },
   nx: { N: 'x', A: 'y', B: 'z' },
@@ -32,9 +20,7 @@ export const FACE_GEO = {
 };
 
 /**
- * The voxel index behind tangent coords (a, b) on slice s of `face` — the
- * lattice cell whose face that is. One home: the regions, the skin's baker
- * and every test compose it here.
+ * The index of the voxel whose face is at tangent coords (a, b) on slice s.
  * @param {string} face  a FACE_KEYS key
  * @param {number} a  along FACE_GEO[face].A
  * @param {number} b  along FACE_GEO[face].B
@@ -51,8 +37,7 @@ export function idxFor(face, a, b, s, dims) {
 }
 
 /**
- * The 3D lattice point at tangent (a, b) on the plane of `face` at slice s —
- * the plane at s + 1 for a positive face, at s for a negative one.
+ * The 3D lattice point at tangent (a, b) on the plane of face at slice s.
  * @param {string} face
  * @param {number} a
  * @param {number} b

package/src/gltf.js

@@ -1,32 +1,15 @@
-// ---------------------------------------------------------------------------
-// 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.
+// glTF 2.0 binary (glb) writer for one textured mesh, and a reader. Typed arrays
+// and a PNG in, bytes out. No THREE.
 //
-// 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 PNG bytes are stored as given, not drawn through a canvas, because privacy
+// browsers perturb canvas readback.
 //
-// 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.
-// ---------------------------------------------------------------------------
+// Layout (little-endian): a 12-byte header ('glTF', version 2, file length), a
+// JSON chunk padded with spaces to 4 bytes, and a BIN chunk padded with zeros.
+// The BIN chunk holds positions, normals, UVs, indices and the PNG, each in a
+// 4-aligned bufferView. Positions are multiplied by scale here, so the accessor
+// min/max are the real extent and the node has no transform. UVs pass through
+// unflipped: glTF v = 0 is the image's top row, as in the skin. Winding is CCW.
 
 const MAGIC = 0x46546c67; // 'glTF'
 const VERSION = 2;
@@ -44,12 +27,11 @@ 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.
+ * The model to write. position and normal are per-vertex xyz (stage units, unit
+ * length), uv per-vertex pairs in [0, 1], index three CCW vertex indices per
+ * triangle. scale multiplies every position (default 1). image is the skin as an
+ * encoded PNG, or null for a flat color (linear RGB 0..1). unlit adds
+ * KHR_materials_unlit. generator and extras go on the asset.
  * @typedef {{
  *   name: string,
  *   position: ArrayLike<number>,
@@ -80,7 +62,7 @@ export function glbFromModel(model) {
   if (index.length % 3 !== 0 || index.length < 3)
     throw new Error('gltf: indices come in triangles');
 
-  // The vertex buffers — positions scaled, with their extent.
+  // Scaled positions and their extent.
   const pos = new Float32Array(n * 3);
   const min = [Infinity, Infinity, Infinity];
   const max = [-Infinity, -Infinity, -Infinity];
@@ -91,7 +73,7 @@ export function glbFromModel(model) {
     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.
+  // Round the bounds to Float32 so they contain the stored values.
   for (let k = 0; k < 3; k++) {
     min[k] = Math.fround(min[k]);
     max[k] = Math.fround(max[k]);
@@ -101,7 +83,7 @@ export function glbFromModel(model) {
   const wide = n > 65535;
   const idx = wide ? Uint32Array.from(index) : Uint16Array.from(index);
 
-  // The BIN chunk: each view at a 4-aligned offset.
+  // BIN chunk: each view at a 4-aligned offset.
   /** @type {{bytes: Uint8Array, target?: number}[]} */
   const views = [
     { bytes: new Uint8Array(pos.buffer), target: ARRAY_BUFFER },
@@ -196,7 +178,7 @@ export function glbFromModel(model) {
     buffers: [{ byteLength: binLength }],
   };
 
-  // The file: header, the JSON chunk (space-padded), the BIN chunk (zero-padded).
+  // Header, JSON chunk (space-padded), BIN chunk (zero-padded).
   const jsonBytes = new TextEncoder().encode(JSON.stringify(json));
   const jsonLength = pad4(jsonBytes.length);
   const total = 12 + 8 + jsonLength + 8 + binLength;
@@ -217,9 +199,8 @@ export function glbFromModel(model) {
 }
 
 /**
- * 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.
+ * Read a glb: its parsed JSON and its BIN chunk (a view into bytes). Throws unless
+ * it is a version-2 glb with a JSON chunk first.
  * @param {Uint8Array} bytes
  * @returns {{json: any, bin: Uint8Array}}
  */
@@ -244,7 +225,7 @@ export function glbParts(bytes) {
 }
 
 /**
- * A bufferView's bytes out of a read glb (a reader convenience).
+ * A bufferView's bytes from a read glb.
  * @param {{json: any, bin: Uint8Array}} parts  @param {number} index
  */
 export function glbViewBytes(parts, index) {

package/src/index.js

@@ -1,12 +1,6 @@
-// ---------------------------------------------------------------------------
-// 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`.
-// ---------------------------------------------------------------------------
+// Public API of the sprite-machine package. Exports are listed by name: with
+// export *, a name exported by two modules is silently dropped. The Node adapter
+// is sprite-machine/node, the three adapter sprite-machine/three.
 
 export {
   packRGBA,
@@ -25,7 +19,7 @@ export {
   extractSurface,
 } from './carve.js';
 export { buildPalette, makeSnapper, colorize } from './colorize.js';
-export { buildVoxels } from './pipeline.js';
+export { buildVoxels, unionVoxels, buildLayeredVoxels } from './pipeline.js';
 export {
   VIEW_TO_FACE,
   FACE_TO_VIEW,
@@ -50,6 +44,7 @@ export {
   DEFAULT_ATLAS_LAYOUT,
   TILE_MIN,
   TILE_MAX,
+  LAYER_MAX,
   clampTile,
   layoutSize,
   deriveTileSize,
@@ -57,6 +52,7 @@ export {
   contentBounds,
   validateSheet,
   sliceAtlas,
+  sliceLayers,
   blitTile,
   resizeTileTo,
   resizeTile,
@@ -64,10 +60,11 @@ export {
   resizeAtlas,
   cellOf,
 } from './atlas.js';
+export { LAYERS_CHUNK, layersChunk, parseLayersChunk, layerCount } from './layers.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 { weldVertices } from './weld.js';
 export { wedgeMesh } from './wedge-mesh.js';
 export {
   PNG_SIGNATURE,

package/src/ingest.js

@@ -1,23 +1,14 @@
-// ---------------------------------------------------------------------------
-// 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.
+// Ingest: a sprite image to occupancy and color typed arrays, at native size. No
+// THREE or DOM.
 //
-// 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.
+// Tiles are not cropped to their alpha bounds. A texel's place in its tile is its
+// lattice position and must line up across faces.
 //
-// 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).
-// ---------------------------------------------------------------------------
+// Input is ImageData-like { width, height, data } with RGBA bytes. Colors pack into
+// a Uint32 as 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).
+// Sprites are hard pixel art. A texel is solid at alpha >= 128, which tolerates the
+// ±1 alpha noise privacy browsers add to canvas reads.
 const ALPHA_SOLID = 128;
 
 export const packRGBA = (r, g, b, a = 255) =>
@@ -50,9 +41,8 @@ function rot90cw(img) {
   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.
+// Mirror an image horizontally (flipX) and/or vertically (flipY). With both false
+// it returns the same object, otherwise a new copy.
 export function flip(img, flipX, flipY) {
   if (!flipX && !flipY) return img;
   const { width: W, height: H, data } = img;
@@ -73,8 +63,8 @@ export function flip(img, flipX, flipY) {
 }
 
 /**
- * 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.
+ * Reorient a sprite to the pipeline's view conventions before ingest. rot is
+ * quarter-turns clockwise (0-3). Flips apply after the rotation.
  * @param {{width,height,data}} img
  * @param {{rot?:number, flipX?:boolean, flipY?:boolean}} t
  */
@@ -86,10 +76,8 @@ export function applyTransform(img, t = {}) {
 }
 
 /**
- * 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).
+ * Occupancy and color for a whole tile at native size. A fully transparent tile
+ * returns null and counts as absent.
  * @param {{width:number,height:number,data:ArrayLike<number>}} img
  * @returns {{w:number,h:number,occ:Uint8Array,rgb:Uint32Array} | null}
  */
@@ -115,23 +103,18 @@ export function ingestSprite(img) {
       }
     }
   }
-  if (!any) return null; // fully transparent -> absent (mirror-filled)
+  if (!any) return null;
   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.
+ * Copy a view into a targetW × targetH grid at native scale with its (0,0) texel
+ * at (offX, offY). Uncovered cells stay empty and texels outside are clipped.
  * @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)
+  if (w === targetW && h === targetH) return { occ, rgb }; // assumes offX = offY = 0
   const outOcc = new Uint8Array(targetW * targetH);
   const outRgb = new Uint32Array(targetW * targetH);
   for (let sy = 0; sy < h; sy++) {

package/src/layers.js

@@ -0,0 +1,55 @@
+// The sprite-machine:layers chunk: a document PNG's layer names in block order.
+// Its length is the layer count.
+
+import { DEFAULT_ATLAS_LAYOUT, LAYER_MAX, layoutSize } from './atlas.js';
+
+/** PNG text chunk keyword. */
+export const LAYERS_CHUNK = 'sprite-machine:layers';
+
+/**
+ * The chunk's text, `{"layers":[{"name":"Layer 1"}]}` for one layer.
+ * @param {string[]} names  one per block, in block order
+ * @returns {string}
+ */
+export function layersChunk(names) {
+  return JSON.stringify({ layers: names.map((name) => ({ name })) });
+}
+
+/**
+ * The names in a chunk's text. Null for a missing or malformed chunk, or one
+ * naming no layers or more than LAYER_MAX.
+ * @param {string|null|undefined} text
+ * @returns {string[]|null}
+ */
+export function parseLayersChunk(text) {
+  if (!text) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const list = parsed?.layers;
+  if (!Array.isArray(list) || list.length < 1 || list.length > LAYER_MAX) return null;
+  const names = [];
+  for (const entry of list) {
+    if (typeof entry?.name !== 'string') return null;
+    names.push(entry.name);
+  }
+  return names;
+}
+
+/**
+ * The layer count of a sheet `height` px tall whose chunk holds `names`: their
+ * count when it divides the height into whole blocks, else null.
+ * @param {number} height
+ * @param {string[]|null|undefined} names
+ * @returns {number|null}
+ */
+export function layerCount(height, names) {
+  const n = names?.length ?? 0;
+  const { rows } = layoutSize(DEFAULT_ATLAS_LAYOUT);
+  return n > 0 && Number.isInteger(height) && height > 0 && height % (rows * n) === 0
+    ? n
+    : null;
+}

package/src/model.js

@@ -1,102 +1,98 @@
-// ---------------------------------------------------------------------------
-// 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.
+// Headless entry: a sheet's pixels to a model, and a model to a glb.
 //
-// `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.
-// ---------------------------------------------------------------------------
+// buildModel runs slice, ingest, carve, colorize, the layer union and the
+// wedge mesher, and returns the record at one unit per voxel, so a position is
+// a lattice coordinate. modelToGlb writes the same glb as the app's export,
+// with the skin encoded from bytes. Both are synchronous.
 
-import { sliceAtlas, validateSheet } from './atlas.js';
-import { buildVoxels } from './pipeline.js';
+import { sliceLayers, validateSheet } from './atlas.js';
+import { buildLayeredVoxels } from './pipeline.js';
 import { wedgeMesh } from './wedge-mesh.js';
 import { encodePng } from './png-encode.js';
 import { glbFromModel } from './gltf.js';
+import { unpackRGBA } from './ingest.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,
+ * A built model: the mesher's record, the lattice dims and the units per voxel
+ * (1 from buildModel).
+ * @typedef {import('./wedge-mesh.js').Built & {
  *   dims: {nx:number, ny:number, nz:number},
  *   unitsPerVoxel: number,
- *   triangles: number,
  *   warnings: string[],
  * }} Model
  */
 
 /**
- * Build the model of a 3×2 sprite sheet.
+ * Build the model of a sprite sheet: one 3×2 block of tiles, or `layers` blocks
+ * stacked top to bottom, whose hulls are unioned (unionVoxels).
  * @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
+ *   the atlas's RGBA pixels, ImageData-shaped
+ * @param {{transforms?: Record<string, {rot?:number, flipX?:boolean, flipY?:boolean}>,
+ *          layers?: number}} [opts]
+ *   `transforms`: per-view reorientation, as stored in the
+ *   `sprite-machine:transforms` chunk, applied in every layer; `layers`: the
+ *   sheet's block count
+ * @returns {Model}  the model at one unit per voxel
+ * @throws on an invalid sheet, or one with no painted view in any layer
  */
-export function buildModel(sheet, { transforms = {} } = {}) {
+export function buildModel(sheet, { transforms = {}, layers = 1 } = {}) {
   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++;
+  const sliced = sliceLayers(sheet, { layers });
+  const result = buildLayeredVoxels(
+    sliced.layers.map((views) =>
+      Object.fromEntries(VIEW_NAMES.map((n) => [n, views[n] || null]))
+    ),
+    { transforms }
+  );
+  if (result.providedViews.length === 0) {
+    throw new Error('buildModel: the sheet has no painted view.');
   }
-  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,
+    ...wedgeMesh(result, { worldSize: Math.max(nx, ny, nz) }),
     dims: result.dims,
     unitsPerVoxel: 1,
-    triangles: Number(mesh.userData.triangles) || 0,
     warnings: [...sliced.warnings, ...(result.warnings || [])],
   };
 }
 
+/** The sRGB transfer to linear, one channel in 0..1. */
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+/** A packed sRGB color as linear RGB in 0..1. */
+function linearRGB(packed) {
+  const { r, g, b } = unpackRGBA(packed);
+  return [r / 255, g / 255, b / 255].map(srgbToLinear);
+}
+
 /**
- * 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
+ * The model as a glb, with its skin embedded behind a nearest sampler, or its
+ * flat color, made linear, when it has no skin.
+ * @param {{geometry: import('./wedge-mesh.js').Geometry,
+ *          skin: import('./skin.js').Skin|null, color?: number|null,
+ *          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
+ *   `voxelsPerMeter` sets the scale (at 10, a 40-voxel car is 4 m long);
+ *   `unlit` adds KHR_materials_unlit; `generator` is written to the asset
  * @returns {Uint8Array}  the .glb file
  */
 export function modelToGlb(
   model,
   { name, voxelsPerMeter = 10, unlit = false, generator }
 ) {
-  const { mesh, dims } = model;
+  const { geometry, skin, 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,
+    position: geometry.position,
+    normal: geometry.normal,
+    uv: geometry.uv,
+    index: geometry.index,
     scale: 1 / (unitsPerVoxel * voxelsPerMeter),
-    image: map ? { bytes: encodePng(map.image) } : null,
-    color: map ? null : material.color.toArray(),
+    image: skin ? { bytes: encodePng(skin) } : null,
+    color: skin || model.color == null ? null : linearRGB(model.color),
     unlit,
     generator,
     extras: { 'sprite-machine': { voxelsPerMeter, dims: { ...dims } } },