@openpresentation/opf-editor 0.24.2 → 0.25.0

package/dist/presenter.d.ts

@@ -0,0 +1,105 @@
+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;
+  /** `"quiet"` (default): a transparent icon button like the toolbar's undo and redo. `"primary"`: the filled accent look of the Export trigger. */
+  variant?: "quiet" | "primary";
+}
+
+export interface PresentButton {
+  readonly element: HTMLButtonElement;
+  setDisabled(reason?: boolean | string): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  setVariant(variant: "quiet" | "primary"): void;
+  destroy(): void;
+}
+
+/** The icon-only Present button: a Lucide Presentation icon, `aria-label="Present"`, title "Present (F5)". Quiet by default (a transparent icon button like undo and redo); `variant: "primary"` styles it 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,431 @@
+// 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)
+ * `label` (the accessible name, default "Present") and `variant` (`"quiet"`, the default: a transparent icon button like the toolbar's undo and redo,
+ * or `"primary"`: the filled accent look of the Export trigger). A disabled button stays focusable (`aria-disabled`) and does nothing.
+ *
+ * Returns `{ element, setDisabled(reason), setDensity(density), setVariant(variant), 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", "data-variant": options.variant === "primary" ? "primary" : "quiet",
+  }, 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"; },
+    setVariant(next) { button.dataset.variant = next === "primary" ? "primary" : "quiet"; },
+    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>;