@openpresentation/opf-editor 0.26.10 → 0.27.0

package/dist/react.js

@@ -1,3 +1,4 @@
+import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore } from "react";
 import { commitCatalogControl } from "./catalog-control.js";
 import {
   getCatalogOptions,
@@ -96,3 +97,122 @@ export function createOPFReactComponents(React) {
     OPFCatalogSelect
   };
 }
+
+// ---- CE-06: the embeddable editor for React 18 and 19 ----------------------------------------------------------------------------------
+// `<OpfEditor>` mounts `createOpfEditor` (src/workspace.js) in an effect and destroys it in the cleanup, so it is correct under StrictMode's
+// mount, unmount, mount: the editor module is loaded on demand (an import that resolves after both effects), the first effect's request is
+// cancelled by its cleanup, and only the second creates an editor. The server renders an empty container; nothing of the editor
+// (and none of its code) runs there. React is an optional peer: only this entry point needs it.
+
+const NO_STOP = () => {};
+const isRef = (value) => value !== null && typeof value === "object" && "current" in value;
+
+/** `slots` whose values are React refs (`useRef`) resolve to their elements when the editor mounts, after the commit that attached them. */
+function resolveSlots(slots) {
+  if (!slots) return undefined;
+  const resolved = {};
+  for (const [name, value] of Object.entries(slots)) resolved[name] = isRef(value) ? value.current : value;
+  return resolved;
+}
+
+// The props that are not editor options.
+const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onError", "onReady"]);
+
+function splitProps(props) {
+  const options = {};
+  const rest = {};
+  for (const [name, value] of Object.entries(props)) (COMPONENT_PROPS.has(name) ? rest : options)[name] = value;
+  return { options, rest };
+}
+
+/**
+ * Create and destroy one editor in the element `container.current` points at. The options are read once, when the editor mounts (change the
+ * `key` of the component to mount another); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders. The callbacks
+ * (`onChange`, `onSelection`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
+ */
+function useMountedEditor(container, props, onEditor) {
+  const [editor, setEditor] = useState(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const report = useRef(onEditor);
+  report.current = onEditor;
+  useEffect(() => {
+    const element = container.current;
+    if (!element) return undefined;
+    let cancelled = false;
+    let created = null;
+    import("./workspace.js").then(({ createOpfEditor }) => {
+      if (cancelled) return;
+      const { options } = splitProps(latest.current);
+      const current = () => latest.current;
+      created = createOpfEditor(element, {
+        ...options,
+        slots: resolveSlots(latest.current.slots),
+        onChange: (detail) => current().onChange?.(detail),
+        onSelection: (detail) => current().onSelection?.(detail),
+        onError: (error, detail) => current().onError?.(error, detail),
+        onReady: (detail) => current().onReady?.(detail),
+      });
+      setEditor(created);
+      report.current?.(created);
+    }, (error) => {
+      if (!cancelled) latest.current.onError?.(error instanceof Error ? error : new Error(String(error)), {});
+    });
+    return () => {
+      cancelled = true;
+      if (!created) return;
+      created.destroy();
+      created = null;
+      setEditor(null);
+      report.current?.(null);
+    };
+    // The editor mounts once per element: later options are applied by the effects below, or by a new `key`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [container]);
+  const { theme, readOnly, view, density, exportMode } = props;
+  // A theme written inline in JSX is a new object on every render; it is applied again only when its content changed.
+  const themeKey = theme === undefined ? undefined : JSON.stringify(theme);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => { if (editor && theme !== undefined) editor.setTheme(theme); }, [editor, themeKey]);
+  useEffect(() => { if (editor && readOnly !== undefined) editor.setReadOnly(readOnly); }, [editor, readOnly]);
+  useEffect(() => { if (editor && view !== undefined && editor.view !== view) editor.setView(view); }, [editor, view]);
+  useEffect(() => { if (editor && density !== undefined) editor.setDensity(density); }, [editor, density]);
+  useEffect(() => { if (editor && exportMode !== undefined) editor.setExportMode(exportMode); }, [editor, exportMode]);
+  return editor;
+}
+
+/**
+ * The editor in a `<div>`. Every prop that is not `className`, `style`, `id`, `slots` or a callback is an option of `createOpfEditor`;
+ * `ref` is the editor handle once mounted, and `onEditor(editor | null)` tells the parent when it is created and destroyed (for the hooks below).
+ */
+export const OpfEditor = forwardRef(function OpfEditor(props, ref) {
+  const container = useRef(null);
+  const editor = useMountedEditor(container, props, props.onEditor);
+  useImperativeHandle(ref, () => editor, [editor]);
+  const { rest } = splitProps(props);
+  return createElement("div", { ref: container, id: rest.id, className: rest.className, style: rest.style, "data-opf-react": "" });
+});
+
+/**
+ * The editor as a hook, for a host that renders its own element: `const { ref, editor } = useOpfEditor(options)` and `<div ref={ref} />`.
+ * `editor` is `null` on the server and until the client has mounted it. Options are read once, as for `<OpfEditor>`.
+ */
+export function useOpfEditor(options = {}) {
+  const ref = useRef(null);
+  const editor = useMountedEditor(ref, options);
+  return { ref, editor };
+}
+
+const subscribeTo = (editor, event) => (notify) => (editor ? editor.on(event, notify) : NO_STOP);
+
+/** The document of an editor, replaced on every change (it is frozen, so it works as a store snapshot). `undefined` until there is an editor. */
+export function useOpfDocument(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "change"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.getDocument() : undefined), () => undefined);
+}
+
+/** The content last selected on the canvas, `{ path, value }`, or `null`. */
+export function useOpfSelection(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "selection"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.selection : null), () => null);
+}

