slidemind 0.3.19 → 0.4.0

package/src/bridge/config.mjs

@@ -19,7 +19,8 @@
 // credential with a different subject: the CLI session is minted by the add-in
 // for whoever clicked Connect CLI, the Graph token belongs to whoever completed
 // the browser sign-in. Written only when present, so a machine that never ran
-// `login` keeps a byte-identical file.
+// `login` keeps a byte-identical file. `msGraphUsername` names that account (as
+// the id_token spelled it) so `whoami` can report it without a network probe.
 //
 // Stored under XDG_CONFIG_HOME (config, not cache/state) so it persists and is
 // clearly user-scoped. 0600 — it holds bearer credentials.
@@ -131,10 +132,45 @@ function readRaw() {
   try {
     return JSON.parse(raw);
   } catch {
+    // Two CLI processes writing at once (a token refresh in each of two sim
+    // sessions, 2026-09-19) left the shorter write followed by the tail of the
+    // longer one: a complete object plus trailing bytes. The first complete
+    // top-level object is the store; anything after it is the collision.
+    const first = firstJsonObject(raw);
+    if (first) return first;
     return null; // malformed JSON
   }
 }
 
+// The first complete `{…}` at the start of `raw`, parsed — or null.
+export function firstJsonObject(raw) {
+  const start = raw.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  let inString = false;
+  for (let i = start; i < raw.length; i++) {
+    const ch = raw[i];
+    if (inString) {
+      if (ch === "\\") i++;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(raw.slice(start, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
 // Every credential this file hands out is registered for output scrubbing the
 // moment it is read, so a token spliced into an error message downstream — a
 // server echoing the request back, a response body used as an error detail —
@@ -164,6 +200,9 @@ export function readSessions() {
       ...(typeof s.msGraphRefreshToken === "string" && s.msGraphRefreshToken
         ? { msGraphRefreshToken: s.msGraphRefreshToken }
         : {}),
+      ...(typeof s.msGraphUsername === "string" && s.msGraphUsername
+        ? { msGraphUsername: s.msGraphUsername }
+        : {}),
     }));
   }
   // v1: { backendURL, sessionToken }
@@ -202,6 +241,7 @@ function writeAll(sessions, defaultBackend) {
       label: s.label || deriveEnvLabel(s.backendURL),
       ...(s.oid ? { oid: s.oid } : {}),
       ...(s.msGraphRefreshToken ? { msGraphRefreshToken: s.msGraphRefreshToken } : {}),
+      ...(s.msGraphUsername ? { msGraphUsername: s.msGraphUsername } : {}),
     })),
   };
   const def =
@@ -209,9 +249,12 @@ function writeAll(sessions, defaultBackend) {
       ? defaultBackend
       : sessions[0]?.backendURL;
   if (def) payload.default = def;
-  fs.writeFileSync(sessionConfigPath(), `${JSON.stringify(payload, null, 2)}\n`, {
-    mode: 0o600,
-  });
+  // Atomic: write beside the store and rename over it, so a second process
+  // writing at the same moment can never interleave bytes with this one.
+  const target = sessionConfigPath();
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, target);
 }
 
 // Add or replace a session (keyed by backendURL). Becomes the default if none
@@ -248,6 +291,11 @@ export function upsertSession({ backendURL, sessionToken, label = null, oid = nu
     ...(samePerson && previous?.msGraphRefreshToken
       ? { msGraphRefreshToken: previous.msGraphRefreshToken }
       : {}),
+    // The name travels with the token it describes — never on its own, or a
+    // re-pair by someone else would keep printing the previous user's account.
+    ...(samePerson && previous?.msGraphRefreshToken && previous?.msGraphUsername
+      ? { msGraphUsername: previous.msGraphUsername }
+      : {}),
   });
   const def = getDefaultBackend() || backendURL;
   writeAll(sessions, def);
