@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/image-crop.js

@@ -1,13 +1,12 @@
 // Image crop and focal point (RR-25): the model.
 //
-// The OPF schema has no crop rectangle and no focal point on an image (`Asset` is `src`, `alt`, `title`, `description`,
-// `mediaType`, `format`; the only fit controls are `design.imageFill` and a slide image's `fill`, both "crop" or "fit",
-// and a crop is always centred). `crop` and `focalPoint` are listed as deferred fields in core's
-// docs/content-item-design-overrides.md. So the editor writes a crop into the picture itself: the cropped pixels become a
-// new entry of `assets` and the image points at it, in ONE undoable change. Because the preview and the PPTX export both
-// read those pixels, they cannot disagree about what is shown; the fit the document already has (centred "crop" cover, or
-// "fit") then places the cropped picture in its frame exactly as before (opf-pptx writes the usual `a:srcRect` for that
-// placement, and none for a picture whose shape matches its frame).
+// The OPF schema has no crop rectangle on an image (`Asset` is `src`, `alt`, `title`, `description`, `mediaType`, `format`).
+// An image block has a `fit` (cover, contain, stretch) and, since OPF 0.15, a `focus` point that a cover fit keeps in view
+// (image-options.js sets both). A crop that removes part of the picture is still not a field, so the editor writes it into
+// the picture itself: the cropped pixels become a new entry of `assets` and the image points at it, in ONE undoable change.
+// Because the preview and the PPTX export both read those pixels, they cannot disagree about what is shown; the block's fit
+// then places the cropped picture in its frame exactly as before (opf-pptx writes the usual `a:srcRect` for that placement,
+// and none for a picture whose shape matches its frame).
 //
 // A focal point works the same way: the picture is cut to the frame's shape around the chosen point, so a centred cover
 // fit shows what was chosen. The original asset stays in `assets`, and the new asset's `description` says "Cropped from
