@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/content-actions.js

@@ -1,8 +1,8 @@
-// Content actions (RR-26): list levels, grouping, regions, images between content and design, and slide
+// Content actions (RR-26): list levels, grouping, regions, images between content and design (background or watermark), and slide
 // split and merge, as editor transactions. The pure transforms live in core (`@openpresentation/opf/convert`);
 // each action here finds its target in the document, calls the transform, turns the result into a guarded patch
 // (`test` of what was read, then `replace`, or per-slide `remove` and `add`), validates the document and, in the
-// apply form, applies it as ONE undoable step. Every prepare function returns `{ document, patches, changed,
+// apply form, applies it as ONE undoable step. Every prepare function returns `{ presentation, patches, changed,
 // lossless, loss, path }` without touching a session; a refusal throws `content-action-refused`.
 import {
   OPFConversionError,
@@ -19,9 +19,10 @@ import {
   unwrapGroup,
   wrapBlocks,
 } from "@openpresentation/opf/convert";
-import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { readBlockContent } from "./block-convert.js";
 import { checkedDocument, fail } from "./edit-helpers.js";
+import { checkFormat } from "./checks.js";
 
 const refuse = (message, details) => fail("content-action-refused", message, details);
 
@@ -39,14 +40,14 @@ function requireEditor(editor) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
 }
 
