@calo-design/cli 0.7.0 → 0.8.0

package/bin/cli.js

@@ -774,7 +774,8 @@ 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")}

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.7.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"
   }
 }