slidemind 0.2.2 → 0.2.4

package/src/bridge/client.mjs

@@ -1,7 +1,8 @@
 // Client for the slidemind cloud relay.
 //
 // The CLI talks to `<backendURL>/api/cli/*` with a Bearer session token — both
-// established once by `slidemind pair` (see config.mjs). The add-in's cloud
+// established by redeeming a one-time setup claim minted in the authenticated add-in.
+// The add-in's cloud
 // backend runs render/bundle in-process and relays insert/replace/engine to the
 // open PowerPoint pane. No localhost, no shared loopback token, no cert.
 
@@ -9,6 +10,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -121,11 +123,11 @@ function readinessTimeoutMs() {
 }
 
 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.";
+  "slidemind is not connected. In PowerPoint open slidemind → Settings → " +
+  "General → Connect CLI, press the link button, and run the command it shows.";
 
 // The one-command remedy every host-precondition error now points at:
-// `slidemind ready` runs the whole pairing → reachability → version → window →
+// `slidemind ready` runs authorization → reachability → version → window →
 // design ladder and materializes the bundle, so a stuck author has a single
 // next step instead of a scavenger hunt across doctor/presentations/download.
 // Appended (never substituted) to the existing prose so callers' assert.match
@@ -149,6 +151,29 @@ function transientRetryDelays() {
     .filter((n) => Number.isFinite(n) && n >= 0);
 }
 
