sprite-machine 0.1.0 → 0.2.0

package/src/node.js

@@ -1,16 +1,11 @@
-// ---------------------------------------------------------------------------
-// The Node adapter (`sprite-machine/node`): a document PNG's bytes in, the
-// pixels and the metadata the app would read from it out — and, in one
-// call, the glb. The engine itself takes pixels and never decodes a file
-// (index.js is environment-free); this is the one place a decoder lives,
-// `pngjs`, which reads every PNG a sprite editor exports — indexed, 16-bit,
-// interlaced — as 8-bit RGBA, the ImageData shape the pipeline consumes.
-// The chunks are read best-effort, as the app's loader reads them: a torn
-// chunk list costs the name and the transforms, never the pixels.
-// ---------------------------------------------------------------------------
+// Node adapter (sprite-machine/node): decodes a document PNG to RGBA pixels
+// and its metadata, or straight to a glb. The only PNG decoder in the engine
+// (pngjs). Text chunks are read best-effort: a malformed chunk list loses the
+// name, transforms and layer names but not the pixels.
 
 import { PNG } from 'pngjs';
 import { isPng, readTextChunks } from './png-chunks.js';
+import { LAYERS_CHUNK, parseLayersChunk, layerCount } from './layers.js';
 import { buildModel, modelToGlb } from './model.js';
 
 const TRANSFORMS_CHUNK = 'sprite-machine:transforms';
@@ -22,10 +17,10 @@ const TRANSFORMS_CHUNK = 'sprite-machine:transforms';
  *   image: {width:number, height:number, data:Uint8ClampedArray},
  *   name: string|null,
  *   transforms: Record<string, {rot?:number, flipX?:boolean, flipY?:boolean}>,
+ *   layers: string[]|null,
  *   chunks: Record<string, string>,
- * }}  the pixels; the Title chunk's name; the transforms chunk, parsed; and
- *   every text chunk verbatim (the ring settings ride here, unparsed — a
- *   viewing choice, the app's business)
+ * }}  the pixels, the Title chunk, the parsed transforms chunk, the layer
+ *   names from the sprite-machine:layers chunk, and every text chunk verbatim
  * @throws when the bytes are not a PNG, or pngjs cannot decode them
  */
 export function readSheet(bytes) {
@@ -54,19 +49,30 @@ export function readSheet(bytes) {
       transforms = {};
     }
   }
