@openpresentation/opf-editor 0.12.1 → 0.14.2

package/dist/block-convert.js

@@ -5,9 +5,10 @@
 // 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 { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { listBlockContainers } from "./blocks.js";
 import { fail } from "./edit-helpers.js";
+import { firstErrorMessage, errorFindings, checkFormat } from "./checks.js";
 
 /** Every content kind a block can hold, with its display label. */
 export const BLOCK_KIND_LABELS = CONTENT_KIND_LABELS;
@@ -32,7 +33,7 @@ function convertOwner(owner, kind, options) {
  * 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) {
+export function readBlockContent(presentation, path) {
   let parts;
   try {
     parts = splitOpfPath(path);
@@ -41,7 +42,7 @@ export function readBlockContent(document, path) {
   }
   const pointer = opfPathToJsonPointer(parts);
   const explicit = parts.at(-2) === "blocks" && /^(0|[1-9][0-9]*)$/.test(parts.at(-1) ?? "");
-  const owner = getValueAtPath(document, parts);
+  const owner = getValueAtPath(presentation, 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.
@@ -49,7 +50,7 @@ export function readBlockContent(document, path) {
     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);
+    const implicit = listBlockContainers(presentation, { includeImplicit: true }).find((entry) => entry.path === pointer && entry.implicit);
     if (!implicit || implicit.count !== 1) return undefined;
   }
   const info = readContent(owner);
@@ -58,7 +59,7 @@ export function readBlockContent(document, path) {
 }
 
 /** 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) {
+export function blockPathForSelection(presentation, selectedPath) {
   let parts;
   try {
     parts = splitOpfPath(selectedPath);
@@ -68,7 +69,7 @@ export function blockPathForSelection(document, selectedPath) {
   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);
+    const found = readBlockContent(presentation, 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(".");
   }
@@ -79,7 +80,7 @@ export function blockPathForSelection(document, selectedPath) {
  * 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) {
+export function metricGroupForSelection(presentation, selectedPath) {
   let parts;
   try {
     parts = splitOpfPath(selectedPath);
@@ -89,7 +90,7 @@ export function metricGroupForSelection(document, selectedPath) {
   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);
+    const found = readBlockContent(presentation, candidate);
     if (found?.kind === "group") return candidate.join(".");
   }
   return undefined;
@@ -101,10 +102,10 @@ export function metricGroupForSelection(document, selectedPath) {
  * 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);
+export function blockConversionTargets(presentation, path, options = {}) {
+  const found = readBlockContent(presentation, path);
   // RR-54: a table that shows a shared dataset needs the document's datasets to convert to anything but a chart.
-  return found ? contentConversionTargets(found.owner, { document, ...options }) : [];
+  return found ? contentConversionTargets(found.owner, { presentation: presentation, ...options }) : [];
 }
 
 /**
@@ -112,21 +113,21 @@ export function blockConversionTargets(document, path, options = {}) {
  * 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);
+export function prepareBlockConversion(presentation, path, kind, options = {}) {
+  const found = readBlockContent(presentation, path);
   if (!found) throw refuse(CHOOSE, { path });
   const pointer = opfPathToJsonPointer(found.path);
   const from = found.kind;
-  const result = convertOwner(found.owner, kind, { document, ...options });
-  if (!result.changed) return { document: structuredClone(document), patches: [], path: found.path.join("."), changed: false, lossless: true, loss: [], from, to: kind };
+  const result = convertOwner(found.owner, kind, { presentation: presentation, ...options });
+  if (!result.changed) return { presentation: structuredClone(presentation), 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 };
+  const next = applyJsonPatch(presentation, patches);
+  const validation = checkFormat(next);
+  if (!validation.valid) throw fail("invalid-opf-edit", firstErrorMessage(validation, "The converted block is not valid OPF."), { issues: errorFindings(validation), patches });
+  return { presentation: next, patches, path: found.path.join("."), changed: true, lossless: result.lossless, loss: result.loss, from, to: kind };
 }
 
 /**
@@ -135,9 +136,9 @@ export function prepareBlockConversion(document, path, kind, options = {}) {
  */
 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 prepared = prepareBlockConversion(editor.presentation, 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 };
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, 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/blocks.d.ts

@@ -1,15 +1,15 @@
 import type {JsonPatchOperation} from './index.js';
 /** Move a complete block; toIndex is the insertion position before removal. */
-export declare function prepareBlockMove(document:unknown,fromPath:string,toContainerPath:string,toIndex:number):{
- document:unknown;patches:JsonPatchOperation[];path:string;changed:boolean;
+export declare function prepareBlockMove(presentation:unknown,fromPath:string,toContainerPath:string,toIndex:number):{
+ presentation:unknown;patches:JsonPatchOperation[];path:string;changed:boolean;
 };
-export declare function listBlockContainers(document:unknown,options?:{slideIndex?:number;includeImplicit?:boolean}):{path:string;label:string;count:number;implicit?:boolean}[];
+export declare function listBlockContainers(presentation:unknown,options?:{slideIndex?:number;includeImplicit?:boolean}):{path:string;label:string;count:number;implicit?:boolean}[];
 
-export interface PreparedBlockChange { document:unknown;patches:JsonPatchOperation[];path:string;changed:boolean }
-export declare function prepareBlockInsert(document:unknown,containerPath:string,block:unknown,index?:number):PreparedBlockChange;
-export declare function prepareBlockDuplicate(document:unknown,path:string):PreparedBlockChange;
-export declare function prepareBlockRemove(document:unknown,path:string):PreparedBlockChange;
+export interface PreparedBlockChange { presentation:unknown;patches:JsonPatchOperation[];path:string;changed:boolean }
+export declare function prepareBlockInsert(presentation:unknown,containerPath:string,block:unknown,index?:number):PreparedBlockChange;
+export declare function prepareBlockDuplicate(presentation:unknown,path:string):PreparedBlockChange;
+export declare function prepareBlockRemove(presentation:unknown,path:string):PreparedBlockChange;
 /** Replace one complete block (or a slide/region's single content field). Replacement only: the old payload is discarded and nothing is converted between content types. Keeps `id` and `extensions` when the new block sets none. */
-export declare function prepareBlockReplace(document:unknown,path:string,block:unknown):PreparedBlockChange;
+export declare function prepareBlockReplace(presentation:unknown,path:string,block:unknown):PreparedBlockChange;
 export type ContentBlockKind='text'|'list'|'chart'|'table'|'metric'|'quote'|'code'|'timeline'|'group'|'image'|'video';
 export declare function createContentBlock(kind:ContentBlockKind,options?:{source?:string}):Record<string,unknown>;

package/dist/blocks.js

@@ -1,20 +1,21 @@
-import {splitOpfPath,opfPathToJsonPointer,getValueAtPath,applyJsonPatch,validateOpfDocument} from './index.js';
+import { splitOpfPath, opfPathToJsonPointer, getValueAtPath, applyJsonPatch } from './index.js';
+import { firstErrorMessage, checkFormat } from "./checks.js";
 const prefix=(a,b)=>a.length<=b.length&&a.every((part,i)=>part===b[i]);
 
 /** Move one complete block. The insertion index refers to the destination before removal. */
-export function prepareBlockMove(document,fromPath,toContainerPath,toIndex) {
+export function prepareBlockMove(presentation,fromPath,toContainerPath,toIndex) {
   const from=splitOpfPath(fromPath),to=splitOpfPath(toContainerPath);
   if(from.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(from.at(-1)??''))throw new TypeError('Move a complete block using its blocks/index path.');
   const sourceIndex=Number(from.at(-1)),sourceContainer=from.slice(0,-2),sourceArray=from.slice(0,-1);
-  const containers=new Set(listBlockContainers(document).map(item=>item.path));
+  const containers=new Set(listBlockContainers(presentation).map(item=>item.path));
   if(!containers.has(opfPathToJsonPointer(sourceContainer))||!containers.has(opfPathToJsonPointer(to)))throw new TypeError('Choose slide or group block containers.');
-  const source=getValueAtPath(document,sourceArray),destination=getValueAtPath(document,[...to,'blocks']);
+  const source=getValueAtPath(presentation,sourceArray),destination=getValueAtPath(presentation,[...to,'blocks']);
   if(!Array.isArray(source)||sourceIndex>=source.length||!Array.isArray(destination))throw new RangeError('Source and destination must be existing block containers.');
   if(!Number.isInteger(toIndex)||toIndex<0||toIndex>destination.length)throw new RangeError('Destination insertion index is out of range.');
   if(prefix(from,to))throw new Error('A group cannot move into itself or one of its descendants.');
   const same=JSON.stringify(sourceContainer)===JSON.stringify(to);
   const index=same&&toIndex>sourceIndex?toIndex-1:toIndex;
-  if(same&&index===sourceIndex)return {document:structuredClone(document),patches:[],path:opfPathToJsonPointer(from),changed:false};
+  if(same&&index===sourceIndex)return {presentation:structuredClone(presentation),patches:[],path:opfPathToJsonPointer(from),changed:false};
   if(!same&&source.length===1)throw new Error('This move would leave an empty block container. Move the group or add another block first.');
   // Removing a preceding sibling shifts a destination group's address.
   const rebased=[...to];
@@ -22,16 +23,16 @@ export function prepareBlockMove(document,fromPath,toContainerPath,toIndex) {
     rebased[sourceArray.length]=String(Number(to[sourceArray.length])-1);
   const target=[...rebased,'blocks',String(index)];
   const guards=[sourceContainer,...(same?[]:[to])].filter((path,i,all)=>!all.some((other,j)=>j!==i&&other.length<path.length&&prefix(other,path)));
-  const patches=[...guards.map(path=>({op:'test',path:opfPathToJsonPointer(path),value:structuredClone(getValueAtPath(document,path))})),
+  const patches=[...guards.map(path=>({op:'test',path:opfPathToJsonPointer(path),value:structuredClone(getValueAtPath(presentation,path))})),
     {op:'remove',path:opfPathToJsonPointer(from)},
     {op:'add',path:opfPathToJsonPointer(target),value:structuredClone(source[sourceIndex])}];
-  const next=applyJsonPatch(document,patches),validation=validateOpfDocument(next);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The moved document is not valid OPF.');
-  return {document:next,patches,path:opfPathToJsonPointer(target),changed:true};
+  const next=applyJsonPatch(presentation,patches),validation=checkFormat(next);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The moved document is not valid OPF.'));
+  return {presentation:next,patches,path:opfPathToJsonPointer(target),changed:true};
 }
 
 /** Discover actual block containers without interpreting imported content as instructions. */
-export function listBlockContainers(document,{slideIndex,includeImplicit=false}={}) {
+export function listBlockContainers(presentation,{slideIndex,includeImplicit=false}={}) {
   const result=[];
   function visit(value,path,label,depth=0){
     if(!value||typeof value!=='object'||depth>32)return;
@@ -40,7 +41,7 @@ export function listBlockContainers(document,{slideIndex,includeImplicit=false}=
       value.blocks.forEach((block,i)=>visit(block,[...path,'blocks',String(i)],`${label} › Group ${i+1}`,depth+1));
     }
   }
-  (document?.slides??[]).forEach((slide,i)=>{
+  (presentation?.slides??[]).forEach((slide,i)=>{
     if(slideIndex!==undefined&&slideIndex!==i)return;
     const path=['slides',String(i)],label=`Slide ${i+1}`;
     if(includeImplicit&&!Array.isArray(slide.blocks)&&!Object.keys(slide).some(isRegion))result.push({path:opfPathToJsonPointer(path),label,count:contentFields.filter(key=>Object.hasOwn(slide,key)).length,implicit:true});
@@ -53,20 +54,20 @@ export function listBlockContainers(document,{slideIndex,includeImplicit=false}=
 
 const contentFields=['text','items','bullets','image','video','chart','table','code','metric','quote','timeline'];
 const isRegion=key=>/^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/.test(key);
-function preparedChange(document,container,next,path) {
+function preparedChange(presentation,container,next,path) {
   const pointer=opfPathToJsonPointer(container);
-  const patches=[{op:'test',path:pointer,value:structuredClone(getValueAtPath(document,container))},
+  const patches=[{op:'test',path:pointer,value:structuredClone(getValueAtPath(presentation,container))},
     {op:'replace',path:pointer,value:next}];
-  const result=applyJsonPatch(document,patches),validation=validateOpfDocument(result);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The changed document is not valid OPF.');
-  return {document:result,patches,path:opfPathToJsonPointer(path),changed:true};
+  const result=applyJsonPatch(presentation,patches),validation=checkFormat(result);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The changed document is not valid OPF.'));
+  return {presentation:result,patches,path:opfPathToJsonPointer(path),changed:true};
 }
 /** Insert into a slide, existing group or named region. Implicit payloads become blocks. */
-export function prepareBlockInsert(document,containerPath,block,index) {
+export function prepareBlockInsert(presentation,containerPath,block,index) {
   const path=splitOpfPath(containerPath),pointer=opfPathToJsonPointer(path);
-  if(!listBlockContainers(document,{includeImplicit:true}).some(c=>c.path===pointer))throw new TypeError('Choose a slide, group or named region content container.');
+  if(!listBlockContainers(presentation,{includeImplicit:true}).some(c=>c.path===pointer))throw new TypeError('Choose a slide, group or named region content container.');
   if(!block||typeof block!=='object'||Array.isArray(block))throw new TypeError('Insert an OPF content block object.');
-  const next=structuredClone(getValueAtPath(document,path));
+  const next=structuredClone(getValueAtPath(presentation,path));
   if(!Array.isArray(next.blocks)){
     next.blocks=contentFields.filter(key=>Object.hasOwn(next,key)).map(key=>({...(next.type?{type:next.type}:{}),[key]:next[key]}));
     for(const key of [...contentFields,'type'])delete next[key];
@@ -74,12 +75,12 @@ export function prepareBlockInsert(document,containerPath,block,index) {
   const at=index??next.blocks.length;
   if(!Number.isInteger(at)||at<0||at>next.blocks.length)throw new RangeError('Insertion index is out of range.');
   next.blocks.splice(at,0,structuredClone(block));
-  return preparedChange(document,path,next,[...path,'blocks',String(at)]);
+  return preparedChange(presentation,path,next,[...path,'blocks',String(at)]);
 }
-function checkedBlock(document,path) {
+function checkedBlock(presentation,path) {
   const parts=splitOpfPath(path),container=parts.slice(0,-2),index=Number(parts.at(-1));
-  if(parts.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'')||!listBlockContainers(document).some(c=>c.path===opfPathToJsonPointer(container)))throw new TypeError('Choose a complete block using its blocks/index path.');
-  const blocks=getValueAtPath(document,[...container,'blocks']);
+  if(parts.at(-2)!=='blocks'||!/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'')||!listBlockContainers(presentation).some(c=>c.path===opfPathToJsonPointer(container)))throw new TypeError('Choose a complete block using its blocks/index path.');
+  const blocks=getValueAtPath(presentation,[...container,'blocks']);
   if(index>=blocks.length)throw new RangeError('Block does not exist.');
   return {parts,container,index,blocks};
 }
@@ -90,21 +91,21 @@ function checkedBlock(document,path) {
  * region payload (exactly one content field, no `blocks`) is replaced in place, keeping its
  * other slide fields. The test guard fails if the block changed since it was read.
  */
-export function prepareBlockReplace(document,path,block) {
+export function prepareBlockReplace(presentation,path,block) {
   if(!block||typeof block!=='object'||Array.isArray(block))throw new TypeError('Replace with an OPF content block object.');
   const parts=splitOpfPath(path),pointer=opfPathToJsonPointer(parts);
   const explicit=parts.at(-2)==='blocks'&&/^(0|[1-9][0-9]*)$/.test(parts.at(-1)??'');
   let old,next;
   if(explicit){
-    const {index,blocks}=checkedBlock(document,path);
+    const {index,blocks}=checkedBlock(presentation,path);
     old=blocks[index];
     next=structuredClone(block);
     for(const key of ['id','extensions'])if(next[key]===undefined&&old[key]!==undefined)next[key]=structuredClone(old[key]);
   } else {
-    const implicit=listBlockContainers(document,{includeImplicit:true}).find(c=>c.path===pointer&&c.implicit);
+    const implicit=listBlockContainers(presentation,{includeImplicit:true}).find(c=>c.path===pointer&&c.implicit);
     if(!implicit)throw new TypeError('Choose a complete block using its blocks/index path, or a slide or region with one content field.');
     if(implicit.count!==1)throw new TypeError('This slide or region holds several content fields. Choose one block, or insert and remove blocks.');
-    old=getValueAtPath(document,parts);
+    old=getValueAtPath(presentation,parts);
     next=structuredClone(old);
     for(const key of [...contentFields,'type'])delete next[key];
     // The block's own id and extensions would overwrite the slide's; they are not carried over.
@@ -112,28 +113,28 @@ export function prepareBlockReplace(document,path,block) {
     Object.assign(next,payload);
   }
   const patches=[{op:'test',path:pointer,value:structuredClone(old)},{op:'replace',path:pointer,value:next}];
-  const result=applyJsonPatch(document,patches),validation=validateOpfDocument(result);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'The replaced block is not valid OPF.');
-  return {document:result,patches,path:pointer,changed:JSON.stringify(old)!==JSON.stringify(next)};
+  const result=applyJsonPatch(presentation,patches),validation=checkFormat(result);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'The replaced block is not valid OPF.'));
+  return {presentation:result,patches,path:pointer,changed:JSON.stringify(old)!==JSON.stringify(next)};
 }
 /** Duplicate the entire block immediately after itself, preserving formatting and asset references. */
-export function prepareBlockDuplicate(document,path) {
-  const {container,index,blocks}=checkedBlock(document,path);
-  return prepareBlockInsert(document,opfPathToJsonPointer(container),blocks[index],index+1);
+export function prepareBlockDuplicate(presentation,path) {
+  const {container,index,blocks}=checkedBlock(presentation,path);
+  return prepareBlockInsert(presentation,opfPathToJsonPointer(container),blocks[index],index+1);
 }
 /** Delete a block and prune empty ancestor groups; a slide itself is never deleted. */
-export function prepareBlockRemove(document,path) {
-  let {parts,container,index,blocks}=checkedBlock(document,path);
+export function prepareBlockRemove(presentation,path) {
+  let {parts,container,index,blocks}=checkedBlock(presentation,path);
   while(blocks.length===1&&container.length>2){
     if(container.length===3&&isRegion(container[2])){
-      const slidePath=container.slice(0,2),next=structuredClone(getValueAtPath(document,slidePath));delete next[container[2]];
-      return preparedChange(document,slidePath,next,slidePath);
+      const slidePath=container.slice(0,2),next=structuredClone(getValueAtPath(presentation,slidePath));delete next[container[2]];
+      return preparedChange(presentation,slidePath,next,slidePath);
     }
-    ({parts,container,index,blocks}=checkedBlock(document,container));
+    ({parts,container,index,blocks}=checkedBlock(presentation,container));
   }
-  const next=structuredClone(getValueAtPath(document,container));next.blocks.splice(index,1);
+  const next=structuredClone(getValueAtPath(presentation,container));next.blocks.splice(index,1);
   const selection=next.blocks.length?[...container,'blocks',String(Math.min(index,next.blocks.length-1))]:container;
-  return preparedChange(document,container,next,selection);
+  return preparedChange(presentation,container,next,selection);
 }
 
 /** Small, schema-valid starting points. Media requires an explicit source. */

package/dist/canvas-fields.js

@@ -1,11 +1,6 @@
-import {
-  applyJsonPatch,
-  createValuePatch,
-  validateOpfDocument,
-  splitOpfPath,
-  opfPathToJsonPointer,
-} from "./index.js";
+import { applyJsonPatch, createValuePatch, splitOpfPath, opfPathToJsonPointer } from "./index.js";
 import {preserveTextLineEndings} from './text-input.js';
+import { firstErrorMessage, checkFormat } from "./checks.js";
 export {preserveTextLineEndings} from './text-input.js';
 /** Scalar fields and collection paths use JSON Pointer to preserve arbitrary object keys. */
 export function getEditableFields(value, path) {
@@ -52,15 +47,43 @@ export function parseCanvasValue(text, type, original) {
   return type === 'string' && typeof original === 'string' ? preserveTextLineEndings(original,String(text)) : text;
 }
 
-export function createCanvasDraft(document, path, value) {
+export function createCanvasDraft(presentation, path, value) {
   const draft = applyJsonPatch(
-    document,
-    createValuePatch(document, path, value),
+    presentation,
+    createValuePatch(presentation, path, value),
   );
-  const validation = validateOpfDocument(draft);
+  const validation = checkFormat(draft);
   if (!validation.valid)
     throw new Error(
-      validation.errors[0]?.message ?? "This change is not valid OPF.",
+      firstErrorMessage(validation, "This change is not valid OPF."),
     );
   return draft;
 }
+
+/** The progress states of a timeline event (`TimelineEvent.status`). */
+export const TIMELINE_STATUS_CHOICES = Object.freeze(["done", "current", "planned"]);
+/** The fixed choices of a form field, or undefined for free text: an event's `status` inside a timeline payload. */
+export function fieldChoices(field) {
+  const segments = splitOpfPath(field.path);
+  return segments.at(-1) === "status" && segments.at(-3) === "timeline"
+    ? TIMELINE_STATUS_CHOICES
+    : segments.at(-1) === "status" && segments.at(-3) === "events" && segments.at(-4) === "timeline"
+      ? TIMELINE_STATUS_CHOICES
+      : undefined;
+}
+/**
+ * A blank copy of `value`'s shape for the "Add" button: texts empty, numbers 0, booleans false, `type`, `mode` and
+ * `language` kept. A timeline event's `status` is left out, so a new event starts with no status instead of a copy.
+ */
+export function emptyLike(value, key = "") {
+  if (Array.isArray(value)) return value.map((child) => emptyLike(child));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([name]) => name !== "status")
+        .map(([name, child]) => [name, emptyLike(child, name)]),
+    );
+  if (typeof value === "number") return 0;
+  if (typeof value === "boolean") return false;
+  return ["type", "mode", "language"].includes(key) ? value : "";
+}

package/dist/canvas.d.ts

@@ -1,55 +1,47 @@
 import type { EditorSession } from "./index.js";
 import type { RenderSvgOptions } from "@openpresentation/opf-render";
+import type { BrowserFontsHandle } from "@openpresentation/opf-render/fonts-browser";
 import type { SlideComposition } from "@openpresentation/opf/composition";
-/** Faces a document needs (script packages and vendored files) that are not loaded yet, and the way to load them. */
-export interface FontGate {
-  /** Synchronous. Empty means the document can render now. Never throws. `renderOptions` are the options the host renders with (`catalogs`, ...); the canvas passes its current ones. */
-  pending(document: unknown, renderOptions?: RenderSvgOptions): string[];
-  /** Load every pending face (vendored faces first, then script faces). Rejects with a `fonts-unavailable` error; never retries by itself. */
-  ensure(document: unknown, options?: { signal?: AbortSignal; renderOptions?: RenderSvgOptions }): Promise<void>;
-  /** `whenFontsReady` on this gate. */
-  run(document: unknown, handlers?: FontGateHandlers): Promise<void>;
-}
-export interface FontGateHandlers {
+/**
+ * The fonts the canvas, the export and `whenFontsReady` take: the renderer's handle from `loadFonts()` (`@openpresentation/opf-render/fonts-browser`).
+ * Only `textMeasurement` is required to measure; `pending` and `ensure` make the canvas load script and vendored faces before it draws.
+ */
+export type EditorFonts = Pick<BrowserFontsHandle, "textMeasurement"> & Partial<Pick<BrowserFontsHandle, "embeddedFonts" | "pending" | "ensure" | "registry">>;
+export interface FontsReadyHandlers {
   /** Return false once the document was superseded; the late result is then dropped. */
   isCurrent?: () => boolean;
   loading?: (pending: string[]) => void;
   ready?: () => void;
   failed?: (error: Error) => void;
-  /** The options the host renders with (`catalogs`, ...), passed to the gate. */
+  /** The options the host renders with (`catalogs`, ...), passed to the fonts handle. */
   renderOptions?: RenderSvgOptions;
 }
 export declare const FONTS_PENDING: "fonts-pending";
 export declare const FONTS_UNAVAILABLE: "fonts-unavailable";
-/** Wrap a browser font registry (`loadBrowserFontRegistry`). Registries without the lazy loaders gate nothing. */
-/**
- * `options.renderOptions` (an object, or a function called on every use) are the default render options passed to the registry
- * (`catalogs`, ...), under a call's own; the canvas passes its current `renderOptions` itself, so a gate needs none.
- */
-export declare function createFontGate(registry: object, options?: { renderOptions?: RenderSvgOptions | (() => RenderSvgOptions | undefined) }): FontGate;
 /**
- * Ensure fonts for a document, then run `ready` (synchronously when nothing is pending). The one
- * "ensure fonts, then render" helper: load failures and exceptions from `ready` go to `failed`.
+ * Ensure fonts for a presentation, then run `ready` (synchronously when nothing is pending). The one
+ * "ensure fonts, then render" helper: load failures and exceptions from `ready` go to `failed`. `fonts` is the renderer's fonts handle.
  */
 export declare function whenFontsReady(
-  gate: Pick<FontGate, "pending" | "ensure"> | undefined,
-  document: unknown,
-  handlers?: FontGateHandlers,
+  fonts: Pick<EditorFonts, "pending" | "ensure"> | undefined,
+  presentation: unknown,
+  handlers?: FontsReadyHandlers,
 ): Promise<void>;
 export interface CanvasEditorOptions {
   editor?: EditorSession;
-  document?: unknown;
+  presentation?: unknown;
   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
-   * loading: it shows "Loading fonts…", loads them and then renders, on every path (editor changes, undo/redo,
-   * imports, dimension switches, slide changes, drafts). Without one every document renders at once.
+   * The renderer's fonts handle (`loadFonts()` from `@openpresentation/opf-render/fonts-browser`). Its `textMeasurement` lays the slide out and
+   * its faces draw it. With its `pending` and `ensure` the canvas never renders a document whose faces are still loading: it shows
+   * "Loading fonts…", loads them and then renders, on every path (editor changes, undo/redo, imports, dimension switches, slide
+   * changes, drafts). Without a handle every document renders at once, laid out with core's portable text estimate.
    */
-  fonts?: Pick<FontGate, "pending" | "ensure">;
+  fonts?: EditorFonts;
   /**
    * How a pointer enters text editing. "click" (default): a single press on editable text starts editing with the caret at the
    * pressed character, and a press-drag selects a range. "dblclick": a click selects, a double-click enters with the caret at the
@@ -68,7 +60,7 @@ export interface CanvasEditorOptions {
     editor: EditorSession;
   }) => void;
   onDraft?: (draft: {
-    document: unknown;
+    presentation: unknown;
     path: string;
     value: unknown;
   }) => void;
@@ -78,7 +70,7 @@ export interface CanvasEditorOptions {
   /** Font loading progress of the canvas: `loading`, `error` (a face could not be loaded; the canvas offers a retry) and `ready`. */
   onFonts?: (event: { state: "loading"; pending: string[] } | { state: "error"; error: Error } | { state: "ready" }) => void;
   onRender?: (event: {
-    document: unknown;
+    presentation: unknown;
     slideIndex: number;
     svg: SVGSVGElement;
     geometry: SlideComposition;
@@ -110,7 +102,7 @@ export interface CanvasEditor {
   editProperties(path: string): boolean;
   commit(): boolean;
   cancel(): void;
-  render(document?: unknown): void;
+  render(presentation?: 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),