@openpresentation/opf-editor 0.12.1 → 0.14.2

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

@@ -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

@@ -26,7 +26,7 @@ export type BackgroundSpec =
 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`. */
 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 {
@@ -45,4 +45,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;

package/dist/background-options.js

@@ -11,7 +11,7 @@ export const IMAGE_BACKGROUND_FITS = Object.freeze(["cover", "contain", "tile"])
 /** Scheme slots and roles a ColorRef may name (the schema's ColorRef enum), besides hex colors and `var:<id>`. */
 export const COLOR_NAMES = Object.freeze([
   "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink",
-  "primary", "secondary", "accent", "background", "surface", "text", "textSecondary",
+  "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary",
 ]);
 /**
  * The 54 DrawingML preset patterns (ECMA-376 ST_PresetPatternVal) by family. PPTX export writes them as
@@ -102,8 +102,8 @@ export function normalizeBackground(spec) {
 }
 
 /** Compute the patch that sets (or, for `null`, removes) the background, without touching a session. Options as `prepareDimensionSwitch` (`slideIndex`, `clearSlideOverrides`). */
-export function prepareBackground(document, spec, options = {}) {
-  return prepareDimensionSwitch(document, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
+export function prepareBackground(presentation, spec, options = {}) {
+  return prepareDimensionSwitch(presentation, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
 }
 
 /** Set the background as one undoable transaction; `null` removes it so the theme's (or the deck's) shows again. */
@@ -116,9 +116,9 @@ export function setBackground(editor, spec, options = {}) {
  * `{ type, slot?, color?, opacity?, angle?, stops?, src?, fit?, preset?, foregroundColor?, backgroundColor?, scope, value }`.
  * `type` is undefined when nothing is set; `scope` is "slide" when the slide sets its own, else "deck".
  */
-export function readBackground(document, { slideIndex } = {}) {
-  const own = slideIndex === undefined ? undefined : document.slides?.[slideIndex]?.design?.background;
-  const value = own !== undefined ? own : document.design?.background;
+export function readBackground(presentation, { slideIndex } = {}) {
+  const own = slideIndex === undefined ? undefined : presentation.slides?.[slideIndex]?.design?.background;
+  const value = own !== undefined ? own : presentation.design?.background;
   const scope = own !== undefined ? "slide" : "deck";
   if (value === undefined) return { scope };
   if (typeof value === "string") return THEME_BACKGROUND_SLOTS.includes(value) ? { type: "theme", slot: value, scope, value } : { type: "solid", color: value, scope, value };

package/dist/block-controls.js

@@ -13,18 +13,18 @@ export function createBlockControls(root, options) {
   function apply(prepared){
     if(!prepared?.changed){cancel();return true;}
     // Retain changes outside the guarded containers and preflight the exact candidate.
-    const candidate=applyJsonPatch(editor.document,prepared.patches);
+    const candidate=applyJsonPatch(editor.presentation,prepared.patches);
     options.validate(candidate);
     committing=true;
     try{cancel();editor.applyPatch(prepared.patches,{source:'canvas-block-edit',rejectInvalid:true});options.onMove?.(prepared.path);([ ...layer.querySelectorAll("[data-block-path]")].find(node=>node.dataset.blockPath===prepared.path)??layer.querySelector('[data-block-add]'))?.focus();options.clearError?.();options.onCommit?.({path:prepared.path,editor});return true;}
     finally{committing=false;}
   }
-  function move(from,to,index,base=editor.document){
+  function move(from,to,index,base=editor.presentation){
     try{return apply(prepareBlockMove(base,from,to,index));}catch(error){cancel();options.onError(error);return false;}
   }
   function open(path){
     if(!options.beforeEdit())return;
-    cancel();returnFocus=doc.activeElement;path=opfPathToJsonPointer(path);const base=editor.document,parts=splitOpfPath(path),container=opfPathToJsonPointer(parts.slice(0,-2)),index=Number(parts.at(-1));
+    cancel();returnFocus=doc.activeElement;path=opfPathToJsonPointer(path);const base=editor.presentation,parts=splitOpfPath(path),container=opfPathToJsonPointer(parts.slice(0,-2)),index=Number(parts.at(-1));
     const source=getValueAtPath(base,[...parts.slice(0,-2),'blocks']);
     if(parts.at(-2)!=='blocks'||!Number.isInteger(index)||index<0||!Array.isArray(source)||index>=source.length){options.onError(new Error('Choose an existing content block.'));return;}
     const count=source.length;
@@ -56,7 +56,7 @@ export function createBlockControls(root, options) {
   }
   function openInsert(containerPath,index) {
     if(!options.beforeEdit())return;
-    cancel();returnFocus=doc.activeElement;const base=editor.document;
+    cancel();returnFocus=doc.activeElement;const base=editor.presentation;
     const containers=listBlockContainers(base,{slideIndex:options.slideIndex(),includeImplicit:true});
     if(!containers.length){options.onError(new Error('No content container is available on this slide.'));return;}
     const requested=containerPath===undefined?containers[0].path:opfPathToJsonPointer(containerPath);
@@ -91,7 +91,7 @@ export function createBlockControls(root, options) {
     panel.append(add,close);panel.onkeydown=event=>{if(event.key==='Escape'){event.preventDefault();event.stopPropagation();cancel();}};
     layer.append(panel);kind.focus();
   }
-  function update(document,nextGeometry){
+  function update(presentation,nextGeometry){
     geometry=nextGeometry;
     if(drag)return;
     cancel();layer.replaceChildren();cells=[];
@@ -99,7 +99,7 @@ export function createBlockControls(root, options) {
     const add=doc.createElement('button');add.type='button';add.textContent='+ Add content';add.setAttribute('aria-label','Add content');add.dataset.blockAdd='';
     add.style.cssText='position:absolute;right:8px;top:8px;pointer-events:auto;padding:5px 9px;background:#f6f3fc;color:#675394;border:1px solid #cfc4e7;border-radius:5px;font:12px system-ui;cursor:pointer';add.onclick=()=>openInsert();layer.append(add);
     for(const flow of geometry.flows??[]){
-      const blocks=getValueAtPath(document,[...splitOpfPath(flow.path),'blocks']);
+      const blocks=getValueAtPath(presentation,[...splitOpfPath(flow.path),'blocks']);
       if(!Array.isArray(blocks)||blocks.length!==flow.itemCount)continue;
       blocks.forEach((block,index)=>{
         const col=flow.columns[index%flow.columns.length],row=flow.rows[Math.floor(index/flow.columns.length)];if(!col||!row)return;
@@ -116,7 +116,7 @@ export function createBlockControls(root, options) {
         node.onkeydown=event=>{if(['ArrowLeft','ArrowUp','ArrowRight','ArrowDown'].includes(event.key)){event.preventDefault();event.stopPropagation();if(!options.beforeEdit())return;const delta=['ArrowLeft','ArrowUp'].includes(event.key)?-1:1;if(index+delta>=0&&index+delta<blocks.length)move(path,container,index+(delta>0?2:-1));}};
         node.ondragstart=event=>{
           if(!options.beforeEdit()){event.preventDefault();return;}
-          cancel();drag={from:path,container,index,base:editor.document,signature:signature(container),cells:[...cells],prepared:null};
+          cancel();drag={from:path,container,index,base:editor.presentation,signature:signature(container),cells:[...cells],prepared:null};
           event.dataTransfer.effectAllowed='move';event.dataTransfer.setData('text/plain',path);
         };
         node.ondragend=()=>{cancel();options.render();};layer.append(node);

package/dist/block-convert.d.ts

@@ -32,7 +32,7 @@ export interface BlockConversionTarget {
   reason?: string;
 }
 export interface PreparedBlockConversion {
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   path: string;
   changed: boolean;
@@ -41,8 +41,8 @@ export interface PreparedBlockConversion {
   from: BlockKind;
   to: BlockKind;
 }
-export interface BlockConversionChange extends Omit<EditorChange, "document" | "patches"> {
-  document: unknown;
+export interface BlockConversionChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   lossless: boolean;
   loss: string[];
@@ -53,12 +53,12 @@ export interface BlockConversionChange extends Omit<EditorChange, "document" | "
 }
 
 /** The single content payload of the block at `path`, or undefined (image-only, groups and blocks with several fields have none to convert). */
-export declare function readBlockContent(document: unknown, path: string | string[]): BlockContent | undefined;
+export declare function readBlockContent(presentation: unknown, path: string | string[]): BlockContent | undefined;
 /** The block that contains a selected path (slides.0.blocks.1.text maps to slides.0.blocks.1), or undefined. */
-export declare function blockPathForSelection(document: unknown, selectedPath: string): string | undefined;
+export declare function blockPathForSelection(presentation: unknown, selectedPath: string): string | undefined;
 /** The kinds the block can convert to, each with its loss report or the reason it is unavailable. */
-export declare function blockConversionTargets(document: unknown, path: string | string[]): BlockConversionTarget[];
+export declare function blockConversionTargets(presentation: unknown, path: string | string[]): BlockConversionTarget[];
 /** Compute the conversion patch without touching a session. Throws `block-not-convertible` for an unsupported pair or content that does not fit. */
-export declare function prepareBlockConversion(document: unknown, path: string | string[], kind: BlockKind, options?: ConvertOptions): PreparedBlockConversion;
+export declare function prepareBlockConversion(presentation: unknown, path: string | string[], kind: BlockKind, options?: ConvertOptions): PreparedBlockConversion;
 /** Convert one block as a single undoable transaction. */
 export declare function convertBlock(editor: EditorSession, path: string | string[], kind: BlockKind, meta?: Record<string, unknown>, options?: ConvertOptions): BlockConversionChange;