slidemind 0.1.5 → 0.1.6

package/skills/search/SKILL.md

@@ -14,9 +14,10 @@ So this file owns only what is genuinely CLI-specific: the **host precondition**
 This skill drives the `slidemind` CLI + its MCP server (`slidemind_list_open_presentations`, `slidemind_list_engines`, `slidemind_search_engine`, `slidemind_view_slide`, `slidemind_insert_slide`, `slidemind_add_slide_to_deck`, `slidemind_download_result`). The CLI reaches PowerPoint through the add-in's **cloud relay** — it doesn't run any local server. Patch what's missing yourself; the **pairing** step needs the user once (they hold the add-in's identity):
 
 - **CLI missing** (`slidemind` not on `PATH`, or the `slidemind_*` MCP tools absent): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` (registers the MCP server + (re)deploys this skill). The harness may need a restart for the `slidemind_*` tools to appear.
-- **Not paired** (a command says *slidemind is not paired*): the one step you can't do for the user. Tell them: in the slidemind add-in click **"Connect CLI"**, then paste the shown `slidemind pair …` command into this terminal. It's one-time per environment. `slidemind whoami` lists every paired environment.
+- **Not paired** (a command says *slidemind is not paired*): the one step you can't do for the user. Tell them: in the slidemind add-in open **Settings → General → Connect CLI**, press **Pair**, and run the shown one-time `slidemind pair <code>` command in this terminal (the code expires in ~10 min — re-press **Pair** for a fresh one). It's one-time per environment; `slidemind whoami` lists every paired environment.
+- **Restart the add-in once after pairing** — the wizard never says this. If, right after pairing, `slidemind presentations` still doesn't list the window even though PowerPoint is open with the add-in and a corporate design active, ask the user to **restart the add-in** (close + reopen the slidemind task pane; if it still doesn't appear, reopen PowerPoint) so the freshly-paired pane registers on the relay. Then retry.
 
-This is the same bootstrap as `slidemind-create-slides`; if you set it up there it's already set up here.
+This is the same bootstrap as `slidemind-create-slides` (whose **Pairing the CLI with the add-in** section has the full step-by-step + triage table); if you set it up there it's already set up here.
 
 ## Precondition gate (check this first, every time)
 
@@ -26,7 +27,7 @@ Engine search and slide reuse are **pane-touching, host-required** operations
 2. **≥1 registered → you're set.** The engine catalog is **per-user, not bound to a window**, so search and discovery attach to **any** connected window automatically. **Never ask the user which window to search with**, and don't pass `--to`/`presentation_id` to search just to disambiguate — leave it off and let the CLI grab one. (A window only matters when you *insert a slide live*, and even then it's simply the window the search already ran on — see Reuse.)
 3. **None registered → stop.** Tell the user: *open PowerPoint, load the slidemind add-in, and pick or create a corporate design, then retry.*
 
-> **Empty list vs. not paired — different fixes.** An *empty* registry means no PowerPoint is connected (ask the user to open it / enable Connect CLI). A *not paired* error means this machine has no session — ask the user to pair once via **"Connect CLI"** (see Bootstrap). They are different problems; don't conflate them.
+> **Empty list vs. not paired — different fixes.** An *empty* registry with no PowerPoint connected means open it / enable Connect CLI. A *not paired* error means this machine has no session — pair once via **"Connect CLI"** (see Bootstrap). An *empty* registry **while** PowerPoint is open with the add-in **and** this machine is already paired usually means a just-paired pane that never registered — ask the user to **restart the add-in** (see Bootstrap), then retry. Three different problems; don't conflate them.
 
 The pane-touching ops here (`search`, `view_slide`, `insert-slide`, `download-result`) wait for the pane themselves: the CLI waits up to ~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries safely. Relay that line once and keep waiting — don't re-plan or babysit.
 
@@ -49,6 +50,8 @@ A found slide can be reused two ways. Both extract the picked result(s) as nativ
 
 > **The durable rule:** a slide folded into a deck with `add-slide` is **deck source-of-truth**. The render pipeline splices native `slides/*.pptx` into the deck **by play-order filename**, alongside any authored `.jsx`, so a reused slide **survives every `build-pptx` and `push` re-render** — it is never lost on re-push. Reorder it the same way you reorder JSX: rename its numeric prefix.
 
+> **Building a `.pptx` file from found slides → one combined deck, always.** When the user wants the reused slides as a **`.pptx` file** (rather than a live insert), collect **every** picked slide into **one** deck and render **one** file — never one `.pptx` per slide and never a deck per slide. Fold all picks into the same deck — pass every selection in a single `add-slide` call (`--pick n1,n2,…`), repeating only to cover picks that came from different `searchId`s (always the same `--deck`) — then run `slidemind build-pptx <deck>` once. The render splices every native `slides/*.pptx` into a **single `decks/<slug>/<slug>.pptx`** in play-order, so all the found slides land in one file. That combined `.pptx` is the deliverable; hand back its path. (Need new authored slides interleaved with the reused ones in that same file? That's still one deck — hand off to `slidemind-create-slides` to add the JSX, then `build-pptx` the whole deck once.)
+
 For brand **imagery** (icons/images, not whole slides), the reuse step is `slidemind_download_result` — it writes the asset into the deck's `assets/`. That mechanism (including the icon-recolor descriptor) is documented where it's used, in `slidemind-create-slides`.
 
 ## Working with slidemind-create-slides

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

@@ -1,5 +1,9 @@
 // Render a deck server-side via the bridge, then push the bytes into a running
-// PowerPoint window (or write them to a file).
+// PowerPoint window (or write them to a file). Also hosts `viewDraft` — the
+// push-free, .pptx-free draft preview (the CLI analog of the persona's
+// `see_draft`): it runs the shipped capture engine locally and returns the
+// per-slide preview PNGs it already produces, so the agent can look before the
+// `review` gate.
 //
 // The CLI ships ZERO exporter code: the authored slide JSX + deck-local assets
 // are POSTed to the add-in's `render-pptx` route, which renders them against
@@ -17,7 +21,7 @@ import {
   pickPresentationEntry,
   renderPptx,
   replaceSlides,
-  requireHost,
+  requireRenderHost,
   translateDeck,
   waitForPaneReady,
 } from "./client.mjs";
@@ -177,6 +181,181 @@ export async function renderDeckToBase64(
   return result; // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
+// Map ONE captured slide to a draft-view entry. The capture engine produces a
+// `previewDataUrl` (the 1280×720 stage PNG) only for FREEFORM slides that go
+// through the Chrome box capture — purpose-built (Mode A) layouts have no
+// freeform region and so carry no preview, exactly like the add-in's see_draft.
+// Degraded renders still yield a flat raster the agent can look at; lint/parse
+// failures surface as a status line so the agent is never blind.
+function mapCapturedSlide(fileName, cap, warnings) {
+  if (!cap) {
+    return {
+      fileName,
+      status: "missing",
+      note: "the capture engine produced no result for this slide",
+    };
+  }
+  for (const w of cap.lint?.warnLines ?? []) warnings.push(`${fileName}: ${w}`);
+  for (const w of cap.render?.warnings ?? []) warnings.push(`${fileName}: ${w}`);
+
+  if (cap.previewDataUrl) {
+    return { fileName, status: "ok", dataUri: cap.previewDataUrl };
+  }
+  // A degraded render is a non-editable raster; push/build-pptx will REJECT it.
+  // Attach it anyway (so the agent isn't blind) but flag the named cause.
+  if (cap.render?.degraded && cap.render?.fallbackPngBase64) {
+    return {
+      fileName,
+      status: "degraded",
+      dataUri: `data:image/png;base64,${cap.render.fallbackPngBase64}`,
+      note:
+        `did NOT render cleanly (degraded ${cap.render.degraded} raster, not editable shapes) — ` +
+        `push/build-pptx will reject it as-is. Fix the named cause in the JSX: ` +
+        (cap.render.errorText ?? "unknown render failure"),
+    };
+  }
+  if (cap.lint?.errorMessage) {
+    return { fileName, status: "failed", note: cap.lint.errorMessage };
+  }
+  if (cap.captureError) {
+    return { fileName, status: "failed", note: cap.captureError };
+  }
+  // No preview and no error: a purpose-built (Mode A) layout has no freeform
+  // region to capture — there is simply nothing to draft-preview for it.
+  return {
+    fileName,
+    status: "no-preview",
+    note: "no preview rendered — a purpose-built layout has no freeform region to capture (use slidemind review for a full-deck look)",
+  };
+}
+
+// Render a deck's authored slides to per-slide preview PNGs WITHOUT pushing,
+// translating, or assembling a .pptx — the CLI analog of the add-in persona's
+// `see_draft`. It runs the add-in's shipped capture engine on THIS machine's
+// Chrome (the same engine the local-capture render path uses) and returns the
+// `previewDataUrl` it already produces, so the agent can LOOK at its slides and
+// self-correct before the user ever sees them at the `review` gate.
+//
+// Host-free once the bundle is materialized: the capture runs locally against
+// the cached bundle, so no open PowerPoint is needed. A host is required ONLY
+// when the bundle (and its capture engine) isn't cached yet — then we fetch it
+// like `download-bundle` does. Returns { slides: [{fileName, dataUri?, status,
+// note?}], warnings: [] }.
+export async function viewDraft(
+  deckDir,
+  { presentationId = null, onProgress = null } = {},
+) {
+  if (!deckDir) throw new Error("viewDraft: deckDir is required");
+  const slidesDir = path.join(deckDir, "slides");
+  if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
+    throw new Error(`Expected 'slides/' folder in ${deckDir}`);
+  }
+  // Authored JSX + reused native .pptx share one play-order namespace, exactly
+  // as the render path sees them — walk them in that order so the draft view
+  // lines up with the deck the user will get.
+  const all = sortSlideFilenames(
+    fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
+  );
+  if (all.length === 0) {
+    throw new Error(`No .jsx or .pptx slides under ${slidesDir}`);
+  }
+  const hasJsx = all.some((f) => f.endsWith(".jsx"));
+
+  // Resolve the materialized bundle. Local capture needs the bundle's capture
+  // engine; once it's cached this whole call is offline. Only reach for a host
+  // (to fetch the bundle) when there are JSX slides and no usable cached engine.
+  let ref = readDeckBundleRef(deckDir);
+  let bundleDir = resolveBundleDirForDeck(deckDir);
+  if (hasJsx && (!bundleDir || !bundleHasCaptureEngine(bundleDir))) {
+    const registry = await requireRenderHost();
+    const entry = pickPresentationEntry(registry, presentationId, {
+      preferBrandId: ref?.presFP ?? null,
+    });
+    const mat = await materializeBundle(entry.presId, {
+      backendURL: entry.backendURL ?? null,
+      preferBrandId: ref?.presFP ?? null,
+    });
+    writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+    bundleDir = resolveBundleDirForDeck(deckDir);
+  }
+
+  const warnings = [];
+
+  // A native-only deck (just reused .pptx) has no authored JSX to draft-preview.
+  if (!hasJsx) {
+    return {
+      slides: all.map((fileName) => ({
+        fileName,
+        status: "native",
+        note: "reused native slide — not authored JSX, no draft preview rendered",
+      })),
+      warnings,
+    };
+  }
+
+  if (!bundleDir || !bundleHasCaptureEngine(bundleDir)) {
+    throw new Error(
+      "draft preview needs the corporate design's capture engine, which ships in the " +
+        "materialized bundle. Run `slidemind download-bundle <deck>` against an open " +
+        "PowerPoint host once, then retry — or use `slidemind build <deck>` for a " +
+        "host-free HTML preview.",
+    );
+  }
+
+  let captured;
+  try {
+    captured = await captureDeckLocally({ deckDir, bundleDir, onProgress });
+  } catch (err) {
+    throw new Error(
+      `local draft capture failed (${err instanceof Error ? err.message : String(err)}). ` +
+        "It runs a local headless Chrome; if Chrome can't launch here, use " +
+        "`slidemind build <deck>` for an HTML preview instead.",
+    );
+  }
+
+  const byFile = new Map((captured?.slides ?? []).map((s) => [s.fileName, s]));
+  const slides = all.map((fileName) =>
+    fileName.endsWith(".pptx")
+      ? {
+          fileName,
+          status: "native",
+          note: "reused native slide — not authored JSX, no draft preview rendered",
+        }
+      : mapCapturedSlide(fileName, byFile.get(fileName), warnings),
+  );
+
+  return { slides, warnings };
+}
+
+async function renderWithRetarget(deckDir, entry, onProgress) {
+  const run = (target) =>
+    renderDeckToBase64(deckDir, {
+      presId: target.presId,
+      backendURL: target.backendURL ?? null,
+      onProgress,
+    });
+  try {
+    return { entry, result: await run(entry) };
+  } catch (err) {
+    const recoverable =
+      err?.status === 404 || err?.code === "unknown_presentation";
+    if (!recoverable) throw err;
+    const live = await waitForPaneReady(entry.presId, {
+      backendURL: entry.backendURL ?? null,
+      fileName: entry.fileName ?? entry.title ?? null,
+      brandId: entry.brandId ?? null,
+      timeoutMs: 15000,
+      onWait: (seconds) =>
+        process.stderr.write(
+          "render target changed — waiting for the slidemind pane to " +
+            `re-register (up to ${seconds}s)…\n`,
+        ),
+    });
+    if (!live) throw err;
+    return { entry: live, result: await run(live) };
+  }
+}
+
 export async function buildAndPush({
   deckDir,
   presentationId = null,
@@ -200,18 +379,15 @@ export async function buildAndPush({
   }
 
   const deckRef = readDeckBundleRef(deckDir);
-  const registry = await requireHost();
+  const registry = await requireRenderHost();
   const entry = pickPresentationEntry(registry, presentationId, {
     preferBrandId: deckRef?.presFP ?? null,
   });
-  const presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
-
-  const result = await renderDeckToBase64(deckDir, {
-    presId,
-    backendURL,
-    onProgress,
-  });
+  const rendered = await renderWithRetarget(deckDir, entry, onProgress);
+  const renderEntry = rendered.entry;
+  const presId = renderEntry.presId;
+  const backendURL = renderEntry.backendURL ?? null;
+  const result = rendered.result;
   const base64 = result.base64;
   const bytes = Buffer.byteLength(base64, "base64");
   const mode = replace ? "replace" : "insert";
@@ -255,8 +431,8 @@ export async function buildAndPush({
     if (!recoverable) throw err;
     const live = await waitForPaneReady(presId, {
       backendURL,
-      fileName: entry.fileName ?? entry.title ?? null,
-      brandId: entry.brandId ?? null,
+      fileName: renderEntry.fileName ?? renderEntry.title ?? null,
+      brandId: renderEntry.brandId ?? null,
       onWait: (seconds) =>
         process.stderr.write(
           "task pane suspended — click the slidemind pane in PowerPoint to " +
@@ -309,16 +485,16 @@ export async function buildPptxFile({
 }) {
   if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
   const deckRef = readDeckBundleRef(deckDir);
-  const registry = await requireHost();
+  const registry = await requireRenderHost();
   const entry = pickPresentationEntry(registry, presentationId, {
     preferBrandId: deckRef?.presFP ?? null,
   });
-  const presId = entry.presId;
-  const result = await renderDeckToBase64(deckDir, {
-    presId,
-    backendURL: entry.backendURL ?? null,
+  const { entry: renderEntry, result } = await renderWithRetarget(
+    deckDir,
+    entry,
     onProgress,
-  });
+  );
+  const presId = renderEntry.presId;
   const out =
     outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
   fs.writeFileSync(out, Buffer.from(result.base64, "base64"));

package/src/bridge/client.mjs

@@ -41,6 +41,13 @@ function engineTimeoutMs() {
   );
 }
 
+function readinessTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_READY_TIMEOUT_MS || "20000", 10) ||
+    20000
+  );
+}
+
 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.";
@@ -251,6 +258,69 @@ async function listPresentationsForBackend(backendURL) {
   });
 }
 
+async function readinessForBackend(backendURL) {
+  const env = deriveEnvLabel(backendURL);
+  try {
+    const res = await bridgeFetch(
+      "/api/cli/readiness",
+      { timeoutMs: listTimeoutMs() },
+      backendURL,
+    );
+    const data = (await res.json()) ?? {};
+    const presentations = Array.isArray(data.presentations)
+      ? data.presentations.map((p) => ({ ...p, backendURL, env }))
+      : [];
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: data.readinessV1 === true,
+      capabilities: data.capabilities ?? null,
+      presentations,
+      summary: data.summary ?? null,
+    };
+  } catch (err) {
+    if (err?.status !== 404) throw err;
+    // Older add-ins do not serve /readiness. Fall back to the legacy
+    // presentations route and mark the result as a compatibility response.
+    const presentations = await listPresentationsForBackend(backendURL);
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: false,
+      capabilities: null,
+      presentations,
+      summary: null,
+    };
+  }
+}
+
+export async function connectionStatus() {
+  const sessions = sessionsInScope();
+  const settled = await Promise.allSettled(
+    sessions.map((s) => readinessForBackend(s.backendURL)),
+  );
+  const backends = settled.map((r, i) => {
+    const backendURL = sessions[i].backendURL;
+    const env = deriveEnvLabel(backendURL);
+    if (r.status === "fulfilled") return r.value;
+    return {
+      env,
+      backendURL,
+      ok: false,
+      error: r.reason?.message ? r.reason.message : String(r.reason),
+      presentations: [],
+    };
+  });
+  return {
+    paired: sessions.length > 0,
+    backendCount: sessions.length,
+    backends,
+    presentations: backends.flatMap((b) => b.presentations ?? []),
+  };
+}
+
 // Fan out across every backend in scope, concurrently. Never rejects: each
 // backend's outcome is partitioned into merged presentations vs. a failure
 // record, so one unreachable environment can't hide the others.
@@ -352,6 +422,93 @@ export async function requireHost() {
   );
 }
 
+function hasReadinessFields(p) {
+  return (
+    p &&
+    (typeof p.connectionState === "string" ||
+      typeof p.designState === "string" ||
+      (p.capabilities && typeof p.capabilities === "object"))
+  );
+}
+
+export function isRenderReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return true;
+  if (p.capabilities?.render === true) return true;
+  if (p.designState === "ready" && p.capabilities?.render !== false) return true;
+  return false;
+}
+
+export function isPaneReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return p.connected !== false && !p.suspendedAt;
+  if (p.capabilities?.paneOps === true) return true;
+  return (
+    p.connectionState === "connected" &&
+    p.connected !== false &&
+    !p.suspendedAt &&
+    p.connectionState !== "stale"
+  );
+}
+
+async function waitForReadyPresentation(predicate, { timeoutMs = null } = {}) {
+  const waitMs = timeoutMs ?? readinessTimeoutMs();
+  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const { presentations, unreachable } = await listOpenPresentationsDetailed();
+    if (presentations.some(predicate)) return presentations;
+    // Do not wait when nothing is registered at all. Waiting helps only for an
+    // already-open pane that is still hydrating brand/readiness metadata.
+    if (presentations.length === 0 || Date.now() >= deadline) {
+      return { presentations, unreachable, timedOut: presentations.length > 0 };
+    }
+    await sleep(pollMs);
+  }
+}
+
+export async function requireRenderHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isRenderReadyPresentation)) {
+    return first.presentations;
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isRenderReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited;
+    if (waited.presentations.some(isRenderReadyPresentation)) {
+      return waited.presentations;
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but no window is render-ready yet. " +
+        "Wait for the corporate design to finish matching, or pick/create a corporate design in the add-in, then retry.",
+    );
+  }
+  return requireHost();
+}
+
+export async function requirePaneHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isPaneReadyPresentation)) {
+    return first.presentations;
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isPaneReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited;
+    if (waited.presentations.some(isPaneReadyPresentation)) {
+      return waited.presentations;
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but the task pane is not ready for pane operations. " +
+        "Bring PowerPoint forward and click or reopen the slidemind pane, then retry.",
+    );
+  }
+  return 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
@@ -361,7 +518,7 @@ export async function requireHost() {
 //       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);
+  const live = matches.filter(isPaneReadyPresentation);
   if (preferBrandId) {
     const want = live.filter((m) => m.brandId === preferBrandId);
     if (want.length === 1) return want[0];
@@ -433,7 +590,7 @@ export async function waitForPaneReady(
       /* transient list failure — poll again until the deadline */
     }
     const connected = list.filter(
-      (p) => p.connected !== false && !p.suspendedAt,
+      (p) => isPaneReadyPresentation(p),
     );
     const same = connected.find((p) => p.presId === presId);
     if (same) return same;
