@openpresentation/opf-editor 0.10.5 → 0.11.0

package/dist/design-options.d.ts

@@ -0,0 +1,108 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export type DesignOptionId =
+  | "titleAlignment"
+  | "contentAlignment"
+  | "contentDirection"
+  | "chartPrimary"
+  | "listBullet"
+  | "contentBox"
+  | "accentFont"
+  | "logo"
+  | "organizationLogo"
+  | "watermark"
+  | "slideImage";
+export interface DesignOptionDescriptor {
+  id: DesignOptionId;
+  label: string;
+  type: "enum" | "boolean" | "font" | "logo" | "organization-logo" | "watermark" | "slide-image";
+  /** Allowed values of an enum option. */
+  values?: readonly string[];
+  scopes: ("deck" | "slide")[];
+  path: string;
+}
+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"];
+/** Date format tokens (English names). */
+export declare const DATE_FORMAT_TOKENS: readonly string[];
+export declare const HEADER_FOOTER_ZONES: readonly ["left", "center", "right"];
+export type HeaderFooterZone = (typeof HEADER_FOOTER_ZONES)[number];
+
+export interface DesignOptionOptions {
+  /** One slide instead of the deck. Not allowed for organizationLogo. */
+  slideIndex?: number;
+  /** Deck scope: also remove slide-level values that would hide the change. */
+  clearSlideOverrides?: boolean;
+  /** organizationLogo with several organizations (default 0). */
+  index?: number;
+  /** Session change metadata (session forms only). */
+  meta?: Record<string, unknown>;
+}
+export interface DesignWarning {
+  code: "unresolved-logo" | "unresolved-content";
+  path: string;
+  message: string;
+}
+export interface PreparedDesignOption {
+  option: string;
+  scope: "deck" | "slide";
+  slideIndex?: number;
+  /** The logo variant or header/footer zone an edit named. */
+  variant?: string;
+  zone?: string;
+  document: unknown;
+  patches: JsonPatchOperation[];
+  changed: boolean;
+  /** Slides whose own design hides a deck-level change. */
+  shadowed: number[];
+  /** Settings that need a logo the document does not have. */
+  warnings: DesignWarning[];
+}
+export interface DesignOptionChange extends Omit<EditorChange, "document" | "patches"> {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  option: string;
+  scope: "deck" | "slide";
+  slideIndex?: number;
+  changed: boolean;
+  shadowed: number[];
+  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;
+/** 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;
+/** 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 interface HeaderFooterZoneFields {
+  logo?: boolean | null;
+  text?: string | null;
+  image?: string | Record<string, unknown> | null;
+  slideNumber?: boolean | null;
+  slideNumberFormat?: string | null;
+  date?: boolean | string | null;
+  dateFormat?: string | null;
+  organization?: boolean | null;
+  socials?: boolean | null;
+  section?: boolean | null;
+}
+export declare function prepareHeaderFooterZone(document: 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;
+/** 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 };
+/** 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[];

package/dist/design-options.js

@@ -0,0 +1,412 @@
+// Design-level options (RR-06): the settings the All-properties workspace used to be the only
+// place to edit. Each is one validated JSON Patch applied as one undoable transaction, at the deck
+// 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 { checkedDocument, designPatches, fail, same } from "./edit-helpers.js";
+
+/** The `design.logo` variant slots of a LogoSet, in schema order. */
+export const LOGO_VARIANTS = Object.freeze([
+  "default",
+  "light",
+  "dark",
+  "stacked",
+  "stackedLight",
+  "stackedDark",
+  "icon",
+  "iconLight",
+  "iconDark",
+  "wordmark",
+  "wordmarkLight",
+  "wordmarkDark",
+]);
+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"]);
+/** 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}$/;
+
+// 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 (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}.");
+  if (key === "date" && typeof value !== "boolean" && typeof value !== "string") throw bad("A date is true (the current date) or a fixed date.");
+  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"],
+});
+
+/**
+ * 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
+ * the option applies to the deck, one slide, or both.
+ */
+export const DESIGN_OPTIONS = Object.freeze([
+  { id: "titleAlignment", label: "Title alignment", type: "enum", values: ENUMS.titleAlignment, scopes: ["deck", "slide"], path: "design.titleAlignment" },
+  { id: "contentAlignment", label: "Content alignment", type: "enum", values: ENUMS.contentAlignment, scopes: ["deck", "slide"], path: "design.contentAlignment" },
+  { id: "contentDirection", label: "Content direction", type: "enum", values: ENUMS.contentDirection, scopes: ["deck", "slide"], path: "design.contentDirection" },
+  { 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: "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) {
+  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 });
+  return { scope: "slide", base: ["slides", String(index)], slideIndex: index };
+}
+
+function ownDesign(document, base) {
+  const design = getValueAtPath(document, base.length ? [...base, "design"] : ["design"]);
+  return isObject(design) ? design : {};
+}
+
+function primaryOrganization(document) {
+  const list = Array.isArray(document.organization) ? document.organization : document.organization ? [document.organization] : [];
+  return list.find((entry) => entry?.role === "primary") ?? 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);
+}
+
+/**
+ * Plain-language warnings for settings that need a logo the document does not have: a header or
+ * 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 };
+  const warnings = [];
+  const hasLogo = hasResolvableLogo(document, 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);
+  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?.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.` });
+    }
+  if (!hasLogo && design.listBullet === "image")
+    warnings.push({ code: "unresolved-logo", path: "design.listBullet", message: "Picture bullets use the logo, but no logo is set, so lists draw the character bullet. Add a logo or an organization logo." });
+  return warnings;
+}
+
+function shadowed(document, keys) {
+  return (document.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);
+  const slideIndex = extra.slideIndex;
+  return {
+    ...extra,
+    document: structuredClone(next),
+    patches,
+    changed: patches.length > 0,
+    warnings: designWarnings(next, slideIndex ?? 0),
+  };
+}
+
+// --- per-option value rules ---------------------------------------------------------------------
+
+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 });
+  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;
+  }
+  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 (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) {
+  // 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 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() };
+  }
+  const keys = Object.keys(object);
+  if (!keys.length) return null;
+  if (keys.length === 1 && keys[0] === "id") return object.id;
+  return object;
+}
+
+function logoSetOf(existing) {
+  if (existing === undefined) return {};
+  if (typeof existing === "string" || (isObject(existing) && Object.hasOwn(existing, "src"))) return { default: existing };
+  return isObject(existing) ? { ...existing } : {};
+}
+function collapseLogo(set) {
+  const keys = Object.keys(set);
+  if (!keys.length) return null;
+  if (keys.length === 1 && keys[0] === "default") return set.default;
+  return set;
+}
+
+// --- design option ----------------------------------------------------------------------------
+
+/**
+ * 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.
+ * 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 = {}) {
+  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 (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);
+  let patches = [];
+  let keys = [];
+
+  if (descriptor.type === "organization-logo") {
+    const organization = document.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 });
+    const path = Array.isArray(organization) ? ["organization", String(index), "logo"] : ["organization", "logo"];
+    const present = Object.hasOwn(owner, "logo");
+    if (value === null) patches = present ? [{ op: "remove", path: opfPathToJsonPointer(path) }] : [];
+    else if (!present) patches = [{ op: "add", path: opfPathToJsonPointer(path), value: structuredClone(value) }];
+    else if (!same(owner.logo, value)) patches = [{ op: "replace", path: opfPathToJsonPointer(path), value: structuredClone(value) }];
+  } else {
+    let entries;
+    if (descriptor.type === "enum") {
+      if (value !== null && !ENUMS[option].includes(value)) throw fail("invalid-design-value", `${descriptor.label} is one of ${ENUMS[option].join(", ")}.`, { option, value });
+      entries = { [option]: value };
+    } else if (descriptor.type === "boolean") {
+      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) };
+    } 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) };
+    }
+    keys = Object.keys(entries);
+    patches = designPatches(document, base, entries);
+  }
+
+  let shadowedSlides = [];
+  if (scope === "deck" && keys.length) {
+    shadowedSlides = shadowed(document, 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]) });
+      shadowedSlides = [];
+    }
+  }
+  return finish(document, 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 change = editor.applyPatch(patches, { ...meta, source: meta.source ?? "design-option", option: prepared.option, scope: prepared.scope });
+  return { ...change, ...summary };
+}
+function checkEditor(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function")
+    throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/** Set one design option as a single undoable transaction. See {@link prepareDesignOption}. */
+export function setDesignOption(editor, option, value, options = {}) {
+  checkEditor(editor);
+  const { meta, ...rest } = options;
+  return apply(editor, prepareDesignOption(editor.document, 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.
+ */
+export function getDesignOption(document, 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 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;
+  };
+  const slideValue = options.slideIndex === undefined ? undefined : pick(document.slides?.[options.slideIndex]?.design);
+  if (slideValue !== undefined) return { value: slideValue, scope: "slide", inherited: false };
+  const deckValue = pick(document.design);
+  if (deckValue !== undefined) return { value: deckValue, scope: "deck", inherited: options.slideIndex !== undefined };
+  return { value: undefined, scope: "default", inherited: false };
+}
+
+// --- logo variants ----------------------------------------------------------------------------
+
+/**
+ * Compute the patch that sets (a source, asset reference or Asset object) or clears (`null`) one logo
+ * 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 = {}) {
+  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);
+  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: [] });
+}
+/** 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);
+}
+/** 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;
+  return logoSetOf(own);
+}
+
+// --- header and footer zones ------------------------------------------------------------------
+
+/**
+ * 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`,
+ * `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
+ * (the other zones stay); a slide emptied that way hides the furniture (`false`) instead of
+ * 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 = {}) {
+  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 current = own !== undefined ? own : inherited;
+  const container = isObject(current) ? structuredClone(current) : {};
+  const item = isObject(container[zone]) ? container[zone] : {};
+  for (const [key, entry] of Object.entries(fields)) {
+    const removes = entry === null || entry === undefined || ((ZONE_FLAGS.includes(key) || key === "date") && entry === false) || entry === "";
+    if (removes) delete item[key];
+    else {
+      checkZoneField(key, entry);
+      item[key] = entry;
+    }
+  }
+  // A fixed date with a format must be an ISO date (the schema's rule); say so before the generic error.
+  if (typeof item.date === "string" && item.dateFormat && !ISO_DATE.test(item.date)) throw fail("invalid-design-value", "A fixed date with a date format must be written YYYY-MM-DD, for example 2026-10-01.", { field: "date", value: item.date });
+  if (Object.keys(item).length) container[zone] = item;
+  else delete container[zone];
+  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: [] });
+}
+/** 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);
+}
+/**
+ * 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];
+  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 };
+}

package/dist/edit-helpers.js

@@ -0,0 +1,52 @@
+// 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";
+
+export function fail(code, message, details) {
+  return new OPFEditorError(code, message, details);
+}
+
+export function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object")
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+/** Structural equality that ignores object key order. */
+export function same(a, b) {
+  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(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"]);
+  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))
+    return set.length ? [{ op: "add", path: opfPathToJsonPointer([...base, "design"]), value: structuredClone(Object.fromEntries(set)) }] : [];
+  const patches = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (value === undefined) continue;
+    const present = Object.hasOwn(design, key);
+    if (value === null) {
+      if (present) patches.push({ op: "remove", path: at(key) });
+    } else if (!present) patches.push({ op: "add", path: at(key), value: structuredClone(value) });
+    else if (!same(design[key], value)) patches.push({ op: "replace", path: at(key), value: structuredClone(value) });
+  }
+  return patches;
+}
+
+/**
+ * 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;
+  if (patches.length) {
+    const validation = validateOpfDocument(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 });
+  }
+  return next;
+}

package/dist/export.d.ts

@@ -0,0 +1,77 @@
+import type { RenderSvgOptions } from "@openpresentation/opf-render";
+import type { FontGate } from "./canvas.js";
+
+export type ExportFormat = "pdf" | "png" | "svg";
+export declare const EXPORT_FORMATS: Readonly<Record<ExportFormat, { extension: string; type: string; label: string }>>;
+/** Largest PNG scale offered (4: a 1280 x 720 slide is 5120 x 2880 pixels). */
+export declare const MAX_PNG_SCALE: 4;
+
+/**
+ * The download name: the deck's `filename` (a trailing .pptx, .pdf, .png or .svg dropped), else the slugified `name`, else "presentation",
+ * then `suffix` and `.extension`.
+ */
+export declare function exportFileName(deck: { filename?: string; name?: string } | undefined, extension: string, suffix?: string): string;
+/** Slide numbers (0-based) an export covers; hidden slides are skipped in an "all" export unless `includeHidden`. */
+export declare function slidesToExport(deck: { slides?: Array<{ hidden?: boolean }> }, options?: { slides?: "current" | "all" | number[]; slideIndex?: number; includeHidden?: boolean }): number[];
+/** The registry's faces marked to embed only where a slide draws them; a face with a non-permissive license text is left out (`onSkip` is told). */
+export declare function embeddableFonts(registry: object | undefined, onSkip?: (face: { family: string; weight: number; italic?: boolean; license?: string }) => void): Array<Record<string, unknown>>;
+
+export interface ExportDiagnostic {
+  code: string;
+  severity: "info" | "warning";
+  message: string;
+  /** 0-based slide number, when the note belongs to one slide. */
+  slide?: number;
+  path?: string;
+  family?: string;
+}
+export declare function describeDiagnostic(diagnostic: { code?: string; message?: string; path?: string; family?: string; [key: string]: unknown }, source?: "render" | "pdf"): ExportDiagnostic;
+
+export interface ExportProgress {
+  stage: "fonts" | "render" | "convert" | "archive" | "done";
+  done: number;
+  total: number;
+  message?: string;
+}
+export interface ExportFile { name: string; type: string; bytes: Uint8Array }
+export interface ExportOptions {
+  format: ExportFormat;
+  /** "all" (default), "current" (with `slideIndex`) or slide numbers (0-based). */
+  slides?: "current" | "all" | number[];
+  slideIndex?: number;
+  includeHidden?: boolean;
+  /** "vector" (default): selectable text and vector shapes; "raster": an image per slide. */
+  pdfMode?: "vector" | "raster";
+  /** PNG pixel density (and the raster PDF's), 1 to 4; default 2. */
+  scale?: number;
+  /** The options the host draws its preview with (`textMeasurement`, `catalogs`, ...). */
+  renderOptions?: RenderSvgOptions;
+  /** A font gate: the faces the deck needs load before anything is drawn. */
+  fonts?: Pick<FontGate, "pending" | "ensure">;
+  /** The browser font registry; its faces are what gets embedded. */
+  registry?: object;
+  /** Faces to embed instead of the registry's. */
+  embeddedFonts?: Array<Record<string, unknown>>;
+  /** PDF document properties beyond the title and subject taken from the deck. */
+  metadata?: Record<string, unknown>;
+  /** The family the PDF uses when a requested one is missing; default "Roboto". */
+  fallbackFamily?: string;
+  /** Replace the renderer's `export-browser` entry (tests, or a host with its own converter). */
+  convert?: { svgToPdf(svgs: string[], options?: object): Promise<Uint8Array>; svgToPng(svg: string, options?: object): Promise<Uint8Array> };
+  signal?: AbortSignal;
+  onProgress?: (progress: ExportProgress) => void;
+  onDiagnostic?: (diagnostic: ExportDiagnostic) => void;
+}
+export interface ExportResult {
+  /** One PDF, PNG or SVG, or a ZIP of several. */
+  download: ExportFile;
+  files: ExportFile[];
+  diagnostics: ExportDiagnostic[];
+  /** The slide numbers (0-based) exported. */
+  slides: number[];
+}
+/**
+ * Draw the deck with the renderer the preview uses and convert it. Rejects with an error whose `code` is `export-aborted`, `export-no-slides`,
+ * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code.
+ */
+export declare function exportDeck(deck: unknown, options: ExportOptions): Promise<ExportResult>;