@openpresentation/opf-editor 0.0.1 → 0.1.0

package/README.md

@@ -14,6 +14,28 @@ Embeddable local editor primitives for Open Presentation Format documents. The p
 - JSON Patch state transitions with inverse patches for undo/redo
 - Optional DOM controls plus React and Svelte bindings in separate embeddable entry points
 
+## Live browser canvas (preview)
+
+The new `@openpresentation/opf-editor/canvas` entry provides a framework-independent SVG canvas with inline text/table-cell editing, live validated drafts, undo/redo, cancellation, and structured property forms for charts, lists, metrics, quotes, code, timelines and images. Mount it in a DOM container:
+
+```js
+import { createCanvasEditor } from '@openpresentation/opf-editor/canvas';
+
+const canvas = createCanvasEditor(container, {
+  document: presentation,
+  renderOptions: { textMeasurement: fontRegistry.textMeasurement },
+  onCommit: ({ editor }) => saveDocument(editor.document),
+});
+await canvas.ready;
+// canvas.destroy() when unmounting.
+```
+
+Load the same font bytes into the browser using `loadBrowserFontRegistry` from `@openpresentation/opf-render/fonts-browser` before mounting. The host owns font URLs, storage and collaboration. `onDraft` provides live document drafts; the session only changes on commit. Escape cancels. Concurrent edits to the selected payload cancel a stale draft.
+
+These APIs are included in version 0.1.0 and require core 0.4.0 and renderer 0.1.0 for the canvas. See the OPF repository’s `docs/live-editor.md` for setup, the support matrix and roadmap. `pnpm pack:ecosystem` in that repository also prepares local preview tarballs for coordinated development.
+
+The canvas retains canonical SVG glyphs while a transparent native input supplies the caret. Complete rich-text formatting, freeform drag/resize, all chart/media treatments, and cross-engine pixel identity remain work in progress. The Source dialog in the playground now provides a live JSON preview; changes are validated before committing.
+
 ## Runtime Policy
 
 The package runtime must stay local and deterministic:
@@ -145,3 +167,60 @@ Required first-publish setup:
 3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
 
 This repo does not require an npm automation token when Trusted Publishing is configured.
