sprite-machine 0.1.0

package/src/regions.js

@@ -0,0 +1,298 @@
+// ---------------------------------------------------------------------------
+// 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).
+//
+// 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).
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+import { FACE_KEYS, FACE_NORMAL } from './views.js';
+import { FACE_GEO, idxFor } from './faces.js';
+
+/**
+ * @typedef {{a:number, b:number, color:number}} Cell
+ * @typedef {{a:number, b:number, hiA:boolean, hiB:boolean, color:number}} Half
+ * @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).
+ * @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 */
+function area2(poly) {
+  let s = 0;
+  for (let i = 0; i < poly.length; i++) {
+    const p = poly[i];
+    const q = poly[(i + 1) % poly.length];
+    s += p[0] * q[1] - q[0] * p[1];
+  }
+  return s;
+}
+
+/** Even-odd point-in-polygon; the ray is horizontal, and no test point here has an integer y. */
+function inside(poly, x, y) {
+  let c = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if (yi > y !== yj > y && x < xi + ((y - yi) * (xj - xi)) / (yj - yi)) c = !c;
+  }
+  return c;
+}
+
+/** Drop the vertices a ring runs straight through. Ring edges are unit steps, so a step's sign is its direction. */
+function dropCollinear(ring) {
+  const n = ring.length;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const p = ring[(i - 1 + n) % n];
+    const c = ring[i];
+    const q = ring[(i + 1) % n];
+    const straight =
+      Math.sign(c[0] - p[0]) === Math.sign(q[0] - c[0]) &&
+      Math.sign(c[1] - p[1]) === Math.sign(q[1] - c[1]);
+    if (!straight) out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Trace the regions of one plane from its pieces.
+ * @param {Cell[]} cells
+ * @param {Half[]} halves
+ * @returns {Region2D[]}
+ */
+export function traceRegions(cells, halves) {
+  /** @type {{poly:number[][], at:number[], color:number, a:number, b:number, half:boolean}[]} */
+  const pieces = [];
+  for (const c of cells) {
+    pieces.push({
+      poly: [
+        [c.a, c.b],
+        [c.a + 1, c.b],
+        [c.a + 1, c.b + 1],
+        [c.a, c.b + 1],
+      ],
+      at: [c.a + 0.5, c.b + 0.5],
+      color: c.color >>> 0,
+      a: c.a,
+      b: c.b,
+      half: false,
+    });
+  }
+  for (const h of halves) {
+    const ca = h.a + (h.hiA ? 1 : 0); // the right angle's corner
+    const cb = h.b + (h.hiB ? 1 : 0);
+    const qa = h.a + (h.hiA ? 0 : 1); // the legs' far ends
+    const sb = h.b + (h.hiB ? 0 : 1);
+    let poly = [
+      [ca, cb],
+      [qa, cb],
+      [ca, sb],
+    ];
+    if (area2(poly) < 0) poly = [poly[0], poly[2], poly[1]];
+    pieces.push({
+      poly,
+      at: [(2 * ca + qa) / 3, (2 * cb + sb) / 3],
+      color: h.color >>> 0,
+      a: h.a,
+      b: h.b,
+      half: true,
+    });
+  }
+
+  // 1. directed edges; one whose reverse is present is interior and cancels
+  const ekey = (p, q) => p[0] + ',' + p[1] + '>' + q[0] + ',' + q[1];
+  /** @type {Map<string, {p:number[], q:number[]}>} */
+  const edges = new Map();
+  for (const pc of pieces)
+    for (let i = 0; i < pc.poly.length; i++) {
+      const p = pc.poly[i];
+      const q = pc.poly[(i + 1) % pc.poly.length];
+      if (edges.has(ekey(p, q)))
+        throw new Error(`regions: two pieces share the edge ${ekey(p, q)}`);
+      edges.set(ekey(p, q), { p, q });
+    }
+  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
+  const vkey = (p) => p[0] + ',' + p[1];
+  /** @type {Map<string, {p:number[], q:number[]}[]>} */
+  const outAt = new Map();
+  for (const e of boundary) {
+    const k = vkey(e.p);
+    if (!outAt.has(k)) outAt.set(k, []);
+    outAt.get(k).push(e);
+  }
+  const next = new Map();
+  for (const e of boundary) {
+    const dx = e.q[0] - e.p[0];
+    const dy = e.q[1] - e.p[1];
+    let best = null;
+    let bestTurn = -Infinity;
+    for (const f of outAt.get(vkey(e.q)) || []) {
+      const fx = f.q[0] - f.p[0];
+      const fy = f.q[1] - f.p[1];
+      const turn = Math.atan2(dx * fy - dy * fx, dx * fx + dy * fy);
+      if (turn > bestTurn) {
+        bestTurn = turn;
+        best = f;
+      }
+    }
+    if (!best) throw new Error('regions: the boundary is open at ' + vkey(e.q));
+    next.set(e, best);
+  }
+
+  // 3. the loops: the cycles of the successor map
+  const seen = new Set();
+  /** @type {Loop[]} */
+  const loops = [];
+  for (const e0 of boundary) {
+    if (seen.has(e0)) continue;
+    const ring = [];
+    let e = e0;
+    do {
+      seen.add(e);
+      ring.push(e.p);
+      e = next.get(e);
+    } while (e !== e0 && !seen.has(e));
+    if (e !== e0) throw new Error('regions: the boundary walk did not close');
+    loops.push(dropCollinear(ring));
+  }
+
+  // 4. outers and holes; each hole and each piece to the innermost outer around it
+  /** @type {Loop[]} */
+  const outers = [];
+  /** @type {Loop[]} */
+  const holes = [];
+  for (const loop of loops) (area2(loop) > 0 ? outers : holes).push(loop);
+  outers.sort((p, q) => area2(p) - area2(q));
+  const owner = (x, y) => {
+    for (let i = 0; i < outers.length; i++) if (inside(outers[i], x, y)) return i;
+    throw new Error(`regions: (${x}, ${y}) lies in no outer loop`);
+  };
+  const groups = outers.map((outer) => ({ outer, holes: [], pieces: [] }));
+  for (const h of holes) {
+    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
+    groups[
+      owner((p[0] + q[0]) / 2 + 0.25 * dy, (p[1] + q[1]) / 2 - 0.25 * dx)
+    ].holes.push(h);
+  }
+  for (const pc of pieces) groups[owner(pc.at[0], pc.at[1])].pieces.push(pc);
+
+  return groups.map(({ outer, holes, pieces }) => {
+    let a0 = Infinity,
+      b0 = Infinity,
+      a1 = -Infinity,
+      b1 = -Infinity;
+    for (const [a, b] of outer) {
+      if (a < a0) a0 = a;
+      if (b < b0) b0 = b;
+      if (a > a1) a1 = a;
+      if (b > b1) b1 = b;
+    }
+    const w = a1 - a0;
+    const h = b1 - b0;
+    const texels = new Uint32Array(w * h);
+    const present = new Uint8Array(w * h);
+    let uniform = null;
+    let mixed = false;
+    let area = 0;
+    for (const pc of pieces) {
+      const i = pc.a - a0 + (pc.b - b0) * w;
+      texels[i] = pc.color;
+      present[i] = 1;
+      area += pc.half ? 1 : 2;
+      if (uniform === null) uniform = pc.color;
+      else if (uniform !== pc.color) mixed = true;
+    }
+    return {
+      outer,
+      holes,
+      a: a0,
+      b: b0,
+      w,
+      h,
+      texels,
+      present,
+      uniform: mixed ? null : uniform,
+      area2: area,
+    };
+  });
+}
+
+/** The key a plane's halves are filed under: a face key at 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.
+ * @param {{nx:number, ny:number, nz:number}} dims
+ * @param {Uint8Array} surfaceMask
+ * @param {Map<number, number>} faceColor
+ * @param {Map<string, Half[]>} [halves]  by planeKey(face, s)
+ * @returns {Region[]}
+ */
+export function faceRegions(dims, surfaceMask, faceColor, halves = new Map()) {
+  /** @type {Region[]} */
+  const out = [];
+  FACE_KEYS.forEach((face, f) => {
+    const g = FACE_GEO[face];
+    const normal = FACE_NORMAL[face];
+    const dimN = DIM(dims, g.N);
+    const dimA = DIM(dims, g.A);
+    const dimB = DIM(dims, g.B);
+    for (let s = 0; s < dimN; s++) {
+      /** @type {Cell[]} */
+      const cells = [];
+      for (let b = 0; b < dimB; b++)
+        for (let a = 0; a < dimA; a++) {
+          const idx = idxFor(face, a, b, s, dims);
+          if (surfaceMask[idx] & (1 << f))
+            cells.push({ a, b, color: faceColor.get(idx * 6 + f) >>> 0 });
+        }
+      const hs = halves.get(planeKey(face, s)) || [];
+      if (!cells.length && !hs.length) continue;
+      for (const r of traceRegions(cells, hs)) out.push({ face, s, normal, ...r });
+    }
+  });
+  return out;
+}

package/src/skin.js

@@ -0,0 +1,242 @@
+// ---------------------------------------------------------------------------
+// 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.
+//
+// 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.
+//
+// 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.
+//
+// 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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+import { FACE_GEO } from './faces.js';
+import { unpackRGBA } from './ingest.js';
+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.
+ * @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.
+ */
+
+const GUTTER = 1;
+const MIN_WIDTH = 16;
+
+const pow2ceil = (n) => {
+  let p = 1;
+  while (p < n) p *= 2;
+  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.
+function shelfPack(items, width) {
+  const at = new Array(items.length);
+  let x = 0,
+    y = 0,
+    shelf = 0;
+  items.forEach((it, i) => {
+    if (x + it.pw > width) {
+      x = 0;
+      y += shelf;
+      shelf = 0;
+    }
+    at[i] = { x, y };
+    x += it.pw;
+    if (it.ph > shelf) shelf = it.ph;
+  });
+  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).
+function floodBox(region) {
+  const { w, h, texels, present } = region;
+  const W = w + 2 * GUTTER;
+  const H = h + 2 * GUTTER;
+  const fill = new Uint32Array(W * H);
+  const done = new Uint8Array(W * H);
+  const queue = [];
+  for (let j = 0; j < h; j++)
+    for (let k = 0; k < w; k++)
+      if (present[j * w + k]) {
+        const n = (j + GUTTER) * W + k + GUTTER;
+        fill[n] = texels[j * w + k];
+        done[n] = 1;
+        queue.push(n);
+      }
+  const STEPS = [1, -1, W, -W];
+  for (let qi = 0; qi < queue.length; qi++) {
+    const n = queue[qi];
+    const x = n % W;
+    for (const d of STEPS) {
+      if ((d === 1 && x === W - 1) || (d === -1 && x === 0)) continue;
+      const m = n + d;
+      if (m < 0 || m >= W * H || done[m]) continue;
+      fill[m] = fill[n];
+      done[m] = 1;
+      queue.push(m);
+    }
+  }
+  return { W, H, fill };
+}
+
+/**
+ * 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
+ * @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.
+  /** @type {{i:number, region:import('./regions.js').Region2D}[]} */
+  const bodies = [];
+  /** @type {(Chart|null)[]} */
+  const charts = new Array(regions.length).fill(null);
+  regions.forEach((region, i) => {
+    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).
+  const seen = new Set();
+  /** @type {number[]} */
+  const swatchColors = [];
+  const addColor = (c) => {
+    const k = c >>> 0;
+    if (seen.has(k)) return;
+    seen.add(k);
+    swatchColors.push(k);
+  };
+  for (const c of colors) addColor(c);
+  for (const c of faceColor.values()) addColor(c);
+  for (const region of regions)
+    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.
+  /** @type {{pw:number, ph:number, body?:{i:number, region:import('./regions.js').Region2D}, color?:number}[]} */
+  const items = bodies.map((body) => ({
+    body,
+    pw: body.region.w + 2 * GUTTER,
+    ph: body.region.h + 2 * GUTTER,
+  }));
+  items.sort((p, q) => q.ph - p.ph || q.pw - p.pw || p.body.i - q.body.i);
+  for (const color of swatchColors) items.push({ color, pw: 1, ph: 1 });
+
+  let widest = 1;
+  for (const it of items) if (it.pw > widest) widest = it.pw;
+  let width = Math.max(MIN_WIDTH, pow2ceil(widest));
+  let packed = shelfPack(items, width);
+  let height = pow2ceil(packed.height);
+  while (height > width) {
+    width *= 2;
+    packed = shelfPack(items, width);
+    height = pow2ceil(packed.height);
+  }
+
+  // 4. Bake. Unused texels stay transparent black — nothing samples them.
+  const data = new Uint8Array(width * height * 4);
+  const put = (x, y, c) => {
+    const o = (y * width + x) * 4;
+    const { r, g, b } = unpackRGBA(c);
+    data[o] = r;
+    data[o + 1] = g;
+    data[o + 2] = b;
+    data[o + 3] = 255;
+  };
+  /** @type {Map<number, {u:number, v:number}>} */
+  const swatch = new Map();
+  items.forEach((it, n) => {
+    const { x, y } = packed.at[n];
+    if (it.body) {
+      const { i, region } = it.body;
+      const { W, H, fill } = floodBox(region);
+      for (let j = 0; j < H; j++)
+        for (let k = 0; k < W; k++) put(x + k, y + j, fill[j * W + k]);
+      charts[i] = { u0: x + GUTTER, v0: y + GUTTER, w: region.w, h: region.h };
+    } else {
+      put(x, y, it.color);
+      swatch.set(it.color, { u: x, v: y });
+    }
+  });
+
+  return { width, height, data, charts, swatch };
+}
+
+/**
+ * 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.
+ * @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
+ * @returns {[number, number]}
+ */
+export function uvOfLattice(chart, region, p) {
+  const g = FACE_GEO[region.face];
+  return [
+    chart.u0 + (p[AXIS_INDEX[g.A]] - region.a),
+    chart.v0 + (p[AXIS_INDEX[g.B]] - region.b),
+  ];
+}
+
+/**
+ * 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]}
+ */
+export function swatchUV(skin, packed) {
+  const at = skin.swatch.get(packed >>> 0);
+  if (!at) throw new Error(`skin: no swatch for color 0x${(packed >>> 0).toString(16)}`);
+  return [at.u + 0.5, at.v + 0.5];
+}

package/src/t-junction.js

@@ -0,0 +1,160 @@
+// ---------------------------------------------------------------------------
+// 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.
+//
+// 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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+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).
+function interiorPointsOnEdge(p, q, vset) {
+  const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
+  const axes = [];
+  for (let i = 0; i < 3; i++) if (d[i] !== 0) axes.push(i);
+  if (axes.length === 0 || axes.length === 3) return []; // degenerate, or a chord
+  const n = Math.abs(d[axes[0]]);
+  if (axes.length === 2 && Math.abs(d[axes[1]]) !== n) return []; // not 45°
+  const out = [];
+  for (let t = 1; t < n; t++) {
+    const pt = [p[0], p[1], p[2]];
+    for (const i of axes) pt[i] += Math.sign(d[i]) * t;
+    if (vset.has(key(pt))) out.push(pt);
+  }
+  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.
+function triangulateConvex(ring, normal, emit) {
+  const turn = (o, a, b) => {
+    const ux = a[0] - o[0],
+      uy = a[1] - o[1],
+      uz = a[2] - o[2];
+    const vx = b[0] - o[0],
+      vy = b[1] - o[1],
+      vz = b[2] - o[2];
+    return (
+      (uy * vz - uz * vy) * normal[0] +
+      (uz * vx - ux * vz) * normal[1] +
+      (ux * vy - uy * vx) * normal[2]
+    );
+  };
+  // v strictly interior to segment p->q (collinear + between the endpoints).
+  const onSeg = (p, q, v) => {
+    const dx = q[0] - p[0],
+      dy = q[1] - p[1],
+      dz = q[2] - p[2];
+    const ex = v[0] - p[0],
+      ey = v[1] - p[1],
+      ez = v[2] - p[2];
+    if (dy * ez - dz * ey || dz * ex - dx * ez || dx * ey - dy * ex) return false;
+    const dot = dx * ex + dy * ey + dz * ez;
+    return dot > 0 && dot < dx * dx + dy * dy + dz * dz;
+  };
+  const poly = ring.slice();
+  let guard = poly.length * poly.length + 8;
+  while (poly.length > 3 && guard-- > 0) {
+    let clipped = false;
+    for (let i = 0; i < poly.length; i++) {
+      const prev = poly[(i - 1 + poly.length) % poly.length];
+      const cur = poly[i];
+      const next = poly[(i + 1) % poly.length];
+      if (turn(prev, cur, next) <= 0) continue; // reflex or collinear
+      let blocked = false;
+      for (let j = 0; j < poly.length && !blocked; j++)
+        if (
+          poly[j] !== prev &&
+          poly[j] !== cur &&
+          poly[j] !== next &&
+          onSeg(prev, next, poly[j])
+        )
+          blocked = true;
+      if (blocked) continue;
+      emit(prev, cur, next);
+      poly.splice(i, 1);
+      clipped = true;
+      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).
+      let ai = 0;
+      for (let i = 0; i < poly.length; i++) {
+        const prev = poly[(i - 1 + poly.length) % poly.length];
+        const next = poly[(i + 1) % poly.length];
+        if (turn(prev, poly[i], next) > 0) {
+          ai = i;
+          break;
+        }
+      }
+      for (let k = 1; k < poly.length - 1; k++) {
+        const w1 = poly[(ai + k) % poly.length];
+        const w2 = poly[(ai + k + 1) % poly.length];
+        if (turn(poly[ai], w1, w2) !== 0) emit(poly[ai], w1, w2);
+      }
+      return;
+    }
+  }
+  if (poly.length === 3 && turn(poly[0], poly[1], poly[2]) !== 0)
+    emit(poly[0], poly[1], poly[2]);
+}
+
+/**
+ * @template {{a:number[], b:number[], c:number[], normal:number[]}} T
+ * @param {T[]} tris
+ *   triangles with INTEGER-lattice vertex coords, wound CCW wrt `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.
+ */
+export function eliminateTJunctions(tris) {
+  const vset = new Set();
+  for (const t of tris) {
+    vset.add(key(t.a));
+    vset.add(key(t.b));
+    vset.add(key(t.c));
+  }
+
+  const out = [];
+  for (const t of tris) {
+    const ab = interiorPointsOnEdge(t.a, t.b, vset);
+    const bc = interiorPointsOnEdge(t.b, t.c, vset);
+    const ca = interiorPointsOnEdge(t.c, t.a, vset);
+    if (!ab.length && !bc.length && !ca.length) {
+      out.push(t);
+      continue;
+    }
+    const ring = [t.a, ...ab, t.b, ...bc, t.c, ...ca];
+    triangulateConvex(ring, t.normal, (a, b, c) => out.push({ ...t, a, b, c }));
+  }
+  return out;
+}