@openpresentation/opf-editor 0.26.9 → 0.27.0

package/README.md

@@ -2,6 +2,38 @@
 
 Unfinished prepared shaping work is preserved in the [September 15 roadmap](docs/roadmap-shaping-20260915.md); it is not part of the published runtime.
 
+## Embed the editor (CE-06)
+
+One call mounts the whole editor, over one session and one fonts handle: the source pane, the canvas, the slide row, Present, Export, the sorter, the outline, Layout Studio, Review, Find and autosave, each part optional.
+
+```js
+import "@openpresentation/opf-editor/styles.css";
+import { createOpfEditor } from "@openpresentation/opf-editor/workspace";
+
+const editor = createOpfEditor(element, {
+  document,                          // an OPF object or its JSON text, or `session` to adopt one
+  catalogs: [gallery],
+  fonts,                             // the renderer's fonts handle, a lease { fonts, release }, a promise or a function of either
+  persistence: { key: "my-deck" },   // optional autosave and restore prompt
+  theme: { colorScheme: "auto", tokens: { accent: "hsl(262 60% 38%)" } },
+  onChange: ({ document }) => save(document),
+});
+await editor.ready;
+editor.setView("outline");
+editor.destroy();
+```
+
+From React 18 or 19 (StrictMode-safe, renders an empty container on the server):
+
+```jsx
+import { OpfEditor, useOpfDocument } from "@openpresentation/opf-editor/react";
+
+<OpfEditor document={deck} fonts={loadFonts} catalogs={[gallery]} theme={theme} onEditor={setEditor} />;
+const document = useOpfDocument(editor); // also useOpfSelection(editor), useOpfEditor(options)
+```
+
+[docs/embedding.md](docs/embedding.md) lists the layouts, `panels`, `slots` (your own arrangement), every option, the handle, the events and the React bindings; [docs/theming.md](docs/theming.md) is the token contract (surface, text, accent, border, radius and font, light and dark) and the `theme` option. `examples/playground.js` is a thin user of it.
+
 ## Install the editor and optional export dependencies (RR-63)
 
 `@openpresentation/opf-render` is an optional peer of the editor, and from render 0.16 its heavy pieces are optional peers too, so install only what you use. The editor itself draws with `@openpresentation/opf-render/svg` and loads fonts with `/fonts-browser`, which need nothing else. Add:
@@ -356,6 +388,25 @@ editor.redo();
 
 `createSvgTraceBinding` only reads `data-opf-path`; it does not require a hosted service, a second renderer, storage, analytics, auth, or product chrome. Host applications decide how selected paths appear in their own inspector UI.
 
