slidemind 0.3.20 → 0.4.1

package/src/bridge/bundle.mjs

@@ -39,6 +39,11 @@
 //   ├── lint-engine.mjs           (wire.lintEngine.source — the add-in's slide-lint engine)
 //   ├── primitives.json           (wire.lintEngine.primitives — closed component registry)
 //   └── bundle.json               ({ presFP, name, version, etag, lintEngineVersion, tokenRoleMap, … })
+//
+// A deck REFERENCES this directory; it never carries a copy. The HTML preview
+// points at these paths by absolute file: URL, the review server serves them
+// from here, and the server render resolves brand assets from the design
+// itself — so re-materializing a bundle changes no file inside any deck.
 
 import fs from "node:fs";
 import os from "node:os";
@@ -53,14 +58,49 @@ import {
   listBrands,
 } from "./client.mjs";
 import { updateCliInstruction } from "../install-channel.mjs";
+import { statePath } from "../lib/deck-paths.mjs";
 
 // Highest bundle wire-contract version this CLI understands. The add-in stamps
 // `schemaVersion` on every bundle; a higher value means the CLI is too old.
 const CLI_MAX_BUNDLE_SCHEMA = 1;
 
+// The bundle cache normally lives under the user's cache dir. Agent sandboxes
+// (codex `workspace-write`, probed 2026-09-19: ~/.cache and ~/.config are
+// DENIED, the cwd is allowed) refuse writes there, and a session that cannot
+// materialize the bundle cannot author at all — two sim sessions "fixed" this
+// by rewriting the harness wrapper. So when the preferred root is not
+// writable, the cache falls back to `<cwd>/.slidemind-cache/bundles`, which
+// every sandbox allows. A cache is a cache: a second copy costs a download.
+// ponytail: probed once per process; a root that turns unwritable mid-run
+// fails the write like before.
+// Memo keyed by the preferred root: tests (and users) switch XDG_CACHE_HOME
+// within one process.
+const cacheRootMemo = new Map();
 export function bundleCacheRoot() {
   const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
-  return path.join(base, "slidemind", "bundles");
+  const preferred = path.join(base, "slidemind", "bundles");
+  if (cacheRootMemo.has(preferred)) return cacheRootMemo.get(preferred);
+  cacheRootMemo.set(preferred, preferred);
+  try {
+    fs.mkdirSync(preferred, { recursive: true });
+    const probe = path.join(preferred, `.probe.${process.pid}`);
+    fs.writeFileSync(probe, "");
+    fs.rmSync(probe, { force: true });
+  } catch (err) {
+    if (err?.code !== "EPERM" && err?.code !== "EACCES" && err?.code !== "EROFS") return preferred;
+    const fallback = path.join(process.cwd(), ".slidemind-cache", "bundles");
+    // Say it once per fallback dir, not once per command: an agent session
+    // runs sixty commands and read this banner 53 times (x30 audit).
+    const said = !fs.existsSync(fallback);
+    fs.mkdirSync(fallback, { recursive: true });
+    if (said) {
+      process.stderr.write(
+        `slidemind: bundle cache ${preferred} is not writable here (${err.code}) — using ${fallback} for this session\n`,
+      );
+    }
+    cacheRootMemo.set(preferred, fallback);
+  }
+  return cacheRootMemo.get(preferred);
 }
 
 function sanitizeKey(value) {
@@ -141,6 +181,21 @@ export function clearBundleCache() {
 // add-in's self-signed dev certificate on loopback hosts (the same posture the
 // bridge client uses). Azure blob SAS URLs are public HTTPS and need no special
 // handling beyond a normal GET.
+// Every file in the cache lands via tmp + rename. The cache is shared by every
+// concurrent slidemind process on the machine, and each deck command re-syncs
+// it (refreshDeckBundle) — a plain writeFileSync truncates first, so a sibling
+// process dynamic-importing lint-engine.mjs / capture-engine.mjs at that instant
+// saw an empty module ("Cached lint engine is corrupt", "predates the lint
+// engine"; four hits in one 4-session sim batch, 2026-09-18). rename is atomic
+// on the same filesystem, so a reader sees the old bytes or the new, never half.
+const TMP_SUFFIX_RE = /\.\d+\.sm-tmp$/;
+export function writeFileAtomic(target, data, encoding) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.sm-tmp`;
+  fs.writeFileSync(tmp, data, encoding);
+  fs.renameSync(tmp, target);
+}
+
 function getBuffer(url, { redirects = 4 } = {}) {
   return new Promise((resolve, reject) => {
     let u;
@@ -187,8 +242,7 @@ function getBuffer(url, { redirects = 4 } = {}) {
 
 async function downloadInto(targetPath, url) {
   const buf = await getBuffer(url);
-  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-  fs.writeFileSync(targetPath, buf);
+  writeFileAtomic(targetPath, buf);
 }
 
 const REUSABLE_KIND_ORDER = [
@@ -309,9 +363,7 @@ export async function materializeBundle(
   // Everything this sync owns, as dir-relative paths; drives the prune pass.
   const expected = new Set(["bundle.json"]);
   const writeText = (rel, text) => {
-    const target = path.join(dir, rel);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, text, "utf8");
+    writeFileAtomic(path.join(dir, rel), text, "utf8");
     expected.add(rel);
   };
 
@@ -423,8 +475,10 @@ export async function materializeBundle(
   // vision pass lifted from the brand's own master and flagged `reusable`).
   // Each carries a `workspacePath` (e.g. `assets/master-<sha8>.<ext>`) that the
   // add-in's design persona references from slide JSX as `<img src="./assets/
-  // <file>">`; land them at that exact path so copyDesignSystem ships them into
-  // the deck next to the role-keyed brand assets. Content-addressed name →
+  // <file>">`; land them at that exact path inside the BUNDLE, next to the
+  // role-keyed brand assets — the preview rewrites such a reference to this
+  // directory and the render resolves it server-side, so no deck carries a
+  // copy. Content-addressed name →
   // write-once (a changed image gets a new sha8 path; the old one prunes out).
   // The catalogue of these (name/kind/description) rides in design.md's
   // `### Brand Reusable Images` block, so the local agent sees both halves.
@@ -447,7 +501,7 @@ export async function materializeBundle(
   // HTML builder rewrites to `./assets/…`, so the local preview shows real brand
   // chrome instead of bare layouts. Each carries a `workspacePath`
   // (`assets/chrome-<componentName>.<ext>`); land it next to the other assets so
-  // copyDesignSystem ships it into the deck. Etag-keyed → re-fetch only on change.
+  // the preview reads it from here. Etag-keyed → re-fetch only on change.
   for (const chrome of wire.layoutBackgrounds ?? []) {
     if (!chrome?.url || typeof chrome.workspacePath !== "string") continue;
     const rel = path.join("assets", path.basename(chrome.workspacePath));
@@ -538,7 +592,7 @@ export async function materializeBundle(
     fetchedAt: new Date().toISOString(),
     incompleteAssets: warnings.length > 0,
   };
-  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), "utf8");
+  writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), "utf8");
 
   // Last, after every write AND the prune — the overlay must win over the wire.
   const overlaid = applyBundleOverlay(dir);
