@openpresentation/opf-editor 0.24.2 → 0.24.3

package/README.md

@@ -831,6 +831,67 @@ const dialog = createAgentHandoffDialog(document.body, { document: deck, target:
 
 Icons are inlined path data from [Lucide](https://lucide.dev) (ISC license), never loaded from a CDN.
 
+## Presenter and Present button (RR-98)
+
+`@openpresentation/opf-editor/presenter` shows the deck full screen, one slide at a time. It is plain DOM like the other modules, with no network, no fonts or CSS fetched at runtime, and no second renderer: slides are drawn by `toSvg` with the same fonts handle, catalogs and render options the canvas and the thumbnails use. Its CSS is `src/styles/presenter.css` (classes `opf-presenter-*` and `opf-present-button`; `--opf-ui-*` tokens only, part of `styles.css`). The module needs `@openpresentation/opf-render`, an optional peer, like the thumbnail strip.
+
+```js
+import { createPresenter, createPresentButton, bindPresentShortcut } from "@openpresentation/opf-editor/presenter";
+
+const presenter = createPresenter(document.body, {
+  editor,                      // or presentation: deck (an object, or a function returning it)
+  fonts,                       // the renderer's fonts handle, the same one the canvas and the exports use
+  renderOptions: { catalogs }, // merged after the session's catalogs
+  slideIndex: current,         // the slide start() opens on (default 0)
+  onSlideChange: (index) => {},  // the shown slide changed (deck index)
+  onExit: (index) => { current = index; redraw(); }, // by any route: the host returns to that slide
+  density: "comfortable",      // "touch": the exit button is 40px
+});
+createPresentButton(document.querySelector("#present"), { onPresent: () => presenter.start(current) });
+bindPresentShortcut(document, () => presenter.start(current)); // F5
+```
+
+`createPresenter(container, options)` returns `{ element, start(slideIndex?), stop(), next(), previous(), goTo(index), getSlide(), isRunning(), destroy() }`. The presenter stays hidden until `start`. Call `start` from a user gesture (a click or a key press): the browser grants full screen only then. `start` resolves `"fullscreen"` or `"overlay"`.
+
+- **Display.** The presenter's own element goes full screen through the Fullscreen API. When the browser refuses (no gesture, an iframe without `allow="fullscreen"`, iPhone Safari), the same element is a fixed overlay over the window, so everything below works the same. Slides fill the viewport and letterbox on black. The next and previous slides are drawn ahead, so advancing draws nothing. Slides draw with their `{{variables}}` resolved, as the exports do.
+- **Navigation.** Right, Space, PageDown and Enter go forward; Left, PageUp and Backspace go back; Home and End jump; Esc exits. A click advances, and a click on the left third goes back. On touch, a swipe left goes forward and a swipe right goes back; a tap uses the same zones. Keys with Ctrl, Alt or Meta are left to the browser, and the keys the presenter handles do not reach the host page.
+- **Hidden slides** are skipped, as the exports skip them (`slidesToConvert`; `includeHidden: true` presents them). `start(i)` and `goTo(i)` on a hidden slide show the next slide that is not hidden (`onSlideChange` says which). A deck with only hidden slides shows a message and `onExit(-1)`.
+- **Counter.** A subtle "03 / 12" (mono, the navigator's format; hidden slides are not counted) and the exit button show on pointer move and hide after 2 seconds, with the cursor.
+- **Exit.** Esc, the exit button, leaving full screen (the browser's Esc), `stop()` and `destroy()` all call `onExit(index)` with the deck index of the slide shown, then focus returns to the element that was focused at `start`.
+- **Accessibility.** The element is `role="dialog"` with `aria-modal="true"` and an `aria-label` ("Presentation"; `labels.dialog`). Focus moves into it on start and stays in it (Tab cycles the dialog and the exit button). An `aria-live="polite"` region announces "Slide 3 of 12" (`labels.position`).
+- **Fonts.** Like the canvas, the presenter waits for the faces the deck needs (`fonts.pending` and `fonts.ensure`) and shows "Loading fonts…" meanwhile.
+
+`createPresentButton(container, { onPresent, disabled, density })` mounts an icon-only button (the Lucide Presentation icon, inlined) named "Present" (`aria-label`), titled "Present (F5)" and styled like the Export menu's trigger. `disabled` is `true` or a reason string (the title); the button stays focusable (`aria-disabled`) and does nothing. It returns `{ element, setDisabled(reason), setDensity(density), destroy() }`. `bindPresentShortcut(target, onPresent)` binds F5 (and prevents the browser's reload); it ignores F5 while typing in inputs, selects and editors (CodeMirror, contenteditable), in menus and dialogs, and with a modifier key, and returns a function that removes the listener. `examples/playground.js` wires all three next to the Export menu.
+
+Tests: `npm run test:presenter-browser` and `npm run test:present-button-browser`.
+
+## Opening a deck file (RR-98)
+
+`@openpresentation/opf-editor/read-deck-file` reads a deck file in any OPF source format, with no DOM:
+
+```js
+import { readDeckFile, DECK_FILE_ACCEPT, DeckFileError } from "@openpresentation/opf-editor/read-deck-file";
+
+input.accept = DECK_FILE_ACCEPT;            // ".json,.opf,.yaml,.yml,.md"
+input.onchange = async () => {
+  try {
+    const { document, format, name, findings } = await readDeckFile(input.files[0], { catalogs });
+    const editor = createEditorSession(document, { catalogs }); // the session validates it; findings say what to fix first
+  } catch (error) {
+    if (error instanceof DeckFileError) show(error.code, error.message, error.findings);
+  }
+};
+```
+
+`readDeckFile(file | { name, text }, { catalogs? })` takes a `File` (or anything with `name` and `text()`), or `{ name, text }` with the text as a string, and returns `{ document, format: "json" | "yaml" | "md", name, findings }`.
+
+- **Format.** The extension picks it: `.yaml` and `.yml` are YAML, `.md` is Markdown, and `.json`, `.opf` or anything else is JSON. If JSON fails to parse, the text is tried as YAML, and as Markdown when it starts with front matter (`---`); `format` is the one that read it. YAML and Markdown go through core's browser-safe `fromYaml` and `fromMarkdown` (`@openpresentation/opf/yaml` and `/markdown`, loaded on first use). JSON that wraps a deck (`opfSnippet`, `opf`, `presentation`) is unwrapped as `parseOpfTransfer` does.
+- **Name.** The file name without a directory and without `.opf.json`, `.opf.yaml`, `.opf.md` or its plain extension (`Q3 plan.opf.yaml` gives `Q3 plan`).
+- **Findings.** The conversion's findings for YAML and Markdown, in core's `Finding` shape: `path` (a JSON Pointer such as `/slides/1/bogus`), `message`, `severity` and `location` (line and column in the file). A deck that reads but has OPF errors is returned with them, so a host can show them; JSON gives none (the editor session validates it).
+- **Errors.** Text that cannot be read at all throws `DeckFileError` with a `code` and a clear message: `unreadable`, `file-too-large` (over 20 MB), `empty-file`, `unsupported-file` (a .pptx or other binary file), `invalid-json`, `invalid-yaml`, `invalid-markdown` (with the syntax `findings` and the line) and `not-a-deck` (JSON without a `slides` list, such as one slide or a block, which a host can send to its paste path as the playground does).
+
+The source pane has no file-opening path of its own, so it keeps no second copy of this. The playground's Import dialog uses `readDeckFile` and `DECK_FILE_ACCEPT` for its file tab and for dropped files (`examples/transfer-controls.js`). Icons in the presenter button are inlined [Lucide](https://lucide.dev) paths (ISC license).
+
 ## Optional React Bindings
 
 React bindings are isolated under `@openpresentation/opf-editor/react` and require the host app to pass its React runtime. The core package does not add React to the critical path.

package/dist/presenter.d.ts

@@ -0,0 +1,102 @@
+import type { EditorSession } from "./index.js";
+import type { ToSvgOptions } from "@openpresentation/opf-render";
+import type { EditorFonts } from "./canvas.js";
+
+export interface PresenterLabels {
+  /** The accessible name of the presenter dialog. Default: "Presentation". */
+  dialog?: string;
+  /** The accessible name and title of the exit button. Default: "Exit presentation". */
+  exit?: string;
+  /** Default: "Exit (Esc)". */
+  exitTitle?: string;
+  /** What the live region announces. Default: "Slide 3 of 12" (both numbers count the slides that are shown, not the hidden ones). */
+  position?: (position: number, count: number) => string;
+  /** Shown while the faces the deck needs load. Default: "Loading fonts…". */
+  loading?: string;
+  /** Shown when every slide is hidden. */
+  empty?: string;
+}
+
+export interface PresenterOptions {
+  /** The editor session. The presenter reads its current document and catalogs. */
+  editor?: EditorSession;
+  /** Without an editor: an OPF presentation, or a function returning the current one. Keep the object stable while presenting: slides are drawn once per object. */
+  presentation?: { slides?: unknown[] } | (() => { slides?: unknown[] });
+  /**
+   * The renderer's fonts handle (`loadFonts()`), the one the canvas, the thumbnails and the exports use. With its `pending` and `ensure` the
+   * presenter loads the faces a deck needs before it draws ("Loading fonts…" meanwhile).
+   */
+  fonts?: EditorFonts;
+  /** Extra `toSvg` options, such as `catalogs` (merged after the session's). Slides draw with `text: "system"`, `trace: false` and their `{{variables}}` resolved. */
+  renderOptions?: ToSvgOptions;
+  /** The slide `start()` opens on (0-based deck index; default 0). A hidden slide opens the next one that is not hidden. */
+  slideIndex?: number;
+  /** The presentation closed, by any route (Esc, the exit button, leaving full screen, `stop()`, `destroy()`). `index` is the deck index of the slide it showed, so the host can return to it. */
+  onExit?(index: number): void;
+  /** The shown slide changed (deck index): by key, click, swipe or `next`, `previous` and `goTo`. Also once at start when a hidden slide was requested. */
+  onSlideChange?(index: number): void;
+  /** `"touch"` makes the exit button 40px. Default `"comfortable"` (32px). */
+  density?: "comfortable" | "touch";
+  /** Show hidden slides too (default false: they are skipped, as the exports skip them). */
+  includeHidden?: boolean;
+  labels?: PresenterLabels;
+}
+
+export interface Presenter {
+  /** The root element, mounted in the container: `role="dialog"`, `aria-modal`, hidden until `start`. `data-mode` is `fullscreen` or `overlay`. */
+  readonly element: HTMLElement;
+  /**
+   * Open the presentation on `slideIndex` (default: the `slideIndex` option) and ask the browser for full screen. Call it from a user gesture
+   * (a click, a key press): browsers refuse full screen otherwise, and the presentation then fills the window as a fixed overlay. Resolves
+   * with the mode once the browser answered. Calling it while open goes to that slide.
+   */
+  start(slideIndex?: number): Promise<"fullscreen" | "overlay">;
+  /** Close the presentation, leave full screen, return focus to the element that was focused at `start`, and call `onExit(index)`. */
+  stop(): void;
+  /** Show the next slide that is not hidden. Returns false at the end. */
+  next(): boolean;
+  /** Show the previous slide that is not hidden. Returns false at the start. */
+  previous(): boolean;
+  /** Show a slide by its deck index (a hidden slide shows the next one that is not hidden). Returns false when the shown slide did not change. */
+  goTo(index: number): boolean;
+  /** The deck index of the shown slide; -1 when stopped or when every slide is hidden. */
+  getSlide(): number;
+  isRunning(): boolean;
+  /** `stop()`, then remove the element. */
+  destroy(): void;
+}
+
+/**
+ * The presenter: full screen (or a fixed overlay), one slide at a time on black, drawn by the renderer, catalogs and fonts handle the canvas
+ * uses. Right, Space, PageDown and Enter go forward; Left, PageUp and Backspace go back; Home and End jump; Esc exits. A click goes forward,
+ * a click on the left third goes back, and a swipe on touch moves. A "03 / 12" counter shows on pointer move for 2 seconds.
+ * CSS: `src/styles/presenter.css`, classes `opf-presenter-*`.
+ */
+export declare function createPresenter(container: HTMLElement, options: PresenterOptions): Presenter;
+
+export interface PresentButtonOptions {
+  /** The button was activated (not called while disabled). */
+  onPresent?(event: MouseEvent): void;
+  /** `true` disables with a default reason, a string with your own (it is the title). The button stays focusable (`aria-disabled`) and does nothing. */
+  disabled?: boolean | string;
+  /** `"touch"` makes the button 40px. Default `"comfortable"` (32px). */
+  density?: "comfortable" | "touch";
+  /** The accessible name (default "Present"). */
+  label?: string;
+}
+
+export interface PresentButton {
+  readonly element: HTMLButtonElement;
+  setDisabled(reason?: boolean | string): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  destroy(): void;
+}
+
+/** The icon-only Present button: a Lucide Presentation icon, `aria-label="Present"`, title "Present (F5)", styled like the Export trigger. */
+export declare function createPresentButton(container: HTMLElement, options?: PresentButtonOptions): PresentButton;
+
+/**
+ * Bind F5 to `onPresent(event)` on `target` (default: the document); the browser's reload is suppressed when it fires. F5 is ignored while
+ * typing in inputs, selects and editors, in menus and dialogs, and with a modifier key held. Returns a function that removes the listener.
+ */
+export declare function bindPresentShortcut(target: Document | HTMLElement | Window | undefined | null, onPresent: (event: KeyboardEvent) => void): () => void;

package/dist/presenter.js

@@ -0,0 +1,429 @@
+// RR-98: the presenter and the Present button. `createPresenter` shows the deck full screen (the Fullscreen API on its own element, with a fixed
+// overlay when the browser refuses), one slide at a time, letterboxed on black. Slides are drawn by the renderer the canvas and the thumbnails
+// use (`toSvg` with the host's one fonts handle and catalogs); the next and previous slides are drawn ahead, so advancing is instant. Hidden
+// slides are skipped, as the exports skip them (`slidesToConvert`). `createPresentButton` is the icon-only trigger and `bindPresentShortcut`
+// binds F5. Plain DOM, no framework, no network; styles in src/styles/presenter.css (classes `opf-presenter-*` and `opf-present-button`).
+import { toSvg } from "@openpresentation/opf-render/svg";
+import { mergeCatalogs } from "./catalogs.js";
+import { el, icon } from "./export-dom.js";
+import { whenFontsReady } from "./font-gate.js";
+import { formatSlideCounter } from "./slide-navigator.js";
+
+const COUNTER_MS = 2000;
+const PRELOAD_DELAY_MS = 20;
+const SWIPE_MIN = 48;
+const SWIPE_MAX_MS = 800;
+const TAP_SLOP = 10;
+const TAP_MAX_MS = 600;
+const CLICK_GUARD_MS = 450;
+const NEXT_KEYS = new Set(["ArrowRight", " ", "PageDown", "Enter"]);
+const PREVIOUS_KEYS = new Set(["ArrowLeft", "PageUp", "Backspace"]);
+
+const DEFAULT_LABELS = {
+  /** The accessible name of the presenter dialog. */
+  dialog: "Presentation",
+  exit: "Exit presentation",
+  exitTitle: "Exit (Esc)",
+  /** What the live region announces, for example "Slide 3 of 12". */
+  position: (position, count) => `Slide ${position} of ${count}`,
+  loading: "Loading fonts…",
+  empty: "No visible slides to present. Unhide a slide first.",
+};
+
+/** The slides a presentation shows: the deck's indexes without the hidden ones, as the exports select them (`slidesToConvert`). */
+function visibleIndices(deck, includeHidden) {
+  const list = Array.isArray(deck?.slides) ? deck.slides : [];
+  const found = [];
+  list.forEach((slide, index) => { if (includeHidden || slide?.hidden !== true) found.push(index); });
+  return found;
+}
+
+const clampIndex = (deck, wanted) => Math.max(0, Math.min((Array.isArray(deck?.slides) ? deck.slides.length : 1) - 1, Math.trunc(Number(wanted) || 0)));
+
+/**
+ * Mount the presenter in `container` (it stays hidden until `start`).
+ *
+ * Options: `editor` (an editor session) or `presentation` (an OPF object, or a function returning the current one), `fonts` (the renderer's fonts
+ * handle the canvas uses), `renderOptions` (extra `toSvg` options, such as `catalogs`; slides are drawn with `text: "system"`, `trace: false` and
+ * their `{{variables}}` resolved), `slideIndex` (the slide `start()` shows, 0-based), `onExit(index)` (the presenter closed, on the slide it showed),
+ * `onSlideChange(index)` (the shown slide changed), `density` (`"comfortable"` or `"touch"`), `includeHidden` (default false) and `labels`. Indexes are always positions in the deck, hidden slides included.
+ *
+ * Returns `{ element, start(slideIndex?), stop(), next(), previous(), goTo(index), getSlide(), isRunning(), destroy() }`.
+ */
+export function createPresenter(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const { editor } = options;
+  const source = options.presentation;
+  if (!editor && source === undefined) throw new TypeError("createPresenter needs an editor session or a presentation.");
+  if (editor && typeof editor.subscribe !== "function") throw new TypeError("createPresenter needs an editor session.");
+  const doc = container.ownerDocument;
+  const win = doc.defaultView;
+  const labels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  const density = options.density === "touch" ? "touch" : "comfortable";
+  const includeHidden = options.includeHidden === true;
+
+  // The snapshot is cached between edits, so reading it on every move is cheap.
+  const deckNow = () => (editor ? (editor.snapshot?.().presentation ?? editor.presentation) : typeof source === "function" ? source() : source);
+  const resolveOptions = () => ({ ...(options.renderOptions ?? {}), catalogs: mergeCatalogs(editor?.catalogs, options.renderOptions?.catalogs) });
+  const drawOptions = () => ({ ...resolveOptions(), fonts: options.fonts, text: "system", trace: false });
+  // Drawn slides by deck index, for the deck object they were drawn from: a new snapshot (an edit) or a new start() draws again.
+  let drawn = new Map(), drawnFor;
+
+  let active = false, destroyed = false, current = -1, opener = null, enteredFullscreen = false, leaving = false;
+  let counterTimer, preloadTimer, renderToken = 0, swipe = null, clickGuardUntil = 0;
+
+  // ---- the DOM ----------------------------------------------------------------------------------------------------------------------------
+  const slide = el(doc, "div", { class: "opf-presenter-slide" });
+  const message = el(doc, "p", { class: "opf-presenter-message", hidden: true });
+  const counter = el(doc, "span", { class: "opf-presenter-counter", "aria-hidden": "true" });
+  const closeButton = el(doc, "button", { type: "button", class: "opf-presenter-close", "aria-label": labels.exit, title: labels.exitTitle }, icon(doc, "X", 18));
+  const live = el(doc, "div", { class: "opf-presenter-live", role: "status", "aria-live": "polite", "aria-atomic": "true" });
+  const root = el(doc, "div", {
+    class: "opf-presenter opf-ui", role: "dialog", "aria-modal": "true", "aria-label": labels.dialog, tabindex: "-1", hidden: true,
+    "data-density": density, "data-mode": "overlay", "data-chrome": "hidden",
+  }, slide, message, counter, closeButton, live);
+  container.append(root);
+
+  // ---- slides -----------------------------------------------------------------------------------------------------------------------------
+  /** The slide to show for a requested index: that slide, else the next one that is not hidden, else the last one before it. -1: none. */
+  function resolve(deck, wanted) {
+    const shown = visibleIndices(deck, includeHidden);
+    if (!shown.length) return -1;
+    const target = clampIndex(deck, wanted);
+    return shown.find((index) => index >= target) ?? shown[shown.length - 1];
+  }
+  function showMessage(text) {
+    slide.replaceChildren();
+    message.textContent = text;
+    message.hidden = false;
+  }
+  function paint(html) {
+    if (typeof html === "string" && /^\s*<svg[\s>]/.test(html)) {
+      message.hidden = true;
+      slide.innerHTML = html;
+    } else showMessage(typeof html === "string" ? html : "Preview unavailable");
+  }
+  // Draw the listed slides that are not drawn yet, in one renderer call (it composes the deck once). A slide that cannot be drawn keeps the renderer's message.
+  function draw(deck, indices) {
+    if (deck !== drawnFor) { drawn = new Map(); drawnFor = deck; }
+    const missing = indices.filter((index) => !drawn.has(index));
+    if (!missing.length) return;
+    const options = drawOptions();
+    try {
+      const images = toSvg(deck, missing.map((index) => index + 1), options);
+      missing.forEach((index, position) => drawn.set(index, images[position]));
+    } catch {
+      // One bad slide must not hide the others.
+      for (const index of missing) {
+        try { drawn.set(index, toSvg(deck, index + 1, options)); } catch (error) { drawn.set(index, error?.message ?? "Preview unavailable"); }
+      }
+    }
+  }
+  function preload(deck, shown, index) {
+    win.clearTimeout(preloadTimer);
+    const at = shown.indexOf(index);
+    const wanted = [shown[at - 1], shown[at + 1]].filter((value) => value !== undefined);
+    if (!wanted.length) return;
+    preloadTimer = win.setTimeout(() => {
+      if (active) draw(deck, wanted);
+    }, PRELOAD_DELAY_MS);
+  }
+  // Draw the slide once the faces its deck needs are loaded (a deck in loaded faces draws synchronously).
+  function render(index) {
+    const token = ++renderToken;
+    const deck = deckNow();
+    const renderOptions = resolveOptions();
+    return whenFontsReady(options.fonts, deck, {
+      renderOptions,
+      isCurrent: () => active && token === renderToken,
+      loading: () => showMessage(labels.loading),
+      ready: () => {
+        draw(deck, [index]);
+        paint(drawn.get(index));
+        preload(deck, visibleIndices(deck, includeHidden), index);
+      },
+      failed: (error) => showMessage(error?.message ?? "Preview unavailable"),
+    });
+  }
+  function announce(deck, index) {
+    const shown = visibleIndices(deck, includeHidden);
+    const position = shown.indexOf(index);
+    counter.textContent = formatSlideCounter(Math.max(0, position), shown.length);
+    live.textContent = position < 0 ? "" : labels.position(position + 1, shown.length);
+  }
+
+  function show(wanted, { notify = true } = {}) {
+    const deck = deckNow();
+    const index = resolve(deck, wanted);
+    if (index < 0) {
+      current = -1;
+      renderToken++;
+      showMessage(labels.empty);
+      counter.textContent = formatSlideCounter(0, 0);
+      live.textContent = labels.empty;
+      return false;
+    }
+    const changed = index !== current;
+    current = index;
+    announce(deck, index);
+    render(index);
+    if (changed && notify) options.onSlideChange?.(index);
+    return changed;
+  }
+  function move(step) {
+    if (!active || current < 0) return false;
+    const shown = visibleIndices(deckNow(), includeHidden);
+    const at = shown.indexOf(current);
+    // The shown slide can be gone (the deck changed under it): step from where it was.
+    const target = at >= 0 ? shown[at + step] : step > 0 ? shown.find((index) => index > current) : [...shown].reverse().find((index) => index < current);
+    return target === undefined ? false : show(target);
+  }
+
+  // ---- the counter ------------------------------------------------------------------------------------------------------------------------
+  function showCounter() {
+    if (!active) return;
+    root.dataset.chrome = "visible";
+    win.clearTimeout(counterTimer);
+    counterTimer = win.setTimeout(() => { root.dataset.chrome = "hidden"; }, COUNTER_MS);
+  }
+
+  // ---- full screen ------------------------------------------------------------------------------------------------------------------------
+  // The element is always a fixed overlay; the Fullscreen API only makes the browser give the screen to it. When the browser refuses (no
+  // user gesture, an iframe without `allow="fullscreen"`, iPhone Safari), the overlay is the presentation.
+  function enterFullscreen() {
+    const request = root.requestFullscreen ?? root.webkitRequestFullscreen;
+    if (typeof request !== "function" || doc.fullscreenEnabled === false) return Promise.resolve("overlay");
+    let attempt;
+    try { attempt = Promise.resolve(request.call(root, { navigationUI: "hide" })); } catch (error) { attempt = Promise.reject(error); }
+    return attempt.then(
+      () => {
+        if (!active || doc.fullscreenElement !== root) return "overlay";
+        enteredFullscreen = true;
+        root.dataset.mode = "fullscreen";
+        return "fullscreen";
+      },
+      () => "overlay",
+    );
+  }
+  // The browser takes full screen away with Esc (that key never reaches the page) or the host exits it: the presentation ends with it.
+  function onFullscreenChange() {
+    if (doc.fullscreenElement === root) return;
+    if (leaving) {
+      // The exit that stop() asked for finished. If the host started again meanwhile, full screen is gone and the overlay carries on.
+      leaving = false;
+      if (active && enteredFullscreen) { enteredFullscreen = false; root.dataset.mode = "overlay"; }
+      return;
+    }
+    if (active && enteredFullscreen) stop();
+  }
+
+  // ---- input ------------------------------------------------------------------------------------------------------------------------------
+  function onKeydown(event) {
+    if (!active || event.altKey || event.ctrlKey || event.metaKey || event.isComposing) return;
+    const key = event.key;
+    const onButton = event.target === closeButton;
+    let handled = true;
+    if (key === "Escape") stop();
+    else if (key === "Tab") (doc.activeElement === closeButton ? root : closeButton).focus();
+    else if (onButton && (key === "Enter" || key === " ")) handled = false; // the button's own click exits
+    else if (NEXT_KEYS.has(key)) move(1);
+    else if (PREVIOUS_KEYS.has(key)) move(-1);
+    else if (key === "Home") show(0);
+    else if (key === "End") show(Number.MAX_SAFE_INTEGER);
+    else handled = false;
+    if (handled) { event.preventDefault(); event.stopPropagation(); }
+  }
+  // A press on the left third goes back, anywhere else forward.
+  function byZone(clientX) {
+    const box = root.getBoundingClientRect();
+    return move(clientX < box.left + box.width / 3 ? -1 : 1);
+  }
+  function onClick(event) {
+    if (!active || closeButton.contains(event.target)) return;
+    // A touch is handled on pointerup (below); the click the browser adds after it must not move a second time.
+    if (win.performance.now() < clickGuardUntil) return;
+    byZone(event.clientX);
+  }
+  function onPointerdown(event) {
+    showCounter();
+    swipe = event.pointerType === "mouse" ? null : { id: event.pointerId, x: event.clientX, y: event.clientY, at: win.performance.now() };
+  }
+  // Touch and pen: a swipe moves, and a tap uses the click zones. Both are read here, so they do not depend on the browser's click for touch.
+  function onPointerup(event) {
+    const start = swipe;
+    swipe = null;
+    if (!active || !start || start.id !== event.pointerId) return;
+    const dx = event.clientX - start.x, dy = event.clientY - start.y, now = win.performance.now(), elapsed = now - start.at;
+    if (Math.abs(dx) >= SWIPE_MIN && Math.abs(dx) >= Math.abs(dy) * 1.5 && elapsed <= SWIPE_MAX_MS) {
+      clickGuardUntil = now + CLICK_GUARD_MS;
+      move(dx < 0 ? 1 : -1);
+    } else if (Math.abs(dx) <= TAP_SLOP && Math.abs(dy) <= TAP_SLOP && elapsed <= TAP_MAX_MS && !closeButton.contains(event.target)) {
+      clickGuardUntil = now + CLICK_GUARD_MS;
+      byZone(event.clientX);
+    }
+  }
+  // Focus stays inside the dialog: the page behind it is not reachable while it is open.
+  function onFocusin(event) {
+    if (active && !root.contains(event.target)) root.focus({ preventScroll: true });
+  }
+
+  root.addEventListener("click", onClick);
+  root.addEventListener("pointermove", showCounter);
+  root.addEventListener("pointerdown", onPointerdown);
+  root.addEventListener("pointerup", onPointerup);
+  root.addEventListener("pointercancel", () => { swipe = null; });
+  closeButton.addEventListener("click", () => stop());
+  // Always listening: the exit that stop() asks for arrives after stop() returned.
+  doc.addEventListener("fullscreenchange", onFullscreenChange);
+  doc.addEventListener("webkitfullscreenchange", onFullscreenChange);
+
+  // ---- start and stop ---------------------------------------------------------------------------------------------------------------------
+  function start(slideIndex) {
+    if (destroyed) return Promise.resolve("overlay");
+    const wanted = slideIndex ?? options.slideIndex ?? 0;
+    if (active) { show(wanted); return Promise.resolve(root.dataset.mode); }
+    active = true;
+    opener = doc.activeElement && doc.activeElement !== doc.body ? doc.activeElement : null;
+    current = -1;
+    drawn = new Map();
+    drawnFor = undefined;
+    root.hidden = false;
+    root.dataset.mode = "overlay";
+    root.dataset.chrome = "hidden";
+    doc.addEventListener("keydown", onKeydown, true);
+    doc.addEventListener("focusin", onFocusin, true);
+    // Full screen must be requested inside the user's gesture, so before anything is drawn.
+    const entering = enterFullscreen();
+    root.focus({ preventScroll: true });
+    show(wanted, { notify: false });
+    // The host asked for a slide that is hidden: tell it which slide the presentation really opened on.
+    if (current >= 0 && current !== clampIndex(deckNow(), wanted)) options.onSlideChange?.(current);
+    return entering;
+  }
+  function stop() {
+    if (!active) return;
+    const index = current;
+    active = false;
+    enteredFullscreen = false;
+    renderToken++;
+    win.clearTimeout(counterTimer);
+    win.clearTimeout(preloadTimer);
+    doc.removeEventListener("keydown", onKeydown, true);
+    doc.removeEventListener("focusin", onFocusin, true);
+    const fullscreen = doc.fullscreenElement === root;
+    root.hidden = true;
+    slide.replaceChildren();
+    swipe = null;
+    const back = opener;
+    opener = null;
+    const restoreFocus = () => {
+      // Only when nobody took focus since: the host may move it in `onExit`.
+      const now = doc.activeElement;
+      if (back?.isConnected && typeof back.focus === "function" && (!now || now === doc.body || now === root)) back.focus({ preventScroll: true });
+    };
+    restoreFocus();
+    if (fullscreen) {
+      leaving = true;
+      // The page behind a full screen element takes no focus until the exit is done.
+      Promise.resolve(doc.exitFullscreen?.()).then(restoreFocus, () => { leaving = false; });
+    }
+    // The deck index the presentation ended on (-1 when no slide was shown: there was nothing to present).
+    options.onExit?.(index);
+  }
+
+  return {
+    element: root,
+    /** Open the presentation on `slideIndex` (default: the `slideIndex` option). Resolves `"fullscreen"` or `"overlay"` once the browser answered. */
+    start,
+    /** Close the presentation. `onExit(index)` is called with the slide it showed. */
+    stop,
+    /** Show the next slide that is not hidden. Returns false at the end. */
+    next: () => move(1),
+    /** Show the previous slide that is not hidden. Returns false at the start. */
+    previous: () => move(-1),
+    /** Show a slide by its deck index; a hidden slide shows the next one that is not hidden. Returns false when the slide did not change. */
+    goTo: (index) => (active ? show(index) : false),
+    /** The deck index of the shown slide (-1 when stopped or empty). */
+    getSlide: () => (active ? current : -1),
+    isRunning: () => active,
+    destroy() {
+      if (destroyed) return;
+      stop();
+      destroyed = true;
+      doc.removeEventListener("fullscreenchange", onFullscreenChange);
+      doc.removeEventListener("webkitfullscreenchange", onFullscreenChange);
+      root.remove();
+    },
+  };
+}
+
+// ---- the Present button ---------------------------------------------------------------------------------------------------------------------
+
+/** True when a key press belongs to something else: typing, an editor, a menu or a dialog. */
+function isInteractiveTarget(target) {
+  if (!target || typeof target.closest !== "function") return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  return Boolean(target.closest('[contenteditable=""],[contenteditable="true"],.cm-editor,[role="textbox"],[role="combobox"],[role="listbox"],[role="menu"],[role="slider"],[role="spinbutton"],dialog[open],[role="dialog"]'));
+}
+
+/**
+ * Mount the Present button in `container`: an icon-only button (Lucide Presentation) named "Present", titled "Present (F5)".
+ *
+ * Options: `onPresent(event)`, `disabled` (`true`, or a string that says why and is the title), `density` (`"comfortable"` 32px, or `"touch"` 40px)
+ * and `label` (the accessible name, default "Present"). A disabled button stays focusable (`aria-disabled`) and does nothing.
+ *
+ * Returns `{ element, setDisabled(reason), setDensity(density), destroy() }`.
+ */
+export function createPresentButton(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const doc = container.ownerDocument;
+  const label = options.label ?? "Present";
+  let disabledReason = options.disabled === true ? "Nothing to present." : typeof options.disabled === "string" && options.disabled ? options.disabled : undefined;
+  let destroyed = false;
+  const button = el(doc, "button", {
+    type: "button", class: "opf-present-button opf-ui", "aria-label": label, title: "Present (F5)", "aria-keyshortcuts": "F5",
+    "data-density": options.density === "touch" ? "touch" : "comfortable",
+  }, icon(doc, "Presentation", 16));
+  const paint = () => {
+    if (disabledReason) { button.setAttribute("aria-disabled", "true"); button.title = disabledReason; }
+    else { button.removeAttribute("aria-disabled"); button.title = "Present (F5)"; }
+  };
+  button.addEventListener("click", (event) => {
+    if (destroyed || disabledReason) return;
+    options.onPresent?.(event);
+  });
+  paint();
+  container.append(button);
+  return {
+    element: button,
+    /** `true` disables with a default reason, a string with your own (it becomes the title), `false` enables. */
+    setDisabled(reason) {
+      disabledReason = reason === true ? "Nothing to present." : typeof reason === "string" && reason ? reason : undefined;
+      paint();
+    },
+    setDensity(next) { button.dataset.density = next === "touch" ? "touch" : "comfortable"; },
+    destroy() { destroyed = true; button.remove(); },
+  };
+}
+
+/**
+ * F5 starts the presentation (`onPresent(event)`), and the browser's reload is suppressed when it does. `target` defaults to the document. F5 is
+ * ignored while typing in inputs, selects and editors (CodeMirror, contenteditable), in menus and in dialogs, and with Ctrl, Alt, Meta or Shift held.
+ * Returns a function that removes the listener.
+ */
+export function bindPresentShortcut(target, onPresent) {
+  if (typeof onPresent !== "function") throw new TypeError("bindPresentShortcut needs onPresent().");
+  const doc = target?.ownerDocument ?? target?.document ?? (typeof document === "undefined" ? undefined : document);
+  const handler = (event) => {
+    if (event.key !== "F5" || event.defaultPrevented || event.repeat || event.isComposing) return;
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+    if (isInteractiveTarget(event.target) || isInteractiveTarget(doc?.activeElement)) return;
+    event.preventDefault();
+    onPresent(event);
+  };
+  const listener = target ?? doc;
+  listener.addEventListener("keydown", handler);
+  return () => listener.removeEventListener("keydown", handler);
+}

package/dist/read-deck-file.d.ts

@@ -0,0 +1,59 @@
+import type { Catalog, Finding } from "@openpresentation/opf";
+
+/** The `accept` value for a file input that opens a deck: `".json,.opf,.yaml,.yml,.md"`. */
+export declare const DECK_FILE_ACCEPT: string;
+
+/** The format a deck file was read as: `json` (canonical), `yaml` (`.opf.yaml`) or `md` (`.opf.md`). */
+export type DeckFileFormat = "json" | "yaml" | "md";
+
+/** A file, or a name and its text. A `File` or any object with `name` and `text()` works; `size` is checked against the 20 MB limit when present. */
+export type DeckFileInput = { name: string; size?: number; text(): Promise<string> } | { name: string; text: string };
+
+export interface ReadDeckFileOptions {
+  /** The host's catalogs, for the references check of the YAML and Markdown conversion. Nothing is fetched. */
+  catalogs?: readonly Catalog[];
+}
+
+/** A conversion finding. Core's `Finding`: `path` is a JSON Pointer into the deck when there is one, `location` the line and column in the text. */
+export type DeckFileFinding = Finding & { location?: { offset: number; length: number; line: number; column: number } };
+
+export interface DeckFile {
+  /** The deck. Not validated for JSON; for YAML and Markdown the OPF errors are in `findings`. */
+  document: any;
+  /** The format that read it, which can differ from the one the extension suggests (see `readDeckFile`). */
+  format: DeckFileFormat;
+  /** The file name without `.opf.json`, `.opf.yaml`, `.opf.md` or its plain extension (`deck` when nothing is left). */
+  name: string;
+  /** The conversion findings of YAML and Markdown, in source order. Empty for JSON. */
+  findings: DeckFileFinding[];
+}
+
+/**
+ * Why a file could not be read:
+ * `unreadable` (not a file, or reading it failed), `file-too-large` (over 20 MB), `empty-file`, `unsupported-file` (a binary file such as .pptx),
+ * `invalid-json` (not JSON, YAML or Markdown with front matter), `invalid-yaml`, `invalid-markdown` (syntax errors, in `findings`) and
+ * `not-a-deck` (JSON that has no `slides` list).
+ */
+export type DeckFileErrorCode = "unreadable" | "file-too-large" | "empty-file" | "unsupported-file" | "invalid-json" | "invalid-yaml" | "invalid-markdown" | "not-a-deck";
+
+export declare class DeckFileError extends Error {
+  readonly name: "DeckFileError";
+  readonly code: DeckFileErrorCode;
+  /** The format that was tried first (from the extension). */
+  readonly format?: DeckFileFormat;
+  readonly fileName?: string;
+  /** The parser's findings for `invalid-yaml` and `invalid-markdown`. */
+  readonly findings: DeckFileFinding[];
+  constructor(code: DeckFileErrorCode, message: string, context?: { format?: DeckFileFormat; name?: string; findings?: DeckFileFinding[]; cause?: unknown });
+}
+
+/** The file name without its directory and its `.opf.json`, `.opf.yaml`, `.opf.md` or plain extension. */
+export declare function deckFileName(fileName: string): string;
+/** The format the extension suggests: `.yaml`/`.yml` YAML, `.md` Markdown, anything else JSON. */
+export declare function deckFileFormat(fileName: string): DeckFileFormat;
+
+/**
+ * Read a deck file in any OPF source format. The extension picks the format; text that is not JSON falls back to YAML, and to Markdown when it
+ * starts with front matter. YAML and Markdown go through core's `fromYaml` and `fromMarkdown` (loaded on first use). Throws `DeckFileError`.
+ */
+export declare function readDeckFile(file: DeckFileInput | File, options?: ReadDeckFileOptions): Promise<DeckFile>;

package/dist/read-deck-file.js

@@ -0,0 +1,142 @@
+// RR-98: read a deck file of any OPF source format. `readDeckFile(file | { name, text })` detects JSON, YAML or Markdown (the extension decides
+// first, then the content), converts YAML and Markdown with core's browser-safe `fromYaml` and `fromMarkdown` (`@openpresentation/opf/yaml`, `/markdown`,
+// loaded on first use) and returns `{ document, format, name, findings }`. Plain functions, no DOM, no network. A host's Open button passes
+// `DECK_FILE_ACCEPT` to `<input accept>` and the chosen file to `readDeckFile`.
+import { MAX_OPF_BYTES, unwrapOpf } from "./transfer.js";
+
+/** The `accept` value for a file input that opens a deck: JSON (`.json`, `.opf`), YAML and Markdown. */
+export const DECK_FILE_ACCEPT = ".json,.opf,.yaml,.yml,.md";
+
+/** Raised by `readDeckFile`. `code` says why; `format` is the format that was tried first; `findings` holds the parser's findings, if any. */
+export class DeckFileError extends Error {
+  constructor(code, message, { format, name, findings = [], cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "DeckFileError";
+    this.code = code;
+    this.format = format;
+    this.fileName = name;
+    this.findings = findings;
+  }
+}
+
+const YAML_EXTENSIONS = /\.(?:ya?ml)$/i;
+const MARKDOWN_EXTENSIONS = /\.(?:md|markdown)$/i;
+const COMPOUND = /\.opf\.(?:json|ya?ml|md|markdown)$/i;
+const PLAIN = /\.(?:json|opf|ya?ml|md|markdown)$/i;
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const stripBom = (text) => text.replace(/^/, "");
+
+/** The file name without its directory and its `.opf.json`, `.opf.yaml`, `.opf.md` or plain extension. */
+export function deckFileName(fileName) {
+  const base = String(fileName ?? "").split(/[\\/]/).pop().trim();
+  const stripped = base.replace(COMPOUND, "").replace(PLAIN, "");
+  const name = stripped !== base ? stripped : base.replace(/(?<=.)\.[A-Za-z0-9]{1,8}$/, "");
+  return name || "deck";
+}
+
+/** The format the extension suggests: `.yaml` and `.yml` are YAML, `.md` Markdown, and `.json`, `.opf` or anything else JSON. */
+export function deckFileFormat(fileName) {
+  const name = String(fileName ?? "");
+  return YAML_EXTENSIONS.test(name) ? "yaml" : MARKDOWN_EXTENSIONS.test(name) ? "md" : "json";
+}
+
+const hasFrontMatter = (text) => /^---[ \t]*\r?\n/.test(stripBom(text).replace(/^\s*(?=---)/, ""));
+const looksBinary = (text) => text.startsWith("PK\u0003\u0004") || text.includes("\u0000");
+
+function failure(code, message, context, extra) {
+  return new DeckFileError(code, message, { ...context, ...extra });
+}
+
+async function readSource(input) {
+  if (input === null || typeof input !== "object") throw failure("unreadable", "Choose a deck file to open.", {});
+  const name = typeof input.name === "string" ? input.name : "";
+  const context = { name };
+  if (typeof input.size === "number" && input.size > MAX_OPF_BYTES) throw failure("file-too-large", "Choose a file smaller than 20 MB.", context);
+  let text = input.text;
+  try {
+    if (typeof text === "function") text = await input.text();
+  } catch (cause) {
+    throw failure("unreadable", `${name || "The file"} could not be read.${cause?.message ? ` ${cause.message}` : ""}`, context, { cause });
+  }
+  if (typeof text !== "string") throw failure("unreadable", "Pass a File, or { name, text } with the file's text.", context);
+  if (new TextEncoder().encode(text).length > MAX_OPF_BYTES) throw failure("file-too-large", "Choose a file smaller than 20 MB.", context);
+  return { name, text: stripBom(text), context };
+}
+
+function readJson(text, context) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (cause) {
+    throw failure("invalid-json", `This is not valid JSON: ${cause.message}`, context, { format: "json", cause });
+  }
+  const document = unwrapOpf(value);
+  if (!isObject(document) || !Array.isArray(document.slides)) {
+    throw failure("not-a-deck", "This JSON is not an OPF deck: a deck has a \"slides\" list.", context, { format: "json" });
+  }
+  return { document, findings: [] };
+}
+
+// A conversion result as a deck, or a typed error when the text itself could not be read (a syntax or dialect error, not an OPF finding).
+function fromConversion(result, format, context) {
+  const findings = result.findings ?? [];
+  const syntax = findings.filter((finding) => finding.severity === "error" && !String(finding.ruleId ?? "").startsWith("opf/"));
+  if (syntax.length) {
+    const first = syntax[0];
+    const place = first.location?.line ? ` (line ${first.location.line})` : "";
+    throw failure(format === "yaml" ? "invalid-yaml" : "invalid-markdown", `This is not valid ${format === "yaml" ? "YAML" : "Markdown"}${place}: ${first.message}`, context, { format, findings });
+  }
+  return { document: result.presentation, findings };
+}
+
+async function convert(format, text, options, context) {
+  if (format === "yaml") {
+    const { fromYaml } = await import("@openpresentation/opf/yaml");
+    return fromConversion(fromYaml(text, { catalogs: options.catalogs }), "yaml", context);
+  }
+  const { fromMarkdown } = await import("@openpresentation/opf/markdown");
+  return fromConversion(fromMarkdown(text, { catalogs: options.catalogs }), "md", context);
+}
+
+/**
+ * Read a deck file. `file` is a `File` (or anything with `name` and `text()`), or `{ name, text }` with the text as a string.
+ *
+ * The extension picks the format: `.yaml` and `.yml` are YAML, `.md` is Markdown, and `.json`, `.opf` or anything else is JSON. Text that is not
+ * valid JSON is then tried as YAML, and as Markdown when it starts with front matter (`---`). The result is
+ * `{ document, format: "json" | "yaml" | "md", name, findings }`: `format` is the one that read it, `name` is the file name without
+ * `.opf.json`, `.opf.yaml`, `.opf.md` or its plain extension, and `findings` are the conversion findings of YAML and Markdown (core's
+ * `Finding`, each with a JSON Pointer `path` and a `location` in the text; JSON gives none). A deck that reads but has OPF errors is returned,
+ * with those findings; text that cannot be read at all throws `DeckFileError`.
+ *
+ * `options.catalogs`: the host's catalogs, for the references check of the YAML and Markdown conversion.
+ */
+export async function readDeckFile(file, options = {}) {
+  const { name: fileName, text, context } = await readSource(file);
+  const name = deckFileName(fileName);
+  const chosen = deckFileFormat(fileName);
+  const done = (format, read) => ({ document: read.document, format, name, findings: read.findings });
+  if (!text.trim()) throw failure("empty-file", `${fileName || "The file"} is empty.`, context, { format: chosen });
+  if (looksBinary(text)) throw failure("unsupported-file", "This looks like a PowerPoint or other binary file, not an OPF deck. Open a .json, .yaml or .md deck.", context, { format: chosen });
+
+  if (chosen === "yaml") return done("yaml", await convert("yaml", text, options, context));
+  if (chosen === "md") return done("md", await convert("md", text, options, context));
+
+  let jsonError;
+  try {
+    return done("json", readJson(text, context));
+  } catch (error) {
+    // A parsed value that is not a deck is a real answer. Only text that is not JSON falls through to the other formats.
+    if (error.code !== "invalid-json") throw error;
+    jsonError = error;
+  }
+  try {
+    const read = await convert("yaml", text, options, context);
+    if (isObject(read.document) && Array.isArray(read.document.slides)) return done("yaml", read);
+  } catch (error) {
+    if (!(error instanceof DeckFileError)) throw error;
+  }
+  if (hasFrontMatter(text)) {
+    try { return done("md", await convert("md", text, options, context)); } catch (error) { if (!(error instanceof DeckFileError)) throw error; }
+  }
+  throw failure("invalid-json", `${jsonError.message} It is not valid YAML${hasFrontMatter(text) ? " or Markdown" : ""} either.`, context, { format: "json", cause: jsonError.cause });
+}

package/dist/styles.css

@@ -2981,6 +2981,163 @@
   }
 }
 
+/* presenter.css */
+/* RR-98: the presenter and the Present button (src/presenter.js). Only --opf-ui-* tokens, no color literals (test/styles.mjs). */
+
+/* ---- the presenter -------------------------------------------------------------------------------------------------------------------- */
+.opf-presenter,
+.opf-presenter *,
+.opf-presenter *::before,
+.opf-presenter *::after { box-sizing: border-box; }
+.opf-presenter[hidden] { display: none !important; }
+
+.opf-presenter {
+  position: fixed;
+  inset: 0;
+  z-index: 2000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  /* Slides are letterboxed on black in every theme, so the bars never take a token's light or dark value. */
+  background: black;
+  font-family: var(--opf-ui-font);
+  font-size: 13px;
+  line-height: 1.4;
+  color: var(--opf-ui-fg);
+  user-select: none;
+  -webkit-user-select: none;
+  touch-action: none;
+  outline: none;
+}
+.opf-presenter[data-chrome="hidden"] { cursor: none; }
+
+.opf-presenter .opf-presenter-slide {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+/* The slide's own width and height attributes give its shape (viewBox); this makes it as large as the screen allows. */
+.opf-presenter .opf-presenter-slide svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  max-width: 100%;
+  max-height: 100%;
+}
+.opf-presenter .opf-presenter-message {
+  position: absolute;
+  margin: 0;
+  max-width: 40ch;
+  padding: 12px 16px;
+  border: 1px solid var(--opf-ui-border);
+  border-radius: var(--opf-ui-radius-md);
+  background: var(--opf-ui-surface);
+  color: var(--opf-ui-muted-fg);
+  text-align: center;
+  font: 400 13px/1.5 var(--opf-ui-font);
+}
+.opf-presenter .opf-presenter-message[hidden] { display: none; }
+.opf-presenter .opf-presenter-live {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ---- the counter and the exit button (they appear on pointer move) ---------------------------------------------------------------------- */
+.opf-presenter .opf-presenter-counter,
+.opf-presenter .opf-presenter-close {
+  position: absolute;
+  background: var(--opf-ui-surface);
+  color: var(--opf-ui-muted-fg);
+  border: 1px solid var(--opf-ui-border);
+  opacity: 0;
+  transition: opacity var(--opf-ui-ease), color var(--opf-ui-ease), border-color var(--opf-ui-ease);
+}
+.opf-presenter[data-chrome="visible"] .opf-presenter-counter,
+.opf-presenter[data-chrome="visible"] .opf-presenter-close,
+.opf-presenter .opf-presenter-close:focus-visible { opacity: 1; }
+
+.opf-presenter .opf-presenter-counter {
+  bottom: 16px;
+  left: 0;
+  right: 0;
+  width: max-content;
+  margin: 0 auto;
+  padding: 4px 10px;
+  border-radius: var(--opf-ui-radius);
+  font: 500 11.5px/1.4 var(--opf-ui-mono);
+  letter-spacing: 0.04em;
+  pointer-events: none;
+}
+.opf-presenter .opf-presenter-close {
+  top: 16px;
+  right: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--opf-ui-control-h);
+  height: var(--opf-ui-control-h);
+  padding: 0;
+  margin: 0;
+  border-radius: var(--opf-ui-radius);
+  font: inherit;
+  cursor: pointer;
+}
+.opf-presenter .opf-presenter-close:hover { color: var(--opf-ui-fg); background: var(--opf-ui-muted); }
+.opf-presenter .opf-presenter-close:focus-visible {
+  outline: 2px solid var(--opf-ui-ring);
+  outline-offset: 2px;
+}
+.opf-presenter .opf-icon { flex: none; }
+
+/* ---- the Present button (styled like the Export trigger) ------------------------------------------------------------------------------- */
+.opf-present-button,
+.opf-present-button *,
+.opf-present-button *::before,
+.opf-present-button *::after { box-sizing: border-box; }
+.opf-present-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--opf-ui-control-h);
+  height: var(--opf-ui-control-h);
+  margin: 0;
+  padding: 0;
+  border: 1px solid var(--opf-ui-accent);
+  border-radius: var(--opf-ui-radius);
+  background: var(--opf-ui-accent);
+  color: var(--opf-ui-accent-fg);
+  font: inherit;
+  cursor: pointer;
+  transition: opacity var(--opf-ui-ease);
+}
+.opf-present-button:hover { opacity: 0.92; }
+.opf-present-button:focus-visible {
+  outline: 2px solid var(--opf-ui-ring);
+  outline-offset: 2px;
+}
+.opf-present-button[aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.opf-present-button .opf-icon { flex: none; }
+
+@media (prefers-reduced-motion: reduce) {
+  .opf-presenter .opf-presenter-counter,
+  .opf-presenter .opf-presenter-close,
+  .opf-present-button { transition: none; }
+}
+
 /* source-pane.css */
 /* Source pane (RR-98). Only --opf-ui-* tokens (src/styles/tokens.css). */
 .opf-source {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-editor",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
   "license": "MIT",
   "type": "module",
@@ -230,6 +230,14 @@
       "types": "./dist/source-pane.d.ts",
       "default": "./dist/source-pane.js"
     },
+    "./presenter": {
+      "types": "./dist/presenter.d.ts",
+      "default": "./dist/presenter.js"
+    },
+    "./read-deck-file": {
+      "types": "./dist/read-deck-file.d.ts",
+      "default": "./dist/read-deck-file.js"
+    },
     "./export-menu": {
       "types": "./dist/export-menu.d.ts",
       "default": "./dist/export-menu.js"
@@ -270,7 +278,7 @@
     "check:font-hotlinks": "node --test scripts/check-font-hotlinks.test.mjs && node scripts/check-font-hotlinks.mjs",
     "check:font-hotlinks:built": "node scripts/check-font-hotlinks.mjs --built dist artifacts/playground",
     "build:playground": "node scripts/build-playground.mjs",
-    "test:playground": "npm run build:playground && npm run check:font-hotlinks:built && node test/playground-pptx.mjs && node test/playground-script-fonts.mjs artifacts/playground-script-fonts && node test/playground-lazy-fonts.mjs artifacts/playground-lazy-fonts && node test/playground-base-fonts.mjs artifacts/playground-base-fonts && node test/playground-source.mjs && node test/design-controls-browser.mjs && node test/design-gaps-browser.mjs && node test/chart-options-browser.mjs && node test/persistence-browser.mjs && node test/slides-browser.mjs && node test/slide-navigator-browser.mjs && node test/layout-templates-browser.mjs && node test/template-panel-browser.mjs && node test/numbering-panel-browser.mjs && node test/playground-ensure-fonts.mjs artifacts/playground-ensure-fonts && node test/canvas-fonts-browser.mjs artifacts/canvas-fonts && node test/find-replace-browser.mjs && node test/image-crop-browser.mjs && node test/mobile-browser.mjs && node test/review-panel-browser.mjs && node test/review-hook-browser.mjs && node test/source-pane-browser.mjs && node test/playground-download.mjs artifacts/playground-download && node test/export-menu-browser.mjs && node test/agent-handoff-browser.mjs",
+    "test:playground": "npm run build:playground && npm run check:font-hotlinks:built && node test/playground-pptx.mjs && node test/playground-script-fonts.mjs artifacts/playground-script-fonts && node test/playground-lazy-fonts.mjs artifacts/playground-lazy-fonts && node test/playground-base-fonts.mjs artifacts/playground-base-fonts && node test/playground-source.mjs && node test/design-controls-browser.mjs && node test/design-gaps-browser.mjs && node test/chart-options-browser.mjs && node test/persistence-browser.mjs && node test/slides-browser.mjs && node test/slide-navigator-browser.mjs && node test/layout-templates-browser.mjs && node test/template-panel-browser.mjs && node test/numbering-panel-browser.mjs && node test/playground-ensure-fonts.mjs artifacts/playground-ensure-fonts && node test/canvas-fonts-browser.mjs artifacts/canvas-fonts && node test/find-replace-browser.mjs && node test/image-crop-browser.mjs && node test/mobile-browser.mjs && node test/review-panel-browser.mjs && node test/review-hook-browser.mjs && node test/source-pane-browser.mjs && node test/playground-download.mjs artifacts/playground-download && node test/export-menu-browser.mjs && node test/agent-handoff-browser.mjs && node test/presenter-browser.mjs && node test/present-button-browser.mjs",
     "test:code-browser": "node test/code-browser.mjs",
     "test:selection-browser": "node test/selection-browser.mjs",
     "test:click-entry-browser": "node test/click-entry-browser.mjs",
@@ -297,6 +305,8 @@
     "test:export-license-browser": "node test/export-license-browser.mjs",
     "test:chart-options-browser": "node test/chart-options-browser.mjs",
     "test:numbering-panel-browser": "node test/numbering-panel-browser.mjs",
+    "test:presenter-browser": "node test/presenter-browser.mjs",
+    "test:present-button-browser": "node test/present-button-browser.mjs",
     "test:export-menu-browser": "node test/export-menu-browser.mjs",
     "test:agent-handoff-browser": "node test/agent-handoff-browser.mjs"
   },