@openpresentation/opf-editor 0.10.6 → 0.11.1

package/dist/annotations.js

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

package/dist/assets.d.ts

@@ -0,0 +1,67 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export declare const IMAGE_MEDIA_TYPES: Readonly<Record<string, readonly string[]>>;
+/** The `accept` value for a file input: image/png,image/jpeg,image/gif,image/webp,image/svg+xml. */
+export declare const IMAGE_ACCEPT: string;
+/** Default size cap for an uploaded image: 2 MiB. */
+export declare const DEFAULT_MAX_IMAGE_BYTES: number;
+
+export interface ValidatedImage {
+  name: string;
+  mediaType: string;
+  bytes: Uint8Array;
+  size: number;
+}
+export interface PreparedImageAsset {
+  id: string;
+  /** `asset:<id>` */
+  reference: string;
+  entry: { src: string; mediaType: string; title: string; alt?: string };
+  patches: JsonPatchOperation[];
+}
+export interface ImageUploadOptions {
+  /** Saved on the asset (or passed to `onAddAsset`). */
+  alt?: string;
+  /** Size cap in bytes (default 2 MiB). */
+  maxBytes?: number;
+  /** For hosts that store images elsewhere: receives the validated bytes and returns the reference to use; nothing is added to `assets`. */
+  onAddAsset?: (image: { name: string; mediaType: string; bytes: Uint8Array; size: number; alt?: string; file: unknown }) => string | { src: string } | Promise<string | { src: string }>;
+  meta?: Record<string, unknown>;
+}
+export interface ImageUploadChange extends Omit<EditorChange, "document" | "patches"> {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  /** The new asset's id (absent with `onAddAsset`). */
+  assetId?: string;
+  reference: string;
+  changed: boolean;
+  prepared: { patches: JsonPatchOperation[]; [key: string]: unknown };
+}
+
+/** The image type the first bytes say it is (SVG by its root element), or undefined. */
+export declare function sniffImageType(bytes: Uint8Array): string | undefined;
+/** Validate bytes and name: type, contents matching the claimed type, size cap, and no script in SVG. Throws `invalid-image` or `image-too-large` with a message that says what to do. */
+export declare function checkImageBytes(bytes: Uint8Array, options?: { name?: string; declaredType?: string; maxBytes?: number }): { mediaType: string };
+/** Read a File or Blob into validated bytes. */
+export declare function readImageFile(file: { name?: string; type?: string; size?: number; arrayBuffer(): Promise<ArrayBuffer> }, options?: { maxBytes?: number }): Promise<ValidatedImage>;
+export declare function imageDataUri(bytes: Uint8Array, mediaType: string): string;
+/** A free asset id for a file name (`logo`, then `logo-2`). */
+export declare function uniqueAssetId(document: unknown, name: string): string;
+/** The patch that adds one validated image to `assets`. */
+export declare function prepareImageAsset(document: unknown, image: ValidatedImage, options?: { alt?: string; id?: string }): PreparedImageAsset;
+/**
+ * Add an uploaded image and use it in one undoable transaction. `build(reference, document)` returns the prepared change
+ * that uses the image (any `prepare...` function of this package); its patches run after the asset patch.
+ */
+export declare function applyImageUpload(
+  editor: EditorSession,
+  file: { name?: string; type?: string; size?: number; arrayBuffer(): Promise<ArrayBuffer> },
+  build: (reference: string, document: any) => { patches: JsonPatchOperation[] },
+  options?: ImageUploadOptions,
+): Promise<ImageUploadChange>;
+/** The patch that sets (or, for an empty string, removes) an asset's alt text. */
+export declare function prepareAssetAlt(document: unknown, assetId: string, alt: string): { assetId: string; patches: JsonPatchOperation[]; changed: boolean };
+/** Set an asset's alt text as one undoable transaction. */
+export declare function setAssetAlt(editor: EditorSession, assetId: string, alt: string, meta?: Record<string, unknown>): unknown;
+/** The `assets` id a reference names (`asset:logo` gives `logo`), or undefined for a URL or data address. */
+export declare function assetIdOf(reference: unknown): string | undefined;

package/dist/assets.js

