slidemind 0.3.20 → 0.4.1

package/src/builders/slide-prep.mjs

@@ -0,0 +1,67 @@
+// What preparing a slide resolves and tells its author — one wording on both
+// clients (src/cli/transcribe.mjs, the add-in's prepare-transcribed-slides.ts).
+
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalLayoutName, contentSlotFromLayoutSource } from "./layout-names.mjs";
+
+/**
+ * The plan's layout for a slide, resolved against the bundle, and the content
+ * slot its children are laid into. `layout` is null for a name the design does
+ * not carry; `slot` is null when the layout has no freeform content slot —
+ * such a slide is filled from the plan through the layout's own props, and no
+ * inventory is read for it (never a made-up slot: the reader would map the
+ * mockup into a rectangle the layout does not have).
+ */
+export function plannedLayoutSlot(bundleDir, layoutName) {
+  let names = [];
+  try {
+    names = fs.readdirSync(path.join(bundleDir, "layouts")).filter((f) => f.endsWith(".jsx")).map((f) => f.slice(0, -4));
+  } catch {}
+  const layout = canonicalLayoutName(layoutName, names);
+  if (!layout) return { layout: null, slot: null };
+  const src = fs.readFileSync(path.join(bundleDir, "layouts", `${layout}.jsx`), "utf8");
+  return { layout, slot: contentSlotFromLayoutSource(src) };
+}
+
+// The reader's notes the author acts on: a concept drawn against its layout's
+// tone, a drawing defect it flagged, the template marks it left out — and each
+// image binding it could not make (`spec.issues`).
+const AUTHOR_NOTE = /^the concept was drawn on a |^concept flaw —|^left out as the template's own marks/;
+export function specAuthorNotes(spec) {
+  return [
+    ...(spec?.notes ?? []).filter((note) => AUTHOR_NOTE.test(note)),
+    ...(spec?.issues ?? []).map((issue) => `${issue.code} — ${issue.message}${issue.action ? ` ${issue.action}` : ""}`),
+  ];
+}
+
+// An approved original the deck's registry could not resolve.
+export function unresolvedUseNote(issue) {
+  return `image use ${issue.useId ?? "(registry)"}${issue.assetId ? ` → ${issue.assetId}` : ""} did not resolve [${issue.code}]: ${issue.message}`;
+}
+
+// Every approved original bound to `slide` that its source does not place. An
+// obligation added after the slide was written, or an edit that dropped the
+// picture, is REPORTED, never repaired by rewriting the file.
+export function unplacedUseNotes(source, bound, slide) {
+  const notes = [];
+  for (const b of bound.values()) {
+    if (b.slide !== slide) continue;
+    // `use="<id>"` also matches the rendered `data-asset-use="<id>"`.
+    if (String(source ?? "").includes(`use="${b.useId}"`)) continue;
+    notes.push(
+      `the plan binds image use ${b.useId} (${b.displayName}) to this slide, but its JSX does not place it — add ` +
+        `<I id="…" x={…} y={…} w={…} h={…} src="${b.src}" use="${b.useId}" fit="${b.fit ?? "contain"}" />; the source is already on disk, do not search for one`,
+    );
+  }
+  return notes;
+}
+
+// What the author is told when a planned slide gets no inventory because of its
+// layout — one wording on both clients.
+export function layoutSlotNote(planned, resolved) {
+  if (!resolved.layout) {
+    return `approved layout ${planned ?? "(missing)"} is unavailable, so this slide was not prepared. Correct the plan or restore that layout; do not substitute a layout from the concept image.`;
+  }
+  return `layout ${resolved.layout} has no freeform content slot; fill its native props from the plan.`;
+}

package/src/builders/spec-assets.mjs

