slidemind 0.1.3 → 0.1.5

package/src/bridge/client.mjs

@@ -5,6 +5,7 @@
 // backend runs render/bundle in-process and relays insert/replace/engine to the
 // open PowerPoint pane. No localhost, no shared loopback token, no cert.
 
+import { randomUUID } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 
@@ -27,6 +28,19 @@ function listTimeoutMs() {
   );
 }
 
+// Engine ops (list / search / download / extract) are RELAYED through the task
+// pane: the server waits up to ~25s for a suspended pane to reconnect, then up
+// to 60s for the pane's ack. Budget above that sum so a typed pane error
+// (pane_suspended / pane_timeout) wins over a client timeout. Note `ls engines`
+// is pane-relayed too — using the 8s list timeout there masked the real
+// pane_suspended as a bare "timed out after 8000ms".
+function engineTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+    90000
+  );
+}
+
 const NOT_PAIRED_MESSAGE =
   'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
   "and run the shown `slidemind pair …` command, then retry.";
@@ -338,19 +352,44 @@ export async function requireHost() {
   );
 }
 
+// Tie-break a multi-backend presId collision without bothering the user when
+// only one candidate can actually serve the deck:
+//   (a) exactly one CONNECTED pane whose active CD matches the deck's bundle
+//       ref (`preferBrandId` — the deck's presFP, which equals the pane's
+//       brandId by the bundle-cache contract);
+//   (b) else exactly one connected pane with ANY active CD (brandId set) —
+//       e.g. a local dev backend connected without a CD next to prod with one.
+// Returns the winning entry or null when genuinely ambiguous.
+function tieBreakMatches(matches, preferBrandId) {
+  const live = matches.filter((m) => m.connected !== false && !m.suspendedAt);
+  if (preferBrandId) {
+    const want = live.filter((m) => m.brandId === preferBrandId);
+    if (want.length === 1) return want[0];
+  }
+  const withCd = live.filter((m) => m.brandId);
+  if (withCd.length === 1) return withCd[0];
+  return null;
+}
+
 // Resolve which backend a presId lives on via a LIVE fan-out list (never a
 // cached map — a presId can move backends on re-pair/redeploy). Throws an
 // actionable message on a miss, or an ambiguity error when the same presId is
