scenri 0.7.4 → 0.8.0

package/dist/serve.js

@@ -212,11 +212,13 @@ function widenNodeStatusCheck(db) {
         overlays TEXT NOT NULL DEFAULT '{}',
         brief TEXT,
         archived INTEGER NOT NULL DEFAULT 0,
-        duration_ms INTEGER
+        duration_ms INTEGER,
+        batch_id TEXT,
+        batch_index INTEGER NOT NULL DEFAULT 0
       );
       INSERT INTO nodes_new
         SELECT id, project_id, parent_id, kind, prompt, engine_id, status, images, cost_usd, kept, error,
-               created_at, overlays, brief, archived, duration_ms
+               created_at, overlays, brief, archived, duration_ms, batch_id, batch_index
         FROM nodes;
       DROP TABLE nodes;
       ALTER TABLE nodes_new RENAME TO nodes;
@@ -295,11 +297,104 @@ function collapseProjects(db) {
     })();
   }
 }
-var SCHEMA_VERSION = 1;
+function splitMultiImageNodes(db) {
+  const rows = db.prepare("SELECT * FROM nodes").all();
+  const multi = rows.filter((r) => {
+    try {
+      return JSON.parse(r.images).length > 1;
+    } catch {
+      return false;
+    }
+  });
+  if (!multi.length) return;
+  const parse2 = (s) => {
+    if (!s) return null;
+    try {
+      return JSON.parse(s);
+    } catch {
+      return null;
+    }
+  };
+  const stampOf = (iso, minusMs) => {
+    const t = (/* @__PURE__ */ new Date(`${iso.replace(" ", "T")}Z`)).getTime() - minusMs;
+    const d = new Date(t);
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`;
+  };
+  const updateOriginal = db.prepare(
+    "UPDATE nodes SET images=?, overlays=?, brief=?, batch_id=?, batch_index=0 WHERE id=?"
+  );
+  const insertSibling = db.prepare(
+    `INSERT INTO nodes (id, project_id, parent_id, kind, prompt, engine_id, status, images, cost_usd, kept,
+       error, created_at, overlays, brief, archived, duration_ms, batch_id, batch_index)
+     VALUES (?,?,?,?,?,?,?,?,0,?,?,?,?,?,?,NULL,?,?)`
+  );
+  const childrenOf = db.prepare("SELECT id, brief FROM nodes WHERE parent_id=?");
+  const repoint = db.prepare("UPDATE nodes SET parent_id=? WHERE id=?");
+  const setsOf = db.prepare("SELECT set_id FROM set_nodes WHERE node_id=?");
+  const addMember = db.prepare("INSERT OR IGNORE INTO set_nodes (set_id, node_id) VALUES (?,?)");
+  db.transaction(() => {
+    for (const r of multi) {
+      const images = JSON.parse(r.images);
+      const overlays = parse2(r.overlays) ?? {};
+      const brief = parse2(r.brief);
+      const sizes = Array.isArray(brief?.rendered?.sizes) ? brief.rendered.sizes : null;
+      const briefFor = (i) => {
+        if (!brief) return null;
+        const b = { ...brief, variants: images.length };
+        if (brief.rendered) {
+          const { requested: _req, variantIndexes: _vi, ...rendered } = brief.rendered;
+          b.rendered = { ...rendered, ...sizes ? { sizes: sizes[i] !== void 0 ? [sizes[i]] : [] } : {} };
+        }
+        return JSON.stringify(b);
+      };
+      const siblingIds = [r.id];
+      updateOriginal.run(
+        JSON.stringify([images[0]]),
+        JSON.stringify(overlays["0"] !== void 0 ? { "0": overlays["0"] } : {}),
+        briefFor(0),
+        r.id,
+        r.id
+      );
+      for (let i = 1; i < images.length; i++) {
+        const id = randomUUID();
+        siblingIds.push(id);
+        insertSibling.run(
+          id,
+          r.project_id,
+          r.parent_id,
+          r.kind,
+          r.prompt,
+          r.engine_id,
+          r.status,
+          JSON.stringify([images[i]]),
+          r.kept,
+          r.error,
+          stampOf(r.created_at, i),
+          JSON.stringify(overlays[String(i)] !== void 0 ? { "0": overlays[String(i)] } : {}),
+          briefFor(i),
+          r.archived,
+          r.id,
+          i
+        );
+      }
+      for (const child of childrenOf.all(r.id)) {
+        const src = parse2(child.brief)?.sourceImage;
+        if (typeof src !== "string") continue;
+        const at = images.indexOf(src);
+        if (at > 0) repoint.run(siblingIds[at], child.id);
+      }
+      for (const s of setsOf.all(r.id)) {
+        for (let i = 1; i < siblingIds.length; i++) addMember.run(s.set_id, siblingIds[i]);
+      }
+    }
+  })();
+}
+var SCHEMA_VERSION = 2;
 var SchemaTooNewError = class extends Error {
-  constructor(found, supported) {
+  constructor(found, supported, backupsDir) {
     super(
-      `This library was written by a newer Scenri (schema ${found}; this build understands ${supported}). Update and retry: npx scenri@latest`
+      `This library was written by a newer Scenri (schema ${found}; this build understands ${supported}). Update and retry: npx scenri@latest` + (backupsDir ? ` (a pre-migration snapshot of the library is kept in ${backupsDir})` : "")
     );
     this.name = "SchemaTooNewError";
   }
@@ -329,7 +424,7 @@ function openDb(homeDir) {
   const found = db.pragma("user_version", { simple: true });
   if (found > SCHEMA_VERSION) {
     db.close();
-    throw new SchemaTooNewError(found, SCHEMA_VERSION);
+    throw new SchemaTooNewError(found, SCHEMA_VERSION, join(homeDir, "backups"));
   }
   if (preExisting && found < SCHEMA_VERSION) backupBeforeMigration(db, homeDir, found);
   db.exec(MIGRATIONS);
@@ -346,6 +441,12 @@ function openDb(homeDir) {
   if (!nodeCols.includes("duration_ms")) {
     db.exec("ALTER TABLE nodes ADD COLUMN duration_ms INTEGER");
   }
+  if (!nodeCols.includes("batch_id")) {
+    db.exec("ALTER TABLE nodes ADD COLUMN batch_id TEXT");
+  }
+  if (!nodeCols.includes("batch_index")) {
+    db.exec("ALTER TABLE nodes ADD COLUMN batch_index INTEGER NOT NULL DEFAULT 0");
+  }
   const projectCols = db.pragma("table_info(projects)").map((c) => c.name);
   if (!projectCols.includes("slug")) {
     db.exec("ALTER TABLE projects ADD COLUMN slug TEXT");
@@ -362,6 +463,7 @@ function openDb(homeDir) {
   widenNodeStatusCheck(db);
   backfillSlugs(db);
   collapseProjects(db);
+  splitMultiImageNodes(db);
   db.prepare(
     "UPDATE nodes SET status='error', error='interrupted: server restarted mid-generation' WHERE status='running'"
   ).run();
@@ -482,9 +584,21 @@ function rowToNode(r) {
     createdAt: r.created_at,
     overlays: JSON.parse(r.overlays ?? "{}"),
     brief: r.brief ? JSON.parse(r.brief) : null,
-    archived: !!r.archived
+    archived: !!r.archived,
+    batchId: r.batch_id ?? null,
+    batchIndex: r.batch_index ?? 0
   };
 }
+var lastBatchStamp = 0;
+function batchStamps(count) {
+  const base = Math.max(Date.now(), lastBatchStamp + count);
+  lastBatchStamp = base;
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return Array.from({ length: count }, (_, i) => {
+    const d = new Date(base - i);
+    return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`;
+  });
+}
 function createStore(db) {
   return {
     // brands
@@ -648,6 +762,42 @@ function createStore(db) {
       ).run(id, input.projectId, input.parentId, input.kind, input.prompt, input.engineId);
       return this.getNode(id);
     },
+    /**
+     * One multi-shot request, N first-class sibling nodes, one transaction.
+     * Slot 0 gets the newest stamp (see batchStamps) so the newest-first feed
+     * reads the batch in request order; batch_id is the first node's id, held
+     * by every sibling including the first, and stays null for a single send
+     * — one shot is not a batch.
+     */
+    addNodes(input) {
+      if (input.parentId) {
+        const parent = this.getNode(input.parentId);
+        if (!parent || parent.projectId !== input.projectId) throw new Error("parent node not found in project");
+      }
+      const count = Math.max(1, Math.floor(input.count));
+      const ids = Array.from({ length: count }, () => randomUUID());
+      const stamps = batchStamps(count);
+      const batchId = count > 1 ? ids[0] : null;
+      const insert = db.prepare(
+        "INSERT INTO nodes (id, project_id, parent_id, kind, prompt, engine_id, created_at, batch_id, batch_index) VALUES (?,?,?,?,?,?,?,?,?)"
+      );
+      db.transaction(() => {
+        for (let i = 0; i < count; i++) {
+          insert.run(
+            ids[i],
+            input.projectId,
+            input.parentId,
+            input.kind,
+            input.prompt,
+            input.engineId,
+            stamps[i],
+            batchId,
+            i
+          );
+        }
+      })();
+      return ids.map((id) => this.getNode(id));
+    },
     completeNode(id, result) {
       db.prepare("UPDATE nodes SET status='done', images=?, cost_usd=?, duration_ms=? WHERE id=?").run(
         JSON.stringify(result.images),
@@ -656,6 +806,16 @@ function createStore(db) {
         id
       );
     },
+    /**
+     * The run's money, written once it is known. A batch's first sibling used
+     * to be charged inside completeNode, at the end of the whole call; a
+     * sibling now completes the moment its own image lands, and the cost is
+     * only known when the call resolves, so it is written afterwards, onto a
+     * node that finished. A failed or running node keeps 0, as before.
+     */
+    chargeNode(id, costUsd) {
+      db.prepare("UPDATE nodes SET cost_usd=? WHERE id=? AND status='done'").run(costUsd, id);
+    },
     failNode(id, error) {
       db.prepare("UPDATE nodes SET status='error', error=? WHERE id=?").run(error, id);
     },
@@ -1454,7 +1614,17 @@ function createOpenRouterEngine(opts) {
         localOnly: false,
         supportsEdit: true,
         supportsMask: false,
+        // Four is OUR conservative constant, not a provider fact: OpenRouter
+        // multiplexes many image models and their input limits differ, so
+        // there is no single upstream number to cite the way codex's five is
+        // cited. Four keeps a full identity payload (product essential +
+        // angle, presenter, mark) inside every model we have routed to.
         maxReferenceImages: 4,
+        // Same uplink argument as codex: the provider reads references at
+        // reduced resolution anyway, and these ride base64-inlined inside a
+        // JSON body — a full-resolution phone photo is tens of megabytes of
+        // request for nothing.
+        maxReferenceEdge: 2048,
         // N sequential calls, one image each: the server budgets the node by
         // that shape instead of handing the whole run one flat ten minutes.
         perImageTimeoutMs: PER_IMAGE_TIMEOUT_MS,
@@ -1470,7 +1640,7 @@ function createOpenRouterEngine(opts) {
       const count = "count" in req ? req.count : 1;
       return count * perImageUsd;
     },
-    async generate(req, signal) {
+    async generate(req, signal, onImage) {
       const key = requireKey();
       const roles = req.referenceRoles ?? [];
       const refs = req.referenceImages ?? [];
@@ -1506,7 +1676,9 @@ function createOpenRouterEngine(opts) {
           signal
         );
         raws.push(json);
-        for (const buf of extractImages(json)) hashes.push(opts.saveImage(buf));
+        const own = extractImages(json).map((buf) => opts.saveImage(buf));
+        hashes.push(...own);
+        if (own[0]) onImage?.(i, own[0]);
         if (typeof json?.usage?.cost === "number") {
           reportedCost += json.usage.cost;
           sawReportedCost = true;
@@ -2703,7 +2875,7 @@ function createCodexEngine(opts) {
     async costEstimate() {
       return 0;
     },
-    async generate(req, signal) {
+    async generate(req, signal, onImage) {
       const count = Math.max(1, req.count);
       const refs = req.referenceImages ?? [];
       const roles = req.referenceRoles ?? refs.map(() => "reference");
@@ -2742,6 +2914,7 @@ function createCodexEngine(opts) {
             const i = next++;
             try {
               results[i] = await jobs[i]();
+              if (results[i][0]) onImage?.(i, results[i][0]);
             } catch (err) {
               if (signal?.aborted && signal.reason !== BUDGET_EXHAUSTED) throw err;
               results[i] = [];
@@ -2881,7 +3054,30 @@ function createEngineRegistry(core, extra = []) {
     codexRunner
   };
 }
-function createDemoEngine(saveImage) {
+function demoOptionsFromEnv(env) {
+  const out = {};
+  const stagger = Number(env.SCENRI_DEMO_STAGGER_MS);
+  if (env.SCENRI_DEMO_STAGGER_MS && Number.isFinite(stagger) && stagger > 0) out.staggerMs = stagger;
+  if (env.SCENRI_DEMO_ORDER === "reverse") out.order = "reverse";
+  const fail = Number(env.SCENRI_DEMO_FAIL_SLOT);
+  if (env.SCENRI_DEMO_FAIL_SLOT && Number.isInteger(fail) && fail >= 0) out.failSlot = fail;
+  return out;
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function createDemoEngine(saveImage, opts = {}) {
   const paletteOf = (req) => {
     const p = req.brand?.brand?.palette;
     const hexes = [p?.primary?.hex, p?.secondary?.hex, ...(p?.accent ?? []).map((a) => a?.hex)].filter(
@@ -2927,13 +3123,31 @@ function createDemoEngine(saveImage) {
     async costEstimate() {
       return 0;
     },
-    async generate(req) {
+    async generate(req, signal, onImage) {
       const colors = paletteOf(req);
-      const images = [];
-      for (let i = 0; i < Math.max(1, req.count); i++) {
-        images.push(saveImage(await render(colors, req.prompt, req.width, req.height, i + req.prompt.length)));
-      }
-      return { images, costUsd: 0 };
+      const count = Math.max(1, req.count);
+      const slots = Array.from({ length: count }, (_, i) => i);
+      if (opts.order === "reverse") slots.reverse();
+      const landed = /* @__PURE__ */ new Map();
+      const failures = [];
+      for (const [position, slot] of slots.entries()) {
+        if (position > 0 && opts.staggerMs) await sleep2(opts.staggerMs, signal);
+        if (signal?.aborted) {
+          if (signal.reason === BUDGET_EXHAUSTED) break;
+          throw Object.assign(new Error("generation cancelled"), { name: "AbortError" });
+        }
+        if (slot === opts.failSlot) {
+          failures.push(`demo: slot ${slot + 1} refused`);
+          continue;
+        }
+        const hash = saveImage(await render(colors, req.prompt, req.width, req.height, slot + req.prompt.length));
+        landed.set(slot, hash);
+        onImage?.(slot, hash);
+      }
+      const done = [...landed.keys()].sort((a, b) => a - b);
+      const images = done.map((slot) => landed.get(slot));
+      if (done.length === count) return { images, costUsd: 0 };
+      return { images, costUsd: 0, raw: { requested: count, variantIndexes: done, partialFailures: failures } };
     },
     async edit(req) {
       const colors = paletteOf(req);
@@ -3238,13 +3452,22 @@ function defaultDemoProductsDir() {
 }
 
 // src/attachmentBudget.ts
+var SEAT_TIER = {
+  brand: 0,
+  reference: 0,
+  product: 0,
+  character: 0,
+  scene: 0,
+  composition: 1,
+  style: 2
+};
 var ROLE_PRIORITY = {
   product: 0,
   character: 1,
   brand: 2,
-  scene: 3,
-  composition: 4,
-  reference: 5,
+  reference: 3,
+  scene: 4,
+  composition: 5,
   style: 6
 };
 function allocateAttachments(attachments, cap2) {
@@ -3260,11 +3483,8 @@ function allocateAttachments(attachments, cap2) {
     kept.add(x.i);
     keptGroups.add(groupOf(x.a));
   };
-  for (const x of legacyOrder) {
-    if (kept.size >= max) break;
-    if (x.a.essential) admit(x);
-  }
-  for (const x of legacyOrder) {
+  const seatOrder = [...indexed].sort((x, y) => SEAT_TIER[x.a.role] - SEAT_TIER[y.a.role] || x.i - y.i);
+  for (const x of seatOrder) {
     if (kept.size >= max) break;
     if (!kept.has(x.i) && !keptGroups.has(groupOf(x.a))) admit(x);
   }
@@ -3289,7 +3509,13 @@ function allocateAttachments(attachments, cap2) {
   }
   return {
     kept: legacyOrder.filter((x) => kept.has(x.i)).map((x) => x.a),
-    dropped: legacyOrder.filter((x) => !kept.has(x.i)).map((x) => x.a)
+    dropped: legacyOrder.filter((x) => !kept.has(x.i)).map((x) => x.a),
+    // The same images in the order the brief placed them, for a caller that
+    // will allocate again: `kept` is re-sorted by role for the consumers
+    // below, and feeding that back into a second, tighter allocation put
+    // every product ahead of every face on a refinement whatever the line
+    // said.
+    seated: seatOrder.filter((x) => kept.has(x.i)).map((x) => x.a)
   };
 }
 function mergeEditAttachments(own, inherited, cap2) {
@@ -3454,12 +3680,19 @@ function shotSpecifiesCamera(text) {
     text
   );
 }
+function namesAreNotLetteringDirective() {
+  return "The names in this brief identify what to show and are never text to render: no caption, label, signage, engraving or lettering spells a product name or a person's name, in any language or script, anywhere in the picture. Printing that is part of a product's own packaging stays exactly as photographed, and nothing else spells a name unless the direction above explicitly asks for it to be written.";
+}
 function sceneFigureDirectives(opts) {
   const figure = opts.figure.trim().replace(/[.\s]+$/, "");
   if (!figure) return [];
   const treatment = (opts.treatment ?? "").trim().replace(/[.\s]+$/, "");
   const out = [];
-  if (opts.hasPerson) {
+  if (opts.hasPerson && (opts.people ?? 1) > 1) {
+    out.push(
+      `This world is built around one figure: ${figure}. The attached presenters share that role: the first named presenter takes the figure position and the others stand with them in the same frame, every one of them clearly visible. Any person the scene direction describes IS one of the attached presenters and never an extra person, and each identity comes from their own attached photograph alone, never from anything the scene direction says about a body.`
+    );
+  } else if (opts.hasPerson) {
     out.push(
       `This world is built around one figure: ${figure}. The attached presenter is that figure. Any person the scene direction describes IS the presenter and never a second person, and their identity comes from their own attached photograph alone, never from anything the scene direction says about a body.`
     );
@@ -3580,6 +3813,8 @@ function validateBrief(brief) {
       case "ref":
       case "mark":
         if (!str4(t.imageHash)) errors.push(`${at}.imageHash must be a non-empty string`);
+        if (t.t === "ref" && t.label !== void 0 && typeof t.label !== "string")
+          errors.push(`${at}.label must be a string when present`);
         break;
       case "format":
         if (!Number.isFinite(t.w) || !Number.isFinite(t.h) || Number(t.w) <= 0 || Number(t.h) <= 0)
@@ -3594,6 +3829,7 @@ function validateBrief(brief) {
 function compileBrief(brief, ctx) {
   const warnings = [];
   const attachments = [];
+  const unattachable = [];
   const rawSceneFallback = [];
   const productDirectives = [];
   const personDirectives = [];
@@ -3605,6 +3841,7 @@ function compileBrief(brief, ctx) {
   const characters = ctx.brand?.characters ?? [];
   const inlineTemplates = [];
   let hasPerson = false;
+  let people = 0;
   let sentence = "";
   const append = (s) => {
     sentence += (sentence && !sentence.endsWith(" ") ? " " : "") + s;
@@ -3645,7 +3882,7 @@ function compileBrief(brief, ctx) {
               ...angle ? { angle } : {}
             });
           });
-          productDirectives.push(productFidelityDirective(pshots.length));
+          productDirectives.push({ need: "fidelity", id: p.id });
           productDirectives.push(...productFactDirectives(p));
           if (p.description && !p.dimensions)
             productDirectives.push(
@@ -3653,6 +3890,7 @@ function compileBrief(brief, ctx) {
             );
         } else {
           warnings.push(`${p.name} has no usable photo, so it is named but not attached.`);
+          unattachable.push({ role: "product", id: p.id, label: p.name, hash: "", essential: true, reason: "missing" });
         }
         break;
       }
@@ -3663,6 +3901,7 @@ function compileBrief(brief, ctx) {
           break;
         }
         hasPerson = true;
+        people += 1;
         append(c.promptName ?? c.name);
         const cshots = (c.shots ?? []).slice(0, CHARACTER_REF_MAX).map((s) => ({ h: assetHash2(s?.file), angle: s?.angle ? String(s.angle) : void 0 })).filter((x) => !!x.h && ctx.images.has(x.h));
         if (cshots.length) {
@@ -3694,13 +3933,23 @@ function compileBrief(brief, ctx) {
           if (c.build) personDirectives.push(`${c.promptName ?? c.name}'s build: ${c.build}.`);
         } else {
           warnings.push(`${c.name} has no usable photo, so they are named but not attached.`);
+          unattachable.push({
+            role: "character",
+            id: c.id,
+            label: c.name,
+            hash: "",
+            essential: true,
+            reason: "missing"
+          });
         }
         break;
       }
       case "color": {
         const hex = tok.hex.toUpperCase();
-        append(tok.name ? `${tok.name} (${hex})` : hex);
-        otherDirectives.push(`Use ${hex} as a defining color in the composition.`);
+        append(tok.name ? `(brand color ${tok.name} ${hex})` : `(brand color ${hex})`);
+        otherDirectives.push(
+          `Use ${hex} as a defining color in the composition, in surfaces, materials and light, never as lettering.`
+        );
         break;
       }
       case "ref": {
@@ -3713,7 +3962,12 @@ function compileBrief(brief, ctx) {
           break;
         }
         attachments.push({ role: "reference", label: "Reference shot", hash: tok.imageHash });
-        otherDirectives.push("Match the composition, lighting and treatment of the attached reference.");
+        otherDirectives.push({
+          need: "attachment",
+          role: "reference",
+          hash: tok.imageHash,
+          text: "Match the composition, lighting and treatment of the attached reference."
+        });
         break;
       }
       case "mark": {
@@ -3733,9 +3987,12 @@ function compileBrief(brief, ctx) {
             );
         } catch {
         }
-        otherDirectives.push(
-          "The attached brand mark is this brand's own mark. If the direction asks for the logo to appear, reproduce it exactly as drawn \u2014 same colours, letterforms and proportions, never redrawn or re-lettered. Every character it carries appears intact, including the smallest secondary lettering, in its original script and reading direction \u2014 never translated, transliterated or re-spelled. Otherwise take only its colour and treatment from it."
-        );
+        otherDirectives.push({
+          need: "attachment",
+          role: "brand",
+          hash: tok.imageHash,
+          text: "The attached brand mark is this brand's own mark. If the direction asks for the logo to appear, reproduce it exactly as drawn \u2014 same colours, letterforms and proportions, never redrawn or re-lettered. Every character it carries appears intact, including the smallest secondary lettering, in its original script and reading direction \u2014 never translated, transliterated or re-spelled. Otherwise take only its colour and treatment from it."
+        });
         break;
       }
       case "template": {
@@ -3815,8 +4072,50 @@ function compileBrief(brief, ctx) {
       if (i !== -1) attachments.splice(i, 1);
     }
   }
+  const identityHashes = /* @__PURE__ */ new Map();
+  for (const a of attachments)
+    if ((a.role === "product" || a.role === "character") && !identityHashes.has(a.hash))
+      identityHashes.set(a.hash, a.label);
+  for (let i = attachments.length - 1; i >= 0; i--) {
+    const a = attachments[i];
+    if (a.role === "reference" && identityHashes.has(a.hash)) {
+      attachments.splice(i, 1);
+      warnings.push(
+        `That reference is the same image as ${identityHashes.get(a.hash)}'s own photo, so it rides once, as the identity.`
+      );
+    }
+  }
   const max = ctx.engineCaps.maxReferenceImages;
-  const { kept, dropped } = allocateAttachments(attachments, max);
+  const { kept, dropped: budgetDropped, seated } = allocateAttachments(attachments, max);
+  const presentKeys = new Set((ctx.presentAttachments ?? kept).map((a) => `${a.role}:${a.hash}`));
+  const resolveDirective = (d) => {
+    if (typeof d === "string") return d;
+    if (d.need === "fidelity") {
+      const n = attachments.filter(
+        (a) => a.role === "product" && a.id === d.id && presentKeys.has(`product:${a.hash}`)
+      ).length;
+      return n > 0 ? productFidelityDirective(n) : null;
+    }
+    return presentKeys.has(`${d.role}:${d.hash}`) ? d.text : null;
+  };
+  const absentDirectives = [];
+  const absentSeen = /* @__PURE__ */ new Set();
+  for (const a of attachments) {
+    const key = `${a.role}:${a.hash}`;
+    if (presentKeys.has(key) || absentSeen.has(key)) continue;
+    if (a.role === "reference") {
+      absentSeen.add(key);
+      const words = ctx.wordsFor?.(a.hash) ?? null;
+      absentDirectives.push(
+        words ? `A reference shot was not attached this time; it showed ${words}. Match that composition, lighting and treatment.` : "A reference image was attached but not sent this time."
+      );
+    } else if (a.role === "brand") {
+      absentSeen.add(key);
+      absentDirectives.push(
+        `The brand mark "${a.label}" was not attached this time; keep every branded surface plain and do not invent a logo.`
+      );
+    }
+  }
   const guard = scene ? sceneGuardDirectives({
     hasProduct: !!productId,
     hasPerson,
@@ -3833,13 +4132,16 @@ function compileBrief(brief, ctx) {
     "Any earlier instruction that bans props, hands, people, or a presenter from the frame is a solo-packshot rule for this product and does not apply to this shot: the attached presenter is deliberate and must appear as directed.",
     productHandlingDirective()
   ] : [];
+  const nameDirectives = productId || hasPerson ? [namesAreNotLetteringDirective()] : [];
   const figureDirectives = scene?.figure ? sceneFigureDirectives({
     figure: scene.figure,
     treatment: scene.figureTreatment,
     hasPerson,
+    people,
     // The treatment's fictional-brands rule needs to know a real mark is
-    // deliberately in play; attachments are fully collected by this point.
-    hasMark: attachments.some((a) => a.role === "brand")
+    // deliberately in play - and only one that actually rides counts,
+    // same honesty rule as the photo guard above.
+    hasMark: [...presentKeys].some((k) => k.startsWith("brand:"))
   }) : [];
   if (hasPerson) personDirectives.push(personSkinDirective());
   const closeUpDirectives = hasPerson && /\bclose[- ]?up\b|\bmacro\b|\bzoom(?:ed)?\b|\bDOF\b|\bdepth of field\b/i.test(sentence) ? [
@@ -3864,12 +4166,16 @@ function compileBrief(brief, ctx) {
   }) ? [garmentDisplayDirective()] : [];
   const refGuard = ctx.mode !== "edit" && hasPerson && kept.some((a) => a.role === "reference") ? [referenceIdentityGuard()] : [];
   const allDirectives = [
+    // First, beside the sentence that names things: the model reads the names
+    // and this line in one breath, before any spec repeats them.
+    ...nameDirectives,
     ...productDirectives,
     ...personDirectives,
     ...pairDirectives,
     ...figureDirectives,
     ...closeUpDirectives,
     ...otherDirectives,
+    ...absentDirectives,
     ...cameraDirectives,
     ...apparelUnworn,
     ...brandLines,
@@ -3877,31 +4183,59 @@ function compileBrief(brief, ctx) {
     ...refGuard,
     ...preservation
   ];
-  if (allDirectives.length) prompt = `${prompt}${prompt.endsWith(".") ? "" : "."} ${dedupe(allDirectives).join(" ")}`;
-  if (dropped.some((d) => d.role !== "scene")) {
+  const spoken = dedupe(allDirectives.map(resolveDirective).filter((s) => s !== null));
+  if (spoken.length) prompt = `${prompt}${prompt.endsWith(".") ? "" : "."} ${spoken.join(" ")}`;
+  if (max === 0 && budgetDropped.some((d) => d.role !== "scene")) {
     const keptLabels = new Set(kept.map((a) => a.label));
-    const names = [...new Set(dropped.filter((d) => d.role !== "scene").map((d) => d.label))].filter(
+    const names = [...new Set(budgetDropped.filter((d) => d.role !== "scene").map((d) => d.label))].filter(
       (l) => !keptLabels.has(l)
     );
     if (names.length) {
-      const reads = max === 0 ? "reads no reference images" : `reads ${max} reference image${max === 1 ? "" : "s"}`;
       warnings.push(
-        `${ctx.engineCaps.displayName} ${reads}, so ${names.join(" and ")} ${names.length === 1 ? "was" : "were"} left out.`
+        `${names.join(" and ")} ${names.length === 1 ? "was" : "were"} left out \u2014 ${ctx.engineCaps.displayName} reads no reference images.`
       );
     }
   }
   return {
     prompt: prompt.trim(),
     referenceImages: kept.map((a) => ctx.images.pathFor(a.hash)),
-    dropped,
+    // The missing-photo identities lead: they are essential, and the refusal
+    // path reads this list. Budget losses carry their reason for the chips.
+    dropped: [...unattachable, ...budgetDropped.map((d) => ({ ...d, reason: "budget" }))],
     width,
     height,
     attachments: kept,
+    seated,
     warnings,
     productId
   };
 }
 var dedupe = (xs) => [...new Set(xs)];
+
+// src/shotWords.ts
+function shotWords(prompt, max = 160) {
+  if (!prompt) return null;
+  const head = prompt.split(/\. (?=[A-Z])/)[0]?.trim() ?? "";
+  if (!head) return null;
+  const clipped = head.length > max ? `${head.slice(0, max).replace(/\s+\S*$/, "")}\u2026` : head;
+  return clipped.replace(/[.\s]+$/, "");
+}
+function shotWordsFor(core, brandId) {
+  let byHash = null;
+  return (hash) => {
+    if (!byHash) {
+      byHash = /* @__PURE__ */ new Map();
+      for (const p of core.store.listProjects(brandId)) {
+        for (const n of core.store.treeFor(p.id)) {
+          const words = shotWords(n.prompt);
+          if (!words) continue;
+          for (const h of n.images ?? []) if (!byHash.has(h)) byHash.set(h, words);
+        }
+      }
+    }
+    return byHash.get(hash) ?? null;
+  };
+}
 var DEFAULT_CONTENT_URL = "https://github.com/tonygorb/scenri/releases/download/content-latest/scenri-content.zip";
 var TIMEOUT_MS = 10 * 60 * 1e3;
 function resolveContentUrl(env = process.env, override) {
@@ -4828,7 +5162,7 @@ function dedupeProducts(products) {
 
 // ../catalog/src/http/fetch.ts
 var USER_AGENT = "scenri-catalog/0.1 (+https://scenri.co)";
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function httpGet(url, opts = {}) {
@@ -4852,7 +5186,7 @@ async function httpGet(url, opts = {}) {
         }
       });
       if ((res.status === 429 || res.status >= 500) && attempt < retries) {
-        await sleep2(400 * 2 ** attempt);
+        await sleep3(400 * 2 ** attempt);
         continue;
       }
       return res;
@@ -4860,7 +5194,7 @@ async function httpGet(url, opts = {}) {
       lastErr = err;
       if (opts.signal?.aborted) throw err;
       if (attempt < retries) {
-        await sleep2(400 * 2 ** attempt);
+        await sleep3(400 * 2 ** attempt);
         continue;
       }
       throw err;
@@ -7830,11 +8164,6 @@ function registerLogoRoutes(app, deps) {
     if (!v.valid) return reply.status(400).send({ error: "brand became invalid", details: v.errors });
     return core.store.updateBrand(brand.id, json);
   });
-  app.get("/api/brands/:id/directives", async (req, reply) => {
-    const brand = core.store.getBrand(req.params.id);
-    if (!brand) return reply.status(404).send({ error: "brand not found" });
-    return { directives: brandRuleDirectives(brand.json) };
-  });
   app.delete("/api/brands/:id/logos/:hash", async (req, reply) => {
     const brand = core.store.getBrand(req.params.id);
     if (!brand) return reply.status(404).send({ error: "brand not found" });
@@ -8760,6 +9089,48 @@ function registerImageRoutes(app, deps) {
 
 // src/release/notes.data.ts
 var RELEASES = [
+  {
+    version: "0.8.0",
+    date: "2026-09-02",
+    title: "The composer, rebuilt around what a shot is made of.",
+    sections: [
+      {
+        heading: "Create",
+        body: "Ingredients are compact chips now, each carrying the picture it stands for, and hovering one shows you what it is holding. A shot can hold twelve of them: the ones your engine can photograph are lit, and the rest ride along in words rather than being dropped, with every chip saying which it is. Photos go out in the order you wrote them, so the first thing you named is the first thing pictured. The asset panel beside the brief is a second door into it, so a tile ticks when its chip is in and clicking it again takes the chip out."
+      },
+      {
+        heading: "Refine",
+        body: "The panel beside an open shot has been redrawn, and its edge can be dragged to the width you want. Above the brief it shows what the picture is actually made of, resolved through the whole chain of refinements rather than just the last one, so nothing is repeated and nothing is lost at depth."
+      },
+      {
+        heading: "Brand",
+        body: "A product name is something to show in a shot, never lettering to paint into it, and a brand colour is now spoken as a note rather than an instruction, which keeps invented signage out of your pictures. Brand rules apply to every shot from Settings, so the composer no longer carries a row to say so."
+      },
+      {
+        heading: "Fixes",
+        body: "A finished shot appears the moment it lands instead of waiting for the rest of its batch, and a batch sent from a set files every shot in it. Typing around a chip behaves: the chip owns the space beside it, one press removes it, and two chips always keep the single space between them. Two presenters in a scene no longer compose one of them out."
+      }
+    ]
+  },
+  {
+    version: "0.7.5",
+    date: "2026-09-01",
+    title: "Every shot is one card.",
+    sections: [
+      {
+        heading: "Create",
+        body: "Every shot is now its own card with its own image. Asking for several shots gives you that many cards, made together and standing on their own, and older multi-image shots split into separate cards the first time this version opens. The shot panel is rebuilt around the brief itself, with inline ingredient chips and versions in a single strip under the picture."
+      },
+      {
+        heading: "Refining",
+        body: "The shot being refined appears as a regular chip in the composer, and the card it points at is marked in the feed. Scenes sit out of the attach panel while a refine is armed, with a note saying why, instead of quietly trading the refine for a new shot."
+      },
+      {
+        heading: "Fixes",
+        body: "Generation requests carry exactly the reference images they claim to carry, and a product or presenter whose photo is missing stops the shot with a clear message instead of running without it. Cards that are still rendering show a simple counter and a cancel button."
+      }
+    ]
+  },
   {
     version: "0.7.4",
     date: "2026-08-31",
@@ -9900,9 +10271,10 @@ function buildServer(opts) {
       }
     }
     if (inheritedPerson) inheritedDirectives.push(personSkinDirective());
-    const compiled2 = compileBrief(brief, {
+    const compileCtx = {
       brand: brandJson,
       images: core.images,
+      wordsFor: shotWordsFor(core, brandId),
       engineCaps: uncapped,
       template: brief.templateId ? sceneById(String(brief.templateId)) : void 0,
       templateById: sceneById,
@@ -9918,7 +10290,8 @@ function buildServer(opts) {
       // Only the explicit op drops the dimension promise: an implicit legacy
       // expansion keeps its historical prompt byte for byte.
       ...opts2?.reshape === "extend" ? { editReshape: "extend" } : {}
-    });
+    };
+    const compiled2 = compileBrief(brief, compileCtx);
     let inheritedAttachments = [];
     let identityWarnings = [];
     if (inheritedTokens.length) {
@@ -9938,30 +10311,19 @@ function buildServer(opts) {
       }).map((a) => ({ ...a, inherited: true }));
     }
     const cap2 = Math.max(0, engineCaps.maxReferenceImages - 1);
-    const merged = mergeEditAttachments(compiled2.attachments, inheritedAttachments, cap2);
+    const merged = mergeEditAttachments(compiled2.seated, inheritedAttachments, cap2);
+    const prompt = compileBrief(brief, { ...compileCtx, presentAttachments: merged.kept }).prompt;
     const warnings = [...compiled2.warnings, ...identityWarnings.filter((w) => !compiled2.warnings.includes(w))];
     if (inherited.truncated)
       warnings.push("This thread is deeper than 64 steps, so identity attached before that could not be carried.");
-    if (merged.dropped.length) {
-      if (engineCaps.maxReferenceImages <= 1) {
-        warnings.push(
-          `${engineCaps.displayName} cannot carry reference images, so the identity rides on the source frame alone.`
-        );
-      } else {
-        const keptLabels = new Set(merged.kept.map((a) => a.label));
-        const names = [...new Set(merged.dropped.map((d) => d.label))].filter((l) => !keptLabels.has(l));
-        if (names.length)
-          warnings.push(
-            `${engineCaps.displayName} reads ${engineCaps.maxReferenceImages} reference images and the frame being refined keeps one, so ${names.join(
-              " and "
-            )} ${names.length === 1 ? "was" : "were"} left out.`
-          );
-      }
-    }
+    if (merged.dropped.length && engineCaps.maxReferenceImages <= 1)
+      warnings.push(`The identity rides on the shot itself \u2014 ${engineCaps.displayName} reads no other images.`);
     return {
-      compiled: compiled2,
+      compiled: { ...compiled2, prompt },
       inheritedTokens,
       merged,
+      /** The seats this refinement had: the engine's, less the source frame. */
+      cap: cap2,
       warnings,
       editScope: verdict.scope,
       editRemoval: verdict.removal ?? false
@@ -9986,9 +10348,15 @@ function buildServer(opts) {
       return {
         ...rest2,
         attachments: edit.merged.kept,
-        dropped: edit.merged.dropped,
+        // The own compile runs uncapped, so its dropped list holds exactly the
+        // missing-photo identities; the budget losses live on the merge.
+        dropped: [...edit.compiled.dropped, ...edit.merged.dropped],
         warnings: edit.warnings,
-        referenceCount: edit.merged.kept.length
+        referenceCount: edit.merged.kept.length,
+        // How many photo groups this refine can carry in total: the engine's
+        // slots less the one the source frame holds. The composer refuses a
+        // pick past it rather than warning after the fact.
+        cap: edit.cap
       };
     }
     const brandJson = await brandJsonWithIdentityCrops(
@@ -10012,12 +10380,13 @@ function buildServer(opts) {
     const compiled2 = compileBrief(brief, {
       brand: brandJson,
       images: core.images,
+      wordsFor: shotWordsFor(core, brand.id),
       engineCaps: engine.capabilities(),
       template: brief.templateId ? sceneById(String(brief.templateId)) : void 0,
       templateById: sceneById
     });
     const { referenceImages, ...rest } = compiled2;
-    return { ...rest, referenceCount: referenceImages.length };
+    return { ...rest, referenceCount: referenceImages.length, cap: engine.capabilities().maxReferenceImages };
   });
   registerProjectRoutes(app, { core });
   registerCodexSetupRoutes(app, { codexSetup: opts.codexSetup, codexRunner: engines.codexRunner });
@@ -10141,11 +10510,11 @@ function buildServer(opts) {
     }
   }
   const NODE_TIMEOUT_MS = 6e5;
-  async function runNode(nodeId, engine, estimate, work, expect, post, timeoutMs) {
+  async function runNode(nodeIds, engine, estimate, work, expect, postFor, timeoutMs) {
     const engineId = engine?.capabilities().id ?? "local";
     reserved.set(engineId, (reserved.get(engineId) ?? 0) + estimate);
     const ctrl = new AbortController();
-    runningGenerations.set(nodeId, ctrl);
+    for (const id of nodeIds) runningGenerations.set(id, ctrl);
     const bound = opts.nodeTimeoutMs ?? timeoutMs ?? NODE_TIMEOUT_MS;
     let watchdogFired = false;
     const watchdog = setTimeout(() => {
@@ -10153,43 +10522,78 @@ function buildServer(opts) {
       ctrl.abort(BUDGET_EXHAUSTED);
     }, bound);
     const startedAt = Date.now();
-    try {
-      const result = await work(ctrl.signal);
-      clearTimeout(watchdog);
-      result.images = await normalizePngs(result.images);
-      if (post) result.images = await post(result.images);
-      if (expect) await assertAspect(result.images, expect);
+    const settled = /* @__PURE__ */ new Set();
+    const settleSlot = async (slot, hash) => {
+      const id = nodeIds[slot];
       try {
-        const sizes = [];
-        for (const h of result.images) {
-          const meta2 = await sharp20(core.images.read(h)).metadata();
-          if (meta2.width && meta2.height) sizes.push([meta2.width, meta2.height]);
+        let own = await normalizePngs([hash]);
+        const post = postFor?.(id);
+        if (post) own = await post(own);
+        if (expect) await assertAspect(own, expect);
+        try {
+          const meta2 = await sharp20(core.images.read(own[0])).metadata();
+          const node = core.store.getNode(id);
+          if (node && meta2.width && meta2.height) {
+            const brief = node.brief ?? {};
+            const asked = expect ? { requestedSize: [expect.width, expect.height] } : {};
+            core.store.setBrief(id, { ...brief, rendered: { sizes: [[meta2.width, meta2.height]], ...asked } });
+            if (node.kind === "generation" && engineId === "codex-cli" && expect && expect.width !== expect.height && meta2.width === expect.width && meta2.height === expect.height)
+              app.log.warn(
+                { nodeId: id },
+                "codex delivered exactly the requested pixels; its image tool cannot pin size - suggests a forbidden shell resize"
+              );
+          }
+        } catch {
         }
-        const node = core.store.getNode(nodeId);
-        if (node && sizes.length) {
-          const brief = node.brief ?? {};
-          const raw = result.raw;
-          const survivors = typeof raw?.requested === "number" && Array.isArray(raw.variantIndexes) ? { requested: raw.requested, variantIndexes: raw.variantIndexes } : {};
-          const asked = expect ? { requestedSize: [expect.width, expect.height] } : {};
-          core.store.setBrief(nodeId, { ...brief, rendered: { sizes, ...survivors, ...asked } });
-          if (node.kind === "generation" && engineId === "codex-cli" && expect && expect.width !== expect.height && sizes.some(([w, h]) => w === expect.width && h === expect.height))
-            app.log.warn(
-              { nodeId },
-              "codex delivered exactly the requested pixels; its image tool cannot pin size - suggests a forbidden shell resize"
-            );
+        core.store.completeNode(id, { images: own, costUsd: 0, durationMs: Date.now() - startedAt });
+      } catch (err) {
+        core.store.failNode(id, String(err?.message ?? err));
+      } finally {
+        settled.add(id);
+      }
+    };
+    const landing = /* @__PURE__ */ new Map();
+    let accepting = true;
+    const onImage = (slot, hash) => {
+      if (!accepting || !Number.isInteger(slot) || slot < 0 || slot >= nodeIds.length || landing.has(slot)) return;
+      landing.set(slot, settleSlot(slot, hash));
+    };
+    try {
+      const result = await work(ctrl.signal, onImage);
+      accepting = false;
+      clearTimeout(watchdog);
+      await Promise.allSettled(landing.values());
+      const raw = result.raw;
+      const bySlot = new Array(nodeIds.length);
+      result.images.forEach((h, k) => {
+        const slot = raw?.variantIndexes?.[k] ?? k;
+        if (slot < nodeIds.length && bySlot[slot] === void 0) bySlot[slot] = h;
+      });
+      const failures = [...raw?.partialFailures ?? []];
+      for (let slot = 0; slot < nodeIds.length; slot++) {
+        if (landing.has(slot)) continue;
+        const hash = bySlot[slot];
+        if (hash === void 0) {
+          core.store.failNode(nodeIds[slot], failures.shift() ?? "the engine returned no image for this shot");
+          settled.add(nodeIds[slot]);
+          continue;
         }
-      } catch {
+        await settleSlot(slot, hash);
       }
-      core.store.completeNode(nodeId, { ...result, durationMs: Date.now() - startedAt });
-      core.ledger.recordCost(engineId, nodeId, result.costUsd);
+      core.store.chargeNode(nodeIds[0], result.costUsd);
+      core.ledger.recordCost(engineId, nodeIds[0], result.costUsd);
     } catch (err) {
-      if (watchdogFired)
-        core.store.failNode(nodeId, `generation timed out after ${Math.round(bound / 6e4)} minutes`);
-      else if (ctrl.signal.aborted) core.store.cancelNode(nodeId);
-      else core.store.failNode(nodeId, String(err?.message ?? err));
+      accepting = false;
+      await Promise.allSettled(landing.values());
+      for (const id of nodeIds) {
+        if (settled.has(id)) continue;
+        if (watchdogFired) core.store.failNode(id, `generation timed out after ${Math.round(bound / 6e4)} minutes`);
+        else if (ctrl.signal.aborted) core.store.cancelNode(id);
+        else core.store.failNode(id, String(err?.message ?? err));
+      }
     } finally {
       clearTimeout(watchdog);
-      runningGenerations.delete(nodeId);
+      for (const id of nodeIds) runningGenerations.delete(id);
       const left = (reserved.get(engineId) ?? 0) - estimate;
       if (left > 1e-9) reserved.set(engineId, left);
       else reserved.delete(engineId);
@@ -10238,7 +10642,7 @@ function buildServer(opts) {
         images: [core.images.save(await sharp20(args.srcBuf).extract(window).png().toBuffer())],
         costUsd: 0
       });
-      void runNode(node2.id, null, 0, work2, { width: plan2.width, height: plan2.height }).catch(
+      void runNode([node2.id], null, 0, work2, { width: plan2.width, height: plan2.height }).catch(
         (err) => app.log.error({ err }, "crop run failed")
       );
       return reply.status(202).send(args.note ? { ...node2, warnings: [args.note] } : node2);
@@ -10332,6 +10736,7 @@ function buildServer(opts) {
         compiled2 = compileBrief(brief, {
           brand: brandJson,
           images: core.images,
+          wordsFor: shotWordsFor(core, project.brandId),
           engineCaps: engine.capabilities(),
           template: brief.templateId ? sceneById(String(brief.templateId)) : void 0,
           templateById: sceneById
@@ -10369,6 +10774,7 @@ function buildServer(opts) {
       compiled2 = compileBrief(legacyBrief, {
         brand: brandJson,
         images: core.images,
+        wordsFor: shotWordsFor(core, project.brandId),
         engineCaps: engine.capabilities(),
         templateById: sceneFor(brandJson)
       });
@@ -10393,8 +10799,17 @@ function buildServer(opts) {
     if (kind === "generation") {
       const cap2 = engine.capabilities().maxReferenceImages;
       const wantedCount = Math.min(Math.max(1, Number(count)), 8);
-      const lostIdentity = engine.capabilities().placeholder ? [] : (compiled2?.dropped ?? []).filter((d) => d.essential);
+      const blind = engine.capabilities().maxReferenceImages === 0;
+      const lostIdentity = engine.capabilities().placeholder ? [] : (compiled2?.dropped ?? []).filter((d) => d.essential && (d.reason === "missing" || blind));
       if (lostIdentity.length) {
+        const missing = lostIdentity.filter((d) => d.reason === "missing");
+        if (missing.length) {
+          const names2 = joinNames(missing.map((d) => d.label));
+          const kindWord2 = missing[0].role === "product" ? "product" : "presenter";
+          return reply.code(400).send({
+            error: `${names2} ${missing.length === 1 ? "has" : "have"} no usable photo, so the result would not be your ${kindWord2}. Re-add ${missing.length === 1 ? "its" : "their"} photo, or remove ${names2} from the brief.`
+          });
+        }
         const names = joinNames(lostIdentity.map((d) => d.label));
         const kindWord = lostIdentity[0].role === "product" ? "product" : "presenter";
         return reply.code(400).send({
@@ -10405,6 +10820,19 @@ function buildServer(opts) {
       const keptRefs = referenceImages && cap2 > 0 ? referenceImages.slice(0, cap2) : void 0;
       const sentRefs = keptRefs && maxEdge ? await Promise.all(keptRefs.map((p) => capReferenceEdge(core, p, maxEdge))) : keptRefs;
       const sentRoles = referenceRoles && cap2 > 0 ? referenceRoles.slice(0, cap2) : referenceRoles ?? [];
+      if (process.env.SCENRI_DEBUG) {
+        const sent = {};
+        for (const r of sentRoles) sent[r] = (sent[r] ?? 0) + 1;
+        app.log.info(
+          {
+            engine: engine.capabilities().id,
+            cap: cap2,
+            sent,
+            dropped: (compiled2?.dropped ?? []).map((d) => `${d.role}:${d.label} (${d.reason ?? "budget"})`)
+          },
+          "reference transport"
+        );
+      }
       const briefText = Array.isArray(brief?.tokens) ? brief.tokens.filter((t) => t?.t === "text").map((t) => String(t?.v ?? "")).join(" ") : String(prompt ?? "");
       const variations = variationPlan(wantedCount, {
         hasPresenter: sentRoles.includes("character"),
@@ -10423,7 +10851,7 @@ function buildServer(opts) {
         ...variations.length ? { variations } : {}
       };
       estimate = await engine.costEstimate(genReq);
-      work = (signal) => engine.generate(genReq, signal);
+      work = (signal, onImage) => engine.generate(genReq, signal, onImage);
       expectShape = { width, height };
     } else {
       const parent = core.store.getNode(resolvedParentId);
@@ -10436,6 +10864,20 @@ function buildServer(opts) {
       const editRefs = mergedEdit ? mergedEdit.kept.map((a) => ({ path: core.images.pathFor(a.hash), role: a.role })) : (referenceImages ?? []).map((path, i) => ({ path, role: referenceRoles?.[i] })).slice(0, Math.max(0, engine.capabilities().maxReferenceImages - 1));
       const editEdge = engine.capabilities().maxReferenceEdge;
       if (editEdge) for (const r of editRefs) r.path = await capReferenceEdge(core, r.path, editEdge);
+      if (process.env.SCENRI_DEBUG) {
+        const sent = {};
+        for (const r of editRefs) sent[String(r.role ?? "reference")] = (sent[String(r.role ?? "reference")] ?? 0) + 1;
+        app.log.info(
+          {
+            engine: engine.capabilities().id,
+            cap: Math.max(0, engine.capabilities().maxReferenceImages - 1),
+            sourceFrame: true,
+            sent,
+            dropped: (mergedEdit?.dropped ?? []).map((d) => `${d.role}:${d.label} (${d.reason ?? "budget"})`)
+          },
+          "reference transport"
+        );
+      }
       const srcBuf = core.images.read(String(srcHash));
       const srcMeta = await sharp20(srcBuf).metadata();
       if (srcMeta.width && srcMeta.height) expectShape = { width: srcMeta.width, height: srcMeta.height };
@@ -10511,8 +10953,9 @@ function buildServer(opts) {
         expectShape = { width: expandPlan.width, height: expandPlan.height };
       }
       const editPixelBudget = runEngine.capabilities().editPixelBudget;
-      if (!expandPlan && editPixelBudget && srcMeta.width && srcMeta.height && srcMeta.width * srcMeta.height > editPixelBudget) {
-        sentSize = budgetSize(srcMeta.width, srcMeta.height, editPixelBudget);
+      const stepped = !expandPlan && editPixelBudget && srcMeta.width && srcMeta.height && srcMeta.width * srcMeta.height > editPixelBudget ? budgetSize(srcMeta.width, srcMeta.height, editPixelBudget) : null;
+      if (editPixelBudget && stepped && (stepped.width !== srcMeta.width || stepped.height !== srcMeta.height)) {
+        sentSize = stepped;
         budgetSourceHash = core.images.save(
           await sharp20(srcBuf).resize(sentSize.width, sentSize.height, { fit: "fill", kernel: "lanczos3" }).png().toBuffer()
         );
@@ -10603,15 +11046,26 @@ function buildServer(opts) {
     }
     const billedId = runEngine.capabilities().id;
     core.ledger.assertUnderCap(billedId, estimate + (reserved.get(billedId) ?? 0));
-    const node = core.store.addNode({
+    const nodes = kind === "generation" ? core.store.addNodes({
       projectId: project.id,
       parentId: resolvedParentId,
       kind,
       prompt: finalPrompt,
-      engineId: billedId
-    });
-    if (brief)
-      core.store.setBrief(node.id, {
+      engineId: billedId,
+      // the same clamp the engine request and the watchdog use
+      count: Math.min(Math.max(1, Number(count)), 8)
+    }) : [
+      core.store.addNode({
+        projectId: project.id,
+        parentId: resolvedParentId,
+        kind,
+        prompt: finalPrompt,
+        engineId: billedId
+      })
+    ];
+    const node = nodes[0];
+    for (const sibling of brief ? nodes : [])
+      core.store.setBrief(sibling.id, {
         ...briefInputsOnly(brief),
         ...editedFrom ? { sourceImage: editedFrom } : {},
         ...kind === "edit" && reshape ? { reshape } : {},
@@ -10636,7 +11090,7 @@ function buildServer(opts) {
           }
         } : {},
         // What the refinement carried, recorded apart from what it asked for:
-        // the detail view shows both, and remix reads tokens alone.
+        // the detail view shows both, and reuse setup merges both (mergeCarried).
         ...kind === "edit" && inheritedTokens.length ? { inherited: inheritedTokens } : {}
       });
     const plan = expandPlan;
@@ -10758,14 +11212,23 @@ function buildServer(opts) {
         staged = await conformToCanvas(node.id, expectShape)(staged);
       }
       return enforceEditCanvas(staged);
-    } : kind === "generation" && compiled2?.width && compiled2?.height ? conformToCanvas(node.id, { width: compiled2.width, height: compiled2.height }) : void 0;
+    } : void 0;
+    const genW = compiled2?.width;
+    const genH = compiled2?.height;
+    const postFor = post !== void 0 ? () => post : kind === "generation" && genW && genH ? (id) => conformToCanvas(id, { width: genW, height: genH }) : void 0;
     const runCaps = runEngine.capabilities();
     const nodeBudgetMs = kind === "generation" && runCaps.perImageTimeoutMs ? Math.ceil(Math.min(Math.max(1, Number(count)), 8) / Math.max(1, runCaps.imageConcurrency ?? 1)) * runCaps.perImageTimeoutMs + 6e4 : void 0;
-    void runNode(node.id, runEngine, estimate, work, expectShape, post, nodeBudgetMs).catch(
-      (err) => app.log.error({ err }, "node run failed")
-    );
+    void runNode(
+      nodes.map((n) => n.id),
+      runEngine,
+      estimate,
+      work,
+      expectShape,
+      postFor,
+      nodeBudgetMs
+    ).catch((err) => app.log.error({ err }, "node run failed"));
     const allWarnings = [...compiled2?.warnings ?? [], ...extraWarnings];
-    return reply.status(202).send(allWarnings.length ? { ...node, warnings: allWarnings } : node);
+    return reply.status(202).send({ ...node, siblings: nodes, ...allWarnings.length ? { warnings: allWarnings } : {} });
   });
   app.post("/api/nodes/:id/cancel", async (req, reply) => {
     const id = req.params.id;
@@ -10838,7 +11301,10 @@ function buildServer(opts) {
     runtime,
     stageImpl: opts.stageImpl,
     exitImpl: opts.exitImpl,
-    busyCount: () => runningGenerations.size + runningImportCount() + runningAssetBuildCount()
+    // one physical run counts once, however many sibling nodes share its
+    // controller — an update gate held open by a 4-shot batch is still held
+    // open by exactly one piece of work
+    busyCount: () => new Set(runningGenerations.values()).size + runningImportCount() + runningAssetBuildCount()
   });
   let drained = null;
   app.decorate("drain", () => {
@@ -10907,7 +11373,7 @@ async function serve() {
 }
 async function run() {
   const core = createCore();
-  const stubs = process.env.SCENRI_DEMO_ENGINE === "1" ? [createDemoEngine((b) => core.images.save(b))] : [];
+  const stubs = process.env.SCENRI_DEMO_ENGINE === "1" ? [createDemoEngine((b) => core.images.save(b), demoOptionsFromEnv(process.env))] : [];
   const engines = createEngineRegistry(core, stubs);
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [join(here, "..", "..", "..", "apps", "studio", "dist"), join(here, "..", "studio-dist")];