package/dist/slide-retention.js

@@ -0,0 +1,13 @@
+// CE-06 (promoted from openpresentation.org's playground runtime): which slide to show after the document changed outside the canvas
+// (the source pane, an opened file, a restored copy). Stable ids survive a reorder; a deck without ids, or an id that is not unique, keeps
+// the position and clamps it to the deck.
+
+/** @param {readonly {id?: string}[]} before @param {readonly {id?: string}[]} after @param {number} index */
+export function retainedSlideIndex(before, after, index) {
+  const id = before[index]?.id;
+  if (id && before.filter((slide) => slide.id === id).length === 1) {
+    const matches = after.flatMap((slide, position) => (slide.id === id ? [position] : []));
+    if (matches.length === 1) return matches[0];
+  }
+  return Math.max(0, Math.min(index, after.length - 1));
+}

package/dist/styles.css

@@ -1,7 +1,8 @@
 /*
  * OPF editor UI tokens (RR-98). Every other file in this stylesheet uses only these `--opf-ui-*` variables.
  * Values copy the openpresentation.org design system. The host loads Inter and Geist Mono; nothing here fetches a font.
- * Light is the default. Dark applies under `.dark .opf-ui`, `.opf-ui.dark`, `[data-theme=dark]` (on the root or on any ancestor) and `:root.dark`.
+ * Light is the default. Dark applies under `.dark .opf-ui`, `.opf-ui.dark`, `[data-theme=dark]` (on the root or on any ancestor) and `:root.dark`;
+ * `[data-theme=light]` on an ancestor or on the surface forces light inside a dark page. docs/theming.md is the contract for hosts.
  */
 :root,
 .opf-ui {
@@ -66,6 +67,39 @@
   color-scheme: dark;
 }
 
