slidemind 0.3.20 → 0.4.0

package/src/builders/red-thread-backbone.mjs

@@ -11,12 +11,13 @@
  *
  * Pure string logic — no React, no Office (unit-testable).
  *
- * 1:1 port of the add-in's red-thread-backbone.ts. Top-level helpers are
- * prefixed `rt…` so the browser bundle (one IIFE across five modules) has no
- * name collisions; exported API names match the add-in verbatim.
+ * Canonical here; the add-in imports a byte-identical mirror
+ * (scripts/sync-transcription-runtime.mjs). Top-level helpers are prefixed
+ * `rt…` so the browser bundle (one IIFE across five modules) has no name
+ * collisions.
  */
 
-import { extractRedThreadMessages, findRedThreadSection } from "./storyboard-markdown.mjs";
+import { extractFrameLine, extractRedThreadMessages, findRedThreadSection, replaceStoryboardSegment, splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
 
 /**
  * One slide in the user-edited backbone draft:
@@ -54,19 +55,44 @@ function rtFindSlideSections(markdown) {
 }
 
 /**
- * The backbone is editable only when the red-thread moves and the slide
+ * A frame slide is a section but not a move: the red thread lists body moves
+ * only and names the frame on its `Frame:` line. Returns a frame slide's card
+ * label, or null for a body slide (an unreadable record counts as body).
+ */
+function rtFrameLabel(sectionText) {
+  const board = splitPlanMarkdownIntoSegments(sectionText).find(
+    (segment) => segment.type === "storyboard",
+  );
+  const data = board?.data;
+  if (data?.role !== "frame") return null;
+  const heading = /^###\s+Slide\s+\d+\s*:?[ \t]*(.*)$/m.exec(sectionText)?.[1];
+  return data.keyMessage?.trim() || heading?.trim() || data.frameKind || "Frame";
+}
+
+/**
+ * The backbone is editable only when the red-thread moves and the BODY slide
  * sections line up one-to-one — otherwise a positional restructure could
- * attach the wrong storyboard to a move.
+ * attach the wrong storyboard to a move. Frame slides sit between them in play
+ * order; a whole presentation always has some, so counting them as moves left
+ * every presentation's storyline read-only.
  *
- * Returns { messages, sectionCount } or null.
+ * Returns { messages, sectionCount, frame } or null: `messages` holds one card
+ * label per section (a body slide's move, a frame slide's key message), `frame`
+ * marks the frame sections.
  */
 export function parsePlanBackbone(markdown) {
-  const messages = extractRedThreadMessages(markdown);
-  if (!messages.length) return null;
+  const moves = extractRedThreadMessages(markdown);
+  if (!moves.length) return null;
   if (!findRedThreadSection(markdown)) return null;
   const sections = rtFindSlideSections(markdown);
-  if (sections.length !== messages.length) return null;
-  return { messages, sectionCount: sections.length };
+  const labels = sections.map((section) => rtFrameLabel(section.text));
+  if (labels.filter((label) => label === null).length !== moves.length) return null;
+  let move = 0;
+  return {
+    messages: labels.map((label) => label ?? moves[move++] ?? ""),
+    sectionCount: sections.length,
+    frame: labels.map((label) => label !== null),
+  };
 }
 
 function rtSanitizeMessage(message) {
@@ -84,34 +110,87 @@ function rtRenumberSection(text, slideNumber, editedMessage) {
   return next.replace(/("slide"\s*:\s*)\d+/, `$1${slideNumber}`);
 }
 
-const RT_NEW_SLIDE_CONTENT_MAX = 28;
+// ---------------------------------------------------------------------------
+// image uses across a restructure
+// ---------------------------------------------------------------------------
+//
+// Reordering and deletion need no help: a slide's `assetUses` live inside its
+// own storyboard fence, so they move with the section text and vanish with it,
+// and `useId`s stay exactly as they were (design decision 8 — never persist a
+// use's ownership as a slide number).
+//
+// DUPLICATION does: the copy would carry the original's `useId`s, and a use ID
+// is the identity the spec binding, the render evidence and the targeted-edit
+// override all key on. Two slides claiming one ID is not a picture used twice,
+// it is one obligation the renderer cannot attribute to a slide. So the first
+// occurrence keeps its IDs and every later copy mints fresh ones (A12).
+
+// Every useId the plan already spends, so a minted one can't collide. Scanned
+// off the RAW markdown rather than the parsed records: a fence that fails to
+// parse still spends its IDs the moment someone fixes it, and a taken set that
+// is too large only ever costs a suffix. Matches the add-in's scan verbatim.
+const RT_USE_ID_RE = /"useId"\s*:\s*"([A-Za-z0-9_-]+)"/g;
+
+function rtUseIdsIn(markdown) {
+  const taken = new Set();
+  for (const match of markdown.matchAll(RT_USE_ID_RE)) taken.add(match[1]);
+  return taken;
+}
+
+// The contract caps an ID at 128 characters, so the stem is trimmed before the
+// `_c<n>` suffix is appended — an over-long mint would fail the contract's own
+// parser and take the whole duplicated record down with it. The trim is PER
+// CANDIDATE, because the suffix grows with n: a fixed 124-character stem is
+// right for `_c2` and four characters too long for `_c1000`. Must stay
+// byte-identical to the add-in's `mintUseId`
+// (src/ui/src/pages/plan-review/red-thread-backbone.ts).
+const RT_USE_ID_MAX = 128;
+
+function rtMintUseId(base, n) {
+  const suffix = `_c${n}`;
+  return `${base.slice(0, RT_USE_ID_MAX - suffix.length)}${suffix}`;
+}
+
+function rtFreshUseId(base, taken) {
+  for (let n = 2; ; n++) {
+    const id = rtMintUseId(base, n);
+    if (taken.has(id)) continue;
+    taken.add(id);
+    return id;
+  }
+}
+
+/**
+ * Rewrite one section's image uses with fresh IDs. A section whose record
+ * carries none is returned byte-identical — a restructure of a deck with no
+ * image intent must not reformat a single fence.
+ */
+function rtRemintAssetUses(sectionText, taken) {
+  const board = splitPlanMarkdownIntoSegments(sectionText).find(
+    (segment) => segment.type === "storyboard" && segment.data?.assetUses?.length,
+  );
+  if (!board) return sectionText;
+  return replaceStoryboardSegment(sectionText, board, {
+    ...board.data,
+    assetUses: board.data.assetUses.map((use) => ({
+      ...use,
+      useId: rtFreshUseId(use.useId, taken),
+    })),
+  });
+}
 
 function rtPlaceholderSection(message, slideNumber) {
-  const content =
-    message.slice(0, RT_NEW_SLIDE_CONTENT_MAX).trim() || `Slide ${slideNumber}`;
-  const storyboard = {
-    version: 1,
-    slide: slideNumber,
-    blocks: [
-      {
-        id: "block-1",
-        x: 80,
-        y: 110,
-        w: 1440,
-        h: 300,
-        designElement: "Open canvas",
-        content,
-      },
-    ],
-    keyMessage: message,
-  };
+  // A slide the user inserted, with no content yet: the record carries the move
+  // as its story beat and nothing else. The agent fills in the content points
+  // and the layout on the round the composer sends.
+  const record = { version: 1, slide: slideNumber, keyMessage: message };
   return [
     `### Slide ${slideNumber}: ${message}`,
     "",
     `Core message: ${message}`,
     "",
     "```storyboard-canvas",
-    JSON.stringify(storyboard, null, 2),
+    JSON.stringify(record, null, 2),
     "```",
   ].join("\n");
 }
@@ -127,14 +206,19 @@ function rtPlaceholderSection(message, slideNumber) {
 export function stageStoryIteration(markdown, slides) {
   const editedPlanMarkdown = applyPlanBackbone(markdown, slides);
   if (!editedPlanMarkdown) return null;
-  const committed = extractRedThreadMessages(markdown);
+  const backbone = parsePlanBackbone(markdown);
+  const committed = backbone?.messages ?? [];
   const changes = [];
   slides.forEach((slide, index) => {
     const position = index + 1;
     if (slide.originalIndex === null) {
       changes.push(`Added slide ${position} for the move "${slide.message}".`);
     } else if (committed[slide.originalIndex] !== slide.message) {
-      changes.push(`Renamed slide ${position}'s move to "${slide.message}".`);
+      changes.push(
+        backbone?.frame[slide.originalIndex]
+          ? `Renamed slide ${position} to "${slide.message}".`
+          : `Renamed slide ${position}'s move to "${slide.message}".`,
+      );
     }
   });
   if (!changes.length) return null;
@@ -166,10 +250,21 @@ export function applyPlanBackbone(markdown, slides) {
   if (!firstSection || !lastSection) return null;
   if (firstSection.start < redThread.bodyEnd) return null;
 
-  const newRedThreadBody = `\n\n${cleaned
+  // Frame slides keep their place among the sections but are not moves.
+  const moves = cleaned.filter(
+    (slide) => slide.originalIndex === null || !backbone.frame[slide.originalIndex],
+  );
+  if (!moves.length) return null;
+  // The `Frame:` declaration is not a move, so it is not in `cleaned` — and
+  // rewriting the body without it would silently drop the deck's frame from an
+  // approved plan on the first reorder.
+  const frameLine = extractFrameLine(markdown);
+  const newRedThreadBody = `\n\n${moves
     .map((slide) => `- ${slide.message}`)
-    .join("\n")}\n\n`;
+    .join("\n")}${frameLine ? `\n\n${frameLine}` : ""}\n\n`;
 
+  const takenUseIds = rtUseIdsIn(markdown);
+  const placed = new Set();
   const newSections = cleaned.map((slide, index) => {
     const slideNumber = index + 1;
     if (slide.originalIndex === null) {
@@ -180,7 +275,11 @@ export function applyPlanBackbone(markdown, slides) {
     const originalMessage = backbone.messages[slide.originalIndex] ?? "";
     const edited =
       rtSanitizeMessage(originalMessage) !== slide.message ? slide.message : null;
-    return rtRenumberSection(section.text.trimEnd(), slideNumber, edited);
+    const text = rtRenumberSection(section.text.trimEnd(), slideNumber, edited);
+    // Second and later appearances of one original section are copies.
+    if (placed.has(slide.originalIndex)) return rtRemintAssetUses(text, takenUseIds);
+    placed.add(slide.originalIndex);
+    return text;
   });
 
   return [

package/src/builders/repair.mjs

@@ -0,0 +1,205 @@
+// Bounded, transactional repair of transcribed slides
+// (openspec/changes/safeguard-slide-editing 6.3).
+//
+// The engine itself is pure and lives in the mirrored core (settle.mjs:
+// `validateSettleTarget`, `repairPasses`, `REPAIR_BUDGET`). This module is the
+// CLI half that gives it a place to work and a way to publish: a CANDIDATE
+// workspace, and one atomic commit at the end. The two are separate files
+// because settle.mjs ships byte-identical into the add-in runtime
+// (scripts/sync-transcription-runtime.mjs), where none of the deck state below
+// exists.
+//
+// The order is the whole point:
+//
+//   1. the operation is a `repair`, and its source is still the bytes it was
+//      prepared against (`assertOperationFresh`);
+//   2. every target's CURRENT representation is one the core may rewrite
+//      (`validateSettleTarget`) — before a candidate is even staged;
+//   3. all passes run in the candidate, rendered there, budget checked against
+//      the ORIGINAL after every pass;
+//   4. the last mutation is rendered before anything is published;
+//   5. compare-and-swap, then one atomic activation of source + assets +
+//      records together.
+//
+// Anything that fails discards the candidate. Nothing is restored, because
+// nothing was published.
+import fs from "node:fs";
+import path from "node:path";
+
+import { conversionProvenance } from "../lib/conversions.mjs";
+import { assertOperationFresh, readSlidePreservation, recordOperation, sourceHash, writeSlidePreservation } from "../lib/edit-state.mjs";
+import { inlineComponents } from "../lib/inline-components.mjs";
+import { compareSlideSource } from "../lib/preservation-verdict.mjs";
+import { stageWorkspace } from "../lib/workspace-transaction.mjs";
+import { refoldLike } from "./fold-sets.mjs";
+import { repairPasses, repairPolicyFor, repairDelta, validateSettleTarget } from "./settle.mjs";
+
+/**
+ * One slide's result, in the shape both adapters report and the preservation
+ * verdict composes with (safeguard-slide-editing 6.5).
+ *
+ * `elements` is `compareSlideSource`'s own output — changed elements keyed to
+ * the operation record's PROPERTY_SCOPES (geom | text | fill | line | media |
+ * chart | native), so a repair's summary and a preservation requirement speak
+ * one vocabulary rather than two. `delta` carries the raw numbers the budget
+ * was read from; `changes` and `routeChanges` are the engine's own sentences.
+ *
+ * @typedef {{
+ *   slideKey: string, jsxPath: string,
+ *   verdict: "repaired" | "unchanged" | "refused",
+ *   changes: string[], routeChanges: string[], unresolved: string[],
+ *   elements: Array<{elementId: string, action: string, properties: string[]}>,
+ *   unknown: Array<object>, unsupported: Array<object>, ambiguous: Array<object>,
+ *   delta: object,
+ * }} RepairSlideSummary
+ */
+function summarise(slides, verdictOf) {
+  return slides.map((s) => {
+    const comparison = compareSlideSource(s.original, s.src);
+    return {
+      slideKey: s.key,
+      jsxPath: s.path,
+      verdict: verdictOf(s),
+      changes: s.changes,
+      routeChanges: s.routeChanges,
+      unresolved: s.unresolved,
+      elements: comparison.changes,
+      unknown: comparison.unknown,
+      unsupported: comparison.unsupported,
+      ambiguous: comparison.ambiguous,
+      delta: repairDelta(s.original, s.src),
+    };
+  });
+}
+
+const refusal = (code, message, extra = {}) => ({ ok: false, committed: false, passes: 0, verified: false, slides: [], reasons: [{ code, message, ...extra }] });
+
+/**
+ * Repair the slides one `repair` operation scopes.
+ *
+ * @param {string} workspaceDir  the deck workspace (`<deck>/.slidemind`, or the
+ *                               deck itself for a workspace-less deck)
+ * @param {object} options
+ * @param {object} options.operation  the operation record (kind `repair`)
+ * @param {(ctx: {workspaceDir: string, files: string[]}) => Promise<Map<string, Map>>} options.capture
+ *        render the CANDIDATE and return each file's measured boxes
+ * @param {() => boolean} [options.cancelled] checked before every pass
+ * @param {() => void} [options.checkpoint]  runs inside the commit, before the swap
+ * @param {(rel: string) => void} [options.fault] runs after each activated file
+ * @returns {Promise<{ok: boolean, committed: boolean, passes: number, verified: boolean,
+ *                    slides: Array<object>, reasons: Array<{code: string, message: string}>}>}
+ */
+export async function repairOperation(workspaceDir, { operation, capture, cancelled = () => false, checkpoint = () => {}, fault = () => {} }) {
+  if (operation?.kind !== "repair") {
+    return refusal("not_a_repair", `bounded repair runs under a repair operation; this one is ${operation?.kind ?? "absent"}`);
+  }
+  const targets = operation.targets ?? [];
+  if (!targets.length) return refusal("no_targets", "this operation scopes no slides");
+
+  try {
+    assertOperationFresh(workspaceDir, operation);
+  } catch (err) {
+    return refusal(err.code ?? "source_moved", err.message);
+  }
+
+  // 2. The representation gate, on every target, before a candidate exists.
+  const slides = [];
+  const reasons = [];
+  for (const target of targets) {
+    const file = path.join(workspaceDir, target.jsxPath);
+    let original;
+    try {
+      original = fs.readFileSync(file, "utf8");
+    } catch (err) {
+      reasons.push({ code: "source_missing", slide: target.slideKey, message: `${target.jsxPath} cannot be read (${err.message})` });
+      continue;
+    }
+    // Three states, not two: a record that exists and cannot be read is
+    // `undefined` — unknown, which the validator refuses — and never `null`,
+    // which would say "looked, not converted" about a slide nobody could
+    // classify. The byte marker catches a converted slide that still carries
+    // its pragma; this is what catches one whose pragma was removed (E15).
+    const conversion = conversionProvenance(workspaceDir, target.jsxPath);
+    if (conversion === undefined) {
+      reasons.push({
+        code: "conversion_unreadable",
+        slide: target.slideKey,
+        jsxPath: target.jsxPath,
+        message: `conversions/${path.basename(target.jsxPath).replace(/\.jsx$/i, "")}.json exists but cannot be read, so whether ${target.jsxPath} is converted is unknown; repair or remove that record first`,
+      });
+    }
+    // A set component is repaired in its members' own lines: the core reads
+    // and rewrites one literal element per line, so each call site is inlined
+    // first and the result folded back afterwards (fold-sets.mjs refoldLike).
+    const flat = inlineComponents(original, { preserveLines: false });
+    for (const u of flat.unreadable) {
+      reasons.push({ code: "unreadable_component", slide: target.slideKey, jsxPath: target.jsxPath, line: u.line, message: `<${u.component}> is spread from an object, so bounded repair cannot read its members — edit the JSX directly` });
+    }
+    const check = validateSettleTarget(flat.src, { conversion });
+    for (const reason of check.reasons) reasons.push({ ...reason, slide: target.slideKey, jsxPath: target.jsxPath });
+    const { policy, errors } = repairPolicyFor(target);
+    for (const error of errors) reasons.push({ ...error, slide: target.slideKey });
+    slides.push({ key: target.slideKey, path: target.jsxPath, original: flat.src, raw: original, policy });
+  }
+  if (reasons.length) return { ok: false, committed: false, passes: 0, verified: false, slides: [], reasons };
+
+  // 3–4. The candidate. Every write below lands in the staged copy.
+  let candidate;
+  try {
+    candidate = stageWorkspace(workspaceDir);
+  } catch (err) {
+    return refusal(err.code ?? "stage_failed", err.message);
+  }
+  try {
+    const measured = new Map();
+    const result = await repairPasses({
+      slides,
+      cancelled,
+      render: async (sources) => {
+        for (const [rel, src] of sources) fs.writeFileSync(path.join(candidate.workspace, rel), src);
+        const captured = await capture({ workspaceDir: candidate.workspace, files: [...sources.keys()] });
+        for (const [rel, boxes] of captured ?? []) measured.set(rel, boxes);
+        return captured;
+      },
+    });
+    // An untouched slide keeps its own bytes; a repaired one goes back to its
+    // components where that is still exact.
+    const published = (s) => (s.src === s.original ? s.raw : refoldLike(s.raw, s.src, measured.get(s.path) ?? null).src);
+    if (!result.ok) {
+      return { ok: false, committed: false, passes: result.passes, verified: result.verified, slides: summarise(result.slides, () => "refused"), reasons: result.reasons };
+    }
+    const summary = summarise(result.slides, (s) => (s.src === s.original ? "unchanged" : "repaired"));
+
+    // 5. Publish: the repaired source, then the records that describe it, then
+    // one activation. `assertOperationFresh` names the slide that moved;
+    // `activate` refuses on ANY file that changed since staging. Every step
+    // here writes into the candidate only, so a throw anywhere leaves the deck
+    // exactly as it was — and comes back as a reason, not as an exception.
+    try {
+      for (const s of result.slides) fs.writeFileSync(path.join(candidate.workspace, s.path), published(s));
+      const preservation = readSlidePreservation(candidate.workspace);
+      let touched = false;
+      for (const s of result.slides) {
+        const entry = preservation.slides?.[s.key];
+        if (!entry?.baseline) continue;
+        // Requirements do not move; the source they were read from does.
+        entry.baseline = { ...entry.baseline, sourceHash: sourceHash(candidate.workspace, s.path) };
+        touched = true;
+      }
+      if (touched) writeSlidePreservation(candidate.workspace, preservation, { operation });
+      recordOperation(candidate.workspace, { ...operation, status: "committed" });
+      candidate.activate({
+        checkpoint: () => {
+          checkpoint();
+          assertOperationFresh(workspaceDir, operation);
+        },
+        fault,
+      });
+    } catch (err) {
+      return { ok: false, committed: false, passes: result.passes, verified: result.verified, slides: summary, reasons: [{ code: err.code ?? "commit_failed", message: err.message }] };
+    }
+    return { ok: true, committed: true, passes: result.passes, verified: result.verified, slides: summary, reasons: [] };
+  } finally {
+    candidate.dispose();
+  }
+}