sprite-machine 0.1.0

package/src/node.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+import { PNG } from 'pngjs';
+import { isPng, readTextChunks } from './png-chunks.js';
+import { buildModel, modelToGlb } from './model.js';
+
+const TRANSFORMS_CHUNK = 'sprite-machine:transforms';
+
+/**
+ * Decode a document PNG.
+ * @param {Uint8Array} bytes
+ * @returns {{
+ *   image: {width:number, height:number, data:Uint8ClampedArray},
+ *   name: string|null,
+ *   transforms: Record<string, {rot?:number, flipX?:boolean, flipY?:boolean}>,
+ *   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)
+ * @throws when the bytes are not a PNG, or pngjs cannot decode them
+ */
+export function readSheet(bytes) {
+  if (!isPng(bytes)) throw new Error('readSheet: not a PNG.');
+  const png = PNG.sync.read(
+    Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  );
+  const image = {
+    width: png.width,
+    height: png.height,
+    data: new Uint8ClampedArray(png.data.buffer, png.data.byteOffset, png.data.length),
+  };
+  /** @type {Record<string, string>} */
+  let chunks = {};
+  try {
+    chunks = readTextChunks(bytes);
+  } catch {
+    chunks = {};
+  }
+  /** @type {Record<string, {rot?:number, flipX?:boolean, flipY?:boolean}>} */
+  let transforms = {};
+  if (chunks[TRANSFORMS_CHUNK]) {
+    try {
+      transforms = JSON.parse(chunks[TRANSFORMS_CHUNK]);
+    } catch {
+      transforms = {};
+    }
+  }
+  return { image, name: chunks.Title ?? null, transforms, chunks };
+}
+
+/**
+ * A document PNG's bytes → its glb: `readSheet`, `buildModel`, `modelToGlb`.
+ * @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'
+ * @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 });
+  return modelToGlb(model, {
+    name: name ?? sheet.name ?? 'sprite',
+    voxelsPerMeter,
+    unlit,
+    generator,
+  });
+}

package/src/pipeline.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+import { ingestSprite, applyTransform } from './ingest.js';
+import { reconcileDims, gridViews, carve, extractSurface } from './carve.js';
+import { colorize } from './colorize.js';
+import { VIEW_NAMES } from './views.js';
+
+/**
+ * @param {Record<string, {width:number,height:number,data:ArrayLike<number>}|null>} rawViews
+ * @param {{transforms?:Record<string,{rot?:number,flipX?:boolean,flipY?:boolean}>,
+ *          mirror?:{x?:boolean,y?:boolean,z?:boolean}}} [opts]
+ */
+export function buildVoxels(rawViews, opts = {}) {
+  const transforms = opts.transforms || {};
+  /** @type {Record<string, any>} */
+  const ingested = {};
+  for (const name of VIEW_NAMES) {
+    let img = rawViews[name];
+    if (!img) continue;
+    if (transforms[name]) img = applyTransform(img, transforms[name]);
+    const v = ingestSprite(img);
+    if (v) ingested[name] = v;
+  }
+
+  const { dims, warnings } = reconcileDims(ingested);
+  if (Object.keys(ingested).length === 0) {
+    warnings.unshift('No usable views: every provided sprite was empty or missing.');
+  }
+  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) {
+    warnings.push('No opaque pixels found — every provided sprite is fully transparent.');
+  }
+
+  return {
+    dims,
+    solid,
+    surfaceMask,
+    surfaceCount: count,
+    solidCount,
+    faceColor,
+    palette,
+    warnings,
+    gviews,
+    ingested,
+    providedViews: Object.keys(ingested),
+  };
+}

package/src/png-chunks.js

