quiver-cli 1.2.0 → 1.3.1

package/template/.agents/skills/design/impeccable/scripts/lib/png.mjs

@@ -0,0 +1,281 @@
+/**
+ * Dependency-free PNG decode/encode for the skill scripts.
+ *
+ * decodePng(buffer) -> { width, height, data } where data is RGBA8 (Uint8Array,
+ * width*height*4). Handles every color type (0, 2, 3, 4, 6), bit depths 1-16
+ * (16-bit is reduced to 8), all five filters, and Adam7 interlacing.
+ *
+ * encodePng({ width, height, data }) -> Buffer, RGBA8 in, 8-bit RGBA PNG out.
+ *
+ * Kept small on purpose: the skill scripts ship without npm dependencies, and
+ * comps (gpt-image PNGs) and screenshots (Playwright / harness PNGs) are the
+ * only formats the comp-fidelity tooling has to read.
+ */
+import zlib from 'node:zlib';
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const crcTable = (() => {
+  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;
+})();
+
+function crc32(data) {
+  let c = 0xffffffff;
+  for (let i = 0; i < data.length; i++) c = crcTable[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+export function isPng(buf) {
+  return buf && buf.length > 8 && buf.subarray(0, 8).equals(SIGNATURE);
+}
+
+function readChunks(buf) {
+  const chunks = [];
+  let pos = 8;
+  while (pos + 8 <= buf.length) {
+    const length = buf.readUInt32BE(pos);
+    const type = buf.toString('latin1', pos + 4, pos + 8);
+    const data = buf.subarray(pos + 8, pos + 8 + length);
+    chunks.push({ type, data });
+    pos += 12 + length;
+    if (type === 'IEND') break;
+  }
+  return chunks;
+}
+
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+/** Unfilter one pass of scanlines in place; returns the raw (unfiltered) bytes. */
+function unfilter(raw, width, height, bpp, bitDepth, channels) {
+  const stride = Math.ceil((width * channels * bitDepth) / 8);
+  const out = new Uint8Array(stride * height);
+  let inPos = 0;
+  let prev = null;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[inPos++];
+    const line = out.subarray(y * stride, (y + 1) * stride);
+    line.set(raw.subarray(inPos, inPos + stride));
+    inPos += stride;
+    switch (filter) {
+      case 0: break;
+      case 1: for (let i = bpp; i < stride; i++) line[i] = (line[i] + line[i - bpp]) & 0xff; break;
+      case 2: if (prev) for (let i = 0; i < stride; i++) line[i] = (line[i] + prev[i]) & 0xff; break;
+      case 3:
+        for (let i = 0; i < stride; i++) {
+          const left = i >= bpp ? line[i - bpp] : 0;
+          const up = prev ? prev[i] : 0;
+          line[i] = (line[i] + ((left + up) >> 1)) & 0xff;
+        }
+        break;
+      case 4:
+        for (let i = 0; i < stride; i++) {
+          const left = i >= bpp ? line[i - bpp] : 0;
+          const up = prev ? prev[i] : 0;
+          const ul = prev && i >= bpp ? prev[i - bpp] : 0;
+          line[i] = (line[i] + paeth(left, up, ul)) & 0xff;
+        }
+        break;
+      default: throw new Error(`png: unknown filter ${filter} on row ${y}`);
+    }
+    prev = line;
+  }
+  return { bytes: out, stride, consumed: inPos };
+}
+
+/** Read sample `index` (0-based across the row) from a packed scanline. */
+function sampleReader(bitDepth) {
+  if (bitDepth === 8) return (line, i) => line[i];
+  if (bitDepth === 16) return (line, i) => line[i * 2]; // high byte
+  const perByte = 8 / bitDepth;
+  const mask = (1 << bitDepth) - 1;
+  const scale = 255 / mask;
+  return (line, i) => {
+    const byte = line[(i / perByte) | 0];
+    const shift = 8 - bitDepth * ((i % perByte) + 1);
+    return Math.round(((byte >> shift) & mask) * scale);
+  };
+}
+
+function writePixels(dst, dstWidth, bytes, stride, passWidth, passHeight, colorType, bitDepth, palette, trns, mapX, mapY) {
+  const channels = CHANNELS[colorType];
+  const read = sampleReader(bitDepth);
+  const rawIndex = bitDepth < 8 ? (line, i) => {
+    const perByte = 8 / bitDepth;
+    const mask = (1 << bitDepth) - 1;
+    const byte = line[(i / perByte) | 0];
+    const shift = 8 - bitDepth * ((i % perByte) + 1);
+    return (byte >> shift) & mask;
+  } : read;
+  for (let y = 0; y < passHeight; y++) {
+    const line = bytes.subarray(y * stride, (y + 1) * stride);
+    const dy = mapY(y);
+    for (let x = 0; x < passWidth; x++) {
+      const dx = mapX(x);
+      const o = (dy * dstWidth + dx) * 4;
+      let r, g, b, a = 255;
+      switch (colorType) {
+        case 0: {
+          r = g = b = read(line, x);
+          if (trns && trns.gray === rawIndex(line, x)) a = 0;
+          break;
+        }
+        case 2: {
+          r = read(line, x * 3); g = read(line, x * 3 + 1); b = read(line, x * 3 + 2);
+          break;
+        }
+        case 3: {
+          const idx = rawIndex(line, x);
+          r = palette[idx * 3]; g = palette[idx * 3 + 1]; b = palette[idx * 3 + 2];
+          if (trns && trns.alpha && idx < trns.alpha.length) a = trns.alpha[idx];
+          break;
+        }
+        case 4: {
+          r = g = b = read(line, x * 2); a = read(line, x * 2 + 1);
+          break;
+        }
+        case 6: {
+          r = read(line, x * 4); g = read(line, x * 4 + 1); b = read(line, x * 4 + 2); a = read(line, x * 4 + 3);
+          break;
+        }
+        default: throw new Error(`png: unsupported color type ${colorType}`);
+      }
+      dst[o] = r; dst[o + 1] = g; dst[o + 2] = b; dst[o + 3] = a;
+    }
+  }
+  return channels;
+}
+
+export function decodePng(buf) {
+  if (!isPng(buf)) throw new Error('png: not a PNG (bad signature)');
+  const chunks = readChunks(buf);
+  const ihdr = chunks.find((c) => c.type === 'IHDR');
+  if (!ihdr) throw new Error('png: missing IHDR');
+  const width = ihdr.data.readUInt32BE(0);
+  const height = ihdr.data.readUInt32BE(4);
+  const bitDepth = ihdr.data[8];
+  const colorType = ihdr.data[9];
+  const interlace = ihdr.data[12];
+  const channels = CHANNELS[colorType];
+  if (!channels) throw new Error(`png: unsupported color type ${colorType}`);
+  const palChunk = chunks.find((c) => c.type === 'PLTE');
+  const palette = palChunk ? palChunk.data : null;
+  const trnsChunk = chunks.find((c) => c.type === 'tRNS');
+  let trns = null;
+  if (trnsChunk) {
+    if (colorType === 3) trns = { alpha: trnsChunk.data };
+    else if (colorType === 0) trns = { gray: trnsChunk.data.readUInt16BE(0) >> (bitDepth === 16 ? 8 : 0) };
+  }
+  const idat = Buffer.concat(chunks.filter((c) => c.type === 'IDAT').map((c) => c.data));
+  const raw = zlib.inflateSync(idat);
+  const bpp = Math.max(1, Math.ceil((channels * bitDepth) / 8));
+  const data = new Uint8Array(width * height * 4);
+  const text = {};
+  for (const c of chunks) {
+    if (c.type === 'tEXt') {
+      const z = c.data.indexOf(0);
+      if (z > 0) text[c.data.toString('latin1', 0, z)] = c.data.toString('utf8', z + 1);
+    }
+  }
+
+  if (interlace === 0) {
+    const { bytes, stride } = unfilter(raw, width, height, bpp, bitDepth, channels);
+    writePixels(data, width, bytes, stride, width, height, colorType, bitDepth, palette, trns, (x) => x, (y) => y);
+  } else {
+    // Adam7
+    const passes = [
+      [0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2],
+    ];
+    let offset = 0;
+    for (const [sx, sy, dx, dy] of passes) {
+      const pw = Math.ceil((width - sx) / dx);
+      const ph = Math.ceil((height - sy) / dy);
+      if (pw <= 0 || ph <= 0) continue;
+      const { bytes, stride, consumed } = unfilter(raw.subarray(offset), pw, ph, bpp, bitDepth, channels);
+      offset += consumed;
+      writePixels(data, width, bytes, stride, pw, ph, colorType, bitDepth, palette, trns, (x) => sx + x * dx, (y) => sy + y * dy);
+    }
+  }
+  return { width, height, data, text };
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const typeBuf = Buffer.from(type, 'latin1');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+  return Buffer.concat([len, typeBuf, data, crc]);
+}
+
+/**
+ * Encode RGBA8 to PNG. `text` (optional) is a map of tEXt keyword -> value.
+ * Uses filter type 0 on every row: comps and screenshots compress fine and the
+ * encoder stays trivial.
+ */
+export function encodePng({ width, height, data }, { text = null, level = 6 } = {}) {
+  if (data.length !== width * height * 4) throw new Error(`png: data length ${data.length} != ${width}x${height}x4`);
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  const parts = [SIGNATURE, chunk('IHDR', ihdr)];
+  if (text) {
+    for (const [k, v] of Object.entries(text)) {
+      parts.push(chunk('tEXt', Buffer.concat([Buffer.from(k, 'latin1'), Buffer.from([0]), Buffer.from(String(v), 'utf8')])));
+    }
+  }
+  parts.push(chunk('IDAT', zlib.deflateSync(raw, { level })));
+  parts.push(chunk('IEND', Buffer.alloc(0)));
+  return Buffer.concat(parts);
+}
+
+/**
+ * Read any raster the comp pipeline meets (PNG natively; WebP / JPEG / GIF /
+ * AVIF through a converter on PATH) as RGBA. Non-PNG input is converted to a
+ * sibling cache file `<name>.<ext>.png` next to the source, never in place:
+ * a session that overwrites `comp.webp` with PNG bytes leaves a file the
+ * next tool cannot trust and a transcript replay cannot reconstruct.
+ * Returns { image, path } where path is the PNG actually decoded.
+ */
+export function loadRaster(file) {
+  const buf = fs.readFileSync(file);
+  if (isPng(buf)) return { image: decodePng(buf), path: file };
+  const cache = `${file}.png`;
+  if (fs.existsSync(cache)) {
+    try { const b = fs.readFileSync(cache); if (isPng(b)) return { image: decodePng(b), path: cache }; } catch { /* reconvert */ }
+  }
+  const attempts = [
+    ['dwebp', [file, '-o', cache]],
+    ['sips', ['-s', 'format', 'png', file, '--out', cache]],
+    ['magick', [file, cache]],
+    ['convert', [file, cache]],
+  ];
+  let lastErr = null;
+  for (const [cmd, args] of attempts) {
+    try { execFileSync(cmd, args, { stdio: 'ignore' }); const b = fs.readFileSync(cache); if (isPng(b)) return { image: decodePng(b), path: cache }; }
+    catch (e) { lastErr = e; }
+  }
+  throw new Error(`png: ${file} is not a PNG and no converter (dwebp, sips, magick, convert) could produce ${cache}${lastErr ? `: ${lastErr.message}` : ''}`);
+}

package/template/.agents/skills/design/impeccable/scripts/lib/raster.mjs

@@ -0,0 +1,194 @@
+/**
+ * Small RGBA raster toolkit shared by the comp-fidelity scripts: crop, resize
+ * (area-averaging down, bilinear up), composite, fills, rectangles, and a
+ * bitmap-font label so composites can be captioned without a font stack.
+ *
+ * An image is `{ width, height, data }` with RGBA8 data (Uint8Array).
+ */
+
+export function createImage(width, height, fill = [0, 0, 0, 0]) {
+  const data = new Uint8Array(width * height * 4);
+  if (fill[0] || fill[1] || fill[2] || fill[3]) {
+    for (let i = 0; i < data.length; i += 4) { data[i] = fill[0]; data[i + 1] = fill[1]; data[i + 2] = fill[2]; data[i + 3] = fill[3]; }
+  }
+  return { width, height, data };
+}
+
+export function clampRect(img, x, y, w, h) {
+  const x0 = Math.max(0, Math.min(img.width, Math.round(x)));
+  const y0 = Math.max(0, Math.min(img.height, Math.round(y)));
+  const x1 = Math.max(x0, Math.min(img.width, Math.round(x + w)));
+  const y1 = Math.max(y0, Math.min(img.height, Math.round(y + h)));
+  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+
+export function crop(img, x, y, w, h) {
+  const r = clampRect(img, x, y, w, h);
+  const out = createImage(Math.max(1, r.w), Math.max(1, r.h));
+  for (let yy = 0; yy < r.h; yy++) {
+    const src = ((r.y + yy) * img.width + r.x) * 4;
+    out.data.set(img.data.subarray(src, src + r.w * 4), yy * out.width * 4);
+  }
+  return out;
+}
+
+/** Resize with area averaging when shrinking and bilinear when growing. */
+export function resize(img, width, height) {
+  width = Math.max(1, Math.round(width));
+  height = Math.max(1, Math.round(height));
+  if (width === img.width && height === img.height) return { width, height, data: new Uint8Array(img.data) };
+  const out = createImage(width, height);
+  const sx = img.width / width, sy = img.height / height;
+  if (sx >= 1 && sy >= 1) {
+    for (let y = 0; y < height; y++) {
+      const y0 = Math.floor(y * sy), y1 = Math.min(img.height, Math.max(y0 + 1, Math.floor((y + 1) * sy)));
+      for (let x = 0; x < width; x++) {
+        const x0 = Math.floor(x * sx), x1 = Math.min(img.width, Math.max(x0 + 1, Math.floor((x + 1) * sx)));
+        let r = 0, g = 0, b = 0, a = 0, n = 0;
+        for (let yy = y0; yy < y1; yy++) {
+          let p = (yy * img.width + x0) * 4;
+          for (let xx = x0; xx < x1; xx++, p += 4) { r += img.data[p]; g += img.data[p + 1]; b += img.data[p + 2]; a += img.data[p + 3]; n++; }
+        }
+        const o = (y * width + x) * 4;
+        out.data[o] = r / n; out.data[o + 1] = g / n; out.data[o + 2] = b / n; out.data[o + 3] = a / n;
+      }
+    }
+    return out;
+  }
+  for (let y = 0; y < height; y++) {
+    const fy = Math.min(img.height - 1, (y + 0.5) * sy - 0.5);
+    const y0 = Math.max(0, Math.floor(fy)), y1 = Math.min(img.height - 1, y0 + 1), wy = fy - y0;
+    for (let x = 0; x < width; x++) {
+      const fx = Math.min(img.width - 1, (x + 0.5) * sx - 0.5);
+      const x0 = Math.max(0, Math.floor(fx)), x1 = Math.min(img.width - 1, x0 + 1), wx = fx - x0;
+      const o = (y * width + x) * 4;
+      for (let c = 0; c < 4; c++) {
+        const p00 = img.data[(y0 * img.width + x0) * 4 + c], p10 = img.data[(y0 * img.width + x1) * 4 + c];
+        const p01 = img.data[(y1 * img.width + x0) * 4 + c], p11 = img.data[(y1 * img.width + x1) * 4 + c];
+        out.data[o + c] = (p00 * (1 - wx) + p10 * wx) * (1 - wy) + (p01 * (1 - wx) + p11 * wx) * wy;
+      }
+    }
+  }
+  return out;
+}
+
+/** Scale to fit inside (maxW x maxH) preserving aspect; never upscale unless `allowUpscale`. */
+export function fit(img, maxW, maxH, allowUpscale = false) {
+  const s = Math.min(maxW / img.width, maxH / img.height);
+  if (s >= 1 && !allowUpscale) return img;
+  return resize(img, img.width * s, img.height * s);
+}
+
+/** Alpha-composite `src` onto `dst` at (x, y). */
+export function blit(dst, src, x, y) {
+  x = Math.round(x); y = Math.round(y);
+  for (let yy = 0; yy < src.height; yy++) {
+    const dy = y + yy; if (dy < 0 || dy >= dst.height) continue;
+    for (let xx = 0; xx < src.width; xx++) {
+      const dx = x + xx; if (dx < 0 || dx >= dst.width) continue;
+      const s = (yy * src.width + xx) * 4, d = (dy * dst.width + dx) * 4;
+      const a = src.data[s + 3] / 255;
+      if (a >= 1) { dst.data[d] = src.data[s]; dst.data[d + 1] = src.data[s + 1]; dst.data[d + 2] = src.data[s + 2]; dst.data[d + 3] = 255; continue; }
+      if (a <= 0) continue;
+      const da = dst.data[d + 3] / 255, oa = a + da * (1 - a);
+      for (let c = 0; c < 3; c++) dst.data[d + c] = (src.data[s + c] * a + dst.data[d + c] * da * (1 - a)) / (oa || 1);
+      dst.data[d + 3] = oa * 255;
+    }
+  }
+}
+
+export function fillRect(img, x, y, w, h, rgba) {
+  const r = clampRect(img, x, y, w, h);
+  const a = (rgba[3] ?? 255) / 255;
+  for (let yy = r.y; yy < r.y + r.h; yy++) {
+    for (let xx = r.x; xx < r.x + r.w; xx++) {
+      const o = (yy * img.width + xx) * 4;
+      if (a >= 1) { img.data[o] = rgba[0]; img.data[o + 1] = rgba[1]; img.data[o + 2] = rgba[2]; img.data[o + 3] = 255; }
+      else { for (let c = 0; c < 3; c++) img.data[o + c] = rgba[c] * a + img.data[o + c] * (1 - a); img.data[o + 3] = Math.max(img.data[o + 3], a * 255); }
+    }
+  }
+}
+
+export function strokeRect(img, x, y, w, h, rgba, thickness = 2) {
+  fillRect(img, x, y, w, thickness, rgba);
+  fillRect(img, x, y + h - thickness, w, thickness, rgba);
+  fillRect(img, x, y, thickness, h, rgba);
+  fillRect(img, x + w - thickness, y, thickness, h, rgba);
+}
+
+// 5x7 bitmap font, uppercase + digits + a little punctuation. Enough for labels.
+const GLYPHS = {
+  A: ['01110', '10001', '10001', '11111', '10001', '10001', '10001'],
+  B: ['11110', '10001', '10001', '11110', '10001', '10001', '11110'],
+  C: ['01110', '10001', '10000', '10000', '10000', '10001', '01110'],
+  D: ['11110', '10001', '10001', '10001', '10001', '10001', '11110'],
+  E: ['11111', '10000', '10000', '11110', '10000', '10000', '11111'],
+  F: ['11111', '10000', '10000', '11110', '10000', '10000', '10000'],
+  G: ['01110', '10001', '10000', '10111', '10001', '10001', '01111'],
+  H: ['10001', '10001', '10001', '11111', '10001', '10001', '10001'],
+  I: ['11111', '00100', '00100', '00100', '00100', '00100', '11111'],
+  J: ['00111', '00010', '00010', '00010', '00010', '10010', '01100'],
+  K: ['10001', '10010', '10100', '11000', '10100', '10010', '10001'],
+  L: ['10000', '10000', '10000', '10000', '10000', '10000', '11111'],
+  M: ['10001', '11011', '10101', '10101', '10001', '10001', '10001'],
+  N: ['10001', '10001', '11001', '10101', '10011', '10001', '10001'],
+  O: ['01110', '10001', '10001', '10001', '10001', '10001', '01110'],
+  P: ['11110', '10001', '10001', '11110', '10000', '10000', '10000'],
+  Q: ['01110', '10001', '10001', '10001', '10101', '10010', '01101'],
+  R: ['11110', '10001', '10001', '11110', '10100', '10010', '10001'],
+  S: ['01111', '10000', '10000', '01110', '00001', '00001', '11110'],
+  T: ['11111', '00100', '00100', '00100', '00100', '00100', '00100'],
+  U: ['10001', '10001', '10001', '10001', '10001', '10001', '01110'],
+  V: ['10001', '10001', '10001', '10001', '10001', '01010', '00100'],
+  W: ['10001', '10001', '10001', '10101', '10101', '10101', '01010'],
+  X: ['10001', '10001', '01010', '00100', '01010', '10001', '10001'],
+  Y: ['10001', '10001', '01010', '00100', '00100', '00100', '00100'],
+  Z: ['11111', '00001', '00010', '00100', '01000', '10000', '11111'],
+  0: ['01110', '10001', '10011', '10101', '11001', '10001', '01110'],
+  1: ['00100', '01100', '00100', '00100', '00100', '00100', '01110'],
+  2: ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],
+  3: ['11110', '00001', '00001', '01110', '00001', '00001', '11110'],
+  4: ['00010', '00110', '01010', '10010', '11111', '00010', '00010'],
+  5: ['11111', '10000', '11110', '00001', '00001', '10001', '01110'],
+  6: ['00110', '01000', '10000', '11110', '10001', '10001', '01110'],
+  7: ['11111', '00001', '00010', '00100', '01000', '01000', '01000'],
+  8: ['01110', '10001', '10001', '01110', '10001', '10001', '01110'],
+  9: ['01110', '10001', '10001', '01111', '00001', '00010', '01100'],
+  ' ': ['00000', '00000', '00000', '00000', '00000', '00000', '00000'],
+  '.': ['00000', '00000', '00000', '00000', '00000', '01100', '01100'],
+  ':': ['00000', '01100', '01100', '00000', '01100', '01100', '00000'],
+  '-': ['00000', '00000', '00000', '11111', '00000', '00000', '00000'],
+  '/': ['00001', '00010', '00010', '00100', '01000', '01000', '10000'],
+  '%': ['11001', '11010', '00010', '00100', '01000', '01011', '10011'],
+  '(': ['00010', '00100', '01000', '01000', '01000', '00100', '00010'],
+  ')': ['01000', '00100', '00010', '00010', '00010', '00100', '01000'],
+  '#': ['01010', '01010', '11111', '01010', '11111', '01010', '01010'],
+  '_': ['00000', '00000', '00000', '00000', '00000', '00000', '11111'],
+  '?': ['01110', '10001', '00001', '00010', '00100', '00000', '00100'],
+  '=': ['00000', '00000', '11111', '00000', '11111', '00000', '00000'],
+  '+': ['00000', '00100', '00100', '11111', '00100', '00100', '00000'],
+  ',': ['00000', '00000', '00000', '00000', '01100', '00100', '01000'],
+};
+
+export function textWidth(text, scale = 2) {
+  return text.length * 6 * scale;
+}
+
+/** Draw uppercase bitmap text. Returns width drawn. */
+export function drawText(img, text, x, y, rgba, scale = 2) {
+  let cx = Math.round(x);
+  for (const chRaw of String(text).toUpperCase()) {
+    const g = GLYPHS[chRaw] || GLYPHS['?'];
+    for (let r = 0; r < 7; r++) for (let c = 0; c < 5; c++) if (g[r][c] === '1') fillRect(img, cx + c * scale, y + r * scale, scale, scale, rgba);
+    cx += 6 * scale;
+  }
+  return cx - x;
+}
+
+/** Draw a label with a background pill. */
+export function drawLabel(img, text, x, y, { fg = [255, 255, 255, 255], bg = [0, 0, 0, 220], scale = 2, pad = 4 } = {}) {
+  const w = textWidth(text, scale) + pad * 2, h = 7 * scale + pad * 2;
+  fillRect(img, x, y, w, h, bg);
+  drawText(img, text, x + pad, y + pad, fg, scale);
+  return { w, h };
+}

package/template/.agents/skills/design/impeccable/scripts/lib/roll-selection.mjs

@@ -96,31 +96,38 @@ function* rank(items, input, idFor = item => item.id) {
     .map(entry => entry.item);
 }
 
-// Two independent exclusions, and either one is enough to hold a world back.
-// Rating grades quality: a 3-star earns a second ticket, a 1-star marginal keep
-// leaves the pool. Breadth says whether a world can serve an arbitrary build at
-// all, so a niche world leaves however good it is, keeping its approval for
-// direct briefs. Breadth was split out of rating because the only way to hold a
-// narrow world back used to be calling it marginal, which made "excellent but
-// narrow" unrecordable and corrupted ratings as a calibration signal.
+// Rating sets how many tickets a world holds; breadth decides whether it draws
+// at all. A niche world leaves the pool however good it is, keeping its approval
+// for direct briefs. Breadth was split out of rating because the only way to
+// hold a narrow world back used to be calling it marginal, which made "excellent
+// but narrow" unrecordable and corrupted ratings as a calibration signal.
+//
+// Two tickets for a 3-star, one for everything else, was too sharp. Measured
+// against the catalog as it stood: 3-star worlds absorbed 57% of the graphic
+// draw from 65 of 163 eligible worlds, 46% of atmosphere from 13 of 43, and
+// 75% of interaction from 15 of 25. The reviewer's complaint, that the same
+// worlds keep coming back, is what a rating multiplier does to a pool whose
+// thinnest tier holds 25 worlds.
+//
+// So a 3-star no longer outdraws a 2-star, and a 1-star draws at half rather
+// than not at all. A marginal keep is still worth showing sometimes: the
+// judgement it records is "narrow or unexceptional", not "wrong", and excluding
+// it entirely made a rating do a job breadth already does properly.
+const RATING_TICKETS = { 1: 1, 2: 2, 3: 2 };
+const ticketsForRating = rating => RATING_TICKETS[rating] ?? 2;
+
 function challengerTickets(pool) {
   return pool.flatMap(concept => {
-    const rating = concept.review?.rating;
-    if (rating === 1 || concept.review?.breadth === 'niche') return [];
-    return rating === 3
-      ? [{ concept, ticket: 0 }, { concept, ticket: 1 }]
-      : [{ concept, ticket: 0 }];
+    if (concept.review?.breadth === 'niche') return [];
+    return Array.from({ length: ticketsForRating(concept.review?.rating) },
+      (_, ticket) => ({ concept, ticket }));
   });
 }
 
 function compositionTickets(pool) {
-  return pool.flatMap(composition => {
-    const rating = composition.review?.rating;
-    if (rating === 1) return [];
-    return rating === 3
-      ? [{ composition, ticket: 0 }, { composition, ticket: 1 }]
-      : [{ composition, ticket: 0 }];
-  });
+  return pool.flatMap(composition => Array.from(
+    { length: ticketsForRating(composition.review?.rating) },
+    (_, ticket) => ({ composition, ticket })));
 }
 
 /**

package/template/.agents/skills/design/impeccable/scripts/lib/staleness-deep.mjs

@@ -117,6 +117,23 @@ export function checkDesignDrift({ designPath, projectRoot, threshold = 25 }) {
  * a section can be absent because it never applied, so this is reported as a
  * documentation gap for a human to judge, never as an error.
  */
+function hasCoverageValue(value) {
+  if (Array.isArray(value)) return value.some(hasCoverageValue);
+  if (value && typeof value === 'object') {
+    return Object.values(value).some(hasCoverageValue);
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 && !/^(?:\[\s*\]|\{\s*\})$/.test(trimmed);
+  }
+  return false;
+}
+
+const SEED_DESIGN_MARKERS = ['/', '$'].map((prefix) =>
+  '<!-- SEED: established with the user before implementation; '
+    + `re-run ${prefix}impeccable document once there's code to capture the actual tokens and components. -->`
+);
+
 export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   if (!design || typeof parseDesignMd !== 'function') return [];
   let model;
@@ -125,8 +142,12 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   } catch {
     return [];
   }
