@openpresentation/opf-editor 0.10.6 → 0.11.0

package/dist/outline.js

@@ -0,0 +1,271 @@
+// Outline model and edits (RR-21). The outline is the deck as text: one row per slide title, with the slide's text, bullets and
+// subtitle beneath it and a read-only chip for content that is not text (a chart, a table, an image). Every edit is one validated
+// patch and one undo step, like the slide operations in `slides.js`.
+//
+// Rows. `readOutline` returns `{ rows }`. A row is `{ key, kind, slideIndex, level, text, path, editable, ... }`:
+//   slide     the slide title (`path` is `slides.N.title`; a slide with no title still has a row)
+//   subtitle  the slide subtitle
+//   text      a text payload that is a plain string
+//   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 { checkedDocument, fail } from "./edit-helpers.js";
+import { visitContentPayloads } from "./presentation-ids.js";
+import { prepareAddSlide, prepareMoveSlidesBy } from "./slides.js";
+
+const clone = (value) => structuredClone(value);
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const OTHER_LABELS = { image: "Image", video: "Video", chart: "Chart", table: "Table", code: "Code", metric: "Metric", quote: "Quote", timeline: "Timeline" };
+const LIST_KEYS = ["items", "bullets"];
+
+const flatten = (value) => (typeof value === "string" ? value : Array.isArray(value) ? value.map((run) => (typeof run === "string" ? run : (run?.text ?? ""))).join("") : "");
+/** The text, level and editability of one list item or bullet. */
+function itemParts(item) {
+  if (isObject(item)) return { text: flatten(item.text), level: Number.isInteger(item.level) ? item.level : 0, plain: typeof item.text === "string", object: true };
+  return { text: flatten(item), level: 0, plain: typeof item === "string", object: false };
+}
+const itemTextPath = (listPath, index, item) => (isObject(item) ? `${listPath}.${index}.text` : `${listPath}.${index}`);
+
+function walkPayload(node, path, slideIndex, rows) {
+  for (const key of LIST_KEYS) {
+    if (!Array.isArray(node[key])) continue;
+    const listPath = `${path}.${key}`;
+    node[key].forEach((item, itemIndex) => {
+      const parts = itemParts(item);
+      rows.push({ key: `item:${listPath}.${itemIndex}`, kind: "item", slideIndex, level: 1 + parts.level, text: parts.text, path: itemTextPath(listPath, itemIndex, item), listPath, itemIndex, editable: parts.plain });
+    });
+  }
+  if (node.text !== undefined && (typeof node.text === "string" || Array.isArray(node.text)))
+    rows.push({ key: `text:${path}.text`, kind: "text", slideIndex, level: 1, text: flatten(node.text), path: `${path}.text`, editable: typeof node.text === "string" });
+  for (const [field, label] of Object.entries(OTHER_LABELS))
+    if (node[field] !== undefined) rows.push({ key: `other:${path}.${field}`, kind: "other", slideIndex, level: 1, text: "", path: `${path}.${field}`, label, editable: false });
+}
+
+/**
+ * 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.");
+  const rows = [];
+  document.slides.forEach((slide, slideIndex) => {
+    const base = `slides.${slideIndex}`;
+    const title = typeof slide?.title === "string" ? 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 (!isObject(slide)) return;
+    walkPayload(slide, base, slideIndex, rows);
+    visitContentPayloads(slide, base, (payload, path) => walkPayload(payload, path, slideIndex, rows));
+  });
+  return { rows };
+}
+
+// --- 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) {
+  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 pointer = opfPathToJsonPointer(row.path);
+  const patches = [{ op: current === undefined ? "add" : "replace", path: pointer, value }];
+  return finish(document, 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");
+}
+
+// --- list levels -----------------------------------------------------------------------------------
+
+function listAt(document, row) {
+  const list = getValueAtPath(document, 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;
+}
+/** Write a nesting level on an item, collapsing back to the plain string form at level 0 when nothing else is carried. */
+function withLevel(item, level) {
+  if (!isObject(item)) return level > 0 ? { text: item, level } : item;
+  const next = { ...item };
+  if (level > 0) next.level = level;
+  else delete next.level;
+  return Object.keys(next).length === 1 && typeof next.text === "string" ? next.text : next;
+}
+/** The index just after the item at `index` and everything nested beneath it. */
+function blockEnd(levels, index) {
+  let end = index + 1;
+  while (end < levels.length && levels[end] > levels[index]) end += 1;
+  return end;
+}
+
+/**
+ * Compute nesting a list item in (`delta` 1) or out (`delta` -1). Items nested beneath it move with it. A level is at most one more
+ * 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);
+  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] });
+  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}` });
+}
+
+// --- item order ------------------------------------------------------------------------------------
+
+/**
+ * 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);
+  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] };
+  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.
+    let at = index - 1;
+    while (at >= 0 && levels[at] > levels[index]) at -= 1;
+    if (at < 0 || levels[at] !== levels[index]) return none;
+    order = [...list.slice(0, at), ...list.slice(index, end), ...list.slice(at, index), ...list.slice(end)];
+    focusIndex = at;
+  } else {
+    if (end >= list.length || levels[end] !== levels[index]) return none;
+    const siblingEnd = blockEnd(levels, end);
+    order = [...list.slice(0, index), ...list.slice(end, siblingEnd), ...list.slice(index, end), ...list.slice(siblingEnd)];
+    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}` });
+}
+
+// --- 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);
+  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}` });
+}
+/** 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];
+  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 (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` });
+}
+/** Compute deleting a list item together with the items nested under it. */
+export function prepareRemoveOutlineItem(document, row) {
+  const list = listAt(document, row);
+  const levels = list.map((item) => itemParts(item).level);
+  const end = blockEnd(levels, row.itemIndex);
+  const patches = [];
+  for (let at = end - 1; at >= row.itemIndex; at -= 1) patches.push({ op: "remove", path: `${opfPathToJsonPointer(row.listPath)}/${at}` });
+  const survivors = list.length - (end - row.itemIndex);
+  // An empty `items` array is not a useful list: drop it with its last item.
+  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 });
+}
+
+// --- promote and demote across slides --------------------------------------------------------------
+
+/**
+ * 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);
+  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 key = row.listPath.endsWith(".bullets") ? "bullets" : "items";
+  if (following.length) slide[key] = clone(following);
+  const pointer = opfPathToJsonPointer(row.listPath);
+  const rootList = row.listPath.split(".").length === 3;
+  // Take the item and everything after it out of the old list (the whole list goes when nothing is left above the item).
+  const removal = row.itemIndex === 0 && rootList
+    ? [{ 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 });
+}
+
+const MERGEABLE = new Set(["id", "title", "text", "items", "bullets", "section", "hidden"]);
+/**
+ * Compute demoting a slide: its title becomes a top-level bullet of the previous slide and its own text and bullets nest one level
+ * 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;
+  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 });
+  const extra = Object.keys(slide).filter((key) => !MERGEABLE.has(key));
+  if (extra.length) throw fail("outline-row-not-supported", `This slide also has ${extra.join(", ")}, which would be lost. Merge it from the slide menu or move that content first.`, { slideIndex, keys: extra });
+  if (typeof slide.title !== "string" || slide.title === "" || (slide.text !== undefined && typeof slide.text !== "string")) throw fail("outline-row-not-supported", "Only a slide with a plain title and plain text can join the slide before it.", { slideIndex });
+  const previous = slides[slideIndex - 1];
+  const body = ["text", "items", "bullets", "blocks", "image", "video", "chart", "table", "code", "metric", "quote", "timeline"].filter((key) => previous[key] !== undefined);
+  const listKey = LIST_KEYS.find((key) => Array.isArray(previous[key]));
+  if (body.length && !(listKey && body.length === 1) && !(listKey && body.length === 2 && previous.text !== undefined))
+    throw fail("outline-row-not-supported", "The slide before this one has content that is not a list, so this slide cannot become a bullet there.", { slideIndex });
+  const key = listKey ?? "items";
+  const nested = LIST_KEYS.flatMap((field) => (Array.isArray(slide[field]) ? slide[field] : [])).map((item) => withLevel(item, itemParts(item).level + 1));
+  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)}` });
+}
+
+// --- 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);
+  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}` };
+}
+
+// --- 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 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 change = editor.applyPatch(patches, { ...meta, source: meta?.source ?? "outline", action });
+  return { ...change, ...summary };
+}
+
+/** Apply any prepared outline change as one undoable step. */
+export function applyOutlineChange(editor, prepared, meta) {
+  return apply(editor, prepared, meta, prepared.action ?? "outline");
+}