@@ -0,0 +1,240 @@
+// ---------------------------------------------------------------------------
+// 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/.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+/** The 8-byte PNG signature. */
+export const PNG_SIGNATURE = Uint8Array.of(
+  0x89,
+  0x50,
+  0x4e,
+  0x47,
+  0x0d,
+  0x0a,
+  0x1a,
+  0x0a
+);
+
+/** @param {Uint8Array} bytes */
+export function isPng(bytes) {
+  if (bytes.length < PNG_SIGNATURE.length) return false;
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) return false;
+  }
+  return true;
+}
+
+// --- CRC32 (the PNG polynomial), table built once ---------------------------
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+/** CRC32 of a byte range (PNG flavor: over the chunk's type + data). @param {Uint8Array} bytes */
+export function crc32(bytes) {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) {
+    c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+const readU32 = (b, i) =>
+  ((b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3]) >>> 0;
+
+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).
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{type:string, data:Uint8Array, offset:number, end:number}[]}
+ */
+export function readChunks(bytes) {
+  if (!isPng(bytes)) throw new Error('png-chunks: not a PNG (bad signature)');
+  const chunks = [];
+  let i = PNG_SIGNATURE.length;
+  while (i < bytes.length) {
+    if (i + 8 > bytes.length) throw new Error('png-chunks: truncated chunk header');
+    const length = readU32(bytes, i);
+    const end = i + 8 + length + 4;
+    if (end > bytes.length) throw new Error('png-chunks: truncated chunk data');
+    const type = typeAt(bytes, i + 4);
+    chunks.push({ type, data: bytes.subarray(i + 8, i + 8 + length), offset: i, end });
+    i = end;
+    if (type === 'IEND') break;
+  }
+  return chunks;
+}
+
+// --- text codecs ------------------------------------------------------------
+const latin1Encodable = (s) => {
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0xff) return false;
+  return true;
+};
+const latin1Bytes = (s) => {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+};
+const latin1String = (b) => {
+  let s = '';
+  for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]);
+  return s;
+};
+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.
+ *  @param {string} type  @param {Uint8Array} data */
+export function buildChunk(type, data) {
+  const out = new Uint8Array(8 + data.length + 4);
+  const dv = new DataView(out.buffer);
+  dv.setUint32(0, data.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  dv.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+
+/** A tEXt chunk: keyword | 0 | Latin-1 text. */
+function buildTextChunk(keyword, text) {
+  const kw = latin1Bytes(keyword);
+  const tx = latin1Bytes(text);
+  const data = new Uint8Array(kw.length + 1 + tx.length);
+  data.set(kw, 0);
+  data.set(tx, kw.length + 1);
+  return buildChunk('tEXt', data);
+}
+
+/** An iTXt chunk, uncompressed: 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.
+  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).
+function decodeTextChunk(chunk) {
+  const d = chunk.data;
+  const nul = d.indexOf(0);
+  if (nul < 0) return null;
+  const keyword = latin1String(d.subarray(0, nul));
+  if (chunk.type === 'tEXt') {
+    return { keyword, text: latin1String(d.subarray(nul + 1)) };
+  }
+  // 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
+  let i = nul + 3;
+  while (i < d.length && d[i] !== 0) i++; // language tag
+  i++;
+  while (i < d.length && d[i] !== 0) i++; // translated keyword
+  i++;
+  return { keyword, text: utf8String(d.subarray(i)) };
+}
+
+/**
+ * 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.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {Record<string, string>}
+ */
+export function readTextChunks(bytes) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const chunk of readChunks(bytes)) {
+    if (chunk.type !== 'tEXt' && chunk.type !== 'iTXt') continue;
+    const decoded = decodeTextChunk(chunk);
+    if (decoded) out[decoded.keyword] = decoded.text;
+  }
+  return out;
+}
+
+/**
+ * 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.
+ *
+ * @param {Uint8Array} bytes
+ * @param {Record<string, string|null|undefined>} entries
+ * @returns {Uint8Array}
+ */
+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 */
+  const parts = [];
+  const fresh = [];
+  for (const [keyword, text] of Object.entries(entries)) {
+    if (text == null) continue;
+    if (!keyword.length || keyword.length > 79) {
+      throw new Error(`png-chunks: keyword must be 1–79 bytes ("${keyword}")`);
+    }
+    fresh.push(
+      latin1Encodable(text)
+        ? buildTextChunk(keyword, text)
+        : buildItxtChunk(keyword, text)
+    );
+  }
+
+  for (const chunk of chunks) {
+    if (chunk.type === 'tEXt' || chunk.type === 'iTXt') {
+      const decoded = decodeTextChunk(chunk);
+      if (decoded && replaced.has(decoded.keyword)) continue; // superseded
+    }
+    parts.push(bytes.subarray(chunk.offset, chunk.end));
+    if (chunk.type === 'IHDR') parts.push(...fresh.splice(0));
+  }
+  if (fresh.length) throw new Error('png-chunks: no IHDR to splice after');
+
+  let total = PNG_SIGNATURE.length;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  out.set(PNG_SIGNATURE, 0);
+  let at = PNG_SIGNATURE.length;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}

package/src/png-encode.js

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// 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.)
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+import { PNG_SIGNATURE, buildChunk } from './png-chunks.js';
+
+const BLOCK = 65535;
+
+/** Adler-32 of a byte string — the zlib trailer. @param {Uint8Array} bytes */
+export function adler32(bytes) {
+  let a = 1;
+  let b = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    a = (a + bytes[i]) % 65521;
+    b = (b + a) % 65521;
+  }
+  return ((b << 16) | a) >>> 0;
+}
+
+/** Wrap raw bytes as a zlib stream of stored deflate blocks. @param {Uint8Array} raw */
+export function zlibStored(raw) {
+  const blocks = Math.max(1, Math.ceil(raw.length / BLOCK));
+  const out = new Uint8Array(2 + blocks * 5 + raw.length + 4);
+  out[0] = 0x78;
+  out[1] = 0x01;
+  let at = 2;
+  for (let i = 0; i < blocks; i++) {
+    const start = i * BLOCK;
+    const len = Math.min(BLOCK, raw.length - start);
+    out[at++] = i === blocks - 1 ? 1 : 0; // BFINAL; BTYPE 00 = stored
+    out[at++] = len & 0xff;
+    out[at++] = (len >>> 8) & 0xff;
+    out[at++] = ~len & 0xff;
+    out[at++] = (~len >>> 8) & 0xff;
+    out.set(raw.subarray(start, start + len), at);
+    at += len;
+  }
+  new DataView(out.buffer).setUint32(at, adler32(raw)); // big-endian
+  return out;
+}
+
+/**
+ * Encode an RGBA image as a PNG file: row 0 the top row, four bytes a texel.
+ * @param {{width:number, height:number, data:Uint8Array|Uint8ClampedArray}} img
+ * @returns {Uint8Array}
+ */
+export function encodePng({ width, height, data }) {
+  if (!(width > 0 && height > 0) || !data || data.length < width * height * 4) {
+    throw new Error(
+      `encodePng: expected {width>0, height>0, data.length>=w*h*4}, got ` +
+        `${width}×${height} with ${data ? data.length : 'no'} bytes.`
+    );
+  }
+  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.set(data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const iv = new DataView(ihdr.buffer);
+  iv.setUint32(0, width);
+  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
+  const parts = [
+    PNG_SIGNATURE,
+    buildChunk('IHDR', ihdr),
+    buildChunk('IDAT', zlibStored(raw)),
+    buildChunk('IEND', new Uint8Array(0)),
+  ];
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}