slidemind 0.0.27 → 0.0.29

package/README.md

@@ -72,7 +72,7 @@ If `slidemind presentations` returns nothing, the add-in isn't running — open
 
 ## Icon / image search
 
-`slidemind search "<query>"` searches the active corporate design's **brand engine** (icons/images) over the local bridge — proxied to the open PowerPoint task pane, so it returns the same results the in-app design agent sees (an open host is required). It prints a `searchId` plus numbered results; the agent then fetches a chosen result into the deck's `assets/` via the MCP tool `slidemind_download_result`. The agent-facing flow (`slidemind_search_engine` → `slidemind_download_result`) is owned by the add-in's design bundle and read by the skill. There is no local icon library anymore.
+`slidemind search "<query>"` searches the active corporate design's **brand engine** (icons/images) over the local bridge, using the add-in's server-side bridge when available so it returns the same results the in-app design agent sees (an open host is required). It prints a `searchId` plus numbered results; the agent then fetches a chosen result into the deck's `assets/` via the MCP tool `slidemind_download_result`. The agent-facing flow (`slidemind_search_engine` → `slidemind_download_result`) is owned by the add-in's design bundle and read by the skill. There is no local icon library anymore.
 
 ## Install into a coding-agent harness
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -34,7 +34,7 @@ Authoring and rendering hard-require an **open PowerPoint host with the slidemin
 2. One registered → that's your target `presentation_id`. **Several → ask the user which**, by `title`/`fileName` (never raw ids) — once for **which presentation's corporate design to download**, and again at render time for **which presentation to push into** (the CD source and the push target may be different presentations).
 3. **None registered → stop.** Tell the user: *open PowerPoint, load the slidemind add-in, and pick or create a corporate design, then retry.*
 
-**Connections drop when PowerPoint is backgrounded — try first, reconnect only on failure.** The add-in's task pane suspends when PowerPoint isn't the focused app, so its bridge connection can drop and `slidemind presentations` may briefly go empty even though PowerPoint is still open with a deck. So **always just run the command first — never pre-emptively ask the user to do anything.** Only if a command fails with *no host registered* (or a bridge-connection error) do you ask the user to **click into PowerPoint and focus the slidemind task pane** so it reconnects, then **retry the same command** — the deck and bundle are already prepared, so it's just a re-run. Reserve the full "open PowerPoint…" instruction in (3) for when nothing is registered at all.
+**Backgrounded PowerPoint is expected to work.** Do not pre-emptively ask the user to focus PowerPoint or the task pane. The bridge retains the registered presentation and pane-free routes keep working; live push/replace waits for the task-pane socket to reconnect if it truly dropped. Only if a command fails with *no host registered* (or a bridge wait timeout) do you ask the user to click the slidemind task pane once so it reconnects, then retry the same command — the deck and bundle are already prepared. Reserve the full "open PowerPoint…" instruction in (3) for when nothing is registered at all.
 
 Local HTML preview (`slidemind build`) runs offline, but it reads a **previously materialized bundle** — so the host must have been available at least once.
 