package/dist/persistence-ui.d.ts

@@ -0,0 +1,24 @@
+import type { AutosaveStatus, RestoreChoice, RestoreOffer } from "./persistence.js";
+
+export interface PersistenceUiOptions {
+  /** The element the restore prompt is drawn in (hidden when there is nothing to offer). */
+  banner?: HTMLElement;
+  /** An element for the one-line autosave status ("Saved on this device at 2:03 PM", or why autosave is off). */
+  indicator?: HTMLElement;
+  locale?: string;
+  /** Appended to the status sentence in the indicator (for example "Save an OPF file to keep a copy."). */
+  suffix?: string;
+  /** What the indicator shows until storage reports (and when a status has no sentence); lines are split on a newline. */
+  fallback?: string;
+  /** Wired to `persistence.restoreEarlier` for the "Restore older copy" button. */
+  restoreEarlier?: () => Promise<boolean>;
+}
+export interface PersistenceUi {
+  /** Pass as `onRestorePrompt` of `createPersistence`. */
+  prompt(offer: RestoreOffer, actions: { restore(): Promise<boolean>; discard(): Promise<boolean> }): RestoreChoice;
+  /** Pass as `onStatus` of `createPersistence`. */
+  status(status: AutosaveStatus): void;
+  hide(): void;
+  destroy(): void;
+}
+export declare function createPersistenceUi(options: PersistenceUiOptions): PersistenceUi;

