@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/index.js

@@ -1,38 +1,42 @@
 import { paginateSlide } from "@openpresentation/opf/pagination";
-import { PatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
+import { OPFPatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
 import { collectReservedPresentationIds } from "./presentation-ids.js";
-import { DEFAULT_FONT_SCHEME, resolveFontSchemeReference } from "./font-defaults.js";
-import { composeSlide, resolveCanvasDimensions, resolveFontFamilies } from "@openpresentation/opf/composition";
-import {
-  catalogKinds,
-  catalogs as bundledCatalogs,
-  validatePresentation
-} from "@openpresentation/opf";
-
-function resolveCompositionOptions(document, slideIndex, { onDiagnostic, ...options } = {}) {
-      const slide = document.slides?.[slideIndex];
-      if (!Number.isInteger(slideIndex) || !slide) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
-      const inline = document.catalogs?.layouts?.records ?? [];
-      const layout = options.layout ?? inline.find(record => record.id === slide.layout)
-        ?? bundledCatalogs.layouts.find(record => record.id === slide.layout);
-      const themeReference = slide.design?.theme ?? document.design?.theme ?? "minimal";
-      const themeId = typeof themeReference === "string" ? themeReference : themeReference.id;
-      const theme = document.catalogs?.themes?.records?.find(record => record.id === themeId)
-        ?? bundledCatalogs.themes.find(record => record.id === themeId);
-      const reference = slide.design?.fontScheme ?? document.design?.fontScheme ?? theme?.fontScheme ?? DEFAULT_FONT_SCHEME;
-      const fontPath = slide.design?.fontScheme !== undefined ? `slides.${slideIndex}.design.fontScheme` : document.design?.fontScheme !== undefined ? "design.fontScheme" : slide.design?.theme !== undefined ? `slides.${slideIndex}.design.theme` : "design.theme";
-      const { scheme: fontScheme, diagnostic } = resolveFontSchemeReference(reference, id => document.catalogs?.fontSchemes?.records?.find(record=>record.id===id) ?? bundledCatalogs.fontSchemes.find(record=>record.id===id), fontPath);
-      if (diagnostic) onDiagnostic?.(diagnostic);
-      return { ...resolveCanvasDimensions(slide.design?.dimensions ?? document.design?.dimensions ?? theme?.dimensions), fonts:resolveFontFamilies(fontScheme), contentAlignment:slide.design?.contentAlignment??document.design?.contentAlignment, titleAlignment:slide.design?.titleAlignment??document.design?.titleAlignment, contentBox:slide.design?.contentBox??document.design?.contentBox, presentation:document, ...options, layout, slideIndex };
-}
-
-/**
- * The font families a slide resolves to (`heading`, `body`, `code`), by the same slide, deck,
- * theme, default order that composition, pagination and export use. Hosts read this after a
- * font-scheme or theme switch to show the fonts the preview now uses.
- */
-export function resolveSlideFonts(document, slideIndex = 0, options = {}) {
-  return resolveCompositionOptions(document, slideIndex, options).fonts;
+import { composeSlide } from "@openpresentation/opf/composition";
+import { catalogKinds, resolveSlideContext, stats } from "@openpresentation/opf";
+import { checkFormat, errorFindings } from "./checks.js";
+import { forkEditedRecords, forkNotice, listCatalogRecords, mergeCatalogs } from "./catalogs.js";
+
+export {
+  REFERENCE_FINDING_CODES,
+  applyCatalogUpdate,
+  catalogRecordAt,
+  catalogRecordLabel,
+  catalogsFor,
+  checkCatalogUpdates,
+  editedCatalogRecords,
+  FORKED_RECORD_KINDS,
+  forkEditedRecords,
+  forkNotice,
+  listCatalogRecords,
+  mergeCatalogs,
+  moveToCustom,
+  prepareMoveToCustom,
+  prepareSave,
+  referenceFindings,
+  saveDocument,
+} from "./catalogs.js";
+
+// The options `composeSlide` and `paginateSlide` take for one slide of the open deck. Core's `resolveSlideContext` resolves the
+// slide's canvas, layout, theme, colour scheme and font families the one way every engine does (slide design, deck design,
+// theme, engine default), with the session's registered catalogs, so the editor measures and composes what the renderer draws
+// and the exporter writes. `options.fonts` is the renderer's fonts handle (its `textMeasurement` measures); `options.catalogs`
+// adds catalogs for this call; `options.onDiagnostic` hears each diagnostic (`unresolved-reference`);
+// any other option overrides the resolved one (`layout`, ...).
+function slideContext(presentation, slideIndex, catalogs, { fonts, catalogs: _extra, onDiagnostic, ...overrides } = {}) {
+  if (!Number.isInteger(slideIndex) || !presentation.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
+  const { options, diagnostics } = resolveSlideContext(presentation, slideIndex, { fonts, catalogs });
+  for (const diagnostic of diagnostics) onDiagnostic?.(diagnostic);
+  return { ...options, ...overrides };
 }
 
 export const packageName = "@openpresentation/opf-editor";
@@ -85,20 +89,20 @@ export function jsonPointerToOpfPath(pointer) {
   return parseJsonPointer(pointer).join(".");
 }
 
-export function getValueAtPath(document, path, fallback) {
-  const found = readPointer(document, splitOpfPath(path));
+export function getValueAtPath(presentation, path, fallback) {
+  const found = readPointer(presentation, splitOpfPath(path));
   return found.found ? found.value : fallback;
 }
 
-export function hasValueAtPath(document, path) {
-  return readPointer(document, splitOpfPath(path)).found;
+export function hasValueAtPath(presentation, path) {
+  return readPointer(presentation, splitOpfPath(path)).found;
 }
 
-export function createValuePatch(document, path, value) {
+export function createValuePatch(presentation, path, value) {
   const pointer = normalizePatchPath(path);
   return [
     {
-      op: hasValueAtPath(document, pointer) ? "replace" : "add",
+      op: hasValueAtPath(presentation, pointer) ? "replace" : "add",
       path: pointer,
       value: clone(value)
     }
@@ -108,40 +112,43 @@ export function createValuePatch(document, path, value) {
 // Patch semantics (RFC 6902, pointers, inverse patches) live in core's
 // "@openpresentation/opf/patch"; the editor adds its path spellings (dotted OPF
 // paths), its error type and its clone policy on top.
-export function applyJsonPatch(document, operations) {
+export function applyJsonPatch(presentation, operations) {
   assertPatchOperations(operations);
   const patch = operations.map(normalizeOperation);
   try {
-    return applyCorePatch(document, patch);
+    return applyCorePatch(presentation, patch);
   } catch (error) {
     throw editorPatchError(error);
   }
 }
 
-export function invertJsonPatch(document, operations) {
+export function invertJsonPatch(presentation, operations) {
   assertPatchOperations(operations);
   const patch = operations.map(normalizeOperation);
   try {
-    return invertPatch(document, patch);
+    return invertPatch(presentation, patch);
   } catch (error) {
     throw editorPatchError(error);
   }
 }
 
-export function validateOpfDocument(document, validator = validatePresentation) {
-  const result = validator(document);
-  const valid = Boolean(result?.valid);
-  return {
-    valid,
-    errors: Array.isArray(result?.errors) ? result.errors : [],
-    warnings: Array.isArray(result?.warnings) ? result.warnings : [],
-    result
-  };
+/**
+ * Facts about the open presentation, from core's `stats`: slide, layout and section counts, payload kinds, words and notes coverage,
+ * images and their alt text, charts, tables, citations, fonts and an estimated speaking time (`options`: `perSlide`, `values`,
+ * `wordsPerMinute`). They are facts, never findings: no severities and no judgment about whether a number is too high, so a deck-info
+ * view can show them next to the Review panel. It reads the JSON only, so it also works on a document that fails validation.
+ */
+export function deckStats(editor, options) {
+  assertEditorSession(editor);
+  return stats(editor.presentation, options);
 }
 
 export function createEditorSession(input, options = {}) {
-  let document = parseInput(input);
-  let validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+  let presentation = parseInput(input);
+  // The host's registered catalogs (FA-23): one list, handed to every core call, the renderer and the exporter.
+  let catalogs = mergeCatalogs(options.catalogs);
+  const check = (document) => checkFormat(document, { catalogs });
+  let validation = check(presentation);
   const undoStack = [];
   const redoStack = [];
   const listeners = new Set();
@@ -156,27 +163,44 @@ export function createEditorSession(input, options = {}) {
 
   function commitPatch(operations, meta = {}) {
     assertPatchOperations(operations);
-    const patches = operations.map(normalizeOperation);
-    const before = document;
+    let patches = operations.map(normalizeOperation);
+    const before = presentation;
     let next, inversePatches;
     try {
-      ({ document: next, inverse: inversePatches } = applyPatchWithInverse(before, patches));
+      ({ presentation: next, inverse: inversePatches } = applyPatchWithInverse(before, patches));
     } catch (error) {
       throw editorPatchError(error);
     }
-    const nextValidation = validateOpfDocument(next, options.validate ?? validatePresentation);
+    // Owner rule (FA-23): an edit of a record under catalogs.default or a named group forks it into catalogs.custom (every reference
+    // follows, the original is dropped), in this same undo step. Catalog updates and moves change catalog records on purpose.
+    let forks = [];
+    if (meta.catalogRecordEdit !== "in-place") {
+      const forked = forkEditedRecords(before, next, { catalogs, forkIds: meta.forkIds });
+      if (forked.forks.length) {
+        forks = forked.forks;
+        for (const key of new Set([...Object.keys(next), ...Object.keys(forked.document)]))
+          if (!jsonEqual(next[key], forked.document[key])) patches = [...patches, forked.document[key] === undefined ? { op: "remove", path: formatPointer([key]) } : { op: Object.hasOwn(next, key) ? "replace" : "add", path: formatPointer([key]), value: clone(forked.document[key]) }];
+        try {
+          ({ presentation: next, inverse: inversePatches } = applyPatchWithInverse(before, patches));
+        } catch (error) {
+          throw editorPatchError(error);
+        }
+        meta = { ...meta, forked: forks, notice: forks.map(forkNotice).join(" ") };
+      }
+    }
+    const nextValidation = check(next);
 
     if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
       throw new OPFEditorError("invalid-opf-edit", "OPF edit produced an invalid document.", {
-        issues: nextValidation.errors,
+        issues: errorFindings(nextValidation),
         patches
       });
     }
 
     if (patches.every(patch => patch.op === "test")) return {
-      document: clone(document), patches: clonePatchOperations(patches), inversePatches: [], validation: nextValidation
+      presentation: clone(presentation), patches: clonePatchOperations(patches), inversePatches: [], validation: nextValidation
     };
-    document = next;
+    presentation = next;
     validation = nextValidation;
     undoStack.push({ patches: clonePatchOperations(patches), inversePatches, meta });
     redoStack.length = 0;
@@ -189,20 +213,35 @@ export function createEditorSession(input, options = {}) {
     });
 
     return {
-      document: clone(document),
+      presentation: clone(presentation),
       patches: clonePatchOperations(patches),
       inversePatches: clonePatchOperations(inversePatches),
-      validation
+      validation,
+      ...(forks.length ? { forked: forks, notice: meta.notice } : {})
     };
   }
 
   const editor = {
-    get document() {
-      return clone(document);
+    get presentation() {
+      return clone(presentation);
     },
     get validation() {
       return validation;
     },
+    /** The catalogs the host registered (`Catalog[]`, frozen): the first is the host default. */
+    get catalogs() {
+      return catalogs;
+    },
+    /**
+     * Replace the registered catalogs (for example after the host loads a company catalog). The document is not changed; it is
+     * re-validated against the new list (reference findings depend on it) and one `catalogs` event tells every view to redraw.
+     */
+    setCatalogs(next, meta = {}) {
+      catalogs = mergeCatalogs(next);
+      validation = check(presentation);
+      emit({ type: "catalogs", patches: [], validation, meta });
+      return catalogs;
+    },
     get canUndo() {
       return undoStack.length > 0;
     },
@@ -211,7 +250,7 @@ export function createEditorSession(input, options = {}) {
     },
     snapshot() {
       return snapshotCache ??= freezeSnapshot({
-        document: clone(document),
+        presentation: clone(presentation),
         validation: clone(validation),
         canUndo: undoStack.length > 0,
         canRedo: redoStack.length > 0,
@@ -227,33 +266,37 @@ export function createEditorSession(input, options = {}) {
       return () => listeners.delete(listener);
     },
     get(path, fallback) {
-      return getValueAtPath(document, path, fallback);
+      return getValueAtPath(presentation, path, fallback);
     },
     set(path, value, meta = {}) {
-      return commitPatch(createValuePatch(document, path, value), {
+      return commitPatch(createValuePatch(presentation, path, value), {
         ...meta,
         path: normalizePatchPath(path)
       });
     },
     composeSlide(slideIndex, options = {}) {
-      return composeSlide(document.slides?.[slideIndex], resolveCompositionOptions(document, slideIndex, options));
+      return composeSlide(presentation.slides?.[slideIndex], slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options));
     },
     paginateSlide(slideIndex, options = {}, meta = {}) {
-      const resolved = resolveCompositionOptions(document, slideIndex, options);
-      const pagination = paginateSlide(document.slides[slideIndex], {
+      const list = mergeCatalogs(catalogs, options.catalogs);
+      // Core pagination reads the measurement from `fonts`, so the resolved context hands it over that way.
+      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options);
+      const pagination = paginateSlide(presentation.slides[slideIndex], {
         ...resolved,
-        reservedIds: collectReservedPresentationIds(document),
+        catalogs: list,
+        fonts: options.fonts ?? (textMeasurement ? { textMeasurement } : undefined),
+        reservedIds: collectReservedPresentationIds(presentation),
       });
       // Pagination can persist a readability policy without adding a page. Commit
       // that change too, so preview/export use the same minimum that was evaluated.
-      if (pagination.slides.length === 1 && jsonEqual(pagination.slides[0], document.slides[slideIndex])) return { change: null, pagination };
-      const slides = [...document.slides];
+      if (pagination.slides.length === 1 && jsonEqual(pagination.slides[0], presentation.slides[slideIndex])) return { change: null, pagination };
+      const slides = [...presentation.slides];
       slides.splice(slideIndex, 1, ...pagination.slides);
       const change = editor.set('slides', slides, { ...meta, rejectInvalid: true, pagination: pagination.pages });
       return { change, pagination };
     },
     setComposition(slideIndex, composition, meta = {}) {
-      if (!Number.isInteger(slideIndex) || !document.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
+      if (!Number.isInteger(slideIndex) || !presentation.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
       return editor.set(`slides.${slideIndex}.composition`, composition, { ...meta, rejectInvalid: true });
     },
     setGroupComposition(path, composition, meta = {}) {
@@ -268,7 +311,7 @@ export function createEditorSession(input, options = {}) {
     applyPatch: commitPatch,
     /**
      * The undo and redo stacks as plain data (oldest entry first): `{ undo: [{ patches, inversePatches, meta }], redo: [...] }`.
-     * Together with `document` this is everything `restoreState` needs to bring a session back, for hosts that persist work.
+     * Together with `presentation` this is everything `restoreState` needs to bring a session back, for hosts that persist work.
      */
     exportHistory() {
       const entry = (item) => ({ patches: clonePatchOperations(item.patches), inversePatches: clonePatchOperations(item.inversePatches), meta: clone(item.meta ?? {}) });
@@ -281,11 +324,11 @@ export function createEditorSession(input, options = {}) {
      * before anything changes, so a stale or damaged copy never corrupts the session. Emits one `restore` event.
      */
     restoreState(state, meta = {}) {
-      if (!state || typeof state !== "object") throw new OPFEditorError("invalid-state", "restoreState needs { document, undo?, redo? }.");
-      const next = parseInput(state.document);
-      const nextValidation = validateOpfDocument(next, options.validate ?? validatePresentation);
+      if (!state || typeof state !== "object") throw new OPFEditorError("invalid-state", "restoreState needs { presentation, undo?, redo? }.");
+      const next = parseInput(state.presentation);
+      const nextValidation = check(next);
       if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
-        throw new OPFEditorError("invalid-opf-edit", "The restored document is not valid OPF.", { issues: nextValidation.errors });
+        throw new OPFEditorError("invalid-opf-edit", "The restored document is not valid OPF.", { issues: errorFindings(nextValidation) });
       }
       const undo = state.undo ?? [], redo = state.redo ?? [];
       const wellFormed = (entries) => Array.isArray(entries) && entries.every((item) => item && Array.isArray(item.patches) && Array.isArray(item.inversePatches));
@@ -307,20 +350,20 @@ export function createEditorSession(input, options = {}) {
         throw new OPFEditorError("invalid-history", "The undo history does not belong to this document.", { cause: error instanceof Error ? error.message : String(error) });
       }
       const entry = (item) => ({ patches: item.patches.map(normalizeOperation), inversePatches: item.inversePatches.map(normalizeOperation), meta: clone(item.meta ?? {}) });
-      document = next;
+      presentation = next;
       validation = nextValidation;
       undoStack.length = 0;
       redoStack.length = 0;
       undoStack.push(...undo.map(entry));
       redoStack.push(...redo.map(entry));
       emit({ type: "restore", patches: [], validation, meta });
-      return { document: clone(document), patches: [], validation };
+      return { presentation: clone(presentation), patches: [], validation };
     },
     undo(meta = {}) {
       const entry = undoStack.pop();
       if (!entry) return null;
-      document = applyJsonPatch(document, entry.inversePatches);
-      validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+      presentation = applyJsonPatch(presentation, entry.inversePatches);
+      validation = check(presentation);
       redoStack.push(entry);
       emit({
         type: "undo",
@@ -330,7 +373,7 @@ export function createEditorSession(input, options = {}) {
         meta
       });
       return {
-        document: clone(document),
+        presentation: clone(presentation),
         patches: clonePatchOperations(entry.inversePatches),
         redoPatches: clonePatchOperations(entry.patches),
         validation
@@ -339,8 +382,8 @@ export function createEditorSession(input, options = {}) {
     redo(meta = {}) {
       const entry = redoStack.pop();
       if (!entry) return null;
-      document = applyJsonPatch(document, entry.patches);
-      validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+      presentation = applyJsonPatch(presentation, entry.patches);
+      validation = check(presentation);
       undoStack.push(entry);
       emit({
         type: "redo",
@@ -350,7 +393,7 @@ export function createEditorSession(input, options = {}) {
         meta
       });
       return {
-        document: clone(document),
+        presentation: clone(presentation),
         patches: clonePatchOperations(entry.patches),
         inversePatches: clonePatchOperations(entry.inversePatches),
         validation
@@ -431,29 +474,29 @@ export function createSvgTraceBinding(root, editor, options = {}) {
   };
 }
 
+/**
+ * The records a catalog control can offer for `catalogKind`, from core's `catalogRecords`: the document's embedded records,
+ * then the registered catalogs' (`options.catalogs`, merged with `options.editor`'s). Each is the record itself.
+ */
 export function getCatalogRecords(catalogKind, options = {}) {
-  assertCatalogKind(catalogKind);
-  const presentationCatalog = options.presentation?.catalogs?.[catalogKind];
-  const explicitCatalog = options.catalogs?.[catalogKind] ?? options.catalogSources?.[catalogKind];
-
-  return firstRecords(presentationCatalog)
-    ?? firstRecords(explicitCatalog)
-    ?? firstRecords(bundledCatalogs[catalogKind])
-    ?? [];
+  return getCatalogOptions(catalogKind, options).map((option) => option.record);
 }
 
+/**
+ * Picker options for `catalogKind`: `{ id, reference, label, record, group, source, origin }`, where `id` (= `reference`) is the
+ * reference to write, `id` or `name:id`. `options.presentation` is the document (default: `options.editor`'s), `options.catalogs`
+ * the host catalogs (merged after the session's registered ones).
+ */
 export function getCatalogOptions(catalogKind, options = {}) {
-  return getCatalogRecords(catalogKind, options).map((record) => ({
-    id: record.id,
-    label: catalogLabel(record),
-    record
-  }));
+  assertCatalogKind(catalogKind);
+  const presentation = options.presentation ?? options.editor?.presentation ?? {};
+  return listCatalogRecords(presentation, catalogKind, { catalogs: mergeCatalogs(options.editor?.catalogs, options.catalogs) });
 }
 
 export function assertCatalogId(catalogKind, id, options = {}) {
   assertCatalogKind(catalogKind);
   if (typeof id !== "string" || id.length === 0) {
-    throw new OPFEditorError("invalid-catalog-id", "Catalog control values must be non-empty catalog IDs.", {
+    throw new OPFEditorError("invalid-catalog-id", "Catalog control values must be non-empty catalog references.", {
       catalogKind,
       id
     });
@@ -461,7 +504,7 @@ export function assertCatalogId(catalogKind, id, options = {}) {
 
   const optionsById = new Set(getCatalogOptions(catalogKind, options).map((option) => option.id));
   if (!optionsById.has(id)) {
-    throw new OPFEditorError("unknown-catalog-id", `Unknown ${catalogKind} catalog ID: ${id}.`, {
+    throw new OPFEditorError("unknown-catalog-id", `Unknown ${catalogKind} catalog reference: ${id}.`, {
       catalogKind,
       id
     });
@@ -470,16 +513,16 @@ export function assertCatalogId(catalogKind, id, options = {}) {
   return id;
 }
 
+/** Write the catalog reference `id` at `path` (an object reference keeps its overrides and takes the new `id`). */
 export function setCatalogId(editor, path, catalogKind, id, meta = {}) {
   assertEditorSession(editor);
   const catalogId = assertCatalogId(catalogKind, id, {
-    presentation: meta.presentation ?? editor.document,
-    catalogs: meta.catalogs,
-    catalogSources: meta.catalogSources
+    presentation: meta.presentation ?? editor.presentation,
+    catalogs: mergeCatalogs(editor.catalogs, meta.catalogs)
   });
   const current = editor.get(path);
   const value = catalogReferenceValue(current, catalogId);
-  const { catalogs, catalogSources, presentation, ...commitMeta } = meta;
+  const { catalogs: _catalogs, presentation: _presentation, ...commitMeta } = meta;
   return editor.set(path, value, {
     ...commitMeta,
     catalogKind,
@@ -533,8 +576,8 @@ export function createCatalogSelect(editor, options) {
   if (options?.label) select.setAttribute("aria-label", options.label);
 
   for (const option of getCatalogOptions(catalogKind, {
-    ...options,
-    presentation: options?.presentation ?? editor.document
+    catalogs: mergeCatalogs(editor.catalogs, options?.catalogs),
+    presentation: options?.presentation ?? editor.presentation
   })) {
     const optionElement = documentRef.createElement("option");
     optionElement.value = option.id;
@@ -549,7 +592,6 @@ export function createCatalogSelect(editor, options) {
   const onChange = () => {
     setCatalogId(editor, path, catalogKind, select.value, {
       catalogs: options?.catalogs,
-      catalogSources: options?.catalogSources,
       presentation: options?.presentation,
       source: "catalog-select"
     });
@@ -636,12 +678,12 @@ function normalizeOperation(operation) {
 
 // Core patch errors keep their stable codes; the editor reports them as OPFEditorError.
 function editorPatchError(error) {
-  if (!(error instanceof PatchError)) return error;
+  if (!(error instanceof OPFPatchError)) return error;
   const details = {};
   if (error.path !== undefined) details.path = error.path;
   if (error.operation !== undefined) details.operation = error.operation;
   if (error.index !== undefined) details.index = error.index;
-  if (error.validation) details.issues = error.validation.errors;
+  if (error.validation) details.issues = errorFindings(error.validation);
   return new OPFEditorError(error.code, error.message, details);
 }
 
@@ -693,20 +735,6 @@ function assertCatalogKind(catalogKind) {
   }
 }
 
-function firstRecords(value) {
-  if (Array.isArray(value)) return value.filter(isCatalogRecord);
-  if (Array.isArray(value?.records)) return value.records.filter(isCatalogRecord);
-  return null;
-}
-
-function isCatalogRecord(record) {
-  return Boolean(record && typeof record === "object" && typeof record.id === "string");
-}
-
-function catalogLabel(record) {
-  return String(record.name ?? record.title ?? record.label ?? record.id);
-}
-
 function catalogReferenceValue(current, id) {
   if (current && typeof current === "object" && !Array.isArray(current)) {
     return { ...current, id };

package/dist/json-editor.js

@@ -103,7 +103,7 @@ function skipDelimiter(view, delimiter) {
 }
 function mountJsonCodeEditor(parent, options) {
   const attributes = new Compartment(), indent = new Compartment();
-  let disposed=false, menu=null, catalogs=options.catalogs??{}, generation=0;
+  let disposed=false, menu=null, catalogs=options.catalogs??[], generation=0;
   function closeOptions(){generation++;menu?.destroy();menu=null;}
   async function openOptions(left,top){
     closeOptions();
@@ -244,7 +244,7 @@ function mountJsonCodeEditor(parent, options) {
   return {
     api,
     openOptions,
-    setCatalogs(value){catalogs=value??{};closeOptions();},
+    setCatalogs(value){catalogs=value??[];closeOptions();},
     update(code, invalid=false, field=null, describedBy) {
       if(code!==api.getValue())closeOptions();
       const current = view.state.doc.toString(), normalized=textInputMap(code).text;

package/dist/json-menu.js

@@ -26,9 +26,9 @@ export function mountJsonFieldMenu(parent,api,catalogs,left,top,onClose){
   const error=add('p',undefined,'json-field-empty');error.setAttribute('role','alert');error.hidden=true;
   if(isLayout){
     const help=add('details',undefined,'json-field-catalog-help');add('summary','Where do these layouts come from?',undefined,help);
-    add('p','Standard OPF: included with OPF. Provided by app: extra records supplied by the host app. In this document: records in your JSON, which override matching IDs. External galleries are not automatically loaded.',undefined,help);
+    add('p','Provided by app: records from the catalogs the host app registered. In this document: records embedded in your JSON, which take precedence. Nothing is fetched; saving embeds every record the document uses.',undefined,help);
   }
-  add('p',context.unloadedSource?'Using available records. External catalog URLs are not loaded here.':'Choose an option or press Escape to keep editing JSON.','json-field-footnote');
+  add('p',context.unloadedSource?'Using the embedded records: a catalog this document names is not registered here.':'Choose an option or press Escape to keep editing JSON.','json-field-footnote');
   let selected=Math.max(0,context.options.findIndex(option=>option.value===context.value)),choices=[],disposed=false;
   function close(restore=false){if(disposed)return;disposed=true;observer.disconnect();root.remove();doc.removeEventListener('pointerdown',outside);doc.removeEventListener('wheel',outside,true);doc.removeEventListener('touchmove',outside,true);win.removeEventListener('resize',resize);onClose();if(restore){api.focus();api.setSelection(...selection);}}
   function outside(event){if(!root.contains(event.target))close();}

package/dist/json-options.d.ts

@@ -1,11 +1,11 @@
-/** Already-loaded catalog records by kind. No remote catalog URLs are fetched. */
-export type JsonCatalogContext = Readonly<Record<string, readonly Record<string, unknown>[]>>;
+/** The host's catalogs (core `Catalog[]`): records offered after the document's embedded ones. */
+export type JsonCatalogContext = readonly import("@openpresentation/opf").Catalog[];
 export type JsonOptionValue = string | number | boolean;
 export interface JsonFieldOption {
   value: JsonOptionValue;
   label: string;
   description?: string;
-  source: 'Built-in catalog' | 'Loaded catalog' | 'Document catalog' | 'Schema' | 'Current value';
+  source: 'Loaded catalog' | 'Document catalog' | 'Schema' | 'Current value';
   suggested?: boolean;
   /** User-facing provenance; source remains stable for existing consumers. */
   sourceLabel?: string;