@openpresentation/opf-editor 0.10.6 → 0.11.0

package/dist/index.js

@@ -1,4 +1,5 @@
 import { paginateSlide } from "@openpresentation/opf/pagination";
+import { PatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
 import { collectReservedPresentationIds } from "./presentation-ids.js";
 import { DEFAULT_FONT_SCHEME, resolveFontSchemeReference } from "./font-defaults.js";
 import { composeSlide, resolveCanvasDimensions, resolveFontFamilies } from "@openpresentation/opf/composition";
@@ -54,7 +55,6 @@ export const runtimePolicy = Object.freeze({
 const DATA_OPF_PATH = "data-opf-path";
 const COMPONENT_ATTR = "data-opf-component";
 const SELECT_EVENT = "opfselect";
-const MISSING = Symbol("opf-editor.missing");
 
 export class OPFEditorError extends Error {
   constructor(code, message, details = {}) {
@@ -78,9 +78,7 @@ export function splitOpfPath(path) {
 }
 
 export function opfPathToJsonPointer(path) {
-  const segments = splitOpfPath(path);
-  if (!segments.length) return "";
-  return `/${segments.map(escapePointerSegment).join("/")}`;
+  return formatPointer(splitOpfPath(path));
 }
 
 export function jsonPointerToOpfPath(pointer) {
@@ -88,12 +86,12 @@ export function jsonPointerToOpfPath(pointer) {
 }
 
 export function getValueAtPath(document, path, fallback) {
-  const value = readAtPath(document, splitOpfPath(path));
-  return value === MISSING ? fallback : value;
+  const found = readPointer(document, splitOpfPath(path));
+  return found.found ? found.value : fallback;
 }
 
 export function hasValueAtPath(document, path) {
-  return readAtPath(document, splitOpfPath(path)) !== MISSING;
+  return readPointer(document, splitOpfPath(path)).found;
 }
 
 export function createValuePatch(document, path, value) {
@@ -107,45 +105,27 @@ export function createValuePatch(document, path, value) {
   ];
 }
 
+// Patch semantics (RFC 6902, pointers, inverse patches) live in core's
+// "@openpresentation/opf/patch"; the editor adds its path spellings (dotted OPF
+// paths), its error type and its clone policy on top.
 export function applyJsonPatch(document, operations) {
   assertPatchOperations(operations);
-  let next = clone(document);
-  for (const operation of operations) {
-    next = applyJsonPatchOperation(next, normalizeOperation(operation));
+  const patch = operations.map(normalizeOperation);
+  try {
+    return applyCorePatch(document, patch);
+  } catch (error) {
+    throw editorPatchError(error);
   }
-  return next;
 }
 
 export function invertJsonPatch(document, operations) {
   assertPatchOperations(operations);
-  let current = clone(document);
-  const inverse = [];
-
-  for (const operation of operations.map(normalizeOperation)) {
-    const previous = readAtPath(current, parseJsonPointer(operation.path));
-    if (operation.op !== "add" && previous === MISSING) {
-      throw new OPFEditorError("patch-path-missing", `Cannot invert ${operation.op} for missing path ${operation.path}.`, {
-        path: operation.path,
-        operation
-      });
-    }
-    const addReplacedObjectValue = operation.op === "add" && previous !== MISSING && !pathParentIsArray(current, operation.path);
-    const inversePath = operation.op === "add" ? insertedPathForAdd(operation.path, previous, current) : operation.path;
-
-    current = applyJsonPatchOperation(current, operation);
-
-    if (addReplacedObjectValue) {
-      inverse.unshift({ op: "replace", path: operation.path, value: clone(previous) });
-    } else if (operation.op === "add") {
-      inverse.unshift({ op: "remove", path: inversePath });
-    } else if (operation.op === "replace") {
-      inverse.unshift({ op: "replace", path: operation.path, value: clone(previous) });
-    } else if (operation.op === "remove") {
-      inverse.unshift({ op: "add", path: operation.path, value: clone(previous) });
-    }
+  const patch = operations.map(normalizeOperation);
+  try {
+    return invertPatch(document, patch);
+  } catch (error) {
+    throw editorPatchError(error);
   }
-
-  return inverse;
 }
 
 export function validateOpfDocument(document, validator = validatePresentation) {
@@ -178,8 +158,12 @@ export function createEditorSession(input, options = {}) {
     assertPatchOperations(operations);
     const patches = operations.map(normalizeOperation);
     const before = document;
-    const inversePatches = invertJsonPatch(before, patches);
-    const next = applyJsonPatch(before, patches);
+    let next, inversePatches;
+    try {
+      ({ document: next, inverse: inversePatches } = applyPatchWithInverse(before, patches));
+    } catch (error) {
+      throw editorPatchError(error);
+    }
     const nextValidation = validateOpfDocument(next, options.validate ?? validatePresentation);
 
     if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
@@ -282,6 +266,56 @@ export function createEditorSession(input, options = {}) {
       return setCatalogId(editor, path, catalogKind, id, meta);
     },
     applyPatch: commitPatch,
+    /**
+     * The undo and redo stacks as plain data (oldest entry first): `{ undo: [{ patches, inversePatches, meta }], redo: [...] }`.
+     * Together with `document` this is everything `restoreState` needs to bring a session back, for hosts that persist work.
+     */
+    exportHistory() {
+      const entry = (item) => ({ patches: clonePatchOperations(item.patches), inversePatches: clonePatchOperations(item.inversePatches), meta: clone(item.meta ?? {}) });
+      return { undo: undoStack.map(entry), redo: redoStack.map(entry) };
+    },
+    /**
+     * Replace the document, and optionally the undo and redo history, in one step (a session that was persisted and is being restored).
+     * The document is validated like any edit; the history is checked by replaying it (the inverse patches of the undo stack must walk
+     * back from the document, the redo stack must walk forward), and a history that does not fit is refused with `invalid-history`
+     * before anything changes, so a stale or damaged copy never corrupts the session. Emits one `restore` event.
+     */
+    restoreState(state, meta = {}) {
+      if (!state || typeof state !== "object") throw new OPFEditorError("invalid-state", "restoreState needs { document, undo?, redo? }.");
+      const next = parseInput(state.document);
+      const nextValidation = validateOpfDocument(next, options.validate ?? validatePresentation);
+      if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
+        throw new OPFEditorError("invalid-opf-edit", "The restored document is not valid OPF.", { issues: nextValidation.errors });
+      }
+      const undo = state.undo ?? [], redo = state.redo ?? [];
+      const wellFormed = (entries) => Array.isArray(entries) && entries.every((item) => item && Array.isArray(item.patches) && Array.isArray(item.inversePatches));
+      if (!wellFormed(undo) || !wellFormed(redo)) throw new OPFEditorError("invalid-history", "The undo history is not in the exported shape.");
+      try {
+        // The undo stack must walk back from the document and forward again to exactly the document; the redo stack must walk forward and
+        // back again. Inverse patches alone would apply to any document, so the round trip is what ties the history to this one.
+        let base = next;
+        for (let at = undo.length - 1; at >= 0; at -= 1) base = applyJsonPatch(base, undo[at].inversePatches.map(normalizeOperation));
+        let forward = base;
+        for (let at = 0; at < undo.length; at += 1) forward = applyJsonPatch(forward, undo[at].patches.map(normalizeOperation));
+        if (canonicalJson(forward) !== canonicalJson(next)) throw new Error("the undo history does not reproduce the document");
+        let ahead = next;
+        for (let at = redo.length - 1; at >= 0; at -= 1) ahead = applyJsonPatch(ahead, redo[at].patches.map(normalizeOperation));
+        let back = ahead;
+        for (let at = 0; at < redo.length; at += 1) back = applyJsonPatch(back, redo[at].inversePatches.map(normalizeOperation));
+        if (canonicalJson(back) !== canonicalJson(next)) throw new Error("the redo history does not return to the document");
+      } catch (error) {
+        throw new OPFEditorError("invalid-history", "The undo history does not belong to this document.", { cause: error instanceof Error ? error.message : String(error) });
+      }
+      const entry = (item) => ({ patches: item.patches.map(normalizeOperation), inversePatches: item.inversePatches.map(normalizeOperation), meta: clone(item.meta ?? {}) });
+      document = next;
+      validation = nextValidation;
+      undoStack.length = 0;
+      redoStack.length = 0;
+      undoStack.push(...undo.map(entry));
+      redoStack.push(...redo.map(entry));
+      emit({ type: "restore", patches: [], validation, meta });
+      return { document: clone(document), patches: [], validation };
+    },
     undo(meta = {}) {
       const entry = undoStack.pop();
       if (!entry) return null;
@@ -556,168 +590,67 @@ function clone(value) {
   return JSON.parse(JSON.stringify(value));
 }
 
-function clonePatchOperations(operations) {
-  return operations.map((operation) => clone(operation));
-}
-
-function escapePointerSegment(segment) {
-  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+/** JSON with object keys sorted, so two documents compare equal whatever order their keys were written in. */
+function canonicalJson(value) {
+  return JSON.stringify(value, (key, item) => (item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.keys(item).sort().map((name) => [name, item[name]])) : item));
 }
 
-function unescapePointerSegment(segment) {
-  return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+function clonePatchOperations(operations) {
+  return operations.map((operation) => clone(operation));
 }
 
 function parseJsonPointer(pointer) {
-  if (pointer === "") return [];
-  if (typeof pointer !== "string" || !pointer.startsWith("/")) {
-    throw new OPFEditorError("invalid-json-pointer", "JSON Patch paths must be JSON Pointers.", { path: pointer });
+  try {
+    return parsePointer(pointer);
+  } catch (error) {
+    throw editorPatchError(error);
   }
-  return pointer.slice(1).split("/").map(unescapePointerSegment);
 }
 
 function normalizePatchPath(path) {
   return typeof path === "string" && path.startsWith("/") ? path : opfPathToJsonPointer(path);
 }
 
+const PATCH_OPERATIONS = ["add", "replace", "remove", "move", "copy", "test"];
+
 function normalizeOperation(operation) {
   if (!operation || typeof operation !== "object") {
     throw new OPFEditorError("invalid-patch-operation", "JSON Patch operation must be an object.", { operation });
   }
-  if (!["add", "replace", "remove", "test"].includes(operation.op)) {
+  if (!PATCH_OPERATIONS.includes(operation.op)) {
     throw new OPFEditorError("unsupported-patch-operation", `Unsupported JSON Patch operation: ${operation.op}.`, {
       operation
     });
   }
   if (operation.op === "test" && !Object.prototype.hasOwnProperty.call(operation, "value"))
     throw new OPFEditorError("invalid-patch-operation", "A test operation requires a value.");
-  const normalized = {
-    op: operation.op,
-    path: normalizePatchPath(operation.path)
-  };
-  if (operation.op !== "remove") normalized.value = clone(operation.value);
+  const normalized = { op: operation.op };
+  if (operation.op === "move" || operation.op === "copy") {
+    if (operation.from === undefined) throw new OPFEditorError("invalid-patch-operation", `A ${operation.op} operation requires from.`, { operation });
+    normalized.from = normalizePatchPath(operation.from);
+  }
+  normalized.path = normalizePatchPath(operation.path);
+  if (operation.op === "add" || operation.op === "replace" || operation.op === "test") normalized.value = clone(operation.value);
   return normalized;
 }
 
+// Core patch errors keep their stable codes; the editor reports them as OPFEditorError.
+function editorPatchError(error) {
+  if (!(error instanceof PatchError)) return error;
+  const details = {};
+  if (error.path !== undefined) details.path = error.path;
+  if (error.operation !== undefined) details.operation = error.operation;
+  if (error.index !== undefined) details.index = error.index;
+  if (error.validation) details.issues = error.validation.errors;
+  return new OPFEditorError(error.code, error.message, details);
+}
+
 function assertPatchOperations(operations) {
   if (!Array.isArray(operations)) {
     throw new OPFEditorError("invalid-patch", "JSON Patch must be an array of operations.", { operations });
   }
 }
 
-function readAtPath(document, segments) {
-  let current = document;
-  for (const segment of segments) {
-    if (Array.isArray(current)) {
-      if (segment === "-") return MISSING;
-      const index = Number(segment);
-      if (!Number.isInteger(index) || index < 0 || index >= current.length) return MISSING;
-      current = current[index];
-    } else if (current && typeof current === "object" && Object.prototype.hasOwnProperty.call(current, segment)) {
-      current = current[segment];
-    } else {
-      return MISSING;
-    }
-  }
-  return current;
-}
-
-function jsonEqual(a, b) {
-  if (a === b) return true;
-  if (a === null || b === null || typeof a !== "object" || typeof b !== "object" || Array.isArray(a) !== Array.isArray(b)) return false;
-  const keys = Object.keys(a);
-  return keys.length === Object.keys(b).length && keys.every(key => Object.prototype.hasOwnProperty.call(b, key) && jsonEqual(a[key], b[key]));
-}
-function applyJsonPatchOperation(document, operation) {
-  const segments = parseJsonPointer(operation.path);
-  if (operation.op === "test") {
-    const current = readAtPath(document, segments);
-    if (current === MISSING || !jsonEqual(current, operation.value))
-      throw new OPFEditorError("patch-test-failed", `The value changed at ${operation.path || "/"}.`, {path: operation.path});
-    return clone(document);
-  }
-  if (segments.length === 0) {
-    if (operation.op === "remove") return undefined;
-    return clone(operation.value);
-  }
-
-  const next = clone(document);
-  const parent = readAtPath(next, segments.slice(0, -1));
-  const key = segments.at(-1);
-
-  if (parent === MISSING || parent === null || typeof parent !== "object") {
-    throw new OPFEditorError("patch-parent-missing", `Patch parent does not exist for ${operation.path}.`, {
-      path: operation.path,
-      operation
-    });
-  }
-
-  if (Array.isArray(parent)) applyArrayOperation(parent, key, operation);
-  else applyObjectOperation(parent, key, operation);
-
-  return next;
-}
-
-function insertedPathForAdd(path, previous, document) {
-  if (previous !== MISSING || !path.endsWith("/-")) return path;
-  const parentPath = path.slice(0, -2);
-  const parent = readAtPath(document, parseJsonPointer(parentPath));
-  if (!Array.isArray(parent)) return path;
-  return `${parentPath}/${parent.length}`;
-}
-
-function pathParentIsArray(document, path) {
-  const segments = parseJsonPointer(path);
-  if (segments.length === 0) return false;
-  const parent = readAtPath(document, segments.slice(0, -1));
-  return Array.isArray(parent);
-}
-
-function applyArrayOperation(parent, key, operation) {
-  if (!/^(0|[1-9][0-9]*)$/.test(key) && !(key === "-" && operation.op === "add")) {
-    throw new OPFEditorError("invalid-array-index", `Invalid array index in patch path ${operation.path}.`, { path: operation.path });
-  }
-  const index = key === "-" ? parent.length : Number(key);
-  if (!Number.isInteger(index) || index < 0 || index > parent.length) {
-    throw new OPFEditorError("invalid-array-index", `Invalid array index in patch path ${operation.path}.`, {
-      path: operation.path,
-      operation
-    });
-  }
-
-  if (operation.op === "add") {
-    parent.splice(index, 0, clone(operation.value));
-    return;
-  }
-
-  if (index >= parent.length) {
-    throw new OPFEditorError("patch-path-missing", `Patch path does not exist: ${operation.path}.`, {
-      path: operation.path,
-      operation
-    });
-  }
-
-  if (operation.op === "replace") parent[index] = clone(operation.value);
-  else parent.splice(index, 1);
-}
-
-function applyObjectOperation(parent, key, operation) {
-  if (operation.op === "add") {
-    Object.defineProperty(parent, key, { value: clone(operation.value), writable: true, enumerable: true, configurable: true });
-    return;
-  }
-
-  if (!Object.prototype.hasOwnProperty.call(parent, key)) {
-    throw new OPFEditorError("patch-path-missing", `Patch path does not exist: ${operation.path}.`, {
-      path: operation.path,
-      operation
-    });
-  }
-
-  if (operation.op === "replace") parent[key] = clone(operation.value);
-  else delete parent[key];
-}
-
 function assertElementRoot(root) {
   if (!root || typeof root !== "object" || typeof root.querySelectorAll !== "function") {
     throw new OPFEditorError("invalid-root", "SVG trace binding requires a root element with querySelectorAll.");

package/dist/numbering-panel.d.ts

@@ -0,0 +1,21 @@
+import type { EditorSession } from "./index.js";
+
+export interface NumberingPanelOptions {
+  editor: EditorSession;
+  /** The path the host has selected (a list, an entry of one, or anything inside one); the panel numbers that list. */
+  getTarget?: () => string | undefined;
+  /** The slide whose lists the panel offers when nothing in a list is selected. */
+  getSlideIndex?: () => number;
+  /** Called with every status or error message the panel shows. */
+  onStatus?: (message: string, info: { error: boolean }) => void;
+}
+export interface NumberingPanel {
+  element: HTMLElement;
+  /** Show another list (a path in it); with no argument, re-read the host's selection. */
+  setTarget(path?: string): void;
+  /** Redraw from the document (called on every document change). */
+  refresh(): void;
+  destroy(): void;
+}
+/** Mount the numbering control: number a list, pick the style, start and suffix, set them per level, and restart the count at an entry. Every change is one undoable edit. */
+export declare function createNumberingPanel(container: HTMLElement, options: NumberingPanelOptions): NumberingPanel;

package/dist/numbering-panel.js

@@ -0,0 +1,200 @@
+// List numbering panel (RR-33): the DOM control over the numbering model. It numbers a list (or turns numbering off), picks
+// the style, start and suffix, optionally per list level, shows the markers the list will draw, and restarts the count at
+// the selected entry. The panel owns no document state: every change is one validated, undoable edit through the session, and
+// the panel redraws from the document. Importing this module does not need a DOM; mounting does.
+import {
+  MAX_NUMBERING_LEVELS,
+  MAX_NUMBERING_START,
+  NUMBERING_STYLE_OPTIONS,
+  NUMBERING_SUFFIX_OPTIONS,
+  findNumberableLists,
+  numberingAvailable,
+  numberingState,
+  numberingValue,
+  setEntryStart,
+  setNumbering,
+} from "./numbering.js";
+
+let panelCounter = 0;
+
+function h(doc, tag, attributes = {}, ...children) {
+  const element = doc.createElement(tag);
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined || value === false) continue;
+    if (key === "class") element.className = value;
+    else if (key === "text") element.textContent = value;
+    else if (key.startsWith("on")) element.addEventListener(key.slice(2), value);
+    else element.setAttribute(key, value === true ? "" : String(value));
+  }
+  for (const child of children) if (child) element.append(child);
+  return element;
+}
+
+/**
+ * Mount the numbering control. Options: `editor` (a session), `getTarget()` (the path the host has selected: a list, an entry
+ * or anything inside one), `getSlideIndex()` (the slide whose lists are offered when nothing in a list is selected) and
+ * `onStatus(message, {error})`.
+ */
+export function createNumberingPanel(container, options) {
+  if (!numberingAvailable()) throw new Error("The numbering control needs a core release that ships numbering.");
+  const { editor, getTarget, getSlideIndex, onStatus } = options;
+  const doc = container.ownerDocument;
+  const id = `opf-numbering-${++panelCounter}`;
+  let explicit;
+  let destroyed = false;
+  let drawn = "";
+
+  const root = h(doc, "section", { class: "opf-numbering-panel", "data-opf-component": "numbering-panel", "aria-label": "List numbering" });
+  const body = h(doc, "div", { class: "opf-numbering-body" });
+  const live = h(doc, "p", { class: "opf-numbering-live", role: "status", "aria-live": "polite" });
+  root.append(body, live);
+  container.append(root);
+
+  const say = (message, error = false) => {
+    live.textContent = message;
+    live.dataset.error = error ? "true" : "false";
+    onStatus?.(message, { error });
+  };
+
+  const currentPath = () => {
+    const slide = getSlideIndex?.() ?? 0;
+    const lists = findNumberableLists(editor.document, slide);
+    const wanted = explicit ?? getTarget?.();
+    if (wanted && numberingState(editor.document, wanted)) return { path: wanted, lists };
+    return { path: lists[0]?.path, lists };
+  };
+
+  const optionElements = (options, selected) => options.map((option) => h(doc, "option", { value: option.value, text: option.label, selected: option.value === selected }));
+
+  function levelRow(index, level, { label, enabled }) {
+    const prefix = `${id}-l${index}`;
+    const style = h(doc, "select", { id: `${prefix}-style`, "data-field": "style", "data-level": index, disabled: !enabled }, ...optionElements(NUMBERING_STYLE_OPTIONS, level.style));
+    const start = h(doc, "input", { id: `${prefix}-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: level.start, "data-field": "start", "data-level": index, disabled: !enabled });
+    const suffix = h(doc, "select", { id: `${prefix}-suffix`, "data-field": "suffix", "data-level": index, disabled: !enabled }, ...optionElements(NUMBERING_SUFFIX_OPTIONS, level.suffix));
+    return h(doc, "div", { class: "opf-numbering-level", role: "group", "aria-label": label },
+      h(doc, "span", { class: "opf-numbering-level-name", text: label }),
+      h(doc, "label", { for: style.id, text: "Style" }), style,
+      h(doc, "label", { for: start.id, text: "Start at" }), start,
+      h(doc, "label", { for: suffix.id, text: "After the number" }), suffix);
+  }
+
+  function readLevels(state) {
+    const rows = [...body.querySelectorAll(".opf-numbering-level")];
+    return rows.map((row) => ({
+      style: row.querySelector('[data-field="style"]').value,
+      start: Number(row.querySelector('[data-field="start"]').value),
+      suffix: row.querySelector('[data-field="suffix"]').value,
+    })).slice(0, state.perLevel ? MAX_NUMBERING_LEVELS : 1);
+  }
+
+  function commit(path, value, message) {
+    try {
+      setNumbering(editor, path, value);
+      say(message);
+    } catch (error) {
+      say(error?.issues?.[0]?.message ?? error?.message ?? String(error), true);
+      draw(true);
+    }
+  }
+
+  function draw(force = false) {
+    if (destroyed) return;
+    const { path, lists } = currentPath();
+    const state = path ? numberingState(editor.document, path) : undefined;
+    const signature = JSON.stringify([path, state, lists.map((entry) => [entry.path, entry.numbered])]);
+    if (!force && signature === drawn) return;
+    drawn = signature;
+    body.replaceChildren();
+    if (!state) {
+      body.append(h(doc, "p", { class: "opf-numbering-empty", text: "This slide has no list. Add a list or a bullets block to number it." }));
+      return;
+    }
+    const enabled = state.numbered;
+    if (lists.length > 1) {
+      const select = h(doc, "select", { id: `${id}-list`, "aria-label": "List" }, ...lists.map((entry) => h(doc, "option", { value: entry.path, text: `${entry.label} (${entry.count} ${entry.count === 1 ? "entry" : "entries"})`, selected: entry.path === state.path })));
+      select.addEventListener("change", () => { explicit = select.value; draw(true); });
+      body.append(h(doc, "div", { class: "opf-numbering-list" }, h(doc, "label", { for: select.id, text: "List" }), select));
+    }
+    const toggle = h(doc, "input", { id: `${id}-enabled`, type: "checkbox", checked: enabled });
+    toggle.checked = enabled;
+    toggle.addEventListener("change", () => {
+      if (toggle.checked) commit(state.path, numberingValue(state.levels), "Numbered the list.");
+      else commit(state.path, undefined, "Numbering turned off; the list shows bullets again.");
+    });
+    body.append(h(doc, "div", { class: "opf-numbering-toggle" }, toggle, h(doc, "label", { for: toggle.id, text: "Number this list" })));
+
+    const levels = state.perLevel ? Array.from({ length: Math.min(MAX_NUMBERING_LEVELS, Math.max(state.depth, state.levels.length)) }, (_, index) => state.levels[Math.min(index, state.levels.length - 1)]) : [state.levels[0]];
+    const rowsHost = h(doc, "div", { class: "opf-numbering-levels" });
+    levels.forEach((level, index) => rowsHost.append(levelRow(index, level, { label: state.perLevel ? `Level ${index + 1}` : "Every level", enabled })));
+    rowsHost.addEventListener("change", (event) => {
+      if (!event.target.closest(".opf-numbering-level")) return;
+      try {
+        commit(state.path, numberingValue(readLevels(state)), "Updated the numbering.");
+      } catch (error) {
+        say(error?.message ?? String(error), true);
+        draw(true);
+      }
+    });
+    body.append(rowsHost);
+
+    if (state.depth > 1 || state.perLevel) {
+      const perLevel = h(doc, "input", { id: `${id}-per-level`, type: "checkbox", disabled: !enabled });
+      perLevel.checked = state.perLevel;
+      perLevel.addEventListener("change", () => {
+        // Turning it on starts an outline (1. a. i.), because identical levels would be written as one entry again.
+        const cycle = ["arabic", "alpha-lower", "roman-lower", "alpha-upper", "roman-upper"];
+        const next = [{ ...state.levels[0] }];
+        for (let index = 1; index < Math.min(MAX_NUMBERING_LEVELS, Math.max(2, state.depth)); index++) {
+          const previous = next[index - 1].style;
+          const style = cycle.slice((index - 1) % cycle.length).concat(cycle).find((candidate) => candidate !== previous);
+          next.push({ ...state.levels[0], start: 1, style });
+        }
+        commit(state.path, perLevel.checked ? numberingValue(next) : numberingValue([state.levels[0]]), perLevel.checked ? "Numbering can now differ per level." : "Every level uses the first level's numbering.");
+      });
+      body.append(h(doc, "div", { class: "opf-numbering-toggle" }, perLevel, h(doc, "label", { for: perLevel.id, text: "Different numbering for each level" })));
+    }
+
+    if (enabled) {
+      const shown = state.markers.slice(0, 8).map((marker) => marker.text).join("  ");
+      body.append(h(doc, "p", { class: "opf-numbering-preview", "aria-label": "Markers", text: `${shown}${state.markers.length > 8 ? "  …" : ""}` }));
+      if (state.markers.some((marker) => marker.adapted)) body.append(h(doc, "p", { class: "opf-numbering-note", text: "Roman numerals stop at 3999; larger numbers are drawn in arabic." }));
+    }
+
+    if (enabled && state.entry) {
+      const start = h(doc, "input", { id: `${id}-entry-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: state.entry.start ?? "", placeholder: state.entry.marker ?? "" });
+      const apply = () => {
+        const text = start.value.trim();
+        try {
+          setEntryStart(editor, `${state.path}.${state.entry.index}`, text === "" ? undefined : Number(text));
+          say(text === "" ? "Removed the restart." : `Entry ${state.entry.index + 1} now starts at ${text}.`);
+        } catch (error) {
+          say(error?.issues?.[0]?.message ?? error?.message ?? String(error), true);
+          draw(true);
+        }
+      };
+      start.addEventListener("change", apply);
+      body.append(h(doc, "div", { class: "opf-numbering-entry" },
+        h(doc, "label", { for: start.id, text: `Entry ${state.entry.index + 1} starts at` }), start,
+        h(doc, "span", { class: "opf-numbering-help", text: "Leave empty to continue the count. Later entries carry on from it." })));
+    }
+  }
+
+  const unsubscribe = editor.subscribe(() => draw());
+  draw(true);
+
+  return {
+    element: root,
+    setTarget(path) {
+      explicit = path;
+      draw(true);
+    },
+    refresh() {
+      draw(true);
+    },
+    destroy() {
+      destroyed = true;
+      unsubscribe();
+      root.remove();
+    },
+  };
+}

package/dist/numbering.d.ts

@@ -0,0 +1,62 @@
+import type { EditorSession } from "./index.js";
+
+export type NumberingStyleName = "arabic" | "roman-upper" | "roman-lower" | "alpha-upper" | "alpha-lower";
+export type NumberingSuffixName = "period" | "paren" | "paren-both";
+/** One list level's numbering with every default applied. */
+export interface NumberingLevel { style: NumberingStyleName; start: number; suffix: NumberingSuffixName }
+/** The `numbering` field: a style name, an object (every level) or an array with one entry per level. */
+export type NumberingValue = NumberingStyleName | Partial<NumberingLevel> | readonly (NumberingStyleName | Partial<NumberingLevel>)[];
+
+export declare const NUMBERING_STYLE_OPTIONS: readonly { value: NumberingStyleName; label: string; sample: string }[];
+export declare const NUMBERING_SUFFIX_OPTIONS: readonly { value: NumberingSuffixName; label: string; sample: string }[];
+export declare const MAX_NUMBERING_LEVELS: 9;
+export declare const MAX_NUMBERING_START: 32767;
+
+/** True when the core this editor runs on composes numbered lists. */
+export declare function numberingAvailable(): boolean;
+
+export interface ListPayloadLocation {
+  /** The payload that owns the list ("" for a document-level path is not possible; a slide, region or block). */
+  payloadPath: string;
+  field: "items" | "bullets";
+  /** Path of the list array itself. */
+  path: string;
+  payload: Record<string, unknown>;
+  /** The entry index when the path points at or into an entry. */
+  entry?: number;
+}
+/** Where a list lives for a path that points at it or into it (`slides.0.items`, `slides.0.items.2`, `slides.0.left.items.1.text`). */
+export declare function listPayloadAt(document: unknown, path: string): ListPayloadLocation | undefined;
+
+export interface NumberableList { path: string; payloadPath: string; field: "items" | "bullets"; label: string; count: number; numbered: boolean }
+/** Every list of a slide: path, label, entry count and whether it is numbered. */
+export declare function findNumberableLists(document: unknown, slideIndex: number): NumberableList[];
+
+/** The shortest `numbering` value for per-level settings (a style name, an object of the non-default fields, or an array). */
+export declare function numberingValue(levels: readonly Partial<NumberingLevel>[]): NumberingValue;
+
+export interface NumberingMarker { index: number; level: number; text: string; value: number; adapted?: "roman-range" }
+export interface NumberingState {
+  path: string;
+  payloadPath: string;
+  field: "items" | "bullets";
+  count: number;
+  numbered: boolean;
+  /** True when the levels differ (an array in the document). */
+  perLevel: boolean;
+  /** One entry when the numbering applies to every level, else one per authored level. */
+  levels: NumberingLevel[];
+  /** Levels the list uses (deepest entry level + 1, at most 9). */
+  depth: number;
+  value?: NumberingValue;
+  /** The markers the list draws, one per entry (empty when not numbered). */
+  markers: NumberingMarker[];
+  /** The entry the path selects, with its own `start` and the marker it draws. */
+  entry?: { index: number; start?: number; marker?: string };
+}
+export declare function numberingState(document: unknown, path: string): NumberingState | undefined;
+
+/** Number a list, change its numbering, or (with `undefined` or `null`) turn it off, as one undoable validated edit. Turning it off also removes the entry `start` values. */
+export declare function setNumbering(editor: EditorSession, path: string, value: NumberingValue | undefined | null, meta?: Record<string, unknown>): unknown;
+/** Restart the numbering at an entry (`undefined` or `null` removes the restart), as one undoable validated edit. */
+export declare function setEntryStart(editor: EditorSession, itemPath: string, start: number | undefined | null, meta?: Record<string, unknown>): unknown;