package/dist/persistence-ui.js

@@ -0,0 +1,81 @@
+// The restore prompt and the autosave indicator for `createPersistence` (RR-22), as plain DOM a host can mount or ignore. The prompt is a
+// non-modal region with two buttons (nothing steals focus or blocks editing); the indicator is a short line of text, and the problems
+// (storage unavailable, full) are also announced in a polite live region. Importing needs no DOM; mounting does.
+import { describeAutosave } from "./persistence.js";
+
+function el(doc, tag, props = {}, ...children) {
+  const node = doc.createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key === "class") node.className = value;
+    else if (key === "text") node.textContent = value;
+    else node.setAttribute(key, value === true ? "" : String(value));
+  }
+  node.append(...children.filter((child) => child !== null && child !== undefined && child !== false));
+  return node;
+}
+const when = (savedAt, locale) => new Date(savedAt).toLocaleString(locale, { dateStyle: "medium", timeStyle: "short" });
+const slides = (count) => (Number.isInteger(count) ? `${count} slide${count === 1 ? "" : "s"}` : "");
+
+/**
+ * Build the prompt and the indicator. Options: `banner` (the element the prompt is drawn in; it is hidden when there is nothing to
+ * offer), `indicator` (an element for the one-line autosave status) and `locale`. Pass `ui.prompt` as `onRestorePrompt` and `ui.status` as
+ * `onStatus` of `createPersistence`.
+ */
+export function createPersistenceUi(options) {
+  const { banner, indicator, locale } = options;
+  const doc = (banner ?? indicator).ownerDocument;
+  const live = el(doc, "div", { class: "sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" });
+  (banner ?? indicator).after(live);
+  let announced = "";
+  const say = (message) => {
+    if (!message || message === announced) return;
+    announced = message;
+    live.textContent = "";
+    globalThis.setTimeout(() => { live.textContent = message; }, 20);
+  };
+  if (banner) { banner.hidden = true; }
+
+  function hide() {
+    if (banner) { banner.hidden = true; banner.replaceChildren(); }
+  }
+  const ui = {
+    /** `onRestorePrompt`: draw the offer. The buttons call `actions.restore` and `actions.discard`; the promise stays "later" (the buttons decide). */
+    prompt(offer, actions) {
+      if (!banner) return "later";
+      const intro = offer.dirty
+        ? `You have unsaved work from ${when(offer.savedAt, locale)}${offer.slideCount ? ` (${slides(offer.slideCount)})` : ""}, kept in this browser. Restore it?`
+        : `Your last session from ${when(offer.savedAt, locale)}${offer.slideCount ? ` (${slides(offer.slideCount)})` : ""} is kept in this browser. Open it again?`;
+      const note = offer.earlier ? el(doc, "p", { class: "restore-note", text: `An older copy from ${when(offer.earlier.savedAt, locale)} is also kept.` }) : null;
+      const restore = el(doc, "button", { type: "button", class: "primary restore-yes", text: "Restore" });
+      const discard = el(doc, "button", { type: "button", class: "secondary restore-no", text: "Discard copy", title: "Delete the stored copy" });
+      const earlier = offer.earlier ? el(doc, "button", { type: "button", class: "secondary restore-earlier", text: "Restore older copy" }) : null;
+      restore.addEventListener("click", async () => { restore.disabled = discard.disabled = true; const done = await actions.restore(); if (done) { hide(); say("Restored. Undo goes back to what you had."); } else { restore.disabled = discard.disabled = false; } });
+      discard.addEventListener("click", async () => { await actions.discard(); hide(); say("Discarded the stored copy."); });
+      earlier?.addEventListener("click", async () => { const done = await options.restoreEarlier?.(); if (done) { hide(); say("Restored the older copy. Undo goes back to what you had."); } });
+      banner.replaceChildren(el(doc, "p", { class: "restore-text", id: `${banner.id || "restore"}-text`, text: intro }), note, el(doc, "div", { class: "restore-actions" }, restore, discard, earlier));
+      banner.setAttribute("role", "region");
+      banner.setAttribute("aria-label", "Restore your work");
+      banner.hidden = false;
+      say(intro);
+      return "later";
+    },
+    /** `onStatus`: update the indicator and announce problems. */
+    status(status) {
+      const text = describeAutosave(status, { locale });
+      if (indicator) {
+        // The indicator keeps its own fallback line until storage reports; a problem keeps the suffix too, so it still says how to keep the work.
+        if (text) indicator.textContent = options.suffix ? `${text}${/[.!?]$/.test(text) ? "" : "."} ${options.suffix}` : text;
+        else if (options.fallback !== undefined) indicator.replaceChildren(...String(options.fallback).split("\n").flatMap((line, at) => (at ? [doc.createElement("br"), line] : [line])));
+        else indicator.textContent = "";
+        indicator.dataset.state = status.state;
+        if (!options.fallback) indicator.hidden = !text;
+      }
+      if (status.state === "unavailable" || status.state === "error") say(status.message);
+    },
+    /** Hide the prompt (for example after the host restored through its own control). */
+    hide,
+    destroy() { hide(); live.remove(); if (indicator) indicator.textContent = ""; },
+  };
+  return ui;
+}

