@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/canvas.d.ts

@@ -1,55 +1,54 @@
 import type { EditorSession } from "./index.js";
 import type { RenderSvgOptions } from "@openpresentation/opf-render";
+import type { BrowserFontsHandle } from "@openpresentation/opf-render/fonts-browser";
 import type { SlideComposition } from "@openpresentation/opf/composition";
-/** Faces a document needs (script packages and vendored files) that are not loaded yet, and the way to load them. */
-export interface FontGate {
-  /** Synchronous. Empty means the document can render now. Never throws. `renderOptions` are the options the host renders with (`catalogs`, ...); the canvas passes its current ones. */
-  pending(document: unknown, renderOptions?: RenderSvgOptions): string[];
-  /** Load every pending face (vendored faces first, then script faces). Rejects with a `fonts-unavailable` error; never retries by itself. */
-  ensure(document: unknown, options?: { signal?: AbortSignal; renderOptions?: RenderSvgOptions }): Promise<void>;
-  /** `whenFontsReady` on this gate. */
-  run(document: unknown, handlers?: FontGateHandlers): Promise<void>;
-}
-export interface FontGateHandlers {
+import type { Catalog } from "@openpresentation/opf";
+/**
+ * The fonts the canvas, the export and `whenFontsReady` take: the renderer's handle from `loadFonts()` (`@openpresentation/opf-render/fonts-browser`).
+ * Only `textMeasurement` is required to measure; `pending` and `ensure` make the canvas load script and vendored faces before it draws.
+ */
+export type EditorFonts = Pick<BrowserFontsHandle, "textMeasurement"> & Partial<Pick<BrowserFontsHandle, "embeddedFonts" | "pending" | "ensure" | "registry">>;
+export interface FontsReadyHandlers {
   /** Return false once the document was superseded; the late result is then dropped. */
   isCurrent?: () => boolean;
   loading?: (pending: string[]) => void;
   ready?: () => void;
   failed?: (error: Error) => void;
-  /** The options the host renders with (`catalogs`, ...), passed to the gate. */
+  /** The options the host renders with (`catalogs`, ...), passed to the fonts handle. */
   renderOptions?: RenderSvgOptions;
 }
 export declare const FONTS_PENDING: "fonts-pending";
 export declare const FONTS_UNAVAILABLE: "fonts-unavailable";
-/** Wrap a browser font registry (`loadBrowserFontRegistry`). Registries without the lazy loaders gate nothing. */
 /**
- * `options.renderOptions` (an object, or a function called on every use) are the default render options passed to the registry
- * (`catalogs`, ...), under a call's own; the canvas passes its current `renderOptions` itself, so a gate needs none.
- */
-export declare function createFontGate(registry: object, options?: { renderOptions?: RenderSvgOptions | (() => RenderSvgOptions | undefined) }): FontGate;
-/**
- * Ensure fonts for a document, then run `ready` (synchronously when nothing is pending). The one
- * "ensure fonts, then render" helper: load failures and exceptions from `ready` go to `failed`.
+ * Ensure fonts for a presentation, then run `ready` (synchronously when nothing is pending). The one
+ * "ensure fonts, then render" helper: load failures and exceptions from `ready` go to `failed`. `fonts` is the renderer's fonts handle.
  */
 export declare function whenFontsReady(
-  gate: Pick<FontGate, "pending" | "ensure"> | undefined,
-  document: unknown,
-  handlers?: FontGateHandlers,
+  fonts: Pick<EditorFonts, "pending" | "ensure"> | undefined,
+  presentation: unknown,
+  handlers?: FontsReadyHandlers,
 ): Promise<void>;
 export interface CanvasEditorOptions {
   editor?: EditorSession;
-  document?: unknown;
+  presentation?: unknown;
+  /**
+   * The host's catalogs (core `Catalog[]`, for example `[defaultCatalog]` from `@openpresentation/opf/catalog`) for the session the
+   * canvas creates from `presentation`. With `editor`, register them on that session instead (`createEditorSession(doc, { catalogs })`);
+   * `renderOptions.catalogs` adds catalogs for drawing only, merged after the session's.
+   */
+  catalogs?: readonly Catalog[];
   slideIndex?: number;
   /** Show keyboard-accessible dividers for resizing composition tracks. */
   layoutEditing?: boolean;
   /** Render options. The canvas draws the document as authored (`variables: false`: a template's `{{tokens}}` stay visible, so inline edits never overwrite them); pass `variables` to draw resolved values instead. */
   renderOptions?: RenderSvgOptions;
   /**
-   * A font gate (`createFontGate(registry)`). With one, the canvas never renders a document whose faces are still
-   * loading: it shows "Loading fonts…", loads them and then renders, on every path (editor changes, undo/redo,
-   * imports, dimension switches, slide changes, drafts). Without one every document renders at once.
+   * The renderer's fonts handle (`loadFonts()` from `@openpresentation/opf-render/fonts-browser`). Its `textMeasurement` lays the slide out and
+   * its faces draw it. With its `pending` and `ensure` the canvas never renders a document whose faces are still loading: it shows
+   * "Loading fonts…", loads them and then renders, on every path (editor changes, undo/redo, imports, dimension switches, slide
+   * changes, drafts). Without a handle every document renders at once, laid out with core's portable text estimate.
    */
-  fonts?: Pick<FontGate, "pending" | "ensure">;
+  fonts?: EditorFonts;
   /**
    * How a pointer enters text editing. "click" (default): a single press on editable text starts editing with the caret at the
    * pressed character, and a press-drag selects a range. "dblclick": a click selects, a double-click enters with the caret at the
@@ -68,7 +67,7 @@ export interface CanvasEditorOptions {
     editor: EditorSession;
   }) => void;
   onDraft?: (draft: {
-    document: unknown;
+    presentation: unknown;
     path: string;
     value: unknown;
   }) => void;
@@ -78,7 +77,7 @@ export interface CanvasEditorOptions {
   /** Font loading progress of the canvas: `loading`, `error` (a face could not be loaded; the canvas offers a retry) and `ready`. */
   onFonts?: (event: { state: "loading"; pending: string[] } | { state: "error"; error: Error } | { state: "ready" }) => void;
   onRender?: (event: {
-    document: unknown;
+    presentation: unknown;
     slideIndex: number;
     svg: SVGSVGElement;
     geometry: SlideComposition;
@@ -94,7 +93,7 @@ export interface CanvasEditor {
   /** True while the crop layer is open. */
   readonly cropping: boolean;
   /**
-   * Open the crop layer for the picture at `path` (an image block, a slide's `image`, or `slides.N.design.slideImage`); `tool: "focus"`
+   * Open the crop layer for the picture at `path` (an image block or a slide's `image`); `tool: "focus"`
    * starts with the focal point. Apply writes one undoable change (see `@openpresentation/opf-editor/image-crop`). Resolves to whether it opened.
    */
   cropImage(path: string, options?: { tool?: "crop" | "focus" }): Promise<boolean>;
@@ -110,7 +109,7 @@ export interface CanvasEditor {
   editProperties(path: string): boolean;
   commit(): boolean;
   cancel(): void;
-  render(document?: unknown): void;
+  render(presentation?: unknown): void;
   setSlide(index: number): boolean;
   /**
    * Select the content at `path`, or the closest enclosing content the canvas can select (a list item selects its list),

package/dist/canvas.js

@@ -1,17 +1,19 @@
 import {
   createEditorSession,
+  mergeCatalogs,
   opfPathToJsonPointer,
   applyJsonPatch,
-  validateOpfDocument,
   getValueAtPath,
   splitOpfPath,
 } from "./index.js";
 import {
-  renderSvg,
+  renderSlideSvg,
   resolvePresentation,
 } from "@openpresentation/opf-render/svg";
 import {
   getEditableFields,
+  emptyLike,
+  fieldChoices,
   parseCanvasValue,
   createCanvasDraft,
 } from "./canvas-fields.js";
@@ -21,9 +23,10 @@ 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, fontsPendingError, whenFontsReady } from "./font-gate.js";
+import { FONTS_PENDING, fontGate, fontsPendingError, previewFonts, whenFontsReady } from "./font-gate.js";
+import { checkFormat, firstErrorMessage } from "./checks.js";
 export { getEditableFields } from "./canvas-fields.js";
-export { createFontGate, whenFontsReady, FONTS_PENDING, FONTS_UNAVAILABLE } from "./font-gate.js";
+export { whenFontsReady, FONTS_PENDING, FONTS_UNAVAILABLE } from "./font-gate.js";
 
 /** Allocated placeholder or internal-part bounds for the selection outline, not glyph ink. */
 export function allocatedSelectionBox(node, item) {
@@ -65,10 +68,14 @@ export function createCanvasEditor(container, options = {}) {
     win = doc.defaultView;
   const editor =
     options.editor ??
-    createEditorSession(options.document, { rejectInvalid: true });
-  // `options.fonts` is a font gate (createFontGate): a document whose faces are not loaded yet is never rendered. The canvas
-  // loads them first and shows "Loading fonts…" meanwhile; without a gate every document renders at once, as before.
-  const fonts = options.fonts;
+    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);
+  // 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) });
+  const drawOptions = (extra) => ({ ...resolveOptions(), fonts: previewFonts(handle), ...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.
@@ -120,7 +127,7 @@ export function createCanvasEditor(container, options = {}) {
     onTyping: beginEdit,
     onProperties(path) { if (commit()) openProperties(path, editor.get(path)); },
     validateChange(path, value) {
-      validateRender(createCanvasDraft(editor.document, path, value));
+      validateRender(createCanvasDraft(editor.presentation, path, value));
     },
     onChange(path) { clearNotice(); options.onCommit?.({path, editor}); }
   });
@@ -144,7 +151,7 @@ export function createCanvasEditor(container, options = {}) {
   const blockControls = createBlockControls(root, {
     editor, render: renderFor, beforeEdit: () => {if(!commit())return false;richToolbar.hide();return true;}, enabled: () => layoutHandles.enabled,
     isEditing: () => !!active || !!layoutHandles.editingPath, slideIndex: () => slideIndex,
-    validate: document => validateRender(document),
+    validate: presentation => validateRender(presentation),
     clearError: clearNotice, onError: report,
     onMove: path => choose(splitOpfPath(path).join(".")),
     onCommit: value => options.onCommit?.(value),
@@ -175,20 +182,20 @@ export function createCanvasEditor(container, options = {}) {
   const pendingMessage = "Loading fonts for this document…";
   // 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(document) {
-    const pending = fonts?.pending(document, renderOptions) ?? [];
+  function requireFonts(presentation) {
+    const pending = fonts?.pending(presentation, resolveOptions()) ?? [];
     if (!pending.length) return;
     notice.hidden = false;
     notice.textContent = pendingMessage;
-    fonts.ensure(document, { renderOptions }).then(
+    fonts.ensure(presentation, { renderOptions: resolveOptions() }).then(
       () => { if (!disposed && notice.textContent === pendingMessage) clearNotice(); },
       (error) => { if (!disposed) report(error); },
     );
     throw fontsPendingError(pending);
   }
-  function validateRender(document) {
-    requireFonts(document);
-    return renderSvg(document, {...renderOptions, slideIndex});
+  function validateRender(presentation) {
+    requireFonts(presentation);
+    return renderSlideSvg(presentation, slideIndex, drawOptions());
   }
   function fontsState(kind, detail) {
     fontsShown = true;
@@ -218,8 +225,8 @@ export function createCanvasEditor(container, options = {}) {
   function show(target) {
     if (disposed) return;
     const token = ++showToken;
-    return whenFontsReady(fonts, target ?? editor.document, {
-      renderOptions,
+    return whenFontsReady(fonts, target ?? editor.presentation, {
+      renderOptions: resolveOptions(),
       isCurrent: () => !disposed && token === showToken,
       loading: (pending) => fontsState("loading", pending),
       ready: () => {
@@ -234,27 +241,23 @@ 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(document) {
-    if (fonts?.pending(document ?? editor.document, renderOptions).length) show(document);
-    else render(document);
+  function renderFor(presentation) {
+    if (fonts?.pending(presentation ?? editor.presentation, resolveOptions()).length) show(presentation);
+    else render(presentation);
   }
-  function render(document = editor.document) {
+  function render(presentation = editor.presentation) {
     if (disposed) return;
-    requireFonts(document);
+    requireFonts(presentation);
     showToken++;
-    const slides = document.slides ?? [];
+    const slides = presentation.slides ?? [];
     slideIndex = Math.max(0, Math.min(slideIndex, slides.length - 1));
-    const svgText = renderSvg(document, {
-      ...renderOptions,
-      slideIndex,
-      trace: true,
-    });
+    const svgText = renderSlideSvg(presentation, slideIndex, drawOptions({ trace: true }));
     preview.innerHTML = svgText;
     const svg = preview.querySelector("svg");
     svg.setAttribute("role", "group");
     svg.setAttribute("aria-label", "Editable slide");
     svg.removeAttribute("aria-labelledby");
-    const geometry = resolvePresentation(document, renderOptions).slides[
+    const geometry = resolvePresentation(presentation, drawOptions()).slides[
       slideIndex
     ].geometry;
     const candidates = [...svg.querySelectorAll("[data-opf-path]")];
@@ -262,7 +265,7 @@ export function createCanvasEditor(container, options = {}) {
     for (const node of candidates) {
       const path = node.getAttribute("data-opf-path");
       const item = geometry.items.find((item) => item.path === path);
-      const value = getValueAtPath(document, path);
+      const value = getValueAtPath(presentation, path);
       if (
         seen.has(path) ||
         node.getAttribute('data-opf-generated') === 'true' ||
@@ -340,8 +343,8 @@ export function createCanvasEditor(container, options = {}) {
       });
       if (path === selectedPath) node.setAttribute("data-canvas-selected", "");
     }
-    layoutHandles.update(document, geometry);
-    blockControls.update(document, geometry);
+    layoutHandles.update(presentation, geometry);
+    blockControls.update(presentation, geometry);
     imageCropper?.update();
     if (active?.kind === "text") positionInput();
     if (active?.kind === "rich-text") active.rich?.update();
@@ -350,7 +353,7 @@ export function createCanvasEditor(container, options = {}) {
       options.onFonts?.({ state: "ready" });
     }
     options.onRender?.({
-      document,
+      presentation,
       slideIndex,
       svg,
       geometry,
@@ -366,11 +369,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();
@@ -392,7 +395,7 @@ export function createCanvasEditor(container, options = {}) {
           clearNotice();
           render(draft);
           options.onDraft?.({
-            document: draft,
+            presentation: draft,
             path: active.path,
             value: undefined,
           });
@@ -403,13 +406,13 @@ export function createCanvasEditor(container, options = {}) {
       }
       try {
         const value = active.kind === "rich-text" ? active.rich.value : parseCanvasValue(active.input.value, active.type, active.originalValue);
-        const draft = createCanvasDraft(editor.document, active.path, value);
+        const draft = createCanvasDraft(editor.presentation, active.path, value);
         if (deferDraft(draft)) return;
         clearNotice();
         active.valid = true;
         active.draft = draft;
         render(draft);
-        options.onDraft?.({ document: draft, path: active.path, value });
+        options.onDraft?.({ presentation: draft, path: active.path, value });
       } catch (error) {
         active.valid = false;
         report(error);
@@ -429,8 +432,8 @@ export function createCanvasEditor(container, options = {}) {
     const font = win.getComputedStyle(text),
       fontSize = parseFloat(font.fontSize),
       geometry = resolvePresentation(
-        active.draft ?? editor.document,
-        renderOptions,
+        active.draft ?? editor.presentation,
+        drawOptions(),
       ).slides[slideIndex].geometry;
     const item = geometry.items.find((item) => item.path === active.path);
     const metricLayout=geometry.items.find(item=>item.metricLayout?.parts.some(part=>part.path===active.path))?.metricLayout;
@@ -600,7 +603,7 @@ export function createCanvasEditor(container, options = {}) {
       // Only offer rich text where the canonical schema accepts TextRun[].
       if (typeof value === "string") {
         try {
-          createCanvasDraft(editor.document, path, [value]);
+          createCanvasDraft(editor.presentation, path, [value]);
           const format = doc.createElement("button");
           format.type = "button";
           format.textContent = "Format text";
@@ -683,11 +686,11 @@ export function createCanvasEditor(container, options = {}) {
     }));
   }
   function propertyDraft(edit) {
-    const draft = applyJsonPatch(editor.document, propertyPatches(edit)),
-      validation = validateOpfDocument(draft);
+    const draft = applyJsonPatch(editor.presentation, propertyPatches(edit)),
+      validation = checkFormat(draft);
     if (!validation.valid)
       throw new Error(
-        validation.errors[0]?.message ?? "This change is not valid OPF.",
+        firstErrorMessage(validation, "This change is not valid OPF."),
       );
     return draft;
   }
@@ -706,10 +709,20 @@ export function createCanvasEditor(container, options = {}) {
       label.style.cssText =
         "display:block;margin-top:10px;color:#756b85;font-size:11px";
       label.textContent = field.label;
+      const choices = field.type === "string" ? fieldChoices(field) : undefined;
       const input = doc.createElement(
-        field.type === "boolean" ? "input" : "textarea",
+        choices ? "select" : field.type === "boolean" ? "input" : "textarea",
       );
-      if (field.type === "boolean") {
+      if (choices) {
+        // A fixed set of values (a timeline event's status) is a menu, not free text.
+        for (const choice of choices) {
+          const option = doc.createElement("option");
+          option.value = choice;
+          option.textContent = choice;
+          input.append(option);
+        }
+        input.value = field.value;
+      } else if (field.type === "boolean") {
         input.type = "checkbox";
         input.checked = field.value;
       } else {
@@ -780,26 +793,9 @@ export function createCanvasEditor(container, options = {}) {
           if (!commit()) return;
           try {
             const values = editor.get(array.path);
-            const empty = (value, key = "") =>
-              Array.isArray(value)
-                ? value.map((child) => empty(child))
-                : value && typeof value === "object"
-                  ? Object.fromEntries(
-                      Object.entries(value).map(([key, child]) => [
-                        key,
-                        empty(child, key),
-                      ]),
-                    )
-                  : typeof value === "number"
-                    ? 0
-                    : typeof value === "boolean"
-                      ? false
-                      : ["type", "mode", "language"].includes(key)
-                        ? value
-                        : "";
             const next = remove
               ? values.slice(0, -1)
-              : [...values, empty(values.at(-1) ?? "")];
+              : [...values, emptyLike(values.at(-1) ?? "")];
             editor.set(array.path, next, {
               source: "canvas-collection",
               rejectInvalid: true,
@@ -876,7 +872,7 @@ export function createCanvasEditor(container, options = {}) {
         value = parseCanvasValue(edit.input.value, edit.type, edit.originalValue);
       else value = propertyDraft(edit);
       if (edit.kind === "text" || edit.kind === "rich-text")
-        validateRender(createCanvasDraft(editor.document, edit.path, value));
+        validateRender(createCanvasDraft(editor.presentation, edit.path, value));
       committing = true;
       if ((edit.kind === "text" || edit.kind === "rich-text") && JSON.stringify(value) !== edit.base)
         editor.set(edit.path, value, { source: "canvas", rejectInvalid: true });
@@ -928,7 +924,7 @@ export function createCanvasEditor(container, options = {}) {
     options.onCancel?.({ path });
   }
   function setSlide(index) {
-    if (!Number.isInteger(index) || !editor.document.slides?.[index])
+    if (!Number.isInteger(index) || !editor.presentation.slides?.[index])
       throw new RangeError("Slide index is out of range.");
     if (index === slideIndex) {
       if (!active) renderFor();
@@ -1027,7 +1023,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/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 };