@openpresentation/opf-editor 0.26.10 → 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/react.d.ts

@@ -30,3 +30,37 @@ export declare function createOPFReactComponents(React: {
   OPFTextInput(props: OPFTextInputProps): unknown;
   OPFCatalogSelect(props: OPFCatalogSelectProps): unknown;
 };
+
+// ---- CE-06: the embeddable editor ---------------------------------------------------------------------------------------------------------
+import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, RefAttributes } from "react";
+import type { OpfEditor as OpfEditorHandle, OpfEditorOptions, OpfEditorSlots } from "./workspace.js";
+
+/** A slot is an element, or a React ref to one (resolved when the editor mounts). */
+export type OpfEditorReactSlots = { [Name in keyof OpfEditorSlots]?: OpfEditorSlots[Name] | { current: OpfEditorSlots[Name] | null } };
+
+export interface OpfEditorProps extends Omit<OpfEditorOptions, "slots"> {
+  slots?: OpfEditorReactSlots;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  /** Called with the editor right after it is created, and with `null` when it is destroyed. For the hooks below. */
+  onEditor?: (editor: OpfEditorHandle | null) => void;
+}
+
+/**
+ * The editor in a `<div>`. Every other prop is an option of `createOpfEditor`, read once when it mounts (give the component another `key` to mount a
+ * new one); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders, and the callbacks are always the latest. `ref` is the
+ * editor handle once mounted. Correct under StrictMode; renders an empty container on the server.
+ */
+export declare const OpfEditor: ForwardRefExoticComponent<OpfEditorProps & RefAttributes<OpfEditorHandle | null>>;
+
+/** The editor as a hook: `const { ref, editor } = useOpfEditor(options)`, then `<div ref={ref} />`. `editor` is `null` on the server and until mounted. */
+export declare function useOpfEditor(options?: OpfEditorProps): { ref: MutableRefObject<HTMLDivElement | null>; editor: OpfEditorHandle | null };
+
+/** The document of an editor, replaced on every change; `undefined` while `editor` is `null`. Frozen: do not modify it. */
+export declare function useOpfDocument(editor: OpfEditorHandle | null | undefined): unknown;
+
+/** The content last selected on the canvas, or `null`. */
+export declare function useOpfSelection(editor: OpfEditorHandle | null | undefined): { path: string; value: unknown } | null;
+
+export type { OpfEditorHandle };