@@ -571,27 +625,29 @@ export function applyBundleOverlay(dir) {
   let copied = 0;
   try {
     if (!fs.statSync(overlay).isDirectory()) return 0;
-    fs.cpSync(overlay, dir, {
-      recursive: true,
-      force: true,
-      // Docs only (.md/.css): the bundle dir also holds lint-engine.mjs and
-      // capture-engine.mjs, which the CLI dynamic-imports — an overlay must
-      // never be able to swap executable code, and text files re-sync from the
-      // wire on every materialize so a doc overlay can't persist past the
-      // experiment (binaries would).
-      filter: (src) => {
+    // Docs only (.md/.css): the bundle dir also holds lint-engine.mjs and
+    // capture-engine.mjs, which the CLI dynamic-imports — an overlay must
+    // never be able to swap executable code, and text files re-sync from the
+    // wire on every materialize so a doc overlay can't persist past the
+    // experiment (binaries would). Copied atomically like every other cache
+    // write: a sibling session reading create.md mid-copy must not get half.
+    const walk = (rel) => {
+      for (const entry of fs.readdirSync(path.join(overlay, rel), { withFileTypes: true })) {
+        const childRel = path.join(rel, entry.name);
         let st;
         try {
-          st = fs.lstatSync(src);
+          st = fs.statSync(path.join(overlay, childRel));
         } catch {
-          return false; // dangling symlink — skip, never fail the materialize
+          continue; // dangling symlink — skip, never fail the materialize
         }
-        if (st.isDirectory()) return true;
-        if (!/\.(md|css)$/i.test(src)) return false;
-        copied += 1;
-        return true;
-      },
-    });
+        if (st.isDirectory()) walk(childRel);
+        else if (/\.(md|css)$/i.test(entry.name)) {
+          writeFileAtomic(path.join(dir, childRel), fs.readFileSync(path.join(overlay, childRel)));
+          copied += 1;
+        }
+      }
+    };
+    walk("");
   } catch (err) {
     // The overlay is an experiment convenience — a bad overlay must not break
     // ready/build/push after an otherwise successful sync.
@@ -615,6 +671,16 @@ function pruneUnexpected(dir, expected) {
         if (fs.readdirSync(path.join(dir, childRel)).length === 0) {
           fs.rmdirSync(path.join(dir, childRel));
         }
+      } else if (TMP_SUFFIX_RE.test(entry.name)) {
+        // A sibling process's in-flight write — leave it, or its rename fails.
+        // One that outlived its process (a crash mid-write) is swept after 60s.
+        let stale = false;
+        try {
+          stale = Date.now() - fs.statSync(path.join(dir, childRel)).mtimeMs > 60_000;
+        } catch {
+          continue; // renamed away between readdir and stat — the happy path
+        }
+        if (stale) fs.rmSync(path.join(dir, childRel), { force: true });
       } else if (!expected.has(childRel)) {
         fs.rmSync(path.join(dir, childRel), { force: true });
         pruned += 1;
@@ -629,13 +695,14 @@ function pruneUnexpected(dir, expected) {
 // against — lets `render-pptx` pass the etag for skew detection, and lets the
 // local HTML/editor resolve the right materialized bundle.
 export function deckBundleRefPath(deckDir) {
-  return path.join(deckDir, ".bundle-ref.json");
+  return statePath(deckDir, "bundle-ref.json");
 }
 
 export function writeDeckBundleRef(deckDir, { presFP, etag }) {
   fs.mkdirSync(deckDir, { recursive: true });
-  fs.writeFileSync(
-    deckBundleRefPath(deckDir),
+  const file = deckBundleRefPath(deckDir);
+  writeFileAtomic(
+    file,
     JSON.stringify(
       { presFP, etag: etag ?? null, updatedAt: new Date().toISOString() },
       null,
@@ -801,7 +868,9 @@ const IMAGE_ENGINE_KIND_RE = /^(image|icon|photo|illustration|vector)$/i;
 // True when an engine produces insertable image bytes. Gates on the engine's
 // real modality — `kind` for bundle engines.json entries, `subtype` for live
 // `GET /api/cli/engines` catalog entries — NOT a guess over its
-// label/description.
+// label/description. Which of those image engines serves an icon and which a
+// photo IS read from label and description (asset-fetch.mjs selectAssetEngine),
+// since the catalog's subtype is "image" for both.
 export function isImageEngine(engine) {
   return IMAGE_ENGINE_KIND_RE.test(engine?.kind ?? engine?.subtype ?? "");
 }

package/src/bridge/capture.mjs

@@ -15,12 +15,19 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { convertedHostLayouts, loadConversions } from "../lib/conversions.mjs";
+import { deckSlug } from "../lib/deck-paths.mjs";
+import { selectSlideFiles } from "../lib/slide-selection.mjs";
 
 // Same launch profile as the add-in's chrome-launcher.ts, so the client browser
 // behaves identically to the server's during capture.
 const LAUNCH_ARGS = [
   "--no-sandbox",
   "--disable-gpu",
+  // Headless Chrome ties its frames to the display's vsync: with the Mac's
+  // display asleep, requestAnimationFrame and screenshots never fire and every
+  // render hangs at 0% CPU (the add-in's chrome-launcher carries the same pair).
+  "--disable-gpu-vsync",
+  "--disable-frame-rate-limit",
   "--hide-scrollbars",
   "--disable-features=AppShimRemoteCocoa,AppShimNewCloseBehavior,WebAppSystemMediaControls",
   "--disable-default-apps",
@@ -54,11 +61,10 @@ function readBundleMeta(bundleDir) {
   }
 }
 
-function readJsxDir(dir) {
+function readJsxDir(dir, only = null) {
   const out = {};
   if (!fs.existsSync(dir)) return out;
-  for (const name of fs.readdirSync(dir)) {
-    if (!name.endsWith(".jsx")) continue;
+  for (const name of selectSlideFiles(fs.readdirSync(dir).filter(name => name.endsWith(".jsx")), only)) {
     out[name] = fs.readFileSync(path.join(dir, name), "utf8");
   }
   return out;
@@ -85,10 +91,10 @@ function readAssetsAsBase64(dir, out, prefix = "") {
 // Build the in-memory workspace the capture engine renders: the deck's slides +
 // the materialized bundle's layouts / css / assets / fonts / primitives.
 // Exported for tests (pure: filesystem in, plain JSON out).
-export function buildCaptureInput(deckDir, bundleDir) {
+export function buildCaptureInput(deckDir, bundleDir, { only = null } = {}) {
   const meta = readBundleMeta(bundleDir);
 
-  const slides = readJsxDir(path.join(deckDir, "slides"));
+  const slides = readJsxDir(path.join(deckDir, "slides"), only);
   const layouts = readJsxDir(path.join(bundleDir, "layouts"));
   // Converted slides (`slidemind adopt`) invoke a ConvertedHost layout the
   // server mints per source canvas — no bundle carries it, so without a
@@ -151,7 +157,7 @@ export function buildCaptureInput(deckDir, bundleDir) {
     assets,
     fonts,
     primitives,
-    deckName: path.basename(deckDir),
+    deckName: deckSlug(deckDir),
   };
 }
 
@@ -243,16 +249,7 @@ export async function captureDeckLocally({ deckDir, bundleDir, onProgress, only
     );
   }
 
-  const input = buildCaptureInput(deckDir, bundleDir);
-  // `only`: capture a subset of the authored slides (a per-slide builder
-  // re-checking its own file) — the engine renders each slide on its own, so
-  // dropping the others from the input is exact, not an approximation.
-  if (Array.isArray(only) && only.length > 0) {
-    const keep = new Set(only);
-    for (const name of Object.keys(input.slides)) {
-      if (!keep.has(name)) delete input.slides[name];
-    }
-  }
+  const input = buildCaptureInput(deckDir, bundleDir, { only });
   return withBrowser((browser) => engine.captureDeck(browser, input, { onProgress }));
 }
 
@@ -289,7 +286,7 @@ export async function loadConnectorPreview(bundleDir) {
 
 /**
  * The measured draft checks (`draftChecks: { fill, typeScale, typeScaleTokens,
- * overlap }`) exported from the same artifact — the rules the add-in's own
+ * overlap, escape, chrome, wordFit, splitText, splitTextAdvice }`) exported from the same artifact — the rules the add-in's own
  * see_draft runs. view-draft calls them on its local capture so both harnesses
  * teach one contract. The CLI ships no draft-check rule of its own; null when
  * the bundle has no engine or the engine predates the export.

package/src/bridge/client/brands.mjs

@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { deriveEnvLabel } from "../config.mjs";
 import { resolveBackendForPres } from "./presentations.mjs";
-import { listTimeoutMs, engineTimeoutMs, withTransientRetry, sessionsInScope, sessionForBackend, bridgeFetch, backendCapabilities, backendSupportsBrandRoutes, backendSupportsConceptImages, backendSupportsImageGeneration, backendSupportsBrandsList, graphHeaders } from "./transport.mjs";
+import { listTimeoutMs, engineTimeoutMs, withTransientRetry, sessionsInScope, sessionForBackend, bridgeFetch, backendCapabilities, backendSupportsBrandRoutes, backendSupportsConceptImages, backendSupportsConceptSpecs, backendSupportsConceptSpecJobs, backendSupportsImageGeneration, backendSupportsBrandsList, assertImageIntentSupported, graphHeaders } from "./transport.mjs";
 
 // GET the full design bundle (tokens, css, layouts, designRules, signed asset
 // URLs, engines) for the presentation's active corporate design.
@@ -93,9 +93,11 @@ export async function getDesignBundleForBrandAnyBackend(brandId) {
 export async function listBrands() {
   const out = [];
   for (const s of sessionsInScope()) {
-    if (!(await backendSupportsBrandsList(s.backendURL))) continue;
     const env = deriveEnvLabel(s.backendURL);
     try {
+      // Inside the try: a probe that got no answer is "that environment
+      // contributes none" like any other failure, not a crash of the listing.
+      if (!(await backendSupportsBrandsList(s.backendURL))) continue;
       const res = await bridgeFetch(
         "/api/cli/brands",
         { timeoutMs: listTimeoutMs() },
@@ -136,9 +138,12 @@ export function conceptTimeoutMs() {
 
 export async function postConceptImages(
   brandId,
-  { planMarkdown, slideNumbers, references, force },
+  { planMarkdown, slideNumbers, force, imageIntent = null },
   backendURL,
 ) {
+  // An envelope the add-in would ignore is worse than no envelope: it would
+  // generate against the wrong picture and say nothing. Probe, then send.
+  if (imageIntent) await assertImageIntentSupported(backendURL);
   const body = { planMarkdown };
   // `--force`: the server keeps a per-plan mockup cache; an unchanged plan
   // would otherwise hand back last time's images no matter what changed
@@ -147,12 +152,10 @@ export async function postConceptImages(
   if (Array.isArray(slideNumbers) && slideNumbers.length > 0) {
     body.slideNumbers = slideNumbers;
   }
-  // The user's own images, inline: `{ role: "concept" | "style", image:
-  // <data URI>, slides?: number[], name? }`. A concept replaces the generated
-  // mockup for its slides; a style reference leads the generation.
-  if (Array.isArray(references) && references.length > 0) {
-    body.references = references;
-  }
+  // The deck's approved image obligations, with the sources inline
+  // (src/bridge/image-intent-envelope.mjs). Omitted entirely when the deck has
+  // none — which is what keeps every existing request byte-identical.
+  if (imageIntent) body.imageIntent = imageIntent;
   const res = await bridgeFetch(
     `/api/cli/brands/${encodeURIComponent(brandId)}/concept-images`,
     {
@@ -170,9 +173,10 @@ export async function postConceptImages(
 }
 
 // Generate concept mockup images for a brand over the pane-free brand route.
-// Body `{ planMarkdown, slideNumbers?, references? }`; the optional `slideNumbers`
+// Body `{ planMarkdown, slideNumbers?, imageIntent? }`; the optional `slideNumbers`
 // filters which storyboard beats are rendered (the CLI batches per-slide);
-// `references` carries the user's own concept/style images inline. Returns the
+// `imageIntent` carries the user's own images inline with their approved uses.
+// Returns the
 // server's `{ ok, images, slideCount }` augmented with the resolved
 // `backendURL`. When `backendURL` is given it posts directly; otherwise it
 // fans out — like getDesignBundleForBrandAnyBackend, presFP/brandId is globally
@@ -184,9 +188,9 @@ export async function generateConceptImagesForBrand(
   {
     planMarkdown,
     slideNumbers = null,
-    references = null,
     backendURL = null,
     force = false,
+    imageIntent = null,
   } = {},
 ) {
   if (!brandId) {
@@ -198,7 +202,7 @@ export async function generateConceptImagesForBrand(
   if (backendURL) {
     return postConceptImages(
       brandId,
-      { planMarkdown, slideNumbers, references, force },
+      { planMarkdown, slideNumbers, force, imageIntent },
       backendURL,
     );
   }
@@ -215,7 +219,7 @@ export async function generateConceptImagesForBrand(
       }
       return await postConceptImages(
         brandId,
-        { planMarkdown, slideNumbers, references, force },
+        { planMarkdown, slideNumbers, force, imageIntent },
         s.backendURL,
       );
     } catch (err) {
@@ -241,18 +245,32 @@ export async function generateConceptImagesForBrand(
 // null when several environments qualify (developer machines only; each request
 // then fans out as before). Throws the typed `concept_route_unavailable` when
 // none does, so the caller degrades to "continue without".
+//
+// An environment whose probe got no answer is passed over, not fatal: it cannot
+// generate right now whatever it would have said, and the request names the
+// deck's design, so an environment that does not serve it refuses instead of
+// drawing the wrong one. Only when NO environment answered with the route is
+// that unanswered probe the result — `capability_unknown`, retryable, never
+// "no concept route" (2026-10-11: a stopped `local` session aborted every
+// `concepts` run before the deck's own `dev` was asked).
 export async function resolveConceptBackend() {
   const sessions = sessionsInScope();
   const capable = [];
   const failures = [];
+  const unanswered = [];
   for (const s of sessions) {
-    if (await backendSupportsConceptImages(s.backendURL)) {
-      capable.push(s.backendURL);
-    } else {
-      failures.push(`${deriveEnvLabel(s.backendURL)}: no concept-images route`);
+    try {
+      if (await backendSupportsConceptImages(s.backendURL)) {
+        capable.push(s.backendURL);
+      } else {
+        failures.push(`${deriveEnvLabel(s.backendURL)}: no concept-images route`);
+      }
+    } catch (err) {
+      unanswered.push(err);
     }
   }
   if (capable.length === 0) {
+    if (unanswered.length) throw unanswered[0];
     const detail = failures.join("; ");
     const err = new Error(
       "no paired backend generates concept mockups" +
@@ -264,8 +282,129 @@ export async function resolveConceptBackend() {
   return capable.length === 1 ? capable[0] : null;
 }
 
+// Extract concept specs for a brand over the pane-free brand route. Body
+// `{ slides: [{ slide, image, storyboard? }], slot: { w, h } }` → the server's
+// `{ ok, specs: [{ slide, spec }], failures }`. Returns null when the backend
+// predates the route, so `slidemind concepts` degrades to PNGs only.
+export async function extractConceptSpecsForBrand(
+  brandId,
+  { slides, slot, backendURL, palette = null, onProgress = null, onSpec = null,
+    imageIntent = null,
+    schemaFormat = process.env.SLIDEMIND_SPEC_SCHEMA || "compact-v1" },
+) {
+  if (!brandId) throw new Error("extractConceptSpecsForBrand: brandId is required");
+  if (!backendURL) throw new Error("extractConceptSpecsForBrand: backendURL is required");
+  if (!["legacy", "compact-v1"].includes(schemaFormat)) throw new Error(`Unknown spec schema: ${schemaFormat}`);
+  const schemaOption = { schemaFormat };
+  const checkSchema = (entry) => {
+    if (schemaFormat === "compact-v1" && entry?.spec?.schemaFormat !== schemaFormat) {
+      throw new Error("Backend did not return compact-v1 specs; update the add-in backend, or explicitly select SLIDEMIND_SPEC_SCHEMA=legacy for compatibility.");
+    }
+  };
+  // Same gate as the concept call: extraction that drops the envelope would
+  // inventory the mockup's approximation of the user's picture and record it as
+  // the slide's elements. Refuse before the request, never degrade.
+  if (imageIntent) await assertImageIntentSupported(backendURL);
+  if (!(await backendSupportsConceptSpecs(backendURL))) return null;
+  // The same envelope the concept call carried, so extraction sees the sources
+  // the mockup was made from. Absent for a deck with no image uses, and both
+  // the job and the sync body below spread it in — one contract, two routes.
+  const intentOption = imageIntent ? { imageIntent } : {};
+  // The polled job when the add-in has it: one POST, then a GET every few
+  // seconds until `state: done`. A dense slide gets its eight minutes; a
+  // sync request died at the ingress's ~240 s (x27–x32: 1–2 specs per deck).
+  if (await backendSupportsConceptSpecJobs(backendURL)) {
+    const base = `/api/cli/brands/${encodeURIComponent(brandId)}/concept-spec-jobs`;
+    const created = await bridgeFetch(
+      base,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ slides, slot, ...schemaOption, ...(palette?.length ? { palette } : {}), ...intentOption }),
+        // ~7 MB of inlined mockups, and the server checks the image intent
+        // before its 202: the 8 s list timeout aborted the upload before the job
+        // existed (x69). The server takes no idempotency key to reuse one by.
+        timeoutMs: Math.max(conceptTimeoutMs(), 120_000),
+      },
+      backendURL,
+    );
+    const job = (await created.json()) ?? {};
+    if (job.jobId) {
+      const started = Date.now();
+      const deadline = started + Math.max(conceptTimeoutMs(), 20 * 60_000);
+      const delivered = new Set();
+      let lastBeat = started;
+      let lastDone = -1;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 5000));
+        let state;
+        try {
+          const res = await bridgeFetch(`${base}/${encodeURIComponent(job.jobId)}`, { timeoutMs: listTimeoutMs() }, backendURL);
+          state = (await res.json()) ?? {};
+        } catch (err) {
+          if (err?.status === 404) break; // the container restarted; the sync route below
+          continue;
+        }
+        // Each spec is handed over the moment it exists: a command the agent
+        // gives up on still leaves what was read (x33: two stalls, nothing
+        // written), and the next run asks only for the rest.
+        for (const entry of state.specs ?? []) {
+          checkSchema(entry);
+          const n = Number(entry?.slide);
+          if (delivered.has(n)) continue;
+          delivered.add(n);
+          if (typeof onSpec === "function") onSpec(entry);
+        }
+        const done = delivered.size + (state.failures?.length ?? 0);
+        // A line when the count moves, else one heartbeat every 30 s.
+        if (typeof onProgress === "function" && (done !== lastDone || Date.now() - lastBeat >= 30_000)) {
+          onProgress({ done, total: state.total ?? slides.length, elapsedMs: Date.now() - started });
+          lastBeat = Date.now();
+          lastDone = done;
+        }
+        if (state.state === "done") return { ok: true, specs: state.specs ?? [], failures: state.failures ?? [], streamed: true };
+      }
+    }
+  }
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/concept-specs`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ slides, slot, ...schemaOption, ...(palette?.length ? { palette } : {}), ...intentOption }),
+      // The server budgets 300s per slide and runs a batch in parallel; give
+      // the round trip headroom over that so a slow inventory is a server
+      // failure the response names, never a client abort.
+      timeoutMs: Math.max(conceptTimeoutMs(), 330_000),
+    },
+    backendURL,
+  );
+  const result = (await res.json()) ?? {};
+  for (const entry of result.specs ?? []) checkSchema(entry);
+  return result;
+}
+
 // gpt-image calls routinely take 60-120s; budget like the concept relay so a
 // typed server error wins over a client timeout.
+// Shorten the words of texts that do not fit their room (copy-fit.mjs), one
+// slide per call, over `/api/cli/brands/:brandId/copy-fit`: `{ items, context,
+// plan }` → `[{ id, text }]`. Null when the backend has no such route: the
+// slide keeps its words and the author shortens them.
+export async function fitCopyForBrand(brandId, { items, context = "", plan = null, backendURL }) {
+  if (!brandId || !backendURL || (await backendCapabilities(backendURL))?.copyFitV1 !== true) return null;
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/copy-fit`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ items: items.map(({ id, role, text, maxChars, keepPrefix }) => ({ id, role, text, maxChars, ...(keepPrefix ? { keepPrefix } : {}) })), context, plan }),
+      timeoutMs: 120_000,
+    },
+    backendURL,
+  );
+  return ((await res.json()) ?? {}).items ?? [];
+}
+
 export function imagenTimeoutMs() {
   return (
     parseInt(process.env.SLIDEMIND_BRIDGE_IMAGEN_TIMEOUT_MS || "200000", 10) ||