@@ -0,0 +1,176 @@
+// Image assets for the design controls (RR-06): turn a local file into an entry of the document's
+// `assets` map and reference it from a logo, watermark, slide image, background or header/footer
+// zone in the same undoable patch. The file is validated before anything changes: the type must be
+// PNG, JPEG, GIF, WebP or SVG, its bytes must match that type, and its size must be under a cap with a
+// clear error. A host that keeps images elsewhere passes `onAddAsset` and gets the bytes instead.
+import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer } from "./index.js";
+import { fail } from "./edit-helpers.js";
+
+/** Accepted image types by media type, with their usual extensions. */
+export const IMAGE_MEDIA_TYPES = Object.freeze({
+  "image/png": ["png"],
+  "image/jpeg": ["jpg", "jpeg"],
+  "image/gif": ["gif"],
+  "image/webp": ["webp"],
+  "image/svg+xml": ["svg"],
+});
+/** The `accept` value for a file input. */
+export const IMAGE_ACCEPT = Object.keys(IMAGE_MEDIA_TYPES).join(",");
+/** Default size cap for an uploaded image (2 MiB). Raise it with the `maxBytes` option. */
+export const DEFAULT_MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+
+const formatSize = (bytes) => (bytes < 1024 ? `${bytes} bytes` : bytes >= 1024 * 1024 ? `${+(bytes / (1024 * 1024)).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`);
+const formatKb = (bytes) => `${+(bytes / 1024).toFixed(1)} KB`;
+// "2 MB; the limit is 2 MB" tells nobody anything: when the two round alike, say it in kilobytes.
+function tooLarge(name, size, maxBytes) {
+  const [actual, limit] = formatSize(size) === formatSize(maxBytes) ? [formatKb(size), formatKb(maxBytes)] : [formatSize(size), formatSize(maxBytes)];
+  return `${name ? `"${name}"` : "This file"} is ${actual}; the limit is ${limit}. Resize or compress it, or host it and use a web address instead.`;
+}
+
+/** The image type the first bytes of `bytes` say it is, or undefined. SVG is recognized by its root element. */
+export function sniffImageType(bytes) {
+  const at = (index) => bytes[index];
+  if (bytes.length >= 8 && at(0) === 0x89 && at(1) === 0x50 && at(2) === 0x4e && at(3) === 0x47) return "image/png";
+  if (bytes.length >= 3 && at(0) === 0xff && at(1) === 0xd8 && at(2) === 0xff) return "image/jpeg";
+  if (bytes.length >= 6 && at(0) === 0x47 && at(1) === 0x49 && at(2) === 0x46 && at(3) === 0x38) return "image/gif";
+  if (bytes.length >= 12 && at(0) === 0x52 && at(1) === 0x49 && at(2) === 0x46 && at(3) === 0x46 && at(8) === 0x57 && at(9) === 0x45 && at(10) === 0x42 && at(11) === 0x50) return "image/webp";
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, 2048)).replace(/^/, "").trimStart();
+  if (/^(?:<\?xml[^>]*\?>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg[\s>]/i.test(head)) return "image/svg+xml";
+  return undefined;
+}
+
+function mediaTypeFromName(name) {
+  const extension = /\.([a-z0-9]+)$/i.exec(name ?? "")?.[1]?.toLowerCase();
+  return Object.entries(IMAGE_MEDIA_TYPES).find(([, extensions]) => extensions.includes(extension))?.[0];
+}
+
+// An SVG used as an image cannot run script in a browser, but the same bytes travel in the document
+// to other tools; refuse the constructs that exist only to run or fetch things.
+function unsafeSvg(bytes) {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  return /<script[\s>]|<foreignObject[\s>]|\son[a-z]+\s*=|javascript:|<iframe[\s>]|<!ENTITY/i.test(text);
+}
+
+/**
+ * Validate a file's bytes and name. Returns `{ mediaType }` or throws `invalid-image` with a message that says what to do.
+ * `declaredType` is the browser-reported type (may be empty); the bytes decide.
+ */
+export function checkImageBytes(bytes, { name, declaredType, maxBytes = DEFAULT_MAX_IMAGE_BYTES } = {}) {
+  const label = name ? `"${name}"` : "This file";
+  if (!bytes || !bytes.length) throw fail("invalid-image", `${label} is empty.`, { name });
+  if (bytes.length > maxBytes)
+    throw fail("image-too-large", tooLarge(name, bytes.length, maxBytes), { name, size: bytes.length, maxBytes });
+  const mediaType = sniffImageType(bytes);
+  if (!mediaType) throw fail("invalid-image", `${label} is not a PNG, JPEG, GIF, WebP or SVG image.`, { name, declaredType });
+  const claimed = declaredType && IMAGE_MEDIA_TYPES[declaredType] ? declaredType : mediaTypeFromName(name);
+  if (claimed && claimed !== mediaType) throw fail("invalid-image", `${label} says it is ${claimed.replace("image/", "").toUpperCase()} but its contents are ${mediaType.replace("image/", "").toUpperCase()}. Save it as the right type and choose it again.`, { name, claimed, mediaType });
+  if (mediaType === "image/svg+xml" && unsafeSvg(bytes)) throw fail("invalid-image", `${label} contains script or embedded content that an image must not carry. Export a plain SVG and choose it again.`, { name });
+  return { mediaType };
+}
+
+/** Read a File or Blob into validated bytes: `{ name, mediaType, bytes, size }`. Rejects before reading when the size is already over the cap. */
+export async function readImageFile(file, { maxBytes = DEFAULT_MAX_IMAGE_BYTES } = {}) {
+  if (!file || typeof file.arrayBuffer !== "function") throw fail("invalid-image", "Choose an image file.", {});
+  if (typeof file.size === "number" && file.size > maxBytes)
+    throw fail("image-too-large", tooLarge(file.name, file.size, maxBytes), { name: file.name, size: file.size, maxBytes });
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const { mediaType } = checkImageBytes(bytes, { name: file.name, declaredType: file.type, maxBytes });
+  return { name: file.name ?? "image", mediaType, bytes, size: bytes.length };
+}
+
+function toBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+  return btoa(binary);
+}
+
+/** A data URI for validated image bytes. */
+export function imageDataUri(bytes, mediaType) {
+  return `data:${mediaType};base64,${toBase64(bytes)}`;
+}
+
+/** An asset id for a file name that is free in the document (`logo`, then `logo-2`, ...). */
+export function uniqueAssetId(document, name) {
+  const base = String(name ?? "image").replace(/\.[a-z0-9]+$/i, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "image";
+  const taken = document?.assets && typeof document.assets === "object" ? document.assets : {};
+  if (!Object.hasOwn(taken, base)) return base;
+  for (let n = 2; ; n += 1) if (!Object.hasOwn(taken, `${base}-${n}`)) return `${base}-${n}`;
+}
+
+/**
+ * The patch that adds one validated image to `assets` (the entry is `{ src: dataUri, mediaType, title, alt? }`),
+ * with the `asset:<id>` reference to use. Pure: touches no session.
+ */
+export function prepareImageAsset(document, image, { alt, id } = {}) {
+  const assetId = id ?? uniqueAssetId(document, image.name);
+  if (document?.assets && Object.hasOwn(document.assets, assetId)) throw fail("asset-exists", `An asset named "${assetId}" already exists.`, { id: assetId });
+  const entry = { src: imageDataUri(image.bytes, image.mediaType), mediaType: image.mediaType, title: image.name };
+  if (typeof alt === "string" && alt.trim()) entry.alt = alt.trim();
+  const patches = document?.assets && typeof document.assets === "object" && !Array.isArray(document.assets)
+    ? [{ op: "add", path: opfPathToJsonPointer(["assets", assetId]), value: entry }]
+    : [{ op: "add", path: "/assets", value: { [assetId]: entry } }];
+  return { id: assetId, reference: `asset:${assetId}`, entry, patches };
+}
+
+/**
+ * Add an uploaded image and use it in one undoable transaction. `build(reference, document)` returns the
+ * prepared change that uses the image (any `prepare...` function of this package, for example
+ * `(ref, doc) => prepareLogoVariant(doc, "light", ref)`); its patches run after the asset patch.
+ *
+ * Options: `alt` (saved on the asset), `maxBytes`, `meta`, and `onAddAsset({ name, mediaType, bytes, size, alt, file })`
+ * for a host that stores images itself: it returns the reference to use (a web address or an `asset:` id the
+ * host added) and nothing is added to `assets`.
+ */
+export async function applyImageUpload(editor, file, build, options = {}) {
+  if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+  const image = await readImageFile(file, { maxBytes: options.maxBytes });
+  const { alt, meta } = options;
+  let reference;
+  let assetPatches = [];
+  let assetId;
+  if (typeof options.onAddAsset === "function") {
+    const stored = await options.onAddAsset({ name: image.name, mediaType: image.mediaType, bytes: image.bytes, size: image.size, alt: alt?.trim() || undefined, file });
+    reference = typeof stored === "string" ? stored : stored?.src;
+    if (typeof reference !== "string" || !reference.trim()) throw fail("invalid-asset-reference", "The host's onAddAsset must return the image's reference (a web address or an asset: id).", {});
+  } else {
+    // Build against the document as it is after the read: the file may have taken a moment to arrive.
+    const added = prepareImageAsset(editor.document, image, { alt });
+    reference = added.reference;
+    assetPatches = added.patches;
+    assetId = added.id;
+  }
+  const document = assetPatches.length ? applyJsonPatch(editor.document, assetPatches) : editor.document;
+  const prepared = build(reference, document);
+  const patches = [...assetPatches, ...prepared.patches];
+  const summary = { assetId, reference, changed: patches.length > 0, prepared };
+  if (!patches.length) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(patches, { ...meta, source: meta?.source ?? "image-upload", ...(assetId ? { assetId } : {}), reference });
+  return { ...change, ...summary };
+}
+
+/** The patch that sets (or, for an empty string, removes) an asset's alt text. The asset must exist in `assets`. */
+export function prepareAssetAlt(document, assetId, alt) {
+  const entry = getValueAtPath(document, ["assets", assetId]);
+  if (entry === undefined) throw fail("unknown-asset", `There is no asset named "${assetId}".`, { assetId });
+  const object = typeof entry === "string" ? { src: entry } : { ...entry };
+  const text = typeof alt === "string" ? alt.trim() : "";
+  if (text) object.alt = text;
+  else delete object.alt;
+  const value = Object.keys(object).length === 1 && typeof object.src === "string" ? object.src : object;
+  const same = JSON.stringify(value) === JSON.stringify(entry);
+  return { assetId, patches: same ? [] : [{ op: "replace", path: opfPathToJsonPointer(["assets", assetId]), value }], changed: !same };
+}
+
+/** Set an asset's alt text as one undoable transaction. */
+export function setAssetAlt(editor, assetId, alt, meta = {}) {
+  if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+  const prepared = prepareAssetAlt(editor.document, assetId, alt);
+  if (!prepared.changed) return { ...prepared, document: editor.document, inversePatches: [], validation: editor.validation };
+  return { ...editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? "asset-alt", assetId }), assetId, changed: true };
+}
+
+/** The `assets` id a reference names (`asset:logo` gives `logo`), or undefined for a URL or data address. */
+export function assetIdOf(reference) {
+  const source = typeof reference === "string" ? reference : reference && typeof reference === "object" ? reference.src : undefined;
+  return typeof source === "string" && source.startsWith("asset:") ? source.slice("asset:".length) : undefined;
+}

