slidemind 0.1.6 → 0.1.8

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

@@ -6,11 +6,13 @@
 // `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";
@@ -21,6 +23,7 @@ import {
   pickPresentationEntry,
   renderPptx,
   replaceSlides,
+  requireHost,
   requireRenderHost,
   translateDeck,
   waitForPaneReady,
@@ -93,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);
@@ -103,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 });
@@ -129,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 {
@@ -139,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;
@@ -157,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.
@@ -327,6 +339,45 @@ export async function viewDraft(
   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, {
@@ -379,20 +430,66 @@ export async function buildAndPush({
   }
 
   const deckRef = readDeckBundleRef(deckDir);
-  const registry = await requireRenderHost();
-  const entry = pickPresentationEntry(registry, presentationId, {
-    preferBrandId: deckRef?.presFP ?? null,
-  });
-  const rendered = await renderWithRetarget(deckDir, entry, onProgress);
-  const renderEntry = rendered.entry;
-  const presId = renderEntry.presId;
-  const backendURL = renderEntry.backendURL ?? null;
-  const result = rendered.result;
+
+  // --- 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.
@@ -418,16 +515,25 @@ 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,
@@ -440,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);
@@ -474,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,
@@ -485,6 +579,25 @@ export async function buildPptxFile({
 }) {
   if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
   const deckRef = readDeckBundleRef(deckDir);
+  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,
@@ -495,8 +608,6 @@ export async function buildPptxFile({
     onProgress,
   );
   const presId = renderEntry.presId;
-  const out =
-    outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
   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)}`
   );