@openpresentation/opf-editor 0.14.2 → 0.16.0

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
 import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
-import type { Fonts, PresentationStats, SlideContextDiagnostic, StatsOptions, ValidationReport } from "@openpresentation/opf";
+import type { Catalog, Fonts, PresentationStats, SlideContextDiagnostic, StatsOptions, ValidationReport } from "@openpresentation/opf";
+export * from "./catalogs.js";
 /**
  * What the editor adds to the options of `composeSlide` and `paginateSlide`: `fonts` is the renderer's fonts handle (`loadFonts()`), whose
- * `textMeasurement` measures the text; `catalogs` are host catalog records; `onDiagnostic` hears every `unresolved-font-scheme`,
- * `unresolved-layout`, `unresolved-theme` and `unresolved-color-scheme` diagnostic of core's `resolveSlideContext`. Any other option overrides
- * the resolved one.
+ * `textMeasurement` measures the text; `catalogs` are host catalogs for this call (merged after the session's registered ones);
+ * `onDiagnostic` hears every diagnostic of core's `resolveSlideContext` (`unresolved-reference`). Any other
+ * option overrides the resolved one.
  */
 export interface EditorDiagnosticOptions {
   fonts?: Fonts;
-  catalogs?: Record<string, readonly unknown[]>;
+  catalogs?: readonly Catalog[];
   onDiagnostic?: (diagnostic: SlideContextDiagnostic) => void;
 }
 export declare const packageName = "@openpresentation/opf-editor";
