@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/annotations.d.ts

@@ -16,7 +16,7 @@ export interface PreparedAnnotationChange {
   /** The edited container path (the block, `references`, or the run array). */
   path: string;
   /** The validated candidate document. */
-  document: Record<string, unknown>;
+  presentation: Record<string, unknown>;
   /** A test guard plus one replace; empty when nothing changes. */
   patches: JsonPatchOperation[];
   changed: boolean;
@@ -26,7 +26,7 @@ export interface PreparedAnnotationChange {
   ids?: string[];
   removedCites?: string[];
 }
-export type AnnotationChange = (EditorChange & Omit<PreparedAnnotationChange, "document" | "patches">) | PreparedAnnotationChange;
+export type AnnotationChange = (EditorChange & Omit<PreparedAnnotationChange, "presentation" | "patches">) | PreparedAnnotationChange;
 
 export interface CaptionTarget { blockPath: string; field: string; caption?: CaptionSettings }
 export interface CaptionState { blockPath: string; field: string; caption?: CaptionSettings }
@@ -42,30 +42,30 @@ export interface CitationState {
 /** Normalize a caption value to `{ text, position, align }`, or undefined. */
 export declare function normalizeCaption(value: unknown): CaptionSettings | undefined;
 /** Every block (and one-payload slide root) that can carry a caption, with its current caption. */
-export declare function captionTargets(document: unknown): CaptionTarget[];
-export declare function readCaption(document: unknown, blockPath: string | string[]): CaptionState;
-export declare function prepareCaption(document: unknown, blockPath: string | string[], caption: CaptionInput | null): PreparedAnnotationChange;
+export declare function captionTargets(presentation: unknown): CaptionTarget[];
+export declare function readCaption(presentation: unknown, blockPath: string | string[]): CaptionState;
+export declare function prepareCaption(presentation: unknown, blockPath: string | string[], caption: CaptionInput | null): PreparedAnnotationChange;
 export declare function setCaption(editor: EditorSession, blockPath: string | string[], caption: CaptionInput | null, meta?: Record<string, unknown>): AnnotationChange;
 
-export declare function listReferences(document: unknown): ReferenceState[];
-export declare function prepareReference(document: unknown, reference: Reference): PreparedAnnotationChange;
+export declare function listReferences(presentation: unknown): ReferenceState[];
+export declare function prepareReference(presentation: unknown, reference: Reference): PreparedAnnotationChange;
 export declare function addReference(editor: EditorSession, reference: Reference, meta?: Record<string, unknown>): AnnotationChange;
-export declare function prepareReferenceUpdate(document: unknown, id: string, fields: { text?: RichText; url?: string | null }): PreparedAnnotationChange;
+export declare function prepareReferenceUpdate(presentation: unknown, id: string, fields: { text?: RichText; url?: string | null }): PreparedAnnotationChange;
 export declare function updateReference(editor: EditorSession, id: string, fields: { text?: RichText; url?: string | null }, meta?: Record<string, unknown>): AnnotationChange;
 /** Refuses while a run cites the id unless `force`, which also removes those cites. */
-export declare function prepareReferenceRemoval(document: unknown, id: string, options?: { force?: boolean }): PreparedAnnotationChange;
+export declare function prepareReferenceRemoval(presentation: unknown, id: string, options?: { force?: boolean }): PreparedAnnotationChange;
 export declare function removeReference(editor: EditorSession, id: string, options?: { force?: boolean }, meta?: Record<string, unknown>): AnnotationChange;
 
 /** The run at a run path (`slides.0.text.2`): its run array path segments, index and value. */
-export declare function runAt(document: unknown, runPath: string | string[]): { parts: string[]; index: number; run: string | Record<string, unknown> };
-export declare function prepareCite(document: unknown, runPath: string | string[], ids: string | string[]): PreparedAnnotationChange;
+export declare function runAt(presentation: unknown, runPath: string | string[]): { parts: string[]; index: number; run: string | Record<string, unknown> };
+export declare function prepareCite(presentation: unknown, runPath: string | string[], ids: string | string[]): PreparedAnnotationChange;
 export declare function citeRun(editor: EditorSession, runPath: string | string[], ids: string | string[], meta?: Record<string, unknown>): AnnotationChange;
-export declare function prepareUncite(document: unknown, runPath: string | string[]): PreparedAnnotationChange;
+export declare function prepareUncite(presentation: unknown, runPath: string | string[]): PreparedAnnotationChange;
 export declare function unciteRun(editor: EditorSession, runPath: string | string[], meta?: Record<string, unknown>): AnnotationChange;
-export declare function prepareFootnote(document: unknown, runPath: string | string[], text: RichText | null): PreparedAnnotationChange;
+export declare function prepareFootnote(presentation: unknown, runPath: string | string[], text: RichText | null): PreparedAnnotationChange;
 export declare function setFootnote(editor: EditorSession, runPath: string | string[], text: RichText | null, meta?: Record<string, unknown>): AnnotationChange;
 
-/** The deck numbering the engines draw (core `collectCitations`). Throws `annotations-unavailable` on a core without it. */
-export declare function listCitations(document: unknown): CitationState;
+/** The deck numbering the engines draw (core `collectCitations`). */
+export declare function listCitations(presentation: unknown): CitationState;
 /** An ordinary list slide of the cited references (core `referencesSlide`). */
-export declare function referencesSlideFor(document: unknown, options?: { title?: string }): Record<string, unknown>;
+export declare function referencesSlideFor(presentation: unknown, options?: { title?: string }): Record<string, unknown>;

package/dist/annotations.js

@@ -6,15 +6,16 @@
 // canvas redraws and Undo restores the document. Nothing here invents text or ids: a reference is
 // what the caller supplies, and removing a cited reference refuses unless `force` also removes its
 // cites. Numbering comes from core (`collectCitations`), so the panel shows what the engines draw.
-import { getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { checkedDocument, fail } from "./edit-helpers.js";
-// Namespace import: a core published before RR-34 has no citation helpers; the verbs then throw annotations-unavailable.
-import * as opfCore from "@openpresentation/opf";
+import { captionSettings, collectCitations, referencesSlide, walkCitationRuns } from "@openpresentation/opf/composition";
+import { checkFormat } from "./checks.js";
 
 export const CAPTION_POSITIONS = Object.freeze(["below", "above"]);
 export const CAPTION_ALIGNMENTS = Object.freeze(["left", "center", "right"]);
 export const CAPTIONABLE_FIELDS = Object.freeze(["image", "chart", "table", "video"]);
-const TEXT_FIELDS = ["text", "bullets", "items"];
+// Fields whose runs can carry a marker: the slide heading group (FA-10) plus text, quote text, bullets and items.
+const TEXT_FIELDS = ["title", "subtitle", "tag", "text", "bullets", "items"];
 
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const clone = (value) => structuredClone(value);
@@ -24,29 +25,29 @@ function checkEditor(editor) {
   if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
 }
 function commit(editor, prepared, meta = {}) {
-  const { document, patches, ...summary } = prepared;
-  void document;
-  if (!prepared.changed) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   const change = editor.applyPatch(patches, { ...meta, source: meta.source ?? "annotation", action: prepared.action, path: prepared.path });
   return { ...change, ...summary };
 }
 // One guarded replace of the container at `parts`; the candidate must validate when the document did.
-function transaction(document, parts, next, extra) {
-  const current = getValueAtPath(document, parts);
+function transaction(presentation, parts, next, extra) {
+  const current = getValueAtPath(presentation, parts);
   const pointer = opfPathToJsonPointer(parts);
   const changed = JSON.stringify(current) !== JSON.stringify(next);
   const patches = changed ? [{ op: "test", path: pointer, value: clone(current) }, { op: "replace", path: pointer, value: clone(next) }] : [];
-  const before = validateOpfDocument(document);
-  const result = changed ? checkedDocument(document, patches, before) : document;
-  return { ...extra, path: parts.join("."), document: clone(result), patches, changed };
+  const before = checkFormat(presentation);
+  const result = changed ? checkedDocument(presentation, patches, before) : presentation;
+  return { ...extra, path: parts.join("."), presentation: clone(result), patches, changed };
 }
 
 // --- captions -----------------------------------------------------------------------------------
 
-function captionHost(document, blockPath) {
+function captionHost(presentation, blockPath) {
   let parts;
   try { parts = splitOpfPath(blockPath); } catch { throw fail("invalid-path", `Invalid block path ${JSON.stringify(blockPath)}.`); }
-  const host = getValueAtPath(document, parts);
+  const host = getValueAtPath(presentation, parts);
   if (!isObject(host)) throw fail("invalid-path", `No block at ${parts.join(".")}.`);
   if (Array.isArray(host.blocks)) throw fail("caption-unsupported", "A group cannot carry a caption; choose one of its blocks.", { path: parts.join(".") });
   const fields = CAPTIONABLE_FIELDS.filter((field) => host[field] !== undefined);
@@ -56,15 +57,11 @@ function captionHost(document, blockPath) {
 
 /** Normalize a caption value to `{ text, position, align }`, or undefined. */
 export function normalizeCaption(value) {
-  if (typeof opfCore.captionSettings === "function") return opfCore.captionSettings(value);
-  if (value === undefined || value === null) return undefined;
-  if (typeof value === "string" || Array.isArray(value)) return { text: value, position: "below", align: "left" };
-  if (!isObject(value) || value.text === undefined) return undefined;
-  return { text: value.text, position: value.position === "above" ? "above" : "below", align: CAPTION_ALIGNMENTS.includes(value.align) ? value.align : "left" };
+  return captionSettings(value);
 }
 
 /** Every block (and one-payload slide root) that can carry a caption, with its current caption. */
-export function captionTargets(document) {
+export function captionTargets(presentation) {
   const targets = [];
   const visit = (host, path) => {
     if (!isObject(host)) return;
@@ -72,7 +69,7 @@ export function captionTargets(document) {
     const fields = CAPTIONABLE_FIELDS.filter((field) => host[field] !== undefined);
     if (fields.length === 1) targets.push({ blockPath: path, field: fields[0], caption: normalizeCaption(host.caption) });
   };
-  (document?.slides ?? []).forEach((slide, index) => {
+  (presentation?.slides ?? []).forEach((slide, index) => {
     if (!isObject(slide)) return;
     const regions = Object.keys(slide).filter((key) => /^(top|middle|bottom|left|center|right)([+:]|$)/.test(key) && isObject(slide[key])).sort();
     if (regions.length) for (const key of regions) visit(slide[key], `slides.${index}.${key}`);
@@ -82,8 +79,8 @@ export function captionTargets(document) {
 }
 
 /** The caption of the block at `blockPath` (`{ field, caption }`; `caption` undefined when none). */
-export function readCaption(document, blockPath) {
-  const { host, field } = captionHost(document, blockPath);
+export function readCaption(presentation, blockPath) {
+  const { host, field } = captionHost(presentation, blockPath);
   return { blockPath: splitOpfPath(blockPath).join("."), field, caption: normalizeCaption(host.caption) };
 }
 
@@ -91,8 +88,8 @@ export function readCaption(document, blockPath) {
  * Set (a string, TextRun[] or `{ text, position?, align? }`) or remove (`null`) the caption of the
  * block at `blockPath`. A caption at the default position and alignment is stored in its short form.
  */
-export function prepareCaption(document, blockPath, caption) {
-  const { parts, host, field } = captionHost(document, blockPath);
+export function prepareCaption(presentation, blockPath, caption) {
+  const { parts, host, field } = captionHost(presentation, blockPath);
   const next = clone(host);
   if (caption === null || caption === undefined) delete next.caption;
   else {
@@ -102,21 +99,17 @@ export function prepareCaption(document, blockPath, caption) {
       throw fail("invalid-caption", "A caption is a string, TextRun[] or { text, position: below|above, align: left|center|right }.");
     next.caption = settings.position === "below" && settings.align === "left" ? clone(settings.text) : { text: clone(settings.text), position: settings.position, align: settings.align };
   }
-  return transaction(document, parts, next, { action: "caption", field });
+  return transaction(presentation, parts, next, { action: "caption", field });
 }
 export function setCaption(editor, blockPath, caption, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareCaption(editor.document, blockPath, caption), meta);
+  return commit(editor, prepareCaption(editor.presentation, blockPath, caption), meta);
 }
 
 // --- references ---------------------------------------------------------------------------------
 
-function citationsOf(document) {
-  if (typeof opfCore.collectCitations !== "function") throw fail("annotations-unavailable", "The installed @openpresentation/opf has no citation helpers (needs the core that ships RR-34).");
-  return opfCore.collectCitations(document);
-}
-function referenceList(document) {
-  return Array.isArray(document?.references) ? document.references : [];
+function referenceList(presentation) {
+  return Array.isArray(presentation?.references) ? presentation.references : [];
 }
 function checkReference(reference, existing, { allowExisting = false } = {}) {
   if (!isObject(reference) || typeof reference.id !== "string" || !reference.id) throw fail("invalid-reference", "A reference needs a non-empty string id.");
@@ -129,46 +122,46 @@ function checkReference(reference, existing, { allowExisting = false } = {}) {
 }
 
 /** The deck's references with their marker numbers and whether a run cites them. */
-export function listReferences(document) {
-  const list = referenceList(document);
-  const citations = typeof opfCore.collectCitations === "function" ? opfCore.collectCitations(document) : undefined;
+export function listReferences(presentation) {
+  const list = referenceList(presentation);
+  const citations = collectCitations(presentation);
   return list.map((reference, index) => {
-    const note = citations?.references.find((item) => item.id === reference?.id);
+    const note = citations.references.find((item) => item.id === reference?.id);
     return { index, id: reference?.id, text: reference?.text, url: reference?.url, cited: Boolean(note), ...(note ? { number: note.number } : {}) };
   });
 }
 /** Append a reference `{ id, text, url? }`; ids must be unique. */
-export function prepareReference(document, reference) {
-  const list = referenceList(document);
+export function prepareReference(presentation, reference) {
+  const list = referenceList(presentation);
   const next = [...clone(list), checkReference(reference, list)];
-  return transaction(document, ["references"], next, { action: "add-reference", id: reference.id });
+  return transaction(presentation, ["references"], next, { action: "add-reference", id: reference.id });
 }
 export function addReference(editor, reference, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareReference(editor.document, reference), meta);
+  return commit(editor, prepareReference(editor.presentation, reference), meta);
 }
 /** Change the text and/or url of the reference `id` (`url: null` removes the url); the id itself does not change. */
-export function prepareReferenceUpdate(document, id, fields) {
-  const list = referenceList(document), index = list.findIndex((item) => item?.id === id);
+export function prepareReferenceUpdate(presentation, id, fields) {
+  const list = referenceList(presentation), index = list.findIndex((item) => item?.id === id);
   if (index < 0) throw fail("unknown-reference", `No reference '${id}'.`, { id });
   const merged = { ...list[index], ...(fields?.text !== undefined ? { text: fields.text } : {}), ...(fields?.url !== undefined ? { url: fields.url } : {}) };
   if (fields?.url === null) delete merged.url;
   const next = clone(list);
   next[index] = checkReference(merged, list, { allowExisting: true });
-  return transaction(document, ["references"], next, { action: "update-reference", id });
+  return transaction(presentation, ["references"], next, { action: "update-reference", id });
 }
 export function updateReference(editor, id, fields, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareReferenceUpdate(editor.document, id, fields), meta);
+  return commit(editor, prepareReferenceUpdate(editor.presentation, id, fields), meta);
 }
 /** Remove the reference `id`. Refuses while a run cites it unless `force`, which also removes those cites. */
-export function prepareReferenceRemoval(document, id, { force = false } = {}) {
-  const list = referenceList(document), index = list.findIndex((item) => item?.id === id);
+export function prepareReferenceRemoval(presentation, id, { force = false } = {}) {
+  const list = referenceList(presentation), index = list.findIndex((item) => item?.id === id);
   if (index < 0) throw fail("unknown-reference", `No reference '${id}'.`, { id });
   const citing = [];
-  if (typeof opfCore.walkCitationRuns === "function") (document.slides ?? []).forEach((slide, slideIndex) => opfCore.walkCitationRuns(slide, `slides.${slideIndex}`, (entry) => { if (entry.cite.includes(id)) citing.push(entry.path); }));
+  (presentation.slides ?? []).forEach((slide, slideIndex) => walkCitationRuns(slide, `slides.${slideIndex}`, (entry) => { if (entry.cite.includes(id)) citing.push(entry.path); }));
   if (citing.length && !force) throw fail("reference-cited", `Reference '${id}' is cited by ${citing.length} run${citing.length === 1 ? "" : "s"}; pass force to remove the citations too.`, { id, runs: citing });
-  const next = clone(document);
+  const next = clone(presentation);
   next.references = list.filter((_, position) => position !== index);
   if (!next.references.length) delete next.references;
   for (const runPath of citing) {
@@ -177,15 +170,15 @@ export function prepareReferenceRemoval(document, id, { force = false } = {}) {
     runs[runIndex] = withoutCite(run, id);
   }
   const pointer = "";
-  const changed = JSON.stringify(document) !== JSON.stringify(next);
-  const patches = changed ? [{ op: "test", path: pointer, value: clone(document) }, { op: "replace", path: pointer, value: clone(next) }] : [];
-  const before = validateOpfDocument(document);
-  const result = changed ? checkedDocument(document, patches, before) : document;
-  return { action: "remove-reference", id, removedCites: citing, path: "references", document: clone(result), patches, changed };
+  const changed = JSON.stringify(presentation) !== JSON.stringify(next);
+  const patches = changed ? [{ op: "test", path: pointer, value: clone(presentation) }, { op: "replace", path: pointer, value: clone(next) }] : [];
+  const before = checkFormat(presentation);
+  const result = changed ? checkedDocument(presentation, patches, before) : presentation;
+  return { action: "remove-reference", id, removedCites: citing, path: "references", presentation: clone(result), patches, changed };
 }
 export function removeReference(editor, id, options = {}, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareReferenceRemoval(editor.document, id, options), meta);
+  return commit(editor, prepareReferenceRemoval(editor.presentation, id, options), meta);
 }
 
 // --- citations and footnotes --------------------------------------------------------------------
@@ -199,56 +192,56 @@ function withoutCite(run, id) {
 const simplifyRun = (run) => Object.keys(run).length === 1 && typeof run.text === "string" ? run.text : run;
 
 /** The run at `runPath` (`slides.0.text.2`, `slides.0.blocks.1.items.0.text.1`): its run array path, index and value. */
-export function runAt(document, runPath) {
+export function runAt(presentation, runPath) {
   let parts;
   try { parts = splitOpfPath(runPath); } catch { throw fail("invalid-path", `Invalid run path ${JSON.stringify(runPath)}.`); }
   if (parts.length < 3 || !/^(0|[1-9]\d*)$/.test(parts[parts.length - 1])) throw fail("invalid-path", `${parts.join(".")} is not a run path.`);
   const arrayParts = parts.slice(0, -1), index = Number(parts[parts.length - 1]);
-  const runs = getValueAtPath(document, arrayParts);
+  const runs = getValueAtPath(presentation, arrayParts);
   const field = [...arrayParts].reverse().find((segment) => TEXT_FIELDS.includes(segment));
-  if (!Array.isArray(runs) || !field || !(index in runs)) throw fail("invalid-path", `${parts.join(".")} is not a run of a text, bullets or items payload.`);
+  if (!Array.isArray(runs) || !field || !(index in runs)) throw fail("invalid-path", `${parts.join(".")} is not a run of a title, subtitle, tag, text, bullets or items field.`);
   const run = runs[index];
   if (typeof run !== "string" && !(isObject(run) && typeof run.text === "string")) throw fail("invalid-path", `${parts.join(".")} is not a text run.`);
   return { parts: arrayParts, index, run };
 }
 
 /** Make the run at `runPath` cite `ids` (a string or array; replaces its current cites). The ids must exist in references. */
-export function prepareCite(document, runPath, ids) {
+export function prepareCite(presentation, runPath, ids) {
   const list = Array.isArray(ids) ? ids : [ids];
   if (!list.length || !list.every((id) => typeof id === "string" && id)) throw fail("invalid-reference", "cite needs one or more reference ids.");
-  const known = new Set(referenceList(document).map((item) => item?.id));
+  const known = new Set(referenceList(presentation).map((item) => item?.id));
   const unknown = list.filter((id) => !known.has(id));
   if (unknown.length) throw fail("unknown-reference", `Unknown reference${unknown.length === 1 ? "" : "s"} ${unknown.map((id) => `'${id}'`).join(", ")}; add them with addReference first.`, { ids: unknown });
-  const { parts, index, run } = runAt(document, runPath);
-  const runs = clone(getValueAtPath(document, parts));
+  const { parts, index, run } = runAt(presentation, runPath);
+  const runs = clone(getValueAtPath(presentation, parts));
   const next = typeof run === "string" ? { text: run } : { ...clone(run) };
   if (!next.text) throw fail("invalid-run", "An empty run cannot carry a marker.", { path: runPath });
   const unique = [...new Set(list)];
   next.cite = unique.length === 1 ? unique[0] : unique;
   runs[index] = next;
-  return transaction(document, parts, runs, { action: "cite", runPath: [...parts, index].join("."), ids: unique });
+  return transaction(presentation, parts, runs, { action: "cite", runPath: [...parts, index].join("."), ids: unique });
 }
 export function citeRun(editor, runPath, ids, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareCite(editor.document, runPath, ids), meta);
+  return commit(editor, prepareCite(editor.presentation, runPath, ids), meta);
 }
 /** Remove every cite from the run at `runPath`. */
-export function prepareUncite(document, runPath) {
-  const { parts, index, run } = runAt(document, runPath);
-  const runs = clone(getValueAtPath(document, parts));
+export function prepareUncite(presentation, runPath) {
+  const { parts, index, run } = runAt(presentation, runPath);
+  const runs = clone(getValueAtPath(presentation, parts));
   const next = typeof run === "string" ? run : { ...clone(run) };
   if (typeof next === "object") delete next.cite;
   runs[index] = typeof next === "object" ? simplifyRun(next) : next;
-  return transaction(document, parts, runs, { action: "uncite", runPath: [...parts, index].join(".") });
+  return transaction(presentation, parts, runs, { action: "uncite", runPath: [...parts, index].join(".") });
 }
 export function unciteRun(editor, runPath, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareUncite(editor.document, runPath), meta);
+  return commit(editor, prepareUncite(editor.presentation, runPath), meta);
 }
 /** Set (a string or TextRun[]) or remove (`null`) the inline footnote of the run at `runPath`. */
-export function prepareFootnote(document, runPath, text) {
-  const { parts, index, run } = runAt(document, runPath);
-  const runs = clone(getValueAtPath(document, parts));
+export function prepareFootnote(presentation, runPath, text) {
+  const { parts, index, run } = runAt(presentation, runPath);
+  const runs = clone(getValueAtPath(presentation, parts));
   const next = typeof run === "string" ? { text: run } : { ...clone(run) };
   if (text === null || text === undefined) delete next.footnote;
   else {
@@ -257,16 +250,16 @@ export function prepareFootnote(document, runPath, text) {
     next.footnote = clone(text);
   }
   runs[index] = simplifyRun(next);
-  return transaction(document, parts, runs, { action: "footnote", runPath: [...parts, index].join(".") });
+  return transaction(presentation, parts, runs, { action: "footnote", runPath: [...parts, index].join(".") });
 }
 export function setFootnote(editor, runPath, text, meta = {}) {
   checkEditor(editor);
-  return commit(editor, prepareFootnote(editor.document, runPath, text), meta);
+  return commit(editor, prepareFootnote(editor.presentation, runPath, text), meta);
 }
 
 /** The deck numbering the engines draw: notes in number order, cited references, per-slide markers, unused ids. */
-export function listCitations(document) {
-  const citations = citationsOf(document);
+export function listCitations(presentation) {
+  const citations = collectCitations(presentation);
   return {
     notes: citations.notes.map((note) => ({ ...note })),
     references: citations.references.map((note) => ({ ...note })),
@@ -275,7 +268,6 @@ export function listCitations(document) {
   };
 }
 /** An ordinary list slide of the cited references (core `referencesSlide`), ready for `prepareBlockInsert` or a slide insert. */
-export function referencesSlideFor(document, options = {}) {
-  if (typeof opfCore.referencesSlide !== "function") throw fail("annotations-unavailable", "The installed @openpresentation/opf has no referencesSlide (needs the core that ships RR-34).");
-  return opfCore.referencesSlide(document, options);
+export function referencesSlideFor(presentation, options = {}) {
+  return referencesSlide(presentation, options);
 }

package/dist/assets.d.ts

@@ -28,8 +28,8 @@ export interface ImageUploadOptions {
   onAddAsset?: (image: { name: string; mediaType: string; bytes: Uint8Array; size: number; alt?: string; file: unknown }) => string | { src: string } | Promise<string | { src: string }>;
   meta?: Record<string, unknown>;
 }
-export interface ImageUploadChange extends Omit<EditorChange, "document" | "patches"> {
-  document: unknown;
+export interface ImageUploadChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   /** The new asset's id (absent with `onAddAsset`). */
   assetId?: string;
@@ -46,21 +46,21 @@ export declare function checkImageBytes(bytes: Uint8Array, options?: { name?: st
 export declare function readImageFile(file: { name?: string; type?: string; size?: number; arrayBuffer(): Promise<ArrayBuffer> }, options?: { maxBytes?: number }): Promise<ValidatedImage>;
 export declare function imageDataUri(bytes: Uint8Array, mediaType: string): string;
 /** A free asset id for a file name (`logo`, then `logo-2`). */
-export declare function uniqueAssetId(document: unknown, name: string): string;
+export declare function uniqueAssetId(presentation: unknown, name: string): string;
 /** The patch that adds one validated image to `assets`. */
-export declare function prepareImageAsset(document: unknown, image: ValidatedImage, options?: { alt?: string; id?: string }): PreparedImageAsset;
+export declare function prepareImageAsset(presentation: unknown, image: ValidatedImage, options?: { alt?: string; id?: string }): PreparedImageAsset;
 /**
- * Add an uploaded image and use it in one undoable transaction. `build(reference, document)` returns the prepared change
+ * Add an uploaded image and use it in one undoable transaction. `build(reference, presentation)` returns the prepared change
  * that uses the image (any `prepare...` function of this package); its patches run after the asset patch.
  */
 export declare function applyImageUpload(
   editor: EditorSession,
   file: { name?: string; type?: string; size?: number; arrayBuffer(): Promise<ArrayBuffer> },
-  build: (reference: string, document: any) => { patches: JsonPatchOperation[] },
+  build: (reference: string, presentation: any) => { patches: JsonPatchOperation[] },
   options?: ImageUploadOptions,
 ): Promise<ImageUploadChange>;
 /** The patch that sets (or, for an empty string, removes) an asset's alt text. */
-export declare function prepareAssetAlt(document: unknown, assetId: string, alt: string): { assetId: string; patches: JsonPatchOperation[]; changed: boolean };
+export declare function prepareAssetAlt(presentation: unknown, assetId: string, alt: string): { assetId: string; patches: JsonPatchOperation[]; changed: boolean };
 /** Set an asset's alt text as one undoable transaction. */
 export declare function setAssetAlt(editor: EditorSession, assetId: string, alt: string, meta?: Record<string, unknown>): unknown;
 /** The `assets` id a reference names (`asset:logo` gives `logo`), or undefined for a URL or data address. */

package/dist/assets.js

@@ -1,5 +1,5 @@
 // Image assets for the design controls (RR-06): turn a local file into an entry of the document's
-// `assets` map and reference it from a logo, watermark, slide image, background or header/footer
+// `assets` map and reference it from a logo, watermark, background or header/footer
 // zone in the same undoable patch. The file is validated before anything changes: the type must be
 // PNG, JPEG, GIF, WebP or SVG, its bytes must match that type, and its size must be under a cap with a
 // clear error. A host that keeps images elsewhere passes `onAddAsset` and gets the bytes instead.
@@ -90,9 +90,9 @@ export function imageDataUri(bytes, mediaType) {
 }
 
 /** An asset id for a file name that is free in the document (`logo`, then `logo-2`, ...). */
-export function uniqueAssetId(document, name) {
+export function uniqueAssetId(presentation, name) {
   const base = String(name ?? "image").replace(/\.[a-z0-9]+$/i, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "image";
-  const taken = document?.assets && typeof document.assets === "object" ? document.assets : {};
+  const taken = presentation?.assets && typeof presentation.assets === "object" ? presentation.assets : {};
   if (!Object.hasOwn(taken, base)) return base;
   for (let n = 2; ; n += 1) if (!Object.hasOwn(taken, `${base}-${n}`)) return `${base}-${n}`;
 }
@@ -101,19 +101,19 @@ export function uniqueAssetId(document, name) {
  * The patch that adds one validated image to `assets` (the entry is `{ src: dataUri, mediaType, title, alt? }`),
  * with the `asset:<id>` reference to use. Pure: touches no session.
  */
-export function prepareImageAsset(document, image, { alt, id } = {}) {
-  const assetId = id ?? uniqueAssetId(document, image.name);
-  if (document?.assets && Object.hasOwn(document.assets, assetId)) throw fail("asset-exists", `An asset named "${assetId}" already exists.`, { id: assetId });
+export function prepareImageAsset(presentation, image, { alt, id } = {}) {
+  const assetId = id ?? uniqueAssetId(presentation, image.name);
+  if (presentation?.assets && Object.hasOwn(presentation.assets, assetId)) throw fail("asset-exists", `An asset named "${assetId}" already exists.`, { id: assetId });
   const entry = { src: imageDataUri(image.bytes, image.mediaType), mediaType: image.mediaType, title: image.name };
   if (typeof alt === "string" && alt.trim()) entry.alt = alt.trim();
-  const patches = document?.assets && typeof document.assets === "object" && !Array.isArray(document.assets)
+  const patches = presentation?.assets && typeof presentation.assets === "object" && !Array.isArray(presentation.assets)
     ? [{ op: "add", path: opfPathToJsonPointer(["assets", assetId]), value: entry }]
     : [{ op: "add", path: "/assets", value: { [assetId]: entry } }];
   return { id: assetId, reference: `asset:${assetId}`, entry, patches };
 }
 
 /**
- * Add an uploaded image and use it in one undoable transaction. `build(reference, document)` returns the
+ * Add an uploaded image and use it in one undoable transaction. `build(reference, presentation)` returns the
  * prepared change that uses the image (any `prepare...` function of this package, for example
  * `(ref, doc) => prepareLogoVariant(doc, "light", ref)`); its patches run after the asset patch.
  *
@@ -134,23 +134,23 @@ export async function applyImageUpload(editor, file, build, options = {}) {
     if (typeof reference !== "string" || !reference.trim()) throw fail("invalid-asset-reference", "The host's onAddAsset must return the image's reference (a web address or an asset: id).", {});
   } else {
     // Build against the document as it is after the read: the file may have taken a moment to arrive.
-    const added = prepareImageAsset(editor.document, image, { alt });
+    const added = prepareImageAsset(editor.presentation, image, { alt });
     reference = added.reference;
     assetPatches = added.patches;
     assetId = added.id;
   }
-  const document = assetPatches.length ? applyJsonPatch(editor.document, assetPatches) : editor.document;
-  const prepared = build(reference, document);
+  const presentation = assetPatches.length ? applyJsonPatch(editor.presentation, assetPatches) : editor.presentation;
+  const prepared = build(reference, presentation);
   const patches = [...assetPatches, ...prepared.patches];
   const summary = { assetId, reference, changed: patches.length > 0, prepared };
-  if (!patches.length) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  if (!patches.length) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   const change = editor.applyPatch(patches, { ...meta, source: meta?.source ?? "image-upload", ...(assetId ? { assetId } : {}), reference });
   return { ...change, ...summary };
 }
 
 /** The patch that sets (or, for an empty string, removes) an asset's alt text. The asset must exist in `assets`. */
-export function prepareAssetAlt(document, assetId, alt) {
-  const entry = getValueAtPath(document, ["assets", assetId]);
+export function prepareAssetAlt(presentation, assetId, alt) {
+  const entry = getValueAtPath(presentation, ["assets", assetId]);
   if (entry === undefined) throw fail("unknown-asset", `There is no asset named "${assetId}".`, { assetId });
   const object = typeof entry === "string" ? { src: entry } : { ...entry };
   const text = typeof alt === "string" ? alt.trim() : "";
@@ -164,8 +164,8 @@ export function prepareAssetAlt(document, assetId, alt) {
 /** Set an asset's alt text as one undoable transaction. */
 export function setAssetAlt(editor, assetId, alt, meta = {}) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
-  const prepared = prepareAssetAlt(editor.document, assetId, alt);
-  if (!prepared.changed) return { ...prepared, document: editor.document, inversePatches: [], validation: editor.validation };
+  const prepared = prepareAssetAlt(editor.presentation, assetId, alt);
+  if (!prepared.changed) return { ...prepared, presentation: editor.presentation, inversePatches: [], validation: editor.validation };
   return { ...editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? "asset-alt", assetId }), assetId, changed: true };
 }
 

package/dist/background-options.d.ts

@@ -1,9 +1,12 @@
 import type { EditorSession } from "./index.js";
+import type { ImageFocus, ImageOverlay } from "./image-options.js";
 import type { DimensionSwitchChange, DimensionSwitchOptions, PreparedDimensionSwitch } from "./switches.js";
 
 export declare const BACKGROUND_TYPES: readonly ["theme", "solid", "gradient", "image", "pattern"];
 export declare const THEME_BACKGROUND_SLOTS: readonly ["light1", "light2", "dark1", "dark2"];
-export declare const IMAGE_BACKGROUND_FITS: readonly ["cover", "contain", "tile"];
+export declare const IMAGE_BACKGROUND_FITS: readonly ["cover", "contain", "stretch", "tile"];
+/** Image sources the background string shorthand accepts: `asset:`, `https://`, `data:`, `./`, `../`. */
+export declare const IMAGE_SOURCE: RegExp;
 /** Scheme slots and roles a ColorRef may name. */
 export declare const COLOR_NAMES: readonly string[];
 /** The 54 DrawingML preset patterns by family. */
@@ -19,14 +22,14 @@ export type BackgroundSpec =
   | { type: "theme"; slot: (typeof THEME_BACKGROUND_SLOTS)[number] }
   | { type: "solid"; color: string; opacity?: number }
   | { type: "gradient"; gradient: { angle?: number; stops: GradientStop[] }; opacity?: number }
-  | { type: "image"; image: { src: string; fit?: (typeof IMAGE_BACKGROUND_FITS)[number] }; opacity?: number }
+  | { type: "image"; src: string; alt?: string; fit?: (typeof IMAGE_BACKGROUND_FITS)[number]; focus?: ImageFocus; opacity?: number; recolor?: "grayscale" | { dark: string; light: string }; overlay?: ImageOverlay }
   | { type: "pattern"; pattern: { preset: string; foregroundColor?: string; backgroundColor?: string }; opacity?: number };
 
 /** Whether `value` is a ColorRef: a hex color, a scheme slot or role name, or `var:<id>`. */
 export declare function isColorRef(value: unknown): boolean;
-/** Validate a background description and return the value to store (a theme slot or plain hex stays the shorthand string). Throws `invalid-background`. */
+/** Validate a background description and return the value to store (a theme slot, a plain hex color or a plain cover image stays the shorthand string). Throws `invalid-background`. */
 export declare function normalizeBackground(spec: BackgroundSpec): string | Record<string, unknown>;
-export declare function prepareBackground(document: unknown, spec: BackgroundSpec | null, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
+export declare function prepareBackground(presentation: unknown, spec: BackgroundSpec | null, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
 /** Set the background as one undoable transaction; `null` removes it. */
 export declare function setBackground(editor: EditorSession, spec: BackgroundSpec | null, options?: DimensionSwitchOptions): DimensionSwitchChange;
 export interface BackgroundState {
@@ -37,7 +40,11 @@ export interface BackgroundState {
   angle?: number;
   stops?: GradientStop[];
   src?: string;
+  alt?: string;
   fit?: string;
+  focus?: ImageFocus;
+  recolor?: "grayscale" | { dark: string; light: string };
+  overlay?: ImageOverlay;
   preset?: string;
   foregroundColor?: string;
   backgroundColor?: string;
@@ -45,4 +52,4 @@ export interface BackgroundState {
   value?: unknown;
 }
 /** The background that applies at a scope, flattened for a form. */
-export declare function readBackground(document: unknown, options?: { slideIndex?: number }): BackgroundState;
+export declare function readBackground(presentation: unknown, options?: { slideIndex?: number }): BackgroundState;