@@ -0,0 +1,236 @@
+// The visual assets a spec asks for, in the two ways a slide can get them:
+// FETCHED from an engine (an unbound `image.query` — attachSpecAsset writes the
+// downloaded bytes under the name the skeleton already references), or BOUND to
+// a picture the user supplied (an `image.assetUseId` — resolveBoundImageUses
+// answers it from the deck's own registry, and nothing is searched for).
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { effectiveUsesForSlides } from '../bridge/image-intent-envelope.mjs';
+import { imageRenderPlan } from '../lib/image-derivatives.mjs';
+import { resolveImageAsset } from '../lib/image-assets.mjs';
+import { statePath, writeStateFile } from '../lib/deck-paths.mjs';
+
+export function attachSpecAsset(row, downloaded, assetsDir) {
+  const ext = path.extname(downloaded.path);
+  if (!/^\.[a-z0-9]+$/i.test(ext) || ext === '.bin') throw new Error('engine returned an unsupported image format');
+  // A fetched asset is named by the skeleton (`NN-<element>.asset`) and lands
+  // flat in the deck's assets/. A row naming a path could only come from
+  // somewhere else — and `assets/local/` is the immutable registry, whose bytes
+  // a search result must never be written over.
+  if (/[\\/]/.test(row.file)) throw new Error(`asset ${row.file} is not a fetched asset file name; engine results never overwrite a registered source`);
+  const filename = `${path.parse(row.file).name}${ext}`;
+  const target = path.join(assetsDir, filename);
+  const source = fs.readFileSync(row.slideFile, 'utf8');
+  const before = JSON.stringify(`./assets/${row.file}`);
+  const after = JSON.stringify(`./assets/${filename}`);
+  if (!source.includes(before)) throw new Error(`asset reference ${row.file} is no longer in its slide`);
+  if (path.resolve(downloaded.path) !== path.resolve(target)) fs.copyFileSync(downloaded.path, target);
+  fs.writeFileSync(row.slideFile, source.split(before).join(after));
+  return { ...row, file: filename, mimeType: downloaded.mimeType, size: downloaded.size, recolor: downloaded.recolor };
+}
+
+/**
+ * The deck's `original` image uses for `slides`, each resolved to bytes that
+ * are actually on disk and still hash to what was registered.
+ *
+ * The uses come from what is PERSISTED — the plan's storyboard fences and the
+ * targeted-edit overrides — through the same `effectiveUsesForSlides` the wire
+ * envelope is built from, so the transcriber places exactly what was approved.
+ *
+ * A use that cannot be resolved is an ISSUE, never a substitution: the caller
+ * reports it and the slide keeps its unresolved reference. `reconstruct` and
+ * `reference` uses are deliberately absent — they oblige no picture, so there
+ * is nothing here for the transcriber to place.
+ *
+ * @returns {{bound: Map<string, object>, issues: Array<{code, slide, useId, assetId, message}>}}
+ */
+export function resolveBoundImageUses(deckDir, slides, { planMarkdown = null } = {}) {
+  const bound = new Map();
+  const issues = [];
+  let uses;
+  try {
+    uses = effectiveUsesForSlides(deckDir, slides, { planMarkdown });
+  } catch (err) {
+    // An unreadable registry or override file: report it once and transcribe
+    // the rest of the deck. A spec that binds a use still fails loudly, in
+    // `scaffoldSlideJsx`, because nothing resolved.
+    issues.push({ code: err?.code ?? 'image_intent_invalid', slide: null, useId: null, assetId: null, message: err?.message ?? String(err) });
+    return { bound, issues, reconstructed: new Set() };
+  }
+  // Slides rebuilt from a whole supplied reference: transcribed with the
+  // reference's own colours, not the design's tokens (workflow/create.md).
+  const reconstructed = new Set([...uses].filter(([, list]) => list.some((u) => u.fidelity === 'reconstruct' && u.reconstructionScope === 'slide')).map(([slide]) => slide));
+  for (const [slide, list] of uses) {
+    for (const use of list) {
+      if (use.fidelity !== 'original') continue;
+      let resolved;
+      try {
+        resolved = resolveImageAsset(deckDir, use.assetId);
+      } catch (err) {
+        issues.push({
+          code: err?.code ?? 'image_asset_missing',
+          slide,
+          useId: use.useId,
+          assetId: use.assetId,
+          message: err?.message ?? String(err),
+        });
+        continue;
+      }
+      // How these bytes reach a slide — as themselves, or through a declared
+      // derivative (a WebP source, an EXIF rotation, an animated first frame).
+      // The slide references the SOURCE either way; the notes say what the
+      // render does with it.
+      const plan = imageRenderPlan(resolved.asset, resolved.bytes);
+      bound.set(use.useId, {
+        useId: use.useId,
+        assetId: use.assetId,
+        slide,
+        src: `./${resolved.asset.workspacePath}`,
+        workspacePath: resolved.asset.workspacePath,
+        displayName: resolved.asset.displayName,
+        sha256: resolved.asset.sha256,
+        fit: use.fit ?? 'contain',
+        position: use.position ?? { x: 0.5, y: 0.5 },
+        crop: use.crop ?? null,
+        slot: use.slot ?? null,
+        notes: plan.notes,
+      });
+    }
+  }
+  return { bound, issues, reconstructed };
+}
+
+// ---------------------------------------------------------------------------
+// The asset ledger — what makes a RESUME cheap and safe
+// (openspec/changes/safeguard-slide-editing, task 7.3 / E22)
+// ---------------------------------------------------------------------------
+//
+// An engine search can miss: the motif has no glyph, the engine is down, the
+// download dies halfway. The slide then keeps an unresolved `./assets/NN-<id>`
+// reference, which `view-draft` reports as a blocking `[asset:error]` — the
+// right surfacing, and the reason nothing deletes it to make the build "clean".
+//
+// What was missing is the way back. `transcribe` builds its fetch list from the
+// slides it just WROTE, so on a second run every slide is skipped ("exists"),
+// the list is empty and nothing is retried. The only lever left was `--force`,
+// which regenerates the source from the spec — precisely what a resume must not
+// do. So the rows a run planned are written down here, and a later run reads
+// them back and retries just the unresolved ones.
+//
+// Three rules the ledger exists to keep:
+//
+//   * **A resume retries the asset work and nothing else.** These rows carry
+//     the query and the colour the transcriber resolved, so no spec is
+//     re-extracted, no source is regenerated, and no geometry is settled.
+//   * **A manually changed reference is never reclaimed.** A row is retried
+//     only while the slide still contains the exact `./assets/<file>` string
+//     the machine wrote. Point the slide at your own picture and the fetcher
+//     has nothing to match — the same rule text normalization follows, where
+//     the machine's own string being present is the evidence.
+//   * **The format is whatever arrived.** The ledger stores the reference as
+//     it currently stands; `attachSpecAsset` names the file from the bytes the
+//     engine actually returned and rewrites the reference to match. Nothing
+//     here forces an extension.
+
+/** Sidecar name under the deck's `state/`. */
+export const SPEC_ASSETS_FILE = 'spec-assets.json';
+
+/** The only schema version this build reads. */
+export const SPEC_ASSETS_VERSION = 1;
+
+const rowKey = (row) => `${row.slide}|${row.id}`;
+
+/** The ledger as it stands, or an empty one. An unreadable/foreign file reads as empty. */
+export function readSpecAssetLedger(deckDir) {
+  let doc;
+  try {
+    doc = JSON.parse(fs.readFileSync(statePath(deckDir, SPEC_ASSETS_FILE), 'utf8'));
+  } catch {
+    return { version: SPEC_ASSETS_VERSION, rows: [] };
+  }
+  if (!doc || doc.version !== SPEC_ASSETS_VERSION || !Array.isArray(doc.rows)) {
+    return { version: SPEC_ASSETS_VERSION, rows: [] };
+  }
+  return { version: SPEC_ASSETS_VERSION, rows: doc.rows.filter((r) => r && r.id != null && r.slide != null) };
+}
+
+/**
+ * Merge this run's rows into the ledger.
+ *
+ * A row is keyed by slide + element id, so re-recording it updates the file
+ * name and the outcome rather than adding a second entry. Rows for slides this
+ * run did not touch are LEFT ALONE: `transcribe --only 3` must not make the
+ * deck forget that slide 5 is still waiting for a picture.
+ */
+export function recordSpecAssets(deckDir, rows) {
+  const ledger = readSpecAssetLedger(deckDir);
+  const byKey = new Map(ledger.rows.map((r) => [rowKey(r), r]));
+  for (const row of rows ?? []) {
+    if (row?.id == null || row.slide == null || !row.file) continue;
+    byKey.set(rowKey(row), {
+      slide: row.slide,
+      id: row.id,
+      kind: row.kind ?? 'icon',
+      file: row.file,
+      query: row.query ?? null,
+      ...(Array.isArray(row.keywords) && row.keywords.length ? { keywords: row.keywords } : {}),
+      color: row.color ?? null,
+      colorHex: row.colorHex ?? null,
+      ...(row.tintHex ? { tintHex: row.tintHex } : {}),
+      resolved: Boolean(row.resolved),
+      ...(row.error ? { error: String(row.error) } : {}),
+      ...(!row.resolved && row.code ? { code: row.code, retryable: Boolean(row.retryable), attempts: row.attempts, retryAfterMs: row.retryAfterMs } : {}),
+    });
+  }
+  const next = { version: SPEC_ASSETS_VERSION, rows: [...byKey.values()].sort((a, b) => a.slide - b.slide || String(a.id).localeCompare(String(b.id))) };
+  // Idempotent, and silent when there is nothing to say. A run that refused —
+  // a hand-owned slide under `--only`, a converted slide — must leave the
+  // workspace byte-identical, and a new sidecar where there was none is a
+  // mutation like any other (E03).
+  const serialized = JSON.stringify(next, null, 2) + '\n';
+  let current = null;
+  try {
+    current = fs.readFileSync(statePath(deckDir, SPEC_ASSETS_FILE), 'utf8');
+  } catch {
+    if (!next.rows.length) return next;
+  }
+  if (current !== serialized) writeStateFile(deckDir, SPEC_ASSETS_FILE, serialized);
+  return next;
+}
+
+/**
+ * The rows a resume should retry: the ledger's entries whose asset is still
+ * missing from disk AND whose reference is still the one the machine wrote.
+ *
+ * @param {string} deckDir
+ * @param {Map<number,string>|Array<[number,string]>} slideFiles  slide number → its .jsx path
+ * @returns {Array<object>} fetch rows, each with `slideFile` filled in
+ */
+export function pendingSpecAssets(deckDir, slideFiles) {
+  const files = slideFiles instanceof Map ? slideFiles : new Map(slideFiles ?? []);
+  const assetsDir = path.join(deckDir, 'assets');
+  const pending = [];
+  for (const row of readSpecAssetLedger(deckDir).rows) {
+    const slideFile = files.get(row.slide);
+    if (!slideFile) continue;
+    // A fetched asset is a flat file name in the deck's assets/. Anything with
+    // a separator names the immutable registry, which an engine result may
+    // never be written over (`attachSpecAsset` refuses it too).
+    if (!row.file || /[\\/]/.test(row.file)) continue;
+    if (fs.existsSync(path.join(assetsDir, row.file))) continue;
+    let source;
+    try {
+      source = fs.readFileSync(slideFile, 'utf8');
+    } catch {
+      continue; // the slide is gone; there is nothing to fill in
+    }
+    // The evidence that this reference is still ours to resolve. An author who
+    // repointed the element at their own file removed this exact string, and
+    // the retry stops there.
+    if (!source.includes(`./assets/${row.file}`)) continue;
+    if (!row.query) continue; // no motif to search for; the note already says so
+    pending.push({ ...row, slideFile });
+  }
+  return pending;
+}