package/dist/background-options.d.ts

@@ -0,0 +1,48 @@
+import type { EditorSession } from "./index.js";
+import type { DimensionSwitchChange, DimensionSwitchOptions, PreparedDimensionSwitch } from "./switches.js";
+
+export declare const BACKGROUND_TYPES: readonly ["theme", "solid", "gradient", "image", "pattern"];
+export declare const THEME_BACKGROUND_SLOTS: readonly ["light1", "light2", "dark1", "dark2"];
+export declare const IMAGE_BACKGROUND_FITS: readonly ["cover", "contain", "tile"];
+/** Scheme slots and roles a ColorRef may name. */
+export declare const COLOR_NAMES: readonly string[];
+/** The 54 DrawingML preset patterns by family. */
+export declare const PATTERN_GROUPS: Readonly<Record<string, readonly string[]>>;
+export declare const PATTERN_PRESETS: readonly string[];
+
+export interface GradientStop {
+  color: string;
+  position: number;
+}
+export type BackgroundSpec =
+  | string
+  | { type: "theme"; slot: (typeof THEME_BACKGROUND_SLOTS)[number] }
+  | { type: "solid"; color: string; opacity?: number }
+  | { type: "gradient"; gradient: { angle?: number; stops: GradientStop[] }; opacity?: number }
+  | { type: "image"; image: { src: string; fit?: (typeof IMAGE_BACKGROUND_FITS)[number] }; opacity?: number }
+  | { type: "pattern"; pattern: { preset: string; foregroundColor?: string; backgroundColor?: string }; opacity?: number };
+
+/** Whether `value` is a ColorRef: a hex color, a scheme slot or role name, or `var:<id>`. */
+export declare function isColorRef(value: unknown): boolean;
+/** Validate a background description and return the value to store (a theme slot or plain hex stays the shorthand string). Throws `invalid-background`. */
+export declare function normalizeBackground(spec: BackgroundSpec): string | Record<string, unknown>;
+export declare function prepareBackground(document: unknown, spec: BackgroundSpec | null, options?: DimensionSwitchOptions): PreparedDimensionSwitch;
+/** Set the background as one undoable transaction; `null` removes it. */
+export declare function setBackground(editor: EditorSession, spec: BackgroundSpec | null, options?: DimensionSwitchOptions): DimensionSwitchChange;
+export interface BackgroundState {
+  type?: "theme" | "solid" | "gradient" | "image" | "pattern";
+  slot?: string;
+  color?: string;
+  opacity?: number;
+  angle?: number;
+  stops?: GradientStop[];
+  src?: string;
+  fit?: string;
+  preset?: string;
+  foregroundColor?: string;
+  backgroundColor?: string;
+  scope: "deck" | "slide";
+  value?: unknown;
+}
+/** The background that applies at a scope, flattened for a form. */
+export declare function readBackground(document: unknown, options?: { slideIndex?: number }): BackgroundState;