-function slideParts(document, path, what) {
+function slideParts(presentation, path, what) {
   let parts;
   try {
     parts = splitOpfPath(path);
   } catch {
     parts = undefined;
   }
-  if (!parts || parts[0] !== "slides" || !/^(0|[1-9][0-9]*)$/.test(parts[1] ?? "") || !document?.slides?.[Number(parts[1])]) throw refuse(`Choose ${what} on a slide.`, { path });
+  if (!parts || parts[0] !== "slides" || !/^(0|[1-9][0-9]*)$/.test(parts[1] ?? "") || !presentation?.slides?.[Number(parts[1])]) throw refuse(`Choose ${what} on a slide.`, { path });
   return { slideIndex: Number(parts[1]), relative: parts.slice(2), parts };
 }
 
@@ -54,27 +55,27 @@ const asNumbers = (path) => path.map((part) => (/^(0|[1-9][0-9]*)$/.test(String(
 const toDocumentPath = (slideIndex, relative) => ["slides", String(slideIndex), ...(relative ?? []).map(String)].join(".");
 
 /** Replace one value (a slide, a block, a list) as `test` + `replace`, validated like every other edit. */
-function replacePatches(document, parts, next) {
+function replacePatches(presentation, parts, next) {
   const pointer = opfPathToJsonPointer(parts);
   return [
-    { op: "test", path: pointer, value: structuredClone(getValueAtPath(document, parts)) },
+    { op: "test", path: pointer, value: structuredClone(getValueAtPath(presentation, parts)) },
     { op: "replace", path: pointer, value: next },
   ];
 }
 // `validate: false` skips the whole-document check, for a dry run that only needs the loss report (core has already
 // validated the changed slide); applying always validates.
-function finish(document, patches, extra, validate = true) {
-  if (!validate) return { document: applyJsonPatch(document, patches), patches, ...extra };
-  const before = validateOpfDocument(document);
-  return { document: checkedDocument(document, patches, before), patches, ...extra };
+function finish(presentation, patches, extra, validate = true) {
+  if (!validate) return { presentation: applyJsonPatch(presentation, patches), patches, ...extra };
+  const before = checkFormat(presentation);
+  return { presentation: checkedDocument(presentation, patches, before), patches, ...extra };
 }
 function apply(editor, prepared, meta, source) {
-  if (!prepared.changed) return { ...prepared, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  if (!prepared.changed) return { ...prepared, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   const change = editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? source, path: prepared.path });
   const extra = Object.fromEntries(["levels", "range", "slideCount", "pages"].filter((key) => prepared[key] !== undefined).map((key) => [key, prepared[key]]));
   return { ...change, changed: true, lossless: prepared.lossless, loss: prepared.loss, path: prepared.path, ...extra };
 }
-const unchanged = (document, path, reason) => ({ document: structuredClone(document), patches: [], path, changed: false, lossless: true, loss: [], ...(reason ? { reason } : {}) });
+const unchanged = (presentation, path, reason) => ({ presentation: structuredClone(presentation), patches: [], path, changed: false, lossless: true, loss: [], ...(reason ? { reason } : {}) });
 
 // --- list levels -------------------------------------------------------------------------------
 
@@ -91,75 +92,75 @@ export function listItemIndexForSelection(selectedPath, blockPath) {
  * item cannot be nested, and items under a moved item move with it (`options.withChildren`, default true).
  * `changed` is false, with a `reason`, when nothing can move.
  */
-export function prepareListShift(document, blockPath, indices, delta, options = {}) {
-  const found = readBlockContent(document, blockPath);
+export function prepareListShift(presentation, blockPath, indices, delta, options = {}) {
+  const found = readBlockContent(presentation, blockPath);
   if (!found || found.kind !== "list") throw refuse("Choose a list block.", { path: blockPath });
   const result = core(() => shiftListLevels(found.owner, indices, delta, options));
   const path = found.path.join(".");
-  if (!result.changed) return unchanged(document, path, result.reason);
-  return finish(document, replacePatches(document, found.path, result.payload), { path, changed: true, lossless: result.lossless, loss: result.loss, levels: result.levels }, options.validate !== false);
+  if (!result.changed) return unchanged(presentation, path, result.reason);
+  return finish(presentation, replacePatches(presentation, found.path, result.payload), { path, changed: true, lossless: result.lossless, loss: result.loss, levels: result.levels }, options.validate !== false);
 }
 /** Nest or un-nest list items as one undoable step. Returns the session change plus `changed`, `reason`, `levels`, `lossless` and `loss`. */
 export function shiftListItems(editor, blockPath, indices, delta, options = {}, meta = {}) {
   requireEditor(editor);
-  return apply(editor, prepareListShift(editor.document, blockPath, indices, delta, options), meta, "list-level");
+  return apply(editor, prepareListShift(editor.presentation, blockPath, indices, delta, options), meta, "list-level");
 }
 
 // --- structure inside one slide ----------------------------------------------------------------
 
 /** One slide-level transform as a guarded replace of that slide. */
-function slideAction(document, slideIndex, transform, targetPath, validate = true) {
-  const slide = document.slides[slideIndex];
+function slideAction(presentation, slideIndex, transform, targetPath, validate = true) {
+  const slide = presentation.slides[slideIndex];
   const result = core(() => transform(slide));
   const path = result.path ? toDocumentPath(slideIndex, result.path) : (targetPath ?? `slides.${slideIndex}`);
-  if (!result.changed) return unchanged(document, path);
-  const patches = replacePatches(document, ["slides", String(slideIndex)], result.slide);
-  return finish(document, patches, { path, changed: true, lossless: result.lossless, loss: result.loss }, validate);
+  if (!result.changed) return unchanged(presentation, path);
+  const patches = replacePatches(presentation, ["slides", String(slideIndex)], result.slide);
+  return finish(presentation, patches, { path, changed: true, lossless: result.lossless, loss: result.loss }, validate);
 }
 
 /** Wrap the blocks at `indices` of the container at `containerPath` (a slide `slides.0`, a group or a region group) in a new group. */
-export function prepareGroupBlocks(document, containerPath, indices, options = {}) {
-  const { slideIndex, relative } = slideParts(document, containerPath, "a container");
-  return slideAction(document, slideIndex, (slide) => wrapBlocks(slide, indices, { container: asNumbers(relative), ...(options.composition ? { composition: options.composition } : {}) }), undefined, options.validate !== false);
+export function prepareGroupBlocks(presentation, containerPath, indices, options = {}) {
+  const { slideIndex, relative } = slideParts(presentation, containerPath, "a container");
+  return slideAction(presentation, slideIndex, (slide) => wrapBlocks(slide, indices, { container: asNumbers(relative), ...(options.composition ? { composition: options.composition } : {}) }), undefined, options.validate !== false);
 }
 /** Replace the group at `groupPath` by its blocks. What the group carried (composition, id) is reported in `loss`. */
-export function prepareUngroupBlock(document, groupPath, options = {}) {
-  const { slideIndex, relative } = slideParts(document, groupPath, "a group");
-  return slideAction(document, slideIndex, (slide) => unwrapGroup(slide, asNumbers(relative)), undefined, options.validate !== false);
+export function prepareUngroupBlock(presentation, groupPath, options = {}) {
+  const { slideIndex, relative } = slideParts(presentation, groupPath, "a group");
+  return slideAction(presentation, slideIndex, (slide) => unwrapGroup(slide, asNumbers(relative)), undefined, options.validate !== false);
 }
 /** Place every block of a slide in its own named region: `regions[i]` is block i's region (`left`, `right`, `top:left`, ...). */
-export function prepareBlocksToRegions(document, slideIndex, regions, options = {}) {
-  slideParts(document, `slides.${slideIndex}`, "a slide");
-  return slideAction(document, slideIndex, (slide) => blocksToRegions(slide, regions), undefined, options.validate !== false);
+export function prepareBlocksToRegions(presentation, slideIndex, regions, options = {}) {
+  slideParts(presentation, `slides.${slideIndex}`, "a slide");
+  return slideAction(presentation, slideIndex, (slide) => blocksToRegions(slide, regions), undefined, options.validate !== false);
 }
 /** Turn the named regions of a slide into ordinary blocks in reading order. The regions' placement is reported in `loss`. */
-export function prepareRegionsToBlocks(document, slideIndex, options = {}) {
-  slideParts(document, `slides.${slideIndex}`, "a slide");
-  return slideAction(document, slideIndex, (slide) => regionsToBlocks(slide), undefined, options.validate !== false);
+export function prepareRegionsToBlocks(presentation, slideIndex, options = {}) {
+  slideParts(presentation, `slides.${slideIndex}`, "a slide");
+  return slideAction(presentation, slideIndex, (slide) => regionsToBlocks(slide), undefined, options.validate !== false);
 }
 /** Move the content of region `from` to region `to`, or swap them when `to` is taken and `options.swap` is true. */
-export function prepareMoveRegion(document, slideIndex, from, to, options = {}) {
-  slideParts(document, `slides.${slideIndex}`, "a slide");
-  return slideAction(document, slideIndex, (slide) => moveRegion(slide, from, to, options), undefined, options.validate !== false);
+export function prepareMoveRegion(presentation, slideIndex, from, to, options = {}) {
+  slideParts(presentation, `slides.${slideIndex}`, "a slide");
+  return slideAction(presentation, slideIndex, (slide) => moveRegion(slide, from, to, options), undefined, options.validate !== false);
 }
-/** Move the image block at `blockPath` into the slide's design as `slideImage`, `background` or `watermark`. */
-export function prepareImageToDesign(document, blockPath, target, options = {}) {
-  const { slideIndex, relative } = slideParts(document, blockPath, "an image block");
-  return slideAction(document, slideIndex, (slide) => promoteImage(slide, asNumbers(relative), target, options), `slides.${slideIndex}`, options.validate !== false);
+/** Move the image block at `blockPath` into the slide's design as its `background` or `watermark` (core's `promoteImage`). */
+export function prepareImageToDesign(presentation, blockPath, target, options = {}) {
+  const { slideIndex, relative } = slideParts(presentation, blockPath, "an image block");
+  return slideAction(presentation, slideIndex, (slide) => promoteImage(slide, asNumbers(relative), target, options), `slides.${slideIndex}`, options.validate !== false);
 }
-/** Move a slide's own `slideImage`, `background` image or `watermark` back into its content as an image block. */
-export function prepareImageToContent(document, slideIndex, source, options = {}) {
-  slideParts(document, `slides.${slideIndex}`, "a slide");
-  return slideAction(document, slideIndex, (slide) => demoteImage(slide, source, options), undefined, options.validate !== false);
+/** Move a slide's own `background` image or `watermark` back into its content as an image block (core's `demoteImage`). */
+export function prepareImageToContent(presentation, slideIndex, source, options = {}) {
+  slideParts(presentation, `slides.${slideIndex}`, "a slide");
+  return slideAction(presentation, slideIndex, (slide) => demoteImage(slide, source, options), undefined, options.validate !== false);
 }
 
-export const groupBlocks = (editor, containerPath, indices, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareGroupBlocks(editor.document, containerPath, indices, options), meta, "group-blocks"));
-export const ungroupBlock = (editor, groupPath, meta = {}) => (requireEditor(editor), apply(editor, prepareUngroupBlock(editor.document, groupPath), meta, "ungroup-block"));
-export const placeBlocksInRegions = (editor, slideIndex, regions, meta = {}) => (requireEditor(editor), apply(editor, prepareBlocksToRegions(editor.document, slideIndex, regions), meta, "blocks-to-regions"));
-export const regionsAsBlocks = (editor, slideIndex, meta = {}) => (requireEditor(editor), apply(editor, prepareRegionsToBlocks(editor.document, slideIndex), meta, "regions-to-blocks"));
-export const moveSlideRegion = (editor, slideIndex, from, to, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareMoveRegion(editor.document, slideIndex, from, to, options), meta, "move-region"));
-export const moveImageToDesign = (editor, blockPath, target, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToDesign(editor.document, blockPath, target, options), meta, "image-to-design"));
-export const moveImageToContent = (editor, slideIndex, source, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToContent(editor.document, slideIndex, source, options), meta, "image-to-content"));
+export const groupBlocks = (editor, containerPath, indices, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareGroupBlocks(editor.presentation, containerPath, indices, options), meta, "group-blocks"));
+export const ungroupBlock = (editor, groupPath, meta = {}) => (requireEditor(editor), apply(editor, prepareUngroupBlock(editor.presentation, groupPath), meta, "ungroup-block"));
+export const placeBlocksInRegions = (editor, slideIndex, regions, meta = {}) => (requireEditor(editor), apply(editor, prepareBlocksToRegions(editor.presentation, slideIndex, regions), meta, "blocks-to-regions"));
+export const regionsAsBlocks = (editor, slideIndex, meta = {}) => (requireEditor(editor), apply(editor, prepareRegionsToBlocks(editor.presentation, slideIndex), meta, "regions-to-blocks"));
+export const moveSlideRegion = (editor, slideIndex, from, to, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareMoveRegion(editor.presentation, slideIndex, from, to, options), meta, "move-region"));
+export const moveImageToDesign = (editor, blockPath, target, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToDesign(editor.presentation, blockPath, target, options), meta, "image-to-design"));
+export const moveImageToContent = (editor, slideIndex, source, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToContent(editor.presentation, slideIndex, source, options), meta, "image-to-content"));
 
 // --- slides ------------------------------------------------------------------------------------
 
@@ -168,8 +169,8 @@ export const moveImageToContent = (editor, slideIndex, source, options = {}, met
  * replaced slide, a `replace` for each one that changed, `remove` for the surplus old slides and `add` for the
  * surplus new ones, so a split or merge stays one guarded, undoable transaction without rewriting the other slides.
  */
-function slidePatches(document, range, slides) {
-  const old = document.slides.slice(range.start, range.start + range.deleteCount);
+function slidePatches(presentation, range, slides) {
+  const old = presentation.slides.slice(range.start, range.start + range.deleteCount);
   const patches = old.map((slide, offset) => ({ op: "test", path: `/slides/${range.start + offset}`, value: structuredClone(slide) }));
   const common = Math.min(old.length, slides.length);
   for (let offset = 0; offset < common; offset++) if (JSON.stringify(old[offset]) !== JSON.stringify(slides[offset])) patches.push({ op: "replace", path: `/slides/${range.start + offset}`, value: structuredClone(slides[offset]) });
@@ -177,31 +178,31 @@ function slidePatches(document, range, slides) {
   for (let offset = common; offset < slides.length; offset++) patches.push({ op: "add", path: `/slides/${range.start + offset}`, value: structuredClone(slides[offset]) });
   return patches;
 }
-function slidesAction(document, result, extra = {}) {
+function slidesAction(presentation, result, extra = {}) {
   const path = `slides.${result.range.start}`;
-  if (!result.changed) return unchanged(document, path, "Nothing to change.");
-  return finish(document, slidePatches(document, result.range, result.slides), { path, changed: true, lossless: result.lossless, loss: result.loss, range: result.range, slideCount: result.slides.length, ...extra });
+  if (!result.changed) return unchanged(presentation, path, "Nothing to change.");
+  return finish(presentation, slidePatches(presentation, result.range, result.slides), { path, changed: true, lossless: result.lossless, loss: result.loss, range: result.range, slideCount: result.slides.length, ...extra });
 }
 
 /** Split a slide by its blocks (`options.at`: block indexes where a new slide starts, or `options.each`). See core's `splitSlide`. */
-export function prepareSplitSlide(document, slideIndex, options = {}) {
-  return slidesAction(document, core(() => splitSlide(document, slideIndex, options)));
+export function prepareSplitSlide(presentation, slideIndex, options = {}) {
+  return slidesAction(presentation, core(() => splitSlide(presentation, slideIndex, options)));
 }
-/** Split a slide that overflows into pages with the existing pagination (`options`: text measurement, fonts, as for `paginatePresentation`). `pages` maps the new slides back for `prepareUnpaginate`. */
-export function prepareSplitSlideOnOverflow(document, slideIndex, options = {}) {
-  const result = core(() => splitSlideOnOverflowCore(document, slideIndex, options));
-  return slidesAction(document, result, { pages: result.pages });
+/** Split a slide that overflows into pages with the existing pagination (`options`: text measurement, fonts, as for core `paginate`). `pages` maps the new slides back for `prepareUnpaginate`. */
+export function prepareSplitSlideOnOverflow(presentation, slideIndex, options = {}) {
+  const result = core(() => splitSlideOnOverflowCore(presentation, slideIndex, options));
+  return slidesAction(presentation, result, { pages: result.pages });
 }
 /** Merge `count` consecutive slides from `start`. The first slide's id, headings and design win; what is dropped is reported in `loss`. */
-export function prepareMergeSlides(document, start, count = 2) {
-  return slidesAction(document, core(() => mergeSlidesCore(document, start, count)));
+export function prepareMergeSlides(presentation, start, count = 2) {
+  return slidesAction(presentation, core(() => mergeSlidesCore(presentation, start, count)));
 }
-/** Put the continuation slides of a pagination back into one slide each. `pages` is the mapping `splitSlideOnOverflow` or `paginatePresentation` returned. */
-export function prepareUnpaginate(document, pages, options = {}) {
-  return slidesAction(document, core(() => unpaginate(document, pages, options)));
+/** Put the continuation slides of a pagination back into one slide each. `pages` is the mapping `splitSlideOnOverflow` or core `paginate` returned. */
+export function prepareUnpaginate(presentation, pages, options = {}) {
+  return slidesAction(presentation, core(() => unpaginate(presentation, pages, options)));
 }
 
-export const splitSlideByBlocks = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlide(editor.document, slideIndex, options), meta, "split-slide"));
-export const splitSlideOnOverflow = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlideOnOverflow(editor.document, slideIndex, options), meta, "split-slide-overflow"));
-export const mergeSlides = (editor, start, count = 2, meta = {}) => (requireEditor(editor), apply(editor, prepareMergeSlides(editor.document, start, count), meta, "merge-slides"));
-export const unpaginateSlides = (editor, pages, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareUnpaginate(editor.document, pages, options), meta, "unpaginate-slides"));
+export const splitSlideByBlocks = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlide(editor.presentation, slideIndex, options), meta, "split-slide"));
+export const splitSlideOnOverflow = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlideOnOverflow(editor.presentation, slideIndex, options), meta, "split-slide-overflow"));
+export const mergeSlides = (editor, start, count = 2, meta = {}) => (requireEditor(editor), apply(editor, prepareMergeSlides(editor.presentation, start, count), meta, "merge-slides"));
+export const unpaginateSlides = (editor, pages, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareUnpaginate(editor.presentation, pages, options), meta, "unpaginate-slides"));

package/dist/content-controls.js

@@ -36,20 +36,20 @@ export const REGION_LAYOUTS = Object.freeze({
   4: [{ id: "grid", label: "Two by two", regions: ["top:left", "top:right", "bottom:left", "bottom:right"] }],
 });
 
-/** Where an image block can go in the slide's design. The value is `<target>` or `<target>:<position>`. */
+/**
+ * Where an image block can go in the slide's design (OPF 0.15): its background (a full-bleed photo behind the content) or its
+ * watermark. Bleeding an image to one edge beside the content is not a move: it is the block's `placement` (image-options.js).
+ */
 export const IMAGE_DESTINATIONS = Object.freeze([
-  { value: "slideImage:right", label: "Slide image, on the right", target: "slideImage", options: { position: "right" } },
-  { value: "slideImage:left", label: "Slide image, on the left", target: "slideImage", options: { position: "left" } },
-  { value: "slideImage:top", label: "Slide image, along the top", target: "slideImage", options: { position: "top" } },
-  { value: "slideImage:bottom", label: "Slide image, along the bottom", target: "slideImage", options: { position: "bottom" } },
-  { value: "slideImage:background", label: "Slide image, full slide behind the content", target: "slideImage", options: { position: "background" } },
-  { value: "background", label: "Slide background", target: "background", options: {} },
+  { value: "background", label: "Slide background, full slide behind the content", target: "background", options: {} },
   { value: "watermark", label: "Watermark", target: "watermark", options: {} },
 ]);
 
 const REGION_KEY = /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/;
 const regionKeysOfSlide = (slide) => Object.keys(slide).filter((key) => REGION_KEY.test(key));
-const DESIGN_IMAGE_LABELS = { slideImage: "slide image", background: "background image", watermark: "watermark" };
+const DESIGN_IMAGE_LABELS = { background: "background image", watermark: "watermark" };
+// An image block's own framing fields (FA-22) do not stop it being "a block that holds only an image".
+const IMAGE_BLOCK_FIELDS = new Set(["id", "extensions", "type", "fit", "focus", "aspectRatio", "shape", "cornerRadius", "border", "opacity", "recolor", "overlay", "placement"]);
 const messageOf = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
 const lossText = (prepared) => (prepared.loss.length ? `Not carried over: ${prepared.loss.join(", ")}.` : "Nothing is lost.");
 
@@ -104,7 +104,7 @@ export function createContentControls(ctx) {
     const prepare = (delta) => (state) => {
       const item = index(state);
       if (item === undefined) return { changed: false, loss: [], reason: "Select a list item to change its level." };
-      return prepareListShift(editor.document, state.blockPath, [item], delta, { validate: false });
+      return prepareListShift(editor.presentation, state.blockPath, [item], delta, { validate: false });
     };
     const apply = (delta) => () => {
       const state = ctxState.current;
@@ -140,7 +140,7 @@ export function createContentControls(ctx) {
   updaters.push((state) => {
     metrics.wrap.hidden = !state.metricGroupPath;
     if (!state.metricGroupPath) return;
-    const targets = blockConversionTargets(editor.document, state.metricGroupPath);
+    const targets = blockConversionTargets(editor.presentation, state.metricGroupPath);
     metrics.setOptions(
       targets.map((target) => ({
         value: target.kind,
@@ -172,7 +172,7 @@ export function createContentControls(ctx) {
       prepare: (state) => {
         const indices = next(state);
         if (!indices) return { changed: false, loss: [], reason: "There is no block after this one in its container." };
-        return prepareGroupBlocks(editor.document, containerPath(state), indices, { validate: false });
+        return prepareGroupBlocks(editor.presentation, containerPath(state), indices, { validate: false });
       },
       apply: () => {
         const state = ctxState.current;
@@ -190,7 +190,7 @@ export function createContentControls(ctx) {
       prepare: (state) => {
         const path = parentGroup(state);
         if (!path) return { changed: false, loss: [], reason: "This block is not inside a group." };
-        return prepareUngroupBlock(editor.document, path, { validate: false });
+        return prepareUngroupBlock(editor.presentation, path, { validate: false });
       },
       apply: () => ungroupBlock(editor, parentGroup(ctxState.current)),
       selectAfter: (change) => change.path,
@@ -222,7 +222,7 @@ export function createContentControls(ctx) {
         image.setOptions(
           IMAGE_DESTINATIONS.map((entry) => {
             try {
-              const prepared = prepareImageToDesign(editor.document, state.blockPath, entry.target, { ...entry.options, validate: false });
+              const prepared = prepareImageToDesign(editor.presentation, state.blockPath, entry.target, { ...entry.options, validate: false });
               return { value: entry.value, label: `${entry.label}${prepared.loss.length ? ` (loses ${prepared.loss.join(", ")})` : ""}` };
             } catch (error) {
               return { value: entry.value, label: `${entry.label} (unavailable)`, disabled: true, title: messageOf(error) };
@@ -251,21 +251,21 @@ export function createContentControls(ctx) {
     });
     const toBlocks = action("Turn regions into blocks", {
       role: "regions-to-blocks",
-      prepare: () => prepareRegionsToBlocks(editor.document, getSlide(), { validate: false }),
+      prepare: () => prepareRegionsToBlocks(editor.presentation, getSlide(), { validate: false }),
       apply: () => regionsAsBlocks(editor, getSlide()),
       done: "Regions are now blocks, in reading order.",
     });
     const designImages = Object.keys(DESIGN_IMAGE_LABELS).map((source) =>
       action(`Move the ${DESIGN_IMAGE_LABELS[source]} into the content`, {
         role: `back-${source}`,
-        prepare: () => prepareImageToContent(editor.document, getSlide(), source, { validate: false }),
+        prepare: () => prepareImageToContent(editor.presentation, getSlide(), source, { validate: false }),
         apply: () => moveImageToContent(editor, getSlide(), source),
         done: `The ${DESIGN_IMAGE_LABELS[source]} is now an image block.`,
       }),
     );
     slideBox.append(layouts.wrap, toBlocks.wrap, ...designImages.map((entry) => entry.wrap));
     updaters.push((state) => {
-      const slide = editor.document.slides?.[state.slideIndex];
+      const slide = editor.presentation.slides?.[state.slideIndex];
       if (!slide) return;
       const regions = regionKeysOfSlide(slide);
       const count = blockCount(state.slideIndex);
@@ -275,7 +275,7 @@ export function createContentControls(ctx) {
         layouts.setOptions(
           choices.map((choice) => {
             try {
-              const prepared = prepareBlocksToRegions(editor.document, state.slideIndex, choice.regions, { validate: false });
+              const prepared = prepareBlocksToRegions(editor.presentation, state.slideIndex, choice.regions, { validate: false });
               return { value: choice.id, label: `${choice.label}${prepared.loss.length ? ` (loses ${prepared.loss.join(", ")})` : ""}` };
             } catch (error) {
               return { value: choice.id, label: `${choice.label} (unavailable)`, disabled: true, title: messageOf(error) };
@@ -296,7 +296,7 @@ export function createContentControls(ctx) {
 
   /** The number of blocks a slide can place in regions: its `blocks`, or the content fields it holds inline. */
   function blockCount(slideIndex) {
-    const slide = editor.document.slides?.[slideIndex];
+    const slide = editor.presentation.slides?.[slideIndex];
     if (!slide) return 0;
     if (Array.isArray(slide.blocks)) return slide.blocks.length;
     return ["text", "items", "bullets", "image", "video", "chart", "table", "code", "metric", "quote", "timeline"].filter((key) => slide[key] !== undefined).length;
@@ -309,9 +309,9 @@ export function createContentControls(ctx) {
     slideNode: slideBox,
     /** Update every control from the session and the current selection. */
     sync(state) {
-      const slide = editor.document.slides?.[state.slideIndex];
+      const slide = editor.presentation.slides?.[state.slideIndex];
       const imageBlock = state.blockPath ? isImageBlock(editor, state.blockPath) : false;
-      const full = { ...state, imageBlock, metricGroupPath: state.selectedPath ? metricGroupForSelection(editor.document, state.selectedPath) : undefined, slide };
+      const full = { ...state, imageBlock, metricGroupPath: state.selectedPath ? metricGroupForSelection(editor.presentation, state.selectedPath) : undefined, slide };
       ctxState.current = full;
       for (const update of updaters) update(full);
     },
@@ -321,6 +321,6 @@ export function createContentControls(ctx) {
 function isImageBlock(editor, blockPath) {
   const block = editor.get(blockPath);
   if (!block || typeof block !== "object" || Array.isArray(block)) return false;
-  const keys = Object.keys(block).filter((key) => key !== "id" && key !== "extensions" && key !== "type");
+  const keys = Object.keys(block).filter((key) => !IMAGE_BLOCK_FIELDS.has(key));
   return keys.length === 1 && keys[0] === "image";
 }

package/dist/data-grid.js

@@ -33,7 +33,6 @@ import {
   setGridColumnFormat,
   setGridHeader,
   sortGridRows,
-  supportsChartTableData,
   transposeGridData,
 } from "./grid-model.js";
 import { NUMBER_FORMATS, parseDelimited, resolveNumberFormat, toDelimited } from "./grid-text.js";
@@ -456,7 +455,7 @@ export function createDataGrid(container, options = {}) {
   function resolveTarget() {
     const path = getPath();
     if (!path) return undefined;
-    return resolveDataGridTarget(editor.document, path);
+    return resolveDataGridTarget(editor.presentation, path);
   }
 
   function rebuild() {
@@ -486,7 +485,7 @@ export function createDataGrid(container, options = {}) {
       grid = undefined;
       return;
     }
-    grid = describeDataGrid(editor.document, next.path, opts());
+    grid = describeDataGrid(editor.presentation, next.path, opts());
     buildTable();
     buildDatasetRow();
     buildMapping();
@@ -505,7 +504,7 @@ export function createDataGrid(container, options = {}) {
   function dataSignature() {
     if (!target || target.editable === false) return "";
     try {
-      return JSON.stringify([target.path, editor.get(target.path), target.dataset ? editor.document.datasets?.[target.dataset.id] : undefined, numberFormat]);
+      return JSON.stringify([target.path, editor.get(target.path), target.dataset ? editor.presentation.datasets?.[target.dataset.id] : undefined, numberFormat]);
     } catch {
       return "";
     }
@@ -551,7 +550,7 @@ export function createDataGrid(container, options = {}) {
   // moves the selection before the field's change event fires, and the format typed for one column must not land on the next.
   let formatBound = 0;
   function updateFormatRow() {
-    const visible = Boolean(grid?.hasHeader) && target?.editable !== false && supportsChartTableData;
+    const visible = Boolean(grid?.hasHeader) && target?.editable !== false;
     formatRow.hidden = !visible;
     if (!visible) return;
     if (doc.activeElement !== formatInput) {
@@ -613,11 +612,11 @@ export function createDataGrid(container, options = {}) {
 
   function buildMapping() {
     mappingBody.replaceChildren();
-    mappingBox.hidden = !grid || target?.kind !== "chart" || !supportsChartTableData;
+    mappingBox.hidden = !grid || target?.kind !== "chart";
     if (mappingBox.hidden) return;
     let view;
     try {
-      view = describeChartMapping(editor.document, target.path);
+      view = describeChartMapping(editor.presentation, target.path);
     } catch {
       mappingBox.hidden = true;
       return;
@@ -694,7 +693,7 @@ export function createDataGrid(container, options = {}) {
   }
 
   function checkLive(area, u, c) {
-    const issues = gridCellIssues(editor.document, target.path, [{ ...addr(u, c), text: area.value }], opts());
+    const issues = gridCellIssues(editor.presentation, target.path, [{ ...addr(u, c), text: area.value }], opts());
     if (issues.length) {
       area.setAttribute("aria-invalid", "true");
       complain(issues[0].message);

package/dist/data.d.ts

@@ -1,5 +1,5 @@
-export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";
-export type {TabularData, DataImportOptions, DataContentOptions} from "@openpresentation/opf/data";
+export {parseTabularData, importData, OPFDataImportError} from "@openpresentation/opf/data";
+export type {TabularData, DataImportOptions, ImportDataOptions} from "@openpresentation/opf/data";
 import type { JsonPatchOperation } from "./index.js";
 
 /** The id pattern of a top-level dataset (the assets id pattern). */
@@ -19,5 +19,5 @@ export interface DatasetImport {
   /** True when a dataset of that id existed and its columns and rows were replaced. */
   replaced: boolean;
 }
-/** Store imported data (the result of `createDataContent`) as a shared dataset, as `opf import-data --dataset <id>` does. Throws `dataset-id-invalid`. */
-export declare function prepareDatasetImport(document: unknown, content: { table: unknown } | { chart: { type: string; data: unknown } }, options: DatasetImportOptions): DatasetImport;
+/** Store imported data (the result of `importData`) as a shared dataset, as `opf import-data --dataset <id>` does. Throws `dataset-id-invalid`. */
+export declare function prepareDatasetImport(presentation: unknown, content: { table: unknown } | { chart: { type: string; data: unknown } }, options: DatasetImportOptions): DatasetImport;

package/dist/data.js

@@ -1,4 +1,4 @@
-export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";
+export {parseTabularData, importData, OPFDataImportError} from "@openpresentation/opf/data";
 import { opfPathToJsonPointer } from "./index.js";
 import { fail } from "./edit-helpers.js";
 
@@ -8,19 +8,19 @@ export const DATASET_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 
 /**
- * Store imported data as a shared dataset (RR-54), as `opf import-data --dataset <id>` does. `content` is what `createDataContent` returns
+ * Store imported data as a shared dataset (RR-54), as `opf import-data --dataset <id>` does. `content` is what `importData` returns
  * (`{ table }` or `{ chart: { type, data } }`). Returns `{ id, content, patches, replaced }`: `content` is the same table or chart holding
  * `{ dataset: id }` instead of the rows, and `patches` write `datasets.<id>` (the imported columns and rows replace those of an existing
  * dataset of that id, which keeps its title, description and source; `source` is merged into its `source`). Apply `patches` and the patch that
  * places `content` in one `applyPatch` call so the import is one undoable edit. Throws `dataset-id-invalid`.
  */
-export function prepareDatasetImport(document, content, options = {}) {
+export function prepareDatasetImport(presentation, content, options = {}) {
   const id = options.id;
   if (typeof id !== "string" || !DATASET_ID_PATTERN.test(id)) throw fail("dataset-id-invalid", 'A dataset id starts with a letter or digit and holds letters, digits, ".", "_" or "-".', { id });
   const isTable = isObject(content) && isObject(content.table);
-  if (!isTable && !(isObject(content) && isObject(content.chart) && isObject(content.chart.data))) throw fail("dataset-content-invalid", "Give the table or chart that createDataContent returned.", {});
+  if (!isTable && !(isObject(content) && isObject(content.chart) && isObject(content.chart.data))) throw fail("dataset-content-invalid", "Give the table or chart that importData returned.", {});
   const data = isTable ? content.table : content.chart.data;
-  const datasets = isObject(document) && isObject(document.datasets) ? document.datasets : undefined;
+  const datasets = isObject(presentation) && isObject(presentation.datasets) ? presentation.datasets : undefined;
   const previous = datasets && Object.hasOwn(datasets, id) && isObject(datasets[id]) ? datasets[id] : undefined;
   const origin = isObject(options.source) && typeof options.source.src === "string" ? options.source : undefined;
   const entry = {

package/dist/dataset-refs.d.ts

@@ -12,6 +12,6 @@ export interface DatasetItem {
 /** The dataset reference test (core's `isDatasetRef`). */
 export declare function isDatasetRef(value: unknown): boolean;
 /** Visit every chart and table that references a dataset (slides, nested blocks and promoted regions). */
-export declare function walkDatasetItems(document: unknown, visit: (entry: DatasetItem) => void): void;
+export declare function walkDatasetItems(presentation: unknown, visit: (entry: DatasetItem) => void): void;
 /** The charts and tables that use dataset `id`, in document order. */
-export declare function datasetUsage(document: unknown, id: string): Array<{ kind: "chart" | "table"; path: string; parts: string[] }>;
+export declare function datasetUsage(presentation: unknown, id: string): Array<{ kind: "chart" | "table"; path: string; parts: string[] }>;

package/dist/dataset-refs.js

@@ -14,8 +14,8 @@ export const isDatasetRef = (value) => isObject(value) && typeof value.dataset =
  * `item` is the chart or table object, `parts` its path, and `ref` the object that holds `dataset` and `fields`
  * (`chart.data` for a chart, the table itself for a table) at `refParts`.
  */
-export function walkDatasetItems(document, visit) {
-  if (!isObject(document) || !Array.isArray(document.slides)) return;
+export function walkDatasetItems(presentation, visit) {
+  if (!isObject(presentation) || !Array.isArray(presentation.slides)) return;
   const walk = (payload, base, depth, ancestors) => {
     if (isObject(payload.chart) && isDatasetRef(payload.chart.data))
       visit({ kind: "chart", id: payload.chart.data.dataset, parts: [...base, "chart"], item: payload.chart, refParts: [...base, "chart", "data"], ref: payload.chart.data });
@@ -27,7 +27,7 @@ export function walkDatasetItems(document, visit) {
       if (isObject(block)) walk(block, [...base, "blocks", String(index)], depth + 1, nested);
     });
   };
-  document.slides.forEach((slide, index) => {
+  presentation.slides.forEach((slide, index) => {
     if (!isObject(slide)) return;
     const base = ["slides", String(index)];
     walk(slide, base, 0, []);
@@ -36,9 +36,9 @@ export function walkDatasetItems(document, visit) {
 }
 
 /** The charts and tables that use dataset `id`: `[{ kind, path, parts }]` in document order. */
-export function datasetUsage(document, id) {
+export function datasetUsage(presentation, id) {
   const items = [];
-  walkDatasetItems(document, (entry) => {
+  walkDatasetItems(presentation, (entry) => {
     if (entry.id === id) items.push({ kind: entry.kind, path: entry.parts.join("."), parts: entry.parts });
   });
   return items;

package/dist/design-controls.d.ts

@@ -1,7 +1,13 @@
+import type { Catalog } from "@openpresentation/opf";
 import type { EditorSession } from "./index.js";
+import type { SwitchVocabularies } from "./switches.js";
 
-export type DesignControlSection = "look" | "background" | "slide-image" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "table" | "slide-content";
-/** Every section, in panel order. `selection` and `table` follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the current slide. */
+export type DesignControlSection = "look" | "background" | "header-footer" | "brand" | "layout-options" | "info" | "selection" | "image" | "table" | "slide-content" | "catalog";
+/**
+ * Every section, in panel order. `selection`, `image` (the selected image block's fit, focus, treatments and placement) and `table`
+ * follow the host's current selection; `slide-content` (RR-26: blocks and regions, images between content and design) follows the
+ * current slide; `catalog` lists the catalog reference findings and runs the explicit "Update from catalog".
+ */
 export declare const DESIGN_CONTROL_SECTIONS: readonly DesignControlSection[];
 
 export interface DesignControlsOptions {
@@ -14,9 +20,10 @@ export interface DesignControlsOptions {
   sections?: readonly DesignControlSection[];
   /** Initial "Applies to" choice. */
   scope?: "deck" | "slide";
-  /** Caller-loaded catalog records by kind (layouts, font schemes, themes, ...) for options the bundled catalogs do not have. */
-  catalogs?: Record<string, unknown>;
-  catalogSources?: Record<string, unknown>;
+  /** Host catalogs for the pickers, merged after the session's registered ones. */
+  catalogs?: readonly Catalog[];
+  /** Display metadata for the engine vocabularies (languages, chart types, social platforms): `catalogDisplay` from `@openpresentation/opf/catalog`. */
+  vocabularies?: SwitchVocabularies;
   /** Called after every committed change (never for a refused one). */
   onChange?: (change: unknown) => void;
   /** Called after a content conversion or replacement with the path to keep selected (the block, or the inline payload field), since the old selection path may no longer exist. */