+
+## Shared dynamic composition (local development)
+
+The current checkout uses `@openpresentation/opf/composition` for portable geometry. Slides can select `auto`, `row`, `column`, or `grid`, set weighted tracks, and request path-specific overflow diagnostics. See the sibling OPF repo's `docs/dynamic-composition.md` for the complete contract.
+
+Version 0.1.0 requires published `@openpresentation/opf@^0.4.0`. The optional renderer peer requires `@openpresentation/opf-render@^0.1.0`. Clean registry installs support the new composition APIs without sibling checkouts. For coordinated source development, build OPF and run `node scripts/link-ecosystem.mjs` there; `pnpm test:ecosystem` verifies shared geometry and import/export behavior.
+
+## Local interactive demo
+
+With the sibling workspace linked, run `pnpm demo:editor` from the OPF repo, then serve its `artifacts/editor` directory with a static HTTP server. The demo lets you select SVG text, apply edits, change composition, edit the JSON document, and undo/redo. It uses the real renderer and editor session with no service dependency.
+
+Editor snapshots are immutable and keep the same object identity until a change. This supports React `useSyncExternalStore` without render loops. `editor.document` remains a separate mutable copy for callers that need one.
+
+Nested content groups expose their bounds through `editor.composeSlide(index).groups`. Use `editor.setGroupComposition("slides.0.blocks.0", {mode:"column"})` to reflow a group with validation and undo/redo. The playground includes a nested example and group arrangement controls.
+
+`editor.paginateSlide(index, {minFontSize:24})` splits a crowded draft into ordinary OPF slides as one undoable transaction. It returns the change and source mappings; failed pagination leaves the document unchanged. The playground’s Split overflow action demonstrates the workflow.
+
+`composeSlide(index, {textMeasurement})` and `paginateSlide(index, {textMeasurement})` accept the same font provider as preview and export. The local playground now uses bundled, embedded fonts and reports substitutions.
+
+
+## Copy, paste, and gallery imports
+
+The browser-safe `/transfer` export provides `parseOpfTransfer`, `serializeOpfTransfer`, and `prepareOpfImport`. Copy whole documents, self-contained slides, or selected JSON values as readable JSON, compact JSON, or fenced Markdown. Parse pasted documents, slides, arrays, fragments, and one fenced code block. Prepare an immutable validated import before applying one root JSON Patch through the editor session. Insertion namespaces inline catalogs and conflicting asset/slide IDs and preserves primary source design defaults.
+
+The `/galleries` export provides `loadOpfGallery` and `loadOpfGalleryItem`, accepting an AbortSignal and injectable fetch. Registries use `{name, items:[{id, name, category, opf}]}` for inline documents or `opfUrl` for a relative JSON URL. Public PPTX.gallery registry descriptors are supported. Cross-origin endpoints need CORS; requests omit credentials/referrers, cap responses at 20 MB, and keep automatic item requests on the configured gallery origin. Documents should include inline catalog records; arbitrary external catalog sources are not automatically fetched.
+
+The playground includes Copy OPF and Add OPF dialogs with paste, file/drop, gallery search, and URL tabs. Preview before inserting or opening. Custom registries persist in local storage; defaults are configured in `examples/galleries.json`. Copy permissions may require using the Select all fallback. Pasting within text fields keeps normal text editing. Cmd/Ctrl+Shift+C opens copying and Cmd/Ctrl+O opens file import.
+
+Slide insertion does not merge root speakers, organizations, or narrative metadata. Use Open as a presentation for the full source document. Some gallery presets contain minimal examples. The root OPF workspace's `docs/live-editor.md` documents the complete demo and npm API workflow.
+
+
+## Schema-driven property editing
+
+`@openpresentation/opf-editor/schema-inspector` exports `createSchemaInspector(container, {editor, path, onDraft, onCommit})`. It uses the canonical schemas to expose optional properties, union forms, nested arrays and maps, catalog records, and scalar fields. Valid drafts invoke `onDraft` for a host preview. `commit()` validates and applies one undoable root patch; `reset()` discards the draft; `navigate(path)` selects another field; `destroy()` unsubscribes and removes owned DOM. Concurrent document changes reject a stale draft.
+
+`@openpresentation/opf-editor/schema` exports schema resolution, field traversal, initial values, and the full property inventory. These APIs power the All properties workspace and the gallery reference. Arbitrary extensions can use string, number, boolean, object, array, and null forms. Full-schema editing does not imply that the SVG renderer implements every visual feature.
+
+
+### Rich text on the canvas
+
+Select rendered rich text to format it, or double-click a rich text block to select all of it. The toolbar supports character styles, point size, font family, hex color, links, scripts, and selected-text replacement. Plain text payloads offer **Format text** during inline editing. **Edit runs** opens the structured fields; `canvas.editProperties(path)` does the same programmatically. Each action is validated and undoable. Continuous rich-text typing with a mixed-style caret remains under development.
+
+Headless applications and agents can import `formatRichTextRange`, `replaceRichTextRange`, and `richTextContent` from `@openpresentation/opf-editor/rich-text`. The helpers preserve surrounding run metadata and accept UTF-16 offsets on whole grapheme boundaries. A null format value removes an override. Apply the returned value through the editor session or validate the resulting document before saving.
+
+
+### Resize dynamic layouts
+
+The canvas can show draggable, keyboard-accessible dividers for root and nested composition tracks. Pass `layoutEditing: true`, or call `canvas.setLayoutEditing(true)`. A pointer drag produces live preview drafts and commits one undo step. Escape cancels; strict overflow prevents invalid fit. Automatic layouts become explicit grids when resized. Promoted regions stay fixed, while their nested groups can be resized.
+
+`prepareTrackResize(document, flow, boundary, fraction)` from `@openpresentation/opf-editor/layout` returns a candidate document and guarded patches for headless agents. Obtain `flow` from the shared renderer's `geometry.flows`; preview the candidate before applying. The editor supports JSON Patch `test` guards alongside add/replace/remove; failed guards leave state and history unchanged. This export is included in version 0.1.0.
+
+
+### Move complete blocks
+
+Arrange mode also shows numbered block handles. Drag to reorder siblings, use arrow keys for earlier/later, or click a handle to choose an existing destination group/slide and insertion position. The move preserves the whole block, including rich text, table/chart data, and nested groups. Each move is validated, preflighted by the renderer, and undoable. Parent weights stay with layout positions; moves that leave an empty container or create a containment cycle are rejected.
+
+Agents can import `prepareBlockMove` and `listBlockContainers` from `@openpresentation/opf-editor/layout`. The prepared result includes a full candidate document, guarded atomic patches, the new block path, and a changed flag. Destination indexes refer to the pre-removal document. Use `canvas.openBlockMenu(path)` for the corresponding browser controls.

