@openpresentation/opf-editor 0.12.1 → 0.14.2

package/dist/persistence.d.ts

@@ -22,7 +22,7 @@ export interface RestoreOffer {
   dirty: boolean;
   /** Whether the undo history is stored with it. */
   hasHistory: boolean;
-  document: unknown;
+  presentation: 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 };
 }

package/dist/persistence.js

@@ -14,8 +14,9 @@
 //     shows, and the editor keeps working.
 import { fail } from "./edit-helpers.js";
 
-const VERSION = 1;
-const PREFIX = "opf-editor/v1/";
+// 2: the stored record holds `presentation` (it held `document` in version 1). A record of another version is never read.
+const VERSION = 2;
+const PREFIX = "opf-editor/v2/";
 export const DEFAULT_DEBOUNCE_MS = 800;
 export const DEFAULT_MAX_WAIT_MS = 5000;
 export const DEFAULT_MAX_HISTORY_ENTRIES = 200;
@@ -155,7 +156,7 @@ export function createPersistence(editor, options = {}) {
   const limits = { entries: options.maxHistoryEntries ?? DEFAULT_MAX_HISTORY_ENTRIES, bytes: options.maxHistoryBytes ?? DEFAULT_MAX_HISTORY_BYTES };
 
   let adapter;
-  let baseline = jsonOf(editor.document); // JSON of the document last saved elsewhere; null means "unsaved in a way we cannot compare"
+  let baseline = jsonOf(editor.presentation); // JSON of the document last saved elsewhere; null means "unsaved in a way we cannot compare"
   let touched = false; // the document changed (or was saved) since this controller was created: only then is a copy written
   let pending; // the stored record on offer
   let stashed = false; // the offered record has been moved aside (earlierKey) because the user kept editing
@@ -172,20 +173,20 @@ export function createPersistence(editor, options = {}) {
     options.onStatus?.(status);
   };
   function isDirty() {
-    return baseline === null || jsonOf(editor.document) !== baseline;
+    return baseline === null || jsonOf(editor.presentation) !== baseline;
   }
 
   // --- writing --------------------------------------------------------------------------------------
 
   async function writeRecord() {
     if (!adapter || destroyed) return false;
-    const document = editor.document;
-    const json = jsonOf(document);
+    const presentation = editor.presentation;
+    const json = jsonOf(presentation);
     const dirty = baseline === null || json !== baseline;
     const history = includeHistory ? trimHistory(editor.exportHistory(), limits) : undefined;
     const signature = `${json}|${dirty}|${history ? history.undo.length + ":" + history.redo.length : ""}`;
     if (signature === lastWritten) return true;
-    const record = { version: VERSION, key: options.key, savedAt: now(), name: typeof document.name === "string" ? document.name : undefined, slideCount: Array.isArray(document.slides) ? document.slides.length : 0, dirty, document, ...(history ? { undo: history.undo, redo: history.redo } : {}) };
+    const record = { version: VERSION, key: options.key, savedAt: now(), name: typeof presentation.name === "string" ? presentation.name : undefined, slideCount: Array.isArray(presentation.slides) ? presentation.slides.length : 0, dirty, presentation, ...(history ? { undo: history.undo, redo: history.redo } : {}) };
     setStatus({ state: "saving" });
     try {
       // The first write while an offer is open moves the offered copy aside, so ignoring the prompt never loses it.
@@ -233,24 +234,24 @@ export function createPersistence(editor, options = {}) {
 
   // --- offering and restoring -------------------------------------------------------------------------
 
-  const validRecord = (record) => isRecordObject(record) && record.version === VERSION && isRecordObject(record.document) && Array.isArray(record.document.slides);
-  const offerOf = (record) => ({ key: options.key, savedAt: record.savedAt, name: record.name, slideCount: record.slideCount, dirty: record.dirty !== false, hasHistory: Boolean(record.undo?.length || record.redo?.length), document: record.document });
+  const validRecord = (record) => isRecordObject(record) && record.version === VERSION && isRecordObject(record.presentation) && Array.isArray(record.presentation.slides);
+  const offerOf = (record) => ({ key: options.key, savedAt: record.savedAt, name: record.name, slideCount: record.slideCount, dirty: record.dirty !== false, hasHistory: Boolean(record.undo?.length || record.redo?.length), presentation: record.presentation });
 
   async function applyRecord(record) {
     const pristine = !touched && !editor.canUndo && !editor.canRedo;
-    const state = { document: record.document, undo: record.undo ?? [], redo: record.redo ?? [] };
+    const state = { presentation: record.presentation, undo: record.undo ?? [], redo: record.redo ?? [] };
     if (pristine) {
       try { editor.restoreState(state, { source: "restore" }); }
       catch (error) {
         if (error?.code !== "invalid-history") throw error;
-        editor.restoreState({ document: record.document }, { source: "restore" });
+        editor.restoreState({ presentation: record.presentation }, { source: "restore" });
       }
     } else {
       // The user already worked in this session: bring the copy back as one undoable change instead of replacing their history.
-      editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.document) }], { source: "restore" });
+      editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.presentation) }], { source: "restore" });
     }
     touched = true;
