layoutbridge-light 0.0.0-stage → 1.0.0

package/indesign/commands/70-text.js

@@ -0,0 +1,675 @@
+/* Bereich G – Text lesen und schreiben. */
+
+/*
+ * Zeilenumbrueche im Parameter: ein echter Zeilenumbruch (LF, CRLF) wird zur
+ * Absatzmarke (CR, wie InDesign sie fuehrt). U+2028 bleibt ein weicher
+ * Zeilenumbruch, alles andere unveraendert (E-30).
+ */
+function idcNormaliseText(text) {
+  var s = String(text);
+  var out = '';
+  var i, ch;
+  for (i = 0; i < s.length; i++) {
+    ch = s.charAt(i);
+    if (ch === '\r') {
+      out += '\r';
+      if (i + 1 < s.length && s.charAt(i + 1) === '\n') { i += 1; }
+    } else if (ch === '\n') {
+      out += '\r';
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+/* Enumeratorname des letzten Zeichens (SpecialCharacters) in die Absatzende-Art. */
+function idcBreakTypeFromEnum(name, fallback) {
+  if (name === 'COLUMN_BREAK') { return 'column'; }
+  if (name === 'FRAME_BREAK') { return 'frame'; }
+  if (name === 'PAGE_BREAK') { return 'page'; }
+  if (name === 'ODD_PAGE_BREAK') { return 'odd_page'; }
+  if (name === 'EVEN_PAGE_BREAK') { return 'even_page'; }
+  return fallback;
+}
+
+/* Absatzende-Art am letzten Zeichen eines Absatzes. */
+function idcBreakType(lastChar) {
+  var code = lastChar.length === 0 ? -1 : lastChar.charCodeAt(0);
+  if (code === 13) { return 'paragraph'; }
+  if (code === 14) { return 'column'; }
+  if (code === 15) { return 'frame'; }
+  if (code === 16) { return 'page'; }
+  if (code === 17) { return 'odd_page'; }
+  if (code === 18) { return 'even_page'; }
+  return 'none';
+}
+
+function idcStoryOf(frame) {
+  var story = null;
+  try { story = frame.parentStory; } catch (e) { story = null; }
+  if (story === null || story === undefined) {
+    IDC.fail('invalid_state', 'Text frame ' + Number(frame.id) + ' has no story.', { frame_id: Number(frame.id) });
+  }
+  return story;
+}
+
+function idcOverflows(frame) {
+  try { return frame.overflows === true; } catch (e) { return null; }
+}
+
+function idcParagraphStyleName(paragraph) {
+  try { return String(paragraph.appliedParagraphStyle.name); } catch (e) { return null; }
+}
+
+/* ----------------------------------------------------------- get_frame_text */
+
+IDC.register('get_frame_text', { needs_document: true, read_only: true, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcTextFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var story = idcStoryOf(frame);
+    var paragraphs = [];
+    var storyLength = 0;
+    var i, p, text, length, last, breakType, position = 0, endExcl, frameStart = null, frameEnd = null, frameChars = null;
+    var onlyPortion = args.only_frame_portion === true;
+    var showPlaceholders = args.show_placeholders === true;
+    var maxChars = args.max_chars === undefined || args.max_chars === null ? null : args.max_chars;
+    var kept, used = 0, omitted = 0, truncated = false, entry, from, to;
+    var lockInfo = idcStoryLockInfo(story);
+
+    if (args.include_overset !== undefined) {
+      IDC.fail('invalid_argument', 'get_frame_text has no include_overset parameter; use only_frame_portion true for the part of the story in this frame.', null);
+    }
+    if (args.only_frame_portion !== undefined && args.only_frame_portion !== null && typeof args.only_frame_portion !== 'boolean') {
+      IDC.fail('invalid_argument', 'only_frame_portion must be true or false.', { only_frame_portion: args.only_frame_portion });
+    }
+    if (maxChars !== null && (typeof maxChars !== 'number' || maxChars < 1 || Math.floor(maxChars) !== maxChars)) {
+      IDC.fail('invalid_argument', 'max_chars must be a whole number of 1 or more.', { max_chars: maxChars });
+    }
+    try { storyLength = Number(story.characters.length); } catch (e0) { storyLength = 0; }
+
+    try {
+      for (i = 0; i < story.paragraphs.length; i++) {
+        p = story.paragraphs.item(i);
+        text = '';
+        try { text = String(p.contents); } catch (e1) { text = ''; }
+        try { length = Number(p.characters.length); } catch (e2) { length = text.length; }
+        last = text.length > 0 ? text.charAt(text.length - 1) : '';
+        breakType = idcBreakType(last);
+        /*
+         * Live 05.09.2026: im Absatztext (String) erscheinen Spalten-, Rahmen-
+         * und Seitenumbruch als "\r"; erst das letzte Zeichen einzeln gelesen
+         * nennt den Enumerator (COLUMN_BREAK ...). Deshalb nachfassen.
+         */
+        if (breakType === 'paragraph' && length > 0) {
+          try { breakType = idcBreakTypeFromEnum(String(p.characters.item(length - 1).contents), breakType); } catch (eBT) { /* bleibt */ }
+        }
+        endExcl = breakType === 'none' ? position + length : position + length - 1;
+        paragraphs.push({
+          index: i,
+          start_index: position,
+          end_index: endExcl,
+          end_index_incl_break: position + length,
+          paragraph_style: idcParagraphStyleName(p),
+          text: (function () { var t = breakType === 'none' ? text : text.substr(0, text.length - 1); return showPlaceholders ? idcShowPlaceholders(t) : t; })(),
+          is_empty: endExcl === position,
+          break_type: breakType
+        });
+        position += length;
+      }
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not read the paragraphs of frame ' + args.frame_id + ': ' + String(e.message ? e.message : e),
+        { frame_id: args.frame_id, paragraphs_read: paragraphs.length });
+    }
+
+    /* Anteil dieses Rahmens an der Story (verkettete Rahmen). */
+    try {
+      var portion = frame.texts.item(0);
+      frameChars = Number(portion.characters.length);
+      if (frameChars > 0) {
+        frameStart = Number(portion.characters.item(0).index);
+        frameEnd = frameStart + frameChars;
+      } else {
+        /* Leerer Rahmen am Ende der Kette: Anteil 0, Indizes ohne Aussage. */
+        frameStart = null; frameEnd = null;
+      }
+    } catch (e3) { frameStart = null; frameEnd = null; frameChars = null; }
+
+    /*
+     * only_frame_portion: nur Absaetze, die diesen Rahmen beruehren; Text an
+     * den Rahmengrenzen beschnitten (Fund 5, Hefttest). max_chars: Textbudget
+     * ueber alle gelieferten Absaetze, danach nur noch Zaehlung.
+     */
+    if (onlyPortion) {
+      kept = [];
+      if (frameStart !== null) {
+        for (i = 0; i < paragraphs.length; i++) {
+          entry = paragraphs[i];
+          if (entry.end_index_incl_break <= frameStart || entry.start_index >= frameEnd) { continue; }
+          from = Math.max(entry.start_index, frameStart);
+          to = Math.min(entry.end_index, frameEnd);
+          entry.clipped_start = from > entry.start_index;
+          entry.clipped_end = to < entry.end_index;
+          if (entry.clipped_start || entry.clipped_end) {
+            entry.text = entry.text.substr(from - entry.start_index, Math.max(0, to - from));
+          }
+          kept.push(entry);
+        }
+      }
+      paragraphs = kept;
+    }
+    if (maxChars !== null) {
+      kept = [];
+      for (i = 0; i < paragraphs.length; i++) {
+        entry = paragraphs[i];
+        if (used >= maxChars) { omitted += 1; truncated = true; continue; }
+        if (used + entry.text.length > maxChars) {
+          entry.text = entry.text.substr(0, maxChars - used);
+          entry.clipped_end = true;
+          truncated = true;
+        }
+        used += entry.text.length;
+        kept.push(entry);
+      }
+      paragraphs = kept;
+    }
+
+    return {
+      frame_id: Number(frame.id),
+      story_id: (function () { try { return Number(story.id); } catch (e4) { return null; } })(),
+      story_length: storyLength,
+      paragraphs: paragraphs,
+      paragraph_count: paragraphs.length,
+      only_frame_portion: onlyPortion,
+      show_placeholders: showPlaceholders,
+      paragraphs_omitted: omitted,
+      truncated: truncated,
+      overset: idcOverflows(frame),
+      threaded: idcIsThreaded(frame),
+      frame_start_index: frameStart,
+      frame_end_index: frameEnd,
+      frame_character_count: frameChars,
+      lock_state: lockInfo.lock_state,
+      managed_file: lockInfo.managed_file
+    };
+  });
+
+/* ----------------------------------------------------------------- set_text */
+
+IDC.register('set_text', { needs_document: true, read_only: false, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcTextFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var story = idcStoryOf(frame);
+    var text, before = 0, after = 0;
+
+    if (typeof args.text !== 'string') {
+      IDC.fail('invalid_argument', 'text is required (a string; "" empties the frame).', null);
+    }
+    /* A-8.8: erst Absatzmarken normalisieren, dann Platzhalter – {{line_break}} bleibt so ein Zeilenumbruch. */
+    var expansion = idcExpandPlaceholders(idcNormaliseText(args.text), args.placeholders !== false);
+    var split = idcSplitBreaks(expansion.text);
+    text = split.plain;
+    idcPlaceholderWarnings(ctx, expansion);
+    idcRejectStoryLocked(story, Number(frame.id), 'set_text');
+    try { before = Number(story.characters.length); } catch (e0) { before = 0; }
+
+    /* Wirklich ersetzen: die ganze Story (0 … Laenge), nicht anhaengen. */
+    try {
+      story.contents = text;
+    } catch (e) {
+      try {
+        if (before > 0) { story.characters.itemByRange(0, before - 1).contents = text; }
+        else { story.insertionPoints.item(0).contents = text; }
+      } catch (e2) {
+        IDC.fail('script_error', 'InDesign could not set the text of frame ' + args.frame_id + ': ' + String(e.message ? e.message : e) +
+          ' / ' + String(e2.message ? e2.message : e2), { frame_id: args.frame_id });
+      }
+    }
+    try { idcInsertBreaks(story, 0, split.breaks); } catch (eB) {
+      if (eB && eB.isIdcError) { throw eB; }
+      ctx.warn('Column/frame/page breaks could not be inserted: ' + String(eB.message ? eB.message : eB));
+    }
+    text = expansion.text;
+    try { after = Number(story.characters.length); } catch (e3) { after = null; }
+    if (after !== null && after !== text.length) {
+      ctx.warn('The story reads ' + after + ' characters after writing ' + text.length + ' – InDesign may have converted or dropped characters.');
+    }
+    if (idcIsThreaded(frame)) {
+      ctx.warn('The frame is threaded (verkettet); the whole story across all its frames was replaced.');
+    }
+    ctx.changes = { modified_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      character_count: after,
+      previous_character_count: before,
+      overset: idcOverflows(frame),
+      story_id: (function () { try { return Number(story.id); } catch (e4) { return null; } })(),
+      placeholders_replaced: expansion.replaced,
+      placeholders_unknown: expansion.unknown
+    };
+  });
+
+/* -------------------------------------------------------- set_text_in_range */
+
+/*
+ * Sitzung 24 (Befund aus dem Praxiseinsatz): contents = auf einem Bereich loescht
+ * ihn und setzt am Einfuegepunkt neu ein. Der Einfuegepunkt traegt das
+ * Format des Zeichens davor – beginnt der Bereich an einem Absatzanfang, ist
+ * das die Absatzmarke des vorigen Absatzes, und der neue Text erbt dessen
+ * Format. keep_format_of:
+ *   start  (Vorgabe) neuen Text hinter das erste ersetzte Zeichen setzen –
+ *          er erbt dessen Format –, dann die alten Zeichen entfernen;
+ *   before bisheriger Weg (InDesigns eigene Wahl, das Zeichen davor);
+ *   none   bisheriger Weg, danach Zeichenformat [None] und keine lokalen
+ *          Zeichenabweichungen im neuen Text (Format des Absatzformats).
+ */
+function idcKeepFormatOf(args) {
+  var mode = args.keep_format_of;
+  if (mode === undefined || mode === null) { return 'start'; }
+  if (mode !== 'start' && mode !== 'before' && mode !== 'none') {
+    IDC.fail('invalid_argument', 'keep_format_of must be "start", "before" or "none".', { keep_format_of: mode });
+  }
+  return mode;
+}
+
+/*
+ * Bereich [start, end) durch text ersetzen, absatzweise (Nacharbeit 2 zu
+ * Sitzung 24, Lauf S24). Vorbild je ersetztem Absatz ist sein erstes Zeichen
+ * im Bereich: der Bereichsanfang, dann jede Stelle hinter einer Absatzmarke
+ * im Bereich. Der neue Text wird an den Absatzmarken geteilt; Teil 0 (bis
+ * einschliesslich der ersten neuen Absatzmarke) bekommt das Format des
+ * ersten ersetzten Zeichens, Teil i das des i-ten ersetzten Absatzes, jeder
+ * weitere Teil das des letzten ersetzten Absatzes.
+ *
+ * Jeder Teil wird hinter sein Vorbild eingefuegt und erbt so dessen Format.
+ * Ist das Vorbild eine Absatzmarke, liegt der Einfuegepunkt dahinter schon
+ * im naechsten Absatz (Lauf S24: 9 statt 20 pt) – dann vor ihr einfuegen,
+ * also im Absatz, dessen Marke ersetzt wird. Danach die alten Zeichen
+ * entfernen (von hinten) und jedem neuen Absatz das Absatzformat seines
+ * Vorbilds zuweisen, wenn InDesign beim Verschmelzen ein anderes gewaehlt
+ * hat (lokale Abweichungen bleiben).
+ */
+function idcReplaceKeepingStart(story, start, end, text) {
+  var old = '', anchors = [], segments = [], groups = [], i, k, c, shift, ip, piece, first, last, runEnd, offset, para, style;
+  try { old = String(story.characters.itemByRange(start, end - 1).contents); } catch (e0) { old = ''; }
+  if (old.length !== end - start) {
+    old = '';
+    for (i = start; i < end; i++) { old += String(story.characters.item(i).contents); }
+  }
+  anchors.push(start);
+  for (i = 0; i < old.length - 1; i++) {
+    if (old.charAt(i) === '\r') { anchors.push(start + i + 1); }
+  }
+  /* neuer Text in Teile bis einschliesslich jeder Absatzmarke */
+  piece = '';
+  for (i = 0; i < text.length; i++) {
+    piece += text.charAt(i);
+    if (text.charAt(i) === '\r') { segments.push(piece); piece = ''; }
+  }
+  if (piece.length > 0 || segments.length === 0) { segments.push(piece); }
+  /* Gruppen je Vorbild: Text, Einfuegepunkt, Absatzformat des Vorbilds, Anfang jedes Teils im neuen Text */
+  for (k = 0; k < anchors.length; k++) {
+    groups.push({ anchor: anchors[k], text: '', parts: [], style: null, ip: 0 });
+  }
+  offset = 0;
+  for (i = 0; i < segments.length; i++) {
+    k = i < anchors.length ? i : anchors.length - 1;
+    groups[k].parts.push(offset);
+    groups[k].text += segments[i];
+    offset += segments[i].length;
+  }
+  for (k = 0; k < groups.length; k++) {
+    c = old.charAt(groups[k].anchor - start);
+    groups[k].ip = c === '\r' ? groups[k].anchor : groups[k].anchor + 1;
+    try { groups[k].style = story.characters.item(groups[k].anchor).appliedParagraphStyle; } catch (eS) { groups[k].style = null; }
+  }
+  /* einfuegen von hinten, damit die vorderen Stellen gelten */
+  for (k = groups.length - 1; k >= 0; k--) {
+    if (groups[k].text.length > 0) { story.insertionPoints.item(groups[k].ip).contents = groups[k].text; }
+  }
+  /* alte Zeichen: neue Lage = alte + Laenge aller Teile, die davor eingefuegt wurden; zusammenhaengend von hinten entfernen */
+  runEnd = -1;
+  last = -1;
+  for (i = end - 1; i >= start - 1; i--) {
+    ip = -1;
+    if (i >= start) {
+      shift = 0;
+      for (k = 0; k < groups.length; k++) {
+        if (groups[k].ip <= i) { shift += groups[k].text.length; }
+      }
+      ip = i + shift;
+    }
+    if (ip >= 0 && runEnd >= 0 && ip === last - 1) {
+      last = ip;
+    } else {
+      if (runEnd >= 0) { story.characters.itemByRange(last, runEnd).remove(); }
+      runEnd = ip;
+      last = ip;
+    }
+  }
+  /* Absatzformat je neuem Teil */
+  for (k = 0; k < groups.length; k++) {
+    if (groups[k].style === null) { continue; }
+    for (i = 0; i < groups[k].parts.length; i++) {
+      first = start + groups[k].parts[i];
+      if (first >= start + text.length) { continue; }
+      try {
+        para = story.characters.item(first).paragraphs.item(0);
+        style = para.appliedParagraphStyle;
+        if (String(style.name) !== String(groups[k].style.name)) {
+          try { para.applyParagraphStyle(groups[k].style, false); } catch (eA) { para.appliedParagraphStyle = groups[k].style; }
+        }
+      } catch (eP) { /* Absatzformat nicht lesbar: InDesigns Wahl bleibt */ }
+    }
+  }
+}
+
+/* Zeichenformat [None] und keine lokalen Zeichenabweichungen im Bereich [start, start + n). */
+function idcClearCharacterFormat(doc, story, start, n) {
+  var range, none;
+  if (n < 1) { return; }
+  range = story.characters.itemByRange(start, start + n - 1);
+  none = idcNoneCharacterStyle(doc);
+  if (none !== null) {
+    try { range.applyCharacterStyle(none); } catch (e1) { range.appliedCharacterStyle = none; }
+  }
+  if (typeof OverrideType !== 'undefined') { range.clearOverrides(OverrideType.CHARACTER_ONLY); }
+  else { range.clearOverrides(); }
+}
+
+IDC.register('set_text_in_range', { needs_document: true, read_only: false, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcTextFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var story = idcStoryOf(frame);
+    var start = args.start_index;
+    var end = args.end_index;
+    var text, length = 0, replaced, after;
+    var keepFormat = idcKeepFormatOf(args);
+
+    if (typeof start !== 'number' || Math.floor(start) !== start || start < 0) {
+      IDC.fail('invalid_argument', 'start_index must be a whole number of 0 or more (inclusive).', { start_index: start });
+    }
+    if (typeof end !== 'number' || Math.floor(end) !== end || end < start) {
+      IDC.fail('invalid_argument', 'end_index must be a whole number not smaller than start_index (exclusive).', { start_index: start, end_index: end });
+    }
+    if (typeof args.text !== 'string') {
+      IDC.fail('invalid_argument', 'text is required (a string; "" deletes the range).', null);
+    }
+    var expansion = idcExpandPlaceholders(idcNormaliseText(args.text), args.placeholders !== false);
+    var split = idcSplitBreaks(expansion.text);
+    text = split.plain;
+    idcPlaceholderWarnings(ctx, expansion);
+    try { length = Number(story.characters.length); } catch (e0) { length = 0; }
+    if (end > length) {
+      IDC.fail('invalid_argument', 'end_index ' + end + ' exceeds the story length ' + length + '.', { end_index: end, story_length: length });
+    }
+    replaced = end - start;
+    idcRejectStoryLocked(story, Number(frame.id), 'set_text_in_range');
+
+    try {
+      if (replaced === 0) {
+        if (text.length > 0) { story.insertionPoints.item(start).contents = text; }
+      } else if (text.length === 0) {
+        story.characters.itemByRange(start, end - 1).remove();
+      } else if (keepFormat === 'start') {
+        idcReplaceKeepingStart(story, start, end, text);
+      } else {
+        story.characters.itemByRange(start, end - 1).contents = text;
+      }
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not change characters ' + start + '–' + end + ' of frame ' + args.frame_id + ': ' +
+        String(e.message ? e.message : e), { frame_id: args.frame_id, start_index: start, end_index: end });
+    }
+    try { idcInsertBreaks(story, start, split.breaks); } catch (eB) {
+      if (eB && eB.isIdcError) { throw eB; }
+      ctx.warn('Column/frame/page breaks could not be inserted: ' + String(eB.message ? eB.message : eB));
+    }
+    text = expansion.text;
+    if (keepFormat === 'none' && text.length > 0) {
+      try { idcClearCharacterFormat(doc, story, start, text.length); } catch (eN) {
+        ctx.warn('The new text was written, but its character formatting could not be cleared: ' + String(eN.message ? eN.message : eN));
+      }
+    }
+    try { after = Number(story.characters.length); } catch (e1) { after = null; }
+    if (after !== null && after !== length - replaced + text.length) {
+      ctx.warn('The story reads ' + after + ' characters, expected ' + (length - replaced + text.length) + '.');
+    }
+    ctx.changes = { modified_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      replaced_chars: replaced,
+      inserted_chars: text.length,
+      story_length: after,
+      keep_format_of: keepFormat,
+      overset: idcOverflows(frame),
+      placeholders_replaced: expansion.replaced,
+      placeholders_unknown: expansion.unknown
+    };
+  });
+
+/* ------------------------------------------------------------- find_replace */
+
+function idcSetFindOptions(options, args) {
+  try { options.includeMasterPages = args.include_master_pages === true; } catch (e1) { /* nicht vorhanden */ }
+  try { options.includeHiddenLayers = args.include_hidden_layers === true; } catch (e2) { /* nicht vorhanden */ }
+  try { options.includeLockedLayersForFind = args.include_locked_layers === true; } catch (e3) { /* nicht vorhanden */ }
+  try { options.includeLockedStoriesForFind = args.include_locked_layers === true; } catch (e4) { /* nicht vorhanden */ }
+  try { options.includeFootnotes = true; } catch (e5) { /* nicht vorhanden */ }
+  try { options.caseSensitive = args.case_sensitive === true; } catch (e6) { /* GREP kennt das nicht */ }
+  try { options.wholeWord = args.whole_word === true; } catch (e7) { /* GREP kennt das nicht */ }
+}
+
+/* Fundstelle beschreiben: Rahmen, Seite, Index, Text. */
+function idcDescribeMatch(doc, textObject) {
+  var entry = { frame_id: null, page_id: null, page_name: '', index: null, text: null, story_id: null };
+  var frames, frame, landing;
+  try { entry.index = Number(textObject.index); } catch (e0) { entry.index = null; }
+  try { entry.text = String(textObject.contents); } catch (e1) { entry.text = null; }
+  try { entry.story_id = Number(textObject.parentStory.id); } catch (e2) { entry.story_id = null; }
+  try {
+    frames = textObject.parentTextFrames;
+    if (frames && frames.length > 0) {
+      frame = IDC.concrete(frames[0]);
+      entry.frame_id = Number(frame.id);
+      landing = IDC.landing(frame);
+      entry.page_id = landing.page_id;
+      entry.page_name = landing.page_name;
+    }
+  } catch (e3) { /* Text ohne Rahmen (Uebersatz) */ }
+  return entry;
+}
+
+/*
+ * Sitzung 38 (A-23, A-25 Nr. 2 und 4): Fundstellen nach Story ordnen und
+ * gesperrte Stories herausnehmen. Liefert { open: [Fundstellen], stories:
+ * [freie Stories in Reihenfolge], skipped: [Sperrangaben mit matches] }.
+ */
+function idcSplitMatchesByLock(found) {
+  var out = { open: [], stories: [], skipped: [] };
+  var seen = {}, i, story, id, info, entry, frames;
+  for (i = 0; i < found.length; i++) {
+    story = null;
+    try { story = found[i].parentStory; } catch (e0) { story = null; }
+    id = null;
+    try { id = Number(story.id); } catch (e1) { id = null; }
+    if (story === null || story === undefined || id === null) { out.open.push(found[i]); continue; }
+    if (!IDC.hasOwn(seen, String(id))) {
+      info = idcStoryLockInfo(story);
+      entry = { story: story, info: info, skipped: null };
+      if (info.write_locked) {
+        entry.skipped = { story_id: id, frame_id: null, lock_state: info.lock_state, managed_file: info.managed_file, matches: 0 };
+        try {
+          frames = story.textContainers;
+          if (frames && frames.length > 0) { entry.skipped.frame_id = Number(IDC.concrete(frames[0]).id); }
+        } catch (e2) { /* ohne Rahmen */ }
+        out.skipped.push(entry.skipped);
+      } else {
+        out.stories.push(story);
+      }
+      seen[String(id)] = entry;
+    }
+    entry = seen[String(id)];
+    if (entry.skipped !== null) { entry.skipped.matches += 1; } else { out.open.push(found[i]); }
+  }
+  return out;
+}
+
+/* Rahmen-IDs der geaenderten Stellen (A-25 Nr. 2), jede einmal, in Fundreihenfolge. */
+function idcFrameIdsOfMatches(found) {
+  var ids = [], seen = {}, i, frames, id;
+  for (i = 0; i < found.length; i++) {
+    try {
+      frames = found[i].parentTextFrames;
+      if (frames && frames.length > 0) {
+        id = Number(IDC.concrete(frames[0]).id);
+        if (!IDC.hasOwn(seen, String(id))) { seen[String(id)] = true; ids.push(id); }
+      }
+    } catch (e) { /* Uebersatz: kein Rahmen */ }
+  }
+  return ids;
+}
+
+/*
+ * Ersetzen in einer freien Story: Story.changeText/changeGrep, sonst ueber
+ * ihren Text (texts.item(0)) wie im Rahmenbereich. Live zu pruefen (Testplan
+ * Sitzung 38): nur dieser Weg laeuft, wenn gesperrte Fundstellen dabei sind.
+ */
+function idcChangeInStory(story, grep) {
+  var text = null;
+  if (typeof story.changeText === 'function') { return grep ? story.changeGrep() : story.changeText(); }
+  try { text = story.texts.item(0); } catch (e0) { text = null; }
+  if (text === null || text === undefined) {
+    IDC.fail('script_error', 'This story offers no find/change.', null);
+  }
+  return grep ? text.changeGrep() : text.changeText();
+}
+
+IDC.register('find_replace', { needs_document: true, read_only: false, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var mode = args.mode === undefined || args.mode === null ? 'literal' : args.mode;
+    var scope = args.scope === undefined || args.scope === null ? 'document' : args.scope;
+    var dryRun = args.dry_run === true;
+    var maxMatches = 200;
+    var target, frame, found, i, matches = [], count = 0, prefsFind, prefsChange, options;
+    var split = { open: [], stories: [], skipped: [] }, changed = [], part, j, skippedMatches = 0, lockedInScope = [], unlisted = 0, frameLock;
+
+    if (typeof args.find !== 'string' || args.find === '') {
+      IDC.fail('invalid_argument', 'find is required and must not be empty.', null);
+    }
+    if (!dryRun && typeof args.replace !== 'string') {
+      IDC.fail('invalid_argument', 'replace is required (a string; "" deletes the matches). Use dry_run true to only count.', null);
+    }
+    if (mode !== 'literal' && mode !== 'grep') {
+      IDC.fail('invalid_argument', 'mode must be literal or grep.', { mode: mode });
+    }
+    if (scope !== 'document' && scope !== 'frame') {
+      IDC.fail('invalid_argument', 'scope must be document or frame.', { scope: scope });
+    }
+    if (scope === 'frame') {
+      frame = idcTextFrameArg(doc, args, 'frame_id').item;
+      try { target = frame.texts.item(0); } catch (e0) { target = null; }
+      if (target === null || target === undefined) { target = idcStoryOf(frame); }
+    } else {
+      target = doc;
+    }
+
+    if (mode === 'grep') {
+      prefsFind = 'findGrepPreferences';
+      prefsChange = 'changeGrepPreferences';
+      options = app.findChangeGrepOptions;
+    } else {
+      prefsFind = 'findTextPreferences';
+      prefsChange = 'changeTextPreferences';
+      options = app.findChangeTextOptions;
+    }
+
+    try {
+      app[prefsFind] = NothingEnum.NOTHING;
+      app[prefsChange] = NothingEnum.NOTHING;
+      idcSetFindOptions(options, args);
+      app[prefsFind].findWhat = args.find;
+      if (!dryRun) { app[prefsChange].changeTo = args.replace; }
+
+      /*
+       * Erst suchen, dann nur in freien Stories ersetzen: gesperrte Stories
+       * (A-23) aendert InDesign im Layout, die Redaktionsdatei bliebe alt –
+       * oder es ersetzt still nichts (A-25 Nr. 4). Ohne gesperrte Fundstellen
+       * bleibt der Lauf wie bisher ein einziger changeText/changeGrep.
+       */
+      found = mode === 'grep' ? target.findGrep() : target.findText();
+      split = idcSplitMatchesByLock(found);
+      if (dryRun) {
+        count = split.open.length;
+        for (i = 0; i < split.open.length && i < maxMatches; i++) { matches.push(idcDescribeMatch(doc, split.open[i])); }
+        if (split.open.length > maxMatches) { ctx.warn('Only the first ' + maxMatches + ' of ' + split.open.length + ' matches are listed.'); }
+      } else if (split.skipped.length === 0) {
+        changed = mode === 'grep' ? target.changeGrep() : target.changeText();
+        count = changed.length;
+      } else {
+        for (i = 0; i < split.stories.length; i++) {
+          part = idcChangeInStory(split.stories[i], mode === 'grep');
+          for (j = 0; j < part.length; j++) { changed.push(part[j]); }
+        }
+        count = changed.length;
+      }
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not run find/change (' + mode + '): ' + String(e.message ? e.message : e),
+        { find: args.find, mode: mode, scope: scope });
+    } finally {
+      try { app[prefsFind] = NothingEnum.NOTHING; } catch (er1) { ctx.warn('Could not reset the find preferences.'); }
+      try { app[prefsChange] = NothingEnum.NOTHING; } catch (er2) { ctx.warn('Could not reset the change preferences.'); }
+    }
+
+    if (mode === 'literal' && / /.test(args.find)) {
+      ctx.warn('The search text contains a non-breaking space (U+00A0); literal search does not find it reliably – use mode grep with ~S.');
+    }
+    for (i = 0; i < split.skipped.length; i++) { skippedMatches += split.skipped[i].matches; }
+    if (split.skipped.length > 0) {
+      ctx.warn(skippedMatches + ' match(es) in ' + split.skipped.length + ' locked story/stories were ' + (dryRun ? 'left out of the count' : 'not replaced') +
+        ' (see skipped_locked). Check the story out in the editorial system or in InCopy first.');
+    }
+    if (args.include_locked_layers !== true) {
+      /* Ohne include_locked_layers sucht InDesign gesperrte Stories nicht ab: darauf hinweisen. */
+      if (scope === 'frame') {
+        frameLock = idcStoryLockInfo(idcStoryOf(frame));
+        if (frameLock.write_locked) { lockedInScope.push(frameLock); }
+      } else {
+        lockedInScope = idcWriteLockedStories(doc);
+      }
+      for (i = 0; i < lockedInScope.length; i++) {
+        unlisted += 1;
+        for (j = 0; j < split.skipped.length; j++) {
+          if (split.skipped[j].story_id === lockedInScope[i].story_id) { unlisted -= 1; break; }
+        }
+      }
+      if (unlisted > 0) {
+        ctx.warn(unlisted + ' locked story/stories ' + (scope === 'frame' ? '(this frame) ' : '') + 'were not searched and are never changed by find_replace; include_locked_layers true lists their matches in skipped_locked.');
+      }
+    }
+    if (!dryRun && count > 0) { ctx.changes = { replacements: count, modified_frame_ids: scope === 'frame' ? [Number(frame.id)] : idcFrameIdsOfMatches(changed) }; }
+    var out = {
+      replacements: dryRun ? 0 : count,
+      matches_found: count,
+      dry_run: dryRun,
+      scope: scope,
+      mode: mode,
+      frame_id: scope === 'frame' ? Number(frame.id) : null,
+      master_pages_included: args.include_master_pages === true,
+      hidden_layers_included: args.include_hidden_layers === true,
+      locked_layers_included: args.include_locked_layers === true,
+      skipped_locked: split.skipped
+    };
+    if (dryRun) { out.matches = matches; }
+    return out;
+  });