@openpresentation/opf-editor 0.28.0 → 0.29.0

package/dist/exact-source.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@openpresentation/opf-editor/exact-source`: the writer the editor uses to put a changed document back into the JSON text it was read from,
+ * keeping the author's bytes. Only the tokens of values that changed are rewritten; indentation, key order, escapes (`"\/"`, `"é"`), line
+ * endings and every unrelated value stay byte for byte. A memory of the texts it has seen brings an authored spelling back when a value returns
+ * (Escape, Undo, Redo) instead of re-serializing it.
+ */
+
+/** Texts longer than this many characters are not remembered (edits still work; a returning value is then written normally). */
+export declare const MAX_EXACT_SOURCE_LENGTH: number;
+
+/** The memory of exact source texts, keyed by the parsed value. Give each document (each editor, each file) its own. */
+export interface SourceMemory {
+  /** True when the last source given was too long to remember (see `MAX_EXACT_SOURCE_LENGTH`): tell the author a returning value may be respelled. */
+  limited: boolean;
+  readonly limit: number;
+  readonly maxBytes: number;
+}
+
+/** A new memory: at most `limit` texts (default 64) and `maxBytes` characters in total (default 8,000,000), the oldest evicted first. */
+export declare function createSourceMemory(limit?: number, maxBytes?: number): SourceMemory;
+
+/**
+ * Write `document` into `source` (JSON text) and return the new text. Only the affected values change; everything else is kept byte for byte.
+ * Throws when `source` is not valid JSON. The result always parses to `document`: when an edit in place cannot achieve that (the source
+ * repeats a key, say), the whole document is written as JSON indented like `source`. Without `memory` a memory shared by the module is used.
+ */
+export declare function updateJsonSource(source: string, document: unknown, memory?: SourceMemory): string;
+
+/** The first object key that JSON text repeats (which `JSON.parse` silently collapses to the last), as `{ key, path }`; null when there is none. */
+export declare function findDuplicateKey(source: string): { key: string; path: (string | number)[] } | null;

package/dist/font-gate.js

@@ -30,8 +30,27 @@ const GATE = Symbol("opf-editor.fontGate");
 export function fontGate(fonts) {
   if (!fonts || typeof fonts !== "object") return undefined;
   if (fonts[GATE]) return fonts;
+  // CE-20: "nothing is pending" for one document object and the same options stays true (faces are never unloaded), so it is remembered:
+  // the canvas, the workspace and the thumbnails ask about the same frozen snapshot several times per edit, and on a long deck each
+  // answer composes every slide.
+  const settled = new WeakMap();
+  const sameOptions = (a = {}, b = {}) => {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+      const x = a[key], y = b[key];
+      if (x === y) continue;
+      if (Array.isArray(x) && Array.isArray(y) && x.length === y.length && x.every((entry, at) => entry === y[at])) continue;
+      return false;
+    }
+    return true;
+  };
   const pending = (presentation, renderOptions) => {
-    try { return fonts.pending?.(presentation, renderOptions) ?? []; } catch { return []; /* the renderer reports the document itself when it renders */ }
+    const known = presentation && typeof presentation === "object" ? settled.get(presentation) : undefined;
+    if (known?.some((options) => sameOptions(options, renderOptions))) return [];
+    let found;
+    try { found = fonts.pending?.(presentation, renderOptions) ?? []; } catch { return []; /* the renderer reports the document itself when it renders */ }
+    if (!found.length && presentation && typeof presentation === "object" && Object.isFrozen(presentation)) settled.set(presentation, [...(known ?? []), renderOptions ?? {}].slice(-4));
+    return found;
   };
   const gate = {
     [GATE]: true,

package/dist/json-editor.js

@@ -13,6 +13,7 @@ import {textInputMap} from './text-input.js';
 import {detectIndent,formatJsonSource,whitespaceEdits} from './json-format.js';
 import { redoPair, undoPair } from "./source-undo-groups.js";
 import {a11yExtension,createAnnouncer} from './source-a11y.js';
+import { checkCodeMirrorCopies } from './codemirror-guard.js';
 import { forEachDiagnostic } from "@codemirror/lint";
 import {createDiagnostics,editsTransaction} from './source-diagnostics.js';
 import { createKeymap, domKeymap, strokeText } from './source-keymap.js';
@@ -530,6 +531,8 @@ function mountJsonCodeEditor(parent, options) {
   const shortcutAttribute = (ids) => ids.flatMap((id) => km.shortcuts().find((row) => row.id === id)?.strokes.slice(0, 1) ?? []).map((stroke) => strokeText(stroke, km.platform).replace(/Cmd/g, "Meta").replace(/Ctrl/g, "Control")).join(" ");
   const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
     "aria-label": options.label,
+    // CE-20: the scroller around the text is a scrolling region; its text is focusable (axe scrollable-region-focusable).
+    tabindex: "0",
     "aria-invalid": String(Boolean(invalid)),
     "aria-describedby": describedBy ?? "",
     "aria-keyshortcuts": shortcutAttribute(["suggest.trigger", "problem.next", "problem.previous", "problem.quickFix", "format.document", "nav.symbol"]),
@@ -538,7 +541,7 @@ function mountJsonCodeEditor(parent, options) {
     autocapitalize: "off",
     autocorrect: "off"
   });
-  const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: [
+  const mountExtensions = [
     // The problem menu's keys come before the list's: the two are never open together, and Enter must reach whichever is.
     diagnostics.extension,
     language.of(languageExtension(languageName, completionExtension)),
@@ -618,7 +621,10 @@ function mountJsonCodeEditor(parent, options) {
       if (update.docChanged) options.onDocChange?.();
       if (update.docChanged && update.transactions.some((tr) => tr.isUserEvent("input.type"))) autoHint(update.view);
     })
-  ] }) });
+  ];
+  // Two copies of @codemirror/view break the tooltips, completions, problems and find without an error: say so once (codemirror-guard.js).
+  checkCodeMirrorCopies(mountExtensions, options.onError);
+  const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: mountExtensions }) });
   const api = {
     getValue: () => view.state.field(jsonSource),
     getSelection: () => {const map=textInputMap(api.getValue());return [map.toSource(view.state.selection.main.from),map.toSource(view.state.selection.main.to)];},

package/dist/json-options.d.ts

@@ -9,7 +9,8 @@ export interface JsonFieldOption {
   /** User-facing provenance; source remains stable for existing consumers. */
   sourceLabel?: string;
   sourceDescription?: string;
-  layoutGroup?: 'Current layout' | 'Openers and closers' | 'Text' | 'Groups of items' | 'Numbers' | 'Visuals' | 'Mixed' | 'Custom layouts';
+  /** `Current layout`, the layout record's catalog group (for the Gallery: Openers and closers, Text, Groups of items, Numbers, Visuals or Mixed), or `Custom layouts`. */
+  layoutGroup?: string;
   /** Region names, accepted kinds and flow from the v2 template. */
   regions?: string;
 }

package/dist/json-options.js

@@ -2,7 +2,7 @@ import { checkFormat, firstErrorMessage } from "./checks.js";
 import { listCatalogRecords } from "./catalogs.js";
 import { resolveSchema, schemaAtPath, schemaVariants } from "./schema.js";
 import { findNodeAtOffset, getNodePath, parse as parseJsonc, parseTree } from "jsonc-parser";
-import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
+import { CUSTOM_LAYOUTS_GROUP, layoutGroupName, layoutGroupOrder, layoutRegionSummary } from "./layout-templates.js";
 import { catalogKindAt } from "@openpresentation/opf/schema";
 const sourceDetails = {
     "Loaded catalog": ["Provided by app", "Records from a catalog this app registered; nothing is fetched from a URL. Saving embeds the record in the document."],
@@ -10,16 +10,17 @@ const sourceDetails = {
     "Current value": ["Custom value", "The current value is not in the available catalogs."],
     "Schema": ["OPF option", "Allowed by the OPF schema."],
 };
-const layoutGroups = ["Current layout", ...LAYOUT_INTENT_GROUPS.map(group => group.name), "Custom layouts"];
 function describeOptions(choices, records, current, catalog) {
+    // A layout's group is its catalog record's (see layoutGroupName); the groups follow the catalog's own order.
+    const layoutGroups = catalog === "layouts" ? ["Current layout", ...layoutGroupOrder([...records.values()]), CUSTOM_LAYOUTS_GROUP] : [];
     for (const option of choices) {
         const [label, description] = sourceDetails[option.source];
         option.sourceLabel = label;
         option.sourceDescription = description;
         if (catalog !== "layouts") continue;
-        const id = String(option.value).replace(/^default:/, "");
-        option.regions = layoutRegionSummary(records.get(String(option.value)));
-        option.layoutGroup = option.value === current ? "Current layout" : LAYOUT_INTENT_GROUPS.find(group => group.ids.includes(id))?.name ?? "Custom layouts";
+        const entry = records.get(String(option.value));
+        option.regions = layoutRegionSummary(entry?.record);
+        option.layoutGroup = option.value === current ? "Current layout" : entry ? layoutGroupName(entry) : CUSTOM_LAYOUTS_GROUP;
     }
     const priority = option => option.source === "Document catalog" ? 2 : option.source === "Loaded catalog" ? 1 : 0;
     return choices.sort((a, b) => (catalog === "layouts" ? layoutGroups.indexOf(a.layoutGroup) - layoutGroups.indexOf(b.layoutGroup) : priority(b) - priority(a)) || a.label.localeCompare(b.label, "en", {numeric: true}) || String(a.value).localeCompare(String(b.value), "en"));
@@ -42,7 +43,7 @@ function fieldOptions(presentation, path, loadedCatalogs, { string, boolean }) {
         const attempt = (document) => { try { return listCatalogRecords(document, catalog, { catalogs: hostCatalogs }); } catch { return undefined; } };
         const available = attempt(presentation) ?? attempt({ ...presentation, catalogs: undefined }) ?? [];
         for (const option of available) {
-            records.set(option.id, option.record);
+            records.set(option.id, option);
             options.set(option.id, { value: option.id, label: option.label, description: option.description,
                 source: option.origin === "document" ? "Document catalog" : "Loaded catalog" });
         }

package/dist/layout-templates.d.ts

@@ -1,8 +1,13 @@
 import type { EditorSession, EditorChange, JsonPatchOperation } from "./index.js";
 
-export interface LayoutChoice { id: string; label: string; record?: Record<string, unknown> }
-export interface LayoutIntentGroup { name: string; ids: readonly string[] }
-export declare const LAYOUT_INTENT_GROUPS: readonly LayoutIntentGroup[];
+/** A layout a picker offers. `group` is the catalog group of a `listCatalogRecords` entry (`custom` is the deck's own layout); `origin` is `document` for a record the deck embeds. */
+export interface LayoutChoice { id: string; label: string; record?: Record<string, unknown>; group?: string; origin?: string }
+/** The group of layouts the catalogs do not group: a deck's or host's own layout, or a record with no tags. */
+export declare const CUSTOM_LAYOUTS_GROUP: "Custom layouts";
+/** The picker group of a layout: the first tag of its catalog record (the Gallery's index group), else `CUSTOM_LAYOUTS_GROUP`. */
+export declare function layoutGroupName(choice: LayoutChoice): string;
+/** The catalog's groups in picker order (the catalog's own layout order), without the custom group. */
+export declare function layoutGroupOrder(choices: readonly LayoutChoice[]): string[];
 export declare const LAYOUT_REGION_KINDS: readonly string[];
 export declare const LAYOUT_REGION_ROLES: readonly string[];
 export declare const LAYOUT_REGION_FLOWS: readonly string[];

package/dist/layout-templates.js

@@ -5,14 +5,32 @@ import { applyJsonPatch, createValuePatch, opfPathToJsonPointer } from "./index.
 import { checkedDocument, fail } from "./edit-helpers.js";
 import { checkFormat } from "./checks.js";
 
-export const LAYOUT_INTENT_GROUPS = Object.freeze([
-  { name: "Openers and closers", ids: ["cover", "section", "agenda", "statement", "closing"] },
-  { name: "Text", ids: ["text", "list", "quote", "two-column"] },
-  { name: "Groups of items", ids: ["pillars", "comparison", "process", "timeline", "faq"] },
-  { name: "Numbers", ids: ["metrics", "scorecard"] },
-  { name: "Visuals", ids: ["image", "image-beside", "gallery", "chart", "chart-beside", "table", "table-beside", "code"] },
-  { name: "Mixed", ids: ["hero", "dashboard", "team", "logos"] },
-]);
+/** The group of a layout the catalogs do not group: a deck's or host's own layout, or a catalog record with no group. */
+export const CUSTOM_LAYOUTS_GROUP = "Custom layouts";
+
+/**
+ * The picker group of one layout choice (`listCatalogRecords` entry, or a host's `{ id, label, record?, group? }`). A catalog
+ * record carries its group as its first tag (the Gallery publishes the same group in its layout index, and its tests keep the
+ * two equal), so a layout added to the catalog is grouped with no change here. A record with no tag, a choice with no record and a
+ * deck's own layout (catalog group `custom`) are `CUSTOM_LAYOUTS_GROUP`.
+ */
+export function layoutGroupName(choice) {
+  if (choice?.group === "custom") return CUSTOM_LAYOUTS_GROUP;
+  const tag = Array.isArray(choice?.record?.tags) ? choice.record.tags[0] : undefined;
+  return typeof tag === "string" && tag.trim() ? tag.trim() : CUSTOM_LAYOUTS_GROUP;
+}
+
+/**
+ * The catalog's groups in picker order, without the custom group: the order the catalog lists its layouts in (the Gallery lists
+ * them in its index order), so the groups follow the catalog. Records a deck embeds come after the registered catalogs' own.
+ */
+export function layoutGroupOrder(choices) {
+  const names = [];
+  const pass = (list) => { for (const choice of list) { const name = layoutGroupName(choice); if (name !== CUSTOM_LAYOUTS_GROUP && !names.includes(name)) names.push(name); } };
+  pass(choices.filter((choice) => choice.origin !== "document"));
+  pass(choices.filter((choice) => choice.origin === "document"));
+  return names;
+}
 
 export const LAYOUT_REGION_KINDS = Object.freeze(["text", "list", "image", "video", "chart", "table", "code", "metric", "quote", "timeline", "group"]);
 export const LAYOUT_REGION_ROLES = Object.freeze(["primary", "secondary", "media", "supporting"]);
@@ -20,15 +38,11 @@ export const LAYOUT_REGION_FLOWS = Object.freeze(["none", "grid", "column", "aut
 const RESERVED = new Set(["title", "subtitle", "tag", "auto", "left", "center", "right", "top", "middle", "bottom"]);
 const NAME = /^[a-z][a-z0-9-]*$/;
 
-/** Group registered layouts by the 28 built-in intents, then any deck or host layouts. */
+/** Group layouts by their catalog group (see `layoutGroupName`), in catalog order, then the custom ones. Choices keep their order within a group. */
 export function groupLayoutChoices(choices) {
-  const byId = new Map(choices.map((choice) => [choice.id, choice]));
-  const used = new Set();
-  const groups = LAYOUT_INTENT_GROUPS.map(({ name, ids }) => ({
-    name, choices: ids.map((id) => byId.get(id)).filter((choice) => { if (!choice || used.has(choice.id)) return false; used.add(choice.id); return true; }),
-  })).filter((group) => group.choices.length);
-  const custom = choices.filter((choice) => !used.has(choice.id));
-  if (custom.length) groups.push({ name: "Custom layouts", choices: custom });
+  const groups = layoutGroupOrder(choices).map((name) => ({ name, choices: choices.filter((choice) => layoutGroupName(choice) === name) }));
+  const custom = choices.filter((choice) => layoutGroupName(choice) === CUSTOM_LAYOUTS_GROUP);
+  if (custom.length) groups.push({ name: CUSTOM_LAYOUTS_GROUP, choices: custom });
   return groups;
 }
 

package/dist/numbering-panel.js

@@ -159,7 +159,7 @@ export function createNumberingPanel(container, options) {
     }
 
     if (enabled && state.entry) {
-      const start = h(doc, "input", { id: `${id}-entry-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: state.entry.start ?? "", placeholder: state.entry.marker ?? "" });
+      const start = h(doc, "input", { id: `${id}-entry-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: state.entry.start ?? "", placeholder: state.entry.marker ?? "", title: "Empty continues the count" });
       const apply = () => {
         const text = start.value.trim();
         try {
@@ -172,8 +172,7 @@ export function createNumberingPanel(container, options) {
       };
       start.addEventListener("change", apply);
       body.append(h(doc, "div", { class: "opf-numbering-entry" },
-        h(doc, "label", { for: start.id, text: `Entry ${state.entry.index + 1} starts at` }), start,
-        h(doc, "span", { class: "opf-numbering-help", text: "Leave empty to continue the count. Later entries carry on from it." })));
+        h(doc, "label", { for: start.id, text: `Entry ${state.entry.index + 1} starts at` }), start));
     }
   }
 

package/dist/react.d.ts

@@ -32,9 +32,9 @@ export declare function createOPFReactComponents(React: {
 };
 
 // ---- CE-06: the embeddable editor ---------------------------------------------------------------------------------------------------------
-import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, RefAttributes } from "react";
+import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, ReactNode, RefAttributes } from "react";
 import type { SourceCursor } from "./source-pane.js";
-import type { OpfEditor as OpfEditorHandle, OpfEditorOptions, OpfEditorSlots } from "./workspace.js";
+import type { OpfEditor as OpfEditorHandle, OpfEditorOptions, OpfEditorSlots, OpfCommandInfo, OpfStudioHostPanel, OpfStudioSelectionItem } 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 } };
@@ -46,6 +46,11 @@ export interface OpfEditorProps extends Omit<OpfEditorOptions, "slots"> {
   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;
+  /**
+   * CE-20, the Studio: the host's panels (`layout: "studio"`). Each `render()` is mounted by React through a portal into the panel the Studio
+   * makes for it (a tab of the right panel, or a section of the left panel with `side: "left"`), so it shares the host's context and state.
+   */
+  hostPanels?: (Omit<OpfStudioHostPanel, "mount"> & { render(): ReactNode })[];
 }
 
 /**
@@ -61,8 +66,11 @@ export declare function useOpfEditor(options?: OpfEditorProps): { ref: MutableRe
 /** 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;
+/** The content last selected on the canvas, or `null`; in the Studio, the selection list `[{ key, path, idPath, kind }]`. */
+export declare function useOpfSelection(editor: OpfEditorHandle | null | undefined): { path: string; value: unknown } | OpfStudioSelectionItem[] | null;
+
+/** CE-20: the Studio's commands for a host palette (pptx.dev's Cmd+K): the list with each command's state, and `run(id)`. */
+export declare function useOpfCommands(editor: OpfEditorHandle | null | undefined): { commands: OpfCommandInfo[]; run(id: string): boolean };
 
 /** The path under the caret of the source pane, the latest `cursor` event (`pointer`, `idPath`, `from`, `to`, ...), or `null` before the first. */
 export declare function useOpfCursor(editor: OpfEditorHandle | null | undefined): SourceCursor | null;

package/dist/react.js

@@ -1,4 +1,5 @@
-import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore } from "react";
+import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
 import { commitCatalogControl } from "./catalog-control.js";
 import {
   getCatalogOptions,
@@ -116,7 +117,7 @@ function resolveSlots(slots) {
 }
 
 // The props that are not editor options.
-const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onCursor", "onError", "onReady"]);
+const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onCursor", "onError", "onReady", "hostPanels"]);
 
 function splitProps(props) {
   const options = {};
@@ -130,7 +131,7 @@ function splitProps(props) {
  * `key` of the component to mount another); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders. The callbacks
  * (`onChange`, `onSelection`, `onCursor`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
  */
-function useMountedEditor(container, props, onEditor) {
+function useMountedEditor(container, props, onEditor, registerPanel) {
   const [editor, setEditor] = useState(null);
   const latest = useRef(props);
   latest.current = props;
@@ -145,8 +146,11 @@ function useMountedEditor(container, props, onEditor) {
       if (cancelled) return;
       const { options } = splitProps(latest.current);
       const current = () => latest.current;
+      // CE-20: host panels with `render` are mounted by React through portals into the Studio's panel elements.
+      const hostPanels = (latest.current.hostPanels ?? []).map(({ render: _render, ...panel }) => ({ ...panel, mount: (panelElement) => registerPanel?.(panel.id, panelElement) }));
       created = createOpfEditor(element, {
         ...options,
+        ...(hostPanels.length ? { studio: { ...options.studio, hostPanels: [...(options.studio?.hostPanels ?? []), ...hostPanels] } } : {}),
         slots: resolveSlots(latest.current.slots),
         onChange: (detail) => current().onChange?.(detail),
         onSelection: (detail) => current().onSelection?.(detail),
@@ -188,10 +192,22 @@ function useMountedEditor(container, props, onEditor) {
  */
 export const OpfEditor = forwardRef(function OpfEditor(props, ref) {
   const container = useRef(null);
-  const editor = useMountedEditor(container, props, props.onEditor);
+  // CE-20: the elements of the Studio's host panels, by id, once the editor mounted them; each `render` goes there through a portal.
+  const [panelHosts, setPanelHosts] = useState({});
+  const registerPanel = useCallback((id, panelElement) => {
+    setPanelHosts((previous) => ({ ...previous, [id]: panelElement }));
+    return () => setPanelHosts((previous) => {
+      if (previous[id] !== panelElement) return previous;
+      const next = { ...previous };
+      delete next[id];
+      return next;
+    });
+  }, []);
+  const editor = useMountedEditor(container, props, props.onEditor, registerPanel);
   useImperativeHandle(ref, () => editor, [editor]);
   const { rest } = splitProps(props);
-  return createElement("div", { ref: container, id: rest.id, className: rest.className, style: rest.style, "data-opf-react": "" });
+  const portals = (props.hostPanels ?? []).map((panel) => (panelHosts[panel.id] && typeof panel.render === "function" ? createPortal(panel.render(), panelHosts[panel.id], panel.id) : null));
+  return createElement("div", { ref: container, id: rest.id, className: rest.className, style: rest.style, "data-opf-react": "" }, ...portals);
 });
 
 /**
@@ -218,6 +234,24 @@ export function useOpfSelection(editor) {
   return useSyncExternalStore(subscribe, () => (editor ? editor.selection : null), () => null);
 }
 
+/**
+ * CE-20: the Studio's commands for a host palette: `{ commands, run }`, where `commands` is `editor.commands.list()` (id, label, group, keys,
+ * shortcut, enabled, reason), read again after every selection, document, layout and command change, and `run(id)` runs one.
+ */
+export function useOpfCommands(editor) {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    if (!editor) return undefined;
+    const bump = () => setVersion((value) => value + 1);
+    const stops = ["selection", "change", "layout", "command", "source", "slide"].map((name) => editor.on(name, bump));
+    return () => { for (const stop of stops) stop(); };
+  }, [editor]);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const commands = useMemo(() => (editor ? editor.commands.list() : []), [editor, version]);
+  const run = useCallback((id) => (editor ? editor.commands.run(id) : false), [editor]);
+  return { commands, run };
+}
+
 /** The path under the caret of the source pane (the latest `cursor` event: `{ pointer, idPath, from, to, ... }`), or `null` before the first. */
 export function useOpfCursor(editor) {
   const subscribe = useCallback(subscribeTo(editor, "cursor"), [editor]);

package/dist/slide-adapter.d.ts

@@ -0,0 +1,49 @@
+/** CE-19 (internal; no package subpath exports it yet): the studio kit's document adapter for the slides of a deck, over an editor session. */
+import type { Catalog } from "@openpresentation/opf";
+import type { SlideComposition } from "@openpresentation/opf/composition";
+import type { EditorSession } from "./index.js";
+import type { StudioDocumentAdapter, StudioNode } from "./studio-kit/index.js";
+import type { KitSelectionAdapter } from "./studio-kit/selection.js";
+import type { PreparedSceneChange, StudioClipboard } from "./slide-edits.js";
+import type { SceneBox, SceneContainer, SceneDrop, SceneHit, SlideScene } from "./slide-scene.js";
+
+export type SlideCommand = "move" | "moveBy" | "moveInto" | "group" | "ungroup" | "duplicate" | "delete" | "resizeTracks" | "equalize" | "setWeights" | "paste" | "moveSlides";
+export declare const SLIDE_COMMANDS: readonly SlideCommand[];
+export interface SlideCommandResult { ok: boolean; changed: boolean; keys: string[]; label?: string; reason?: string }
+export interface SlideAdapterOptions {
+  slideIndex?: number;
+  /** The `SlideComposition` of a slide as it is drawn; default core composition with the session's catalogs. */
+  geometry?(presentation: unknown, slideIndex: number): SlideComposition;
+  /** The keys selected now, recorded with each change so undo and redo restore them. */
+  selection?(): string[];
+  onPreview?(event: { presentation: unknown | null; message?: string }): void;
+  onSelection?(keys: string[], info: { source: string }): void;
+  onRefuse?(event: { reason: string; command?: string }): void;
+}
+export interface SlideAdapter extends Omit<StudioDocumentAdapter<string, PreparedSceneChange>, "nodes" | "boxOf" | "containerOf" | "hitChain"> {
+  readonly session: EditorSession;
+  readonly slideIndex: number;
+  setSlide(indexOrKey: number | string): boolean;
+  scene(): SlideScene;
+  slides(): { key: string; path: string; index: number; label: string; hidden: boolean }[];
+  nodes(): StudioNode<string>[];
+  boxOf(key: string): (SceneBox & { depth: number }) | undefined;
+  containerOf(key: string): SceneContainer | undefined;
+  hitChain(point: { x: number; y: number }, skip?: (hit: SceneHit) => boolean, options?: { parts?: boolean }): SceneHit[];
+  target(chain: SceneHit[], options?: { primary?: string | null; shift?: boolean; deep?: boolean }): SceneHit | null;
+  dropAt(point: { x: number; y: number }, keys: string[]): (SceneDrop & { ok: boolean; reason: string; noop: boolean }) | null;
+  selectionAdapter(): KitSelectionAdapter<string>;
+  keyOf(path: string): string;
+  pathOf(key: string): string | null;
+  survivor(key: string): string | null;
+  ensureIds(): boolean;
+  prepare(command: SlideCommand, ...args: unknown[]): PreparedSceneChange & { base: unknown; command: SlideCommand };
+  apply(command: SlideCommand, ...args: unknown[]): SlideCommandResult;
+  run(command: SlideCommand, ...args: unknown[]): boolean;
+  readonly lastResult: SlideCommandResult | null;
+  copy(keys: string[]): StudioClipboard;
+  readonly gestureActive: boolean;
+  destroy(): void;
+}
+export declare function composeSlideGeometry(presentation: unknown, slideIndex: number, options?: { catalogs?: readonly Catalog[]; fonts?: unknown }): SlideComposition;
+export declare function createSlideAdapter(session: EditorSession, options?: SlideAdapterOptions): SlideAdapter;