package/dist/block-controls.js

@@ -0,0 +1,143 @@
+import {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,createContentBlock} from './blocks.js';
+import {getValueAtPath,splitOpfPath,opfPathToJsonPointer,applyJsonPatch} from './index.js';
+
+/** Arrange-mode block handles. Native drag reorders siblings; the menu also reparents blocks. */
+export function createBlockControls(root, options) {
+  const doc=root.ownerDocument,editor=options.editor;
+  const layer=doc.createElement('div');layer.className='opf-block-controls';
+  layer.style.cssText='position:absolute;inset:0;pointer-events:none;z-index:4';root.append(layer);
+  let cells=[],geometry,drag=null,panel=null,committing=false,returnFocus=null;
+  const signature=path=>JSON.stringify(editor.get(path));
+  const clearMarker=()=>layer.querySelector('[data-block-drop]')?.remove();
+  function cancel(){drag=null;clearMarker();const restore=panel?.contains(doc.activeElement);panel?.remove();panel=null;if(restore&&returnFocus?.isConnected)returnFocus.focus();returnFocus=null;}
+  function apply(prepared){
+    if(!prepared?.changed){cancel();return true;}
+    // Retain changes outside the guarded containers and preflight the exact candidate.
+    const candidate=applyJsonPatch(editor.document,prepared.patches);
+    options.validate(candidate);
+    committing=true;
+    try{cancel();editor.applyPatch(prepared.patches,{source:'canvas-block-edit',rejectInvalid:true});options.onMove?.(prepared.path);([ ...layer.querySelectorAll("[data-block-path]")].find(node=>node.dataset.blockPath===prepared.path)??layer.querySelector('[data-block-add]'))?.focus();options.clearError?.();options.onCommit?.({path:prepared.path,editor});return true;}
+    finally{committing=false;}
+  }
+  function move(from,to,index,base=editor.document){
+    try{return apply(prepareBlockMove(base,from,to,index));}catch(error){cancel();options.onError(error);return false;}
+  }
+  function open(path){
+    if(!options.beforeEdit())return;
+    cancel();returnFocus=doc.activeElement;path=opfPathToJsonPointer(path);const base=editor.document,parts=splitOpfPath(path),container=opfPathToJsonPointer(parts.slice(0,-2)),index=Number(parts.at(-1));
+    const source=getValueAtPath(base,[...parts.slice(0,-2),'blocks']);
+    if(parts.at(-2)!=='blocks'||!Number.isInteger(index)||index<0||!Array.isArray(source)||index>=source.length){options.onError(new Error('Choose an existing content block.'));return;}
+    const count=source.length;
+    panel=doc.createElement('div');panel.setAttribute('role','dialog');panel.setAttribute('aria-label','Move content block');
+    panel.style.cssText='position:absolute;right:8px;bottom:8px;width:280px;max-width:calc(100% - 16px);box-sizing:border-box;padding:14px;background:white;color:#332e40;border:1px solid #d5cde5;border-radius:8px;box-shadow:0 5px 24px #28203922;pointer-events:auto;font:12px/1.5 system-ui;z-index:3';
+    const heading=doc.createElement('strong');heading.textContent='Move content';panel.append(heading);
+    const button=(label,handler,disabled=false)=>{const b=doc.createElement('button');b.type='button';b.textContent=label;b.disabled=disabled;b.style.cssText='margin:6px 5px 0 0;padding:5px 8px;border:1px solid #ded8e8;border-radius:4px;background:#faf9fc;color:inherit;cursor:pointer';b.onclick=handler;panel.append(b);return b;};
+    button('Earlier',()=>move(path,container,index-1,base),index===0);
+    button('Later',()=>move(path,container,index+2,base),index===count-1);
+    const label=doc.createElement('label');label.textContent='Destination';label.style.cssText='display:block;margin-top:10px';
+    const destinations=doc.createElement('select');destinations.setAttribute('aria-label','Move destination');destinations.style.cssText='display:block;width:100%;padding:6px;margin-top:4px';
+    const containers=listBlockContainers(base).filter(item=>item.path!==path&&!item.path.startsWith(path+'/'));
+    for(const item of containers){const option=doc.createElement('option');option.value=item.path;option.textContent=item.label;destinations.append(option);}destinations.value=container;label.append(destinations);panel.append(label);
+    const positionLabel=doc.createElement('label');positionLabel.textContent='Position';positionLabel.style.cssText='display:block;margin-top:8px';
+    const positions=doc.createElement('select');positions.setAttribute('aria-label','Move position');positions.style.cssText='display:block;width:100%;padding:6px;margin-top:4px';positionLabel.append(positions);panel.append(positionLabel);
+    function fillPositions(){positions.replaceChildren();const selected=containers.find(c=>c.path===destinations.value);for(let i=0;i<=selected.count;i++){const option=doc.createElement('option');option.value=String(i);option.textContent=i===selected.count?'At the end':`Before block ${i+1}`;positions.append(option);}positions.value=destinations.value===container?String(index):String(selected.count);}
+    destinations.onchange=fillPositions;fillPositions();
+    button('Move',()=>move(path,destinations.value,Number(positions.value),base));
+    button('Duplicate',()=>change(()=>prepareBlockDuplicate(base,path)));
+    button('Delete',()=>change(()=>prepareBlockRemove(base,path)));
+    button('Add after',()=>openInsert(container,index+1));
+    if(Array.isArray(source[index].blocks))button('Add inside',()=>openInsert(path));
+    button('Cancel',cancel);
+    panel.onkeydown=event=>{if(event.key==='Escape'){event.preventDefault();event.stopPropagation();cancel();}};
+    layer.append(panel);destinations.focus();
+  }
+  function change(prepare) {
+    try{return apply(prepare());}catch(error){options.onError(error);return false;}
+  }
+  function openInsert(containerPath,index) {
+    if(!options.beforeEdit())return;
+    cancel();returnFocus=doc.activeElement;const base=editor.document;
+    const containers=listBlockContainers(base,{slideIndex:options.slideIndex(),includeImplicit:true});
+    if(!containers.length){options.onError(new Error('No content container is available on this slide.'));return;}
+    const requested=containerPath===undefined?containers[0].path:opfPathToJsonPointer(containerPath);
+    if(!containers.some(c=>c.path===requested)){options.onError(new Error('Choose a content container on this slide.'));return;}
+    if(index!==undefined&&(!Number.isInteger(index)||index<0||index>containers.find(c=>c.path===requested).count)){options.onError(new Error('Insertion index is out of range.'));return;}
+    panel=doc.createElement('div');panel.setAttribute('role','dialog');panel.setAttribute('aria-label','Add content');
+    panel.style.cssText='position:absolute;right:8px;top:40px;width:300px;max-width:calc(100% - 16px);max-height:calc(100% - 48px);overflow:auto;box-sizing:border-box;padding:14px;background:white;color:#332e40;border:1px solid #d5cde5;border-radius:8px;box-shadow:0 5px 24px #28203922;pointer-events:auto;font:12px/1.5 system-ui;z-index:3';
+    const heading=doc.createElement('strong');heading.textContent='Add content';panel.append(heading);
+    function field(label,node){const wrapper=doc.createElement('label');wrapper.textContent=label;wrapper.style.cssText='display:block;margin-top:10px';node.setAttribute('aria-label',label);node.style.cssText='display:block;box-sizing:border-box;width:100%;padding:6px;margin-top:4px';wrapper.append(node);panel.append(wrapper);return wrapper;}
+    const kind=doc.createElement('select');for(const [value,label] of [['text','Text'],['list','List'],['chart','Chart'],['table','Table'],['metric','Metric'],['quote','Quote'],['code','Code'],['timeline','Timeline'],['group','Group'],['image','Image'],['video','Video']]){const option=doc.createElement('option');option.value=value;option.textContent=label;kind.append(option);}field('Content type',kind);
+    const destinations=doc.createElement('select');for(const item of containers){const option=doc.createElement('option');option.value=item.path;option.textContent=item.label;destinations.append(option);}destinations.value=requested;field('Add destination',destinations);
+    const positions=doc.createElement('select');field('Add position',positions);
+    function positionsFor(){positions.replaceChildren();const count=containers.find(c=>c.path===destinations.value).count;for(let i=0;i<=count;i++){const option=doc.createElement('option');option.value=String(i);option.textContent=i===count?'At the end':`Before block ${i+1}`;positions.append(option);}positions.value=String(destinations.value===requested&&index!==undefined?Math.min(index,count):count);}
+    destinations.onchange=positionsFor;positionsFor();
+    const source=doc.createElement('input');source.type='text';const media=field('Media URL or asset reference',source);media.style.display='none';
+    const file=doc.createElement('input');file.type='file';file.accept='image/png,image/jpeg,image/webp';const upload=field('Or choose an image',file);upload.style.display='none';
+    let loading=false,fileRevision=0;const thisPanel=panel;
+    const add=doc.createElement('button');add.type='button';add.textContent='Add';add.style.cssText='margin:12px 6px 0 0;padding:6px 12px;border:1px solid #bfb1de;border-radius:4px;background:#ede7f9;color:inherit;cursor:pointer';
+    const close=doc.createElement('button');close.type='button';close.textContent='Cancel';close.onclick=cancel;close.style.cssText=add.style.cssText;
+    const cancelRead=()=>{fileRevision++;loading=false;add.disabled=false;};
+    source.oninput=()=>{cancelRead();file.value='';};
+    kind.onchange=()=>{cancelRead();media.style.display=['image','video'].includes(kind.value)?'block':'none';upload.style.display=kind.value==='image'?'block':'none';};
+    file.onchange=()=>{
+      cancelRead();const revision=fileRevision,chosen=file.files?.[0];if(!chosen)return;
+      if(!['image/png','image/jpeg','image/webp'].includes(chosen.type)){options.onError(new Error('Choose a PNG, JPEG or WebP image.'));return;}
+      loading=true;add.disabled=true;const reader=new doc.defaultView.FileReader();
+      reader.onload=()=>{if(panel!==thisPanel||revision!==fileRevision)return;source.value=String(reader.result);loading=false;add.disabled=false;};
+      reader.onerror=()=>{if(panel!==thisPanel||revision!==fileRevision)return;loading=false;add.disabled=false;options.onError(new Error('The image file could not be read.'));};
+      reader.readAsDataURL(chosen);
+    };
+    add.onclick=()=>{if(!loading)change(()=>prepareBlockInsert(base,destinations.value,createContentBlock(kind.value,{source:source.value}),Number(positions.value)));};
+    panel.append(add,close);panel.onkeydown=event=>{if(event.key==='Escape'){event.preventDefault();event.stopPropagation();cancel();}};
+    layer.append(panel);kind.focus();
+  }
+  function update(document,nextGeometry){
+    geometry=nextGeometry;
+    if(drag)return;
+    cancel();layer.replaceChildren();cells=[];
+    if(!options.enabled()||options.isEditing())return;
+    const add=doc.createElement('button');add.type='button';add.textContent='+ Add content';add.setAttribute('aria-label','Add content');add.dataset.blockAdd='';
+    add.style.cssText='position:absolute;right:8px;top:8px;pointer-events:auto;padding:5px 9px;background:#f6f3fc;color:#675394;border:1px solid #cfc4e7;border-radius:5px;font:12px system-ui;cursor:pointer';add.onclick=()=>openInsert();layer.append(add);
+    for(const flow of geometry.flows??[]){
+      const blocks=getValueAtPath(document,[...splitOpfPath(flow.path),'blocks']);
+      if(!Array.isArray(blocks)||blocks.length!==flow.itemCount)continue;
+      blocks.forEach((block,index)=>{
+        const col=flow.columns[index%flow.columns.length],row=flow.rows[Math.floor(index/flow.columns.length)];if(!col||!row)return;
+        const path=opfPathToJsonPointer([...splitOpfPath(flow.path),'blocks',String(index)]),container=opfPathToJsonPointer(flow.path);
+        const box={x:flow.box.x+col.offset,y:flow.box.y+row.offset,width:col.size,height:row.size};
+        const depth=splitOpfPath(path).filter(p=>p==='blocks').length;
+        const node=doc.createElement('button');node.type='button';node.draggable=true;node.dataset.blockPath=path;
+        node.textContent=Array.isArray(block.blocks)?`Group ${index+1} ⋮⋮`:`${index+1} ⋮⋮`;
+        node.setAttribute('aria-label',`Move ${Array.isArray(block.blocks)?'group':'block'} ${index+1} in ${flow.path===`slides.${options.slideIndex()}`?'slide':'group'}`);
+        node.title='Drag to reorder · Click to move between groups · Arrow keys reorder';
+        node.style.cssText=`position:absolute;pointer-events:auto;touch-action:none;cursor:grab;left:calc(${(box.x+box.width)/geometry.width*100}% - ${Array.isArray(block.blocks)?70:38}px);top:calc(${box.y/geometry.height*100}% + ${(depth-1)*23}px);height:22px;min-width:34px;padding:2px 5px;background:#f6f3fc;color:#675394;border:1px solid #cfc4e7;border-radius:4px;font:11px system-ui;z-index:${depth}`;
+        const cell={path,container,index,box,axis:flow.composition.mode==='column'?'y':'x',node};cells.push(cell);
+        node.onclick=()=>open(path);
+        node.onkeydown=event=>{if(['ArrowLeft','ArrowUp','ArrowRight','ArrowDown'].includes(event.key)){event.preventDefault();event.stopPropagation();if(!options.beforeEdit())return;const delta=['ArrowLeft','ArrowUp'].includes(event.key)?-1:1;if(index+delta>=0&&index+delta<blocks.length)move(path,container,index+(delta>0?2:-1));}};
+        node.ondragstart=event=>{
+          if(!options.beforeEdit()){event.preventDefault();return;}
+          cancel();drag={from:path,container,index,base:editor.document,signature:signature(container),cells:[...cells],prepared:null};
+          event.dataTransfer.effectAllowed='move';event.dataTransfer.setData('text/plain',path);
+        };
+        node.ondragend=()=>{cancel();options.render();};layer.append(node);
+      });
+    }
+  }
+  function over(event){
+    if(!drag)return;
+    const rect=root.querySelector('.opf-canvas-preview svg').getBoundingClientRect();
+    const x=(event.clientX-rect.left)*geometry.width/rect.width,y=(event.clientY-rect.top)*geometry.height/rect.height;
+    const target=drag.cells.find(cell=>cell.container===drag.container&&x>=cell.box.x&&x<=cell.box.x+cell.box.width&&y>=cell.box.y&&y<=cell.box.y+cell.box.height);
+    clearMarker();drag.prepared=null;if(!target)return;
+    event.preventDefault();event.dataTransfer.dropEffect='move';
+    const after=target.axis==='x'?x>target.box.x+target.box.width/2:y>target.box.y+target.box.height/2;
+    try{drag.prepared=prepareBlockMove(drag.base,drag.from,target.container,target.index+(after?1:0));}catch(error){options.onError(error);return;}
+    const marker=doc.createElement('div');marker.dataset.blockDrop='';const vertical=target.axis==='x',box=target.box;
+    marker.style.cssText=`position:absolute;pointer-events:none;background:#7765d0;z-index:10;${vertical?`left:${(box.x+(after?box.width:0))/geometry.width*100}%;top:${box.y/geometry.height*100}%;width:3px;height:${box.height/geometry.height*100}%`:`top:${(box.y+(after?box.height:0))/geometry.height*100}%;left:${box.x/geometry.width*100}%;height:3px;width:${box.width/geometry.width*100}%`}`;layer.append(marker);
+  }
+  function drop(event){if(!drag)return;event.preventDefault();const prepared=drag.prepared;try{apply(prepared);}catch(error){cancel();options.onError(error);}finally{cancel();options.render();}}
+  const escape=event=>{if(event.key==='Escape'&&(drag||panel)){event.preventDefault();event.stopPropagation();cancel();options.render();}};
+  root.addEventListener('dragover',over);root.addEventListener('drop',drop);doc.addEventListener('keydown',escape,true);
+  const unsubscribe=editor.subscribe(()=>{if(committing)return;if(drag&&signature(drag.container)!==drag.signature){cancel();options.onError(new Error('The block container changed elsewhere. Start the move again.'));}if(panel)cancel();});
+  return {update,cancel,open,openInsert,hide(){cancel();layer.replaceChildren();},get editingPath(){return drag?.from??null;},destroy(){cancel();unsubscribe();root.removeEventListener('dragover',over);root.removeEventListener('drop',drop);doc.removeEventListener('keydown',escape,true);layer.remove();}};
+}