+/*
+ * A surface that forces light (`data-theme="light"` on the editor root, the `colorScheme: "light"` theme option) wins over a dark page.
+ * The values repeat the light block above; test/styles.mjs keeps the two equal.
+ */
+[data-theme="light"].opf-ui,
+[data-theme="light"] .opf-ui,
+.dark [data-theme="light"].opf-ui,
+.dark [data-theme="light"] .opf-ui,
+[data-theme="dark"] [data-theme="light"].opf-ui,
+[data-theme="dark"] [data-theme="light"] .opf-ui {
+  --opf-ui-bg: hsl(210 30% 98%);
+  --opf-ui-surface: hsl(0 0% 100%);
+  --opf-ui-muted: hsl(214 28% 93%);
+  --opf-ui-muted-2: hsl(214 28% 96%);
+  --opf-ui-fg: hsl(220 28% 11%);
+  --opf-ui-muted-fg: hsl(218 14% 38%);
+  --opf-ui-accent: hsl(214 57% 28%);
+  --opf-ui-accent-fg: hsl(0 0% 100%);
+  --opf-ui-accent-strong: hsl(214 57% 28%);
+  --opf-ui-border: hsl(214 22% 83%);
+  --opf-ui-border-strong: hsl(214 22% 72%);
+  --opf-ui-ring: hsl(214 57% 28%);
+  --opf-ui-danger: hsl(0 72% 45%);
+  --opf-ui-warn: hsl(28 75% 38%);
+  --opf-ui-success: hsl(152 76% 26%);
+  --opf-ui-code-bg: hsl(220 30% 96%);
+  --opf-ui-code-border: hsl(214 18% 84%);
+
+  --opf-ui-shadow-pop: 0 8px 24px rgba(0, 0, 0, 0.1);
+
+  color-scheme: light;
+}
+
 /* Touch density: controls grow to 40px, as in the mobile design. */
 .opf-ui[data-density="touch"],
 [data-density="touch"] .opf-ui {
@@ -5044,3 +5078,266 @@ input.opf-lx-input[data-field="max"] { font-family: var(--opf-ui-mono); font-siz
     min-height: 44px;
   }
 }