@@ -56,7 +57,8 @@ export interface EditorChange {
 }
 
 export interface EditorEvent {
-  type: "patch" | "undo" | "redo" | "restore";
+  /** `catalogs`: the registered catalogs changed (`setCatalogs`); the document did not. */
+  type: "patch" | "undo" | "redo" | "restore" | "catalogs";
   patches: JsonPatchOperation[];
   inversePatches?: JsonPatchOperation[];
   redoPatches?: JsonPatchOperation[];
@@ -73,7 +75,12 @@ export interface EditorSession {
   composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   readonly presentation: unknown;
+  /** The `format` report of the document plus the catalog reference rules, checked against the registered catalogs. */
   readonly validation: ValidationReport;
+  /** The host's registered catalogs, frozen; the first is the host default. */
+  readonly catalogs: readonly Catalog[];
+  /** Replace the registered catalogs: re-validates the document and emits one `catalogs` event. */
+  setCatalogs(catalogs: readonly Catalog[] | undefined, meta?: Record<string, unknown>): readonly Catalog[];
   readonly canUndo: boolean;
   readonly canRedo: boolean;
   snapshot(): EditorSnapshot;
@@ -94,18 +101,28 @@ export interface EditorSession {
 export interface CreateEditorSessionOptions {
   /** Refuse every edit whose result has an error finding (the default per edit is `meta.rejectInvalid`). */
   rejectInvalid?: boolean;
+  /** The host's catalogs (for example `[defaultCatalog]` from `@openpresentation/opf/catalog`): resolution, validation, pickers, embedding. */
+  catalogs?: readonly Catalog[];
 }
 
 export interface CatalogOption {
+  /** The reference to write: `id` or `name:id`. */
   id: string;
+  reference: string;
   label: string;
+  description?: string;
   record: Record<string, unknown>;
+  /** The catalog group the record resolves in (`custom`, `default` or a named group). */
+  group: string;
+  source?: string;
+  origin: "document" | "host";
 }
 
 export interface CatalogOptionsInput {
   presentation?: { catalogs?: Record<string, unknown> } | Record<string, unknown>;
-  catalogs?: Record<string, unknown>;
-  catalogSources?: Record<string, unknown>;
+  /** Host catalogs, merged after `editor`'s registered ones. */
+  catalogs?: readonly Catalog[];
+  editor?: EditorSession;
   [key: string]: unknown;
 }
 
@@ -145,6 +162,7 @@ export interface CatalogSelectOptions extends CatalogOptionsInput {
   path: string;
   catalogKind: string;
   label?: string;
+  onError?: (error: Error) => void;
   document?: { createElement(tagName: string): any };
 }
 

package/dist/index.js

@@ -1,16 +1,39 @@
+import { commitCatalogControl } from "./catalog-control.js";
 import { paginateSlide } from "@openpresentation/opf/pagination";
 import { OPFPatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
 import { collectReservedPresentationIds } from "./presentation-ids.js";
 import { composeSlide } from "@openpresentation/opf/composition";
-import { catalogKinds, catalogs as bundledCatalogs, resolveSlideContext, stats } from "@openpresentation/opf";
+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, default), 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.onDiagnostic` hears each `unresolved-*` diagnostic;
+// 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, { fonts, catalogs, onDiagnostic, ...overrides } = {}) {
+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);
@@ -123,7 +146,10 @@ export function deckStats(editor, options) {
 
 export function createEditorSession(input, options = {}) {
   let presentation = parseInput(input);
-  let validation = checkFormat(presentation);
+  // 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();
@@ -138,7 +164,7 @@ export function createEditorSession(input, options = {}) {
 
   function commitPatch(operations, meta = {}) {
     assertPatchOperations(operations);
-    const patches = operations.map(normalizeOperation);
+    let patches = operations.map(normalizeOperation);
     const before = presentation;
     let next, inversePatches;
     try {
@@ -146,7 +172,24 @@ export function createEditorSession(input, options = {}) {
     } catch (error) {
       throw editorPatchError(error);
     }
-    const nextValidation = checkFormat(next);
+    // 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.", {
@@ -174,7 +217,8 @@ export function createEditorSession(input, options = {}) {
       presentation: clone(presentation),
       patches: clonePatchOperations(patches),
       inversePatches: clonePatchOperations(inversePatches),
-      validation
+      validation,
+      ...(forks.length ? { forked: forks, notice: meta.notice } : {})
     };
   }
 
@@ -185,6 +229,20 @@ export function createEditorSession(input, options = {}) {
     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;
     },
@@ -218,13 +276,15 @@ export function createEditorSession(input, options = {}) {
       });
     },
     composeSlide(slideIndex, options = {}) {
-      return composeSlide(presentation.slides?.[slideIndex], slideContext(presentation, slideIndex, options));
+      return composeSlide(presentation.slides?.[slideIndex], slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options));
     },
     paginateSlide(slideIndex, options = {}, meta = {}) {
+      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, options);
+      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options);
       const pagination = paginateSlide(presentation.slides[slideIndex], {
         ...resolved,
+        catalogs: list,
         fonts: options.fonts ?? (textMeasurement ? { textMeasurement } : undefined),
         reservedIds: collectReservedPresentationIds(presentation),
       });
@@ -267,7 +327,7 @@ export function createEditorSession(input, options = {}) {
     restoreState(state, meta = {}) {
       if (!state || typeof state !== "object") throw new OPFEditorError("invalid-state", "restoreState needs { presentation, undo?, redo? }.");
       const next = parseInput(state.presentation);
-      const nextValidation = checkFormat(next);
+      const nextValidation = check(next);
       if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
         throw new OPFEditorError("invalid-opf-edit", "The restored document is not valid OPF.", { issues: errorFindings(nextValidation) });
       }
@@ -304,7 +364,7 @@ export function createEditorSession(input, options = {}) {
       const entry = undoStack.pop();
       if (!entry) return null;
       presentation = applyJsonPatch(presentation, entry.inversePatches);
-      validation = checkFormat(presentation);
+      validation = check(presentation);
       redoStack.push(entry);
       emit({
         type: "undo",
@@ -324,7 +384,7 @@ export function createEditorSession(input, options = {}) {
       const entry = redoStack.pop();
       if (!entry) return null;
       presentation = applyJsonPatch(presentation, entry.patches);
-      validation = checkFormat(presentation);
+      validation = check(presentation);
       undoStack.push(entry);
       emit({
         type: "redo",
@@ -415,29 +475,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
     });
@@ -445,7 +505,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
     });
@@ -454,18 +514,29 @@ 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.presentation,
-    catalogs: meta.catalogs,
-    catalogSources: meta.catalogSources
+    catalogs: mergeCatalogs(editor.catalogs, meta.catalogs)
   });
   const current = editor.get(path);
   const value = catalogReferenceValue(current, catalogId);
-  const { catalogs, catalogSources, presentation, ...commitMeta } = meta;
-  return editor.set(path, value, {
+  const { catalogs: _catalogs, presentation: _presentation, ...commitMeta } = meta;
+  // Only documented design references may initialize their optional design parent.
+  // Ordinary set/applyPatch retain RFC 6902's existing-parent requirement.
+  const segments = splitOpfPath(path);
+  const designField = { themes: "theme", colorSchemes: "colorScheme", fontSchemes: "fontScheme" }[catalogKind];
+  const deckDesign = segments.length === 2 && segments[0] === "design";
+  const slideDesign = segments.length === 4 && segments[0] === "slides" && /^(0|[1-9][0-9]*)$/.test(segments[1]) && segments[2] === "design" && editor.get(segments.slice(0, 2));
+  const parent = segments.slice(0, -1);
+  const patches = designField === segments.at(-1) && (deckDesign || slideDesign) && !hasValueAtPath(editor.presentation, parent)
+    ? [{ op: "add", path: opfPathToJsonPointer(parent), value: { [designField]: value } }]
+    : createValuePatch(editor.presentation, path, value);
+  return editor.applyPatch(patches, {
     ...commitMeta,
+    rejectInvalid: true,
     catalogKind,
     catalogId,
     source: commitMeta.source ?? "catalog-control"
@@ -517,7 +588,7 @@ export function createCatalogSelect(editor, options) {
   if (options?.label) select.setAttribute("aria-label", options.label);
 
   for (const option of getCatalogOptions(catalogKind, {
-    ...options,
+    catalogs: mergeCatalogs(editor.catalogs, options?.catalogs),
     presentation: options?.presentation ?? editor.presentation
   })) {
     const optionElement = documentRef.createElement("option");
@@ -530,14 +601,13 @@ export function createCatalogSelect(editor, options) {
     const current = editor.get(path);
     select.value = typeof current === "object" && current ? current.id : current ?? "";
   };
-  const onChange = () => {
-    setCatalogId(editor, path, catalogKind, select.value, {
+  const onChange = () => commitCatalogControl(select, options?.onError, updateValue, () => {
+    return setCatalogId(editor, path, catalogKind, select.value, {
       catalogs: options?.catalogs,
-      catalogSources: options?.catalogSources,
       presentation: options?.presentation,
       source: "catalog-select"
     });
-  };
+  });
   const unsubscribe = editor.subscribe(updateValue);
 
   select.addEventListener?.("change", onChange);
@@ -677,20 +747,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;

package/dist/json-options.js

@@ -1,19 +1,29 @@
-import { catalogKinds, catalogSchemaNames, schemas, validateCatalogRecord } from "@openpresentation/opf";
 import { checkFormat, firstErrorMessage } from "./checks.js";
-import { getCatalogOptions } from "./index.js";
+import { listCatalogRecords } from "./catalogs.js";
 import { schemaAtPath, schemaVariants } from "./schema.js";
 import { applyEdits, findNodeAtLocation, findNodeAtOffset, getNodePath, modify, parseTree } from "jsonc-parser";
-import { populateLayoutPlaceholders } from "./layout-placeholders.js";
-function catalogFor(description) {
-    return catalogKinds.find(kind => description.includes(`catalogs.${kind}`)
-        || new RegExp(`\\b${kind}['’]? catalog`).test(description));
+import { layoutSlotSummary, layoutSlotTypes, populateLayoutPlaceholders } from "./layout-placeholders.js";
+// The catalog kind a field references (OPF 0.15: every content kind is `id` or `name:id`), read from where the field sits.
+const ROOT_REFERENCES = { narrative: "narratives", audience: "audiences", purpose: "purposes", tone: "tones" };
+const DESIGN_REFERENCES = { theme: "themes", colorScheme: "colorSchemes", fontScheme: "fontSchemes" };
+function catalogAtPath(path) {
+    const parts = path.map(String);
+    // A reference's object form names its record with `id`; an audience array's entries are references too.
+    const field = parts.at(-1) === "id" ? parts.slice(0, -1) : parts;
+    const tail = /^\d+$/.test(field.at(-1) ?? "") && field.at(-2) === "audience" ? field.slice(0, -1) : field;
+    const key = tail.at(-1);
+    if (tail.length === 3 && tail[0] === "slides" && key === "layout") return "layouts";
+    if (tail.length === 1 && ROOT_REFERENCES[key]) return ROOT_REFERENCES[key];
+    if (DESIGN_REFERENCES[key] && ((tail.length === 2 && tail[0] === "design") || (tail.length === 4 && tail[0] === "slides" && tail[2] === "design"))) return DESIGN_REFERENCES[key];
+    // Inside an embedded record: a theme's colour or font scheme.
+    if (tail.length === 5 && tail[0] === "catalogs" && tail[2] === "themes" && (key === "colorScheme" || key === "fontScheme")) return DESIGN_REFERENCES[key];
+    return undefined;
 }
 // Compare declared placeholders, including multiplicity. This describes a layout
 // contract, not a claim that arbitrary slide content will render without overflow.
+// FA-26: a record's placeholder groups compare by their leaf regions, the slots its content fills.
 function layoutTypes(record) {
-    if (!Array.isArray(record?.placeholders))
-        return undefined;
-    return record.placeholders.map(p => p.type).sort();
+    return layoutSlotTypes(record)?.sort();
 }
 function placeholderSummary(types) {
     if (!types)
@@ -28,9 +38,8 @@ function placeholderSummary(types) {
     }).join(" + ");
 }
 const sourceDetails = {
-    "Built-in catalog": ["Standard OPF", "Included with OPF and available offline."],
-    "Loaded catalog": ["Provided by app", "Additional records supplied to the preview by this app; these are not fetched from a URL."],
-    "Document catalog": ["In this document", "Defined in this document’s catalogs. Takes precedence over app and standard records with the same ID."],
+    "Loaded catalog": ["Provided by app", "Records from a catalog this app registered; nothing is fetched from a URL. Saving embeds the record in the document."],
+    "Document catalog": ["In this document", "Embedded in this document’s catalogs. Takes precedence over the app’s records with the same reference."],
     "Current value": ["Custom value", "The current value is not in the available catalogs."],
     "Schema": ["OPF option", "Allowed by the OPF schema."],
 };
@@ -47,8 +56,10 @@ function describeOptions(choices, records, current, catalog) {
         if (catalog !== "layouts")
             continue;
         const types = layoutTypes(option.value === current ? currentRecord : records.get(String(option.value)));
-        option.placeholderTypes = records.get(String(option.value))?.placeholders?.map(placeholder => placeholder.type);
-        option.placeholders = placeholderSummary(types);
+        const record = records.get(String(option.value));
+        option.placeholderTypes = layoutSlotTypes(record);
+        // A record with placeholder groups also shows how its slots nest.
+        option.placeholders = placeholderSummary(types) + (record?.placeholders?.some?.(entry => entry?.type === "group") ? ` · ${layoutSlotSummary(record)}` : "");
         const same = types && currentTypes && signature(types) === signature(currentTypes);
         const equivalent = types && currentTypes && signature(compatible(types)) === signature(compatible(currentTypes));
         const sameKinds = types && currentTypes && signature([...new Set(compatible(types))]) === signature([...new Set(compatible(currentTypes))]);
@@ -64,7 +75,7 @@ function describeOptions(choices, records, current, catalog) {
 }
 // The installed schema identifies fields; a document field merely named "layout"
 // inside arbitrary metadata is not mistaken for an OPF layout reference.
-export function getJsonFieldContext(source, position, loadedCatalogs = {}) {
+export function getJsonFieldContext(source, position, loadedCatalogs = []) {
     let presentation;
     try {
         presentation = JSON.parse(source);
@@ -87,42 +98,21 @@ export function getJsonFieldContext(source, position, loadedCatalogs = {}) {
         return null;
     const schema = schemaAtPath(presentation, path.map(String));
     const variants = schemaVariants(schema);
-    const description = String(schema.description ?? "");
-    let catalog = catalogFor(description);
-    // Audience arrays inherit the catalog context from the array property.
-    if (!catalog && typeof path.at(-1) === "number")
-        catalog = catalogFor(String(schemaAtPath(presentation, path.slice(0, -1).map(String)).description ?? ""));
+    const catalog = catalogAtPath(path);
     const options = new Map();
     const records = new Map();
-    let unloadedSource = false;
+    // A document group whose source no registered catalog matches: its records beyond the embedded ones are not available here.
+    const registered = new Set((Array.isArray(loadedCatalogs) ? loadedCatalogs : []).map(entry => entry?.source));
+    const unloadedSource = Boolean(catalog) && Object.entries(presentation.catalogs ?? {}).some(([name, group]) => name !== "custom" && group && typeof group === "object" && typeof group.source === "string" && !registered.has(group.source));
     if (catalog && typeof node.value === "string") {
-        const entries = presentation.catalogs;
-        const local = entries?.[catalog];
-        unloadedSource = Boolean(local?.source);
-        for (const option of getCatalogOptions(catalog)) {
+        const hostCatalogs = Array.isArray(loadedCatalogs) ? loadedCatalogs : [];
+        // A draft whose own catalogs are malformed still offers the host's records; a malformed host list offers nothing.
+        const attempt = (document) => { try { return listCatalogRecords(document, catalog, { catalogs: hostCatalogs }); } catch { return undefined; } };
+        const available = attempt(presentation) ?? attempt({ ...presentation, catalogs: undefined }) ?? [];
+        for (const option of available) {
             records.set(option.id, option.record);
-            options.set(option.id, { value: option.id, label: option.label, description: typeof option.record.description === "string" ? option.record.description : undefined,
-                source: "Built-in catalog" });
-        }
-        for (const { value, source } of [...(Array.isArray(loadedCatalogs?.[catalog]) ? loadedCatalogs[catalog] : []).map(value => ({ value, source: "Loaded catalog" })),
-            ...(Array.isArray(local?.records) ? local.records : []).map(value => ({ value, source: "Document catalog" }))]) {
-            if (!value || typeof value !== "object")
-                continue;
-            const record = value;
-            if (typeof record.id !== "string")
-                continue;
-            // Inline records may omit the standalone document's $schema marker.
-            // Supply it only for validation; never change the authored record.
-            const schemaId = schemas[catalogSchemaNames[catalog]].$id;
-            if (!validateCatalogRecord(catalog, { $schema: schemaId, ...record }).valid) {
-                options.delete(record.id);
-                records.delete(record.id);
-                continue;
-            }
-            records.set(record.id, record);
-            options.set(record.id, { value: record.id, label: typeof record.name === "string" ? record.name : record.id,
-                description: typeof record.description === "string" ? record.description : undefined,
-                source });
+            options.set(option.id, { value: option.id, label: option.label, description: option.description,
+                source: option.origin === "document" ? "Document catalog" : "Loaded catalog" });
         }
     }
     else {

package/dist/layout-handles.js

@@ -60,6 +60,19 @@ export function createLayoutHandles(root, options) {
     lastGeometry=geometry;
     layer.replaceChildren();
     if(!enabled||options.isTextEditing())return;
+    // FA-26: the slots of a layout record with placeholder groups, drawn under the handles while arranging: each group and
+    // region as a dashed outline at its cell, deeper groups inset, an empty region labelled with its kind. They are the
+    // record's, not the document's, so they are not editable here; the content in a slot keeps its own selection.
+    for(const slot of geometry.slots??[]){
+      const node=doc.createElement('div');
+      node.dataset.layoutSlot=slot.path;node.dataset.layoutSlotType=slot.type;node.setAttribute('aria-hidden','true');
+      const group=slot.type==='group',empty=!group&&!slot.content;
+      node.title=group?`Layout group (${slot.path})`:`${empty?'Empty ':''}${slot.type} slot (${slot.path})`;
+      const inset=group?Math.min(4,slot.depth*2):0;
+      node.style.cssText=`position:absolute;pointer-events:none;box-sizing:border-box;left:calc(${slot.box.x/geometry.width*100}% + ${inset}px);top:calc(${slot.box.y/geometry.height*100}% + ${inset}px);width:calc(${slot.box.width/geometry.width*100}% - ${2*inset}px);height:calc(${slot.box.height/geometry.height*100}% - ${2*inset}px);border:1px dashed ${group?'#8170d5':'#8a78d7aa'};border-radius:4px;${empty?'background:#8a78d714;':''}`;
+      if(empty){const label=doc.createElement('span');label.textContent=`Empty ${slot.type} slot`;label.style.cssText='position:absolute;left:6px;top:4px;font:11px system-ui;color:#675394';node.append(label);}
+      layer.append(node);
+    }
     for(const flow of geometry.flows??[]){
       const {axis,size,tracks}=trackData(flow);
       if(tracks.length<2||tracks.length>12||flow.itemCount!==flow.slotCount)continue;

package/dist/layout-placeholders.js

@@ -1,5 +1,20 @@
+import {layoutLeaves,layoutStructure} from '@openpresentation/opf/composition';
 import {listBlockContainers,prepareBlockInsert} from './blocks.js';
 
+/**
+ * The slot kinds a layout record declares, in reading order: its headings and the leaf regions of its placeholder groups
+ * (FA-26), the kinds a slide's flat content fills. Undefined when the record states no placeholders.
+ */
+export function layoutSlotTypes(record){
+  if(!Array.isArray(record?.placeholders))return undefined;
+  try{return layoutLeaves(record).map(leaf=>leaf.type);}catch{return record.placeholders.filter(entry=>entry?.type!=='group').map(entry=>entry?.type);}
+}
+/** A one-line description of a record's slots, nested groups in parentheses: `title, column (text, text), chart`. */
+export function layoutSlotSummary(record){
+  if(!Array.isArray(record?.placeholders))return '';
+  try{return layoutStructure(record);}catch{return layoutSlotTypes(record).join(', ');}
+}
+
 const payloadFields=['text','items','bullets','image','video','chart','table','code','metric','quote','timeline'];
 const headingFields=new Set(['title','subtitle','tag']);
 const fields={text:'text',list:'items',image:'image',video:'video',chart:'chart',table:'table',code:'code',metric:'metric',quote:'quote',timeline:'timeline'};

package/dist/react.d.ts

@@ -14,6 +14,7 @@ export interface OPFCatalogSelectProps {
   path: string;
   catalogKind: string;
   label?: string;
+  onError?: (error: Error) => void;
   catalogOptions?: CatalogOption[];
   selectProps?: Record<string, unknown>;
   [key: string]: unknown;

package/dist/react.js

@@ -1,3 +1,4 @@
+import { commitCatalogControl } from "./catalog-control.js";
 import {
   getCatalogOptions,
   getValueAtPath,
@@ -56,13 +57,14 @@ export function createOPFReactComponents(React) {
     catalogKind,
     label,
     catalogOptions,
+    onError,
     selectProps = {},
     ...props
   }) {
     const snapshot = useEditorSnapshot(editor);
     const value = getValueAtPath(snapshot.presentation, path, "");
     const currentId = value && typeof value === "object" ? value.id : value;
-    const options = catalogOptions ?? getCatalogOptions(catalogKind, { presentation: snapshot.presentation });
+    const options = catalogOptions ?? getCatalogOptions(catalogKind, { presentation: snapshot.presentation, catalogs: editor.catalogs });
 
     return React.createElement(
       "select",
@@ -78,7 +80,9 @@ export function createOPFReactComponents(React) {
           selectProps.onChange?.(event);
           props.onChange?.(event);
           if (!event.defaultPrevented) {
-            setCatalogId(editor, path, catalogKind, event.currentTarget.value, { source: "react-catalog-select" });
+            const node = event.currentTarget;
+            commitCatalogControl(node, onError, () => { node.value = currentId ?? ""; }, () =>
+              setCatalogId(editor, path, catalogKind, node.value, { source: "react-catalog-select" }));
           }
         }
       },