layoutbridge-spm 0.0.1 → 1.0.0

package/indesign/commands/60-images.js

@@ -0,0 +1,771 @@
+/* Bereich F – Bilder und Verknuepfungen. */
+
+/* Verknuepfungsstatus als Text. longForm: LINK_MISSING/LINK_OUT_OF_DATE (list_links), sonst MISSING/OUT_OF_DATE. */
+function idcLinkStatusName(status, longForm) {
+  if (status === null || status === undefined) { return null; }
+  if (typeof LinkStatus !== 'undefined') {
+    if (IDC.enumIs(status, LinkStatus.NORMAL)) { return 'NORMAL'; }
+    if (IDC.enumIs(status, LinkStatus.LINK_MISSING)) { return longForm ? 'LINK_MISSING' : 'MISSING'; }
+    if (IDC.enumIs(status, LinkStatus.LINK_OUT_OF_DATE)) { return longForm ? 'LINK_OUT_OF_DATE' : 'OUT_OF_DATE'; }
+    if (IDC.enumIs(status, LinkStatus.LINK_EMBEDDED)) { return 'EMBEDDED'; }
+  }
+  var text = String(status);
+  if (!longForm) { text = text.replace(/^LINK_/, ''); }
+  return text;
+}
+
+function idcLinkOf(graphic) {
+  var link = null;
+  try {
+    link = graphic.itemLink;
+    if (link && link.isValid !== false) { return link; }
+  } catch (e) { link = null; }
+  return null;
+}
+
+/* Alle Grafiken eines Rahmens (auch in Gruppen) als Array. */
+function idcGraphicsOf(item) {
+  var out = [];
+  var i, all;
+  try {
+    all = item.allGraphics;
+    for (i = 0; i < all.length; i++) { out.push(IDC.concrete(all[i])); }
+    if (out.length > 0) { return out; }
+  } catch (e) { /* weiter */ }
+  try {
+    all = item.graphics;
+    for (i = 0; i < all.length; i++) { out.push(IDC.concrete(all.item(i))); }
+  } catch (e2) { /* keine */ }
+  return out;
+}
+
+/* Rahmen fuer Grafiken: Rechteck, Oval, Polygon – keine Gruppe, kein Text, keine Linie. */
+function idcGraphicFrameArg(doc, args, field) {
+  var found = idcFrameArg(doc, args, field);
+  var className = IDC.className(found.item);
+  if (className !== 'Rectangle' && className !== 'Oval' && className !== 'Polygon') {
+    IDC.fail('invalid_state', 'Object ' + args[field] + ' is a ' + IDC.itemType(found.item) + ' (' + className + '), not a graphic frame.',
+      { frame_id: args[field], type: IDC.itemType(found.item) });
+  }
+  return found;
+}
+
+/* ppi [x, y] -> { x, y, min } oder null. */
+/*
+ * Mindestaufloesung fuer die Warnung (G-1): Parameter min_ppi, sonst 300 –
+ * der uebliche Offsetwert (doppelte 150-lpi-Rasterweite). Konfigurierbar
+ * ueber die Serverkonfiguration (E-54), die den Wert in die args legt.
+ */
+function idcMinPpi(args) {
+  if (args && typeof args.min_ppi === 'number' && isFinite(args.min_ppi) && args.min_ppi > 0) {
+    return args.min_ppi;
+  }
+  return 300;
+}
+
+function idcPpi(value) {
+  var x, y;
+  try {
+    if (IDC.isArray(value) && value.length >= 2) {
+      x = IDC.round(Number(value[0]), 1);
+      y = IDC.round(Number(value[1]), 1);
+      if (x === null || y === null) { return null; }
+      return { x: x, y: y, min: Math.min(x, y) };
+    }
+    if (typeof value === 'number') { return { x: IDC.round(value, 1), y: IDC.round(value, 1), min: IDC.round(value, 1) }; }
+  } catch (e) { return null; }
+  return null;
+}
+
+/* Rueckfallkette, wenn die gewuenschte PDF-Box fehlt (Fund 1, Hefttest Sitzung 6). */
+function idcPdfCropFallbacks(name) {
+  if (name === 'bleed') { return ['trim', 'crop', 'media']; }
+  if (name === 'trim') { return ['crop', 'media']; }
+  if (name === 'art' || name === 'content' || name === 'crop') { return ['crop', 'media']; }
+  return [];
+}
+
+function idcPdfCropFor(name) {
+  if (typeof PDFCrop === 'undefined') { return null; }
+  if (name === 'media') { return PDFCrop.CROP_MEDIA; }
+  if (name === 'crop') { return PDFCrop.CROP_PDF; }
+  if (name === 'trim') { return PDFCrop.CROP_TRIM; }
+  if (name === 'bleed') { return PDFCrop.CROP_BLEED; }
+  if (name === 'art') { return PDFCrop.CROP_ART; }
+  if (name === 'content') { return PDFCrop.CROP_CONTENT; }
+  return null;
+}
+
+function idcFitOptionFor(name) {
+  if (typeof FitOptions === 'undefined') { return null; }
+  if (name === 'fill_proportionally') { return FitOptions.FILL_PROPORTIONALLY; }
+  if (name === 'fit_proportionally') { return FitOptions.PROPORTIONALLY; }
+  if (name === 'fit_content_to_frame') { return FitOptions.CONTENT_TO_FRAME; }
+  if (name === 'center_content') { return FitOptions.CENTER_CONTENT; }
+  return null;
+}
+
+/* Deckt die Grafik den Rahmen bis auf 0,2 mm? */
+function idcCoversFrame(frameBounds, graphicBounds) {
+  var t = 0.2;
+  if (!frameBounds || !graphicBounds) { return false; }
+  return graphicBounds.x <= frameBounds.x + t
+    && graphicBounds.y <= frameBounds.y + t
+    && graphicBounds.x + graphicBounds.width >= frameBounds.x + frameBounds.width - t
+    && graphicBounds.y + graphicBounds.height >= frameBounds.y + frameBounds.height - t;
+}
+
+/* Beschreibung einer Grafik: Datei, Status, ppi, Farbraum, Art, Begrenzungen. */
+function idcDescribeGraphic(doc, frame, graphic, page) {
+  var link = idcLinkOf(graphic);
+  var entry = {
+    graphic_id: null,
+    link_id: null,
+    file_name: null,
+    file_path: null,
+    link_status: null,
+    effective_ppi: null,
+    effective_ppi_xy: null,
+    actual_ppi: null,
+    actual_ppi_xy: null,
+    color_space: null,
+    image_type: IDC.className(graphic),
+    is_pdf: false,
+    frame_bounds: null,
+    graphic_bounds: null,
+    hints: []
+  };
+  var ppi;
+  try { entry.graphic_id = Number(graphic.id); } catch (e0) { entry.graphic_id = null; }
+  if (link !== null) {
+    try { entry.link_id = Number(link.id); } catch (e1) { entry.link_id = null; }
+    try { entry.file_name = String(link.name); } catch (e2) { entry.file_name = null; }
+    try { entry.file_path = String(link.filePath); } catch (e3) { entry.file_path = null; }
+    try { entry.link_status = idcLinkStatusName(link.status, false); } catch (e4) { entry.link_status = null; }
+  } else {
+    entry.hints.push('err: no link object (pasted or embedded graphic without link)');
+  }
+  try {
+    if (graphic.imageTypeName !== undefined && graphic.imageTypeName !== null) { entry.image_type = String(graphic.imageTypeName); }
+  } catch (e8) { /* Klassenname bleibt */ }
+  /* Platzierte PDFs heissen "Adobe PDF" (imageTypeName) bzw. "PDF" (Klasse) – Live-Fund 04.09.2026. */
+  entry.is_pdf = /pdf/i.test(entry.image_type) || IDC.className(graphic) === 'PDF';
+  try {
+    ppi = idcPpi(graphic.effectivePpi);
+    if (ppi !== null) { entry.effective_ppi = ppi.min; entry.effective_ppi_xy = [ppi.x, ppi.y]; }
+  } catch (e5) { if (!entry.is_pdf) { entry.hints.push('err: effective ppi not available (' + String(e5.message ? e5.message : e5) + ')'); } }
+  try {
+    ppi = idcPpi(graphic.actualPpi);
+    if (ppi !== null) { entry.actual_ppi = ppi.min; entry.actual_ppi_xy = [ppi.x, ppi.y]; }
+  } catch (e6) { if (!entry.is_pdf) { entry.hints.push('err: actual ppi not available (' + String(e6.message ? e6.message : e6) + ')'); } }
+  try {
+    if (graphic.space !== undefined && graphic.space !== null) { entry.color_space = String(graphic.space).toUpperCase(); }
+  } catch (e7) { if (!entry.is_pdf) { entry.hints.push('err: colour space not available (' + String(e7.message ? e7.message : e7) + ')'); } }
+  if (entry.is_pdf && (entry.effective_ppi === null || entry.color_space === null)) {
+    entry.hints.push('err: InDesign reports neither ppi nor colour space for placed PDFs – check the file itself');
+  }
+  try { entry.frame_bounds = IDC.boundsOnPage(doc, frame, page); } catch (e9) { entry.frame_bounds = null; }
+  try { entry.graphic_bounds = IDC.boundsOnPage(doc, graphic, page); } catch (e10) { entry.graphic_bounds = null; }
+  return entry;
+}
+
+/* -------------------------------------------------------------- place_image */
+
+IDC.register('place_image', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcGraphicFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var path = args.image_path;
+    var fit = args.fit === undefined || args.fit === null ? null : args.fit;
+    var crop = args.pdf_crop === undefined || args.pdf_crop === null ? null : args.pdf_crop;
+    var pdfPage = args.pdf_page === undefined || args.pdf_page === null ? 1 : args.pdf_page;
+    var fallback = args.pdf_crop_fallback !== false;
+    var file, isPdf, prevCrop = null, prevPage = null, cropSet = false, pageSet = false;
+    var placed, graphic, removed = 0, i, graphics, fitOption, page, frameBounds, graphicBounds, fits, entry;
+    var cropUsed = crop, attempts, attempt, lastError = null, firstErrorMessage = '', k, minPpi;
+
+    if (typeof path !== 'string' || path === '') {
+      IDC.fail('invalid_argument', 'image_path is required: a real file path on the machine running InDesign.', null);
+    }
+    if (fit !== null && idcFitOptionFor(fit) === null && typeof FitOptions !== 'undefined') {
+      IDC.fail('invalid_argument', 'fit must be fill_proportionally, fit_proportionally, fit_content_to_frame or center_content.', { fit: fit });
+    }
+    if (crop !== null && idcPdfCropFor(crop) === null && typeof PDFCrop !== 'undefined') {
+      IDC.fail('invalid_argument', 'pdf_crop must be media, crop, trim, bleed, art or content.', { pdf_crop: crop });
+    }
+    if (typeof pdfPage !== 'number' || pdfPage < 1 || Math.floor(pdfPage) !== pdfPage) {
+      IDC.fail('invalid_argument', 'pdf_page must be a whole number of 1 or more.', { pdf_page: pdfPage });
+    }
+    file = IDC.fileFor(path);
+    if (!file.exists) {
+      IDC.fail('not_found', 'File not found: ' + path, { image_path: path });
+    }
+    if (IDC.fileSize(file) === 0) {
+      IDC.fail('io_error', 'File is empty (0 bytes) – a cloud placeholder that is not downloaded yet? ' + path, { image_path: path });
+    }
+    isPdf = /\.(pdf|ai)$/i.test(path);
+
+    /* Bestehende Grafik entfernen – erneutes Platzieren setzt Zuschnitt und Skalierung zurueck. */
+    graphics = idcGraphicsOf(frame);
+    for (i = graphics.length - 1; i >= 0; i--) {
+      try { graphics[i].remove(); removed += 1; } catch (er) { /* dann ersetzt place() */ }
+    }
+    if (removed > 0) { ctx.warn('The frame held ' + removed + ' graphic(s); they were replaced (crop and scale reset).'); }
+
+    try {
+      if (typeof ContentType !== 'undefined') { frame.contentType = ContentType.GRAPHIC_TYPE; }
+    } catch (ec) { /* Inhaltstyp bleibt */ }
+
+    /*
+     * Platzieren mit PDF-Importvorgabe nur fuer diesen Versuch. Fehlt der PDF
+     * die gewuenschte Box (z. B. keine TrimBox in einem QR-Code-PDF), wirft
+     * InDesign; dann Rueckfall auf die naechstgroessere Box mit Warnung
+     * (pdf_crop_fallback false schaltet das ab).
+     */
+    attempts = [crop];
+    if (isPdf && crop !== null && fallback) { attempts = attempts.concat(idcPdfCropFallbacks(crop)); }
+    placed = null;
+    for (k = 0; k < attempts.length; k++) {
+      attempt = attempts[k];
+      cropSet = false; pageSet = false;
+      try {
+        if (isPdf && typeof app.pdfPlacePreferences !== 'undefined') {
+          if (attempt !== null) {
+            prevCrop = app.pdfPlacePreferences.pdfCrop;
+            app.pdfPlacePreferences.pdfCrop = idcPdfCropFor(attempt);
+            cropSet = true;
+          }
+          prevPage = app.pdfPlacePreferences.pageNumber;
+          app.pdfPlacePreferences.pageNumber = pdfPage;
+          pageSet = true;
+        }
+      } catch (ep) {
+        ctx.warn('Could not set the PDF place preferences: ' + String(ep.message ? ep.message : ep));
+      }
+      try {
+        placed = frame.place(file);
+        lastError = null;
+      } catch (e) {
+        lastError = e;
+        placed = null;
+      } finally {
+        try { if (cropSet) { app.pdfPlacePreferences.pdfCrop = prevCrop; } } catch (er1) { ctx.warn('Could not restore the PDF crop preference.'); }
+        try { if (pageSet) { app.pdfPlacePreferences.pageNumber = prevPage; } } catch (er2) { ctx.warn('Could not restore the PDF page preference.'); }
+      }
+      if (lastError === null) {
+        cropUsed = attempt;
+        if (k > 0) {
+          ctx.warn('pdf_crop "' + crop + '" failed (InDesign: ' + firstErrorMessage + '); the PDF was placed with pdf_crop "' +
+            attempt + '" instead – the box is larger, check the position.');
+        }
+        break;
+      }
+      if (k === 0) { firstErrorMessage = String(lastError.message ? lastError.message : lastError); }
+      if (idcGraphicsOf(frame).length > 0) {
+        /* Trotz Fehler etwas platziert? Dann nicht nochmals. */
+        break;
+      }
+    }
+    if (lastError !== null) {
+      IDC.fail('io_error', 'InDesign could not place ' + path + ': ' + String(lastError.message ? lastError.message : lastError) +
+        (attempts.length > 1 ? ' (tried pdf_crop ' + attempts.join(', ') + ')' : ''), { image_path: path, frame_id: args.frame_id, pdf_crop_tried: attempts });
+    }
+    /*
+     * place() liefert in ExtendScript ein Array, das IDC.isArray nicht als
+     * solches erkennt (Live-Fund 04.09.2026). Deshalb zuerst die Grafik im
+     * Rahmen frisch lesen, place()-Rueckgabe nur als Rueckfall.
+     */
+    graphic = null;
+    graphics = idcGraphicsOf(frame);
+    if (graphics.length > 0) { graphic = graphics[0]; }
+    if (graphic === null) {
+      try {
+        if (placed && typeof placed.length === 'number' && placed.id === undefined && placed.length > 0) { graphic = IDC.concrete(placed[0]); }
+        else if (placed) { graphic = IDC.concrete(placed); }
+      } catch (eg) { graphic = null; }
+    }
+    if (graphic === null) {
+      IDC.fail('io_error', 'place() returned no graphic for ' + path, { image_path: path, frame_id: args.frame_id });
+    }
+
+    if (fit !== null) {
+      fitOption = idcFitOptionFor(fit);
+      try {
+        if (fitOption !== null) { frame.fit(fitOption); }
+      } catch (ef) {
+        ctx.warn('The graphic was placed but fit "' + fit + '" failed: ' + String(ef.message ? ef.message : ef));
+      }
+    }
+
+    page = idcPageOfItem(doc, frame);
+    entry = idcDescribeGraphic(doc, frame, graphic, page);
+    frameBounds = entry.frame_bounds;
+    graphicBounds = entry.graphic_bounds;
+    fits = idcCoversFrame(frameBounds, graphicBounds);
+    if (!fits) {
+      ctx.warn('The graphic does not cover the frame (tolerance 0.2 mm): frame ' + IDC.stringify(frameBounds) + ', graphic ' + IDC.stringify(graphicBounds) +
+        '. Use fit "fill_proportionally" or scale_image_in_frame.');
+    }
+    if (entry.link_status !== null && entry.link_status !== 'NORMAL' && entry.link_status !== 'EMBEDDED') {
+      ctx.warn('Link status after placing: ' + entry.link_status + '.');
+    }
+    minPpi = idcMinPpi(args);
+    if (entry.effective_ppi !== null && entry.effective_ppi < minPpi && !entry.is_pdf) {
+      ctx.warn('Effective resolution is ' + entry.effective_ppi + ' ppi – below ' + minPpi + ' ppi (min_ppi).');
+    }
+    var h;
+    for (h = 0; h < entry.hints.length; h++) { if (!entry.is_pdf || !/ppi|colour/.test(entry.hints[h])) { ctx.warn(entry.hints[h]); } }
+
+    ctx.changes = { modified_frame_ids: [Number(frame.id)], created_graphic_ids: [entry.graphic_id] };
+    return {
+      frame_id: Number(frame.id),
+      graphic_id: entry.graphic_id,
+      link_id: entry.link_id,
+      file_name: entry.file_name,
+      link_status: entry.link_status,
+      image_type: entry.image_type,
+      is_pdf: entry.is_pdf,
+      fit: fit,
+      pdf_crop: isPdf ? crop : null,
+      pdf_crop_used: isPdf ? cropUsed : null,
+      pdf_page: isPdf ? pdfPage : null,
+      frame_bounds_mm: frameBounds,
+      graphic_bounds_mm: graphicBounds,
+      fits_frame: fits,
+      effective_ppi: entry.effective_ppi,
+      color_space: entry.color_space,
+      graphics_replaced: removed,
+      page_id: page === null ? null : Number(page.id),
+      on_parent_page: found.on_parent
+    };
+  });
+
+/* ----------------------------------------------------- scale_image_in_frame */
+
+/* Ankerpunkt {x, y} aus einer Begrenzung. */
+function idcAnchorPoint(bounds, anchor) {
+  var x = bounds.x + bounds.width / 2;
+  var y = bounds.y + bounds.height / 2;
+  if (/left/.test(anchor)) { x = bounds.x; }
+  if (/right/.test(anchor)) { x = bounds.x + bounds.width; }
+  if (/top/.test(anchor)) { y = bounds.y; }
+  if (/bottom/.test(anchor)) { y = bounds.y + bounds.height; }
+  return { x: x, y: y };
+}
+
+IDC.register('scale_image_in_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcGraphicFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var zoom = args.zoom_factor;
+    var anchor = args.anchor === undefined || args.anchor === null ? 'center' : args.anchor;
+    var anchors = { center: 1, top: 1, bottom: 1, left: 1, right: 1, top_left: 1, top_right: 1, bottom_left: 1, bottom_right: 1 };
+    var minPpi;
+    var graphics, graphic, page, frameBounds, before, pivot, after, rotation, dx, entry;
+
+    if (typeof zoom !== 'number' || !isFinite(zoom) || !(zoom > 0)) {
+      IDC.fail('invalid_argument', 'zoom_factor must be a number greater than 0 (1.2 = 20 % larger).', { zoom_factor: zoom });
+    }
+    if (typeof anchor !== 'string' || !IDC.hasOwn(anchors, anchor)) {
+      IDC.fail('invalid_argument', 'anchor must be center, top, bottom, left, right, top_left, top_right, bottom_left or bottom_right.', { anchor: anchor });
+    }
+    graphics = idcGraphicsOf(frame);
+    if (graphics.length === 0) {
+      IDC.fail('invalid_state', 'Frame ' + args.frame_id + ' holds no graphic.', { frame_id: args.frame_id });
+    }
+    graphic = graphics[0];
+    if (graphics.length > 1) { ctx.warn('The frame holds ' + graphics.length + ' graphics; only the first was scaled.'); }
+    rotation = idcRotationOf(graphic);
+    if (rotation !== null && rotation !== 0) { ctx.warn('The graphic is rotated by ' + rotation + ' degrees; scaling via bounds may shift it.'); }
+
+    page = idcPageOfItem(doc, frame);
+    frameBounds = IDC.boundsOnPage(doc, frame, page);
+    before = IDC.boundsOnPage(doc, graphic, page);
+    pivot = idcAnchorPoint(frameBounds, anchor);
+    after = {
+      x: pivot.x + (before.x - pivot.x) * zoom,
+      y: pivot.y + (before.y - pivot.y) * zoom,
+      width: before.width * zoom,
+      height: before.height * zoom
+    };
+    dx = page === null ? 0 : IDC.spreadOffsetOfPage(page);
+    try {
+      IDC.withRulerOrigin(doc, RulerOrigin.SPREAD_ORIGIN, function () {
+        graphic.geometricBounds = [after.y, after.x + dx, after.y + after.height, after.x + after.width + dx];
+      });
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not scale the graphic in frame ' + args.frame_id + ': ' + String(e.message ? e.message : e),
+        { frame_id: args.frame_id, zoom_factor: zoom });
+    }
+
+    entry = idcDescribeGraphic(doc, frame, graphic, page);
+    minPpi = idcMinPpi(args);
+    if (entry.effective_ppi !== null && entry.effective_ppi < minPpi && !entry.is_pdf) {
+      ctx.warn('Effective resolution after zoom is ' + entry.effective_ppi + ' ppi – below ' + minPpi + ' ppi (min_ppi).');
+    }
+    if (!idcCoversFrame(entry.frame_bounds, entry.graphic_bounds)) {
+      ctx.warn('The graphic no longer covers the whole frame (tolerance 0.2 mm).');
+    }
+    ctx.changes = { modified_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      graphic_id: entry.graphic_id,
+      zoom_factor: zoom,
+      anchor: anchor,
+      graphic_bounds_mm: entry.graphic_bounds,
+      frame_bounds_mm: entry.frame_bounds,
+      graphic_bounds_before_mm: before,
+      effective_ppi: entry.effective_ppi,
+      effective_ppi_xy: entry.effective_ppi_xy,
+      fits_frame: idcCoversFrame(entry.frame_bounds, entry.graphic_bounds)
+    };
+  });
+
+/* -------------------------------------------------- position_image_in_frame */
+
+/*
+ * Sitzung 24 (Befund aus dem Praxiseinsatz, E-79): Grafik im Rahmen verschieben,
+ * ohne sie zu skalieren und ohne den Rahmen anzufassen – an einem der neun
+ * Bezugspunkte ausrichten (Bezugspunkt der Grafik auf denselben des
+ * Rahmens) und/oder um offset_mm versetzen. Schreibweg wie
+ * scale_image_in_frame: Begrenzung der Grafik unter Bogen-Nullpunkt, gleiche
+ * Groesse.
+ */
+IDC.register('position_image_in_frame', { needs_document: true, read_only: false, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcGraphicFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var anchors = { center: 1, top: 1, bottom: 1, left: 1, right: 1, top_left: 1, top_right: 1, bottom_left: 1, bottom_right: 1 };
+    var align = args.align === undefined || args.align === null ? null : args.align;
+    var offset = null;
+    var graphics, graphic, page, frameBounds, before, target, frameAnchor, graphicAnchor, rotation, dxPage, entry, frameAfter;
+
+    if (align !== null && (typeof align !== 'string' || !IDC.hasOwn(anchors, align))) {
+      IDC.fail('invalid_argument', 'align must be center, top, bottom, left, right, top_left, top_right, bottom_left or bottom_right.', { align: align });
+    }
+    if (args.offset_mm !== undefined && args.offset_mm !== null) { offset = idcPointArg(args.offset_mm, 'offset_mm'); }
+    if (align === null && offset === null) {
+      IDC.fail('invalid_argument', 'Pass align, offset_mm or both.', null);
+    }
+    graphics = idcGraphicsOf(frame);
+    if (graphics.length === 0) {
+      IDC.fail('invalid_state', 'Frame ' + args.frame_id + ' holds no graphic.', { frame_id: args.frame_id });
+    }
+    graphic = graphics[0];
+    if (graphics.length > 1) { ctx.warn('The frame holds ' + graphics.length + ' graphics; only the first was positioned.'); }
+    rotation = idcRotationOf(graphic);
+    if (rotation !== null && rotation !== 0) { ctx.warn('The graphic is rotated by ' + rotation + ' degrees; alignment uses its bounding box.'); }
+
+    page = idcPageOfItem(doc, frame);
+    frameBounds = IDC.boundsOnPage(doc, frame, page);
+    before = IDC.boundsOnPage(doc, graphic, page);
+    target = { x: before.x, y: before.y };
+    if (align !== null) {
+      frameAnchor = idcAnchorPoint(frameBounds, align);
+      graphicAnchor = idcAnchorPoint(before, align);
+      target.x = before.x + (frameAnchor.x - graphicAnchor.x);
+      target.y = before.y + (frameAnchor.y - graphicAnchor.y);
+    }
+    if (offset !== null) {
+      target.x += offset.x;
+      target.y += offset.y;
+    }
+    dxPage = page === null ? 0 : IDC.spreadOffsetOfPage(page);
+    try {
+      IDC.withRulerOrigin(doc, RulerOrigin.SPREAD_ORIGIN, function () {
+        graphic.geometricBounds = [target.y, target.x + dxPage, target.y + before.height, target.x + before.width + dxPage];
+      });
+    } catch (e) {
+      IDC.fail('script_error', 'InDesign could not move the graphic in frame ' + args.frame_id + ': ' + String(e.message ? e.message : e),
+        { frame_id: args.frame_id });
+    }
+
+    entry = idcDescribeGraphic(doc, frame, graphic, page);
+    frameAfter = entry.frame_bounds;
+    if (!idcCoversFrame(entry.frame_bounds, entry.graphic_bounds)) {
+      ctx.warn('The graphic no longer covers the whole frame (tolerance 0.2 mm) – part of the frame shows no picture.');
+    }
+    ctx.changes = { modified_frame_ids: [Number(frame.id)] };
+    return {
+      frame_id: Number(frame.id),
+      graphic_id: entry.graphic_id,
+      align: align,
+      offset_mm: offset,
+      moved_by_mm: { x: IDC.round(target.x - before.x), y: IDC.round(target.y - before.y) },
+      graphic_bounds_mm: entry.graphic_bounds,
+      graphic_bounds_before_mm: before,
+      frame_bounds_mm: frameAfter,
+      coordinate_space: page === null ? 'spread' : 'page',
+      page_id: page === null ? null : Number(page.id),
+      fits_frame: idcCoversFrame(entry.frame_bounds, entry.graphic_bounds)
+    };
+  });
+
+/* ------------------------------------------------------ get_image_link_info */
+
+IDC.register('get_image_link_info', { needs_document: true, read_only: true, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var found = idcFrameArg(doc, args, 'frame_id');
+    var frame = found.item;
+    var graphics = idcGraphicsOf(frame);
+    var page = idcPageOfItem(doc, frame);
+    var out = [];
+    var i, entry, h;
+
+    for (i = 0; i < graphics.length; i++) {
+      entry = idcDescribeGraphic(doc, frame, graphics[i], page);
+      for (h = 0; h < entry.hints.length; h++) { ctx.warn('Graphic ' + entry.graphic_id + ': ' + entry.hints[h]); }
+      out.push({
+        graphic_id: entry.graphic_id,
+        link_id: entry.link_id,
+        file_name: entry.file_name,
+        file_path: entry.file_path,
+        link_status: entry.link_status,
+        effective_ppi: entry.effective_ppi,
+        effective_ppi_xy: entry.effective_ppi_xy,
+        actual_ppi: entry.actual_ppi,
+        actual_ppi_xy: entry.actual_ppi_xy,
+        color_space: entry.color_space,
+        image_type: entry.image_type,
+        is_pdf: entry.is_pdf,
+        frame_bounds: entry.frame_bounds,
+        graphic_bounds: entry.graphic_bounds,
+        fits_frame: idcCoversFrame(entry.frame_bounds, entry.graphic_bounds),
+        err: entry.hints.length > 0 ? entry.hints.join('; ') : null
+      });
+    }
+    if (graphics.length === 0) { ctx.warn('Frame ' + args.frame_id + ' holds no graphic.'); }
+    return {
+      frame_id: Number(frame.id),
+      type: IDC.itemType(frame),
+      count: out.length,
+      graphics: out,
+      page_id: page === null ? null : Number(page.id),
+      coordinate_space: page === null ? 'spread' : 'page',
+      on_parent_page: found.on_parent
+    };
+  });
+
+/* --------------------------------------------------------------- list_links */
+
+/* Rahmen und Seite einer Verknuepfung. */
+function idcLinkPlacement(doc, link) {
+  var out = { frame_id: null, page_id: null, page_name: '' };
+  var graphic = null, frame = null, landing;
+  try { graphic = link.parent; } catch (e0) { graphic = null; }
+  if (graphic === null || graphic === undefined) { return out; }
+  try { frame = graphic.parent; } catch (e1) { frame = null; }
+  try {
+    if (frame !== null && frame !== undefined && IDC.className(frame) !== 'Spread' && IDC.className(frame) !== 'MasterSpread') {
+      out.frame_id = Number(frame.id);
+    }
+  } catch (e2) { out.frame_id = null; }
+  try {
+    landing = IDC.landing(frame !== null && frame !== undefined ? frame : graphic);
+    out.page_id = landing.page_id;
+    out.page_name = landing.page_name;
+  } catch (e3) { /* bleibt leer */ }
+  return out;
+}
+
+function idcDescribeLink(doc, link) {
+  var placement = idcLinkPlacement(doc, link);
+  var entry = { link_id: null, file_name: null, file_path: null, status: null, page_id: placement.page_id, page_name: placement.page_name, frame_id: placement.frame_id };
+  try { entry.link_id = Number(link.id); } catch (e0) { entry.link_id = null; }
+  try { entry.file_name = String(link.name); } catch (e1) { entry.file_name = null; }
+  try { entry.file_path = String(link.filePath); } catch (e2) { entry.file_path = null; }
+  try { entry.status = idcLinkStatusName(link.status, true); } catch (e3) { entry.status = null; }
+  return entry;
+}
+
+IDC.register('list_links', { needs_document: true, read_only: true, ruler: 'page' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var filter = args.path_contains === undefined || args.path_contains === null ? null : String(args.path_contains).toLowerCase();
+    var out = [];
+    var i, link, entry, haystack;
+
+    for (i = 0; i < doc.links.length; i++) {
+      link = doc.links.item(i);
+      entry = idcDescribeLink(doc, link);
+      if (filter !== null) {
+        haystack = String(entry.file_path === null ? '' : entry.file_path) + '\n' + String(entry.file_name === null ? '' : entry.file_name);
+        if (haystack.toLowerCase().indexOf(filter) < 0) { continue; }
+      }
+      out.push(entry);
+    }
+    return { links: out, count: out.length, total: Number(doc.links.length), path_contains: filter };
+  });
+
+/* ------------------------------------------------------------- relink_links */
+
+/*
+ * Gleicher Dateipfad? macOS: Gross-/Kleinschreibung egal, /private/var und
+ * /var sind derselbe Ort (Integrationssuite: temporaerer Ordner, 04.09.2026).
+ */
+function idcSamePath(a, b) {
+  function norm(p) {
+    var t = String(p).toLowerCase();
+    if (t.indexOf('/private/') === 0) { t = t.substr(8); }
+    return t;
+  }
+  return norm(a) === norm(b);
+}
+
+function idcLinkById(doc, id) {
+  var i, link;
+  try {
+    link = doc.links.itemByID(Number(id));
+    if (link && link.isValid === true) { return link; }
+  } catch (e) { /* weiter */ }
+  for (i = 0; i < doc.links.length; i++) {
+    link = doc.links.item(i);
+    try { if (Number(link.id) === Number(id)) { return link; } } catch (e2) { /* weiter */ }
+  }
+  return null;
+}
+
+IDC.register('relink_links', { needs_document: true, read_only: false, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var list = args.relink;
+    var results = [];
+    var relinked = 0, failed = 0;
+    var i, spec, link, file, oldPath, graphic, fresh, newId, statusAfter, entry;
+
+    if (!IDC.isArray(list) || list.length < 1 || list.length > 500) {
+      IDC.fail('invalid_argument', 'relink must be an array of 1 to 500 entries { link_id, new_path }.', null);
+    }
+    for (i = 0; i < list.length; i++) {
+      spec = list[i] || {};
+      entry = { link_id: spec.link_id === undefined ? null : spec.link_id, new_link_id: null, ok: false, status_after: null, reason: null, new_path: spec.new_path === undefined ? null : String(spec.new_path) };
+      if (typeof spec.link_id !== 'number' || typeof spec.new_path !== 'string' || spec.new_path === '') {
+        entry.reason = 'entry needs link_id (number) and new_path (string)';
+        failed += 1; results.push(entry); continue;
+      }
+      link = idcLinkById(doc, spec.link_id);
+      if (link === null) {
+        entry.reason = 'no link with link_id ' + spec.link_id;
+        failed += 1; results.push(entry); continue;
+      }
+      file = IDC.fileFor(spec.new_path);
+      if (!file.exists) {
+        entry.reason = 'file not found: ' + spec.new_path;
+        failed += 1; results.push(entry); continue;
+      }
+      if (IDC.fileSize(file) === 0) {
+        entry.reason = 'file is empty (0 bytes) – cloud placeholder not downloaded? ' + spec.new_path;
+        failed += 1; results.push(entry); continue;
+      }
+      oldPath = '';
+      try { oldPath = String(link.filePath); } catch (e0) { oldPath = ''; }
+      if (oldPath !== '' && idcSamePath(oldPath, IDC.fsPath(file))) {
+        entry.reason = 'new path equals the current path – use update_links';
+        failed += 1; results.push(entry); continue;
+      }
+      graphic = null;
+      try { graphic = link.parent; } catch (e1) { graphic = null; }
+      try {
+        link.relink(file);
+      } catch (e) {
+        entry.reason = 'InDesign refused: ' + String(e.message ? e.message : e);
+        failed += 1; results.push(entry); continue;
+      }
+      /* Nach relink() kann ein neues Link-Objekt entstehen – ueber die Grafik frisch lesen. */
+      fresh = null;
+      try { if (graphic !== null && graphic.isValid !== false) { fresh = graphic.itemLink; } } catch (e2) { fresh = null; }
+      if (fresh === null || fresh === undefined) { fresh = link; }
+      try {
+        if (fresh.isValid !== false) {
+          try { if (IDC.enumIs(fresh.status, LinkStatus.LINK_OUT_OF_DATE)) { fresh.update(); } } catch (eu) { /* Status bleibt */ }
+          statusAfter = idcLinkStatusName(fresh.status, true);
+          newId = Number(fresh.id);
+        } else { statusAfter = null; newId = null; }
+      } catch (e3) { statusAfter = null; newId = null; }
+      entry.ok = true;
+      entry.status_after = statusAfter;
+      entry.new_link_id = newId;
+      if (statusAfter !== null && statusAfter !== 'NORMAL') {
+        ctx.warn('Link ' + spec.link_id + ' was relinked but reads ' + statusAfter + '.');
+      }
+      relinked += 1;
+      results.push(entry);
+    }
+    if (relinked > 0) {
+      ctx.changes = { modified_link_ids: (function () {
+        var ids = [], seen = {}, k;
+        for (k = 0; k < results.length; k++) {
+          if (results[k].ok && !IDC.hasOwn(seen, String(results[k].link_id))) { seen[String(results[k].link_id)] = 1; ids.push(results[k].link_id); }
+        }
+        return ids;
+      })() };
+    }
+    return { results: results, relinked: relinked, failed: failed, considered: results.length };
+  });
+
+/* ------------------------------------------------------------- update_links */
+
+IDC.register('update_links', { needs_document: true, read_only: false, ruler: 'none' },
+  function (ctx) {
+    var args = ctx.args;
+    var doc = ctx.doc;
+    var ids = args.link_ids;
+    var results = [];
+    var updated = 0, failed = 0, nothing = 0;
+    var i, link, entry, placement, before, after, candidates = [];
+
+    if (ids !== undefined && ids !== null) {
+      if (!IDC.isArray(ids) || ids.length < 1 || ids.length > 500) {
+        IDC.fail('invalid_argument', 'link_ids must be an array of 1 to 500 link ids; leave it out to update every out-of-date link.', null);
+      }
+      for (i = 0; i < ids.length; i++) { candidates.push({ id: ids[i], link: idcLinkById(doc, ids[i]) }); }
+    } else {
+      for (i = 0; i < doc.links.length; i++) {
+        link = doc.links.item(i);
+        try { if (IDC.enumIs(link.status, LinkStatus.LINK_OUT_OF_DATE)) { candidates.push({ id: Number(link.id), link: link }); } } catch (e0) { /* ueberspringen */ }
+      }
+    }
+
+    for (i = 0; i < candidates.length; i++) {
+      link = candidates[i].link;
+      entry = { link_id: candidates[i].id, name: null, page_name: '', status_before: null, status_after: null, ok: false, reason: null };
+      if (link === null) {
+        entry.reason = 'no link with link_id ' + candidates[i].id;
+        failed += 1; results.push(entry); continue;
+      }
+      try { entry.name = String(link.name); } catch (e1) { entry.name = null; }
+      placement = idcLinkPlacement(doc, link);
+      entry.page_name = placement.page_name;
+      try { before = link.status; } catch (e2) { before = null; }
+      entry.status_before = idcLinkStatusName(before, true);
+      if (!IDC.enumIs(before, LinkStatus.LINK_OUT_OF_DATE)) {
+        entry.ok = true;
+        entry.status_after = entry.status_before;
+        entry.reason = 'nothing to do';
+        nothing += 1; results.push(entry); continue;
+      }
+      try {
+        link.update();
+      } catch (e) {
+        entry.reason = 'InDesign refused: ' + String(e.message ? e.message : e);
+        failed += 1; results.push(entry); continue;
+      }
+      try { after = link.status; } catch (e3) { after = null; }
+      entry.status_after = idcLinkStatusName(after, true);
+      entry.ok = true;
+      updated += 1;
+      results.push(entry);
+    }
+    if (updated > 0) { ctx.changes = { modified_link_ids: (function () { var out = [], k; for (k = 0; k < results.length; k++) { if (results[k].ok && results[k].reason === null) { out.push(results[k].link_id); } } return out; })() }; }
+    return { results: results, updated: updated, failed: failed, nothing_to_do: nothing, considered: results.length };
+  });