@openpresentation/opf-editor 0.14.2 → 0.16.0

package/dist/design-options.js

@@ -41,19 +41,18 @@ function checkZoneField(key, value) {
   if (key === "dateFormat" && (typeof value !== "string" || !value.trim())) throw bad(`A date format uses tokens such as ${DATE_FORMAT_TOKENS.join(", ")}.`);
 }
 
-const SLIDE_IMAGE_POSITIONS = ["background", "top", "bottom", "left", "right"];
-
 const ENUMS = Object.freeze({
   titleAlignment: ["left", "center", "right"],
   contentAlignment: ["left", "center", "right"],
   contentDirection: ["horizontal", "vertical"],
   chartPrimary: ["none", "top", "bottom", "left", "right"],
   listBullet: ["character", "image"],
+  imageFit: ["cover", "contain", "stretch"],
 });
 
 /**
  * Descriptors for every design option, in the order a panel shows them. `type` is "enum", "boolean",
- * "font", "asset", "logo", "watermark", "slide-image" or "organization-logo"; `scopes` says whether
+ * "font", "asset", "logo", "watermark" or "organization-logo"; `scopes` says whether
  * the option applies to the deck, one slide, or both.
  */
 export const DESIGN_OPTIONS = Object.freeze([
@@ -63,11 +62,11 @@ export const DESIGN_OPTIONS = Object.freeze([
   { id: "chartPrimary", label: "Primary chart position", type: "enum", values: ENUMS.chartPrimary, scopes: ["deck", "slide"], path: "design.chartPrimary" },
   { id: "listBullet", label: "List bullets", type: "enum", values: ENUMS.listBullet, scopes: ["deck", "slide"], path: "design.listBullet" },
   { id: "contentBox", label: "Content box", type: "boolean", scopes: ["deck", "slide"], path: "design.contentBox" },
+  { id: "imageFit", label: "Image fit", type: "enum", values: ENUMS.imageFit, scopes: ["deck", "slide"], path: "design.imageFit" },
   { id: "accentFont", label: "Accent font", type: "font", scopes: ["deck", "slide"], path: "design.fontScheme.accent" },
   { id: "logo", label: "Logo", type: "logo", scopes: ["deck", "slide"], path: "design.logo" },
   { id: "organizationLogo", label: "Organization logo", type: "organization-logo", scopes: ["deck"], path: "organization.logo" },
   { id: "watermark", label: "Watermark", type: "watermark", scopes: ["deck", "slide"], path: "design.watermark" },
-  { id: "slideImage", label: "Slide image", type: "slide-image", scopes: ["deck", "slide"], path: "design.slideImage" },
 ]);
 const BY_ID = Object.fromEntries(DESIGN_OPTIONS.map((option) => [option.id, option]));
 
@@ -173,22 +172,6 @@ function mergedWatermark(existing, value) {
   return merged;
 }
 
-function mergedSlideImage(existing, value) {
-  if (value === null) return null;
-  if (typeof value === "string") return value;
-  if (!isObject(value)) throw fail("invalid-design-value", "A slide image is an image source or an object with a position.", { value });
-  const base = typeof existing === "string" ? { src: existing } : isObject(existing) ? (existing.position ? { ...existing } : { src: existing.src, ...(existing.alt ? { alt: existing.alt } : {}) }) : {};
-  const merged = { ...base };
-  for (const [key, entry] of Object.entries(value)) {
-    if (entry === null || entry === undefined) delete merged[key];
-    else merged[key] = entry;
-  }
-  if (merged.src === undefined) delete merged.src;
-  if (merged.position === undefined) merged.position = "background";
-  if (!SLIDE_IMAGE_POSITIONS.includes(merged.position)) throw fail("invalid-design-value", `Slide image position is one of ${SLIDE_IMAGE_POSITIONS.join(", ")}.`, { value });
-  return merged;
-}
-
 function fontSchemeWithAccent(presentation, base, family) {
   // The slide's own font scheme, else the deck's: an object form is kept with its overrides.
   const own = ownDesign(presentation, base).fontScheme;
@@ -223,8 +206,8 @@ function collapseLogo(set) {
 
 /**
  * Compute the patch that sets one design option, without touching any session. `value === null`
- * removes the option at that scope so it is inherited again. Object-valued options (`watermark`,
- * `slideImage`) merge the fields you pass into the existing object; a `null` field removes it.
+ * removes the option at that scope so it is inherited again. The object-valued `watermark` merges the
+ * fields you pass into the existing object; a `null` field removes it.
  * Options: `slideIndex` (one slide instead of the deck), `clearSlideOverrides` (deck scope: also
  * remove slide-level values that hide it) and `index` (organizationLogo with several
  * organizations).
@@ -261,12 +244,9 @@ export function prepareDesignOption(presentation, option, value, options = {}) {
     } else if (descriptor.type === "logo") {
       if (value !== null && typeof value !== "string" && !isObject(value)) throw fail("invalid-design-value", "A logo is an image source, an asset object or a set of logo variants.", { option });
       entries = { logo: value };
-    } else if (descriptor.type === "watermark") {
+    } else {
       const existing = ownDesign(presentation, base).watermark;
       entries = { watermark: mergedWatermark(existing, value) };
-    } else {
-      const existing = ownDesign(presentation, base).slideImage;
-      entries = { slideImage: mergedSlideImage(existing, value) };
     }
     keys = Object.keys(entries);
     patches = designPatches(presentation, base, entries);

package/dist/export.d.ts

@@ -42,10 +42,17 @@ export interface ExportOptions {
   includeHidden?: boolean;
   /** "vector" (default): selectable text and vector shapes; "raster": an image per slide. */
   pdfMode?: "vector" | "raster";
+  /**
+   * Raster PDF only: the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (opf-render 0.16), so the host passes it;
+   * without it a `pdfMode: "raster"` PDF rejects with the renderer's `converter-missing`. Vector PDF, PNG and SVG need no option.
+   */
+  pdfLib?: { PDFDocument: { create(options?: { updateMetadata?: boolean }): Promise<any> } };
   /** PNG pixel density (and the raster PDF's), 1 to 4; default 2. */
   scale?: number;
   /** The options the host draws its preview with (`catalogs`, `date`, ...); the fonts go in `fonts`. */
   renderOptions?: RenderSvgOptions;
+  /** Host catalogs (merged with `renderOptions.catalogs`). The deck is embedded first (core `embed`), like a saved file. */
+  catalogs?: readonly import("@openpresentation/opf").Catalog[];
   /** The renderer's fonts handle (`loadFonts()`): it measures the text, loads the faces the deck needs before anything is drawn, and its registry's faces are what gets embedded. */
   fonts?: EditorFonts;
   /** Faces to embed instead of the registry's. */
@@ -70,6 +77,6 @@ export interface ExportResult {
 }
 /**
  * Draw the deck with the renderer the preview uses and convert it. Rejects with an error whose `code` is `export-aborted`, `export-fonts-unlicensed` (the license rule left the PDF converter no face for some text), `export-no-slides`,
- * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code.
+ * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
  */
 export declare function exportDeck(deck: unknown, options: ExportOptions): Promise<ExportResult>;

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";
 
@@ -123,8 +124,13 @@ async function loadConverters(options) {
  * - `format`: "pdf", "png" or "svg" (required).
  * - `slides`: "current" (with `slideIndex`), "all" (default; hidden slides only with `includeHidden`) or an array of slide numbers.
  * - `pdfMode`: "vector" (default: selectable text, vector shapes) or "raster" (each slide an image).
+ * - `pdfLib`: for `pdfMode: "raster"` only, the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (RR-63, opf-render 0.16),
+ *   so a host that offers the raster PDF imports pdf-lib itself; without it a raster PDF rejects with the renderer's `converter-missing` (its `details.install` names the package).
+ *   Vector PDF, PNG and SVG need no option.
  * - `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).
@@ -134,9 +140,9 @@ async function loadConverters(options) {
  *   `export-fonts-unlicensed` (the converter's error is its `cause`).
  * - `signal`, `onProgress({ stage, done, total, message })`, `onDiagnostic(diagnostic)`.
  * 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-fonts-unlicensed`, `export-no-slides`, `export-unavailable`, `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
  */
-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 +150,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);
@@ -208,6 +216,8 @@ export async function exportDeck(deck, options = {}) {
         metadata,
         signal,
         fontData: pdfFontData(embeddedFonts),
+        // RR-63: the renderer's browser entry imports no pdf-lib; raster mode takes the module the host imported.
+        ...(options.pdfMode === "raster" && options.pdfLib ? { pdfLib: options.pdfLib } : {}),
         ...(options.fallbackFamily ? { defaultFontFamily: options.fallbackFamily } : {}),
         onDiagnostic: (diagnostic) => { const described = describeDiagnostic(diagnostic, "pdf"); if (keep(described)) note(described); },
         onProgress: ({ page, pages }) => progress("convert", page, pages, `Page ${page} of ${pages}`),

package/dist/find-replace.js

@@ -107,6 +107,7 @@ function payloadFields(fields, state, base, payload, prefix = "") {
     }));
   }
   if (isObject(payload.chart)) field(fields, state, at("chart", "alt"), payload.chart.alt, `${prefix}Chart alt text`, "alt");
+  if (isObject(payload.table)) field(fields, state, at("table", "alt"), payload.table.alt, `${prefix}Table alt text`, "alt");
   const table = payload.table;
   if (isObject(table)) {
     if (Array.isArray(table.columns)) table.columns.forEach((cell, c) => (isObject(cell) && !("value" in cell) ? field(fields, state, at("table", "columns", String(c), "name"), cell.name, `${prefix}Table header ${c + 1}`, "table") : cellFields(fields, state, at("table", "columns", String(c)), cell, `${prefix}Table header ${c + 1}`)));

package/dist/font-gate.js

@@ -13,17 +13,6 @@ export const FONTS_UNAVAILABLE = "fonts-unavailable";
 
 const GATE = Symbol("opf-editor.fontGate");
 
-/**
- * The fonts a preview draws with: the handle's text measurement and nothing else. A full handle also lists `embeddedFonts`, which
- * the renderer writes into every SVG it returns (an export needs that, so the SVG carries its faces); a preview inside a page
- * that already loaded the faces would repeat megabytes of base64 in every canvas, thumbnail and panel preview. The measurement
- * is read from the handle at each use, so faces it loads later still measure.
- */
-export function previewFonts(fonts) {
-  if (!fonts || typeof fonts !== "object") return undefined;
-  return { get textMeasurement() { return fonts.textMeasurement; } };
-}
-
 /**
  * The gate over a fonts handle: the two calls the canvas and the export need, with the editor's error contract.
  *

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 };
+}