slidemind 0.0.27

package/skills/create-slides/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: slidemind-create-slides
+description: Author branded slide decks and individual slides against the active corporate design. Owns the user-facing intake → plan → create → edit workflow that turns per-slide .jsx files into editable .pptx (rendered server-side in PowerPoint) plus a local HTML preview. Reads the brand rules, layout palette, and authoring workflow from a materialized design bundle served by the slidemind PowerPoint add-in — it ships neither its own brand nor its own exporter. Use whenever the user asks for a slide, a deck, a presentation, a slideshow, or to convert content into one; interview them for intent and output format first, then stay on-brand by reading the bundle at every step. Skip when the user only wants to open, present, rename, search, or query an existing deck without authoring or editing slide content.
+---
+
+# slidemind-create-slides
+
+This skill is **thin workflow glue for the local harness**. Everything that determines how a deck is authored, styled, and rendered lives in the **slidemind PowerPoint add-in** and reaches you through a **materialized design bundle**:
+
+- The **brand** — tokens, `corporate-design.css`, the `design.md` brand rules, the closed layout palette, brand assets — is served per corporate design.
+- The **authoring workflow craft** — create, edit, composition, layouts, authoring contract, build/export — is the add-in's deployment-shipped `workflow/*.md`, served on the same bundle so the local harness reads **byte-identical** guidance to the in-app design agent.
+- The **`.pptx` render** happens server-side in the add-in. There is no local exporter.
+
+So this file owns only what is genuinely CLI-specific: the **host precondition**, a compact **intake/plan**, the **create flow**, and the **command mapping** that translates the add-in's in-app tool names (used throughout the bundle's `workflow/*.md`) into your `slidemind` commands and MCP tools. Read the workflow + brand from the bundle; never restate or duplicate them here.
+
+## Make sure the slidemind CLI is installed (npm)
+
+This skill drives the `slidemind` CLI and its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). If `slidemind` isn't on `PATH` — or those `slidemind_*` MCP tools aren't available — install the package from npm, then register it with the harness:
+
+```bash
+npm install -g slidemind
+slidemind init --for <claude|codex|opencode|all>   # registers the MCP server + (re)deploys this skill
+```
+
+- For a one-off command without a global install, `npx slidemind <command>` works.
+- `slidemind --version` confirms it's on `PATH`. `slidemind update` upgrades to the latest npm release (`--ref <version>` to pin).
+- If `slidemind init` just registered the MCP server, the harness may need a restart before the `slidemind_*` tools appear.
+
+## Precondition gate (check this first, every time)
+
+Authoring and rendering hard-require an **open PowerPoint host with the slidemind add-in loaded and an active corporate design**. Without a host there is no bundle to read and no renderer to push to; `download-bundle`, `build-pptx`, and `push` all fail.
+
+1. Run `slidemind presentations` (or MCP `slidemind_list_open_presentations`).
+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.
+
+Local HTML preview (`slidemind build`) runs offline, but it reads a **previously materialized bundle** — so the host must have been available at least once.
+
+## Intake → plan (you own this; do it in chat)
+
+The add-in's in-app flow has a manager do planning (`present_plan_for_review`); **here, you run it directly with the user.** Don't write slide JSX until the plan is agreed.
+
+- **Read scope from the wording**, don't ask redundantly: single slide ("make a slide about X"), small set ("add three slides on Y"), or whole deck ("a deck for Friday"). Only ask "one slide, a small set, or a full deck?" when truly ambiguous.
+- **Interview just enough** to pin: audience/goal, the content and its sources (none / pasted / local files / existing deck / web research), the **output format** (push into PowerPoint, `.pptx` file, HTML preview, or a mix), and the slide outline (each slide's role + a layout *job* like cover/agenda/section/quote/closing/body — the concrete brand layout is chosen later against the bundle).
+- **Replay and get sign-off.** Single slides / tiny sets → a compact in-chat plan. Decks → persist `decks/<slug>/plan.md` (content direction, narrative red thread, sources, per-slide role + layout job — *not* visual shape, *not* brand specifics). A valid existing `decks/<slug>/plan.md` counts as approved; restate what you're building.
+
+Keep planning about intent and content. Don't materialize the bundle or read brand/layout/composition detail until create/edit.
+
+## The create flow
+
+1. **Choose the host** (gate above) → `presentation_id`.
+2. **Materialize the bundle.** `slidemind download-bundle <deck> --to <presId>` downloads the active corporate design and binds the deck to it. The bundle dir is keyed by the deck's `.bundle-ref.json` → `${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/`. It contains:
+   - `design.md` — brand rules + authoring contract pointers + the `### Brand Image Sources` block (the brand source of truth — **read it**).
+   - `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.
+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`.
+7. **Sanity pass.** Run the checks in `workflow/create.md` before reporting done.
+
+## Recolouring engine icons (CLI specifics)
+
+Engine results land as files referenced with `<img src="./assets/<file>">`. The bundle's `workflow/*.md` are written for the in-app render; these two facts are specific to the local harness:
+
+- **Never open the SVG to find out whether it recolours.** `slidemind_download_result` returns a `recolor` descriptor — `{ recolorable, mode, applied, note }`, where `mode` is `currentColor`, `mono`, `multicolor`, or `raster`. Read it; that *is* the answer.
+- **Two ways to colour an icon, both honoured in the `slidemind build` preview *and* the render:**
+  - **Bake it in (prefer this):** pass `icon_color` — a hex you resolve from a token in the bundle's `corporate-design.css` — to `slidemind_download_result`. Works for any `recolorable` glyph and the colour is in the saved file, so preview and render always agree.
+  - **Tint via CSS:** set `color` to a token on the `<img>`. This works only for `mode: "currentColor"` icons (the preview inlines the SVG so `color` resolves, and the render substitutes `currentColor`). A `mono` icon will not respond to CSS colour — bake it instead.
+- **Batch the fetch.** Pull every icon a slide needs in one call via `selections: [{ selection, icon_color }, …]` — the downloads run concurrently. Don't call `slidemind_download_result` once per icon.
+
+## Command mapping (CLI ⇄ the bundle's `workflow/*.md`)
+
+The bundle's `workflow/*.md` are written for the in-app design agent and name **its** tools. You are the local harness — translate as you read:
+
+| In `workflow/*.md` (in-app agent) | Your equivalent (local harness) |
+|---|---|
+| `build_and_push` | `slidemind push <deck>` (into the open PowerPoint) · `slidemind build-pptx <deck>` (to a `.pptx` file) — both render server-side via the bridge |
+| `engine_search` | MCP `slidemind_search_engine({ presentation_id, query })` → returns a `searchId` + numbered results |
+| `engine_add` / `insert_image` | MCP `slidemind_download_result({ presentation_id, deck_path, search_id, selection, icon_color? })` — or batch many at once with `selections: [{ selection, icon_color? }, …]`. Writes each asset into `decks/<slug>/assets/`, returns a `./assets/<file>` reference for `<img src=...>` plus a `recolor` descriptor (see *Recolouring engine icons*) |
+| writing `slides/<topic>.jsx` in the chat workspace | write files under `decks/<slug>/slides/*.jsx` on disk |
+| reading workspace files (`design.md`, `layouts/`, `workflow/*`) | read them from the materialized bundle dir (`<bundle>/…`) and your `decks/<slug>/` |
+| reference-slide thumbnails injected at `add_slide` (in-app persona) | **Read** 3 random images from the materialized bundle's `samples/` dir — the Read tool renders them (see *The create flow* step 3) |
+| `present_plan_for_review` (manager-owned) | **you** run intake → plan with the user (above); persist `decks/<slug>/plan.md` for decks |
+
+Everything else in `workflow/*.md` — the composition craft, the substrate/authoring rules, the layout discovery and slot/working-area rules, the sanity bar — applies to you unchanged.
+
+## The brand and the workflow both live in the bundle, not here
+
+Do not restate brand values (colour, type scale, spacing, layout names, accent discipline) or re-derive the authoring/composition craft in this file or in slide files — they are in the bundle's `design.md` and `workflow/*.md`. Read them and follow them. Don't load external UI/design-taste plugins during slide work; compose against the bundle's layouts and tokens. If a render returns `bundle_etag_stale`, the corporate design moved — re-run `slidemind download-bundle <deck>` and re-read.
+
+## Failure modes the render lint can't catch
+
+Render-time lint rejects contract violations (deny-listed CSS, bad imports, remote `<img>` URLs — defined in the bundle's `design.md`). It can't catch content-shaped failures; check for these in the sanity pass:
+
+- Layout-default / placeholder text leaking through an unfilled prop.
+- A bullet list standing in for a structured idea (process, comparison, timeline).
+- An equal-card grid with no hero and no hierarchy.
+- Em dashes / curly quotes leaking from pasted source.
+- Hand-rolled glyphs instead of engine imagery.
+- Slide-local class names colliding with global token utility classes.
+- Internal composition vocabulary (`hero`, `focal`, …) rendered as visible text.
+
+## Where the deck lives
+
+`decks/<slug>/` is created in the **current working directory** (the shell's pwd when the skill was invoked). Every `slidemind` command and `mkdir` resolves `decks/` against that cwd — don't `cd` into the skill's install directory. The materialized bundle lives in the cache dir above, not under the deck.

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

@@ -0,0 +1,232 @@
+// Render a deck server-side via the bridge, then push the bytes into a running
+// PowerPoint window (or write them to a file).
+//
+// The CLI ships ZERO exporter code: the authored slide JSX + deck-local assets
+// are POSTed to the add-in's `render-pptx` route, which renders them against
+// the presentation's own corporate design using the SAME OOXML exporter the
+// in-app design persona uses. The returned base64 .pptx is then inserted /
+// replaced (push) or written to disk (build-pptx). An open PowerPoint host with
+// an active corporate design is therefore a hard precondition for both paths.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  insertSlides,
+  listOpenPresentations,
+  pickPresentation,
+  renderPptx,
+  replaceSlides,
+  requireHost,
+} from "./client.mjs";
+import {
+  materializeBundle,
+  readDeckBundleRef,
+  writeDeckBundleRef,
+} from "./bundle.mjs";
+
+function gatherSlides(deckDir) {
+  const slidesDir = path.join(deckDir, "slides");
+  if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
+    throw new Error(`Expected 'slides/' folder in ${deckDir}`);
+  }
+  const files = fs
+    .readdirSync(slidesDir)
+    .filter((f) => f.endsWith(".jsx"))
+    .sort();
+  if (files.length === 0) {
+    throw new Error(`No .jsx slides under ${slidesDir}`);
+  }
+  const slides = {};
+  for (const f of files) {
+    slides[f] = fs.readFileSync(path.join(slidesDir, f), "utf8");
+  }
+  return slides;
+}
+
+// Collect deck-local assets (icons the agent downloaded, deck photos) as
+// base64, keyed by their `assets/<rel>` path so the server-side renderer mounts
+// them where the slide JSX references them (`<img src="./assets/<rel>">`).
+function gatherDeckAssets(deckDir) {
+  const assetsDir = path.join(deckDir, "assets");
+  const out = {};
+  if (!fs.existsSync(assetsDir)) return out;
+  const walk = (dir, prefix) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(abs, rel);
+      } else {
+        out[`assets/${rel}`] = fs.readFileSync(abs).toString("base64");
+      }
+    }
+  };
+  walk(assetsDir, "");
+  return out;
+}
+
+// Render a deck to base64 .pptx over the bridge. Pass the deck's authored-against
+// bundle etag (when recorded) so the server can detect CD skew.
+export async function renderDeckToBase64(deckDir, { presId }) {
+  const slides = gatherSlides(deckDir);
+  const deckAssets = gatherDeckAssets(deckDir);
+  // Bind the deck to a materialized bundle if it isn't already. Without a
+  // `.bundle-ref.json` the etag below is null (server-side skew detection
+  // silently no-ops) AND the local HTML/editor preview can't resolve the
+  // deck's design files. `download-bundle <deck>` normally writes this; here we
+  // self-heal so `push`/`build-pptx` work even when it wasn't run explicitly.
+  let ref = readDeckBundleRef(deckDir);
+  if (!ref?.etag) {
+    try {
+      const mat = await materializeBundle(presId);
+      writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+      ref = readDeckBundleRef(deckDir);
+    } catch {
+      /* best-effort: the add-in still resolves the CD server-side, so the
+         render itself succeeds — only skew detection / local preview binding
+         are skipped when the bundle can't be materialized here. */
+    }
+  }
+  const result = await renderPptx({
+    presId,
+    slides,
+    deckAssets,
+    etag: ref?.etag ?? null,
+  });
+  if (!result?.base64) {
+    throw new Error("render-pptx returned no pptx bytes");
+  }
+  return result; // { ok, base64, slideCount, warnings, skippedSlides }
+}
+
+export async function buildAndPush({
+  deckDir,
+  presentationId = null,
+  insertAt = null,
+  replace = false,
+  slideIds = null,
+}) {
+  if (!deckDir) throw new Error("buildAndPush: deckDir is required");
+  // `slideIds` selects a subset of the BUILT deck's slides to push (a SOURCE
+  // filter, applied as Office.js sourceSlideIds on insert). The replace path
+  // has no source-subset support on the bridge — passing both would silently
+  // wipe the WHOLE presentation and re-push every built slide. Reject the combo
+  // (mirrors the `--replace` / `--slides` guard in the CLI dispatcher).
+  if (replace && Array.isArray(slideIds) && slideIds.length > 0) {
+    throw new Error(
+      "replace cannot be combined with slideIds — that would wipe the entire " +
+        "presentation. Push without replace to insert a slide subset, or " +
+        "replace the full deck without slideIds.",
+    );
+  }
+
+  const registry = await requireHost();
+  const presId = pickPresentation(registry, presentationId);
+
+  const result = await renderDeckToBase64(deckDir, { presId });
+  const base64 = result.base64;
+  const bytes = Buffer.byteLength(base64, "base64");
+  const mode = replace ? "replace" : "insert";
+
+  const doPush = () =>
+    replace
+      ? replaceSlides({ presId, base64 })
+      : insertSlides({ presId, base64, insertAt, sourceSlideIds: slideIds });
+
+  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;
+  }
+  return {
+    presId,
+    mode,
+    bytes,
+    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({
+  deckDir,
+  presentationId = null,
+  outPath = null,
+}) {
+  if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
+  const registry = await requireHost();
+  const presId = pickPresentation(registry, presentationId);
+  const result = await renderDeckToBase64(deckDir, { presId });
+  const out =
+    outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+  fs.writeFileSync(out, Buffer.from(result.base64, "base64"));
+  return {
+    outPath: out,
+    presId,
+    slideCount: result.slideCount ?? null,
+    warnings: result.warnings ?? [],
+    skippedSlides: result.skippedSlides ?? [],
+  };
+}