@openpresentation/opf-editor 0.27.0 → 0.29.0

package/dist/react.d.ts

@@ -32,8 +32,9 @@ export declare function createOPFReactComponents(React: {
 };
 
 // ---- CE-06: the embeddable editor ---------------------------------------------------------------------------------------------------------
-import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, RefAttributes } from "react";
-import type { OpfEditor as OpfEditorHandle, OpfEditorOptions, OpfEditorSlots } from "./workspace.js";
+import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, ReactNode, RefAttributes } from "react";
+import type { SourceCursor } from "./source-pane.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 } };
@@ -45,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 })[];
 }
 
 /**
@@ -60,7 +66,13 @@ 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;
 
 export type { OpfEditorHandle };

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", "onError", "onReady"]);
+const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onCursor", "onError", "onReady", "hostPanels"]);
 
 function splitProps(props) {
   const options = {};
@@ -128,9 +129,9 @@ function splitProps(props) {
 /**
  * Create and destroy one editor in the element `container.current` points at. The options are read once, when the editor mounts (change the
  * `key` of the component to mount another); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders. The callbacks
- * (`onChange`, `onSelection`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
+ * (`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,11 +146,15 @@ 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),
+        onCursor: (detail) => current().onCursor?.(detail),
         onError: (error, detail) => current().onError?.(error, detail),
         onReady: (detail) => current().onReady?.(detail),
       });
@@ -187,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);
 });
 
 /**
@@ -216,3 +233,27 @@ export function useOpfSelection(editor) {
   const subscribe = useCallback(subscribeTo(editor, "selection"), [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]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.sourceCursor : null), () => null);
+}

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;

package/dist/slide-adapter.js

@@ -0,0 +1,289 @@
+// CE-19: the studio kit's document adapter for the slides of a deck, over an editor session. Layout Studio has `layout-adapter.js` over its
+// record model; this is the same contract over `createEditorSession`: keys are id paths (`/slides/@intro/blocks/@kpi`, see
+// `slide-scene.js`), boxes and containers come from the composed layout geometry of the current slide, a trial move runs the edit
+// without applying it, and every edit is ONE validated `applyPatch` guarded by `expectHash` (the document must still be the one the edit
+// was computed from). A gesture (a drag, a divider) previews drafts without writing to the document and lands as one undo step. No DOM:
+// the Studio (CE-20) draws, this answers.
+import { resolveSlideContext } from "@openpresentation/opf";
+import { composeSlide } from "@openpresentation/opf/composition";
+import { documentHash, resolveIdPointer, toIdPointer } from "@openpresentation/opf/ids";
+import { parsePointer } from "@openpresentation/opf/patch";
+import { createGesture } from "./studio-kit/gesture.js";
+import { dropTarget, slideScene } from "./slide-scene.js";
+import {
+  copyScene,
+  prepareSceneDelete,
+  prepareSceneDuplicate,
+  prepareSceneEqualize,
+  prepareSceneGroup,
+  prepareSceneMove,
+  prepareSceneMoveBy,
+  prepareSceneMoveInto,
+  prepareSceneMoveSlides,
+  prepareScenePaste,
+  prepareSceneTrackResize,
+  prepareSceneUngroup,
+  prepareSceneWeights,
+} from "./slide-edits.js";
+
+const COMMANDS = {
+  move: prepareSceneMove,
+  moveBy: prepareSceneMoveBy,
+  moveInto: prepareSceneMoveInto,
+  group: prepareSceneGroup,
+  ungroup: prepareSceneUngroup,
+  duplicate: prepareSceneDuplicate,
+  delete: prepareSceneDelete,
+  resizeTracks: prepareSceneTrackResize,
+  equalize: prepareSceneEqualize,
+  setWeights: prepareSceneWeights,
+  paste: prepareScenePaste,
+  moveSlides: prepareSceneMoveSlides,
+};
+/** The command names `prepare`, `apply` and `run` take. */
+export const SLIDE_COMMANDS = Object.freeze(Object.keys(COMMANDS));
+
+/** Core composition of slide `slideIndex` (portable text estimate unless `fonts` measure), as the session's `composeSlide` does. */
+export function composeSlideGeometry(presentation, slideIndex, { catalogs, fonts } = {}) {
+  const { slide, options } = resolveSlideContext(presentation, slideIndex, { catalogs, fonts });
+  return composeSlide(slide, options);
+}
+
+/**
+ * The studio document adapter of the slides of `session`. Options:
+ * - `slideIndex` (default 0): the slide the scene shows; `setSlide` changes it;
+ * - `geometry(presentation, slideIndex)`: the `SlideComposition` of a slide as it is drawn (the canvas's `onRender` geometry, or the
+ *   renderer's `resolvePresentation(...).slides[i].geometry` with the canvas fonts); default core composition with the session's catalogs;
+ * - `selection()`: the keys selected now, recorded with each change (`meta.selection`) so undo and redo can restore them;
+ * - `onPreview({ presentation, message })`: draw a gesture's draft (`presentation` is null when the gesture ends or is cancelled);
+ * - `onSelection(keys, { source })`: the keys to select after an edit, an undo or a redo;
+ * - `onRefuse({ reason, command })`: a command was refused (the Studio's status line and live region).
+ */
+export function createSlideAdapter(session, options = {}) {
+  if (!session || typeof session.applyPatch !== "function") throw new TypeError("createSlideAdapter needs an editor session.");
+  let slideIndex = options.slideIndex ?? 0;
+  let draft = null; // the prepared change a gesture shows
+  let lastResult = null;
+  const geometryOf = options.geometry ?? ((presentation, index) => composeSlideGeometry(presentation, index, { catalogs: session.catalogs }));
+  const document = () => session.snapshot().presentation;
+  const catalogs = () => session.catalogs;
+
+  // One scene per (document, slide); the draft's while a gesture previews one.
+  let cache = { doc: null, index: -1, scene: null };
+  function sceneFor(doc, index) {
+    if (cache.doc === doc && cache.index === index) return cache.scene;
+    const findings = doc === document() ? session.validation?.findings ?? [] : [];
+    const scene = slideScene(doc, index, { geometry: geometryOf(doc, index), findings });
+    cache = { doc, index, scene };
+    return scene;
+  }
+  const clampSlide = () => { const count = document().slides?.length ?? 0; slideIndex = Math.max(0, Math.min(slideIndex, count - 1)); return slideIndex; };
+  const committedScene = () => sceneFor(document(), clampSlide());
+  const scene = () => (draft ? sceneFor(draft.presentation, Math.min(slideIndex, draft.presentation.slides.length - 1)) : committedScene());
+
+  // Trial moves are asked on every pointer move of a drag: one answer per (document, keys, target, index).
+  let trials = { doc: null, map: new Map() };
+  function trialMove(keys, target, index) {
+    const doc = document();
+    if (trials.doc !== doc) trials = { doc, map: new Map() };
+    const id = JSON.stringify([keys, target, index]);
+    if (!trials.map.has(id)) {
+      let answer;
+      try {
+        const prepared = prepareSceneMove(doc, committedScene(), keys, target, index, { catalogs: catalogs() });
+        answer = { ok: true, reason: "", noop: !prepared.changed };
+      } catch (error) {
+        answer = { ok: false, reason: error?.message ?? String(error), noop: false };
+      }
+      trials.map.set(id, answer);
+    }
+    return trials.map.get(id);
+  }
+
+  /** Prepare `command` against the session's document without applying it (a refusal throws, with the reason as its message). */
+  function prepare(command, ...args) {
+    const run = COMMANDS[command];
+    if (!run) throw new TypeError(`Unknown slide command ${command}.`);
+    const doc = document();
+    const last = args.length && args.at(-1) && typeof args.at(-1) === "object" && !Array.isArray(args.at(-1)) && !args.at(-1).kind ? args.pop() : {};
+    const prepared = run(doc, committedScene(), ...args, { ...last, catalogs: catalogs() });
+    // CE-20: a caller may name the step itself (`{ label }` as the last argument: "Inserted chart" for a paste of a new block).
+    return { ...prepared, ...(typeof last.label === "string" ? { label: last.label } : {}), base: doc, command };
+  }
+
+  // Selections recorded per undo depth, so undo and redo restore the selection of the edit they cross.
+  const selections = new Map();
+  let applying = false;
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === "patch" && !applying) selections.delete(event.snapshot.undoDepth);
+    if (event.type === "restore") selections.clear();
+  });
+  const keysFor = (doc, paths) => (paths ?? []).map((path) => { try { return toIdPointer(doc, path); } catch { return path; } });
+
+  /** Apply a prepared change as one undo step, guarded by the hash of the document it was prepared from. */
+  function commitPrepared(prepared, message) {
+    if (!prepared?.changed) return result({ ok: true, changed: false, keys: keysFor(document(), prepared?.paths), label: prepared?.label ?? message });
+    const before = options.selection?.() ?? [];
+    const label = message ?? prepared.label;
+    applying = true;
+    try {
+      session.applyPatch(prepared.patches, { source: "studio", label, command: prepared.command, selection: before, rejectInvalid: true }, { expectHash: documentHash(prepared.base) });
+    } catch (error) {
+      const reason = error?.code === "patch-hash-mismatch" ? "The document changed while this edit was prepared. Nothing was changed; try again." : error?.message ?? String(error);
+      return refused(reason, prepared.command);
+    } finally {
+      applying = false;
+    }
+    const doc = document();
+    const keys = keysFor(doc, prepared.paths);
+    selections.set(session.snapshot().undoDepth, { before, after: keys });
+    if (prepared.paths?.[0]) {
+      const slide = parsePointer(prepared.paths[0]);
+      if (slide[0] === "slides" && /^\d+$/.test(slide[1] ?? "")) slideIndex = Number(slide[1]);
+    }
+    options.onSelection?.(keys, { source: prepared.command ?? "studio" });
+    return result({ ok: true, changed: true, keys, label });
+  }
+  function result(value) { lastResult = value; return value; }
+  function refused(reason, command) {
+    options.onRefuse?.({ reason, command });
+    return result({ ok: false, changed: false, keys: [], reason });
+  }
+
+  /** Prepare and apply `command` as one undo step. Returns `{ ok, changed, keys, label, reason }`; a refusal changes nothing. */
+  function apply(command, ...args) {
+    let prepared;
+    try {
+      prepared = prepare(command, ...args);
+    } catch (error) {
+      if (error instanceof TypeError && /^Unknown slide command/.test(error.message)) throw error;
+      return refused(error?.message ?? String(error), command);
+    }
+    return commitPrepared(prepared);
+  }
+
+  // A gesture over the kit's gesture history: drafts are prepared changes, shown through `onPreview`; the end applies the last one.
+  const gesture = createGesture({
+    snapshot: () => document(),
+    preview(prepared, message) {
+      draft = prepared?.changed ? prepared : null;
+      options.onPreview?.({ presentation: draft?.presentation ?? null, message });
+    },
+    commit(start, { message }) {
+      const last = draft;
+      draft = null;
+      options.onPreview?.({ presentation: null, message });
+      if (!last) return false;
+      if (last.base !== start) { refused("The document changed during the gesture. Nothing was changed.", last.command); return false; }
+      return commitPrepared(last, message).changed;
+    },
+    restore() {
+      draft = null;
+      options.onPreview?.({ presentation: null });
+    },
+  });
+
+  const historyStep = (direction) => {
+    const depth = session.snapshot().undoDepth;
+    const change = direction < 0 ? session.undo({ source: "studio" }) : session.redo({ source: "studio" });
+    if (!change) return false;
+    const entry = selections.get(direction < 0 ? depth : session.snapshot().undoDepth);
+    if (entry) options.onSelection?.(direction < 0 ? entry.before : entry.after, { source: direction < 0 ? "undo" : "redo" });
+    return true;
+  };
+
+  const slideKeyAt = (doc, index) => toIdPointer(doc, `/slides/${index}`);
+  const isSlideKey = (key) => typeof key === "string" && !key.includes("#") && parsePointer(key).length === 2 && parsePointer(key)[0] === "slides";
+  const slideOf = (key) => { try { return Number(parsePointer(resolveIdPointer(document(), key))[1]); } catch { return -1; } };
+
+  /** The kit selection's adapter: slide keys at the top (nothing selected is the deck), then the current slide's tree. */
+  function selectionAdapter() {
+    return {
+      exists: (key) => (isSlideKey(key) ? slideOf(key) >= 0 : Boolean(scene().node(key))),
+      parent: (key) => (isSlideKey(key) ? null : scene().node(key)?.parent ?? null),
+      firstChild(key) {
+        const s = scene();
+        if (isSlideKey(key) && slideOf(key) !== slideIndex) return null;
+        const first = s.children(isSlideKey(key) ? s.slideKey : key).find((node) => node.kind !== "part");
+        return first?.key ?? null;
+      },
+      sibling(key, delta) {
+        if (isSlideKey(key)) { const doc = document(); const at = slideOf(key) + delta; return at >= 0 && at < doc.slides.length ? slideKeyAt(doc, at) : null; }
+        const s = scene(), node = s.node(key);
+        if (!node?.parent) return null;
+        const list = s.children(node.parent).filter((child) => child.kind !== "part");
+        return list[list.findIndex((child) => child.key === key) + delta]?.key ?? null;
+      },
+      first: () => scene().slideKey,
+      siblings(key) {
+        if (isSlideKey(key)) { const doc = document(); return doc.slides.map((_, at) => slideKeyAt(doc, at)); }
+        const s = scene(), node = s.node(key);
+        return node?.parent ? s.children(node.parent).filter((child) => child.kind !== "part").map((child) => child.key) : [key];
+      },
+    };
+  }
+
+  return {
+    session,
+    get slideIndex() { return clampSlide(); },
+    /** Show slide `indexOrKey` (an index or a slide key). Returns false when there is no such slide. */
+    setSlide(indexOrKey) {
+      const index = typeof indexOrKey === "number" ? indexOrKey : slideOf(indexOrKey);
+      if (!Number.isInteger(index) || index < 0 || index >= (document().slides?.length ?? 0)) return false;
+      slideIndex = index;
+      return true;
+    },
+    /** The scene of the current slide (of the gesture's draft while one previews). */
+    scene,
+    /** The slides of the deck, for the filmstrip: `{ key, path, index, label, hidden }`. */
+    slides() {
+      const doc = document();
+      return (doc.slides ?? []).map((slide, index) => ({ key: slideKeyAt(doc, index), path: `/slides/${index}`, index, label: `Slide ${index + 1}${typeof slide.layout === "string" && slide.layout !== "auto" ? ` · ${slide.layout}` : ""}`, hidden: slide.hidden === true }));
+    },
+    /** The current slide's nodes as the kit's layers and overlay read them. */
+    nodes: () => scene().nodes.map(({ key, path, kind, parent, depth, label, findings }) => ({ key, path, kind, parent, depth, label, findings })),
+    boxOf: (key) => scene().boxOf(key),
+    containerOf: (key) => scene().containerOf(key),
+    /** The boxes under a unit point, outermost first (the kit's signature; `skip(box)` leaves boxes out, `box.node` is the scene node). */
+    hitChain: (point, skip, hitOptions = {}) => scene().hitChain(point, { ...hitOptions, skip }),
+    /** The node a click on `chain` selects (see `SlideScene.target`). */
+    target: (chain, targetOptions = {}) => scene().target(chain, { primary: options.selection?.().at(-1) ?? null, ...targetOptions }),
+    trialMove,
+    /** Where the dragged `keys` would land at `point`, with the trial's answer: `{ target, index, line, into, ok, reason, noop }`, or null. */
+    dropAt(point, keys) {
+      const found = dropTarget(committedScene(), point, keys);
+      if (!found) return null;
+      return { ...found, ...trialMove(keys, found.target, found.index) };
+    },
+    selectionAdapter,
+    /** The key of an index pointer in the current document (its id path), or the pointer when it does not resolve. */
+    keyOf: (path) => keysFor(document(), [path])[0],
+    /** The index pointer a key names now, or null when it is gone (a virtual region key gives its slide's pointer). */
+    pathOf(key) {
+      try { return resolveIdPointer(document(), key.split("#")[0]); } catch { return null; }
+    },
+    /** The nearest existing node at or above `key` on the current slide (selection after an edit by someone else). */
+    survivor: (key) => scene().survivor(key),
+    /** Give every slide and block an id (one undoable change named "Add ids"), so keys survive reorders. Returns whether ids were added. */
+    ensureIds() {
+      const change = session.assignIds({}, { source: "assign-ids", label: "Add ids" });
+      return Boolean(change);
+    },
+    prepare,
+    apply,
+    /** `apply(command, ...args).changed`, for the kit's `run`. */
+    run: (command, ...args) => apply(command, ...args).changed,
+    get lastResult() { return lastResult; },
+    /** What the clipboard holds for `keys` (`copyScene`); paste it with `apply("paste", clip, { target, index })`. */
+    copy: (keys) => copyScene(document(), committedScene(), keys, { catalogs: catalogs() }),
+    begin: (label) => gesture.begin(label),
+    /** Show a draft: a change from `prepare` (or null to show the document). Nothing is written until `commit`. */
+    preview: (prepared, message) => { gesture.update(prepared, message); },
+    commit: (message) => gesture.end(message),
+    cancel: () => { gesture.cancel(); },
+    get gestureActive() { return gesture.active; },
+    undo: () => historyStep(-1),
+    redo: () => historyStep(1),
+    destroy() { gesture.reset(); draft = null; unsubscribe(); },
+  };
+}

