@openpresentation/opf-editor 0.12.1 → 0.14.2

package/dist/layout.d.ts

@@ -1,8 +1,8 @@
 import type {ComposedFlow, Composition} from '@openpresentation/opf/composition';
 import type {JsonPatchOperation} from './index.js';
 /** Resize adjacent tracks. Fractions clamp to 5–95%; automatic flows become explicit grids. */
-export declare function prepareTrackResize(document:unknown,flow:ComposedFlow,boundary:number,fraction:number):{
-  document:unknown;patches:JsonPatchOperation[];composition:Composition;fraction:number;
+export declare function prepareTrackResize(presentation:unknown,flow:ComposedFlow,boundary:number,fraction:number):{
+  presentation:unknown;patches:JsonPatchOperation[];composition:Composition;fraction:number;
 };
 
 export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,prepareBlockReplace,createContentBlock} from './blocks.js';

package/dist/layout.js

@@ -1,7 +1,8 @@
-import {getValueAtPath, createValuePatch, applyJsonPatch, validateOpfDocument, opfPathToJsonPointer} from './index.js';
+import { getValueAtPath, createValuePatch, applyJsonPatch, opfPathToJsonPointer } from './index.js';
+import { firstErrorMessage, checkFormat } from "./checks.js";
 
 /** Prepare a validated track resize; the test operation guards its container revision. */
