slidemind 0.1.3 → 0.1.4

package/src/bridge/bundle.mjs

@@ -14,20 +14,30 @@
 // corporate-design fingerprint, deliberately shared across decks/presentations
 // on the same CD — so it must NOT be keyed by backendURL, which would break that
 // sharing). If two backends ever mint the same presFP for different content,
-// they would collide here.
+// they would collide here. The lint engine (deployment-owned, not CD-owned)
+// shares this posture: paired backends on different add-in versions flip
+// lint-engine.mjs to whichever backend synced last.
 //
 //   ${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/
 //   ├── corporate-design.css      (from wire.css)
 //   ├── design.md                 (from wire.designRules)
 //   ├── layouts/layouts.css       (from wire.layoutsCss, when present)
 //   ├── layouts/*.jsx             (one per wire.layouts[])
-//   ├── assets/*                  (downloaded from wire.assets[].url)
+//   ├── assets/*                  (downloaded from wire.assets[].url — role-keyed brand assets
+//   │                              plus reusable master images from wire.extractedImages[],
+//   │                              each landed at its own `workspacePath`, e.g.
+//   │                              assets/master-<sha8>.<ext>)
+//   ├── assets/brand-images.md    (on-demand manifest of the reusable master images,
+//   │                              built from wire.extractedImages — design.md only
+//   │                              carries a sparse pointer + per-kind counts)
 //   ├── samples/*                 (downloaded from wire.samples[].url — brand reference slides)
 //   ├── fonts/*                   (downloaded from wire.fonts[].url, optional)
 //   ├── master/empty-layout.pptx  (downloaded from wire.master.url, optional)
 //   ├── engines.json              (wire.engines[])
 //   ├── workflow/*.md             (wire.workflowRefs — add-in-owned authoring craft)
-//   └── bundle.json               ({ presFP, version, etag, tokenRoleMap, … })
+//   ├── lint-engine.mjs           (wire.lintEngine.source — the add-in's slide-lint engine)
+//   ├── primitives.json           (wire.lintEngine.primitives — closed component registry)
+//   └── bundle.json               ({ presFP, version, etag, lintEngineVersion, tokenRoleMap, … })
 
 import fs from "node:fs";
 import os from "node:os";
@@ -55,6 +65,29 @@ export function bundleDirForPresFP(presFP) {
   return path.join(bundleCacheRoot(), sanitizeKey(presFP));
 }
 
+// Wipe the whole materialized bundle cache so the next build/push/download
+// re-fetches every design bundle fresh from the add-in. `slidemind init` calls
+// this: init is the deliberate (re)setup point — and `slidemind update`
+// redeploys through it — so a stale binary or an orphaned per-presFP dir can
+// never survive a re-init. (materializeBundle rewrites text every sync but only
+// re-downloads a binary when its etag changes, and a presFP dir for a CD that
+// no longer exists is never pruned, so the only clean reset is to remove the
+// root.) The dirs are recreated on demand by the next materialize. Returns the
+// number of per-presentation bundle dirs removed.
+export function clearBundleCache() {
+  const root = bundleCacheRoot();
+  let removed = 0;
+  try {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (entry.isDirectory()) removed += 1;
+    }
+  } catch {
+    return 0; // No cache root yet — nothing to clear.
+  }
+  fs.rmSync(root, { recursive: true, force: true });
+  return removed;
+}
+
 // Plain HTTPS/HTTP GET → Buffer. Follows a few redirects and tolerates the
 // add-in's self-signed dev certificate on loopback hosts (the same posture the
 // bridge client uses). Azure blob SAS URLs are public HTTPS and need no special
@@ -125,14 +158,75 @@ function sampleExt(contentType) {
   }
 }
 