package/dist/slide-edits.d.ts

@@ -0,0 +1,46 @@
+/** CE-19 (internal): the structural edits of the slide scene, as prepared changes (nothing is applied). */
+import type { Catalog } from "@openpresentation/opf";
+import type { JsonPatchOperation, OPFEditorError } from "./index.js";
+import type { SlideScene } from "./slide-scene.js";
+import type { SlideComposition } from "@openpresentation/opf/composition";
+
+export interface PreparedSceneChange {
+  presentation: unknown;
+  patches: JsonPatchOperation[];
+  changed: boolean;
+  /** Index pointers to select afterwards. */
+  paths: string[];
+  label?: string;
+  /** A move that changes nothing. */
+  noop?: boolean;
+  lossless?: boolean;
+  loss?: unknown[];
+  weights?: number[];
+  [key: string]: unknown;
+}
+export interface SceneEditOptions { catalogs?: readonly Catalog[] }
+export type StudioClipboard =
+  | { kind: "opf-studio-blocks"; blocks: unknown[]; count: number }
+  | { kind: "opf-studio-slides"; presentation: unknown; count: number };
+
+export declare function refuse(message: string, details?: Record<string, unknown>): OPFEditorError;
+export declare function prepareSceneMove(presentation: unknown, scene: SlideScene, keys: string[], targetKey: string, index: number, options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneMoveBy(presentation: unknown, scene: SlideScene, keys: string[], delta: -1 | 1, options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneMoveInto(presentation: unknown, scene: SlideScene, keys: string[], delta: -1 | 1, options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneGroup(presentation: unknown, scene: SlideScene, keys: string[], options?: SceneEditOptions & { composition?: Record<string, unknown> }): PreparedSceneChange;
+export declare function prepareSceneUngroup(presentation: unknown, scene: SlideScene, key: string, options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneDuplicate(presentation: unknown, scene: SlideScene, keys: string[], options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneDelete(presentation: unknown, scene: SlideScene, keys: string[], options?: SceneEditOptions): PreparedSceneChange;
+export declare function ratioLabel(a: number, b: number): string;
+/**
+ * The weights a composed flow's tracks are drawn with (`drawn` when a content-sized column is read as weights from its drawn heights, the
+ * last row taking the empty space), and `scale(boundary)`, which turns a fraction of the drawn pair into the fraction of the weighted pair.
+ */
+export declare function drawnTracks(flow: SlideComposition["flows"][number]): { weights: number[]; drawn: boolean; scale(boundary: number): number };
+export declare function snapTrackPair(weights: number[], boundary: number, fraction: number, options?: { free?: boolean }): { a: number; b: number };
+export declare function prepareSceneTrackResize(presentation: unknown, scene: SlideScene, key: string, boundary: number, fraction: number, options?: SceneEditOptions & { free?: boolean }): PreparedSceneChange;
+export declare function prepareSceneEqualize(presentation: unknown, scene: SlideScene, key: string, boundary: number, options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneWeights(presentation: unknown, scene: SlideScene, key: string, weights: number[], options?: SceneEditOptions): PreparedSceneChange;
+export declare function prepareSceneMoveSlides(presentation: unknown, scene: SlideScene, keys: string[], to: number, options?: SceneEditOptions & { section?: string | null }): PreparedSceneChange;
+export declare function copyScene(presentation: unknown, scene: SlideScene, keys: string[], options?: SceneEditOptions): StudioClipboard;
+export declare function prepareScenePaste(presentation: unknown, scene: SlideScene, clip: StudioClipboard, options?: SceneEditOptions & { target?: string; index?: number; slideIndex?: number }): PreparedSceneChange;