@@ -56,9 +56,9 @@ Keep planning about intent and content. Don't materialize the bundle or read bra
    - `corporate-design.css`, `layouts/*.jsx`, `layouts/layouts.css`, `assets/`, `samples/` (the brand's own reference slides), `engines.json`.
    - `workflow/` — the add-in-owned authoring craft: `create.md`, `edit.md`, `composition.md`, `layouts.md`, `authoring.md`, `build-and-export.md`.
 3. **Study brand samples (before composing).** The materialized bundle's `samples/` dir holds the brand's own reference slides. If it's non-empty, pick **3 at random** and **Read** each (the Read tool renders images) *before* writing any JSX — this is the local-harness stand-in for the in-app persona's reference thumbnails, and it is what keeps a deck looking on-brand rather than merely compliant. Study them for whitespace rhythm, shape density, hierarchy, accent use, and layering, then compose in that spirit (never copy a sample 1:1). This is `composition.md`'s samples discipline; skip only when `samples/` is empty.
-4. **Read, then author.** Read `workflow/create.md` (the procedure), `workflow/layouts.md` + `workflow/authoring.md` (how to compose + the substrate rules), and the deck's `design.md` + the specific `layouts/*.jsx` the plan uses. Then write `decks/<slug>/slides/*.jsx` — one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe. Pull in `workflow/composition.md` when the plan has 3+ parallel ideas, a repeated skeleton, a pacing/rhythm need, or a slide that's merely compliant.
+4. **Read, then author.** Read the four create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written.) Then write `decks/<slug>/slides/*.jsx` — one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe.
 5. **Imagery from the engine.** Per the `### Brand Image Sources` block in `design.md`, search the brand engine and place results (see the command mapping — this is `engine_search`/`engine_add` in the workflow docs).
-6. **Render / push.** `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file) — both render server-side. This is `build_and_push` in `workflow/build-and-export.md`. If several presentations are open, confirm **which one to push into** first (it can differ from the CD source). **Run the push without asking otherwise**; if it fails because the host disconnected (PowerPoint was backgrounded / the task pane suspended), ask the user to focus PowerPoint and retry — don't rebuild anything, just re-run `push`.
+6. **Render / push.** `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file) — both render server-side. This is `build_and_push` in `workflow/build-and-export.md`. If several presentations are open, confirm **which one to push into** first (it can differ from the CD source). **Run the push without asking otherwise**; it should work while PowerPoint is backgrounded. If it times out waiting for a true task-pane reconnect, ask the user to click the slidemind task pane once and re-run `push` without rebuilding.
 7. **Sanity pass.** Run the checks in `workflow/create.md` before reporting done.
 
 ## Recolouring engine icons (CLI specifics)

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