+// A 401 from either bridge transport. Carries the remediation as its message
+// AND a machine-readable shape, because callers that probe several backends in
+// a row have to tell "this environment doesn't have that record" (routing
+// information) from "this session is dead" (the user's problem) — see
+// resolveSearchBackend.
+function sessionInvalidError() {
+  const err = new Error(
+    "slidemind session is invalid or expired. Run `slidemind logout --all`, then " +
+      "reconnect with a fresh command from the add-in's Connect CLI panel.",
+  );
+  err.status = 401;
+  err.code = "session_invalid";
+  return err;
+}
+
+// True for the 401 class above, and for anything else that arrives with a 401
+// status (an older path, or a rethrown response error).
+export function isSessionInvalidError(err) {
+  if (!err) return false;
+  if (err.status === 401 || err.code === "session_invalid") return true;
+  return /slidemind session is invalid or expired/i.test(String(err.message ?? ""));
+}
+
 function isTransientBridgeError(err) {
   if (!err) return false;
   // pane_suspended needs the user (foreground PowerPoint), not a blind retry —
@@ -230,18 +255,13 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
     if (err && /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(String(err.message || err))) {
       throw new Error(
         `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
-          "if it persists, re-pair with `slidemind pair`.",
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
     throw err;
   }
   enforceVersionFloor(response);
-  if (response.status === 401) {
-    throw new Error(
-      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
-        'click "Connect CLI", and run the shown `slidemind pair …`.',
-    );
-  }
+  if (response.status === 401) throw sessionInvalidError();
   if (response.status < 200 || response.status >= 300) {
     let parsed = null;
     try {
@@ -271,6 +291,10 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
   return {
     json: async () => (response.body ? JSON.parse(response.body) : null),
     text: async () => response.body,
+    // Exposed for routes that carry their answer partly in headers (the
+    // source-presentation read reports slide counts and truncation there, so a
+    // caller learns the deck was windowed without parsing the Markdown).
+    headers: response.headers ?? {},
   };
 }
 
@@ -447,18 +471,13 @@ async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
     ) {
       throw new Error(
         `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
-          "if it persists, re-pair with `slidemind pair`.",
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
     throw err;
   }
   enforceVersionFloor(response);
-  if (response.status === 401) {
-    throw new Error(
-      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
-        'click "Connect CLI", and run the shown `slidemind pair …`.',
-    );
-  }
+  if (response.status === 401) throw sessionInvalidError();
   if (response.status < 200 || response.status >= 300) {
     let parsed = null;
     try {
@@ -796,6 +815,21 @@ export async function requirePaneHost({ timeoutMs = null } = {}) {
   return requireHost();
 }
 
+// "Is a task pane available RIGHT NOW?" — the non-throwing twin of
+// requirePaneHost, for paths where an open pane is an OPTION rather than a
+// precondition (a stale permission snapshot can be routed around by relaying
+// through a live pane, which signs each request with a fresh browser token).
+// Never waits for hydration and never authors a blocker: an empty array means
+// "no, carry on with what you were doing", not "stop".
+export async function paneReadyPresentations() {
+  try {
+    const { presentations } = await listOpenPresentationsDetailed();
+    return presentations.filter(isPaneReadyPresentation);
+  } catch {
+    return [];
+  }
+}
+
 // 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
@@ -851,17 +885,23 @@ export async function resolveBackendForPres(
 // 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.
+//
+// `otherPresIds` are windows the caller already knows are NOT the target (the
+// rest of the registry it picked from). They are excluded from the last-resort
+// design-fingerprint match — see below.
 export async function waitForPaneReady(
   presId,
   {
     backendURL = null,
     fileName = null,
     brandId = null,
+    otherPresIds = null,
     timeoutMs = null,
     pollMs = null,
     onWait = null,
   } = {},
 ) {
+  const notTheTarget = new Set(otherPresIds ?? []);
   const waitMs =
     timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_TIMEOUT_MS", 120000);
   const stepMs = pollMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_POLL_MS", 3000);
@@ -888,6 +928,25 @@ export async function waitForPaneReady(
           (!brandId || p.brandId === brandId),
       );
       if (rematch) return rematch;
+      // Last resort: match on the design fingerprint alone (presFP == brandId).
+      // A reconnect can report a different name for the same window — the user
+      // hit Save As, or the pane reports the title where it used to report the
+      // file name — but the active corporate design does not change with it.
+      // Only when EXACTLY one connected window carries it: two windows on the
+      // same design are indistinguishable, and pushing into the wrong one is
+      // worse than waiting.
+      //
+      // A window the caller ALREADY saw next to the target is not a churned
+      // target — it is a different presentation that merely shares the design
+      // (most tenants run exactly one), and retargeting to it would append the
+      // deck's slides to an unrelated file. Most tenants run a single corporate
+      // design, so brandId alone is not window identity.
+      if (fileName && brandId) {
+        const byBrand = connected.filter(
+          (p) => p.brandId === brandId && !notTheTarget.has(p.presId),
+        );
+        if (byBrand.length === 1) return byBrand[0];
+      }
     }
     if (Date.now() >= deadline) return null;
     if (!notified) {
@@ -907,6 +966,16 @@ function paneWaitNotice(seconds) {
   );
 }
 
+// The window is gone from the registry but its pane may already be back under a
+// new presId (churn on every reconnect) — nothing for the user to do here, so
+// say what the CLI is doing rather than asking for a click.
+function paneRetargetNotice(seconds) {
+  process.stderr.write(
+    "the target PowerPoint window re-registered — re-matching it by corporate " +
+      `design (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(
@@ -984,6 +1053,45 @@ export async function getDesignBundleForBrandAnyBackend(brandId) {
   throw err;
 }
 
+// The corporate designs this user may build against, straight off the CLI
+// session — no open window, no pane. One entry per design: `{ presFP, name,
+// env }`, where presFP IS the brandId every pane-free route is keyed by. Only
+// backends advertising `brandsList` are asked (older ones have no such route);
+// a backend that fails is skipped rather than failing the whole answer, so one
+// unreachable environment can't hide another's designs.
+export async function listBrands() {
+  const out = [];
+  for (const s of sessionsInScope()) {
+    if (!(await backendSupportsBrandsList(s.backendURL))) continue;
+    const env = deriveEnvLabel(s.backendURL);
+    try {
+      const res = await bridgeFetch(
+        "/api/cli/brands",
+        { timeoutMs: listTimeoutMs() },
+        s.backendURL,
+      );
+      const data = (await res.json()) ?? {};
+      const arr = Array.isArray(data.brands) ? data.brands : [];
+      for (const b of arr) {
+        // The wire may name the design by either of its two equivalent keys
+        // (presFP on the bundle contract, brandId on the routes) — normalize to
+        // the one the deck ref stores.
+        const presFP = b?.presFP ?? b?.brandId ?? b?.id ?? null;
+        if (!presFP) continue;
+        out.push({
+          presFP,
+          name: b?.name ?? b?.designName ?? null,
+          env,
+          backendURL: s.backendURL,
+        });
+      }
+    } catch {
+      /* unreachable / not granted — that environment simply contributes none */
+    }
+  }
+  return out;
+}
+
 // Concept-image generation is a heavy provider call (per-image cap ~180s
 // server-side). Budget just over that so a typed server error wins over a
 // client timeout, but keep it below the relay's ~240s ingress cap — the CLI
@@ -1155,7 +1263,26 @@ export async function generateImageForBrand(
 // 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.
+// content). Returns a flat `{ engines: [...], catalog }` like the single-backend
+// route.
+//
+// `catalog` is the pane-free route's summary — `{totalEngines, totalScopes,
+// filtered, emptyEngines}`, counted BEFORE the type/subtype filter — and it is
+// what separates "this filter matched nothing" from "this deployment has no
+// engines". Older backends (and the pane-relay path) send none; it stays null
+// there and every caller falls back to its pre-summary wording.
+function readCatalogSummary(data) {
+  const c = data?.catalog;
+  if (!c || typeof c !== "object" || Array.isArray(c)) return null;
+  const num = (v) => (Number.isFinite(v) ? v : 0);
+  return {
+    totalEngines: num(c.totalEngines),
+    totalScopes: num(c.totalScopes),
+    filtered: Boolean(c.filtered),
+    emptyEngines: num(c.emptyEngines),
+  };
+}
+
 async function listEnginesForBackend(backendURL, { type = null, subtype = null } = {}) {
   return withTransientRetry(async () => {
     const params = new URLSearchParams();
@@ -1172,22 +1299,60 @@ async function listEnginesForBackend(backendURL, { type = null, subtype = null }
     const data = await res.json();
     const arr = Array.isArray(data?.engines) ? data.engines : [];
     const env = deriveEnvLabel(backendURL);
-    return arr.map((e) => ({ ...e, env }));
+    return {
+      engines: arr.map((e) => ({ ...e, env })),
+      catalog: readCatalogSummary(data),
+    };
   });
 }
 
+// A scope (scope:all / scope:sharepoint) is not one environment's object: it is
+// the same saved search target, named identically on every deployment. Pooling
+// two backends' catalogs therefore repeats it verbatim — same id, same label —
+// which reads as two different things to choose between. Real engines DO differ
+// per environment and keep their duplicates; their `env` tag tells them apart.
+function isScopeRow(e) {
+  return e?.type === "scope" || /^scope:/.test(String(e?.id ?? ""));
+}
+
 export async function listEngines({ type = null, subtype = null, backendURL = null } = {}) {
   const sessions = backendURL ? [sessionForBackend(backendURL)] : sessionsInScope();
   const settled = await Promise.allSettled(
     sessions.map((s) => listEnginesForBackend(s.backendURL, { type, subtype })),
   );
   const engines = [];
+  const catalogs = [];
   const failures = [];
+  // Which environments actually contributed. NOT derivable from the pooled rows
+  // any more: a second environment that only repeated the scopes leaves no row
+  // of its own, and the human renderer keys its `[env]` tags off this.
+  const envs = [];
+  // Scope id → the one pooled row kept for it.
+  const scopeRows = new Map();
   let fulfilledCount = 0;
   settled.forEach((r, i) => {
     if (r.status === "fulfilled") {
       fulfilledCount += 1;
-      engines.push(...r.value);
+      envs.push(deriveEnvLabel(sessions[i].backendURL));
+      for (const e of r.value.engines) {
+        const id = typeof e?.id === "string" ? e.id : null;
+        if (id && isScopeRow(e)) {
+          const kept = scopeRows.get(id);
+          if (kept) {
+            // Contributed by more than one environment, so it belongs to none
+            // of them in particular — drop the tag rather than crediting
+            // whichever backend happened to answer first.
+            kept.env = null;
+            continue;
+          }
+          const row = { ...e };
+          scopeRows.set(id, row);
+          engines.push(row);
+          continue;
+        }
+        engines.push(e);
+      }
+      if (r.value.catalog) catalogs.push(r.value.catalog);
     } else {
       failures.push({ env: deriveEnvLabel(sessions[i].backendURL), err: r.reason });
     }
@@ -1200,7 +1365,24 @@ export async function listEngines({ type = null, subtype = null, backendURL = nu
         failures.map((f) => `  ${f.env}: ${f.err.message}`).join("\n"),
     );
   }
-  return { engines };
+  // Fanned out, the summary is the sum of what each environment reported: the
+  // engines are pooled into one list, so their counts pool too. SCOPES are the
+  // exception — the same named targets everywhere, deduped above — so summing
+  // them double-counts; the distinct total is the largest environment's count,
+  // or the number of distinct scope rows actually pooled when that is larger.
+  // (The catalog counts are pre-filter and the rows post-filter, which is why
+  // both terms are needed.) `filtered` is the same question asked of every
+  // backend, so any one of them saying yes is the answer. Null when no backend
+  // supplied one (old add-in / pane relay).
+  const catalog = catalogs.length
+    ? {
+        totalEngines: catalogs.reduce((n, c) => n + c.totalEngines, 0),
+        totalScopes: Math.max(...catalogs.map((c) => c.totalScopes), scopeRows.size),
+        filtered: catalogs.some((c) => c.filtered),
+        emptyEngines: catalogs.reduce((n, c) => n + c.emptyEngines, 0),
+      }
+    : null;
+  return { engines, catalog, envs };
 }
 
 // ---------------------------------------------------------------------------
@@ -1229,7 +1411,12 @@ function sleep(ms) {
 // mixed versions each get their own answer.
 const backendCapabilitiesCache = new Map();
 
-function backendCapabilities(backendURL) {
+// The probe result, failure included. Every ordinary caller wants the graceful
+// `{}` (an older backend simply 404s this path), but a caller that is DIAGNOSING
+// has to see a 401 — "this session is revoked" must never be reported as "this
+// add-in is too old". Kept as one cached promise so the distinction costs no
+// extra round-trip.
+function backendCapabilitiesResult(backendURL) {
   let probe = backendCapabilitiesCache.get(backendURL);
   if (!probe) {
     probe = (async () => {
@@ -1239,11 +1426,11 @@ function backendCapabilities(backendURL) {
           { timeoutMs: listTimeoutMs() },
           backendURL,
         );
-        return (await res.json()) ?? {};
-      } catch {
+        return { caps: (await res.json()) ?? {}, error: null };
+      } catch (err) {
         // Older backends 404 this path (with a non-JSON body) — no
         // capabilities: sync render, no version floor.
-        return {};
+        return { caps: {}, error: err };
       }
     })();
     backendCapabilitiesCache.set(backendURL, probe);
@@ -1251,6 +1438,10 @@ function backendCapabilities(backendURL) {
   return probe;
 }
 
+async function backendCapabilities(backendURL) {
+  return (await backendCapabilitiesResult(backendURL)).caps;
+}
+
 async function backendSupportsRenderJobs(backendURL) {
   const caps = await backendCapabilities(backendURL);
   return caps?.renderJobs === true;
@@ -1283,6 +1474,35 @@ export async function backendSupportsImageGeneration(backendURL) {
   return caps?.imageGeneration === true;
 }
 
+// Whether a backend can list the corporate designs a user may build against
+// (`GET /api/cli/brands`). It is what lets `ready` bind a deck with PowerPoint
+// closed — without it the only way to learn a design's identity is an open
+// window. Advertised by newer add-ins only.
+export async function backendSupportsBrandsList(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.brandsList === true;
+}
+
+// Whether a backend can read the SOURCE deck behind a chosen slide search
+// result (`/api/cli/presentations/:presId/source-presentation`). Advertised by
+// newer add-ins only; older ones omit the flag and the caller must say so
+// rather than surfacing a bare 404.
+export async function backendSupportsSourcePresentation(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.sourcePresentation === true;
+}
+
+// Pane-free ENGINE routes (`/api/cli/engines`, `/api/cli/searches/*`): engine
+// discovery, search and every per-result fetch answered off the CLI session
+// itself instead of being relayed through the task-pane webview — the one
+// transport that a backgrounded PowerPoint is free to suspend mid-run.
+// Advertised by newer add-ins only; older ones keep the pane relay, which stays
+// as the compat path (see the direct-route block further down).
+export async function backendSupportsEngineRoutes(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.engineRoutes === true;
+}
+
 // The add-in's hard version floor: /api/cli/capabilities advertises the oldest
 // CLI it still speaks (`minCliVersion`). An older CLI must refuse to proceed —
 // mid-rollout skew otherwise surfaces as confusing route/contract errors deep
@@ -1573,6 +1793,22 @@ export async function translateDeck({
   return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
+// A 404 the RELAY emitted about the presId itself (the window is no longer in
+// the registry — a pane reconnect mints a new presId for the same window)
+// rather than one a ROUTE emitted about something else it was asked for (a
+// stale `unknown_search`, an unimplemented route). Only the former is worth
+// re-targeting: the same window is probably back under a new id.
+//
+// Read the PARSED code, never `err.code`: bridgeFetch falls that back to the
+// human error string, and the relay's vanished-presId 404 carries prose only
+// ("No PowerPoint window registered for presId='X'") — so testing `err.code`
+// saw a truthy, unmatched value and never retargeted anything.
+function isMissingPresentationError(err) {
+  if (err?.status !== 404) return false;
+  const code = err?.body?.code ?? null;
+  return !code || code === "unknown_presentation" || code === "presentation_not_found";
+}
+
 // Run a pane-relayed engine op; on `pane_suspended` (the server already waited
 // ~25s for a reconnect) OR `pane_timeout` (the pane looked connected but never
 // acked within the server's 60s window — the server marks it suspended on the
@@ -1581,22 +1817,282 @@ export async function translateDeck({
 // presId churn too). Engine ops are idempotent reads, and the one mutation
 // (live insert) rides the SAME operationId through the retry so the pane-side
 // dedup makes a re-send safe.
-async function engineOpWithPaneWait(presId, backendURL, attempt) {
+//
+// `fileName`/`brandId` identify the WINDOW so the wait can re-match it after a
+// presId churn (see waitForPaneReady). `retargetOnMissing` additionally treats a
+// vanished presId as recoverable — opt-in, because for most engine ops a 404 is
+// the search record talking, not the window: it re-lists the registry, re-matches
+// by presFP and retries ONCE on a short budget before the caller surfaces the
+// wake-PowerPoint blocker.
+async function engineOpWithPaneWait(
+  presId,
+  backendURL,
+  attempt,
+  {
+    fileName = null,
+    brandId = null,
+    otherPresIds = null,
+    retargetOnMissing = false,
+  } = {},
+) {
   try {
     return await attempt(presId, backendURL);
   } catch (err) {
-    if (err?.code !== "pane_suspended" && err?.code !== "pane_timeout") {
-      throw err;
-    }
+    const suspended =
+      err?.code === "pane_suspended" || err?.code === "pane_timeout";
+    const churned = retargetOnMissing && isMissingPresentationError(err);
+    if (!suspended && !churned) throw err;
     const live = await waitForPaneReady(presId, {
       backendURL,
-      onWait: paneWaitNotice,
+      fileName,
+      brandId,
+      otherPresIds,
+      // A churned presId needs a re-list, not a user: the window is already
+      // there under a new id, so poll briefly instead of holding the full
+      // click-the-pane budget. A suspended pane keeps that budget.
+      timeoutMs: churned && !suspended ? envInt("SLIDEMIND_BRIDGE_PANE_RETARGET_TIMEOUT_MS", 15000) : null,
+      onWait: churned && !suspended ? paneRetargetNotice : paneWaitNotice,
     });
     if (!live) throw err;
     return attempt(live.presId, live.backendURL ?? backendURL);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Pane-free engine routes (the DIRECT path)
+// ---------------------------------------------------------------------------
+//
+// Newer add-ins serve the whole engine surface off the CLI session:
+//   GET  /api/cli/engines                                  catalog (same path,
+//                                                          answered pane-free)
+//   POST /api/cli/searches                                 → { searchId, results }
+//   GET  /api/cli/searches/:id/results/:sel/image           stream
+//   GET  /api/cli/searches/:id/results/:sel/thumbnail       stream
+//   GET  /api/cli/searches/:id/results/:sel/slide           stream (one-slide .pptx)
+//   GET  /api/cli/searches/:id/results/:sel/source-presentation
+//
+// The searchId is SERVER-owned (per user, short TTL) rather than bound to a
+// window's pane, and a request carries only that searchId plus the selection
+// index — the server resolves the source config it stored at search time, so no
+// client ever names a file, site or drive.
+//
+// How a function picks its path: a `presId` means "relay through THAT window"
+// (the compat path old add-ins need and live insert always needs); NO presId
+// plus an explicit `backendURL`/`brandId` means "run this pane-free". Callers
+// resolve the backend once with resolveEngineBackend(), which returns null when
+// nothing paired advertises the routes — that null is the signal to fall back
+// to the pane relay, never a failure.
+
+function searchRoute(searchId, suffix = "") {
+  return `/api/cli/searches/${encodeURIComponent(String(searchId))}${suffix}`;
+}
+
+// A searchId is a number on the pane relay (the pane mints it per window) and an
+// opaque server-minted id on the direct routes — accept either, reject anything
+// else before a call goes near the network.
+function assertSearchId(fn, searchId) {
+  const ok =
+    (typeof searchId === "number" && Number.isFinite(searchId)) ||
+    (typeof searchId === "string" && searchId.trim().length > 0);
+  if (!ok) throw new Error(`${fn}: searchId is required`);
+}
+
+// A large asset legitimately takes longer than an engine op: the server is
+// fetching from SharePoint/blob AND piping. Separate budget so raising it
+// doesn't loosen every other bridge call.
+function downloadTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000", 10) ||
+    600000
+  );
+}
+
+function resultRoute(searchId, selection, leaf, params = null) {
+  const qs = params && [...params.keys()].length > 0 ? `?${params}` : "";
+  return `${searchRoute(searchId, `/results/${encodeURIComponent(String(selection))}/${leaf}`)}${qs}`;
+}
+
+// Per-process memo of which backend serves a brand's engine routes, so a
+// multi-environment session pays the brand probe at most once per design.
+const engineBackendForBrand = new Map();
+
+// A searchId is opaque (server-minted, hex) on the direct routes and numeric on
+// the pane relay. The distinction routes: an opaque id names a record on the
+// backend that minted it, and the pane can NEVER serve it — its handler only
+// understands its own per-window numeric ids.
+export function isOpaqueSearchId(searchId) {
+  return (
+    typeof searchId === "string" &&
+    searchId.trim() !== "" &&
+    !/^\d+$/.test(searchId.trim())
+  );
+}
+
+// Which paired backend minted this server-owned search record. Search records
+// are oid-scoped, so a foreign environment answers the same 404 as an expired
+// id — probing every engine-routes candidate with the record's own GET is both
+// exact and cheap (2h TTL, at most a couple of environments). Returns null when
+// no candidate holds it: expired, or minted by an environment no longer in
+// scope. Never falls back to the pane — see isOpaqueSearchId.
+//
+// One failure class is NOT routing information: a 401 means the session itself
+// is dead (revoked in the add-in's Connect CLI panel, or aged past its hard
+// lifetime). Swallowing it reports a revoked session as "that search expired",
+// and the user then re-runs a search that 401s the same way. So per-candidate
+// failures are collected and a session-invalid one is rethrown instead.
+export async function resolveSearchBackend(searchId) {
+  if (!isOpaqueSearchId(searchId)) return null;
+  const failures = [];
+  for (const s of sessionsInScope()) {
+    // A revoked session 401s the capability probe too, and that answer is
+    // indistinguishable from "old add-in" unless the failure is kept.
+    const probe = await backendCapabilitiesResult(s.backendURL);
+    if (probe.error && isSessionInvalidError(probe.error)) {
+      failures.push(probe.error);
+      continue;
+    }
+    if (probe.caps?.engineRoutes !== true) continue;
+    try {
+      await bridgeFetch(searchRoute(searchId), {}, s.backendURL);
+      return s.backendURL;
+    } catch (err) {
+      // 404 (not this environment's record / expired) or unreachable — try the
+      // next candidate; the distinction doesn't matter to routing.
+      failures.push(err);
+    }
+  }
+  // The two failures that are NOT the record talking: a dead session, and a
+  // permission snapshot that has aged out (the record re-read is an engine
+  // route, so it degrades with the rest of corpus search). Reported as "that
+  // search expired", both send the user to re-run a search that fails the same
+  // way — so they outrank the expired-record answer.
+  const blocking = failures.find(
+    (e) => isSessionInvalidError(e) || e?.code === "permissions_stale",
+  );
+  if (blocking) throw blocking;
+  return null;
+}
+
+// Which paired backend runs the pane-free engine routes for this call. An
+// explicit backendURL is honoured as-is (the caller already resolved a window or
+// a deck). Otherwise: every session in scope that advertises the routes is a
+// candidate — with ONE connected environment (the normal case) that IS the
+// answer, and no probe is worth paying for it. With several connected, the
+// DECK's bound design decides, never an open window's origin. presFP/brandId is
+// content-derived, so the SAME design onboarded in two environments carries the
+// SAME id — candidates are therefore probed FIRST, and only when none serves
+// the design does the caller fall back to the pane relay (the design lives on
+// an older add-in, and searching a different corpus would fold ITS slides into
+// this deck). Returns null for that fallback and when nothing paired serves the
+// routes at all.
+export async function resolveEngineBackend({ backendURL = null, brandId = null } = {}) {
+  if (backendURL) {
+    return (await backendSupportsEngineRoutes(backendURL)) ? backendURL : null;
+  }
+  const sessions = sessionsInScope();
+  const candidates = [];
+  for (const s of sessions) {
+    if (await backendSupportsEngineRoutes(s.backendURL)) candidates.push(s.backendURL);
+  }
+  if (candidates.length === 0) return null;
+  // Exactly one CONNECTED environment: there is nothing else the deck could
+  // belong to. Note the test is on the sessions, not on the candidates — during
+  // a rollout only one of several environments serves the routes, and taking it
+  // regardless would have searched the wrong corpus.
+  if (sessions.length === 1) return candidates[0];
+  if (brandId) {
+    // The memo only stands while that environment is still a candidate.
+    const memo = engineBackendForBrand.get(brandId);
+    if (memo) return candidates.includes(memo) ? memo : null;
+    // Candidates first: an environment that serves both the design AND the
+    // engine routes wins outright, even when an older environment also has the
+    // (content-identical) design.
+    for (const be of candidates) {
+      try {
+        await getDesignBundleForBrand(brandId, { backendURL: be });
+        engineBackendForBrand.set(brandId, be);
+        return be;
+      } catch {
+        // This candidate doesn't serve the design — try the next.
+      }
+    }
+    try {
+      const { backendURL: be } = await getDesignBundleForBrandAnyBackend(brandId);
+      engineBackendForBrand.set(brandId, be);
+      // Only a non-candidate can answer here: the design's environment is an
+      // older add-in with no engine routes. null sends the caller to that
+      // environment's pane relay instead of a different corpus.
+      return null;
+    } catch {
+      // No backend owns the design (unknown brand, old add-in) — fall through
+      // rather than guessing an environment.
+    }
+  }
+  if (candidates.length === 1) return candidates[0];
+  const err = new Error(
+    `Several connected environments run engine search (${candidates
+      .map((u) => deriveEnvLabel(u))
+      .join(", ")}). Scope the command with --backend <env>, point it at a ` +
+      "bound deck (--deck) so the deck's design picks one, or name an open " +
+      "window with --to <presId> to relay through it.",
+  );
+  err.code = "engine_backend_ambiguous";
+  throw err;
+}
+
+// Which connected environments answer the pane-free engine routes — the
+// "backend authoring ready" half of the readiness picture (`doctor`, `ready`),
+// reported as ENV LABELS so no URL can reach a printed line. Pass
+// connectionStatus()'s `backends` to skip environments that are already known
+// unreachable; without it every session in scope is probed.
+export async function engineReachability({ backends = null } = {}) {
+  const urls = Array.isArray(backends)
+    ? backends.filter((b) => b?.ok && b.backendURL).map((b) => b.backendURL)
+    : sessionsInScope().map((s) => s.backendURL);
+  const envs = [];
+  for (const url of urls) {
+    if (await backendSupportsEngineRoutes(url)) envs.push(deriveEnvLabel(url));
+  }
+  return { available: envs.length > 0, envs };
+}
+
+// Resolve + verify the backend for a direct engine call. Throws a typed
+// `engine_routes_unavailable` when the caller asked for the pane-free path on a
+// backend that doesn't serve it — a programming error by then, since callers go
+// through resolveEngineBackend first, but it must never surface as a bare 404.
+async function directEngineBackend(fn, { backendURL = null, brandId = null }) {
+  const be = backendURL ?? (await resolveEngineBackend({ brandId }));
+  if (be && (await backendSupportsEngineRoutes(be))) return be;
+  const err = new Error(
+    `${fn}: no connected slidemind add-in serves pane-free engine routes` +
+      `${be ? ` ('${deriveEnvLabel(be)}' is too old)` : ""}. ` +
+      "Open PowerPoint with the slidemind pane so the search can be relayed, or update the add-in.",
+  );
+  err.code = "engine_routes_unavailable";
+  throw err;
+}
+
+// The permission SNAPSHOT behind corpus search is refreshed whenever the add-in
+// runs; when it ages out the engine routes answer
+// `403 { error: "permissions_stale", action: "…" }` and only corpus search
+// degrades (render/bundle never do). Shape it like the connection ladder's rungs
+// — `{ code, actor, message }` — so the CLI can print ONE actionable line and an
+// agent knows it cannot clear this one itself. Returns null for any other error.
+export function permissionsStaleBlocker(err) {
+  if (err?.code !== "permissions_stale") return null;
+  const action =
+    typeof err?.body?.action === "string" && err.body.action.trim()
+      ? err.body.action.trim()
+      : "open the slidemind add-in once to refresh access";
+  return {
+    code: "permissions_stale",
+    actor: "user",
+    message:
+      `slidemind needs your search permissions refreshed before it can search the corpus — ${action}. ` +
+      "Everything else (render, bundle, imagery already downloaded) keeps working.",
+  };
+}
+
 // 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 results (image thumbnails, or
@@ -1608,8 +2104,12 @@ async function engineOpWithPaneWait(presId, backendURL, attempt) {
 // an unfiltered search over the whole corpus rather than one engine's saved
 // folder filter. A scope has no subtype to derive its index from, so it needs an
 // explicit `resultType`; the add-in rejects a scope search without one.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this runs pane-free
+// against `POST /api/cli/searches` (same body) and tags the answer with the
+// backend that owns the searchId.
 export async function engineSearch({
-  presId,
+  presId = null,
   engineId,
   query,
   subtype = null,
@@ -1617,22 +2117,42 @@ export async function engineSearch({
   intent = null,
   top = null,
   backendURL = null,
+  brandId = 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 direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("engineSearch: presId is required");
   const body = { engineId, query };
   if (subtype) body.subtype = subtype;
   // Additive: omitted unless set, so the body an older add-in sees is unchanged.
   if (resultType) body.resultType = resultType;
   if (intent) body.intent = intent;
   if (typeof top === "number") body.top = top;
+  if (direct) {
+    const be = await directEngineBackend("engineSearch", { backendURL, brandId });
+    const res = await bridgeFetch(
+      "/api/cli/searches",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: timeoutMs ?? engineTimeoutMs(),
+      },
+      be,
+    );
+    const data = (await res.json()) ?? {};
+    // Tag the routing state (like the brand routes do) so every follow-up pick
+    // hits the backend that owns the searchId. `env` is the printable half —
+    // callers must never surface backendURL.
+    return { ...data, backendURL: be, env: deriveEnvLabel(be) };
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
   const run = async (pid, b) => {
     const res = await bridgeFetch(
       `/api/cli/presentations/${encodeURIComponent(pid)}/engine/search`,
@@ -1730,6 +2250,11 @@ export async function engineSearchAnyPane({
 // Fetch a chosen engine result's bytes through the local bridge. For image
 // engines this returns SVG/PNG bytes (+ optional recoloured svgMarkup) WITHOUT
 // inserting onto a slide.
+//
+// Pane-only by design: the pane-free route table streams (see
+// engineDownloadToFile), and this base64-through-the-ack path only exists for
+// add-ins that predate streaming — which by definition predate the direct
+// routes too.
 export async function engineDownload({
   presId,
   searchId,
@@ -1738,9 +2263,7 @@ export async function engineDownload({
   backendURL = null,
 }) {
   if (!presId) throw new Error("engineDownload: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("engineDownload: searchId (number) is required");
-  }
+  assertSearchId("engineDownload", searchId);
   if (typeof selection !== "number") {
     throw new Error("engineDownload: selection (number) is required");
   }
@@ -1777,46 +2300,32 @@ export async function engineDownload({
 // byte stream: it is kilobytes and its recolour happens pane-side. Callers get
 // `{ svgMarkup }` in that case and `{ bytesWritten, mimeType }` otherwise, so they
 // can persist whichever arrived.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
+// from `GET /api/cli/searches/:searchId/results/:selection/image` — same answer
+// shape, no window involved.
 export async function engineDownloadToFile({
-  presId,
+  presId = null,
   searchId,
   selection,
   destPath,
   iconColor = null,
   backendURL = null,
+  brandId = null,
   onProgress = null,
 }) {
-  if (!presId) throw new Error("engineDownloadToFile: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("engineDownloadToFile: searchId (number) is required");
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) {
+    throw new Error("engineDownloadToFile: presId is required");
   }
+  assertSearchId("engineDownloadToFile", searchId);
   if (typeof selection !== "number") {
     throw new Error("engineDownloadToFile: selection (number) is required");
   }
   if (!destPath) throw new Error("engineDownloadToFile: destPath is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { searchId, selection };
-  if (iconColor) body.iconColor = iconColor;
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeStreamToFile(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        // A large image legitimately takes longer than an engine op: the server
-        // is fetching from SharePoint/blob AND piping. Separate budget so raising
-        // it doesn't loosen every other relay call.
-        timeoutMs:
-          parseInt(
-            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
-            10,
-          ) || 600000,
-        onProgress,
-      },
-      destPath,
-      b,
-    );
+  // Both paths answer with the same two shapes (streamed bytes, or the inline
+  // SVG as JSON), so the response shaping is authored once.
+  const shape = (res) => {
     if (!res.streamed) {
       // The inline-SVG answer (kilobytes) arrives as JSON, not as a byte stream.
       const parsed = res.body ? JSON.parse(res.body) : {};
@@ -1838,6 +2347,41 @@ export async function engineDownloadToFile({
       bytesWritten: res.bytesWritten,
       ...(warnings ? { warnings } : {}),
     };
+  };
+  if (direct) {
+    const b = await directEngineBackend("engineDownloadToFile", {
+      backendURL,
+      brandId,
+    });
+    // Only the recolour rides the query string — the RESOURCE is never
+    // client-supplied on this path; the server resolves it from searchId+selection.
+    const params = new URLSearchParams();
+    if (iconColor) params.set("iconColor", iconColor);
+    const res = await bridgeStreamToFile(
+      resultRoute(searchId, selection, "image", params),
+      { method: "GET", timeoutMs: downloadTimeoutMs(), onProgress },
+      destPath,
+      b,
+    );
+    return shape(res);
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { searchId, selection };
+  if (iconColor) body.iconColor = iconColor;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    return shape(res);
   });
 }
 
@@ -1846,22 +2390,47 @@ export async function engineDownloadToFile({
 // request, and the add-in server performs it and pipes the (base64-decoded) bytes
 // here. `extractSlide` puts the whole slide through the pane's Socket.IO ack as
 // base64, so it is capped at ~7 MB of real bytes — which real reused slides reach.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
+// from `GET /api/cli/searches/:searchId/results/:selection/slide`.
 export async function extractSlideToFile({
-  presId,
+  presId = null,
   searchId,
   selection,
   destPath,
   backendURL = null,
+  brandId = null,
   onProgress = null,
 }) {
-  if (!presId) throw new Error("extractSlideToFile: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("extractSlideToFile: searchId (number) is required");
-  }
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("extractSlideToFile: presId is required");
+  assertSearchId("extractSlideToFile", searchId);
   if (typeof selection !== "number") {
     throw new Error("extractSlideToFile: selection (number) is required");
   }
   if (!destPath) throw new Error("extractSlideToFile: destPath is required");
+  const shape = (res) => {
+    const title = res.headers?.["x-slidemind-presentation-title"];
+    return {
+      ok: true,
+      bytesWritten: res.bytesWritten,
+      slideId: res.headers?.["x-slidemind-slide-id"] ?? undefined,
+      presentationTitle: title ? decodeURIComponent(String(title)) : undefined,
+    };
+  };
+  if (direct) {
+    const b = await directEngineBackend("extractSlideToFile", {
+      backendURL,
+      brandId,
+    });
+    const res = await bridgeStreamToFile(
+      resultRoute(searchId, selection, "slide"),
+      { method: "GET", timeoutMs: downloadTimeoutMs(), onProgress },
+      destPath,
+      b,
+    );
+    return shape(res);
+  }
   const be = backendURL || (await resolveBackendForPres(presId));
   return engineOpWithPaneWait(presId, be, async (pid, b) => {
     const res = await bridgeStreamToFile(
@@ -1870,29 +2439,21 @@ export async function extractSlideToFile({
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ searchId, selection }),
-        timeoutMs:
-          parseInt(
-            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
-            10,
-          ) || 600000,
+        timeoutMs: downloadTimeoutMs(),
         onProgress,
       },
       destPath,
       b,
     );
-    const title = res.headers?.["x-slidemind-presentation-title"];
-    return {
-      ok: true,
-      bytesWritten: res.bytesWritten,
-      slideId: res.headers?.["x-slidemind-slide-id"] ?? undefined,
-      presentationTitle: title ? decodeURIComponent(String(title)) : undefined,
-    };
+    return shape(res);
   });
 }
 
 // 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.
+// the pane like search/download, and pane-only for the same reason as
+// engineDownload: the pane-free route streams (extractSlideToFile above), and
+// this capped ack path exists only for add-ins that predate it.
 export async function extractSlide({
   presId,
   searchId,
@@ -1900,9 +2461,7 @@ export async function extractSlide({
   backendURL = null,
 }) {
   if (!presId) throw new Error("extractSlide: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("extractSlide: searchId (number) is required");
-  }
+  assertSearchId("extractSlide", searchId);
   if (typeof selection !== "number") {
     throw new Error("extractSlide: selection (number) is required");
   }
@@ -1926,17 +2485,23 @@ export async function extractSlide({
 
 // Insert one or more chosen slide-search results live into the open
 // presentation (the "reuse → insert live" path). Relayed through the pane.
+//
+// `fileName`/`brandId` identify the target WINDOW (brandId == the deck's presFP).
+// They cost nothing on the happy path and are what lets the single retry find
+// the same window again after a pane reconnect churned its presId — the same
+// self-healing `push` does around its insert.
 export async function insertSlideLive({
   presId,
   searchId,
   selections,
   at = null,
   backendURL = null,
+  fileName = null,
+  brandId = null,
+  otherPresIds = null,
 }) {
   if (!presId) throw new Error("insertSlideLive: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("insertSlideLive: searchId (number) is required");
-  }
+  assertSearchId("insertSlideLive", searchId);
   if (!Array.isArray(selections) || selections.length === 0) {
     throw new Error("insertSlideLive: selections (number[]) is required");
   }
@@ -1950,54 +2515,279 @@ export async function insertSlideLive({
   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,
+      );
+      // Tag the window the insert actually landed in: after a retarget it is no
+      // longer the presId the caller passed, and the caller reports it.
+      return { ...(await res.json()), presId: pid }; // { ok, insertedCount, insertedSlideIds, presId }
+    },
+    // A vanished presId is recoverable HERE (unlike the engine reads, whose
+    // 404s are about the search record): the insert never landed, so re-listing
+    // and retrying against the re-registered window is safe — and the same
+    // operationId rides along, so even an ambiguous first attempt can't
+    // double-insert.
+    { fileName, brandId, otherPresIds, retargetOnMissing: true },
+  );
+}
+
+// Reuse chosen slide-search results live when the search record is the
+// BACKEND's rather than a pane's.
+//
+// The pane's slide-insert handler resolves a selection out of the in-browser
+// search context IT minted (a numeric id); a searchId from the pane-free search
+// is server-owned and opaque, so relaying it would answer `searchId_required`.
+// The two legs `add-slide --search` + `push` already run therefore do the job in
+// the other order: extract each pick pane-free, then hand the BYTES to the
+// window's own insert route. Live insert stays pane-bound (Office.js is the only
+// thing that can type into an open deck) — only the searchId resolution moves.
+export async function insertSlidesFromSearch({
+  presId,
+  searchId,
+  selections,
+  at = null,
+  backendURL = null,
+  engineBackendURL = null,
+  fileName = null,
+  brandId = null,
+  otherPresIds = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("insertSlidesFromSearch: presId is required");
+  assertSearchId("insertSlidesFromSearch", searchId);
+  if (!Array.isArray(selections) || selections.length === 0) {
+    throw new Error("insertSlidesFromSearch: selections (number[]) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-reuse-"));
+  try {
+    let insertedCount = 0;
+    let livePresId = presId;
+    let liveBackendURL = be;
+    const insertedSlideIds = [];
+    for (const [i, selection] of selections.entries()) {
+      const slidePath = path.join(dir, `pick-${selection}.pptx`);
+      const extracted = await extractSlideToFile({
+        searchId,
+        selection,
+        destPath: slidePath,
+        backendURL: engineBackendURL,
+        brandId,
+        onProgress,
+      });
+      if (!extracted?.bytesWritten) {
+        throw new Error(`selection ${selection} produced no slide bytes`);
+      }
+      // One insert per pick, each with its own dedup key, so a retry inside
+      // engineOpWithPaneWait re-sends THAT pick and nothing else. `at` counts
+      // forward so the picks land in the order they were named.
+      const operationId = `insert-${randomUUID()}`;
+      const base64 = fs.readFileSync(slidePath).toString("base64");
+      const resp = await engineOpWithPaneWait(
+        livePresId,
+        liveBackendURL,
+        async (pid, b) => {
+          const ack = await insertSlides({
+            presId: pid,
+            base64,
+            insertAt: typeof at === "number" ? at + i : null,
+            sourceSlideIds: extracted.slideId ? [extracted.slideId] : null,
+            operationId,
+            backendURL: b,
+          });
+          return { ...ack, presId: pid, backendURL: b };
+        },
+        { fileName, brandId, otherPresIds, retargetOnMissing: true },
+      );
+      // A retarget moves every remaining pick to the window that answered, so
+      // a multi-pick reuse cannot end up split across two presentations.
+      livePresId = resp.presId ?? livePresId;
+      liveBackendURL = resp.backendURL ?? liveBackendURL;
+      const landed = Array.isArray(resp.insertedSlideIds)
+        ? resp.insertedSlideIds
+        : [];
+      insertedCount += landed.length || 1;
+      insertedSlideIds.push(...landed);
+      fs.rmSync(slidePath, { force: true });
+    }
+    return { ok: true, insertedCount, insertedSlideIds, presId: livePresId };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// 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.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this reads the pane-free
+// `GET …/results/:selection/thumbnail`, which STREAMS: a thumbnail is small, so
+// it is buffered back into the same `{ dataUri }` contract rather than forcing
+// every caller to grow a file path.
+export async function viewSlide({
+  presId = null,
+  searchId,
+  selection,
+  backendURL = null,
+  brandId = null,
+}) {
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("viewSlide: presId is required");
+  assertSearchId("viewSlide", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("viewSlide: selection (number) is required");
+  }
+  if (direct) {
+    const b = await directEngineBackend("viewSlide", { backendURL, brandId });
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-thumb-"));
+    const tmp = path.join(dir, "thumbnail.bin");
+    try {
+      const res = await bridgeStreamToFile(
+        resultRoute(searchId, selection, "thumbnail"),
+        { method: "GET", timeoutMs: engineTimeoutMs() },
+        tmp,
+        b,
+      );
+      if (!res.streamed) {
+        // An add-in that answers with an inline preview passes straight through.
+        return res.body ? JSON.parse(res.body) : { ok: false };
+      }
+      const mimeType =
+        String(res.headers?.["content-type"] ?? "").split(";")[0].trim() ||
+        "image/png";
+      return {
+        ok: true,
+        mimeType,
+        dataUri: `data:${mimeType};base64,${fs.readFileSync(tmp).toString("base64")}`,
+      };
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
   return engineOpWithPaneWait(presId, be, async (pid, b) => {
     const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-insert`,
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-view`,
       {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
+        body: JSON.stringify({ searchId, selection }),
         timeoutMs:
           parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
           90000,
       },
       b,
     );
-    return res.json(); // { ok, insertedCount, insertedSlideIds }
+    return res.json(); // { ok, dataUri, mimeType }
   });
 }
 
-// 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,
+// Read the ORIGINAL deck a chosen slide-search result came from — NOT the open
+// window (that is getPresentationContent below). Answers "what else is in the
+// presentation this slide belongs to?": the surrounding narrative, the slides
+// either side, the argument the source deck was making.
+//
+// The add-in reads it out of the slide index rather than downloading the source
+// file, so this is fast and works the same for blob- and SharePoint-backed
+// results — but the text is the last SYNCED extraction, not the live file. The
+// response is Markdown, and the pane never carries it: the relay route resolves
+// the selection through the pane and performs the backend read itself.
+//
+// searchId is presentation-scoped on the pane path, so that path relays through
+// the window the search ran on, like viewSlide. Idempotent, so the
+// pane_suspended retry is safe. With NO presId and a resolved
+// `backendURL`/`brandId` it reads the pane-free
+// `GET …/results/:selection/source-presentation` instead (the searchId is
+// server-owned there, so no window is involved at all).
+export async function readSourcePresentation({
+  presId = null,
   searchId,
   selection,
+  fromSlide = null,
+  toSlide = null,
   backendURL = null,
+  brandId = null,
 }) {
-  if (!presId) throw new Error("viewSlide: presId is required");
-  if (typeof searchId !== "number") {
-    throw new Error("viewSlide: searchId (number) is required");
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) {
+    throw new Error("readSourcePresentation: presId is required");
   }
+  assertSearchId("readSourcePresentation", searchId);
   if (typeof selection !== "number") {
-    throw new Error("viewSlide: selection (number) is required");
+    throw new Error("readSourcePresentation: selection (number) is required");
+  }
+  // Both paths answer with Markdown plus the counts/truncation in headers.
+  const shape = async (res) => ({
+    ok: true,
+    markdown: await res.text(),
+    truncated: res.headers?.["x-slidemind-truncated"] === "1",
+    slideCount: Number(res.headers?.["x-slidemind-slide-count"] ?? 0) || 0,
+    totalSlideCount:
+      Number(res.headers?.["x-slidemind-total-slide-count"] ?? 0) || 0,
+    presentationTitle: res.headers?.["x-slidemind-presentation-title"]
+      ? decodeURIComponent(String(res.headers["x-slidemind-presentation-title"]))
+      : undefined,
+  });
+  if (direct) {
+    // The direct route table carries source-presentation, so engineRoutes is the
+    // capability that gates it here (sourcePresentation gates the pane route).
+    const b = await directEngineBackend("readSourcePresentation", {
+      backendURL,
+      brandId,
+    });
+    const params = new URLSearchParams();
+    if (typeof fromSlide === "number") params.set("fromSlide", String(fromSlide));
+    if (typeof toSlide === "number") params.set("toSlide", String(toSlide));
+    const res = await bridgeFetch(
+      resultRoute(searchId, selection, "source-presentation", params),
+      {
+        method: "GET",
+        headers: { accept: "text/markdown, text/plain" },
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return shape(res);
   }
   const be = backendURL || (await resolveBackendForPres(presId));
+  if (!(await backendSupportsSourcePresentation(be))) {
+    const err = new Error(
+      "This slidemind add-in cannot read a result's source presentation yet. Update the add-in, then try again.",
+    );
+    err.code = "source_presentation_unsupported";
+    throw err;
+  }
+  const body = { searchId, selection };
+  if (typeof fromSlide === "number") body.fromSlide = fromSlide;
+  if (typeof toSlide === "number") body.toSlide = toSlide;
   return engineOpWithPaneWait(presId, be, async (pid, b) => {
     const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-view`,
+      `/api/cli/presentations/${encodeURIComponent(pid)}/source-presentation`,
       {
         method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ searchId, selection }),
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-          90000,
+        headers: {
+          "content-type": "application/json",
+          accept: "text/markdown, text/plain",
+        },
+        body: JSON.stringify(body),
+        timeoutMs: engineTimeoutMs(),
       },
       b,
     );
-    return res.json(); // { ok, dataUri, mimeType }
+    return shape(res);
   });
 }