package/src/builders/spec-match.mjs

@@ -0,0 +1,56 @@
+// One-to-one matching of two element inventories of the same slide (two reads
+// of one image, or a read of the concept and a read of the deliverable): texts
+// pair by their words, everything else by place and overlap.
+const norm = (t) => String(t ?? "").toLowerCase().replace(/[^a-z0-9%€$.]+/g, " ").trim();
+const words = (t) => new Set(norm(t).split(" ").filter(Boolean));
+export const normText = norm;
+export function textSim(a, b) {
+  const A = words(a), B = words(b);
+  if (!A.size || !B.size) return 0;
+  let k = 0;
+  for (const w of A) if (B.has(w)) k++;
+  return (2 * k) / (A.size + B.size);
+}
+export const kindOf = (e) => (e.text != null && String(e.text).trim() ? "text"
+  : e.kind === "chart" ? "chart"
+  : e.kind === "icon" || e.kind === "image" ? "icon"
+  : e.kind === "path" || e.kind === "rule" ? "mark"
+  : "shape");
+export function iou(a, b) {
+  const x0 = Math.max(a.x, b.x), y0 = Math.max(a.y, b.y);
+  const x1 = Math.min(a.x + a.w, b.x + b.w), y1 = Math.min(a.y + a.h, b.y + b.h);
+  const i = Math.max(0, x1 - x0) * Math.max(0, y1 - y0);
+  const u = a.w * a.h + b.w * b.h - i;
+  return u > 0 ? i / u : 0;
+}
+const cx = (e) => e.x + e.w / 2, cy = (e) => e.y + e.h / 2;
+
+// Greedy by cost: texts pay in words (and distance), everything else in
+// distance (normalised by the slot diagonal) and overlap. Shapes and marks may
+// pair with each other (one read's filled path is another's box).
+export function matchElements(A, B, slot) {
+  const diag = Math.hypot(slot.w, slot.h);
+  const pairs = [];
+  for (const a of A) for (const b of B) {
+    const ka = kindOf(a), kb = kindOf(b);
+    if (ka !== kb && !((ka === "shape" || ka === "mark") && (kb === "shape" || kb === "mark"))) continue;
+    const d = Math.hypot(cx(a) - cx(b), cy(a) - cy(b)) / diag;
+    let cost;
+    if (ka === "text") {
+      const s = textSim(a.text, b.text);
+      if (s < 0.5) continue;
+      cost = (1 - s) + d;
+    } else {
+      if (d > 0.12 && iou(a, b) < 0.2) continue;
+      cost = d + (1 - iou(a, b)) * 0.5 + (ka !== kb ? 0.2 : 0);
+    }
+    pairs.push({ a, b, cost });
+  }
+  pairs.sort((p, q) => p.cost - q.cost);
+  const ua = new Set(), ub = new Set(), m = new Map();
+  for (const p of pairs) {
+    if (ua.has(p.a) || ub.has(p.b)) continue;
+    ua.add(p.a); ub.add(p.b); m.set(p.a, p.b);
+  }
+  return m;
+}