sprite-machine 0.1.0 → 0.2.0

package/src/skin.js

@@ -1,48 +1,25 @@
-// ---------------------------------------------------------------------------
-// The skin: the model's color as a TEXTURE, so the mesher can merge on
-// occupancy alone (regions.js). Pure — no THREE, no canvas — and Node-tested;
-// mesh-util.js turns the bytes into the DataTexture the material samples.
+// The skin: the model's color as a texture, so the mesher can merge faces on
+// occupancy alone (regions.js). mesh-util.js turns the bytes into a
+// DataTexture.
 //
-// What is in it. A region whose pieces are NOT all one color becomes a
-// CHART: the region's bounding box as texels, one per cell, holding its
-// pieces' colors verbatim — a face's, or a gable cap's wedge color — padded
-// by one texel on every side (the gutter) and with every texel the pieces do
-// not cover (the gutter, a hole, the box outside a diagonal edge) filled
-// from the NEAREST piece texel, a breadth-first flood from the pieces
-// outward: a fragment on the region's edge that rounds to the neighbouring
-// texel still reads its own color, and an importer with bilinear filtering
-// on gets no bleed. A region of one color — every one-color wall, every
-// solid cube's face — gets no chart: its triangles point at the SWATCH
-// STRIP, one 1×1 chart per distinct color (the palette, plus anything the
-// faces actually hold), sampled at the texel's center — one texel read at
-// its middle needs no gutter. A wedge's slope is one material by the gate,
-// so it points at a swatch too. The skin is therefore only the regions that
-// cross a color, plus the strip — a fraction of "every exposed face" — and
-// its size is bounded by the multi-color regions' boxes, never by the grid.
+// A region with more than one color gets a chart: its bounding box at one
+// texel per cell, padded by a one-texel gutter. Texels no piece covers (the
+// gutter, holes, the box outside a diagonal edge) take the nearest piece's
+// color by a breadth-first flood, so edge fragments and bilinear filtering
+// read the region's own colors. A one-color region, and every wedge slope,
+// samples a 1×1 swatch at its texel center. There is one swatch per color.
 //
-// Packing is a shelf packer, deterministic (the goldens depend on it): the
-// padded charts sorted by height then width, descending, laid left to right
-// on shelves, the swatches after them. The width starts at the smallest
-// power of two holding the widest padded chart (16 at least) and doubles
-// while the packed height, rounded up to a power of two, would exceed it —
-// no ceiling (a skin past a device's texture limit is a sprite the carve
-// could not have rebuilt live either). Power-of-two sides are not required
-// by three or by WebGL2; exporters and older engines are happier with them,
-// and it costs nothing here.
+// Packing: padded charts sorted by height then width, descending, on
+// left-to-right shelves, then the swatches. The width starts at the smallest
+// power of two that fits the widest chart (at least 16) and doubles while the
+// packed height, rounded up to a power of two, exceeds it.
 //
-// Orientation is stated ONCE: a chart's texel (i, j) is the cell at tangent
-// (a + i, b + j) of the region's box — i along FACE_GEO[face].A, j along .B —
-// and a vertex's UV is the same affine read of its lattice position
-// (uvOfLattice). There is no per-face flip table, so nothing can drift; if a
-// face ever renders mirrored the bug is in the corner-to-UV read, not the
-// bake. The texture's row 0 is v = 0 (DataTexture's flipY is false) — leave
-// it there.
+// Orientation: chart texel (i, j) is the cell at tangent (a + i, b + j) of the
+// region's box, i along FACE_GEO[face].A and j along .B. A vertex's UV is the
+// same affine map of its lattice position (uvOfLattice). Texture row 0 is v = 0.
 //