@@ -156,11 +155,11 @@ export const isFullRect = (rect, bounds) => rect.x < 0.5 && rect.y < 0.5 && Math
  * (the field is `{ src, ... }`); `assetSrc` is what `src` resolves to (the asset's own `src`), and `origin` is the asset a
  * crop of this picture was made from, when there is one.
  */
-export function describeImage(document, path) {
+export function describeImage(presentation, path) {
   const segments = String(path).split(".");
   const last = segments.at(-1);
-  if (!["image", "slideImage"].includes(last)) return { error: "This is not a picture." };
-  const value = getValueAtPath(document, path);
+  if (last !== "image") return { error: "This is not a picture." };
+  const value = getValueAtPath(presentation, path);
   const pointer = opfPathToJsonPointer(segments);
   let form;
   let src;
@@ -177,7 +176,7 @@ export function describeImage(document, path) {
   let assetSrc = src;
   let entry;
   if (assetId !== undefined) {
-    entry = getValueAtPath(document, ["assets", assetId]);
+    entry = getValueAtPath(presentation, ["assets", assetId]);
     if (entry === undefined) return { error: `The picture asset "${assetId}" is missing from this presentation.` };
     assetSrc = typeof entry === "string" ? entry : entry?.src;
     if (typeof assetSrc !== "string") return { error: `The picture asset "${assetId}" has no source.` };
@@ -193,22 +192,22 @@ export function describeImage(document, path) {
 }
 
 /** How many places in the document use `asset:<id>` (the `assets` map itself is not counted). */
-export function countAssetReferences(document, id) {
+export function countAssetReferences(presentation, id) {
   const reference = `asset:${id}`;
   let count = 0;
   const walk = (value) => {
     if (typeof value === "string") count += value === reference ? 1 : 0;
     else if (Array.isArray(value)) value.forEach(walk);
-    else if (isObject(value)) for (const [key, child] of Object.entries(value)) if (key !== "assets" || value !== document) walk(child);
+    else if (isObject(value)) for (const [key, child] of Object.entries(value)) if (key !== "assets" || value !== presentation) walk(child);
   };
-  walk(document);
+  walk(presentation);
   return count;
 }
 
 // ---- the change --------------------------------------------------------------------------------------------------------
 
-function assetPatches(document, id, entry) {
-  const assets = document?.assets;
+function assetPatches(presentation, id, entry) {
+  const assets = presentation?.assets;
   return isObject(assets)
     ? [{ op: "add", path: opfPathToJsonPointer(["assets", id]), value: entry }]
     : [{ op: "add", path: "/assets", value: { [id]: entry } }];
@@ -219,33 +218,33 @@ function assetPatches(document, id, entry) {
  * pointing at it. `pixels` is `{ dataUri, mediaType, width, height }` (from `cropImagePixels`). A previous crop's asset that
  * nothing else uses is removed in the same change. Pure.
  */
-export function prepareCrop(document, path, pixels) {
-  const image = describeImage(document, path);
+export function prepareCrop(presentation, path, pixels) {
+  const image = describeImage(presentation, path);
   if (image.error) throw fail("not-croppable", image.error, { path });
   const origin = image.origin ?? image.assetId;
-  const id = uniqueAssetId(document, `${origin ?? "image"}-crop`);
+  const id = uniqueAssetId(presentation, `${origin ?? "image"}-crop`);
   const title = (isObject(image.entry) && typeof image.entry.title === "string" ? image.entry.title : origin ?? "Picture").replace(/ \(cropped\)$/, "");
   const entry = { src: pixels.dataUri, mediaType: pixels.mediaType, title: `${title} (cropped)` };
   if (image.alt) entry.alt = image.alt;
   if (origin) entry.description = `Cropped from asset:${origin}`;
-  const patches = assetPatches(document, id, entry);
+  const patches = assetPatches(presentation, id, entry);
   patches.push({ op: "replace", path: image.srcPointer, value: `asset:${id}` });
-  if (image.origin && image.assetId && countAssetReferences(document, image.assetId) === 1) patches.push({ op: "remove", path: opfPathToJsonPointer(["assets", image.assetId]) });
+  if (image.origin && image.assetId && countAssetReferences(presentation, image.assetId) === 1) patches.push({ op: "remove", path: opfPathToJsonPointer(["assets", image.assetId]) });
   return { patches, assetId: id, reference: `asset:${id}`, origin, image };
 }
 
 /** The patches that put a cropped picture back to the asset it was cropped from, or null when there is none. */
-export function prepareRestore(document, path) {
-  const image = describeImage(document, path);
-  if (image.error || !image.origin || getValueAtPath(document, ["assets", image.origin]) === undefined) return null;
+export function prepareRestore(presentation, path) {
+  const image = describeImage(presentation, path);
+  if (image.error || !image.origin || getValueAtPath(presentation, ["assets", image.origin]) === undefined) return null;
   const patches = [{ op: "replace", path: image.srcPointer, value: `asset:${image.origin}` }];
-  if (countAssetReferences(document, image.assetId) === 1) patches.push({ op: "remove", path: opfPathToJsonPointer(["assets", image.assetId]) });
+  if (countAssetReferences(presentation, image.assetId) === 1) patches.push({ op: "remove", path: opfPathToJsonPointer(["assets", image.assetId]) });
   return { patches, origin: image.origin, image };
 }
 
 /** Put a cropped picture back to its original as one undoable change. Returns null when there is no original to restore. */
 export function restoreOriginal(editor, path, meta = {}) {
-  const prepared = prepareRestore(editor.document, path);
+  const prepared = prepareRestore(editor.presentation, path);
   if (!prepared) return null;
   return { ...editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? "image-restore", path }), origin: prepared.origin };
 }
@@ -325,12 +324,12 @@ export async function cropImagePixels(loaded, rect, { mediaType, maxBytes = DEFA
  * `{ assetId, reference, width, height }`.
  */
 export async function applyCrop(editor, path, rect, options = {}) {
-  const image = describeImage(editor.document, path);
+  const image = describeImage(editor.presentation, path);
   if (image.error) throw fail("not-croppable", image.error, { path });
   const loaded = options.loaded ?? await loadImagePixels(image.assetSrc);
   const pixels = await cropImagePixels(loaded, rect, { mediaType: image.mediaType, maxBytes: options.maxBytes });
   // The document may have changed while the picture was encoding.
-  const prepared = prepareCrop(editor.document, path, pixels);
+  const prepared = prepareCrop(editor.presentation, path, pixels);
   const change = editor.applyPatch(prepared.patches, { ...options.meta, source: options.meta?.source ?? "image-crop", path, assetId: prepared.assetId });
   return { ...change, assetId: prepared.assetId, reference: prepared.reference, width: pixels.width, height: pixels.height };
 }

package/dist/image-cropper.js

@@ -121,7 +121,7 @@ export function createImageCropper(root, overlay, options) {
 
   function placePill() {
     const target = selected && !session ? frameImage(selected) : null;
-    if (!target || !editor || describeImage(editor.document, selected).error) { pill.hidden = true; return; }
+    if (!target || !editor || describeImage(editor.presentation, selected).error) { pill.hidden = true; return; }
     const box = target.getBoundingClientRect();
     const base = root.getBoundingClientRect();
     if (!box.width || !box.height) { pill.hidden = true; return; }
@@ -135,7 +135,7 @@ export function createImageCropper(root, overlay, options) {
   async function open(path, openOptions = {}) {
     if (destroyed || session) return false;
     if (options.beforeOpen && !options.beforeOpen()) return false;
-    const image = describeImage(editor.document, path);
+    const image = describeImage(editor.presentation, path);
     if (image.error) {
       options.report?.(new Error(image.error));
       return false;
@@ -483,7 +483,7 @@ export function createImageCropper(root, overlay, options) {
     aspectSelect.querySelector('option[value="frame"]').disabled = !frame;
     s.rect = fullRect(s.loaded.width, s.loaded.height);
     layout();
-    restoreButton.hidden = !prepareRestore(editor.document, path);
+    restoreButton.hidden = !prepareRestore(editor.presentation, path);
     if (s.tool === "focus") {
       s.tool = "crop";
       setTool("focus");

package/dist/image-options.d.ts

@@ -0,0 +1,45 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export declare const IMAGE_FITS: readonly ["cover", "contain", "stretch"];
+export declare const IMAGE_SHAPES: readonly ["rectangle", "rounded", "circle", "hexagon"];
+export declare const IMAGE_EDGES: readonly ["left", "right", "top", "bottom"];
+export declare const IMAGE_TREATMENT_FIELDS: readonly ["fit", "focus", "aspectRatio", "shape", "cornerRadius", "border", "opacity", "recolor", "overlay", "placement"];
+
+export interface ImageFocus { x: number; y: number }
+/** One overlay, shared by image backgrounds and image blocks: the whole picture, or a band along `edge` (`size` 0.05 to 1). */
+export interface ImageOverlay { color: string; opacity: number; edge?: (typeof IMAGE_EDGES)[number]; size?: number }
+/** The block bleeds to `edge` and takes `size` (0.1 to 0.9, default 0.5) of the slide; `inset` keeps it inside the padding. */
+export interface ImagePlacement { edge: (typeof IMAGE_EDGES)[number]; size?: number; inset?: boolean }
+export interface ImageTreatments {
+  fit?: (typeof IMAGE_FITS)[number] | null;
+  focus?: ImageFocus | null;
+  aspectRatio?: number | null;
+  shape?: (typeof IMAGE_SHAPES)[number] | null;
+  cornerRadius?: number | null;
+  border?: { color: string; width: number } | null;
+  opacity?: number | null;
+  recolor?: "grayscale" | { dark: string; light: string } | null;
+  overlay?: ImageOverlay | null;
+  placement?: ImagePlacement | null;
+}
+export interface ImageTreatmentState extends Omit<ImageTreatments, "fit" | "focus"> {
+  path: string;
+  fit?: (typeof IMAGE_FITS)[number];
+  focus?: ImageFocus;
+  /** Whether the block may be placed (a top-level block, `slides.N.blocks.I`). */
+  placeable: boolean;
+  /** Edges other placed blocks of the slide already take. */
+  usedEdges: (typeof IMAGE_EDGES)[number][];
+}
+
+export declare function normalizeFocus(value: unknown): ImageFocus;
+export declare function normalizeOverlay(value: unknown): ImageOverlay;
+export declare function normalizeRecolor(value: unknown): "grayscale" | { dark: string; light: string };
+export declare function normalizePlacement(value: unknown): ImagePlacement;
+/** The image block's framing for a form. Throws `not-an-image-block`. */
+export declare function readImageTreatments(presentation: unknown, blockPath: string | string[]): ImageTreatmentState;
+/** The patches that set (a value) or remove (`null`) the fields. Throws `invalid-image-treatment`, `placement-not-top-level` or `placement-edge-taken`. */
+export declare function imageTreatmentPatches(presentation: unknown, blockPath: string | string[], fields: ImageTreatments): JsonPatchOperation[];
+export declare function prepareImageTreatment(presentation: unknown, blockPath: string | string[], fields: ImageTreatments): { presentation: unknown; patches: JsonPatchOperation[]; changed: boolean; path: string; slideIndex: number };
+/** Set or remove treatment fields of one image block as one undoable transaction. */
+export declare function setImageTreatment(editor: EditorSession, blockPath: string | string[], fields: ImageTreatments, meta?: Record<string, unknown>): EditorChange & { changed: boolean; path: string; slideIndex: number };

package/dist/image-options.js

@@ -0,0 +1,195 @@
+// Image blocks (FA-22/FA-23, OPF 0.15): every content picture is an image block, and its framing lives on the block: fit and
+// focus, the treatments (shape, corner radius, border, opacity, recolor, overlay, aspect ratio) and placement (bleed to one slide
+// edge, the only thing that moves content aside). Each change is one validated JSON Patch applied as one undoable transaction;
+// the `prepare…` form returns the patch without touching a session. `design.imageFit` (a design option) is the deck or slide
+// default fit.
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
+import { checkedDocument, fail, same } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
+import { isAuthoringColorRef } from "./color-authoring.js";
+
+export const IMAGE_FITS = Object.freeze(["cover", "contain", "stretch"]);
+export const IMAGE_SHAPES = Object.freeze(["rectangle", "rounded", "circle", "hexagon"]);
+export const IMAGE_EDGES = Object.freeze(["left", "right", "top", "bottom"]);
+/** The fields an image block carries besides its `image`, in schema order. */
+export const IMAGE_TREATMENT_FIELDS = Object.freeze(["fit", "focus", "aspectRatio", "shape", "cornerRadius", "border", "opacity", "recolor", "overlay", "placement"]);
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const bad = (message, details) => fail("invalid-image-treatment", message, details);
+const fraction = (value, min = 0, max = 1) => typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+const colorRef = (value, what) => {
+  if (typeof value !== "string" || !value.trim() || !isAuthoringColorRef(value)) throw bad(`${what} must be a hex color such as #1F2937, a scheme color such as accent1 or surface, or var:<id>.`, { value });
+  return value.trim();
+};
+
+/** A focus point `{ x, y }`, each 0 (left/top) to 1 (right/bottom). */
+export function normalizeFocus(value) {
+  if (!isObject(value) || !fraction(Number(value.x)) || !fraction(Number(value.y))) throw bad("A focus point is { x, y }, each from 0 (left or top) to 1 (right or bottom).", { value });
+  return { x: Number(value.x), y: Number(value.y) };
+}
+
+/**
+ * An overlay `{ color, opacity, edge?, size? }`, shared by image backgrounds and image blocks: a scrim over the whole picture, or a
+ * band along one edge (`size` 0.05 to 1, default 0.3). `color` is any ColorRef, theme roles included.
+ */
+export function normalizeOverlay(value) {
+  if (!isObject(value)) throw bad("An overlay is { color, opacity }, with an optional edge and size for a band.", { value });
+  const out = { color: colorRef(value.color, "The overlay color"), opacity: Number(value.opacity) };
+  if (value.opacity === undefined || value.opacity === "" || !fraction(out.opacity)) throw bad("The overlay opacity is a number from 0 to 1.", { value });
+  if (value.edge !== undefined && value.edge !== null && value.edge !== "") {
+    if (!IMAGE_EDGES.includes(value.edge)) throw bad(`An overlay band runs along one edge: ${IMAGE_EDGES.join(", ")}.`, { value });
+    out.edge = value.edge;
+    if (value.size !== undefined && value.size !== null && value.size !== "") {
+      const size = Number(value.size);
+      if (!fraction(size, 0.05, 1)) throw bad("The overlay band size is a share of the picture from 0.05 to 1.", { value });
+      out.size = size;
+    }
+  }
+  return out;
+}
+
+/** A recolor: `"grayscale"` or a duotone `{ dark, light }` (ColorRefs), shared by image backgrounds and image blocks. */
+export function normalizeRecolor(value) {
+  if (value === "grayscale") return value;
+  if (isObject(value)) return { dark: colorRef(value.dark, "The duotone dark color"), light: colorRef(value.light, "The duotone light color") };
+  throw bad('Recolor is "grayscale" or a duotone { dark, light }.', { field: "recolor", value });
+}
+
+/** A placement `{ edge, size?, inset? }`: the block bleeds to that slide edge and takes `size` (0.1 to 0.9, default 0.5) of the slide. */
+export function normalizePlacement(value) {
+  if (!isObject(value) || !IMAGE_EDGES.includes(value.edge)) throw bad(`A placement names the slide edge the image bleeds to: ${IMAGE_EDGES.join(", ")}.`, { value });
+  const out = { edge: value.edge };
+  if (value.size !== undefined && value.size !== null && value.size !== "") {
+    const size = Number(value.size);
+    if (!fraction(size, 0.1, 0.9)) throw bad("The placed image's share of the slide is from 0.1 to 0.9.", { value });
+    out.size = size;
+  }
+  if (value.inset === true) out.inset = true;
+  return out;
+}
+
+function normalizeField(key, value) {
+  switch (key) {
+    case "fit":
+      if (!IMAGE_FITS.includes(value)) throw bad(`Image fit is one of ${IMAGE_FITS.join(", ")}.`, { field: key, value });
+      return value;
+    case "focus":
+      return normalizeFocus(value);
+    case "aspectRatio": {
+      const ratio = Number(value);
+      if (!(Number.isFinite(ratio) && ratio > 0 && ratio <= 10)) throw bad("The frame's aspect ratio is a width-to-height number above 0 and up to 10, for example 1.78.", { field: key, value });
+      return ratio;
+    }
+    case "shape":
+      if (!IMAGE_SHAPES.includes(value)) throw bad(`Image shape is one of ${IMAGE_SHAPES.join(", ")}.`, { field: key, value });
+      return value;
+    case "cornerRadius": {
+      const radius = Number(value);
+      if (!fraction(radius, 0, 0.5)) throw bad("The corner radius is a share of the frame's shorter side from 0 to 0.5.", { field: key, value });
+      return radius;
+    }
+    case "border": {
+      if (!isObject(value)) throw bad("A border is { color, width }.", { field: key, value });
+      const width = Number(value.width);
+      if (!fraction(width, 0, 64)) throw bad("The border width is from 0 to 64 reference pixels.", { field: key, value });
+      return { color: colorRef(value.color, "The border color"), width };
+    }
+    case "opacity": {
+      const opacity = Number(value);
+      if (!fraction(opacity)) throw bad("Image opacity is a number from 0 to 1.", { field: key, value });
+      return opacity;
+    }
+    case "recolor":
+      return normalizeRecolor(value);
+    case "overlay":
+      return normalizeOverlay(value);
+    case "placement":
+      return normalizePlacement(value);
+    default:
+      throw bad(`Unknown image treatment: ${key}. Use ${IMAGE_TREATMENT_FIELDS.join(", ")}.`, { field: key });
+  }
+}
+
+/** The payload that holds the picture at `blockPath` (a block, a region payload or the slide itself for `Slide.image`). */
+function imagePayload(presentation, blockPath) {
+  const parts = splitOpfPath(blockPath);
+  if (parts[0] === "slides" && parts.at(-1) === "image") parts.pop();
+  if (parts[0] !== "slides" || !presentation.slides?.[Number(parts[1])]) throw fail("not-an-image-block", "Choose an image block on a slide.", { path: blockPath });
+  // The slide's own `image` (Slide.image) takes no framing fields: the slide object is not an image block.
+  if (parts.length === 2) throw fail("not-an-image-block", "The slide's own image takes no fit, treatments or placement. Make it an image block (in blocks) to frame it.", { path: blockPath });
+  const payload = getValueAtPath(presentation, parts);
+  if (!isObject(payload) || payload.image === undefined) throw fail("not-an-image-block", "Choose an image block: these settings frame a picture.", { path: blockPath });
+  return { parts, payload };
+}
+
+// Only a top-level block (slides.N.blocks.I) may be placed (core's image-placement-invalid rule; the slide's own image cannot).
+const placeable = (parts) => parts.length === 4 && parts[2] === "blocks";
+
+/** Edges already taken by another placed top-level block of the slide. */
+function usedEdges(presentation, parts) {
+  const slide = presentation.slides[Number(parts[1])];
+  const self = parts.length === 4 ? Number(parts[3]) : -1;
+  const edges = new Set();
+  for (const [index, block] of (Array.isArray(slide?.blocks) ? slide.blocks : []).entries()) if (index !== self && isObject(block?.placement)) edges.add(block.placement.edge);
+  return edges;
+}
+
+/**
+ * The image block's framing as a form shows it: `{ path, fit, focus, aspectRatio, shape, cornerRadius, border, opacity, recolor,
+ * overlay, placement, placeable, usedEdges }`. Fields the block does not set are undefined (the effective fit is then
+ * `design.imageFit`, else cover).
+ */
+export function readImageTreatments(presentation, blockPath) {
+  const { parts, payload } = imagePayload(presentation, blockPath);
+  const out = { path: parts.join(".") };
+  for (const key of IMAGE_TREATMENT_FIELDS) out[key] = payload[key] === undefined ? undefined : structuredClone(payload[key]);
+  out.placeable = placeable(parts);
+  out.usedEdges = [...usedEdges(presentation, parts)];
+  return out;
+}
+
+/** The patches that set (a value) or remove (`null`) treatment fields of the image block at `blockPath`. */
+export function imageTreatmentPatches(presentation, blockPath, fields) {
+  if (!isObject(fields)) throw bad("Pass the image settings to change, for example { fit: \"contain\" }.", { fields });
+  const { parts, payload } = imagePayload(presentation, blockPath);
+  const patches = [];
+  for (const [key, raw] of Object.entries(fields)) {
+    if (raw === undefined) continue;
+    const at = opfPathToJsonPointer([...parts, key]);
+    if (raw === null) {
+      if (payload[key] !== undefined) patches.push({ op: "remove", path: at });
+      continue;
+    }
+    const value = normalizeField(key, raw);
+    if (key === "placement") {
+      if (!placeable(parts)) throw fail("placement-not-top-level", "Only an image block directly in the slide's blocks can bleed to an edge, not one inside a group or region or the slide's own image.", { path: blockPath });
+      if (usedEdges(presentation, parts).has(value.edge)) throw fail("placement-edge-taken", `Another image already bleeds to the ${value.edge} edge of this slide. Choose another edge or move that image first.`, { path: blockPath, edge: value.edge });
+    }
+    if (payload[key] === undefined) patches.push({ op: "add", path: at, value });
+    else if (!same(payload[key], value)) patches.push({ op: "replace", path: at, value });
+  }
+  return patches;
+}
+
+/** Compute the patch for `setImageTreatment` without touching a session: `{ presentation, patches, changed, path, slideIndex }`. */
+export function prepareImageTreatment(presentation, blockPath, fields) {
+  const before = checkFormat(presentation);
+  const patches = imageTreatmentPatches(presentation, blockPath, fields);
+  const next = checkedDocument(presentation, patches, before);
+  const parts = splitOpfPath(blockPath);
+  return { presentation: structuredClone(next), patches, changed: patches.length > 0, path: parts.join("."), slideIndex: Number(parts[1]) };
+}
+
+/**
+ * Set or remove (`null`) treatment fields of one image block as a single undoable transaction:
+ * `setImageTreatment(editor, "slides.1.blocks.0", { fit: "contain", placement: { edge: "right", size: 0.45 } })`.
+ */
+export function setImageTreatment(editor, blockPath, fields, meta = {}) {
+  if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+  const prepared = prepareImageTreatment(editor.presentation, blockPath, fields);
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(patches, { ...meta, source: meta.source ?? "image-treatment", path: prepared.path });
+  return { ...change, ...summary };
+}

package/dist/index.d.ts

@@ -1,8 +1,18 @@
 import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
 import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
-/** Reported when a font-scheme id matches no inline or bundled record; the default font scheme (`aptos`) is the base. */
-export interface FontSchemeDiagnostic { code: "unresolved-font-scheme"; path: string; message: string; id: string; fallback: string }
-export interface EditorDiagnosticOptions { onDiagnostic?: (diagnostic: FontSchemeDiagnostic) => void }
+import type { Catalog, Fonts, PresentationStats, SlideContextDiagnostic, StatsOptions, ValidationReport } from "@openpresentation/opf";
+export * from "./catalogs.js";
+/**
+ * What the editor adds to the options of `composeSlide` and `paginateSlide`: `fonts` is the renderer's fonts handle (`loadFonts()`), whose
+ * `textMeasurement` measures the text; `catalogs` are host catalogs for this call (merged after the session's registered ones);
+ * `onDiagnostic` hears every diagnostic of core's `resolveSlideContext` (`unresolved-reference`). Any other
+ * option overrides the resolved one.
+ */
+export interface EditorDiagnosticOptions {
+  fonts?: Fonts;
+  catalogs?: readonly Catalog[];
+  onDiagnostic?: (diagnostic: SlideContextDiagnostic) => void;
+}
 export declare const packageName = "@openpresentation/opf-editor";
 
 export declare const releaseLane: Readonly<{
@@ -29,16 +39,9 @@ export type JsonPatchOperation =
   | { op: "copy"; from: string; path: string }
   | { op: "test"; path: string; value: unknown };
 
-export interface OPFValidationSummary {
-  valid: boolean;
-  errors: unknown[];
-  warnings: unknown[];
-  result: unknown;
-}
-
 export interface EditorSnapshot {
-  document: unknown;
-  validation: OPFValidationSummary;
+  presentation: unknown;
+  validation: ValidationReport;
   canUndo: boolean;
   canRedo: boolean;
   undoDepth: number;
@@ -46,19 +49,20 @@ export interface EditorSnapshot {
 }
 
 export interface EditorChange {
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   inversePatches?: JsonPatchOperation[];
   redoPatches?: JsonPatchOperation[];
-  validation: OPFValidationSummary;
+  validation: ValidationReport;
 }
 
 export interface EditorEvent {
-  type: "patch" | "undo" | "redo" | "restore";
+  /** `catalogs`: the registered catalogs changed (`setCatalogs`); the document did not. */
+  type: "patch" | "undo" | "redo" | "restore" | "catalogs";
   patches: JsonPatchOperation[];
   inversePatches?: JsonPatchOperation[];
   redoPatches?: JsonPatchOperation[];
-  validation: OPFValidationSummary;
+  validation: ValidationReport;
   meta?: Record<string, unknown>;
   snapshot: EditorSnapshot;
 }
@@ -70,8 +74,13 @@ export interface EditorSession {
   paginateSlide(slideIndex: number, options?: PaginationOptions & EditorDiagnosticOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
   composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
-  readonly document: unknown;
-  readonly validation: OPFValidationSummary;
+  readonly presentation: unknown;
+  /** The `format` report of the document plus the catalog reference rules, checked against the registered catalogs. */
+  readonly validation: ValidationReport;
+  /** The host's registered catalogs, frozen; the first is the host default. */
+  readonly catalogs: readonly Catalog[];
+  /** Replace the registered catalogs: re-validates the document and emits one `catalogs` event. */
+  setCatalogs(catalogs: readonly Catalog[] | undefined, meta?: Record<string, unknown>): readonly Catalog[];
   readonly canUndo: boolean;
   readonly canRedo: boolean;
   snapshot(): EditorSnapshot;
@@ -84,26 +93,36 @@ export interface EditorSession {
   /** The undo and redo stacks as plain data (oldest entry first), for hosts that persist work. */
   exportHistory(): EditorHistory;
   /** Replace the document and, optionally, the history in one step (one `restore` event). A history that does not replay against the document throws `invalid-history` before anything changes. */
-  restoreState(state: { document: unknown; undo?: EditorHistoryEntry[]; redo?: EditorHistoryEntry[] }, meta?: Record<string, unknown>): EditorChange;
+  restoreState(state: { presentation: unknown; undo?: EditorHistoryEntry[]; redo?: EditorHistoryEntry[] }, meta?: Record<string, unknown>): EditorChange;
   undo(meta?: Record<string, unknown>): EditorChange | null;
   redo(meta?: Record<string, unknown>): EditorChange | null;
 }
 
 export interface CreateEditorSessionOptions {
-  validate?: (document: unknown) => unknown;
+  /** Refuse every edit whose result has an error finding (the default per edit is `meta.rejectInvalid`). */
   rejectInvalid?: boolean;
+  /** The host's catalogs (for example `[defaultCatalog]` from `@openpresentation/opf/catalog`): resolution, validation, pickers, embedding. */
+  catalogs?: readonly Catalog[];
 }
 
 export interface CatalogOption {
+  /** The reference to write: `id` or `name:id`. */
   id: string;
+  reference: string;
   label: string;
+  description?: string;
   record: Record<string, unknown>;
+  /** The catalog group the record resolves in (`custom`, `default` or a named group). */
+  group: string;
+  source?: string;
+  origin: "document" | "host";
 }
 
 export interface CatalogOptionsInput {
   presentation?: { catalogs?: Record<string, unknown> } | Record<string, unknown>;
-  catalogs?: Record<string, unknown>;
-  catalogSources?: Record<string, unknown>;
+  /** Host catalogs, merged after `editor`'s registered ones. */
+  catalogs?: readonly Catalog[];
+  editor?: EditorSession;
   [key: string]: unknown;
 }
 
@@ -160,20 +179,18 @@ export declare function opfPathToJsonPointer(path: string | string[]): string;
 
 export declare function jsonPointerToOpfPath(pointer: string): string;
 
-export declare function getValueAtPath(document: unknown, path: string | string[], fallback?: unknown): unknown;
-
-export declare function hasValueAtPath(document: unknown, path: string | string[]): boolean;
+export declare function getValueAtPath(presentation: unknown, path: string | string[], fallback?: unknown): unknown;
 
-export declare function createValuePatch(document: unknown, path: string | string[], value: unknown): JsonPatchOperation[];
+export declare function hasValueAtPath(presentation: unknown, path: string | string[]): boolean;
 
-export declare function applyJsonPatch(document: unknown, operations: JsonPatchOperation[]): unknown;
+export declare function createValuePatch(presentation: unknown, path: string | string[], value: unknown): JsonPatchOperation[];
 
-export declare function invertJsonPatch(document: unknown, operations: JsonPatchOperation[]): JsonPatchOperation[];
+export declare function applyJsonPatch(presentation: unknown, operations: JsonPatchOperation[]): unknown;
 
-export declare function validateOpfDocument(document: unknown, validator?: (document: unknown) => unknown): OPFValidationSummary;
+export declare function invertJsonPatch(presentation: unknown, operations: JsonPatchOperation[]): JsonPatchOperation[];
 
-/** Font families the slide resolves to (slide, deck, theme, then the shared default scheme). */
-export declare function resolveSlideFonts(document: unknown, slideIndex?: number, options?: EditorDiagnosticOptions): { heading?: string; body?: string; code?: string; [role: string]: string | undefined };
+/** Core's `stats` of the session's document: neutral facts (counts, words, notes coverage, images and alt text, speaking time), never severities. Reads the JSON only. */
+export declare function deckStats(editor: EditorSession, options?: StatsOptions): PresentationStats;
 
 export declare function createEditorSession(input: unknown, options?: CreateEditorSessionOptions): EditorSession;