@davmash/bygone 0.9.7 → 0.10.0

package/out/changeTour.js

@@ -41,9 +41,49 @@ __export(changeTour_exports, {
   materializeChangeUnits: () => materializeChangeUnits,
   parseChangeTourManifest: () => parseChangeTourManifest,
   parseChangeTourSource: () => parseChangeTourSource,
-  parseChangeTourStory: () => parseChangeTourStory
+  parseChangeTourStory: () => parseChangeTourStory,
+  pinTourSource: () => pinTourSource
 });
 module.exports = __toCommonJS(changeTour_exports);
+
+// src/tourImage.ts
+var MAX_TOUR_IMAGE_BYTES = 8 * 1024 * 1024;
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validPath(value) {
+  return typeof value === "string" && value.length > 0 && !/[\\\x00-\x1f:]/.test(value) && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function validateTourImageSource(value, label) {
+  if (value === void 0) return;
+  if (!record(value) || Object.keys(value).some((key) => !["file", "revision", "alt"].includes(key)) || !validPath(value.file) || !["base", "head"].includes(String(value.revision)) || typeof value.alt !== "string" || !value.alt.trim()) {
+    throw new Error(`${label} must contain a repository-relative file, base/head revision, and non-empty alt text.`);
+  }
+}
+function validateTourImage(value, label) {
+  if (value === void 0) return;
+  if (!record(value) || !validPath(value.path) || typeof value.alt !== "string" || !value.alt.trim() || typeof value.revision !== "string" || !/^[a-f0-9]{40,64}$/.test(value.revision) || typeof value.dataUrl !== "string" || !value.dataUrl.startsWith("data:image/png;base64,")) {
+    throw new Error(`${label} must contain pinned, embedded PNG evidence and alt text.`);
+  }
+  const base64 = value.dataUrl.slice(22);
+  const decodedBytes = base64.length / 4 * 3 - (base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0);
+  if (decodedBytes > MAX_TOUR_IMAGE_BYTES || base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(base64)) throw new Error(`${label} must be a PNG of at most 8 MiB.`);
+  const header = Uint8Array.from(atob(base64.slice(0, 44)), (character) => character.charCodeAt(0));
+  validatePngHeader(header, label);
+}
+function validatePngHeader(bytes, label) {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82];
+  if (bytes.length < 33 || signature.some((byte, index) => bytes[index] !== byte)) {
+    throw new Error(`${label} must be a PNG with an IHDR header.`);
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16), height = view.getUint32(20);
+  if (!width || !height || width > 16384 || height > 16384 || width * height > 64 * 1024 * 1024) {
+    throw new Error(`${label} exceeds the PNG dimension limit.`);
+  }
+}
+
+// src/changeTour.ts
 var import_child_process4 = require("child_process");
 
 // src/gitComparison.ts
@@ -160,8 +200,8 @@ function listBranchCommits(repoRoot, mergeBaseOid, headOid, runGit3 = createGitR
     "--format=%H%x00%h%x00%cI%x00%s%x00%P%x1e",
     `${mergeBaseOid}..${headOid}`
   ], repoRoot);