-// Built from bytes: the packed colors are written straight into the RGBA
-// array. No 2D canvas, no getImageData, so a privacy browser's canvas farble
-// (the Helium bug, wedge-mesh.test.mjs) cannot touch it. Keep it that way:
-// no canvas in this file, ever.
-// ---------------------------------------------------------------------------
+// The RGBA bytes are written directly. Do not use a canvas here: privacy
+// browsers perturb getImageData.
 
 import { FACE_GEO } from './faces.js';
 import { unpackRGBA } from './ingest.js';
@@ -50,11 +27,11 @@ import { AXIS_INDEX } from './views.js';
 
 /**
  * @typedef {{u0:number, v0:number, w:number, h:number}} Chart
- *   a charted region's texels, in texel coords, the gutter excluded.
+ *   a chart's texel rect, excluding the gutter.
  * @typedef {{width:number, height:number, data:Uint8Array,
  *            charts:(Chart|null)[], swatch:Map<number, {u:number, v:number}>}} Skin
- *   charts[i] is regions[i]'s chart — null where the region is one color (a
- *   swatch); swatch maps a packed color to its 1×1 chart's texel.
+ *   charts[i] is regions[i]'s chart, or null for a one-color region. swatch
+ *   maps a packed color to its texel.
  */
 
 const GUTTER = 1;
@@ -66,9 +43,8 @@ const pow2ceil = (n) => {
   return p;
 };
 
