@calo-design/cli 0.6.0 → 0.8.0

package/bin/cli.js

@@ -20,6 +20,7 @@ const { cmdArtPush } = require("./art-push");
 const { cmdShare } = require("./share");
 const { cmdImage } = require("./imagegen");
 const { cmdLogin, cmdLogout, ensureLoggedIn, githubToken, reportEvent, ensureSession, loadSession, BROKER } = require("./login");
+const { cmdFeedback, cmdTasks } = require("./feedback");
 
 const ORG = "Calo-Design";
 const SKILL_REPO = `${ORG}/calo-design`;
@@ -773,12 +774,17 @@ function help() {
   ${c.dim("art push <dir>")}                            upload a bulk image set to the CDN + emit a remote-source manifest (login only)
   ${c.dim("    art push ./art/byo --set byo --manifest src/byo-art.ts  --dry-run  --force  --direct")}
   ${c.dim("image \"<prompt>\"")}                          AI image generation via the broker (metered per user; login only)
-  ${c.dim("    image \"…\" --out hero.png --ref photo.jpg --model google/gemini-3-pro-image --json")}
+  ${c.dim("    image \"…\" --out hero.png --ref photo-or-url --model google/gemini-3-pro-image --json")}
+  ${c.dim("    image \"…\" --ref <vessel-url> --ref-sheet <comp1> --ref-sheet <comp2>   food refs: vessel + composed component sheet")}
   ${c.dim("image usage")}                               your monthly image-generation metering (images + USD)
   ${c.dim("share")}                                     publish THIS web prototype (React/Vite/CRA/Next) to Cloudflare Pages → share link
   ${c.dim("    share --slug x --dir dist --build --project calo-prototypes  --dry-run")}
   ${c.dim("gallery")}                                   serve the @calo/design-system component gallery locally (live from the runtime)
   ${c.dim("    gallery --port 8091")}
+  ${c.dim("feedback [slug]")}                           feedback inbox for shared prototypes (open threads; --all, --json)
+  ${c.dim("    feedback new <slug> <text>   comment|resolve|reopen <threadId>   shot <slug> <png>")}
+  ${c.dim("tasks [slug]")}                              triaged work items (--status todo|in_progress|done|wontfix, --json)
+  ${c.dim("    tasks new <slug> <title> --from <threadId>   start|done|wontfix <id>   done <id> --version v9")}
 
   Login is required once before init; the session refreshes automatically.
   init always installs the skill and ensures the shared ds/flows runtime on your machine;
@@ -803,6 +809,8 @@ function help() {
     else if (cmd === "insights") await cmdInsights();
     else if (cmd === "whoami") await cmdWhoami();
     else if (cmd === "gallery") await cmdGallery();
+    else if (cmd === "feedback") await cmdFeedback(args.slice(1));
+    else if (cmd === "tasks") await cmdTasks(args.slice(1));
     else help();
   } catch (err) {
     // Diagnostics go to stderr so stdout stays pure for machine callers (The Pass parses

package/bin/feedback.js

@@ -0,0 +1,193 @@
+"use strict";
+
+/**
+ * `calo-design feedback …` / `calo-design tasks …` — prototype feedback threads and
+ * triaged tasks, stored broker-side (calo-broker docs/feedback-plan.md).
+ *
+ * Triple duty: humans in the terminal, Claude working the task queue, and Design
+ * Kitchen shelling out with --json (same bridge pattern as `feed --json`). All calls
+ * ride the existing broker session (ensureSession → Bearer).
+ *
+ *   feedback [slug]                 inbox (open threads; --all for resolved too)
+ *   feedback new <slug> <text…>     plain thread (no pin)
+ *   feedback comment <threadId> <text…>
+ *   feedback resolve <threadId> | reopen <threadId>
+ *   feedback shot <slug> <file.png> upload a pin screenshot → prints URL
+ *   tasks [slug]                    list (--status todo|in_progress|done|wontfix)
+ *   tasks new <slug> <title…>       (--from <threadId> converts a thread, --body <text>)
+ *   tasks start|done|wontfix <id>   (done: --version <v> stamps closed_in_version)
+ */
+
+const fs = require("node:fs");
+const { ensureSession, BROKER } = require("./login");
+
+const c = { dim: (s) => `\x1b[2m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, g: (s) => `\x1b[32m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m` };
+const log = (s = "") => console.log(s);
+
+// Bounded fetch that speaks the broker's JSON envelope. GET+POST (login.js api() is
+// POST-only); --json callers get the raw response text so the bridge never re-encodes.
+async function call(method, pathname, { body, raw } = {}) {
+  const session = await ensureSession();
+  let res;
+  try {
+    res = await fetch(BROKER + pathname, {
+      method,
+      headers: {
+        authorization: `Bearer ${session}`,
+        ...(body !== undefined && !Buffer.isBuffer(body) ? { "content-type": "application/json" } : {}),
+        ...(Buffer.isBuffer(body) ? { "content-type": "image/png" } : {}),
+      },
+      body: body === undefined ? undefined : Buffer.isBuffer(body) ? body : JSON.stringify(body),
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (e) {
+    throw new Error(`can't reach the Calo broker at ${BROKER} (${e.message})`);
+  }
+  const text = await res.text();
+  let json;
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { raw: text }; }
+  if (!res.ok) throw new Error(json.error || `${pathname} → HTTP ${res.status}`);
+  return raw ? text : json;
+}
+
+const flagVal = (args, name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : undefined;
+};
+const stripFlags = (args) => args.filter((a, i, all) => !a.startsWith("--") && !(all[i - 1] || "").match(/^--(status|version|from|body|route|anchor|shot)$/));
+
+const ago = (ts) => {
+  const s = Math.max(1, Math.floor(Date.now() / 1000) - ts);
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+};
+const short = (id) => id.slice(0, 8);
+// A thread's version is the deploy it was left on; slugs.last_version is current.
+const stale = (t) => t.version && t.current_version && t.version !== t.current_version;
+
+function printThread(t, { comments = false } = {}) {
+  const state = t.status === "resolved" ? c.g("✓ resolved") : c.y("● open");
+  const pin = t.anchor_json ? " 📌" : "";
+  const staleTag = stale(t) ? c.y(" [stale]") : "";
+  const task = t.task ? c.dim(`  → task ${short(t.task.id)} (${t.task.status})`) : "";
+  log(`${state}  ${c.b(t.slug)}${t.route ? c.dim(" " + t.route) : ""}${pin}${staleTag}  ${c.dim(short(t.id))}  ${c.dim(ago(t.created_at) + " ago")}${task}`);
+  const list = comments ? t.comments : t.comments.slice(0, 1);
+  for (const cm of list) {
+    const who = cm.kind === "system" ? c.dim("system") : cm.author.split("@")[0];
+    log(`    ${who}: ${cm.kind === "system" ? c.dim(cm.body) : cm.body}`);
+  }
+  if (!comments && t.comments.length > 1) log(c.dim(`    … ${t.comments.length - 1} more — calo-design feedback ${t.slug}`));
+}
+
+async function cmdFeedback(args = []) {
+  const json = args.includes("--json");
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "";
+
+  if (sub === "new") {
+    const [slug, ...words] = stripFlags(args.slice(1));
+    const body = words.join(" ").trim();
+    if (!slug || !body) throw new Error("usage: calo-design feedback new <slug> <text…> [--shot <png>] [--anchor <json>] [--route <path>] [--version <v>]");
+    // Pin threads (Kitchen Review view): upload the frozen frame first, then attach
+    // its URL — /v1/feedback/thread only accepts screenshot URLs minted by /shot.
+    let screenshotUrl;
+    const shotFile = flagVal(args, "shot");
+    if (shotFile) {
+      const png = fs.readFileSync(shotFile);
+      const up = await call("POST", `/v1/feedback/shot?slug=${encodeURIComponent(slug)}`, { body: png });
+      screenshotUrl = up.url;
+    }
+    let anchor;
+    const anchorRaw = flagVal(args, "anchor");
+    if (anchorRaw) {
+      try { anchor = JSON.parse(anchorRaw); } catch { throw new Error("--anchor must be a JSON object"); }
+    }
+    const r = await call("POST", "/v1/feedback/thread", {
+      body: { slug, body, screenshotUrl, anchor, route: flagVal(args, "route"), version: flagVal(args, "version") },
+      raw: json,
+    });
+    if (json) return process.stdout.write(r + "\n");
+    log(`${c.g("✓")} thread ${short(r.thread.id)} opened on ${c.b(slug)}${screenshotUrl ? c.dim(" (with screenshot)") : ""}`);
+    return;
+  }
+
+  if (sub === "comment" || sub === "resolve" || sub === "reopen") {
+    const [threadId, ...words] = stripFlags(args.slice(1));
+    if (!threadId) throw new Error(`usage: calo-design feedback ${sub} <threadId>${sub === "comment" ? " <text…>" : ""}`);
+    const path = { comment: "/v1/feedback/comment", resolve: "/v1/feedback/resolve", reopen: "/v1/feedback/reopen" }[sub];
+    const body = sub === "comment" ? { threadId, body: words.join(" ").trim() } : { threadId };
+    if (sub === "comment" && !body.body) throw new Error("comment text required");
+    const r = await call("POST", path, { body, raw: json });
+    if (json) return process.stdout.write(r + "\n");
+    log(`${c.g("✓")} ${sub === "comment" ? "commented" : sub + "ed"}`);
+    return;
+  }
+
+  if (sub === "shot") {
+    const [slug, file] = stripFlags(args.slice(1));
+    if (!slug || !file) throw new Error("usage: calo-design feedback shot <slug> <file.png>");
+    const png = fs.readFileSync(file);
+    const r = await call("POST", `/v1/feedback/shot?slug=${encodeURIComponent(slug)}`, { body: png, raw: json });
+    if (json) return process.stdout.write(r + "\n");
+    log(`${c.g("✓")} ${r.url}`);
+    return;
+  }
+
+  // list: `feedback` (inbox: open everywhere) or `feedback <slug>` (--all incl. resolved)
+  const slug = sub || undefined;
+  const all = args.includes("--all");
+  const qs = new URLSearchParams();
+  if (slug) qs.set("slug", slug);
+  if (!all) qs.set("status", "open");
+  const r = await call("GET", `/v1/feedback?${qs}`, { raw: json });
+  if (json) return process.stdout.write(r + "\n");
+  const threads = r.threads;
+  if (!threads.length) return log(c.dim(slug ? `no ${all ? "" : "open "}feedback on ${slug}` : "inbox zero 🎉"));
+  log(c.b(`\n${threads.length} thread(s)${slug ? ` on ${slug}` : ""}${all ? "" : " (open)"}\n`));
+  for (const t of threads) printThread(t, { comments: !!slug });
+}
+
+async function cmdTasks(args = []) {
+  const json = args.includes("--json");
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "";
+
+  if (sub === "new") {
+    const [slug, ...words] = stripFlags(args.slice(1));
+    const title = words.join(" ").trim();
+    if (!slug || !title) throw new Error("usage: calo-design tasks new <slug> <title…> [--from <threadId>] [--body <text>]");
+    const body = { slug, title, sourceThread: flagVal(args, "from"), body: flagVal(args, "body") };
+    const r = await call("POST", "/v1/tasks", { body, raw: json });
+    if (json) return process.stdout.write(r + "\n");
+    log(`${c.g("✓")} task ${short(r.task.id)}: ${r.task.title}${r.task.source_thread ? c.dim(` (from thread ${short(r.task.source_thread)})`) : ""}`);
+    return;
+  }
+
+  if (["start", "done", "wontfix"].includes(sub)) {
+    const [id] = stripFlags(args.slice(1));
+    if (!id) throw new Error(`usage: calo-design tasks ${sub} <id>`);
+    const status = sub === "start" ? "in_progress" : sub;
+    const body = { id, status, ...(sub === "done" && flagVal(args, "version") ? { closedInVersion: flagVal(args, "version") } : {}) };
+    const r = await call("POST", "/v1/tasks/update", { body, raw: json });
+    if (json) return process.stdout.write(r + "\n");
+    log(`${c.g("✓")} ${r.task.title} → ${c.b(r.task.status)}${r.task.closed_in_version ? c.dim(` (${r.task.closed_in_version})`) : ""}`);
+    if (sub === "done") log(c.dim("  source thread (if any) auto-resolved"));
+    return;
+  }
+
+  const slug = sub || undefined;
+  const qs = new URLSearchParams();
+  if (slug) qs.set("slug", slug);
+  const status = flagVal(args, "status");
+  if (status) qs.set("status", status);
+  const r = await call("GET", `/v1/tasks?${qs}`, { raw: json });
+  if (json) return process.stdout.write(r + "\n");
+  const list = r.tasks;
+  if (!list.length) return log(c.dim("no tasks" + (slug ? ` on ${slug}` : "")));
+  log(c.b(`\n${list.length} task(s)${slug ? ` on ${slug}` : ""}\n`));
+  const badge = { todo: c.y("○ todo"), in_progress: c.b("◐ in progress"), done: c.g("● done"), wontfix: c.dim("✕ wontfix") };
+  for (const t of list) {
+    log(`${badge[t.status] || t.status}  ${c.b(t.slug)}  ${t.title}  ${c.dim(short(t.id))}${t.source_thread ? c.dim(" ← " + short(t.source_thread)) : ""}${t.closed_in_version ? c.dim(" " + t.closed_in_version) : ""}`);
+  }
+}
+
+module.exports = { cmdFeedback, cmdTasks };

package/bin/imagegen.js

@@ -5,11 +5,20 @@
  *
  *   calo-design image "prompt"                  generate → writes ./<slug>.png, prints path + URL + cost
  *   calo-design image "prompt" --out hero.png   choose the output path
- *   calo-design image "prompt" --ref photo.jpg  reference/edit input (repeatable, ≤4)
+ *   calo-design image "prompt" --ref photo.jpg  reference/edit input (repeatable; file or https URL)
+ *   calo-design image "prompt" --ref-sheet a.jpg --ref-sheet b.jpg
+ *                                               composite component photos into ONE tile-grid
+ *                                               reference sheet (row-major order — the food
+ *                                               register's component sheet); counts as one ref
+ *   calo-design image "prompt" --sheet-out s.jpg  also save the composed sheet for inspection
  *   calo-design image "prompt" --model <id>     pick an allowed model (default: broker's)
  *   calo-design image usage                     your monthly metering (images + USD, caps)
  *   --json on either form for machine callers (the design/marketing skills use this)
  *
+ * Refs cap at 4 per generation (broker limit). https refs are fetched (≤6 MB) —
+ * this is how CDN reference art (e.g. the food-refs set) attaches without a
+ * local copy.
+ *
  * The OpenRouter key lives on the broker only; identity is the normal CLI session,
  * and the broker meters every generated image per user per month. The broker also
  * mirrors each image to the CDN (content-hashed, immutable) and returns that URL —
@@ -52,19 +61,40 @@ async function apiGet(pathname, session) {
   return json;
 }
 
-function refToDataUrl(file) {
-  const mime = MIMES[path.extname(file).toLowerCase()];
-  if (!mime) throw new Error(`--ref ${file}: must be a .png/.jpg/.jpeg/.webp file`);
+const MAGIC_MIMES = [
+  [(b) => b.length > 2 && b[0] === 0xff && b[1] === 0xd8, "image/jpeg"],
+  [(b) => b.length > 7 && b.readUInt32BE(0) === 0x89504e47, "image/png"],
+  [(b) => b.length > 11 && b.toString("ascii", 8, 12) === "WEBP", "image/webp"],
+];
+
+// A ref is a local file or an https URL (CDN reference art). Returns { buf, mime }.
+async function loadRef(spec, flagName = "--ref") {
   let buf;
-  try {
-    buf = fs.readFileSync(file);
-  } catch {
-    throw new Error(`--ref ${file}: can't read file`);
+  if (/^https?:\/\//i.test(spec)) {
+    let res;
+    try {
+      res = await fetch(spec, { signal: AbortSignal.timeout(20000) });
+    } catch (e) {
+      throw new Error(`${flagName} ${spec}: fetch failed (${e.message})`);
+    }
+    if (!res.ok) throw new Error(`${flagName} ${spec}: HTTP ${res.status}`);
+    buf = Buffer.from(await res.arrayBuffer());
+  } else {
+    try {
+      buf = fs.readFileSync(spec);
+    } catch {
+      throw new Error(`${flagName} ${spec}: can't read file`);
+    }
   }
-  if (buf.length > 6e6) throw new Error(`--ref ${file}: over 6 MB — resize it first`);
-  return `data:${mime};base64,${buf.toString("base64")}`;
+  if (buf.length > 6e6) throw new Error(`${flagName} ${spec}: over 6 MB — resize it first`);
+  const magic = MAGIC_MIMES.find(([test]) => test(buf));
+  const mime = magic ? magic[1] : MIMES[path.extname(new URL(spec, "file:///").pathname).toLowerCase()];
+  if (!mime) throw new Error(`${flagName} ${spec}: must be a png/jpg/webp image`);
+  return { buf, mime };
 }
 
+const toDataUrl = ({ buf, mime }) => `data:${mime};base64,${buf.toString("base64")}`;
+
 // "A hero shot of a grain bowl!" → "a-hero-shot-of-a-grain"
 const promptSlug = (p) =>
   p.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").split("-").slice(0, 5).join("-") || "image";
@@ -105,7 +135,7 @@ async function cmdImage(args) {
 
   // First positional = the prompt. Walk the args so a space-separated flag value
   // (`--ref img.png`) is never mistaken for it.
-  const VALUE_FLAGS = new Set(["--out", "--model", "--ref"]);
+  const VALUE_FLAGS = new Set(["--out", "--model", "--ref", "--ref-sheet", "--sheet-out"]);
   let prompt;
   for (let i = 0; i < args.length; i++) {
     if (VALUE_FLAGS.has(args[i])) i++; // skip the flag's value
@@ -113,14 +143,39 @@ async function cmdImage(args) {
   }
   if (!prompt) {
     throw new Error(
-      'usage: calo-design image "<prompt>" [--out file.png] [--ref img.png]... [--model id] [--json]\n  or:  calo-design image usage'
+      'usage: calo-design image "<prompt>" [--out file.png] [--ref img-or-url]... [--ref-sheet img-or-url]... [--model id] [--json]\n  or:  calo-design image usage'
     );
   }
-  const refImages = flagAll(args, "ref").map(refToDataUrl);
+  const refImages = [];
+  for (const spec of flagAll(args, "ref")) refImages.push(toDataUrl(await loadRef(spec)));
+
+  // --ref-sheet: composite N component photos into ONE row-major tile grid that
+  // costs a single ref slot. Order of the flags = tile order = the order the
+  // prompt's sheet map must bind.
+  const sheetSpecs = flagAll(args, "ref-sheet");
+  let sheetInfo = null;
+  if (sheetSpecs.length) {
+    const { composeSheet } = require("./refsheet");
+    const inputs = [];
+    for (const spec of sheetSpecs) inputs.push({ ...(await loadRef(spec, "--ref-sheet")), label: spec });
+    const sheet = composeSheet(inputs);
+    if (sheet.buf.length > 6e6) throw new Error(`--ref-sheet: composed sheet is over 6 MB (${sheetSpecs.length} tiles) — send fewer tiles`);
+    const sheetOut = flag(args, "sheet-out");
+    if (sheetOut) {
+      fs.mkdirSync(path.dirname(path.resolve(sheetOut)), { recursive: true });
+      fs.writeFileSync(sheetOut, sheet.buf);
+    }
+    refImages.push(toDataUrl({ buf: sheet.buf, mime: "image/jpeg" }));
+    sheetInfo = { tiles: sheetSpecs.length, cols: sheet.cols, rows: sheet.rows, ...(sheetOut ? { file: path.resolve(sheetOut) } : {}) };
+  }
+  if (refImages.length > 4) {
+    throw new Error(`${refImages.length} reference images — the broker caps a generation at 4. Move component refs onto --ref-sheet (one composed sheet = one ref).`);
+  }
   const model = flag(args, "model");
   const out = flag(args, "out");
 
   const session = await ensureSession();
+  if (!jsonOut && sheetInfo) log(c.dim(`Composed reference sheet: ${sheetInfo.tiles} tiles, ${sheetInfo.cols}×${sheetInfo.rows} grid (row-major)${sheetInfo.file ? ` → ${sheetInfo.file}` : ""}`));
   if (!jsonOut) log(c.dim(`Generating${model ? ` with ${model}` : ""}… (typically 10–30s)`));
   let res;
   try {
@@ -156,7 +211,7 @@ async function cmdImage(args) {
 
   if (jsonOut) {
     const { images: _images, ...rest } = data; // drop the base64 payload from machine output
-    process.stdout.write("\n" + JSON.stringify({ ...rest, files }) + "\n");
+    process.stdout.write("\n" + JSON.stringify({ ...rest, files, ...(sheetInfo ? { refSheet: sheetInfo } : {}) }) + "\n");
     return;
   }
   for (const f of files) {

package/bin/refsheet.js

@@ -0,0 +1,107 @@
+"use strict";
+
+/**
+ * Component reference sheet compositor for `calo-design image --ref-sheet`.
+ *
+ * Ported from the imagegen-lab collage builder: N component photos → one
+ * tile-grid JPEG (512px tiles, off-white gutterless grid, row-major order).
+ * The grid exists because the broker caps a generation at 4 reference images —
+ * a meal with more components sends ONE composed sheet instead, and the prompt
+ * binds each tile to its named component ("REFERENCE COMPONENT SHEET MAP").
+ *
+ * Pure-JS on purpose (jpeg-js + pngjs): the CLI stays native-dep-free so
+ * install never needs a compiler toolchain.
+ */
+
+const jpeg = require("jpeg-js");
+const { PNG } = require("pngjs");
+
+const TILE_PX = 512; // longest edge of each tile (matches the lab's collage)
+const BG = [248, 248, 246];
+
+// Same grid ladder as the lab's _pick_grid: near-square, fills row-major.
+function pickGrid(n) {
+  if (n <= 1) return [1, 1];
+  if (n <= 2) return [2, 1];
+  if (n <= 4) return [2, 2];
+  if (n <= 6) return [3, 2];
+  if (n <= 9) return [3, 3];
+  const cols = Math.ceil(Math.sqrt(n));
+  return [cols, Math.ceil(n / cols)];
+}
+
+function decode(buf, label) {
+  if (buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8) {
+    const { width, height, data } = jpeg.decode(buf, { maxMemoryUsageInMB: 256 });
+    return { width, height, data };
+  }
+  if (buf.length > 8 && buf.readUInt32BE(0) === 0x89504e47) {
+    const { width, height, data } = PNG.sync.read(buf);
+    return { width, height, data };
+  }
+  throw new Error(`--ref-sheet ${label}: only JPEG/PNG images can go on a reference sheet`);
+}
+
+// Bilinear resize, RGBA in/out. Never upscales (scale capped at 1).
+function resize(img, maxEdge) {
+  const scale = Math.min(maxEdge / img.width, maxEdge / img.height, 1);
+  const w = Math.max(1, Math.round(img.width * scale));
+  const h = Math.max(1, Math.round(img.height * scale));
+  if (w === img.width && h === img.height) return img;
+  const out = Buffer.alloc(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    const sy = ((y + 0.5) * img.height) / h - 0.5;
+    const y0 = Math.max(0, Math.floor(sy));
+    const y1 = Math.min(img.height - 1, y0 + 1);
+    const fy = sy - y0;
+    for (let x = 0; x < w; x++) {
+      const sx = ((x + 0.5) * img.width) / w - 0.5;
+      const x0 = Math.max(0, Math.floor(sx));
+      const x1 = Math.min(img.width - 1, x0 + 1);
+      const fx = sx - x0;
+      const di = (y * w + x) * 4;
+      for (let ch = 0; ch < 4; ch++) {
+        const p00 = img.data[(y0 * img.width + x0) * 4 + ch];
+        const p10 = img.data[(y0 * img.width + x1) * 4 + ch];
+        const p01 = img.data[(y1 * img.width + x0) * 4 + ch];
+        const p11 = img.data[(y1 * img.width + x1) * 4 + ch];
+        out[di + ch] = Math.round(
+          p00 * (1 - fx) * (1 - fy) + p10 * fx * (1 - fy) + p01 * (1 - fx) * fy + p11 * fx * fy
+        );
+      }
+    }
+  }
+  return { width: w, height: h, data: out };
+}
+
+/**
+ * Compose the sheet. `inputs` = [{ buf, label }] in the order the caller wants
+ * the tiles bound (row-major). Returns { buf (JPEG), width, height, cols, rows }.
+ */
+function composeSheet(inputs) {
+  if (!inputs.length) throw new Error("--ref-sheet: no images to compose");
+  const tiles = inputs.map((i) => resize(decode(i.buf, i.label), TILE_PX));
+  const [cols, rows] = pickGrid(tiles.length);
+  const W = cols * TILE_PX;
+  const H = rows * TILE_PX;
+  const canvas = Buffer.alloc(W * H * 4);
+  for (let p = 0; p < W * H; p++) {
+    canvas[p * 4] = BG[0];
+    canvas[p * 4 + 1] = BG[1];
+    canvas[p * 4 + 2] = BG[2];
+    canvas[p * 4 + 3] = 255;
+  }
+  tiles.forEach((tile, idx) => {
+    const cx = (idx % cols) * TILE_PX + Math.floor((TILE_PX - tile.width) / 2);
+    const cy = Math.floor(idx / cols) * TILE_PX + Math.floor((TILE_PX - tile.height) / 2);
+    for (let y = 0; y < tile.height; y++) {
+      // Alpha is ignored on paste: reference photos are opaque; PNG alpha
+      // lands on the off-white background anyway after JPEG encode.
+      tile.data.copy(canvas, ((cy + y) * W + cx) * 4, y * tile.width * 4, (y + 1) * tile.width * 4);
+    }
+  });
+  const out = jpeg.encode({ data: canvas, width: W, height: H }, 85);
+  return { buf: out.data, width: W, height: H, cols, rows };
+}
+
+module.exports = { composeSheet, _pickGrid: pickGrid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calo-design/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "One-line setup for Calo design tooling: logs in with your Calo email and installs the calo-design skill + design-system packages. No GitHub account needed.",
   "bin": {
     "calo-design": "bin/cli.js"
@@ -16,6 +16,8 @@
     "node": ">=18"
   },
   "dependencies": {
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
     "qrcode-terminal": "^0.12.0"
   }
 }