@@ -1108,6 +1265,46 @@ export async function viewSlide({
   });
 }
 
+// Read the CURRENT content of an open presentation (the "pull content" path
+// behind `slidemind read` / slidemind_read_presentation). `mode` selects the
+// depth: "summary" returns a per-slide outline (index, layout, title, subtitle);
+// "raw" (default) returns each slide's full plain text — NOT the add-in's editing
+// markup. Unlike engine ops, content is WINDOW-BOUND: it reads THAT presentation,
+// so we resolve the origin backend from the presId and relay through that
+// window's pane. It's an idempotent read, so engineOpWithPaneWait's single
+// pane_suspended client-wait + retry against the live entry is safe (like viewSlide).
+export async function getPresentationContent({
+  presId,
+  mode = "raw",
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("getPresentationContent: presId is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { mode: mode === "summary" ? "summary" : "raw" };
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/content`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return res.json(); // { ok, mode, slideCount, slides }
+  });
+}
+
+function ensurePaneAckOk(data, operation) {
+  if (!data || data.ok !== false) return data ?? {};
+  const detail = data.error || `${operation} failed`;
+  const err = new Error(detail);
+  err.code = data.code || `${operation}_failed`;
+  err.body = data;
+  throw err;
+}
+
 export async function insertSlides({
   presId,
   base64,
@@ -1132,7 +1329,7 @@ export async function insertSlides({
     },
     be,
   );
-  return res.json().catch(() => ({}));
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "insert");
 }
 
 export async function replaceSlides({
@@ -1156,7 +1353,7 @@ export async function replaceSlides({
     },
     be,
   );
-  return res.json().catch(() => ({}));
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "replace");
 }
 
 // Pick a target presentation given the (possibly multi-backend) registry and an
@@ -1238,7 +1435,9 @@ export function pickAnyPresentationEntry(registry, explicitPresId, opts = {}) {
     );
   }
   return (
-    registry.find((p) => p.connected !== false && !p.suspendedAt) ?? registry[0]
+    registry.find(isPaneReadyPresentation) ??
+    registry.find((p) => p.connected !== false && !p.suspendedAt) ??
+    registry[0]
   );
 }