@@ -10,10 +10,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 
 import {
   insertSlides,
-  listOpenPresentations,
   pickPresentation,
   renderPptx,
   replaceSlides,
@@ -128,86 +128,31 @@ export async function buildAndPush({
   const base64 = result.base64;
   const bytes = Buffer.byteLength(base64, "base64");
   const mode = replace ? "replace" : "insert";
+  const operationId = `push-${randomUUID()}`;
 
   const doPush = () =>
     replace
-      ? replaceSlides({ presId, base64 })
-      : insertSlides({ presId, base64, insertAt, sourceSlideIds: slideIds });
+      ? replaceSlides({ presId, base64, operationId })
+      : insertSlides({
+          presId,
+          base64,
+          insertAt,
+          sourceSlideIds: slideIds,
+          operationId,
+        });
 
-  let resp;
-  try {
-    resp = await pushWithPaneRetry(doPush, presId);
-  } catch (err) {
-    // The pane stayed backgrounded through every retry. The render already
-    // succeeded (it's pane-free), so don't lose it: write the bytes to
-    // <deck>.pptx and report a clean, resumable outcome instead of throwing.
-    if (err && err.code === "pane_suspended") {
-      const fallbackFile = path.join(deckDir, `${path.basename(deckDir)}.pptx`);
-      fs.writeFileSync(fallbackFile, Buffer.from(base64, "base64"));
-      return {
-        presId,
-        mode,
-        bytes,
-        paneSuspended: true,
-        fallbackFile,
-        warnings: result.warnings ?? [],
-        skippedSlides: result.skippedSlides ?? [],
-      };
-    }
-    throw err;
-  }
+  const resp = await doPush();
   return {
     presId,
     mode,
     bytes,
+    operationId,
     response: resp,
     warnings: result.warnings ?? [],
     skippedSlides: result.skippedSlides ?? [],
   };
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-// Push into the live deck (insert/replace) tolerating a transiently backgrounded
-// task pane. Retry ONLY the definitive pre-ack `pane_suspended` (the registry
-// entry exists but its socket is gone, so the emit provably never happened —
-// re-sending the same bytes is safe). NEVER retry a `bridge_timeout`: there the
-// emit may have been delivered, and insert is append-only, so a retry could
-// double-insert.
-async function pushWithPaneRetry(doPush, presId, attempts = 3) {
-  let lastErr;
-  for (let i = 0; i < attempts; i++) {
-    try {
-      return await doPush();
-    } catch (err) {
-      if (!err || err.code !== "pane_suspended") throw err;
-      lastErr = err;
-      if (i === attempts - 1) break;
-      // Give the user a moment to foreground PowerPoint; resolve as soon as the
-      // pane re-registers as connected, up to a growing window.
-      await waitForConnected(presId, 2000 * (i + 1));
-    }
-  }
-  throw lastErr;
-}
-
-async function waitForConnected(presId, windowMs) {
-  const deadline = Date.now() + windowMs;
-  while (Date.now() < deadline) {
-    try {
-      const reg = (await listOpenPresentations()).find(
-        (p) => p.presId === presId,
-      );
-      // `connected` is undefined against an older add-in — treat that as ready
-      // so we still retry rather than stall.
-      if (reg && reg.connected !== false) return;
-    } catch {
-      /* bridge momentarily unreachable; keep polling within the window */
-    }
-    await sleep(500);
-  }
-}
-
 // Render a deck to a .pptx file (the `slidemind build-pptx` path). Still
 // requires an open host because the render happens server-side.
 export async function buildPptxFile({

package/src/bridge/bundle.mjs

@@ -358,16 +358,27 @@ export function loadEnginesForDeck(deckDir) {
   return readEnginesFromDir(resolveBundleDirForDeck(deckDir));
 }
 
-// Pick the default engine to search: the first image/icon engine, else the
-// first engine. Single source of truth for the heuristic shared by the CLI
-// dispatcher (`slidemind search`) and the MCP `slidemind_search_engine` tool.
+// Image-producing engine kinds — the modality "image" plus the finer image
+// content kinds an authored bundle may carry. Excludes "slide" (a slide-search
+// engine returns whole slides, not insertable bytes). Mirrors the add-in's
+// local-bridge `engine_not_image` gate so the CLI never picks an engine the
+// bridge would reject.
+const IMAGE_ENGINE_KIND_RE = /^(image|icon|photo|illustration|vector)$/i;
+
+// True when an engine produces insertable image bytes. Gates on the engine's
+// real `kind` (its modality from the design bundle) — NOT a guess over its
+// label/description.
+export function isImageEngine(engine) {
+  return IMAGE_ENGINE_KIND_RE.test(engine?.kind ?? "");
+}
+
+// Pick the default engine to search: the first image engine, by its real
+// `kind`. Returns null when the CD exposes no image engine (e.g. only a
+// slide-search engine) — callers surface a "wire an image engine" message
+// rather than falling back to an engine the bridge can't insert. Single source
+// of truth for the heuristic shared by the CLI dispatcher (`slidemind search`)
+// and the MCP `slidemind_search_engine` tool.
 export function pickImageEngine(engines) {
   const list = Array.isArray(engines) ? engines : [];
-  return (
-    list.find((e) =>
-      /image|icon/i.test(`${e.kind ?? ""} ${e.label ?? ""} ${e.description ?? ""}`),
-    ) ||
-    list[0] ||
-    null
-  );
+  return list.find(isImageEngine) ?? null;
 }

package/src/bridge/client.mjs

@@ -127,7 +127,8 @@ function nodeRequest(urlString, init = {}) {
   }
 
   const timeoutMs =
-    parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000;
+    init.timeoutMs ??
+    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
   return new Promise((resolve, reject) => {
     const req = transport.request(
       url,
@@ -232,9 +233,9 @@ export async function renderPptx({
   return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
-// Brand-engine search, proxied through the open task pane. Engine-agnostic
-// (image/icon engines today; slide engines later). Returns a searchId + a
-// numbered set of result thumbnails for the agent to choose from.
+// 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 }) {
   if (!presId) throw new Error("engineSearch: presId is required");
   if (!engineId) throw new Error("engineSearch: engineId is required");
@@ -250,9 +251,9 @@ export async function engineSearch({ presId, engineId, query }) {
   return res.json(); // { ok, searchId, resultCount, gridDataUri, thumbnails }
 }
 
-// Fetch a chosen engine result's bytes (proxied through the task pane). For
-// image engines this returns SVG/PNG bytes (+ optional recoloured svgMarkup)
-// WITHOUT inserting onto a slide.
+// 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.
 export async function engineDownload({
   presId,
   searchId,
@@ -279,22 +280,31 @@ export async function engineDownload({
   return res.json(); // { ok, base64, mimeType, svgMarkup }
 }
 
-export async function insertSlides({ presId, base64, insertAt = null, sourceSlideIds = null }) {
+export async function insertSlides({
+  presId,
+  base64,
+  insertAt = null,
+  sourceSlideIds = null,
+  operationId = null,
+}) {
   if (!presId) throw new Error("insertSlides: presId is required");
   if (!base64) throw new Error("insertSlides: base64 is required");
-  const body = { base64, insertAt, sourceSlideIds };
+  const body = { base64, insertAt, sourceSlideIds, operationId };
   const res = await bridgeFetch(
     `/local/presentations/${encodeURIComponent(presId)}/insert`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
     },
   );
   return res.json().catch(() => ({}));
 }
 
-export async function replaceSlides({ presId, base64 }) {
+export async function replaceSlides({ presId, base64, operationId = null }) {
   if (!presId) throw new Error("replaceSlides: presId is required");
   if (!base64) throw new Error("replaceSlides: base64 is required");
   const res = await bridgeFetch(
@@ -302,7 +312,10 @@ export async function replaceSlides({ presId, base64 }) {
     {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ base64 }),
+      body: JSON.stringify({ base64, operationId }),
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
     },
   );
   return res.json().catch(() => ({}));

package/src/builders/resolve-skill.mjs

@@ -44,6 +44,26 @@ function firstExisting(candidates) {
   return null;
 }
 
+// Does a design root actually carry brand files? A root qualifies if it has the
+// corporate-design CSS or a layouts dir that holds at least one real layout
+// (a `*.jsx` or `layouts.css`). A bare/junk-only `layouts/` — e.g. one left
+// behind on disk holding only a macOS `.DS_Store` — must NOT count, or it would
+// mask the "materialize the bundle first" guidance for a deck that hasn't
+// downloaded one yet.
+function carriesDesign(root, cssName) {
+  if (!root) return false;
+  if (fs.existsSync(path.join(root, cssName))) return true;
+  const layoutsDir = path.join(root, "layouts");
+  if (!fs.existsSync(layoutsDir)) return false;
+  try {
+    return fs
+      .readdirSync(layoutsDir)
+      .some((f) => f.endsWith(".jsx") || f === "layouts.css");
+  } catch {
+    return false;
+  }
+}
+
 // First existing candidate, or `fallback` when none exist. Encodes the
 // deck-override → bundle → skill precedence in one place so every resolved path
 // shares the same lookup rule.
@@ -73,12 +93,7 @@ export function resolveSkill(skillName, planMeta = {}, opts = {}) {
   const designRoots = [
     bundleDir,
     fs.existsSync(skillDir) ? skillDir : null,
-  ].filter(
-    (r) =>
-      r &&
-      (fs.existsSync(path.join(r, cssName)) ||
-        fs.existsSync(path.join(r, "layouts"))),
-  );
+  ].filter((r) => carriesDesign(r, cssName));
   if (designRoots.length === 0) {
     throw new Error(
       `No design source for skill "${skillName}". The corporate design now lives ` +

package/src/mcp/server.mjs

@@ -7,8 +7,8 @@
 //
 // Tools:
 //   slidemind_list_open_presentations
-//     Lists PowerPoint windows that have the slidemind add-in connected to
-//     the local bridge.
+//     Lists PowerPoint windows registered with the local bridge, including
+//     retained entries whose task-pane socket is temporarily disconnected.
 //
 //   slidemind_push_deck
 //     Renders a deck server-side via the add-in and pushes its slides into one
@@ -16,7 +16,7 @@
 //
 //   slidemind_search_engine
 //     Searches the active corporate design's brand engine (icons/images today,
-//     slide engines later) over the bridge — proxied to the open task pane.
+//     slide engines later) over the bridge.
 //
 //   slidemind_download_result
 //     Fetches a chosen search result's bytes and writes them into a deck's
@@ -66,12 +66,13 @@ function errorResult(err) {
   let text = err && err.message ? err.message : String(err);
   const code = err && err.code;
   // Known transient states are recoverable without rebuilding anything — tell
-  // the agent exactly how to resume so it pauses for a pane focus instead of
-  // aborting the deck.
+  // the agent exactly how to resume if the bridge timed out waiting for a true
+  // task-pane reconnect. Normal backgrounded PowerPoint should not reach this.
   if (code === "pane_suspended") {
     text +=
-      "\n\nRecoverable: ask the user to click the slidemind task pane to bring " +
-      "PowerPoint to the foreground, then retry this call — nothing needs rebuilding.";
+      "\n\nRecoverable: the render is already done, but the task-pane bridge did " +
+      "not reconnect before the wait timeout. Ask the user to click the slidemind " +
+      "task pane once so it reconnects, then retry this same call.";
   } else if (code === "engine_auth_expired") {
     text +=
       "\n\nRecoverable: ask the user to click the slidemind task pane for ~1s so " +
@@ -140,7 +141,7 @@ server.registerTool(
   {
     title: "List open PowerPoint windows",
     description:
-      "List PowerPoint windows that currently have the slidemind add-in connected to the local bridge. " +
+      "List PowerPoint windows registered with the slidemind local bridge, including retained entries whose task-pane socket is temporarily disconnected. " +
       "Each entry has a stable presId — pass it as `presentation_id` to slidemind_push_deck. " +
       "If the list is empty the user has no PowerPoint open with the add-in loaded.",
     inputSchema: {},
@@ -202,23 +203,6 @@ server.registerTool(
         replace: replace === true,
         slideIds: slide_ids ?? null,
       });
-      if (result.paneSuspended) {
-        return {
-          content: [
-            {
-              type: "text",
-              text:
-                "PowerPoint is backgrounded, so the rendered slides couldn't be " +
-                "inserted yet. The render succeeded and was saved to " +
-                `${result.fallbackFile}. Ask the user to click the slidemind task ` +
-                "pane to bring PowerPoint to the foreground, then call " +
-                "slidemind_push_deck again — the deck is already built, so this " +
-                "just retries the insert.",
-            },
-          ],
-          isError: true,
-        };
-      }
       return textResult(result);
     } catch (err) {
       return errorResult(err);
@@ -232,7 +216,7 @@ server.registerTool(
     title: "Search the brand engine for imagery",
     description:
       "Search the active corporate design's brand engine over the bridge (icons/images today; slide engines later). " +
-      "Proxied to the open PowerPoint task pane, so it returns the SAME results the in-app design agent sees. " +
+      "Uses the add-in's server-side bridge when available, so it returns the SAME results the in-app design agent sees. " +
       "Returns a searchId and a numbered set of result thumbnails (and a grid image you can view). " +
       "Pick a number, then call slidemind_download_result with the searchId + selection. " +
       "engine_id is optional — omit it to use the corporate design's first image engine.",