-// Fetch + write the bundle for `presId`. Returns { dir, presFP, etag, version,
-// cached }. Skips the re-download when the cached bundle's etag already matches
-// (unless `force`).
+const REUSABLE_KIND_ORDER = [
+  "logo",
+  "icon",
+  "illustration",
+  "decoration",
+  "photo",
+  "other",
+];
+const REUSABLE_KIND_PLURAL = {
+  logo: "logos",
+  icon: "icons",
+  illustration: "illustrations",
+  decoration: "decorations",
+  photo: "photos",
+  other: "others",
+};
+const pluralKind = (kind) => REUSABLE_KIND_PLURAL[kind] ?? `${kind}s`;
+
+// Build the `assets/brand-images.md` manifest from the wire's extracted images —
+// every reusable master image as `- ./assets/<file> — <description>`, grouped by
+// kind. Mirrors the add-in's `buildReusableImagesManifest` so the local agent
+// reads the same catalogue the in-app design persona does. Returns "" when none.
+function buildReusableImagesManifest(extractedImages) {
+  const rows = [];
+  for (const img of extractedImages ?? []) {
+    if (!img || typeof img.workspacePath !== "string") continue;
+    rows.push({
+      file: path.basename(img.workspacePath),
+      kind: typeof img.kind === "string" ? img.kind : "other",
+      description:
+        typeof img.description === "string" ? img.description.trim() : "",
+    });
+  }
+  if (rows.length === 0) return "";
+  const present = new Set(rows.map((r) => r.kind));
+  const kinds = REUSABLE_KIND_ORDER.filter((k) => present.has(k));
+  for (const k of present) if (!kinds.includes(k)) kinds.push(k);
+  const lines = [
+    "# Brand reusable images",
+    "",
+    'Images lifted from the brand’s PowerPoint master. Reference one from slide JSX with `<img src="./assets/<file>">` — the files are already in `assets/`.',
+  ];
+  for (const kind of kinds) {
+    lines.push("", `## ${pluralKind(kind)}`);
+    for (const row of rows.filter((r) => r.kind === kind)) {
+      lines.push(
+        `- ./assets/${row.file}${row.description ? ` — ${row.description}` : ""}`,
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+// Sync the bundle for `presId`. Idempotent: every call rewrites all inline
+// text from the freshly fetched wire (the wire is fetched on every call
+// anyway), downloads only binaries whose per-item blob etag changed (samples
+// are write-once by id), and prunes files the wire no longer serves. There is
+// deliberately NO staleness token to compare — the materialized dir is always
+// a per-item projection of the last wire, so authored-layer edits that bypass
+// a bundle re-produce (engines, image-source guidelines, sample curation) and
+// deployment-owned content (workflow refs, the lint engine) can never go
+// stale here. `force` re-downloads binaries even when their etags match.
+// Returns { dir, presFP, etag, version, downloaded, pruned, engineUpdated,
+// warnings }.
 export async function materializeBundle(
   presId,
-  { force = false, backendURL = null } = {},
+  { force = false, backendURL = null, preferBrandId = null } = {},
 ) {
-  const wire = await getDesignBundle(presId, { backendURL });
+  const wire = await getDesignBundle(presId, { backendURL, preferBrandId });
   if (!wire || !wire.presFP) {
     throw new Error("design-bundle response is missing presFP");
   }
@@ -152,146 +246,203 @@ export async function materializeBundle(
   const dir = bundleDirForPresFP(presFP);
   const metaPath = path.join(dir, "bundle.json");
 
-  if (!force && fs.existsSync(metaPath)) {
-    try {
-      const prev = JSON.parse(fs.readFileSync(metaPath, "utf8"));
-      // Prefer etag equality; fall back to version equality for CDs whose
-      // effective etag is empty (no stored blob etag), so the cache can still
-      // short-circuit instead of re-downloading on every call.
-      const sameEtag = prev.etag && wire.etag && prev.etag === wire.etag;
-      const sameVersion =
-        !wire.etag &&
-        prev.version != null &&
-        wire.version != null &&
-        prev.version === wire.version;
-      if (sameEtag || sameVersion) {
-        return {
-          dir,
-          presFP,
-          etag: wire.etag ?? null,
-          version: wire.version ?? null,
-          cached: true,
-          warnings: [],
-        };
-      }
-    } catch {
-      /* unreadable metadata — fall through and rewrite the bundle */
-    }
+  let prev = {};
+  try {
+    prev = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+  } catch {
+    /* first sync or unreadable meta — sync from scratch */
   }
+  const prevBinaries =
+    prev.binaries && typeof prev.binaries === "object" ? prev.binaries : {};
 
-  // Rewrite from scratch so a stale layout/asset can never linger.
-  fs.rmSync(dir, { recursive: true, force: true });
-  fs.mkdirSync(path.join(dir, "layouts"), { recursive: true });
-  fs.mkdirSync(path.join(dir, "assets"), { recursive: true });
-  fs.mkdirSync(path.join(dir, "samples"), { recursive: true });
+  // Everything this sync owns, as dir-relative paths; drives the prune pass.
+  const expected = new Set(["bundle.json"]);
+  const writeText = (rel, text) => {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, text, "utf8");
+    expected.add(rel);
+  };
 
-  fs.writeFileSync(
-    path.join(dir, "corporate-design.css"),
-    wire.css ?? "",
-    "utf8",
-  );
-  fs.writeFileSync(path.join(dir, "design.md"), wire.designRules ?? "", "utf8");
+  // --- Inline text: always rewritten (the bytes are already in hand). ---
+  writeText("corporate-design.css", wire.css ?? "");
+  writeText("design.md", wire.designRules ?? "");
   if (typeof wire.layoutsCss === "string" && wire.layoutsCss.length > 0) {
-    fs.writeFileSync(
-      path.join(dir, "layouts", "layouts.css"),
-      wire.layoutsCss,
-      "utf8",
-    );
+    writeText(path.join("layouts", "layouts.css"), wire.layoutsCss);
   }
-
   for (const layout of wire.layouts ?? []) {
     const name = layout.name || layout.componentName;
     if (!name || typeof layout.source !== "string") continue;
     const file = name.endsWith(".jsx") ? name : `${name}.jsx`;
-    fs.writeFileSync(
-      path.join(dir, "layouts", path.basename(file)),
-      layout.source,
-      "utf8",
-    );
+    writeText(path.join("layouts", path.basename(file)), layout.source);
   }
-
-  fs.writeFileSync(
-    path.join(dir, "engines.json"),
-    JSON.stringify(wire.engines ?? [], null, 2),
-    "utf8",
-  );
+  writeText("engines.json", JSON.stringify(wire.engines ?? [], null, 2));
 
   // Brand-agnostic authoring workflow craft (create/edit/composition/layouts/
   // authoring/build-export) — owned by the add-in, served on the bundle so the
   // local agent reads the SAME workflow guidance the in-app design persona does.
   if (wire.workflowRefs && typeof wire.workflowRefs === "object") {
-    fs.mkdirSync(path.join(dir, "workflow"), { recursive: true });
     for (const [name, text] of Object.entries(wire.workflowRefs)) {
       if (typeof text !== "string") continue;
-      fs.writeFileSync(
-        path.join(dir, "workflow", path.basename(name)),
-        text,
-        "utf8",
-      );
+      writeText(path.join("workflow", path.basename(name)), text);
     }
   }
 
-  // Download signed URLs IMMEDIATELY and in PARALLEL — they expire ~15 min
-  // after the wire response is minted, so serializing N independent GETs only
-  // raises the odds a late one races an expiring URL. Failures are non-fatal
-  // (a missing brand asset degrades local HTML preview but never the server
-  // render) but are NOT silent: each is collected into `warnings` so the caller
-  // can tell the user the materialized bundle is incomplete.
+  // The add-in's slide-lint engine + its primitives registry (deployment-
+  // owned). `version` feeds the lint wrapper's import cache-bust key, not a
+  // staleness check — the files re-sync like all other text. Absent when the
+  // paired backend predates the engine; src/builders/lint.mjs surfaces an
+  // actionable error in that case rather than skipping the gate.
+  const engineUpdated = Boolean(
+    wire.lintEngine && prev.lintEngineVersion !== wire.lintEngine.version,
+  );
+  if (wire.lintEngine && typeof wire.lintEngine.source === "string") {
+    writeText("lint-engine.mjs", wire.lintEngine.source);
+    writeText(
+      "primitives.json",
+      JSON.stringify(wire.lintEngine.primitives ?? {}, null, 2),
+    );
+  }
+
+  // The add-in's slide-capture engine (deployment-owned, puppeteer-external).
+  // The CLI dynamic-imports this to capture decks LOCALLY with its own Chrome,
+  // then POSTs the result to the server's /translate route. Absent when the
+  // paired backend predates the feature; src/bridge/build-and-push.mjs falls
+  // back to the server-side render path in that case.
+  const captureEngineUpdated = Boolean(
+    wire.captureEngine &&
+      prev.captureEngineVersion !== wire.captureEngine.version,
+  );
+  if (wire.captureEngine && typeof wire.captureEngine.source === "string") {
+    writeText("capture-engine.mjs", wire.captureEngine.source);
+  }
+
+  // --- Binaries: per-item sync keyed by the wire's blob etags. Signed URLs
+  // expire ~15 min after the wire is minted, so changed items download
+  // IMMEDIATELY and in PARALLEL. Failures are non-fatal (a missing brand
+  // asset degrades local HTML preview but never the server render) but NOT
+  // silent: each is collected into `warnings`. ---
   const downloads = [];
+  const binaries = {};
+  const queueBinary = (rel, url, etag, label) => {
+    expected.add(rel);
+    const target = path.join(dir, rel);
+    const exists = fs.existsSync(target);
+    if (!force && exists && etag && prevBinaries[rel] === etag) {
+      binaries[rel] = etag; // current — carry the record forward
+      return;
+    }
+    if (!force && exists && !etag) {
+      return; // write-once binary (samples carry no etag) — presence is currency
+    }
+    downloads.push({ rel, target, url, etag: etag ?? null, label });
+  };
+
   for (const asset of wire.assets ?? []) {
     if (!asset?.url || !asset?.filename) continue;
-    downloads.push({
-      label: `asset ${asset.filename}`,
-      target: path.join(dir, "assets", path.basename(asset.filename)),
-      url: asset.url,
-    });
+    queueBinary(
+      path.join("assets", path.basename(asset.filename)),
+      asset.url,
+      asset.etag ?? null,
+      `asset ${asset.filename}`,
+    );
   }
   for (const font of wire.fonts ?? []) {
     if (!font?.url) continue;
     const fname = font.filename || `${font.role || font.family || "font"}.bin`;
-    downloads.push({
-      label: `font ${fname}`,
-      target: path.join(dir, "fonts", path.basename(fname)),
-      url: font.url,
-    });
+    queueBinary(
+      path.join("fonts", path.basename(fname)),
+      font.url,
+      font.etag ?? null,
+      `font ${fname}`,
+    );
   }
   if (wire.master?.url) {
-    downloads.push({
-      label: "master empty-layout.pptx",
-      target: path.join(dir, "master", "empty-layout.pptx"),
-      url: wire.master.url,
-    });
+    queueBinary(
+      path.join("master", "empty-layout.pptx"),
+      wire.master.url,
+      wire.master.etag ?? null,
+      "master empty-layout.pptx",
+    );
   }
-  // Per-CD sample slides (the brand's own reference slides) — the offline agent
-  // studies a random few before composing. Keyed by the sample's stable `id`;
-  // extension derived from `contentType`. Same non-fatal degradation as assets.
+  // Per-CD sample slides (the brand's own reference slides) — write-once
+  // captures keyed by the sample's stable `id`; extension derived from
+  // `contentType`.
   for (const sample of wire.samples ?? []) {
     if (!sample?.url || !sample?.id) continue;
-    downloads.push({
-      label: `sample ${sample.id}`,
-      target: path.join(
-        dir,
+    queueBinary(
+      path.join(
         "samples",
         `${path.basename(sample.id)}${sampleExt(sample.contentType)}`,
       ),
-      url: sample.url,
-    });
+      sample.url,
+      null,
+      `sample ${sample.id}`,
+    );
+  }
+  // Reusable master images (logos, decorations, illustrations the add-in's
+  // vision pass lifted from the brand's own master and flagged `reusable`).
+  // Each carries a `workspacePath` (e.g. `assets/master-<sha8>.<ext>`) that the
+  // add-in's design persona references from slide JSX as `<img src="./assets/
+  // <file>">`; land them at that exact path so copyDesignSystem ships them into
+  // the deck next to the role-keyed brand assets. Content-addressed name →
+  // write-once (a changed image gets a new sha8 path; the old one prunes out).
+  // The catalogue of these (name/kind/description) rides in design.md's
+  // `### Brand Reusable Images` block, so the local agent sees both halves.
+  for (const image of wire.extractedImages ?? []) {
+    if (!image?.url || typeof image.workspacePath !== "string") continue;
+    const rel = path.join("assets", path.basename(image.workspacePath));
+    queueBinary(rel, image.url, null, `master image ${rel}`);
+  }
+  // The brand-reusable-images catalogue is kept OUT of design.md (which only
+  // carries a sparse pointer + per-kind counts, to stay prompt-light). The full
+  // per-image descriptions live in this manifest the agent reads on demand. Built
+  // from the same wire.extractedImages we just hydrated; pruned when none.
+  const reusableManifest = buildReusableImagesManifest(wire.extractedImages);
+  if (reusableManifest) {
+    writeText(path.join("assets", "brand-images.md"), reusableManifest);
+  }
+  // Per-layout chrome images — the add-in's server-side render of each layout
+  // (background + decor + logos + key-visual), one per layout. Codegen sets each
+  // as the `.layout-<slug>` background via `url("../assets/<file>")`, which the
+  // HTML builder rewrites to `./assets/…`, so the local preview shows real brand
+  // chrome instead of bare layouts. Each carries a `workspacePath`
+  // (`assets/chrome-<componentName>.<ext>`); land it next to the other assets so
+  // copyDesignSystem ships it into the deck. Etag-keyed → re-fetch only on change.
+  for (const chrome of wire.layoutBackgrounds ?? []) {
+    if (!chrome?.url || typeof chrome.workspacePath !== "string") continue;
+    const rel = path.join("assets", path.basename(chrome.workspacePath));
+    queueBinary(rel, chrome.url, chrome.etag ?? null, `layout chrome ${rel}`);
   }
 
   const warnings = [];
+  let downloaded = 0;
   const settled = await Promise.allSettled(
     downloads.map((d) => downloadInto(d.target, d.url)),
   );
   settled.forEach((r, i) => {
+    const d = downloads[i];
     if (r.status === "rejected") {
       const reason =
         r.reason instanceof Error ? r.reason.message : String(r.reason);
       warnings.push(
-        `failed to download ${downloads[i].label}: ${reason} (signed URL may have expired — re-run with --force)`,
+        `failed to download ${d.label}: ${reason} (signed URL may have expired — re-run with --force)`,
       );
+      // Keep the previous record when an older copy is still on disk: its
+      // etag differs from the wire's, so the next sync retries.
+      if (fs.existsSync(d.target) && prevBinaries[d.rel]) {
+        binaries[d.rel] = prevBinaries[d.rel];
+      }
+      return;
     }
+    downloaded += 1;
+    if (d.etag) binaries[d.rel] = d.etag;
   });
 
+  // --- Prune: anything on disk this sync doesn't own goes away, so a stale
+  // layout/asset can never linger — without the old rmSync-everything. ---
+  const pruned = pruneUnexpected(dir, expected);
+
   const meta = {
     presFP,
     version: wire.version ?? null,
@@ -299,6 +450,29 @@ export async function materializeBundle(
     scope: wire.scope ?? null,
     tokenRoleMap: wire.tokenRoleMap ?? null,
     engines: wire.engines ?? [],
+    // Role-keyed brand assets land flat at assets/<filename>; the role→filename
+    // map can't be reconstructed from the files alone, so carry it (like fonts).
+    // Lets consumers resolve an asset by role, e.g. the review window's brand
+    // `logoMark` (the add-in-rendered orb). Absent roles simply aren't listed.
+    assets: (wire.assets ?? [])
+      .filter((a) => a?.role && a?.filename)
+      .map((a) => ({ role: a.role, filename: path.basename(a.filename) })),
+    // Import cache-bust key for src/builders/lint.mjs; null = the paired
+    // backend serves no engine (predates the feature).
+    lintEngineVersion: wire.lintEngine?.version ?? null,
+    // Same, for the local-capture engine (src/bridge/capture.mjs).
+    captureEngineVersion: wire.captureEngine?.version ?? null,
+    // Font role/family manifest — the fonts land flat at fonts/<filename> but
+    // local capture must rebuild the @font-face roles the server uses, so carry
+    // the mapping the wire knows (the cache files alone can't reconstruct it).
+    fonts: (wire.fonts ?? [])
+      .filter((f) => f?.role && f?.family && f?.filename)
+      .map((f) => ({
+        role: f.role,
+        family: f.family,
+        filename: path.basename(f.filename),
+      })),
+    binaries,
     fetchedAt: new Date().toISOString(),
     incompleteAssets: warnings.length > 0,
   };
@@ -309,11 +483,38 @@ export async function materializeBundle(
     presFP,
     etag: wire.etag ?? null,
     version: wire.version ?? null,
-    cached: false,
+    downloaded,
+    pruned,
+    engineUpdated,
+    captureEngineUpdated,
     warnings,
   };
 }
 
+// Delete files the current sync doesn't own and collapse empty directories.
+// `expected` holds dir-relative paths exactly as `path.join` built them, so
+// the comparison is platform-consistent.
+function pruneUnexpected(dir, expected) {
+  let pruned = 0;
+  const walk = (rel) => {
+    const abs = rel ? path.join(dir, rel) : dir;
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      const childRel = rel ? path.join(rel, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        walk(childRel);
+        if (fs.readdirSync(path.join(dir, childRel)).length === 0) {
+          fs.rmdirSync(path.join(dir, childRel));
+        }
+      } else if (!expected.has(childRel)) {
+        fs.rmSync(path.join(dir, childRel), { force: true });
+        pruned += 1;
+      }
+    }
+  };
+  walk("");
+  return pruned;
+}
+
 // Per-deck record of which CD bundle (presFP + etag) the deck was authored
 // against — lets `render-pptx` pass the etag for skew detection, and lets the
 // local HTML/editor resolve the right materialized bundle.
@@ -352,6 +553,31 @@ export function resolveBundleDirForDeck(deckDir) {
   return fs.existsSync(dir) ? dir : null;
 }
 
+// Resolve a role-keyed brand asset (e.g. "logoMark") for a deck to its
+// materialized file path, trying the requested roles in order. Returns
+// { role, filename, path } for the first role present on disk, else null.
+// The role→filename map lives in the bundle's bundle.json (see materializeBundle).
+export function resolveBrandAsset(deckDir, roles) {
+  const dir = resolveBundleDirForDeck(deckDir);
+  if (!dir) return null;
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(path.join(dir, "bundle.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  const list = Array.isArray(meta.assets) ? meta.assets : [];
+  for (const role of roles) {
+    const hit = list.find((a) => a.role === role && a.filename);
+    if (!hit) continue;
+    const filePath = path.join(dir, "assets", hit.filename);
+    if (fs.existsSync(filePath)) {
+      return { role, filename: hit.filename, path: filePath };
+    }
+  }
+  return null;
+}
+
 // Read the engines[] descriptor list from a materialized bundle directory.
 export function readEnginesFromDir(dir) {
   if (!dir) return [];