@openpresentation/opf-editor 0.11.3 → 0.14.2

package/dist/review.js

@@ -1,17 +1,14 @@
-// Review (RR-29): the headless model behind the Review panel. It runs core's design and accessibility audit
-// (`auditPresentation`) over the session's document, turns a finding into something an editor can act on (the
-// slide and the nearest existing path to select) and applies its suggested fixes through the session, so every
-// fix is a validated, undoable JSON Patch edit like any other. Importing this module needs no DOM.
-// Core is read from the namespace so an older core still loads this module; the audit then throws "audit-unavailable".
-import * as core from "@openpresentation/opf";
+// Review (RR-29, RR-55): the headless model behind the Review panel. The findings are core's: `validate(presentation)` runs the
+// full check (format, references, policy, accessibility, layout and content) and returns `Finding`s with a rule id, severity,
+// category, JSON Pointer path and optional `fixes`. A hosted reviewer (pptx.dev's AI review, a house style checker) returns the
+// same shape through the panel's `review` hook, and `mergeFindingReports` puts both in one list keyed by `Finding.source`. This
+// module turns a finding into something an editor can act on (the slide and the nearest existing path to select) and applies its
+// suggested fixes through the session, so every fix is a validated, undoable JSON Patch edit like any other. Importing this
+// module needs no DOM.
+import { validationCategories } from "@openpresentation/opf";
 import { OPFEditorError, getValueAtPath, hasValueAtPath, jsonPointerToOpfPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { assetIdOf, prepareAssetAlt } from "./assets.js";
 
-/** True when the installed core ships the audit (`@openpresentation/opf` after 0.11.4). */
-export function auditAvailable() {
-  return typeof core.auditPresentation === "function";
-}
-
 function fail(code, message, details) {
   return new OPFEditorError(code, message, details);
 }
@@ -19,34 +16,59 @@ function fail(code, message, details) {
 const SEVERITIES = ["error", "warning", "info"];
 const RANK = { error: 3, warning: 2, info: 1 };
 export const reviewSeverities = Object.freeze([...SEVERITIES]);
+/** Core's finding categories in the order a report lists them: format, references, policy, accessibility, layout, content. */
+export const reviewCategories = validationCategories;
+/** The `source` of a finding that names none: core's own checks (`Finding.source` defaults to `opf`). */
+export const CORE_SOURCE = "opf";
+
+const sourceOf = (finding) => finding?.source ?? CORE_SOURCE;
+
+const countBySeverity = (findings) => {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const finding of findings) if (finding.severity in counts) counts[finding.severity] += 1;
+  return counts;
+};
 
 /**
- * Audit a document. `options` are core's `AuditOptions` (severity per rule, `ignore`, thresholds, `textMeasurement`, ...);
- * pass `options.audit` to use another audit function. Returns core's report.
+ * One report from core's and a hosted reviewer's. Findings are kept per `Finding.source`: a report replaces what an earlier one
+ * said for the sources it carries, so the hook's findings (`pptx.dev/review`) sit beside core's (`opf`) and never overwrite them.
+ * A hook finding that names no source gets `hookSource` (default `review`), so it cannot be mistaken for one of core's.
+ * Returns `{ valid, findings, counts, sources }` (core's `FindingReport` plus the sources present).
  */
-export function runAudit(document, options = {}) {
-  const { audit = core.auditPresentation, ...auditOptions } = options;
-  if (typeof audit !== "function") {
-    throw fail("audit-unavailable", "The review needs a core release that ships the audit (@openpresentation/opf after 0.11.4).");
-  }
-  return audit(document, auditOptions);
+export function mergeFindingReports(core, hook, { hookSource = "review" } = {}) {
+  const bySource = new Map();
+  const add = (report, defaultSource) => {
+    const fresh = new Map();
+    for (const finding of report?.findings ?? []) {
+      const source = finding.source ?? defaultSource;
+      const entry = source === finding.source ? finding : { ...finding, source };
+      if (!fresh.has(source)) fresh.set(source, []);
+      fresh.get(source).push(entry);
+    }
+    for (const [source, list] of fresh) bySource.set(source, list);
+  };
+  add(core, CORE_SOURCE);
+  add(hook, hookSource);
+  const findings = [...bySource.values()].flat();
+  const counts = countBySeverity(findings);
+  return { valid: counts.error === 0, findings, counts, sources: [...bySource.keys()] };
 }
 
 /**
- * The review's findings: core's diagnostics with an `id` unique within the report, the slide index (or null for
- * the deck) and `dottedPath`, the OPF path to select. Sorted by slide, then severity (errors first), then rule.
+ * The review's findings: a report's `findings` with an `id` unique within the report, the slide index (or null for
+ * the deck) and `dottedPath`, the OPF path to select.
  */
 export function reviewFindings(report) {
   const seen = new Map();
-  return (report?.diagnostics ?? []).map((diagnostic) => {
-    const base = `${diagnostic.ruleId}|${diagnostic.path}`;
+  return (report?.findings ?? []).map((finding) => {
+    const base = `${sourceOf(finding)}|${finding.ruleId}|${finding.path}`;
     const count = seen.get(base) ?? 0;
     seen.set(base, count + 1);
     return {
-      ...diagnostic,
+      ...finding,
       id: count ? `${base}#${count}` : base,
-      slide: Number.isInteger(diagnostic.slide) ? diagnostic.slide : slideOfPointer(diagnostic.path),
-      dottedPath: safeDotted(diagnostic.path),
+      slide: Number.isInteger(finding.slide) ? finding.slide : slideOfPointer(finding.path),
+      dottedPath: safeDotted(finding.path),
     };
   });
 }
@@ -65,9 +87,7 @@ function safeDotted(pointer) {
 
 /** Counts by severity and the number of findings. */
 export function countFindings(findings) {
-  const counts = { error: 0, warning: 0, info: 0 };
-  for (const finding of findings) counts[finding.severity] += 1;
-  return { ...counts, total: findings.length };
+  return { ...countBySeverity(findings), total: findings.length };
 }
 
 /** Findings at or above `minimum` severity (`info` keeps all), optionally only those of one slide (or the deck, `null`). */
@@ -75,61 +95,80 @@ export function filterFindings(findings, { minimum = "info", slide } = {}) {
   return findings.filter((finding) => RANK[finding.severity] >= RANK[minimum] && (slide === undefined || finding.slide === slide));
 }
 
+/** Findings in reading order: the deck first, then each slide; errors before warnings before notes; then by rule and path. */
+export function sortFindings(findings) {
+  return [...findings].sort((a, b) =>
+    (a.slide ?? -1) - (b.slide ?? -1) || RANK[b.severity] - RANK[a.severity] || a.ruleId.localeCompare(b.ruleId) || a.path.localeCompare(b.path));
+}
+
+/**
+ * Findings grouped by category, core's categories first in core's order, then any other category (a hosted reviewer's `narrative`,
+ * ...) in the order it first appears. Each group is sorted as `sortFindings` does. Empty categories are left out.
+ */
+export function groupFindings(findings) {
+  const groups = new Map(reviewCategories.map((category) => [category, []]));
+  for (const finding of findings) {
+    if (!groups.has(finding.category)) groups.set(finding.category, []);
+    groups.get(finding.category).push(finding);
+  }
+  return [...groups].filter(([, list]) => list.length).map(([category, list]) => ({ category, findings: sortFindings(list) }));
+}
+
 /**
  * Where "go to" lands for a finding: the slide and the deepest existing path on the finding's way (a finding about
  * a missing field points at the field's parent). `path` is the OPF dotted path a host selects; `pointer` the JSON Pointer.
  */
-export function findingTarget(document, finding) {
+export function findingTarget(presentation, finding) {
   const segments = splitOpfPath(finding.path ?? "");
   let length = segments.length;
-  while (length > 0 && !hasValueAtPath(document, segments.slice(0, length))) length -= 1;
+  while (length > 0 && !hasValueAtPath(presentation, segments.slice(0, length))) length -= 1;
   const kept = segments.slice(0, length);
   const slide = kept[0] === "slides" && /^\d+$/.test(kept[1] ?? "") ? Number(kept[1]) : null;
   return { slide, path: kept.join("."), pointer: opfPathToJsonPointer(kept), exact: length === segments.length };
 }
 
-const PATCH_OPS = new Set(["add", "replace", "remove"]);
-const MAX_FIX_OPERATIONS = 4;
+const PATCH_OPS = new Set(["add", "replace", "remove", "move", "copy", "test"]);
+const MAX_FIX_OPERATIONS = 20;
+const STALE = "The slide has changed since this finding was made. The review has been refreshed; apply the fix again if it still shows.";
 
-function checkPatch(document, operations) {
+function checkPatch(presentation, operations) {
   if (!Array.isArray(operations) || !operations.length || operations.length > MAX_FIX_OPERATIONS) {
     throw fail("invalid-fix", `A review fix changes one to ${MAX_FIX_OPERATIONS} fields.`);
   }
   for (const operation of operations) {
     if (!operation || !PATCH_OPS.has(operation.op) || typeof operation.path !== "string" || !operation.path.startsWith("/") || operation.path === "/") {
-      throw fail("invalid-fix", "A review fix may add, replace or remove a field below the document root.", { operation });
+      throw fail("invalid-fix", "A review fix may change a field below the document root.", { operation });
     }
     // The finding is stale when the field it was about has since changed: refuse instead of guessing.
-    if ((operation.op === "replace" || operation.op === "remove") && !hasValueAtPath(document, operation.path)) {
-      throw fail("stale-finding", "The slide has changed since this finding was made. The review has been refreshed; apply the fix again if it still shows.", { operation });
-    }
+    if ((operation.op === "replace" || operation.op === "remove") && !hasValueAtPath(presentation, operation.path)) throw fail("stale-finding", STALE, { operation });
+    if ((operation.op === "move" || operation.op === "copy") && (typeof operation.from !== "string" || !hasValueAtPath(presentation, operation.from))) throw fail("stale-finding", STALE, { operation });
   }
 }
 
 /**
- * Apply one `patch` fix of a finding as a single undoable session change (validated: a fix that would make the
- * document invalid is rejected). Returns the session's change.
+ * Apply one `patch` fix of a finding (core's `FindingFix`: `title`, `patch`; a fix with no `kind` is a patch fix) as a single
+ * undoable session change, validated: a fix that would make the document invalid is rejected. Returns the session's change.
  */
 export function applyReviewFix(editor, finding, fix, meta = {}) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
-  if (!fix || fix.kind !== "patch") throw fail("invalid-fix", "Only patch fixes can be applied; a focus fix asks the author to type something.");
-  checkPatch(editor.document, fix.patch);
+  if (!fix || (fix.kind ?? "patch") !== "patch") throw fail("invalid-fix", "Only patch fixes can be applied; a focus fix asks the author to type something.");
+  checkPatch(editor.presentation, fix.patch);
   return editor.applyPatch(fix.patch, { ...meta, source: meta.source ?? "review", ruleId: finding?.ruleId, fix: fix.id, rejectInvalid: true });
 }
 
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 /** The patch operations that give the asset value at `pointer` alt text (`""` marks it decorative), or `null` when it already has exactly this alt. */
-export function altTextPatch(document, pointer, text) {
-  const value = getValueAtPath(document, pointer);
+export function altTextPatch(presentation, pointer, text) {
+  const value = getValueAtPath(presentation, pointer);
   if (value === undefined) throw fail("stale-finding", "The picture this finding is about no longer exists.", { pointer });
   const alt = String(text ?? "");
   const id = assetIdOf(value);
-  const entry = id === undefined ? undefined : getValueAtPath(document, ["assets", id]);
+  const entry = id === undefined ? undefined : getValueAtPath(presentation, ["assets", id]);
   // A picture that points into the assets registry gets its alt text there, so every use of the asset has it.
   if (id !== undefined && entry !== undefined) {
     // prepareAssetAlt treats "" as "remove the alt"; an empty alt here is the decorative choice and must stay in the document.
-    if (alt !== "") return prepareAssetAlt(document, id, alt).patches;
+    if (alt !== "") return prepareAssetAlt(presentation, id, alt).patches;
     if (isObject(entry)) {
       if (entry.alt === "") return null;
       return [{ op: Object.hasOwn(entry, "alt") ? "replace" : "add", path: opfPathToJsonPointer(["assets", id, "alt"]), value: "" }];
@@ -148,23 +187,23 @@ export function altTextPatch(document, pointer, text) {
 export function setReviewAltText(editor, pointer, text, meta = {}) {
   const alt = String(text ?? "").trim();
   if (!alt) throw fail("empty-alt-text", "Write what the picture shows, or mark it decorative.", { pointer });
-  const patch = altTextPatch(editor.document, pointer, alt);
-  if (!patch) return { changed: false, document: editor.document };
+  const patch = altTextPatch(editor.presentation, pointer, alt);
+  if (!patch) return { changed: false, presentation: editor.presentation };
   return { changed: true, ...editor.applyPatch(patch, { ...meta, source: meta.source ?? "review-alt", pointer, rejectInvalid: true }) };
 }
 
 /** Mark a picture decorative (empty alt text), an explicit choice, as one undoable change. */
 export function markDecorative(editor, pointer, meta = {}) {
-  const patch = altTextPatch(editor.document, pointer, "");
-  if (!patch) return { changed: false, document: editor.document };
+  const patch = altTextPatch(editor.presentation, pointer, "");
+  if (!patch) return { changed: false, presentation: editor.presentation };
   return { changed: true, ...editor.applyPatch(patch, { ...meta, source: meta.source ?? "review-decorative", pointer, rejectInvalid: true }) };
 }
 
 /** The alt text a picture has now (own or through the assets registry), for pre-filling the field. */
-export function currentAltText(document, pointer) {
-  const value = getValueAtPath(document, pointer);
+export function currentAltText(presentation, pointer) {
+  const value = getValueAtPath(presentation, pointer);
   if (isObject(value) && typeof value.alt === "string") return value.alt;
   const id = assetIdOf(value);
-  const entry = id === undefined ? undefined : getValueAtPath(document, ["assets", id]);
+  const entry = id === undefined ? undefined : getValueAtPath(presentation, ["assets", id]);
   return isObject(entry) && typeof entry.alt === "string" ? entry.alt : "";
 }

package/dist/rich-text-input.js

@@ -27,14 +27,15 @@ export function createRichTextInput(root, overlay, {path, value, getTarget, onIn
     const range=doc.createRange();range.setStart(node.firstChild,start);range.setEnd(node.firstChild,end);return range.getBoundingClientRect();
   }
   function boundaries() {
-    const result=[];
+    // A rich quote draws its quotation marks inside its first and last run (FA-10): they sit just outside the text, so their offsets clamp to its ends.
+    const result=[],total=richTextContent(current).length,clampOffset=offset=>Math.max(0,Math.min(total,offset));
     for(const node of fragments()) {
       if(!node.firstChild)continue;
       const start=Number(node.dataset.opfTextStart),text=node.textContent;
       for(const part of new Intl.Segmenter(undefined,{granularity:'grapheme'}).segment(text)) {
         const box=rect(node,part.index,part.index+part.segment.length),rtl=win.getComputedStyle(node).direction==='rtl';
-        result.push({offset:start+part.index,x:rtl?box.right:box.left,y:box.top,height:box.height,node});
-        result.push({offset:start+part.index+part.segment.length,x:rtl?box.left:box.right,y:box.top,height:box.height,node});
+        result.push({offset:clampOffset(start+part.index),x:rtl?box.right:box.left,y:box.top,height:box.height,node});
+        result.push({offset:clampOffset(start+part.index+part.segment.length),x:rtl?box.left:box.right,y:box.top,height:box.height,node});
       }
     }
     const target=getTarget(path),matrix=target?.getScreenCTM();

package/dist/rich-text-toolbar.js

@@ -72,7 +72,7 @@ export function createRichTextToolbar(root, {editor, report, beforeChange, onPro
       onChange?.(snapshot.path);
     } finally {restoring=false;}
   }
-  for(const [key,label] of [['bold','Bold'],['italic','Italic'],['underline','Underline'],['strikethrough','Strike'],['superscript','Superscript'],['subscript','Subscript']])
+  for(const [key,label] of [['bold','Bold'],['italic','Italic'],['underline','Underline'],['strikethrough','Strike'],['superscript','Superscript'],['subscript','Subscript'],['code','Code']])
     buttons.set(key,button(label,()=>apply({[key]:!currentRuns().every(run=>!!run[key])})));
   function field(label,type='text') {
     const input=doc.createElement('input');input.type=type;input.setAttribute('aria-label',label);input.placeholder=label;
@@ -85,11 +85,13 @@ export function createRichTextToolbar(root, {editor, report, beforeChange, onPro
   const size=field('Font size (pt)','number');size.min='0.1';size.step='0.5';size.style.width='80px';
   size.onchange=()=>{try{apply({fontSize:size.value?Number(size.value):null});}catch(error){report(error);}};
   const family=field('Font family');family.onchange=()=>{try{apply({fontFamily:family.value||null});}catch(error){report(error);}};
-  const link=field('Link URL');link.onchange=()=>{try{if(link.value&&!/^(https?:|mailto:)/i.test(link.value))throw new Error('Use an HTTP, HTTPS, or mailto link.');apply({link:link.value||null});}catch(error){report(error);}};
+  const link=field('Link URL');link.onchange=()=>{try{if(link.value&&!/^(https?:\/\/|mailto:|tel:)\S+$/.test(link.value))throw new Error('Use an HTTP, HTTPS, mailto or tel link without spaces.');apply({link:link.value||null});}catch(error){report(error);}};
+  const language=field('Language tag');language.style.width='80px';
+  language.onchange=()=>{try{if(language.value&&!/^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/.test(language.value))throw new Error('Use a BCP-47 language tag such as fr-FR or ja-JP.');apply({lang:language.value||null});}catch(error){report(error);}};
   const replacement=field('Selected text');replacement.style.width='160px';
   replacement.onkeydown=event=>{if(event.key==='Enter'){event.preventDefault();try{apply(null,replacement.value);}catch(error){report(error);}}};
   button('Replace text',()=>apply(null,replacement.value));
-  button('Reset style',()=>apply(Object.fromEntries(['bold','italic','underline','strikethrough','superscript','subscript','color','fontSize','fontFamily','link'].map(key=>[key,null]))));
+  button('Reset style',()=>apply(Object.fromEntries(['bold','italic','underline','strikethrough','superscript','subscript','code','color','fontSize','fontFamily','link','lang'].map(key=>[key,null]))));
   button('Edit text',()=>{const path=selected?.path;hide();if(path)onTyping?.(path);});
   button('Edit runs',()=>{const path=selected?.path;hide();if(path)onProperties?.(path);});
   button('Done',()=>{hide();win.getSelection()?.removeAllRanges();});

package/dist/rich-text.js

@@ -19,8 +19,10 @@ function range(value, start, end, allowEmpty) {
   if (!boundaries.has(start) || !boundaries.has(end)) throw new RangeError('Text ranges must end at whole grapheme boundaries.');
   return runs(value);
 }
-const booleans = ['bold','italic','underline','strikethrough','superscript','subscript'];
-const strings = ['color','fontFamily','link'];
+const booleans = ['bold','italic','underline','strikethrough','superscript','subscript','code'];
+const strings = ['color','fontFamily','link','lang'];
+// TextRun.lang is a BCP-47 tag (core schema pattern).
+const languageTag = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/;
 function checkedFormat(format) {
   if (!format || typeof format !== 'object' || Array.isArray(format)) throw new TypeError('Expected a run formatting object.');
   for (const [key,value] of Object.entries(format)) {
@@ -29,6 +31,7 @@ function checkedFormat(format) {
     if (booleans.includes(key) && typeof value !== 'boolean' || strings.includes(key) && typeof value !== 'string' || key === 'fontSize' && (!Number.isFinite(value) || value <= 0))
       throw new TypeError(`Invalid run style: ${key}`);
   }
+  if (typeof format.lang === 'string' && !languageTag.test(format.lang)) throw new TypeError('Use a BCP-47 language tag such as fr-FR or ja-JP.');
   if (format.superscript && format.subscript) throw new TypeError('Choose superscript or subscript, not both.');
   return {...format, ...(format.superscript ? {subscript:false} : {}), ...(format.subscript ? {superscript:false} : {})};
 }

package/dist/schema-inspector.d.ts

@@ -1,3 +1,3 @@
 import type { EditorSession } from './index.js';
-export interface SchemaInspector { navigate(path:string|string[]):void; commit():boolean; reset():void; readonly document:any; readonly dirty:boolean; destroy():void; }
-export declare function createSchemaInspector(container:HTMLElement, options:{editor:EditorSession;path?:string;onDraft?:(event:{document:any;path:string;dirty:boolean})=>void;onCommit?:(event:{editor:EditorSession;path:string})=>void;onCancel?:()=>void;onError?:(error:Error)=>void}):SchemaInspector;
+export interface SchemaInspector { navigate(path:string|string[]):void; commit():boolean; reset():void; readonly presentation:any; readonly dirty:boolean; destroy():void; }
+export declare function createSchemaInspector(container:HTMLElement, options:{editor:EditorSession;path?:string;onDraft?:(event:{presentation:any;path:string;dirty:boolean})=>void;onCommit?:(event:{editor:EditorSession;path:string})=>void;onCancel?:()=>void;onError?:(error:Error)=>void}):SchemaInspector;

package/dist/schema-inspector.js

@@ -1,9 +1,11 @@
-import { applyJsonPatch, createValuePatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from './index.js';
+import { applyJsonPatch, createValuePatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from './index.js';
 import { schemaAtPath, schemaVariants, activeSchema, schemaType, schemaLabel, createSchemaValue } from './schema.js';
+import { validate } from "@openpresentation/opf";
+import { checkFormat } from "./checks.js";
 /** A staged form editor; valid drafts preview immediately and Apply creates one undo step. */
 export function createSchemaInspector(container, {editor,path='',onDraft,onCommit,onCancel,onError}={}) {
   if(!editor)throw new Error('An editor session is required.');
-  let base=JSON.stringify(editor.document), draft=structuredClone(editor.document), selected=opfPathToJsonPointer(path), dirty=false, destroyed=false, suppress=false;
+  let base=JSON.stringify(editor.presentation), draft=structuredClone(editor.presentation), selected=opfPathToJsonPointer(path), dirty=false, destroyed=false, suppress=false;
   const doc=container.ownerDocument;
   const el=(tag,text,cls)=>{const node=doc.createElement(tag);if(text!==undefined)node.textContent=text;if(cls)node.className=cls;return node;};
   const button=(text,action)=>{const node=el('button',text);node.type='button';node.onclick=()=>{try{action();}catch(error){showError(error.message);onError?.(error);}};return node;};
@@ -15,24 +17,27 @@ export function createSchemaInspector(container, {editor,path='',onDraft,onCommi
   container.replaceChildren(nav,body,errorBox,actions);container.classList.add('opf-schema-inspector');
   function showError(message){errorBox.textContent=message;}
   function check(){
-    const validation=validateOpfDocument(draft);
+    // The draft must be valid OPF (the format category, as every edit); unresolved references (an unknown variable, a missing asset) are listed as notes.
+    const report=validate(draft,{only:['format','references']});
+    const errors=report.findings.filter(finding=>finding.severity==='error'&&finding.category==='format'),warnings=report.findings.filter(finding=>finding.category!=='format'&&finding.severity!=='info');
+    const validation={valid:!errors.length};
     apply.disabled=!dirty||!validation.valid;
-    const warningNote=validation.warnings?.length?` · ${validation.warnings.length} warning${validation.warnings.length===1?'':'s'}`:'';
+    const warningNote=warnings.length?` · ${warnings.length} warning${warnings.length===1?'':'s'}`:'';
     status.textContent=dirty?`Draft changes · apply to save${warningNote}`:`No pending changes${warningNote}`;
-    const issues=[...(validation.valid?[]:validation.errors.slice(0,3).map(error=>`${error.path||'/'}: ${error.message}`)),...(validation.warnings?.slice(0,2).map(warning=>`${warning.path||'/'}: ${warning.message}`)??[])];
+    const issues=[...(validation.valid?[]:errors.slice(0,3).map(error=>`${error.path||'/'}: ${error.message}`)),...warnings.slice(0,2).map(warning=>`${warning.path||'/'}: ${warning.message}`)];
     showError(issues.join('\n'));
-    if(validation.valid)try{onDraft?.({document:structuredClone(draft),path:selected,dirty});}catch(error){showError(`Preview: ${error.message}`);onError?.(error);}
+    if(validation.valid)try{onDraft?.({presentation:structuredClone(draft),path:selected,dirty});}catch(error){showError(`Preview: ${error.message}`);onError?.(error);}
   }
   function mutate(operations,redraw=true){draft=applyJsonPatch(draft,operations);dirty=JSON.stringify(draft)!==base;if(redraw)render();check();}
   function set(path,value,redraw=true){mutate(createValuePatch(draft,path,value),redraw);}
   function navigate(path){selected=opfPathToJsonPointer(path);render();check();}
-  function reset(){base=JSON.stringify(editor.document);draft=structuredClone(editor.document);dirty=false;render();check();onCancel?.();}
+  function reset(){base=JSON.stringify(editor.presentation);draft=structuredClone(editor.presentation);dirty=false;render();check();onCancel?.();}
   function commit(){
     if(!dirty)return true;
-    if(JSON.stringify(editor.document)!==base){showError('The document changed elsewhere. Discard this draft and reopen the field to avoid overwriting newer changes.');return false;}
-    const result=validateOpfDocument(draft);if(!result.valid){check();return false;}
+    if(JSON.stringify(editor.presentation)!==base){showError('The document changed elsewhere. Discard this draft and reopen the field to avoid overwriting newer changes.');return false;}
+    const result=checkFormat(draft);if(!result.valid){check();return false;}
     suppress=true;
-    try{editor.applyPatch([{op:'replace',path:'',value:draft}],{source:'schema-inspector',rejectInvalid:true});base=JSON.stringify(editor.document);draft=structuredClone(editor.document);dirty=false;render();check();onCommit?.({editor,path:selected});return true;}finally{suppress=false;}
+    try{editor.applyPatch([{op:'replace',path:'',value:draft}],{source:'schema-inspector',rejectInvalid:true});base=JSON.stringify(editor.presentation);draft=structuredClone(editor.presentation);dirty=false;render();check();onCommit?.({editor,path:selected});return true;}finally{suppress=false;}
   }
   function summary(value){return Array.isArray(value)?`${value.length} items`:value&&typeof value==='object'?`${Object.keys(value).length} fields`:String(value??'').slice(0,80);}
   function render(){
@@ -98,5 +103,5 @@ export function createSchemaInspector(container, {editor,path='',onDraft,onCommi
   }
   const unsubscribe=editor.subscribe(()=>{if(suppress)return;if(dirty){showError('The document changed elsewhere. Discard the draft to load the latest version.');apply.disabled=true;}else reset();});
   render();check();
-  return {navigate,commit,reset,get document(){return structuredClone(draft);},get dirty(){return dirty;},destroy(){destroyed=true;unsubscribe();container.replaceChildren();}};
+  return {navigate,commit,reset,get presentation(){return structuredClone(draft);},get dirty(){return dirty;},destroy(){destroyed=true;unsubscribe();container.replaceChildren();}};
 }

package/dist/schema.d.ts

@@ -4,7 +4,7 @@ export declare function resolveSchema(schema: Schema, root?: Schema): Schema;
 export declare function schemaVariants(schema: Schema, root?: Schema): Schema[];
 export declare function schemaType(schema: Schema, value?: unknown): string;
 export declare function activeSchema(schema: Schema, value: unknown, root?: Schema): Schema;
-export declare function schemaAtPath(document: unknown, path: string | string[], root?: Schema): Schema;
+export declare function schemaAtPath(presentation: unknown, path: string | string[], root?: Schema): Schema;
 export declare function schemaLabel(schema: Schema, index?: number): string;
 export declare function createSchemaValue(schema: Schema, root?: Schema): any;
 export declare function listSchemaFields(): Array<{schema:string;path:string;name:string;description:string;reference:string|null;type:string|null;values:unknown[]|null}>;

package/dist/schema.js

@@ -3,9 +3,22 @@ import { getValueAtPath, splitOpfPath, opfPathToJsonPointer } from './index.js';
 export const opfSchemas = schemas;
 const documents = new Map(Object.values(schemas).map(schema => [schema.$id, schema]));
 const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+// An allOf of shaping members (the SlideDesign definition is Design plus a `not` constraint) reads as one schema: members are
+// merged, properties included; constraint-only members (`not`, `required`) shape nothing a picker can show and are dropped.
+function mergeAllOf(schema, root, seen) {
+  if (!Array.isArray(schema.allOf)) return schema;
+  const {allOf, ...base} = schema;
+  let merged = base;
+  for (const member of allOf) {
+    const resolved = resolveSchema(member, root, new Set(seen));
+    if (!resolved.properties && !resolved.type && !resolved.oneOf && !resolved.anyOf) continue;
+    merged = {...resolved, ...merged, ...(resolved.properties || merged.properties ? {properties: {...resolved.properties, ...merged.properties}} : {})};
+  }
+  return merged;
+}
 export function resolveSchema(schema, root = schemas.presentation, seen = new Set()) {
   if (!schema || typeof schema !== 'object') return {};
-  if (!schema.$ref) return schema;
+  if (!schema.$ref) return mergeAllOf(schema, root, seen);
   const ref = schema.$ref;
   if (seen.has(ref)) return {};
   seen.add(ref);
@@ -15,7 +28,7 @@ export function resolveSchema(schema, root = schemas.presentation, seen = new Se
   const resolved = fragment ? getValueAtPath(target, fragment) : target;
   if (!resolved) throw new Error(`Unresolved OPF schema: ${ref}`);
   const { $ref, ...rest } = schema;
-  return {...resolveSchema(resolved, target, seen), ...rest};
+  return mergeAllOf({...resolveSchema(resolved, target, seen), ...rest}, target, seen);
 }
 export function schemaVariants(schema, root = schemas.presentation) {
   const resolved = resolveSchema(schema, root);
@@ -23,7 +36,14 @@ export function schemaVariants(schema, root = schemas.presentation) {
   const variants = resolved.oneOf ?? resolved.anyOf;
   if (!variants) return [resolved];
   const {$ref, oneOf, anyOf, ...base} = resolved;
-  return variants.flatMap(child => schemaVariants(child, root).map(variant => ({...base, ...variant, properties: base.properties || variant.properties ? {...base.properties,...variant.properties} : undefined})));
+  return variants.flatMap(child => schemaVariants(child, root).map(variant => {
+    // A branch that only names required fields (Watermark: exactly one of src and text) adds to the base's required list and is
+    // labelled by them, so the generic form offers "src" and "text" as two forms of one object.
+    const requiredOnly = !variant.type && !variant.properties && !variant.$ref && Array.isArray(variant.required);
+    return {...base, ...variant, properties: base.properties || variant.properties ? {...base.properties,...variant.properties} : undefined,
+      ...(base.required || variant.required ? {required: [...new Set([...(base.required ?? []), ...(variant.required ?? [])])]} : {}),
+      ...(requiredOnly && !variant.title ? {title: variant.required.join(' + ')} : {})};
+  }));
 }
 export function schemaType(schema, value) {
   return schema.type ?? (schema.properties || schema.additionalProperties ? 'object' : schema.items ? 'array' : schema.const !== undefined ? typeof schema.const : value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value === 'undefined' ? 'string' : typeof value);
@@ -45,8 +65,8 @@ function score(schema, value) {
 export function activeSchema(schema, value, root=schemas.presentation) {
   return schemaVariants(schema,root).sort((a,b)=>score(b,value)-score(a,value))[0] ?? {};
 }
-export function schemaAtPath(document, path, root = schemas.presentation) {
-  const parts=splitOpfPath(path);let current=root,value=document;
+export function schemaAtPath(presentation, path, root = schemas.presentation) {
+  const parts=splitOpfPath(path);let current=root,value=presentation;
   for(let index=0; index<parts.length;index++) {
     const key=parts[index], resolved=activeSchema(current,value,root);
     if(parts[0]==='catalogs' && parts[2]==='records' && index===3) current=schemas[catalogSchemaNames[parts[1]]]??{};

package/dist/slide-manager.d.ts

@@ -12,7 +12,7 @@ export interface SlideManagerOptions {
   /** Called when the user chooses or moves to a slide; the host shows it and calls `render()`. */
   setSlideIndex: (index: number) => void;
   /** The thumbnail of one slide as an HTML string (usually the renderer's SVG). Cache it: it is called for every card on every render. */
-  renderThumbnail?: (document: unknown, index: number) => string;
+  renderThumbnail?: (presentation: unknown, index: number) => string;
   /** `"navigator"` (a vertical list, the default) or `"sorter"` (a grid with arrow keys in both directions). */
   variant?: "navigator" | "sorter";
   /** An element to fill with the Duplicate, Delete, Hide and More buttons. */
@@ -20,7 +20,7 @@ export interface SlideManagerOptions {
   /** Show Split and Merge in the slide menu. */
   contentActions?: SlideContentActions;
   /** Layout choices for "Add slide with layout" (default: the layouts catalog, via `listSwitchOptions`). */
-  layoutOptions?: (document: unknown) => { id: string; label: string; record?: Record<string, any> }[];
+  layoutOptions?: (presentation: unknown) => { id: string; label: string; record?: Record<string, any> }[];
   /** Every message the manager announces in its live region, for a visual status line. */
   onStatus?: (message: string) => void;
   onError?: (error: unknown) => void;

package/dist/slide-manager.js

@@ -52,9 +52,9 @@ const isMac = () => /Mac|iPhone|iPad/.test(globalThis.navigator?.platform ?? "")
 
 /**
  * Mount the slide list into `container` (a `nav` or `div`; one `.slide-card` button per slide, with section headers between when the deck has
- * sections). Options: `editor`, `getSlideIndex()`, `setSlideIndex(index)`, `renderThumbnail(document, index)` (an HTML string), `variant`
+ * sections). Options: `editor`, `getSlideIndex()`, `setSlideIndex(index)`, `renderThumbnail(presentation, index)` (an HTML string), `variant`
  * (`"navigator"` or `"sorter"`), `toolbar` (an element to fill with the action buttons), `contentActions` (the RR-26 split and merge
- * functions: `{ splitSlideByBlocks, mergeSlides }`), `layoutOptions(document)` (layout choices for "Add slide with layout"), `onStatus(message)`
+ * functions: `{ splitSlideByBlocks, mergeSlides }`), `layoutOptions(presentation)` (layout choices for "Add slide with layout"), `onStatus(message)`
  * `autoRender` (false to skip the first draw) and `onError(error)`. Returns `{ render, getSelection, setSelection, openLayoutPicker, destroy }`.
  */
 export function createSlideManager(container, options) {
@@ -79,7 +79,7 @@ export function createSlideManager(container, options) {
     : "Up and Down arrows move between slides. Shift plus arrow keys extend the selection. Alt plus Up or Down moves the selected slides. Delete removes them. Press the context menu key for more actions." });
   container.after(hint);
 
-  const deck = () => editor.document;
+  const deck = () => editor.presentation;
   const count = () => deck().slides.length;
   const current = () => Math.max(0, Math.min(count() - 1, options.getSlideIndex()));
   const announce = (message) => {
@@ -107,9 +107,9 @@ export function createSlideManager(container, options) {
     return `${occurrence}:${section.name ?? ""}`;
   }
   function render() {
-    const document = deck();
-    const sections = hasSections(document) ? listSections(document) : [];
-    const slideCount = document.slides.length;
+    const presentation = deck();
+    const sections = hasSections(presentation) ? listSections(presentation) : [];
+    const slideCount = presentation.slides.length;
     selection = new Set([...selection].filter((index) => index < slideCount));
     selection.add(current());
     if (selection.size === 1) anchor = current();
@@ -122,19 +122,19 @@ export function createSlideManager(container, options) {
     const nodes = [];
     const sectionAtStart = new Map(sections.map((section) => [section.start, section]));
     const sectionOfIndex = (index) => sections.find((section) => index >= section.start && index < section.start + section.count);
-    document.slides.forEach((slide, index) => {
+    presentation.slides.forEach((slide, index) => {
       const section = sectionAtStart.get(index);
       if (section) nodes.push(sectionHeader(sections, section));
       const owner = sectionOfIndex(index);
       if (owner && collapsed.has(sectionKey(sections, owner))) return;
-      nodes.push(card(document, slide, index, slideCount));
+      nodes.push(card(presentation, slide, index, slideCount));
     });
     container.replaceChildren(...nodes);
     container.setAttribute("aria-label", variant === "sorter" ? "Slide sorter" : "Slides");
     if (hadFocus) container.querySelector(`.slide-card[data-index="${focusIndex}"]`)?.focus({ preventScroll: false });
     renderToolbar();
   }
-  function card(document, slide, index, slideCount) {
+  function card(presentation, slide, index, slideCount) {
     const selected = selection.has(index);
     const title = slideTitle(slide) || "Untitled slide";
     const hidden = slide.hidden === true;
@@ -150,7 +150,7 @@ export function createSlideManager(container, options) {
     const number = el("span", { class: "thumbnail-number", draggable: "true", text: String(index + 1).padStart(2, "0") });
     const thumbnail = el("span", { class: "thumbnail", "aria-hidden": "true" });
     let html = "";
-    try { html = options.renderThumbnail?.(document, index) ?? ""; } catch { html = "Preview unavailable"; }
+    try { html = options.renderThumbnail?.(presentation, index) ?? ""; } catch { html = "Preview unavailable"; }
     thumbnail.innerHTML = html;
     thumbnail.querySelectorAll("[tabindex]").forEach((node) => node.removeAttribute("tabindex"));
     const label = el("span", { class: "thumbnail-title", text: slideTitle(slide) || "Untitled slide" });
@@ -281,9 +281,9 @@ export function createSlideManager(container, options) {
     } catch (error) { report(error); }
   }
   function sectionNote(index) {
-    const document = deck();
-    if (!hasSections(document)) return "";
-    const name = document.slides[index].section;
+    const presentation = deck();
+    if (!hasSections(presentation)) return "";
+    const name = presentation.slides[index].section;
     return name ? `, in section ${name}` : ", with no section";
   }
   function moveTo(indices, edge) {
@@ -339,8 +339,8 @@ export function createSlideManager(container, options) {
     } catch (error) { report(error); }
   }
   async function sectionPrompt(index) {
-    const document = deck();
-    const hasAny = hasSections(document);
+    const presentation = deck();
+    const hasAny = hasSections(presentation);
     const name = await ask("Add section", "Section name", hasAny ? "" : "Section 1", `The section starts at slide ${index + 1}.`);
     if (name === null) { focusCard(index); return; }
     try {
@@ -380,9 +380,9 @@ export function createSlideManager(container, options) {
 
   function slideMenu() {
     const list = selectedList();
-    const document = deck();
-    const sections = hasSections(document) ? listSections(document) : [];
-    const everyHidden = list.every((index) => document.slides[index].hidden === true);
+    const presentation = deck();
+    const sections = hasSections(presentation) ? listSections(presentation) : [];
+    const everyHidden = list.every((index) => presentation.slides[index].hidden === true);
     const first = list[0];
     const items = [
       { label: list.length > 1 ? `Duplicate ${list.length} slides` : "Duplicate slide", shortcut: `${isMac() ? "⌘" : "Ctrl"}+D`, run: () => act("duplicate") },