package/dist/blocks.d.ts

@@ -0,0 +1,13 @@
+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 listBlockContainers(document: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 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

@@ -0,0 +1,125 @@
+import {splitOpfPath,opfPathToJsonPointer,getValueAtPath,applyJsonPatch,validateOpfDocument} from './index.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) {
+  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));
+  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']);
+  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&&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];
+  if(!same&&prefix(sourceArray,to)&&/^(0|[1-9][0-9]*)$/.test(to[sourceArray.length]??'')&&Number(to[sourceArray.length])>sourceIndex)
+    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))})),
+    {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};
+}
+
+/** Discover actual block containers without interpreting imported content as instructions. */
+export function listBlockContainers(document,{slideIndex,includeImplicit=false}={}) {
+  const result=[];
+  function visit(value,path,label,depth=0){
+    if(!value||typeof value!=='object'||depth>32)return;
+    if(Array.isArray(value.blocks)){
+      result.push({path:opfPathToJsonPointer(path),label,count:value.blocks.length});
+      value.blocks.forEach((block,i)=>visit(block,[...path,'blocks',String(i)],`${label} › Group ${i+1}`,depth+1));
+    }
+  }
+  (document?.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});
+    visit(slide,path,label);
+    if(includeImplicit)for(const [key,value] of Object.entries(slide))if(isRegion(key)&&value&&typeof value==='object'&&!Array.isArray(value.blocks))result.push({path:opfPathToJsonPointer([...path,key]),label:`${label} › ${key}`,count:1,implicit:true});
+    for(const [key,value] of Object.entries(slide))if(key.split(/[+:]/).every(part=>['top','middle','bottom','left','center','right'].includes(part))&&value&&typeof value==='object'&&!Array.isArray(value)&&Array.isArray(value.blocks))visit(value,[...path,key],`${label} › ${key}`);
+  });
+  return result;
+}
+
+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) {
+  const pointer=opfPathToJsonPointer(container);
+  const patches=[{op:'test',path:pointer,value:structuredClone(getValueAtPath(document,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};
+}
+/** Insert into a slide, existing group or named region. Implicit payloads become blocks. */
+export function prepareBlockInsert(document,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(!block||typeof block!=='object'||Array.isArray(block))throw new TypeError('Insert an OPF content block object.');
+  const next=structuredClone(getValueAtPath(document,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];
+  }
+  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)]);
+}
+function checkedBlock(document,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(index>=blocks.length)throw new RangeError('Block does not exist.');
+  return {parts,container,index,blocks};
+}
+/** 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);
+}
+/** 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);
+  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);
+    }
+    ({parts,container,index,blocks}=checkedBlock(document,container));
+  }
+  const next=structuredClone(getValueAtPath(document,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);
+}
+
+/** Small, schema-valid starting points. Media requires an explicit source. */
+export function createContentBlock(kind,{source}={}) {
+  const presets={
+    text:{text:'Add your text'},
+    list:{items:['First point','Second point']},
+    chart:{chart:{type:'column',data:{columns:['Category','Value'],rows:[['A',12],['B',18],['C',9]]}}},
+    table:{table:{columns:['Item','Value'],rows:[['First','12'],['Second','18']]}},
+    metric:{metric:{value:42,label:'Metric'}},
+    quote:{quote:{text:'Add a quotation',attribution:'Source'}},
+    code:{code:{source:'const message = "Hello";',language:'javascript'}},
+    timeline:{timeline:[{when:'Now',what:'First milestone'},{when:'Next',what:'Second milestone'}]},
+    group:{composition:{mode:'column'},blocks:[{text:'First point'},{text:'Second point'}]}
+  };
+  if(kind==='image'||kind==='video'){
+    if(typeof source!=='string'||!source.trim())throw new TypeError('Choose a media file or enter its source.');
+    return {[kind]:source};
+  }
+  if(!Object.hasOwn(presets,kind))throw new TypeError('Unknown content block kind.');
+  return structuredClone(presets[kind]);
+}

