@openpresentation/opf-editor 0.10.6 → 0.11.1

package/dist/background-options.js

@@ -0,0 +1,134 @@
+// Backgrounds (RR-06): every background form the schema has, with validation that explains itself.
+// A background is a theme slot, a solid color, a linear gradient, an image or a pattern, at the deck
+// or on one slide. `setBackground` is one undoable patch through the `backgrounds` switch, so the
+// preview, export and Undo behave like every other dimension.
+import { prepareDimensionSwitch, switchDimension } from "./switches.js";
+import { fail } from "./edit-helpers.js";
+
+export const BACKGROUND_TYPES = Object.freeze(["theme", "solid", "gradient", "image", "pattern"]);
+export const THEME_BACKGROUND_SLOTS = Object.freeze(["light1", "light2", "dark1", "dark2"]);
+export const IMAGE_BACKGROUND_FITS = Object.freeze(["cover", "contain", "tile"]);
+/** Scheme slots and roles a ColorRef may name (the schema's ColorRef enum), besides hex colors and `var:<id>`. */
+export const COLOR_NAMES = Object.freeze([
+  "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink",
+  "primary", "secondary", "accent", "background", "surface", "text", "textSecondary",
+]);
+/**
+ * The 54 DrawingML preset patterns (ECMA-376 ST_PresetPatternVal) by family. PPTX export writes them as
+ * native pattern fills; the schema also allows engine-defined ids, which `setBackground` accepts as text.
+ */
+export const PATTERN_GROUPS = Object.freeze({
+  Percent: ["pct5", "pct10", "pct20", "pct25", "pct30", "pct40", "pct50", "pct60", "pct70", "pct75", "pct80", "pct90"],
+  "Horizontal and vertical": ["horz", "vert", "ltHorz", "ltVert", "dkHorz", "dkVert", "narHorz", "narVert", "dashHorz", "dashVert", "cross"],
+  Diagonal: ["dnDiag", "upDiag", "ltDnDiag", "ltUpDiag", "dkDnDiag", "dkUpDiag", "wdDnDiag", "wdUpDiag", "dashDnDiag", "dashUpDiag", "diagCross"],
+  "Checks, grids and bricks": ["smCheck", "lgCheck", "smGrid", "lgGrid", "dotGrid", "smConfetti", "lgConfetti", "horzBrick", "diagBrick"],
+  "Shapes and textures": ["solidDmnd", "openDmnd", "dotDmnd", "plaid", "sphere", "weave", "divot", "shingle", "wave", "trellis", "zigZag"],
+});
+export const PATTERN_PRESETS = Object.freeze(Object.values(PATTERN_GROUPS).flat());
+
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** Whether `value` is a ColorRef: a hex color, a scheme slot or role name, or `var:<id>`. */
+export function isColorRef(value) {
+  return typeof value === "string" && (HEX.test(value) || COLOR_NAMES.includes(value) || /^var:[a-z][a-z0-9-]*$/.test(value));
+}
+
+function colorRef(value, what) {
+  if (!isColorRef(value)) throw fail("invalid-background", `${what} must be a hex color such as #1F2937, a scheme color such as accent1 or surface, or var:<id>.`, { value });
+  return typeof value === "string" && HEX.test(value) ? value.toUpperCase() : value;
+}
+
+function opacityOf(spec) {
+  if (spec.opacity === undefined || spec.opacity === null) return undefined;
+  if (typeof spec.opacity !== "number" || !(spec.opacity >= 0 && spec.opacity <= 1)) throw fail("invalid-background", "Background opacity is a number from 0 to 1.", { opacity: spec.opacity });
+  return spec.opacity;
+}
+
+/**
+ * Validate a background description and return the value to store: a theme slot or a plain hex color stays
+ * the shorthand string; everything else is the object form. Throws `invalid-background` with a sentence a
+ * person can act on. Gradient stops are sorted by position (at least two); radial gradients are not part
+ * of the schema.
+ */
+export function normalizeBackground(spec) {
+  if (typeof spec === "string") {
+    if (THEME_BACKGROUND_SLOTS.includes(spec)) return spec;
+    if (HEX.test(spec)) return spec.toUpperCase();
+    throw fail("invalid-background", `A background shorthand is a theme slot (${THEME_BACKGROUND_SLOTS.join(", ")}) or a hex color.`, { spec });
+  }
+  if (!isObject(spec)) throw fail("invalid-background", "Describe the background as { type, ... } or a theme slot / hex shorthand.", { spec });
+  const opacity = opacityOf(spec);
+  const withOpacity = (value) => (opacity === undefined ? value : { ...value, opacity });
+  switch (spec.type) {
+    case "theme":
+      if (!THEME_BACKGROUND_SLOTS.includes(spec.slot)) throw fail("invalid-background", `A theme background names a slot: ${THEME_BACKGROUND_SLOTS.join(", ")}.`, { spec });
+      return spec.slot;
+    case "solid": {
+      const color = colorRef(spec.color, "A solid background color");
+      return opacity === undefined && HEX.test(color) ? color : withOpacity({ type: "solid", color });
+    }
+    case "gradient": {
+      const gradient = spec.gradient;
+      if (!isObject(gradient) || !Array.isArray(gradient.stops) || gradient.stops.length < 2) throw fail("invalid-background", "A gradient needs at least two color stops.", { spec });
+      const stops = gradient.stops.map((stop, index) => {
+        if (!isObject(stop)) throw fail("invalid-background", `Stop ${index + 1} needs a color and a position.`, { spec });
+        const position = typeof stop.position === "string" && stop.position.trim() !== "" ? Number(stop.position) : stop.position;
+        if (typeof position !== "number" || !(position >= 0 && position <= 1)) throw fail("invalid-background", `Stop ${index + 1}: the position is a number from 0 (start) to 1 (end).`, { spec });
+        return { color: colorRef(stop.color, `Stop ${index + 1}: the color`), position };
+      });
+      stops.sort((a, b) => a.position - b.position);
+      const angle = gradient.angle === undefined || gradient.angle === null || gradient.angle === "" ? undefined : Number(gradient.angle);
+      if (angle !== undefined && !Number.isFinite(angle)) throw fail("invalid-background", "The gradient angle is a number of degrees (0 is left to right, 90 top to bottom).", { spec });
+      return withOpacity({ type: "gradient", gradient: { ...(angle === undefined ? {} : { angle }), stops } });
+    }
+    case "image": {
+      const image = spec.image;
+      if (!isObject(image) || typeof image.src !== "string" || !image.src.trim()) throw fail("invalid-background", "An image background needs an image: choose a file or enter a source.", { spec });
+      if (image.fit !== undefined && image.fit !== "" && !IMAGE_BACKGROUND_FITS.includes(image.fit)) throw fail("invalid-background", `Image fit is one of ${IMAGE_BACKGROUND_FITS.join(", ")}.`, { spec });
+      return withOpacity({ type: "image", image: { src: image.src.trim(), ...(image.fit ? { fit: image.fit } : {}) } });
+    }
+    case "pattern": {
+      const pattern = spec.pattern;
+      if (!isObject(pattern) || typeof pattern.preset !== "string" || !pattern.preset.trim()) throw fail("invalid-background", "A pattern background needs a preset.", { spec });
+      const out = { preset: pattern.preset.trim() };
+      if (pattern.foregroundColor) out.foregroundColor = colorRef(pattern.foregroundColor, "The pattern foreground color");
+      if (pattern.backgroundColor) out.backgroundColor = colorRef(pattern.backgroundColor, "The pattern background color");
+      return withOpacity({ type: "pattern", pattern: out });
+    }
+    default:
+      throw fail("invalid-background", `Background type is one of ${BACKGROUND_TYPES.join(", ")}.`, { spec });
+  }
+}
+
+/** Compute the patch that sets (or, for `null`, removes) the background, without touching a session. Options as `prepareDimensionSwitch` (`slideIndex`, `clearSlideOverrides`). */
+export function prepareBackground(document, spec, options = {}) {
+  return prepareDimensionSwitch(document, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
+}
+
+/** Set the background as one undoable transaction; `null` removes it so the theme's (or the deck's) shows again. */
+export function setBackground(editor, spec, options = {}) {
+  return switchDimension(editor, "backgrounds", spec === null ? null : normalizeBackground(spec), options);
+}
+
+/**
+ * The background that applies at a scope as a flat description for a form:
+ * `{ type, slot?, color?, opacity?, angle?, stops?, src?, fit?, preset?, foregroundColor?, backgroundColor?, scope, value }`.
+ * `type` is undefined when nothing is set; `scope` is "slide" when the slide sets its own, else "deck".
+ */
+export function readBackground(document, { slideIndex } = {}) {
+  const own = slideIndex === undefined ? undefined : document.slides?.[slideIndex]?.design?.background;
+  const value = own !== undefined ? own : document.design?.background;
+  const scope = own !== undefined ? "slide" : "deck";
+  if (value === undefined) return { scope };
+  if (typeof value === "string") return THEME_BACKGROUND_SLOTS.includes(value) ? { type: "theme", slot: value, scope, value } : { type: "solid", color: value, scope, value };
+  if (!isObject(value)) return { scope, value };
+  const base = { type: value.type, opacity: value.opacity, scope, value };
+  if (value.type === "theme") return { ...base, slot: value.slot };
+  if (value.type === "solid") return { ...base, color: value.color };
+  if (value.type === "gradient") return { ...base, angle: value.gradient?.angle, stops: structuredClone(value.gradient?.stops ?? []) };
+  if (value.type === "image") return { ...base, src: value.image?.src, fit: value.image?.fit };
+  if (value.type === "pattern") return { ...base, preset: value.pattern?.preset, foregroundColor: value.pattern?.foregroundColor, backgroundColor: value.pattern?.backgroundColor };
+  return base;
+}
+

package/dist/block-convert.d.ts

@@ -0,0 +1,64 @@
+import type { ConvertOptions } from "@openpresentation/opf/convert";
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+
+export type { ConvertOptions } from "@openpresentation/opf/convert";
+
+export type BlockKind = "text" | "list" | "quote" | "metric" | "code" | "timeline" | "chart" | "table" | "image" | "video" | "group" | "metrics";
+/** Display label of every content kind. */
+export declare const BLOCK_KIND_LABELS: Readonly<Record<BlockKind, string>>;
+/** Source kind to the kinds it can convert to (core's `CONTENT_CONVERSIONS`): text to list, quote, metric, code, timeline or table; list to text, timeline or table; quote, metric and code to text; timeline to text, list or table; chart to table; table to chart, list, timeline, text or a set of metric blocks; a group of metric blocks to a table. */
+export declare const BLOCK_CONVERSIONS: Readonly<Record<string, readonly BlockKind[]>>;
+
+export interface BlockContent {
+  path: string[];
+  /** True for a `blocks/N` block, false for a slide or region holding one content field. */
+  explicit: boolean;
+  owner: Record<string, unknown>;
+  /** The content field: text, items, bullets, chart, table, and so on. */
+  key: string;
+  /** The content kind (`items` and `bullets` are both "list"). */
+  kind: BlockKind;
+  content: unknown;
+}
+export interface BlockConversionTarget {
+  kind: BlockKind;
+  label: string;
+  available: boolean;
+  /** True when everything in the block carries over. */
+  lossless: boolean;
+  /** What the target cannot carry, for example "text formatting", "list nesting levels", "chart type". */
+  loss: string[];
+  /** Why the conversion is unavailable (available is false). */
+  reason?: string;
+}
+export interface PreparedBlockConversion {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  path: string;
+  changed: boolean;
+  lossless: boolean;
+  loss: string[];
+  from: BlockKind;
+  to: BlockKind;
+}
+export interface BlockConversionChange extends Omit<EditorChange, "document" | "patches"> {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  lossless: boolean;
+  loss: string[];
+  from: BlockKind;
+  to: BlockKind;
+  path: string;
+  changed: boolean;
+}
+
+/** The single content payload of the block at `path`, or undefined (image-only, groups and blocks with several fields have none to convert). */
+export declare function readBlockContent(document: unknown, path: string | string[]): BlockContent | undefined;
+/** The block that contains a selected path (slides.0.blocks.1.text maps to slides.0.blocks.1), or undefined. */
+export declare function blockPathForSelection(document: unknown, selectedPath: string): string | undefined;
+/** The kinds the block can convert to, each with its loss report or the reason it is unavailable. */
+export declare function blockConversionTargets(document: unknown, path: string | string[]): BlockConversionTarget[];
+/** Compute the conversion patch without touching a session. Throws `block-not-convertible` for an unsupported pair or content that does not fit. */
+export declare function prepareBlockConversion(document: unknown, path: string | string[], kind: BlockKind, options?: ConvertOptions): PreparedBlockConversion;
+/** Convert one block as a single undoable transaction. */
+export declare function convertBlock(editor: EditorSession, path: string | string[], kind: BlockKind, meta?: Record<string, unknown>, options?: ConvertOptions): BlockConversionChange;

package/dist/block-convert.js

@@ -0,0 +1,142 @@
+// Safe content-type conversion for one block (RR-06; RR-26 moved the converters into core).
+// The pure converters live in `@openpresentation/opf/convert`: a conversion moves the block's own text into
+// the new content type and never invents content, what a conversion cannot carry is reported in `loss`
+// instead of being dropped silently, and a pair that has no meaningful mapping is refused. This module is the
+// transaction around them: it finds the block, turns the converted payload into one guarded patch, validates
+// the document, and applies it as one undoable step.
+import { CONTENT_CONVERSIONS, CONTENT_KIND_LABELS, OPFConversionError, contentConversionTargets, convertContent, readContent } from "@openpresentation/opf/convert";
+import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { listBlockContainers } from "./blocks.js";
+import { fail } from "./edit-helpers.js";
+
+/** Every content kind a block can hold, with its display label. */
+export const BLOCK_KIND_LABELS = CONTENT_KIND_LABELS;
+/** The conversion matrix: source kind to the kinds it can convert to (core's `CONTENT_CONVERSIONS`). */
+export const BLOCK_CONVERSIONS = CONTENT_CONVERSIONS;
+
+const refuse = (message, details) => fail("block-not-convertible", message, details);
+const CHOOSE = "Choose a block that holds one text, list, quote, metric, code, timeline, chart or table payload, or a group of metric blocks.";
+
+/** Run a core conversion; a refusal becomes the editor's `block-not-convertible`. */
+function convertOwner(owner, kind, options) {
+  try {
+    return convertContent(owner, kind, options);
+  } catch (error) {
+    if (error instanceof OPFConversionError) throw refuse(error.message, { ...error.details, kind });
+    throw error;
+  }
+}
+
+/**
+ * The single content payload of the block at `path` (an explicit `blocks/N` block, or a slide or
+ * region that holds exactly one content field), or a group of metric blocks (a `blocks` array in a
+ * slide, region or group). Returns undefined when there is none.
+ */
+export function readBlockContent(document, path) {
+  let parts;
+  try {
+    parts = splitOpfPath(path);
+  } catch {
+    return undefined;
+  }
+  const pointer = opfPathToJsonPointer(parts);
+  const explicit = parts.at(-2) === "blocks" && /^(0|[1-9][0-9]*)$/.test(parts.at(-1) ?? "");
+  const owner = getValueAtPath(document, parts);
+  if (!owner || typeof owner !== "object" || Array.isArray(owner)) return undefined;
+  if (Array.isArray(owner.blocks)) {
+    // Only a set of metrics converts as a group; any other group has nothing to offer.
+    if (!contentConversionTargets(owner).length) return undefined;
+    return { path: parts, explicit, owner, key: "blocks", kind: "group", content: owner.blocks };
+  }
+  if (!explicit) {
+    const implicit = listBlockContainers(document, { includeImplicit: true }).find((entry) => entry.path === pointer && entry.implicit);
+    if (!implicit || implicit.count !== 1) return undefined;
+  }
+  const info = readContent(owner);
+  if (!info) return undefined;
+  return { path: parts, explicit, owner, key: info.key, kind: info.kind, content: info.content };
+}
+
+/** Whether `path` is inside a block and, if so, that block's path. A selection such as slides.0.blocks.1.text maps to slides.0.blocks.1. */
+export function blockPathForSelection(document, selectedPath) {
+  let parts;
+  try {
+    parts = splitOpfPath(selectedPath);
+  } catch {
+    return undefined;
+  }
+  for (let length = parts.length; length >= 2; length -= 1) {
+    const candidate = parts.slice(0, length);
+    if (candidate[0] !== "slides") return undefined;
+    const found = readBlockContent(document, candidate);
+    // A slide or region that holds one payload inline is a block only when the selection is that payload.
+    if (found && found.kind !== "group" && (found.explicit || parts[length] === found.key)) return candidate.join(".");
+  }
+  return undefined;
+}
+
+/**
+ * The nearest group of metric blocks around a selection (`slides.0.blocks.2.metric` finds `slides.0` when the
+ * slide's blocks are all metrics), or undefined. A group of metrics converts to a table as a whole.
+ */
+export function metricGroupForSelection(document, selectedPath) {
+  let parts;
+  try {
+    parts = splitOpfPath(selectedPath);
+  } catch {
+    return undefined;
+  }
+  if (parts[0] !== "slides") return undefined;
+  for (let length = parts.length; length >= 2; length -= 1) {
+    const candidate = parts.slice(0, length);
+    const found = readBlockContent(document, candidate);
+    if (found?.kind === "group") return candidate.join(".");
+  }
+  return undefined;
+}
+
+/**
+ * The kinds the block at `path` can convert to, each with whether the conversion keeps everything
+ * (`lossless`), what it cannot carry (`loss`), or why it is unavailable (`available: false`).
+ * Returns [] for a block with no convertible content (image, video, a group that is not a set of metrics, several fields).
+ * `options` are core's conversion options (`looseWhen`, `fences`, `headings`, `columns`, `delimiter`, `header`).
+ */
+export function blockConversionTargets(document, path, options = {}) {
+  const found = readBlockContent(document, path);
+  return found ? contentConversionTargets(found.owner, options) : [];
+}
+
+/**
+ * Compute the patch that converts the block at `path` to `kind`, without touching a session.
+ * Throws `block-not-convertible` for a pair with no safe mapping or content that does not fit.
+ * `prepared.loss` lists what the target cannot carry; `lossless` is true when nothing is lost.
+ */
+export function prepareBlockConversion(document, path, kind, options = {}) {
+  const found = readBlockContent(document, path);
+  if (!found) throw refuse(CHOOSE, { path });
+  const pointer = opfPathToJsonPointer(found.path);
+  const from = found.kind;
+  const result = convertOwner(found.owner, kind, options);
+  if (!result.changed) return { document: structuredClone(document), patches: [], path: found.path.join("."), changed: false, lossless: true, loss: [], from, to: kind };
+  const patches = [
+    { op: "test", path: pointer, value: structuredClone(found.owner) },
+    { op: "replace", path: pointer, value: result.payload },
+  ];
+  const next = applyJsonPatch(document, patches);
+  const validation = validateOpfDocument(next);
+  if (!validation.valid) throw fail("invalid-opf-edit", validation.errors[0]?.message ?? "The converted block is not valid OPF.", { issues: validation.errors, patches });
+  return { document: next, patches, path: found.path.join("."), changed: true, lossless: result.lossless, loss: result.loss, from, to: kind };
+}
+
+/**
+ * Convert one block to another content kind as a single undoable transaction. Returns the session
+ * change plus `lossless`, `loss`, `from` and `to`.
+ */
+export function convertBlock(editor, path, kind, meta = {}, options = {}) {
+  if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+  const prepared = prepareBlockConversion(editor.document, path, kind, options);
+  const summary = { lossless: prepared.lossless, loss: prepared.loss, from: prepared.from, to: prepared.to, path: prepared.path, changed: prepared.changed };
+  if (!prepared.changed) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? "block-conversion", blockPath: prepared.path, from: prepared.from, to: prepared.to });
+  return { ...change, ...summary };
+}

