@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/templates.js

@@ -2,12 +2,13 @@
 // with variables; filling it resolves the variables to a concrete deck (core resolveVariables).
 // Everything here reads and writes the document through the session, so a fill, a declaration
 // and a token insertion are validated, undoable JSON Patch edits like any other. Importing this
-// module needs no DOM. Core is read from the namespace so an older core still loads this module;
-// the functions then throw "templates-unavailable".
-import * as core from "@openpresentation/opf";
+// module needs no DOM.
+import { coerceVariableValue, hasContentVariables, listBuiltinVariables, listVariables, resolveVariables, variableDeclarations } from "@openpresentation/opf";
 import { OPFEditorError, getValueAtPath, opfPathToJsonPointer } from "./index.js";
 
 const VARIABLE_ID = /^[a-z][a-z0-9-]*$/;
+// A built-in variable name (core FA-04): `speakers`, or deck/speaker/organization plus one or two dotted segments.
+const BUILTIN_NAME = /^(?:speakers|(?:deck|speaker|organization)(?:.[A-Za-z0-9_-]+){1,2})$/;
 const KINDS = ["color", "text", "number", "date", "image", "url", "list"];
 
 /** The form control each variable kind uses. */
@@ -25,12 +26,6 @@ function fail(code, message, details) {
   return new OPFEditorError(code, message, details);
 }
 