-    baseline = record.dirty === false ? jsonOf(editor.document) : null;
+    baseline = record.dirty === false ? jsonOf(editor.presentation) : null;
   }
 
   /** Put the offered copy back. Resolves true when it was restored, false when there was nothing on offer or it was refused. */
@@ -294,7 +295,7 @@ export function createPersistence(editor, options = {}) {
     let record;
     try { record = await adapter.get(earlierKey); } catch { return false; }
     if (!validRecord(record)) return false;
-    try { editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.document) }], { source: "restore" }); }
+    try { editor.applyPatch([{ op: "replace", path: "", value: structuredClone(record.presentation) }], { source: "restore" }); }
     catch { return false; }
     pending = undefined;
     touched = true;
@@ -309,13 +310,13 @@ export function createPersistence(editor, options = {}) {
 
   /** The host saved the document somewhere of its own (a download, a server): it is no longer "unsaved", and the stored copy says so. */
   function markSaved() {
-    baseline = jsonOf(editor.document);
+    baseline = jsonOf(editor.presentation);
     touched = true;
     return flush();
   }
   /** Treat the current document as the starting point (a host that loads a document into the editor): no write, and not dirty, until the next change. */
   function rebase() {
-    baseline = jsonOf(editor.document);
+    baseline = jsonOf(editor.presentation);
     touched = false;
     clearTimeout(timer);
     firstDirtyAt = 0;
@@ -329,7 +330,7 @@ export function createPersistence(editor, options = {}) {
     await dropEarlier();
     lastWritten = "";
     touched = false;
-    baseline = jsonOf(editor.document);
+    baseline = jsonOf(editor.presentation);
     setStatus({ state: status.available ? "idle" : status.state, message: "" });
   }
 
@@ -371,7 +372,7 @@ export function createPersistence(editor, options = {}) {
       setStatus({ state: "error", message: `Saved work could not be read (${String(error?.message ?? error)}).` });
       return { available: true, offered: false };
     }
-    if (!validRecord(record) || jsonOf(record.document) === jsonOf(editor.document)) return { available: true, offered: false };
+    if (!validRecord(record) || jsonOf(record.presentation) === jsonOf(editor.presentation)) return { available: true, offered: false };
     try {
       const earlier = await adapter.get(earlierKey);
       hasEarlier = validRecord(earlier);

package/dist/presentation-ids.js

@@ -47,9 +47,9 @@ export function slideIds(slide) {
   return ids;
 }
 
-export function collectReservedPresentationIds(document) {
+export function collectReservedPresentationIds(presentation) {
   const ids = [];
-  for (const slide of document.slides ?? []) ids.push(...slideIds(slide));
+  for (const slide of presentation.slides ?? []) ids.push(...slideIds(slide));
   return ids.filter(Boolean);
 }
 

package/dist/react.js

@@ -32,7 +32,7 @@ export function createOPFReactComponents(React) {
     ...props
   }) {
     const snapshot = useEditorSnapshot(editor);
-    const value = getValueAtPath(snapshot.document, path, "");
+    const value = getValueAtPath(snapshot.presentation, path, "");
     const tag = multiline ? "textarea" : "input";
     return React.createElement(tag, {
       ...props,
@@ -60,9 +60,9 @@ export function createOPFReactComponents(React) {
     ...props
   }) {
     const snapshot = useEditorSnapshot(editor);
-    const value = getValueAtPath(snapshot.document, path, "");
+    const value = getValueAtPath(snapshot.presentation, path, "");
     const currentId = value && typeof value === "object" ? value.id : value;
-    const options = catalogOptions ?? getCatalogOptions(catalogKind, { presentation: snapshot.document });
+    const options = catalogOptions ?? getCatalogOptions(catalogKind, { presentation: snapshot.presentation });
 
     return React.createElement(
       "select",

package/dist/review-panel.d.ts

@@ -1,44 +1,61 @@
+import type { ValidateOptions } from "@openpresentation/opf";
 import type { EditorSession } from "./index.js";
-import type { ReviewAuditOptions, ReviewFinding, ReviewFix, ReviewReport, ReviewTarget } from "./review.js";
+import type { ReviewFinding, ReviewFix, ReviewHook, ReviewReport, ReviewTarget } from "./review.js";
 
 export interface ReviewPanelOptions {
   editor: EditorSession;
   /** The slide the "This slide only" filter follows. Call `update()` when it changes. */
   getSlideIndex?: () => number;
-  /** Core's `AuditOptions` for this document, for example `{ textMeasurement }` from the host's font registry. */
-  getAuditOptions?: (document: unknown) => ReviewAuditOptions;
+  /** Core's `ValidateOptions` for this document, for example `{ fonts: { textMeasurement } }` from the host's fonts handle (a function of the slide index is accepted too). */
+  getValidateOptions?: (presentation: unknown) => ValidateOptions;
   /** Select the content a finding is about. `target.path` is the OPF dotted path (the nearest existing field), `target.slide` the slide or null. */
   onGoTo?: (event: { finding: ReviewFinding; target: ReviewTarget }) => void;
   /** Focus a field the panel does not own (a title, text, link, language or font size) after going to it. Alt text is edited in the panel itself. */
   onFocusField?: (event: { finding: ReviewFinding; fix: ReviewFix; target: ReviewTarget }) => void;
   /** Called with every status or error message the panel shows. */
   onStatus?: (message: string, info: { error: boolean }) => void;
-  /** Called after every redraw with the counts of the findings shown (after the filters and hidden checks) and of all findings. */
-  onChange?: (counts: { error: number; warning: number; info: number; total: number; all: number; unavailable: boolean }) => void;
+  /** Called after every redraw with the counts of the findings shown (after the filters and hidden checks), of all findings, and the sources present (`opf`, `pptx.dev/review`, ...). */
+  onChange?: (counts: { error: number; warning: number; info: number; total: number; all: number; sources: string[]; unavailable: boolean }) => void;
   /** Rule ids hidden at the start, and a callback when the author hides or restores a check. */
   ignored?: string[];
   onIgnoredChange?: (ids: string[]) => void;
-  /** Re-audit after every session change (default true). Set false to call `refresh()` yourself, for example after the host's fonts have loaded. */
+  /** Re-check after changes (default true). Set false to call `refresh()` yourself, for example after the host's fonts have loaded. */
   autoRefresh?: boolean;
-  /** Use another audit function instead of core's `auditPresentation`. */
-  audit?: ReviewAuditOptions["audit"];
+  /** Milliseconds the document must be quiet after a change before the full `validate` runs again (default 300). `refresh()` checks at once. */
+  delay?: number;
+  /**
+   * A hosted reviewer: resolves a `FindingReport` whose findings (`source`, for example `pptx.dev/review`) are listed beside core's. It runs when
+   * the author presses its button, or after every re-check with `autoReview`. A finding with no `source` is listed under `review`.
+   */
+  review?: ReviewHook;
+  /** The label of the button that runs the `review` hook (default "Run review"). */
+  reviewLabel?: string;
+  /** Run the `review` hook after every re-check, not only on the button (default false: a hosted review can be slow or metered). */
+  autoReview?: boolean;
 }
 
 export interface ReviewPanel {
   element: HTMLElement;
-  /** The latest findings before the panel's filters and hidden checks. */
+  /** The latest findings before the panel's filters and hidden checks: core's and the hosted reviewer's. */
   readonly findings: ReviewFinding[];
+  /** The merged report (`valid`, `findings`, `counts`, `sources`). */
   readonly report: ReviewReport | undefined;
-  /** Audit the document again and redraw. */
+  /** Core's `validate` report alone, or undefined when it could not run. */
+  readonly validation: import("@openpresentation/opf").ValidationReport | undefined;
+  /** Run core's full check again now and redraw. */
   refresh(): void;
-  /** Redraw without auditing, after the host's slide changed. */
+  /** Check after `delay` milliseconds without another call (a burst of calls checks once). With `autoRefresh: false` the host calls this after each redraw. */
+  schedule(): void;
+  /** Run the `review` hook now; resolves once its findings are listed (or its error is shown). */
+  review(): Promise<void>;
+  /** Redraw without checking, after the host's slide changed. */
   update(): void;
   /** Hide (true) or show again (false) the findings of one rule in this panel. */
   setIgnored(ruleId: string, hidden: boolean): void;
   destroy(): void;
 }
 
-export { auditAvailable, reviewSeverities } from "./review.js";
+export { reviewSeverities } from "./review.js";
 
-/** Mount the Review panel: the audit's findings with go-to, safe quick fixes and live updates as the document changes. */
+/** Mount the Review panel: core's findings by category with go-to and quick fixes, a hosted reviewer's beside them, and updates as the document changes. */
 export declare function createReviewPanel(container: HTMLElement, options: ReviewPanelOptions): ReviewPanel;

package/dist/review-panel.js

@@ -1,22 +1,29 @@
-// Review panel (RR-29): the DOM panel over core's design and accessibility audit. It lists the findings of the
-// open presentation (contrast, overflow, alt text, reading order, fonts, links and more), lets the author go to
-// the content a finding is about, offers safe quick fixes (type the alt text in place, switch a failing text
-// colour to the readable one) and updates as the document changes. The panel owns no document state: every fix
-// is an undoable edit through the editor session. Importing this module does not need a DOM; mounting does.
+// Review panel (RR-29, RR-55): the DOM panel over core's `validate` report and, optionally, a hosted reviewer. It lists the findings
+// of the open presentation by category (format, references, policy, accessibility, layout, content, and any category a hosted
+// reviewer adds), lets the author go to the content a finding is about, offers quick fixes (type the alt text in place, switch a
+// failing text colour to the readable one) and updates as the document changes. The full check runs after the document has been
+// quiet for a moment, not on every keystroke (the session itself checks only the `format` category per edit). The panel owns no
+// document state: every fix is an undoable edit through the editor session. Importing this module does not need a DOM;
+// mounting does.
+import { validate } from "@openpresentation/opf";
 import {
   applyReviewFix,
-  auditAvailable,
   countFindings,
   currentAltText,
   filterFindings,
   findingTarget,
+  CORE_SOURCE,
+  groupFindings,
+  mergeFindingReports,
   reviewFindings,
   reviewSeverities,
-  runAudit,
   setReviewAltText,
 } from "./review.js";
 
 const SEVERITY_LABELS = { error: "Error", warning: "Warning", info: "Note" };
+const CATEGORY_LABELS = { format: "Format", references: "References", policy: "Policy", accessibility: "Accessibility", layout: "Layout", content: "Content" };
+const categoryLabel = (category) => CATEGORY_LABELS[category] ?? (category.charAt(0).toUpperCase() + category.slice(1));
+const DEFAULT_DELAY = 300;
 const MINIMUMS = { all: "info", warnings: "warning", errors: "error" };
 let panelCounter = 0;
 
@@ -40,7 +47,10 @@ const STYLE = `
 .opf-review-counts{margin:0;color:var(--muted,#656570)}
 .opf-review-filters{display:flex;flex-wrap:wrap;gap:6px 14px;align-items:center;margin:0 0 8px}
 .opf-review-filters label{display:inline-flex;gap:6px;align-items:center;margin:0;font-weight:400}
-.opf-review-list{list-style:none;margin:0;padding:0}
+.opf-review-list{margin:0;padding:0}
+.opf-review-category{margin:0 0 8px}
+.opf-review-category-title{margin:10px 0 2px;font-size:12px;font-weight:600;color:var(--muted,#656570)}
+.opf-review-items{list-style:none;margin:0;padding:0}
 .opf-review-item{border-top:1px solid var(--border,#e8e8ec);padding:8px 0}
 .opf-review-item[aria-current="true"]{background:var(--review-current,rgba(101,89,207,.07))}
 .opf-review-goto{display:block;width:100%;box-sizing:border-box;white-space:normal;overflow-wrap:anywhere;line-height:1.45;text-align:left;background:none;border:0;padding:2px 4px;font:inherit;color:inherit;cursor:pointer;border-radius:4px}
@@ -87,33 +97,51 @@ function summaryText(counts, scopeLabel) {
 
 /**
  * Mount the Review panel. Options: `editor` (a session), `getSlideIndex()` (the slide the "This slide only" filter
- * follows), `getAuditOptions(document)` (core's AuditOptions; pass `textMeasurement` from the host's font registry
- * for font-exact overflow), `onGoTo({finding, target})` (select the content: `target` is {slide, path, pointer, exact}),
- * `onFocusField({finding, fix, target})` (focus a field the panel does not own: a title, text, link or language),
- * `onStatus(message, {error})`, `onChange({error, warning, info, total, all, unavailable})` (after every redraw, with the shown counts), `ignored` (rule ids hidden at the start) and `onIgnoredChange(ids)`,
- * `autoRefresh` (default true: re-audit after every session change; a host that must wait for its fonts sets false and
- * calls `refresh()` itself), `audit` (replace core's audit function).
+ * follows), `getValidateOptions(presentation)` (core's `ValidateOptions`: `fonts` with the host's `textMeasurement` for font-exact
+ * overflow, `severity`, `ignore`, `thresholds`, `contracts`, ...), `onGoTo({finding, target})` (select the content: `target` is
+ * {slide, path, pointer, exact}), `onFocusField({finding, fix, target})` (focus a field the panel does not own: a title, text, link or
+ * language), `onStatus(message, {error})`, `onChange({error, warning, info, total, all, sources, unavailable})` (after every redraw, with
+ * the shown counts), `ignored` (rule ids hidden at the start) and `onIgnoredChange(ids)`.
+ *
+ * The full `validate(presentation)` runs once the document has been quiet for `delay` milliseconds (default 300) after a session change,
+ * and at once on mount and on `refresh()`. `autoRefresh` (default true) turns the re-check after changes off for a host that must wait
+ * for its fonts; it then calls `refresh()` itself.
+ *
+ * `review(presentation, { signal, report, validateOptions })` is an optional hook that returns a `FindingReport` from a hosted reviewer
+ * (pptx.dev's review). Its findings join core's in the same list, kept per `Finding.source`; a finding with no source is listed under
+ * `review`. The hook can cost money and take seconds, so it runs when the author presses its button (`reviewLabel`, default "Run
+ * review") or, with `autoReview: true`, after every re-check; findings from an earlier run stay listed, marked as possibly out of date,
+ * until the next run. A failing hook shows its message and leaves core's findings in place.
  */
 export function createReviewPanel(container, options) {
-  const { editor, getSlideIndex, getAuditOptions, onGoTo, onFocusField, onStatus, onIgnoredChange, onChange } = options;
+  const { editor, getSlideIndex, getValidateOptions, onGoTo, onFocusField, onStatus, onIgnoredChange, onChange, review } = options;
+  if (review !== undefined && typeof review !== "function") throw new TypeError("The Review panel's review hook must be a function (presentation, options) returning a FindingReport.");
   if (!editor || typeof editor.subscribe !== "function") throw new Error("The Review panel needs an editor session created by createEditorSession.");
   const doc = container.ownerDocument;
   ensureStyles(doc);
   const id = `opf-review-${++panelCounter}`;
   const ignored = new Set(options.ignored ?? []);
   let report;
+  let coreReport;
+  let hookReport;
+  let hookStale = false;
+  let hookError;
+  let hookRunning;
   let findings = [];
   let destroyed = false;
-  let scheduled = false;
+  let timer;
   let currentId;
   let editingAlt;
   let altDraft = "";
   let lastAuditError;
+  const delay = Number.isFinite(options.delay) && options.delay >= 0 ? options.delay : DEFAULT_DELAY;
 
   const root = h(doc, "section", { class: "opf-review", "data-opf-component": "review-panel", "aria-labelledby": `${id}-title` });
   const counts = h(doc, "p", { class: "opf-review-counts", id: `${id}-counts`, role: "status", "aria-live": "polite" });
   const title = h(doc, "h2", { id: `${id}-title`, text: "Review", tabindex: "-1" });
-  const head = h(doc, "div", { class: "opf-review-head" }, title, counts);
+  const hookButton = review ? h(doc, "button", { type: "button", class: "opf-review-fix", "data-action": "run-review", text: options.reviewLabel ?? "Run review", onclick: () => { void runHook(); } }) : undefined;
+  const hookStatus = review ? h(doc, "p", { class: "opf-review-meta", role: "status", "aria-live": "polite" }) : undefined;
+  const head = h(doc, "div", { class: "opf-review-head" }, title, counts, hookButton);
   const severitySelect = h(doc, "select", { id: `${id}-severity` },
     h(doc, "option", { value: "all", text: "All findings" }),
     h(doc, "option", { value: "warnings", text: "Errors and warnings" }),
@@ -122,10 +150,10 @@ export function createReviewPanel(container, options) {
   const filters = h(doc, "div", { class: "opf-review-filters" },
     h(doc, "label", { for: `${id}-severity` }, "Show ", severitySelect),
     h(doc, "label", { for: `${id}-slide` }, slideOnly, "This slide only"));
-  const list = h(doc, "ul", { class: "opf-review-list", "aria-label": "Review findings" });
+  const list = h(doc, "div", { class: "opf-review-list", role: "group", "aria-label": "Review findings" });
   const empty = h(doc, "p", { class: "opf-review-empty" });
   const ignoredBox = h(doc, "details", { class: "opf-review-ignored", hidden: true });
-  root.append(head, filters, list, empty, ignoredBox);
+  root.append(head, ...(hookStatus ? [hookStatus] : []), filters, list, empty, ignoredBox);
   container.append(root);
 
   const say = (message, error = false) => {
@@ -135,21 +163,64 @@ export function createReviewPanel(container, options) {
   function visible() {
     const minimum = MINIMUMS[severitySelect.value] ?? "info";
     const slide = slideOnly.checked ? (getSlideIndex?.() ?? 0) : undefined;
-    return filterFindings(findings, { minimum, slide }).filter((finding) => !ignored.has(finding.ruleId));
+    const shown = filterFindings(findings, { minimum, slide }).filter((finding) => !ignored.has(finding.ruleId));
+    return groupFindings(shown).flatMap((group) => group.findings);
   }
 
-  function audit() {
+  // Core's full check, then the hook's findings merged in by source.
+  function validateNow() {
     lastAuditError = undefined;
     try {
-      report = runAudit(editor.document, { ...(getAuditOptions?.(editor.document) ?? {}), ...(options.audit ? { audit: options.audit } : {}) });
-      findings = reviewFindings(report);
+      coreReport = validate(editor.presentation, getValidateOptions?.(editor.presentation) ?? {});
     } catch (error) {
-      report = undefined;
-      findings = [];
+      coreReport = undefined;
       lastAuditError = error;
     }
+    merge();
   }
 
+  function merge() {
+    report = coreReport || hookReport ? mergeFindingReports(coreReport, hookReport) : undefined;
+    findings = reviewFindings(report);
+  }
+
+  function hookMessage() {
+    if (!review) return "";
+    if (hookRunning) return "Running the hosted review…";
+    if (hookError) return `The hosted review could not run: ${messageOf(hookError)}`;
+    if (hookReport && hookStale) return "Hosted review findings are from before your latest edit.";
+    if (hookReport) return "Hosted review is up to date.";
+    return "";
+  }
+
+  // The hosted reviewer: one run at a time; a document change while it runs drops its result (the next run starts from the new text).
+  async function runHook() {
+    if (!review || destroyed) return;
+    hookRunning?.controller.abort();
+    const controller = new AbortController();
+    const running = { controller };
+    hookRunning = running;
+    hookError = undefined;
+    if (!coreReport && !lastAuditError) validateNow();
+    renderList();
+    try {
+      const result = await review(editor.presentation, { signal: controller.signal, report: coreReport, validateOptions: getValidateOptions?.(editor.presentation) ?? {} });
+      if (destroyed || hookRunning !== running) return;
+      if (!result || !Array.isArray(result.findings)) throw new TypeError("The review hook must resolve a FindingReport ({ valid, findings, counts }).");
+      hookRunning = undefined;
+      hookReport = result;
+      hookStale = false;
+      merge();
+    } catch (error) {
+      if (destroyed || hookRunning !== running) return;
+      hookRunning = undefined;
+      hookError = error;
+    }
+    renderList();
+  }
+
+  const itemFor = (findingId) => [...list.querySelectorAll(".opf-review-item")].find((entry) => entry.dataset.findingId === findingId);
+
   function focusGoto(findingId) {
     const buttons = [...list.querySelectorAll(".opf-review-goto")];
     (buttons.find((button) => button.dataset.findingId === findingId) ?? buttons[0])?.focus();
@@ -157,21 +228,21 @@ export function createReviewPanel(container, options) {
 
   function go(finding) {
     currentId = finding.id;
-    const target = findingTarget(editor.document, finding);
-    for (const item of list.children) item.setAttribute("aria-current", String(item.dataset.findingId === finding.id));
+    const target = findingTarget(editor.presentation, finding);
+    for (const entry of list.querySelectorAll(".opf-review-item")) entry.setAttribute("aria-current", String(entry.dataset.findingId === finding.id));
     onGoTo?.({ finding, target });
   }
 
   function altForm(finding, fix) {
     const pointer = fix.focus.path;
     const inputId = `${id}-alt-${finding.id.replace(/[^a-z0-9]+/gi, "-")}`;
-    const input = h(doc, "input", { type: "text", id: inputId, value: altDraft || currentAltText(editor.document, pointer), "aria-describedby": `${inputId}-help` });
+    const input = h(doc, "input", { type: "text", id: inputId, value: altDraft || currentAltText(editor.presentation, pointer), "aria-describedby": `${inputId}-help` });
     const error = h(doc, "span", { class: "opf-review-error", role: "alert" });
     const form = h(doc, "form", { class: "opf-review-alt", novalidate: true },
       h(doc, "label", { for: inputId, text: "Alt text" }), input,
       h(doc, "button", { type: "submit", class: "opf-review-fix", text: "Save alt text" }),
       h(doc, "button", { type: "button", class: "opf-review-fix quiet", text: "Cancel", onclick: () => closeAlt(finding) }),
-      h(doc, "span", { id: `${inputId}-help`, class: "opf-review-meta", text: "Describe what the picture shows. Press Escape to cancel." }), error);
+      h(doc, "span", { id: `${inputId}-help`, class: "opf-review-meta", text: `${finding.ruleId === "opf/chart-text-alternative" || String(finding.path ?? "").includes("/chart") ? "Describe what the chart shows: its point and the key numbers." : "Describe what the picture shows."} Press Escape to cancel.` }), error);
     input.addEventListener("input", () => { altDraft = input.value; });
     form.addEventListener("keydown", (event) => { if (event.key === "Escape") { event.stopPropagation(); closeAlt(finding); } });
     form.addEventListener("submit", (event) => {
@@ -181,6 +252,7 @@ export function createReviewPanel(container, options) {
         editingAlt = undefined;
         altDraft = "";
         say("Alt text saved. Undo restores the previous text.");
+        refresh();
       } catch (problem) {
         error.textContent = messageOf(problem);
         say(messageOf(problem), true);
@@ -203,18 +275,19 @@ export function createReviewPanel(container, options) {
         editingAlt = finding.id;
         altDraft = "";
         renderList();
-        [...list.children].find((entry) => entry.dataset.findingId === finding.id)?.querySelector(".opf-review-alt input")?.focus();
+        itemFor(finding.id)?.querySelector(".opf-review-alt input")?.focus();
         return;
       }
       go(finding);
-      onFocusField?.({ finding, fix, target: findingTarget(editor.document, finding) });
+      onFocusField?.({ finding, fix, target: findingTarget(editor.presentation, finding) });
       return;
     }
     const index = visible().findIndex((entry) => entry.id === finding.id);
     try {
       applyReviewFix(editor, finding, fix);
-      say(`${fix.label}. Undo restores the previous state.`);
-      // The change re-audits the document (the subscription); put focus on the neighbouring finding.
+      say(`${fix.title}. Undo restores the previous state.`);
+      // Check the changed document at once, then put focus on the neighbouring finding.
+      refresh();
       const after = visible();
       const next = after[Math.min(Math.max(index, 0), after.length - 1)];
       if (next) focusGoto(next.id);
@@ -236,17 +309,17 @@ export function createReviewPanel(container, options) {
     },
     h(doc, "span", { class: "opf-review-sev", text: SEVERITY_LABELS[finding.severity] }),
     h(doc, "span", { class: "opf-review-msg", text: finding.message }),
-    h(doc, "span", { class: "opf-review-meta", text: `${where} · ${finding.ruleId}` }));
-    const li = h(doc, "li", { class: "opf-review-item", "data-finding-id": finding.id, "data-rule": finding.ruleId, "data-severity": finding.severity, "aria-current": String(finding.id === currentId) }, go_,
-      h(doc, "p", { class: "opf-review-help", text: finding.help }));
+    h(doc, "span", { class: "opf-review-meta", text: `${where} · ${finding.ruleId}${finding.source && finding.source !== CORE_SOURCE ? ` · ${finding.source}` : ""}` }));
+    const li = h(doc, "li", { class: "opf-review-item", "data-finding-id": finding.id, "data-rule": finding.ruleId, "data-source": finding.source ?? CORE_SOURCE, "data-severity": finding.severity, "aria-current": String(finding.id === currentId) }, go_,
+      finding.help ? h(doc, "p", { class: "opf-review-help", text: finding.help }) : undefined);
     const actions = h(doc, "div", { class: "opf-review-actions" });
     for (const fix of finding.fixes ?? []) {
       actions.append(h(doc, "button", {
         type: "button",
         class: `opf-review-fix${fix.safe ? "" : " is-careful"}`,
-        "data-fix": fix.id,
+        "data-fix": fix.id ?? fix.title,
         title: fix.safe ? undefined : "This changes how the slide looks or what it says; it can be undone.",
-        text: fix.label,
+        text: fix.title,
         onclick: () => runFix(finding, fix),
       }));
     }
@@ -289,22 +362,30 @@ export function createReviewPanel(container, options) {
     const hadFocus = doc.activeElement && list.contains(doc.activeElement) ? { id: doc.activeElement.closest("[data-finding-id]")?.dataset.findingId, fix: doc.activeElement.dataset.fix, tag: doc.activeElement.tagName } : undefined;
     const shown = visible();
     const slideScope = slideOnly.checked ? ` on slide ${(getSlideIndex?.() ?? 0) + 1}` : "";
-    list.replaceChildren(...shown.map(item));
+    list.replaceChildren(...groupFindings(shown).map(({ category, findings: inGroup }) => {
+      const heading = h(doc, "h3", { class: "opf-review-category-title", id: `${id}-cat-${category}`, text: `${categoryLabel(category)} (${inGroup.length})` });
+      return h(doc, "section", { class: "opf-review-category", "data-category": category, "aria-labelledby": heading.id }, heading, h(doc, "ul", { class: "opf-review-items" }, ...inGroup.map(item)));
+    }));
+    if (hookStatus) {
+      hookStatus.textContent = hookMessage();
+      hookButton.disabled = Boolean(hookRunning);
+      hookButton.textContent = hookReport ? `${options.reviewLabel ?? "Run review"} again` : options.reviewLabel ?? "Run review";
+    }
     if (lastAuditError) {
       empty.hidden = false;
-      empty.textContent = lastAuditError.code === "audit-unavailable" ? lastAuditError.message : `The review could not run: ${messageOf(lastAuditError)}`;
+      empty.textContent = `The review could not run: ${messageOf(lastAuditError)}`;
       counts.textContent = "Review unavailable.";
     } else {
       const hiddenCount = findings.length - findings.filter((finding) => !ignored.has(finding.ruleId)).length;
       counts.textContent = summaryText(countFindings(shown), slideScope) + (hiddenCount ? ` ${plural(hiddenCount, "finding")} hidden.` : "");
       empty.hidden = shown.length > 0;
-      empty.textContent = findings.length && !shown.length ? "Nothing to show with these filters." : "The audit found nothing to fix. It checks contrast, text fit, alt text, reading order and more; it does not replace looking at the slides.";
+      empty.textContent = findings.length && !shown.length ? "Nothing to show with these filters." : "Nothing to fix. The checks cover the format, references, contrast, text fit, alt text, reading order and more; they do not replace looking at the slides.";
     }
     renderIgnored();
-    onChange?.({ ...countFindings(shown), all: findings.length, unavailable: Boolean(lastAuditError) });
+    onChange?.({ ...countFindings(shown), all: findings.length, sources: report?.sources ?? [], unavailable: Boolean(lastAuditError) });
     // Live updates must not take the keyboard away: put focus back on the same control, or the same finding.
     if (hadFocus?.id && !lastAuditError) {
-      const li = [...list.children].find((entry) => entry.dataset.findingId === hadFocus.id);
+      const li = itemFor(hadFocus.id);
       const target = (hadFocus.fix ? [...li?.querySelectorAll("[data-fix]") ?? []].find((button) => button.dataset.fix === hadFocus.fix) : hadFocus.tag === "INPUT" ? li?.querySelector("input") : li?.querySelector(".opf-review-goto")) ?? li?.querySelector(".opf-review-goto");
       if (target && doc.activeElement !== target) target.focus();
     }
@@ -312,16 +393,27 @@ export function createReviewPanel(container, options) {
 
   function refresh() {
     if (destroyed) return;
-    scheduled = false;
-    audit();
+    clearTimeout(timer);
+    timer = undefined;
+    validateNow();
     renderList();
+    if (options.autoReview && review) void runHook();
   }
 
-  const unsubscribe = options.autoRefresh === false ? undefined : editor.subscribe(() => {
-    if (scheduled || destroyed) return;
-    scheduled = true;
-    // One re-audit per burst of edits (an undo group, a paste), after the session has settled.
-    Promise.resolve().then(refresh);
+  // One full check per burst of changes (typing, an undo group, a paste): when nothing has changed for `delay` milliseconds.
+  function schedule() {
+    if (destroyed) return;
+    clearTimeout(timer);
+    timer = setTimeout(refresh, delay);
+  }
+
+  // A change while the hosted review runs drops its result (it was about the old text); one that comes after marks it out of date.
+  const stop = editor.subscribe(() => {
+    if (destroyed) return;
+    if (hookRunning) { hookRunning.controller.abort(); hookRunning = undefined; }
+    if (hookReport) hookStale = true;
+    if (options.autoRefresh === false) { renderList(); return; }
+    schedule();
   });
 
   severitySelect.addEventListener("change", renderList);
@@ -341,19 +433,28 @@ export function createReviewPanel(container, options) {
 
   return {
     element: root,
-    /** The latest findings (core's diagnostics with `id`, `slide` and `dottedPath`), before filters and hidden checks. */
+    /** The latest findings (core's, and the hosted reviewer's, with `id`, `slide` and `dottedPath`), before filters and hidden checks. */
     get findings() { return findings; },
+    /** The merged report: `valid`, `findings`, `counts` and `sources`. */
     get report() { return report; },
+    /** Core's `validate` report alone. */
+    get validation() { return coreReport; },
     refresh,
+    /** Check after `delay` milliseconds without another call: a host that drives its own checks (`autoRefresh: false`) calls this after each redraw. */
+    schedule,
+    /** Run the hosted reviewer now (the `review` hook); resolves when its findings are listed. */
+    review: runHook,
     /** Re-render after the host's slide changed (the "This slide only" filter). */
     update: renderList,
     setIgnored,
     destroy() {
       destroyed = true;
-      unsubscribe?.();
+      clearTimeout(timer);
+      hookRunning?.controller.abort();
+      stop();
       root.remove();
     },
   };
 }
 
-export { auditAvailable, reviewSeverities };
+export { reviewSeverities };