package/dist/canvas-fields.js

@@ -0,0 +1,63 @@
+import {
+  applyJsonPatch,
+  createValuePatch,
+  validateOpfDocument,
+  splitOpfPath,
+  opfPathToJsonPointer,
+} from "./index.js";
+/** Scalar fields and collection paths use JSON Pointer to preserve arbitrary object keys. */
+export function getEditableFields(value, path) {
+  const fields = [],
+    arrays = [],
+    root = splitOpfPath(path);
+  const walk = (value, segments, labels) => {
+    const path = opfPathToJsonPointer(segments),
+      label = labels.join(" · ") || root.at(-1) || "Value";
+    if (Array.isArray(value)) {
+      arrays.push({ path, label, length: value.length });
+      value.forEach((child, index) =>
+        walk(
+          child,
+          [...segments, String(index)],
+          [...labels, String(index + 1)],
+        ),
+      );
+    } else if (value && typeof value === "object")
+      for (const [key, child] of Object.entries(value))
+        walk(child, [...segments, key], [...labels, key]);
+    else
+      fields.push({
+        path,
+        label,
+        type: value === null ? "null" : typeof value,
+        value,
+      });
+  };
+  walk(value, root, []);
+  return { fields, arrays };
+}
+export function parseCanvasValue(text, type) {
+  if (type === "number") {
+    if (!String(text).trim() || !Number.isFinite(Number(text)))
+      throw new Error("Enter a finite number.");
+    return Number(text);
+  }
+  if (type === "boolean") return text === true || text === "true";
+  if (type === "null") {
+    if (text === "null") return null;
+    throw new Error("This field must be null.");
+  }
+  return text;
+}
+export function createCanvasDraft(document, path, value) {
+  const draft = applyJsonPatch(
+    document,
+    createValuePatch(document, path, value),
+  );
+  const validation = validateOpfDocument(draft);
+  if (!validation.valid)
+    throw new Error(
+      validation.errors[0]?.message ?? "This change is not valid OPF.",
+    );
+  return draft;
+}