+### Ids, id-addressed events and `expectHash` (CE-04)
+
+Slides and blocks can carry an `id` (core's `assignIds` fills the missing ones; `editor.assignIds()` does it as one undoable edit and returns `null` when none is missing). A path may name an element by id instead of by index, `slides.@intro.title` or `/slides/@intro/blocks/@kpi/text`, in `get`, `set` and `applyPatch`; the session resolves it against the open document.
+
+By default the events are unchanged and carry index paths. Create the session with `idPaths: true` and every change and every `subscribe` event also carries the same patches addressed by id, each written against the document it applies to:
+
+```js
+const editor = createEditorSession(doc, { idPaths: true });
+editor.subscribe((event) => {
+  event.patches;          // [{ op: "replace", path: "/slides/1/blocks/1/text", value: "Edited" }]
+  event.idPatches;        // [{ op: "replace", path: "/slides/@kpis/blocks/@note/text", value: "Edited" }]
+  event.idInversePatches; // patch events; undo events have idPatches and idRedoPatches
+});
+```
+
+The id form still means the same thing on a replica whose slides are in another order, so a host can send it to a sync server or attach comments to it. Elements without an `id` keep their indexes, and an insertion keeps its index (or `-`) as the last token. It costs one extra walk of each patch.
+
+`editor.documentHash()` is core's `documentHash` of the open document (`sha256:` and 64 hex digits, independent of key order). Pass it to `editor.applyPatch(ops, meta, { expectHash })` and the edit applies only while the document is still that one; otherwise it throws an `OPFEditorError` with code `patch-hash-mismatch` (`details.expected`, `details.actual`), changes nothing and emits nothing.
+
 ## Catalog Controls
 
 Catalog helpers commit catalog references (`id` or `name:id`) that resolve in the document or the session's registered catalogs, instead of accepting freeform incompatible values:
@@ -767,10 +818,11 @@ import "@openpresentation/opf-editor/styles.css";
 
 `pnpm run build` writes `dist/styles.css`: the token layer (`src/styles/tokens.css`) first, then every other `src/styles/*.css` in alphabetical order. It is plain CSS with no preprocessor, no `@import` and no `url()`: nothing is fetched. The package bundles no fonts either; load Inter and Geist Mono yourself (or leave the fallbacks: `system-ui` and `ui-monospace`). The panels that existed before it (design controls, review, slide manager, find, fill template, numbering, chart options, data grid, crop, the custom layout editor, the JSON editor and the restore banner) are styled with the tokens and nothing else. The find, review, crop and data-grid components still inject a small fallback stylesheet of their own, so they look as before when you do not import `styles.css`; with it, its rules win whichever `<style>` comes last.
 
-**Tokens.** Every rule reads only `--opf-ui-*` custom properties, defined on `:root` and on `.opf-ui`, light by default. Override any of them on `:root`, on a wrapper with the class `opf-ui`, or on one component's container:
+**Tokens.** Every rule reads only `--opf-ui-*` custom properties, defined on `:root` and on `.opf-ui`, light by default. The whole contract, with light and dark values and what each token is for, is in [docs/theming.md](docs/theming.md). `createOpfEditor({ theme })` sets them for you; by hand, set them on the `.opf-ui` elements themselves (every component root carries the class and declares its own defaults, so a value set on a wrapper does not reach it) with a selector that outranks `.dark .opf-ui`:
 
 ```css
-.my-editor.opf-ui {
+html .opf-ui,
+html.dark .opf-ui {
   --opf-ui-accent: hsl(262 60% 38%);
   --opf-ui-accent-strong: hsl(262 60% 38%);
   --opf-ui-ring: hsl(262 60% 38%);
@@ -792,7 +844,7 @@ import "@openpresentation/opf-editor/styles.css";
 
 Put the class `opf-ui` on an element that wraps a mounted component to get the base rules: the font, the text color, `box-sizing: border-box`, a 2px `--opf-ui-ring` outline with a 2px offset on `:focus-visible`, and no transitions under `prefers-reduced-motion: reduce`.
 
-**Dark mode.** The dark values apply under `.dark .opf-ui`, `.opf-ui.dark`, `[data-theme="dark"]` (on the root or any ancestor) and `:root.dark`. The host decides when: toggle `class="dark"` or `data-theme="dark"` on `<html>`, or on the wrapper. The stylesheet does not read `prefers-color-scheme`, so a host that wants to follow the system setting sets the attribute from `matchMedia("(prefers-color-scheme: dark)")`. Dark also sets `color-scheme: dark`, so native controls follow.
+**Dark mode.** The dark values apply under `.dark .opf-ui`, `.opf-ui.dark`, `[data-theme="dark"]` (on the root or any ancestor) and `:root.dark`; `[data-theme="light"]` on an ancestor or on the surface forces light inside a dark page. The host decides when: toggle `class="dark"` or `data-theme="dark"` on `<html>`, or on the wrapper. The stylesheet does not read `prefers-color-scheme`; `createOpfEditor({ theme: { colorScheme: "auto" } })` follows it for you, and a host that mounts components itself sets the attribute from `matchMedia("(prefers-color-scheme: dark)")`. Dark also sets `color-scheme: dark`, so native controls follow.
 
 **Touch.** `data-density="touch"` on an `.opf-ui` element raises `--opf-ui-control-h` from 32px to 40px for everything inside it (the mobile design). The new components take the same value as a `density: "comfortable" | "touch"` option.
 
@@ -973,7 +1025,9 @@ Put the opened document in the session with `editor.replaceDocument(document)` (
 
 ## Optional React Bindings
 
-React bindings are isolated under `@openpresentation/opf-editor/react` and require the host app to pass its React runtime. The core package does not add React to the critical path.
+React bindings are isolated under `@openpresentation/opf-editor/react`; React (18 or later) is an optional peer, needed only by that entry point. The core package does not add React to the critical path.
+
+`<OpfEditor>`, `useOpfEditor`, `useOpfDocument` and `useOpfSelection` mount and read the embeddable editor ([Embed the editor](#embed-the-editor-ce-06)). The older factory below builds two controls over a session you already have, with the React you pass:
 
 ```jsx
 import { createOPFReactComponents } from "@openpresentation/opf-editor/react";

package/dist/canvas-variables.d.ts

@@ -0,0 +1,15 @@
+import type { EditorSession } from "./index.js";
+import type { CanvasEditor } from "./canvas.js";
+
+/**
+ * For a host that mounts the canvas itself (`createCanvasEditor`) and draws `{{variables}}` resolved (`renderOptions.variables: {}`): a press on text
+ * that holds a variable token opens the field's properties form (which edits the authored value) instead of an inline edit of the resolved glyphs,
+ * and a press on text with no field of its own calls `focusSource`. `resolved()` says whether the canvas draws variables resolved now (a template deck
+ * draws them as authored). Returns a function that removes the listeners. `createOpfEditor({ variables: "resolved" })` (`@openpresentation/opf-editor/workspace`) does this for you.
+ */
+export declare function installCanvasVariableEditing(
+  host: HTMLElement,
+  editor: EditorSession,
+  canvas: CanvasEditor,
+  options?: { resolved?: () => boolean; focusSource?: () => void },
+): () => void;

package/dist/canvas-variables.js

@@ -0,0 +1,52 @@
+// CE-06 (promoted from openpresentation.org's playground runtime): editing a document whose `{{variables}}` the canvas draws resolved.
+// With `variables: "resolved"` the canvas shows a deck's variables filled in, and a glyph offset of the resolved text does not address
+// the authored `{{token}}`. A press on such text opens the field's properties form (which edits the authored value) instead of an
+// inline text edit, and a press on text that has no field of its own focuses the source pane.
+
+function hasSourceToken(value) {
+  if (typeof value === "string") return value.includes("{{") || value.startsWith("var:");
+  if (Array.isArray(value)) return value.some(hasSourceToken);
+  return value !== null && typeof value === "object" && Object.values(value).some(hasSourceToken);
+}
+
+/**
+ * Route inline edits of text that holds a variable token to the canvas's properties form. `resolved()` says whether the canvas currently
+ * draws variables resolved (a template deck draws them as authored). Returns a function that removes the listeners.
+ */
+export function installCanvasVariableEditing(host, editor, canvas, { resolved = () => true, focusSource } = {}) {
+  function route(event) {
+    if (!resolved() || !(event.target instanceof Element)) return;
+    const target = event.target.closest('svg [data-opf-path][role="button"]');
+    if (!target || !host.contains(target) || !target.querySelector("text")) return;
+    const path = target.getAttribute("data-opf-path");
+    const value = editor.get(path);
+    const inline = ((typeof value === "string" || typeof value === "number") && !/\.(image|video)$/.test(path))
+      || (Array.isArray(value) && target.hasAttribute("data-opf-rich-text"));
+    if (value !== undefined && (!inline || !hasSourceToken(value))) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    if (value === undefined) {
+      focusSource?.();
+      return;
+    }
+    // The click following pointerdown must not commit and reopen the same form.
+    if (canvas.editingPath !== path) canvas.editProperties(path);
+  }
+  function pointer(event) {
+    // A touch press may begin scrolling. Its actual click opens the form.
+    if (event.pointerType !== "touch" && event.button === 0) route(event);
+  }
+  function key(event) {
+    if (!event.isComposing && event.keyCode !== 229 && ["Enter", " ", "F2"].includes(event.key)) route(event);
+  }
+  host.addEventListener("pointerdown", pointer, true);
+  host.addEventListener("click", route, true);
+  host.addEventListener("dblclick", route, true);
+  host.addEventListener("keydown", key, true);
+  return () => {
+    host.removeEventListener("pointerdown", pointer, true);
+    host.removeEventListener("click", route, true);
+    host.removeEventListener("dblclick", route, true);
+    host.removeEventListener("keydown", key, true);
+  };
+}

package/dist/canvas.js

@@ -113,7 +113,7 @@ export function createCanvasEditor(container, options = {}) {
   notice.hidden = true;
   const style = doc.createElement("style");
   style.textContent =
-    ".opf-canvas-preview>svg{display:block;width:100%;height:auto}.opf-canvas [data-canvas-target]{cursor:text}.opf-canvas .opf-inline-input::selection{background:#8975d933;color:var(--opf-inline-selection-color,transparent)}.opf-canvas [data-canvas-target]:focus{outline:none}.opf-canvas [data-canvas-target]:hover>.opf-selection{stroke:#9c90df}.opf-canvas [data-canvas-selected]>.opf-selection,.opf-canvas [data-canvas-target]:focus-visible>.opf-selection{stroke:#7765d0}.opf-canvas [data-canvas-target][data-canvas-editing]>.opf-selection{stroke:none}.opf-canvas button:focus-visible,.opf-canvas textarea:focus-visible,.opf-canvas input:focus-visible{outline:2px solid #8170d5;outline-offset:2px}";
+    ".opf-canvas-preview>svg{display:block;width:100%;height:auto}.opf-canvas [data-canvas-target]{cursor:text}.opf-canvas .opf-inline-input::selection{background:#8975d933;color:var(--opf-inline-selection-color,transparent)}.opf-canvas [data-canvas-target]:focus,.opf-canvas .opf-selection:focus{outline:none}.opf-canvas [data-canvas-target]:hover>.opf-selection{stroke:#9c90df}.opf-canvas [data-canvas-selected]>.opf-selection,.opf-canvas [data-canvas-target]:focus-visible>.opf-selection,.opf-canvas .opf-selection:focus-visible{stroke:#7765d0}.opf-canvas [data-canvas-target][data-canvas-editing]>.opf-selection{stroke:none}.opf-canvas button:focus-visible,.opf-canvas textarea:focus-visible,.opf-canvas input:focus-visible{outline:2px solid #8170d5;outline-offset:2px}";
   root.append(style, preview, overlay, notice);
   container.replaceChildren(root);
   const report = (error) => {
@@ -167,6 +167,14 @@ export function createCanvasEditor(container, options = {}) {
       (node) => node.getAttribute("data-opf-path") === path,
     );
   }
+  // A target that holds other targets (a table with its cells, a chart with its labels) is a plain group, so it is never focusable
+  // itself (axe nested-interactive); keyboard focus for it lives on its selection handle, the first child. A leaf target takes focus.
+  function handleOf(node) {
+    return node?.getAttribute("role") === "group" ? node.querySelector(":scope > .opf-selection[tabindex]") : null;
+  }
+  function focusTarget(node, options = { preventScroll: false }) {
+    (handleOf(node) ?? node)?.focus?.(options);
+  }
   function choose(path) {
     selectedPath = path;
     imageCropper?.sync(path);
@@ -350,7 +358,12 @@ export function createCanvasEditor(container, options = {}) {
         // A touch tap has no pointerdown entry (a touch press may start a scroll): it enters on the click itself.
         const kind = editKind(path);
         if (textEntry === "click" && event.detail > 0 && (kind === "text" || kind === "rich-text")) startEdit(path, { point: event });
-        else choose(path);
+        else {
+          choose(path);
+          // A press on a container's own drawing (not on a child target) used to focus the container; now it focuses its handle.
+          const handle = handleOf(node);
+          if (handle && !event.target.closest?.(".opf-selection")) handle.focus({ preventScroll: true });
+        }
       });
       node.addEventListener("dblclick", (event) => {
         event.preventDefault();
@@ -368,6 +381,21 @@ export function createCanvasEditor(container, options = {}) {
       });
       if (path === selectedPath) node.setAttribute("data-canvas-selected", "");
     }
+    // WCAG 4.1.2 / axe nested-interactive: an interactive element must not contain interactive descendants. A target that holds
+    // other targets is a named group; the button and the tab stop move to its selection handle (the transparent rect that already
+    // covers it and takes its pointer presses), so the container stays selectable by click, Tab and Enter, and its children stay buttons.
+    for (const node of svg.querySelectorAll("g[data-canvas-target]")) {
+      if (!node.querySelector("[data-canvas-target]")) continue;
+      const handle = node.querySelector(":scope > .opf-selection");
+      if (!handle) continue;
+      const field = node.getAttribute("data-opf-path").split(".").at(-1);
+      handle.setAttribute("role", "button");
+      handle.setAttribute("tabindex", "0");
+      handle.setAttribute("aria-label", node.getAttribute("aria-label"));
+      node.setAttribute("role", "group");
+      node.removeAttribute("tabindex");
+      node.setAttribute("aria-label", `${field.charAt(0).toUpperCase()}${field.slice(1)}`);
+    }
     layoutHandles.update(presentation, geometry);
     blockControls.update(presentation, geometry);
     imageCropper?.update();
@@ -924,7 +952,7 @@ export function createCanvasEditor(container, options = {}) {
       options.propertiesContainer?.replaceChildren();
       clearNotice();
       render();
-      getTarget(edit.path)?.focus();
+      focusTarget(getTarget(edit.path));
       options.onCommit?.({ path: edit.path, editor });
       return true;
     } catch (error) {
@@ -949,7 +977,7 @@ export function createCanvasEditor(container, options = {}) {
     options.propertiesContainer?.replaceChildren();
     if (clear) clearNotice();
     render();
-    getTarget(path)?.focus();
+    focusTarget(getTarget(path));
     options.onCancel?.({ path });
   }
   function setSlide(index) {
@@ -984,7 +1012,7 @@ export function createCanvasEditor(container, options = {}) {
       if (!node) continue;
       choose(candidate);
       node.scrollIntoView?.({ block: "nearest", inline: "nearest" });
-      if (focus) node.focus?.({ preventScroll: true });
+      if (focus) focusTarget(node, { preventScroll: true });
       return candidate;
     }
     return null;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
 import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
 import type { Catalog, Fonts, PresentationStats, SlideContextDiagnostic, StatsOptions, ValidationReport } from "@openpresentation/opf";
+import type { AssignIdsOptions } from "@openpresentation/opf/ids";
 export * from "./catalogs.js";
 /**
  * What the editor adds to the options of `composeSlide` and `paginateSlide`: `fonts` is the renderer's fonts handle (`loadFonts()`), whose
@@ -31,7 +32,10 @@ export declare const runtimePolicy: Readonly<{
   deterministicLocalExecution: true;
 }>;
 
-/** RFC 6902 operations, executed by core's `@openpresentation/opf/patch`. Paths are JSON Pointers or dotted OPF paths. */
+/**
+ * RFC 6902 operations, executed by core's `@openpresentation/opf/patch`. Paths are JSON Pointers or dotted OPF paths. In an array, a
+ * token `@id` names the element whose `id` is `id` (`/slides/@intro/title`, or `slides.@intro.title` as an OPF path).
+ */
 export type JsonPatchOperation =
   | { op: "add"; path: string; value: unknown }
   | { op: "replace"; path: string; value: unknown }
@@ -54,6 +58,14 @@ export interface EditorChange {
   patches: JsonPatchOperation[];
   inversePatches?: JsonPatchOperation[];
   redoPatches?: JsonPatchOperation[];
+  /**
+   * With the session option `idPaths`: `patches`, `inversePatches` and `redoPatches` addressed by id (`/slides/@intro/title`), each
+   * written against the document it applies to (core's `toIdPatch`). Elements without an `id` keep their indexes; an insertion keeps
+   * its index (or `-`) as the last token.
+   */
+  idPatches?: JsonPatchOperation[];
+  idInversePatches?: JsonPatchOperation[];
+  idRedoPatches?: JsonPatchOperation[];
   validation: ValidationReport;
 }
 
@@ -63,6 +75,10 @@ export interface EditorEvent {
   patches: JsonPatchOperation[];
   inversePatches?: JsonPatchOperation[];
   redoPatches?: JsonPatchOperation[];
+  /** With the session option `idPaths`: the id-addressed form of `patches`, `inversePatches` and `redoPatches` (see `EditorChange`). `[]` for `restore` and `catalogs`. */
+  idPatches?: JsonPatchOperation[];
+  idInversePatches?: JsonPatchOperation[];
+  idRedoPatches?: JsonPatchOperation[];
   validation: ValidationReport;
   meta?: Record<string, unknown>;
   snapshot: EditorSnapshot;
@@ -79,6 +95,12 @@ export interface PrecomputedValidation {
 }
 export interface ApplyPatchOptions {
   validated?: PrecomputedValidation;
+  /**
+   * Apply the edit only while the open document is the one this hash (`session.documentHash()` or core's `documentHash`) was taken
+   * from. A document that changed since throws an `OPFEditorError` with code `patch-hash-mismatch` and `details.expected` and
+   * `details.actual`; nothing is applied. A value that is not a hash throws `invalid-expect-hash`.
+   */
+  expectHash?: string;
 }
 
 export interface EditorSession {
@@ -107,6 +129,14 @@ export interface EditorSession {
    * current `catalogs` list (the same object); otherwise the session validates the document itself. It is never stored in `meta` or the history.
    */
   applyPatch(operations: JsonPatchOperation[], meta?: Record<string, unknown>, options?: ApplyPatchOptions): EditorChange;
+  /** The content hash of the open document (core's `documentHash`: `sha256:` and 64 hex digits, independent of key order). Use it as `applyPatch`'s `expectHash`. */
+  documentHash(): string;
+  /**
+   * Give every slide and block without an `id` one (core's `assignIds`) as one undoable edit. Returns the change, or `null` when every
+   * slide and block already has an id. `meta.source` defaults to `"assign-ids"`. A `generate` that returns an unusable id throws an
+   * `OPFEditorError` with code `invalid-id` or `duplicate-id`.
+   */
+  assignIds(options?: AssignIdsOptions, meta?: Record<string, unknown>): EditorChange | null;
   /**
    * Open a different document in the session: the whole document is replaced as one undoable change, and the replacement is never
    * read as an edit of the catalog records the two documents share, so nothing under `catalogs.default` or a named group is forked
@@ -128,6 +158,12 @@ export interface CreateEditorSessionOptions {
   rejectInvalid?: boolean;
   /** The host's catalogs (for example `[gallery]` from `@openpresentation/gallery`): resolution, validation, pickers, embedding. */
   catalogs?: readonly Catalog[];
+  /**
+   * Also report every change and event by id: `idPatches`, `idInversePatches` and `idRedoPatches` next to `patches`,
+   * `inversePatches` and `redoPatches`, so a host can sync, comment or merge by `/slides/@intro/blocks/@kpi/text`
+   * instead of by indexes that move. Default false (the events are unchanged); it costs one extra walk of each patch.
+   */
+  idPaths?: boolean;
 }
 
 export interface CatalogOption {

package/dist/index.js

@@ -1,6 +1,7 @@
 import { commitCatalogControl } from "./catalog-control.js";
 import { paginateSlide } from "@openpresentation/opf/pagination";
 import { OPFPatchError, applyPatch as applyCorePatch, applyPatchWithInverse, formatPointer, invertPatch, jsonEqual, parsePointer, readPointer } from "@openpresentation/opf/patch";
+import { OPFIdError, assignIds, documentHash, toIdPatch } from "@openpresentation/opf/ids";
 import { collectReservedPresentationIds } from "./presentation-ids.js";
 import { composeSlide } from "@openpresentation/opf/composition";
 import { catalogKinds, resolveSlideContext, stats } from "@openpresentation/opf";
@@ -157,6 +158,18 @@ export function createEditorSession(input, options = {}) {
   const redoStack = [];
   const listeners = new Set();
   const rejectInvalid = Boolean(options.rejectInvalid);
+  // CE-04: with `idPaths`, every event and change also carries the same patches addressed by id (`/slides/@intro/title`), which stay
+  // true when slides and blocks move, for hosts that sync or comment by id. Each is written against the document it applies to.
+  // It costs one walk of each patch over a copy of the document, so it is off by default.
+  const idPaths = Boolean(options.idPaths);
+  const idForms = (fields) => {
+    if (!idPaths) return {};
+    const out = {};
+    if (fields.patches) out.idPatches = toIdPatch(fields.patches[0], fields.patches[1]);
+    if (fields.inversePatches) out.idInversePatches = toIdPatch(fields.inversePatches[0], fields.inversePatches[1]);
+    if (fields.redoPatches) out.idRedoPatches = toIdPatch(fields.redoPatches[0], fields.redoPatches[1]);
+    return out;
+  };
   let snapshotCache;
 
   function emit(event) {
@@ -178,7 +191,8 @@ export function createEditorSession(input, options = {}) {
     const before = presentation;
     let next, inversePatches;
     try {
-      ({ presentation: next, inverse: inversePatches } = applyPatchWithInverse(before, patches));
+      // `expectHash` (CE-04) is the precondition of this edit: the session's document must still be the one the caller hashed.
+      ({ presentation: next, inverse: inversePatches } = applyPatchWithInverse(before, patches, applyOptions?.expectHash === undefined ? {} : { expectHash: applyOptions.expectHash }));
     } catch (error) {
       throw editorPatchError(error);
     }
@@ -215,10 +229,12 @@ export function createEditorSession(input, options = {}) {
     validation = nextValidation;
     undoStack.push({ patches: clonePatchOperations(patches), inversePatches, meta });
     redoStack.length = 0;
+    const ids = idForms({ patches: [before, patches], inversePatches: [next, inversePatches] });
     emit({
       type: "patch",
       patches: clonePatchOperations(patches),
       inversePatches: clonePatchOperations(inversePatches),
+      ...ids,
       validation,
       meta
     });
@@ -227,6 +243,7 @@ export function createEditorSession(input, options = {}) {
       presentation: clone(presentation),
       patches: clonePatchOperations(patches),
       inversePatches: clonePatchOperations(inversePatches),
+      ...ids,
       validation,
       ...(forks.length ? { forked: forks, notice: meta.notice } : {})
     };
@@ -250,7 +267,7 @@ export function createEditorSession(input, options = {}) {
     setCatalogs(next, meta = {}) {
       catalogs = mergeCatalogs(next);
       validation = check(presentation);
-      emit({ type: "catalogs", patches: [], validation, meta });
+      emit({ type: "catalogs", patches: [], ...(idPaths ? { idPatches: [] } : {}), validation, meta });
       return catalogs;
     },
     get canUndo() {
@@ -322,6 +339,27 @@ export function createEditorSession(input, options = {}) {
       return setCatalogId(editor, path, catalogKind, id, meta);
     },
     applyPatch: commitPatch,
+    /**
+     * The content hash of the open document (core's `documentHash`): pass it as `applyPatch(ops, meta, { expectHash })` to apply an edit
+     * only while the document is still the one the hash was taken from. Reads the session's document without copying it.
+     */
+    documentHash() {
+      return documentHash(presentation);
+    },
+    /**
+     * Give every slide and block without an `id` one (core's `assignIds`) as ONE undoable edit, and return the change, or `null` when
+     * every slide and block already has an id. `options` are core's (`generate`); `meta.source` defaults to `"assign-ids"`.
+     */
+    assignIds(assignOptions = {}, meta = {}) {
+      let result;
+      try {
+        result = assignIds(presentation, assignOptions);
+      } catch (error) {
+        throw error instanceof OPFIdError ? new OPFEditorError(error.code, error.message, { path: error.path }) : error;
+      }
+      if (!result.patch.length) return null;
+      return commitPatch(result.patch, { ...meta, source: meta.source ?? "assign-ids" });
+    },
     /**
      * Open a different document in the session (a host's example menu, File > Open, "start over"): the whole document is replaced as ONE
      * undoable change (Undo restores the previous document, Redo the new one). Unlike an `applyPatch` that replaces the root, this is
@@ -386,19 +424,22 @@ export function createEditorSession(input, options = {}) {
       redoStack.length = 0;
       undoStack.push(...undo.map(entry));
       redoStack.push(...redo.map(entry));
-      emit({ type: "restore", patches: [], validation, meta });
+      emit({ type: "restore", patches: [], ...(idPaths ? { idPatches: [] } : {}), validation, meta });
       return { presentation: clone(presentation), patches: [], validation };
     },
     undo(meta = {}) {
       const entry = undoStack.pop();
       if (!entry) return null;
+      const before = presentation;
       presentation = applyJsonPatch(presentation, entry.inversePatches);
       validation = check(presentation);
       redoStack.push(entry);
+      const ids = idForms({ patches: [before, entry.inversePatches], redoPatches: [presentation, entry.patches] });
       emit({
         type: "undo",
         patches: clonePatchOperations(entry.inversePatches),
         redoPatches: clonePatchOperations(entry.patches),
+        ...ids,
         validation,
         meta
       });
@@ -406,19 +447,23 @@ export function createEditorSession(input, options = {}) {
         presentation: clone(presentation),
         patches: clonePatchOperations(entry.inversePatches),
         redoPatches: clonePatchOperations(entry.patches),
+        ...ids,
         validation
       };
     },
     redo(meta = {}) {
       const entry = redoStack.pop();
       if (!entry) return null;
+      const before = presentation;
       presentation = applyJsonPatch(presentation, entry.patches);
       validation = check(presentation);
       undoStack.push(entry);
+      const ids = idForms({ patches: [before, entry.patches], inversePatches: [presentation, entry.inversePatches] });
       emit({
         type: "redo",
         patches: clonePatchOperations(entry.patches),
         inversePatches: clonePatchOperations(entry.inversePatches),
+        ...ids,
         validation,
         meta
       });
@@ -426,6 +471,7 @@ export function createEditorSession(input, options = {}) {
         presentation: clone(presentation),
         patches: clonePatchOperations(entry.patches),
         inversePatches: clonePatchOperations(entry.inversePatches),
+        ...ids,
         validation
       };
     }
@@ -725,6 +771,7 @@ function editorPatchError(error) {
   if (error.operation !== undefined) details.operation = error.operation;
   if (error.index !== undefined) details.index = error.index;
   if (error.validation) details.issues = errorFindings(error.validation);
+  if (error.code === "patch-hash-mismatch") Object.assign(details, { expected: error.expected, actual: error.actual });
   return new OPFEditorError(error.code, error.message, details);
 }
 

package/dist/presenter.js

@@ -19,25 +19,40 @@ const CLICK_GUARD_MS = 450;
 const NEXT_KEYS = new Set(["ArrowRight", " ", "PageDown", "Enter"]);
 const PREVIOUS_KEYS = new Set(["ArrowLeft", "PageUp", "Backspace"]);
 
-// Full screen belongs to the document, not to one presenter: the browser ends whatever is full screen when an exit it was asked for runs, and tells
-// every listener. A presenter that closed early asks for its exit late (when its pending full screen request resolves), possibly after a newer
-// presenter took full screen. So the exits the presenters asked for are counted per document, and any presenter reads a `fullscreenchange` that
-// answers one of them as ours, not as the user leaving full screen.
-const exitRequests = new WeakMap(); // Document -> Set of exits asked for and not yet reported
+// Full screen belongs to the document, not to one presenter, and the browser answers a request later than it was made. Two things follow, and
+// both are kept per document so that presenters (any number can be mounted) see the same facts.
+// 1. An exit a presenter asked for can run after a newer presenter took full screen, and the browser then ends that one's full screen too.
+//    A presenter whose request resolved after it was closed therefore leaves full screen only when no newer request is in flight (that request
+//    replaces it); otherwise it marks its element abandoned, and the newer presenter gives the screen back if its own request does not get it.
+// 2. The `fullscreenchange` an exit answers must not read as the user leaving. The exits presenters asked for are listed until their event is
+//    seen and the exit has settled, in whichever order those two happen. An event that finds the screen taken by an element drops the exits that
+//    already settled, since events arrive in the order of the changes: a later exit event is the user's, however soon it follows.
+const documentStates = new WeakMap(); // Document -> { requests (counted), inFlight (their numbers, until answered), exits, abandoned (elements) }
 const attributedEvents = new WeakMap(); // fullscreenchange Event -> whether it answered an exit a presenter asked for
-function noteExit(doc, win) {
-  let requests = exitRequests.get(doc);
-  if (!requests) exitRequests.set(doc, requests = new Set());
-  const request = {};
-  requests.add(request);
-  // The browser reports an exit with the event; when it does not (the exit was refused, or two exits became one event), stop counting it soon.
-  return { forget: () => requests.delete(request), forgetSoon: () => win.setTimeout(() => requests.delete(request), 500) };
+function stateOf(doc) {
+  let state = documentStates.get(doc);
+  if (!state) documentStates.set(doc, state = { requests: 0, inFlight: new Set(), exits: new Set(), abandoned: new WeakSet() });
+  return state;
+}
+function noteExit(doc) {
+  const { exits } = stateOf(doc);
+  const exit = { settled: false, seen: false };
+  exits.add(exit);
+  return {
+    // The browser reports an exit with an event; when none came (the exit was refused, or two exits became one event) it is not waited for.
+    settle: (done) => { if (!done || exit.seen) exits.delete(exit); else exit.settled = true; },
+  };
 }
 function answersAnExit(doc, event) {
   if (attributedEvents.has(event)) return attributedEvents.get(event);
-  const requests = exitRequests.get(doc);
-  const ours = Boolean(requests?.size) && !doc.fullscreenElement;
-  if (ours) requests.delete(requests.values().next().value);
+  const { exits } = stateOf(doc);
+  let ours = false;
+  if (doc.fullscreenElement) {
+    for (const exit of exits) if (exit.settled) exits.delete(exit);
+  } else {
+    const exit = [...exits].find((candidate) => !candidate.seen);
+    if (exit) { ours = true; if (exit.settled) exits.delete(exit); else exit.seen = true; }
+  }
   attributedEvents.set(event, ours);
   return ours;
 }
@@ -92,7 +107,7 @@ export function createPresenter(container, options = {}) {
   // Drawn slides by deck index, for the deck object they were drawn from: a new snapshot (an edit) or a new start() draws again.
   let drawn = new Map(), drawnFor;
 
-  let active = false, destroyed = false, current = -1, opener = null, enteredFullscreen = false, returnTo = null;
+  let active = false, destroyed = false, current = -1, opener = null, enteredFullscreen = false, returnTo = null, pendingRequests = 0;
   let counterTimer, preloadTimer, renderToken = 0, swipe = null, clickGuardUntil = 0;
 
   // ---- the DOM ----------------------------------------------------------------------------------------------------------------------------
@@ -216,36 +231,57 @@ export function createPresenter(container, options = {}) {
   function enterFullscreen() {
     const request = root.requestFullscreen ?? root.webkitRequestFullscreen;
     if (typeof request !== "function" || doc.fullscreenEnabled === false) return Promise.resolve("overlay");
+    const state = stateOf(doc);
+    const ticket = ++state.requests;
+    state.inFlight.add(ticket);
+    pendingRequests++;
+    state.abandoned.delete(root);
+    const answered = () => { state.inFlight.delete(ticket); pendingRequests--; };
     let attempt;
     try { attempt = Promise.resolve(request.call(root, { navigationUI: "hide" })); } catch (error) { attempt = Promise.reject(error); }
     return attempt.then(
       () => {
-        if (doc.fullscreenElement !== root) return "overlay";
-        // stop() ran while the request was pending (a quick Esc or close), so it saw no full screen to leave: give the screen back now, or the
-        // page stays full screen behind a hidden presenter.
-        if (!active) { leaveFullscreen(); return "overlay"; }
+        answered();
+        if (doc.fullscreenElement !== root) return reclaimAbandoned();
+        if (!active) {
+          // stop() ran while the request was pending (a quick Esc or close), so it saw no full screen to leave: give the screen back now, or the
+          // page stays full screen behind a hidden presenter. Not when a newer request is still in flight: it replaces this element, and an exit asked
+          // for now would run after it and end the newer presenter's full screen.
+          if ([...state.inFlight].some((newer) => newer > ticket)) state.abandoned.add(root); else leaveFullscreen();
+          return "overlay";
+        }
         enteredFullscreen = true;
         root.dataset.mode = "fullscreen";
         return "fullscreen";
       },
-      () => "overlay",
+      () => { answered(); return reclaimAbandoned(); },
     );
   }
+  // This presenter did not get the screen (refused, or taken by another element): if an earlier, closed presenter's element still holds it
+  // because that presenter left the exit to this request, give it back.
+  function reclaimAbandoned() {
+    const holder = doc.fullscreenElement, { abandoned } = stateOf(doc);
+    if (holder && holder !== root && abandoned.has(holder)) { abandoned.delete(holder); leaveFullscreen(); } else if (!active) restoreFocus();
+    return "overlay";
+  }
   // Ask the browser to leave full screen; onFullscreenChange then sees that the event answers an exit asked for (by this presenter or an earlier
-  // one) and does not read it as the user's. Focus goes back to the element that opened the presentation once the exit is done, because the page
-  // behind a full screen element takes no focus until then.
+  // one) and does not read it as the user's. Focus goes back to the element that opened the presentation once the exit is done (or refused: the
+  // screen was already gone), because the page behind a full screen element takes no focus until then.
   function leaveFullscreen() {
-    const exit = noteExit(doc, win);
-    Promise.resolve(doc.exitFullscreen?.()).then(() => { exit.forgetSoon(); restoreFocus(); }, exit.forget);
+    const exit = noteExit(doc);
+    Promise.resolve(doc.exitFullscreen?.()).then(() => { exit.settle(true); restoreFocus(); }, () => { exit.settle(false); restoreFocus(); });
   }
-  // Only when nobody took focus since: the host may move it in `onExit`.
+  // Only when nobody took focus since: the host may move it in `onExit`. While the screen is still full screen the page behind takes no focus, and
+  // a browser reports the end of an exit's promise before the end of full screen; so the element is kept until the `fullscreenchange` that ends it (and while a request of this presenter is unanswered: it may still take the screen).
   function restoreFocus() {
     const now = doc.activeElement;
     if (returnTo?.isConnected && typeof returnTo.focus === "function" && (!now || now === doc.body || now === root)) returnTo.focus({ preventScroll: true });
+    if (!doc.fullscreenElement && !pendingRequests) returnTo = null;
   }
   // The browser takes full screen away with Esc (that key never reaches the page) or the host exits it: the presentation ends with it.
   function onFullscreenChange(event) {
     if (doc.fullscreenElement === root) return;
+    if (!active && !doc.fullscreenElement) restoreFocus();
     if (answersAnExit(doc, event)) {
       // An exit that a presenter asked for finished: ours from stop(), or an earlier presenter's that ran after this one took full screen. A
       // presentation still running carries on as the overlay.
@@ -321,6 +357,7 @@ export function createPresenter(container, options = {}) {
     const wanted = slideIndex ?? options.slideIndex ?? 0;
     if (active) { show(wanted); return Promise.resolve(root.dataset.mode); }
     active = true;
+    returnTo = null;
     opener = doc.activeElement && doc.activeElement !== doc.body ? doc.activeElement : null;
     current = -1;
     drawn = new Map();