-function requireCore() {
-  if (typeof core.resolveVariables !== "function" || typeof core.listVariables !== "function") {
-    throw fail("templates-unavailable", "Templates need a core release that ships resolveVariables (@openpresentation/opf after 0.11.4).");
-  }
-}
-
 function checkEditor(editor) {
   if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function") {
     throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
@@ -39,19 +34,22 @@ function checkEditor(editor) {
 
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
-/** True when the core this editor runs on can resolve template variables. */
-export function templatesAvailable() {
-  return typeof core.resolveVariables === "function" && typeof core.listVariables === "function";
-}
-
 /** True when the document is marked as a template (`template: true`). */
-export function isTemplateDocument(document) {
-  return isObject(document) && document.template === true;
+export function isTemplateDocument(presentation) {
+  return isObject(presentation) && presentation.template === true;
 }
 
 /** True when the document is a template or declares a variable that is not a color. */
-export function hasTemplateVariables(document) {
-  return templatesAvailable() && core.hasContentVariables(document);
+export function hasTemplateVariables(presentation) {
+  return hasContentVariables(presentation);
+}
+
+/**
+ * The presentation's built-in variables (read-only values from its own speaker, organization and deck metadata) with
+ * kind, label, current value, whether the presentation has a source value and where each is used.
+ */
+export function listBuiltins(presentation) {
+  return listBuiltinVariables(presentation);
 }
 
 function humanize(id) {
@@ -80,10 +78,9 @@ export function valueToFieldText(kind, value) {
  * applies again). Returns `{ ok: true, value }` (value undefined when cleared) or `{ ok: false, message }`.
  */
 export function fieldTextToValue(kind, text) {
-  requireCore();
   if (typeof text !== "string") return { ok: false, message: "Expected text." };
   if (text.trim() === "") return { ok: true, value: undefined };
-  const coerced = core.coerceVariableValue(kind, kind === "text" ? text : text.trim());
+  const coerced = coerceVariableValue(kind, kind === "text" ? text : text.trim());
   return coerced.ok ? { ok: true, value: coerced.value } : { ok: false, message: `${coerced.message}.` };
 }
 
@@ -92,10 +89,9 @@ export function fieldTextToValue(kind, text) {
  * `status` is "filled" (a value was supplied), "default" (the declaration has a value), "unfilled"
  * (required, no value) or "optional" (not required, no value).
  */
-export function listTemplateFields(document, values = {}) {
-  requireCore();
-  const declared = new Map(core.variableDeclarations(document).map((declaration) => [declaration.id, declaration]));
-  return core.listVariables(document, values).map((info) => {
+export function listTemplateFields(presentation, values = {}) {
+  const declared = new Map(variableDeclarations(presentation).map((declaration) => [declaration.id, declaration]));
+  return listVariables(presentation, values).map((info) => {
     const declaration = declared.get(info.id);
     const supplied = Object.hasOwn(values, info.id) && values[info.id] !== undefined && values[info.id] !== null;
     const defaultValue = declaration?.value;
@@ -122,12 +118,12 @@ export function listTemplateFields(document, values = {}) {
 }
 
 /** The summary a panel shows: how many required variables still need a value. */
-export function templateStatus(document, values = {}) {
-  const fields = listTemplateFields(document, values);
+export function templateStatus(presentation, values = {}) {
+  const fields = listTemplateFields(presentation, values);
   const required = fields.filter((field) => field.required);
   const unfilled = fields.filter((field) => field.status === "unfilled").map((field) => field.id);
   return {
-    template: isTemplateDocument(document),
+    template: isTemplateDocument(presentation),
     fieldCount: fields.length,
     requiredCount: required.length,
     filledRequiredCount: required.length - unfilled.length,
@@ -140,9 +136,8 @@ export function templateStatus(document, values = {}) {
  * Preview data for the supplied values: the concrete deck with each unfilled variable's example (or its
  * token when it has none). Never throws for missing values; the diagnostics say what was unfilled.
  */
-export function previewTemplate(document, values = {}) {
-  requireCore();
-  return core.resolveVariables(document, values, { examples: true, partial: true });
+export function previewTemplate(presentation, values = {}) {
+  return resolveVariables(presentation, values, { examples: true, partial: true });
 }
 
 /**
@@ -151,34 +146,33 @@ export function previewTemplate(document, values = {}) {
  * document, `subscribe` notifies listeners (a panel redraws on it).
  */
 export function createTemplateFill(editor, options = {}) {
-  requireCore();
   checkEditor(editor);
   let values = {};
   const listeners = new Set();
   const emit = () => {
     for (const listener of listeners) listener(api);
   };
-  const declared = () => new Set(core.variableDeclarations(editor.document).map((declaration) => declaration.id));
-  const kindOf = (id) => core.variableDeclarations(editor.document).find((declaration) => declaration.id === id)?.kind;
+  const declared = () => new Set(variableDeclarations(editor.presentation).map((declaration) => declaration.id));
+  const kindOf = (id) => variableDeclarations(editor.presentation).find((declaration) => declaration.id === id)?.kind;
   const api = {
     get values() {
       return structuredClone(values);
     },
     fields() {
-      return listTemplateFields(editor.document, values);
+      return listTemplateFields(editor.presentation, values);
     },
     status() {
-      return templateStatus(editor.document, values);
+      return templateStatus(editor.presentation, values);
     },
     preview() {
-      return previewTemplate(editor.document, values);
+      return previewTemplate(editor.presentation, values);
     },
     set(id, value) {
       if (!declared().has(id)) throw fail("unknown-variable", `No variable '${id}' is declared.`, { id });
       if (value === undefined || value === null) {
         delete values[id];
       } else {
-        const coerced = core.coerceVariableValue(kindOf(id), value);
+        const coerced = coerceVariableValue(kindOf(id), value);
         if (!coerced.ok) throw fail("invalid-variable-value", `Value for '${id}': ${coerced.message}.`, { id });
         values[id] = coerced.value;
       }
@@ -218,8 +212,8 @@ export function createTemplateFill(editor, options = {}) {
      * `partial` is set (the unfilled ones stay declared for a later pass).
      */
     apply({ partial = false, meta = {} } = {}) {
-      const document = editor.document;
-      const result = core.resolveVariables(document, values, { partial, template: false });
+      const presentation = editor.presentation;
+      const result = resolveVariables(presentation, values, { partial, template: false });
       const errors = result.diagnostics.filter((entry) => entry.severity === "error");
       if (errors.length) {
         const unfilled = errors.some((entry) => entry.code === "variable-unfilled");
@@ -239,27 +233,27 @@ export function createTemplateFill(editor, options = {}) {
   return api;
 }
 
-/** The token text for a variable: `{{id}}`, or `{{id|format}}` with a one-off format. */
+/** The token text for a variable or a built-in name: `{{id}}`, or `{{id|format}}` with a one-off format. */
 export function variableToken(id, format) {
-  if (!VARIABLE_ID.test(id)) throw fail("invalid-variable-id", "A variable id is lowercase kebab-case: letters, digits and hyphens, starting with a letter.", { id });
+  if (!VARIABLE_ID.test(id) && !BUILTIN_NAME.test(id)) throw fail("invalid-variable-id", "A variable id is lowercase kebab-case: letters, digits and hyphens, starting with a letter.", { id });
   return format ? `{{${id}|${format}}}` : `{{${id}}}`;
 }
 
 /** An unused variable id derived from a label, for a "new variable" form. */
-export function suggestVariableId(document, label = "value") {
+export function suggestVariableId(presentation, label = "value") {
   const base = String(label).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/^[^a-z]+/, "") || "value";
-  const taken = new Set(isObject(document?.variables) ? Object.keys(document.variables) : []);
+  const taken = new Set(isObject(presentation?.variables) ? Object.keys(presentation.variables) : []);
   if (!taken.has(base)) return base;
   for (let n = 2; ; n++) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`;
 }
 
-function declarationPatches(document, id, declaration) {
+function declarationPatches(presentation, id, declaration) {
   if (!VARIABLE_ID.test(id)) throw fail("invalid-variable-id", "A variable id is lowercase kebab-case: letters, digits and hyphens, starting with a letter.", { id });
   const entry = typeof declaration === "string" ? declaration : structuredClone(declaration);
   if (typeof entry !== "string" && !(isObject(entry) && KINDS.includes(entry.type))) {
     throw fail("invalid-variable", `A variable declaration is a hex color or an object whose type is one of ${KINDS.join(", ")}.`, { id });
   }
-  const variables = document.variables;
+  const variables = presentation.variables;
   if (variables !== undefined && !isObject(variables)) throw fail("invalid-variable", "The document's variables field is not an object.", { id });
   if (variables && Object.hasOwn(variables, id)) throw fail("variable-exists", `A variable '${id}' is already declared.`, { id });
   return variables === undefined
@@ -269,22 +263,21 @@ function declarationPatches(document, id, declaration) {
 
 /** Declare a variable as one undoable edit. The resulting document must validate (a required variable with no value needs `template: true`). */
 export function declareVariable(editor, id, declaration, meta = {}) {
-  requireCore();
   checkEditor(editor);
-  return editor.applyPatch(declarationPatches(editor.document, id, declaration), { source: "template-variable", rejectInvalid: true, ...meta });
+  return editor.applyPatch(declarationPatches(editor.presentation, id, declaration), { source: "template-variable", rejectInvalid: true, ...meta });
 }
 
 /** Mark the document as a template (or, with `false`, as a normal deck) as one undoable edit. */
 export function setTemplate(editor, enabled, meta = {}) {
   checkEditor(editor);
-  const document = editor.document;
-  const present = Object.hasOwn(document, "template");
+  const presentation = editor.presentation;
+  const present = Object.hasOwn(presentation, "template");
   const patches = enabled
     ? [{ op: present ? "replace" : "add", path: "/template", value: true }]
     : present
       ? [{ op: "remove", path: "/template" }]
       : [];
-  if (!patches.length) return { document, patches: [], inversePatches: [], validation: editor.validation };
+  if (!patches.length) return { presentation, patches: [], inversePatches: [], validation: editor.validation };
   return editor.applyPatch(patches, { source: "template-mode", rejectInvalid: true, ...meta });
 }
 
@@ -295,18 +288,18 @@ export function setTemplate(editor, enabled, meta = {}) {
  * the declaration, and both changes commit together.
  */
 export function insertVariableToken(editor, path, id, { start, end, runIndex, format, declare, meta = {} } = {}) {
-  requireCore();
   checkEditor(editor);
-  const document = editor.document;
+  const presentation = editor.presentation;
   const token = variableToken(id, format);
   const patches = [];
-  const declaredNow = isObject(document.variables) && Object.hasOwn(document.variables, id);
+  // A built-in needs no declaration; an unknown built-in path fails the validated edit.
+  const declaredNow = BUILTIN_NAME.test(id) || (isObject(presentation.variables) && Object.hasOwn(presentation.variables, id));
   if (!declaredNow) {
     if (declare === undefined) throw fail("unknown-variable", `No variable '${id}' is declared. Declare it first, or pass its declaration.`, { id });
-    patches.push(...declarationPatches(document, id, declare));
+    patches.push(...declarationPatches(presentation, id, declare));
   }
   const pointer = opfPathToJsonPointer(path);
-  const current = getValueAtPath(document, path);
+  const current = getValueAtPath(presentation, path);
   const splice = (text) => {
     const from = start === undefined ? text.length : start;
     const to = end === undefined ? from : end;

package/dist/transfer.d.ts

@@ -1,19 +1,22 @@
+import type { Catalog, CopiedRecordRename } from "@openpresentation/opf";
 export declare const MAX_OPF_BYTES: number;
 export interface OpfTransfer {
   kind: "presentation" | "slides" | "selection";
   value: unknown;
-  document?: any;
+  presentation?: any;
 }
-export declare function assertOpf(document: any): any;
+export declare function assertOpf(presentation: any): any;
 export declare function unwrapOpf(value: any): any;
 export declare function parseOpfTransfer(text: string): OpfTransfer;
 export declare function serializeOpfTransfer(
-  document: any,
+  presentation: any,
   options?: {
     scope?: "presentation" | "slide" | "selection";
     slideIndex?: number;
     path?: string;
     format?: "pretty" | "compact" | "markdown";
+    /** Host catalogs: a presentation or slide is embedded (core `embed`) so it renders the same where none is registered. */
+    catalogs?: readonly Catalog[];
   },
 ): string;
 export declare function prepareOpfImport(
@@ -23,5 +26,13 @@ export declare function prepareOpfImport(
     mode?: "insert" | "replace" | "selection";
     slideIndex?: number;
     path?: string;
+    /** Host catalogs, for resolving and copying the inserted slides' records (core `copySlides`). */
+    catalogs?: readonly Catalog[];
   },
-): { document: any; slideIndex: number };
+): {
+  presentation: any;
+  slideIndex: number;
+  /** Records that did not keep their reference while inserting: tell the user. */
+  renamed: CopiedRecordRename[];
+  addedGroups: { name: string; source?: string }[];
+};

package/dist/transfer.js

@@ -1,20 +1,16 @@
-import {
-  applyJsonPatch,
-  createValuePatch,
-  getValueAtPath,
-  validateOpfDocument,
-} from "./index.js";
-import { catalogs } from "@openpresentation/opf";
+import { applyJsonPatch, createValuePatch, getValueAtPath } from "./index.js";
+import { ENGINE_DEFAULT_COLOR_SCHEME, ENGINE_DEFAULT_FONT_SCHEME, ENGINE_DEFAULT_THEME, copySlides, parseReference, resolveReference } from "@openpresentation/opf";
 import { collectReservedPresentationIds, remapSlideTreeIds } from "./presentation-ids.js";
-import { DEFAULT_FONT_SCHEME } from "./font-defaults.js";
+import { checkFormat, firstErrorMessage } from "./checks.js";
+import { mergeCatalogs, prepareSave } from "./catalogs.js";
 export const MAX_OPF_BYTES = 20 * 1024 * 1024;
 const clone = (value) => structuredClone(value);
-export function assertOpf(document) {
-  bounded(document);
-  const result = validateOpfDocument(document);
+export function assertOpf(presentation) {
+  bounded(presentation);
+  const result = checkFormat(presentation);
   if (!result.valid)
-    throw new Error(result.errors[0]?.message ?? "Invalid OPF document.");
-  return document;
+    throw new Error(firstErrorMessage(result, "Invalid OPF document."));
+  return presentation;
 }
 function bounded(value, depth = 0, budget = { remaining: 250000 }) {
   if (depth > 64 || --budget.remaining < 0)
@@ -36,7 +32,7 @@ export function unwrapOpf(value, depth = 0) {
     if (snippet) return unwrapOpf(snippet.value ?? JSON.parse(snippet.source), depth + 1);
   }
   if (value?.opf && typeof value.opf === "object") return unwrapOpf(value.opf, depth + 1);
-  if (value?.document) return unwrapOpf(value.document, depth + 1);
+  if (value?.presentation) return unwrapOpf(value.presentation, depth + 1);
   return value;
 }
 export function parseOpfTransfer(text) {
@@ -63,123 +59,110 @@ export function parseOpfTransfer(text) {
   bounded(value);
   if (value?.slides) {
     assertOpf(value);
-    return { kind: "presentation", value, document: clone(value) };
+    return { kind: "presentation", value, presentation: clone(value) };
   }
-  const document = { slides: Array.isArray(value) ? value : [value] };
-  if (validateOpfDocument(document).valid)
-    return { kind: "slides", value, document };
+  const presentation = { slides: Array.isArray(value) ? value : [value] };
+  if (checkFormat(presentation).valid)
+    return { kind: "slides", value, presentation };
   return { kind: "selection", value };
 }
+/**
+ * The OPF text to copy or save. A presentation or a slide is self-contained: core's `embed` adds every catalog record it
+ * references (from `catalogs`, the host's registered list), so it renders the same where no catalog is registered.
+ */
 export function serializeOpfTransfer(
-  document,
-  { scope = "presentation", slideIndex = 0, path, format = "pretty" } = {},
+  presentation,
+  { scope = "presentation", slideIndex = 0, path, format = "pretty", catalogs } = {},
 ) {
-  let value = document;
+  let value = presentation;
   if (scope === "slide") {
-    if (!document.slides?.[slideIndex])
+    if (!presentation.slides?.[slideIndex])
       throw new Error("Select a slide first.");
-    value = { ...document, slides: [document.slides[slideIndex]] };
+    value = prepareSave({ ...presentation, slides: [presentation.slides[slideIndex]] }, { catalogs }).document;
+  } else if (scope === "presentation") {
+    value = prepareSave(presentation, { catalogs }).document;
   } else if (scope === "selection") {
-    value = getValueAtPath(document, path);
+    value = getValueAtPath(presentation, path);
     if (value === undefined) throw new Error("Select some content first.");
   }
   const json = JSON.stringify(value, null, format === "compact" ? 0 : 2);
   return format === "markdown" ? `\`\`\`json\n${json}\n\`\`\`` : json;
 }
-const catalogKeys = {
-  layouts: "layout",
-  themes: "theme",
-  fontSchemes: "fontScheme",
-  colorSchemes: "colorScheme",
-  narratives: "narrative",
-  languages: "language",
-  tones: "tone",
-  audiences: "audience",
-  purposes: "purpose",
-  socialPlatforms: "platform",
-};
-function themeFor(document, reference) {
-  const id = typeof reference === "string" ? reference : reference?.id;
-  const record =
-    document.catalogs?.themes?.records?.find((item) => item.id === id) ??
-    catalogs.themes.find((item) => item.id === id);
-  return { ...record, ...(typeof reference === "object" ? reference : {}) };
+const RESERVED_GROUPS = new Set(["default", "custom"]);
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+// A reference read out of a record of `group` keeps naming that group's record when it is written on a slide.
+function qualified(value, group) {
+  const qualify = (reference) => {
+    const parsed = typeof reference === "string" ? parseReference(reference) : undefined;
+    return !parsed || parsed.group || RESERVED_GROUPS.has(group) ? reference : `${group}:${parsed.id}`;
+  };
+  if (typeof value === "string") return qualify(value);
+  if (isObject(value) && typeof value.id === "string") return { ...clone(value), id: qualify(value.id) };
+  return value === undefined ? undefined : clone(value);
+}
+
+/**
+ * Freeze the source deck's look on its slides before they move: each slide carries its colour scheme, font scheme, background
+ * and header/footer, so the target deck's design does not restyle it. A value the source takes from its theme is written with
+ * the theme's catalog group; one it takes from the engine default is written only when the target would not use the engine
+ * default too (core's `ENGINE_DEFAULT_*`, never a catalog id).
+ */
+function frozenSlides(incoming, current, catalogs) {
+  const target = isObject(current.design) ? current.design : {};
+  const targetDefault = (key) => target[key] === undefined && target.theme === undefined;
+  return incoming.slides.map((slide) => {
+    // A slide's design cannot set dimensions (a PPTX has one slide size): the inserted slide takes the host deck's.
+    const { dimensions: _deckSize, ...design } = { ...incoming.design, ...slide.design };
+    const theme = typeof design.theme === "string" ? resolveReference(incoming, "themes", design.theme, { catalogs }) : undefined;
+    const record = isObject(theme?.record) ? theme.record : {};
+    const next = { ...design };
+    const freeze = (key, engineDefault) => {
+      if (design[key] !== undefined) return;
+      if (record[key] !== undefined) next[key] = qualified(record[key], theme.group);
+      else if (!targetDefault(key)) next[key] = clone(engineDefault);
+    };
+    freeze("colorScheme", ENGINE_DEFAULT_COLOR_SCHEME);
+    freeze("fontScheme", ENGINE_DEFAULT_FONT_SCHEME);
+    freeze("background", ENGINE_DEFAULT_THEME.background);
+    next.header = design.header ?? false;
+    next.footer = design.footer ?? false;
+    return { ...slide, design: next };
+  });
 }
+
+/**
+ * Apply a parsed transfer to the current document. `mode` "selection" replaces the selected value, "replace" opens the transfer
+ * as the presentation, and "insert" copies its slides in after `slideIndex` with core's `copySlides`: catalog groups match by
+ * `source`, identical records are reused, a differing record is renamed, and `renamed` / `addedGroups` say what changed so the
+ * host can tell the user. Assets and shared datasets come along under free ids. `catalogs` are the host's registered catalogs.
+ * Returns `{ presentation, slideIndex, renamed, addedGroups }`.
+ */
 export function prepareOpfImport(
   current,
   transfer,
-  { mode = "insert", slideIndex = 0, path } = {},
+  { mode = "insert", slideIndex = 0, path, catalogs } = {},
 ) {
   if (mode === "selection") {
-    const document = applyJsonPatch(
+    const presentation = applyJsonPatch(
       current,
       createValuePatch(current, path, transfer.value),
     );
-    assertOpf(document);
-    return { document, slideIndex };
+    assertOpf(presentation);
+    return { presentation, slideIndex, renamed: [], addedGroups: [] };
   }
-  if (!transfer.document)
+  if (!transfer.presentation)
     throw new Error(
       "This is a content fragment. Choose Replace selected content.",
     );
   if (mode === "replace")
-    return { document: assertOpf(clone(transfer.document)), slideIndex: 0 };
+    return { presentation: assertOpf(clone(transfer.presentation)), slideIndex: 0, renamed: [], addedGroups: [] };
   if (mode !== "insert") throw new Error("Unknown import action.");
-  const incoming = clone(transfer.document),
-    document = clone(current);
-  // Freeze the source deck defaults on inserted slides before changing their catalog ids.
-  incoming.slides = incoming.slides.map((slide) => {
-    const design = { ...incoming.design, ...slide.design };
-    const theme = themeFor(incoming, design.theme ?? "minimal");
-    return {
-      ...slide,
-      design: {
-        ...design,
-        theme: design.theme ?? "minimal",
-        colorScheme: design.colorScheme ?? theme.colorScheme ?? "cool-horizon",
-        fontScheme: design.fontScheme ?? theme.fontScheme ?? DEFAULT_FONT_SCHEME,
-        dimensions: design.dimensions ?? theme.dimensions ?? "widescreen",
-        background: design.background ?? theme.background ?? "#FFFFFF",
-        header: design.header ?? false,
-        footer: design.footer ?? false,
-      },
-    };
-  });
-  const mappings = {},
-    assetMap = new Map();
-  let chartTypes = new Map();
-  for (const [kind, catalog] of Object.entries(incoming.catalogs ?? {})) {
-    const existing = document.catalogs?.[kind];
-    if (
-      catalog.source &&
-      existing?.source &&
-      JSON.stringify(catalog.source) !== JSON.stringify(existing.source)
-    )
-      throw new Error(
-        `The ${kind} gallery sources conflict. Open this as a separate presentation instead.`,
-      );
-    if (catalog.source && !existing?.source)
-      throw new Error(
-        `Resolve ${kind} records into this OPF before inserting, or open it as a presentation.`,
-      );
-    const used = new Set(
-      [...(existing?.records ?? []), ...(catalogs[kind] ?? [])].map(
-        (record) => record.id,
-      ),
-    );
-    const names = new Map();
-    for (const record of catalog.records ?? []) {
-      let id = `import-${record.id}`,
-        n = 2;
-      while (used.has(id)) id = `import-${record.id}-${n++}`;
-      used.add(id);
-      names.set(record.id, id);
-      record.id = id;
-    }
-    if (catalogKeys[kind]) mappings[catalogKeys[kind]] = names;
-    if (kind === "chartTypes") chartTypes = names;
-  }
-  const assetIds = new Set(Object.keys(document.assets ?? {}));
+  const list = mergeCatalogs(catalogs);
+  const incoming = clone(transfer.presentation),
+    target = clone(current);
+  incoming.slides = frozenSlides(incoming, current, list);
+  const assetMap = new Map();
+  const assetIds = new Set(Object.keys(target.assets ?? {}));
   for (const id of Object.keys(incoming.assets ?? {})) {
     let next = id,
       n = 2;
@@ -197,11 +180,11 @@ export function prepareOpfImport(
     else if (key === "dataset" && typeof value === "string") usedDatasets.add(value);
   };
   collectDatasets(incoming.slides);
-  const datasetIds = new Set(Object.keys(document.datasets ?? {}));
+  const datasetIds = new Set(Object.keys(target.datasets ?? {}));
   for (const id of usedDatasets) {
     const mine = incoming.datasets && Object.hasOwn(incoming.datasets, id) ? incoming.datasets[id] : undefined;
     if (mine === undefined) continue;
-    if (datasetIds.has(id) && JSON.stringify(document.datasets[id]) === JSON.stringify(mine)) {
+    if (datasetIds.has(id) && JSON.stringify(target.datasets[id]) === JSON.stringify(mine)) {
       datasetMap.set(id, id);
       continue;
     }
@@ -213,70 +196,33 @@ export function prepareOpfImport(
   }
   const rewrite = (value, key = "") => {
     if (Array.isArray(value)) return value.map((child) => rewrite(child, key));
-    if (value && typeof value === "object") {
-      const result = Object.fromEntries(
-        Object.entries(value).map(([childKey, child]) => [
-          childKey,
-          rewrite(child, childKey),
-        ]),
-      );
-      if (key === "socials" && mappings.platform) {
-        for (const [id, child] of Object.entries(result)) {
-          if (mappings.platform.has(id)) {
-            delete result[id];
-            result[mappings.platform.get(id)] = child;
-          }
-        }
-      }
-      if (mappings[key]?.has(value.id)) result.id = mappings[key].get(value.id);
-      if (value.data && chartTypes.has(value.type))
-        result.type = chartTypes.get(value.type);
-      return result;
-    }
+    if (value && typeof value === "object")
+      return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, rewrite(child, childKey)]));
     if (typeof value === "string") {
       if (key === "dataset" && datasetMap.has(value)) return datasetMap.get(value);
-      if (mappings[key]?.has(value)) return mappings[key].get(value);
-      if (
-        ["src", "image", "video", "poster"].includes(key) &&
-        value.startsWith("asset:") &&
-        assetMap.has(value.slice(6))
-      )
+      if (["src", "image", "video", "poster", "background"].includes(key) && value.startsWith("asset:") && assetMap.has(value.slice(6)))
         return `asset:${assetMap.get(value.slice(6))}`;
     }
     return value;
   };
-  const rewritten = rewrite(incoming);
-  if (incoming.catalogs) {
-    document.catalogs ??= {};
-    for (const [kind, catalog] of Object.entries(rewritten.catalogs))
-      document.catalogs[kind] = {
-        ...document.catalogs[kind],
-        ...catalog,
-        records: [
-          ...(document.catalogs[kind]?.records ?? []),
-          ...(catalog.records ?? []),
-        ],
-      };
-  }
+  incoming.slides = rewrite(incoming.slides);
   if (incoming.assets) {
-    document.assets ??= {};
-    for (const [id, asset] of Object.entries(rewritten.assets))
-      document.assets[assetMap.get(id)] =
-        typeof asset === "string" &&
-        asset.startsWith("asset:") &&
-        assetMap.has(asset.slice(6))
-          ? `asset:${assetMap.get(asset.slice(6))}`
-          : asset;
+    target.assets ??= {};
+    for (const [id, asset] of Object.entries(rewrite(incoming.assets)))
+      target.assets[assetMap.get(id)] =
+        typeof asset === "string" && asset.startsWith("asset:") && assetMap.has(asset.slice(6)) ? `asset:${assetMap.get(asset.slice(6))}` : asset;
   }
   for (const [id, next] of datasetMap) {
-    if (document.datasets && Object.hasOwn(document.datasets, next)) continue;
-    document.datasets ??= {};
-    document.datasets[next] = clone(incoming.datasets[id]);
+    if (target.datasets && Object.hasOwn(target.datasets, next)) continue;
+    target.datasets ??= {};
+    target.datasets[next] = clone(incoming.datasets[id]);
   }
-  const ids = new Set(collectReservedPresentationIds(document));
-  for (const slide of rewritten.slides) remapSlideTreeIds(slide, ids);
-  const index = Math.max(0, Math.min(document.slides.length, slideIndex + 1));
-  document.slides.splice(index, 0, ...rewritten.slides);
-  assertOpf(document);
-  return { document, slideIndex: index };
+  const index = Math.max(0, Math.min(target.slides.length, slideIndex + 1));
+  // Core copies the catalog records the slides use and rewrites their references (FA-20).
+  const copied = copySlides(incoming, target, incoming.slides.map((_, at) => at), { catalogs: list, at: index });
+  const presentation = clone(copied.document);
+  const ids = new Set(collectReservedPresentationIds({ ...presentation, slides: presentation.slides.filter((_, at) => !copied.slides.includes(at)) }));
+  for (const at of copied.slides) remapSlideTreeIds(presentation.slides[at], ids);
+  assertOpf(presentation);
+  return { presentation, slideIndex: copied.slides[0] ?? index, renamed: copied.renamed ?? [], addedGroups: copied.addedGroups ?? [] };
 }