+
+/* workspace.css */
+/* The embeddable editor (CE-06): the default arrangement `createOpfEditor` builds for `layout: "full" | "canvas" | "source"`.
+   Uses only --opf-ui-* tokens. A host that passes its own `slots` ignores all of this except the `data-` attributes. */
+.opf-workspace {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  background: var(--opf-ui-bg);
+  color: var(--opf-ui-fg);
+  font-family: var(--opf-ui-font);
+}
+/* A host that arranges the page itself gets no box from the editor. */
+.opf-workspace[data-opf-layout="slots"] {
+  display: contents;
+}
+.opf-ws-bar {
+  display: flex;
+  flex: none;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  padding: 6px 12px;
+  border-bottom: 1px solid var(--opf-ui-border);
+  background: var(--opf-ui-surface);
+}
+.opf-ws-group,
+.opf-ws-views {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+.opf-ws-spacer {
+  flex: 1 1 0;
+}
+.opf-ws-button {
+  box-sizing: border-box;
+  min-height: var(--opf-ui-control-h);
+  padding: 0 12px;
+  border: 1px solid var(--opf-ui-border);
+  border-radius: var(--opf-ui-radius);
+  background: var(--opf-ui-surface);
+  color: var(--opf-ui-fg);
+  font: 500 13px/1 var(--opf-ui-font);
+  cursor: pointer;
+  transition: color var(--opf-ui-ease), background-color var(--opf-ui-ease), border-color var(--opf-ui-ease);
+}
+.opf-ws-button:hover:not(:disabled) {
+  background: var(--opf-ui-muted);
+}
+.opf-ws-button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+.opf-ws-button[aria-pressed="true"],
+.opf-ws-button[aria-expanded="true"] {
+  border-color: var(--opf-ui-accent);
+  background: var(--opf-ui-muted);
+  color: var(--opf-ui-accent-strong);
+}
+.opf-ws-autosave {
+  max-width: 240px;
+  color: var(--opf-ui-muted-fg);
+  font-size: 12px;
+  line-height: 1.3;
+}
+.opf-ws-banner {
+  flex: none;
+}
+.opf-ws-banner[hidden] {
+  display: none;
+}
+.opf-ws-body {
+  display: flex;
+  flex: 1 1 0;
+  min-height: 0;
+}
+.opf-ws-source {
+  display: flex;
+  flex: 0 1 42%;
+  min-width: 280px;
+  min-height: 0;
+  border-right: 1px solid var(--opf-ui-border);
+  background: var(--opf-ui-surface);
+}
+.opf-ws-source-host {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+.opf-ws-main {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+.opf-ws-find {
+  flex: none;
+  padding: 8px 12px 0;
+}
+.opf-ws-find[hidden] {
+  display: none;
+}
+.opf-ws-stage {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  min-height: 0;
+  padding: 12px;
+  overflow: auto;
+}
+.opf-ws-frame {
+  display: grid;
+  flex: 1 1 0;
+  place-items: center;
+  min-height: 0;
+}
+.opf-ws-frame[hidden],
+.opf-ws-view[hidden] {
+  display: none;
+}
+.opf-ws-canvas {
+  position: relative;
+  overflow: hidden;
+  border: 1px solid var(--opf-ui-border);
+  border-radius: var(--opf-ui-radius-sm);
+  background: var(--opf-ui-surface);
+}
+.opf-ws-view {
+  flex: 1 1 0;
+  min-height: 0;
+  overflow: auto;
+}
+.opf-ws-dock {
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 0 12px 8px;
+}
+.opf-ws-status {
+  flex: none;
+  margin: 0;
+  padding: 4px 12px 8px;
+  color: var(--opf-ui-muted-fg);
+  font-size: 12px;
+}
+.opf-ws-side {
+  display: flex;
+  flex: 0 0 300px;
+  flex-direction: column;
+  min-height: 0;
+  border-left: 1px solid var(--opf-ui-border);
+  background: var(--opf-ui-surface);
+  overflow: auto;
+}
+.opf-ws-tabs {
+  display: flex;
+  gap: 2px;
+  padding: 6px 8px 0;
+  border-bottom: 1px solid var(--opf-ui-border);
+}
+.opf-ws-tab {
+  min-height: var(--opf-ui-control-h);
+  padding: 0 12px;
+  border: 0;
+  border-bottom: 2px solid transparent;
+  background: transparent;
+  color: var(--opf-ui-muted-fg);
+  font: 500 13px/1 var(--opf-ui-font);
+  cursor: pointer;
+}
+.opf-ws-tab[aria-selected="true"] {
+  border-bottom-color: var(--opf-ui-accent);
+  color: var(--opf-ui-fg);
+}
+.opf-ws-panel {
+  padding: 12px;
+}
+.opf-ws-panel[hidden] {
+  display: none;
+}
+/* Layout Studio inside the workspace. */
+.opf-ws-layouts {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.opf-ws-layouts-bar {
+  display: flex;
+  flex: none;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+.opf-ws-layouts-bar select,
+.opf-ws-layouts-bar button {
+  min-height: var(--opf-ui-control-h);
+  border: 1px solid var(--opf-ui-border);
+  border-radius: var(--opf-ui-radius);
+  background: var(--opf-ui-surface);
+  color: var(--opf-ui-fg);
+  font: 500 13px/1 var(--opf-ui-font);
+}
+.opf-ws-layouts-bar button {
+  padding: 0 12px;
+  cursor: pointer;
+}
+.opf-ws-layouts-bar button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+.opf-ws-layouts-pick {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--opf-ui-muted-fg);
+  font-size: 12px;
+}
+.opf-ws-layouts-status {
+  color: var(--opf-ui-muted-fg);
+  font-size: 12px;
+}
+.opf-ws-layouts-host {
+  flex: 1 1 0;
+  min-height: 0;
+}
+/* A phone: the parts stack, the source above the slide, the side panel below. */
+@media (max-width: 760px) {
+  .opf-ws-body {
+    flex-direction: column;
+    overflow: auto;
+  }
+  .opf-ws-source {
+    flex: none;
+    min-width: 0;
+    height: 40vh;
+    border-right: 0;
+    border-bottom: 1px solid var(--opf-ui-border);
+  }
+  .opf-ws-main {
+    flex: none;
+  }
+  .opf-ws-stage {
+    flex: none;
+    min-height: 40vh;
+  }
+  .opf-ws-side {
+    flex: none;
+    border-left: 0;
+    border-top: 1px solid var(--opf-ui-border);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .opf-ws-button {
+    transition: none;
+  }
+}

package/dist/workspace-layouts.d.ts

@@ -0,0 +1,31 @@
+import type { EditorSession } from "./index.js";
+import type { LayoutEditor, LayoutEditorDensity } from "./layout-editor.js";
+
+export interface LayoutStudioOptions {
+  session: EditorSession;
+  toSvg?: (...args: any[]) => string;
+  fonts?: unknown;
+  renderOptions?: Record<string, unknown> | (() => Record<string, unknown>);
+  getSlideIndex: () => number;
+  onStatus?: (message: string) => void;
+  density?: LayoutEditorDensity;
+  readOnly?: boolean;
+  labels?: Partial<Record<"layout" | "pick" | "fresh" | "save" | "apply", string>>;
+}
+/** Layout Studio inside the workspace: the layout editor over the deck's own custom layouts, with a bar to pick, save and apply. */
+export interface LayoutStudio {
+  element: HTMLElement;
+  editor: LayoutEditor;
+  pick: HTMLSelectElement;
+  save: HTMLButtonElement;
+  apply: HTMLButtonElement;
+  status: HTMLElement;
+  /** Re-read the deck's custom layouts into the picker. */
+  refresh(): void;
+  /** Edit the deck's layout `id`, or a new layout for `""`. */
+  load(id: string): void;
+  setReadOnly(readOnly: boolean): void;
+  setDensity(density: LayoutEditorDensity): void;
+  destroy(): void;
+}
+export declare function createLayoutStudio(container: HTMLElement, options: LayoutStudioOptions): LayoutStudio;

package/dist/workspace-layouts.js

@@ -0,0 +1,84 @@
+// CE-06 (promoted from examples/playground.js): Layout Studio inside the workspace. The layout editor (palette, canvas, layers, inspector)
+// works on one layout record at a time; "Save to deck" writes it to `catalogs.custom.layouts` (one undoable edit) and "Use on this slide"
+// also makes it the layout of the current slide. A bar above the editor picks which of the deck's own layouts to edit.
+import { blankLayoutRecord, createLayoutEditor } from "./layout-editor.js";
+
+const make = (doc, tag, attributes = {}, ...children) => {
+  const node = doc.createElement(tag);
+  for (const [name, value] of Object.entries(attributes)) {
+    if (name === "text") node.textContent = value;
+    else node.setAttribute(name, value);
+  }
+  node.append(...children);
+  return node;
+};
+
+/**
+ * Mount Layout Studio in `container`. Returns `{ element, refresh, destroy, load }`. `refresh()` re-reads the deck's layouts into the picker (call it
+ * when the view opens); `load(id)` edits the deck's layout `id`, or a new layout for `""`.
+ */
+export function createLayoutStudio(container, { session, toSvg, fonts, renderOptions, getSlideIndex, onStatus, density = "comfortable", readOnly = false, labels = {} }) {
+  const doc = container.ownerDocument;
+  const text = { layout: "Layout", pick: "Layout to edit", fresh: "New layout", save: "Save to deck", apply: "Use on this slide", ...labels };
+  const pick = make(doc, "select", { "data-opf-layouts": "pick", "aria-label": text.pick }, make(doc, "option", { value: "", text: text.fresh }));
+  const save = make(doc, "button", { type: "button", "data-opf-layouts": "save", text: text.save });
+  const apply = make(doc, "button", { type: "button", "data-opf-layouts": "apply", text: text.apply });
+  const status = make(doc, "span", { "data-opf-layouts": "status", role: "status", class: "opf-ws-layouts-status" });
+  const bar = make(doc, "div", { class: "opf-ws-layouts-bar" }, make(doc, "label", { class: "opf-ws-layouts-pick", text: `${text.layout} ` }, pick), save, apply, status);
+  const host = make(doc, "div", { class: "opf-ws-layouts-host" });
+  container.replaceChildren(bar, host);
+  save.disabled = apply.disabled = readOnly;
+
+  const customLayouts = () => session.presentation.catalogs?.custom?.layouts ?? {};
+  function freeLayoutId() {
+    const taken = customLayouts();
+    if (!taken["my-layout"]) return "my-layout";
+    for (let n = 2; ; n++) if (!taken[`my-layout-${n}`]) return `my-layout-${n}`;
+  }
+  const say = (message) => { status.textContent = message; };
+  function refresh() {
+    const current = pick.value;
+    const layouts = customLayouts();
+    pick.replaceChildren(new Option(text.fresh, ""), ...Object.entries(layouts).map(([id, record]) => new Option(`${record.name || id} (${id})`, id)));
+    pick.value = current in layouts ? current : "";
+  }
+  const editor = createLayoutEditor(host, { record: { ...blankLayoutRecord(), id: freeLayoutId() }, toSvg, fonts, renderOptions, density, readOnly });
+  function load(id) {
+    const layouts = customLayouts();
+    editor.setRecord(id ? { id, ...structuredClone(layouts[id]) } : { ...blankLayoutRecord(), id: freeLayoutId() });
+    say(id ? `Editing ${id}. Save to deck replaces it.` : "A new layout. Save to deck adds it to this presentation.");
+  }
+  const problem = (error) => error.issues?.[0]?.message ?? error.message;
+  pick.onchange = () => load(pick.value);
+  save.onclick = () => {
+    const replace = pick.value === editor.getRecord().id;
+    try {
+      const change = editor.saveToDeck(session, { replace });
+      refresh();
+      pick.value = change.layoutId;
+      say(`Saved ${change.layoutId} in custom layouts`);
+      onStatus?.(`Saved ${change.layoutId} in custom layouts`);
+    } catch (error) { say(problem(error)); }
+  };
+  apply.onclick = () => {
+    try {
+      const slideIndex = getSlideIndex();
+      const change = editor.applyToSlide(session, slideIndex);
+      refresh();
+      pick.value = change.layoutId;
+      say(`Slide ${slideIndex + 1} now uses ${change.layoutId}`);
+    } catch (error) { say(problem(error)); }
+  };
+  refresh();
+  load("");
+  return {
+    element: bar.parentElement,
+    editor,
+    pick, save, apply, status,
+    refresh,
+    load,
+    setReadOnly(on) { editor.setReadOnly(on); save.disabled = apply.disabled = on; },
+    setDensity(next) { editor.setDensity(next); },
+    destroy() { editor.destroy(); container.replaceChildren(); },
+  };
+}

package/dist/workspace-measure.js

@@ -0,0 +1,35 @@
+// CE-06 (promoted from examples/playground.js): text measurement and font notes shared by the workspace parts.
+import { createScriptTextMeasurement } from "@openpresentation/opf-render/fonts";
+import { resolveScriptFonts } from "@openpresentation/opf/composition";
+
+/**
+ * The layout options for composing slide `index` of `deck`: the fonts handle's measurement, made script-aware for this document (Japanese
+ * under Aptos measures with Noto Sans JP, where the plain strict measurement would throw "cannot display U+65E5" with every face loaded).
+ * A fonts handle without a measurement is passed through.
+ */
+export function layoutOptionsFor(fonts, deck, index, catalogs) {
+  if (!fonts?.textMeasurement) return fonts ? { fonts } : {};
+  try {
+    return { fonts: { textMeasurement: createScriptTextMeasurement(fonts.textMeasurement, resolveScriptFonts(deck, { slideIndex: index, catalogs })) } };
+  } catch {
+    return { fonts };
+  }
+}
+
+/** Review text for one font resolution the registry recorded. A change inside one family is a style fallback, not a replacement font. */
+export function describeFontChange(change) {
+  const sameFamily = (change.sourceFamily ?? change.requestedFamily).toLowerCase() === change.resolvedFamily.toLowerCase();
+  if (!sameFamily) return `${change.requestedFamily} → ${change.resolvedFamily} · ${change.compatibility === "metric" ? "Metric substitute" : "Approximate substitute; wrapping may change"} (${change.resolvedWeight}).`;
+  const drawn = `${change.resolvedFamily} ${change.resolvedWeight}${change.italic ? " italic" : ""}`;
+  return change.requestedWeight === change.resolvedWeight
+    ? `${change.requestedFamily}: the ${change.italic ? "italic" : "upright"} face asked for is not available, so ${drawn} is drawn; wrapping may change.`
+    : `${change.requestedFamily} ${change.requestedWeight}: that weight is not available, so ${drawn} is drawn; wrapping may change.`;
+}
+
+/** Notes (`{ path, message }`) for the font substitutions a fonts handle recorded, one per requested face. */
+export function fontSubstitutionNotes(fonts) {
+  const changes = fonts?.substitutions ?? [];
+  return changes
+    .filter((change, index, all) => all.findIndex((other) => other.requestedFamily === change.requestedFamily && other.requestedWeight === change.requestedWeight && other.italic === change.italic) === index)
+    .map((change) => ({ path: change.path ?? "design.fontScheme", message: describeFontChange(change) }));
+}