-export function prepareTrackResize(document, flow, boundary, fraction) {
+export function prepareTrackResize(presentation, flow, boundary, fraction) {
   const vertical = flow?.composition?.mode === 'column';
   const tracks = vertical ? flow?.rows : flow?.columns;
   if (!Array.isArray(tracks) || tracks.length < 2 || tracks.length > 12)
@@ -12,7 +13,7 @@ export function prepareTrackResize(document, flow, boundary, fraction) {
     throw new RangeError('Track boundary is out of range.');
   if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
     throw new RangeError('Track fraction must be between zero and one.');
-  const container = getValueAtPath(document,flow.path);
+  const container = getValueAtPath(presentation,flow.path);
   if (!container || typeof container !== 'object') throw new Error('The layout container no longer exists.');
   const effective = flow.composition.weights ?? [];
   const weights = Array.from({length:Math.max(tracks.length,effective.length)},(_,index)=>effective[index]??1);
@@ -25,10 +26,10 @@ export function prepareTrackResize(document, flow, boundary, fraction) {
   const composition={...container.composition,mode:flow.composition.mode??'auto',weights};
   // A drag expresses an explicit arrangement. Preserve the automatic engine's chosen columns.
   if(composition.mode==='auto'){composition.mode='grid';composition.columns=flow.columns.length;}
-  const patches=[{op:'test',path:opfPathToJsonPointer(flow.path),value:structuredClone(container)},...createValuePatch(document,[...flow.path.split('.'),'composition'],composition)];
-  const next=applyJsonPatch(document,patches),validation=validateOpfDocument(next);
-  if(!validation.valid)throw new Error(validation.errors[0]?.message??'Track resize is not valid OPF.');
-  return {document:next,patches,composition,fraction:share};
+  const patches=[{op:'test',path:opfPathToJsonPointer(flow.path),value:structuredClone(container)},...createValuePatch(presentation,[...flow.path.split('.'),'composition'],composition)];
+  const next=applyJsonPatch(presentation,patches),validation=checkFormat(next);
+  if(!validation.valid)throw new Error(firstErrorMessage(validation, 'Track resize is not valid OPF.'));
+  return {presentation:next,patches,composition,fraction:share};
 }
 
 export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,prepareBlockReplace,createContentBlock} from './blocks.js';

package/dist/numbering-panel.js

@@ -8,7 +8,6 @@ import {
   NUMBERING_STYLE_OPTIONS,
   NUMBERING_SUFFIX_OPTIONS,
   findNumberableLists,
-  numberingAvailable,
   numberingState,
   numberingValue,
   setEntryStart,
@@ -36,7 +35,6 @@ function h(doc, tag, attributes = {}, ...children) {
  * `onStatus(message, {error})`.
  */
 export function createNumberingPanel(container, options) {
-  if (!numberingAvailable()) throw new Error("The numbering control needs a core release that ships numbering.");
   const { editor, getTarget, getSlideIndex, onStatus } = options;
   const doc = container.ownerDocument;
   const id = `opf-numbering-${++panelCounter}`;
@@ -58,9 +56,9 @@ export function createNumberingPanel(container, options) {
 
   const currentPath = () => {
     const slide = getSlideIndex?.() ?? 0;
-    const lists = findNumberableLists(editor.document, slide);
+    const lists = findNumberableLists(editor.presentation, slide);
     const wanted = explicit ?? getTarget?.();
-    if (wanted && numberingState(editor.document, wanted)) return { path: wanted, lists };
+    if (wanted && numberingState(editor.presentation, wanted)) return { path: wanted, lists };
     return { path: lists[0]?.path, lists };
   };
 
@@ -100,7 +98,7 @@ export function createNumberingPanel(container, options) {
   function draw(force = false) {
     if (destroyed) return;
     const { path, lists } = currentPath();
-    const state = path ? numberingState(editor.document, path) : undefined;
+    const state = path ? numberingState(editor.presentation, path) : undefined;
     const signature = JSON.stringify([path, state, lists.map((entry) => [entry.path, entry.numbered])]);
     if (!force && signature === drawn) return;
     drawn = signature;

package/dist/numbering.d.ts

@@ -12,8 +12,6 @@ export declare const NUMBERING_SUFFIX_OPTIONS: readonly { value: NumberingSuffix
 export declare const MAX_NUMBERING_LEVELS: 9;
 export declare const MAX_NUMBERING_START: 32767;
 
-/** True when the core this editor runs on composes numbered lists. */
-export declare function numberingAvailable(): boolean;
 
 export interface ListPayloadLocation {
   /** The payload that owns the list ("" for a document-level path is not possible; a slide, region or block). */
@@ -26,11 +24,11 @@ export interface ListPayloadLocation {
   entry?: number;
 }
 /** Where a list lives for a path that points at it or into it (`slides.0.items`, `slides.0.items.2`, `slides.0.left.items.1.text`). */
-export declare function listPayloadAt(document: unknown, path: string): ListPayloadLocation | undefined;
+export declare function listPayloadAt(presentation: unknown, path: string): ListPayloadLocation | undefined;
 
 export interface NumberableList { path: string; payloadPath: string; field: "items" | "bullets"; label: string; count: number; numbered: boolean }
 /** Every list of a slide: path, label, entry count and whether it is numbered. */
-export declare function findNumberableLists(document: unknown, slideIndex: number): NumberableList[];
+export declare function findNumberableLists(presentation: unknown, slideIndex: number): NumberableList[];
 
 /** The shortest `numbering` value for per-level settings (a style name, an object of the non-default fields, or an array). */
 export declare function numberingValue(levels: readonly Partial<NumberingLevel>[]): NumberingValue;
@@ -54,7 +52,7 @@ export interface NumberingState {
   /** The entry the path selects, with its own `start` and the marker it draws. */
   entry?: { index: number; start?: number; marker?: string };
 }
-export declare function numberingState(document: unknown, path: string): NumberingState | undefined;
+export declare function numberingState(presentation: unknown, path: string): NumberingState | undefined;
 
 /** Number a list, change its numbering, or (with `undefined` or `null`) turn it off, as one undoable validated edit. Turning it off also removes the entry `start` values. */
 export declare function setNumbering(editor: EditorSession, path: string, value: NumberingValue | undefined | null, meta?: Record<string, unknown>): unknown;

package/dist/numbering.js

@@ -1,9 +1,8 @@
 // List numbering (RR-33): the headless model behind the numbering control. A list payload (`items` or `bullets`) can
 // carry `numbering`: a style name, a { style, start, suffix } object, or an array with one entry per list level. Every
 // write goes through the session as a validated JSON Patch edit, so each change is one undoable edit. Importing this
-// module needs no DOM. Core is read from the namespace so an older core still loads this module; the writes then
-// throw "numbering-unavailable".
-import * as core from "@openpresentation/opf";
+// module needs no DOM.
+import { listNumbers } from "@openpresentation/opf/composition";
 import { OPFEditorError, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 
 /** The number styles and how each draws, in the order a picker lists them. */
@@ -41,21 +40,12 @@ function checkEditor(editor) {
   }
 }
 
-/** True when the core this editor runs on composes numbered lists (the core that ships `numbering`). */
-export function numberingAvailable() {
-  return typeof core.listNumbers === "function" && typeof core.formatListNumber === "function";
-}
-
-function requireCore() {
-  if (!numberingAvailable()) throw fail("numbering-unavailable", "List numbering needs a core release that ships numbering (@openpresentation/opf after 0.11.4).");
-}
-
 /**
  * Where a list lives for a path that points at it or into it: `slides.0.items`, `slides.0.items.2` or
  * `slides.0.left.items.1.text` all resolve to the payload that owns the list. Returns undefined when the path is not
  * inside a list.
  */
-export function listPayloadAt(document, path) {
+export function listPayloadAt(presentation, path) {
   let segments;
   try {
     segments = splitOpfPath(path);
@@ -67,7 +57,7 @@ export function listPayloadAt(document, path) {
     const next = segments[index + 1];
     if (next !== undefined && !/^\d+$/.test(next)) continue;
     const payloadPath = segments.slice(0, index);
-    const payload = payloadPath.length ? getValueAtPath(document, payloadPath) : document;
+    const payload = payloadPath.length ? getValueAtPath(presentation, payloadPath) : presentation;
     if (!isObject(payload) || !Array.isArray(payload[segments[index]])) continue;
     const entry = next === undefined ? undefined : Number(next);
     return { payloadPath: payloadPath.join("."), field: segments[index], path: [...payloadPath, segments[index]].join("."), payload, entry };
@@ -78,8 +68,8 @@ export function listPayloadAt(document, path) {
 const isRegionKey = (key) => /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/.test(key);
 
 /** Every list (`items` or `bullets`) of a slide: its path, label, entry count and whether it is numbered. */
-export function findNumberableLists(document, slideIndex) {
-  const slide = document?.slides?.[slideIndex];
+export function findNumberableLists(presentation, slideIndex) {
+  const slide = presentation?.slides?.[slideIndex];
   if (!isObject(slide)) return [];
   const found = [];
   const visit = (payload, base, label, depth = 0) => {
@@ -137,8 +127,8 @@ const maxLevelOf = (items) => items.reduce((max, item) => Math.max(max, isObject
  * numbering applies to every level), the number of levels the list uses, the markers it draws and which entry (if any)
  * the path selects with that entry's own `start`.
  */
-export function numberingState(document, path) {
-  const target = listPayloadAt(document, path);
+export function numberingState(presentation, path) {
+  const target = listPayloadAt(presentation, path);
   if (!target) return undefined;
   const { payload, field, entry } = target;
   const items = payload[field];
@@ -147,9 +137,9 @@ export function numberingState(document, path) {
   const levels = numbered ? resolveLevels(numbering) : [{ ...DEFAULT_LEVEL }];
   const depth = Math.min(MAX_NUMBERING_LEVELS, maxLevelOf(items) + 1);
   let markers = [];
-  if (numbered && numberingAvailable()) {
+  if (numbered) {
     try {
-      markers = core.listNumbers(items, numbering).map((number) => ({ index: number.index, level: number.level, text: number.text, value: number.value, adapted: number.adapted }));
+      markers = listNumbers(items, numbering).map((number) => ({ index: number.index, level: number.level, text: number.text, value: number.value, adapted: number.adapted }));
     } catch {
       markers = [];
     }
@@ -180,14 +170,13 @@ function numberingPointer(target) {
  * the entry `start` values, which mean nothing without it. `path` addresses the list or anything inside it.
  */
 export function setNumbering(editor, path, value, meta = {}) {
-  requireCore();
   checkEditor(editor);
-  const target = listPayloadAt(editor.document, path);
+  const target = listPayloadAt(editor.presentation, path);
   if (!target) throw fail("not-a-list", "Select a list (items or bullets) to number.", { path });
   const patches = [];
   const present = Object.hasOwn(target.payload, "numbering");
   if (value === undefined || value === null) {
-    if (!present) return { document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+    if (!present) return { presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
     patches.push({ op: "remove", path: numberingPointer(target) });
     target.payload[target.field].forEach((item, index) => {
       if (isObject(item) && item.start !== undefined) patches.push({ op: "remove", path: opfPathToJsonPointer(`${target.path}.${index}.start`) });
@@ -203,9 +192,8 @@ export function setNumbering(editor, path, value, meta = {}) {
  * removes the restart. A plain entry (a string or runs) becomes the object form to carry it. One undoable validated edit.
  */
 export function setEntryStart(editor, itemPath, start, meta = {}) {
-  requireCore();
   checkEditor(editor);
-  const target = listPayloadAt(editor.document, itemPath);
+  const target = listPayloadAt(editor.presentation, itemPath);
   if (!target || target.entry === undefined) throw fail("not-an-entry", "Select a list entry to restart its numbering.", { path: itemPath });
   if (target.payload.numbering === undefined) throw fail("not-numbered", "Number the list first; an entry start has no effect on a bulleted list.", { path: itemPath });
   const item = target.payload[target.field][target.entry];
@@ -218,6 +206,6 @@ export function setEntryStart(editor, itemPath, start, meta = {}) {
     if (isObject(item)) patches.push({ op: item.start === undefined ? "add" : "replace", path: `${pointer}/start`, value: start });
     else patches.push({ op: "replace", path: pointer, value: { text: structuredClone(item), start } });
   }
-  if (!patches.length) return { document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  if (!patches.length) return { presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   return editor.applyPatch(patches, { source: "list-numbering-start", rejectInvalid: true, ...meta });
 }

package/dist/outline-view.js

@@ -92,9 +92,9 @@ export function createOutlineView(container, options) {
     const firstDraw = !lastSnapshot;
     if (snapshot === lastSnapshot && !pendingFocus) return;
     lastSnapshot = snapshot;
-    const document = editor.document;
-    rows = readOutline(document).rows;
-    const sections = hasSections(document);
+    const presentation = editor.presentation;
+    rows = readOutline(presentation).rows;
+    const sections = hasSections(presentation);
     const entries = [];
     let lastSection;
     for (const row of rows) {
@@ -143,18 +143,18 @@ export function createOutlineView(container, options) {
   function activeRow() { return activeKey ? rowByKey(activeKey) : undefined; }
   function updateTools() {
     const row = activeRow();
-    const document = editor.document;
+    const presentation = editor.presentation;
     const can = { promote: false, demote: false, up: false, down: false, add: Boolean(row) };
     if (row) {
       try {
         if (row.kind === "item") {
-          can.demote = prepareShiftOutlineItem(document, row, 1).changed;
-          can.promote = row.level > 1 ? prepareShiftOutlineItem(document, row, -1).changed : row.editable;
-          can.up = prepareMoveOutlineItem(document, row, -1).changed;
-          can.down = prepareMoveOutlineItem(document, row, 1).changed;
+          can.demote = prepareShiftOutlineItem(presentation, row, 1).changed;
+          can.promote = row.level > 1 ? prepareShiftOutlineItem(presentation, row, -1).changed : row.editable;
+          can.up = prepareMoveOutlineItem(presentation, row, -1).changed;
+          can.down = prepareMoveOutlineItem(presentation, row, 1).changed;
         } else if (row.kind === "slide") {
           can.up = row.slideIndex > 0;
-          can.down = row.slideIndex < document.slides.length - 1;
+          can.down = row.slideIndex < presentation.slides.length - 1;
           can.demote = row.slideIndex > 0;
         }
       } catch { /* a row that vanished mid-edit leaves the tools off */ }
@@ -167,7 +167,7 @@ export function createOutlineView(container, options) {
     if (!row?.editable) return false;
     if (input.value === row.text) return false;
     try {
-      const prepared = prepareSetOutlineText(editor.document, row, input.value);
+      const prepared = prepareSetOutlineText(editor.presentation, row, input.value);
       if (!prepared.changed) return false;
       applyOutlineChange(editor, prepared);
       render();
@@ -203,25 +203,25 @@ export function createOutlineView(container, options) {
     const key = activeKey;
     const row = settle(input ?? inputFor(key), key);
     if (!row) return;
-    const document = editor.document;
+    const presentation = editor.presentation;
     if (action === "add") {
-      if (row.kind === "item") apply(() => prepareInsertOutlineItem(document, row), "Line added");
-      else if (row.kind === "slide") apply(() => prepareAddOutlineBullet(document, row.slideIndex), "Bullet added under the slide title");
+      if (row.kind === "item") apply(() => prepareInsertOutlineItem(presentation, row), "Line added");
+      else if (row.kind === "slide") apply(() => prepareAddOutlineBullet(presentation, row.slideIndex), "Bullet added under the slide title");
       else announce("Add a line from a title or a bullet");
     } else if (action === "demote") {
-      if (row.kind === "item") apply(() => prepareShiftOutlineItem(document, row, 1), () => "Demoted");
-      else if (row.kind === "slide") apply(() => prepareOutlineDemoteSlide(document, row.slideIndex), "Slide joined the slide before it as a bullet");
+      if (row.kind === "item") apply(() => prepareShiftOutlineItem(presentation, row, 1), () => "Demoted");
+      else if (row.kind === "slide") apply(() => prepareOutlineDemoteSlide(presentation, row.slideIndex), "Slide joined the slide before it as a bullet");
       else announce("Only titles and bullets change level");
     } else if (action === "promote") {
       if (row.kind === "item") {
-        if (row.level > 1) apply(() => prepareShiftOutlineItem(document, row, -1), "Promoted");
-        else apply(() => prepareOutlinePromote(document, row), (prepared) => `Promoted to slide ${prepared.newSlideIndex + 1}`);
+        if (row.level > 1) apply(() => prepareShiftOutlineItem(presentation, row, -1), "Promoted");
+        else apply(() => prepareOutlinePromote(presentation, row), (prepared) => `Promoted to slide ${prepared.newSlideIndex + 1}`);
       } else if (row.kind === "slide") announce("Slide titles are already the top level");
       else announce("Only titles and bullets change level");
     } else if (action === "up" || action === "down") {
       const delta = action === "up" ? -1 : 1;
-      if (row.kind === "item") apply(() => prepareMoveOutlineItem(document, row, delta), `Moved ${action}`);
-      else if (row.kind === "slide") apply(() => prepareMoveOutlineSlide(document, row.slideIndex, delta), (prepared) => `Slide moved to position ${prepared.selection[0] + 1} of ${document.slides.length}`);
+      if (row.kind === "item") apply(() => prepareMoveOutlineItem(presentation, row, delta), `Moved ${action}`);
+      else if (row.kind === "slide") apply(() => prepareMoveOutlineSlide(presentation, row.slideIndex, delta), (prepared) => `Slide moved to position ${prepared.selection[0] + 1} of ${presentation.slides.length}`);
       else announce("Move bullets or slides");
     }
   }
@@ -244,18 +244,18 @@ export function createOutlineView(container, options) {
       event.preventDefault();
       const settled = settle(input, key);
       if (!settled) return;
-      const document = editor.document;
-      if (settled.kind === "item") apply(() => prepareInsertOutlineItem(document, settled), "Line added");
-      else if (settled.kind === "slide") apply(() => prepareInsertOutlineSlide(document, settled.slideIndex), (prepared) => `Slide ${prepared.index + 1} added`);
+      const presentation = editor.presentation;
+      if (settled.kind === "item") apply(() => prepareInsertOutlineItem(presentation, settled), "Line added");
+      else if (settled.kind === "slide") apply(() => prepareInsertOutlineSlide(presentation, settled.slideIndex), (prepared) => `Slide ${prepared.index + 1} added`);
       else focusAt(index + 1);
       return;
     }
     if (event.key === "Backspace" && input.value === "" && input.selectionStart === 0 && !input.readOnly) {
-      if (row.kind === "item") { event.preventDefault(); apply(() => prepareRemoveOutlineItem(editor.document, row), "Line removed"); }
+      if (row.kind === "item") { event.preventDefault(); apply(() => prepareRemoveOutlineItem(editor.presentation, row), "Line removed"); }
       else if (row.kind === "slide" && !rows.some((other) => other.slideIndex === row.slideIndex && other.kind !== "slide")) {
         event.preventDefault();
         apply(() => {
-          const prepared = prepareRemoveSlides(editor.document, [row.slideIndex]);
+          const prepared = prepareRemoveSlides(editor.presentation, [row.slideIndex]);
           return { ...prepared, focus: `slide:slides.${Math.max(0, row.slideIndex - 1)}` };
         }, `Slide ${row.slideIndex + 1} removed`);
       }

package/dist/outline.d.ts

@@ -35,22 +35,22 @@ export interface PreparedOutlineChange extends Omit<PreparedSlideChange, "select
   reason?: string;
   newSlideIndex?: number;
 }
-export type OutlineChange = Omit<EditorChange, "document" | "patches"> & Omit<PreparedOutlineChange, "document" | "patches"> & { document: unknown; patches: JsonPatchOperation[] };
+export type OutlineChange = Omit<EditorChange, "presentation" | "patches"> & Omit<PreparedOutlineChange, "presentation" | "patches"> & { presentation: unknown; patches: JsonPatchOperation[] };
 
-export declare function readOutline(document: unknown): Outline;
-export declare function prepareSetOutlineText(document: unknown, row: OutlineRow, text: string): PreparedOutlineChange;
+export declare function readOutline(presentation: unknown): Outline;
+export declare function prepareSetOutlineText(presentation: unknown, row: OutlineRow, text: string): PreparedOutlineChange;
 export declare function setOutlineText(editor: EditorSession, row: OutlineRow, text: string, meta?: Record<string, unknown>): OutlineChange;
 /** Nest (`delta` 1) or un-nest (-1) a list item with the items under it. A top-level item reports `changed: false` and a `reason`. */
-export declare function prepareShiftOutlineItem(document: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
-export declare function prepareMoveOutlineItem(document: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
-export declare function prepareInsertOutlineItem(document: unknown, row: OutlineRow, text?: string): PreparedOutlineChange;
-export declare function prepareAddOutlineBullet(document: unknown, slideIndex: number, text?: string): PreparedOutlineChange;
-export declare function prepareRemoveOutlineItem(document: unknown, row: OutlineRow): PreparedOutlineChange;
+export declare function prepareShiftOutlineItem(presentation: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
+export declare function prepareMoveOutlineItem(presentation: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
+export declare function prepareInsertOutlineItem(presentation: unknown, row: OutlineRow, text?: string): PreparedOutlineChange;
+export declare function prepareAddOutlineBullet(presentation: unknown, slideIndex: number, text?: string): PreparedOutlineChange;
+export declare function prepareRemoveOutlineItem(presentation: unknown, row: OutlineRow): PreparedOutlineChange;
 /** A top-level list item becomes the title of a new slide that takes the items after it. */
-export declare function prepareOutlinePromote(document: unknown, row: OutlineRow): PreparedOutlineChange;
+export declare function prepareOutlinePromote(presentation: unknown, row: OutlineRow): PreparedOutlineChange;
 /** A plain slide becomes a bullet (with its text nested) of the slide before it. Throws `outline-row-not-supported` rather than dropping content. */
-export declare function prepareOutlineDemoteSlide(document: unknown, slideIndex: number): PreparedOutlineChange;
-export declare function prepareMoveOutlineSlide(document: unknown, slideIndex: number, delta: number): PreparedOutlineChange;
-export declare function prepareInsertOutlineSlide(document: unknown, slideIndex: number): PreparedOutlineChange;
+export declare function prepareOutlineDemoteSlide(presentation: unknown, slideIndex: number): PreparedOutlineChange;
+export declare function prepareMoveOutlineSlide(presentation: unknown, slideIndex: number, delta: number): PreparedOutlineChange;
+export declare function prepareInsertOutlineSlide(presentation: unknown, slideIndex: number): PreparedOutlineChange;
 /** Apply any prepared outline change as one undoable step. */
 export declare function applyOutlineChange(editor: EditorSession, prepared: PreparedOutlineChange | PreparedSlideChange, meta?: Record<string, unknown>): OutlineChange;

package/dist/outline.js

@@ -9,10 +9,11 @@
 //   item      one list item or bullet; `listPath` and `itemIndex` locate it and `level` is 1 plus its nesting level
 //   other     content that is not text, shown by its kind (`label`), never edited here
 // Text that carries formatting (a run array) is shown flattened and is not editable in the outline, so nothing is flattened away.
-import { getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
 import { checkedDocument, fail } from "./edit-helpers.js";
 import { visitContentPayloads } from "./presentation-ids.js";
 import { prepareAddSlide, prepareMoveSlidesBy } from "./slides.js";
+import { checkFormat } from "./checks.js";
 
 const clone = (value) => structuredClone(value);
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -46,14 +47,15 @@ function walkPayload(node, path, slideIndex, rows) {
  * Read the deck as outline rows (see the file header). `rows` follow document order: for each slide its title, subtitle, the
  * slide's own text and list, then every block and region in order.
  */
-export function readOutline(document) {
-  if (!document || !Array.isArray(document.slides)) throw fail("invalid-input", "The outline needs an OPF document with a slides array.");
+export function readOutline(presentation) {
+  if (!presentation || !Array.isArray(presentation.slides)) throw fail("invalid-input", "The outline needs an OPF document with a slides array.");
   const rows = [];
-  document.slides.forEach((slide, slideIndex) => {
+  presentation.slides.forEach((slide, slideIndex) => {
     const base = `slides.${slideIndex}`;
-    const title = typeof slide?.title === "string" ? slide.title : "";
+    // FA-10: a title or subtitle may be TextRun[]: the row shows its plain text and is edited as runs elsewhere (a text row writes a string).
+    const title = flatten(slide?.title);
     rows.push({ key: `slide:${base}`, kind: "slide", slideIndex, level: 0, text: title, path: `${base}.title`, editable: slide?.title === undefined || typeof slide.title === "string", hidden: slide?.hidden === true, section: typeof slide?.section === "string" ? slide.section : undefined, id: slide?.id });
-    if (typeof slide?.subtitle === "string") rows.push({ key: `subtitle:${base}.subtitle`, kind: "subtitle", slideIndex, level: 1, text: slide.subtitle, path: `${base}.subtitle`, editable: true });
+    if (typeof slide?.subtitle === "string" || Array.isArray(slide?.subtitle)) rows.push({ key: `subtitle:${base}.subtitle`, kind: "subtitle", slideIndex, level: 1, text: flatten(slide.subtitle), path: `${base}.subtitle`, editable: typeof slide.subtitle === "string" });
     if (!isObject(slide)) return;
     walkPayload(slide, base, slideIndex, rows);
     visitContentPayloads(slide, base, (payload, path) => walkPayload(payload, path, slideIndex, rows));
@@ -64,23 +66,23 @@ export function readOutline(document) {
 // --- text ------------------------------------------------------------------------------------------
 
 /** Compute editing the text of a row (a title, subtitle, text paragraph or list item); a row that is not plain text throws. */
-export function prepareSetOutlineText(document, row, text) {
+export function prepareSetOutlineText(presentation, row, text) {
   if (!row?.editable) throw fail("outline-row-not-editable", "This text carries formatting or is not text. Edit it on the slide.", { path: row?.path });
   const value = String(text);
-  const current = getValueAtPath(document, splitOpfPath(row.path));
-  if (current === value || (current === undefined && value === "")) return { document: clone(document), patches: [], changed: false, selection: [row.slideIndex] };
+  const current = getValueAtPath(presentation, splitOpfPath(row.path));
+  if (current === value || (current === undefined && value === "")) return { presentation: clone(presentation), patches: [], changed: false, selection: [row.slideIndex] };
   const pointer = opfPathToJsonPointer(row.path);
   const patches = [{ op: current === undefined ? "add" : "replace", path: pointer, value }];
-  return finish(document, patches, { action: "outline-text", selection: [row.slideIndex] });
+  return finish(presentation, patches, { action: "outline-text", selection: [row.slideIndex] });
 }
 export function setOutlineText(editor, row, text, meta) {
-  return apply(editor, prepareSetOutlineText(editor.document, row, text), meta, "outline-text");
+  return apply(editor, prepareSetOutlineText(editor.presentation, row, text), meta, "outline-text");
 }
 
 // --- list levels -----------------------------------------------------------------------------------
 
-function listAt(document, row) {
-  const list = getValueAtPath(document, splitOpfPath(row.listPath));
+function listAt(presentation, row) {
+  const list = getValueAtPath(presentation, splitOpfPath(row.listPath));
   if (!Array.isArray(list) || list[row.itemIndex] === undefined) throw fail("outline-row-not-found", "That list item is no longer there.", { path: row.listPath });
   return list;
 }
@@ -104,17 +106,17 @@ function blockEnd(levels, index) {
  * than the item above, and the first item cannot be nested. Un-nesting an item that is already at the top level is
  * `prepareOutlinePromote`'s job (it becomes a slide); here it reports `changed: false` with a `reason`.
  */
-export function prepareShiftOutlineItem(document, row, delta) {
-  const list = listAt(document, row);
+export function prepareShiftOutlineItem(presentation, row, delta) {
+  const list = listAt(presentation, row);
   const levels = list.map((item) => itemParts(item).level);
   const index = row.itemIndex;
-  const none = (reason) => ({ document: clone(document), patches: [], changed: false, reason, selection: [row.slideIndex] });
+  const none = (reason) => ({ presentation: clone(presentation), patches: [], changed: false, reason, selection: [row.slideIndex] });
   if (delta > 0 && (index === 0 || levels[index] > levels[index - 1])) return none(index === 0 ? "The first item cannot be nested." : "This item is already one level in from the item above.");
   if (delta < 0 && levels[index] === 0) return none("This item is already at the top level.");
   const end = blockEnd(levels, index);
   const next = list.map((item, at) => (at >= index && at < end ? withLevel(item, Math.max(0, levels[at] + delta)) : item));
   const patches = [{ op: "replace", path: opfPathToJsonPointer(row.listPath), value: next }];
-  return finish(document, patches, { action: delta > 0 ? "outline-demote" : "outline-promote", selection: [row.slideIndex], focus: `item:${row.listPath}.${index}` });
+  return finish(presentation, patches, { action: delta > 0 ? "outline-demote" : "outline-promote", selection: [row.slideIndex], focus: `item:${row.listPath}.${index}` });
 }
 
 // --- item order ------------------------------------------------------------------------------------
@@ -123,11 +125,11 @@ export function prepareShiftOutlineItem(document, row, delta) {
  * Compute moving a list item (with the items nested under it) one place up (`delta` -1) or down (1) among the items at its level
  * and under the same parent. At the first or last place nothing changes (`changed` is false).
  */
-export function prepareMoveOutlineItem(document, row, delta) {
-  const list = listAt(document, row);
+export function prepareMoveOutlineItem(presentation, row, delta) {
+  const list = listAt(presentation, row);
   const levels = list.map((item) => itemParts(item).level);
   const index = row.itemIndex, end = blockEnd(levels, index);
-  const none = { document: clone(document), patches: [], changed: false, selection: [row.slideIndex] };
+  const none = { presentation: clone(presentation), patches: [], changed: false, selection: [row.slideIndex] };
   let order, focusIndex;
   if (delta < 0) {
     // The previous sibling starts at the nearest earlier item on the same level, provided no shallower item lies between.
@@ -143,32 +145,32 @@ export function prepareMoveOutlineItem(document, row, delta) {
     focusIndex = index + (siblingEnd - end);
   }
   const patches = [{ op: "replace", path: opfPathToJsonPointer(row.listPath), value: order }];
-  return finish(document, patches, { action: "outline-move", selection: [row.slideIndex], focus: `item:${row.listPath}.${focusIndex}` });
+  return finish(presentation, patches, { action: "outline-move", selection: [row.slideIndex], focus: `item:${row.listPath}.${focusIndex}` });
 }
 
 // --- insert and delete -----------------------------------------------------------------------------
 
 /** Compute adding an empty list item right after the item at `row` and everything nested under it, at the same level. */
-export function prepareInsertOutlineItem(document, row, text = "") {
-  const list = listAt(document, row);
+export function prepareInsertOutlineItem(presentation, row, text = "") {
+  const list = listAt(presentation, row);
   const levels = list.map((item) => itemParts(item).level);
   const end = blockEnd(levels, row.itemIndex);
   const item = levels[row.itemIndex] > 0 ? { text, level: levels[row.itemIndex] } : text;
-  return finish(document, [{ op: "add", path: `${opfPathToJsonPointer(row.listPath)}/${end}`, value: item }], { action: "outline-insert", selection: [row.slideIndex], focus: `item:${row.listPath}.${end}` });
+  return finish(presentation, [{ op: "add", path: `${opfPathToJsonPointer(row.listPath)}/${end}`, value: item }], { action: "outline-insert", selection: [row.slideIndex], focus: `item:${row.listPath}.${end}` });
 }
 /** Compute adding the first bullet under a slide: it goes in the slide's own list, or creates one. */
-export function prepareAddOutlineBullet(document, slideIndex, text = "") {
-  const slide = document.slides?.[slideIndex];
+export function prepareAddOutlineBullet(presentation, slideIndex, text = "") {
+  const slide = presentation.slides?.[slideIndex];
   if (!isObject(slide)) throw fail("slide-index-out-of-range", `Slide ${slideIndex} does not exist.`, { slideIndex });
   const key = LIST_KEYS.find((candidate) => Array.isArray(slide[candidate]));
   const base = `/slides/${slideIndex}`;
-  if (key) return finish(document, [{ op: "add", path: `${base}/${key}/${slide[key].length}`, value: text }], { action: "outline-insert", selection: [slideIndex], focus: `item:slides.${slideIndex}.${key}.${slide[key].length}` });
+  if (key) return finish(presentation, [{ op: "add", path: `${base}/${key}/${slide[key].length}`, value: text }], { action: "outline-insert", selection: [slideIndex], focus: `item:slides.${slideIndex}.${key}.${slide[key].length}` });
   if (Array.isArray(slide.blocks) || slide.type !== undefined) throw fail("outline-row-not-supported", "Add a list to this slide from the Content panel; its content is arranged in blocks.", { slideIndex });
-  return finish(document, [{ op: "add", path: `${base}/items`, value: [text] }], { action: "outline-insert", selection: [slideIndex], focus: `item:slides.${slideIndex}.items.0` });
+  return finish(presentation, [{ op: "add", path: `${base}/items`, value: [text] }], { action: "outline-insert", selection: [slideIndex], focus: `item:slides.${slideIndex}.items.0` });
 }
 /** Compute deleting a list item together with the items nested under it. */
-export function prepareRemoveOutlineItem(document, row) {
-  const list = listAt(document, row);
+export function prepareRemoveOutlineItem(presentation, row) {
+  const list = listAt(presentation, row);
   const levels = list.map((item) => itemParts(item).level);
   const end = blockEnd(levels, row.itemIndex);
   const patches = [];
@@ -178,7 +180,7 @@ export function prepareRemoveOutlineItem(document, row) {
   const removeList = survivors === 0 && row.listPath.split(".").length === 3;
   const finalPatches = removeList ? [{ op: "remove", path: opfPathToJsonPointer(row.listPath) }] : patches;
   const focus = survivors ? `item:${row.listPath}.${Math.max(0, row.itemIndex - 1)}` : `slide:slides.${row.slideIndex}`;
-  return finish(document, finalPatches, { action: "outline-remove", selection: [row.slideIndex], focus });
+  return finish(presentation, finalPatches, { action: "outline-remove", selection: [row.slideIndex], focus });
 }
 
 // --- promote and demote across slides --------------------------------------------------------------
@@ -187,14 +189,14 @@ export function prepareRemoveOutlineItem(document, row) {
  * Compute promoting a top-level list item to a slide: the item becomes the title of a new slide right after its own, and the items that
  * follow it in the same list move to that slide (PowerPoint's outline does the same). Items above it stay.
  */
-export function prepareOutlinePromote(document, row) {
-  const list = listAt(document, row);
+export function prepareOutlinePromote(presentation, row) {
+  const list = listAt(presentation, row);
   const title = itemParts(list[row.itemIndex]);
   if (title.level !== 0) throw fail("outline-row-not-supported", "Only a top-level item becomes a slide.", { path: row.path });
   if (!title.plain) throw fail("outline-row-not-editable", "This item carries formatting. Edit it on the slide.", { path: row.path });
   const following = list.slice(row.itemIndex + 1);
-  const added = prepareAddSlide(document, { at: row.slideIndex + 1, title: title.text });
-  const slide = clone(added.document.slides[row.slideIndex + 1]);
+  const added = prepareAddSlide(presentation, { at: row.slideIndex + 1, title: title.text });
+  const slide = clone(added.presentation.slides[row.slideIndex + 1]);
   const key = row.listPath.endsWith(".bullets") ? "bullets" : "items";
   if (following.length) slide[key] = clone(following);
   const pointer = opfPathToJsonPointer(row.listPath);
@@ -204,7 +206,7 @@ export function prepareOutlinePromote(document, row) {
     ? [{ op: "remove", path: pointer }]
     : Array.from({ length: list.length - row.itemIndex }, (_, offset) => ({ op: "remove", path: `${pointer}/${list.length - 1 - offset}` }));
   const patches = [...removal, { op: "add", path: `/slides/${row.slideIndex + 1}`, value: slide }];
-  return finish(document, patches, { action: "outline-promote-slide", selection: [row.slideIndex + 1], focus: `slide:slides.${row.slideIndex + 1}`, newSlideIndex: row.slideIndex + 1 });
+  return finish(presentation, patches, { action: "outline-promote-slide", selection: [row.slideIndex + 1], focus: `slide:slides.${row.slideIndex + 1}`, newSlideIndex: row.slideIndex + 1 });
 }
 
 const MERGEABLE = new Set(["id", "title", "text", "items", "bullets", "section", "hidden"]);
@@ -213,8 +215,8 @@ const MERGEABLE = new Set(["id", "title", "text", "items", "bullets", "section",
  * beneath it. Only a plain slide qualifies: one with a title and at most text or a list (no blocks, regions, notes, design or layout),
  * after a slide that has a list of its own or no body. Anything else throws `outline-row-not-supported` so nothing is dropped.
  */
-export function prepareOutlineDemoteSlide(document, slideIndex) {
-  const slides = document.slides;
+export function prepareOutlineDemoteSlide(presentation, slideIndex) {
+  const slides = presentation.slides;
   const slide = slides?.[slideIndex];
   if (!isObject(slide)) throw fail("slide-index-out-of-range", `Slide ${slideIndex} does not exist.`, { slideIndex });
   if (slideIndex === 0) throw fail("outline-row-not-supported", "The first slide has no slide before it to join.", { slideIndex });
@@ -231,36 +233,36 @@ export function prepareOutlineDemoteSlide(document, slideIndex) {
   const added = [slide.title, ...(typeof slide.text === "string" && slide.text ? [{ text: slide.text, level: 1 }] : []), ...nested];
   const base = `/slides/${slideIndex - 1}`;
   const patches = [{ op: "remove", path: `/slides/${slideIndex}` }, listKey ? { op: "replace", path: `${base}/${key}`, value: [...previous[key], ...added] } : { op: "add", path: `${base}/${key}`, value: added }];
-  return finish(document, patches, { action: "outline-demote-slide", selection: [slideIndex - 1], focus: `item:slides.${slideIndex - 1}.${key}.${(previous[key]?.length ?? 0)}` });
+  return finish(presentation, patches, { action: "outline-demote-slide", selection: [slideIndex - 1], focus: `item:slides.${slideIndex - 1}.${key}.${(previous[key]?.length ?? 0)}` });
 }
 
 // --- slides ----------------------------------------------------------------------------------------
 
 /** Compute moving a slide (the whole slide: its text moves with its title) by `delta` places; see `prepareMoveSlidesBy`. */
-export function prepareMoveOutlineSlide(document, slideIndex, delta) {
-  const prepared = prepareMoveSlidesBy(document, [slideIndex], delta);
+export function prepareMoveOutlineSlide(presentation, slideIndex, delta) {
+  const prepared = prepareMoveSlidesBy(presentation, [slideIndex], delta);
   return prepared.changed ? { ...prepared, focus: `slide:slides.${prepared.selection[0]}` } : prepared;
 }
 /** Compute adding a slide right after `slideIndex`, with an empty title for the outline to type into. */
-export function prepareInsertOutlineSlide(document, slideIndex) {
-  return { ...prepareAddSlide(document, { at: slideIndex + 1, title: "" }), action: "outline-insert-slide", focus: `slide:slides.${slideIndex + 1}` };
+export function prepareInsertOutlineSlide(presentation, slideIndex) {
+  return { ...prepareAddSlide(presentation, { at: slideIndex + 1, title: "" }), action: "outline-insert-slide", focus: `slide:slides.${slideIndex + 1}` };
 }
 
 // --- apply -----------------------------------------------------------------------------------------
 
-function finish(document, patches, extra) {
-  if (!patches.length) return { document: clone(document), patches: [], changed: false, ...extra };
-  const before = validateOpfDocument(document);
-  return { document: checkedDocument(document, patches, before), patches, changed: true, ...extra };
+function finish(presentation, patches, extra) {
+  if (!patches.length) return { presentation: clone(presentation), patches: [], changed: false, ...extra };
+  const before = checkFormat(presentation);
+  return { presentation: checkedDocument(presentation, patches, before), patches, changed: true, ...extra };
 }
 function requireEditor(editor) {
   if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
 }
 function apply(editor, prepared, meta, action) {
   requireEditor(editor);
-  const { document, patches, ...summary } = prepared;
-  void document;
-  if (!prepared.changed) return { ...summary, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const { presentation, patches, ...summary } = prepared;
+  void presentation;
+  if (!prepared.changed) return { ...summary, presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
   const change = editor.applyPatch(patches, { ...meta, source: meta?.source ?? "outline", action });
   return { ...change, ...summary };
 }