package/dist/persistence.d.ts

@@ -0,0 +1,105 @@
+import type { EditorSession } from "./index.js";
+
+/** What a storage adapter holds: plain JSON-able records under string keys. */
+export interface PersistenceStorage {
+  name?: string;
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+export declare function createMemoryStorage(): PersistenceStorage & { keys(): string[] };
+export declare function createLocalStorageStorage(options?: { storage?: Storage }): PersistenceStorage;
+export declare function createIndexedDbStorage(options?: { indexedDB?: IDBFactory; databaseName?: string; storeName?: string }): PersistenceStorage & { probe(): Promise<void> };
+
+/** A stored copy on offer. */
+export interface RestoreOffer {
+  key: string;
+  /** When it was stored (ms since the epoch). */
+  savedAt: number;
+  name?: string;
+  slideCount?: number;
+  /** True when it held changes that had not been saved elsewhere (`markSaved`); false for a copy saved as a file. */
+  dirty: boolean;
+  /** Whether the undo history is stored with it. */
+  hasHistory: boolean;
+  document: unknown;
+  /** An older copy that was moved aside when the user kept editing while an earlier offer was open. */
+  earlier?: { savedAt: number; name?: string; slideCount?: number };
+}
+export type RestoreChoice = "restore" | "discard" | "later";
+
+export type AutosaveState = "starting" | "idle" | "saving" | "saved" | "unavailable" | "error";
+export interface AutosaveStatus {
+  state: AutosaveState;
+  /** False when no storage works here (private browsing, blocked site data); the editor still works. */
+  available: boolean;
+  /** Whether the document has changes that were not saved with `markSaved`. */
+  dirty: boolean;
+  savedAt?: number;
+  /** A sentence to show the user for `unavailable` and `error` (and a note on `saved`, such as "history too large to keep"). */
+  message?: string;
+  error?: "quota" | "write";
+  /** The adapter in use: "indexedDB", "localStorage", "memory" or the host adapter's name. */
+  storage?: string;
+  offer?: RestoreOffer;
+}
+
+export interface PersistenceOptions {
+  /** A stable string that names this document; two documents with the same key share one stored copy. */
+  key: string;
+  /** `"indexeddb"` (default, with localStorage as the fallback), `"localstorage"`, `"memory"`, `false` (off) or your own adapter. */
+  storage?: "indexeddb" | "localstorage" | "memory" | false | PersistenceStorage;
+  /** Milliseconds after the last change before a copy is written (default 800), and the longest a copy may lag behind (default 5000). */
+  debounceMs?: number;
+  maxWaitMs?: number;
+  /** Store the undo and redo history with the document (default true), limited to the newest entries and bytes (defaults 200 and 2,000,000). */
+  includeHistory?: boolean;
+  maxHistoryEntries?: number;
+  maxHistoryBytes?: number;
+  /**
+   * Called when a stored copy differs from the document the session started with. Return `"restore"`, `"discard"` or `"later"` (or a promise).
+   * `actions` restores or discards on demand, for a prompt with buttons. Without a handler the offer waits in `persistence.pending`.
+   */
+  onRestorePrompt?: (offer: RestoreOffer, actions: { restore(): Promise<boolean>; discard(): Promise<boolean> }) => RestoreChoice | Promise<RestoreChoice>;
+  /** Called on every status change, for an indicator. */
+  onStatus?: (status: AutosaveStatus) => void;
+  /** Called before every write and before the page unloads, so the host can commit a draft (text being edited on the canvas). */
+  beforeFlush?: () => void;
+  /** Warn before the page closes while the document is `dirty` (default true). */
+  warnOnUnload?: boolean;
+  /** For tests and frames: the window that receives `beforeunload`, `pagehide` and `visibilitychange` (default the global window; null for none). */
+  window?: Window | null;
+  now?: () => number;
+}
+export interface Persistence {
+  /** Resolves when storage has been opened and read: `{ available, offered }`. It does not wait for the user's decision on an offer. */
+  readonly ready: Promise<{ available: boolean; offered: boolean; offer?: RestoreOffer; reason?: string }>;
+  readonly status: AutosaveStatus;
+  /** True when the document differs from the last `markSaved()` (or from how the session started). */
+  readonly dirty: boolean;
+  /** The stored copy on offer, or undefined. */
+  readonly pending: RestoreOffer | undefined;
+  /** An older copy moved aside while an offer was open. */
+  readonly pendingEarlier: { savedAt: number; name?: string; slideCount?: number } | undefined;
+  /** Put the offered copy back: one undoable change (and the undo history too, when the session has not been edited). Resolves false when nothing was on offer. */
+  restore(): Promise<boolean>;
+  /** Decline the offered copy and delete it. */
+  discard(): Promise<boolean>;
+  restoreEarlier(): Promise<boolean>;
+  /** The host saved the document elsewhere (a download, a server): it is no longer `dirty`, and the stored copy records that. */
+  markSaved(): Promise<boolean>;
+  /** The host loaded a document into the editor: treat it as the starting point (not dirty, nothing written) until the next change. */
+  rebase(): void;
+  /** Write the document now; resolves when stored (false when it could not be). */
+  flush(): Promise<boolean>;
+  /** Delete the stored copy and stop treating the document as changed. */
+  clear(): Promise<void>;
+  destroy(): void;
+}
+export declare const DEFAULT_DEBOUNCE_MS: 800;
+export declare const DEFAULT_MAX_WAIT_MS: 5000;
+export declare const DEFAULT_MAX_HISTORY_ENTRIES: 200;
+export declare const DEFAULT_MAX_HISTORY_BYTES: 2000000;
+export declare function createPersistence(editor: EditorSession, options: PersistenceOptions): Persistence;
+/** A sentence for a status: "Saved on this device at 2:03 PM", or why autosave is off. */
+export declare function describeAutosave(status: AutosaveStatus | undefined, options?: { locale?: string }): string;