-// open on more than one reachable backend.
-export async function resolveBackendForPres(presId) {
+// open on more than one reachable backend and no tie-break rule settles it.
+export async function resolveBackendForPres(
+  presId,
+  { preferBrandId = null } = {},
+) {
   if (!presId) throw new Error("resolveBackendForPres: presId is required");
   const { presentations } = await fanOutPresentations();
   const matches = presentations.filter((p) => p.presId === presId);
   if (matches.length === 1) return matches[0].backendURL;
   if (matches.length > 1) {
+    const winner = tieBreakMatches(matches, preferBrandId);
+    if (winner) return winner.backendURL;
     const envs = matches.map((m) => m.env).join(", ");
     throw new Error(
-      `Presentation '${presId}' is open on multiple environments: ${envs}. ` +
+      `Presentation '${presId}' is open on multiple environments: ${envs}, ` +
+        "and no single connected one has the deck's corporate design active. " +
         "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
     );
   }
@@ -360,11 +399,79 @@ export async function resolveBackendForPres(presId) {
   );
 }
 
+// Wait for a presentation's task pane to come back after a `pane_suspended`
+// (PowerPoint backgrounded → webview suspended → socket dropped). Polls the
+// live registry; succeeds on the same presId reconnecting, OR on a CONNECTED
+// entry matching `fileName` + `brandId` — a pane reconnect can mint a NEW
+// presId for the same window, so identity-by-content covers the churn. Returns
+// the live registry entry (caller re-targets from it), or null on timeout.
+// `onWait` fires once with the wait budget in seconds — the caller's single
+// actionable "click the pane" line.
+export async function waitForPaneReady(
+  presId,
+  {
+    backendURL = null,
+    fileName = null,
+    brandId = null,
+    timeoutMs = null,
+    pollMs = null,
+    onWait = null,
+  } = {},
+) {
+  const waitMs =
+    timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_TIMEOUT_MS", 120000);
+  const stepMs = pollMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_POLL_MS", 3000);
+  const deadline = Date.now() + waitMs;
+  let notified = false;
+  for (;;) {
+    let list = [];
+    try {
+      list = backendURL
+        ? await listPresentationsForBackend(backendURL)
+        : (await fanOutPresentations()).presentations;
+    } catch {
+      /* transient list failure — poll again until the deadline */
+    }
+    const connected = list.filter(
+      (p) => p.connected !== false && !p.suspendedAt,
+    );
+    const same = connected.find((p) => p.presId === presId);
+    if (same) return same;
+    if (fileName || brandId) {
+      const rematch = connected.find(
+        (p) =>
+          (!fileName || p.fileName === fileName || p.title === fileName) &&
+          (!brandId || p.brandId === brandId),
+      );
+      if (rematch) return rematch;
+    }
+    if (Date.now() >= deadline) return null;
+    if (!notified) {
+      notified = true;
+      onWait?.(Math.round(waitMs / 1000));
+    }
+    await sleep(stepMs);
+  }
+}
+
+// The one actionable line a human needs when a pane op is waiting. stderr so
+// it reaches the terminal from the CLI and the MCP server log alike.
+function paneWaitNotice(seconds) {
+  process.stderr.write(
+    "task pane suspended — click the slidemind pane in PowerPoint to wake it " +
+      `(waiting up to ${seconds}s)…\n`,
+  );
+}
+
 // GET the full design bundle (tokens, css, layouts, designRules, signed asset
 // URLs, engines) for the presentation's active corporate design.
-export async function getDesignBundle(presId, { backendURL = null } = {}) {
+export async function getDesignBundle(
+  presId,
+  { backendURL = null, preferBrandId = null } = {},
+) {
   if (!presId) throw new Error("getDesignBundle: presId is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
+  const be =
+    backendURL || (await resolveBackendForPres(presId, { preferBrandId }));
   return withTransientRetry(async () => {
     const res = await bridgeFetch(
       `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
@@ -375,35 +482,335 @@ export async function getDesignBundle(presId, { backendURL = null } = {}) {
   });
 }
 
+// List the LIVE engine catalog (NOT the bundle's curated set) for the paired
+// backend(s). `GET /api/cli/engines` is backend-scoped, not presId-scoped, so
+// when several environments are paired this fans out and tags each engine with
+// its short `env` label (never the backendURL — the no-URL rule). Filter by
+// engine `type` (collection|search) and/or `subtype` (image|slide|template|
+// content). Returns a flat `{ engines: [...] }` like the single-backend route.
+async function listEnginesForBackend(backendURL, { type = null, subtype = null } = {}) {
+  return withTransientRetry(async () => {
+    const params = new URLSearchParams();
+    if (type) params.set("type", type);
+    if (subtype) params.set("subtype", subtype);
+    const qs = params.toString();
+    const res = await bridgeFetch(
+      `/api/cli/engines${qs ? `?${qs}` : ""}`,
+      // Pane-relayed on the add-in side — needs the engine budget, not the 8s
+      // list timeout (which bailed before the pane could ever answer).
+      { timeoutMs: engineTimeoutMs() },
+      backendURL,
+    );
+    const data = await res.json();
+    const arr = Array.isArray(data?.engines) ? data.engines : [];
+    const env = deriveEnvLabel(backendURL);
+    return arr.map((e) => ({ ...e, env }));
+  });
+}
+
+export async function listEngines({ type = null, subtype = null } = {}) {
+  const sessions = sessionsInScope();
+  const settled = await Promise.allSettled(
+    sessions.map((s) => listEnginesForBackend(s.backendURL, { type, subtype })),
+  );
+  const engines = [];
+  const failures = [];
+  let fulfilledCount = 0;
+  settled.forEach((r, i) => {
+    if (r.status === "fulfilled") {
+      fulfilledCount += 1;
+      engines.push(...r.value);
+    } else {
+      failures.push({ env: deriveEnvLabel(sessions[i].backendURL), err: r.reason });
+    }
+  });
+  // Mirror listOpenPresentations: only surface an error when nothing answered.
+  if (engines.length === 0 && fulfilledCount === 0 && failures.length > 0) {
+    if (failures.length === 1) throw failures[0].err;
+    throw new Error(
+      "slidemind: every paired backend failed to list engines:\n" +
+        failures.map((f) => `  ${f.env}: ${f.err.message}`).join("\n"),
+    );
+  }
+  return { engines };
+}
+
+// ---------------------------------------------------------------------------
+// Server-side OOXML render
+// ---------------------------------------------------------------------------
+//
+// Two protocols, newest first:
+//   1. Render JOBS (preferred): POST creates a job, the CLI polls cheap status
+//      GETs and fetches the result when done. A full deck render routinely
+//      outlives the cloud ingress's ~240s request cap — only short polling
+//      requests survive that reliably, and they carry per-slide progress.
+//   2. Sync render (fallback): one POST held open for the whole render. Kept
+//      for older backends that don't serve /api/cli/capabilities yet.
+
+function envInt(name, fallback) {
+  const n = parseInt(process.env[name] || "", 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// One capability probe per backend per process. Keyed by the RESOLVED backend
+// URL (callers always resolve before probing), so multiple paired backends on
+// mixed versions each get their own answer.
+const renderJobsCapability = new Map();
+
+function backendSupportsRenderJobs(backendURL) {
+  let probe = renderJobsCapability.get(backendURL);
+  if (!probe) {
+    probe = (async () => {
+      try {
+        const res = await bridgeFetch(
+          "/api/cli/capabilities",
+          { timeoutMs: listTimeoutMs() },
+          backendURL,
+        );
+        const data = await res.json();
+        return data?.renderJobs === true;
+      } catch {
+        // Older backends 404 this path (with a non-JSON body) — sync render.
+        return false;
+      }
+    })();
+    renderJobsCapability.set(backendURL, probe);
+  }
+  return probe;
+}
+
+// Rebuild a job failure into the exact error shape bridgeFetch throws for the
+// sync route, so callers (etag self-heal, MCP error texts) can't tell the
+// protocols apart.
+function jobFailureError(jobError, presId) {
+  const status = jobError?.status ?? 500;
+  const detail = jobError?.error ?? "render_failed";
+  const err = new Error(
+    `slidemind bridge ${status} render job failed for ${presId}: ${detail}`,
+  );
+  err.status = status;
+  err.code = detail;
+  err.body = { error: detail, ...(jobError?.extra ?? {}) };
+  return err;
+}
+
+async function renderViaSync({ presId, body, backendURL }) {
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/render-pptx`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      // Server-side OOXML render is a heavy operation — a full deck of richly
+      // composed slides routinely runs well past the 35s default. Treat it like
+      // a mutation: give it a generous default and let env override it.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
+        300000,
+    },
+    backendURL,
+  );
+  return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
+}
+
+async function renderViaJob({ presId, body, backendURL, onProgress }) {
+  const pollMs = envInt("SLIDEMIND_BRIDGE_RENDER_POLL_MS", 2500);
+  const deadlineMs = envInt("SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS", 900000);
+  const resultTimeoutMs = envInt(
+    "SLIDEMIND_BRIDGE_RENDER_RESULT_TIMEOUT_MS",
+    120000,
+  );
+
+  const createJob = async () => {
+    // Deliberately NOT wrapped in withTransientRetry: its blanket 404 retry
+    // would re-upload a multi-MB slide payload, and creation errors (stale
+    // etag, no CD, unknown presId) are definitive.
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(presId)}/render-jobs`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) ||
+          35000,
+      },
+      backendURL,
+    );
+    const data = await res.json();
+    if (!data?.jobId) throw new Error("render-jobs returned no jobId");
+    return data.jobId;
+  };
+
+  let jobId = await createJob();
+  let resubmitted = false;
+  let lastReported = "";
+  const deadline = Date.now() + deadlineMs;
+
+  for (;;) {
+    if (Date.now() > deadline) {
+      const err = new Error(
+        `slidemind render did not finish within ${deadlineMs}ms ` +
+          "(raise SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS for very large decks). " +
+          "The render keeps running server-side — retrying may pick up a warm cache.",
+      );
+      err.code = "bridge_timeout";
+      throw err;
+    }
+    await sleep(pollMs);
+
+    let status;
+    try {
+      const res = await bridgeFetch(
+        `/api/cli/render-jobs/${encodeURIComponent(jobId)}`,
+        { timeoutMs: 15000 },
+        backendURL,
+      );
+      status = await res.json();
+    } catch (err) {
+      // The job record vanished (backend Redis flush/restart) — same recovery
+      // as a lost replica: resubmit once.
+      if (err?.code === "job_not_found") {
+        if (resubmitted) throw jobFailureError({ status: 500, error: "job_lost" }, presId);
+        resubmitted = true;
+        onProgress?.({ state: "restarted" });
+        jobId = await createJob();
+        continue;
+      }
+      // Rate-limited poll: honor the window, then resume.
+      if (err?.status === 429) {
+        const retryAfterSec = err?.body?.retryAfterSec;
+        await sleep(Math.min((retryAfterSec || 5) * 1000, 30000));
+        continue;
+      }
+      // Anything else (network blip, 5xx, replica restart) — polling is
+      // idempotent; just poll again until the deadline.
+      continue;
+    }
+
+    if (onProgress) {
+      const snapshot = JSON.stringify([status.state, status.progress]);
+      if (snapshot !== lastReported) {
+        lastReported = snapshot;
+        onProgress({ state: status.state, ...(status.progress ?? {}) });
+      }
+    }
+
+    if (status.state === "failed") {
+      const jobError = status.error ?? { status: 500, error: "render_failed" };
+      // The rendering replica died (deploy, crash, scale-in). Renders are
+      // idempotent — resubmit once before giving up.
+      if (jobError.error === "job_lost" && !resubmitted) {
+        resubmitted = true;
+        onProgress?.({ state: "restarted" });
+        jobId = await createJob();
+        continue;
+      }
+      throw jobFailureError(jobError, presId);
+    }
+
+    if (status.state === "done") {
+      // The result may be tens of MB — generous timeout, and a couple of
+      // retries for transient blips (the stored result is re-fetchable).
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          const res = await bridgeFetch(
+            `/api/cli/render-jobs/${encodeURIComponent(jobId)}/result`,
+            { timeoutMs: resultTimeoutMs },
+            backendURL,
+          );
+          return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
+        } catch (err) {
+          if (
+            attempt >= 2 ||
+            err?.code === "result_expired" ||
+            err?.code === "job_not_found"
+          ) {
+            throw err;
+          }
+          await sleep(pollMs);
+        }
+      }
+    }
+  }
+}
+
 // Server-side OOXML render: ship authored slide JSX (+ deck-local assets) and
 // get back a native .pptx (base64) rendered against the presentation's own CD.
 // `slides`: { "<file>.jsx": "<jsx source>" }. `deckAssets`: { "assets/<f>": "<base64>" }.
+// `onProgress` (optional) receives `{ state, done?, total?, stage? }` ticks on
+// the job protocol; the sync fallback emits none.
 export async function renderPptx({
   presId,
   slides,
   deckAssets = null,
+  nativeSlides = null,
   etag = null,
   backendURL = null,
+  onProgress = null,
 }) {
   if (!presId) throw new Error("renderPptx: presId is required");
-  if (!slides || Object.keys(slides).length === 0) {
-    throw new Error("renderPptx: slides is required");
+  const hasSlides = slides && Object.keys(slides).length > 0;
+  const hasNative = nativeSlides && Object.keys(nativeSlides).length > 0;
+  if (!hasSlides && !hasNative) {
+    throw new Error("renderPptx: slides or nativeSlides is required");
   }
   const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { slides };
+  const body = { slides: slides ?? {} };
   if (deckAssets && Object.keys(deckAssets).length > 0) {
     body.deckAssets = deckAssets;
   }
+  // Reused native one-slide .pptx (base64), keyed by play-order filename — the
+  // server splices them in by numeric-aware sorted filename (contract #7).
+  if (hasNative) body.nativeSlides = nativeSlides;
+  if (etag) body.etag = etag;
+
+  if (await backendSupportsRenderJobs(be)) {
+    try {
+      return await renderViaJob({ presId, body, backendURL: be, onProgress });
+    } catch (err) {
+      // The backend speaks the protocol but its job store is down — the sync
+      // route renders in-process without Redis, so fall back to it.
+      if (err?.code !== "jobs_unavailable") throw err;
+    }
+  }
+  return renderViaSync({ presId, body, backendURL: be });
+}
+
+// Translate a deck the CLI captured LOCALLY (the shipped capture engine) into a
+// native .pptx. The slow Chrome work already ran client-side, so this is a fast
+// single synchronous request — the server runs only the IP-sensitive boxes→OOXML
+// half. Returns the same shape as renderPptx ({ ok, base64, slideCount, … }).
+export async function translateDeck({
+  presId,
+  captured,
+  nativeSlides = null,
+  etag = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("translateDeck: presId is required");
+  if (!captured) throw new Error("translateDeck: captured is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { captured };
+  // Reused native one-slide .pptx (base64), keyed by play-order filename — the
+  // server splices them in alongside the locally-captured JSX slides (contract
+  // #7). The slow capture already ran client-side; native slides are pass-through.
+  if (nativeSlides && Object.keys(nativeSlides).length > 0) {
+    body.nativeSlides = nativeSlides;
+  }
   if (etag) body.etag = etag;
   const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/render-pptx`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/translate`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
-      // Server-side OOXML render is a heavy operation — a full deck of richly
-      // composed slides routinely runs well past the 35s default. Treat it like
-      // a mutation: give it a generous default and let env override it.
+      // The body carries inlined image bytes and the response a base64 .pptx —
+      // bandwidth, not server compute. Give it the render-grade timeout.
       timeoutMs:
         parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
         300000,
@@ -413,30 +820,142 @@ export async function renderPptx({
   return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
+// Run a pane-relayed engine op; on `pane_suspended` (the server already waited
+// ~25s for a reconnect) wait CLIENT-side for the pane to wake — one actionable
+// line, then a single retry against the live entry (covers presId churn too).
+// Engine ops are idempotent reads, so the retry is safe.
+async function engineOpWithPaneWait(presId, backendURL, attempt) {
+  try {
+    return await attempt(presId, backendURL);
+  } catch (err) {
+    if (err?.code !== "pane_suspended") throw err;
+    const live = await waitForPaneReady(presId, {
+      backendURL,
+      onWait: paneWaitNotice,
+    });
+    if (!live) throw err;
+    return attempt(live.presId, live.backendURL ?? backendURL);
+  }
+}
+
 // Brand-engine search through the local bridge. New add-ins run this
 // server-side with the relayed user token; older add-ins may fall back to a
-// task-pane proxy. Returns a searchId + numbered result thumbnails.
-export async function engineSearch({ presId, engineId, query, backendURL = null }) {
+// task-pane proxy. Returns a searchId + numbered results (image thumbnails, or
+// slide results carrying per-slide text + metadata). `subtype`/`intent`/`top`
+// are passed through for slide engines (image engines ignore intent); omit them
+// and the server uses its defaults (back-compat with older add-ins).
+export async function engineSearch({
+  presId,
+  engineId,
+  query,
+  subtype = null,
+  intent = null,
+  top = null,
+  backendURL = null,
+  // When the chosen pane is suspended, wait CLIENT-side for THIS window to wake
+  // (the single-window default). engineSearchAnyPane sets this false for all but
+  // the last candidate so it can fail over to another live window instead.
+  waitOnSuspend = true,
+  timeoutMs = null,
+}) {
   if (!presId) throw new Error("engineSearch: presId is required");
   if (!engineId) throw new Error("engineSearch: engineId is required");
   if (!query) throw new Error("engineSearch: query is required");
   const be = backendURL || (await resolveBackendForPres(presId));
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/engine/search`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ engineId, query }),
-      // Engine ops relay through the pane: the server may wait up to ~25s for
-      // a suspended pane to reconnect, then up to 60s for the pane's ack —
-      // stay above that sum so typed errors win over client timeouts.
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-        90000,
-    },
-    be,
+  const body = { engineId, query };
+  if (subtype) body.subtype = subtype;
+  if (intent) body.intent = intent;
+  if (typeof top === "number") body.top = top;
+  const run = async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/search`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: timeoutMs ?? engineTimeoutMs(),
+      },
+      b,
+    );
+    return res.json(); // { ok, searchId, engineId, subtype, intent, resultCount, gridDataUri?, results }
+  };
+  return waitOnSuspend ? engineOpWithPaneWait(presId, be, run) : run(presId, be);
+}
+
+// A suspended/throttled background webview must not strand a window-AGNOSTIC
+// engine search: the catalog is per-user, so any connected pane can answer it.
+// Try the picked pane first, then every other connected pane on the same
+// backend (non-suspended first), failing fast past each unresponsive one; the
+// LAST candidate keeps the normal "click the pane to wake it" wait so a genuine
+// single-window/all-asleep case still surfaces the actionable prompt. Returns
+// the search result tagged with the presId/backendURL that actually answered —
+// the searchId is bound to THAT window, so callers must thread it into
+// follow-up view/insert/add-slide. An explicit presId pins the window (no
+// failover — the caller asked for that specific one).
+export async function engineSearchAnyPane({
+  registry,
+  explicitPresId = null,
+  engineId,
+  query,
+  subtype = null,
+  intent = null,
+  top = null,
+}) {
+  const primary = pickAnyPresentationEntry(registry, explicitPresId);
+  const primaryBackend = primary.backendURL ?? null;
+  let candidates;
+  if (explicitPresId) {
+    candidates = [primary];
+  } else {
+    const others = (Array.isArray(registry) ? registry : [])
+      .filter(
+        (p) =>
+          p.presId !== primary.presId &&
+          p.connected !== false &&
+          (p.backendURL ?? null) === primaryBackend,
+      )
+      .sort((a, b) => (a.suspendedAt ? 1 : 0) - (b.suspendedAt ? 1 : 0));
+    candidates = [primary, ...others];
+  }
+  const failoverTimeout = envInt(
+    "SLIDEMIND_BRIDGE_ENGINE_FAILOVER_TIMEOUT_MS",
+    25000,
   );
-  return res.json(); // { ok, searchId, resultCount, gridDataUri, thumbnails }
+  let lastErr = null;
+  for (let i = 0; i < candidates.length; i++) {
+    const cand = candidates[i];
+    const isLast = i === candidates.length - 1;
+    try {
+      const res = await engineSearch({
+        presId: cand.presId,
+        engineId,
+        query,
+        subtype,
+        intent,
+        top,
+        backendURL: cand.backendURL ?? primaryBackend,
+        waitOnSuspend: isLast,
+        timeoutMs: isLast ? null : failoverTimeout,
+      });
+      return {
+        ...res,
+        presId: cand.presId,
+        backendURL: cand.backendURL ?? primaryBackend,
+      };
+    } catch (err) {
+      lastErr = err;
+      // A suspended/frozen/slow pane is recoverable by trying the next window;
+      // anything else (bad engineId, auth, 4xx) is real — surface it now.
+      const recoverable =
+        err?.code === "pane_suspended" ||
+        err?.code === "pane_timeout" ||
+        err?.code === "bridge_timeout" ||
+        err?.status === 503 ||
+        err?.status === 504;
+      if (isLast || !recoverable) throw err;
+    }
+  }
+  throw lastErr ?? new Error("engineSearchAnyPane: no candidate panes");
 }
 
 // Fetch a chosen engine result's bytes through the local bridge. For image
@@ -459,21 +978,134 @@ export async function engineDownload({
   const be = backendURL || (await resolveBackendForPres(presId));
   const body = { searchId, selection };
   if (iconColor) body.iconColor = iconColor;
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/engine/download`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      // Same relay path as engine/search — outlast the server's reconnect
-      // wait + pane ack timeout.
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-        90000,
-    },
-    be,
-  );
-  return res.json(); // { ok, base64, mimeType, svgMarkup }
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        // Same relay path as engine/search — outlast the server's reconnect
+        // wait + pane ack timeout.
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, base64, mimeType, svgMarkup }
+  });
+}
+
+// Extract a chosen slide-search result as a standalone one-slide .pptx (base64),
+// WITHOUT inserting it anywhere — the "fold into a deck" path. Relayed through
+// the pane like search/download.
+export async function extractSlide({
+  presId,
+  searchId,
+  selection,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("extractSlide: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("extractSlide: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("extractSlide: selection (number) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, base64, slideId?, presentationTitle? }
+  });
+}
+
+// Insert one or more chosen slide-search results live into the open
+// presentation (the "reuse → insert live" path). Relayed through the pane.
+export async function insertSlideLive({
+  presId,
+  searchId,
+  selections,
+  at = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("insertSlideLive: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("insertSlideLive: searchId (number) is required");
+  }
+  if (!Array.isArray(selections) || selections.length === 0) {
+    throw new Error("insertSlideLive: selections (number[]) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  // Live insert is a MUTATION, so it carries an operationId for the add-in's
+  // runMutationOnce dedup (the slide-insert handler keys an LRU on it). Generate
+  // it ONCE here, before engineOpWithPaneWait — the body is built once and
+  // reused across the wrapper's single pane_suspended retry, so the SAME id
+  // rides both attempts and a retry can never double-insert. Mirrors how
+  // buildAndPush makes one push operationId reused across attempts.
+  const operationId = `insert-${randomUUID()}`;
+  const body = { searchId, selections, operationId };
+  if (typeof at === "number") body.at = at;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-insert`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, insertedCount, insertedSlideIds }
+  });
+}
+
+// Fetch a chosen slide-search result's thumbnail/preview as a data URI for
+// on-demand viewing (the agent doesn't have to extract the whole .pptx just to
+// look at a slide). Relayed through the pane.
+export async function viewSlide({
+  presId,
+  searchId,
+  selection,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("viewSlide: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("viewSlide: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("viewSlide: selection (number) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-view`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, dataUri, mimeType }
+  });
 }
 
 export async function insertSlides({
@@ -532,7 +1164,13 @@ export async function replaceSlides({
 // `backendURL`/`env` after a fan-out list), or throws with a helpful message if
 // the choice is ambiguous. Callers that already hold the entry can pass its
 // `backendURL` straight to the targeted ops, skipping a second fan-out.
-export function pickPresentationEntry(registry, explicitPresId) {
+// `preferBrandId` (the deck's bundle-ref presFP) tie-breaks a presId open on
+// several backends — see tieBreakMatches.
+export function pickPresentationEntry(
+  registry,
+  explicitPresId,
+  { preferBrandId = null } = {},
+) {
   if (explicitPresId) {
     const matches = registry.filter((p) => p.presId === explicitPresId);
     if (matches.length === 0) {
@@ -542,9 +1180,12 @@ export function pickPresentationEntry(registry, explicitPresId) {
       );
     }
     if (matches.length > 1) {
+      const winner = tieBreakMatches(matches, preferBrandId);
+      if (winner) return winner;
       const envs = matches.map((m) => m.env || "?").join(", ");
       throw new Error(
-        `Presentation '${explicitPresId}' is open on multiple environments: ${envs}. ` +
+        `Presentation '${explicitPresId}' is open on multiple environments: ${envs}, ` +
+          "and no single connected one has the deck's corporate design active. " +
           "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
       );
     }
@@ -557,6 +1198,13 @@ export function pickPresentationEntry(registry, explicitPresId) {
     );
   }
   if (registry.length === 1) return registry[0];
+  // ONE window mirrored across several paired backends is not a user choice —
+  // apply the same tie-break as the explicit-presId path. Several DIFFERENT
+  // windows stay a user decision.
+  if (new Set(registry.map((p) => p.presId)).size === 1) {
+    const winner = tieBreakMatches(registry, preferBrandId);
+    if (winner) return winner;
+  }
   const list = registry
     .map(
       (p) =>
@@ -569,6 +1217,31 @@ export function pickPresentationEntry(registry, explicitPresId) {
   );
 }
 
+// Window-AGNOSTIC picker for engine ops (discovery / search / result view). The
+// engine catalog is per-user and NOT bound to any window, so any connected pane
+// can run the search — there is nothing for the caller to disambiguate. When no
+// explicit presId is given we attach to one automatically (preferring a live,
+// non-suspended pane so we don't have to wake a backgrounded one) instead of
+// throwing the "multiple windows, pick --to" error pickPresentationEntry raises.
+// An explicit presId still resolves exactly as pickPresentationEntry.
+//
+// CAVEAT: the searchId the add-in returns is bound to the pane that ran the
+// search (each window keeps its own search-context store). So follow-up
+// view/extract/insert must target the SAME entry this returns — surface its
+// presId to the caller so it can thread it back.
+export function pickAnyPresentationEntry(registry, explicitPresId, opts = {}) {
+  if (explicitPresId) return pickPresentationEntry(registry, explicitPresId, opts);
+  if (!Array.isArray(registry) || registry.length === 0) {
+    throw new Error(
+      "No PowerPoint windows registered with the slidemind add-in. " +
+        "Open a presentation, ensure the add-in is loaded, and try again.",
+    );
+  }
+  return (
+    registry.find((p) => p.connected !== false && !p.suspendedAt) ?? registry[0]
+  );
+}
+
 // Back-compat shim: returns just the presId string. Prefer
 // pickPresentationEntry when you need the origin backend.
 export function pickPresentation(registry, explicitPresId) {