-  return { image, name: chunks.Title ?? null, transforms, chunks };
+  return {
+    image,
+    name: chunks.Title ?? null,
+    transforms,
+    layers: parseLayersChunk(chunks[LAYERS_CHUNK]),
+    chunks,
+  };
 }
 
 /**
- * A document PNG's bytes → its glb: `readSheet`, `buildModel`, `modelToGlb`.
+ * Convert a document PNG to a glb: readSheet, buildModel, then modelToGlb. The
+ * sheet builds the layers chunk's count when it divides the height into whole
+ * blocks, else one layer.
  * @param {Uint8Array} bytes
  * @param {{name?: string, voxelsPerMeter?: number, unlit?: boolean, generator?: string}} [opts]
- *   `name` overrides the Title chunk's; with neither, the model is 'sprite'
+ *   `name` overrides the Title chunk; with neither, the name is 'sprite'
  * @returns {Uint8Array}  the .glb file
  */
 export function sheetToGlb(bytes, { name, voxelsPerMeter, unlit, generator } = {}) {
   const sheet = readSheet(bytes);
-  const model = buildModel(sheet.image, { transforms: sheet.transforms });
+  const model = buildModel(sheet.image, {
+    transforms: sheet.transforms,
+    layers: layerCount(sheet.image.height, sheet.layers) ?? 1,
+  });
   return modelToGlb(model, {
     name: name ?? sheet.name ?? 'sprite',
     voxelsPerMeter,

package/src/pipeline.js

@@ -1,13 +1,19 @@
-// ---------------------------------------------------------------------------
-// The pure sprite -> voxel pipeline. No THREE, no DOM: fully testable in Node.
-// Input: a map of view name -> ImageData-like { width, height, data(RGBA) }.
-// Output: the voxel grid, surface, and per-face colors, ready for meshing.
-// ---------------------------------------------------------------------------
+// The sprite-to-voxel pipeline. No THREE or DOM.
+// Input: view name -> ImageData-like { width, height, data (RGBA) }.
+// Output: the voxel grid, surface and per-face colors for meshing. A layered
+// sheet builds each layer on its own, and unionVoxels merges the results.
 
 import { ingestSprite, applyTransform } from './ingest.js';
-import { reconcileDims, gridViews, carve, extractSurface } from './carve.js';
+import {
+  reconcileDims,
+  gridViews,
+  carve,
+  extractSurface,
+  voxIndex,
+  unvoxIndex,
+} from './carve.js';
 import { colorize } from './colorize.js';
-import { VIEW_NAMES } from './views.js';
+import { VIEW_NAMES, VIEW_AXES, FACE_TO_VIEW, faceKeyOf } from './views.js';
 
 /**
  * @param {Record<string, {width:number,height:number,data:ArrayLike<number>}|null>} rawViews
@@ -32,8 +38,6 @@ export function buildVoxels(rawViews, opts = {}) {
   }
   const gviews = gridViews(ingested, dims);
   const solid = carve(gviews, dims);
-  // extractSurface already visits + gates every voxel on `solid`, so it returns
-  // solidCount too (no separate full-grid pass needed here).
   const { surfaceMask, count, solidCount } = extractSurface(solid, dims);
   const { faceColor, palette } = colorize(solid, surfaceMask, gviews, dims, opts);
   if (palette.length === 0 && Object.keys(ingested).length > 0) {
@@ -54,3 +58,114 @@ export function buildVoxels(rawViews, opts = {}) {
     providedViews: Object.keys(ingested),
   };
 }
+
+/** @typedef {ReturnType<typeof buildVoxels>} VoxelResult */
+
+// Each lattice axis: its dims key and its world axis.
+const AXES = /** @type {const} */ ([
+  ['nx', 'x'],
+  ['ny', 'y'],
+  ['nz', 'z'],
+]);
+
+// Where a layer's lattice starts in the union's. An axis none of the layer's
+// views observes is one voxel deep, and sits at the far end when the layer
+// has the view of that axis's positive face (left, top or front), else at 0.
+// Every other axis starts at 0.
+function layerOffset(r, dims) {
+  const off = { x: 0, y: 0, z: 0 };
+  for (const [dim, axis] of AXES) {
+    const observed = r.providedViews.some((v) => VIEW_AXES[v].includes(dim));
+    const positive = FACE_TO_VIEW[faceKeyOf(axis, 1)];
+    if (!observed && r.providedViews.includes(positive)) {
+      off[axis] = dims[dim] - r.dims[dim];
+    }
+  }
+  return off;
+}
+
+/**
+ * Merge per-layer buildVoxels results into one model.
+ *   - A layer with no provided view is dropped, warnings included.
+ *   - The lattice is the per-axis max of the kept layers' dims, each layer placed
+ *     by layerOffset. A voxel is solid when any layer holds it, and the surface
+ *     is extracted from that solid.
+ *   - An exposed face takes its color from the last layer in block order that
+ *     holds its voxel. The face is exposed in that layer too, so it has one.
+ *   - The palette is the union of the layers'. Warnings are prefixed "Layer k:".
+ *     `layers` holds the results, null where dropped.
+ * One result, or none with a provided view, returns the first result untouched.
+ * No results is one empty layer.
+ * @param {VoxelResult[]} results  one per layer, in block order
+ */
+export function unionVoxels(results) {
+  if (results.length === 0) return buildVoxels({});
+  const kept = results.map((r) => (r.providedViews.length > 0 ? r : null));
+  const live = kept.filter((r) => r != null);
+  if (results.length === 1 || live.length === 0) return results[0];
+
+  const dims = { nx: 1, ny: 1, nz: 1 };
+  for (const r of live) {
+    for (const [dim] of AXES) dims[dim] = Math.max(dims[dim], r.dims[dim]);
+  }
+  const placed = live.map((r) => ({ r, off: layerOffset(r, dims) }));
+
+  const n = dims.nx * dims.ny * dims.nz;
+  const solid = new Uint8Array(n);
+  // 1 + the index in `placed` of the last layer holding each voxel, 0 for none.
+  const owner = new Uint16Array(n);
+  placed.forEach(({ r, off }, i) => {
+    const d = r.dims;
+    for (let z = 0; z < d.nz; z++) {
+      for (let y = 0; y < d.ny; y++) {
+        for (let x = 0; x < d.nx; x++) {
+          if (!r.solid[voxIndex(x, y, z, d)]) continue;
+          const u = voxIndex(x + off.x, y + off.y, z + off.z, dims);
+          solid[u] = 1;
+          owner[u] = i + 1;
+        }
+      }
+    }
+  });
+
+  const { surfaceMask, count, solidCount } = extractSurface(solid, dims);
+  /** @type {Map<number, number>} */
+  const faceColor = new Map();
+  for (let idx = 0; idx < n; idx++) {
+    const mask = surfaceMask[idx];
+    if (!mask) continue;
+    const { r, off } = placed[owner[idx] - 1];
+    const p = unvoxIndex(idx, dims);
+    const local = voxIndex(p.x - off.x, p.y - off.y, p.z - off.z, r.dims) * 6;
+    for (let f = 0; f < 6; f++) {
+      if (mask & (1 << f)) faceColor.set(idx * 6 + f, r.faceColor.get(local + f));
+    }
+  }
+
+  return {
+    dims,
+    solid,
+    surfaceMask,
+    surfaceCount: count,
+    solidCount,
+    faceColor,
+    palette: [...new Set(live.flatMap((r) => r.palette))],
+    warnings: kept.flatMap((r, k) =>
+      r ? r.warnings.map((w) => `Layer ${k + 1}: ${w}`) : []
+    ),
+    providedViews: VIEW_NAMES.filter((v) =>
+      live.some((r) => r.providedViews.includes(v))
+    ),
+    layers: kept,
+  };
+}
+
+/**
+ * buildVoxels for each layer's views, then unionVoxels.
+ * @param {Record<string, {width:number,height:number,data:ArrayLike<number>}|null>[]} rawViewsByLayer
+ *   one views record per layer, in block order
+ * @param {Parameters<typeof buildVoxels>[1]} [opts]  applied to every layer
+ */
+export function buildLayeredVoxels(rawViewsByLayer, opts = {}) {
+  return unionVoxels(rawViewsByLayer.map((raw) => buildVoxels(raw, opts)));
+}

package/src/png-chunks.js

@@ -1,21 +1,11 @@
-// ---------------------------------------------------------------------------
-// PNG chunk surgery — the document format's foundation (a Sprite Machine
-// document IS one .png with its metadata in standard text chunks). Pure
-// typed-array code, zero deps, Node-tested like the rest of lib/.
+// PNG chunk reading and writing. A document is one .png with its metadata in
+// text chunks.
 //
-// A PNG is an 8-byte signature plus a chunk list; each chunk is
-//   length(4, big-endian) | type(4, ASCII) | data(length) | crc(4, over
-//   type+data). Ancillary text chunks (tEXt: Latin-1, iTXt: UTF-8) are
-//   standard, ignored by every decoder, and legal anywhere between IHDR and
-//   IEND — we splice ours right after IHDR (before the first IDAT), so a
-//   metadata read never has to scan past the pixel data.
-//
-// Reading and writing both handle tEXt AND iTXt; the writer picks tEXt when
-// the text survives Latin-1 and iTXt (UTF-8, uncompressed) otherwise, so a
-// plain ASCII Software tag stays the classic chunk while an emoji title still
-// round-trips. Compressed text chunks (zTXt / iTXt with the compression flag)
-// are passed through untouched but not decoded — nothing we write uses them.
-// ---------------------------------------------------------------------------
+// A PNG is an 8-byte signature and a chunk list. Each chunk is
+//   length (4, big-endian) | type (4, ASCII) | data | crc (4, over type + data).
+// Text chunks are written right after IHDR, before the first IDAT. The writer
+// uses tEXt when the text is Latin-1 and uncompressed iTXt (UTF-8) otherwise.
+// Compressed text chunks (zTXt, compressed iTXt) pass through undecoded.
 
 /** The 8-byte PNG signature. */
 export const PNG_SIGNATURE = Uint8Array.of(
@@ -38,7 +28,7 @@ export function isPng(bytes) {
   return true;
 }
 
-// --- CRC32 (the PNG polynomial), table built once ---------------------------
+// CRC32 lookup table for the PNG polynomial.
 const CRC_TABLE = (() => {
   const t = new Uint32Array(256);
   for (let n = 0; n < 256; n++) {
@@ -49,7 +39,7 @@ const CRC_TABLE = (() => {
   return t;
 })();
 
-/** CRC32 of a byte range (PNG flavor: over the chunk's type + data). @param {Uint8Array} bytes */
+/** CRC32 of a byte range (PNG runs it over type + data). @param {Uint8Array} bytes */
 export function crc32(bytes) {
   let c = 0xffffffff;
   for (let i = 0; i < bytes.length; i++) {
@@ -64,11 +54,9 @@ const readU32 = (b, i) =>
 const typeAt = (b, i) => String.fromCharCode(b[i], b[i + 1], b[i + 2], b[i + 3]);
 
 /**
- * Parse the chunk list. Each entry's `data` is a SUBARRAY view into `bytes`
- * (no copies); `offset` is the chunk's start (the length field) and `end` one
- * past its CRC, so `bytes.subarray(offset, end)` is the whole chunk verbatim.
- * Throws on a non-PNG signature or a truncated chunk (a torn file should fail
- * loudly, not yield half a list).
+ * Parse the chunk list. Each entry's `data` is a subarray of `bytes`, `offset`
+ * is the chunk's start and `end` is one past its CRC. Throws on a bad
+ * signature or a truncated chunk.
  *
  * @param {Uint8Array} bytes
  * @returns {{type:string, data:Uint8Array, offset:number, end:number}[]}
@@ -90,7 +78,7 @@ export function readChunks(bytes) {
   return chunks;
 }
 
-// --- text codecs ------------------------------------------------------------
+// Text codecs.
 const latin1Encodable = (s) => {
   for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0xff) return false;
   return true;
@@ -108,8 +96,7 @@ const latin1String = (b) => {
 const utf8Bytes = (s) => new TextEncoder().encode(s);
 const utf8String = (b) => new TextDecoder().decode(b);
 
-/** Serialize one chunk: length | type | data | crc(type+data). Exported for
- *  the encoder (png-encode.js), which frames IHDR / IDAT / IEND through it.
+/** Serialize one chunk: length | type | data | crc(type+data).
  *  @param {string} type  @param {Uint8Array} data */
 export function buildChunk(type, data) {
   const out = new Uint8Array(8 + data.length + 4);
@@ -131,20 +118,19 @@ function buildTextChunk(keyword, text) {
   return buildChunk('tEXt', data);
 }
 
-/** An iTXt chunk, uncompressed: keyword | 0 | 0 | 0 | lang… | 0 | xlat… | 0 | UTF-8 text. */
+/** An uncompressed iTXt chunk: keyword | 0 | 0 | 0 | lang | 0 | xlat | 0 | UTF-8 text. */
 function buildItxtChunk(keyword, text) {
   const kw = latin1Bytes(keyword);
   const tx = utf8Bytes(text);
   const data = new Uint8Array(kw.length + 5 + tx.length);
   data.set(kw, 0);
-  // keyword NUL, compression flag 0, compression method 0, empty language tag
-  // NUL, empty translated keyword NUL — five zero bytes in a row.
+  // The five bytes after the keyword stay zero: its NUL, the compression flag
+  // and method, and the NULs ending the empty language tag and translated keyword.
   data.set(tx, kw.length + 5);
   return buildChunk('iTXt', data);
 }
 
-// Decode one parsed text chunk to {keyword, text}, or null for a chunk we
-// don't decode (compressed variants pass through unread).
+// Decode a text chunk to {keyword, text}, or null when it is compressed.
 function decodeTextChunk(chunk) {
   const d = chunk.data;
   const nul = d.indexOf(0);
@@ -155,7 +141,7 @@ function decodeTextChunk(chunk) {
   }
   // iTXt: compressionFlag(1) compressionMethod(1) lang\0 translated\0 text
   const flag = d[nul + 1];
-  if (flag !== 0) return null; // compressed — not ours, leave it be
+  if (flag !== 0) return null; // compressed
   let i = nul + 3;
   while (i < d.length && d[i] !== 0) i++; // language tag
   i++;
@@ -165,11 +151,8 @@ function decodeTextChunk(chunk) {
 }
 
 /**
- * Every decodable text entry in the file, in chunk order, as
- * `{keyword: text}` — a later duplicate keyword wins (we never write
- * duplicates; a foreign file's are read leniently). A chunk scan stops
- * before IDAT costs nothing: our own writer puts every text chunk ahead of
- * the pixel data, but a foreign file's trailing chunks are read too.
+ * Every decodable text chunk as `{keyword: text}`, including chunks after
+ * IDAT. A later duplicate keyword wins.
  *
  * @param {Uint8Array} bytes
  * @returns {Record<string, string>}
@@ -186,13 +169,10 @@ export function readTextChunks(bytes) {
 }
 
 /**
- * Return a NEW file with `entries` written as text chunks: any existing
- * tEXt/iTXt chunk whose keyword appears in `entries` is removed (replace
- * semantics), the new chunks are spliced immediately after IHDR, and every
- * other chunk — critical or ancillary, known or unknown — passes through
- * byte-for-byte. An entry whose value is `null`/`undefined` just removes the
- * keyword. Insertion order follows `entries`' key order, so a rewrite is
- * deterministic.
+ * Return a new file with `entries` written as text chunks. Existing text
+ * chunks with those keywords are removed, the new chunks go right after IHDR
+ * in key order, and every other chunk is copied byte for byte. A null or
+ * undefined value only removes the keyword.
  *
  * @param {Uint8Array} bytes
  * @param {Record<string, string|null|undefined>} entries
@@ -202,7 +182,7 @@ export function setTextChunks(bytes, entries) {
   const chunks = readChunks(bytes);
   const replaced = new Set(Object.keys(entries));
 
-  /** @type {Uint8Array[]} the output's chunk byte-runs, in order */
+  /** @type {Uint8Array[]} output chunks, in order */
   const parts = [];
   const fresh = [];
   for (const [keyword, text] of Object.entries(entries)) {

package/src/png-encode.js

@@ -1,28 +1,18 @@
-// ---------------------------------------------------------------------------
-// A PNG ENCODER from bytes — 8-bit RGBA, non-interlaced, every row filter 0,
-// the pixel stream in a zlib container of STORED deflate blocks (no
-// compression) — so an image the app already holds as bytes becomes a file
-// without a canvas. File → Export 3D Model… embeds the skin texture this
-// way: a privacy browser's canvas farble (the readback perturbation that
-// once tripped the wedge gate) never sees it, and the file's texels are the
-// skin's, verbatim. Pure, zero deps, Node-tested against node:zlib's own
-// inflate. (The document PNGs still go through the canvas codec in
-// image-io.js — a document is the canvas's pixels; this is for bytes.)
+// PNG encoder from bytes: 8-bit RGBA, non-interlaced, filter 0 on every row,
+// the pixel stream in stored (uncompressed) deflate blocks. It encodes the
+// skin for glb export without a canvas, because privacy browsers perturb
+// canvas readback.
 //
-// Stored blocks cost nothing but size: a skin is a few kilobytes (64 × 64 ×
-// 4 is sixteen), and the glb it lands in is not a network asset. The zlib
-// framing: the two-byte header (CMF 0x78, FLG 0x01 — deflate, a 32K window,
-// no dictionary, "fastest" flagged; the pair's check passes), then up to
-// 65535 bytes per block behind a five-byte block header (BFINAL on the
-// last, BTYPE 00, LEN, then NLEN its one's complement), then the Adler-32
-// of the raw stream, big-endian.
-// ---------------------------------------------------------------------------
+// zlib framing: the header CMF 0x78, FLG 0x01 (a pair that passes the header
+// check), then blocks of up to 65535 bytes, each behind a 5-byte header
+// (BFINAL, BTYPE 00, LEN, NLEN = ~LEN), then the Adler-32 of the raw stream,
+// big-endian.
 
 import { PNG_SIGNATURE, buildChunk } from './png-chunks.js';
 
 const BLOCK = 65535;
 
-/** Adler-32 of a byte string — the zlib trailer. @param {Uint8Array} bytes */
+/** Adler-32 checksum, the zlib trailer. @param {Uint8Array} bytes */
 export function adler32(bytes) {
   let a = 1;
   let b = 0;
@@ -56,7 +46,7 @@ export function zlibStored(raw) {
 }
 
 /**
- * Encode an RGBA image as a PNG file: row 0 the top row, four bytes a texel.
+ * Encode an RGBA image as a PNG file. Row 0 is the top row.
  * @param {{width:number, height:number, data:Uint8Array|Uint8ClampedArray}} img
  * @returns {Uint8Array}
  */
@@ -70,7 +60,7 @@ export function encodePng({ width, height, data }) {
   const stride = width * 4;
   const raw = new Uint8Array((stride + 1) * height);
   for (let y = 0; y < height; y++) {
-    raw[y * (stride + 1)] = 0; // the row's filter: none
+    raw[y * (stride + 1)] = 0; // filter type: none
     raw.set(data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
   }
   const ihdr = new Uint8Array(13);
@@ -79,7 +69,7 @@ export function encodePng({ width, height, data }) {
   iv.setUint32(4, height);
   ihdr[8] = 8; // bit depth
   ihdr[9] = 6; // color type: RGBA
-  // compression 0, filter 0, interlace 0 — the zeros the array was born with
+  // compression, filter and interlace stay 0
   const parts = [
     PNG_SIGNATURE,
     buildChunk('IHDR', ihdr),

package/src/regions.js

@@ -1,38 +1,21 @@
-// ---------------------------------------------------------------------------
-// Coplanar REGIONS: the union of one plane's exposed unit faces and the gable
-// cap half-faces the wedge blocks end on, traced as boundary loops on the
-// lattice with every collinear run merged — so a wall beside a 45° slope has
-// ONE straight diagonal edge where a stack of rectangles plus a sawtooth of
-// gable triangles had a vertex at every step, each pinning a vertex on the
-// slope that the T-junction repair then had to split the slope at. Pure 2D
-// lattice work, no THREE, Node-tested; the triangulation of a region (earcut,
-// through THREE's ShapeUtils) is the mesher's (wedge-mesh.js).
+// Coplanar regions: one plane's exposed unit faces plus the gable-cap half
+// faces of the wedge blocks, traced as boundary loops with collinear runs
+// merged. A wall beside a 45° slope gets one straight diagonal edge, so no
+// vertices land on the slope. wedge-mesh.js triangulates the regions.
 //
-// Pieces on one plane, in the face's tangent coordinates (a along
-// FACE_GEO[face].A, b along .B): a CELL is the unit square [a, a+1] × [b, b+1]
-// — an exposed voxel face; a HALF is the right triangle in that square whose
-// right angle sits at the corner (a + hiA, b + hiB) — a gable cap, the
-// prism's cross-section. Every piece carries its packed colour: a face's from
-// colorize, a cap's the wedge's. A texel per piece is a texel per unit
-// square, the skin's orientation rule (skin.js).
+// Pieces use the face's tangent coordinates: a along FACE_GEO[face].A, b along
+// .B. A cell is the unit square [a, a+1] × [b, b+1]. A half is the right
+// triangle in that square with its right angle at (a + hiA, b + hiB). Each
+// piece carries a packed color.
 //
-// The trace: every piece contributes its directed edges, CCW in (a, b); an
-// edge whose reverse another piece contributes is interior and cancels; the
-// survivors are chained by the KEEP-LEFT rule — at a vertex with several ways
-// on, the sharpest left turn — which pairs each arriving edge with the one
-// leaving along its own sector of the region. So two cells that meet only at
-// a corner are two loops (two regions, as they should be), while a bay that
-// opens onto the outside through a corner rides the outer loop through that
-// corner twice, and two holes meeting at a corner ride one hole loop twice:
-// a self-touching ring, the very shape earcut builds when it bridges a hole
-// into the outer, and one its ear test handles by design (the zero-length
-// diagonal case); the mesher asserts every region triangulates to its full
-// area. A loop with positive signed area is an OUTER, negative a HOLE. A hole
-// and a piece belong to the smallest outer containing a point of theirs (a
-// piece's centroid, a point a quarter-cell inside a hole's first edge —
-// neither ever on a lattice line or a diagonal a piece can have), so an
-// island inside a hole is its own region.
-// ---------------------------------------------------------------------------
+// Trace: each piece adds its directed edges, CCW in (a, b). An edge whose
+// reverse is also present is interior and cancels. The remaining edges chain
+// by the keep-left rule, taking the sharpest left turn at each vertex. Two
+// cells that touch only at a corner form two loops. A loop can pass through a
+// corner twice, which earcut handles. A loop with positive signed area is an
+// outer, negative a hole. Holes and pieces belong to the smallest outer that
+// contains a test point: a piece's centroid, or a point a quarter cell inside
+// a hole's first edge. Neither can lie on a lattice line or a piece's diagonal.
 
 import { FACE_KEYS, FACE_NORMAL } from './views.js';
 import { FACE_GEO, idxFor } from './faces.js';
@@ -43,15 +26,15 @@ import { FACE_GEO, idxFor } from './faces.js';
  * @typedef {number[][]} Loop  vertices [a, b] in order, the closing vertex not repeated
  * @typedef {{outer:Loop, holes:Loop[], a:number, b:number, w:number, h:number,
  *            texels:Uint32Array, present:Uint8Array, uniform:number|null, area2:number}} Region2D
- *   a region: its loops, its bounding box (a, b, w, h) in cells, a texel per
- *   box cell (`present` marks the pieces'), its one colour or null, and
- *   twice its area (a cell 2, a half 1).
+ *   loops, bounding box (a, b, w, h) in cells, a texel per box cell (`present`
+ *   marks the pieces), the single color or null, and twice the area (a cell 2,
+ *   a half 1).
  * @typedef {Region2D & {face:string, s:number, normal:number[]}} Region
  */
 
 const DIM = (dims, axis) => dims['n' + axis];
 
-/** Twice the signed area of a polygon (shoelace); positive is CCW. @param {number[][]} poly */
+/** Twice the signed area (shoelace). Positive is CCW. @param {number[][]} poly */
 function area2(poly) {
   let s = 0;
   for (let i = 0; i < poly.length; i++) {
@@ -62,7 +45,7 @@ function area2(poly) {
   return s;
 }
 
-/** Even-odd point-in-polygon; the ray is horizontal, and no test point here has an integer y. */
+/** Even-odd point-in-polygon, horizontal ray. Test points never have an integer y. */
 function inside(poly, x, y) {
   let c = false;
   for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
@@ -73,7 +56,7 @@ function inside(poly, x, y) {
   return c;
 }
 
-/** Drop the vertices a ring runs straight through. Ring edges are unit steps, so a step's sign is its direction. */
+/** Drop collinear vertices. Edges are unit steps, so a step's sign is its direction. */
 function dropCollinear(ring) {
   const n = ring.length;
   const out = [];
@@ -134,7 +117,7 @@ export function traceRegions(cells, halves) {
     });
   }
 
-  // 1. directed edges; one whose reverse is present is interior and cancels
+  // 1. Directed edges. An edge whose reverse is present is interior.
   const ekey = (p, q) => p[0] + ',' + p[1] + '>' + q[0] + ',' + q[1];
   /** @type {Map<string, {p:number[], q:number[]}>} */
   const edges = new Map();
@@ -149,7 +132,7 @@ export function traceRegions(cells, halves) {
   const boundary = [];
   for (const e of edges.values()) if (!edges.has(ekey(e.q, e.p))) boundary.push(e);
 
-  // 2. the keep-left successor of every boundary edge
+  // 2. The keep-left successor of each boundary edge.
   const vkey = (p) => p[0] + ',' + p[1];
   /** @type {Map<string, {p:number[], q:number[]}[]>} */
   const outAt = new Map();
@@ -177,7 +160,7 @@ export function traceRegions(cells, halves) {
     next.set(e, best);
   }
 
-  // 3. the loops: the cycles of the successor map
+  // 3. Loops: the cycles of the successor map.
   const seen = new Set();
   /** @type {Loop[]} */
   const loops = [];
@@ -194,7 +177,7 @@ export function traceRegions(cells, halves) {
     loops.push(dropCollinear(ring));
   }
 
-  // 4. outers and holes; each hole and each piece to the innermost outer around it
+  // 4. Outers and holes. Each hole and piece goes to the innermost outer around it.
   /** @type {Loop[]} */
   const outers = [];
   /** @type {Loop[]} */
@@ -210,8 +193,8 @@ export function traceRegions(cells, halves) {
     const [p, q] = h;
     const dx = Math.sign(q[0] - p[0]);
     const dy = Math.sign(q[1] - p[1]);
-    // a quarter-cell to the RIGHT of the hole's first edge: the region is on
-    // the left of every loop, so the right is the hole's own emptiness
+    // A quarter cell to the right of the hole's first edge is inside the hole,
+    // since the region lies to the left of every loop.
     groups[
       owner((p[0] + q[0]) / 2 + 0.25 * dy, (p[1] + q[1]) / 2 - 0.25 * dx)
     ].holes.push(h);
@@ -259,12 +242,12 @@ export function traceRegions(cells, halves) {
   });
 }
 
-/** The key a plane's halves are filed under: a face key at a slice. */
+/** The map key for a plane: a face key and a slice. */
 export const planeKey = (face, s) => face + '|' + s;
 
 /**
- * The regions of every plane of the surface: the exposed faces of `surfaceMask`
- * (coloured by `faceColor`, keyed idx*6 + f) plus the halves filed per plane.
+ * The regions of every surface plane: the exposed faces in `surfaceMask`,
+ * colored by `faceColor` (keyed idx*6 + f), plus each plane's halves.
  * @param {{nx:number, ny:number, nz:number}} dims
  * @param {Uint8Array} surfaceMask
  * @param {Map<number, number>} faceColor