slidemind 0.1.5 → 0.1.7

package/src/bridge/build-and-push.mjs

@@ -1,12 +1,18 @@
 // Render a deck server-side via the bridge, then push the bytes into a running
-// PowerPoint window (or write them to a file).
+// PowerPoint window (or write them to a file). Also hosts `viewDraft` — the
+// push-free, .pptx-free draft preview (the CLI analog of the persona's
+// `see_draft`): it runs the shipped capture engine locally and returns the
+// per-slide preview PNGs it already produces, so the agent can look before the
+// `review` gate.
 //
 // The CLI ships ZERO exporter code: the authored slide JSX + deck-local assets
-// are POSTed to the add-in's `render-pptx` route, which renders them against
-// the presentation's own corporate design using the SAME OOXML exporter the
-// in-app design persona uses. The returned base64 .pptx is then inserted /
-// replaced (push) or written to disk (build-pptx). An open PowerPoint host with
-// an active corporate design is therefore a hard precondition for both paths.
+// are POSTed to the add-in's render routes, which render them against the
+// deck's corporate design using the SAME OOXML exporter the in-app design
+// persona uses. The returned base64 .pptx is then inserted / replaced (push)
+// or written to disk (build-pptx). A BOUND deck renders pane-free over the
+// brand routes (PowerPoint backgrounded or closed); only the INSERT half of a
+// push, and unbound decks (whose brandId must come from the pane registry),
+// still need a registered PowerPoint window.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -18,6 +24,7 @@ import {
   renderPptx,
   replaceSlides,
   requireHost,
+  requireRenderHost,
   translateDeck,
   waitForPaneReady,
 } from "./client.mjs";