-// Lay `items` (each {pw, ph}, padded sizes) on shelves of `width`, left to
-// right, a new shelf when the row is full. Every item is narrower than the
-// width by construction. Returns the packed height and each item's origin.
+// Pack `items` ({pw, ph}, padded sizes) left to right on shelves of `width`.
+// Every item fits the width. Returns the packed height and each item's origin.
 function shelfPack(items, width) {
   const at = new Array(items.length);
   let x = 0,
@@ -87,10 +63,9 @@ function shelfPack(items, width) {
   return { height: y + shelf, at };
 }
 
-// The padded box of a region as texel colors: the pieces' own, and every
-// other texel — gutter, hole, the box beyond a diagonal — the color of the
-// nearest piece texel, a multi-source breadth-first flood (deterministic:
-// the pieces seed in row order, the four neighbours in a fixed order).
+// A region's padded box as texel colors. Uncovered texels take the nearest
+// piece texel's color by a multi-source breadth-first flood. Seeds go in row
+// order and neighbors in a fixed order, so the result is deterministic.
 function floodBox(region) {
   const { w, h, texels, present } = region;
   const W = w + 2 * GUTTER;
@@ -126,13 +101,12 @@ function floodBox(region) {
  * Bake the skin for a mesh: a chart per multi-color region, a swatch per color.
  * @param {import('./regions.js').Region2D[]} regions  the base regions, in emit order
  * @param {number[]} colors  colors to give a swatch (the build's palette);
- *   every value the faces and the regions hold is unioned in, the guard for
- *   a relaxed or dominant color the palette snap left off it
+ *   every color the faces and regions hold is added too
  * @param {Map<number, number>} faceColor  colorize's per-face colors, keyed idx*6 + f
  * @returns {Skin}
  */
 export function bakeSkin(regions, colors, faceColor) {
-  // 1. The regions that chart: the ones not of one color.
+  // 1. Regions with more than one color get a chart.
   /** @type {{i:number, region:import('./regions.js').Region2D}[]} */
   const bodies = [];
   /** @type {(Chart|null)[]} */
@@ -141,8 +115,8 @@ export function bakeSkin(regions, colors, faceColor) {
     if (region.uniform === null) bodies.push({ i, region });
   });
 
-  // 2. The swatch colors: the given palette, then anything the faces and the
-  // regions' pieces hold (a cap's wedge color rides a region, never a face).
+  // 2. Swatch colors: the palette, then every color in the faces and the
+  // regions' pieces. A cap's wedge color appears only in a region.
   const seen = new Set();
   /** @type {number[]} */
   const swatchColors = [];
@@ -158,9 +132,8 @@ export function bakeSkin(regions, colors, faceColor) {
     for (let i = 0; i < region.present.length; i++)
       if (region.present[i]) addColor(region.texels[i]);
 
-  // 3. Pack: padded charts by height then width, descending (the region's own
-  // order the tiebreak, so the pack is a pure function of the input); the
-  // swatches, 1×1 and unpadded, after them.
+  // 3. Pack padded charts by height then width, descending, ties in region
+  // order. The 1×1 unpadded swatches follow.
   /** @type {{pw:number, ph:number, body?:{i:number, region:import('./regions.js').Region2D}, color?:number}[]} */
   const items = bodies.map((body) => ({
     body,
@@ -181,7 +154,7 @@ export function bakeSkin(regions, colors, faceColor) {
     height = pow2ceil(packed.height);
   }
 
-  // 4. Bake. Unused texels stay transparent black — nothing samples them.
+  // 4. Bake. Unused texels stay transparent black.
   const data = new Uint8Array(width * height * 4);
   const put = (x, y, c) => {
     const o = (y * width + x) * 4;
@@ -211,11 +184,9 @@ export function bakeSkin(regions, colors, faceColor) {
 }
 
 /**
- * The texel coordinates of a point on a charted region's plane: an affine
- * read of its position along the face's tangent axes from the region's box
- * origin, so a box corner lands on the chart's corner exactly, and a vertex
- * the T-junction repair inserted along an edge lands on the texel line
- * between two cells. Divide by the skin's width and height for the UV.
+ * The texel coordinates of a point on a charted region's plane: its offset
+ * along the face's tangent axes from the region's box origin, added to the
+ * chart's origin. Divide by the skin's width and height for the UV.
  * @param {Chart} chart
  * @param {{face:string, a:number, b:number}} region
  * @param {number[]} p  a point [x, y, z] on the region's plane, in voxel units
@@ -230,7 +201,7 @@ export function uvOfLattice(chart, region, p) {
 }
 
 /**
- * The texel CENTER of a color's swatch, in texel coordinates.
+ * The texel center of a color's swatch, in texel coordinates.
  * @param {Skin} skin
  * @param {number} packed  a packed RGBA color the skin holds a swatch for
  * @returns {[number, number]}

package/src/t-junction.js

@@ -1,38 +1,21 @@
-// ---------------------------------------------------------------------------
 // T-junction elimination for lattice meshes.
 //
-// Greedy-merging faces into large rectangles introduces T-junctions: a vertex
-// that lands in the MIDDLE of a longer triangle's edge — e.g. where a merged
-// base rectangle meets a unit-scale wedge edge, or two faces merged to different
-// extents meet at an object corner. It's invisible for opaque flat-shaded
-// geometry, but it makes the surface NON-manifold (edges no longer paired),
-// which breaks the watertight weld and clean glTF export.
+// Merged faces leave T-junctions: a vertex in the middle of another triangle's
+// edge. They make the surface non-manifold, which breaks the watertight weld
+// and glTF export. Every vertex is on the integer lattice, so the repair is
+// exact: split each triangle edge at every mesh vertex strictly inside it, then
+// re-triangulate the convex result with its own vertices.
 //
-// Every vertex here sits on the integer lattice, so repair is exact — no
-// floating-point tolerance. Collect all vertex positions, then split each
-// triangle edge at any vertex lying strictly on its interior, re-triangulating
-// the (convex) result with lattice-only vertices. Pure integer geometry: no
-// THREE, Node-testable.
+// Only axis-aligned and 45° diagonal edges can carry interior vertices. Any
+// other edge is a triangulation chord across a region or slope, where a valid
+// surface has no vertex, so it is skipped.
 //
-// Two kinds of edge can carry interior lattice points here: an AXIS-ALIGNED
-// one (a region polygon's, a slope's ridge edge) and a 45° DIAGONAL (a slope
-// block's staircase edge, a region's cut beside it — both long since the
-// merges of Sep 7 2026). Any other segment is a triangulation chord across a
-// region's or a slope's interior, where a valid surface never has a vertex,
-// so it is left alone.
-//
-// A triangle is an opaque record beyond its three vertices: every other field
-// (the normal, and the mesher's paint — a chart and its rect, or a swatch
-// color) is copied onto each piece a split produces, so the repair never has
-// to know what rides on a triangle. UVs are NOT carried through here: they
-// are a function of position (skin.js uvOfLattice), read after the repair.
-// ---------------------------------------------------------------------------
+// UVs are computed from position after the repair (skin.js uvOfLattice).
 
 const key = (p) => p[0] + ',' + p[1] + ',' + p[2];
 
-// Integer lattice points strictly interior to segment p->q that are in `vset`,
-// ordered p->q. Returns [] unless p->q is axis-aligned or a 45° diagonal (two
-// axes stepping by the same magnitude).
+// Vertices in `vset` strictly inside segment p->q, ordered p->q. Returns []
+// unless p->q is axis-aligned or a 45° diagonal.
 function interiorPointsOnEdge(p, q, vset) {
   const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
   const axes = [];
@@ -49,10 +32,10 @@ function interiorPointsOnEdge(p, q, vset) {
   return out;
 }
 
-// Triangulate a convex polygon (wound CCW wrt `normal`) using only its own
-// vertices, tolerating collinear boundary points. Clip only a strictly-convex
-// corner whose EAR EDGE (prev->next) carries no other vertex — otherwise the ear
-// would span a subdivided edge and re-introduce the T-junction we're removing.
+// Triangulate a convex polygon, wound CCW about `normal`, using only its own
+// vertices. Collinear boundary points are allowed. Only a strictly convex
+// corner whose edge prev->next contains no other vertex is clipped. Otherwise
+// the ear would span a split edge and reintroduce a T-junction.
 function triangulateConvex(ring, normal, emit) {
   const turn = (o, a, b) => {
     const ux = a[0] - o[0],
@@ -67,7 +50,7 @@ function triangulateConvex(ring, normal, emit) {
       (ux * vy - uy * vx) * normal[2]
     );
   };
-  // v strictly interior to segment p->q (collinear + between the endpoints).
+  // v lies strictly inside segment p->q.
   const onSeg = (p, q, v) => {
     const dx = q[0] - p[0],
       dy = q[1] - p[1],
@@ -104,8 +87,8 @@ function triangulateConvex(ring, normal, emit) {
       break;
     }
     if (!clipped) {
-      // Defensive: fan from a strictly-convex vertex (clean-ear clipping should
-      // always progress for a convex polygon, so this is a safety net only).
+      // Fallback: fan from a strictly convex vertex. Ear clipping should always
+      // progress on a convex polygon.
       let ai = 0;
       for (let i = 0; i < poly.length; i++) {
         const prev = poly[(i - 1 + poly.length) % poly.length];
@@ -130,11 +113,10 @@ function triangulateConvex(ring, normal, emit) {
 /**
  * @template {{a:number[], b:number[], c:number[], normal:number[]}} T
  * @param {T[]} tris
- *   triangles with INTEGER-lattice vertex coords, wound CCW wrt `normal`.
+ *   triangles with integer lattice vertices, wound CCW about `normal`.
  * @returns {T[]}
- *   an equivalent surface with no T-junctions (every edge split at interior
- *   verts); a split triangle's pieces carry every field of their source but
- *   the three vertices.
+ *   the same surface with no T-junctions. Pieces of a split triangle keep its
+ *   other fields.
  */
 export function eliminateTJunctions(tris) {
   const vset = new Set();

package/src/three.js

@@ -0,0 +1,60 @@
+// Three adapter (sprite-machine/three): the mesher's record as three objects.
+// The only entry that imports three, an optional peer.
+
+import * as THREE from 'three';
+import { unpackRGBA } from './ingest.js';
+
+/**
+ * The skin as a DataTexture. The class defaults match the bake: nearest
+ * filtering, no mipmaps, and flipY false so texel row 0 is v = 0. The bytes
+ * are sRGB.
+ * @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;
+}
+
+/**
+ * The geometry as an indexed BufferGeometry with its bounds computed. The
+ * arrays are copied.
+ * @param {import('./wedge-mesh.js').Geometry} geometry
+ * @returns {THREE.BufferGeometry}
+ */
+export function toGeometry(geometry) {
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute('position', new THREE.Float32BufferAttribute(geometry.position, 3));
+  geo.setAttribute('normal', new THREE.Float32BufferAttribute(geometry.normal, 3));
+  geo.setAttribute('uv', new THREE.Float32BufferAttribute(geometry.uv, 2));
+  geo.setIndex(new THREE.Uint32BufferAttribute(geometry.index, 1));
+  geo.computeBoundingBox();
+  geo.computeBoundingSphere();
+  return geo;
+}
+
+/**
+ * The model as a flat-shaded Mesh with shadows on. The material takes the
+ * skin as `map`, or with no skin the packed sRGB `color`.
+ * @param {import('./wedge-mesh.js').Built} model
+ * @returns {THREE.Mesh}
+ */
+export function toMesh(model) {
+  const map = model.skin ? skinTexture(model.skin) : null;
+  const mat = new THREE.MeshStandardMaterial({
+    flatShading: true,
+    metalness: 0,
+    roughness: 1,
+    ...(map ? { map } : {}),
+  });
+  if (!map && model.color != null) {
+    const { r, g, b } = unpackRGBA(model.color);
+    mat.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+  }
+  const mesh = new THREE.Mesh(toGeometry(model.geometry), mat);
+  mesh.castShadow = true;
+  mesh.receiveShadow = true;
+  return mesh;
+}

package/src/views.js

@@ -1,30 +1,20 @@
-// ---------------------------------------------------------------------------
-// View conventions and projection mappings.
+// View conventions and projections.
 //
-// World frame:  +x = right, +y = up, +z = toward the front (camera).
-// A "view" is an orthographic face render. Each view has:
-//   - normal:   the world-space outward normal of the face it observes.
-//   - axis:     the world axis it looks ALONG (the depth / extrusion axis).
-//   - project(x, y, z, dims) -> {u, v}: which pixel of the view a voxel maps to.
-//                u,v are image coords with (0,0) = top-left, v growing DOWN.
+// World frame: +x right, +y up, +z toward the front (camera).
+// A view is an orthographic render of one face. project(x, y, z, dims) -> {u, v}
+// gives the view pixel for a voxel, with (0, 0) at top-left and v growing down.
 //
-// The image width/height of a view are tied to two of the grid dims:
-//   FRONT/BACK : image is (nx wide, ny tall)  -> sees the X/Y plane
-//   LEFT/RIGHT : image is (nz wide, ny tall)  -> sees the Z/Y plane
-//   TOP/BOTTOM : image is (nx wide, nz tall)  -> sees the X/Z plane
+// View image sizes in grid dims:
+//   FRONT/BACK : nx wide, ny tall (X/Y plane)
+//   LEFT/RIGHT : nz wide, ny tall (Z/Y plane)
+//   TOP/BOTTOM : nx wide, nz tall (X/Z plane)
 //
-// These six mappings are set-and-forget: identical for every model. They were
-// chosen so that, standing at the camera and looking at each face, the sprite's
-// pixel (col,row) lands where a human artist expects (art drawn upright and
-// left-to-right as seen from outside the object).
-// ---------------------------------------------------------------------------
+// The mappings are the same for every model. Art drawn upright and left to
+// right, as seen from outside the object, appears that way on the model.
 
 /** @typedef {{nx:number, ny:number, nz:number}} Dims */
 
-// Human-facing view names -> face normals. Its inverse
-// FACE_TO_VIEW is consumed by colorize, VIEW_TO_FACE by the edge hints (which
-// need a view's own face to know which way it looks); every pair is already
-// implied by the face metadata below.
+// View name -> the face key it colors, and the inverse.
 export const VIEW_TO_FACE = {
   right: 'nx',
   left: 'px',
@@ -37,10 +27,8 @@ export const FACE_TO_VIEW = Object.fromEntries(
   Object.entries(VIEW_TO_FACE).map(([k, v]) => [v, k])
 );
 
-// Outward unit normals per face key. The single source of truth for per-face
-// axis/direction — FACE_AXIS, carve's NEIGHBORS, and faces.js's quad normals are
-// all derived from this so they can't drift from the convention the 6-bit surface
-// mask and the faceColor keying (idx*6+f) depend on.
+// Outward unit normal per face key. FACE_AXIS, carve's NEIGHBORS and faces.js
+// derive from it.
 export const FACE_NORMAL = {
   px: [1, 0, 0],
   nx: [-1, 0, 0],
@@ -50,29 +38,26 @@ export const FACE_NORMAL = {
   nz: [0, 0, -1],
 };
 
-// Canonical face-key order: the 6-bit surface-exposure mask and the faceColor map
-// (keyed idx*6+f) both index by this position, so it is load-bearing. Co-located
-// with FACE_NORMAL; carve.js re-exports it for the consumers that read it there.
+// Face-key order. The 6-bit surface mask and the faceColor keys (idx*6 + f)
+// index by position, so the order must not change. carve.js re-exports it.
 export const FACE_KEYS = ['px', 'nx', 'py', 'ny', 'pz', 'nz'];
 
-// Face key -> its index in FACE_KEYS (memoized indexOf).
+// Face key -> index in FACE_KEYS.
 export const FACE_INDEX = Object.fromEntries(FACE_KEYS.map((k, i) => [k, i]));
 
-// World-axis name -> its index in an [x, y, z] triple.
+// Axis name -> index in an [x, y, z] triple.
 export const AXIS_INDEX = { x: 0, y: 1, z: 2 };
 
 // The face key whose outward normal points along world `axis` with `sign` (±1).
-// Derived from FACE_NORMAL so an (axis, sign) pair can never drift from the normals.
 export const faceKeyOf = (axis, sign) =>
   FACE_KEYS.find((k) => FACE_NORMAL[k][AXIS_INDEX[axis]] === sign);
 
-// Which world axis each face's outward normal lies on. Derived from
-// FACE_NORMAL so it can't drift; used by colorize for mirror-fill.
+// The world axis of each face's normal. colorize uses it for mirror-fill.
 export const FACE_AXIS = Object.fromEntries(
   Object.entries(FACE_NORMAL).map(([k, n]) => [k, n[0] ? 'x' : n[1] ? 'y' : 'z'])
 );
 
-// Opposite face (for mirror-fill).
+// Opposite face, for mirror-fill.
 export const FACE_OPPOSITE = {
   px: 'nx',
   nx: 'px',
@@ -82,18 +67,11 @@ export const FACE_OPPOSITE = {
   nz: 'pz',
 };
 
-// For each face/view: the image dimensions in grid units and the pixel projection.
-// The march axis + direction used for first-hit visibility is NOT stored here — it
-// is derived from FACE_NORMAL in colorize.firstHitFromFace, the single source of
-// truth (a `step`/`from` field here would be a silent drift hazard).
-//
-// projectInto(x,y,z,d,out) writes integer image coords into the reused `out` (no
-// per-voxel allocation in carve's hot triple loop); project() is the allocating
-// convenience that delegates to it, so each view has exactly ONE formula. `imgW`/
-// `imgH` give the expected view image size for a grid, so carve can place each view
-// at native scale (padding, never stretching) and index it 1:1.
+// Per view: the image size for a grid (imgW, imgH) and the pixel projection.
+// projectInto writes into a reused `out` so carve's per-voxel loop does not
+// allocate. project allocates and delegates to it.
 export const VIEWS = {
-  // FRONT: looks toward -z from +z. Sees +z face. Image = X (right) by Y (up).
+  // FRONT: looks toward -z and sees the +z face. Image is X by Y.
   front: {
     imgW: (d) => d.nx,
     imgH: (d) => d.ny,
@@ -102,7 +80,7 @@ export const VIEWS = {
       return this.projectInto(x, y, z, d, { u: 0, v: 0 });
     },
   },
-  // BACK: looks toward +z from -z. Sees -z face. Left-right mirrored vs front.
+  // BACK: looks toward +z and sees the -z face. Mirrored left to right from FRONT.
   back: {
     imgW: (d) => d.nx,
     imgH: (d) => d.ny,
@@ -111,11 +89,9 @@ export const VIEWS = {
       return this.projectInto(x, y, z, d, { u: 0, v: 0 });
     },
   },
-  // LEFT: the atlas tile drawn as the object's LEFT side. It colors the +x face
-  // — viewed straight-on from +x that face reads as a left-side profile, so the
-  // *tile* is named by how it reads (a deliberate labeling choice; see README),
-  // not by the world axis it happens to occupy. Image = Z by Y. u = nz-1-z puts
-  // the object's front (+z) at the left column, matching a nose-left profile.
+  // LEFT: the tile for the object's left side. It colors the +x face, which
+  // seen from +x reads as a left-side profile (see README). Image is Z by Y.
+  // u = nz-1-z puts the front (+z) in the left column.
   left: {
     imgW: (d) => d.nz,
     imgH: (d) => d.ny,
@@ -124,8 +100,8 @@ export const VIEWS = {
       return this.projectInto(x, y, z, d, { u: 0, v: 0 });
     },
   },
-  // RIGHT: the object's RIGHT side; colors the -x face, which reads as a
-  // right-side profile. Mirror of left along z — u = z puts front at the right column.
+  // RIGHT: the object's right side. It colors the -x face. u = z puts the front
+  // in the right column.
   right: {
     imgW: (d) => d.nz,
     imgH: (d) => d.ny,
@@ -134,9 +110,8 @@ export const VIEWS = {
       return this.projectInto(x, y, z, d, { u: 0, v: 0 });
     },
   },
-  // TOP: looks toward -y from +y. Sees +y face. Image = X by Z.
-  // Looking straight down: v = nz-1-z puts the object's front (+z, z=nz-1) on
-  // the TOP row of the image (v=0), matching the FRONT view's top-is-v=0.
+  // TOP: looks toward -y and sees the +y face. Image is X by Z.
+  // v = nz-1-z puts the front (+z) on the top row.
   top: {
     imgW: (d) => d.nx,
     imgH: (d) => d.nz,
@@ -145,10 +120,9 @@ export const VIEWS = {
       return this.projectInto(x, y, z, d, { u: 0, v: 0 });
     },
   },
-  // BOTTOM: looks toward +y from -y. Sees -y face. The car is flipped SIDEWAYS
-  // (rolled about its front-back axis), NOT end-over-end — so the front stays on
-  // the TOP row like TOP (v = nz-1-z) and only left/right swap (u = nx-1-x). That
-  // way the TOP and BOTTOM tiles register front-to-front on the same edge.
+  // BOTTOM: looks toward +y and sees the -y face. The object is rolled about its
+  // front-back axis, so the front stays on the top row as in TOP (v = nz-1-z)
+  // and only u flips (u = nx-1-x).
   bottom: {
     imgW: (d) => d.nx,
     imgH: (d) => d.nz,
@@ -161,19 +135,11 @@ export const VIEWS = {
 
 export const VIEW_NAMES = Object.keys(VIEWS);
 
-// The six view names in atlas-sheet (row-major) order, matching atlas.js
-// DEFAULT_ATLAS_LAYOUT (LEFT FRONT TOP / RIGHT BACK BOTTOM). A pinned convention
-// (a test asserts it equals the layout) — there is no on-screen faces-preview
-// grid; the editor switches faces with text tabs.
+// View names in atlas row-major order, matching atlas.js DEFAULT_ATLAS_LAYOUT.
 export const VIEW_DISPLAY_ORDER = ['left', 'front', 'top', 'right', 'back', 'bottom'];
 
-// Which image edge of a view's tile the object's FRONT (+z, the "nose") points
-// toward. A projection-convention pin (a test checks it against VIEWS' projections)
-// and the reference behind the README's per-face "Front points" column. Derived
-// meaning: in LEFT, front (z=nz-1) maps to u=0, the left column; TOP and BOTTOM
-// both put the front on their TOP edge (BOTTOM is the sideways flip of TOP);
-// FRONT/BACK look straight down +z/-z, so their nose points out of / into the
-// screen — there is no in-plane front edge (null).
+// The edge of each view's tile that the object's front (+z) points toward.
+// FRONT and BACK look along z, so they have none (null).
 export const VIEW_FRONT_EDGE = {
   right: 'right',
   left: 'left',
@@ -183,7 +149,7 @@ export const VIEW_FRONT_EDGE = {
   back: null,
 };
 
-// Each view's opposite (the mirror-fill source when a view has no art of its own).
+// Each view's opposite, the mirror-fill source for a view with no art.
 export const VIEW_OPPOSITE = {
   right: 'left',
   left: 'right',
@@ -193,16 +159,13 @@ export const VIEW_OPPOSITE = {
   bottom: 'top',
 };
 
-// To DISPLAY a mirror-derived face, flip its opposite view's tile along this
-// IMAGE axis. It is 'x' for EVERY pair (a single constant, not a per-view table
-// that would imply the axis varies): the projections make each pair mirror
-// HORIZONTALLY — left↔right and front↔back on the X/Z planes, and top↔bottom too
-// because BOTTOM is the sideways (left/right) flip of TOP, not an end-over-end one.
-// (mirrorImage's 'y' branch in derive.js is therefore unexercised in practice.)
+// The image axis along which an opposite view's tile is flipped to display a
+// mirror-derived face. Every pair mirrors horizontally, top and bottom included,
+// because BOTTOM is TOP rolled sideways.
 export const MIRROR_AXIS = 'x';
 
-// Which grid axes a view's (imgW, imgH) constrain. Used by dimension
-// reconciliation. Each entry: [axisForImgW, axisForImgH].
+// The grid dims a view's image constrains: [axis for imgW, axis for imgH].
+// Used by dimension reconciliation.
 export const VIEW_AXES = {
   front: ['nx', 'ny'],
   back: ['nx', 'ny'],
@@ -212,12 +175,10 @@ export const VIEW_AXES = {
   bottom: ['nx', 'nz'],
 };
 
-// For each view: which world axis its image COLUMNS (u) and ROWS (v) run along,
-// and whether the image index runs the SAME direction as the world coordinate
-// (flip:false) or the OPPOSITE (flip:true). Probed from project() at load so it
-// can never drift from the projections above (test/views.test.mjs pins it).
-// Consumed by the sheet resize (atlas.js resizeAtlas) to place each
-// face's tile so every face sharing a world axis shifts identically.
+// Per view: the axis its image columns (u) and rows (v) run along, and whether
+// the image index runs against the world coordinate (flip). Probed from
+// project() at load. atlas.js resizeAtlas uses it so faces that share an axis
+// shift together.
 const AXIS_ARG = { nx: 0, ny: 1, nz: 2 };
 function probeFlip(spec, axisName, which) {
   const d = { nx: 2, ny: 2, nz: 2 };