sprite-machine 0.1.0 → 0.2.0

package/src/atlas.js

@@ -1,31 +1,30 @@
-// ---------------------------------------------------------------------------
-// Atlas slicing: cut a packed sprite sheet into the six named face tiles.
-//
-// Pure (operates on {width,height,data}, returns the same shape) so it's
-// Node-testable and its output drops straight into buildVoxels(). The tile size
-// is derived from the image dimensions and the layout grid unless given
-// explicitly: a 3x2 layout on a 120x80 sheet => 40x40 tiles.
-// ---------------------------------------------------------------------------
+// Atlas slicing and resizing on ImageData-like {width, height, data} sheets.
+// Unless given, the tile size derives from the sheet and the layout: a 3x2 layout
+// on a 120x80 sheet gives 40x40 tiles. A layered sheet stacks blocks of the
+// layout one under another, every block at the same tile size.
 
 import { VIEW_NAMES, VIEW_IMAGE_AXES } from './views.js';
 
-// Grid of view names (row-major). null = an intentionally empty cell.
+// View names by row. null marks an empty cell.
 export const DEFAULT_ATLAS_LAYOUT = [
   ['left', 'front', 'top'],
   ['right', 'back', 'bottom'],
 ];
 
-// Allowed tile-dimension range for the in-app resize control (integers). A tile
-// maps 1:1 onto a lattice axis, so this is also the voxel grid's per-axis range —
-// and the carve/colorize pass is a synchronous O(n³) walk on the main thread. The
-// ceiling is 64 (a 64³ = 262 k-voxel grid still rebuilds live per stroke); larger
-// tiles (a 256³ = 16.7 M-voxel carve) froze the tab for seconds. clampTile pins
-// both the stepper and the ?tile dev hook into this range.
+// Tile side range, in px. A tile side is also a voxel grid axis, and the carve is
+// a synchronous O(n³) pass. At 64 a rebuild per stroke stays fast.
 export const TILE_MIN = 1;
 export const TILE_MAX = 64;
 export const clampTile = (n) =>
   Math.max(TILE_MIN, Math.min(TILE_MAX, Math.round(Number(n) || 0)));
 
