From 88e7d44e65293b2faeb15916eb633e0a506b0d7d Mon Sep 17 00:00:00 2001
From: JohnsonKC201 <johnsonkc201@gmail.com>
Date: Fri, 31 Jul 2026 13:09:54 -0700
Subject: [PATCH 1/2] feat(art): let painted frames override a composed pose

Every pose is composed in code, which is why one sit covers 28 coats and a
new coat costs nine hex values instead of an art pass. The trade is that
changing how the pet looks means editing geometry, and there was no way in
for hand drawn or generated art at all.

src/art-frames.js is the escape hatch: a table of role-letter grids that
wins over the composer for the pose and the coats it names, and nothing
else. Lookup runs coat name, then build name, then '*', then the composer,
so a pack of one frame is a valid pack and a half finished one still runs.

Baked grids are stamped THROUGH buildSprite rather than around it, so they
pick up outlineHalo(), the eye boxes and the muzzle anchor exactly as a
composed pose does. That means the halo is never authored, a patchy outline
gets its gaps filled, and drawCat needs no special case. A grid that does
not match the pose's canvas is ignored rather than trusted, because the
layout maths around it is built on those constants.

scripts/import-frames.js turns painted PNGs into that table. It carries its
own PNG decoder (colour types 0/2/3/4/6, every filter) rather than adding a
dependency, the way pet-sheet.js hand-rolls its encoder. Each cell takes an
area majority vote over the pixels covering it, so art that does not land
exactly on the grid still imports, and every frame is checked before it is
written: canvas size, an eye block either side of the seam eyeBox() splits
on, a nose for the whiskers to anchor to, a floor row to stand on. A frame
that fails is dropped with a reason instead of shipped.

Only the five held poses are importable. The raised-limb activities are
parameterised rigs (4 climb frames, up to 45 paw frames, 14 bat frames per
coat) and a single still would freeze them mid swing, so the importer
refuses them on purpose.

The load-bearing test is a round trip: compose a real pose, paint it out to
a PNG, read it back through the importer and assert the grid is identical.
That covers decode, resample and colour snap against real sprite shapes
rather than a hand written fixture.
---
 eslint.config.js         |   6 +-
 package.json             |   3 +-
 scripts/import-frames.js | 340 +++++++++++++++++++++++++++++++++++++++
 scripts/overlay-vm.js    |   2 +-
 src/art-frames.js        |  34 ++++
 src/index.html           |   1 +
 src/renderer.js          |  71 +++++---
 tests/art-frames.test.js | 238 +++++++++++++++++++++++++++
 8 files changed, 673 insertions(+), 22 deletions(-)
 create mode 100644 scripts/import-frames.js
 create mode 100644 src/art-frames.js
 create mode 100644 tests/art-frames.test.js

