layoutbridge-spm 0.0.1 → 1.0.0

package/indesign/commands/40-frames.js

@@ -0,0 +1,836 @@
+/* Bereich D – Rahmen und Objekte anlegen. */
+
+/* bounds_mm {x, y, width, height} pruefen; x/y duerfen negativ sein. */
+function idcBoundsArg(spec, field) {
+  if (!spec || typeof spec !== 'object') {
+    IDC.fail('invalid_argument', field + ' is required: { x, y, width, height } in mm.', null);
+  }
+  var keys = ['x', 'y', 'width', 'height'];
+  var i;
+  for (i = 0; i < keys.length; i++) {
+    if (typeof spec[keys[i]] !== 'number' || !isFinite(spec[keys[i]])) {
+      IDC.fail('invalid_argument', field + '.' + keys[i] + ' must be a number.', spec);
+    }
+  }
+  if (spec.width <= 0 || spec.height <= 0) {
+    IDC.fail('invalid_argument', field + '.width and ' + field + '.height must be greater than 0.', spec);
+  }
+  return { x: spec.x, y: spec.y, width: spec.width, height: spec.height };
+}
+
+function idcPointArg(spec, field) {
+  if (!spec || typeof spec !== 'object' || typeof spec.x !== 'number' || typeof spec.y !== 'number'
+    || !isFinite(spec.x) || !isFinite(spec.y)) {
+    IDC.fail('invalid_argument', field + ' is required: { x, y } in mm.', null);
+  }
+  return { x: spec.x, y: spec.y };
+}
+
+function idcCoordinateSpace(args) {
+  var space = args.coordinate_space;
+  if (space === undefined || space === null) { return 'page'; }
+  if (space !== 'page' && space !== 'spread') {
+    IDC.fail('invalid_argument', 'coordinate_space must be "page" or "spread".', { coordinate_space: space });
+  }
+  return space;
+}
+
+/* Seite (Dokument oder Muster) fuer page_id, sonst Fehler. */
+function idcAnyPageById(doc, id) {
+  var found;
+  if (id === undefined || id === null) {
+    IDC.fail('invalid_argument', 'page_id is required.', null);
+  }
+  found = IDC.pageById(doc, id);
+  if (found === null) {
+    IDC.fail('not_found', 'No page with page_id ' + id + ' in this document.', { page_id: id });
+  }
+  return found;
+}
+
+/* [y1, x1, y2, x2] aus {x, y, width, height}. */
+function idcRectToBounds(rect) {
+  return [rect.y, rect.x, rect.y + rect.height, rect.x + rect.width];
+}
+
+/* Seitenkoordinaten in Bogenkoordinaten: x um den Seitenversatz verschieben. */
+function idcToSpreadBounds(page, bounds, space) {
+  var dx = space === 'spread' ? 0 : IDC.spreadOffsetOfPage(page);
+  return [bounds[0], bounds[1] + dx, bounds[2], bounds[3] + dx];
+}
+
+/*
+ * Objekt auf einer Seite anlegen. collectionName: 'textFrames' |
+ * 'rectangles' | 'graphicLines'. Angelegt wird immer unter Bogen-Nullpunkt
+ * mit umgerechneten Koordinaten – so ist eindeutig, wo das Objekt hinkommt,
+ * auch bei Anschnitt ueber den Bund (E-28).
+ */
+function idcAddItem(doc, page, collectionName, bounds, space) {
+  var item;
+  var spreadBounds = idcToSpreadBounds(page, bounds, space);
+  try {
+    item = IDC.withRulerOrigin(doc, RulerOrigin.SPREAD_ORIGIN, function () {
+      var created = page[collectionName].add(undefined, undefined, undefined, { geometricBounds: spreadBounds });
+      return IDC.concrete(created);
+    });
+  } catch (e) {
+    IDC.fail('script_error', 'InDesign could not create the object: ' + String(e.message ? e.message : e),
+      { page_id: Number(page.id), bounds: bounds });
+  }
+  return item;
+}
+
+/* Landeprüfung (allgemeine Anforderung 4): Warnung bei Abweichung. */
+function idcCheckLanding(ctx, item, wantedPage, what) {
+  var landing = IDC.landing(item);
+  if (landing.on_pasteboard) {
+    ctx.warn('The ' + what + ' landed on the pasteboard (Montageflaeche), not on page ' + String(wantedPage.name) + '.');
+  } else if (landing.page_id !== Number(wantedPage.id)) {
+    ctx.warn('The ' + what + ' landed on page ' + landing.page_name + ' (page_id ' + landing.page_id +
+      '), not on the requested page ' + String(wantedPage.name) + ' – InDesign assigns an object to the page holding most of it.');
+  }
+  return landing;
+}
+
+/* Begrenzung relativ zur Seite, auf der das Objekt gelandet ist (Montageflaeche: Bogen). */
+function idcItemBounds(doc, item) {
+  try { return IDC.boundsOnOwnPage(doc, item); } catch (e) { return null; }
+}
+
+/*
+ * Koordinatenraum einer gelesenen Begrenzung: 'page' (Objekt liegt auf einer
+ * Seite, Werte relativ zu deren linker oberer Ecke) oder 'spread' (Montage-
+ * flaeche, Werte im Bogen). Lesende Werkzeuge geben ihn mit aus, damit die
+ * Werte unveraendert an set_frame_bounds zurueckgehen koennen (Vermerk E-63).
+ */
+function idcBoundsSpace(item) {
+  var page = null, valid = false;
+  try { page = item.parentPage; } catch (e) { page = null; }
+  try { valid = page !== null && page !== undefined && page.isValid === true; } catch (e2) { valid = false; }
+  if (valid) { return 'page'; }
+  return 'spread';
+}
+
+/* Hat das Objekt Textumfluss (Textumfluss-Modus ungleich none)? */
+function idcHasTextWrap(item) {
+  var name = idcTextWrapName(item);
+  if (name === null) { return false; }
+  return name !== 'none';
+}
+
+/* Zahl der Stories mit Uebersatz im Dokument; null, wenn nicht lesbar. */
+function idcOversetStoryCount(doc) {
+  var count = 0, i, story, over;
+  try {
+    for (i = 0; i < doc.stories.length; i++) {
+      story = doc.stories.item(i);
+      over = null;
+      try { over = story.overflows === true; } catch (e) { over = null; }
+      if (over === true) { count = count + 1; }
+    }
+  } catch (e2) { return null; }
+  return count;
+}
+
+/* Uebersatzstand vor einer Aenderung an einem Rahmen mit Textumfluss; null ohne Textumfluss. */
+function idcRecomposeBefore(doc, item) {
+  if (!idcHasTextWrap(item)) { return null; }
+  return { overset: idcOversetStoryCount(doc) };
+}
+
+/* Uebersatzstand ohne Bedingung (fuer Werkzeuge, die den Textumfluss selbst setzen). */
+function idcOversetBefore(doc) {
+  return { overset: idcOversetStoryCount(doc) };
+}
+
+/*
+ * Nach der Aenderung: Umbruch erzwingen und den Uebersatzstand gegenhalten.
+ * InDesign bricht die Stories um einen Rahmen mit Textumfluss nach einer
+ * Geometrieaenderung nicht zuverlaessig vollstaendig neu um - der Umbruch
+ * blieb selbst nach Ruecknahme der Geometrie in einem Zwischenzustand, bis
+ * das Dokument geschlossen und neu geoeffnet wurde (Live-Fund 08.09.2026,
+ * Vermerk E-63).
+ */
+function idcRecomposeAfter(ctx, doc, before) {
+  var out = { recomposed: false, overset_stories_before: null, overset_stories_after: null, overset_changed: null };
+  if (before === null || before === undefined) { return out; }
+  out.overset_stories_before = before.overset;
+  try { doc.recompose(); out.recomposed = true; } catch (e) { out.recomposed = false; }
+  if (out.recomposed !== true) {
+    ctx.warn('The object carries a text wrap, but InDesign could not recompose the document; the text flow around it may be stale - check preflight_document.');
+    return out;
+  }
+  out.overset_stories_after = idcOversetStoryCount(doc);
+  if (out.overset_stories_before !== null && out.overset_stories_after !== null) {
+    out.overset_changed = out.overset_stories_after !== out.overset_stories_before;
+    if (out.overset_stories_after > out.overset_stories_before) {
+      ctx.warn('The object carries a text wrap; after recomposing ' + out.overset_stories_after +
+        ' story/stories overflow (before: ' + out.overset_stories_before + ') - see list_stories or preflight_document.');
+    }
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------- Farbfelder */
+
+function idcParseHex(hex, field) {
+  var text = String(hex);
+  var match = text.match(/^#?([0-9a-fA-F]{6})$/);
+  if (!match) {
+    IDC.fail('invalid_argument', field + ' must be a hex colour like "#1A2B3C".', { value: text });
+  }
+  var h = match[1];
+  return {
+    r: parseInt(h.substr(0, 2), 16),
+    g: parseInt(h.substr(2, 2), 16),
+    b: parseInt(h.substr(4, 2), 16),
+    name: '#' + h.toUpperCase()
+  };
+}
+
+/* Farbfeld [None] – der Skriptname ist in jeder Sprachfassung "None". */
+function idcNoneSwatch(doc) {
+  var swatch = null;
+  try {
+    swatch = doc.swatches.itemByName('None');
+    if (swatch && swatch.isValid === true) { return swatch; }
+  } catch (e) { /* weiter */ }
+  try {
+    swatch = doc.swatches.item(0);
+    if (swatch && swatch.isValid === true) { return swatch; }
+  } catch (e2) { /* weiter */ }
+  return null;
+}
+
+function idcBlackSwatch(doc) {
+  var swatch = null;
+  try {
+    swatch = doc.swatches.itemByName('Black');
+    if (swatch && swatch.isValid === true) { return swatch; }
+  } catch (e) { /* weiter */ }
+  return null;
+}
+
+/* RGB-Farbfeld zu einem Hexwert; vorhandenes gleichen Namens wird wiederverwendet. */
+function idcSwatchForHex(doc, hex, field, created) {
+  var rgb = idcParseHex(hex, field);
+  var color = null;
+  try {
+    color = doc.colors.itemByName(rgb.name);
+    if (color && color.isValid === true) { return color; }
+  } catch (e) { color = null; }
+  try {
+    /* Colors.add nimmt nur withProperties – anders als die Rahmensammlungen (Live-Fund 04.09.2026). */
+    color = doc.colors.add({
+      name: rgb.name,
+      model: ColorModel.PROCESS,
+      space: ColorSpace.RGB,
+      colorValue: [rgb.r, rgb.g, rgb.b]
+    });
+    created.push(Number(color.id));
+    return color;
+  } catch (e2) {
+    IDC.fail('script_error', 'InDesign could not create the colour swatch ' + rgb.name + ': ' +
+      String(e2.message ? e2.message : e2), { hex: rgb.name });
+  }
+  return null;
+}
+
+/*
+ * Vorhandenes Farbfeld ueber seinen exakten Namen (Hausfarben, CMYK) –
+ * Alternative zu den Hex-Parametern, die RGB-Felder anlegen (Fund 7,
+ * Hefttest Sitzung 6). "none" ist nicht erlaubt; dafuer die Hex-Wege.
+ */
+function idcSwatchArg(doc, name, field) {
+  var swatch;
+  if (typeof name !== 'string' || name === '') {
+    IDC.fail('invalid_argument', field + ' must be the exact name of an existing swatch.', { value: name });
+  }
+  if (name.charAt(0) === '[' || name.toLowerCase() === 'none') {
+    IDC.fail('invalid_argument', field + ' cannot be "' + name + '"; use the hex parameters or set_frame_appearance with "none".', { value: name });
+  }
+  swatch = idcSwatchByName(doc, name);
+  if (swatch === null) {
+    IDC.fail('not_found', 'Swatch "' + name + '" not found – names are exact (see list_swatches); create it with create_swatch.',
+      { swatch_name: name });
+  }
+  return swatch;
+}
+
+function idcBothGiven(args, a, b) {
+  if (args[a] !== undefined && args[a] !== null && args[b] !== undefined && args[b] !== null) {
+    IDC.fail('invalid_argument', 'Pass either ' + a + ' or ' + b + ', not both.', null);
+  }
+}
+
+function idcSetStrokeWeightPt(item, weight) {
+  IDC.inPoints(function () { item.strokeWeight = weight; });
+}
+
+/* Kontur und Flaeche zurücklesen: Staerke in Punkt, Farbfeldnamen. */
+function idcAppearance(item) {
+  var out = { stroke_weight_pt: null, stroke_color: null, fill_color: null };
+  try { out.stroke_weight_pt = IDC.inPoints(function () { return IDC.round(Number(item.strokeWeight), 3); }); } catch (e1) { out.stroke_weight_pt = null; }
+  try { out.stroke_color = String(item.strokeColor.name); } catch (e2) { out.stroke_color = null; }
+  try { out.fill_color = String(item.fillColor.name); } catch (e3) { out.fill_color = null; }
+  return out;
+}
+
+function idcSetNoTextWrap(item) {
+  try {
+    if (typeof TextWrapModes !== 'undefined') {
+      item.textWrapPreferences.textWrapMode = TextWrapModes.NONE;
+      return true;
+    }
+  } catch (e) { /* kein Umfluss-Objekt */ }
+  return false;
+}
+
+function idcTextWrapName(item) {
+  var mode;
+  try { mode = item.textWrapPreferences.textWrapMode; } catch (e) { return null; }
+  if (typeof TextWrapModes === 'undefined') { return String(mode); }
+  if (IDC.enumIs(mode, TextWrapModes.NONE)) { return 'none'; }
+  if (IDC.enumIs(mode, TextWrapModes.BOUNDING_BOX_TEXT_WRAP)) { return 'bounding_box'; }
+  if (IDC.enumIs(mode, TextWrapModes.CONTOUR)) { return 'contour'; }
+  if (IDC.enumIs(mode, TextWrapModes.JUMP_OBJECT_TEXT_WRAP)) { return 'jump_object'; }
+  if (IDC.enumIs(mode, TextWrapModes.NEXT_COLUMN_TEXT_WRAP)) { return 'next_column'; }
+  return String(mode);
+}
+
+/* -------------------------------------------------------- create_text_frame */
+
+IDC.register('create_text_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcAnyPageById(doc, args.page_id);
+    var page = found.page;
+    var rect = idcBoundsArg(args.bounds_mm, 'bounds_mm');
+    var space = idcCoordinateSpace(args);
+    var frame, landing, wrap;
+
+    if (args.text_wrap !== undefined && args.text_wrap !== null && args.text_wrap !== 'none') {
+      IDC.fail('invalid_argument', 'text_wrap supports only "none" when creating.', { text_wrap: args.text_wrap });
+    }
+    var vj = args.vertical_justification;
+    if (vj !== undefined && vj !== null && vj !== 'top' && vj !== 'center' && vj !== 'bottom' && vj !== 'justify') {
+      IDC.fail('invalid_argument', 'vertical_justification must be top, center, bottom or justify.', { vertical_justification: vj });
+    }
+    /* Rahmenoptionen (Wunschliste J, Sitzung 7): Grundlinienversatz, Umfluss ignorieren, Innenabstand. */
+    var fbo = args.first_baseline_offset;
+    var fboEnum = null;
+    if (fbo !== undefined && fbo !== null) {
+      fboEnum = idcFirstBaselineFor(fbo);
+      if (fboEnum === null) {
+        IDC.fail('invalid_argument', 'first_baseline_offset must be ascent, cap_height, leading, x_height, fixed or embox_top.', { first_baseline_offset: fbo });
+      }
+    }
+    var minFirst = args.min_first_baseline_pt;
+    if (minFirst !== undefined && minFirst !== null && (typeof minFirst !== 'number' || !isFinite(minFirst) || minFirst < 0)) {
+      IDC.fail('invalid_argument', 'min_first_baseline_pt must be a number of 0 or more (points).', { min_first_baseline_pt: minFirst });
+    }
+    var ignoreWrap = args.ignore_text_wrap;
+    if (ignoreWrap !== undefined && ignoreWrap !== null && typeof ignoreWrap !== 'boolean') {
+      IDC.fail('invalid_argument', 'ignore_text_wrap must be true or false.', { ignore_text_wrap: ignoreWrap });
+    }
+    var inset = null;
+    if (args.inset_mm !== undefined && args.inset_mm !== null) { inset = idcInsetArg(args.inset_mm, 'inset_mm'); }
+
+    frame = idcAddItem(doc, page, 'textFrames', idcRectToBounds(rect), space);
+
+    var expansion = { replaced: {}, unknown: [] };
+    try {
+      if (args.initial_text !== undefined && args.initial_text !== null && String(args.initial_text) !== '') {
+        /* A-8.8: Platzhalter; der Text selbst bleibt woertlich (E-30: kein LF-zu-CR hier). */
+        expansion = idcExpandPlaceholders(String(args.initial_text), args.placeholders !== false);
+        var split = idcSplitBreaks(expansion.text);
+        frame.contents = split.plain;
+        idcInsertBreaks(frame, 0, split.breaks);
+      }
+      if (args.text_wrap === 'none') { idcSetNoTextWrap(frame); }
+      if (vj !== undefined && vj !== null && typeof VerticalJustification !== 'undefined') {
+        /*
+         * Kein verschachtelter ?:-Ausdruck: ExtendScript klammert ihn links
+         * (a ? b : c ? d : e wird zu (a ? b : c) ? d : e), "top" und "center"
+         * landeten so auf BOTTOM_ALIGN – Ursache von Fund 3 (Sitzung 6),
+         * am 05.09.2026 live nachgewiesen.
+         */
+        frame.textFramePreferences.verticalJustification = idcVerticalJustificationFor(vj);
+      }
+      if (fboEnum !== null) { frame.textFramePreferences.firstBaselineOffset = fboEnum; }
+      if (minFirst !== undefined && minFirst !== null) {
+        IDC.inPoints(function () { frame.textFramePreferences.minimumFirstBaselineOffset = minFirst; });
+      }
+      if (ignoreWrap !== undefined && ignoreWrap !== null) { frame.textFramePreferences.ignoreWrap = ignoreWrap === true; }
+      if (inset !== null) { frame.textFramePreferences.insetSpacing = [inset.top, inset.left, inset.bottom, inset.right]; }
+    } catch (e) {
+      IDC.fail('script_error', 'The text frame was created (frame_id ' + Number(frame.id) + ') but could not be configured: ' +
+        String(e.message ? e.message : e), { frame_id: Number(frame.id) });
+    }
+
+    landing = idcCheckLanding(ctx, frame, page, 'text frame');
+    idcPlaceholderWarnings(ctx, expansion);
+    wrap = idcTextWrapName(frame);
+    if (wrap !== null && wrap !== 'none') {
+      ctx.warn('The new text frame inherited text wrap (Textumfluss) "' + wrap +
+        '" from the document defaults; text frames underneath may be pushed into overset. Pass text_wrap: "none" or use set_text_wrap.');
+    }
+
+    var options = idcTextFrameOptions(doc, frame);
+    ctx.changes = { created_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      type: 'text',
+      page_id: Number(page.id),
+      coordinate_space: space,
+      bounds_mm: idcItemBounds(doc, frame),
+      landed_on_page_id: landing.page_id,
+      landed_on_page_name: landing.page_name,
+      on_parent_page: found.is_parent_page,
+      text_wrap: wrap,
+      vertical_justification: options.vertical_justification,
+      first_baseline_offset: options.first_baseline_offset,
+      min_first_baseline_pt: options.min_first_baseline_pt,
+      ignore_text_wrap: options.ignore_text_wrap,
+      inset_mm: options.inset_mm,
+      placeholders_replaced: expansion.replaced,
+      placeholders_unknown: expansion.unknown
+    };
+  });
+
+/* ------------------------------------------------------- create_image_frame */
+
+IDC.register('create_image_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcAnyPageById(doc, args.page_id);
+    var page = found.page;
+    var rect = idcBoundsArg(args.bounds_mm, 'bounds_mm');
+    var space = idcCoordinateSpace(args);
+    var keep = args.keep_default_appearance === true;
+    var frame, landing, cleared = false, none;
+
+    frame = idcAddItem(doc, page, 'rectangles', idcRectToBounds(rect), space);
+
+    if (!keep) {
+      try {
+        none = idcNoneSwatch(doc);
+        /* Reihenfolge: erst die Staerke, dann die Farben – sonst bleibt 1 pt stehen (Live-Fund 04.09.2026). */
+        idcSetStrokeWeightPt(frame, 0);
+        if (none !== null) {
+          frame.strokeColor = none;
+          frame.fillColor = none;
+        }
+        cleared = true;
+      } catch (e2) {
+        ctx.warn('Could not clear fill and stroke of the new frame: ' + String(e2.message ? e2.message : e2));
+      }
+    }
+    try {
+      if (typeof ContentType !== 'undefined') { frame.contentType = ContentType.GRAPHIC_TYPE; }
+    } catch (e0) { /* Inhaltstyp bleibt */ }
+    try {
+      if (typeof EmptyFrameFittingOptions !== 'undefined') {
+        frame.frameFittingOptions.fittingOnEmptyFrame = EmptyFrameFittingOptions.PROPORTIONALLY;
+      }
+    } catch (e1) { /* keine Einpassungsoptionen */ }
+
+    landing = idcCheckLanding(ctx, frame, page, 'image frame');
+    var look = idcAppearance(frame);
+    if (cleared && look.stroke_weight_pt !== null && look.stroke_weight_pt > 0) {
+      ctx.warn('The stroke weight reads ' + look.stroke_weight_pt + ' pt after clearing; run set_frame_appearance with stroke_weight_pt 0 and check the export.');
+    }
+
+    ctx.changes = { created_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      type: 'rectangle',
+      page_id: Number(page.id),
+      coordinate_space: space,
+      bounds_mm: idcItemBounds(doc, frame),
+      appearance_cleared: cleared,
+      stroke_weight_pt: look.stroke_weight_pt,
+      stroke_color: look.stroke_color,
+      fill_color: look.fill_color,
+      landed_on_page_id: landing.page_id,
+      landed_on_page_name: landing.page_name,
+      on_parent_page: found.is_parent_page
+    };
+  });
+
+/* --------------------------------------------------------- create_rectangle */
+
+IDC.register('create_rectangle', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcAnyPageById(doc, args.page_id);
+    var page = found.page;
+    var rect = idcBoundsArg(args.bounds_mm, 'bounds_mm');
+    var space = idcCoordinateSpace(args);
+    var swatchIds = [];
+    var fill = null, stroke = null, weight = null, radius = null;
+    var item, landing, none;
+
+    idcBothGiven(args, 'fill_hex', 'fill_swatch_name');
+    idcBothGiven(args, 'stroke_hex', 'stroke_swatch_name');
+    if (args.fill_hex !== undefined && args.fill_hex !== null) { fill = idcSwatchForHex(doc, args.fill_hex, 'fill_hex', swatchIds); }
+    if (args.fill_swatch_name !== undefined && args.fill_swatch_name !== null) { fill = idcSwatchArg(doc, args.fill_swatch_name, 'fill_swatch_name'); }
+    if (args.stroke_hex !== undefined && args.stroke_hex !== null) { stroke = idcSwatchForHex(doc, args.stroke_hex, 'stroke_hex', swatchIds); }
+    if (args.stroke_swatch_name !== undefined && args.stroke_swatch_name !== null) { stroke = idcSwatchArg(doc, args.stroke_swatch_name, 'stroke_swatch_name'); }
+    if (args.stroke_weight_pt !== undefined && args.stroke_weight_pt !== null) {
+      if (typeof args.stroke_weight_pt !== 'number' || args.stroke_weight_pt < 0) {
+        IDC.fail('invalid_argument', 'stroke_weight_pt must be a number of 0 or more.', { stroke_weight_pt: args.stroke_weight_pt });
+      }
+      weight = args.stroke_weight_pt;
+    }
+    radius = idcRadiusArg(args.corner_radius_mm, 'corner_radius_mm');
+    if (args.corner_type !== undefined && args.corner_type !== null) { idcCornerTypeFor(String(args.corner_type), 'corner_type'); }
+    var fillTint = idcTintArg(args.fill_tint_percent, 'fill_tint_percent');
+    var strokeTint = idcTintArg(args.stroke_tint_percent, 'stroke_tint_percent');
+    var fillAngle = idcAngleArg(args.gradient_fill_angle_deg, 'gradient_fill_angle_deg');
+    var strokeAngle = idcAngleArg(args.gradient_stroke_angle_deg, 'gradient_stroke_angle_deg');
+    if (args.text_wrap !== undefined && args.text_wrap !== null && args.text_wrap !== 'none' && args.text_wrap !== 'bounding_box' && args.text_wrap !== 'object_shape') {
+      IDC.fail('invalid_argument', 'text_wrap must be none, bounding_box or object_shape when creating.', { text_wrap: args.text_wrap });
+    }
+
+    item = idcAddShape(doc, page, 'rectangles', idcLayerForNew(doc, args), idcRectToBounds(rect), space, null);
+
+    try {
+      none = idcNoneSwatch(doc);
+      /*
+       * Reihenfolge: erst die Konturstaerke, dann die Konturfarbe, dann die
+       * Flaeche. Wird [None] als Konturfarbe vor der Staerke gesetzt, bleibt
+       * die Staerke bei 1 pt und die Farbe liest sich leer (Live-Fund
+       * 04.09.2026, InDesign 21.5) – die 1-pt-Kontur im Export.
+       */
+      var strokeSwatch = null;
+      var strokeWeight = 0;
+      if (stroke !== null) {
+        strokeSwatch = stroke;
+        strokeWeight = weight === null ? 1 : weight;
+      } else if (weight !== null && weight > 0) {
+        strokeSwatch = idcBlackSwatch(doc) || none;
+        strokeWeight = weight;
+      } else {
+        strokeSwatch = none;
+        strokeWeight = 0;
+      }
+      idcSetStrokeWeightPt(item, strokeWeight);
+      if (strokeSwatch !== null) { item.strokeColor = strokeSwatch; }
+      if (fill !== null) { item.fillColor = fill; }
+      else if (none !== null) { item.fillColor = none; }
+      /* A-8.3: corner_type (Vorgabe rounded, wenn nur corner_radius_mm > 0), A-8.5: Farbton und Verlaufswinkel. */
+      if (typeof CornerOptions !== 'undefined') { idcApplyCornerArgs(item, { corner_type: args.corner_type, corner_radius_mm: radius }); }
+      idcApplyTintsAndAngles(ctx, item, fillTint, strokeTint, fillAngle, strokeAngle);
+      idcApplyCreateTextWrap(item, args);
+      idcApplyName(item, args);
+    } catch (e) {
+      if (e && e.isIdcError) { throw e; }
+      IDC.fail('script_error', 'The rectangle was created (frame_id ' + Number(item.id) + ') but could not be styled: ' +
+        String(e.message ? e.message : e), { frame_id: Number(item.id) });
+    }
+
+    landing = idcCheckLanding(ctx, item, page, 'rectangle');
+    var wrap = idcTextWrapName(item);
+    if (wrap !== null && wrap !== 'none') {
+      ctx.warn('The rectangle carries text wrap (Textumfluss) "' + wrap + '" from the document defaults. Pass text_wrap: "none" or use set_text_wrap.');
+    }
+
+    var look = idcAppearanceFull(item);
+    var corners = idcReadCorners(item);
+    ctx.changes = { created_frame_ids: [Number(item.id)], created_swatch_ids: swatchIds };
+    return {
+      frame_id: Number(item.id),
+      type: 'rectangle',
+      page_id: Number(page.id),
+      coordinate_space: space,
+      bounds_mm: idcItemBounds(doc, item),
+      swatch_ids: swatchIds,
+      stroke_weight_pt: look.stroke_weight_pt,
+      stroke_color: look.stroke_color,
+      stroke_kind: look.stroke_kind,
+      fill_color: look.fill_color,
+      fill_kind: look.fill_kind,
+      fill_tint_percent: look.fill_tint_percent,
+      stroke_tint_percent: look.stroke_tint_percent,
+      gradient_fill_angle_deg: look.gradient_fill_angle_deg,
+      gradient_stroke_angle_deg: look.gradient_stroke_angle_deg,
+      corner_type: corners === null ? null : corners.top_left.type,
+      corners: corners === null ? null : { top_left: corners.top_left, top_right: corners.top_right, bottom_left: corners.bottom_left, bottom_right: corners.bottom_right },
+      landed_on_page_id: landing.page_id,
+      landed_on_page_name: landing.page_name,
+      on_parent_page: found.is_parent_page,
+      text_wrap: wrap,
+      layer_name: (function () { try { return String(item.itemLayer.name); } catch (eL) { return null; } })()
+    };
+  });
+
+/* -------------------------------------------------------------- create_line */
+
+/* Endpunkte relativ zur Landeseite: unter Bogen-Nullpunkt lesen, Seitenversatz abziehen. */
+function idcLineEnds(doc, line) {
+  var landing = IDC.landing(line);
+  var found = landing.on_pasteboard ? null : IDC.pageById(doc, landing.page_id);
+  var dx = found === null ? 0 : IDC.spreadOffsetOfPage(found.page);
+  try {
+    return IDC.withRulerOrigin(doc, RulerOrigin.SPREAD_ORIGIN, function () {
+      var path = line.paths.item(0);
+      var a = path.pathPoints.item(0).anchor;
+      var b = path.pathPoints.item(path.pathPoints.length - 1).anchor;
+      return {
+        start_mm: { x: IDC.round(a[0] - dx), y: IDC.round(a[1]) },
+        end_mm: { x: IDC.round(b[0] - dx), y: IDC.round(b[1]) }
+      };
+    });
+  } catch (e) { return { start_mm: null, end_mm: null }; }
+}
+
+IDC.register('create_line', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcAnyPageById(doc, args.page_id);
+    var page = found.page;
+    var start = idcPointArg(args.start_mm, 'start_mm');
+    var end = idcPointArg(args.end_mm, 'end_mm');
+    var space = idcCoordinateSpace(args);
+    var swatchIds = [];
+    var stroke = null, weight, line, landing, ends;
+
+    if (start.x === end.x && start.y === end.y) {
+      IDC.fail('invalid_argument', 'start_mm and end_mm must differ.', { start_mm: start, end_mm: end });
+    }
+    if (typeof args.stroke_weight_pt !== 'number' || !(args.stroke_weight_pt > 0)) {
+      IDC.fail('invalid_argument', 'stroke_weight_pt is required and must be greater than 0 (points).', { stroke_weight_pt: args.stroke_weight_pt });
+    }
+    weight = args.stroke_weight_pt;
+    idcBothGiven(args, 'stroke_hex', 'swatch_name');
+    if (args.stroke_hex !== undefined && args.stroke_hex !== null) { stroke = idcSwatchForHex(doc, args.stroke_hex, 'stroke_hex', swatchIds); }
+    if (args.swatch_name !== undefined && args.swatch_name !== null) { stroke = idcSwatchArg(doc, args.swatch_name, 'swatch_name'); }
+
+    var dx = space === 'spread' ? 0 : IDC.spreadOffsetOfPage(page);
+    try {
+      line = IDC.withRulerOrigin(doc, RulerOrigin.SPREAD_ORIGIN, function () {
+        var created = IDC.concrete(page.graphicLines.add());
+        created.paths.item(0).entirePath = [[start.x + dx, start.y], [end.x + dx, end.y]];
+        return created;
+      });
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not create the line: ' + String(e.message ? e.message : e),
+        { page_id: Number(page.id), start_mm: start, end_mm: end });
+    }
+
+    var strokeTint = idcTintArg(args.stroke_tint_percent, 'stroke_tint_percent');
+    var strokeAngle = idcAngleArg(args.gradient_stroke_angle_deg, 'gradient_stroke_angle_deg');
+    try {
+      idcSetStrokeWeightPt(line, weight);
+      line.strokeColor = stroke !== null ? stroke : (idcBlackSwatch(doc) || line.strokeColor);
+      idcApplyTintsAndAngles(ctx, line, null, strokeTint, null, strokeAngle);
+      idcSetNoTextWrap(line);
+    } catch (e2) {
+      if (e2 && e2.isIdcError) { throw e2; }
+      IDC.fail('script_error', 'The line was created (frame_id ' + Number(line.id) + ') but could not be styled: ' +
+        String(e2.message ? e2.message : e2), { frame_id: Number(line.id) });
+    }
+
+    landing = idcCheckLanding(ctx, line, page, 'line');
+    ends = idcLineEnds(doc, line);
+    var weightBack = null;
+    try { weightBack = IDC.inPoints(function () { return IDC.round(Number(line.strokeWeight), 3); }); } catch (e3) { weightBack = null; }
+
+    var strokeName = null;
+    try { strokeName = String(line.strokeColor.name); } catch (e4) { strokeName = null; }
+    ctx.changes = { created_frame_ids: [Number(line.id)], created_swatch_ids: swatchIds };
+    return {
+      frame_id: Number(line.id),
+      type: 'line',
+      page_id: Number(page.id),
+      coordinate_space: space,
+      start_mm: ends.start_mm,
+      end_mm: ends.end_mm,
+      bounds_mm: idcItemBounds(doc, line),
+      stroke_weight_pt: weightBack,
+      stroke_color: strokeName,
+      stroke_kind: idcSwatchKindSafe(line, 'strokeColor'),
+      stroke_tint_percent: idcAppearanceFull(line).stroke_tint_percent,
+      gradient_stroke_angle_deg: idcAppearanceFull(line).gradient_stroke_angle_deg,
+      swatch_ids: swatchIds,
+      landed_on_page_id: landing.page_id,
+      landed_on_page_name: landing.page_name,
+      on_parent_page: found.is_parent_page
+    };
+  });
+
+/* ---------------------------------------------------------- duplicate_frame */
+
+function idcFrameArg(doc, args, field) {
+  var found;
+  if (args[field] === undefined || args[field] === null) {
+    IDC.fail('invalid_argument', field + ' is required.', null);
+  }
+  found = IDC.itemById(doc, args[field], 'any');
+  if (found === null) {
+    IDC.fail('not_found', 'No object with ' + field + ' ' + args[field] + ' in this document.', { frame_id: args[field] });
+  }
+  /*
+   * Schreibende Befehle scheitern an gesperrten Ebenen und gesperrten
+   * Objekten – frueher mit nacktem InDesign-Fehler oder gar nicht sichtbar
+   * (Wunschliste J Nr. 2). Deshalb hier zentral: invalid_state mit Ansage.
+   */
+  if (IDC.currentCommand !== null && IDC.currentCommand.read_only !== true) {
+    idcRejectLocked(doc, found.item, args[field], IDC.currentCommand.name);
+  }
+  return found;
+}
+
+IDC.register('duplicate_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcFrameArg(doc, args, 'frame_id');
+    var source = found.item;
+    var offset = { x: 0, y: 0 };
+    var copy, landing, sourceLanding;
+
+    if (args.offset_mm !== undefined && args.offset_mm !== null) { offset = idcPointArg(args.offset_mm, 'offset_mm'); }
+
+    try {
+      copy = source.duplicate(undefined, [offset.x, offset.y]);
+      if (IDC.isArray(copy)) { copy = copy[0]; }
+      copy = IDC.concrete(copy);
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not duplicate object ' + args.frame_id + ': ' + String(e.message ? e.message : e),
+        { frame_id: args.frame_id });
+    }
+
+    sourceLanding = IDC.landing(source);
+    landing = IDC.landing(copy);
+    if (landing.on_pasteboard) {
+      ctx.warn('The duplicate landed on the pasteboard (Montageflaeche); it stays on the spread of the original – use move_frame_to_page for another page.');
+    } else if (!sourceLanding.on_pasteboard && landing.page_id !== sourceLanding.page_id) {
+      ctx.warn('The duplicate landed on page ' + landing.page_name + ', the original is on page ' + sourceLanding.page_name + '.');
+    }
+
+    ctx.changes = { new_frames: [Number(copy.id)], created_frame_ids: [Number(copy.id)] };
+    return {
+      source_frame_id: Number(source.id),
+      frame_id: Number(copy.id),
+      type: IDC.itemType(copy),
+      offset_mm: { x: offset.x, y: offset.y },
+      bounds_mm: idcItemBounds(doc, copy),
+      landed_on_page_id: landing.page_id,
+      landed_on_page_name: landing.page_name,
+      on_parent_page: found.on_parent
+    };
+  });
+
+/* ------------------------------------------------------------- delete_frame */
+
+function idcCollectIds(item, out) {
+  var i, all;
+  try { out.push(Number(item.id)); } catch (e0) { /* egal */ }
+  try {
+    all = item.allPageItems;
+    for (i = 0; i < all.length; i++) { out.push(Number(all[i].id)); }
+  } catch (e) { /* keine Kinder */ }
+}
+
+IDC.register('delete_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcFrameArg(doc, args, 'frame_id');
+    var item = found.item;
+    var type = IDC.itemType(item);
+    var landing = IDC.landing(item);
+    var ids = [];
+    var threaded = false, charactersRemoved = 0, bounds = idcItemBounds(doc, item);
+
+    idcCollectIds(item, ids);
+
+    if (type === 'text') {
+      threaded = idcIsThreaded(item);
+      if (threaded) {
+        /*
+         * Spezifikation: der Textanteil eines verketteten Rahmens geht mit.
+         * InDesign allein wuerde den Text in die Nachbarrahmen fliessen
+         * lassen; deshalb erst den Text dieses Rahmens entfernen.
+         */
+        try {
+          charactersRemoved = Number(item.texts.item(0).characters.length);
+          if (charactersRemoved > 0) { item.texts.item(0).remove(); }
+        } catch (et) {
+          ctx.warn('Could not remove the text of the threaded frame before deleting it; it may have flowed into the neighbouring frames: ' +
+            String(et.message ? et.message : et));
+        }
+      }
+    }
+
+    try {
+      item.remove();
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not delete object ' + args.frame_id + ': ' + String(e.message ? e.message : e),
+        { frame_id: args.frame_id });
+    }
+    if (threaded) {
+      ctx.warn('The frame was threaded (verkettet); its text portion (' + charactersRemoved + ' characters) was removed with it. No undo.');
+    }
+
+    ctx.changes = { removed_frame_ids: ids };
+    return {
+      frame_id: Number(args.frame_id),
+      type: type,
+      was_threaded: threaded,
+      characters_removed: charactersRemoved,
+      removed_frame_ids: ids,
+      bounds_mm: bounds,
+      page_id: landing.page_id,
+      page_name: landing.page_name,
+      on_parent_page: found.on_parent
+    };
+  });
+
+/* ------------------------------------------------------ clear_frame_content */
+
+IDC.register('clear_frame_content', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcFrameArg(doc, args, 'frame_id');
+    var item = found.item;
+    var typeBefore = IDC.itemType(item);
+    var removed = 0;
+    var i, graphics, names = [];
+
+    if (typeBefore === 'text') {
+      ctx.warn('Object ' + args.frame_id + ' is a text frame; its text is left untouched (use set_text with "" to empty it).');
+    } else if (typeBefore === 'line') {
+      ctx.warn('Object ' + args.frame_id + ' is a line; nothing to clear.');
+    } else {
+      try {
+        graphics = item.graphics;
+        for (i = graphics.length - 1; i >= 0; i--) {
+          try { names.push(String(graphics.item(i).itemLink.name)); } catch (en) { names.push(null); }
+          graphics.item(i).remove();
+          removed += 1;
+        }
+      } catch (e) {
+        IDC.fail('script_error', 'InDesign could not remove the graphic from object ' + args.frame_id + ': ' +
+          String(e.message ? e.message : e), { frame_id: args.frame_id, graphics_removed: removed });
+      }
+    }
+
+    if (removed > 0) { ctx.changes = { modified_frame_ids: [Number(item.id)] }; }
+    return {
+      frame_id: Number(item.id),
+      graphics_removed: removed,
+      removed_link_names: names,
+      type_before: typeBefore,
+      type_after: IDC.itemType(item),
+      bounds_mm: idcItemBounds(doc, item),
+      on_parent_page: found.on_parent
+    };
+  });