-  const missing = ['colors', 'typography', 'components']
-    .filter((section) => !model[section]);
+  const isSeed = SEED_DESIGN_MARKERS.some((marker) => design.includes(marker));
+  const requiredSections = isSeed
+    ? ['colors', 'typography']
+    : ['colors', 'typography', 'components'];
+  const missing = requiredSections
+    .filter((section) => !model[section] && !hasCoverageValue(model.frontmatter?.[section]));
   if (!missing.length) return [];
   return [finding({
     id: 'design-md-coverage',
@@ -223,7 +244,8 @@ const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
 //   * bundle-relative: node ".agents/.../hook.mjs"
 //   * legacy unquoted: node .claude/.../hook.mjs
 //   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
-//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * absolute (#476): [ ! -f 'PATH' ] || node 'PATH'   (single-quoted since
+//                      the shell-injection fix; older installs double-quote)
 //   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
 // A quoted path wins; the guard's two occurrences are identical, so the first
 // quoted match is the path. Otherwise fall back to the whitespace/metachar-
@@ -234,6 +256,12 @@ function hookScriptTokenFrom(command) {
   if (!HOOK_MARKER.test(str)) return null;
   const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
   if (quoted) return quoted[1];
+  // A path containing an apostrophe serializes as '\'' inside single quotes;
+  // no regex reassembles that, and the bare fallback would misread a fragment
+  // of it, so return null: the caller never asserts on a path it can't parse.
+  if (str.includes("'\\''")) return null;
+  const singleQuoted = str.match(/'([^']*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)'/);
+  if (singleQuoted) return singleQuoted[1];
   const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
   return bare ? bare[1] : null;
 }