-  return output.split("").map((record) => record.replace(/^\n+|\n+$/g, "")).filter(Boolean).map((record) => {
-    const [oid = "", shortOid = "", timestamp = "", summary = "", parents = ""] = record.split("\0");
+  return output.split("").map((record2) => record2.replace(/^\n+|\n+$/g, "")).filter(Boolean).map((record2) => {
+    const [oid = "", shortOid = "", timestamp = "", summary = "", parents = ""] = record2.split("\0");
     return {
       oid,
       shortOid,
@@ -234,18 +274,110 @@ function readGitMaxBuffer() {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_GIT_MAX_BUFFER_BYTES;
 }
 
+// src/tourFraming.ts
+function validateTourFraming(value, version, path) {
+  for (const key of ["opening", "conclusion"]) {
+    const passage = value[key];
+    if (passage === void 0) continue;
+    if (Number(version) < 5) throw new Error(`${path}.${key} requires version 5.`);
+    if (!passage || typeof passage !== "object" || Array.isArray(passage)) {
+      throw new Error(`${path}.${key} must be an object.`);
+    }
+    const fields = passage;
+    for (const field of Object.keys(fields)) {
+      if (!["title", "summary", "bullets"].includes(field)) throw new Error(`${path}.${key}.${field} is unsupported.`);
+    }
+    for (const field of ["title", "summary"]) requireProse(fields[field], `${path}.${key}.${field}`);
+    if (fields.bullets !== void 0) {
+      if (!Array.isArray(fields.bullets)) throw new Error(`${path}.${key}.bullets must be an array.`);
+      fields.bullets.forEach((bullet, index) => requireProse(bullet, `${path}.${key}.bullets[${index}]`));
+    }
+  }
+}
+function validateOverviewPurpose(value, version, path) {
+  if (value === void 0) return;
+  if (version < 5) {
+    if (value && typeof value === "object" && "purpose" in value) throw new Error(`${path}.purpose requires version 5.`);
+    return;
+  }
+  requireProse(value == null ? void 0 : value.purpose, `${path}.purpose`);
+}
+function requireProse(value, path) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${path} must be a non-empty string.`);
+}
+
+// src/tourDetails.ts
+function validateChangeTourDetails(value, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, ["audience"], path);
+  validateAudience(value.audience, `${path}.audience`);
+}
+function validateAudience(value, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, [
+    "codebase",
+    "language",
+    "domain",
+    "readingDemand",
+    "purpose",
+    "scope",
+    "estimatedMinutes"
+  ], path);
+  if (typeof value.codebase !== "string" || !["none", "some", "maintainer"].includes(value.codebase)) {
+    throw new Error(`${path}.codebase must be none, some, or maintainer.`);
+  }
+  if (typeof value.language !== "string" || !["none", "basic", "fluent", "advanced"].includes(value.language)) {
+    throw new Error(`${path}.language must be none, basic, fluent, or advanced.`);
+  }
+  if (value.domain !== void 0) requireStringArray(value.domain, `${path}.domain`);
+  if (typeof value.readingDemand !== "string" || !["general", "technical", "specialist"].includes(value.readingDemand)) {
+    throw new Error(`${path}.readingDemand must be general, technical, or specialist.`);
+  }
+  if (typeof value.purpose !== "string" || !["overview", "explanation", "review"].includes(value.purpose)) {
+    throw new Error(`${path}.purpose must be overview, explanation, or review.`);
+  }
+  requireString(value.scope, `${path}.scope`);
+  if (value.estimatedMinutes !== void 0 && (typeof value.estimatedMinutes !== "number" || !Number.isFinite(value.estimatedMinutes) || value.estimatedMinutes <= 0)) {
+    throw new Error(`${path}.estimatedMinutes must be a finite positive number.`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function requireStringArray(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) {
+    throw new Error(`${path} must be an array of strings.`);
+  }
+}
+function requireOnlyKeys(value, allowed, path) {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`${path} contains unknown field${unexpected.length === 1 ? "" : "s"}: ${unexpected.join(", ")}`);
+  }
+}
+
 // src/changeTourSource.ts
-var CHANGE_TOUR_SOURCE_VERSION = 3;
+var CHANGE_TOUR_SOURCE_VERSION = 5;
 function parseChangeTourSource(value) {
-  if (isRecord(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_SOURCE_VERSION) {
+  if (isRecord2(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_SOURCE_VERSION) {
     throw new Error(
       `This tour uses source format version ${value.version}, but this version of Bygone supports up to version ${CHANGE_TOUR_SOURCE_VERSION}. Upgrade Bygone to open it.`
     );
   }
-  if (!isRecord(value) || value.version !== 1 && value.version !== 2 && value.version !== CHANGE_TOUR_SOURCE_VERSION) {
+  if (isRecord2(value) && value.version === 3) {
+    throw new Error("Tour source format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
+  }
+  if (!isRecord2(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== CHANGE_TOUR_SOURCE_VERSION) {
     throw new Error("Unsupported or missing change-tour source version.");
   }
-  requireOnlyKeys(value, [
+  requireOnlyKeys2(value, [
     "version",
     "title",
     "windowTitle",
@@ -256,62 +388,65 @@ function parseChangeTourSource(value) {
     "chapters",
     "tours",
     "coverage",
-    "review"
+    "opening",
+    "conclusion",
+    "details"
   ], "source");
+  validateTourFraming(value, value.version, "source");
   optionalString(value.title, "title");
   optionalString(value.windowTitle, "windowTitle");
   optionalString(value.sourceUrl, "sourceUrl");
   if (value.range !== void 0) {
-    if (!isRecord(value.range)) throw new Error("range must be an object.");
-    requireOnlyKeys(value.range, ["base", "head"], "range");
-    requireString(value.range.base, "range.base");
-    requireString(value.range.head, "range.head");
+    if (!isRecord2(value.range)) throw new Error("range must be an object.");
+    requireOnlyKeys2(value.range, ["base", "head"], "range");
+    requireString2(value.range.base, "range.base");
+    requireString2(value.range.head, "range.head");
   }
   if (value.coverage !== void 0) {
-    if (!isRecord(value.coverage) || !Array.isArray(value.coverage.exclusions)) {
+    if (!isRecord2(value.coverage) || !Array.isArray(value.coverage.exclusions)) {
       throw new Error("coverage must contain an exclusions array.");
     }
-    requireOnlyKeys(value.coverage, ["exclusions"], "coverage");
+    requireOnlyKeys2(value.coverage, ["exclusions"], "coverage");
     for (const [index, exclusion] of value.coverage.exclusions.entries()) {
       const exclusionPath = `coverage.exclusions[${index}]`;
-      if (!isRecord(exclusion)) throw new Error(`${exclusionPath} must be an object.`);
-      requireOnlyKeys(exclusion, ["path", "hunks", "reason"], exclusionPath);
-      requireString(exclusion.path, `${exclusionPath}.path`);
-      requireString(exclusion.reason, `${exclusionPath}.reason`);
-      if (exclusion.hunks !== void 0) requireStringArray(exclusion.hunks, `${exclusionPath}.hunks`);
+      if (!isRecord2(exclusion)) throw new Error(`${exclusionPath} must be an object.`);
+      requireOnlyKeys2(exclusion, ["path", "hunks", "reason"], exclusionPath);
+      requireString2(exclusion.path, `${exclusionPath}.path`);
+      requireString2(exclusion.reason, `${exclusionPath}.reason`);
+      if (exclusion.hunks !== void 0) requireStringArray2(exclusion.hunks, `${exclusionPath}.hunks`);
     }
   }
-  if (!isRecord(value.anchors)) {
+  if (!isRecord2(value.anchors)) {
     throw new Error("anchors must be an object.");
   }
   for (const [id, anchor] of Object.entries(value.anchors)) {
-    if (!isRecord(anchor)) {
+    if (!isRecord2(anchor)) {
       throw new Error(`anchors.${id} must be an object.`);
     }
-    requireOnlyKeys(anchor, ["file", "revision", "contains", "occurrence"], `anchors.${id}`);
-    requireString(anchor.file, `anchors.${id}.file`);
+    requireOnlyKeys2(anchor, ["file", "revision", "contains", "occurrence"], `anchors.${id}`);
+    requireString2(anchor.file, `anchors.${id}.file`);
     if (anchor.revision !== "base" && anchor.revision !== "head") {
       throw new Error(`anchors.${id}.revision must be base or head.`);
     }
-    requireString(anchor.contains, `anchors.${id}.contains`);
+    requireString2(anchor.contains, `anchors.${id}.contains`);
     if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || Number(anchor.occurrence) < 1)) {
       throw new Error(`anchors.${id}.occurrence must be a positive integer.`);
     }
   }
-  const rawConnections = Array.isArray(value.connections) ? value.connections : isRecord(value.connections) ? Object.entries(value.connections).map(([id, connection]) => isRecord(connection) ? { id, ...connection } : connection) : null;
+  const rawConnections = Array.isArray(value.connections) ? value.connections : isRecord2(value.connections) ? Object.entries(value.connections).map(([id, connection]) => isRecord2(connection) ? { id, ...connection } : connection) : null;
   if (!rawConnections || !Array.isArray(value.chapters) || value.chapters.length === 0) {
     throw new Error("connections must be an array or object, and chapters must be a non-empty array.");
   }
   const connectionIds = /* @__PURE__ */ new Set();
   for (const [index, connection] of rawConnections.entries()) {
-    if (!isRecord(connection)) {
+    if (!isRecord2(connection)) {
       throw new Error(`connections[${index}] must be an object.`);
     }
-    requireOnlyKeys(connection, ["id", "from", "to", "label"], `connections[${index}]`);
-    requireString(connection.id, `connections[${index}].id`);
-    requireString(connection.from, `connections[${index}].from`);
-    requireString(connection.to, `connections[${index}].to`);
-    requireString(connection.label, `connections[${index}].label`);
+    requireOnlyKeys2(connection, ["id", "from", "to", "label"], `connections[${index}]`);
+    requireString2(connection.id, `connections[${index}].id`);
+    requireString2(connection.from, `connections[${index}].from`);
+    requireString2(connection.to, `connections[${index}].to`);
+    requireString2(connection.label, `connections[${index}].label`);
     const { id, from, to } = connection;
     if (!value.anchors[from] || !value.anchors[to]) {
       throw new Error(`Connection ${id} references an unknown anchor.`);
@@ -321,7 +456,7 @@ function parseChangeTourSource(value) {
     }
     connectionIds.add(id);
   }
-  const authoredWalkthroughSteps = validateSourceChapters(
+  validateSourceChapters(
     value.chapters,
     "chapters",
     value.version,
@@ -329,10 +464,14 @@ function parseChangeTourSource(value) {
     connectionIds,
     "root"
   );
+  if (value.details !== void 0) {
+    if (value.version < 5) throw new Error("source.details requires version 5.");
+    validateChangeTourDetails(value.details, "details");
+  }
   if (value.tours !== void 0) {
-    if (value.version !== 3) throw new Error("Independent tours require version 3.");
-    if (!isRecord(value.tours)) throw new Error("tours must be an object.");
-    requireOnlyKeys(value.tours, ["historical", "deconstructed"], "tours");
+    if (value.version < 4) throw new Error("Independent tours require version 4.");
+    if (!isRecord2(value.tours)) throw new Error("tours must be an object.");
+    requireOnlyKeys2(value.tours, ["historical", "deconstructed"], "tours");
     if (value.tours.historical === void 0 && value.tours.deconstructed === void 0) {
       throw new Error("tours must contain a historical or deconstructed tour.");
     }
@@ -340,15 +479,16 @@ function parseChangeTourSource(value) {
       const tour = value.tours[mode];
       if (tour === void 0) continue;
       const path = `tours.${mode}`;
-      if (!isRecord(tour)) throw new Error(`${path} must be an object.`);
-      requireOnlyKeys(tour, ["chapters"], path);
+      if (!isRecord2(tour)) throw new Error(`${path} must be an object.`);
+      requireOnlyKeys2(tour, ["chapters", "opening", "conclusion", "details"], path);
+      validateTourFraming(tour, value.version, path);
       validateSourceChapters(tour.chapters, `${path}.chapters`, value.version, value.anchors, connectionIds, mode);
+      if (tour.details !== void 0) {
+        if (value.version < 5) throw new Error(`${path}.details requires source version 5.`);
+        validateChangeTourDetails(tour.details, `${path}.details`);
+      }
     }
   }
-  if (value.review !== void 0) {
-    if (value.version !== 3) throw new Error("Review notes require version 3.");
-    validateChangeTourReview(value.review, { authoredWalkthroughSteps });
-  }
   return { ...value, connections: rawConnections };
 }
 function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, connectionIds, mode) {
@@ -357,27 +497,31 @@ function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, c
   }
   const chapterIds = /* @__PURE__ */ new Set();
   const sceneIds = /* @__PURE__ */ new Set();
-  const authoredWalkthroughSteps = /* @__PURE__ */ new Map();
   for (const [chapterIndex, chapter] of chaptersValue.entries()) {
     const chapterPath = `${chaptersPath}[${chapterIndex}]`;
-    if (!isRecord(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
+    if (!isRecord2(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
       throw new Error(`${chapterPath} must contain a non-empty scenes array.`);
     }
-    requireString(chapter.id, `${chapterPath}.id`);
-    requireString(chapter.title, `${chapterPath}.title`);
-    requireOnlyKeys(chapter, ["id", "title", "scenes"], chapterPath);
+    requireString2(chapter.id, `${chapterPath}.id`);
+    requireString2(chapter.title, `${chapterPath}.title`);
+    if (chapter.summary !== void 0) {
+      if (version < 5) throw new Error(`${chapterPath}.summary requires source version 5.`);
+      requireProse2(chapter.summary, `${chapterPath}.summary`);
+    }
+    requireOnlyKeys2(chapter, ["id", "title", "summary", "scenes"], chapterPath);
     if (chapterIds.has(chapter.id)) throw new Error(`Duplicate chapter id: ${chapter.id}`);
     chapterIds.add(chapter.id);
     for (const [sceneIndex, scene] of chapter.scenes.entries()) {
       const path = `${chapterPath}.scenes[${sceneIndex}]`;
-      if (!isRecord(scene)) throw new Error(`${path} must be an object.`);
-      requireString(scene.id, `${path}.id`);
-      requireString(scene.title, `${path}.title`);
+      if (!isRecord2(scene)) throw new Error(`${path} must be an object.`);
+      requireString2(scene.id, `${path}.id`);
+      requireString2(scene.title, `${path}.title`);
       if (sceneIds.has(scene.id)) throw new Error(`Duplicate scene id: ${scene.id}`);
       sceneIds.add(scene.id);
-      if (scene.overview !== void 0 && version !== 3) {
-        throw new Error(`${path}.overview requires version 3.`);
+      if (scene.overview !== void 0 && version < 4) {
+        throw new Error(`${path}.overview requires version 4.`);
       }
+      validateOverviewPurpose(scene.overview, version, `${path}.overview`);
       validateNarrative(scene, path);
       if (scene.kind === "deconstructed-diff") {
         if (mode === "historical") {
@@ -393,9 +537,6 @@ function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, c
         }
         if (requireRealEvidence || scene.steps !== void 0) {
           validateWalkthroughSteps(scene, path, anchors, connectionIds);
-          if (scene.steps !== void 0) {
-            authoredWalkthroughSteps.set(scene.id, collectStepIds(scene.steps));
-          }
         }
         continue;
       }
@@ -412,22 +553,20 @@ function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, c
       if (scene.kind !== void 0 && scene.kind !== "walkthrough") {
         throw new Error(`${path}.kind must be walkthrough, stacked-diff, or deconstructed-diff.`);
       }
-      requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
+      requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
       validateSceneOverview(scene.overview, `${path}.overview`, { allowComparison: false });
       validateWalkthroughSteps(scene, path, anchors, connectionIds);
-      authoredWalkthroughSteps.set(scene.id, collectStepIds(scene.steps));
     }
   }
-  if (mode === "deconstructed" && !chaptersValue.some((chapter) => isRecord(chapter) && Array.isArray(chapter.scenes) && chapter.scenes.some((scene) => isRecord(scene) && scene.kind === "deconstructed-diff"))) {
+  if (mode === "deconstructed" && !chaptersValue.some((chapter) => isRecord2(chapter) && Array.isArray(chapter.scenes) && chapter.scenes.some((scene) => isRecord2(scene) && scene.kind === "deconstructed-diff"))) {
     throw new Error(`${chaptersPath} must contain at least one deconstructed-diff scene.`);
   }
-  return authoredWalkthroughSteps;
 }
 function stackedOverviewEndpointIds(scene, path) {
   if (!Array.isArray(scene.stack)) {
     throw new Error(`${path}.stack must be an array.`);
   }
-  return scene.stack.filter(isRecord).map((entry) => typeof entry.id === "string" ? entry.id : "").filter((id) => id.length > 0);
+  return scene.stack.filter(isRecord2).map((entry) => typeof entry.id === "string" ? entry.id : "").filter((id) => id.length > 0);
 }
 function deconstructedOverviewEndpointIds(scene, path) {
   if (!Array.isArray(scene.stages)) {
@@ -435,78 +574,11 @@ function deconstructedOverviewEndpointIds(scene, path) {
   }
   return [
     "explanation-baseline",
-    ...scene.stages.filter(isRecord).map((stage) => typeof stage.id === "string" ? `explanation-stage-${stage.id}` : "").filter((id) => id.length > 0)
+    ...scene.stages.filter(isRecord2).map((stage) => typeof stage.id === "string" ? `explanation-stage-${stage.id}` : "").filter((id) => id.length > 0)
   ];
 }
-function validateChangeTourReview(value, context = {}) {
-  if (!isRecord(value)) {
-    throw new Error("review must be an object.");
-  }
-  requireOnlyKeys(value, ["baseOid", "headOid", "items"], "review");
-  requireFullGitOid(value.baseOid, "review.baseOid");
-  requireFullGitOid(value.headOid, "review.headOid");
-  if (!Array.isArray(value.items) || value.items.length === 0) {
-    throw new Error("review.items must be a non-empty array.");
-  }
-  if (context.expectedRange) {
-    if (normalizeGitOid(value.baseOid) !== normalizeGitOid(context.expectedRange.baseOid)) {
-      throw new Error(
-        `Stale review: review.baseOid ${value.baseOid} does not match the resolved range.mergeBaseOid ${context.expectedRange.baseOid}.`
-      );
-    }
-    if (normalizeGitOid(value.headOid) !== normalizeGitOid(context.expectedRange.headOid)) {
-      throw new Error(
-        `Stale review: review.headOid ${value.headOid} does not match the resolved range.headOid ${context.expectedRange.headOid}.`
-      );
-    }
-  }
-  const itemIds = /* @__PURE__ */ new Set();
-  for (const [index, item] of value.items.entries()) {
-    const itemPath = `review.items[${index}]`;
-    if (!isRecord(item)) throw new Error(`${itemPath} must be an object.`);
-    requireOnlyKeys(item, ["id", "kind", "title", "body", "evidence", "nextCheck"], itemPath);
-    requireReviewString(item.id, `${itemPath}.id`);
-    if (itemIds.has(item.id)) throw new Error(`Duplicate review item id: ${item.id}`);
-    itemIds.add(item.id);
-    if (typeof item.kind !== "string" || !["concept", "boundary", "tradeoff", "question"].includes(item.kind)) {
-      throw new Error(`${itemPath}.kind must be concept, boundary, tradeoff, or question.`);
-    }
-    requireReviewString(item.title, `${itemPath}.title`);
-    requireReviewString(item.body, `${itemPath}.body`);
-    if (!Array.isArray(item.evidence)) {
-      throw new Error(`${itemPath}.evidence must be an array.`);
-    }
-    if (item.kind !== "question" && item.evidence.length === 0) {
-      throw new Error(`${itemPath}.evidence must contain at least one reference for claims.`);
-    }
-    if (item.kind === "question" && item.nextCheck === void 0) {
-      throw new Error(`${itemPath}.nextCheck must be a non-empty string for question items.`);
-    }
-    if (item.nextCheck !== void 0) requireReviewString(item.nextCheck, `${itemPath}.nextCheck`);
-    for (const [evidenceIndex, evidence] of item.evidence.entries()) {
-      const evidencePath = `${itemPath}.evidence[${evidenceIndex}]`;
-      if (!isRecord(evidence)) throw new Error(`${evidencePath} must be an object.`);
-      requireOnlyKeys(evidence, ["sceneId", "stepId"], evidencePath);
-      requireReviewString(evidence.sceneId, `${evidencePath}.sceneId`);
-      requireReviewString(evidence.stepId, `${evidencePath}.stepId`);
-      if (context.authoredWalkthroughSteps) {
-        const stepIds = context.authoredWalkthroughSteps.get(evidence.sceneId);
-        if (!stepIds) {
-          throw new Error(
-            `${evidencePath} references unknown authored walkthrough scene ${evidence.sceneId}.`
-          );
-        }
-        if (!stepIds.has(evidence.stepId)) {
-          throw new Error(
-            `${evidencePath} references unknown authored walkthrough step ${evidence.sceneId}/${evidence.stepId}.`
-          );
-        }
-      }
-    }
-  }
-}
 function validateDeconstructedScene(scene, path) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "base", "target", "stack", "steps", "stages", "exclusions"], path);
+  requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "base", "target", "stack", "steps", "stages", "exclusions"], path);
   optionalString(scene.base, `${path}.base`);
   optionalString(scene.target, `${path}.target`);
   if (!Array.isArray(scene.stages) || scene.stages.length === 0 || scene.stages.length > 12) {
@@ -515,11 +587,11 @@ function validateDeconstructedScene(scene, path) {
   const stageIds = /* @__PURE__ */ new Set();
   for (const [stageIndex, stage] of scene.stages.entries()) {
     const stagePath = `${path}.stages[${stageIndex}]`;
-    if (!isRecord(stage)) throw new Error(`${stagePath} must be an object.`);
-    requireOnlyKeys(stage, ["id", "title", "narration", "changes"], stagePath);
-    requireString(stage.id, `${stagePath}.id`);
-    requireString(stage.title, `${stagePath}.title`);
-    requireString(stage.narration, `${stagePath}.narration`);
+    if (!isRecord2(stage)) throw new Error(`${stagePath} must be an object.`);
+    requireOnlyKeys2(stage, ["id", "title", "narration", "changes"], stagePath);
+    requireString2(stage.id, `${stagePath}.id`);
+    requireString2(stage.title, `${stagePath}.title`);
+    requireString2(stage.narration, `${stagePath}.narration`);
     if (!Array.isArray(stage.changes) || stage.changes.length === 0) {
       throw new Error(`${stagePath}.changes must be a non-empty array.`);
     }
@@ -547,16 +619,17 @@ function validateWalkthroughSteps(scene, path, anchors, connectionIds) {
   const stepIds = /* @__PURE__ */ new Set();
   for (const [stepIndex, step] of scene.steps.entries()) {
     const stepPath = `${path}.steps[${stepIndex}]`;
-    if (!isRecord(step)) throw new Error(`${stepPath} must be an object.`);
-    requireString(step.id, `${stepPath}.id`);
-    requireString(step.title, `${stepPath}.title`);
-    requireString(step.body, `${stepPath}.body`);
-    requireString(step.focus, `${stepPath}.focus`);
-    requireOnlyKeys(step, ["id", "title", "body", "focus", "connection", "depth", "requirement"], stepPath);
+    if (!isRecord2(step)) throw new Error(`${stepPath} must be an object.`);
+    requireString2(step.id, `${stepPath}.id`);
+    requireString2(step.title, `${stepPath}.title`);
+    requireString2(step.body, `${stepPath}.body`);
+    requireString2(step.focus, `${stepPath}.focus`);
+    requireOnlyKeys2(step, ["id", "title", "body", "focus", "connection", "depth", "requirement", "image"], stepPath);
     if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
       throw new Error(`${stepPath}.depth must be mentioned, explained, or contextualized.`);
     }
     validateStepRequirement(step.requirement, `${stepPath}.requirement`);
+    validateTourImageSource(step.image, `${stepPath}.image`);
     if (stepIds.has(step.id)) throw new Error(`Duplicate step id in scene ${scene.id}: ${step.id}`);
     stepIds.add(step.id);
     if (!anchors[step.focus]) throw new Error(`${stepPath} references unknown anchor ${step.focus}.`);
@@ -567,14 +640,14 @@ function validateWalkthroughSteps(scene, path, anchors, connectionIds) {
   }
 }
 function validateDeconstructedSelection(value, path, requiresReason) {
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, requiresReason ? ["file", "hunks", "reason"] : ["file", "hunks"], path);
-  requireString(value.file, `${path}.file`);
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(value, requiresReason ? ["file", "hunks", "reason"] : ["file", "hunks"], path);
+  requireString2(value.file, `${path}.file`);
   if (!requiresReason || value.hunks !== void 0) {
-    requireStringArray(value.hunks, `${path}.hunks`);
+    requireStringArray2(value.hunks, `${path}.hunks`);
     if (value.hunks.length === 0) throw new Error(`${path}.hunks must not be empty.`);
   }
-  if (requiresReason) requireString(value.reason, `${path}.reason`);
+  if (requiresReason) requireString2(value.reason, `${path}.reason`);
 }
 function validateRealStack(stack, path, minimum) {
   if (!Array.isArray(stack) || stack.length < minimum || stack.length > 6) {
@@ -582,42 +655,42 @@ function validateRealStack(stack, path, minimum) {
   }
   const ids = /* @__PURE__ */ new Set();
   for (const [index, entry] of stack.entries()) {
-    if (!isRecord(entry)) throw new Error(`${path}[${index}] must be an object.`);
-    requireOnlyKeys(entry, ["id", "ref", "label"], `${path}[${index}]`);
-    requireString(entry.id, `${path}[${index}].id`);
-    requireString(entry.ref, `${path}[${index}].ref`);
+    if (!isRecord2(entry)) throw new Error(`${path}[${index}] must be an object.`);
+    requireOnlyKeys2(entry, ["id", "ref", "label"], `${path}[${index}]`);
+    requireString2(entry.id, `${path}[${index}].id`);
+    requireString2(entry.ref, `${path}[${index}].ref`);
     optionalString(entry.label, `${path}[${index}].label`);
     if (ids.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
     ids.add(entry.id);
   }
 }
 function validateStackedScene(scene, path, minimum = 3) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "stack", "files", "steps"], path);
+  requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "stack", "files", "steps"], path);
   if (!Array.isArray(scene.stack) || scene.stack.length < minimum || scene.stack.length > 6) {
     throw new Error(`${path}.stack must contain between ${minimum} and 6 revisions.`);
   }
   const stackIds = /* @__PURE__ */ new Set();
   for (const [index, entry] of scene.stack.entries()) {
     const entryPath = `${path}.stack[${index}]`;
-    if (!isRecord(entry)) throw new Error(`${entryPath} must be an object.`);
-    requireOnlyKeys(entry, ["id", "ref", "label"], entryPath);
-    requireString(entry.id, `${entryPath}.id`);
-    requireString(entry.ref, `${entryPath}.ref`);
+    if (!isRecord2(entry)) throw new Error(`${entryPath} must be an object.`);
+    requireOnlyKeys2(entry, ["id", "ref", "label"], entryPath);
+    requireString2(entry.id, `${entryPath}.id`);
+    requireString2(entry.ref, `${entryPath}.ref`);
     optionalString(entry.label, `${entryPath}.label`);
     if (stackIds.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
     stackIds.add(entry.id);
   }
-  if (scene.files !== void 0) requireStringArray(scene.files, `${path}.files`);
+  if (scene.files !== void 0) requireStringArray2(scene.files, `${path}.files`);
   if (!Array.isArray(scene.steps) || scene.steps.length === 0) throw new Error(`${path}.steps must be a non-empty array.`);
   const stepIds = /* @__PURE__ */ new Set();
   for (const [index, step] of scene.steps.entries()) {
     const stepPath = `${path}.steps[${index}]`;
-    if (!isRecord(step)) throw new Error(`${stepPath} must be an object.`);
-    requireOnlyKeys(step, ["id", "title", "body", "file", "pair", "side", "lines"], stepPath);
-    requireString(step.id, `${stepPath}.id`);
-    requireString(step.title, `${stepPath}.title`);
-    requireString(step.body, `${stepPath}.body`);
-    requireString(step.file, `${stepPath}.file`);
+    if (!isRecord2(step)) throw new Error(`${stepPath} must be an object.`);
+    requireOnlyKeys2(step, ["id", "title", "body", "file", "pair", "side", "lines"], stepPath);
+    requireString2(step.id, `${stepPath}.id`);
+    requireString2(step.title, `${stepPath}.title`);
+    requireString2(step.body, `${stepPath}.body`);
+    requireString2(step.file, `${stepPath}.file`);
     const stepId = step.id;
     if (stepIds.has(stepId)) throw new Error(`Duplicate step id in scene ${scene.id}: ${stepId}`);
     stepIds.add(stepId);
@@ -625,8 +698,8 @@ function validateStackedScene(scene, path, minimum = 3) {
       throw new Error(`${stepPath}.pair must contain two stack entry ids.`);
     }
     const pair = step.pair;
-    const leftIndex = scene.stack.findIndex((entry) => isRecord(entry) && entry.id === pair[0]);
-    const rightIndex = scene.stack.findIndex((entry) => isRecord(entry) && entry.id === pair[1]);
+    const leftIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[0]);
+    const rightIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[1]);
     if (leftIndex < 0 || rightIndex !== leftIndex + 1) throw new Error(`${stepPath}.pair must reference adjacent stack entries in order.`);
     if (step.side !== void 0 && step.side !== "left" && step.side !== "right") throw new Error(`${stepPath}.side must be left or right.`);
     if (step.lines !== void 0 && (!Array.isArray(step.lines) || step.lines.length !== 2 || step.lines.some((line) => !Number.isInteger(line) || Number(line) < 1) || Number(step.lines[1]) < Number(step.lines[0]))) {
@@ -636,10 +709,10 @@ function validateStackedScene(scene, path, minimum = 3) {
 }
 function validateStepRequirement(value, path) {
   if (value === void 0) return;
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, ["id", "text", "status", "source", "confidence"], path);
-  requireString(value.id, `${path}.id`);
-  requireString(value.text, `${path}.text`);
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(value, ["id", "text", "status", "source", "confidence"], path);
+  requireString2(value.id, `${path}.id`);
+  requireString2(value.text, `${path}.text`);
   if (value.status !== void 0 && !["fulfilled", "gap"].includes(String(value.status))) {
     throw new Error(`${path}.status must be fulfilled or gap.`);
   }
@@ -650,20 +723,21 @@ function validateStepRequirement(value, path) {
 }
 function validateSceneOverview(value, path, options = {}) {
   if (value === void 0) return;
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, ["kind", "path", "comparison"], path);
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(value, ["kind", "path", "comparison", "purpose"], path);
   if (value.kind !== "directory-diff") {
     throw new Error(`${path}.kind must be directory-diff.`);
   }
+  if (value.purpose !== void 0) requireString2(value.purpose, `${path}.purpose`);
   if (value.path !== void 0) validateDirectoryOverviewPath(value.path, `${path}.path`);
   if (value.comparison === void 0) return;
   if (options.allowComparison === false) {
     throw new Error(`${path}.comparison is not supported for walkthrough scenes; use the fixed base-to-head comparison.`);
   }
-  if (!isRecord(value.comparison)) throw new Error(`${path}.comparison must be an object.`);
-  requireOnlyKeys(value.comparison, ["from", "to"], `${path}.comparison`);
-  requireString(value.comparison.from, `${path}.comparison.from`);
-  requireString(value.comparison.to, `${path}.comparison.to`);
+  if (!isRecord2(value.comparison)) throw new Error(`${path}.comparison must be an object.`);
+  requireOnlyKeys2(value.comparison, ["from", "to"], `${path}.comparison`);
+  requireString2(value.comparison.from, `${path}.comparison.from`);
+  requireString2(value.comparison.to, `${path}.comparison.to`);
   if (value.comparison.from === value.comparison.to) {
     throw new Error(`${path}.comparison.from and to must identify distinct endpoints.`);
   }
@@ -676,7 +750,7 @@ function validateSceneOverview(value, path, options = {}) {
   }
 }
 function validateDirectoryOverviewPath(value, path) {
-  requireString(value, path);
+  requireString2(value, path);
   if (value.includes("\\")) {
     throw new Error(`${path} must use a relative POSIX directory path without backslashes.`);
   }
@@ -687,53 +761,36 @@ function validateDirectoryOverviewPath(value, path) {
     throw new Error(`${path} must not contain parent-directory traversal.`);
   }
 }
-function collectStepIds(value) {
-  const ids = /* @__PURE__ */ new Set();
-  if (!Array.isArray(value)) return ids;
-  for (const step of value) {
-    if (isRecord(step) && typeof step.id === "string") ids.add(step.id);
-  }
-  return ids;
-}
 function validateNarrative(value, path) {
-  requireString(value.summary, `${path}.summary`);
-  requireStringArray(value.bullets, `${path}.bullets`);
-  requireStringArray(value.tags, `${path}.tags`);
-  requireString(value.takeaway, `${path}.takeaway`);
+  requireString2(value.summary, `${path}.summary`);
+  requireStringArray2(value.bullets, `${path}.bullets`);
+  requireStringArray2(value.tags, `${path}.tags`);
+  requireString2(value.takeaway, `${path}.takeaway`);
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function requireString(value, path) {
+function requireString2(value, path) {
   if (typeof value !== "string" || value.length === 0) {
     throw new Error(`${path} must be a non-empty string.`);
   }
 }
-function requireFullGitOid(value, path) {
-  requireString(value, path);
-  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value)) {
-    throw new Error(`${path} must be a full 40- or 64-character hexadecimal Git OID.`);
+function optionalString(value, path) {
+  if (value !== void 0) {
+    requireString2(value, path);
   }
 }
-function requireReviewString(value, path) {
-  if (typeof value !== "string" || value.trim().length === 0) {
+function requireProse2(value, path) {
+  if (typeof value !== "string" || !value.trim()) {
     throw new Error(`${path} must be a non-empty string.`);
   }
 }
-function normalizeGitOid(value) {
-  return value.toLowerCase();
-}
-function optionalString(value, path) {
-  if (value !== void 0) {
-    requireString(value, path);
-  }
-}
-function requireStringArray(value, path) {
+function requireStringArray2(value, path) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
     throw new Error(`${path} must be an array of strings.`);
   }
 }
-function requireOnlyKeys(value, allowed, path) {
+function requireOnlyKeys2(value, allowed, path) {
   const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
   if (unexpected.length > 0) {
     throw new Error(`${path} contains unknown field${unexpected.length === 1 ? "" : "s"}: ${unexpected.join(", ")}`);
@@ -741,37 +798,42 @@ function requireOnlyKeys(value, allowed, path) {
 }
 
 // src/changeTourManifest.ts
-var CHANGE_TOUR_MANIFEST_VERSION = 3;
-function parseChangeTourManifest(value) {
-  if (isRecord2(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_MANIFEST_VERSION) {
+var CHANGE_TOUR_MANIFEST_VERSION = 5;
+function parseChangeTourManifest(value, options = {}) {
+  if (isRecord3(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_MANIFEST_VERSION) {
     throw new Error(
       `This tour uses manifest format version ${value.version}, but this version of Bygone supports up to version ${CHANGE_TOUR_MANIFEST_VERSION}. Upgrade Bygone to open it.`
     );
   }
-  if (!isRecord2(value) || value.version !== 1 && value.version !== 2 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
+  if (isRecord3(value) && value.version === 3) {
+    throw new Error("Tour manifest format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
+  }
+  if (!isRecord3(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
     throw new Error(`Unsupported or missing change-tour manifest version.`);
   }
-  requireString2(value.title, "title");
-  requireString2(value.generatedAt, "generatedAt");
+  if ("review" in value) throw new Error("Change-tour manifests do not support the review field. Put observations in scene and step narrative.");
+  validateTourFraming(value, value.version, "manifest");
+  requireString3(value.title, "title");
+  requireString3(value.generatedAt, "generatedAt");
   if (value.windowTitle !== void 0) {
-    requireString2(value.windowTitle, "windowTitle");
+    requireString3(value.windowTitle, "windowTitle");
   }
   if (value.sourceUrl !== void 0) {
-    requireString2(value.sourceUrl, "sourceUrl");
+    requireString3(value.sourceUrl, "sourceUrl");
   }
-  if (!isRecord2(value.range)) {
+  if (!isRecord3(value.range)) {
     throw new Error("Change-tour manifest range must be an object.");
   }
   for (const key of ["baseRef", "headRef", "mergeBaseOid", "headOid"]) {
-    requireString2(value.range[key], `range.${key}`);
+    requireString3(value.range[key], `range.${key}`);
   }
-  if (!isRecord2(value.summary)) {
+  if (!isRecord3(value.summary)) {
     throw new Error("Change-tour manifest summary must be an object.");
   }
   for (const key of ["changedFiles", "includedScenes", "additions", "deletions", "commitCount"]) {
     requireNonNegativeInteger(value.summary[key], `summary.${key}`);
   }
-  requireStringArray2(value.summary.omittedFiles, "summary.omittedFiles");
+  requireStringArray3(value.summary.omittedFiles, "summary.omittedFiles");
   if (!Array.isArray(value.commits) || !Array.isArray(value.chapters) || !Array.isArray(value.scenes)) {
     throw new Error("Change-tour manifest commits, chapters, and scenes must be arrays.");
   }
@@ -787,12 +849,13 @@ function parseChangeTourManifest(value) {
     sceneIds.add(candidate.id);
   }
   for (const [index, candidate] of value.chapters.entries()) {
-    if (!isRecord2(candidate)) {
+    if (!isRecord3(candidate)) {
       throw new Error(`chapters[${index}] must be an object.`);
     }
-    requireString2(candidate.id, `chapters[${index}].id`);
-    requireString2(candidate.title, `chapters[${index}].title`);
-    requireStringArray2(candidate.sceneIds, `chapters[${index}].sceneIds`);
+    requireString3(candidate.id, `chapters[${index}].id`);
+    requireString3(candidate.title, `chapters[${index}].title`);
+    validateChapterSummary(candidate.summary, value.version, `chapters[${index}].summary`);
+    requireStringArray3(candidate.sceneIds, `chapters[${index}].sceneIds`);
     for (const sceneId of candidate.sceneIds) {
       if (!sceneIds.has(sceneId)) {
         throw new Error(`Chapter references unknown scene id: ${sceneId}`);
@@ -802,6 +865,10 @@ function parseChangeTourManifest(value) {
   if (value.summary.includedScenes !== value.scenes.length) {
     throw new Error("summary.includedScenes must match the number of scenes.");
   }
+  if (value.details !== void 0) {
+    if (value.version !== 5) throw new Error("details requires manifest version 5.");
+    validateChangeTourDetails(value.details, "details");
+  }
   const files = value.files === void 0 ? collectLegacyTourFiles(value.scenes) : value.files.map((candidate, index) => {
     validateTourFile(candidate, index);
     return candidate;
@@ -813,40 +880,14 @@ function parseChangeTourManifest(value) {
     validateAuthoringCoverage(value.authoringCoverage, value.version);
   }
   if (value.tours !== void 0) {
-    if (value.version !== 3) throw new Error("Independent tours require manifest version 3.");
+    if (value.version !== 4 && value.version !== 5) throw new Error("Independent tours require manifest version 4.");
     validateModeTours(value.tours, value.version);
   }
-  if (value.version !== 1) validateZoom(value, value.version);
-  if (value.review !== void 0) {
-    if (value.version !== 3) throw new Error("Review notes require manifest version 3.");
-    const evidenceScenes = value.version >= 2 && isRecord2(value.zoom) && isRecord2(value.zoom.final) ? value.zoom.final.scenes : value.scenes;
-    validateChangeTourReview(value.review, {
-      expectedRange: {
-        baseOid: String(value.range.mergeBaseOid),
-        headOid: String(value.range.headOid)
-      },
-      authoredWalkthroughSteps: collectAuthoredWalkthroughStepIds(evidenceScenes)
-    });
-  }
+  if (value.version !== 1) validateZoom(value, value.version, Boolean(options.exported));
   return { ...value, files };
 }
-function collectAuthoredWalkthroughStepIds(value) {
-  const scenes = /* @__PURE__ */ new Map();
-  if (!Array.isArray(value)) return scenes;
-  for (const scene of value) {
-    if (!isRecord2(scene) || scene.kind !== "walkthrough" || !Array.isArray(scene.steps) || typeof scene.id !== "string") {
-      continue;
-    }
-    const stepIds = /* @__PURE__ */ new Set();
-    for (const step of scene.steps) {
-      if (isRecord2(step) && typeof step.id === "string") stepIds.add(step.id);
-    }
-    scenes.set(scene.id, stepIds);
-  }
-  return scenes;
-}
 function validateAuthoringCoverage(value, version) {
-  if (!isRecord2(value) || !isRecord2(value.walkthrough) || !Array.isArray(value.explanationAssignments)) {
+  if (!isRecord3(value) || !isRecord3(value.walkthrough) || !Array.isArray(value.explanationAssignments)) {
     throw new Error("authoringCoverage must contain walkthrough and explanationAssignments.");
   }
   const expectedScope = version >= 2 ? "final" : "tour";
@@ -861,8 +902,8 @@ function validateAuthoringCoverage(value, version) {
   }
   for (const [index, assignment] of value.explanationAssignments.entries()) {
     const path = `authoringCoverage.explanationAssignments[${index}]`;
-    if (!isRecord2(assignment)) throw new Error(`${path} must be an object.`);
-    requireString2(assignment.sceneId, `${path}.sceneId`);
+    if (!isRecord3(assignment)) throw new Error(`${path} must be an object.`);
+    requireString3(assignment.sceneId, `${path}.sceneId`);
     requireNonNegativeInteger(assignment.assignedUnits, `${path}.assignedUnits`);
     requireNonNegativeInteger(assignment.excludedUnits, `${path}.excludedUnits`);
     requireNonNegativeInteger(assignment.completeUnits, `${path}.completeUnits`);
@@ -874,16 +915,17 @@ function validateAuthoringCoverage(value, version) {
   }
 }
 function validateModeTours(value, version) {
-  if (!isRecord2(value)) throw new Error("Change-tour manifest tours must be an object.");
+  if (!isRecord3(value)) throw new Error("Change-tour manifest tours must be an object.");
   if (value.historical === void 0 && value.deconstructed === void 0) {
     throw new Error("Change-tour manifest tours must contain a historical or deconstructed tour.");
   }
   for (const mode of ["historical", "deconstructed"]) {
     const tour = value[mode];
     if (tour === void 0) continue;
-    if (!isRecord2(tour) || !Array.isArray(tour.chapters) || !Array.isArray(tour.scenes) || tour.chapters.length === 0 || tour.scenes.length === 0) {
+    if (!isRecord3(tour) || !Array.isArray(tour.chapters) || !Array.isArray(tour.scenes) || tour.chapters.length === 0 || tour.scenes.length === 0) {
       throw new Error(`Change-tour manifest tours.${mode} must contain non-empty chapters and scenes arrays.`);
     }
+    validateTourFraming(tour, version, `tours.${mode}`);
     const sceneIds = /* @__PURE__ */ new Set();
     let hasDeconstructed = false;
     for (const [index, scene] of tour.scenes.entries()) {
@@ -897,16 +939,21 @@ function validateModeTours(value, version) {
         throw new Error("Historical tours cannot contain synthetic deconstructed scenes.");
       }
     }
+    if (tour.details !== void 0) {
+      if (version !== 5) throw new Error(`tours.${mode}.details requires manifest version 5.`);
+      validateChangeTourDetails(tour.details, `tours.${mode}.details`);
+    }
     if (mode === "deconstructed" && !hasDeconstructed) {
       throw new Error("Deconstructed tours must contain a constructed deconstructed-diff scene.");
     }
     for (const [index, chapter] of tour.chapters.entries()) {
-      if (!isRecord2(chapter)) {
+      if (!isRecord3(chapter)) {
         throw new Error(`tours.${mode}.chapters[${index}] must be an object.`);
       }
-      requireString2(chapter.id, `tours.${mode}.chapters[${index}].id`);
-      requireString2(chapter.title, `tours.${mode}.chapters[${index}].title`);
-      requireStringArray2(chapter.sceneIds, `tours.${mode}.chapters[${index}].sceneIds`);
+      requireString3(chapter.id, `tours.${mode}.chapters[${index}].id`);
+      requireString3(chapter.title, `tours.${mode}.chapters[${index}].title`);
+      validateChapterSummary(chapter.summary, version, `tours.${mode}.chapters[${index}].summary`);
+      requireStringArray3(chapter.sceneIds, `tours.${mode}.chapters[${index}].sceneIds`);
       for (const sceneId of chapter.sceneIds) {
         if (!sceneIds.has(sceneId)) {
           throw new Error(`tours.${mode} chapter references unknown scene id: ${sceneId}`);
@@ -916,28 +963,28 @@ function validateModeTours(value, version) {
   }
 }
 function parseChangeTourStory(value) {
-  if (!isRecord2(value) || !Array.isArray(value.scenes)) {
+  if (!isRecord3(value) || !Array.isArray(value.scenes)) {
     throw new Error("Change-tour story must contain a scenes array.");
   }
   if (value.title !== void 0) {
-    requireString2(value.title, "title");
+    requireString3(value.title, "title");
   }
   if (value.sourceUrl !== void 0) {
-    requireString2(value.sourceUrl, "sourceUrl");
+    requireString3(value.sourceUrl, "sourceUrl");
   }
   for (const [index, scene] of value.scenes.entries()) {
-    if (!isRecord2(scene) || scene.kind !== "discussion" && scene.kind !== "file") {
+    if (!isRecord3(scene) || scene.kind !== "discussion" && scene.kind !== "file") {
       throw new Error(`story.scenes[${index}] must be a discussion or file scene.`);
     }
-    requireString2(scene.chapterId, `story.scenes[${index}].chapterId`);
-    requireString2(scene.chapterTitle, `story.scenes[${index}].chapterTitle`);
+    requireString3(scene.chapterId, `story.scenes[${index}].chapterId`);
+    requireString3(scene.chapterTitle, `story.scenes[${index}].chapterTitle`);
     validateNarrative2(scene, `story.scenes[${index}]`);
     if (scene.kind === "discussion") {
-      requireString2(scene.title, `story.scenes[${index}].title`);
+      requireString3(scene.title, `story.scenes[${index}].title`);
     } else {
-      requireString2(scene.path, `story.scenes[${index}].path`);
+      requireString3(scene.path, `story.scenes[${index}].path`);
       if (scene.title !== void 0) {
-        requireString2(scene.title, `story.scenes[${index}].title`);
+        requireString3(scene.title, `story.scenes[${index}].title`);
       }
       if (scene.focusChangeIndex !== void 0) {
         requireNonNegativeInteger(scene.focusChangeIndex, `story.scenes[${index}].focusChangeIndex`);
@@ -946,11 +993,11 @@ function parseChangeTourStory(value) {
   }
   return value;
 }
-function validateZoom(value, version) {
-  if (!isRecord2(value.repository) || typeof value.repository.root !== "string" || !value.repository.root) {
+function validateZoom(value, version, exported) {
+  if (!exported && (!isRecord3(value.repository) || typeof value.repository.root !== "string" || !value.repository.root)) {
     throw new Error("A v2 tour requires its originating repository.root.");
   }
-  if (!isRecord2(value.zoom) || !Array.isArray(value.zoom.revisions) || !isRecord2(value.zoom.final)) {
+  if (!isRecord3(value.zoom) || !Array.isArray(value.zoom.revisions) || !isRecord3(value.zoom.final)) {
     throw new Error("A v2 tour requires zoom metadata and real revision evidence.");
   }
   const scenes = value.scenes;
@@ -995,27 +1042,29 @@ function validateZoom(value, version) {
     finalSceneIds.add(scene.id);
   }
   for (const [index, chapter] of value.zoom.final.chapters.entries()) {
-    if (!isRecord2(chapter) || !Array.isArray(chapter.sceneIds)) {
+    if (!isRecord3(chapter) || !Array.isArray(chapter.sceneIds)) {
       throw new Error(`zoom.final.chapters[${index}] must contain sceneIds.`);
     }
-    requireString2(chapter.id, `zoom.final.chapters[${index}].id`);
-    requireString2(chapter.title, `zoom.final.chapters[${index}].title`);
+    requireString3(chapter.id, `zoom.final.chapters[${index}].id`);
+    requireString3(chapter.title, `zoom.final.chapters[${index}].title`);
+    validateChapterSummary(chapter.summary, version, `zoom.final.chapters[${index}].summary`);
     for (const sceneId of chapter.sceneIds) {
-      requireString2(sceneId, `zoom.final.chapters[${index}].sceneIds`);
+      requireString3(sceneId, `zoom.final.chapters[${index}].sceneIds`);
       if (!finalSceneIds.has(sceneId)) throw new Error(`Final tour chapter references unknown scene: ${sceneId}`);
     }
   }
 }
 function validateScene(value, index, version) {
-  if (!isRecord2(value) || !["text-diff", "discussion", "walkthrough", "stacked-diff", "deconstructed-diff"].includes(String(value.kind))) {
+  if (!isRecord3(value) || !["text-diff", "discussion", "walkthrough", "stacked-diff", "deconstructed-diff"].includes(String(value.kind))) {
     throw new Error(`scenes[${index}] must be a text-diff, discussion, walkthrough, stacked-diff, or deconstructed-diff scene.`);
   }
   for (const key of ["id", "title"]) {
-    requireString2(value[key], `scenes[${index}].${key}`);
+    requireString3(value[key], `scenes[${index}].${key}`);
   }
-  if (value.overview !== void 0 && version !== 3) {
-    throw new Error(`scenes[${index}].overview requires manifest version 3.`);
+  if (value.overview !== void 0 && version < 4) {
+    throw new Error(`scenes[${index}].overview requires manifest version 4.`);
   }
+  validateOverviewPurpose(value.overview, version, `scenes[${index}].overview`);
   validateNarrative2(value, `scenes[${index}]`);
   if (value.kind === "discussion") {
     validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
@@ -1028,21 +1077,22 @@ function validateScene(value, index, version) {
     }
     for (const [stepIndex, step] of value.steps.entries()) {
       const path = `scenes[${index}].steps[${stepIndex}]`;
-      if (!isRecord2(step) || !isRecord2(step.focus) || !isRecord2(step.diff)) {
+      if (!isRecord3(step) || !isRecord3(step.focus) || !isRecord3(step.diff)) {
         throw new Error(`${path} must contain focus and diff objects.`);
       }
-      for (const key of ["id", "title", "body"]) requireString2(step[key], `${path}.${key}`);
+      for (const key of ["id", "title", "body"]) requireString3(step[key], `${path}.${key}`);
       if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
         throw new Error(`${path}.depth must be mentioned, explained, or contextualized.`);
       }
       validateStepRequirement(step.requirement, `${path}.requirement`);
+      validateTourImage(step.image, `${path}.image`);
       validateResolvedAnchor(step.focus, `${path}.focus`);
       validateScene(step.diff, index, version);
       if (step.diff.kind !== "text-diff") throw new Error(`${path}.diff must be a text-diff scene.`);
       if (step.connection !== void 0) {
-        if (!isRecord2(step.connection)) throw new Error(`${path}.connection must be an object.`);
-        requireString2(step.connection.id, `${path}.connection.id`);
-        requireString2(step.connection.label, `${path}.connection.label`);
+        if (!isRecord3(step.connection)) throw new Error(`${path}.connection must be an object.`);
+        requireString3(step.connection.id, `${path}.connection.id`);
+        requireString3(step.connection.label, `${path}.connection.label`);
         validateResolvedAnchor(step.connection.from, `${path}.connection.from`);
         validateResolvedAnchor(step.connection.to, `${path}.connection.to`);
       }
@@ -1065,12 +1115,12 @@ function validateScene(value, index, version) {
   }
   validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
   for (const key of ["path", "leftLabel", "rightLabel", "leftContent", "rightContent"]) {
-    requireString2(value[key], `scenes[${index}].${key}`);
+    requireString3(value[key], `scenes[${index}].${key}`);
   }
   if (value.previousPath !== void 0) {
-    requireString2(value.previousPath, `scenes[${index}].previousPath`);
+    requireString3(value.previousPath, `scenes[${index}].previousPath`);
   }
-  requireString2(value.changeKind, `scenes[${index}].changeKind`);
+  requireString3(value.changeKind, `scenes[${index}].changeKind`);
   requireNonNegativeInteger(value.additions, `scenes[${index}].additions`);
   requireNonNegativeInteger(value.deletions, `scenes[${index}].deletions`);
   if (value.focusChangeIndex !== void 0) {
@@ -1082,8 +1132,8 @@ function validateStackedScene2(value, index) {
     throw new Error(`scenes[${index}].stack must contain between 2 and 6 revisions.`);
   }
   for (const [panelIndex, panel] of value.stack.entries()) {
-    if (!isRecord2(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
-    for (const key of ["id", "ref", "oid", "label"]) requireString2(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
+    if (!isRecord3(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
+    for (const key of ["id", "ref", "oid", "label"]) requireString3(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
   }
   validateMultiPanelFiles(value.files, value.stack.length, index);
   validateMultiPanelSteps(value.steps, value.stack.length, index, false);
@@ -1092,33 +1142,33 @@ function validateDeconstructedScene2(value, index) {
   if (value.stageLabel !== "Explanation stages") {
     throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
   }
-  if (!isRecord2(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
+  if (!isRecord3(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
   for (const key of ["baseRef", "targetRef", "baseOid", "targetOid"]) {
-    requireString2(value.realRange[key], `scenes[${index}].realRange.${key}`);
+    requireString3(value.realRange[key], `scenes[${index}].realRange.${key}`);
   }
   if (!Array.isArray(value.panels) || value.panels.length < 2 || value.panels.length > 13) {
     throw new Error(`scenes[${index}].panels must contain a baseline and between 1 and 12 stages.`);
   }
   const panels = value.panels;
   for (const [panelIndex, panel] of panels.entries()) {
-    if (!isRecord2(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
-    for (const key of ["id", "label", "role"]) requireString2(panel[key], `scenes[${index}].panels[${panelIndex}].${key}`);
+    if (!isRecord3(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
+    for (const key of ["id", "label", "role"]) requireString3(panel[key], `scenes[${index}].panels[${panelIndex}].${key}`);
     const expectedRole = panelIndex === 0 ? "baseline" : "stage";
     if (panel.role !== expectedRole) throw new Error(`scenes[${index}].panels[${panelIndex}].role must be ${expectedRole}.`);
-    if (panelIndex > 0) requireString2(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
+    if (panelIndex > 0) requireString3(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
   }
   validateMultiPanelFiles(value.files, panels.length, index);
   validateMultiPanelSteps(value.steps, panels.length, index, true);
   if (Array.isArray(value.steps)) {
     let previousPairIndex = -1;
     value.steps.forEach((step, stepIndex) => {
-      if (!isRecord2(step)) return;
+      if (!isRecord3(step)) return;
       const pairIndex = Number(step.pairIndex);
       if (pairIndex < previousPairIndex) {
         throw new Error(`scenes[${index}].steps must remain grouped in explanation stage order.`);
       }
       previousPairIndex = pairIndex;
-      if (step.stageId !== void 0) requireString2(step.stageId, `scenes[${index}].steps[${stepIndex}].stageId`);
+      if (step.stageId !== void 0) requireString3(step.stageId, `scenes[${index}].steps[${stepIndex}].stageId`);
       if (step.stageIndex !== void 0) requireNonNegativeInteger(step.stageIndex, `scenes[${index}].steps[${stepIndex}].stageIndex`);
       if (step.focusIndex !== void 0) requireNonNegativeInteger(step.focusIndex, `scenes[${index}].steps[${stepIndex}].focusIndex`);
       if (step.focusCount !== void 0) requirePositiveInteger(step.focusCount, `scenes[${index}].steps[${stepIndex}].focusCount`);
@@ -1131,14 +1181,14 @@ function validateDeconstructedScene2(value, index) {
     });
     for (let stageIndex = 0; stageIndex < panels.length - 1; stageIndex += 1) {
       const panel = panels[stageIndex + 1];
-      const stageSteps = value.steps.filter((step) => isRecord2(step) && Number(step.pairIndex) === stageIndex);
-      if (!isRecord2(panel) || stageSteps.length === 0) {
+      const stageSteps = value.steps.filter((step) => isRecord3(step) && Number(step.pairIndex) === stageIndex);
+      if (!isRecord3(panel) || stageSteps.length === 0) {
         throw new Error(`scenes[${index}].steps must cover every explanation stage.`);
       }
       const firstStep = stageSteps[0];
-      const fallbackStageId = isRecord2(firstStep) ? firstStep.id : void 0;
+      const fallbackStageId = isRecord3(firstStep) ? firstStep.id : void 0;
       if (stageSteps.some((step) => {
-        if (!isRecord2(step)) return true;
+        if (!isRecord3(step)) return true;
         return (step.stageId ?? fallbackStageId) !== panel.stageId;
       })) {
         throw new Error(`scenes[${index}].panels must align with explanation stage ids.`);
@@ -1149,15 +1199,15 @@ function validateDeconstructedScene2(value, index) {
 function validateMultiPanelFiles(value, panelCount, index) {
   if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].files must be non-empty.`);
   for (const [fileIndex, file] of value.entries()) {
-    if (!isRecord2(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
-    requireString2(file.path, `scenes[${index}].files[${fileIndex}].path`);
+    if (!isRecord3(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
+    requireString3(file.path, `scenes[${index}].files[${fileIndex}].path`);
     if (!Array.isArray(file.panels) || file.panels.length !== panelCount) {
       throw new Error(`scenes[${index}].files[${fileIndex}].panels must match panel count.`);
     }
     for (const [panelIndex, panel] of file.panels.entries()) {
-      if (!isRecord2(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
-      for (const key of ["id", "label", "content"]) requireString2(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
-      if (panel.path !== void 0) requireString2(panel.path, `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].path`);
+      if (!isRecord3(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
+      for (const key of ["id", "label", "content"]) requireString3(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
+      if (panel.path !== void 0) requireString3(panel.path, `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].path`);
       if (typeof panel.exists !== "boolean") throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}].exists must be boolean.`);
     }
   }
@@ -1165,12 +1215,12 @@ function validateMultiPanelFiles(value, panelCount, index) {
 function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
   if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].steps must be non-empty.`);
   for (const [stepIndex, step] of value.entries()) {
-    if (!isRecord2(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
-    for (const key of ["id", "title", "body", "file", "side"]) requireString2(step[key], `scenes[${index}].steps[${stepIndex}].${key}`);
+    if (!isRecord3(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
+    for (const key of ["id", "title", "body", "file", "side"]) requireString3(step[key], `scenes[${index}].steps[${stepIndex}].${key}`);
     requireNonNegativeInteger(step.pairIndex, `scenes[${index}].steps[${stepIndex}].pairIndex`);
     if (Number(step.pairIndex) >= panelCount - 1) throw new Error(`scenes[${index}].steps[${stepIndex}].pairIndex is outside the panels.`);
     if (deconstructed) {
-      requireStringArray2(step.introducedHunks, `scenes[${index}].steps[${stepIndex}].introducedHunks`);
+      requireStringArray3(step.introducedHunks, `scenes[${index}].steps[${stepIndex}].introducedHunks`);
       if (step.introducedHunks.length === 0) throw new Error(`scenes[${index}].steps[${stepIndex}].introducedHunks must be non-empty.`);
     }
     if (step.side !== "left" && step.side !== "right") throw new Error(`scenes[${index}].steps[${stepIndex}].side must be left or right.`);
@@ -1179,7 +1229,7 @@ function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
   }
 }
 function validateTourFile(value, index) {
-  if (!isRecord2(value)) throw new Error(`files[${index}] must be an object.`);
+  if (!isRecord3(value)) throw new Error(`files[${index}] must be an object.`);
   if (value.kind === "text-diff") {
     validateScene(value, index, 1);
     return;
@@ -1188,9 +1238,9 @@ function validateTourFile(value, index) {
     throw new Error(`files[${index}].kind must be text-diff or omitted.`);
   }
   for (const key of ["id", "title", "path", "changeKind", "reason"]) {
-    requireString2(value[key], `files[${index}].${key}`);
+    requireString3(value[key], `files[${index}].${key}`);
   }
-  if (value.previousPath !== void 0) requireString2(value.previousPath, `files[${index}].previousPath`);
+  if (value.previousPath !== void 0) requireString3(value.previousPath, `files[${index}].previousPath`);
   requireNonNegativeInteger(value.additions, `files[${index}].additions`);
   requireNonNegativeInteger(value.deletions, `files[${index}].deletions`);
 }
@@ -1210,28 +1260,35 @@ function collectLegacyTourFiles(scenes) {
   return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
 }
 function validateResolvedAnchor(value, path) {
-  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
-  for (const key of ["id", "path", "revision", "excerpt"]) requireString2(value[key], `${path}.${key}`);
+  if (!isRecord3(value)) throw new Error(`${path} must be an object.`);
+  for (const key of ["id", "path", "revision", "excerpt"]) requireString3(value[key], `${path}.${key}`);
   if (value.revision !== "base" && value.revision !== "head") throw new Error(`${path}.revision must be base or head.`);
   requirePositiveInteger(value.startLine, `${path}.startLine`);
   requirePositiveInteger(value.endLine, `${path}.endLine`);
   if (Number(value.endLine) < Number(value.startLine)) throw new Error(`${path}.endLine must not precede startLine.`);
 }
 function validateNarrative2(value, path) {
-  requireString2(value.summary, `${path}.summary`);
-  requireStringArray2(value.bullets, `${path}.bullets`);
-  requireStringArray2(value.tags, `${path}.tags`);
-  requireString2(value.takeaway, `${path}.takeaway`);
+  requireString3(value.summary, `${path}.summary`);
+  requireStringArray3(value.bullets, `${path}.bullets`);
+  requireStringArray3(value.tags, `${path}.tags`);
+  requireString3(value.takeaway, `${path}.takeaway`);
 }
-function isRecord2(value) {
+function validateChapterSummary(value, version, path) {
+  if (value === void 0) return;
+  if (version < 5) throw new Error(`${path} requires manifest version 5.`);
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function requireString2(value, path) {
+function requireString3(value, path) {
   if (typeof value !== "string") {
     throw new Error(`${path} must be a string.`);
   }
 }
-function requireStringArray2(value, path) {
+function requireStringArray3(value, path) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
     throw new Error(`${path} must be an array of strings.`);
   }
@@ -2018,7 +2075,7 @@ function diffArrays(oldArr, newArr, callback) {
 }
 
 // src/diffEngine.ts
-var DEFAULT_MAX_INLINE_HIGHLIGHT_LINE_LENGTH = 500;
+var DEFAULT_MAX_INLINE_HIGHLIGHT_LINE_LENGTH = 2e4;
 var DEFAULT_DIFF_TIMEOUT_MS = 100;
 var MAX_INLINE_HIGHLIGHT_LINE_LENGTH = readPositiveIntegerEnv(
   "BYGONE_MAX_INLINE_HIGHLIGHT_LINE_LENGTH",
@@ -2031,6 +2088,22 @@ function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
   if (leftContent === rightContent) {
     return buildIdenticalTwoWayDiffModel(leftLines);
   }
+  if (leftLines.length === rightLines.length && leftLines.every((line, index) => line === rightLines[index])) {
+    const model = buildIdenticalTwoWayDiffModel(leftLines);
+    const rawLeft = leftContent.match(/[^\n]*\n|[^\n]+$/g) || [];
+    const rawRight = rightContent.match(/[^\n]*\n|[^\n]+$/g) || [];
+    leftLines.forEach((_, index) => {
+      if (rawLeft[index] === rawRight[index]) return;
+      model.leftLines[index].kind = model.rows[index].left.kind = "removed";
+      model.rightLines[index].kind = model.rows[index].right.kind = "added";
+      model.leftLines[index].inlineDetail = model.rightLines[index].inlineDetail = "line-ending";
+      model.blocks.push(makeDiffBlock("replace", index, index + 1, index, index + 1));
+    });
+    model.blocks = mergeTouchingBlocks(model.blocks);
+    model.hasChanges = true;
+    model.formattingOnly = true;
+    return model;
+  }
   const interned = internDiffLines(leftLines, rightLines);
   const internedChanges = diffArrays(interned.left, interned.right, {
     timeout: options.timeoutMs ?? DIFF_TIMEOUT_MS
@@ -2107,14 +2180,54 @@ function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
     }
   }
   const hasChanges = rows.some((row) => row.left.kind !== "context" || row.right.kind !== "context");
-  return {
+  return markUndetailedReplacements({
     rows,
     leftLines: renderedLeftLines,
     rightLines: renderedRightLines,
-    blocks,
+    blocks: mergeTouchingBlocks(blocks),
+    reflows: blocks.filter((block) => block.reflow),
     hasChanges,
     quality: "exact"
-  };
+  });
+}
+function markUndetailedReplacements(model) {
+  for (const block of model.blocks) {
+    if (block.kind !== "replace") continue;
+    for (const side of ["left", "right"]) {
+      for (let index = block[`${side}Start`]; index < block[`${side}End`]; index++) {
+        const line = model[`${side}Lines`][index];
+        if (line.kind !== "context" && !line.segments) line.inlineDetail = "omitted";
+      }
+    }
+  }
+  return model;
+}
+function mergeTouchingBlocks(blocks) {
+  const regions = [];
+  let oneSidedRun = false;
+  for (const original of blocks) {
+    const oneSided = original.kind !== "replace";
+    const previous = regions[regions.length - 1];
+    if (oneSided && oneSidedRun && previous.leftEnd === original.leftStart && previous.rightEnd === original.rightStart) {
+      previous.leftEnd = original.leftEnd;
+      previous.rightEnd = original.rightEnd;
+      if (previous.leftEnd > previous.leftStart && previous.rightEnd > previous.rightStart) {
+        previous.kind = "replace";
+      }
+    } else regions.push({ ...original });
+    oneSidedRun = oneSided;
+  }
+  const merged = [];
+  for (const original of regions) {
+    const block = { ...original };
+    delete block.reflow;
+    const previous = merged[merged.length - 1];
+    if ((previous == null ? void 0 : previous.kind) === block.kind && previous.leftEnd === block.leftStart && previous.rightEnd === block.rightStart) {
+      previous.leftEnd = block.leftEnd;
+      previous.rightEnd = block.rightEnd;
+    } else merged.push(block);
+  }
+  return merged;
 }
 function internDiffLines(leftLines, rightLines) {
   const lineIds = /* @__PURE__ */ new Map();
@@ -2167,14 +2280,14 @@ function buildConservativeTwoWayDiffModel(leftLines, rightLines) {
   } else if (rightLines.length === 0) {
     blockKind = "delete";
   }
-  return {
+  return markUndetailedReplacements({
     rows,
     leftLines: renderedLeftLines,
     rightLines: renderedRightLines,
     blocks: rows.length === 0 ? [] : [makeDiffBlock(blockKind, 0, leftLines.length, 0, rightLines.length)],
     hasChanges: rows.length > 0,
     quality: "fallback"
-  };
+  });
 }
 function normalizeLines(content) {
   if (content.length === 0) {
@@ -2189,33 +2302,64 @@ function normalizeLines(content) {
 function appendReplacementCandidate(leftLines, rightLines, initialLeftLineNumber, initialRightLineNumber, rows, renderedLeftLines, renderedRightLines, blocks) {
   const aligned = alignReplacementLines(leftLines, rightLines);
   const crediblePairs = aligned.filter((row) => row.left !== void 0 && row.right !== void 0 && hasCredibleLineCorrespondence(row.left, row.right)).length;
-  const coherentBlock = hasCoherentBlockCorrespondence(leftLines, rightLines, crediblePairs);
-  const normalized = aligned.flatMap((row) => {
-    if (row.left === void 0 || row.right === void 0 || hasCredibleLineCorrespondence(row.left, row.right)) {
+  const coherentBlock = !aligned.some((row) => row.reflow) && hasCoherentBlockCorrespondence(leftLines, rightLines, crediblePairs);
+  const candidates = aligned.flatMap((row) => {
+    if (row.reflow || row.left === void 0 || row.right === void 0 || hasCredibleLineCorrespondence(row.left, row.right)) {
       return [row];
     }
     return [{ left: row.left }, { right: row.right }];
   });
+  const normalized = [];
+  for (let index = 0; index < candidates.length; ) {
+    const row = candidates[index];
+    if (row.reflow || row.left !== void 0 && row.right !== void 0) {
+      normalized.push(row);
+      index++;
+      continue;
+    }
+    const start = index;
+    while (index < candidates.length && !candidates[index].reflow && (candidates[index].left === void 0 || candidates[index].right === void 0)) index++;
+    const gap = candidates.slice(start, index);
+    const left = gap.filter((item) => item.left !== void 0);
+    const right = gap.filter((item) => item.right !== void 0);
+    if (left.length === 1 && right.length === 1) {
+      normalized.push({ left: left[0].left, right: right[0].right });
+    } else {
+      for (const item of gap) normalized.push(item);
+    }
+  }
   let leftLineNumber = initialLeftLineNumber;
   let rightLineNumber = initialRightLineNumber;
+  let unmatchedLeft = [];
+  let unmatchedRight = [];
+  const flushUnmatched = () => {
+    applyWrappedReplacementHighlights(unmatchedLeft, unmatchedRight);
+    unmatchedLeft = [];
+    unmatchedRight = [];
+  };
   let blockKind;
+  let blockReflow = false;
   let blockLeftStart = renderedLeftLines.length;
   let blockRightStart = renderedRightLines.length;
   const flushBlock = () => {
     if (!blockKind) return;
-    blocks.push(makeDiffBlock(
+    const block = makeDiffBlock(
       blockKind,
       blockLeftStart,
       renderedLeftLines.length,
       blockRightStart,
       renderedRightLines.length
-    ));
+    );
+    if (blockReflow) block.reflow = true;
+    blocks.push(block);
   };
-  for (const { left, right } of normalized) {
-    const nextKind = coherentBlock ? "replace" : left !== void 0 && right !== void 0 ? "replace" : left !== void 0 ? "delete" : "insert";
-    if (blockKind !== nextKind) {
+  for (const { left, right, reflow } of normalized) {
+    if (reflow || left !== void 0 && right !== void 0) flushUnmatched();
+    const nextKind = coherentBlock || reflow ? "replace" : left !== void 0 && right !== void 0 ? "replace" : left !== void 0 ? "delete" : "insert";
+    if (blockKind !== nextKind || blockReflow !== Boolean(reflow) || (reflow == null ? void 0 : reflow.start)) {
       flushBlock();
       blockKind = nextKind;
+      blockReflow = Boolean(reflow);
       blockLeftStart = renderedLeftLines.length;
       blockRightStart = renderedRightLines.length;
     }
@@ -2229,21 +2373,30 @@ function appendReplacementCandidate(leftLines, rightLines, initialLeftLineNumber
       renderedRightLine = makeDiffLine("added", right, rightLineNumber);
       renderedRightLines.push(renderedRightLine);
     }
-    if (renderedLeftLine && renderedRightLine) {
+    if (reflow) {
+      if (renderedLeftLine) renderedLeftLine.segments = reflow.leftSegments;
+      if (renderedRightLine) renderedRightLine.segments = reflow.rightSegments;
+    } else if (renderedLeftLine && renderedRightLine) {
       applyInlineHighlightPair(renderedLeftLine, renderedRightLine);
     } else if (coherentBlock) {
       if (renderedLeftLine) applyFullLineHighlight(renderedLeftLine);
       if (renderedRightLine) applyFullLineHighlight(renderedRightLine);
     }
+    if (!reflow && (left === void 0 || right === void 0)) {
+      if (renderedLeftLine) unmatchedLeft.push(renderedLeftLine);
+      if (renderedRightLine) unmatchedRight.push(renderedRightLine);
+    }
     rows.push(makeDiffRow(
       left === void 0 ? makePlaceholder() : makeDiffCell("removed", left, leftLineNumber++),
       right === void 0 ? makePlaceholder() : makeDiffCell("added", right, rightLineNumber++)
     ));
   }
   flushBlock();
+  flushUnmatched();
   return { left: leftLineNumber, right: rightLineNumber };
 }
 function hasCredibleLineCorrespondence(left, right) {
+  if (!left.trim() && !right.trim()) return true;
   const score = scoreReplacementLinePair(left, right);
   if (score.eligible) return true;
   const leftAnchor = declarationAnchorKey(left);
@@ -2296,24 +2449,101 @@ var MAX_ALIGNMENT_CHARACTER_CELLS = 5e7;
 var MAX_RARE_TOKEN_OCCURRENCES = 4;
 var MAX_CONTEXTUAL_HUNK_LINES = 8;
 var MAX_CONTEXTUAL_LENGTH_DELTA = 4;
+function wrappedTextUnits(lines) {
+  const units = [];
+  for (let index = 0; index < lines.length; index++) {
+    const first = lines[index];
+    const paragraph = [first];
+    const start = first.match(/^(\s*)(?:[\w-]+:\s+|[-*+]\s+)(\S.*)$/);
+    if (start && !/^[|>\[{]/.test(start[2])) {
+      while (index + 1 < lines.length) {
+        const next = lines[index + 1];
+        if (!next.trim() || next.length - next.trimStart().length <= start[1].length || /^\s*(?:[\w-]+:|[-*+]\s|\d+[.)]\s|#)/.test(next)) break;
+        paragraph.push(next);
+        index++;
+      }
+    }
+    units.push(paragraph.join("\n"));
+  }
+  return units;
+}
 function alignReplacementLines(leftLines, rightLines) {
+  if ([...leftLines, ...rightLines].some((line) => line.includes("\n"))) {
+    return alignPhysicalReplacementLines(leftLines, rightLines);
+  }
+  const leftUnits = wrappedTextUnits(leftLines);
+  const rightUnits = wrappedTextUnits(rightLines);
+  if (leftUnits.length === leftLines.length && rightUnits.length === rightLines.length) {
+    return alignPhysicalReplacementLines(leftLines, rightLines);
+  }
+  return alignPhysicalReplacementLines(leftUnits, rightUnits).flatMap((row) => {
+    var _a, _b;
+    const left = ((_a = row.left) == null ? void 0 : _a.split("\n")) || [];
+    const right = ((_b = row.right) == null ? void 0 : _b.split("\n")) || [];
+    if (!left.length || !right.length) {
+      return [...left.map((left2) => ({ left: left2 })), ...right.map((right2) => ({ right: right2 }))];
+    }
+    if (left.length === 1 && right.length === 1) return [row];
+    const whitespace = buildWhitespaceOnlySegments(row.left, row.right);
+    const segments = whitespace || buildInlineSegments(row.left, row.right);
+    const leftSegments = segments && splitSegmentsIntoLines(segments.leftSegments);
+    const rightSegments = segments && splitSegmentsIntoLines(segments.rightSegments);
+    return Array.from({ length: Math.max(left.length, right.length) }, (_, index) => ({
+      left: left[index],
+      right: right[index],
+      reflow: { start: index === 0, leftSegments: leftSegments == null ? void 0 : leftSegments[index], rightSegments: rightSegments == null ? void 0 : rightSegments[index] }
+    }));
+  });
+}
+function alignPhysicalReplacementLines(leftLines, rightLines) {
   if (leftLines.length === 0) {
     return rightLines.map((right) => ({ right }));
   }
   if (rightLines.length === 0) {
     return leftLines.map((left) => ({ left }));
   }
-  const leftCharacterCount = leftLines.reduce((total, line) => total + line.length, 0);
-  const rightCharacterCount = rightLines.reduce((total, line) => total + line.length, 0);
-  if (leftCharacterCount * rightCharacterCount > MAX_ALIGNMENT_CHARACTER_CELLS) {
+  let prefix = 0;
+  while (prefix < Math.min(leftLines.length, rightLines.length) && leftLines[prefix].trim() === rightLines[prefix].trim()) prefix++;
+  if (prefix) {
     return [
-      ...leftLines.map((left) => ({ left })),
-      ...rightLines.map((right) => ({ right }))
+      ...leftLines.slice(0, prefix).map((left, index) => ({ left, right: rightLines[index] })),
+      ...alignReplacementLines(leftLines.slice(prefix), rightLines.slice(prefix))
     ];
   }
+  let leftEnd = 1;
+  let rightEnd = 1;
+  let leftText = leftLines[0].trim().replace(/\s+/g, " ");
+  let rightText = rightLines[0].trim().replace(/\s+/g, " ");
+  while (leftText && rightText && leftText !== rightText) {
+    if (rightText.startsWith(leftText + " ") && leftEnd < leftLines.length) {
+      leftText += " " + leftLines[leftEnd++].trim().replace(/\s+/g, " ");
+    } else if (leftText.startsWith(rightText + " ") && rightEnd < rightLines.length) {
+      rightText += " " + rightLines[rightEnd++].trim().replace(/\s+/g, " ");
+    } else break;
+  }
+  if (leftText === rightText && (leftEnd > 1 || rightEnd > 1) && ![...leftLines, ...rightLines].some((line) => line.includes("\n"))) {
+    const reflow = buildWhitespaceOnlySegments(leftLines.slice(0, leftEnd).join("\n"), rightLines.slice(0, rightEnd).join("\n"));
+    if (reflow) {
+      const leftSegments = splitSegmentsIntoLines(reflow.leftSegments);
+      const rightSegments = splitSegmentsIntoLines(reflow.rightSegments);
+      return [
+        ...Array.from({ length: Math.max(leftEnd, rightEnd) }, (_, index) => ({
+          left: index < leftEnd ? leftLines[index] : void 0,
+          right: index < rightEnd ? rightLines[index] : void 0,
+          reflow: { start: index === 0, leftSegments: leftSegments[index], rightSegments: rightSegments[index] }
+        })),
+        ...alignReplacementLines(leftLines.slice(leftEnd), rightLines.slice(rightEnd))
+      ];
+    }
+  }
+  const leftCharacterCount = leftLines.reduce((total, line) => total + Math.min(line.length, MAX_SCORING_LINE_LENGTH), 0);
+  const rightCharacterCount = rightLines.reduce((total, line) => total + Math.min(line.length, MAX_SCORING_LINE_LENGTH), 0);
+  if (leftCharacterCount * rightCharacterCount > MAX_ALIGNMENT_CHARACTER_CELLS) {
+    return alignLargeReplacementLines(leftLines, rightLines, true);
+  }
   if (leftLines.length === 1 && rightLines.length === 1) {
     const singletonScore = scoreReplacementLinePair(leftLines[0], rightLines[0]);
-    if ((singletonScore.eligible || singletonScore.score >= MINIMUM_SINGLE_PAIR_SCORE) && hasCredibleLineCorrespondence(leftLines[0], rightLines[0]) && haveCompatibleLineRoles(leftLines[0], rightLines[0]) && isInformativeLine(normalizeMatchingContent(leftLines[0])) && isInformativeLine(normalizeMatchingContent(rightLines[0]))) {
+    if (!leftLines[0].trim() && !rightLines[0].trim() || (singletonScore.eligible || singletonScore.score >= MINIMUM_SINGLE_PAIR_SCORE) && hasCredibleLineCorrespondence(leftLines[0], rightLines[0]) && haveCompatibleLineRoles(leftLines[0], rightLines[0]) && isInformativeLine(normalizeMatchingContent(leftLines[0])) && isInformativeLine(normalizeMatchingContent(rightLines[0]))) {
       return [{ left: leftLines[0], right: rightLines[0] }];
     }
     return [{ left: leftLines[0] }, { right: rightLines[0] }];
@@ -2375,16 +2605,7 @@ function scoreReplacementLinePair(left, right) {
   const normalizedRight = normalizeMatchingContent(right);
   const leftInformative = isInformativeLine(normalizedLeft);
   const rightInformative = isInformativeLine(normalizedRight);
-  if (!leftInformative || !rightInformative || normalizedLeft.length > MAX_SCORING_LINE_LENGTH || normalizedRight.length > MAX_SCORING_LINE_LENGTH) {
-    return {
-      score: 0,
-      eligible: false,
-      characterSimilarity: 0,
-      tokenSimilarity: 0,
-      lengthSimilarity: 0
-    };
-  }
-  if (normalizedLeft === normalizedRight) {
+  if (leftInformative && rightInformative && normalizedLeft === normalizedRight) {
     return {
       score: 1,
       eligible: true,
@@ -2393,14 +2614,30 @@ function scoreReplacementLinePair(left, right) {
       lengthSimilarity: 1
     };
   }
+  if (!leftInformative || !rightInformative) {
+    return {
+      score: 0,
+      eligible: false,
+      characterSimilarity: 0,
+      tokenSimilarity: 0,
+      lengthSimilarity: 0
+    };
+  }
   const leftTokens = tokenizeMatchingContent(normalizedLeft);
   const rightTokens = tokenizeMatchingContent(normalizedRight);
-  const characterSimilarity = lineSimilarity(normalizedLeft, normalizedRight);
+  const sample = (text) => text.length <= MAX_SCORING_LINE_LENGTH ? text : [0, Math.floor(text.length / 2) - 300, text.length - 600].map((start) => text.slice(start, start + 600)).join(" ");
+  const characterSimilarity = lineSimilarity(sample(normalizedLeft), sample(normalizedRight));
   const tokenSimilarity = multisetDiceSimilarity(leftTokens, rightTokens);
   const lengthSimilarity = Math.min(normalizedLeft.length, normalizedRight.length) / Math.max(normalizedLeft.length, normalizedRight.length);
   const boundarySimilarity = tokenBoundarySimilarity(leftTokens, rightTokens);
-  const score = characterSimilarity * 0.52 + tokenSimilarity * 0.32 + lengthSimilarity * 0.1 + boundarySimilarity * 0.06;
-  const hasContentEvidence = characterSimilarity >= 0.52 || tokenSimilarity >= 0.45 || characterSimilarity >= 0.48 && tokenSimilarity >= 0.28;
+  const prefix = (text) => {
+    var _a;
+    return (_a = text.match(/^(?:(?:const|let|var)\s+)?([\p{L}_$][\p{L}\p{N}_$.-]*\s*(?::|=(?!=)))\s*/u)) == null ? void 0 : _a[1].replace(/\s+/g, "");
+  };
+  const leftPrefix = prefix(normalizedLeft);
+  const prefixBonus = leftPrefix && leftPrefix === prefix(normalizedRight) ? 0.12 : 0;
+  const score = Math.min(1, characterSimilarity * 0.52 + tokenSimilarity * 0.32 + lengthSimilarity * 0.1 + boundarySimilarity * 0.06 + prefixBonus);
+  const hasContentEvidence = prefixBonus > 0 || characterSimilarity >= 0.52 || tokenSimilarity >= 0.45 || characterSimilarity >= 0.48 && tokenSimilarity >= 0.28;
   return {
     score,
     eligible: hasContentEvidence && score >= MINIMUM_MATCH_SCORE,
@@ -2550,8 +2787,11 @@ function rankEligibleScores(scores) {
   }
   return { best, second };
 }
-function alignLargeReplacementLines(leftLines, rightLines) {
-  const anchors = collectLargeHunkAnchors(leftLines, rightLines);
+function alignLargeReplacementLines(leftLines, rightLines, exactOnly = false) {
+  const anchors = collectLargeHunkAnchors(leftLines, rightLines, exactOnly);
+  if (anchors.length === 0) {
+    return [...leftLines.map((left) => ({ left })), ...rightLines.map((right) => ({ right }))];
+  }
   const aligned = [];
   let leftStart = 0;
   let rightStart = 0;
@@ -2568,8 +2808,8 @@ function alignLargeReplacementLines(leftLines, rightLines) {
   appendBoundedSegment(aligned, leftLines.slice(leftStart), rightLines.slice(rightStart));
   return aligned;
 }
-function collectLargeHunkAnchors(leftLines, rightLines) {
-  const candidatePairs = collectRareTokenCandidatePairs(leftLines, rightLines);
+function collectLargeHunkAnchors(leftLines, rightLines, exactOnly) {
+  const candidatePairs = collectRareTokenCandidatePairs(leftLines, rightLines, exactOnly);
   if (candidatePairs === null) {
     return [];
   }
@@ -2598,7 +2838,7 @@ function collectLargeHunkAnchors(leftLines, rightLines) {
   const anchors = selectMaximumWeightMonotonicAnchors(confident, rightLines.length);
   return anchors.length <= MAX_LARGE_HUNK_ANCHORS ? anchors : [];
 }
-function collectRareTokenCandidatePairs(leftLines, rightLines) {
+function collectRareTokenCandidatePairs(leftLines, rightLines, exactOnly) {
   const leftExact = buildLinePostings(leftLines, normalizeMatchingContent);
   const rightExact = buildLinePostings(rightLines, normalizeMatchingContent);
   const pairs = /* @__PURE__ */ new Map();
@@ -2614,6 +2854,9 @@ function collectRareTokenCandidatePairs(leftLines, rightLines) {
       return null;
     }
   }
+  if (exactOnly) {
+    return [...pairs.values()];
+  }
   const leftTokens = buildTokenPostings(leftLines);
   const rightTokens = buildTokenPostings(rightLines);
   for (const [token, leftIndices] of leftTokens) {
@@ -2826,22 +3069,113 @@ function lineSimilarity(left, right) {
   return 2 * commonLength / maxLength;
 }
 function applyInlineHighlightPair(leftLine, rightLine) {
-  if (leftLine.content.length > MAX_INLINE_HIGHLIGHT_LINE_LENGTH || rightLine.content.length > MAX_INLINE_HIGHLIGHT_LINE_LENGTH) {
+  const whitespace = buildWhitespaceOnlySegments(leftLine.content, rightLine.content);
+  if (whitespace) {
+    leftLine.segments = whitespace.leftSegments;
+    rightLine.segments = whitespace.rightSegments;
     return;
   }
-  const { leftSegments, rightSegments, hasInlineChanges } = buildInlineSegments(leftLine.content, rightLine.content);
-  if (hasInlineChanges) {
-    leftLine.segments = leftSegments;
-    rightLine.segments = rightSegments;
-  }
+  const segments = buildInlineSegments(leftLine.content, rightLine.content);
+  if (segments) {
+    leftLine.segments = segments.leftSegments;
+    rightLine.segments = segments.rightSegments;
+  }
+}
+function applyWrappedReplacementHighlights(leftLines, rightLines) {
+  if (!leftLines.length || !rightLines.length || leftLines.length === 1 && rightLines.length === 1) return;
+  const length = (lines) => lines.reduce((total, line) => total + line.content.length + 1, -1);
+  if (length(leftLines) > MAX_INLINE_HIGHLIGHT_LINE_LENGTH || length(rightLines) > MAX_INLINE_HIGHLIGHT_LINE_LENGTH) return;
+  const left = leftLines.map((line) => line.content).join("\n");
+  const right = rightLines.map((line) => line.content).join("\n");
+  const segments = buildInlineSegments(left, right);
+  if (!segments) return;
+  const { leftSegments, rightSegments } = segments;
+  const leftParts = splitSegmentsIntoLines(leftSegments);
+  const rightParts = splitSegmentsIntoLines(rightSegments);
+  leftLines.forEach((line, index) => {
+    line.segments = leftParts[index];
+  });
+  rightLines.forEach((line, index) => {
+    line.segments = rightParts[index];
+  });
 }
 function applyFullLineHighlight(line) {
   if (/[^\s]/.test(line.content)) {
     line.segments = [{ kind: line.kind, text: line.content, emphasis: true }];
   }
 }
+var inlineGraphemes = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+function trimReplacementEdges(left, right) {
+  if (left === right) return left ? [{ value: left }] : [];
+  const leftChars = Array.from(inlineGraphemes.segment(left), (part) => part.segment);
+  const rightChars = Array.from(inlineGraphemes.segment(right), (part) => part.segment);
+  const limit = Math.min(leftChars.length, rightChars.length);
+  let prefix = 0;
+  let suffix = 0;
+  while (prefix < limit && leftChars[prefix] === rightChars[prefix]) prefix++;
+  while (suffix < limit && leftChars[leftChars.length - suffix - 1] === rightChars[rightChars.length - suffix - 1]) suffix++;
+  if (suffix === limit && prefix < limit) prefix = 0;
+  suffix = Math.min(suffix, limit - prefix);
+  return [
+    { value: leftChars.slice(0, prefix).join("") },
+    { value: leftChars.slice(prefix, leftChars.length - suffix).join(""), removed: true },
+    { value: rightChars.slice(prefix, rightChars.length - suffix).join(""), added: true },
+    { value: suffix ? leftChars.slice(-suffix).join("") : "" }
+  ].filter((change) => change.value.length > 0);
+}
+function edgeTrimmedWordChanges(left, right) {
+  const words = diffWordsWithSpace(left, right, { timeout: DIFF_TIMEOUT_MS, maxEditLength: 2e3 });
+  if (!words) return void 0;
+  const boundaries = (text) => /* @__PURE__ */ new Set([
+    ...Array.from(inlineGraphemes.segment(text), (part) => part.index),
+    text.length
+  ]);
+  const leftBoundaries = boundaries(left);
+  const rightBoundaries = boundaries(right);
+  const result = [];
+  let leftOffset = 0;
+  let rightOffset = 0;
+  let pendingLeft = "";
+  let pendingRight = "";
+  for (let index = 0; index < words.length; ) {
+    const word = words[index];
+    if (!word.added && !word.removed) {
+      pendingLeft += word.value;
+      pendingRight += word.value;
+      leftOffset += word.value.length;
+      rightOffset += word.value.length;
+      index++;
+    } else {
+      while (index < words.length && (words[index].added || words[index].removed)) {
+        const change = words[index++];
+        if (change.removed) {
+          pendingLeft += change.value;
+          leftOffset += change.value.length;
+        } else {
+          pendingRight += change.value;
+          rightOffset += change.value.length;
+        }
+      }
+    }
+    if (leftBoundaries.has(leftOffset) && rightBoundaries.has(rightOffset)) {
+      for (const change of trimReplacementEdges(pendingLeft, pendingRight)) {
+        const previous = result[result.length - 1];
+        if (previous && previous.added === change.added && previous.removed === change.removed) {
+          previous.value += change.value;
+        } else {
+          result.push(change);
+        }
+      }
+      pendingLeft = "";
+      pendingRight = "";
+    }
+  }
+  return result;
+}
 function buildInlineSegments(leftContent, rightContent) {
-  const changes = diffWordsWithSpace(leftContent, rightContent);
+  if (leftContent.length > MAX_INLINE_HIGHLIGHT_LINE_LENGTH || rightContent.length > MAX_INLINE_HIGHLIGHT_LINE_LENGTH) return void 0;
+  const changes = edgeTrimmedWordChanges(leftContent, rightContent);
+  if (!changes) return void 0;
   const leftSegments = [];
   const rightSegments = [];
   let hasInlineChanges = false;
@@ -2857,7 +3191,7 @@ function buildInlineSegments(leftContent, rightContent) {
       rightSegments.push(contextSegment);
       continue;
     }
-    const emphasis = /[^\s]/.test(value);
+    const emphasis = value.length > 0;
     hasInlineChanges = hasInlineChanges || emphasis;
     if (change.removed) {
       leftSegments.push({
@@ -2880,6 +3214,48 @@ function buildInlineSegments(leftContent, rightContent) {
     hasInlineChanges
   };
 }
+function buildWhitespaceOnlySegments(left, right) {
+  const leftParts = left.split(/(\S+)/);
+  const rightParts = right.split(/(\S+)/);
+  if (leftParts.length !== rightParts.length || leftParts.some((part, index) => index % 2 === 1 && part !== rightParts[index])) return void 0;
+  const leftSegments = [];
+  const rightSegments = [];
+  const append = (segments, kind, text) => {
+    if (!text) return;
+    const previous = segments[segments.length - 1];
+    if ((previous == null ? void 0 : previous.kind) === kind) previous.text += text;
+    else segments.push({ kind, text, emphasis: kind !== "context" });
+  };
+  leftParts.forEach((part, index) => {
+    const other = rightParts[index];
+    let prefix = 0;
+    if (index > 0) {
+      while (prefix < Math.min(part.length, other.length) && part[prefix] === other[prefix]) prefix++;
+    }
+    let suffix = 0;
+    while (suffix < Math.min(part.length, other.length) - prefix && part[part.length - suffix - 1] === other[other.length - suffix - 1]) suffix++;
+    if (index === 0) {
+      while (prefix < Math.min(part.length, other.length) - suffix && part[prefix] === other[prefix]) prefix++;
+    }
+    append(leftSegments, "context", part.slice(0, prefix));
+    append(rightSegments, "context", other.slice(0, prefix));
+    append(leftSegments, "removed", part.slice(prefix, part.length - suffix));
+    append(rightSegments, "added", other.slice(prefix, other.length - suffix));
+    append(leftSegments, "context", part.slice(part.length - suffix));
+    append(rightSegments, "context", other.slice(other.length - suffix));
+  });
+  return { leftSegments, rightSegments };
+}
+function splitSegmentsIntoLines(segments) {
+  const lines = [[]];
+  for (const segment of segments) {
+    segment.text.split("\n").forEach((text, index) => {
+      if (index > 0) lines.push([]);
+      if (text) lines[lines.length - 1].push({ ...segment, text });
+    });
+  }
+  return lines;
+}
 function makePlaceholder() {
   return {
     kind: "placeholder",
@@ -3309,20 +3685,16 @@ var CHAPTERS = {
 };
 function buildChangeTourManifest(startPath, options = {}) {
   var _a, _b, _c, _d;
-  const source = options.source ? parseChangeTourSource(options.source) : void 0;
+  let source = options.source ? parseChangeTourSource(options.source) : void 0;
   const range = resolveBranchReviewRange(
     startPath,
     options.headRef ?? ((_a = source == null ? void 0 : source.range) == null ? void 0 : _a.head),
     options.baseRef ?? ((_b = source == null ? void 0 : source.range) == null ? void 0 : _b.base)
   );
-  if (source == null ? void 0 : source.review) {
-    validateChangeTourReview(source.review, {
-      expectedRange: {
-        baseOid: range.mergeBaseOid,
-        headOid: range.headOid
-      }
-    });
-  }
+  if (source) source = pinTourSource(source, range.repoRoot, /* @__PURE__ */ new Map([
+    [range.headRef, range.headOid],
+    [range.baseRef, range.baseOid]
+  ]), range.baseOid, range.headOid);
   const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_TOUR_FILE_BYTES;
   const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_TOUR_LINE_BYTES;
   const omittedFiles = [];
@@ -3403,7 +3775,7 @@ function buildChangeTourManifest(startPath, options = {}) {
     };
     defaultScenes = [...defaultScenes].sort((left, right) => Number(right.path === attention.entryPath) - Number(left.path === attention.entryPath) || focusRank(left.path) - focusRank(right.path) || left.id.localeCompare(right.id));
   }
-  const authored = source ? applySource(source, defaultScenes, range.repoRoot) : options.story ? applyStory(options.story, defaultScenes) : buildGeneratedTourLanding(
+  const authored = source ? applySourceChapters(source, source.chapters, defaultScenes, range.repoRoot, { base: range.mergeBaseOid, head: range.headOid }) : options.story ? applyStory(options.story, defaultScenes) : buildGeneratedTourLanding(
     defaultScenes,
     buildChapters(sceneRecords, new Map(defaultScenes.map((scene) => [scene.path, scene.id]))),
     attention,
@@ -3425,6 +3797,8 @@ function buildChangeTourManifest(startPath, options = {}) {
     version: (source == null ? void 0 : source.version) ?? 1,
     title: (source == null ? void 0 : source.title) || ((_c = options.story) == null ? void 0 : _c.title) || options.title || `${range.headRef} against ${range.baseRef}`,
     windowTitle: source == null ? void 0 : source.windowTitle,
+    opening: source == null ? void 0 : source.opening,
+    conclusion: source == null ? void 0 : source.conclusion,
     sourceUrl: (source == null ? void 0 : source.sourceUrl) || ((_d = options.story) == null ? void 0 : _d.sourceUrl) || options.sourceUrl,
     generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
     range: {
@@ -3445,9 +3819,9 @@ function buildChangeTourManifest(startPath, options = {}) {
     files,
     chapters,
     scenes,
-    ...(source == null ? void 0 : source.review) ? { review: source.review } : {}
+    ...(source == null ? void 0 : source.details) !== void 0 ? { details: source.details } : {}
   };
-  const authoredModeTours = (source == null ? void 0 : source.version) === 3 ? buildAuthoredModeTours(
+  const authoredModeTours = source && source.version >= 4 ? buildAuthoredModeTours(
     source,
     authored,
     defaultScenes,
@@ -3502,10 +3876,7 @@ function buildChangeTourManifest(startPath, options = {}) {
   }
   return parseChangeTourManifest(manifest);
 }
-function applySource(source, defaultScenes, repoRoot) {
-  return applySourceChapters(source, source.chapters, defaultScenes, repoRoot);
-}
-function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot) {
+function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot, imageRevisions) {
   var _a, _b;
   const available = new Map(defaultScenes.map((scene) => [scene.path, scene]));
   const resolvedAnchors = /* @__PURE__ */ new Map();
@@ -3546,7 +3917,8 @@ function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot)
             { ...authoredScene, steps: authoredScene.steps },
             available,
             resolvedAnchors,
-            connections
+            connections,
+            (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision])
           );
           finalScenes.push(finalScene);
           finalSceneIds.push(finalScene.id);
@@ -3570,14 +3942,30 @@ function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot)
         }
         continue;
       }
-      const scene = buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections);
+      const scene = buildWalkthroughManifestScene(
+        authoredScene,
+        available,
+        resolvedAnchors,
+        connections,
+        (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision])
+      );
       scenes.push(scene);
       sceneIds.push(scene.id);
       finalScenes.push(scene);
       finalSceneIds.push(scene.id);
     }
-    chapters.push({ id: chapter.id, title: chapter.title, sceneIds });
-    finalChapters.push({ id: chapter.id, title: chapter.title, sceneIds: finalSceneIds });
+    chapters.push({
+      id: chapter.id,
+      title: chapter.title,
+      ...chapter.summary === void 0 ? {} : { summary: chapter.summary },
+      sceneIds
+    });
+    finalChapters.push({
+      id: chapter.id,
+      title: chapter.title,
+      ...chapter.summary === void 0 ? {} : { summary: chapter.summary },
+      sceneIds: finalSceneIds
+    });
   }
   return { scenes, chapters, finalScenes, finalChapters };
 }
@@ -3585,18 +3973,41 @@ function buildAuthoredModeTours(source, root, defaultScenes, repoRoot, mergeBase
   var _a, _b;
   const tours = {};
   if ((_a = source.tours) == null ? void 0 : _a.historical) {
-    const compiled = applySourceChapters(source, source.tours.historical.chapters, defaultScenes, repoRoot);
+    const compiled = applySourceChapters(source, source.tours.historical.chapters, defaultScenes, repoRoot, { base: mergeBaseOid, head: headOid });
     validateHistoricalStackEndpoints(compiled.scenes, mergeBaseOid, headOid);
-    tours.historical = { chapters: compiled.chapters, scenes: compiled.scenes };
-  } else if (source.version === 3) {
+    tours.historical = {
+      opening: source.tours.historical.opening,
+      conclusion: source.tours.historical.conclusion,
+      chapters: compiled.chapters,
+      scenes: compiled.scenes,
+      ...source.tours.historical.details !== void 0 ? { details: source.tours.historical.details } : {}
+    };
+  } else if (source.version >= 4) {
     const fallback = buildHistoricalFallback(source.chapters, root);
-    if (fallback) tours.historical = fallback;
+    if (fallback) {
+      tours.historical = {
+        ...fallback,
+        ...root.scenes.every((scene) => scene.kind !== "deconstructed-diff") ? { opening: source.opening, conclusion: source.conclusion, details: source.details } : {}
+      };
+    }
   }
   if ((_b = source.tours) == null ? void 0 : _b.deconstructed) {
-    const compiled = applySourceChapters(source, source.tours.deconstructed.chapters, defaultScenes, repoRoot);
-    tours.deconstructed = { chapters: compiled.chapters, scenes: compiled.scenes };
-  } else if (source.version === 3 && source.chapters.some((chapter) => chapter.scenes.some((scene) => scene.kind === "deconstructed-diff"))) {
-    tours.deconstructed = { chapters: root.chapters, scenes: root.scenes };
+    const compiled = applySourceChapters(source, source.tours.deconstructed.chapters, defaultScenes, repoRoot, { base: mergeBaseOid, head: headOid });
+    tours.deconstructed = {
+      opening: source.tours.deconstructed.opening,
+      conclusion: source.tours.deconstructed.conclusion,
+      chapters: compiled.chapters,
+      scenes: compiled.scenes,
+      ...source.tours.deconstructed.details !== void 0 ? { details: source.tours.deconstructed.details } : {}
+    };
+  } else if (source.version >= 4 && source.chapters.some((chapter) => chapter.scenes.some((scene) => scene.kind === "deconstructed-diff"))) {
+    tours.deconstructed = {
+      opening: source.opening,
+      conclusion: source.conclusion,
+      details: source.details,
+      chapters: root.chapters,
+      scenes: root.scenes
+    };
   }
   return tours.historical || tours.deconstructed ? tours : void 0;
 }
@@ -3621,7 +4032,14 @@ function buildHistoricalFallback(sourceChapters, root) {
       scenes.push(scene);
       sceneIds.push(scene.id);
     }
-    if (sceneIds.length > 0) chapters.push({ id: chapter.id, title: chapter.title, sceneIds });
+    if (sceneIds.length > 0) {
+      chapters.push({
+        id: chapter.id,
+        title: chapter.title,
+        ...chapter.summary === void 0 ? {} : { summary: chapter.summary },
+        sceneIds
+      });
+    }
   }
   return scenes.length > 0 ? { chapters, scenes } : void 0;
 }
@@ -3629,11 +4047,12 @@ function compileSceneOverview(overview, includeComparison = true) {
   if (!overview) return void 0;
   return {
     kind: overview.kind,
+    ...overview.purpose === void 0 ? {} : { purpose: overview.purpose },
     ...overview.path === void 0 ? {} : { path: overview.path },
     ...includeComparison && overview.comparison ? { comparison: { ...overview.comparison } } : {}
   };
 }
-function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections) {
+function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections, resolveImage) {
   const overview = compileSceneOverview(authoredScene.overview, false);
   return {
     id: authoredScene.id,
@@ -3654,6 +4073,7 @@ function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors
         body: step.body,
         depth: step.depth,
         requirement: step.requirement,
+        ...step.image ? { image: resolveImage(step.image) } : {},
         focus,
         connection: step.connection ? connections.get(step.connection) : void 0,
         diff: { ...diff2, id: `${authoredScene.id}-${step.id}` }
@@ -3766,8 +4186,10 @@ function buildDeconstructedFocusSteps(sceneId, stages, files) {
     });
     return focuses.map((focus, focusIndex) => ({
       id: focusIndex === 0 ? claimDeconstructedStageId(stage.id, usedIds) : claimDeconstructedFocusId(`${stage.id}-focus-${focusIndex + 1}`, reservedIds, usedIds),
-      title: focuses.length === 1 ? stage.title : `${stage.title} \xB7 ${focus.file} \xB7 Focus ${focusIndex + 1}/${focuses.length}`,
-      body: stage.narration,
+      title: focusIndex === 0 ? stage.title : `${focus.file} \xB7 Evidence ${focusIndex + 1} of ${focuses.length}`,
+      // A stage is one argument supported by multiple code focuses.
+      // Keep its explanation once in the reading/narration sequence.
+      body: focusIndex === 0 ? stage.narration : "",
       file: focus.file,
       pairIndex: stageIndex,
       side: focus.side,
@@ -4070,6 +4492,8 @@ function readGitText2(repoRoot, oid, relativePath, maxBytes, maxLineBytes) {
   if (!relativePath) {
     return { kind: "text", content: "" };
   }
+  const size = Number((0, import_child_process4.execFileSync)("git", ["cat-file", "-s", `${oid}:${relativePath}`], { cwd: repoRoot, encoding: "utf8" }).trim());
+  if (size > maxBytes) return { kind: "binary-or-large", content: "" };
   const content = (0, import_child_process4.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
     cwd: repoRoot,
     encoding: "buffer",
@@ -4111,6 +4535,49 @@ function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
     binary: additionsText === "-" || deletionsText === "-"
   };
 }
+function pinTourSource(source, repoRoot, resolved, baseOid, headOid) {
+  const copy = JSON.parse(JSON.stringify(source));
+  const pin = (ref) => {
+    let oid = resolved.get(ref);
+    if (!oid) {
+      oid = runGitText(repoRoot, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]);
+      resolved.set(ref, oid);
+    }
+    return oid;
+  };
+  copy.range = { base: baseOid, head: headOid };
+  const chapters = [...copy.chapters, ...Object.values(copy.tours || {}).flatMap((tour) => (tour == null ? void 0 : tour.chapters) || [])];
+  for (const chapter of chapters) for (const scene of chapter.scenes) {
+    if (scene.kind === "stacked-diff") for (const entry of scene.stack) {
+      entry.label ||= entry.ref;
+      entry.ref = pin(entry.ref);
+    }
+    if (scene.kind === "deconstructed-diff") {
+      scene.base = scene.base ? pin(scene.base) : baseOid;
+      scene.target = scene.target ? pin(scene.target) : headOid;
+    }
+  }
+  return copy;
+}
+function compileTourImage(repoRoot, source, revision) {
+  const object = `${revision}:${source.file}`;
+  let size;
+  try {
+    size = Number((0, import_child_process4.execFileSync)("git", ["cat-file", "-s", object], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim());
+  } catch {
+    throw new Error(`Image ${source.file} is unavailable at pinned revision ${revision}.`);
+  }
+  if (!Number.isSafeInteger(size) || size < 33 || size > MAX_TOUR_IMAGE_BYTES) {
+    throw new Error(`Image ${source.file} must be a PNG of at most 8 MiB.`);
+  }
+  const bytes = (0, import_child_process4.execFileSync)("git", ["cat-file", "blob", object], { cwd: repoRoot, maxBuffer: MAX_TOUR_IMAGE_BYTES });
+  validatePngHeader(bytes, source.file);
+  return { path: source.file, revision, alt: source.alt, dataUrl: `data:image/png;base64,${bytes.toString("base64")}` };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CHANGE_ATTENTION_VERSION,
@@ -4124,6 +4591,7 @@ function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
   materializeChangeUnits,
   parseChangeTourManifest,
   parseChangeTourSource,
-  parseChangeTourStory
+  parseChangeTourStory,
+  pinTourSource
 });
 //# sourceMappingURL=changeTour.js.map