@openpresentation/opf-editor 0.14.2 → 0.16.0

package/dist/canvas.js

@@ -1,5 +1,6 @@
 import {
   createEditorSession,
+  mergeCatalogs,
   opfPathToJsonPointer,
   applyJsonPatch,
   getValueAtPath,
@@ -22,7 +23,7 @@ import { createRichTextInput } from "./rich-text-input.js";
 import { textInputOffsetAtPoint } from "./text-pointer.js";
 import { createRichTextToolbar } from "./rich-text-toolbar.js";
 import { createImageCropper } from "./image-cropper.js";
-import { FONTS_PENDING, fontGate, fontsPendingError, previewFonts, whenFontsReady } from "./font-gate.js";
+import { FONTS_PENDING, fontGate, fontsPendingError, whenFontsReady } from "./font-gate.js";
 import { checkFormat, firstErrorMessage } from "./checks.js";
 export { getEditableFields } from "./canvas-fields.js";
 export { whenFontsReady, FONTS_PENDING, FONTS_UNAVAILABLE } from "./font-gate.js";
@@ -67,12 +68,16 @@ export function createCanvasEditor(container, options = {}) {
     win = doc.defaultView;
   const editor =
     options.editor ??
-    createEditorSession(options.presentation, { rejectInvalid: true });
+    createEditorSession(options.presentation, { rejectInvalid: true, catalogs: options.catalogs });
   // `options.fonts` is the renderer's fonts handle (`loadFonts()`): it measures the text and draws the faces. A document whose faces
   // are not loaded yet is never rendered: the canvas has the handle load them first and shows "Loading fonts…" meanwhile. Without a
   // handle every document renders at once, with core's portable text estimate.
   const handle = options.fonts, fonts = fontGate(handle);
-  const drawOptions = (extra) => ({ ...renderOptions, fonts: previewFonts(handle), ...extra });
+  // The renderer draws with the session's registered catalogs (plus any `renderOptions.catalogs`): the same list core resolves with.
+  const resolveOptions = () => ({ ...renderOptions, catalogs: mergeCatalogs(editor.catalogs, renderOptions.catalogs) });
+  // RR-61: the handle measures, and the canvas embeds no face: the browser handle already added its faces to the page, so
+  // `@font-face` data would repeat megabytes of base64 in every redraw. Exports keep the default and carry the faces they draw.
+  const drawOptions = (extra) => ({ ...resolveOptions(), fonts: handle, embedFonts: false, ...extra });
   let slideIndex = options.slideIndex ?? 0,
     // RR-32: the canvas edits the document as authored, so a template's {{tokens}} stay visible and an inline edit never
     // overwrites one with its resolved text. The Fill template panel previews the resolved deck. Pass `variables` to override.
@@ -180,11 +185,11 @@ export function createCanvasEditor(container, options = {}) {
   // A synchronous render or validation of a document whose faces are still loading fails with a clear "fonts-pending"
   // error and starts the load, so the next attempt succeeds. It never draws glyphs the registry cannot provide.
   function requireFonts(presentation) {
-    const pending = fonts?.pending(presentation, renderOptions) ?? [];
+    const pending = fonts?.pending(presentation, resolveOptions()) ?? [];
     if (!pending.length) return;
     notice.hidden = false;
     notice.textContent = pendingMessage;
-    fonts.ensure(presentation, { renderOptions }).then(
+    fonts.ensure(presentation, { renderOptions: resolveOptions() }).then(
       () => { if (!disposed && notice.textContent === pendingMessage) clearNotice(); },
       (error) => { if (!disposed) report(error); },
     );
@@ -223,7 +228,7 @@ export function createCanvasEditor(container, options = {}) {
     if (disposed) return;
     const token = ++showToken;
     return whenFontsReady(fonts, target ?? editor.presentation, {
-      renderOptions,
+      renderOptions: resolveOptions(),
       isCurrent: () => !disposed && token === showToken,
       loading: (pending) => fontsState("loading", pending),
       ready: () => {
@@ -239,7 +244,7 @@ export function createCanvasEditor(container, options = {}) {
   }
   // Renders now when the document's fonts are loaded (errors throw to the caller), otherwise after loading them.
   function renderFor(presentation) {
-    if (fonts?.pending(presentation ?? editor.presentation, renderOptions).length) show(presentation);
+    if (fonts?.pending(presentation ?? editor.presentation, resolveOptions()).length) show(presentation);
     else render(presentation);
   }
   function render(presentation = editor.presentation) {
@@ -253,6 +258,9 @@ export function createCanvasEditor(container, options = {}) {
     const svg = preview.querySelector("svg");
     svg.setAttribute("role", "group");
     svg.setAttribute("aria-label", "Editable slide");
+    // FA-30: the renderer labels its slide root a "slide" group named by the title; the canvas is named for editing instead, so it drops
+    // the roledescription rather than announce "Editable slide, slide".
+    svg.removeAttribute("aria-roledescription");
     svg.removeAttribute("aria-labelledby");
     const geometry = resolvePresentation(presentation, drawOptions()).slides[
       slideIndex
@@ -283,6 +291,13 @@ export function createCanvasEditor(container, options = {}) {
         continue;
       seen.add(path);
       node.setAttribute("data-canvas-target", "");
+      // FA-30: the renderer hides decorative drawing and a picture or chart with an empty alt (aria-hidden), and names a chart with
+      // alt as an image group. An editing target is focusable, so neither it nor a group around it may be hidden or presentational:
+      // an ancestor image group (the chart's alt) stays named but becomes a plain group so the targets inside it are reachable.
+      for (let up = node; up && up !== svg; up = up.parentNode) {
+        up.removeAttribute("aria-hidden");
+        if (up !== node && up.getAttribute("role") === "img") up.setAttribute("role", "group");
+      }
       node.setAttribute("role", "button");
       node.setAttribute("tabindex", "0");
       node.setAttribute(
@@ -366,11 +381,11 @@ export function createCanvasEditor(container, options = {}) {
   }
   // An in-progress edit whose text needs faces that are not loaded yet waits for them, then draws again.
   function deferDraft(draft) {
-    if (!fonts?.pending(draft, renderOptions).length) return false;
+    if (!fonts?.pending(draft, resolveOptions()).length) return false;
     active.valid = false;
     notice.hidden = false;
     notice.textContent = pendingMessage;
-    fonts.ensure(draft, { renderOptions }).then(
+    fonts.ensure(draft, { renderOptions: resolveOptions() }).then(
       () => {
         if (disposed) return;
         if (notice.textContent === pendingMessage) clearNotice();
@@ -1020,7 +1035,7 @@ export function createCanvasEditor(container, options = {}) {
     get layoutEditing() { return layoutHandles.enabled; },
     /** True while the crop layer is open. */
     get cropping() { return !!imageCropper?.isOpen; },
-    /** Open the crop layer for the picture at `path` (an image block, a slide's `image`, a slide image). `tool: "focus"` starts with the focal point. */
+    /** Open the crop layer for the picture at `path` (an image block or a slide's `image`). `tool: "focus"` starts with the focal point. */
     cropImage(path, cropOptions) {
       if (!imageCropper) return Promise.resolve(false);
       return imageCropper.open(path, cropOptions);

package/dist/catalog-control.js

@@ -0,0 +1,21 @@
+// Framework-neutral event handling: rejected edits restore the committed value
+// and reach the host callback and a bubbling opferror event.
+export function commitCatalogControl(node, onError, sync, commit) {
+  try {
+    commit();
+    node.setCustomValidity?.("");
+    node.removeAttribute?.("aria-invalid");
+    node.removeAttribute?.("data-opf-error");
+    return true;
+  } catch (error) {
+    sync();
+    node.setCustomValidity?.(error.message);
+    node.setAttribute?.("aria-invalid", "true");
+    node.setAttribute?.("data-opf-error", error.message);
+    onError?.(error);
+    const Event = node.ownerDocument?.defaultView?.CustomEvent;
+    if (Event) node.dispatchEvent?.(new Event("opferror", { detail: error, bubbles: true }));
+    node.reportValidity?.();
+    return false;
+  }
+}

package/dist/catalogs.d.ts

@@ -0,0 +1,48 @@
+import type { Catalog, CatalogKind, CatalogRecordChange, EmbeddedRecord, UnresolvedReferenceDiagnostic, ValidationReport } from "@openpresentation/opf";
+import type { CatalogOption, EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+/** One catalog list: the session's registration first, then each host list; the first catalog with a `source` wins. Throws `invalid-catalogs` for an entry without a source. */
+export declare function mergeCatalogs(...lists: (readonly Catalog[] | Catalog | undefined | null)[]): readonly Catalog[];
+/** The catalogs for one operation: `editor.catalogs`, then `options.catalogs`. */
+export declare function catalogsFor(editor: EditorSession | undefined, options?: { catalogs?: readonly Catalog[] }): readonly Catalog[];
+/** A record's picker label: its name, then its gallery label, then the id. */
+export declare function catalogRecordLabel(record: Record<string, unknown> | undefined, id: string): string;
+/** Core's `catalogRecords` as picker options: embedded records first, then registered ones; `id` is the reference to write. */
+export declare function listCatalogRecords(presentation: unknown, kind: CatalogKind, options?: { catalogs?: readonly Catalog[] }): CatalogOption[];
+
+export interface SavedDocument {
+  /** The self-contained document: every referenced record embedded once under its group, `x-*` stripped. */
+  document: unknown;
+  added: EmbeddedRecord[];
+  unresolved: UnresolvedReferenceDiagnostic[];
+}
+/** Core's `embed`: the document to save or hand on, which renders the same with no catalog registered. The input is not changed. */
+export declare function prepareSave(presentation: unknown, options?: { catalogs?: readonly Catalog[] }): SavedDocument;
+/** `prepareSave` of the session's document with its registered catalogs (and `options.catalogs`). The session is not changed. */
+export declare function saveDocument(editor: EditorSession, options?: { catalogs?: readonly Catalog[] }): SavedDocument;
+
+export interface CatalogUpdateCheck {
+  /** One per embedded record (under `default` or a named group) whose registered record differs. */
+  changes: CatalogRecordChange[];
+  /** RFC 6902; apply only after the author approves (`applyCatalogUpdate`). */
+  patch: JsonPatchOperation[];
+}
+/** The "Update from catalog" check (core's `updateFromCatalog`). Applies nothing. `refs` limits it to some references. */
+export declare function checkCatalogUpdates(presentation: unknown, options?: { catalogs?: readonly Catalog[]; refs?: readonly { kind: CatalogKind; reference: string }[] }): CatalogUpdateCheck;
+/** Apply the approved updates (`refs`) as ONE undoable step, recomputed against the session's current document. */
+export declare function applyCatalogUpdate(
+  editor: EditorSession,
+  options: { refs: readonly { kind: CatalogKind; reference: string }[]; catalogs?: readonly Catalog[]; meta?: Record<string, unknown> },
+): EditorChange & { changed: boolean; changes: CatalogRecordChange[] };
+
+export declare const REFERENCE_FINDING_CODES: readonly ["opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"];
+/** The reference and embedded-record findings (`REFERENCE_FINDING_CODES`) of a report. */
+export declare function referenceFindings(validation: ValidationReport | undefined): ValidationReport["findings"];
+
+export interface CatalogRecordRef { group: string; kind: CatalogKind; id: string }
+/** The record a `opf/catalog-record-not-in-source` finding path names (`/catalogs/<group>/<kind>/<id>`). */
+export declare function catalogRecordAt(path: string): CatalogRecordRef | undefined;
+/** Move a record embedded under `default` or a named group into `catalogs.custom`, rewriting the references that resolved to it. */
+export declare function prepareMoveToCustom(presentation: unknown, target: CatalogRecordRef, options?: { catalogs?: readonly Catalog[] }): { presentation: unknown; patches: JsonPatchOperation[]; changed: boolean; from: CatalogRecordRef; to: CatalogRecordRef };
+/** `prepareMoveToCustom` as one undoable step on the session. */
+export declare function moveToCustom(editor: EditorSession, target: CatalogRecordRef, options?: { catalogs?: readonly Catalog[]; meta?: Record<string, unknown> }): EditorChange & { changed: boolean; from: CatalogRecordRef; to: CatalogRecordRef };

package/dist/catalogs.js

@@ -0,0 +1,217 @@
+// Catalogs (FA-23, OPF 0.15). The editor never ships or imports catalog data: the host registers its catalogs (`Catalog[]`,
+// the shape core's `CatalogOptions.catalogs` takes, for example `defaultCatalog` from `@openpresentation/opf/catalog`), on the
+// session (`createEditorSession(doc, { catalogs })`) or per call. `mergeCatalogs` is the one function that turns those into the
+// one list the editor hands to core (resolution, validation, embedding, copying, updates), to the renderer and to the exporter.
+// Pickers list core's `catalogRecords` and write the reference it gives (`id` or `name:id`); saving and exporting embed every
+// referenced record with core's `embed`, so a saved document renders the same with no catalog registered.
+import { catalogKinds, catalogRecords, embed, moveToCustom as coreMoveToCustom, updateFromCatalog } from "@openpresentation/opf";
+import { OPFEditorError } from "./index.js";
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * One catalog list from any number of lists (or single catalogs): the session's registration first, then each host list, in order.
+ * A catalog is identified by its `source`; the first catalog with a source wins and later ones with the same source are dropped,
+ * so the host default (the first entry) never moves. Entries that are not catalogs throw `invalid-catalogs` (core's
+ * `OPFCatalogsOptionError` code).
+ */
+export function mergeCatalogs(...lists) {
+  const merged = [];
+  const sources = new Set();
+  for (const list of lists) {
+    if (list === undefined || list === null) continue;
+    for (const catalog of Array.isArray(list) ? list : [list]) {
+      if (catalog === undefined || catalog === null) continue;
+      if (!isObject(catalog) || typeof catalog.source !== "string" || catalog.source === "")
+        throw new OPFEditorError("invalid-catalogs", "A registered catalog is an object with a non-empty source, such as defaultCatalog from @openpresentation/opf/catalog.", { catalog });
+      if (sources.has(catalog.source)) continue;
+      sources.add(catalog.source);
+      merged.push(catalog);
+    }
+  }
+  return Object.freeze(merged);
+}
+
+/** The catalogs for one operation: the session's registered list (when `editor` is given), then `options.catalogs`. */
+export function catalogsFor(editor, options = {}) {
+  return mergeCatalogs(editor?.catalogs, options?.catalogs);
+}
+
+/** The label a picker shows for a record: its name, then its gallery label, then the id. */
+export function catalogRecordLabel(record, id) {
+  const gallery = isObject(record?.["x-gallery"]) ? record["x-gallery"] : {};
+  for (const value of [record?.name, record?.title, record?.label, gallery.label, gallery.name]) if (typeof value === "string" && value) return value;
+  return String(id);
+}
+
+/**
+ * Every record a picker can offer for `kind`, from core's `catalogRecords`: the document's embedded records first, then the
+ * registered catalogs'. Each entry is `{ id, reference, label, description, record, group, source, origin }`; `id` and
+ * `reference` are the reference to write (`id` or `name:id`). A reference is listed once.
+ */
+export function listCatalogRecords(presentation, kind, options = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of catalogRecords(presentation ?? {}, kind, { catalogs: mergeCatalogs(options.catalogs) })) {
+    if (seen.has(entry.reference)) continue;
+    seen.add(entry.reference);
+    const record = isObject(entry.record) ? entry.record : {};
+    out.push({
+      id: entry.reference,
+      reference: entry.reference,
+      label: catalogRecordLabel(record, entry.id),
+      ...(typeof record.description === "string" ? { description: record.description } : {}),
+      record,
+      group: entry.group,
+      ...(entry.source !== undefined ? { source: entry.source } : {}),
+      origin: entry.origin,
+    });
+  }
+  return out;
+}
+
+/**
+ * The document to save or hand on: core's `embed` adds every record the document references, once, under its catalog group
+ * (with the records those reference, `x-*` display metadata stripped), so it renders the same with no catalog registered.
+ * Returns `{ document, added, unresolved }`; the input is not changed.
+ */
+export function prepareSave(presentation, options = {}) {
+  const result = embed(presentation, { catalogs: mergeCatalogs(options.catalogs) });
+  return { document: result.document, added: result.added ?? [], unresolved: result.unresolved ?? [] };
+}
+
+/** `prepareSave` for the session's document, with the session's catalogs and `options.catalogs`. The session is not changed. */
+export function saveDocument(editor, options = {}) {
+  assertSession(editor);
+  return prepareSave(editor.presentation, { catalogs: catalogsFor(editor, options) });
+}
+
+/**
+ * The "Update from catalog" check: core's `updateFromCatalog` compares every record embedded under `default` or a named group
+ * (never `custom`) with the registered catalog's current record. Returns `{ changes, patch }`; nothing is applied. `refs` limits
+ * the check to some references (`[{ kind, reference }]`).
+ */
+export function checkCatalogUpdates(presentation, options = {}) {
+  const update = updateFromCatalog(presentation, mergeCatalogs(options.catalogs), options.refs);
+  return { changes: update.changes ?? [], patch: update.patch ?? [] };
+}
+
+/**
+ * Apply an update the author approved, as ONE undoable step. `options.refs` names the approved changes (`[{ kind, reference }]`);
+ * the update is recomputed for exactly those against the session's current document, so a stale review never applies. Returns
+ * the session change plus `changes` (what was applied) and `changed`.
+ */
+export function applyCatalogUpdate(editor, options = {}) {
+  assertSession(editor);
+  if (!Array.isArray(options.refs) || !options.refs.length) throw new OPFEditorError("no-approved-updates", "Choose the catalog updates to apply.");
+  const update = checkCatalogUpdates(editor.presentation, { catalogs: catalogsFor(editor, options), refs: options.refs });
+  if (!update.patch.length) return { changed: false, changes: [], presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(update.patch, { ...options.meta, source: options.meta?.source ?? "catalog-update", catalogRecordEdit: "in-place", catalogUpdate: update.changes.map(({ kind, reference }) => ({ kind, reference })) });
+  return { ...change, changed: true, changes: update.changes };
+}
+
+/**
+ * Core finding codes about catalog references and embedded records, which the editor surfaces next to its catalog controls:
+ * a reference that resolves nowhere, a prefix with no catalog group, and a record embedded under a catalog's group that the
+ * registered catalog does not publish (offer `moveToCustom`).
+ */
+export const REFERENCE_FINDING_CODES = Object.freeze(["opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"]);
+
+/** The reference and embedded-record findings (`REFERENCE_FINDING_CODES`) of a validation report (the session's `validation`). */
+export function referenceFindings(validation) {
+  return (validation?.findings ?? []).filter((finding) => REFERENCE_FINDING_CODES.includes(finding.ruleId ?? finding.code));
+}
+
+function assertSession(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function")
+    throw new OPFEditorError("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/**
+ * The record an `opf/catalog-record-not-in-source` finding names, from its path (`/catalogs/<group>/<kind>/<id>` or the dotted
+ * form): `{ group, kind, id }`, or undefined for a path that names no embedded record.
+ */
+export function catalogRecordAt(path) {
+  const parts = typeof path === "string" ? (path.startsWith("/") ? path.slice(1).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~")) : path.split(".")) : [];
+  if (parts.length !== 4 || parts[0] !== "catalogs" || !catalogKinds.includes(parts[2])) return undefined;
+  return { group: parts[1], kind: parts[2], id: parts[3] };
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Move a record embedded under `default` or a named group into `catalogs.custom` (the fix the `opf/catalog-record-not-in-source`
+ * finding offers, and the fork an edit makes) with core's `moveToCustom`: the document owns it from then on. Every reference that
+ * resolved to it is rewritten to the custom id (`options.id`, else its id, `<id>-2` and up on a conflict), and references written
+ * inside it keep naming what they named. Returns `{ presentation, patches, changed, from, to, references }`.
+ */
+export function prepareMoveToCustom(presentation, target, options = {}) {
+  const { group, kind, id } = target ?? {};
+  const groups = isObject(presentation?.catalogs) ? presentation.catalogs : {};
+  const record = isObject(groups[group]?.[kind]) ? groups[group][kind][id] : undefined;
+  if (group === "custom" || record === undefined) throw new OPFEditorError("not-a-catalog-record", "Choose a record embedded under catalogs.default or a named catalog group.", { group, kind, id });
+  // Core's moveToCustom is the one implementation: references follow, the record's own references keep naming what they named.
+  const reference = group === "default" ? id : `${group}:${id}`;
+  const moved = coreMoveToCustom(presentation, { kind, reference }, { catalogs: mergeCatalogs(options.catalogs), ...(options.id ? { id: options.id } : {}) });
+  const patches = [{ op: "test", path: "/catalogs", value: structuredClone(presentation.catalogs) }, ...moved.patch];
+  return { presentation: moved.document, patches, changed: true, from: { group, kind, id }, to: { group: "custom", kind, id: moved.to.id }, references: moved.references ?? [] };
+}
+
+/**
+ * `prepareMoveToCustom` on the session's document, as ONE undoable step (`meta.source: "catalog-move-to-custom"`). `options.id` names
+ * the custom record (default: the record's id, `<id>-2` on a conflict).
+ */
+export function moveToCustom(editor, target, options = {}) {
+  assertSession(editor);
+  const prepared = prepareMoveToCustom(editor.presentation, target, { catalogs: catalogsFor(editor, options), ...(options.id ? { id: options.id } : {}) });
+  const change = editor.applyPatch(prepared.patches, { ...options.meta, source: options.meta?.source ?? "catalog-move-to-custom", catalogRecordEdit: "in-place" });
+  return { ...change, changed: true, from: prepared.from, to: prepared.to };
+}
+
+/** The record kinds a user edits, which an edit forks into `catalogs.custom` when they live under a catalog's group. */
+export const FORKED_RECORD_KINDS = Object.freeze(["layouts", "themes", "colorSchemes", "fontSchemes"]);
+
+/**
+ * Records under `catalogs.default` or a named group whose content an edit from `before` to `after` changed (present in both, not
+ * equal). An added or removed record is not an edit. Returns `[{ group, kind, id }]`.
+ */
+export function editedCatalogRecords(before, after) {
+  const out = [];
+  const groupsBefore = isObject(before?.catalogs) ? before.catalogs : {};
+  const groupsAfter = isObject(after?.catalogs) ? after.catalogs : {};
+  for (const [group, value] of Object.entries(groupsAfter)) {
+    if (group === "custom" || !isObject(value) || !isObject(groupsBefore[group])) continue;
+    for (const kind of FORKED_RECORD_KINDS) {
+      const was = isObject(groupsBefore[group][kind]) ? groupsBefore[group][kind] : {};
+      const now = isObject(value[kind]) ? value[kind] : {};
+      for (const id of Object.keys(now)) if (Object.hasOwn(was, id) && !sameJson(was[id], now[id])) out.push({ group, kind, id });
+    }
+  }
+  return out;
+}
+
+/** The notice an editor shows after a fork: the record is the deck's own now and no longer receives catalog updates. */
+export function forkNotice(fork) {
+  const label = { layouts: "layout", themes: "theme", colorSchemes: "color scheme", fontSchemes: "font scheme" }[fork.from.kind] ?? fork.from.kind;
+  return `The ${label} ${fork.from.id} is now this presentation's own (${fork.to.id}); it no longer receives catalog updates.`;
+}
+
+/**
+ * Owner rule (FA-23): editing a record that lives under `catalogs.default` or a named group forks it into `catalogs.custom` instead
+ * of changing the catalog's record in place. Given the document before and after an edit, returns the document after the forks
+ * (each edited record moved to custom as `<id>-custom`, or `forkIds[<group>:<kind>:<id>]`, every reference rewritten, the
+ * original dropped) and `forks: [{ from, to }]`. Nothing to fork returns `after` and `[]`.
+ */
+export function forkEditedRecords(before, after, options = {}) {
+  let document = after;
+  const forks = [];
+  for (const target of editedCatalogRecords(before, after)) {
+    const custom = isObject(document.catalogs?.custom?.[target.kind]) ? document.catalogs.custom[target.kind] : {};
+    let id = options.forkIds?.[`${target.group}:${target.kind}:${target.id}`] ?? `${target.id}-custom`;
+    for (let n = 2; Object.hasOwn(custom, id); n += 1) id = `${target.id}-custom-${n}`;
+    const moved = prepareMoveToCustom(document, target, { catalogs: options.catalogs, id });
+    document = moved.presentation;
+    forks.push({ from: moved.from, to: moved.to });
+  }
+  return { document, forks };
+}

package/dist/checks.js

@@ -1,13 +1,15 @@
-// The editor's one use of core's checker. Every edit is validated with `validate(presentation, { only: ["format"] })`: the
-// schema and semantic OPF rules, with no layout built, so it is cheap enough to run on every keystroke and undo. The full
-// report (accessibility, layout, content) belongs to the Review panel, which runs it on idle (`./review.js`).
+// The editor's one use of core's checker. Every edit is validated with core's `validate` for the `format` category and the two
+// catalog rules (`opf/unresolved-reference`, `opf/undeclared-catalog`, `opf/catalog-record-not-in-source`): the schema and semantic OPF rules, with no
+// layout built, so it is cheap enough to run on every keystroke and undo. `catalogs` are the host's registered catalogs, so a
+// reference that resolves in one of them is not reported. The full report (accessibility, layout, content) belongs to the Review
+// panel, which runs it on idle (`./review.js`).
 import { validate } from "@openpresentation/opf";
 
-const FORMAT_ONLY = Object.freeze({ only: Object.freeze(["format"]) });
+const EDIT_CATEGORIES = Object.freeze(["format", "opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"]);
 
-/** Core's `ValidationReport` for the `format` category: `valid`, `findings`, `counts`, `schemaValid`. */
-export function checkFormat(presentation) {
-  return validate(presentation, FORMAT_ONLY);
+/** Core's `ValidationReport` for the `format` category and the catalog reference rules: `valid`, `findings`, `counts`, `schemaValid`. */
+export function checkFormat(presentation, options = {}) {
+  return validate(presentation, { only: EDIT_CATEGORIES, ...(options.catalogs?.length ? { catalogs: options.catalogs } : {}) });
 }
 
 /** The error-severity findings of a report: what makes it invalid. */

package/dist/content-actions.d.ts

@@ -72,9 +72,9 @@ export declare function ungroupBlock(editor: EditorSession, groupPath: string, m
 export declare function placeBlocksInRegions(editor: EditorSession, slideIndex: number, regions: string[], meta?: Record<string, unknown>): ContentActionChange;
 export declare function regionsAsBlocks(editor: EditorSession, slideIndex: number, meta?: Record<string, unknown>): ContentActionChange;
 export declare function moveSlideRegion(editor: EditorSession, slideIndex: number, from: string, to: string, options?: { swap?: boolean }, meta?: Record<string, unknown>): ContentActionChange;
-/** Move an image block into the slide's design as its slide image, background or watermark. */
+/** Move an image block into the slide's design as its background or watermark. */
 export declare function moveImageToDesign(editor: EditorSession, blockPath: string, target: ImageTarget, options?: PromoteImageOptions, meta?: Record<string, unknown>): ContentActionChange;
-/** Move a slide's own slide image, background image or watermark back into its content as an image block. */
+/** Move a slide's own background image or watermark back into its content as an image block. */
 export declare function moveImageToContent(editor: EditorSession, slideIndex: number, source: ImageTarget, options?: { index?: number; region?: string }, meta?: Record<string, unknown>): ContentActionChange;
 
 export declare function prepareSplitSlide(presentation: unknown, slideIndex: number, options?: { at?: number[]; each?: boolean; repeatHeadings?: boolean }): PreparedContentAction;

package/dist/content-actions.js

@@ -1,4 +1,4 @@
-// Content actions (RR-26): list levels, grouping, regions, images between content and design, and slide
+// Content actions (RR-26): list levels, grouping, regions, images between content and design (background or watermark), and slide
 // split and merge, as editor transactions. The pure transforms live in core (`@openpresentation/opf/convert`);
 // each action here finds its target in the document, calls the transform, turns the result into a guarded patch
 // (`test` of what was read, then `replace`, or per-slide `remove` and `add`), validates the document and, in the
@@ -143,12 +143,12 @@ export function prepareMoveRegion(presentation, slideIndex, from, to, options =
   slideParts(presentation, `slides.${slideIndex}`, "a slide");
   return slideAction(presentation, slideIndex, (slide) => moveRegion(slide, from, to, options), undefined, options.validate !== false);
 }
-/** Move the image block at `blockPath` into the slide's design as `slideImage`, `background` or `watermark`. */
+/** Move the image block at `blockPath` into the slide's design as its `background` or `watermark` (core's `promoteImage`). */
 export function prepareImageToDesign(presentation, blockPath, target, options = {}) {
   const { slideIndex, relative } = slideParts(presentation, blockPath, "an image block");
   return slideAction(presentation, slideIndex, (slide) => promoteImage(slide, asNumbers(relative), target, options), `slides.${slideIndex}`, options.validate !== false);
 }
-/** Move a slide's own `slideImage`, `background` image or `watermark` back into its content as an image block. */
+/** Move a slide's own `background` image or `watermark` back into its content as an image block (core's `demoteImage`). */
 export function prepareImageToContent(presentation, slideIndex, source, options = {}) {
   slideParts(presentation, `slides.${slideIndex}`, "a slide");
   return slideAction(presentation, slideIndex, (slide) => demoteImage(slide, source, options), undefined, options.validate !== false);

package/dist/content-controls.js

@@ -36,20 +36,20 @@ export const REGION_LAYOUTS = Object.freeze({
   4: [{ id: "grid", label: "Two by two", regions: ["top:left", "top:right", "bottom:left", "bottom:right"] }],
 });
 
-/** Where an image block can go in the slide's design. The value is `<target>` or `<target>:<position>`. */
+/**
+ * Where an image block can go in the slide's design (OPF 0.15): its background (a full-bleed photo behind the content) or its
+ * watermark. Bleeding an image to one edge beside the content is not a move: it is the block's `placement` (image-options.js).
+ */
 export const IMAGE_DESTINATIONS = Object.freeze([
-  { value: "slideImage:right", label: "Slide image, on the right", target: "slideImage", options: { position: "right" } },
-  { value: "slideImage:left", label: "Slide image, on the left", target: "slideImage", options: { position: "left" } },
-  { value: "slideImage:top", label: "Slide image, along the top", target: "slideImage", options: { position: "top" } },
-  { value: "slideImage:bottom", label: "Slide image, along the bottom", target: "slideImage", options: { position: "bottom" } },
-  { value: "slideImage:background", label: "Slide image, full slide behind the content", target: "slideImage", options: { position: "background" } },
-  { value: "background", label: "Slide background", target: "background", options: {} },
+  { value: "background", label: "Slide background, full slide behind the content", target: "background", options: {} },
   { value: "watermark", label: "Watermark", target: "watermark", options: {} },
 ]);
 
 const REGION_KEY = /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/;
 const regionKeysOfSlide = (slide) => Object.keys(slide).filter((key) => REGION_KEY.test(key));
-const DESIGN_IMAGE_LABELS = { slideImage: "slide image", background: "background image", watermark: "watermark" };
+const DESIGN_IMAGE_LABELS = { background: "background image", watermark: "watermark" };
+// An image block's own framing fields (FA-22) do not stop it being "a block that holds only an image".
+const IMAGE_BLOCK_FIELDS = new Set(["id", "extensions", "type", "fit", "focus", "aspectRatio", "shape", "cornerRadius", "border", "opacity", "recolor", "overlay", "placement"]);
 const messageOf = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
 const lossText = (prepared) => (prepared.loss.length ? `Not carried over: ${prepared.loss.join(", ")}.` : "Nothing is lost.");
 
@@ -321,6 +321,6 @@ export function createContentControls(ctx) {
 function isImageBlock(editor, blockPath) {
   const block = editor.get(blockPath);
   if (!block || typeof block !== "object" || Array.isArray(block)) return false;
-  const keys = Object.keys(block).filter((key) => key !== "id" && key !== "extensions" && key !== "type");
+  const keys = Object.keys(block).filter((key) => !IMAGE_BLOCK_FIELDS.has(key));
   return keys.length === 1 && keys[0] === "image";
 }

package/dist/design-controls.d.ts

@@ -1,7 +1,13 @@
+import type { Catalog } from "@openpresentation/opf";
 import type { EditorSession } from "./index.js";
+import type { SwitchVocabularies } from "./switches.js";
 
-export type DesignControlSection = "look" | "background" | "slide-image" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "table" | "slide-content";
-/** Every section, in panel order. `selection` and `table` follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the current slide. */
+export type DesignControlSection = "look" | "background" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "image" | "table" | "slide-content" | "catalog";
+/**
+ * Every section, in panel order. `selection`, `image` (the selected image block's fit, focus, treatments and placement) and `table`
+ * follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the
+ * current slide; `catalog` lists the catalog reference findings and runs the explicit "Update from catalog".
+ */
 export declare const DESIGN_CONTROL_SECTIONS: readonly DesignControlSection[];
 
 export interface DesignControlsOptions {
@@ -14,9 +20,10 @@ export interface DesignControlsOptions {
   sections?: readonly DesignControlSection[];
   /** Initial "Applies to" choice. */
   scope?: "deck" | "slide";
-  /** Caller-loaded catalog records by kind (layouts, font schemes, themes, ...) for options the bundled catalogs do not have. */
-  catalogs?: Record<string, unknown>;
-  catalogSources?: Record<string, unknown>;
+  /** Host catalogs for the pickers, merged after the session's registered ones. */
+  catalogs?: readonly Catalog[];
+  /** Display metadata for the engine vocabularies (languages, chart types, social platforms): `catalogDisplay` from `@openpresentation/opf/catalog`. */
+  vocabularies?: SwitchVocabularies;
   /** Called after every committed change (never for a refused one). */
   onChange?: (change: unknown) => void;
   /** Called after a content conversion or replacement with the path to keep selected (the block, or the inline payload field), since the old selection path may no longer exist. */