package/dist/canvas.d.ts

@@ -42,6 +42,7 @@ export interface CanvasEditorOptions {
   slideIndex?: number;
   /** Show keyboard-accessible dividers for resizing composition tracks. */
   layoutEditing?: boolean;
+  /** Render options. The canvas draws the document as authored (`variables: false`: a template's `{{tokens}}` stay visible, so inline edits never overwrite them); pass `variables` to draw resolved values instead. */
   renderOptions?: RenderSvgOptions;
   /**
    * A font gate (`createFontGate(registry)`). With one, the canvas never renders a document whose faces are still
@@ -56,6 +57,8 @@ export interface CanvasEditorOptions {
    * their properties on double-click.
    */
   textEntry?: "click" | "dblclick";
+  /** Picture tools (default true): a selected picture shows a "Crop picture" button that opens the crop and focal point layer. */
+  imageTools?: boolean;
   /** Optional empty host for property forms; defaults to a floating canvas panel. */
   propertiesContainer?: HTMLElement;
   onSelect?: (selection: {
@@ -88,6 +91,13 @@ export interface CanvasEditor {
   readonly slideIndex: number;
   readonly editingPath: string | null;
   readonly layoutEditing: boolean;
+  /** True while the crop layer is open. */
+  readonly cropping: boolean;
+  /**
+   * Open the crop layer for the picture at `path` (an image block, a slide's `image`, or `slides.N.design.slideImage`); `tool: "focus"`
+   * starts with the focal point. Apply writes one undoable change (see `@openpresentation/opf-editor/image-crop`). Resolves to whether it opened.
+   */
+  cropImage(path: string, options?: { tool?: "crop" | "focus" }): Promise<boolean>;
   setLayoutEditing(enabled: boolean): boolean;
   /** Open reorder and move-to-group controls for a complete block path. */
   openBlockMenu(path: string): void;
@@ -102,6 +112,12 @@ export interface CanvasEditor {
   cancel(): void;
   render(document?: unknown): void;
   setSlide(index: number): boolean;
+  /**
+   * Select the content at `path`, or the closest enclosing content the canvas can select (a list item selects its list),
+   * after showing the slide the path is on. Returns the selected path, or null when nothing is selectable there (speaker
+   * notes, deck fields) or the slide is not drawn yet (fonts loading). Moves keyboard focus only with `focus: true`.
+   */
+  reveal(path: string, options?: { focus?: boolean }): string | null;
   setRenderOptions(options: RenderSvgOptions): boolean;
   destroy(): void;
 }

package/dist/canvas.js

@@ -20,6 +20,7 @@ import { createLayoutHandles } from "./layout-handles.js";
 import { createRichTextInput } from "./rich-text-input.js";
 import { textInputOffsetAtPoint } from "./text-pointer.js";
 import { createRichTextToolbar } from "./rich-text-toolbar.js";
+import { createImageCropper } from "./image-cropper.js";
 import { FONTS_PENDING, fontsPendingError, whenFontsReady } from "./font-gate.js";
 export { getEditableFields } from "./canvas-fields.js";
 export { createFontGate, whenFontsReady, FONTS_PENDING, FONTS_UNAVAILABLE } from "./font-gate.js";
@@ -69,7 +70,9 @@ export function createCanvasEditor(container, options = {}) {
   // loads them first and shows "Loading fonts…" meanwhile; without a gate every document renders at once, as before.
   const fonts = options.fonts;
   let slideIndex = options.slideIndex ?? 0,
-    renderOptions = options.renderOptions ?? {},
+    // RR-32: the canvas edits the document as authored, so a template's {{tokens}} stay visible and an inline edit never
+    // overwrites one with its resolved text. The Fill template panel previews the resolved deck. Pass `variables` to override.
+    renderOptions = { variables: false, ...(options.renderOptions ?? {}) },
     showToken = 0,
     fontsShown = false,
     active = null,
@@ -91,7 +94,7 @@ export function createCanvasEditor(container, options = {}) {
     overlay = doc.createElement("div"),
     notice = doc.createElement("div");
   root.className = "opf-canvas";
-  root.style.cssText = "position:relative;width:100%;isolation:isolate";
+  root.style.cssText = "position:relative;width:100%;isolation:isolate;touch-action:manipulation";
   preview.className = "opf-canvas-preview";
   overlay.className = "opf-canvas-overlay";
   overlay.style.cssText = "position:absolute;inset:0;pointer-events:none";
@@ -121,6 +124,15 @@ export function createCanvasEditor(container, options = {}) {
     },
     onChange(path) { clearNotice(); options.onCommit?.({path, editor}); }
   });
+  // RR-25: picture tools. A selected picture shows a "Crop picture" button; `cropImage(path)` opens the same layer.
+  const imageCropper = options.imageTools === false ? null : createImageCropper(root, overlay, {
+    editor,
+    beforeOpen: () => commit(),
+    getImageElement: (path) => [...preview.querySelectorAll("image[data-opf-path]")].find((node) => node.getAttribute("data-opf-path") === path) ?? null,
+    report,
+    onCommit: (value) => { clearNotice(); options.onCommit?.({ ...value, editor }); },
+    onCancel: () => options.onCancel?.({}),
+  });
   const layoutHandles = createLayoutHandles(root, {
     editor, enabled: options.layoutEditing, render: renderFor, beforeEdit: commit,
     isTextEditing: () => !!active,
@@ -147,6 +159,7 @@ export function createCanvasEditor(container, options = {}) {
   }
   function choose(path) {
     selectedPath = path;
+    imageCropper?.sync(path);
     for (const node of targets())
       node.toggleAttribute(
         "data-canvas-selected",
@@ -279,11 +292,14 @@ export function createCanvasEditor(container, options = {}) {
       if (node.matches("g")) {
         const bounds = allocatedSelectionBox(node, item);
         const rect = doc.createElementNS("http://www.w3.org/2000/svg", "rect");
+        // RR-25: on a touch screen a text block of a few slide units is a few pixels tall, so the target grows (up to 24 slide units
+        // each way) until it is about 44 CSS pixels in each direction.
+        const padX = touchPad(svg, bounds.width), padY = touchPad(svg, bounds.height);
         for (const [key, value] of Object.entries({
-          x: bounds.x - 4,
-          y: bounds.y - 4,
-          width: Math.max(8, bounds.width + 8),
-          height: Math.max(8, bounds.height + 8),
+          x: bounds.x - padX,
+          y: bounds.y - padY,
+          width: Math.max(2 * padX, bounds.width + 2 * padX),
+          height: Math.max(2 * padY, bounds.height + 2 * padY),
           fill: "transparent",
           stroke: "transparent",
           "stroke-width": 1.5,
@@ -326,6 +342,7 @@ export function createCanvasEditor(container, options = {}) {
     }
     layoutHandles.update(document, geometry);
     blockControls.update(document, geometry);
+    imageCropper?.update();
     if (active?.kind === "text") positionInput();
     if (active?.kind === "rich-text") active.rich?.update();
     if (fontsShown) {
@@ -340,6 +357,13 @@ export function createCanvasEditor(container, options = {}) {
       draft: !!active || !!layoutHandles.editingPath,
     });
   }
+  const coarse = win.matchMedia?.("(pointer: coarse)");
+  function touchPad(svg, size) {
+    if (!coarse?.matches) return 4;
+    const box = svg.getBoundingClientRect(), view = svg.viewBox?.baseVal;
+    const scale = box.width && view?.width ? box.width / view.width : 0;
+    return scale ? Math.max(4, Math.min(24, (44 / scale - size) / 2)) : 4;
+  }
   // An in-progress edit whose text needs faces that are not loaded yet waits for them, then draws again.
   function deferDraft(draft) {
     if (!fonts?.pending(draft, renderOptions).length) return false;
@@ -903,6 +927,43 @@ export function createCanvasEditor(container, options = {}) {
     getTarget(path)?.focus();
     options.onCancel?.({ path });
   }
+  function setSlide(index) {
+    if (!Number.isInteger(index) || !editor.document.slides?.[index])
+      throw new RangeError("Slide index is out of range.");
+    if (index === slideIndex) {
+      if (!active) renderFor();
+      return true;
+    }
+    if (!commit()) return false;
+    richToolbar.hide();
+    imageCropper?.cancel();
+    slideIndex = index;
+    selectedPath = null;
+    imageCropper?.sync(null);
+    renderFor();
+    return true;
+  }
+  // RR-25: select the content at `path`, or the closest enclosing content that is a canvas target (a list item, a table
+  // cell or a quote part selects the list, table or quote it belongs to), after showing the slide the path is on. Returns
+  // the path that was selected, or null when the path is not on a slide that is drawn yet (fonts still loading) or no
+  // enclosing content is selectable (speaker notes, deck fields). It never moves keyboard focus unless `focus` is true.
+  function reveal(path, { focus = false } = {}) {
+    if (disposed || typeof path !== "string") return null;
+    const slide = /^slides\.(\d+)(?:\.|$)/.exec(path);
+    if (slide && Number(slide[1]) !== slideIndex && !setSlide(Number(slide[1]))) return null;
+    if (active && !commit()) return null;
+    const segments = path.split(".");
+    for (let length = segments.length; length >= 3; length--) {
+      const candidate = segments.slice(0, length).join(".");
+      const node = getTarget(candidate);
+      if (!node) continue;
+      choose(candidate);
+      node.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+      if (focus) node.focus?.({ preventScroll: true });
+      return candidate;
+    }
+    return null;
+  }
   const unsubscribe = editor.subscribe(() => {
     if (committing || layoutHandles.editingPath) return;
     if (active) {
@@ -925,6 +986,9 @@ export function createCanvasEditor(container, options = {}) {
     active?.rich?.update();
   });
   resize.observe(root);
+  // The on-screen keyboard shrinks the visual viewport; keep the field being typed in visible above it.
+  const keepEditVisible = () => { if (active?.input && coarse?.matches) active.input.scrollIntoView?.({ block: "center", inline: "nearest" }); };
+  win.visualViewport?.addEventListener("resize", keepEditVisible);
   root.addEventListener("pointerdown", () => { pointerTaken = null; }, true);
   root.addEventListener("keydown", (event) => {
     if (
@@ -961,6 +1025,13 @@ export function createCanvasEditor(container, options = {}) {
       return active?.path ?? layoutHandles.editingPath ?? blockControls.editingPath ?? null;
     },
     get layoutEditing() { return layoutHandles.enabled; },
+    /** True while the crop layer is open. */
+    get cropping() { return !!imageCropper?.isOpen; },
+    /** Open the crop layer for the picture at `path` (an image block, a slide's `image`, a slide image). `tool: "focus"` starts with the focal point. */
+    cropImage(path, cropOptions) {
+      if (!imageCropper) return Promise.resolve(false);
+      return imageCropper.open(path, cropOptions);
+    },
     setLayoutEditing(enabled) {
       if (!commit()) return false;
       return layoutHandles.setEnabled(enabled);
@@ -981,24 +1052,12 @@ export function createCanvasEditor(container, options = {}) {
     commit,
     cancel,
     render,
-    setSlide(index) {
-      if (!Number.isInteger(index) || !editor.document.slides?.[index])
-        throw new RangeError("Slide index is out of range.");
-      if (index === slideIndex) {
-        if (!active) renderFor();
-        return true;
-      }
-      if (!commit()) return false;
-      richToolbar.hide();
-      slideIndex = index;
-      selectedPath = null;
-      renderFor();
-      return true;
-    },
+    setSlide,
+    reveal,
     setRenderOptions(next) {
       if (!commit()) return false;
       richToolbar.hide();
-      renderOptions = next;
+      renderOptions = { variables: false, ...next };
       renderFor();
       return true;
     },
@@ -1006,11 +1065,13 @@ export function createCanvasEditor(container, options = {}) {
       disposed = true;
       stopDrag?.();
       active?.rich?.destroy();
+      imageCropper?.destroy();
       richToolbar.destroy();
       layoutHandles.destroy();
       blockControls.destroy();
       unsubscribe();
       resize.disconnect();
+      win.visualViewport?.removeEventListener("resize", keepEditVisible);
       if (frame) win.cancelAnimationFrame(frame);
       root.remove();
       options.propertiesContainer?.replaceChildren();

package/dist/chart-data.d.ts

@@ -0,0 +1,32 @@
+import type { EditorSession } from "./index.js";
+import type { GridAddress, GridCellEdit, GridChange, GridOptions, GridSortOptions, PreparedGridChange } from "./grid-model.js";
+
+/** Set chart cells from text or typed values: names and categories are text, series cells are numbers read in the number format (blank is a gap, never 0). One patch; every problem is in `error.issues`. */
+export declare function prepareChartCells(document: unknown, chartPath: string, edits: GridCellEdit[], options?: GridOptions): PreparedGridChange;
+export declare function setChartCells(editor: EditorSession, chartPath: string, edits: GridCellEdit[], options?: GridOptions): GridChange;
+export declare function prepareChartPaste(document: unknown, chartPath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): PreparedGridChange;
+export declare function pasteChartText(editor: EditorSession, chartPath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): GridChange;
+/** Insert `count` empty rows (categories) so the first is row `at`. */
+export declare function prepareChartInsertRows(document: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function insertChartRows(editor: EditorSession, chartPath: string, at: number, count?: number, options?: GridOptions): GridChange;
+export declare function prepareChartDeleteRows(document: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function deleteChartRows(editor: EditorSession, chartPath: string, indices: number[], options?: GridOptions): GridChange;
+export declare function prepareChartMoveRows(document: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function moveChartRows(editor: EditorSession, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
+/** Insert `count` unnamed series so the first is column `at`. */
+export declare function prepareChartInsertColumns(document: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function insertChartColumns(editor: EditorSession, chartPath: string, at: number, count?: number, options?: GridOptions): GridChange;
+export declare function prepareChartDeleteColumns(document: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function deleteChartColumns(editor: EditorSession, chartPath: string, indices: number[], options?: GridOptions): GridChange;
+export declare function prepareChartMoveColumns(document: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function moveChartColumns(editor: EditorSession, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
+/** Sort the rows (categories) by a column, stably and by type. */
+export declare function prepareChartSort(document: unknown, chartPath: string, column: number, options?: GridSortOptions): PreparedGridChange;
+export declare function sortChartRows(editor: EditorSession, chartPath: string, column: number, options?: GridSortOptions): GridChange;
+/** Swap categories and series: the first column's values become the series names and each series becomes a row. Numeric categories become text. */
+export declare function prepareChartTranspose(document: unknown, chartPath: string): PreparedGridChange;
+export declare function transposeChart(editor: EditorSession, chartPath: string, options?: { meta?: Record<string, unknown> }): GridChange;
+/** Rename a series: the label of data column `column` (1 or more). */
+export declare function renameChartSeries(editor: EditorSession, chartPath: string, column: number, name: string, options?: { meta?: Record<string, unknown> }): GridChange;
+/** Rename a category: the first-column label of body row `row`. An empty name leaves it blank. */
+export declare function renameChartCategory(editor: EditorSession, chartPath: string, row: number, name: string, options?: { meta?: Record<string, unknown> }): GridChange;