@openpresentation/opf-editor 0.14.2 → 0.15.0

package/dist/export.js

@@ -8,6 +8,7 @@
 //   // result.download is { name, type, bytes }: one PDF, one PNG or SVG, or a ZIP of the slides.
 
 import { renderSvg } from "@openpresentation/opf-render/svg";
+import { mergeCatalogs, prepareSave } from "./catalogs.js";
 import { fontGate } from "./font-gate.js";
 import { createZip } from "./zip.js";
 
@@ -125,6 +126,8 @@ async function loadConverters(options) {
  * - `pdfMode`: "vector" (default: selectable text, vector shapes) or "raster" (each slide an image).
  * - `scale`: PNG pixel density, 1 to 4 (default 2); also the raster PDF's density.
  * - `renderOptions`: the render options the host draws with (`catalogs`, `date`, ...), the same as its preview.
+ * - `catalogs`: the host's registered catalogs (`Catalog[]`, merged with `renderOptions.catalogs`). The deck is embedded first (core's
+ *   `embed`), so what is drawn is the self-contained document a save writes.
  * - `fonts`: the renderer's fonts handle (`loadFonts()` from `@openpresentation/opf-render/fonts-browser`), the one the preview uses. Its
  *   `textMeasurement` lays the slides out, the faces the deck needs load through its `ensure` before anything is drawn, and its registry's
  *   faces are what gets embedded: the SVG carries the faces its slides draw, and the PDF embeds the registry's faces (script faces included).