package/dist/canvas.d.ts

@@ -0,0 +1,67 @@
+import type { EditorSession } from "./index.js";
+import type { RenderSvgOptions } from "@openpresentation/opf-render";
+import type { SlideComposition } from "@openpresentation/opf/composition";
+export interface CanvasEditorOptions {
+  editor?: EditorSession;
+  document?: unknown;
+  slideIndex?: number;
+  /** Show keyboard-accessible dividers for resizing composition tracks. */
+  layoutEditing?: boolean;
+  renderOptions?: RenderSvgOptions;
+  /** Optional empty host for property forms; defaults to a floating canvas panel. */
+  propertiesContainer?: HTMLElement;
+  onSelect?: (selection: {
+    path: string;
+    value: unknown;
+    element: Element | undefined;
+    editor: EditorSession;
+  }) => void;
+  onDraft?: (draft: {
+    document: unknown;
+    path: string;
+    value: unknown;
+  }) => void;
+  onCommit?: (event: { path: string; editor: EditorSession }) => void;
+  onCancel?: (event: { path?: string }) => void;
+  onError?: (error: Error) => void;
+  onRender?: (event: {
+    document: unknown;
+    slideIndex: number;
+    svg: SVGSVGElement;
+    geometry: SlideComposition;
+    draft: boolean;
+  }) => void;
+}
+export interface CanvasEditor {
+  editor: EditorSession;
+  ready: Promise<void>;
+  readonly slideIndex: number;
+  readonly editingPath: string | null;
+  readonly layoutEditing: boolean;
+  setLayoutEditing(enabled: boolean): boolean;
+  /** Open reorder and move-to-group controls for a complete block path. */
+  openBlockMenu(path: string): void;
+  /** Add starter content to a slide/group/region, converting implicit content when needed. */
+  openInsertMenu(containerPath?: string,index?: number): void;
+  select(path: string): void;
+  beginEdit(path: string): void;
+  /** Open structured controls, including rich run fields. */
+  editProperties(path: string): boolean;
+  commit(): boolean;
+  cancel(): void;
+  render(document?: unknown): void;
+  setSlide(index: number): boolean;
+  setRenderOptions(options: RenderSvgOptions): boolean;
+  destroy(): void;
+}
+export declare function createCanvasEditor(
+  container: HTMLElement,
+  options: CanvasEditorOptions,
+): CanvasEditor;
+export declare function getEditableFields(
+  value: unknown,
+  path: string,
+): {
+  fields: { path: string; label: string; type: string; value: unknown }[];
+  arrays: { path: string; label: string; length: number }[];
+};