@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/review-panel.js

@@ -1,22 +1,30 @@
-// 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 { mergeCatalogs } from "./catalogs.js";
 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 +48,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 +98,56 @@ 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;
+  // Core resolves the deck's references with the session's registered catalogs (and any the host adds): the same list as the preview.
+  const validateOptions = () => {
+    const host = getValidateOptions?.(editor.presentation) ?? {};
+    return { ...host, catalogs: mergeCatalogs(editor.catalogs, host.catalogs) };
+  };
+  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 +156,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 +169,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, validateOptions());
     } 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: validateOptions() });
+      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 +234,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 +258,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 +281,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 +315,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 +368,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 +399,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 +439,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 };

package/dist/review.d.ts

@@ -1,50 +1,37 @@
+import type { Finding, FindingFix, FindingReport, FindingSeverity, ValidateOptions, ValidationCategory, ValidationReport } from "@openpresentation/opf";
 import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
 
-export type ReviewSeverity = "error" | "warning" | "info";
+export type ReviewSeverity = FindingSeverity;
+/** A suggested repair from core's `validate` or a hosted reviewer: core's `FindingFix` (`title`, `patch` of RFC 6902 operations, or a `focus` field). */
+export type ReviewFix = FindingFix;
 
-/** A suggested repair from core's audit (the structural subset the editor uses). */
-export interface ReviewFix {
+/** A finding of core's `validate` or of a hosted reviewer (core's `Finding`), with the fields the editor derives. */
+export interface ReviewFinding extends Omit<Finding, "slide"> {
+  /** Unique within the report: the source, the rule id and the path, numbered when they repeat. */
   id: string;
-  label: string;
-  kind: "patch" | "focus";
-  /** True when the change cannot alter what the content says. */
-  safe: boolean;
-  patch?: JsonPatchOperation[];
-  focus?: { path: string; field: "alt" | "title" | "text" | "link" | "language" | "fontSize"; value?: unknown };
-}
-
-/** One finding of core's audit, with the fields the editor adds. */
-export interface ReviewFinding {
-  /** Unique within the report: the rule id and the path, numbered when they repeat. */
-  id: string;
-  ruleId: string;
-  severity: ReviewSeverity;
-  /** JSON Pointer of the content the finding is about. */
-  path: string;
   /** The same path in OPF dotted form (`slides.0.text.1.color`). */
   dottedPath: string;
   /** Zero-based slide index, or null for a finding about the whole presentation. */
   slide: number | null;
-  message: string;
-  help: string;
-  category?: "accessibility" | "design" | "content";
-  measured?: Record<string, number | string | boolean | null>;
-  fixes?: ReviewFix[];
 }
 
-export interface ReviewReport {
-  valid: boolean;
-  documentValid: boolean;
-  diagnostics: Omit<ReviewFinding, "id" | "dottedPath">[];
-  counts: Record<ReviewSeverity, number>;
-  [key: string]: unknown;
+/** What the Review panel holds: core's `FindingReport` of every source merged, the editor's findings, and the sources present (`opf`, `pptx.dev/review`, ...). */
+export interface ReviewReport extends FindingReport {
+  findings: ReviewFinding[];
+  /** The `Finding.source` of every group of findings in the report. `opf` is core's own checks. */
+  sources: string[];
 }
 
-/** Core's `AuditOptions` (severity per rule, `ignore`, `only`, `thresholds`, `textMeasurement`, ...). */
-export type ReviewAuditOptions = Record<string, unknown> & {
-  /** Use this audit function instead of core's `auditPresentation`. */
-  audit?: (document: unknown, options?: Record<string, unknown>) => ReviewReport;
-};
+/** The hook that brings a hosted reviewer's findings into the panel (see `createReviewPanel`). */
+export type ReviewHook = (presentation: unknown, options: ReviewHookOptions) => Promise<FindingReport>;
+export interface ReviewHookOptions {
+  /** Aborted when the document changes while the review runs, or the panel is destroyed. */
+  signal: AbortSignal;
+  /** Core's report for this presentation, so a hosted reviewer need not repeat the deterministic checks. */
+  report: ValidationReport | undefined;
+  /** The options core's `validate` ran with (from the panel's `getValidateOptions`). */
+  validateOptions: ValidateOptions;
+}
 
 export interface ReviewTarget {
   /** The slide the finding is on, or null for the presentation. */
@@ -57,19 +44,25 @@ export interface ReviewTarget {
 }
 
 export declare const reviewSeverities: readonly ReviewSeverity[];
-/** True when the installed core ships the audit (`@openpresentation/opf` after 0.11.4). */
-export declare function auditAvailable(): boolean;
-/** Audit a document with core's `auditPresentation`. Throws `audit-unavailable` when core has none. */
-export declare function runAudit(document: unknown, options?: ReviewAuditOptions): ReviewReport;
-export declare function reviewFindings(report: ReviewReport | undefined): ReviewFinding[];
+/** Core's finding categories in report order: format, references, policy, accessibility, layout, content. */
+export declare const reviewCategories: readonly ValidationCategory[];
+/** The `source` of a finding that names none: core's own checks. */
+export declare const CORE_SOURCE: "opf";
+/** Merge core's report and a hosted reviewer's, keeping findings per `Finding.source` (a report replaces earlier findings of the sources it carries). A hook finding with no source gets `hookSource` (default `review`). */
+export declare function mergeFindingReports(core: FindingReport | undefined, hook?: FindingReport | undefined, options?: { hookSource?: string }): FindingReport & { sources: string[] };
+export declare function reviewFindings(report: Pick<FindingReport, "findings"> | undefined): ReviewFinding[];
 export declare function countFindings(findings: readonly ReviewFinding[]): { error: number; warning: number; info: number; total: number };
 export declare function filterFindings(findings: readonly ReviewFinding[], options?: { minimum?: ReviewSeverity; slide?: number | null }): ReviewFinding[];
+/** The deck first, then each slide; errors before warnings before notes; then by rule and path. */
+export declare function sortFindings(findings: readonly ReviewFinding[]): ReviewFinding[];
+/** Findings grouped by category: core's categories in core's order, then any other category in the order it first appears. Empty categories are left out. */
+export declare function groupFindings(findings: readonly ReviewFinding[]): { category: string; findings: ReviewFinding[] }[];
 /** Where "go to" lands for a finding. */
-export declare function findingTarget(document: unknown, finding: Pick<ReviewFinding, "path">): ReviewTarget;
+export declare function findingTarget(presentation: unknown, finding: Pick<ReviewFinding, "path">): ReviewTarget;
 /** Apply a `patch` fix as one undoable, validated session change; refuses a stale or unsafe patch. */
 export declare function applyReviewFix(editor: EditorSession, finding: Pick<ReviewFinding, "ruleId"> | undefined, fix: ReviewFix, meta?: Record<string, unknown>): EditorChange;
 /** The patch that sets (or, for `""`, marks decorative) the alt text of the picture at `pointer`; null when nothing changes. */
-export declare function altTextPatch(document: unknown, pointer: string, text: string): JsonPatchOperation[] | null;
+export declare function altTextPatch(presentation: unknown, pointer: string, text: string): JsonPatchOperation[] | null;
 export declare function setReviewAltText(editor: EditorSession, pointer: string, text: string, meta?: Record<string, unknown>): { changed: boolean } & Partial<EditorChange>;
 export declare function markDecorative(editor: EditorSession, pointer: string, meta?: Record<string, unknown>): { changed: boolean } & Partial<EditorChange>;
-export declare function currentAltText(document: unknown, pointer: string): string;
+export declare function currentAltText(presentation: unknown, pointer: string): string;