+// The most layers a document stacks. Every layer is carved on its own, so a
+// full rebuild is up to this many carves.
+export const LAYER_MAX = 8;
+
+// A `layers` option as a whole count of at least 1.
+const layerOption = (n) => Math.max(1, Math.floor(Number(n) || 1));
+
 export function layoutSize(layout) {
   const rows = layout.length;
   const cols = Math.max(...layout.map((r) => r.length));
@@ -57,20 +56,15 @@ function subTile(img, sx, sy, w, h) {
   return { width: w, height: h, data: out };
 }
 
-// Is a tile fully transparent? (alpha 0 everywhere — stray RGB under alpha 0 is
-// ignored, matching the editor's hard-pixel rule). Exported as the single "is this
-// empty?" predicate so main.js's applyTileEdit doesn't roll its own copy.
+// True when every texel has alpha 0.
 export const isBlank = (tile) => {
   for (let i = 3; i < tile.data.length; i += 4) if (tile.data[i] !== 0) return false;
   return true;
 };
 
 /**
- * The tight bounding box of a tile's non-transparent texels — the same
- * alpha!==0 rule as isBlank, so the two can never disagree about emptiness:
- * contentBounds(t) === null exactly when isBlank(t). The icon generator trims
- * to this box so a sprite fills its icon instead of shipping the tile's
- * transparent margin.
+ * The tight bounding box of a tile's texels with alpha !== 0. Null exactly when
+ * isBlank(tile).
  * @param {{width:number,height:number,data:ArrayLike<number>}} tile
  * @returns {{x:number,y:number,width:number,height:number}|null}
  */
@@ -94,10 +88,8 @@ export function contentBounds(tile) {
 }
 
 /**
- * Validate an ImageData-like sheet at an ingestion boundary: finite positive
- * dimensions and a data buffer long enough for width*height RGBA texels. Returns
- * an error string (surfaced to the user), or null when the sheet is usable — so
- * sliceAtlas/resizeAtlas downstream can trust their input's shape.
+ * Validate an ImageData-like sheet: finite positive dimensions and at least
+ * width*height*4 bytes of data. Returns a user-facing error, or null when usable.
  * @param {{width:number,height:number,data:ArrayLike<number>}|null|undefined} img
  * @returns {string|null}
  */
@@ -118,43 +110,30 @@ export function validateSheet(img) {
   return null;
 }
 
-/**
- * @param {{width:number,height:number,data:ArrayLike<number>}} img
- * @param {{layout?:string[][], tileW?:number, tileH?:number}} [opts]
- * @returns {{views:Record<string,{width,height,data}|null>,
- *            tileW:number, tileH:number, cols:number, rows:number,
- *            warnings:string[]}}
- */
-export function sliceAtlas(img, opts = {}) {
-  const layout = opts.layout || DEFAULT_ATLAS_LAYOUT;
-  const {
-    cols,
-    rows,
-    tileW: autoW,
-    tileH: autoH,
-  } = deriveTileSize(img.width, img.height, layout);
-  const warnings = [];
-
-  // Fill each dimension independently so a lone tileW/tileH override survives.
-  const tileW = Math.round(opts.tileW || autoW);
-  const tileH = Math.round(opts.tileH || autoH);
+/** @typedef {Record<string, {width:number,height:number,data:Uint8ClampedArray}|null>} Views */
 
-  /** @type {Record<string, {width:number,height:number,data:ArrayLike<number>}|null>} */
-  const views = {};
+// Slice `count` stacked blocks of the layout at tileW × tileH. Block k's cell
+// (r, c) starts at column c·tileW and row (rows·k + r)·tileH. A cell past the
+// sheet's edge is left out, and a blank tile slices to null.
+function sliceBlocks(img, layout, count, tileW, tileH) {
+  const { cols, rows } = layoutSize(layout);
+  const gridRows = rows * count;
+  const warnings = [];
+  /** @type {Views[]} */
+  const blocks = Array.from({ length: count }, () => ({}));
 
-  // Bail on a fundamentally unusable sheet rather than emitting garbage tiles.
   if (!(img.width > 0 && img.height > 0) || tileW < 1 || tileH < 1) {
     warnings.push(
       `Atlas is unusable: a ${img.width}×${img.height}px sheet split into ` +
-        `${cols}×${rows} gives ${tileW}×${tileH}px tiles. Check the image and tile size.`
+        `${cols}×${gridRows} gives ${tileW}×${tileH}px tiles. Check the image and tile size.`
     );
-    return { views, tileW, tileH, cols, rows, warnings };
+    return { blocks, cols, rows, warnings };
   }
 
-  if (cols * tileW !== img.width || rows * tileH !== img.height) {
+  if (cols * tileW !== img.width || gridRows * tileH !== img.height) {
     warnings.push(
-      `Layout ${cols}x${rows} at ${tileW}x${tileH} tiles = ` +
-        `${cols * tileW}x${rows * tileH}px, but image is ${img.width}x${img.height}px. ` +
+      `Layout ${cols}x${gridRows} at ${tileW}x${tileH} tiles = ` +
+        `${cols * tileW}x${gridRows * tileH}px, but image is ${img.width}x${img.height}px. ` +
         `Tiles are read from the top-left; check tile size / layout.`
     );
   }
@@ -162,27 +141,65 @@ export function sliceAtlas(img, opts = {}) {
   for (let r = 0; r < rows; r++) {
     for (let c = 0; c < (layout[r] || []).length; c++) {
       const name = layout[r][c];
-      if (!name) continue;
-      if (!VIEW_NAMES.includes(name)) {
+      if (name && !VIEW_NAMES.includes(name)) {
         warnings.push(`Unknown view "${name}" in layout; ignored.`);
-        continue;
       }
-      const sx = c * tileW;
-      const sy = r * tileH;
-      if (sx + tileW > img.width || sy + tileH > img.height) continue;
-      const tile = subTile(img, sx, sy, tileW, tileH);
-      views[name] = isBlank(tile) ? null : tile;
     }
   }
-  return { views, tileW, tileH, cols, rows, warnings };
+
+  blocks.forEach((views, k) => {
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < (layout[r] || []).length; c++) {
+        const name = layout[r][c];
+        if (!name || !VIEW_NAMES.includes(name)) continue;
+        const sx = c * tileW;
+        const sy = (rows * k + r) * tileH;
+        if (sx + tileW > img.width || sy + tileH > img.height) continue;
+        const tile = subTile(img, sx, sy, tileW, tileH);
+        views[name] = isBlank(tile) ? null : tile;
+      }
+    }
+  });
+  return { blocks, cols, rows, warnings };
+}
+
+/**
+ * @param {{width:number,height:number,data:ArrayLike<number>}} img
+ * @param {{layout?:string[][], tileW?:number, tileH?:number}} [opts]
+ * @returns {{views:Views, tileW:number, tileH:number, cols:number, rows:number,
+ *            warnings:string[]}}
+ */
+export function sliceAtlas(img, opts = {}) {
+  const layout = opts.layout || DEFAULT_ATLAS_LAYOUT;
+  const auto = deriveTileSize(img.width, img.height, layout);
+  const tileW = Math.round(opts.tileW || auto.tileW);
+  const tileH = Math.round(opts.tileH || auto.tileH);
+  const { blocks, cols, rows, warnings } = sliceBlocks(img, layout, 1, tileW, tileH);
+  return { views: blocks[0], tileW, tileH, cols, rows, warnings };
+}
+
+/**
+ * Slice a layered sheet into one views record per block. The tile is the width
+ * over the layout's columns and the height over its rows times `layers`. With
+ * one layer this is sliceAtlas.
+ * @param {{width:number,height:number,data:ArrayLike<number>}} img
+ * @param {{layers?:number, layout?:string[][]}} [opts]
+ * @returns {{layers:Views[], tileW:number, tileH:number, cols:number, rows:number,
+ *            warnings:string[]}}  rows is the layout's, not the sheet's
+ */
+export function sliceLayers(img, opts = {}) {
+  const layout = opts.layout || DEFAULT_ATLAS_LAYOUT;
+  const count = layerOption(opts.layers);
+  const { cols, rows } = layoutSize(layout);
+  const tileW = Math.round(img.width / cols);
+  const tileH = Math.round(img.height / (rows * count));
+  const { blocks, warnings } = sliceBlocks(img, layout, count, tileW, tileH);
+  return { layers: blocks, tileW, tileH, cols, rows, warnings };
 }
 
 /**
- * Inverse of subTile: copy a tile's pixels into a sheet at (sx, sy), in place.
- * Mutates `sheet.data` (does NOT change the ImageData identity, so a canonical
- * `state.atlasImage` reference stays valid). Writes only within the tile's rect
- * and clips to the sheet bounds, so remainder pixels of a non-divisible sheet
- * are left untouched.
+ * Copy a tile's pixels into sheet.data at (sx, sy), clipped to the sheet. Mutates
+ * sheet.data in place and returns the same sheet object.
  * @param {{width:number,height:number,data:Uint8ClampedArray|number[]}} sheet
  * @param {{width:number,height:number,data:ArrayLike<number>}} tile
  * @param {number} sx @param {number} sy
@@ -209,11 +226,9 @@ export function blitTile(sheet, tile, sx, sy) {
 }
 
 /**
- * Core tile-pixel placement: copy `tile` into a fresh (newW×newH) buffer with its
- * top-left corner at (offX, offY), padding the uncovered cells transparent and
- * clipping anything outside (so a NEGATIVE offset crops that edge). Pure — returns a
- * fresh tile. The general primitive under both corner-anchored `resizeTile` and the
- * centered whole-atlas resize.
+ * Copy a tile into a new newW × newH tile with its top-left at (offX, offY).
+ * Uncovered texels are transparent and texels outside are clipped, so a negative
+ * offset crops that edge.
  * @param {{width:number,height:number,data:ArrayLike<number>}} tile
  * @param {number} newW @param {number} newH
  * @param {number} offX @param {number} offY
@@ -224,7 +239,7 @@ export function resizeTileTo(tile, newW, newH, offX, offY) {
   const out = new Uint8ClampedArray(newW * newH * 4);
   for (let sy = 0; sy < h; sy++) {
     const dy = sy + offY;
-    if (dy < 0 || dy >= newH) continue; // clipped when shrinking / negative offset
+    if (dy < 0 || dy >= newH) continue;
     for (let sx = 0; sx < w; sx++) {
       const dx = sx + offX;
       if (dx < 0 || dx >= newW) continue;
@@ -240,33 +255,24 @@ export function resizeTileTo(tile, newW, newH, offX, offY) {
 }
 
 /**
- * Resize ONE tile's pixels to (newW,newH), anchoring the existing art at a chosen
- * corner and padding the opposite edges with transparency (or cropping them when
- * shrinking). Pure — returns a fresh tile.
- *
- * The anchor is what keeps a resize alignment-safe: a tile is a literal lattice
- * slice, so to hold a texel's world position we must add/remove lattice lines at
- * the FAR end of each axis and leave the anchored end fixed. `anchorRight`/
- * `anchorBottom` pick which image edge stays put (the rest pad/crop). A thin wrapper
- * over resizeTileTo — a corner is just the offset that puts all pad/crop on one end.
+ * Resize a tile to newW × newH with the art held at one corner, picked by
+ * anchorRight and anchorBottom. The opposite edges pad transparent or crop.
  * @param {{width:number,height:number,data:ArrayLike<number>}} tile
  * @param {number} newW @param {number} newH
  * @param {boolean} anchorRight @param {boolean} anchorBottom
  * @returns {{width:number,height:number,data:Uint8ClampedArray}}
  */
 export function resizeTile(tile, newW, newH, anchorRight, anchorBottom) {
-  const offX = anchorRight ? newW - tile.width : 0; // all pad/crop lands on the far end
+  const offX = anchorRight ? newW - tile.width : 0;
   const offY = anchorBottom ? newH - tile.height : 0;
   return resizeTileTo(tile, newW, newH, offX, offY);
 }
 
 /**
- * How many lattice lines to add (+) or remove (−) at the world-LOW (origin) end of
- * an axis to keep the art CENTERED as a tile resizes; the rest of the change lands
- * at the far end. The odd leftover of an odd-sized change is biased by the parity of
- * the NEW size, so consecutive ±1 steps alternate which end moves and the art can't
- * drift into a corner over repeated clicks (an even change always splits evenly, and
- * a typed jump divides the difference as evenly as it can).
+ * Lattice lines to add (+) or remove (−) at the low (origin) end of an axis to keep
+ * the art centered as a tile resizes. The rest of the change goes to the far end.
+ * The extra line of an odd change follows the parity of the new size, so repeated
+ * ±1 steps alternate ends and the art does not drift.
  *   splitLow(4,5)=1  splitLow(5,6)=0   grow: alternate the extra line
  *   splitLow(4,6)=1                    even grow: one line each end
  *   splitLow(5,4)=0  splitLow(4,3)=−1  shrink: alternate the cropped line
@@ -281,78 +287,66 @@ export function splitLow(oldSize, newSize) {
 }
 
 /**
- * Resize the whole 3x2 sheet to new per-tile dimensions. Each cell's tile is placed
- * with an offset derived from its view's image-axis flips (VIEW_IMAGE_AXES) so every
- * face sharing a world axis shifts IDENTICALLY (registration held) — the padding just
- * lands at a different image edge per face.
+ * Resize a sheet to new tile dimensions. Each tile's offset follows its view's
+ * image-axis flips (VIEW_IMAGE_AXES), so faces that share a world axis shift
+ * together.
+ *
+ * opts.anchor sets where the change goes on each axis:
+ *   'origin' (default): the origin line stays fixed and the far edge moves, so y=0
+ *     stays put.
+ *   'center': the change splits around the art (splitLow). The model translates,
+ *     so a sprite resting on y=0 lifts off it as the tile grows.
  *
- * `opts.anchor` picks how the size change is distributed on each axis:
- *   'origin' (default) — keep the origin line fixed, grow/shrink only at the far edge.
- *     A square resize is fully registration-safe AND keeps the object ground-rested
- *     (y=0 pinned) at its exact lattice coords. Used by the pipeline; the primitive's
- *     stable default (also what the byte-identical-pin test locks).
- *   'center' — split the change around the art on ALL axes (see splitLow) so it stays
- *     centered as the tile grows/shrinks. Still registration-safe for a square resize
- *     (the whole solid just TRANSLATES by the per-axis pad), but it no longer pins y=0,
- *     so a ground-rested sprite floats up as the tile grows. This is what the editor's
- *     tile stepper uses (the author asked for centered artwork).
+ * A square resize keeps registration with either anchor. When newTileW !== newTileH
+ * the depth axis nz gets two sizes (the side tile's width and the top tile's
+ * height), so the carve drops voxels and warns.
  *
- * A PROPORTIONAL (square, newTileW===newTileH) resize keeps registration for either
- * anchor. An ASYMMETRIC resize (newTileW!==newTileH) intentionally falls OUT of
- * registration — a uniform 3x2 atlas has only two tile dimensions but three lattice
- * axes, and the depth axis nz is the side tile's WIDTH and the top tile's HEIGHT at
- * once, so W!=H gives reconcileDims two disagreeing nz candidates: the carve shears
- * the shared depth axis (dropping voxels) and warns. That trade-off is accepted — the
- * editor lets W and H move independently. Pure — returns a fresh sheet.
+ * opts.layers reads the sheet as that many stacked blocks and resizes each one
+ * the same way. Without it the sheet is one block.
  * @param {{width:number,height:number,data:ArrayLike<number>}} img
  * @param {number} newTileW @param {number} newTileH
- * @param {{layout?:string[][], anchor?:'origin'|'center'}} [opts]
+ * @param {{layout?:string[][], anchor?:'origin'|'center', layers?:number}} [opts]
  * @returns {{width:number,height:number,data:Uint8ClampedArray}}
  */
 export function resizeAtlas(img, newTileW, newTileH, opts = {}) {
   const layout = opts.layout || DEFAULT_ATLAS_LAYOUT;
   const center = opts.anchor === 'center';
-  const {
-    cols,
-    rows,
-    tileW: ow,
-    tileH: oh,
-  } = deriveTileSize(img.width, img.height, layout);
-  const oldW = Math.round(ow);
-  const oldH = Math.round(oh);
+  const count = layerOption(opts.layers);
+  const { cols, rows } = layoutSize(layout);
+  const oldW = Math.round(img.width / cols);
+  const oldH = Math.round(img.height / (rows * count));
   const dW = newTileW - oldW;
   const dH = newTileH - oldH;
-  // Per world axis: how many lattice lines to add/crop at the LOW (origin) end.
-  // 'origin' leaves it 0 (all change at the far end); 'center' splits around the art.
+  // Lattice lines to add or crop at each world axis's low end.
   const padLowCol = center ? splitLow(oldW, newTileW) : 0;
   const padLowRow = center ? splitLow(oldH, newTileH) : 0;
   const W = cols * newTileW;
-  const H = rows * newTileH;
+  const H = rows * count * newTileH;
   const sheet = { width: W, height: H, data: new Uint8ClampedArray(W * H * 4) };
-  for (let r = 0; r < rows; r++) {
-    for (let c = 0; c < (layout[r] || []).length; c++) {
-      const name = layout[r][c];
-      if (!name || !VIEW_NAMES.includes(name)) continue;
-      const sx = c * oldW;
-      const sy = r * oldH;
-      if (sx + oldW > img.width || sy + oldH > img.height) continue; // guard a ragged sheet
-      const src = subTile(img, sx, sy, oldW, oldH);
-      const { colFlip, rowFlip } = VIEW_IMAGE_AXES[name];
-      // Map the world-low pad to this face's image corner: a flipped image axis has its
-      // low pixel at the world-HIGH end, so it takes the complementary (far) pad. This
-      // keeps every face on a shared axis moving together. With 'origin' (padLow=0)
-      // this is exactly the old resizeTile(colFlip, rowFlip) corner anchor.
-      const offX = colFlip ? dW - padLowCol : padLowCol;
-      const offY = rowFlip ? dH - padLowRow : padLowRow;
-      const resized = resizeTileTo(src, newTileW, newTileH, offX, offY);
-      blitTile(sheet, resized, c * newTileW, r * newTileH);
+  for (let k = 0; k < count; k++) {
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < (layout[r] || []).length; c++) {
+        const name = layout[r][c];
+        if (!name || !VIEW_NAMES.includes(name)) continue;
+        const sx = c * oldW;
+        const sy = (rows * k + r) * oldH;
+        if (sx + oldW > img.width || sy + oldH > img.height) continue; // ragged sheet
+        const src = subTile(img, sx, sy, oldW, oldH);
+        const { colFlip, rowFlip } = VIEW_IMAGE_AXES[name];
+        // A flipped image axis has its low pixel at the world-high end, so it
+        // takes the far pad.
+        const offX = colFlip ? dW - padLowCol : padLowCol;
+        const offY = rowFlip ? dH - padLowRow : padLowRow;
+        const resized = resizeTileTo(src, newTileW, newTileH, offX, offY);
+        blitTile(sheet, resized, c * newTileW, (rows * k + r) * newTileH);
+      }
     }
   }
   return sheet;
 }
 
 /**
- * Locate a view's grid cell in the layout without duplicating the layout scan.
+ * A view's cell in the layout, or null.
  * @param {string} name
  * @param {string[][]} [layout]
  * @returns {{r:number, c:number} | null}

package/src/carve.js

@@ -1,24 +1,13 @@
-// ---------------------------------------------------------------------------
-// Carve: reconcile grid dimensions from the ingested views, then compute the
-// visual hull = intersection of every provided view's extruded silhouette.
-//
-// Insight that keeps this simple: each view projects onto ONE of three planes
-//   FRONT/BACK -> X-Y,  LEFT/RIGHT -> Z-Y,  TOP/BOTTOM -> X-Z.
-// The two views of a pair produce the same silhouette (mirror images), so for
-// CARVING a single view per plane fully constrains that axis. Mirroring is only
-// needed for COLOR (see colorize.js). So carving is: UNION the views within
-// each plane (opposite silhouettes are identical in theory, so this is robust
-// to a 1-texel registration slip between hand-drawn opposite sprites — see
-// carve()), then AND across the planes. No camera math, no CSG.
-// ---------------------------------------------------------------------------
+// Carve: reconcile the grid dimensions from the views, then compute the visual
+// hull, the intersection of every view's extruded silhouette. Each view projects
+// onto one plane: front/back X-Y, left/right Z-Y, top/bottom X-Z.
 
 import { placeView } from './ingest.js';
 import { VIEWS, VIEW_AXES, FACE_KEYS, FACE_NORMAL } from './views.js';
 
 export const voxIndex = (x, y, z, d) => x + d.nx * (y + d.ny * z);
 
-/** Inverse of voxIndex: linear grid index -> {x,y,z}. Kept next to voxIndex so
- * the forward and inverse packing can't drift. */
+/** Inverse of voxIndex: a linear grid index to {x, y, z}. */
 export const unvoxIndex = (idx, d) => {
   const z = (idx / (d.nx * d.ny)) | 0;
   const rem = idx - z * d.nx * d.ny;
@@ -27,11 +16,8 @@ export const unvoxIndex = (idx, d) => {
 };
 
 /**
- * Reconcile one integer resolution per axis from the (uncropped) tile sizes.
- * For a well-formed sheet every view is the same size, so each axis has a single
- * candidate and the grid is exactly the tile size. Unequal sizes (a malformed
- * sheet, or non-square tiles whose depth differs between side-width and
- * top-height) take the max and warn — the shorter view under-constrains the tail.
+ * One integer resolution per axis from the view sizes. When views disagree on an
+ * axis, the largest wins and a warning is added.
  * @param {Record<string, {w:number,h:number}>} views  provided views by name
  * @returns {{dims:{nx:number,ny:number,nz:number}, warnings:string[]}}
  */
@@ -70,14 +56,8 @@ export function reconcileDims(views) {
 }
 
 /**
- * Place each provided view into the reconciled (imgW,imgH) grid at NATIVE scale
- * and IDENTITY position (offX=offY=0) — strict registration: a tile's texel
- * (u,v) is a fixed lattice line, so it is NOT re-centered or bottom-anchored.
- * For a well-formed (uniform-tile) sheet each view already equals the grid on
- * the axes it constrains, so this is a 1:1 copy. There is no auto ground-rest:
- * where the object sits in Y is wherever the artist painted it (paint at the
- * tile's bottom rows to rest on y=0). A malformed sheet with unequal-size views
- * lands each at the origin and warns (reconcileDims).
+ * Place each view into its imgW × imgH grid at native scale and offset 0. A texel
+ * is a fixed lattice line, so views are not re-centered or ground-rested.
  * @returns {Record<string,{occ:Uint8Array,rgb:Uint32Array,imgW:number,imgH:number}>}
  */
 export function gridViews(views, dims) {
@@ -104,32 +84,21 @@ export function carve(gviews, dims) {
   const { nx, ny, nz } = dims;
   const solid = new Uint8Array(nx * ny * nz).fill(1);
   const active = Object.entries(gviews);
-  // Contract: with no views, nothing carves — the grid stays filled to its
-  // bounding box. reconcileDims defaults every unconstrained axis to 1, so a
-  // fully empty input yields a single solid voxel (pipeline.js warns about it).
+  // No views: nothing carves and the grid stays full.
   if (active.length === 0) return solid;
 
-  // Group the provided views by the projection PLANE they constrain
-  // (front/back -> X-Y, left/right -> Z-Y, top/bottom -> X-Z). A real solid's
-  // two opposite silhouettes are identical, so WITHIN a plane we UNION the
-  // views — a voxel is covered if ANY view on that plane sees it. This is what
-  // the header means by "a single view per plane fully constrains that axis":
-  // the opposite view is redundant for carving, not an extra constraint.
-  // ANDing the pair instead lets a 1-texel registration slip between two
-  // hand-drawn opposite sprites erode thin protrusions — e.g. a car's side
-  // mirror that survives in the top sprite but sits one row over in the bottom
-  // sprite has an empty top∧bottom intersection, so its outer column vanishes.
-  // We then intersect ACROSS the (up to three) planes to get the visual hull.
+  // Views are unioned within a plane, then intersected across planes. The union
+  // keeps a 1-texel slip between opposite hand-drawn sprites from eroding thin
+  // parts.
   const planes = new Map(); // planeKey -> [{spec, occ, imgW}, ...]
   for (const [name, gv] of active) {
-    const key = VIEW_AXES[name].join(); // e.g. 'nx,ny' — one key per plane
+    const key = VIEW_AXES[name].join(); // e.g. 'nx,ny'
     const group = planes.get(key) || planes.set(key, []).get(key);
     group.push({ spec: VIEWS[name], occ: gv.occ, imgW: gv.imgW });
   }
   const planeList = [...planes.values()];
 
-  // One reused scratch for the projection (projectInto mutates it) so the hot
-  // triple loop below allocates nothing per voxel × view.
+  // Reused scratch for projectInto, so the hot loop allocates nothing.
   const p = { u: 0, v: 0 };
   for (let z = 0; z < nz; z++) {
     for (let y = 0; y < ny; y++) {
@@ -155,17 +124,15 @@ export function carve(gviews, dims) {
   return solid;
 }
 
-// 6 axis-neighbor offsets in FACE_KEYS order — the outward normals themselves.
-// Derived from FACE_NORMAL so they can't drift from the face convention.
+// Axis-neighbor offsets in FACE_KEYS order (the outward normals).
 const NEIGHBORS = FACE_KEYS.map((k) => FACE_NORMAL[k]);
 
 /**
- * Extract surface voxels: a solid voxel with >=1 empty/out-of-bounds neighbor.
- * Also tallies the total solid count in the same pass (every voxel is visited and
- * gated on solid here), so the pipeline needn't re-walk the grid a third time.
+ * Surface voxels: solid voxels with at least one empty or out-of-bounds neighbor.
+ * Also counts all solid voxels in the same pass.
  * @returns {{surfaceMask:Uint8Array, count:number, solidCount:number}}
  *   surfaceMask[idx] holds a 6-bit exposure mask (bit i => FACE_KEYS[i] exposed);
- *   count = surface voxels; solidCount = all solid voxels (surface + interior).
+ *   count = surface voxels; solidCount = all solid voxels.
  */
 export function extractSurface(solid, dims) {
   const { nx, ny, nz } = dims;

package/src/colorize.js

@@ -1,23 +1,12 @@
-// ---------------------------------------------------------------------------
-// Colorize: assign a color to every EXPOSED face of every surface voxel.
-//
-// The corrected rule (the naive "stamp one sprite pixel down the whole depth
-// ray" smears color and was rejected):
-//   SURFACE-ONLY, PER-EXPOSED-FACE, DEPTH-AWARE (first-hit), CLOSEST-FACE-NORMAL,
-//   NEAREST-PALETTE.
-//
-// For each exposed face f with outward normal n:
-//   1. Facing view = the view whose normal == n. Sample it ONLY IF this voxel
-//      is the first solid hit marching from that view inward — i.e. nothing
-//      solid lies beyond the face along +n. This is what prevents a recessed
-//      step wall from being painted with the protruding front pixel's color.
-//   2. Else, if mirror-fill is enabled for this face's axis (on by default for
-//      all axes) and the OPPOSITE view exists, sample it mirrored (symmetry).
-//   3. Else relax: average already-assigned neighbor face colors.
-//   4. Else: the object's dominant body color.
-// Every sampled color is snapped to the sprite palette so AA fringe never
-// produces a muddy off-palette pixel.
-// ---------------------------------------------------------------------------
+// Colorize: a color for every exposed face of every surface voxel. For a face with
+// outward normal n, the first of:
+//   1. The facing view, when nothing solid lies beyond the face along n. The depth
+//      test keeps a recessed wall from taking a protruding pixel's color.
+//   2. The opposite view, under the same depth test, when mirror-fill is on for
+//      the face's axis.
+//   3. The average of already-colored neighbor faces.
+//   4. The dominant body color.
+// Sampled and averaged colors snap to the nearest palette color.
 
 import { unpackRGBA, packRGBA } from './ingest.js';
 import { voxIndex, unvoxIndex } from './carve.js';
@@ -31,7 +20,7 @@ import {
 } from './views.js';
 import { DEFAULT_MIRROR } from './constants.js';
 
-/** Build the deduped palette (union of all solid sprite pixels). */
+/** The distinct colors of all solid view texels. */
 export function buildPalette(gviews) {
   const seen = new Set();
   const palette = [];
@@ -51,8 +40,6 @@ export function buildPalette(gviews) {
 
 export function makeSnapper(palette) {
   const cache = new Map();
-  // Unpack each palette entry once (keeping its packed value) instead of
-  // re-splitting bytes on every query iteration.
   const pal = palette.map((c) => ({ c: c >>> 0, ...unpackRGBA(c) }));
   return (color) => {
     const key = color >>> 0;
@@ -73,7 +60,7 @@ export function makeSnapper(palette) {
   };
 }
 
-/** Is `(x,y,z)`'s face `faceKey` the first solid hit from its facing view? */
+/** True when no solid voxel lies beyond face faceKey of (x, y, z) along its normal. */
 function firstHitFromFace(solid, dims, x, y, z, faceKey) {
   const [nx, ny, nz] = FACE_NORMAL[faceKey];
   let cx = x + nx,
@@ -88,8 +75,7 @@ function firstHitFromFace(solid, dims, x, y, z, faceKey) {
   return true;
 }
 
-// One reused scratch — sampleView reads the projection immediately, so mutating a
-// shared object avoids a per-exposed-face allocation.
+// Reused projection scratch. sampleView reads it immediately.
 const _sampleP = { u: 0, v: 0 };
 function sampleView(gv, name, x, y, z, dims) {
   VIEWS[name].projectInto(x, y, z, dims, _sampleP);
@@ -123,8 +109,7 @@ export function colorize(solid, surfaceMask, gviews, dims, opts = {}) {
       const faceKey = FACE_KEYS[f];
       const key = idx * 6 + f;
 
-      // firstHitFromFace is invariant for this face; memoize so the facing and
-      // mirror branches march the depth ray at most once between them.
+      // Memoized so the depth ray is marched at most once per face.
       let firstHit;
       const isFirstHit = () =>
         (firstHit ??= firstHitFromFace(solid, dims, x, y, z, faceKey));
@@ -147,7 +132,7 @@ export function colorize(solid, surfaceMask, gviews, dims, opts = {}) {
     }
   }
 
-  // 3. Relaxation: average already-colored neighbors (few passes).
+  // 3. Relaxation: average already-colored neighbor faces.
   const TANGENTIAL = {
     x: [
       [0, 1, 0],