@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/design-options.d.ts

@@ -7,15 +7,15 @@ export type DesignOptionId =
   | "chartPrimary"
   | "listBullet"
   | "contentBox"
+  | "imageFit"
   | "accentFont"
   | "logo"
   | "organizationLogo"
-  | "watermark"
-  | "slideImage";
+  | "watermark";
 export interface DesignOptionDescriptor {
   id: DesignOptionId;
   label: string;
-  type: "enum" | "boolean" | "font" | "logo" | "organization-logo" | "watermark" | "slide-image";
+  type: "enum" | "boolean" | "font" | "logo" | "organization-logo" | "watermark";
   /** Allowed values of an enum option. */
   values?: readonly string[];
   scopes: ("deck" | "slide")[];
@@ -25,7 +25,7 @@ export declare const DESIGN_OPTIONS: readonly DesignOptionDescriptor[];
 export declare const LOGO_VARIANTS: readonly ["default", "light", "dark", "stacked", "stackedLight", "stackedDark", "icon", "iconLight", "iconDark", "wordmark", "wordmarkLight", "wordmarkDark"];
 export type LogoVariant = (typeof LOGO_VARIANTS)[number];
 /** Every field a header or footer zone can hold. */
-export declare const ZONE_FIELDS: readonly ["logo", "text", "image", "slideNumber", "slideNumberFormat", "date", "dateFormat", "organization", "socials", "section"];
+export declare const ZONE_FIELDS: readonly ["logo", "text", "image", "slideNumber", "slideNumberFormat", "date", "dateFormat", "organization", "speaker", "socials", "section"];
 /** Date format tokens (English names). */
 export declare const DATE_FORMAT_TOKENS: readonly string[];
 export declare const HEADER_FOOTER_ZONES: readonly ["left", "center", "right"];
@@ -53,7 +53,7 @@ export interface PreparedDesignOption {
   /** The logo variant or header/footer zone an edit named. */
   variant?: string;
   zone?: string;
-  document: unknown;
+  presentation: unknown;
   patches: JsonPatchOperation[];
   changed: boolean;
   /** Slides whose own design hides a deck-level change. */
@@ -61,8 +61,8 @@ export interface PreparedDesignOption {
   /** Settings that need a logo the document does not have. */
   warnings: DesignWarning[];
 }
-export interface DesignOptionChange extends Omit<EditorChange, "document" | "patches"> {
-  document: unknown;
+export interface DesignOptionChange extends Omit<EditorChange, "presentation" | "patches"> {
+  presentation: unknown;
   patches: JsonPatchOperation[];
   option: string;
   scope: "deck" | "slide";
@@ -72,17 +72,17 @@ export interface DesignOptionChange extends Omit<EditorChange, "document" | "pat
   warnings: DesignWarning[];
 }
 
-/** Compute the patch for one option. `null` removes it at that scope; object options (watermark, slideImage) merge the fields passed. */
-export declare function prepareDesignOption(document: unknown, option: DesignOptionId, value: unknown, options?: DesignOptionOptions): PreparedDesignOption;
+/** Compute the patch for one option. `null` removes it at that scope; the watermark object merges the fields passed. `imageFit` is the default fit of image blocks (cover, contain, stretch). */
+export declare function prepareDesignOption(presentation: unknown, option: DesignOptionId, value: unknown, options?: DesignOptionOptions): PreparedDesignOption;
 /** Set one option as a single undoable transaction. */
 export declare function setDesignOption(editor: EditorSession, option: DesignOptionId, value: unknown, options?: DesignOptionOptions): DesignOptionChange;
 /** `{ value, scope, inherited }`; scope is "slide", "deck" or "default". */
-export declare function getDesignOption(document: unknown, option: DesignOptionId, options?: Pick<DesignOptionOptions, "slideIndex" | "index">): { value: unknown; scope: "slide" | "deck" | "default"; inherited: boolean };
-export declare function prepareLogoVariant(document: unknown, variant: LogoVariant, source: string | Record<string, unknown> | null, options?: DesignOptionOptions): PreparedDesignOption;
+export declare function getDesignOption(presentation: unknown, option: DesignOptionId, options?: Pick<DesignOptionOptions, "slideIndex" | "index">): { value: unknown; scope: "slide" | "deck" | "default"; inherited: boolean };
+export declare function prepareLogoVariant(presentation: unknown, variant: LogoVariant, source: string | Record<string, unknown> | null, options?: DesignOptionOptions): PreparedDesignOption;
 /** Set or clear one `design.logo` variant; a lone default stays a bare source. */
 export declare function setLogoVariant(editor: EditorSession, variant: LogoVariant, source: string | Record<string, unknown> | null, options?: DesignOptionOptions): DesignOptionChange;
 /** The variants `design.logo` sets at a scope (a bare logo is reported as `default`). */
-export declare function readLogoVariants(document: unknown, options?: Pick<DesignOptionOptions, "slideIndex">): Partial<Record<LogoVariant, unknown>>;
+export declare function readLogoVariants(presentation: unknown, options?: Pick<DesignOptionOptions, "slideIndex">): Partial<Record<LogoVariant, unknown>>;
 export interface HeaderFooterZoneFields {
   logo?: boolean | null;
   text?: string | null;
@@ -92,17 +92,19 @@ export interface HeaderFooterZoneFields {
   date?: boolean | string | null;
   dateFormat?: string | null;
   organization?: boolean | null;
+  /** The first speaker's name and title ("Ada Lovelace, CTO"). */
+  speaker?: boolean | null;
   socials?: boolean | null;
   section?: boolean | null;
 }
-export declare function prepareHeaderFooterZone(document: unknown, which: "header" | "footer", zone: HeaderFooterZone, fields: HeaderFooterZoneFields, options?: DesignOptionOptions): PreparedDesignOption;
+export declare function prepareHeaderFooterZone(presentation: unknown, which: "header" | "footer", zone: HeaderFooterZone, fields: HeaderFooterZoneFields, options?: DesignOptionOptions): PreparedDesignOption;
 /** Merge fields into one header or footer zone; null, false (flags) or "" remove a field, an empty zone and header are removed. A slide's own header replaces the deck's whole one, so the first edit on a slide starts from a copy of the deck's and keeps its other zones. */
 export declare function setHeaderFooterZone(editor: EditorSession, which: "header" | "footer", zone: HeaderFooterZone, fields: HeaderFooterZoneFields, options?: DesignOptionOptions): DesignOptionChange;
 /** One zone's fields as they apply at a scope: the slide's own header or footer when it has one, else the deck's. */
-export declare function readHeaderFooterZone(document: unknown, which: "header" | "footer", zone: HeaderFooterZone, options?: Pick<DesignOptionOptions, "slideIndex">): HeaderFooterZoneFields;
+export declare function readHeaderFooterZone(presentation: unknown, which: "header" | "footer", zone: HeaderFooterZone, options?: Pick<DesignOptionOptions, "slideIndex">): HeaderFooterZoneFields;
 /** Whether the scope sets the header or footer itself (`own`), shows the deck's (`inherited`) or hides it with `false` (`hidden`). */
-export declare function headerFooterState(document: unknown, which: "header" | "footer", options?: Pick<DesignOptionOptions, "slideIndex">): { own: boolean; inherited: boolean; hidden: boolean };
+export declare function headerFooterState(presentation: unknown, which: "header" | "footer", options?: Pick<DesignOptionOptions, "slideIndex">): { own: boolean; inherited: boolean; hidden: boolean };
 /** Whether a logo resolves for the slide: slide design, deck design, then the primary organization. */
-export declare function hasResolvableLogo(document: unknown, slideIndex: number): boolean;
-/** Settings that need content the document does not have: a logo (zones with `logo: true`, picture bullets), or an organization or its social profiles for zones that show them. */
-export declare function designWarnings(document: unknown, slideIndex?: number): DesignWarning[];
+export declare function hasResolvableLogo(presentation: unknown, slideIndex: number): boolean;
+/** Settings that need content the document does not have: a logo (zones with `logo: true`, picture bullets), an organization or its social profiles, or a named speaker, for zones that show them. */
+export declare function designWarnings(presentation: unknown, slideIndex?: number): DesignWarning[];

package/dist/design-options.js

@@ -3,8 +3,9 @@
 // by default or on one slide with `slideIndex`, exactly like the dimension switches. Every
 // function has a `prepare…` form that returns the patch without touching a session, and a
 // session form that commits it with `meta.source: "design-option"`.
-import { getValueAtPath, opfPathToJsonPointer, validateOpfDocument } from "./index.js";
+import { getValueAtPath, opfPathToJsonPointer } from "./index.js";
 import { checkedDocument, designPatches, fail, same } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
 
 /** The `design.logo` variant slots of a LogoSet, in schema order. */
 export const LOGO_VARIANTS = Object.freeze([
@@ -23,8 +24,8 @@ export const LOGO_VARIANTS = Object.freeze([
 ]);
 export const HEADER_FOOTER_ZONES = Object.freeze(["left", "center", "right"]);
 // Flag fields of a header/footer zone: false is stored as "absent" (so is a `date` of false).
-const ZONE_FLAGS = ["logo", "slideNumber", "organization", "socials", "section"];
-export const ZONE_FIELDS = Object.freeze(["logo", "text", "image", "slideNumber", "slideNumberFormat", "date", "dateFormat", "organization", "socials", "section"]);
+const ZONE_FLAGS = ["logo", "slideNumber", "organization", "speaker", "socials", "section"];
+export const ZONE_FIELDS = Object.freeze(["logo", "text", "image", "slideNumber", "slideNumberFormat", "date", "dateFormat", "organization", "speaker", "socials", "section"]);
 /** Date tokens a `dateFormat` understands (English names, independent of the host locale). */
 export const DATE_FORMAT_TOKENS = Object.freeze(["yyyy", "yy", "MMMM", "MMM", "MM", "M", "dd", "d", "EEEE", "EEE"]);
 const ISO_DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
@@ -32,7 +33,7 @@ const ISO_DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
 // Friendly validation of one zone field before the schema sees it.
 function checkZoneField(key, value) {
   const bad = (message) => fail("invalid-design-value", message, { field: key, value });
-  if (["logo", "slideNumber", "organization", "socials", "section"].includes(key) && typeof value !== "boolean") throw bad(`${key} is true or false.`);
+  if (ZONE_FLAGS.includes(key) && typeof value !== "boolean") throw bad(`${key} is true or false.`);
   if (key === "text" && typeof value !== "string") throw bad("Text is a string.");
   if (key === "image" && typeof value !== "string" && !isObject(value)) throw bad("An image is a source, an asset reference or an asset object.");
   if (key === "slideNumberFormat" && (typeof value !== "string" || !value.includes("{current}"))) throw bad("The slide number format must contain {current}, for example Page {current} of {total}.");
@@ -40,19 +41,18 @@ function checkZoneField(key, value) {
   if (key === "dateFormat" && (typeof value !== "string" || !value.trim())) throw bad(`A date format uses tokens such as ${DATE_FORMAT_TOKENS.join(", ")}.`);
 }
 
-const SLIDE_IMAGE_POSITIONS = ["background", "top", "bottom", "left", "right"];
-
 const ENUMS = Object.freeze({
   titleAlignment: ["left", "center", "right"],
   contentAlignment: ["left", "center", "right"],
   contentDirection: ["horizontal", "vertical"],
   chartPrimary: ["none", "top", "bottom", "left", "right"],
   listBullet: ["character", "image"],
+  imageFit: ["cover", "contain", "stretch"],
 });
 
 /**
  * Descriptors for every design option, in the order a panel shows them. `type` is "enum", "boolean",
- * "font", "asset", "logo", "watermark", "slide-image" or "organization-logo"; `scopes` says whether
+ * "font", "asset", "logo", "watermark" or "organization-logo"; `scopes` says whether
  * the option applies to the deck, one slide, or both.
  */
 export const DESIGN_OPTIONS = Object.freeze([
@@ -62,37 +62,42 @@ export const DESIGN_OPTIONS = Object.freeze([
   { id: "chartPrimary", label: "Primary chart position", type: "enum", values: ENUMS.chartPrimary, scopes: ["deck", "slide"], path: "design.chartPrimary" },
   { id: "listBullet", label: "List bullets", type: "enum", values: ENUMS.listBullet, scopes: ["deck", "slide"], path: "design.listBullet" },
   { id: "contentBox", label: "Content box", type: "boolean", scopes: ["deck", "slide"], path: "design.contentBox" },
-  { id: "accentFont", label: "Accent font", type: "font", scopes: ["deck", "slide"], path: "design.fontScheme.accent.family" },
+  { id: "imageFit", label: "Image fit", type: "enum", values: ENUMS.imageFit, scopes: ["deck", "slide"], path: "design.imageFit" },
+  { id: "accentFont", label: "Accent font", type: "font", scopes: ["deck", "slide"], path: "design.fontScheme.accent" },
   { id: "logo", label: "Logo", type: "logo", scopes: ["deck", "slide"], path: "design.logo" },
   { id: "organizationLogo", label: "Organization logo", type: "organization-logo", scopes: ["deck"], path: "organization.logo" },
   { id: "watermark", label: "Watermark", type: "watermark", scopes: ["deck", "slide"], path: "design.watermark" },
-  { id: "slideImage", label: "Slide image", type: "slide-image", scopes: ["deck", "slide"], path: "design.slideImage" },
 ]);
 const BY_ID = Object.fromEntries(DESIGN_OPTIONS.map((option) => [option.id, option]));
 
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 
-function scopeOf(document, option, options) {
+function scopeOf(presentation, option, options) {
   const index = options.slideIndex;
   if (index === undefined) return { scope: "deck", base: [] };
   if (!BY_ID[option]?.scopes.includes("slide")) throw fail("invalid-scope", `${BY_ID[option]?.label ?? option} applies to the whole presentation, not one slide.`, { option });
-  if (!Number.isInteger(index) || !document.slides?.[index]) throw fail("slide-index-out-of-range", "Choose an existing slide for this option.", { slideIndex: index });
+  if (!Number.isInteger(index) || !presentation.slides?.[index]) throw fail("slide-index-out-of-range", "Choose an existing slide for this option.", { slideIndex: index });
   return { scope: "slide", base: ["slides", String(index)], slideIndex: index };
 }
 
-function ownDesign(document, base) {
-  const design = getValueAtPath(document, base.length ? [...base, "design"] : ["design"]);
+function ownDesign(presentation, base) {
+  const design = getValueAtPath(presentation, base.length ? [...base, "design"] : ["design"]);
   return isObject(design) ? design : {};
 }
 
-function primaryOrganization(document) {
-  const list = Array.isArray(document.organization) ? document.organization : document.organization ? [document.organization] : [];
+function primaryOrganization(presentation) {
+  const list = Array.isArray(presentation.organization) ? presentation.organization : presentation.organization ? [presentation.organization] : [];
   return list.find((entry) => entry?.role === "primary") ?? list[0];
 }
 
+function firstSpeaker(presentation) {
+  const list = Array.isArray(presentation.speaker) ? presentation.speaker : presentation.speaker ? [presentation.speaker] : [];
+  return list[0];
+}
+
 /** Whether a logo resolves for the slide: slide design, then deck design, then the primary organization. */
-export function hasResolvableLogo(document, slideIndex) {
-  return Boolean(document.slides?.[slideIndex]?.design?.logo ?? document.design?.logo ?? primaryOrganization(document)?.logo);
+export function hasResolvableLogo(presentation, slideIndex) {
+  return Boolean(presentation.slides?.[slideIndex]?.design?.logo ?? presentation.design?.logo ?? primaryOrganization(presentation)?.logo);
 }
 
 /**
@@ -100,21 +105,23 @@ export function hasResolvableLogo(document, slideIndex) {
  * footer zone with `logo: true`, or picture bullets. The renderers fall back to a glyph or report
  * unresolved content; the editor surfaces it before export.
  */
-export function designWarnings(document, slideIndex = 0) {
-  const slide = document.slides?.[slideIndex];
-  const design = { ...document.design, ...slide?.design };
+export function designWarnings(presentation, slideIndex = 0) {
+  const slide = presentation.slides?.[slideIndex];
+  const design = { ...presentation.design, ...slide?.design };
   const warnings = [];
-  const hasLogo = hasResolvableLogo(document, slideIndex);
+  const hasLogo = hasResolvableLogo(presentation, slideIndex);
   for (const which of ["header", "footer"])
     for (const zone of HEADER_FOOTER_ZONES)
       if (!hasLogo && isObject(design[which]) && design[which][zone]?.logo === true)
         warnings.push({ code: "unresolved-logo", path: `design.${which}.${zone}.logo`, message: `The ${which} ${zone} zone shows the logo, but no logo is set. Add a logo or an organization logo.` });
-  const organization = primaryOrganization(document);
+  const organization = primaryOrganization(presentation);
   for (const which of ["header", "footer"])
     for (const zone of HEADER_FOOTER_ZONES) {
       const item = isObject(design[which]) ? design[which][zone] : undefined;
       if (item?.organization === true && !organization)
         warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.organization`, message: `The ${which} ${zone} zone shows the organization, but the presentation has none.` });
+      if (item?.speaker === true && !firstSpeaker(presentation)?.name)
+        warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.speaker`, message: `The ${which} ${zone} zone shows the speaker, but the presentation has no named speaker.` });
       if (item?.socials === true && !organization?.socials)
         warnings.push({ code: "unresolved-content", path: `design.${which}.${zone}.socials`, message: `The ${which} ${zone} zone shows social profiles, but the organization has none.` });
     }
@@ -123,17 +130,17 @@ export function designWarnings(document, slideIndex = 0) {
   return warnings;
 }
 
-function shadowed(document, keys) {
-  return (document.slides ?? []).flatMap((slide, index) => (keys.some((key) => slide?.design?.[key] !== undefined) ? [index] : []));
+function shadowed(presentation, keys) {
+  return (presentation.slides ?? []).flatMap((slide, index) => (keys.some((key) => slide?.design?.[key] !== undefined) ? [index] : []));
 }
 
-function finish(document, patches, extra) {
-  const before = validateOpfDocument(document);
-  const next = checkedDocument(document, patches, before);
+function finish(presentation, patches, extra) {
+  const before = checkFormat(presentation);
+  const next = checkedDocument(presentation, patches, before);
   const slideIndex = extra.slideIndex;
   return {
     ...extra,
-    document: structuredClone(next),
+    presentation: structuredClone(next),
     patches,
     changed: patches.length > 0,
     warnings: designWarnings(next, slideIndex ?? 0),
@@ -145,49 +152,37 @@ function finish(document, patches, extra) {
 function mergedWatermark(existing, value) {
   if (value === null || value === false) return value;
   if (typeof value === "string") return value;
-  if (!isObject(value)) throw fail("invalid-design-value", "A watermark is false, an image source or { src, opacity }.", { value });
+  if (!isObject(value)) throw fail("invalid-design-value", "A watermark is false, an image source, { src, opacity } or { text, opacity }.", { value });
   const base = typeof existing === "string" ? { src: existing } : isObject(existing) ? { ...existing } : {};
   const merged = { ...base };
   for (const [key, entry] of Object.entries(value)) {
     if (entry === null || entry === undefined) delete merged[key];
     else merged[key] = entry;
   }
+  // FA-13: a watermark is an image (src) or a text stamp (text), never both: the field set last replaces the other.
+  if (value.text !== undefined && value.text !== null && value.src === undefined) delete merged.src;
+  else if (value.src !== undefined && value.src !== null && value.text === undefined) delete merged.text;
+  if (merged.text !== undefined && (typeof merged.text !== "string" || !merged.text.trim())) throw fail("invalid-design-value", "Watermark text is a non-empty string.", { value });
   if (merged.opacity !== undefined && (typeof merged.opacity !== "number" || merged.opacity < 0 || merged.opacity > 1))
     throw fail("invalid-design-value", "Watermark opacity is a number from 0 to 1.", { value });
-  if (merged.src === undefined && Object.keys(merged).length) throw fail("invalid-design-value", "Choose the watermark image before setting its opacity.", { value });
+  if (merged.src === undefined && merged.text === undefined && Object.keys(merged).length) throw fail("invalid-design-value", "Choose the watermark image before setting its opacity (or give it text instead).", { value });
   if (Object.keys(merged).length === 1 && typeof merged.src === "string") return merged.src;
   if (!Object.keys(merged).length) return null;
   if (merged.opacity === undefined) throw fail("invalid-design-value", "Set an opacity from 0 to 1 for the watermark.", { value });
   return merged;
 }
 
-function mergedSlideImage(existing, value) {
-  if (value === null) return null;
-  if (typeof value === "string") return value;
-  if (!isObject(value)) throw fail("invalid-design-value", "A slide image is an image source or an object with a position.", { value });
-  const base = typeof existing === "string" ? { src: existing } : isObject(existing) ? (existing.position ? { ...existing } : { src: existing.src, ...(existing.alt ? { alt: existing.alt } : {}) }) : {};
-  const merged = { ...base };
-  for (const [key, entry] of Object.entries(value)) {
-    if (entry === null || entry === undefined) delete merged[key];
-    else merged[key] = entry;
-  }
-  if (merged.src === undefined) delete merged.src;
-  if (merged.position === undefined) merged.position = "background";
-  if (!SLIDE_IMAGE_POSITIONS.includes(merged.position)) throw fail("invalid-design-value", `Slide image position is one of ${SLIDE_IMAGE_POSITIONS.join(", ")}.`, { value });
-  return merged;
-}
-
-function fontSchemeWithAccent(document, base, family) {
+function fontSchemeWithAccent(presentation, base, family) {
   // The slide's own font scheme, else the deck's: an object form is kept with its overrides.
-  const own = ownDesign(document, base).fontScheme;
-  const inherited = base.length ? document.design?.fontScheme : undefined;
+  const own = ownDesign(presentation, base).fontScheme;
+  const inherited = base.length ? presentation.design?.fontScheme : undefined;
   const source = own !== undefined ? own : inherited;
   const object = typeof source === "string" ? { id: source } : isObject(source) ? structuredClone(source) : {};
   if (family === null) {
     delete object.accent;
   } else {
     if (typeof family !== "string" || !family.trim()) throw fail("invalid-design-value", "Accent font is a non-empty family name, or null to clear it.", { value: family });
-    object.accent = { ...(isObject(object.accent) ? object.accent : {}), family: family.trim() };
+    object.accent = family.trim();
   }
   const keys = Object.keys(object);
   if (!keys.length) return null;
@@ -211,23 +206,23 @@ function collapseLogo(set) {
 
 /**
  * Compute the patch that sets one design option, without touching any session. `value === null`
- * removes the option at that scope so it is inherited again. Object-valued options (`watermark`,
- * `slideImage`) merge the fields you pass into the existing object; a `null` field removes it.
+ * removes the option at that scope so it is inherited again. The object-valued `watermark` merges the
+ * fields you pass into the existing object; a `null` field removes it.
  * Options: `slideIndex` (one slide instead of the deck), `clearSlideOverrides` (deck scope: also
  * remove slide-level values that hide it) and `index` (organizationLogo with several
  * organizations).
  */
-export function prepareDesignOption(document, option, value, options = {}) {
+export function prepareDesignOption(presentation, option, value, options = {}) {
   const descriptor = BY_ID[option];
   if (!descriptor) throw fail("unknown-design-option", `Unknown design option: ${option}. Use one of ${DESIGN_OPTIONS.map((entry) => entry.id).join(", ")}.`, { option });
-  if (!isObject(document)) throw fail("invalid-input", "Design options need an OPF document object.");
+  if (!isObject(presentation)) throw fail("invalid-input", "Design options need an OPF document object.");
   if (value === undefined) throw fail("invalid-design-value", "Pass a value, or null to remove the option.", { option });
-  const { scope, base, slideIndex } = scopeOf(document, option, options);
+  const { scope, base, slideIndex } = scopeOf(presentation, option, options);
   let patches = [];
   let keys = [];
 
   if (descriptor.type === "organization-logo") {
-    const organization = document.organization;
+    const organization = presentation.organization;
     const index = options.index ?? 0;
     const owner = Array.isArray(organization) ? organization[index] : organization;
     if (!isObject(owner)) throw fail("missing-owner", "Add an organization to the document before setting its logo.", { option });
@@ -245,38 +240,35 @@ export function prepareDesignOption(document, option, value, options = {}) {
       if (value !== null && typeof value !== "boolean") throw fail("invalid-design-value", `${descriptor.label} is true or false.`, { option, value });
       entries = { [option]: value };
     } else if (descriptor.type === "font") {
-      entries = { fontScheme: fontSchemeWithAccent(document, base, value) };
+      entries = { fontScheme: fontSchemeWithAccent(presentation, base, value) };
     } else if (descriptor.type === "logo") {
       if (value !== null && typeof value !== "string" && !isObject(value)) throw fail("invalid-design-value", "A logo is an image source, an asset object or a set of logo variants.", { option });
       entries = { logo: value };
-    } else if (descriptor.type === "watermark") {
-      const existing = ownDesign(document, base).watermark;
-      entries = { watermark: mergedWatermark(existing, value) };
     } else {
-      const existing = ownDesign(document, base).slideImage;
-      entries = { slideImage: mergedSlideImage(existing, value) };
+      const existing = ownDesign(presentation, base).watermark;
+      entries = { watermark: mergedWatermark(existing, value) };
     }
     keys = Object.keys(entries);
-    patches = designPatches(document, base, entries);
+    patches = designPatches(presentation, base, entries);
   }
 
   let shadowedSlides = [];
   if (scope === "deck" && keys.length) {
-    shadowedSlides = shadowed(document, keys);
+    shadowedSlides = shadowed(presentation, keys);
     if (options.clearSlideOverrides) {
       for (const index of shadowedSlides)
         for (const key of keys)
-          if (document.slides[index].design?.[key] !== undefined) patches.push({ op: "remove", path: opfPathToJsonPointer(["slides", String(index), "design", key]) });
+          if (presentation.slides[index].design?.[key] !== undefined) patches.push({ op: "remove", path: opfPathToJsonPointer(["slides", String(index), "design", key]) });
       shadowedSlides = [];
     }
   }
-  return finish(document, patches, { option, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: shadowedSlides });
+  return finish(presentation, patches, { option, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: shadowedSlides });
 }
 
 function apply(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 ?? "design-option", option: prepared.option, scope: prepared.scope });
   return { ...change, ...summary };
 }
@@ -289,30 +281,30 @@ function checkEditor(editor) {
 export function setDesignOption(editor, option, value, options = {}) {
   checkEditor(editor);
   const { meta, ...rest } = options;
-  return apply(editor, prepareDesignOption(editor.document, option, value, rest), meta);
+  return apply(editor, prepareDesignOption(editor.presentation, option, value, rest), meta);
 }
 
 /**
  * Read one design option for a panel: `{ value, scope, inherited }` where `scope` is "slide" when the
  * slide's own design sets it, "deck" when the deck does, and "default" when neither does.
- * `accentFont` reads the family; `organizationLogo` reads the organization.
+ * `accentFont` reads the family name; `organizationLogo` reads the organization.
  */
-export function getDesignOption(document, option, options = {}) {
+export function getDesignOption(presentation, option, options = {}) {
   const descriptor = BY_ID[option];
   if (!descriptor) throw fail("unknown-design-option", `Unknown design option: ${option}.`, { option });
   if (descriptor.type === "organization-logo") {
-    const organization = document.organization;
+    const organization = presentation.organization;
     const owner = Array.isArray(organization) ? organization[options.index ?? 0] : organization;
     return { value: owner?.logo, scope: owner?.logo === undefined ? "default" : "deck", inherited: false };
   }
   const key = descriptor.type === "font" ? "fontScheme" : option;
   const pick = (design) => {
     const value = design?.[key];
-    return descriptor.type === "font" ? (isObject(value) ? value.accent?.family : undefined) : value;
+    return descriptor.type === "font" ? (isObject(value) ? value.accent : undefined) : value;
   };
-  const slideValue = options.slideIndex === undefined ? undefined : pick(document.slides?.[options.slideIndex]?.design);
+  const slideValue = options.slideIndex === undefined ? undefined : pick(presentation.slides?.[options.slideIndex]?.design);
   if (slideValue !== undefined) return { value: slideValue, scope: "slide", inherited: false };
-  const deckValue = pick(document.design);
+  const deckValue = pick(presentation.design);
   if (deckValue !== undefined) return { value: deckValue, scope: "deck", inherited: options.slideIndex !== undefined };
   return { value: undefined, scope: "default", inherited: false };
 }
@@ -324,26 +316,26 @@ export function getDesignOption(document, option, options = {}) {
  * variant of `design.logo`. A single default logo stays a bare source; adding a second variant turns
  * it into a LogoSet, and clearing back to the default collapses it again.
  */
-export function prepareLogoVariant(document, variant, source, options = {}) {
+export function prepareLogoVariant(presentation, variant, source, options = {}) {
   if (!LOGO_VARIANTS.includes(variant)) throw fail("invalid-design-value", `Logo variant is one of ${LOGO_VARIANTS.join(", ")}.`, { variant });
   if (source !== null && typeof source !== "string" && !isObject(source)) throw fail("invalid-design-value", "A logo variant is an image source, an asset object, or null to clear it.", { variant });
   if (typeof source === "string" && !source.trim()) throw fail("invalid-design-value", "Enter an image source or asset reference, or clear the variant.", { variant });
-  const { scope, base, slideIndex } = scopeOf(document, "logo", options);
-  const set = logoSetOf(ownDesign(document, base).logo);
+  const { scope, base, slideIndex } = scopeOf(presentation, "logo", options);
+  const set = logoSetOf(ownDesign(presentation, base).logo);
   if (source === null) delete set[variant];
   else set[variant] = typeof source === "string" ? source.trim() : source;
-  const patches = designPatches(document, base, { logo: collapseLogo(set) });
-  return finish(document, patches, { option: "logo", variant, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: [] });
+  const patches = designPatches(presentation, base, { logo: collapseLogo(set) });
+  return finish(presentation, patches, { option: "logo", variant, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: [] });
 }
 /** Set or clear one logo variant as a single undoable transaction. */
 export function setLogoVariant(editor, variant, source, options = {}) {
   checkEditor(editor);
   const { meta, ...rest } = options;
-  return apply(editor, prepareLogoVariant(editor.document, variant, source, rest), meta);
+  return apply(editor, prepareLogoVariant(editor.presentation, variant, source, rest), meta);
 }
 /** The variants `design.logo` sets at a scope: `{ variant: source }`, a bare logo reported as `default`. */
-export function readLogoVariants(document, options = {}) {
-  const own = options.slideIndex === undefined ? document.design?.logo : document.slides?.[options.slideIndex]?.design?.logo;
+export function readLogoVariants(presentation, options = {}) {
+  const own = options.slideIndex === undefined ? presentation.design?.logo : presentation.slides?.[options.slideIndex]?.design?.logo;
   return logoSetOf(own);
 }
 
@@ -351,7 +343,7 @@ export function readLogoVariants(document, options = {}) {
 
 /**
  * Compute the patch that edits one header or footer zone. `fields` merges into the zone (logo, text,
- * image, slideNumber, slideNumberFormat, date, dateFormat, organization, socials, section); `null`,
+ * image, slideNumber, slideNumberFormat, date, dateFormat, organization, speaker, socials, section); `null`,
  * `false` for a flag, or an empty string removes a field. A zone left empty is removed, then an empty
  * header or footer, so a slide never carries `{}`. A slide's own header or footer replaces the deck's
  * whole one, so the first edit on a slide that has none of its own starts from a copy of the deck's
@@ -359,15 +351,15 @@ export function readLogoVariants(document, options = {}) {
  * inheriting it again. Setting a field on a suppressed (`false`) header replaces the suppression.
  * `logo: true` reports a warning when no logo resolves.
  */
-export function prepareHeaderFooterZone(document, which, zone, fields, options = {}) {
+export function prepareHeaderFooterZone(presentation, which, zone, fields, options = {}) {
   if (!["header", "footer"].includes(which)) throw fail("invalid-design-value", "Choose header or footer.", { which });
   if (!HEADER_FOOTER_ZONES.includes(zone)) throw fail("invalid-design-value", `Zone is one of ${HEADER_FOOTER_ZONES.join(", ")}.`, { zone });
   if (!isObject(fields)) throw fail("invalid-design-value", "Pass the zone fields to change.", { fields });
   const unknown = Object.keys(fields).filter((key) => !ZONE_FIELDS.includes(key));
   if (unknown.length) throw fail("invalid-design-value", `Unknown header/footer field: ${unknown[0]}.`, { fields });
-  const { scope, base, slideIndex } = scopeOf(document, "logo", options);
-  const own = ownDesign(document, base)[which];
-  const inherited = base.length ? document.design?.[which] : undefined;
+  const { scope, base, slideIndex } = scopeOf(presentation, "logo", options);
+  const own = ownDesign(presentation, base)[which];
+  const inherited = base.length ? presentation.design?.[which] : undefined;
   const current = own !== undefined ? own : inherited;
   const container = isObject(current) ? structuredClone(current) : {};
   const item = isObject(container[zone]) ? container[zone] : {};
@@ -386,27 +378,27 @@ export function prepareHeaderFooterZone(document, which, zone, fields, options =
   let next = Object.keys(container).length ? container : null;
   // Emptied: a deck value that would show through again is hidden explicitly; a suppressed header stays suppressed.
   if (next === null && (own === false || isObject(inherited))) next = false;
-  const patches = designPatches(document, base, { [which]: next });
-  return finish(document, patches, { option: which, zone, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: [] });
+  const patches = designPatches(presentation, base, { [which]: next });
+  return finish(presentation, patches, { option: which, zone, scope, ...(slideIndex !== undefined ? { slideIndex } : {}), shadowed: [] });
 }
 /** Edit one header or footer zone as a single undoable transaction. */
 export function setHeaderFooterZone(editor, which, zone, fields, options = {}) {
   checkEditor(editor);
   const { meta, ...rest } = options;
-  return apply(editor, prepareHeaderFooterZone(editor.document, which, zone, fields, rest), meta);
+  return apply(editor, prepareHeaderFooterZone(editor.presentation, which, zone, fields, rest), meta);
 }
 /**
  * One header or footer zone's fields as they apply at a scope: the slide's own header (or footer) when it
  * has one, else the deck's (`{}` when absent or suppressed). `headerFooterState` says which.
  */
-export function readHeaderFooterZone(document, which, zone, options = {}) {
-  const own = options.slideIndex === undefined ? undefined : document.slides?.[options.slideIndex]?.design?.[which];
-  const effective = own !== undefined ? own : document.design?.[which];
+export function readHeaderFooterZone(presentation, which, zone, options = {}) {
+  const own = options.slideIndex === undefined ? undefined : presentation.slides?.[options.slideIndex]?.design?.[which];
+  const effective = own !== undefined ? own : presentation.design?.[which];
   return isObject(effective) && isObject(effective[zone]) ? structuredClone(effective[zone]) : {};
 }
 /** `{ own, inherited, hidden }` for a header or footer at a scope: whether the scope sets it itself, shows the deck's, or hides it with `false`. */
-export function headerFooterState(document, which, options = {}) {
-  const own = options.slideIndex === undefined ? document.design?.[which] : document.slides?.[options.slideIndex]?.design?.[which];
-  const inherited = options.slideIndex !== undefined && own === undefined && document.design?.[which] !== undefined;
-  return { own: own !== undefined, inherited, hidden: (own !== undefined ? own : options.slideIndex !== undefined ? document.design?.[which] : undefined) === false };
+export function headerFooterState(presentation, which, options = {}) {
+  const own = options.slideIndex === undefined ? presentation.design?.[which] : presentation.slides?.[options.slideIndex]?.design?.[which];
+  const inherited = options.slideIndex !== undefined && own === undefined && presentation.design?.[which] !== undefined;
+  return { own: own !== undefined, inherited, hidden: (own !== undefined ? own : options.slideIndex !== undefined ? presentation.design?.[which] : undefined) === false };
 }

package/dist/edit-helpers.js

@@ -1,6 +1,7 @@
 // Helpers shared by the dimension switches, the design options, the block conversions and the
 // table options: the error constructor, structural equality and the design-key patch rules.
-import { OPFEditorError, applyJsonPatch, getValueAtPath, opfPathToJsonPointer, validateOpfDocument } from "./index.js";
+import { OPFEditorError, applyJsonPatch, getValueAtPath, opfPathToJsonPointer } from "./index.js";
+import { firstErrorMessage, errorFindings, checkFormat } from "./checks.js";
 
 export function fail(code, message, details) {
   return new OPFEditorError(code, message, details);
@@ -19,8 +20,8 @@ export function same(a, b) {
 }
 
 // Set (value) or remove (null) design keys at deck or slide scope.
-export function designPatches(document, base, entries) {
-  const design = getValueAtPath(document, base.length ? [...base, "design"] : ["design"]);
+export function designPatches(presentation, base, entries) {
+  const design = getValueAtPath(presentation, base.length ? [...base, "design"] : ["design"]);
   const at = (key) => opfPathToJsonPointer([...base, "design", key]);
   const set = Object.entries(entries).filter(([, value]) => value !== undefined && value !== null);
   if (!design || typeof design !== "object" || Array.isArray(design))
@@ -41,12 +42,12 @@ export function designPatches(document, base, entries) {
  * Validate a candidate patch the way every switch does: the result must be valid OPF unless the
  * input document was already invalid (then nothing new may be reported as the cause).
  */
-export function checkedDocument(document, patches, before) {
-  const next = patches.length ? applyJsonPatch(document, patches) : document;
+export function checkedDocument(presentation, patches, before) {
+  const next = patches.length ? applyJsonPatch(presentation, patches) : presentation;
   if (patches.length) {
-    const validation = validateOpfDocument(next);
+    const validation = checkFormat(next);
     if (!validation.valid && before.valid)
-      throw fail("invalid-opf-edit", validation.errors[0]?.message ?? "This change produces an invalid document.", { issues: validation.errors, patches });
+      throw fail("invalid-opf-edit", firstErrorMessage(validation, "This change produces an invalid document."), { issues: errorFindings(validation), patches });
   }
   return next;
 }

package/dist/exact-source.js

@@ -228,11 +228,11 @@ function typingSignature(previous, ops) {
 /**
  * Change only the affected values. Keeps authored indentation, escaping and all unrelated
  * metadata/content byte-for-byte, including across canvas Escape, Undo and Redo.
- * Throws when `source` is not valid JSON. The result always parses to `document`; if an
+ * Throws when `source` is not valid JSON. The result always parses to `presentation`; if an
  * in-place edit cannot achieve that (for example the source repeats an object key), the whole
  * document is written as indented JSON instead.
  */
-export function updateJsonSource(source, document, memory = sharedMemory) {
+export function updateJsonSource(source, presentation, memory = sharedMemory) {
   const previous = JSON.parse(source);
   const previousKey = JSON.stringify(previous);
   memory.limited = source.length > MAX_EXACT_SOURCE_LENGTH;
@@ -243,9 +243,9 @@ export function updateJsonSource(source, document, memory = sharedMemory) {
     memory.last = null;
   }
   const ops = [];
-  diff(previous, document, [], ops);
+  diff(previous, presentation, [], ops);
   if (!ops.length) return source;
-  const key = JSON.stringify(document);
+  const key = JSON.stringify(presentation);
   const remembered = recall(memory, key);
   if (remembered !== undefined && equalOutside(source, remembered, maskPaths(ops))) {
     memory.last = null;
@@ -306,7 +306,7 @@ export function updateJsonSource(source, document, memory = sharedMemory) {
     valid = JSON.stringify(parsed) === key || canonical(parsed) === canonical(JSON.parse(key));
   } catch { /* Fall back below. */ }
   if (!valid) {
-    result = JSON.stringify(document, null, indent).replaceAll("\n", eol);
+    result = JSON.stringify(presentation, null, indent).replaceAll("\n", eol);
     if (/\n$/.test(source)) result += eol;
   }