@openpresentation/opf-editor 0.26.10 → 0.28.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), useOpfCursor(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:
@@ -110,7 +142,7 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
+Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `getCursor()` and the `onCursor` option (the path under the caret), `revealPath(pointer | range, { focus?, select?, align?, flash?, part? })` (scrolls without moving the caret or the focus), `setDecorations(list, { group? })`, `clearDecorations(group?)` and `getDecorations(group?)` (a host's own marks, by path or range; see "The source pane's hooks" in [docs/embedding.md](docs/embedding.md)), `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
 
 - **Opening a document: `pane.replaceDocument(document, { source, format, name })`.** Loading an example or a file into the pane (never by writing its text into the code editor, which the pane applies as a typed edit and forks the catalog records the two documents share) calls `editor.replaceDocument`: one undoable change, no catalog record forked. `document` is a parsed document or JSON text; `name` is the file name. `source` is the text the document was read from, in any of the three formats: the pane shows it as written (the JSON's formatting, the YAML's comments, the Markdown's layout) when the pane is in that format, and core's rewrite of the document otherwise. `format` (`"json"`, `"yaml"` or `"md"`) says which format `source` is; left out, it is inferred as the first of JSON, the pane's format, YAML and Markdown that reads as exactly this document (a `source` that reads as no format, or as another document, is ignored; an unknown `format` throws a `TypeError` before anything changes). The original text of a format other than the one shown is kept too: switching the pane to it shows those bytes, not a rewrite. Undo and Redo bring back each document's text exactly in the format shown (the opened text as written, the replaced document's text as it was, including YAML comments), so one Undo returns to the document and the text the visitor had. The pane keeps the last 8 such texts, which are also what a later load of the same document shows. A refused document throws (`invalid-opf-edit`, with `issues`) and changes nothing, and works in a read-only pane. A diff typed or pasted into the pane is still an edit, and editing a catalog record in it forks the record.
 - **Keyboard Undo and Redo in the pane (one model).** Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) work in two layers, in this order. First CodeMirror's history, which holds only the text typed in the pane since its last whole-document change (a `replaceDocument`, or a session Undo, Redo or restore, each of which clears it because the typed edits no longer fit the text). When that has nothing left, the key steps the session over a whole-document replace, exactly as its Undo and Redo do, so the text comes back byte for byte: Undo steps back over the nearest `replaceDocument` together with the pane's own edits typed on it (the typing was already undone, step by step, by CodeMirror's history); Redo steps forward over the replace. The key never reaches over an edit made elsewhere (the canvas, a panel): Undo stops at it, and the host's Undo button (or `editor.undo()`) undoes that edit, after which the key reaches the load again. A read-only pane takes neither key. `mountJsonCodeEditor` exposes the same seam as `historyFallback: { undo(), redo() }` (answer `true` when you did something) plus `resetHistory()` and `undoDepth()` on the control.
@@ -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:
@@ -486,7 +537,7 @@ insertZoneLogo(editor, "header", "left");                                  // th
 | `titleAlignment`, `contentAlignment` | `design.titleAlignment`, `design.contentAlignment` | `left`, `center`, `right` |
 | `contentDirection` | `design.contentDirection` | `horizontal`, `vertical` |
 | `chartPrimary` | `design.chartPrimary` | `none`, `top`, `bottom`, `left`, `right` |
-| `listBullet` | `design.listBullet` | `character`, `image` (picture bullets draw the logo) |
+| `listBullet` | `design.listBullet` | `character`, `image` (picture bullets draw the logo), `none` (no marker and no indent) |
 | `contentBox` | `design.contentBox` | `true`, `false` |
 | `imageFit` | `design.imageFit` | `cover`, `contain`, `stretch`: the fit of image blocks that choose none |
 | `accentFont` | `design.fontScheme.accent` | a family name; the font scheme becomes its object form and collapses back to the bare id when the accent is cleared |
@@ -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`, `useOpfSelection` and `useOpfCursor` 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/design-controls.js

@@ -1018,12 +1018,13 @@ export function createDesignControls(container, options = {}) {
     };
     const bullet = selectField("list-bullet", "List bullets", {
       empty: "Default (character)",
-      help: "Picture bullets draw the logo as the marker and need a logo.",
-      onChange: (value) => run(() => setDesignOption(editor, "listBullet", value === "" ? null : value, scoped()), value === "image" ? "Picture bullets on." : "Character bullets."),
+      help: "Picture bullets draw the logo as the marker and need a logo. No bullets draws no marker and no indent, for label-and-description lists.",
+      onChange: (value) => run(() => setDesignOption(editor, "listBullet", value === "" ? null : value, scoped()), value === "image" ? "Picture bullets on." : value === "none" ? "No bullets." : "Character bullets."),
     });
     bullet.setOptions([
       { value: "character", label: "Character" },
       { value: "image", label: "Picture (the logo)" },
+      { value: "none", label: "None (no bullets)" },
     ]);
     const accent = textField("accent-font", "Accent font", {
       placeholder: "Font family name",

package/dist/design-options.js

@@ -62,7 +62,7 @@ const ENUMS = Object.freeze({
   contentAlignment: ["left", "center", "right"],
   contentDirection: ["horizontal", "vertical"],
   chartPrimary: ["none", "top", "bottom", "left", "right"],
-  listBullet: ["character", "image"],
+  listBullet: ["character", "image", "none"],
   imageFit: ["cover", "contain", "stretch"],
 });
 

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/json-editor.d.ts

@@ -29,6 +29,18 @@ export interface EditorProblem {
   fixes?: EditorFix[];
 }
 
+/** One host decoration of the code editor (CE-17): a mark over `from..to`, or the class on every line it touches. Offsets are source offsets. */
+export interface EditorDecoration {
+  from: number;
+  to?: number;
+  className: string;
+  /** The browser tooltip of a mark. */
+  title?: string;
+  line?: boolean;
+  /** Kept as given, for `getDecorations`. */
+  data?: unknown;
+}
+
 /** All offsets address the original source in UTF-16, including CRLF pairs. */
 export interface JsonEditorApi {
   /** Say `message` in the editor's live region (screen readers). */
@@ -37,6 +49,8 @@ export interface JsonEditorApi {
   applyEdits(edits: SourceEdit[], options?: { caret?: number; select?: [number, number]; userEvent?: string }): void;
   getValue(): string;
   getSelection(): [number, number];
+  /** The end of the main selection the caret is at (equal to both ends of `getSelection()` for a plain caret), in source offsets. */
+  getHead(): number;
   hasFocus(): boolean;
   focus(): void;
   setSelection(from: number, to?: number): void;
@@ -115,6 +129,10 @@ export interface JsonCodeEditorOptions {
   /** Cmd/Ctrl+Shift+M: move focus to the host's problems list. Answer true when it did. */
   onFocusProblems?(): boolean;
   onFocus?(): void;
+  /** The selection or the text changed (every change, also one the host made). */
+  onSelectionChange?(): void;
+  /** The text changed (also by `update`). */
+  onDocChange?(): void;
   onHoverField?(path: string | null): void;
   onError?(error: unknown): void;
 }
@@ -153,6 +171,21 @@ export interface JsonCodeEditor {
   resetHistory(): void;
   /** How many typed edit groups CodeMirror can still undo. */
   undoDepth(): number;
+  /**
+   * CE-17: scroll the start of `from..to` (source offsets) into view without moving the selection or the focus. `align` is "center" (default),
+   * "start" or "nearest" (the least scrolling). `select` also selects the range and `focus` also focuses the editor. Folded text around the start is opened.
+   */
+  reveal(from: number, to?: number, options?: { align?: "center" | "start" | "nearest"; select?: boolean; focus?: boolean }): void;
+  /**
+   * CE-17: draw decorations a host owns, kept apart from the editor's own. `key` names a set and a call replaces that set; an empty list
+   * removes it. Each item is a mark over `from..to` (source offsets), or with `line` the class on every line it touches. The decorations
+   * move with the text as it is edited.
+   */
+  setDecorations(key: string, list: readonly EditorDecoration[]): void;
+  /** CE-17: remove the decoration set `key`, or every set when `key` is omitted. */
+  clearDecorations(key?: string): void;
+  /** CE-17: the decorations drawn now, at their current source offsets, in position order. A `line` decoration is one entry over all its lines. */
+  getDecorations(key?: string): (EditorDecoration & { key: string; to: number })[];
   /** The CodeMirror `EditorView`. */
   readonly view: import("@codemirror/view").EditorView;
   openOptions(left?: number, top?: number): Promise<void>;