@@ -89,8 +96,12 @@ function gatherDeckAssets(deckDir) {
 // ref rewritten, and the render retried once against the current design.
 export async function renderDeckToBase64(
   deckDir,
-  { presId, backendURL = null, onProgress = null },
+  { presId = null, brandId = null, backendURL = null, onProgress = null },
 ) {
+  if (!presId && !brandId) {
+    throw new Error("renderDeckToBase64: presId or brandId is required");
+  }
+  const deckName = path.basename(deckDir);
   const { slides, nativeSlides, orderWarning } = gatherSlides(deckDir);
   const hasJsx = Object.keys(slides).length > 0;
   const deckAssets = gatherDeckAssets(deckDir);
@@ -99,9 +110,10 @@ export async function renderDeckToBase64(
   // silently no-ops), the local HTML/editor preview can't resolve the deck's
   // design files, AND local capture has no engine/bundle to read. `download-
   // bundle <deck>` normally writes this; here we self-heal so `push`/`build-pptx`
-  // work even when it wasn't run explicitly.
+  // work even when it wasn't run explicitly. (The brand path implies a bound
+  // deck — its brandId came from the ref — so this only fires with a presId.)
   let ref = readDeckBundleRef(deckDir);
-  if (!ref?.etag) {
+  if (!ref?.etag && presId) {
     try {
       const mat = await materializeBundle(presId, { backendURL });
       writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
@@ -125,6 +137,7 @@ export async function renderDeckToBase64(
   // .pptx slides ride alongside on either path so the server splices them by
   // play-order filename.
   const attemptRender = async (etag) => {
+    const target = { presId, brandId, deckName, backendURL };
     if (useLocalCapture) {
       let captured;
       try {
@@ -135,13 +148,13 @@ export async function renderDeckToBase64(
             "falling back to the server render\n",
         );
         useLocalCapture = false;
-        return renderPptx({ presId, slides, deckAssets, nativeSlides, etag, backendURL, onProgress });
+        return renderPptx({ ...target, slides, deckAssets, nativeSlides, etag, onProgress });
       }
       const n = Array.isArray(captured?.slides) ? captured.slides.length : 0;
       onProgress?.({ done: n, total: n, stage: "assembling" });
-      return translateDeck({ presId, captured, nativeSlides, etag, backendURL });
+      return translateDeck({ ...target, captured, nativeSlides, etag });
     }
-    return renderPptx({ presId, slides, deckAssets, nativeSlides, etag, backendURL, onProgress });
+    return renderPptx({ ...target, slides, deckAssets, nativeSlides, etag, onProgress });
   };
 
   let result;
@@ -153,15 +166,18 @@ export async function renderDeckToBase64(
     // design truth lives in the add-in, so the right move is forward: refresh
     // the local bundle (so previews/lint/capture-engine match), re-bind the
     // deck, and render once against the CURRENT design. A second stale (CD
-    // changed again mid-flight) propagates.
+    // changed again mid-flight) propagates. The refresh rides the SAME target
+    // the render used — the brand route stays pane-free end to end.
     process.stderr.write(
       "corporate design changed since this deck was authored — refreshing the " +
         "bundle and retrying the render against the current design…\n",
     );
-    const mat = await materializeBundle(presId, {
-      backendURL,
-      preferBrandId: ref?.presFP ?? null,
-    });
+    const mat = brandId
+      ? await materializeBundle(null, { backendURL, brandId })
+      : await materializeBundle(presId, {
+          backendURL,
+          preferBrandId: ref?.presFP ?? null,
+        });
     writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
     // The bundle dir is keyed by presFP, so a refreshed capture engine landed
     // in place — re-evaluate in case it appeared (or vanished) on this sync.
@@ -177,6 +193,220 @@ export async function renderDeckToBase64(
   return result; // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
+// Map ONE captured slide to a draft-view entry. The capture engine produces a
+// `previewDataUrl` (the 1280×720 stage PNG) only for FREEFORM slides that go
+// through the Chrome box capture — purpose-built (Mode A) layouts have no
+// freeform region and so carry no preview, exactly like the add-in's see_draft.
+// Degraded renders still yield a flat raster the agent can look at; lint/parse
+// failures surface as a status line so the agent is never blind.
+function mapCapturedSlide(fileName, cap, warnings) {
+  if (!cap) {
+    return {
+      fileName,
+      status: "missing",
+      note: "the capture engine produced no result for this slide",
+    };
+  }
+  for (const w of cap.lint?.warnLines ?? []) warnings.push(`${fileName}: ${w}`);
+  for (const w of cap.render?.warnings ?? []) warnings.push(`${fileName}: ${w}`);
+
+  if (cap.previewDataUrl) {
+    return { fileName, status: "ok", dataUri: cap.previewDataUrl };
+  }
+  // A degraded render is a non-editable raster; push/build-pptx will REJECT it.
+  // Attach it anyway (so the agent isn't blind) but flag the named cause.
+  if (cap.render?.degraded && cap.render?.fallbackPngBase64) {
+    return {
+      fileName,
+      status: "degraded",
+      dataUri: `data:image/png;base64,${cap.render.fallbackPngBase64}`,
+      note:
+        `did NOT render cleanly (degraded ${cap.render.degraded} raster, not editable shapes) — ` +
+        `push/build-pptx will reject it as-is. Fix the named cause in the JSX: ` +
+        (cap.render.errorText ?? "unknown render failure"),
+    };
+  }
+  if (cap.lint?.errorMessage) {
+    return { fileName, status: "failed", note: cap.lint.errorMessage };
+  }
+  if (cap.captureError) {
+    return { fileName, status: "failed", note: cap.captureError };
+  }
+  // No preview and no error: a purpose-built (Mode A) layout has no freeform
+  // region to capture — there is simply nothing to draft-preview for it.
+  return {
+    fileName,
+    status: "no-preview",
+    note: "no preview rendered — a purpose-built layout has no freeform region to capture (use slidemind review for a full-deck look)",
+  };
+}
+
+// Render a deck's authored slides to per-slide preview PNGs WITHOUT pushing,
+// translating, or assembling a .pptx — the CLI analog of the add-in persona's
+// `see_draft`. It runs the add-in's shipped capture engine on THIS machine's
+// Chrome (the same engine the local-capture render path uses) and returns the
+// `previewDataUrl` it already produces, so the agent can LOOK at its slides and
+// self-correct before the user ever sees them at the `review` gate.
+//
+// Host-free once the bundle is materialized: the capture runs locally against
+// the cached bundle, so no open PowerPoint is needed. A host is required ONLY
+// when the bundle (and its capture engine) isn't cached yet — then we fetch it
+// like `download-bundle` does. Returns { slides: [{fileName, dataUri?, status,
+// note?}], warnings: [] }.
+export async function viewDraft(
+  deckDir,
+  { presentationId = null, onProgress = null } = {},
+) {
+  if (!deckDir) throw new Error("viewDraft: deckDir is required");
+  const slidesDir = path.join(deckDir, "slides");
+  if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
+    throw new Error(`Expected 'slides/' folder in ${deckDir}`);
+  }
+  // Authored JSX + reused native .pptx share one play-order namespace, exactly
+  // as the render path sees them — walk them in that order so the draft view
+  // lines up with the deck the user will get.
+  const all = sortSlideFilenames(
+    fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
+  );
+  if (all.length === 0) {
+    throw new Error(`No .jsx or .pptx slides under ${slidesDir}`);
+  }
+  const hasJsx = all.some((f) => f.endsWith(".jsx"));
+
+  // Resolve the materialized bundle. Local capture needs the bundle's capture
+  // engine; once it's cached this whole call is offline. Only reach for a host
+  // (to fetch the bundle) when there are JSX slides and no usable cached engine.
+  let ref = readDeckBundleRef(deckDir);
+  let bundleDir = resolveBundleDirForDeck(deckDir);
+  if (hasJsx && (!bundleDir || !bundleHasCaptureEngine(bundleDir))) {
+    const registry = await requireRenderHost();
+    const entry = pickPresentationEntry(registry, presentationId, {
+      preferBrandId: ref?.presFP ?? null,
+    });
+    const mat = await materializeBundle(entry.presId, {
+      backendURL: entry.backendURL ?? null,
+      preferBrandId: ref?.presFP ?? null,
+    });
+    writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+    bundleDir = resolveBundleDirForDeck(deckDir);
+  }
+
+  const warnings = [];
+
+  // A native-only deck (just reused .pptx) has no authored JSX to draft-preview.
+  if (!hasJsx) {
+    return {
+      slides: all.map((fileName) => ({
+        fileName,
+        status: "native",
+        note: "reused native slide — not authored JSX, no draft preview rendered",
+      })),
+      warnings,
+    };
+  }
+
+  if (!bundleDir || !bundleHasCaptureEngine(bundleDir)) {
+    throw new Error(
+      "draft preview needs the corporate design's capture engine, which ships in the " +
+        "materialized bundle. Run `slidemind download-bundle <deck>` against an open " +
+        "PowerPoint host once, then retry — or use `slidemind build <deck>` for a " +
+        "host-free HTML preview.",
+    );
+  }
+
+  let captured;
+  try {
+    captured = await captureDeckLocally({ deckDir, bundleDir, onProgress });
+  } catch (err) {
+    throw new Error(
+      `local draft capture failed (${err instanceof Error ? err.message : String(err)}). ` +
+        "It runs a local headless Chrome; if Chrome can't launch here, use " +
+        "`slidemind build <deck>` for an HTML preview instead.",
+    );
+  }
+
+  const byFile = new Map((captured?.slides ?? []).map((s) => [s.fileName, s]));
+  const slides = all.map((fileName) =>
+    fileName.endsWith(".pptx")
+      ? {
+          fileName,
+          status: "native",
+          note: "reused native slide — not authored JSX, no draft preview rendered",
+        }
+      : mapCapturedSlide(fileName, byFile.get(fileName), warnings),
+  );
+
+  return { slides, warnings };
+}
+
+// A brand-route miss is definitive for the pane-free path but NOT for the
+// deck: old add-in (no brandRoutes), legacy non-brand presFP in the ref,
+// grant/tenant miss, or a brand with no bundle — every one of these still
+// works through the pane flow, which needs no grant and re-binds the ref.
+function isBrandRouteMiss(err) {
+  return (
+    err?.code === "brand_route_unavailable" ||
+    err?.code === "unknown_brand" ||
+    err?.code === "no_active_cd" ||
+    err?.status === 404
+  );
+}
+
+// Pane-free render for a BOUND deck: sync the bundle over the brand route
+// (proves the backend + grant and refreshes the capture engine/etag exactly
+// like `ready`), re-bind, then render by brandId — no PowerPoint window
+// involved. Returns null when the brand route can't serve this deck (caller
+// falls back to the pane flow); render failures (lint, stale-after-retry)
+// propagate, they are real.
+async function tryDetachedRender(deckDir, deckRef, onProgress) {
+  const brandId = deckRef.presFP;
+  let backendURL;
+  try {
+    const mat = await materializeBundle(null, { brandId });
+    writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+    backendURL = mat.backendURL ?? null;
+    if (!backendURL) return null;
+  } catch (err) {
+    if (isBrandRouteMiss(err)) return null;
+    throw err;
+  }
+  const result = await renderDeckToBase64(deckDir, {
+    brandId,
+    backendURL,
+    onProgress,
+  });
+  return { result, backendURL };
+}
+
+async function renderWithRetarget(deckDir, entry, onProgress) {
+  const run = (target) =>
+    renderDeckToBase64(deckDir, {
+      presId: target.presId,
+      backendURL: target.backendURL ?? null,
+      onProgress,
+    });
+  try {
+    return { entry, result: await run(entry) };
+  } catch (err) {
+    const recoverable =
+      err?.status === 404 || err?.code === "unknown_presentation";
+    if (!recoverable) throw err;
+    const live = await waitForPaneReady(entry.presId, {
+      backendURL: entry.backendURL ?? null,
+      fileName: entry.fileName ?? entry.title ?? null,
+      brandId: entry.brandId ?? null,
+      timeoutMs: 15000,
+      onWait: (seconds) =>
+        process.stderr.write(
+          "render target changed — waiting for the slidemind pane to " +
+            `re-register (up to ${seconds}s)…\n`,
+        ),
+    });
+    if (!live) throw err;
+    return { entry: live, result: await run(live) };
+  }
+}
+
 export async function buildAndPush({
   deckDir,
   presentationId = null,
@@ -200,23 +430,66 @@ export async function buildAndPush({
   }
 
   const deckRef = readDeckBundleRef(deckDir);
-  const registry = await requireHost();
-  const entry = pickPresentationEntry(registry, presentationId, {
-    preferBrandId: deckRef?.presFP ?? null,
-  });
-  const presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
 
-  const result = await renderDeckToBase64(deckDir, {
-    presId,
-    backendURL,
-    onProgress,
-  });
+  // --- Render half. Pane-free for a bound deck (the window may be closed or
+  // backgrounded during the render); the pane matters only for the insert. ---
+  let result = null;
+  let renderEntry = null;
+  if (!presentationId && deckRef?.presFP) {
+    const detached = await tryDetachedRender(deckDir, deckRef, onProgress);
+    if (detached) result = detached.result;
+  }
+  if (!result) {
+    const registry = await requireRenderHost();
+    const entry = pickPresentationEntry(registry, presentationId, {
+      preferBrandId: deckRef?.presFP ?? null,
+    });
+    const rendered = await renderWithRetarget(deckDir, entry, onProgress);
+    renderEntry = rendered.entry;
+    result = rendered.result;
+  }
+
   const base64 = result.base64;
   const bytes = Buffer.byteLength(base64, "base64");
   const mode = replace ? "replace" : "insert";
   const operationId = `push-${randomUUID()}`;
 
+  // The render survived without a window; don't lose it when the insert can't
+  // find one — save the .pptx next to the deck and tell the caller (bin prints
+  // the recovery instructions).
+  const saveFallback = (presIdForResult) => {
+    const fallbackFile = path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+    fs.writeFileSync(fallbackFile, Buffer.from(base64, "base64"));
+    return {
+      presId: presIdForResult,
+      mode,
+      bytes,
+      operationId,
+      response: null,
+      warnings: result.warnings ?? [],
+      skippedSlides: result.skippedSlides ?? [],
+      paneSuspended: true,
+      fallbackFile,
+    };
+  };
+
+  // --- Insert half: needs a registered window. On the pane-free render path
+  // none was resolved yet; if none exists at all, the deck is saved instead of
+  // thrown away. ---
+  if (!renderEntry) {
+    let registry;
+    try {
+      registry = await requireHost();
+    } catch {
+      return saveFallback(null);
+    }
+    renderEntry = pickPresentationEntry(registry, presentationId, {
+      preferBrandId: deckRef?.presFP ?? null,
+    });
+  }
+  const presId = renderEntry.presId;
+  const backendURL = renderEntry.backendURL ?? null;
+
   // The SAME operationId on every attempt: the pane keeps an LRU of applied
   // operationIds and drops duplicates, so a retry after an ambiguous failure
   // can never double-insert.
@@ -242,21 +515,30 @@ export async function buildAndPush({
   try {
     resp = await doPush(presId, backendURL);
   } catch (err) {
-    // Two recoverable shapes, both meaning "nothing was delivered":
+    // Three recoverable shapes:
     //  - pane_suspended (503): the server waited ~25s for a reconnect and gave
-    //    up — the pane needs the user (foreground PowerPoint / click the pane).
+    //    up — nothing was delivered; the pane needs the user (foreground
+    //    PowerPoint / click the pane).
+    //  - pane_timeout (504): the pane looked connected but never acked within
+    //    the server's 60s window (just-frozen webview). Delivery is ambiguous,
+    //    but the retry below re-sends the SAME operationId, so the pane-side
+    //    dedup LRU makes it safe either way. The server marked the pane
+    //    suspended on the way out, so the same client-side wake wait applies.
     //  - 404: the presId vanished from the registry — a pane reconnect mints a
     //    NEW presId for the same window (presId churn).
     // Wait client-side for the pane (rematching by fileName+brandId covers the
-    // churn), then retry ONCE. A `bridge_timeout` is NOT caught: the insert
-    // may already have been delivered, and the operationId dedup only helps if
-    // we re-send — which we deliberately leave to the user for that case.
-    const recoverable = err?.code === "pane_suspended" || err?.status === 404;
+    // churn), then retry ONCE. A client-side `bridge_timeout` is NOT caught:
+    // there the server-side outcome is entirely unknown (the request may still
+    // be executing), so a re-send is deliberately left to the user.
+    const recoverable =
+      err?.code === "pane_suspended" ||
+      err?.code === "pane_timeout" ||
+      err?.status === 404;
     if (!recoverable) throw err;
     const live = await waitForPaneReady(presId, {
       backendURL,
-      fileName: entry.fileName ?? entry.title ?? null,
-      brandId: entry.brandId ?? null,
+      fileName: renderEntry.fileName ?? renderEntry.title ?? null,
+      brandId: renderEntry.brandId ?? null,
       onWait: (seconds) =>
         process.stderr.write(
           "task pane suspended — click the slidemind pane in PowerPoint to " +
@@ -264,25 +546,11 @@ export async function buildAndPush({
         ),
     });
     if (!live) {
-      if (err?.code !== "pane_suspended") throw err;
-      // The pane never woke up. Don't lose the render: save the .pptx next to
-      // the deck and tell the caller (bin prints the recovery instructions).
-      const fallbackFile = path.join(
-        deckDir,
-        `${path.basename(deckDir)}.pptx`,
-      );
-      fs.writeFileSync(fallbackFile, Buffer.from(base64, "base64"));
-      return {
-        presId,
-        mode,
-        bytes,
-        operationId,
-        response: null,
-        warnings: result.warnings ?? [],
-        skippedSlides: result.skippedSlides ?? [],
-        paneSuspended: true,
-        fallbackFile,
-      };
+      if (err?.code !== "pane_suspended" && err?.code !== "pane_timeout") {
+        throw err;
+      }
+      // The pane never woke up — same recovery as no window at all.
+      return saveFallback(presId);
     }
     livePresId = live.presId;
     resp = await doPush(live.presId, live.backendURL ?? backendURL);
@@ -298,9 +566,11 @@ export async function buildAndPush({
   };
 }
 
-// Render a deck to a .pptx file (the `slidemind build-pptx` path). Still
-// requires an open host because the render happens server-side — but NOT an
-// awake task pane: the render runs in the add-in's cloud backend.
+// Render a deck to a .pptx file (the `slidemind build-pptx` path). For a BOUND
+// deck against a backend serving brand routes this is fully pane-free — no
+// PowerPoint window needed at all (backgrounded or closed). Otherwise it needs
+// an open host because the brandId must come from the pane registry — but
+// still not an awake pane: the render runs in the add-in's cloud backend.
 export async function buildPptxFile({
   deckDir,
   presentationId = null,
@@ -309,18 +579,35 @@ export async function buildPptxFile({
 }) {
   if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
   const deckRef = readDeckBundleRef(deckDir);
-  const registry = await requireHost();
+  const out = outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+
+  // Pane-free path. `--to <presId>` names a window explicitly and therefore
+  // keeps the registry path.
+  if (!presentationId && deckRef?.presFP) {
+    const detached = await tryDetachedRender(deckDir, deckRef, onProgress);
+    if (detached) {
+      fs.writeFileSync(out, Buffer.from(detached.result.base64, "base64"));
+      return {
+        outPath: out,
+        presId: null,
+        windowless: true,
+        slideCount: detached.result.slideCount ?? null,
+        warnings: detached.result.warnings ?? [],
+        skippedSlides: detached.result.skippedSlides ?? [],
+      };
+    }
+  }
+
+  const registry = await requireRenderHost();
   const entry = pickPresentationEntry(registry, presentationId, {
     preferBrandId: deckRef?.presFP ?? null,
   });
-  const presId = entry.presId;
-  const result = await renderDeckToBase64(deckDir, {
-    presId,
-    backendURL: entry.backendURL ?? null,
+  const { entry: renderEntry, result } = await renderWithRetarget(
+    deckDir,
+    entry,
     onProgress,
-  });
-  const out =
-    outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+  );
+  const presId = renderEntry.presId;
   fs.writeFileSync(out, Buffer.from(result.base64, "base64"));
   return {
     outPath: out,

package/src/bridge/bundle.mjs

@@ -45,7 +45,11 @@ import path from "node:path";
 import http from "node:http";
 import https from "node:https";
 
-import { getDesignBundle } from "./client.mjs";
+import {
+  getDesignBundle,
+  getDesignBundleForBrand,
+  getDesignBundleForBrandAnyBackend,
+} from "./client.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.
@@ -65,6 +69,21 @@ export function bundleDirForPresFP(presFP) {
   return path.join(bundleCacheRoot(), sanitizeKey(presFP));
 }
 
+// Zero-GET lookup of a materialized bundle's meta by presFP: reads the on-disk
+// bundle.json materializeBundle wrote and returns the parsed record, or null
+// when that CD was never materialized here / the file is unreadable. `new`'s
+// stateless auto-bind uses this to confirm a resolved design's bundle already
+// exists locally BEFORE writing a deck ref — no network, no throw.
+export function readMaterializedBundleMeta(presFP) {
+  if (!presFP) return null;
+  try {
+    const metaPath = path.join(bundleDirForPresFP(presFP), "bundle.json");
+    return JSON.parse(fs.readFileSync(metaPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
 // Wipe the whole materialized bundle cache so the next build/push/download
 // re-fetches every design bundle fresh from the add-in. `slidemind init` calls
 // this: init is the deliberate (re)setup point — and `slidemind update`
@@ -220,13 +239,31 @@ function buildReusableImagesManifest(extractedImages) {
 // a bundle re-produce (engines, image-source guidelines, sample curation) and
 // deployment-owned content (workflow refs, the lint engine) can never go
 // stale here. `force` re-downloads binaries even when their etags match.
-// Returns { dir, presFP, etag, version, downloaded, pruned, engineUpdated,
-// warnings }.
+// Target: `presId` (pane registry), or `brandId` in options for the pane-free
+// brand route (presId may then be null; backendURL null = fan-out).
+// Returns { dir, presFP, etag, version, backendURL, downloaded, pruned,
+// engineUpdated, warnings }.
 export async function materializeBundle(
   presId,
-  { force = false, backendURL = null, preferBrandId = null } = {},
+  { force = false, backendURL = null, preferBrandId = null, brandId = null } = {},
 ) {
-  const wire = await getDesignBundle(presId, { backendURL, preferBrandId });
+  // Two fetch paths for the same wire: by presId through the pane registry
+  // (needs a registered window), or pane-free by brandId through the brand
+  // route (bound deck, PowerPoint optional). Everything below operates on the
+  // wire and is identical for both.
+  let wire;
+  let wireBackendURL = backendURL;
+  if (brandId) {
+    if (backendURL) {
+      wire = await getDesignBundleForBrand(brandId, { backendURL });
+    } else {
+      const resolved = await getDesignBundleForBrandAnyBackend(brandId);
+      wire = resolved.wire;
+      wireBackendURL = resolved.backendURL;
+    }
+  } else {
+    wire = await getDesignBundle(presId, { backendURL, preferBrandId });
+  }
   if (!wire || !wire.presFP) {
     throw new Error("design-bundle response is missing presFP");
   }
@@ -445,6 +482,9 @@ export async function materializeBundle(
 
   const meta = {
     presFP,
+    // In the brand model presFP == brandId; recorded explicitly so consumers
+    // (and humans reading the cache) don't need to know that equivalence.
+    brandId: presFP,
     version: wire.version ?? null,
     etag: wire.etag ?? null,
     scope: wire.scope ?? null,
@@ -483,6 +523,9 @@ export async function materializeBundle(
     presFP,
     etag: wire.etag ?? null,
     version: wire.version ?? null,
+    // Which backend actually served the wire — meaningful on the brandId
+    // fan-out path, where the caller didn't know it up front.
+    backendURL: wireBackendURL,
     downloaded,
     pruned,
     engineUpdated,
@@ -613,8 +656,7 @@ export function isImageEngine(engine) {
 // `kind`. Returns null when the CD exposes no image engine (e.g. only a
 // slide-search engine) — callers surface a "wire an image engine" message
 // rather than falling back to an engine the bridge can't insert. Single source
-// of truth for the heuristic shared by the CLI dispatcher (`slidemind search`)
-// and the MCP `slidemind_search_engine` tool.
+// of truth for the heuristic used by the CLI dispatcher (`slidemind search`).
 export function pickImageEngine(engines) {
   const list = Array.isArray(engines) ? engines : [];
   return list.find(isImageEngine) ?? null;

package/src/bridge/capture.mjs

@@ -171,8 +171,8 @@ export async function captureDeckLocally({ deckDir, bundleDir, onProgress }) {
   }
   const meta = readBundleMeta(bundleDir);
   const version = meta.captureEngineVersion ?? "0";
-  // `?v=` busts Node's module cache so a long-lived process (the MCP server)
-  // picks up a refreshed engine at the same path after a bundle sync.
+  // `?v=` busts Node's module cache so a re-import picks up a refreshed engine
+  // at the same path after a bundle sync.
   const engine = await import(
     `${pathToFileURL(enginePath).href}?v=${encodeURIComponent(version)}`
   );