@@ -136,7 +139,7 @@ async function loadConverters(options) {
  * Resolves `{ download, files, diagnostics, slides }`. Rejects with an error whose `code` is `export-aborted`,
  * `export-fonts-unlicensed`, `export-no-slides`, `export-unavailable`, `fonts-unavailable` or a renderer code.
  */
-export async function exportDeck(deck, options = {}) {
+export async function exportDeck(input, options = {}) {
   const format = EXPORT_FORMATS[options.format];
   if (!format) throw exportError("export-format", `Choose a format: ${Object.keys(EXPORT_FORMATS).join(", ")}.`);
   const { signal } = options;
@@ -144,12 +147,14 @@ export async function exportDeck(deck, options = {}) {
   const note = (diagnostic) => { diagnostics.push(diagnostic); options.onDiagnostic?.(diagnostic); };
   const progress = (stage, done, total, message) => options.onProgress?.({ stage, done, total, message });
   const check = () => { if (signal?.aborted) throw exportError("export-aborted", "The export was cancelled."); };
-  const indexes = slidesToExport(deck, options);
+  const indexes = slidesToExport(input, options);
   if (!indexes.length) throw exportError("export-no-slides", "There are no slides to export.");
   const selected = new Set(indexes);
   const keep = (diagnostic) => diagnostic.slide === undefined || selected.has(diagnostic.slide);
   const scale = Math.min(MAX_PNG_SCALE, Math.max(1, Number(options.scale) || 2));
-  const renderOptions = options.renderOptions ?? {};
+  const catalogs = mergeCatalogs(options.catalogs, options.renderOptions?.catalogs);
+  const renderOptions = { ...(options.renderOptions ?? {}), catalogs };
+  const deck = prepareSave(input, { catalogs }).document;
 
   check();
   const gate = fontGate(options.fonts);

package/dist/galleries.js

@@ -1,5 +1,4 @@
 import { assertOpf, unwrapOpf, MAX_OPF_BYTES } from "./transfer.js";
-import { catalogs } from "@openpresentation/opf";
 export function galleryUrl(input, base) {
   const url = new URL(input, base);
   if (
@@ -133,8 +132,6 @@ function fontRole(value) {
 // pair). `accent` is not part of the record schema and is dropped.
 function fontSchemeRecord(source, id) {
   const record = {
-    $schema: "https://openpresentation.org/schema/opf-font-scheme/v1",
-    id,
     name: source.name ?? id,
     major:
       typeof source.major === "string"
@@ -151,10 +148,25 @@ function fontSchemeRecord(source, id) {
   if (code) record.code = code;
   return record;
 }
-function attachDefinition(presentation, descriptor) {
+const isPlain = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+// Embedded records carry no `$schema`, `id` or `x-*` display metadata (OPF 0.15): the key is the id.
+function embeddedRecord(source) {
+  return Object.fromEntries(
+    Object.entries(structuredClone(source)).filter(
+      ([key]) => key !== "$schema" && key !== "id" && key !== "slug" && !key.startsWith("x-"),
+    ),
+  );
+}
+/**
+ * A gallery item that describes one catalog record (a layout, theme, colour or font scheme) is embedded in the
+ * document it previews: under `default` with the gallery's origin as its `source` when the document has no default
+ * group (or its default is that gallery), else under `custom` (an item with no gallery URL, or another default
+ * catalog). Records the document already embeds are kept.
+ */
+function attachDefinition(presentation, descriptor, gallerySource) {
   const source = descriptor.metadata?.source,
     category = descriptor.category ?? descriptor.metadata?.category;
-  if (!source) return;
+  if (!isPlain(source)) return;
   const kind = {
     layouts: "layouts",
     "font-schemes": "fontSchemes",
@@ -163,12 +175,13 @@ function attachDefinition(presentation, descriptor) {
   }[category];
   if (!kind) return;
   const id = source.id ?? source.slug;
-  if (!id) return;
-  if (
-    catalogs[kind]?.some((record) => record.id === id) ||
-    presentation.catalogs?.[kind]?.records?.some((record) => record.id === id)
-  )
-    return;
+  if (typeof id !== "string" || !/^[a-z][a-z0-9-]*$/.test(id)) return;
+  const groups = (presentation.catalogs ??= {});
+  if (groups.custom?.[kind]?.[id] !== undefined || groups.default?.[kind]?.[id] !== undefined) return;
+  const group = gallerySource && (groups.default === undefined || groups.default?.source === gallerySource) ? "default" : "custom";
+  if (group === "default") groups.default ??= { source: gallerySource };
+  else groups.custom ??= {};
+  groups[group][kind] ??= {};
   let record;
   if (kind === "layouts") {
     // A gallery layout item is a layout record: its placeholders, design hints and composition are the
@@ -176,33 +189,17 @@ function attachDefinition(presentation, descriptor) {
     const placeholders = Array.isArray(source.placeholders)
       ? source.placeholders
           .filter((placeholder) => typeof placeholder?.type === "string")
-          .map((placeholder) => ({ type: placeholder.type }))
+          .map((placeholder) => structuredClone(placeholder))
       : [{ type: "title" }, { type: "text" }];
-    const plain = (value) =>
-      value && typeof value === "object" && !Array.isArray(value)
-        ? structuredClone(value)
-        : undefined;
     record = {
-      $schema: "https://openpresentation.org/schema/opf-layout/v1",
-      id,
       name: source.label ?? source.name ?? id,
-      ...(plain(source.design) ? { design: plain(source.design) } : {}),
+      ...(isPlain(source.design) ? { design: structuredClone(source.design) } : {}),
       placeholders,
-      ...(plain(source.composition)
-        ? { composition: plain(source.composition) }
-        : {}),
+      ...(isPlain(source.composition) ? { composition: structuredClone(source.composition) } : {}),
     };
   } else if (kind === "fontSchemes") record = fontSchemeRecord(source, id);
-  else {
-    record = {
-      ...source,
-      $schema: `https://openpresentation.org/schema/opf-${kind === "themes" ? "theme" : "color-scheme"}/v1`,
-    };
-  }
-  presentation.catalogs ??= {};
-  presentation.catalogs[kind] ??= { records: [] };
-  presentation.catalogs[kind].records ??= [];
-  presentation.catalogs[kind].records.push(record);
+  else record = embeddedRecord(source);
+  groups[group][kind][id] = record;
 }
 export async function loadOpfGalleryItem(item, { gallery, ...options } = {}) {
   const base = gallery ?? options.base;
@@ -221,41 +218,9 @@ export async function loadOpfGalleryItem(item, { gallery, ...options } = {}) {
   const presentation = structuredClone(unwrapOpf(descriptor));
   if (!presentation?.slides)
     throw new Error("This gallery item does not include a presentation.");
-  attachDefinition(presentation, descriptor);
-  // PPTX.gallery's older descriptors omit inline layout records. Resolve only named
-  // layout references from its known, same-origin registry; no arbitrary dependency crawl.
-  if (
-    url &&
-    ["www.pptx.gallery", "pptx.gallery"].includes(new URL(url).hostname)
-  ) {
-    const missing = [
-      ...new Set(
-        presentation.slides
-          .map((slide) => slide.layout)
-          .filter(
-            (id) =>
-              typeof id === "string" &&
-              !catalogs.layouts.some((record) => record.id === id) &&
-              !presentation.catalogs?.layouts?.records?.some(
-                (record) => record.id === id,
-              ),
-          ),
-      ),
-    ];
-    if (missing.length > 12)
-      throw new Error(
-        "This item needs too many layout definitions. Supply self-contained OPF.",
-      );
-    for (const id of missing) {
-      if (!/^[a-z][a-z0-9-]*$/.test(id))
-        throw new Error("Unsupported layout reference.");
-      const dependency = await fetchGalleryJson(
-        `/registry/layouts/${id}.json`,
-        { ...options, base: url, origin: new URL(url).origin },
-      );
-      attachDefinition(presentation, dependency);
-    }
-  }
+  // A gallery publishes self-contained OPF (every record a document uses is embedded, FA-23); the item's own record is
+  // embedded too when the snippet omits it. Nothing else is fetched.
+  attachDefinition(presentation, descriptor, url ? new URL(url).origin : undefined);
   assertOpf(presentation);
   return presentation;
 }

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
@@ -159,7 +158,7 @@ export const isFullRect = (rect, bounds) => rect.x < 0.5 && rect.y < 0.5 && Math
 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." };
+  if (last !== "image") return { error: "This is not a picture." };
   const value = getValueAtPath(presentation, path);
   const pointer = opfPathToJsonPointer(segments);
   let form;

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,15 +1,16 @@
 import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
 import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
-import type { Fonts, PresentationStats, SlideContextDiagnostic, StatsOptions, ValidationReport } from "@openpresentation/opf";
+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 catalog records; `onDiagnostic` hears every `unresolved-font-scheme`,
- * `unresolved-layout`, `unresolved-theme` and `unresolved-color-scheme` diagnostic of core's `resolveSlideContext`. Any other option overrides
- * the resolved one.
+ * `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?: Record<string, readonly unknown[]>;
+  catalogs?: readonly Catalog[];
   onDiagnostic?: (diagnostic: SlideContextDiagnostic) => void;
 }
 export declare const packageName = "@openpresentation/opf-editor";
@@ -56,7 +57,8 @@ export interface EditorChange {
 }
 
 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[];
@@ -73,7 +75,12 @@ export interface EditorSession {
   composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   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;
@@ -94,18 +101,28 @@ export interface EditorSession {
 export interface CreateEditorSessionOptions {
   /** 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;
 }