@openpresentation/opf-editor 0.11.3 → 0.14.2

package/dist/slides.d.ts

@@ -2,7 +2,7 @@ import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js
 
 /** One section of the deck: a maximal run of consecutive slides sharing a `section` label (or none). */
 export interface SlideSection {
-  /** Position in `listSections(document)`, the id every section operation takes. */
+  /** Position in `listSections(presentation)`, the id every section operation takes. */
   index: number;
   /** The label; undefined for the unnamed run of slides with no label. */
   name: string | undefined;
@@ -15,7 +15,7 @@ export interface SlideSummary { index: number; id?: string; title: string; hidde
 
 /** What every `prepare*` function returns without touching a session. Empty `patches` and `changed: false` mean nothing to do. */
 export interface PreparedSlideChange {
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   /** The slide indices to select after the change (the new, moved or remaining slides). */
@@ -38,8 +38,8 @@ export interface PreparedSlideChange {
   section?: string;
 }
 /** The session change of an applied operation, with the same report fields. One undo step; an unchanged operation commits nothing. */
-export interface SlideChange extends Omit<EditorChange, "document" | "patches">, Omit<PreparedSlideChange, "document" | "patches"> {
-  document: unknown;
+export interface SlideChange extends Omit<EditorChange, "presentation" | "patches">, Omit<PreparedSlideChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
 }
 
@@ -61,36 +61,36 @@ export interface AddSlideOptions {
   record?: Record<string, unknown>;
 }
 
-export declare function listSections(document: unknown): SlideSection[];
-export declare function hasSections(document: unknown): boolean;
-export declare function sectionForSlide(document: unknown, slideIndex: number): SlideSection | undefined;
+export declare function listSections(presentation: unknown): SlideSection[];
+export declare function hasSections(presentation: unknown): boolean;
+export declare function sectionForSlide(presentation: unknown, slideIndex: number): SlideSection | undefined;
 export declare function slideTitle(slide: unknown): string;
-export declare function slideSummaries(document: unknown): SlideSummary[];
+export declare function slideSummaries(presentation: unknown): SlideSummary[];
 
-export declare function prepareAddSlide(document: unknown, options?: AddSlideOptions): PreparedSlideChange;
+export declare function prepareAddSlide(presentation: unknown, options?: AddSlideOptions): PreparedSlideChange;
 export declare function addSlide(editor: EditorSession, options?: AddSlideOptions, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareDuplicateSlides(document: unknown, indices: number | number[], options?: { section?: "keep" }): PreparedSlideChange;
+export declare function prepareDuplicateSlides(presentation: unknown, indices: number | number[], options?: { section?: "keep" }): PreparedSlideChange;
 export declare function duplicateSlides(editor: EditorSession, indices: number | number[], options?: { section?: "keep" }, meta?: Record<string, unknown>): SlideChange;
 /** Throws `cannot-remove-all-slides` when every slide is chosen. */
-export declare function prepareRemoveSlides(document: unknown, indices: number | number[]): PreparedSlideChange;
+export declare function prepareRemoveSlides(presentation: unknown, indices: number | number[]): PreparedSlideChange;
 export declare function removeSlides(editor: EditorSession, indices: number | number[], meta?: Record<string, unknown>): SlideChange;
 /** `to` is the drop gap in the original order (0 to the slide count). */
-export declare function prepareMoveSlides(document: unknown, indices: number | number[], to: number, options?: { section?: MoveSectionMode }): PreparedSlideChange;
+export declare function prepareMoveSlides(presentation: unknown, indices: number | number[], to: number, options?: { section?: MoveSectionMode }): PreparedSlideChange;
 export declare function moveSlides(editor: EditorSession, indices: number | number[], to: number, options?: { section?: MoveSectionMode }, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareMoveSlidesBy(document: unknown, indices: number | number[], delta: number, options?: { section?: MoveSectionMode }): PreparedSlideChange;
+export declare function prepareMoveSlidesBy(presentation: unknown, indices: number | number[], delta: number, options?: { section?: MoveSectionMode }): PreparedSlideChange;
 export declare function moveSlidesBy(editor: EditorSession, indices: number | number[], delta: number, options?: { section?: MoveSectionMode }, meta?: Record<string, unknown>): SlideChange;
 /** `hidden` omitted toggles: all hidden become shown, otherwise all become hidden. */
-export declare function prepareSetHidden(document: unknown, indices: number | number[], hidden?: boolean): PreparedSlideChange;
+export declare function prepareSetHidden(presentation: unknown, indices: number | number[], hidden?: boolean): PreparedSlideChange;
 export declare function setHidden(editor: EditorSession, indices: number | number[], hidden?: boolean, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareSetSection(document: unknown, indices: number | number[], name: string | null): PreparedSlideChange;
+export declare function prepareSetSection(presentation: unknown, indices: number | number[], name: string | null): PreparedSlideChange;
 export declare function setSection(editor: EditorSession, indices: number | number[], name: string | null, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareAddSection(document: unknown, slideIndex: number, name: string): PreparedSlideChange;
+export declare function prepareAddSection(presentation: unknown, slideIndex: number, name: string): PreparedSlideChange;
 export declare function addSection(editor: EditorSession, slideIndex: number, name: string, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareRenameSection(document: unknown, sectionIndex: number, name: string): PreparedSlideChange;
+export declare function prepareRenameSection(presentation: unknown, sectionIndex: number, name: string): PreparedSlideChange;
 export declare function renameSection(editor: EditorSession, sectionIndex: number, name: string, meta?: Record<string, unknown>): SlideChange;
-export declare function prepareRemoveSection(document: unknown, sectionIndex: number, options?: { deleteSlides?: boolean }): PreparedSlideChange;
+export declare function prepareRemoveSection(presentation: unknown, sectionIndex: number, options?: { deleteSlides?: boolean }): PreparedSlideChange;
 export declare function removeSection(editor: EditorSession, sectionIndex: number, options?: { deleteSlides?: boolean }, meta?: Record<string, unknown>): SlideChange;
 /** `to` is a gap among the sections (0 to the section count). */
-export declare function prepareMoveSection(document: unknown, sectionIndex: number, to: number): PreparedSlideChange;
+export declare function prepareMoveSection(presentation: unknown, sectionIndex: number, to: number): PreparedSlideChange;
 export declare function moveSection(editor: EditorSession, sectionIndex: number, to: number, meta?: Record<string, unknown>): SlideChange;
-export declare const SLIDE_OPERATIONS: Readonly<Record<string, (document: unknown, ...args: any[]) => PreparedSlideChange>>;
+export declare const SLIDE_OPERATIONS: Readonly<Record<string, (presentation: unknown, ...args: any[]) => PreparedSlideChange>>;

package/dist/slides.js

@@ -1,6 +1,6 @@
 // Slide management (RR-21): add, duplicate, remove, move, hide and section slides as one validated, undoable
 // change each. Every operation has a `prepare*` form that computes the JSON Patch from a document without
-// touching a session (a dry run: `changed`, `patches` and the resulting `document`), and an apply form that
+// touching a session (a dry run: `changed`, `patches` and the resulting `presentation`), and an apply form that
 // commits that patch through the session as ONE transaction, so a single Undo restores the deck exactly and
 // the preview, thumbnails and PPTX export follow from the document.
 //
@@ -8,10 +8,10 @@
 // the same label form a section (see `listSections`). Slides without a label form an unnamed run. `hidden`
 // is a boolean on the slide. Slide order is the `slides` array, so a move is a remove plus an add of the same
 // slide (removing and re-adding keeps every other slide's patch path stable).
-import { validateOpfDocument } from "./index.js";
 import { checkedDocument, fail, same } from "./edit-helpers.js";
 import { collectReservedPresentationIds, remapSlideTreeIds } from "./presentation-ids.js";
 import { prepareDimensionSwitch } from "./switches.js";
+import { checkFormat } from "./checks.js";
 
 const isIndex = (value) => Number.isInteger(value) && value >= 0;
 const clone = (value) => structuredClone(value);
@@ -19,13 +19,13 @@ const clone = (value) => structuredClone(value);
 function requireEditor(editor) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
 }
-function requireSlides(document) {
-  if (!document || typeof document !== "object" || !Array.isArray(document.slides)) throw fail("invalid-input", "Slide management needs an OPF document with a slides array.");
-  return document.slides;
+function requireSlides(presentation) {
+  if (!presentation || typeof presentation !== "object" || !Array.isArray(presentation.slides)) throw fail("invalid-input", "Slide management needs an OPF document with a slides array.");
+  return presentation.slides;
 }
 /** Validate and sort a list of slide indices; a single index is accepted too. */
-function selectionOf(document, indices, what = "Choose at least one slide.") {
-  const slides = requireSlides(document);
+function selectionOf(presentation, indices, what = "Choose at least one slide.") {
+  const slides = requireSlides(presentation);
   const list = [...new Set(Array.isArray(indices) ? indices : [indices])];
   if (!list.length) throw fail("no-slides-chosen", what);
   for (const index of list) if (!isIndex(index) || index >= slides.length) throw fail("slide-index-out-of-range", `Slide ${index} does not exist.`, { slideIndex: index });
@@ -33,21 +33,21 @@ function selectionOf(document, indices, what = "Choose at least one slide.") {
 }
 const sectionOf = (slide) => (typeof slide?.section === "string" && slide.section.trim() !== "" ? slide.section : undefined);
 
-function unchanged(document, extra = {}) {
-  return { document: clone(document), patches: [], changed: false, selection: [], ...extra };
+function unchanged(presentation, extra = {}) {
+  return { presentation: clone(presentation), patches: [], changed: false, selection: [], ...extra };
 }
 /** Validate the candidate the way every switch does (a valid deck must stay valid) and package the result. */
-function finish(document, patches, extra) {
-  if (!patches.length) return unchanged(document, extra);
-  const before = validateOpfDocument(document);
-  const next = checkedDocument(document, patches, before);
-  return { document: next, patches, changed: true, ...extra };
+function finish(presentation, patches, extra) {
+  if (!patches.length) return unchanged(presentation, extra);
+  const before = checkFormat(presentation);
+  const next = checkedDocument(presentation, patches, before);
+  return { presentation: next, patches, changed: true, ...extra };
 }
 function apply(editor, prepared, meta, action) {
   requireEditor(editor);
-  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 ?? "slides", action });
   return { ...change, ...summary };
 }
@@ -59,8 +59,8 @@ function apply(editor, prepared, meta, action) {
  * of slides with no label is reported with `name: undefined` (`unnamed: true`). `index` is the position in
  * the returned list, the id every section operation takes.
  */
-export function listSections(document) {
-  const slides = requireSlides(document);
+export function listSections(presentation) {
+  const slides = requireSlides(presentation);
   const sections = [];
   slides.forEach((slide, slideIndex) => {
     const name = sectionOf(slide);
@@ -71,20 +71,22 @@ export function listSections(document) {
   return sections;
 }
 /** Whether any slide carries a section label (a deck with none shows no section headers). */
-export function hasSections(document) {
-  return requireSlides(document).some((slide) => sectionOf(slide) !== undefined);
+export function hasSections(presentation) {
+  return requireSlides(presentation).some((slide) => sectionOf(slide) !== undefined);
 }
 /** The section (from `listSections`) that holds a slide. */
-export function sectionForSlide(document, slideIndex) {
-  return listSections(document).find((section) => slideIndex >= section.start && slideIndex < section.start + section.count);
+export function sectionForSlide(presentation, slideIndex) {
+  return listSections(presentation).find((section) => slideIndex >= section.start && slideIndex < section.start + section.count);
 }
 /** The title shown for a slide in navigators and outlines. */
 export function slideTitle(slide) {
-  return typeof slide?.title === "string" && slide.title.trim() ? slide.title : "";
+  // A title is a string or TextRun[] (FA-10): either shows as its plain text.
+  const title = typeof slide?.title === "string" ? slide.title : Array.isArray(slide?.title) ? slide.title.map((run) => (typeof run === "string" ? run : (run?.text ?? ""))).join("") : "";
+  return title.trim() ? title : "";
 }
 /** One row per slide for pickers and navigators: `{ index, id, title, hidden, section, layout }`. */
-export function slideSummaries(document) {
-  return requireSlides(document).map((slide, index) => ({ index, id: slide.id, title: slideTitle(slide), hidden: slide.hidden === true, section: sectionOf(slide), layout: slide.layout }));
+export function slideSummaries(presentation) {
+  return requireSlides(presentation).map((slide, index) => ({ index, id: slide.id, title: slideTitle(slide), hidden: slide.hidden === true, section: sectionOf(slide), layout: slide.layout }));
 }
 
 // --- patches ---------------------------------------------------------------------------------------
@@ -120,9 +122,9 @@ function permutationPatches(moved, order, values) {
 
 // --- add -------------------------------------------------------------------------------------------
 
-function newSlideId(document) {
-  const used = new Set(collectReservedPresentationIds(document));
-  let number = document.slides.length + 1;
+function newSlideId(presentation) {
+  const used = new Set(collectReservedPresentationIds(presentation));
+  let number = presentation.slides.length + 1;
   while (used.has(`slide-${number}`)) number += 1;
   return `slide-${number}`;
 }
@@ -133,11 +135,11 @@ function newSlideId(document) {
  * `title`, `text`, `id`, `section` (default: the section of the slide before it), `slide` (a ready slide to
  * insert, for hosts that build their own), `catalogs`/`record` for catalog lookup (as `prepareDimensionSwitch`).
  */
-export function prepareAddSlide(document, options = {}) {
-  const slides = requireSlides(document);
+export function prepareAddSlide(presentation, options = {}) {
+  const slides = requireSlides(presentation);
   const at = options.at === undefined ? slides.length : options.at;
   if (!isIndex(at) || at > slides.length) throw fail("slide-index-out-of-range", "Add the slide at an index from 0 to the slide count.", { at });
-  const id = options.id ?? options.slide?.id ?? newSlideId(document);
+  const id = options.id ?? options.slide?.id ?? newSlideId(presentation);
   let slide = options.slide ? clone(options.slide) : { id };
   if (!options.slide) {
     if (options.title !== undefined) slide.title = String(options.title);
@@ -149,20 +151,20 @@ export function prepareAddSlide(document, options = {}) {
   slide = withSection(slide, inherited);
   if (options.layout) {
     // Switch the layout on a scratch copy to reuse the placeholder rules and the catalog lookup.
-    const scratch = { ...clone(document), slides: [...clone(slides)] };
+    const scratch = { ...clone(presentation), slides: [...clone(slides)] };
     scratch.slides.splice(at, 0, slide);
     const switched = prepareDimensionSwitch(scratch, "layouts", options.layout, { slideIndex: at, catalogs: options.catalogs, record: options.record });
     const catalogOps = switched.patches.filter((patch) => !patch.path.startsWith("/slides/"));
-    slide = switched.document.slides[at];
+    slide = switched.presentation.slides[at];
     const patches = [...catalogOps, { op: "add", path: slidePointer(at), value: slide }];
-    return finish(document, patches, { action: "add", index: at, id: slide.id, selection: [at], layout: options.layout });
+    return finish(presentation, patches, { action: "add", index: at, id: slide.id, selection: [at], layout: options.layout });
   }
-  return finish(document, [{ op: "add", path: slidePointer(at), value: slide }], { action: "add", index: at, id: slide.id, selection: [at] });
+  return finish(presentation, [{ op: "add", path: slidePointer(at), value: slide }], { action: "add", index: at, id: slide.id, selection: [at] });
 }
 /** Add a slide (see `prepareAddSlide`) as one undoable step. The change reports `index`, `id` and `selection`. */
 export function addSlide(editor, options = {}, meta) {
   requireEditor(editor);
-  return apply(editor, prepareAddSlide(editor.document, options), meta, "add");
+  return apply(editor, prepareAddSlide(editor.presentation, options), meta, "add");
 }
 
 // --- duplicate -------------------------------------------------------------------------------------
@@ -172,11 +174,11 @@ export function addSlide(editor, options = {}, meta) {
  * the slide and any content it identifies (`slide-2` becomes `slide-2-2`, as when pagination copies slides).
  * Copies join the section of the slide they follow unless `options.section` is `"keep"`.
  */
-export function prepareDuplicateSlides(document, indices, options = {}) {
-  const list = selectionOf(document, indices, "Choose at least one slide to duplicate.");
-  const slides = document.slides;
+export function prepareDuplicateSlides(presentation, indices, options = {}) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide to duplicate.");
+  const slides = presentation.slides;
   const at = list.at(-1) + 1;
-  const ids = new Set(collectReservedPresentationIds(document));
+  const ids = new Set(collectReservedPresentationIds(presentation));
   const section = options.section === "keep" ? undefined : sectionOf(slides[at - 1]);
   const copies = list.map((index) => {
     let copy = clone(slides[index]);
@@ -185,11 +187,11 @@ export function prepareDuplicateSlides(document, indices, options = {}) {
     return copy;
   });
   const patches = copies.map((copy, offset) => ({ op: "add", path: slidePointer(at + offset), value: copy }));
-  return finish(document, patches, { action: "duplicate", selection: copies.map((_, offset) => at + offset), range: { start: at, count: copies.length }, ids: copies.map((copy) => copy.id) });
+  return finish(presentation, patches, { action: "duplicate", selection: copies.map((_, offset) => at + offset), range: { start: at, count: copies.length }, ids: copies.map((copy) => copy.id) });
 }
 export function duplicateSlides(editor, indices, options = {}, meta) {
   requireEditor(editor);
-  return apply(editor, prepareDuplicateSlides(editor.document, indices, options), meta, "duplicate");
+  return apply(editor, prepareDuplicateSlides(editor.presentation, indices, options), meta, "duplicate");
 }
 
 // --- remove ----------------------------------------------------------------------------------------
@@ -199,17 +201,17 @@ export function duplicateSlides(editor, indices, options = {}, meta) {
  * `cannot-remove-all-slides`. `selection` is the slide to show next (the one that moves into the first
  * removed position, or the last slide).
  */
-export function prepareRemoveSlides(document, indices) {
-  const list = selectionOf(document, indices, "Choose at least one slide to delete.");
-  const slides = document.slides;
+export function prepareRemoveSlides(presentation, indices) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide to delete.");
+  const slides = presentation.slides;
   if (list.length >= slides.length) throw fail("cannot-remove-all-slides", "A presentation needs at least one slide.", { count: slides.length });
   const patches = [...list].reverse().map((index) => ({ op: "remove", path: slidePointer(index) }));
   const remaining = slides.length - list.length;
-  return finish(document, patches, { action: "remove", removed: list, selection: [Math.min(list[0], remaining - 1)] });
+  return finish(presentation, patches, { action: "remove", removed: list, selection: [Math.min(list[0], remaining - 1)] });
 }
 export function removeSlides(editor, indices, meta) {
   requireEditor(editor);
-  return apply(editor, prepareRemoveSlides(editor.document, indices), meta, "remove");
+  return apply(editor, prepareRemoveSlides(editor.presentation, indices), meta, "remove");
 }
 
 // --- move ------------------------------------------------------------------------------------------
@@ -221,9 +223,9 @@ export function removeSlides(editor, indices, meta) {
  * first slide's when moving to the start), `"keep"` leaves labels alone, a string sets that section and
  * `null` clears it.
  */
-export function prepareMoveSlides(document, indices, to, options = {}) {
-  const list = selectionOf(document, indices, "Choose at least one slide to move.");
-  const slides = document.slides;
+export function prepareMoveSlides(presentation, indices, to, options = {}) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide to move.");
+  const slides = presentation.slides;
   if (!isIndex(to) || to > slides.length) throw fail("slide-index-out-of-range", "Move to a gap from 0 to the slide count.", { to });
   const chosen = new Set(list);
   const rest = slides.map((_, index) => index).filter((index) => !chosen.has(index));
@@ -237,18 +239,18 @@ export function prepareMoveSlides(document, indices, to, options = {}) {
   const values = new Map(list.map((index) => [index, target ? withSection(slides[index], target.name) : slides[index]]));
   const sameOrder = order.every((old, at) => old === at);
   const sameValues = list.every((index) => same(values.get(index), slides[index]));
-  if (sameOrder && sameValues) return unchanged(document, { action: "move", selection: list });
+  if (sameOrder && sameValues) return unchanged(presentation, { action: "move", selection: list });
   // A pure relabel keeps the order: patch the labels in place instead of remove and add.
   const moved = new Set(list);
   const patches = sameOrder
     ? list.flatMap((index) => fieldPatch(slides[index], index, "section", sectionOf(values.get(index))))
     : permutationPatches(moved, order, values);
   const selection = list.map((old) => order.indexOf(old));
-  return finish(document, patches, { action: "move", selection, order });
+  return finish(presentation, patches, { action: "move", selection, order });
 }
 export function moveSlides(editor, indices, to, options = {}, meta) {
   requireEditor(editor);
-  return apply(editor, prepareMoveSlides(editor.document, indices, to, options), meta, "move");
+  return apply(editor, prepareMoveSlides(editor.presentation, indices, to, options), meta, "move");
 }
 
 /**
@@ -256,12 +258,12 @@ export function moveSlides(editor, indices, to, options = {}, meta) {
  * scattered one moves each slide past its neighbour, like Alt+Arrow in a list. Moving past the first or last
  * slide changes nothing (`changed` is false).
  */
-export function prepareMoveSlidesBy(document, indices, delta, options = {}) {
-  const list = selectionOf(document, indices, "Choose at least one slide to move.");
-  const count = document.slides.length;
-  if (!Number.isInteger(delta) || delta === 0) return unchanged(document, { action: "move", selection: list });
+export function prepareMoveSlidesBy(presentation, indices, delta, options = {}) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide to move.");
+  const count = presentation.slides.length;
+  if (!Number.isInteger(delta) || delta === 0) return unchanged(presentation, { action: "move", selection: list });
   const step = Math.sign(delta);
-  const order = document.slides.map((_, index) => index);
+  const order = presentation.slides.map((_, index) => index);
   const selected = new Set(list);
   for (let turn = 0; turn < Math.abs(delta); turn += 1) {
     const sequence = step < 0 ? [...order.keys()] : [...order.keys()].reverse();
@@ -274,8 +276,8 @@ export function prepareMoveSlidesBy(document, indices, delta, options = {}) {
     }
     if (!moved) break;
   }
-  if (order.every((old, at) => old === at)) return unchanged(document, { action: "move", selection: list });
-  const slides = document.slides;
+  if (order.every((old, at) => old === at)) return unchanged(presentation, { action: "move", selection: list });
+  const slides = presentation.slides;
   const mode = options.section === undefined ? "adopt" : options.section;
   // A moved slide adopts the section of the nearest slide that did not move: the one before it in the new order,
   // else the one after it.
@@ -288,11 +290,11 @@ export function prepareMoveSlidesBy(document, indices, delta, options = {}) {
     const name = mode === "keep" ? sectionOf(slides[index]) : mode === "adopt" ? adopted(order.indexOf(index)) : mode === null ? undefined : String(mode);
     return [index, withSection(slides[index], name)];
   }));
-  return finish(document, permutationPatches(selected, order, values), { action: "move", selection: list.map((old) => order.indexOf(old)), order });
+  return finish(presentation, permutationPatches(selected, order, values), { action: "move", selection: list.map((old) => order.indexOf(old)), order });
 }
 export function moveSlidesBy(editor, indices, delta, options = {}, meta) {
   requireEditor(editor);
-  return apply(editor, prepareMoveSlidesBy(editor.document, indices, delta, options), meta, "move");
+  return apply(editor, prepareMoveSlidesBy(editor.presentation, indices, delta, options), meta, "move");
 }
 
 // --- hide ------------------------------------------------------------------------------------------
@@ -302,24 +304,24 @@ export function moveSlidesBy(editor, indices, delta, options = {}, meta) {
  * navigator but is skipped when presenting; showing removes the `hidden` field instead of writing `false`.
  * Without `hidden`, the slides toggle together: all hidden become shown, otherwise all become hidden.
  */
-export function prepareSetHidden(document, indices, hidden) {
-  const list = selectionOf(document, indices, "Choose at least one slide.");
-  const slides = document.slides;
+export function prepareSetHidden(presentation, indices, hidden) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide.");
+  const slides = presentation.slides;
   const value = hidden === undefined ? !list.every((index) => slides[index].hidden === true) : Boolean(hidden);
   const patches = list.flatMap((index) => fieldPatch(slides[index], index, "hidden", value ? true : undefined));
   // A stored `hidden: false` counts as shown; showing it removes the field, hiding replaces it.
-  return finish(document, patches, { action: value ? "hide" : "show", hidden: value, selection: list });
+  return finish(presentation, patches, { action: value ? "hide" : "show", hidden: value, selection: list });
 }
 export function setHidden(editor, indices, hidden, meta) {
   requireEditor(editor);
-  const prepared = prepareSetHidden(editor.document, indices, hidden);
+  const prepared = prepareSetHidden(editor.presentation, indices, hidden);
   return apply(editor, prepared, meta, prepared.action);
 }
 
 // --- sections --------------------------------------------------------------------------------------
 
-function sectionAt(document, sectionIndex) {
-  const section = listSections(document)[sectionIndex];
+function sectionAt(presentation, sectionIndex) {
+  const section = listSections(presentation)[sectionIndex];
   if (!section) throw fail("section-index-out-of-range", `Section ${sectionIndex} does not exist.`, { sectionIndex });
   return section;
 }
@@ -329,24 +331,24 @@ const cleanName = (name) => (typeof name === "string" ? name.trim() : name);
  * Compute giving slides a section label (`name`), or clearing it (`null`). The slides keep their order, so
  * labelling a middle slide splits its section in two runs; use `prepareAddSection` to start a section.
  */
-export function prepareSetSection(document, indices, name) {
-  const list = selectionOf(document, indices, "Choose at least one slide.");
+export function prepareSetSection(presentation, indices, name) {
+  const list = selectionOf(presentation, indices, "Choose at least one slide.");
   const label = name === null || name === undefined ? undefined : cleanName(name);
   if (label === "") throw fail("invalid-section-name", "A section needs a name. Use null to remove the section from a slide.");
-  const patches = list.flatMap((index) => fieldPatch(document.slides[index], index, "section", label));
-  return finish(document, patches, { action: "section", section: label, selection: list });
+  const patches = list.flatMap((index) => fieldPatch(presentation.slides[index], index, "section", label));
+  return finish(presentation, patches, { action: "section", section: label, selection: list });
 }
 export function setSection(editor, indices, name, meta) {
   requireEditor(editor);
-  return apply(editor, prepareSetSection(editor.document, indices, name), meta, "section");
+  return apply(editor, prepareSetSection(editor.presentation, indices, name), meta, "section");
 }
 
 /**
  * Compute starting a section at a slide: that slide and the slides after it up to the end of its current
  * section take `name` (PowerPoint's "Add section", whose header sits above the chosen slide).
  */
-export function prepareAddSection(document, slideIndex, name) {
-  const slides = requireSlides(document);
+export function prepareAddSection(presentation, slideIndex, name) {
+  const slides = requireSlides(presentation);
   if (!isIndex(slideIndex) || slideIndex >= slides.length) throw fail("slide-index-out-of-range", `Slide ${slideIndex} does not exist.`, { slideIndex });
   const label = cleanName(name);
   if (typeof label !== "string" || label === "") throw fail("invalid-section-name", "Give the section a name.");
@@ -358,25 +360,25 @@ export function prepareAddSection(document, slideIndex, name) {
   })();
   const indices = Array.from({ length: end - slideIndex + 1 }, (_, offset) => slideIndex + offset);
   const patches = indices.flatMap((index) => fieldPatch(slides[index], index, "section", label));
-  return finish(document, patches, { action: "add-section", section: label, selection: indices });
+  return finish(presentation, patches, { action: "add-section", section: label, selection: indices });
 }
 export function addSection(editor, slideIndex, name, meta) {
   requireEditor(editor);
-  return apply(editor, prepareAddSection(editor.document, slideIndex, name), meta, "add-section");
+  return apply(editor, prepareAddSection(editor.presentation, slideIndex, name), meta, "add-section");
 }
 
 /** Compute renaming a section (an index from `listSections`) for all of its slides. */
-export function prepareRenameSection(document, sectionIndex, name) {
-  const section = sectionAt(document, sectionIndex);
+export function prepareRenameSection(presentation, sectionIndex, name) {
+  const section = sectionAt(presentation, sectionIndex);
   const label = cleanName(name);
   if (typeof label !== "string" || label === "") throw fail("invalid-section-name", "Give the section a name.");
   const indices = Array.from({ length: section.count }, (_, offset) => section.start + offset);
-  const patches = indices.flatMap((index) => fieldPatch(document.slides[index], index, "section", label));
-  return finish(document, patches, { action: "rename-section", section: label, selection: indices });
+  const patches = indices.flatMap((index) => fieldPatch(presentation.slides[index], index, "section", label));
+  return finish(presentation, patches, { action: "rename-section", section: label, selection: indices });
 }
 export function renameSection(editor, sectionIndex, name, meta) {
   requireEditor(editor);
-  return apply(editor, prepareRenameSection(editor.document, sectionIndex, name), meta, "rename-section");
+  return apply(editor, prepareRenameSection(editor.presentation, sectionIndex, name), meta, "rename-section");
 }
 
 /**
@@ -384,37 +386,37 @@ export function renameSection(editor, sectionIndex, name, meta) {
  * lose their label). With `deleteSlides: true` the slides are deleted too (not allowed when they are every
  * slide of the deck).
  */
-export function prepareRemoveSection(document, sectionIndex, options = {}) {
-  const sections = listSections(document);
-  const section = sectionAt(document, sectionIndex);
+export function prepareRemoveSection(presentation, sectionIndex, options = {}) {
+  const sections = listSections(presentation);
+  const section = sectionAt(presentation, sectionIndex);
   const indices = Array.from({ length: section.count }, (_, offset) => section.start + offset);
-  if (options.deleteSlides) return { ...prepareRemoveSlides(document, indices), action: "remove-section" };
+  if (options.deleteSlides) return { ...prepareRemoveSlides(presentation, indices), action: "remove-section" };
   const previous = sections[sectionIndex - 1];
   const label = previous?.name;
-  const patches = indices.flatMap((index) => fieldPatch(document.slides[index], index, "section", label));
-  return finish(document, patches, { action: "remove-section", section: label, selection: indices });
+  const patches = indices.flatMap((index) => fieldPatch(presentation.slides[index], index, "section", label));
+  return finish(presentation, patches, { action: "remove-section", section: label, selection: indices });
 }
 export function removeSection(editor, sectionIndex, options = {}, meta) {
   requireEditor(editor);
-  return apply(editor, prepareRemoveSection(editor.document, sectionIndex, options), meta, "remove-section");
+  return apply(editor, prepareRemoveSection(editor.presentation, sectionIndex, options), meta, "remove-section");
 }
 
 /**
  * Compute moving a whole section to the gap `to` among the sections (0 to the section count, in the
  * original order of `listSections`). The slides keep their labels.
  */
-export function prepareMoveSection(document, sectionIndex, to) {
-  const sections = listSections(document);
-  const section = sectionAt(document, sectionIndex);
+export function prepareMoveSection(presentation, sectionIndex, to) {
+  const sections = listSections(presentation);
+  const section = sectionAt(presentation, sectionIndex);
   if (!isIndex(to) || to > sections.length) throw fail("section-index-out-of-range", "Move to a gap from 0 to the section count.", { to });
-  const gap = to === sections.length ? document.slides.length : sections[to].start;
+  const gap = to === sections.length ? presentation.slides.length : sections[to].start;
   const indices = Array.from({ length: section.count }, (_, offset) => section.start + offset);
-  const prepared = prepareMoveSlides(document, indices, gap, { section: "keep" });
+  const prepared = prepareMoveSlides(presentation, indices, gap, { section: "keep" });
   return { ...prepared, action: "move-section", section: section.name };
 }
 export function moveSection(editor, sectionIndex, to, meta) {
   requireEditor(editor);
-  return apply(editor, prepareMoveSection(editor.document, sectionIndex, to), meta, "move-section");
+  return apply(editor, prepareMoveSection(editor.presentation, sectionIndex, to), meta, "move-section");
 }
 
 /** Every slide operation as a name to its `prepare` function, for hosts that map a command id to a change. */

package/dist/svelte.js

@@ -52,7 +52,7 @@ export function opfCatalogSelect(node, params) {
     replaceOptions(node, getCatalogOptions(catalogKind, {
       catalogs: nextParams.catalogs,
       catalogSources: nextParams.catalogSources,
-      presentation: nextParams.presentation ?? editor.document
+      presentation: nextParams.presentation ?? editor.presentation
     }));
 
     const sync = () => {

package/dist/switches.d.ts

@@ -2,7 +2,7 @@ import type { ConvertOptions } from "@openpresentation/opf/convert";
 import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
 
 /** The schema's DimensionPreset values: the values of the slide-sizes switch. */
-export declare const SLIDE_SIZE_PRESETS: readonly ["16:9", "4:3", "16:10", "letter", "a4", "widescreen", "standard"];
+export declare const SLIDE_SIZE_PRESETS: readonly ["16:9", "4:3", "16:10", "1:1", "4:5", "9:16", "letter", "a4", "widescreen", "standard"];
 export type SlideSizePreset = (typeof SLIDE_SIZE_PRESETS)[number];
 
 /** Every switchable dimension: the 14 pptx.gallery dimensions, then `slide-sizes` and `purposes`. */
@@ -36,9 +36,9 @@ export interface DimensionSwitchOptions {
   /** Extra caller-loaded catalog records by kind. */
   catalogs?: Record<string, unknown>;
   catalogSources?: Record<string, unknown>;
-  /** themes: also write the theme's color scheme, font scheme, background and dimensions to the deck design (default true). */
+  /** themes: also write the theme's color scheme, font scheme and background (and, for the deck, dimensions) to the design (default true). A slide's design cannot set dimensions. */
   bundle?: boolean;
-  /** Deck-scope design switches (and slide-sizes): remove slide-level values that would hide the switch. */
+  /** Deck-scope design switches: remove slide-level values that would hide the switch. */
   clearSlideOverrides?: boolean;
   /** socials: which document field holds the handle (default "speaker") and, for an array, which entry (default 0). */
   owner?: "speaker" | "organization";
@@ -66,7 +66,7 @@ export interface PreparedDimensionSwitch {
   dimension: SwitchDimension;
   scope: "deck" | "slide" | "block";
   slideIndex?: number;
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   /** Slides whose own design hides a deck-level switch. */
@@ -75,8 +75,8 @@ export interface PreparedDimensionSwitch {
   loss?: string[];
 }
 
-export interface DimensionSwitchChange extends Omit<EditorChange, "document" | "patches"> {
-  document: unknown;
+export interface DimensionSwitchChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   dimension: SwitchDimension;
   scope: "deck" | "slide" | "block";
@@ -87,7 +87,7 @@ export interface DimensionSwitchChange extends Omit<EditorChange, "document" | "
 }
 
 /** Compute and validate the patch for one dimension without changing any session. */
-export declare function prepareDimensionSwitch(document: unknown, dimension: SwitchDimension, value: DimensionSwitchValue, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
+export declare function prepareDimensionSwitch(presentation: unknown, dimension: SwitchDimension, value: DimensionSwitchValue, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
 /** Apply one dimension switch to a session as a single undoable transaction. */
 export declare function switchDimension(editor: EditorSession, dimension: SwitchDimension, value: DimensionSwitchValue, options?: DimensionSwitchOptions): DimensionSwitchChange;
 
@@ -101,9 +101,9 @@ export interface CompatibleChartType extends SwitchOption {
   current: boolean;
 }
 /** Values a picker can offer for a catalog-backed dimension (document inline records, caller catalogs, then the bundled catalog, without duplicates); `blocks` lists the content kinds and `slide-sizes` the presets (labelled with their inches). `purposes` lists the catalog; any other goal text is also a valid switch value. */
-export declare function listSwitchOptions(document: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "catalogs" | "catalogSources">): SwitchOption[];
+export declare function listSwitchOptions(presentation: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "catalogs" | "catalogSources">): SwitchOption[];
 /** Chart types the chart's inline data can use as it is (data-shape compatibility, not an engine-support claim). `path` or `slideIndex` picks the chart. */
-export declare function compatibleChartTypes(document: unknown, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "catalogs" | "catalogSources">): CompatibleChartType[];
+export declare function compatibleChartTypes(presentation: unknown, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "catalogs" | "catalogSources">): CompatibleChartType[];
 /** The value a dimension currently has: `{ value, scope }`, with the catalog id for catalog dimensions. `slide-sizes` reads the deck's design.dimensions, else its theme's (a preset string, or the object for a custom size); `purposes` reads the goal text or Purpose id. */
-export declare function currentSwitchValue(document: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "owner" | "index">): { value: unknown; scope: "deck" | "slide" | "block" };
+export declare function currentSwitchValue(presentation: unknown, dimension: SwitchDimension, options?: Pick<DimensionSwitchOptions, "slideIndex" | "path" | "owner" | "index">): { value: unknown; scope: "deck" | "slide" | "block" };
 export { blockConversionTargets } from "./block-convert.js";