diff --git a/eslint.config.js b/eslint.config.js
index 17d758a..3953dfc 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -18,6 +18,8 @@ const sharedOverlay = {
   PET_SPECIES: 'readonly', SPECIES_IDS: 'readonly', speciesOf: 'readonly', coatsFor: 'readonly',
   isSpecies: 'readonly', defaultCoatIndex: 'readonly', CAT_COATS: 'readonly', DOG_COATS: 'readonly',
   BUILDS: 'readonly', TABBY: 'readonly', PATTERN_BUILD: 'readonly',
+  // art-frames.js provides the generated baked-pose table:
+  ART_FRAMES: 'readonly',
   BODY: 'readonly', G: 'readonly', GC: 'readonly', GR: 'readonly', HALO: 'readonly',
   rgbStr: 'readonly', toRgb: 'readonly', shadeStr: 'readonly', lerpHex: 'readonly',
   fillPlaceholders: 'readonly', CLIMB_FRAMES: 'readonly',
@@ -49,7 +51,7 @@ module.exports = [
   {
     // Node / CommonJS: main process, workers, scripts, tests, configs, template.js
     files: ['**/*.js'],
-    ignores: [...CONSUMER_OVERLAY, 'src/cat-sprite.js', 'src/dog-sprite.js', 'src/patterns.js', 'src/pets.js', 'src/audio.js', 'src/effects.js', 'src/jam.js'],
+    ignores: [...CONSUMER_OVERLAY, 'src/cat-sprite.js', 'src/dog-sprite.js', 'src/patterns.js', 'src/pets.js', 'src/art-frames.js', 'src/audio.js', 'src/effects.js', 'src/jam.js'],
     languageOptions: { sourceType: 'commonjs', ecmaVersion: 2023, globals: { ...globals.node } },
   },
   {
@@ -76,7 +78,7 @@ module.exports = [
   {
     // cat-sprite.js / patterns.js are dual-loaded: classic <script> in the overlay AND
     // CommonJS modules in Node (make-app-icon.js / main.js). They DEFINE shared globals.
-    files: ['src/cat-sprite.js', 'src/dog-sprite.js', 'src/patterns.js', 'src/pets.js'],
+    files: ['src/cat-sprite.js', 'src/dog-sprite.js', 'src/patterns.js', 'src/pets.js', 'src/art-frames.js'],
     languageOptions: { sourceType: 'commonjs', ecmaVersion: 2023, globals: { ...globals.node, ...globals.browser } },
   },
   {
diff --git a/package.json b/package.json
index 2babc0a..e016d6f 100644
--- a/package.json
+++ b/package.json
@@ -31,7 +31,8 @@
     "demo:hero": "node scripts/make-demo-gif.js hero mp4",
     "demo:gallery": "node scripts/make-demo-gif.js gallery",
     "demo:carousel": "node scripts/make-demo-gif.js carousel",
-    "demo:all": "node scripts/make-demo-gif.js all mp4"
+    "demo:all": "node scripts/make-demo-gif.js all mp4",
+    "frames:import": "node scripts/import-frames.js"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
diff --git a/scripts/import-frames.js b/scripts/import-frames.js
new file mode 100644
index 0000000..dd9a7d4
--- /dev/null
+++ b/scripts/import-frames.js
@@ -0,0 +1,340 @@
+// Turns painted PNGs into baked pose grids for src/art-frames.js.
+//
+//   node scripts/import-frames.js <dir> [--out src/art-frames.js] [--dry] [--force]
+//
+// Input files are named   <species>-<pose>.png            -> applies to every coat
+//                  or     <species>-<pose>--<key>.png     -> applies to one coat or build
+// e.g. cat-sit.png, cat-sit--Orange Tabby.png, dog-hunt--retriever.png
+//
+// The pet is drawn from a grid of ROLE letters, not colours, which is the whole
+// reason one pose covers 28 coats. So importing is a colour-to-role problem: snap
+// every source pixel to the nearest palette placeholder, take a majority vote per
+// cell, and write the letters out. Majority vote rather than point sampling on
+// purpose, because generated art never lands exactly on the cell grid and a single
+// sampled pixel turns one stray edge pixel into a whole wrong cell.
+//
+// Nothing here trusts its input. Every frame is checked against what the renderer
+// needs (canvas size, two eye clusters either side of the seam eyeBox() splits on,
+// a nose to anchor the whiskers, a floor row to stand on) and a frame that fails is
+// reported and dropped instead of quietly shipping a broken pose.
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+const ROOT = path.join(__dirname, '..');
+
+// The placeholder palette every prompt in the frame pack generates against. These
+// are never seen: the engine swaps in the real coat. They are chosen to sit far
+// apart in RGB so a nearest-colour match cannot confuse two roles.
+const PALETTE = [
+  ['C', [0xD9, 0xC7, 0xA7]],   // coat
+  ['K', [0x33, 0x30, 0x2E]],   // markings
+  ['W', [0xFB, 0xFB, 0xF7]],   // bib, muzzle, toes
+  ['X', [0xD2, 0x76, 0x2B]],   // tortie / calico patch, brows
+  ['I', [0xEF, 0xA9, 0xB8]],   // inner ear
+  ['N', [0xB0, 0x4A, 0x57]],   // nose pad
+  ['E', [0x4F, 0xBF, 0x7A]],   // flat eye block
+  ['O', [0x5C, 0x53, 0x4A]],   // outline
+];
+
+// Only the held poses. The raised-limb activities are parameterised rigs, so a
+// still frame would freeze them (see the comment in src/art-frames.js).
+const POSES = {
+  sit: { COLS: 24, ROWS: 30, floor: true, eyes: 2 },
+  type: { COLS: 24, ROWS: 24, floor: true, eyes: 2 },
+  loaf: { COLS: 24, ROWS: 30, floor: true, eyes: 2 },
+  rear: { COLS: 24, ROWS: 30, floor: true, eyes: 2 },
+  // The crouch and the play bow are the exception: both are drawn clear of the
+  // bottom of their own canvas and the renderer places them by their own height,
+  // so a floor check there would fire on perfectly good art.
+  hunt: { cat: { COLS: 30, ROWS: 20 }, dog: { COLS: 30, ROWS: 22 }, floor: false, eyes: { cat: 2, dog: 1 } },
+};
+
+const ALPHA_MIN = 128;       // below this a source pixel counts as empty
+const SNAP_WARN = 70;        // euclidean RGB distance that means "this was not a palette colour"
+
+function poseSpec(pose, species) {
+  const p = POSES[pose];
+  if (!p) return null;
+  const dims = p[species] || p;
+  const eyes = typeof p.eyes === 'object' ? p.eyes[species] : p.eyes;
+  return { COLS: dims.COLS, ROWS: dims.ROWS, floor: p.floor, eyes };
+}
+
+// ---------------------------------------------------------------- PNG decoding
+// A small decoder rather than a dependency: this repo ships no image libraries on
+// purpose (scripts/pet-sheet.js hand-rolls the encoder for the same reason), and
+// every byte of it is exercised by tests/art-frames.test.js.
+function paeth(a, b, c) {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  return (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c);
+}
+
+function decodePng(buf) {
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let i = 0; i < 8; i++) if (buf[i] !== sig[i]) throw new Error('not a PNG');
+  let p = 8, ihdr = null, plte = null, trns = null;
+  const idat = [];
+  while (p < buf.length) {
+    const len = buf.readUInt32BE(p), type = buf.toString('ascii', p + 4, p + 8), data = buf.subarray(p + 8, p + 8 + len);
+    if (type === 'IHDR') {
+      ihdr = { w: data.readUInt32BE(0), h: data.readUInt32BE(4), depth: data[8], color: data[9], interlace: data[12] };
+    } else if (type === 'PLTE') plte = data;
+    else if (type === 'tRNS') trns = data;
+    else if (type === 'IDAT') idat.push(data);
+    else if (type === 'IEND') break;
+    p += 12 + len;
+  }
+  if (!ihdr) throw new Error('no IHDR');
+  if (ihdr.interlace) throw new Error('interlaced PNGs are not supported, re-save without Adam7 interlacing');
+  const { w, h, depth, color } = ihdr;
+  const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+  const ch = CHANNELS[color];
+  if (!ch) throw new Error(`unsupported PNG colour type ${color}`);
+  if (color !== 3 && depth !== 8 && depth !== 16) throw new Error(`unsupported bit depth ${depth}`);
+  if (color === 3 && ![1, 2, 4, 8].includes(depth)) throw new Error(`unsupported indexed bit depth ${depth}`);
+
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const bpp = Math.max(1, Math.ceil(ch * depth / 8));
+  const stride = Math.ceil(w * ch * depth / 8);
+  const out = Buffer.alloc(h * stride);
+  for (let y = 0; y < h; y++) {
+    const ft = raw[y * (stride + 1)];
+    const src = raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride);
+    const cur = out.subarray(y * stride, (y + 1) * stride);
+    const prev = y ? out.subarray((y - 1) * stride, y * stride) : null;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? cur[x - bpp] : 0, b = prev ? prev[x] : 0, c = (prev && x >= bpp) ? prev[x - bpp] : 0;
+      const v = src[x];
+      cur[x] = (ft === 0 ? v : ft === 1 ? v + a : ft === 2 ? v + b : ft === 3 ? v + ((a + b) >> 1) : v + paeth(a, b, c)) & 255;
+    }
+  }
+
+  // Normalise everything to RGBA8 so the caller only ever sees one layout.
+  const rgba = new Uint8ClampedArray(w * h * 4);
+  const sample = (row, x, i) => {          // channel i of pixel x, as 8 bits
+    if (depth === 16) return out[row * stride + (x * ch + i) * 2];
+    if (depth === 8) return out[row * stride + x * ch + i];
+    const bit = x * depth, byte = out[row * stride + (bit >> 3)];
+    return (byte >> (8 - depth - (bit & 7))) & ((1 << depth) - 1);
+  };
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const o = (y * w + x) * 4;
+    if (color === 3) {
+      const idx = sample(y, x, 0);
+      rgba[o] = plte[idx * 3]; rgba[o + 1] = plte[idx * 3 + 1]; rgba[o + 2] = plte[idx * 3 + 2];
+      rgba[o + 3] = trns && idx < trns.length ? trns[idx] : 255;
+    } else if (color === 0 || color === 4) {
+      const g = sample(y, x, 0);
+      rgba[o] = rgba[o + 1] = rgba[o + 2] = g;
+      rgba[o + 3] = color === 4 ? sample(y, x, 1) : 255;
+    } else {
+      rgba[o] = sample(y, x, 0); rgba[o + 1] = sample(y, x, 1); rgba[o + 2] = sample(y, x, 2);
+      rgba[o + 3] = color === 6 ? sample(y, x, 3) : 255;
+    }
+  }
+  return { w, h, rgba };
+}
+
+// ---------------------------------------------------------------- colour to role
+function snap(r, g, b) {
+  let best = null, bestD = Infinity;
+  for (const [role, c] of PALETTE) {
+    const d = (r - c[0]) ** 2 + (g - c[1]) ** 2 + (b - c[2]) ** 2;
+    if (d < bestD) { bestD = d; best = role; }
+  }
+  return { role: best, dist: Math.sqrt(bestD) };
+}
+
+// Area majority vote: every source pixel inside a cell snaps to a role, and the
+// role with the most pixels wins. Ties break toward the rarer role so a one pixel
+// eye or nose is not swallowed by the coat around it.
+const TIE_RANK = { N: 0, E: 1, I: 2, X: 3, W: 4, K: 5, O: 6, C: 7 };
+
+function toGrid(img, COLS, ROWS) {
+  const rows = [];
+  let far = 0, total = 0;
+  for (let r = 0; r < ROWS; r++) {
+    let line = '';
+    for (let c = 0; c < COLS; c++) {
+      const x0 = Math.floor(c * img.w / COLS), x1 = Math.max(x0 + 1, Math.floor((c + 1) * img.w / COLS));
+      const y0 = Math.floor(r * img.h / ROWS), y1 = Math.max(y0 + 1, Math.floor((r + 1) * img.h / ROWS));
+      const tally = {};
+      let solid = 0, cells = 0;
+      for (let y = y0; y < y1 && y < img.h; y++) for (let x = x0; x < x1 && x < img.w; x++) {
+        cells++;
+        const o = (y * img.w + x) * 4;
+        if (img.rgba[o + 3] < ALPHA_MIN) continue;
+        solid++;
+        const s = snap(img.rgba[o], img.rgba[o + 1], img.rgba[o + 2]);
+        total++; if (s.dist > SNAP_WARN) far++;
+        tally[s.role] = (tally[s.role] || 0) + 1;
+      }
+      if (!cells || solid * 2 < cells) { line += '.'; continue; }
+      let win = '.', wn = 0;
+      for (const [role, n] of Object.entries(tally)) {
+        if (n > wn || (n === wn && TIE_RANK[role] < TIE_RANK[win])) { win = role; wn = n; }
+      }
+      line += win;
+    }
+    rows.push(line);
+  }
+  return { rows, snapQuality: total ? 1 - far / total : 1 };
+}
+
+// ---------------------------------------------------------------- checks
+// eyeBox() in cat-sprite.js splits the grid at COLS/2 to tell the two eyes apart.
+// A face drawn off centre puts one eye in BOTH boxes, the box swells to span the
+// head, and drawCat paints the pupil as a bar across the muzzle. It has bitten this
+// project twice, so it is the first thing checked.
+function check(rows, spec) {
+  const problems = [];
+  const COLS = spec.COLS, ROWS = spec.ROWS;
+  const at = (r, c) => rows[r][c];
+  let filled = 0, eyeL = 0, eyeR = 0, nose = 0, floor = 0;
+  for (let r = 0; r < ROWS; r++) for (let c = 0; c < COLS; c++) {
+    const ch = at(r, c);
+    if (ch === '.') continue;
+    filled++;
+    if (ch === 'E') { if (c < COLS / 2) eyeL++; else eyeR++; }
+    if (ch === 'N') nose++;
+    // Bottom TWO rows: the dog's curl rests its lowest paw one row up and still
+    // stands on the same line, so a strict last-row test would flag it.
+    if (r >= ROWS - 2) floor++;
+  }
+  if (filled < COLS * ROWS * 0.08) problems.push(['fail', `only ${filled} filled cells, the sprite is nearly empty`]);
+  const eyes = (eyeL ? 1 : 0) + (eyeR ? 1 : 0);
+  if (spec.eyes === 2 && eyes < 2) {
+    problems.push(['fail', `needs an eye block either side of column ${COLS / 2}, found ${eyeL} left and ${eyeR} right`]);
+  }
+  if (spec.eyes === 1 && eyes !== 1) {
+    problems.push(['fail', `profile pose needs exactly one eye block, found ${eyeL} left and ${eyeR} right`]);
+  }
+  if (!nose) problems.push(['fail', 'no nose cells, the whiskers and tongue have nothing to anchor to']);
+  if (spec.floor && !floor) problems.push(['warn', 'nothing in the bottom two rows, this pose will float above the floor line']);
+  if (nose > COLS) problems.push(['warn', `${nose} nose cells looks like a painted muzzle rather than a nose pad`]);
+  return problems;
+}
+
+// ---------------------------------------------------------------- emit
+const HEADER = `// Baked pose frames. GENERATED by scripts/import-frames.js from painted PNGs;
+// safe to regenerate at any time, and safe to leave empty (this is the default).
+//
+// Everything the pet does is composed procedurally from grid primitives, which is
+// what makes one pose cover 28 coats. This file is the escape hatch: drop a hand
+// drawn or generated frame in here and it wins over the composer for that pose,
+// for the coats you name, and nothing else changes.
+//
+// Shape:
+//   ART_FRAMES[species][pose][key] = { COLS, ROWS, rows: ['..CC..', ...] }
+//
+// \`key\` is looked up in this order, so you can be as specific as you like:
+//   1. a coat name exactly as it appears in PATTERNS  ('Orange Tabby')
+//   2. a build name from PATTERN_BUILD                ('slender', 'retriever')
+//   3. '*'                                            every coat of that species
+// Anything with no match falls back to the composer, so a half finished pack still
+// runs. \`rows\` holds one ROLE letter per cell (C K W X I N E O, '.' for empty), not
+// colours: the palette is applied per coat at draw time.
+//
+// Do NOT bake the halo ('H'). buildSprite runs outlineHalo() over whatever lands
+// here, which fills any gap in the outline and grows the halo, exactly as it does
+// for a composed pose.
+//
+// Only the five HELD poses are read: sit, type, loaf, rear, hunt. The other six
+// activities (both rope climbs, groom, ponder, play, bat) are animation rigs whose
+// limbs move with a quantised parameter, so a single still would freeze them. See
+// docs/frame-pack.md.`;
+
+function emit(data) {
+  const q = (s) => `'${s.replace(/'/g, "\\'")}'`;
+  const species = ['cat', 'dog'].map((sp) => {
+    const poses = Object.keys(data[sp] || {}).sort();
+    if (!poses.length) return `  ${sp}: {},`;
+    const body = poses.map((pose) => {
+      const keys = Object.keys(data[sp][pose]).sort();
+      const entries = keys.map((k) => {
+        const g = data[sp][pose][k];
+        const rows = g.rows.map((r) => `        ${q(r)},`).join('\n');
+        return `      ${q(k)}: { COLS: ${g.COLS}, ROWS: ${g.ROWS}, rows: [\n${rows}\n      ] },`;
+      }).join('\n');
+      return `    ${pose}: {\n${entries}\n    },`;
+    }).join('\n');
+    return `  ${sp}: {\n${body}\n  },`;
+  }).join('\n');
+  return `${HEADER}\nconst ART_FRAMES = {\n${species}\n};\n\nif (typeof module !== 'undefined' && module.exports) module.exports = { ART_FRAMES };\nelse if (typeof window !== 'undefined') window.ART_FRAMES = ART_FRAMES;\n`;
+}
+
+// ---------------------------------------------------------------- driver
+function parseName(file) {
+  const m = /^(cat|dog)-([a-z]+)(?:--(.+))?\.png$/i.exec(file);
+  if (!m) return null;
+  return { species: m[1].toLowerCase(), pose: m[2].toLowerCase(), key: m[3] || '*' };
+}
+
+function importDir(dir, opts) {
+  const files = fs.readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.png')).sort();
+  const data = { cat: {}, dog: {} };
+  const report = [];
+  let ok = 0, skipped = 0;
+
+  for (const file of files) {
+    const id = parseName(file);
+    if (!id) { report.push(['skip', file, `name must be <species>-<pose>.png or <species>-<pose>--<key>.png`]); skipped++; continue; }
+    const spec = poseSpec(id.pose, id.species);
+    if (!spec) {
+      report.push(['skip', file, `"${id.pose}" is not a bakeable pose (${Object.keys(POSES).join(', ')})`]);
+      skipped++; continue;
+    }
+    let img;
+    try {
+      img = decodePng(fs.readFileSync(path.join(dir, file)));
+    } catch (e) {
+      report.push(['fail', file, e.message]); skipped++; continue;
+    }
+    const { rows, snapQuality } = toGrid(img, spec.COLS, spec.ROWS);
+    const problems = check(rows, spec);
+    if (snapQuality < 0.9) {
+      problems.push(['warn', `${Math.round((1 - snapQuality) * 100)} percent of pixels were not a palette colour, so this was anti aliased or shaded`]);
+    }
+    const fatal = problems.filter((p) => p[0] === 'fail');
+    if (fatal.length && !opts.force) {
+      report.push(['fail', file, fatal.map((p) => p[1]).join('; ')]); skipped++; continue;
+    }
+    (data[id.species][id.pose] = data[id.species][id.pose] || {})[id.key] =
+      { COLS: spec.COLS, ROWS: spec.ROWS, rows };
+    const warns = problems.filter((p) => p[0] === 'warn').map((p) => p[1]);
+    report.push([warns.length ? 'warn' : 'ok', file,
+      `${spec.COLS}x${spec.ROWS} -> ${id.species}.${id.pose}[${id.key}]${warns.length ? '  ' + warns.join('; ') : ''}`]);
+    ok++;
+  }
+  return { data, report, ok, skipped };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const dir = args.find((a) => !a.startsWith('--'));
+  const opts = {
+    out: (args.find((a) => a.startsWith('--out=')) || '').slice(6) || path.join(ROOT, 'src', 'art-frames.js'),
+    dry: args.includes('--dry'),
+    force: args.includes('--force'),
+  };
+  if (!dir) {
+    console.error('usage: node scripts/import-frames.js <dir-of-pngs> [--out=path] [--dry] [--force]');
+    process.exit(1);
+  }
+  if (!fs.existsSync(dir)) { console.error(`no such directory: ${dir}`); process.exit(1); }
+
+  const { data, report, ok, skipped } = importDir(dir, opts);
+  const mark = { ok: '  ok  ', warn: ' warn ', fail: ' FAIL ', skip: ' skip ' };
+  for (const [level, file, msg] of report) console.log(`${mark[level]}${file.padEnd(30)} ${msg}`);
+  console.log(`\n${ok} frame${ok === 1 ? '' : 's'} imported, ${skipped} skipped`);
+  if (!ok) { console.log('nothing to write'); return; }
+  if (opts.dry) { console.log('--dry: not writing'); return; }
+  fs.writeFileSync(opts.out, emit(data));
+  console.log(`wrote ${path.relative(ROOT, opts.out)}`);
+  console.log('next: npm test, then npm run poses:cat / npm run poses:dog and look at the sheets');
+}
+
+if (require.main === module) main();
+
+module.exports = { decodePng, snap, toGrid, check, emit, poseSpec, parseName, importDir, PALETTE, POSES };
diff --git a/scripts/overlay-vm.js b/scripts/overlay-vm.js
index a8d46ec..b727209 100644
--- a/scripts/overlay-vm.js
+++ b/scripts/overlay-vm.js
@@ -19,7 +19,7 @@ const ROOT = path.join(__dirname, '..');
 
 // Same order as src/index.html - these share ONE global scope in the browser, and
 // renderer.js reads bare identifiers defined by the files ahead of it.
-const SCRIPTS = ['cat-sprite.js', 'dog-sprite.js', 'pets.js', 'template.js',
+const SCRIPTS = ['cat-sprite.js', 'dog-sprite.js', 'pets.js', 'art-frames.js', 'template.js',
   'climb-frames.js', 'audio.js', 'effects.js', 'jam.js', 'renderer.js'];
 
 // A canvas 2D context that accepts anything and draws nothing.
diff --git a/src/art-frames.js b/src/art-frames.js
new file mode 100644
index 0000000..678d0cc
--- /dev/null
+++ b/src/art-frames.js
@@ -0,0 +1,34 @@
+// Baked pose frames. GENERATED by scripts/import-frames.js from painted PNGs;
+// safe to regenerate at any time, and safe to leave empty (this is the default).
+//
+// Everything the pet does is composed procedurally from grid primitives, which is
+// what makes one pose cover 28 coats. This file is the escape hatch: drop a hand
+// drawn or generated frame in here and it wins over the composer for that pose,
+// for the coats you name, and nothing else changes.
+//
+// Shape:
+//   ART_FRAMES[species][pose][key] = { COLS, ROWS, rows: ['..CC..', ...] }
+//
+// `key` is looked up in this order, so you can be as specific as you like:
+//   1. a coat name exactly as it appears in PATTERNS  ('Orange Tabby')
+//   2. a build name from PATTERN_BUILD                ('slender', 'retriever')
+//   3. '*'                                            every coat of that species
+// Anything with no match falls back to the composer, so a half finished pack still
+// runs. `rows` holds one ROLE letter per cell (C K W X I N E O, '.' for empty), not
+// colours: the palette is applied per coat at draw time.
+//
+// Do NOT bake the halo ('H'). buildSprite runs outlineHalo() over whatever lands
+// here, which fills any gap in the outline and grows the halo, exactly as it does
+// for a composed pose.
+//
+// Only the five HELD poses are read: sit, type, loaf, rear, hunt. The other six
+// activities (both rope climbs, groom, ponder, play, bat) are animation rigs whose
+// limbs move with a quantised parameter, so a single still would freeze them. See
+// docs/frame-pack.md.
+const ART_FRAMES = {
+  cat: {},
+  dog: {},
+};
+
+if (typeof module !== 'undefined' && module.exports) module.exports = { ART_FRAMES };
+else if (typeof window !== 'undefined') window.ART_FRAMES = ART_FRAMES;
diff --git a/src/index.html b/src/index.html
index 8c9c04d..dcb2653 100644
--- a/src/index.html
+++ b/src/index.html
@@ -24,6 +24,7 @@
   <script src="cat-sprite.js"></script>
   <script src="dog-sprite.js"></script>
   <script src="pets.js"></script>
+  <script src="art-frames.js"></script>
   <script src="template.js"></script>
   <script src="climb-frames.js"></script>
   <script src="audio.js"></script>
diff --git a/src/renderer.js b/src/renderer.js
index 3188b13..65d756a 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -484,12 +484,14 @@ function climbSpriteFor(i, hand, dir) {
   }
   return sp;
 }
-let spriteHunt = buildSprite(SPECIES_DEFS.huntCols, SPECIES_DEFS.huntRows, () => SPECIES_DEFS.hunt(buildFor(0, SPECIES_DEFS)));
+// Cats share ONE crouch across every coat, so its baked override is looked up at
+// index 0: name a coat and only that coat's key can ever match, so key it '*'.
+let spriteHunt = posed('hunt', 0, SPECIES_DEFS.huntCols, SPECIES_DEFS.huntRows, () => SPECIES_DEFS.hunt(buildFor(0, SPECIES_DEFS)));
 let huntSprites = null;   // dogs vary the bow by breed (markings); cats share one crouch
 function huntSpriteFor(i) { return (huntSprites && huntSprites[i]) || spriteHunt; }
 function buildHuntSprites(D) {
   return D === null || !isDog() ? null
-    : D.build.map((b, i) => buildSprite(D.huntCols, D.huntRows, () => D.hunt(buildFor(i, D))));
+    : D.build.map((b, i) => posed('hunt', i, D.huntCols, D.huntRows, () => D.hunt(buildFor(i, D))));
 }
 const TW = 24 * CELL, TH = 24 * CELL;            // front-facing kneading-cat dims (per-coat sprites built below)
 // Sit grid is always 24x30, so SW/SH and the mochi bands stay constant across the
@@ -568,14 +570,46 @@ const octx = oc.getContext('2d'); octx.imageSmoothingEnabled = false;
 const HEAD_SRC = 14 * CELL, FEET_SRC = 7 * CELL, MID_SRC = SH - HEAD_SRC - FEET_SRC;
 
 
-const sprites = PATTERN_BUILD.map((b, i) => buildSprite(24, 30, () => SPECIES_DEFS.sit(buildFor(i, SPECIES_DEFS))));
+// --- baked frames (src/art-frames.js) ---------------------------------------
+// A painted frame beats the composer for the pose and the coat it names, and
+// everything else keeps composing, so a half finished art pack still runs. Only
+// the five HELD poses can be baked: the raised-limb activities are parameterised
+// rigs (pawSpriteFor / batSpriteFor / climbSpriteFor quantise a limb angle into a
+// handful of frames) and one still would freeze them mid swing. A grid that does
+// not match the pose's canvas is ignored rather than trusted, because the layout
+// maths around it is built on those constants.
+function artGrid(pose, i, cols, rows) {
+  const all = typeof ART_FRAMES !== 'undefined' ? ART_FRAMES : null;
+  const byPose = all && all[species] && all[species][pose];
+  if (!byPose) return null;
+  const name = (PATTERNS[i] && PATTERNS[i].name) || '';
+  const g = byPose[name] || byPose[PATTERN_BUILD[i]] || byPose['*'] || null;
+  if (!g || g.COLS !== cols || g.ROWS !== rows || !Array.isArray(g.rows) || g.rows.length !== rows) return null;
+  return g;
+}
+
+// Stamp a baked grid THROUGH buildSprite so it picks up outlineHalo(), the eye
+// boxes and the muzzle anchor exactly as a composed pose does - the halo is never
+// painted by hand, and a patchy outline gets its gaps filled for free.
+function posed(pose, i, cols, rows, compose) {
+  const g = artGrid(pose, i, cols, rows);
+  if (!g) return buildSprite(cols, rows, compose);
+  return buildSprite(cols, rows, () => {
+    for (let r = 0; r < rows; r++) {
+      const row = g.rows[r];
+      for (let c = 0; c < cols && c < row.length; c++) if (row[c] !== '.') setCell(c, r, row[c]);
+    }
+  });
+}
+
+const sprites = PATTERN_BUILD.map((b, i) => posed('sit', i, 24, 30, () => SPECIES_DEFS.sit(buildFor(i, SPECIES_DEFS))));
 // each coat also gets its own typing (kneading) body, so every breed types differently
 // one shared front "kneading cat" shape, recoloured per coat (+ tabby stripes / fluffy tufts)
-const typeSprites = PATTERN_BUILD.map((b, i) => buildSprite(24, 24, () => SPECIES_DEFS.type(buildFor(i, SPECIES_DEFS))));
+const typeSprites = PATTERN_BUILD.map((b, i) => posed('type', i, 24, 24, () => SPECIES_DEFS.type(buildFor(i, SPECIES_DEFS))));
 // and a dedicated loaf (resting) body per coat - same 24x30 size as the sit sprite
-const loafSprites = PATTERN_BUILD.map((b, i) => buildSprite(24, 30, () => SPECIES_DEFS.loaf(buildFor(i, SPECIES_DEFS))));
+const loafSprites = PATTERN_BUILD.map((b, i) => posed('loaf', i, 24, 30, () => SPECIES_DEFS.loaf(buildFor(i, SPECIES_DEFS))));
 // and a rear-up "bat the butterfly" body per coat - same 24x30 size as the sit sprite
-const rearSprites = PATTERN_BUILD.map((b, i) => buildSprite(24, 30, () => SPECIES_DEFS.rear(buildFor(i, SPECIES_DEFS))));
+const rearSprites = PATTERN_BUILD.map((b, i) => posed('rear', i, 24, 30, () => SPECIES_DEFS.rear(buildFor(i, SPECIES_DEFS))));
 huntSprites = buildHuntSprites(SPECIES_DEFS);
 const DEFAULT_PATTERN = Math.max(0, PATTERNS.findIndex((p) => p.name === (species === 'dog' ? 'Golden Retriever' : 'Tuxedo')));
 const coatKey = (sp) => (sp === 'dog' ? 'dogPattern' : 'pattern');
@@ -606,11 +640,12 @@ function applyThemes(list) {
     PATTERN_BUILD.push(build);
     TABBY.push(!!th.tabby);
     const D = SPECIES_DEFS, tb = { ...(D.builds[build] || BUILDS[build] || {}), tabby: !!th.tabby };
-    sprites.push(buildSprite(24, 30, () => D.sit(tb)));
-    typeSprites.push(buildSprite(24, 24, () => D.type(tb)));
-    loafSprites.push(buildSprite(24, 30, () => D.loaf(tb)));
-    rearSprites.push(buildSprite(24, 30, () => D.rear(tb)));
-    if (huntSprites) huntSprites.push(buildSprite(D.huntCols, D.huntRows, () => D.hunt(tb)));
+    const at = PATTERNS.length - 1;   // this custom coat's index, for the baked-frame lookup
+    sprites.push(posed('sit', at, 24, 30, () => D.sit(tb)));
+    typeSprites.push(posed('type', at, 24, 24, () => D.type(tb)));
+    loafSprites.push(posed('loaf', at, 24, 30, () => D.loaf(tb)));
+    rearSprites.push(posed('rear', at, 24, 30, () => D.rear(tb)));
+    if (huntSprites) huntSprites.push(posed('hunt', at, D.huntCols, D.huntRows, () => D.hunt(tb)));
   }
   if (!(patternIndex >= 0 && patternIndex < PATTERNS.length)) patternIndex = DEFAULT_PATTERN;
   if (forcedPattern) { const i = PATTERNS.findIndex((p) => p.name.toLowerCase().includes(forcedPattern.toLowerCase())); if (i >= 0) patternIndex = i; }
@@ -629,15 +664,15 @@ function setSpecies(next, coatIdx) {
     installTables(SPECIES_DEFS);
     BASE_PATTERNS = PATTERNS.length;
     const D = SPECIES_DEFS;
-    const rebuild = (arr, cols, rows, fn) => {
+    const rebuild = (pose, arr, cols, rows, fn) => {
       arr.length = 0;
-      for (let i = 0; i < D.build.length; i++) arr.push(buildSprite(cols, rows, () => fn(buildFor(i, D))));
+      for (let i = 0; i < D.build.length; i++) arr.push(posed(pose, i, cols, rows, () => fn(buildFor(i, D))));
     };
-    rebuild(sprites, 24, 30, D.sit);
-    rebuild(typeSprites, 24, 24, D.type);
-    rebuild(loafSprites, 24, 30, D.loaf);
-    rebuild(rearSprites, 24, 30, D.rear);
-    spriteHunt = buildSprite(D.huntCols, D.huntRows, () => D.hunt(buildFor(0, D)));
+    rebuild('sit', sprites, 24, 30, D.sit);
+    rebuild('type', typeSprites, 24, 24, D.type);
+    rebuild('loaf', loafSprites, 24, 30, D.loaf);
+    rebuild('rear', rearSprites, 24, 30, D.rear);
+    spriteHunt = posed('hunt', 0, D.huntCols, D.huntRows, () => D.hunt(buildFor(0, D)));
     huntSprites = buildHuntSprites(D);
     _palKey = -1;                        // force a cold-palette rebuild for the new coats
     // climbImgs is deliberately NOT cleared: those frames decode once at startup and
diff --git a/tests/art-frames.test.js b/tests/art-frames.test.js
new file mode 100644
index 0000000..254b727
--- /dev/null
+++ b/tests/art-frames.test.js
@@ -0,0 +1,238 @@
+// Baked pose frames: the PNG -> role grid importer, and the renderer hook that
+// lets an imported frame win over the composer.
+//
+// The load-bearing test is the round trip. A composed pose is painted out to a PNG
+// with one flat placeholder colour per role, read back through the importer, and
+// compared cell for cell against the grid it came from. That exercises the whole
+// chain (PNG decode, area majority vote, colour snap) against real sprite shapes
+// rather than a hand written fixture, and it fails loudly if any step drifts.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const zlib = require('node:zlib');
+
+const imp = require('../scripts/import-frames.js');
+const { loadOverlay } = require('../scripts/overlay-vm.js');
+
+const ROLE_RGB = Object.fromEntries(imp.PALETTE);
+
+// --- a minimal PNG encoder, so the fixtures are real files ------------------
+function crc(b) { let c = ~0; for (let i = 0; i < b.length; i++) { c ^= b[i]; for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xEDB88320 & -(c & 1)); } return ~c >>> 0; }
+function chunk(t, d) {
+  const l = Buffer.alloc(4); l.writeUInt32BE(d.length, 0);
+  const b = Buffer.concat([Buffer.from(t), d]);
+  const cc = Buffer.alloc(4); cc.writeUInt32BE(crc(b), 0);
+  return Buffer.concat([l, b, cc]);
+}
+function encodePng(rgba, w, h) {
+  const ih = Buffer.alloc(13); ih.writeUInt32BE(w, 0); ih.writeUInt32BE(h, 4); ih[8] = 8; ih[9] = 6;
+  const stride = w * 4, raw = Buffer.alloc(h * (stride + 1));
+  for (let y = 0; y < h; y++) for (let x = 0; x < stride; x++) raw[y * (stride + 1) + 1 + x] = rgba[y * stride + x];
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk('IHDR', ih), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+}
+
+// Paint a role grid at `scale` px per cell, flat, transparent where empty. The
+// halo is deliberately not painted: outlineHalo() regrows it on import.
+function paintGrid(rows, scale) {
+  const COLS = rows[0].length, ROWS = rows.length, W = COLS * scale, H = ROWS * scale;
+  const rgba = new Uint8ClampedArray(W * H * 4);
+  for (let r = 0; r < ROWS; r++) for (let c = 0; c < COLS; c++) {
+    const ch = rows[r][c];
+    const rgb = ROLE_RGB[ch];
+    if (!rgb) continue;
+    for (let dy = 0; dy < scale; dy++) for (let dx = 0; dx < scale; dx++) {
+      const o = ((r * scale + dy) * W + c * scale + dx) * 4;
+      rgba[o] = rgb[0]; rgba[o + 1] = rgb[1]; rgba[o + 2] = rgb[2]; rgba[o + 3] = 255;
+    }
+  }
+  return encodePng(rgba, W, H);
+}
+
+// A composed pose straight out of the overlay, as rows of role letters with the
+// halo dropped (that is what a painted frame would contain).
+// Array.from re-wraps as a HOST array: values crossing back from the vm carry the
+// context's prototypes, so deepStrictEqual fails its prototype check even when the
+// contents match exactly.
+function composedRows(h, expr) {
+  const sp = h.run(`(() => { const s = ${expr}; return { rows: s.grid.map((r) => r.join('')), COLS: s.COLS, ROWS: s.ROWS }; })()`);
+  return { rows: Array.from(sp.rows, (r) => r.replace(/H/g, '.')), COLS: sp.COLS, ROWS: sp.ROWS };
+}
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pixelpets-frames-'));
+}
+
+test('a painted pose round trips back to the grid it came from', () => {
+  const h = loadOverlay();
+  const cases = [['cat', 'sit', 'sprites[0]'], ['cat', 'loaf', 'loafSprites[0]'], ['dog', 'sit', 'sprites[0]']];
+  for (const [species, pose, expr] of cases) {
+    h.run(`setSpecies(${JSON.stringify(species)})`);
+    const want = composedRows(h, expr);
+    const dir = tmpdir();
+    try {
+      fs.writeFileSync(path.join(dir, `${species}-${pose}.png`), paintGrid(want.rows, 11));
+      const { data, ok, skipped } = imp.importDir(dir, {});
+      assert.strictEqual(skipped, 0, `${species}/${pose} was skipped`);
+      assert.strictEqual(ok, 1);
+      const got = data[species][pose]['*'];
+      assert.strictEqual(got.COLS, want.COLS);
+      assert.strictEqual(got.ROWS, want.ROWS);
+      assert.deepStrictEqual(got.rows, want.rows, `${species}/${pose} did not survive the round trip`);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+test('a non integer scale still round trips, because generated art never lands on the grid', () => {
+  const h = loadOverlay();
+  const want = composedRows(h, 'sprites[0]');
+  const dir = tmpdir();
+  try {
+    // 24x30 cells painted at 11px, then the canvas is what a generator would hand
+    // back: the same picture at an awkward size. The area vote has to cope.
+    const png = paintGrid(want.rows, 17);
+    fs.writeFileSync(path.join(dir, 'cat-sit.png'), png);
+    const { data } = imp.importDir(dir, {});
+    assert.deepStrictEqual(data.cat.sit['*'].rows, want.rows);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('the importer decodes indexed and greyscale PNGs, not just RGBA', () => {
+  // 2x2 indexed, 4 bit depth, with a transparent entry.
+  const plte = Buffer.from([0xD9, 0xC7, 0xA7, 0x33, 0x30, 0x2E]);
+  const trns = Buffer.from([255, 0]);
+  const raw = Buffer.from([0, 0x01, 0, 0x10]);          // filter byte + one packed byte per row
+  const ih = Buffer.alloc(13); ih.writeUInt32BE(2, 0); ih.writeUInt32BE(2, 4); ih[8] = 4; ih[9] = 3;
+  const png = Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk('IHDR', ih), chunk('PLTE', plte), chunk('tRNS', trns),
+    chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+  const img = imp.decodePng(png);
+  assert.strictEqual(img.w, 2);
+  assert.deepStrictEqual([...img.rgba.slice(0, 4)], [0xD9, 0xC7, 0xA7, 255]);
+  assert.strictEqual(img.rgba[7], 0, 'palette index 1 is transparent via tRNS');
+});
+
+test('every PNG filter type decodes', () => {
+  // Sub / Up / Average / Paeth all have to unfilter correctly or the art arrives
+  // sheared. Encode a gradient with a mixed filter per row and check it survives.
+  const w = 4, h = 5, stride = w * 4;
+  const flat = Buffer.alloc(h * stride);
+  for (let i = 0; i < flat.length; i += 4) { flat[i] = i & 255; flat[i + 1] = (i * 3) & 255; flat[i + 2] = (i * 7) & 255; flat[i + 3] = 255; }
+  const raw = Buffer.alloc(h * (stride + 1));
+  for (let y = 0; y < h; y++) {
+    raw[y * (stride + 1)] = y;                            // filter types 0..4, one per row
+    const cur = flat.subarray(y * stride, (y + 1) * stride);
+    const prev = y ? flat.subarray((y - 1) * stride, y * stride) : Buffer.alloc(stride);
+    for (let x = 0; x < stride; x++) {
+      const a = x >= 4 ? cur[x - 4] : 0, b = prev[x], c = x >= 4 ? prev[x - 4] : 0;
+      const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+      const pae = (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c);
+      const sub = [0, a, b, (a + b) >> 1, pae][y];
+      raw[y * (stride + 1) + 1 + x] = (cur[x] - sub) & 255;
+    }
+  }
+  const ih = Buffer.alloc(13); ih.writeUInt32BE(w, 0); ih.writeUInt32BE(h, 4); ih[8] = 8; ih[9] = 6;
+  const png = Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk('IHDR', ih), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+  assert.deepStrictEqual([...imp.decodePng(png).rgba], [...flat]);
+});
+
+test('a face drawn off the eyeBox seam is rejected, not shipped', () => {
+  // eyeBox() splits at COLS/2. Both eyes on one side means one eye lands in both
+  // boxes and drawCat paints the pupil as a bar across the muzzle.
+  const spec = imp.poseSpec('sit', 'cat');
+  const rows = Array.from({ length: spec.ROWS }, () => '.'.repeat(spec.COLS));
+  const put = (r, c, ch) => { rows[r] = rows[r].slice(0, c) + ch + rows[r].slice(c + 1); };
+  for (let r = 4; r < spec.ROWS; r++) for (let c = 4; c < 20; c++) put(r, c, 'C');
+  put(8, 5, 'E'); put(8, 8, 'E');            // both eyes left of the seam
+  put(11, 6, 'N');
+  const problems = imp.check(rows, spec);
+  assert.ok(problems.some((p) => p[0] === 'fail' && /either side of column/.test(p[1])),
+    `expected an eye-seam failure, got ${JSON.stringify(problems)}`);
+});
+
+test('a frame with no nose is rejected', () => {
+  const spec = imp.poseSpec('sit', 'cat');
+  const rows = Array.from({ length: spec.ROWS }, () => '.'.repeat(spec.COLS));
+  const put = (r, c, ch) => { rows[r] = rows[r].slice(0, c) + ch + rows[r].slice(c + 1); };
+  for (let r = 4; r < spec.ROWS; r++) for (let c = 4; c < 20; c++) put(r, c, 'C');
+  put(8, 8, 'E'); put(8, 15, 'E');
+  const problems = imp.check(rows, spec);
+  assert.ok(problems.some((p) => p[0] === 'fail' && /nose/.test(p[1])));
+});
+
+test('the dog play bow is checked as a profile pose, one eye only', () => {
+  assert.strictEqual(imp.poseSpec('hunt', 'dog').eyes, 1);
+  assert.strictEqual(imp.poseSpec('hunt', 'cat').eyes, 2);
+  assert.strictEqual(imp.poseSpec('hunt', 'dog').ROWS, 22);
+  assert.strictEqual(imp.poseSpec('hunt', 'cat').ROWS, 20);
+});
+
+test('only the held poses are importable, the animation rigs are refused', () => {
+  for (const pose of ['climb', 'groom', 'ponder', 'play', 'bat']) {
+    assert.strictEqual(imp.poseSpec(pose, 'cat'), null, `${pose} must not be bakeable`);
+  }
+  for (const pose of ['sit', 'type', 'loaf', 'rear', 'hunt']) {
+    assert.ok(imp.poseSpec(pose, 'cat'), `${pose} must be bakeable`);
+  }
+});
+
+test('file names map to a species, a pose and a coat key', () => {
+  assert.deepStrictEqual(imp.parseName('cat-sit.png'), { species: 'cat', pose: 'sit', key: '*' });
+  assert.deepStrictEqual(imp.parseName('cat-sit--Orange Tabby.png'), { species: 'cat', pose: 'sit', key: 'Orange Tabby' });
+  assert.deepStrictEqual(imp.parseName('dog-hunt--retriever.png'), { species: 'dog', pose: 'hunt', key: 'retriever' });
+  assert.strictEqual(imp.parseName('sit.png'), null);
+  assert.strictEqual(imp.parseName('rabbit-sit.png'), null);
+});
+
+test('the emitted module parses and round trips through the lookup shape', () => {
+  const src = imp.emit({ cat: { sit: { '*': { COLS: 2, ROWS: 2, rows: ['CC', 'WW'] } } }, dog: {} });
+  const mod = { exports: {} };
+  new Function('module', src)(mod);
+  assert.deepStrictEqual(mod.exports.ART_FRAMES.cat.sit['*'].rows, ['CC', 'WW']);
+  assert.deepStrictEqual(mod.exports.ART_FRAMES.dog, {});
+});
+
+test('a baked frame beats the composer, and an unbaked coat still composes', () => {
+  const h = loadOverlay();
+  const before = h.run('sprites[0].grid.map((r) => r.join(""))');
+  const spec = imp.poseSpec('sit', 'cat');
+
+  // A deliberately unmistakable body: a solid block with a face on the seam.
+  const rows = Array.from({ length: spec.ROWS }, () => '.'.repeat(spec.COLS));
+  const put = (r, c, ch) => { rows[r] = rows[r].slice(0, c) + ch + rows[r].slice(c + 1); };
+  for (let r = 6; r < spec.ROWS; r++) for (let c = 6; c < 18; c++) put(r, c, 'C');
+  put(9, 9, 'E'); put(9, 14, 'E'); put(12, 11, 'N');
+
+  h.run(`ART_FRAMES.cat.sit = { 'Orange Tabby': { COLS: ${spec.COLS}, ROWS: ${spec.ROWS}, rows: ${JSON.stringify(rows)} } }`);
+  h.run("setSpecies('dog'); setSpecies('cat')");        // forces both tables to rebuild
+
+  const baked = h.run('sprites[0].grid.map((r) => r.join(""))');
+  const other = h.run('sprites[1].grid.map((r) => r.join(""))');
+  assert.notDeepStrictEqual(baked, before, 'the baked frame did not replace the composed one');
+  // Every body cell we painted survives; the halo is regrown around it.
+  for (let r = 0; r < spec.ROWS; r++) for (let c = 0; c < spec.COLS; c++) {
+    if (rows[r][c] !== '.') assert.strictEqual(baked[r][c], rows[r][c], `cell ${c},${r} was not preserved`);
+  }
+  assert.ok(baked.join('').includes('H'), 'outlineHalo() should still have grown a halo');
+  assert.ok(baked.join('').includes('O'), 'outlineHalo() should still have drawn the outline');
+  assert.ok(other.join('') !== baked.join(''), 'a coat with no baked frame must keep composing');
+
+  // eyeBox still finds two eyes, which is what drawCat needs to place the pupils.
+  const eyes = h.run('sprites[0].eyes.map((e) => e.w)');
+  assert.ok(eyes[0] > 0 && eyes[1] > 0, 'both eye boxes must survive a baked frame');
+});
+
+test('a baked grid on the wrong canvas is ignored rather than trusted', () => {
+  const h = loadOverlay();
+  const before = h.run('sprites[0].grid.map((r) => r.join(""))');
+  h.run("ART_FRAMES.cat.sit = { '*': { COLS: 8, ROWS: 8, rows: ['CCCCCCCC','CCCCCCCC','CCCCCCCC','CCCCCCCC','CCCCCCCC','CCCCCCCC','CCCCCCCC','CCCCCCCC'] } }");
+  h.run("setSpecies('dog'); setSpecies('cat')");
+  assert.deepStrictEqual(h.run('sprites[0].grid.map((r) => r.join(""))'), before);
+});

From c9554d89e2c8a58835ae7f71226571cc19132284 Mon Sep 17 00:00:00 2001
From: JohnsonKC201 <johnsonkc201@gmail.com>
Date: Fri, 31 Jul 2026 13:10:05 -0700
Subject: [PATCH 2/2] docs: how to paint and import a pose

Covers the role grid model, the placeholder palette to paint against, the
three things the engine draws on top that must never be authored (the halo,
the pupils, the dog tongue), the file naming, and the checks the importer
runs. Also spells out which activities are held poses and which are
animation rigs, with the frame count behind each rig, because that is the
distinction that decides whether generated art is a drop in or a reference
to redraw the composer against.
---
 README.md          |  14 ++++-
 docs/frame-pack.md | 126 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+), 1 deletion(-)
 create mode 100644 docs/frame-pack.md

diff --git a/README.md b/README.md
index 3157244..e098c86 100644
--- a/README.md
+++ b/README.md
@@ -491,14 +491,26 @@ isolated worker processes. Your IMAP app password is stored encrypted at rest
 
 ```powershell
 npm start                 # run the cat
-npm test                  # 52 tests: config, poses, petting, audio, site drift
+npm test                  # 81 tests: config, poses, petting, audio, art frames, site drift
 npm run poses:cat         # previews/cat-poses.png (every activity x every coat)
 npm run poses:dog         # the same for all 14 breeds
+npm run frames:import -- <dir>   # import painted PNGs as baked poses
 npm run demo:all          # regenerate the README media (hero, gallery, carousel)
 npm run hook -- cursor    # print a path-filled agent hook config
 npm run icon              # regenerate the tray + app-tile icons
 ```
 
+**Painting a pose by hand.** Every pose is composed in code, which is why one
+`sit` covers 28 coats and a new coat costs nine hex values instead of an art pass.
+The trade is that changing how the pet looks means editing geometry.
+`npm run frames:import` is the escape hatch: paint a pose against a placeholder
+palette, import it, and it wins over the composer for exactly the coats you name
+while everything else keeps composing. Five held poses can be baked (`sit`,
+`type`, `loaf`, `rear`, `hunt`); the six raised-limb activities are parameterised
+rigs whose limbs sweep through quantised frames, so a still would freeze them.
+Palette, naming and the checks the importer runs are in
+[docs/frame-pack.md](docs/frame-pack.md).
+
 **Visual QA.** The overlay is GPU-composited, so ordinary screenshots cannot
 capture it. Poses are reviewed with a one-command contact sheet instead:
 `npm run poses:cat` renders **every activity across every coat** into one image,
diff --git a/docs/frame-pack.md b/docs/frame-pack.md
new file mode 100644
index 0000000..5f0f4a1
--- /dev/null
+++ b/docs/frame-pack.md
@@ -0,0 +1,126 @@
+# Frame pack: painting poses by hand
+
+Every pose the pet holds is composed in code from grid primitives, which is why one
+`sit` covers 28 coats and why a new coat costs nine hex values instead of an art
+pass. The trade is that improving how the pet *looks* means editing geometry.
+
+This is the escape hatch. Paint a pose, import it, and it wins over the composer
+for exactly the coats you name. Everything else keeps composing, so a pack of one
+frame is a perfectly valid pack.
+
+## The model: roles, not colours
+
+A sprite is a grid of **role letters**, one per cell:
+
+| Letter | Role | Where it goes |
+|---|---|---|
+| `C` | coat | body, head, legs, the main mass |
+| `K` | mark | stripes, saddle, mask, ear backs |
+| `W` | white | bib, muzzle, toes, tail tip |
+| `X` | patch | tortie and calico blocks, dog brows |
+| `I` | inner | inner ear only |
+| `N` | nose | nose pad only, anchors the whiskers and the tongue |
+| `E` | eye | flat eye block, the engine paints the pupil into it |
+| `O` | outline | one cell silhouette band |
+| `H` | halo | **generated**, never authored |
+
+`drawCat` looks the colour up per coat at draw time and applies its own top lit
+shading. So the art you import must be **flat**: any shading painted in doubles up
+with the engine's and turns muddy.
+
+Three things are drawn live on top of the frame and must not appear in it: the
+**halo**, the **pupils** (they track the cursor), and the dog **tongue**.
+
+## Painting against the placeholder palette
+
+Paint with these nine colours and nothing in between. They are never seen; they
+exist only so a nearest-colour match can tell the roles apart.
+
+| Role | Hex | | Role | Hex |
+|---|---|---|---|---|
+| coat | `#D9C7A7` | | nose | `#B04A57` |
+| mark | `#33302E` | | eye | `#4FBF7A` |
+| white | `#FBFBF7` | | outline | `#5C534A` |
+| patch | `#D2762B` | | tongue | `#E8747F` (engine only) |
+| inner | `#EFA9B8` | | | |
+
+Transparent background. No anti aliasing, no gradients, no dithering. The importer
+snaps every pixel to the nearest of the eight paintable colours and takes an area
+majority vote per cell, so it survives art that does not land exactly on the grid,
+but it cannot rescue a soft edge: it will report the percentage of pixels that were
+not a palette colour and you should treat anything over 10 percent as a redraw.
+
+## What can be baked, and what cannot
+
+Five poses are **held**: the pet sits in them for whole seconds, and a still frame
+is the right shape for them.
+
+| Pose | Canvas | Notes |
+|---|---|---|
+| `sit` | 24x30 | the default, also the base for drag, pet, startle, greeting |
+| `type` | 24x24 | no forelegs: the kneading paws are drawn over the keycaps |
+| `loaf` | 24x30 | cat loaf, dog nose-to-tail curl (a side view, one eye) |
+| `rear` | 24x30 | cat rear-up, dog beg. No forelegs: they are drawn live |
+| `hunt` | 30x20 cat, 30x22 dog | cat crouch (front on), dog play bow (side view, one eye) |
+
+The other six activities are **animation rigs**, not stills. Their limbs move with
+a quantised parameter, so replacing one with a single frame would freeze it:
+
+| Activity | Rig | Distinct frames per coat |
+|---|---|---|
+| rope climb | `climbSpriteFor(i, hand, dir)` | 4 (two grips x two headings) |
+| groom, ponder, play | `pawSpriteFor(i, lift, out)` | up to 45 (`PAW_STEPS` 8 by 4 steps out) |
+| bat overhead | `batSpriteFor(i, up, ph)` | 14 (two sides x seven arc steps) |
+
+The importer refuses those poses on purpose. Generated art for them is still worth
+having as a **reference to redraw the composer against**, which is how the dog was
+built in the first place: iterate the geometry against a rendered contact sheet
+until the silhouette reads.
+
+## Importing
+
+Name each PNG for the pose it fills, and optionally the coat it belongs to:
+
+```
+cat-sit.png                 every cat coat
+cat-sit--Orange Tabby.png   that one coat, by its PATTERNS name
+dog-hunt--retriever.png     every breed built on the retriever body
+```
+
+Then:
+
+```
+npm run frames:import -- path/to/pngs          # writes src/art-frames.js
+npm run frames:import -- path/to/pngs --dry    # report only, write nothing
+```
+
+Lookup order is coat name, then build name, then `*`, then the composer. So you can
+ship one `*` frame and override a single awkward coat later.
+
+Every frame is checked before it is written, and a frame that fails is dropped with
+a reason rather than shipped:
+
+- the canvas matches the pose (a wrong size would break the layout maths built on it)
+- an eye block sits **either side of the seam `eyeBox()` splits on**, or exactly one
+  for the two profile poses. A face drawn off centre puts one eye in both boxes and
+  `drawCat` paints the pupil as a bar across the muzzle. This has bitten the project
+  twice, once on the cat and once on the dog.
+- a nose exists, because the whiskers and the panting tongue anchor to it
+- the bottom row is occupied, so the pose stands on the same floor line as the others
+
+`--force` writes anyway. It is there for experiments, not for shipping.
+
+## Verifying
+
+```
+npm test                    # includes a PNG round trip and the renderer hook
+npm run poses:cat           # previews/cat-poses.png, every activity x every coat
+npm run poses:dog
+npm run test:boot
+```
+
+Then look at the sheets. Reading grid code cannot tell you whether a silhouette
+reads as an animal, and the two coats worth checking first are **Black** and
+**Slate**: they collapse coat, mark, white and patch into one colour, so anything
+that only reads because of a colour change disappears. If the pose survives those,
+the silhouette is doing the work.