@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/slides-2/server/lib/slide-content-patch.ts

@@ -0,0 +1,1004 @@
+import {
+  applyTargetedReplace,
+  analyzeRegexSource,
+  findTargetedMatches,
+  wrapDiagnosticSnippet,
+  type TargetedAmbiguousMatch,
+  type TargetedCandidate,
+  type TargetedMatchesResult,
+} from "@agent-native/core/shared";
+import { z } from "zod";
+
+export type SlideContentEdit =
+  | {
+      op?: "replace";
+      find?: string;
+      objectId?: string;
+      replace: string;
+      all?: boolean;
+      occurrence?: number;
+      expectedMatches?: number;
+      required?: boolean;
+    }
+  | {
+      op: "insert-before" | "insert-after";
+      marker: string;
+      content: string;
+      occurrence?: number;
+      expectedMatches?: number;
+      required?: boolean;
+    }
+  | {
+      op: "replace-between";
+      start: string;
+      end: string;
+      content: string;
+      includeDelimiters?: boolean;
+      expectedMatches?: number;
+      required?: boolean;
+    }
+  | {
+      op: "regex-replace";
+      pattern: string;
+      replace: string;
+      flags?: string;
+      all?: boolean;
+      expectedMatches?: number;
+      required?: boolean;
+    };
+
+export const SlideContentEditSchema = z.union([
+  z
+    .object({
+      op: z.literal("replace").optional(),
+      find: z.string().optional(),
+      objectId: z.string().min(1).optional(),
+      replace: z.string(),
+      all: z.boolean().optional(),
+      occurrence: z.number().int().positive().optional(),
+      expectedMatches: z.number().int().nonnegative().optional(),
+      required: z.boolean().optional(),
+    })
+    .superRefine((edit, context) => {
+      if (edit.find !== undefined && edit.objectId !== undefined) {
+        context.addIssue({
+          code: "custom",
+          message:
+            "This replace edit sent both find and objectId. Resend it with ONLY objectId (omit find, all, occurrence) to replace a selected element's content, or with ONLY find to search and replace text.",
+        });
+      } else if (edit.find === undefined && edit.objectId === undefined) {
+        context.addIssue({
+          code: "custom",
+          message:
+            "A replace edit needs find (the text to search for) or objectId (the selected element's data-slide-object-id).",
+        });
+      }
+      if (
+        edit.find === undefined &&
+        edit.objectId !== undefined &&
+        (edit.all !== undefined || edit.occurrence !== undefined)
+      ) {
+        context.addIssue({
+          code: "custom",
+          message:
+            "objectId replacement does not support all or occurrence; resend the edit without them (they apply only to find).",
+        });
+      }
+      if (
+        edit.objectId !== undefined &&
+        edit.expectedMatches !== undefined &&
+        edit.expectedMatches !== 1
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "objectId replacement expectedMatches must be 1",
+        });
+      }
+    }),
+  z.object({
+    op: z.enum(["insert-before", "insert-after"]),
+    marker: z.string(),
+    content: z.string(),
+    occurrence: z.number().int().positive().optional(),
+    expectedMatches: z.number().int().nonnegative().optional(),
+    required: z.boolean().optional(),
+  }),
+  z.object({
+    op: z.literal("replace-between"),
+    start: z.string(),
+    end: z.string(),
+    content: z.string(),
+    includeDelimiters: z.boolean().optional(),
+    expectedMatches: z.number().int().nonnegative().optional(),
+    required: z.boolean().optional(),
+  }),
+  z.object({
+    op: z.literal("regex-replace"),
+    pattern: z.string(),
+    replace: z.string(),
+    flags: z.string().optional(),
+    all: z.boolean().optional(),
+    expectedMatches: z.number().int().nonnegative().optional(),
+    required: z.boolean().optional(),
+  }),
+]);
+
+export class SlideContentEditError extends Error {
+  readonly code = "slide_content_edit_failed";
+  readonly actionContractError = true;
+  readonly errorCode = "slide_content_edit_failed";
+  readonly statusCode = 400;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "SlideContentEditError";
+  }
+}
+
+export interface SlideContentPatchResult {
+  content: string;
+  applied: string[];
+  formatted: boolean;
+  changed: boolean;
+}
+
+export async function applySlideContentEdits(
+  currentContent: string,
+  edits: readonly SlideContentEdit[],
+  format = false,
+): Promise<SlideContentPatchResult> {
+  let content = currentContent;
+  const applied: string[] = [];
+  try {
+    for (const edit of edits) {
+      const result = applyEdit(content, edit);
+      content = result.content;
+      applied.push(result.summary);
+    }
+  } catch (error) {
+    if (error instanceof SlideContentEditError) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SlideContentEditError(message);
+  }
+
+  const changed = content !== currentContent;
+  if (format) {
+    content = await formatSlideHtml(content);
+  }
+
+  return { content, applied, formatted: format, changed };
+}
+
+export async function formatSlideHtml(content: string): Promise<string> {
+  try {
+    const [{ format }, ...plugins] = await Promise.all([
+      import("prettier/standalone"),
+      import("prettier/plugins/html"),
+      import("prettier/plugins/postcss"),
+      import("prettier/plugins/babel"),
+      import("prettier/plugins/estree"),
+    ]);
+    const protectedContent = protectPreformattedBlocks(content);
+    const protectedText = protectHtmlText(protectedContent.content);
+    const formatted = await format(protectedText.content, {
+      parser: "html",
+      htmlWhitespaceSensitivity: "ignore",
+      plugins,
+    });
+    return protectedContent.restore(protectedText.restore(formatted));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (
+      message.includes("Cannot find package 'prettier'") ||
+      message.includes('Cannot find package "prettier"') ||
+      message.includes("Cannot find module 'prettier'") ||
+      message.includes('Cannot find module "prettier"')
+    ) {
+      throw new Error(
+        "HTML formatting is unavailable because Prettier is not installed",
+      );
+    }
+    throw new Error(`Unable to format slide HTML: ${message}`);
+  }
+}
+
+function protectPreformattedBlocks(content: string): {
+  content: string;
+  restore: (formatted: string) => string;
+} {
+  const blocks = findPreformattedBlocks(content);
+  if (blocks.length === 0) return { content, restore: (html) => html };
+
+  let markerPrefix = "slides-preformatted-block";
+  while (content.includes(markerPrefix)) markerPrefix += "-";
+
+  const replacements = blocks.map((block, index) => ({
+    ...block,
+    marker: `${markerPrefix}-${index}`,
+  }));
+  let protectedContent = "";
+  let cursor = 0;
+  for (const block of replacements) {
+    protectedContent +=
+      content.slice(cursor, block.start) +
+      `<pre data-slides-preformatted="${block.marker}"></pre>`;
+    cursor = block.end;
+  }
+  protectedContent += content.slice(cursor);
+
+  return {
+    content: protectedContent,
+    restore(formatted) {
+      let restored = formatted;
+      for (const block of replacements) {
+        const placeholder = `<pre data-slides-preformatted="${block.marker}"></pre>`;
+        if (!restored.includes(placeholder)) {
+          throw new Error("Unable to restore preformatted slide content");
+        }
+        restored = restored.replace(
+          placeholder,
+          content.slice(block.start, block.end),
+        );
+      }
+      return restored;
+    },
+  };
+}
+
+function findPreformattedBlocks(
+  html: string,
+): Array<{ start: number; end: number }> {
+  const blocks: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+
+  while (cursor < html.length) {
+    const tagStart = html.indexOf("<", cursor);
+    if (tagStart === -1) break;
+    if (html.startsWith("<!--", tagStart)) {
+      const commentEnd = html.indexOf("-->", tagStart + 4);
+      cursor = commentEnd === -1 ? html.length : commentEnd + 3;
+      continue;
+    }
+
+    const closing = html[tagStart + 1] === "/";
+    const nameStart = tagStart + (closing ? 2 : 1);
+    const tagName = tagNameAt(html, nameStart);
+    if (!tagName) {
+      cursor = tagStart + 1;
+      continue;
+    }
+    const tagEnd = tagEndIndex(html, nameStart + tagName.length);
+    if (tagEnd === -1) break;
+
+    if (!closing && tagName === "pre") {
+      const close = findMatchingCloseTag(html, tagName, tagEnd + 1);
+      if (close) {
+        blocks.push({ start: tagStart, end: close.end });
+        cursor = close.end;
+        continue;
+      }
+    }
+
+    if (!closing && RAW_TEXT_TAG_NAMES.has(tagName)) {
+      const rawClose = rawTextCloseIndex(html, tagName, tagEnd + 1);
+      cursor = rawClose === -1 ? html.length : rawClose + tagName.length + 3;
+    } else {
+      cursor = tagEnd + 1;
+    }
+  }
+
+  return blocks;
+}
+
+function protectHtmlText(content: string): {
+  content: string;
+  restore: (formatted: string) => string;
+} {
+  const ranges = findHtmlText(content);
+  if (ranges.length === 0) return { content, restore: (html) => html };
+
+  let markerPrefix = "slides-text-node";
+  while (content.includes(markerPrefix)) markerPrefix += "-";
+
+  const replacements = ranges.map((range, index) => ({
+    ...range,
+    marker: `${markerPrefix}-${index}`,
+  }));
+  let protectedContent = "";
+  let cursor = 0;
+  for (const range of replacements) {
+    protectedContent +=
+      content.slice(cursor, range.start) +
+      (range.comment ? `<!--${range.marker}-->` : range.marker);
+    cursor = range.end;
+  }
+  protectedContent += content.slice(cursor);
+
+  return {
+    content: protectedContent,
+    restore(formatted) {
+      let restored = formatted;
+      for (const range of replacements) {
+        const placeholder = range.comment
+          ? `<!--${range.marker}-->`
+          : range.marker;
+        const index = restored.indexOf(placeholder);
+        if (index === -1) {
+          throw new Error("Unable to restore slide text content");
+        }
+        const original = content.slice(range.start, range.end);
+        if (!range.comment) {
+          let start = index;
+          let end = index + placeholder.length;
+          while (start > 0 && /[\t\n\f\r ]/.test(restored[start - 1]!)) {
+            start -= 1;
+          }
+          while (end < restored.length && /[\t\n\f\r ]/.test(restored[end]!)) {
+            end += 1;
+          }
+          restored = restored.slice(0, start) + original + restored.slice(end);
+        } else {
+          restored =
+            restored.slice(0, index) +
+            original +
+            restored.slice(index + placeholder.length);
+        }
+      }
+      return restored;
+    },
+  };
+}
+
+function findHtmlText(
+  html: string,
+): Array<{ start: number; end: number; comment?: boolean }> {
+  const ranges: Array<{ start: number; end: number; comment?: boolean }> = [];
+  const addTextRange = (start: number, end: number) => {
+    if (start < end) ranges.push({ start, end });
+  };
+  let cursor = 0;
+  let textStart = 0;
+
+  while (cursor < html.length) {
+    const tagStart = html.indexOf("<", cursor);
+    if (tagStart === -1) break;
+
+    if (html.startsWith("<!--", tagStart)) {
+      addTextRange(textStart, tagStart);
+      const commentEnd = html.indexOf("-->", tagStart + 4);
+      const end = commentEnd === -1 ? html.length : commentEnd + 3;
+      ranges.push({ start: tagStart, end, comment: true });
+      cursor = end;
+      textStart = end;
+      continue;
+    }
+
+    const closing = html[tagStart + 1] === "/";
+    const nameStart = tagStart + (closing ? 2 : 1);
+    const tagName = tagNameAt(html, nameStart);
+    if (!tagName) {
+      cursor = tagStart + 1;
+      continue;
+    }
+    const tagEnd = tagEndIndex(html, nameStart + tagName.length);
+    if (tagEnd === -1) {
+      cursor = tagStart + 1;
+      continue;
+    }
+
+    addTextRange(textStart, tagStart);
+
+    if (!closing && RAW_TEXT_TAG_NAMES.has(tagName)) {
+      const rawClose = rawTextCloseIndex(html, tagName, tagEnd + 1);
+      if (tagName === "style" || tagName === "script") {
+        if (rawClose === -1) {
+          cursor = html.length;
+          textStart = html.length;
+          break;
+        }
+        cursor = rawClose;
+        textStart = rawClose;
+        continue;
+      }
+      if (rawClose === -1) {
+        addTextRange(tagEnd + 1, html.length);
+        cursor = html.length;
+        textStart = html.length;
+        break;
+      }
+      ranges.push({ start: tagEnd + 1, end: rawClose });
+      const closeEnd = tagEndIndex(html, rawClose + tagName.length + 2);
+      if (closeEnd === -1) {
+        cursor = html.length;
+        textStart = html.length;
+        break;
+      }
+      cursor = closeEnd + 1;
+      textStart = cursor;
+      continue;
+    }
+
+    cursor = tagEnd + 1;
+    textStart = cursor;
+  }
+
+  addTextRange(textStart, html.length);
+  return ranges.filter((range) => range.start < range.end);
+}
+
+function applyEdit(
+  content: string,
+  edit: SlideContentEdit,
+): { content: string; summary: string } {
+  switch (edit.op ?? "replace") {
+    case "replace":
+      return applyLiteralReplace(
+        content,
+        edit as Extract<SlideContentEdit, { op?: "replace" }>,
+      );
+    case "insert-before":
+    case "insert-after":
+      return applyInsert(
+        content,
+        edit as Extract<
+          SlideContentEdit,
+          { op: "insert-before" | "insert-after" }
+        >,
+      );
+    case "replace-between":
+      return applyReplaceBetween(
+        content,
+        edit as Extract<SlideContentEdit, { op: "replace-between" }>,
+      );
+    case "regex-replace":
+      return applyRegexReplace(
+        content,
+        edit as Extract<SlideContentEdit, { op: "regex-replace" }>,
+      );
+    default:
+      throw new SlideContentEditError(
+        `Unsupported slide content edit operation: ${String(edit.op)}`,
+      );
+  }
+}
+
+function applyLiteralReplace(
+  content: string,
+  edit: Extract<SlideContentEdit, { op?: "replace" }>,
+): { content: string; summary: string } {
+  if (edit.objectId !== undefined) {
+    if (edit.find !== undefined) {
+      throw new SlideContentEditError(
+        "A replace edit must use either find or objectId, not both",
+      );
+    }
+    if (edit.all !== undefined || edit.occurrence !== undefined) {
+      throw new SlideContentEditError(
+        "objectId replacement does not support all or occurrence",
+      );
+    }
+    if (edit.expectedMatches !== undefined && edit.expectedMatches !== 1) {
+      throw new SlideContentEditError(
+        `objectId replacement expected 1 match(es), found ${edit.expectedMatches}`,
+      );
+    }
+    return applyObjectReplace(content, edit.objectId, edit.replace);
+  }
+
+  if (!edit.find) {
+    throw new SlideContentEditError("Patch find/marker text cannot be empty");
+  }
+
+  const result = applyTargetedReplace(content, edit.find, edit.replace, {
+    occurrence: edit.occurrence,
+    all: edit.all,
+  });
+
+  if (!result.ok) {
+    if (result.reason === "not_found" && isCountedNoOp(edit)) {
+      return { content, summary: "replace:0" };
+    }
+    throwLiteralMatchFailure("replace", result, edit.expectedMatches);
+  }
+
+  if (
+    edit.expectedMatches !== undefined &&
+    result.matchCount !== edit.expectedMatches
+  ) {
+    throw new SlideContentEditError(
+      `replace expected ${edit.expectedMatches} match(es), found ${result.matchCount}`,
+    );
+  }
+
+  const summary =
+    edit.occurrence !== undefined
+      ? `replace:nth:${edit.occurrence}`
+      : edit.all
+        ? `replace:all:${result.matchCount}`
+        : "replace:first";
+  return { content: result.content, summary };
+}
+
+const RAW_TEXT_TAG_NAMES = new Set(["script", "style", "textarea", "title"]);
+const VOID_TAG_NAMES = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+function applyObjectReplace(
+  content: string,
+  objectId: string,
+  replacement: string,
+): { content: string; summary: string } {
+  const targets = findObjectTargets(content, objectId);
+  if (targets.length === 0) {
+    throw new SlideContentEditError(
+      `objectId "${objectId}" found no matching slide object`,
+    );
+  }
+  if (targets.length > 1) {
+    throw new SlideContentEditError(
+      `objectId "${objectId}" matched ${targets.length} slide objects; object IDs must be unique`,
+    );
+  }
+
+  const target = targets[0]!;
+  if (target.isVoid) {
+    throw new SlideContentEditError(
+      `objectId "${objectId}" targets <${target.tagName}>, which has no editable text content`,
+    );
+  }
+  return {
+    content:
+      content.slice(0, target.innerStart) +
+      replacement +
+      content.slice(target.innerEnd),
+    summary: "replace:object",
+  };
+}
+
+function findObjectTargets(
+  html: string,
+  objectId: string,
+): Array<{
+  innerStart: number;
+  innerEnd: number;
+  tagName: string;
+  isVoid: boolean;
+}> {
+  const targets: Array<{
+    innerStart: number;
+    innerEnd: number;
+    tagName: string;
+    isVoid: boolean;
+  }> = [];
+  let cursor = 0;
+
+  while (cursor < html.length) {
+    const tagStart = html.indexOf("<", cursor);
+    if (tagStart === -1) break;
+    if (html.startsWith("<!--", tagStart)) {
+      const commentEnd = html.indexOf("-->", tagStart + 4);
+      cursor = commentEnd === -1 ? html.length : commentEnd + 3;
+      continue;
+    }
+
+    const nameStart = tagStart + 1;
+    const tagName = tagNameAt(html, nameStart);
+    if (!tagName) {
+      cursor = tagStart + 1;
+      continue;
+    }
+    const tagEnd = tagEndIndex(html, nameStart + tagName.length);
+    if (tagEnd === -1) {
+      throw new SlideContentEditError(
+        `objectId "${objectId}" cannot be resolved because the slide HTML has an unclosed tag`,
+      );
+    }
+    const openingTag = html.slice(tagStart, tagEnd + 1);
+    if (hasObjectId(openingTag, objectId)) {
+      const isVoid = isVoidTag(tagName);
+      if (isVoid) {
+        targets.push({
+          innerStart: tagEnd + 1,
+          innerEnd: tagEnd + 1,
+          tagName,
+          isVoid,
+        });
+      } else {
+        const closing = findMatchingCloseTag(html, tagName, tagEnd + 1);
+        if (!closing) {
+          throw new SlideContentEditError(
+            `objectId "${objectId}" targets <${tagName}> without a closing tag`,
+          );
+        }
+        targets.push({
+          innerStart: tagEnd + 1,
+          innerEnd: closing.start,
+          tagName,
+          isVoid,
+        });
+      }
+    }
+
+    if (RAW_TEXT_TAG_NAMES.has(tagName) && !isVoidTag(tagName)) {
+      const rawClose = rawTextCloseIndex(html, tagName, tagEnd + 1);
+      cursor = rawClose === -1 ? html.length : rawClose + tagName.length + 3;
+    } else {
+      cursor = tagEnd + 1;
+    }
+  }
+
+  return targets;
+}
+
+function hasObjectId(tag: string, objectId: string): boolean {
+  const tagName = /^<[A-Za-z][\w:-]*/.exec(tag)?.[0];
+  if (!tagName) return false;
+
+  let cursor = tagName.length;
+  while (cursor < tag.length) {
+    while (/\s/.test(tag[cursor] ?? "")) cursor += 1;
+    if (tag[cursor] === "/" || tag[cursor] === ">") break;
+
+    const attributeStart = cursor;
+    while (cursor < tag.length && !/[\s=>/]/.test(tag[cursor] ?? "")) {
+      cursor += 1;
+    }
+    const attributeName = tag.slice(attributeStart, cursor).toLowerCase();
+    while (/\s/.test(tag[cursor] ?? "")) cursor += 1;
+    if (tag[cursor] !== "=") {
+      while (cursor < tag.length && !/[\s>]/.test(tag[cursor] ?? "")) {
+        cursor += 1;
+      }
+      continue;
+    }
+
+    cursor += 1;
+    while (/\s/.test(tag[cursor] ?? "")) cursor += 1;
+    const quote =
+      tag[cursor] === '"' || tag[cursor] === "'" ? tag[cursor] : null;
+    if (quote) cursor += 1;
+    const valueStart = cursor;
+    if (quote) {
+      while (cursor < tag.length && tag[cursor] !== quote) cursor += 1;
+    } else {
+      while (cursor < tag.length && !/[\s>]/.test(tag[cursor] ?? "")) {
+        cursor += 1;
+      }
+    }
+    const value = tag.slice(valueStart, cursor);
+    if (quote && tag[cursor] === quote) cursor += 1;
+    if (attributeName === "data-slide-object-id" && value === objectId) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function findMatchingCloseTag(
+  html: string,
+  tagName: string,
+  start: number,
+): { start: number; end: number } | null {
+  if (RAW_TEXT_TAG_NAMES.has(tagName)) {
+    const rawClose = rawTextCloseIndex(html, tagName, start);
+    return rawClose === -1
+      ? null
+      : { start: rawClose, end: rawClose + tagName.length + 3 };
+  }
+
+  let depth = 1;
+  let cursor = start;
+  while (cursor < html.length) {
+    const tagStart = html.indexOf("<", cursor);
+    if (tagStart === -1) break;
+    if (html.startsWith("<!--", tagStart)) {
+      const commentEnd = html.indexOf("-->", tagStart + 4);
+      cursor = commentEnd === -1 ? html.length : commentEnd + 3;
+      continue;
+    }
+
+    const closing = html[tagStart + 1] === "/";
+    const nameStart = tagStart + (closing ? 2 : 1);
+    const nestedTagName = tagNameAt(html, nameStart);
+    if (!nestedTagName) {
+      cursor = tagStart + 1;
+      continue;
+    }
+    const tagEnd = tagEndIndex(html, nameStart + nestedTagName.length);
+    if (tagEnd === -1) return null;
+
+    if (closing && nestedTagName === tagName) {
+      depth -= 1;
+      if (depth === 0) {
+        return { start: tagStart, end: tagEnd + 1 };
+      }
+    } else if (
+      !closing &&
+      nestedTagName === tagName &&
+      !isVoidTag(nestedTagName)
+    ) {
+      depth += 1;
+    }
+
+    if (!closing && RAW_TEXT_TAG_NAMES.has(nestedTagName)) {
+      const rawClose = rawTextCloseIndex(html, nestedTagName, tagEnd + 1);
+      cursor =
+        rawClose === -1 ? html.length : rawClose + nestedTagName.length + 3;
+    } else {
+      cursor = tagEnd + 1;
+    }
+  }
+
+  return null;
+}
+
+function isVoidTag(tagName: string): boolean {
+  return VOID_TAG_NAMES.has(tagName);
+}
+
+function tagEndIndex(html: string, start: number): number {
+  let quote: '"' | "'" | null = null;
+  for (let index = start; index < html.length; index += 1) {
+    const character = html[index];
+    if (quote) {
+      if (character === quote) quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (character === ">") return index;
+  }
+  return -1;
+}
+
+function tagNameAt(html: string, start: number): string | null {
+  const match = /^[A-Za-z][\w:-]*/.exec(html.slice(start));
+  return match?.[0]?.toLowerCase() ?? null;
+}
+
+function rawTextCloseIndex(
+  html: string,
+  tagName: string,
+  start: number,
+): number {
+  const pattern = new RegExp(`<\\/${tagName}\\s*>`, "gi");
+  pattern.lastIndex = start;
+  return pattern.exec(html)?.index ?? -1;
+}
+
+function applyInsert(
+  content: string,
+  edit: Extract<SlideContentEdit, { op: "insert-before" | "insert-after" }>,
+): { content: string; summary: string } {
+  if (!edit.marker) {
+    throw new SlideContentEditError("Patch find/marker text cannot be empty");
+  }
+
+  const result = findTargetedMatches(content, edit.marker, {
+    occurrence: edit.occurrence,
+  });
+
+  if (!result.ok) {
+    if (result.reason === "not_found" && isCountedNoOp(edit)) {
+      return { content, summary: `${edit.op}:0` };
+    }
+    throwLiteralMatchFailure(edit.op, result, edit.expectedMatches);
+  }
+
+  const { matches } = result;
+  if (
+    edit.expectedMatches !== undefined &&
+    matches.length !== edit.expectedMatches
+  ) {
+    throw new SlideContentEditError(
+      `${edit.op} expected ${edit.expectedMatches} match(es), found ${matches.length}`,
+    );
+  }
+
+  const occurrence = edit.occurrence ?? 1;
+  const match = matches[occurrence - 1]!;
+  const insertAt = edit.op === "insert-before" ? match.index : match.end;
+  return {
+    content:
+      content.slice(0, insertAt) + edit.content + content.slice(insertAt),
+    summary: `${edit.op}:${occurrence}`,
+  };
+}
+
+function isCountedNoOp(edit: {
+  expectedMatches?: number;
+  required?: boolean;
+}): boolean {
+  return (
+    edit.expectedMatches === 0 ||
+    (edit.expectedMatches === undefined && edit.required === false)
+  );
+}
+
+function throwLiteralMatchFailure(
+  op: string,
+  result: Extract<TargetedMatchesResult, { ok: false }>,
+  expectedMatches: number | undefined,
+): never {
+  if (result.reason === "ambiguous") {
+    throw new SlideContentEditError(
+      `${op} ${formatAmbiguousMatches(result.matches)}`,
+    );
+  }
+  if (result.reason === "invalid_occurrence") {
+    throw new SlideContentEditError(
+      `${op} occurrence must be a positive integer, got ${result.occurrence}`,
+    );
+  }
+  if (result.reason === "occurrence_out_of_range") {
+    if (
+      expectedMatches !== undefined &&
+      result.matchCount !== expectedMatches
+    ) {
+      throw new SlideContentEditError(
+        `${op} expected ${expectedMatches} match(es), found ${result.matchCount}`,
+      );
+    }
+    throw new SlideContentEditError(
+      `${op} could not find occurrence ${result.occurrence}`,
+    );
+  }
+  const expected =
+    expectedMatches !== undefined
+      ? `${op} expected ${expectedMatches} match(es), found 0.`
+      : `${op} found no matches.`;
+  throw new SlideContentEditError(
+    `${expected}${formatCandidates(result.candidates)}`,
+  );
+}
+
+function formatCandidates(candidates: TargetedCandidate[]): string {
+  if (candidates.length === 0) return "";
+  const lines = candidates.map((c) => `line ${c.line}: ${c.text}`).join("\n");
+  return `\nClosest matches in the current slide:\n${wrapDiagnosticSnippet(lines)}`;
+}
+
+function formatAmbiguousMatches(matches: TargetedAmbiguousMatch[]): string {
+  const lines = matches.map((m) => `line ${m.line}: ${m.snippet}`).join("\n");
+  return (
+    `matched ${matches.length} places; pass occurrence to pick one, or add ` +
+    `more surrounding context so it matches exactly one location:\n${wrapDiagnosticSnippet(lines)}`
+  );
+}
+
+function applyReplaceBetween(
+  content: string,
+  edit: Extract<SlideContentEdit, { op: "replace-between" }>,
+): { content: string; summary: string } {
+  const ranges = findBetweenRanges(content, edit.start, edit.end);
+  assertMatchCount(
+    "replace-between",
+    ranges.length,
+    edit.expectedMatches,
+    edit.required,
+  );
+  if (!ranges.length) return { content, summary: "replace-between:0" };
+  if (ranges.length > 1 && edit.expectedMatches === undefined) {
+    throw new SlideContentEditError(
+      `replace-between matched ${ranges.length} ranges; pass expectedMatches to confirm`,
+    );
+  }
+
+  let next = content;
+  for (const range of ranges.slice().reverse()) {
+    const start = edit.includeDelimiters ? range.start : range.innerStart;
+    const end = edit.includeDelimiters ? range.end : range.innerEnd;
+    next = next.slice(0, start) + edit.content + next.slice(end);
+  }
+  return { content: next, summary: `replace-between:${ranges.length}` };
+}
+
+function applyRegexReplace(
+  content: string,
+  edit: Extract<SlideContentEdit, { op: "regex-replace" }>,
+): { content: string; summary: string } {
+  const flags = normalizeRegexFlags(edit.flags, edit.all);
+  const verdict = analyzeRegexSource(edit.pattern, flags, {
+    inputBounded: false,
+  });
+  if (!verdict.safe) {
+    throw new SlideContentEditError(
+      `regex-replace pattern cannot be run safely: ${verdict.reason}. Rewrite it without overlapping repetition, or use a \`find\` edit instead.`,
+    );
+  }
+  const regex = new RegExp(edit.pattern, flags);
+  const countRegex = new RegExp(edit.pattern, ensureGlobal(flags));
+  const matches = Array.from(content.matchAll(countRegex)).length;
+  assertMatchCount(
+    "regex-replace",
+    matches,
+    edit.expectedMatches,
+    edit.required,
+  );
+  if (matches === 0) return { content, summary: "regex-replace:0" };
+  return {
+    content: content.replace(regex, edit.replace),
+    summary: `regex-replace:${edit.all ? "all" : "first"}:${matches}`,
+  };
+}
+
+function assertMatchCount(
+  op: string,
+  actual: number,
+  expected: number | undefined,
+  required: boolean | undefined,
+): void {
+  if (expected !== undefined && actual !== expected) {
+    throw new SlideContentEditError(
+      `${op} expected ${expected} match(es), found ${actual}`,
+    );
+  }
+  if (expected === undefined && required !== false && actual === 0) {
+    throw new SlideContentEditError(`${op} found no matches`);
+  }
+}
+
+function findBetweenRanges(
+  content: string,
+  startMarker: string,
+  endMarker: string,
+): Array<{ start: number; innerStart: number; innerEnd: number; end: number }> {
+  if (!startMarker || !endMarker) {
+    throw new SlideContentEditError(
+      "replace-between requires non-empty start and end markers",
+    );
+  }
+  const ranges: Array<{
+    start: number;
+    innerStart: number;
+    innerEnd: number;
+    end: number;
+  }> = [];
+  let cursor = 0;
+  while (cursor < content.length) {
+    const start = content.indexOf(startMarker, cursor);
+    if (start < 0) break;
+    const innerStart = start + startMarker.length;
+    const innerEnd = content.indexOf(endMarker, innerStart);
+    if (innerEnd < 0) {
+      throw new SlideContentEditError(
+        "replace-between found a start marker without an end",
+      );
+    }
+    const end = innerEnd + endMarker.length;
+    ranges.push({ start, innerStart, innerEnd, end });
+    cursor = end;
+  }
+  return ranges;
+}
+
+function normalizeRegexFlags(flags: string | undefined, all?: boolean): string {
+  const unique = new Set((flags ?? "").split("").filter(Boolean));
+  if (all) {
+    unique.add("g");
+  } else {
+    unique.delete("g");
+  }
+  return Array.from(unique).join("");
+}
+
+function ensureGlobal(flags: string): string {
+  return flags.includes("g") ? flags : `${flags}g`;
+}