@@ -314,6 +362,11 @@ export function getSessionFor(backendURL) {
 // Never during tests: `node --test` sets NODE_TEST_CONTEXT, and a test writing
 // into the developer's real login keychain would outlive the test's isolated
 // XDG_CONFIG_HOME. SLIDEMIND_NO_KEYCHAIN is the explicit opt-out.
+//
+// Never under a redirected HOME either (batch/bisect harnesses isolate runs with
+// HOME=<run>/.home): `security` resolves the login keychain under $HOME, finds
+// none, and macOS raises a modal "Keychain Not Found" dialog that blocks the
+// write until someone clicks it. Such runs keep the token in their own file.
 const KEYCHAIN_MARKER = "@keychain";
 const KEYCHAIN_SERVICE = "slidemind-msgraph";
 
@@ -321,7 +374,8 @@ function keychainUsable() {
   return (
     process.platform === "darwin" &&
     !process.env.NODE_TEST_CONTEXT &&
-    !process.env.SLIDEMIND_NO_KEYCHAIN
+    !process.env.SLIDEMIND_NO_KEYCHAIN &&
+    path.resolve(os.homedir()) === os.userInfo().homedir
   );
 }
 
@@ -385,11 +439,17 @@ export function getGraphRefreshToken(backendURL) {
 // Every refresh returns a NEW refresh token, so this is called on each rotation.
 // Returns false when that backend is no longer paired — a session removed
 // mid-refresh must not resurrect itself as a token-only record.
-export function setGraphRefreshToken(backendURL, refreshToken) {
+//
+// `username` is the signed-in account's name, which only the SIGN-IN knows (it
+// reads it off the id_token). A rotation passes nothing and leaves the stored
+// name alone; clearing the token clears the name with it, so nothing can report
+// an account this machine no longer holds a credential for.
+export function setGraphRefreshToken(backendURL, refreshToken, { username = null } = {}) {
   const sessions = readSessions();
   const record = sessions.find((s) => s.backendURL === backendURL);
   if (!record) return false;
   if (refreshToken) {
+    if (username) record.msGraphUsername = username;
     record.msGraphRefreshToken = refreshToken;
     if (keychainUsable()) {
       try {
@@ -406,6 +466,7 @@ export function setGraphRefreshToken(backendURL, refreshToken) {
       keychainDelete(backendURL);
     }
     delete record.msGraphRefreshToken;
+    delete record.msGraphUsername;
   }
   writeAll(sessions, getDefaultBackend());
   return true;

package/src/bridge/engine-download.mjs

@@ -239,16 +239,6 @@ async function streamOneResult({
           markup = local.markup;
           recolorRefused = null;
         }
-      } else if (!iconColor && describeRecolor(markup, res.mimeType).mode === "mono") {
-        // No colour asked for and the glyph is a single fixed paint: make it
-        // TINTABLE instead of shipping it black. With `currentColor` the slide's
-        // own `color: var(--token)` on the <img> drives the fill in the preview
-        // and in the .pptx alike, so one file serves a white glyph on an accent
-        // medallion and an accent glyph on white. Every sim builder that baked
-        // one hex at download time later lost either the glyph (blue on blue)
-        // or the medallion fill; a baked colour stays available via --icon-color.
-        const tintable = applyLocalRecolor(markup, "currentColor");
-        if (tintable.applied) markup = tintable.markup;
       }
       const filename = `engine-${searchId}-${selection}.svg`;
       const target = path.join(assetsDir, filename);

package/src/bridge/graph-auth.mjs

@@ -108,6 +108,13 @@ function tokenEndpoint(tenantId) {
   return `${authorityBase()}/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`;
 }
 
+// A failure that says nothing about the sign-in: the service could not be
+// reached or was down for a moment. Only these leave a refreshFailures entry.
+const OUTAGE_STATUS = new Set([408, 429]);
+function unreachable(message) {
+  return Object.assign(new Error(message), { transient: true });
+}
+
 // One /env/config read per backend per process — the app registration doesn't
 // change under a running command.
 const appRegistrationCache = new Map();
@@ -122,10 +129,13 @@ async function discoverAppRegistration(backendURL) {
   try {
     res = await httpJson("GET", `${backendURL}/env/config`);
   } catch (err) {
-    throw new Error(
+    throw unreachable(
       `could not reach slidemind${envPhrase(env, "on")} to start sign-in: ${err?.message || err}`,
     );
   }
+  if (OUTAGE_STATUS.has(res.status) || res.status >= 500) {
+    throw unreachable(`slidemind${envPhrase(env, "on")} answered HTTP ${res.status} for its sign-in details`);
+  }
   const clientId = typeof res.json?.CLIENT_ID === "string" ? res.json.CLIENT_ID : "";
   const tenantId = typeof res.json?.TENANT_ID === "string" ? res.json.TENANT_ID : "";
   if (res.status !== 200 || !clientId || !tenantId) {
@@ -453,7 +463,7 @@ async function requestToken(tenantId, form) {
   try {
     res = await httpJson("POST", tokenEndpoint(tenantId), { form });
   } catch (err) {
-    throw new Error(`could not reach Microsoft sign-in: ${err?.message || err}`);
+    throw unreachable(`could not reach Microsoft sign-in: ${err?.message || err}`);
   }
   if (res.status === 200 && res.json?.access_token) {
     // Every mint and every refresh lands here, before any caller can act on the
@@ -470,6 +480,8 @@ async function requestToken(tenantId, form) {
   const err = new Error(String(detail).split("\n")[0]);
   err.oauth = true;
   err.code = res.json?.error ?? null;
+  // Entra down or throttling: the credential was never judged.
+  err.transient = OUTAGE_STATUS.has(res.status) || res.status >= 500;
   throw err;
 }
 
@@ -708,7 +720,11 @@ export async function loginGraph({
     session: paired,
     env: deriveEnvLabel(backendURL),
   });
-  if (!setGraphRefreshToken(backendURL, tokens.refresh_token)) {
+  if (
+    !setGraphRefreshToken(backendURL, tokens.refresh_token, {
+      username: accountName(claims),
+    })
+  ) {
     throw new Error(
       `slidemind is not connected to '${deriveEnvLabel(backendURL)}'.`,
     );
@@ -751,6 +767,24 @@ const cacheKey = (backendURL, resource) => `${backendURL}${resource}`;
 // the next redeems it.
 const refreshChain = new Map();
 
+// Why the last refresh of a backend + resource came back empty for a reason
+// that is NOT the credential (Entra or this backend unreachable, a timeout, an
+// HTTP 408/429/5xx — see `unreachable`).
+// The sign-in is intact then, and a request sent without its token is refused
+// as `login_required`, which sends the user to sign in again for nothing (x108:
+// "run `slidemind login`" mid-run, and the next search answered).
+const refreshFailures = new Map(); // cacheKey → message
+
+/**
+ * The cause of the last failed refresh of this backend's `resource` token while
+ * its sign-in is still stored, or null. Callers refuse to send a request without
+ * the token then, and report a retryable failure instead of a missing sign-in.
+ */
+export function tokenRefreshFailure(backendURL, resource) {
+  if (!hasGraphSession(backendURL)) return null;
+  return refreshFailures.get(cacheKey(backendURL, resource)) ?? null;
+}
+
 function withRefreshLock(backendURL, fn) {
   const tail = refreshChain.get(backendURL) ?? Promise.resolve();
   const next = tail.then(fn, fn);
@@ -781,6 +815,21 @@ export async function getGraphToken(backendURL) {
   return resourceToken(backendURL, "graph");
 }
 
+/**
+ * This deployment's SharePoint origin (`https://tenant.sharepoint.com`), or null
+ * when it has none configured. The SAME value the SharePoint token is minted
+ * for, which is what makes it the only origin the direct adapter may send that
+ * token to — the CLI hardcodes no tenant, exactly as the connect doctrine says.
+ */
+export async function sharePointResource(backendURL) {
+  if (!backendURL) return null;
+  try {
+    return (await discoverAppRegistration(backendURL)).sharePointResource;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A usable SharePoint-resource access token for one backend, or null.
  *
@@ -858,9 +907,12 @@ async function refreshResourceToken(backendURL, resource, storedRefreshToken) {
             "corpus search and SharePoint content need the user to run `slidemind login` again.\n",
         );
       }
+    } else if (err?.transient) {
+      refreshFailures.set(cacheKey(backendURL, resource), err.message);
     }
     return null;
   }
+  refreshFailures.delete(cacheKey(backendURL, resource));
   // Rotation: AAD issues a new refresh token on every refresh and the old one
   // is spent. Persisting it is what keeps the ~90-day window sliding.
   if (tokens.refresh_token) setGraphRefreshToken(backendURL, tokens.refresh_token);

package/src/bridge/image-intent-envelope.mjs

@@ -0,0 +1,239 @@
+// The `imageIntent` request envelope — the deck's approved image obligations,
+// projected onto the wire (implementation guide §4).
+//
+// Two shapes, one builder:
+//
+//   * MODEL endpoints (concept images, concept specs, spec jobs) carry the
+//     bytes INLINE as a data URI. The add-in's model call has no access to this
+//     machine, so a descriptor without bytes would be an instruction to imagine
+//     the picture.
+//   * RENDER / TRANSLATE carry `workspacePath` instead. Those requests already
+//     ship every deck asset as base64 in `deckAssets` (src/bridge/build-and-
+//     push.mjs → gatherDeckAssets, keyed `assets/<rel>`), and an image asset
+//     lives at `assets/local/<assetId>.<ext>` — which IS its workspacePath. So
+//     the envelope points into the byte map the request already has rather than
+//     sending every screenshot twice.
+//
+// Everything is built from what is PERSISTED — the deck's registry
+// (state/image-assets.json), the plan's storyboard fences, and the targeted-edit
+// overrides — never from whatever a command happens to be holding. A use that
+// only exists in a command's arguments is a use the user has not approved.
+//
+// The envelope is returned through the contract's own `parseImageIntentEnvelope`,
+// so a request can never carry a record the receiving validator would reject,
+// and a deck with no image uses builds NO envelope at all: `null`, so the call
+// serializes exactly as it did before this feature existed.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { splitPlanMarkdownIntoSegments } from "../builders/storyboard-markdown.mjs";
+import {
+  imageAssetError,
+  readImageAssetManifest,
+  resolveImageAsset,
+} from "../lib/image-assets.mjs";
+import {
+  IMAGE_INTENT_VERSION,
+  parseImageIntentEnvelope,
+  selectImageIntent,
+} from "../lib/image-intent.mjs";
+import { imageIntentFingerprint } from "../lib/image-intent-fingerprint.mjs";
+import { readImageUseOverrides, slideIdentities } from "../lib/image-use-overrides.mjs";
+
+// The ceiling a SINGLE source may carry into one request. It is the add-in's
+// own `MAX_IMAGE_ASSET_BYTES` (RT/image-assets.ts), which is the ceiling
+// `engine_add` and `generate_image` already enforce server-side — reused rather
+// than re-invented, so an asset this CLI accepts is one the route accepts. Over
+// it, the answer is the contract's `image_asset_too_large`: produce a declared
+// derivative or supply a smaller source. The final source is never silently
+// downsampled and the asset list is never silently shortened.
+export const IMAGE_INTENT_MAX_ASSET_BYTES = 8 * 1024 * 1024;
+
+// The encoded-body target a batched request aims to stay under. Same number,
+// different job: it is what the per-slide batching in `slidemind concepts`
+// already assumed ("four slides keep each body under ~8 MB") now that an
+// envelope's inline sources ride along with the mockup PNGs.
+export const IMAGE_INTENT_REQUEST_BYTE_BUDGET = 8 * 1024 * 1024;
+
+const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+
+function readPlanMarkdown(deckDir) {
+  try {
+    return fs.readFileSync(path.join(deckDir, "plan.md"), "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** The uses each storyboard fence records: `Map<slide, AssetUse[]>`. */
+export function planStoryboardUses(planMarkdown) {
+  const bySlide = new Map();
+  for (const segment of splitPlanMarkdownIntoSegments(planMarkdown ?? "")) {
+    if (segment.type !== "storyboard" || !segment.data?.slide) continue;
+    bySlide.set(segment.data.slide, segment.data.assetUses ?? []);
+  }
+  return bySlide;
+}
+
+/**
+ * The uses that actually apply to each requested slide: its targeted-edit
+ * override if it has one, otherwise the plan's.
+ *
+ * This is `effectiveSlideUses` (src/lib/image-use-overrides.mjs) for a whole
+ * slide set — composed from the same two primitives rather than called per
+ * slide, because the slide-identity half rescans and re-hashes every slide file
+ * on each call and a 20-slide deck would pay for it twenty times.
+ *
+ * @returns {Map<number, Array>}
+ */
+export function effectiveUsesForSlides(deckDir, slides, { planMarkdown = null } = {}) {
+  const planned = planStoryboardUses(planMarkdown ?? readPlanMarkdown(deckDir));
+  const wanted = normalizeSlides(slides);
+  const out = new Map();
+  if (!wanted.length) return out;
+
+  // Only pay for the override machinery when the deck has overrides at all —
+  // which, for a planned deck that was never edited slide-by-slide, is never.
+  const overrides = readImageUseOverrides(deckDir);
+  const idBySlide = new Map();
+  if (overrides.slides.length) {
+    for (const entry of slideIdentities(deckDir)) idBySlide.set(entry.slide, entry.slideId);
+  }
+  for (const slide of wanted) {
+    const { uses } = selectImageIntent({
+      slideId: idBySlide.get(slide) ?? null,
+      storyboardUses: planned.get(slide) ?? [],
+      overrides,
+    });
+    out.set(slide, uses);
+  }
+  return out;
+}
+
+function normalizeSlides(slides) {
+  return [...new Set(slides ?? [])]
+    .filter((n) => Number.isInteger(n) && n > 0)
+    .sort((a, b) => a - b);
+}
+
+// One asset's transport descriptor, with its bytes proved: `resolveImageAsset`
+// raises `image_asset_missing` when the copy is gone and `image_asset_changed`
+// when it no longer hashes to what the registry recorded — the two failures the
+// contract distinguishes because their repairs differ.
+function assetDescriptor(deckDir, assetId, { inline, maxAssetBytes }) {
+  const { asset, bytes } = resolveImageAsset(deckDir, assetId);
+  if (bytes.length > maxAssetBytes) {
+    throw imageAssetError(
+      "image_asset_too_large",
+      `${asset.displayName}: ${mb(bytes.length)} MB is past the ${mb(maxAssetBytes)} MB a single image may carry into one request`,
+      { assetId },
+    );
+  }
+  const descriptor = {
+    assetId: asset.assetId,
+    sha256: asset.sha256,
+    mimeType: asset.mimeType,
+    width: asset.width,
+    height: asset.height,
+    byteLength: bytes.length,
+    displayName: asset.displayName,
+  };
+  return inline
+    ? { ...descriptor, image: `data:${asset.mimeType};base64,${bytes.toString("base64")}` }
+    : { ...descriptor, workspacePath: asset.workspacePath };
+}
+
+/**
+ * The `imageIntent` envelope for one request, or **null** when none of the
+ * requested slides carries an image use.
+ *
+ * Null is the load-bearing case: it is what keeps every existing call — every
+ * deck that has no image intent, which today is all of them — serializing byte
+ * for byte as it did before.
+ *
+ * @param {string} deckDir the deck workspace
+ * @param {{slides: number[], planMarkdown?: string|null, inline?: boolean,
+ *          maxAssetBytes?: number}} opts
+ *   `inline: true` (the default) carries data URIs for the model endpoints;
+ *   `inline: false` carries `workspacePath`, for render/translate, whose
+ *   `deckAssets` byte map already holds those exact bytes under that key.
+ */
+export function buildImageIntentEnvelope(
+  deckDir,
+  { slides, planMarkdown = null, inline = true, maxAssetBytes = IMAGE_INTENT_MAX_ASSET_BYTES } = {},
+) {
+  const uses = effectiveUsesForSlides(deckDir, slides, { planMarkdown });
+  const slidesOut = [];
+  const assetIds = new Set();
+  for (const slide of normalizeSlides([...uses.keys()])) {
+    const list = uses.get(slide) ?? [];
+    if (!list.length) continue;
+    slidesOut.push({ slide, uses: list });
+    for (const use of list) assetIds.add(use.assetId);
+  }
+  if (!slidesOut.length) return null;
+
+  const envelope = {
+    version: IMAGE_INTENT_VERSION,
+    // Only the assets the REQUESTED slides use, in a deterministic order so two
+    // identical requests serialize identically.
+    assets: [...assetIds]
+      .sort()
+      .map((assetId) => assetDescriptor(deckDir, assetId, { inline, maxAssetBytes })),
+    slides: slidesOut,
+  };
+
+  // One validator on both sides of the wire: whatever this builds is run
+  // through the same parser the receiver uses, so a drift here fails here.
+  const parsed = parseImageIntentEnvelope(envelope);
+  if (!parsed.value) {
+    const first = parsed.issues[0];
+    throw imageAssetError(
+      first?.code ?? "image_intent_invalid",
+      `image intent envelope: ${first?.message ?? "invalid"}`,
+      first?.assetId ? { assetId: first.assetId } : {},
+    );
+  }
+  return parsed.value;
+}
+
+/**
+ * The canonical intent fingerprint of each requested slide — `null` for a slide
+ * with no uses, so a legacy no-intent slide has nothing to record and nothing
+ * to invalidate (design decision 6).
+ *
+ * Reads the registry, never the bytes: an entry is immutable, so its recorded
+ * digest IS the source identity. Whether the copy on disk still matches is a
+ * different question, answered where the bytes are actually needed.
+ *
+ * @returns {Map<number, string|null>}
+ */
+export function slideIntentFingerprints(deckDir, slides, { planMarkdown = null, context = null } = {}) {
+  const uses = effectiveUsesForSlides(deckDir, slides, { planMarkdown });
+  const out = new Map();
+  if (![...uses.values()].some((list) => list.length)) {
+    for (const slide of uses.keys()) out.set(slide, null);
+    return out;
+  }
+  const manifest = readImageAssetManifest(deckDir);
+  const byId = new Map(manifest.assets.map((asset) => [asset.assetId, asset]));
+  for (const [slide, list] of uses) {
+    if (!list.length) {
+      out.set(slide, null);
+      continue;
+    }
+    const assets = [...new Set(list.map((use) => use.assetId))]
+      .map((id) => byId.get(id))
+      .filter(Boolean);
+    out.set(
+      slide,
+      imageIntentFingerprint({
+        uses: list,
+        assets,
+        context: { ...(context ?? {}), slide },
+      }),
+    );
+  }
+  return out;
+}

package/src/bridge/package-preview.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { previewPath } from '../lib/deck-paths.mjs';
+import { slideOrderPaths } from '../pptx/ooxml.mjs';
+import { unzip } from '../pptx/zip.mjs';
+import { backendCapabilities, bridgeFetch, withTransientRetry } from './client/transport.mjs';
+import { multipartBody } from './client/brands.mjs';
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+export function validatePackagePreview(bytes, result) {
+  const count = slideOrderPaths(unzip(bytes)).length;
+  if (!count || result?.packageSha256 !== digest(bytes) || result?.renderer !== 'libreoffice')
+    throw new Error('Package preview does not identify the exported PPTX bytes and renderer.');
+  const slides = [...(result.images ?? [])].sort((a,b)=>a.slideNumber-b.slideNumber);
+  if (slides.length !== count || slides.some((s,i)=>s.slideNumber!==i+1))
+    throw new Error('Package preview is incomplete or contains duplicate/out-of-order slide identities.');
+  return slides.map(s => {
+    const png = Buffer.from(s.base64 ?? '', 'base64');
+    if (!png.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])))
+      throw new Error(`Package preview slide ${s.slideNumber} is not a PNG.`);
+    return { slideNumber:s.slideNumber, png };
+  });
+}
+
+// The exact final bytes, including native/reused slides and assembly changes.
+// A browser capture is NEVER reported as a render of this package.
+// The backend renders at most a few packages at once and answers 429
+// preview_busy beyond that. A render holds its slot for tens of seconds, so a
+// busy answer waits long enough for one to finish instead of giving up.
+const BUSY_DELAYS_MS = [10000, 20000, 40000];
+const isBusy = err => err?.status === 429 && err?.code === 'preview_busy';
+
+export async function writePackagePreview({deckDir, bytes, target, onProgress, request, busyDelays = BUSY_DELAYS_MS}) {
+  const packageSha256 = digest(bytes);
+  const unavailable = note => ({ kind:'pptx', renderer:null, status:'unavailable', packageSha256, dir:null, files:[], note });
+  if (!target?.brandId || !target.backendURL) return unavailable('Exported PPTX visual verification unavailable: no brand render target.');
+  try {
+    if (!request) {
+      const caps = await backendCapabilities(target.backendURL);
+      if (!caps.pptxPreview) return unavailable('Exported PPTX visual verification unavailable: this backend does not provide package previews. Browser previews verify source only.');
+      request = async () => {
+        const upload = multipartBody({}, {name:'deck', fileName:'deck.pptx', bytes, contentType:'application/vnd.openxmlformats-officedocument.presentationml.presentation'});
+        const response = await bridgeFetch(`/api/cli/brands/${encodeURIComponent(target.brandId)}/preview-pptx`,{method:'POST',headers:{'content-type':upload.contentType},body:upload.body,timeoutMs:200000},target.backendURL);
+        return response.json();
+      };
+    }
+    onProgress?.({stage:'verifying exported PPTX',done:0,total:1});
+    const result = await withTransientRetry(() => request(bytes, target), isBusy, busyDelays);
+    const slides = validatePackagePreview(bytes,result);
+    // Content-addressed directory: a failed later build cannot leave old PNGs
+    // looking like successful verification of new bytes.
+    const dir = path.join(previewPath(deckDir,'package'),packageSha256);
+    fs.mkdirSync(dir,{recursive:true});
+    const files = slides.map(({slideNumber,png})=>{
+      const file=path.join(dir,`${String(slideNumber).padStart(2,'0')}.png`);
+      fs.writeFileSync(file,png);return file;
+    });
+    const preview={kind:'pptx',renderer:result.renderer,status:'rendered',packageSha256,dir,files,
+      note:'Rendered from the exported PPTX with LibreOffice. Inspect every slide; this is not a PowerPoint pixel-parity or visual-quality verdict.'};
+    fs.writeFileSync(path.join(dir,'manifest.json'),JSON.stringify(preview,null,2)+'\n');
+    return preview;
+  } catch (err) {
+    return unavailable(`Exported PPTX visual verification unavailable: ${err instanceof Error ? err.message : String(err)}. Browser previews verify source only.`);
+  }
+}