@openpresentation/opf-editor 0.17.0 → 0.18.1

package/dist/export.js

@@ -1,13 +1,18 @@
-// RR-23: download a deck as PDF, PNG or SVG from the editor, next to the PowerPoint export. Everything runs in the page:
-// the slides are drawn by the same renderer the preview uses (`renderSvg`, with the fonts handle's text measurement), so
-// a download is the preview, not a second layout. Fonts are the renderer's fonts handle's: the faces the document needs load through
-// the handle first, and only faces its registry holds (bundled or hash-pinned, permissively licensed) are embedded, as
-// @font-face data in each SVG and as subsets in the PDF. No system font is read and nothing is fetched at export time.
+// RR-23, RR-73: `convert(deck, { format })` turns the open deck into PDF, PNG or SVG files in the page, next to the PowerPoint
+// export. It has the name and the result of core's in-memory `convert` (`{ files, findings }`, each PNG or SVG file carrying its
+// one-based `slide`). The slides are drawn by the same renderer the preview uses (`toSvg`, with the fonts handle's text measurement),
+// so a file is the preview, not a second layout. Fonts are the renderer's fonts handle's: the faces the document needs load through
+// the handle first, and only faces its registry holds (bundled or hash-pinned, permissively licensed) are embedded, as @font-face
+// data in each SVG and as subsets in the PDF. No system font is read and nothing is fetched at export time. A browser handle made with
+// `loadFonts({ subsetWasm, shapeWasm })` (opf-editor#141) also cuts each SVG's faces to the slide's glyphs and draws
+// `renderOptions.text: "paths"` with HarfBuzz-shaped outlines.
 //
-//   const result = await exportDeck(editor.presentation, { format: "pdf", fonts, renderOptions, signal, onProgress });
-//   // result.download is { name, type, bytes }: one PDF, one PNG or SVG, or a ZIP of the slides.
+//   const { files, findings } = await convert(editor.presentation, { format: "pdf", fonts, renderOptions, signal, onProgress });
+//   // files: one PDF; one PNG or SVG per slide; or, with `zip: true`, one archive of them.
 
-import { renderSvg } from "@openpresentation/opf-render/svg";
+import { parseSlideSelection } from "@openpresentation/opf";
+import { pointerFromPath } from "@openpresentation/opf/patch";
+import { toSvg } from "@openpresentation/opf-render/svg";
 import { mergeCatalogs, prepareSave } from "./catalogs.js";
 import { fontGate } from "./font-gate.js";
 import { createZip } from "./zip.js";
@@ -17,14 +22,16 @@ export const EXPORT_FORMATS = Object.freeze({
   png: Object.freeze({ extension: "png", type: "image/png", label: "PNG" }),
   svg: Object.freeze({ extension: "svg", type: "image/svg+xml", label: "SVG" }),
 });
+const ZIP_TYPE = "application/zip";
 
 /** Largest PNG scale offered; a 1280 x 720 slide at 4x is 5120 x 2880 pixels. */
 export const MAX_PNG_SCALE = 4;
 
 // Licenses a face may be embedded under (the repository's font policy: OFL-1.1, Apache-2.0, MIT, UFL-1.0). The registry's faces carry the
-// face's own license text; a text that names none of these keeps the face out of the download.
+// face's own license text; a text that names none of these keeps the face out of the file.
 const PERMISSIVE_LICENSE = /SIL OPEN FONT LICENSE|OPEN FONT LICENSE|\bOFL\b|APACHE LICENSE|\bMIT LICENSE\b|PERMISSION IS HEREBY GRANTED|UBUNTU FONT LICEN[SC]E|\bUFL\b/i;
-const FONT_WARNINGS = new Set([
+// PDF converter codes that are warnings; every other `pdf-` code (embedded faces, page notes) is information. Renderer codes are warnings.
+const PDF_WARNINGS = new Set([
   "pdf-font-substituted", "pdf-font-fallback", "pdf-glyph-missing", "pdf-raster-fallback", "pdf-image-skipped", "pdf-font-unreadable",
   "pdf-font-embedding-restricted", "pdf-font-unsupported-format", "pdf-expansion-limit", "pdf-font-unavailable",
 ]);
@@ -32,7 +39,7 @@ const FONT_WARNINGS = new Set([
 const yieldToHost = () => new Promise((resolve) => setTimeout(resolve, 0));
 
 /**
- * The download file name: the deck's `filename` (a trailing .pptx, .pdf, .png or .svg is dropped), else the slugified `name`, else
+ * The file name: the deck's `filename` (a trailing .pptx, .pdf, .png or .svg is dropped), else the slugified `name`, else
  * "presentation", plus `suffix` and `.extension`. Characters a file system rejects are replaced, so the name is safe to save.
  */
 export function exportFileName(deck, extension, suffix = "") {
@@ -43,12 +50,17 @@ export function exportFileName(deck, extension, suffix = "") {
   return `${base}${suffix}.${extension}`;
 }
 
-/** The slide numbers (0-based) an export covers. Hidden slides are skipped in an "all" export unless `includeHidden`; one chosen slide is always exported. */
-export function slidesToExport(deck, { slides = "all", slideIndex = 0, includeHidden = false } = {}) {
-  const count = deck?.slides?.length ?? 0;
-  if (Array.isArray(slides)) return slides.filter((index) => Number.isInteger(index) && index >= 0 && index < count);
-  if (slides === "current") return slideIndex >= 0 && slideIndex < count ? [slideIndex] : [];
-  return deck.slides.map((slide, index) => (includeHidden || slide?.hidden !== true ? index : -1)).filter((index) => index >= 0);
+/**
+ * The slide numbers (one-based, ascending) a conversion covers. `slides` is core's slide selection (`3`, `"1-3"`, `"1,3-5"`, `[1, 3]`;
+ * `parseSlideSelection`): exactly those slides, hidden or not. Without it every slide that is not hidden, or every slide with
+ * `includeHidden`. A deck without slides gives `[]`; a malformed selection or a slide past the end throws core's `OPFApiError`
+ * (`invalid-option`).
+ */
+export function slidesToConvert(deck, { slides, includeHidden = false } = {}) {
+  const list = Array.isArray(deck?.slides) ? deck.slides : [];
+  if (!list.length) return [];
+  if (slides !== undefined) return parseSlideSelection(slides, list.length);
+  return list.map((slide, index) => (includeHidden || slide?.hidden !== true ? index + 1 : 0)).filter(Boolean);
 }
 
 /**
@@ -72,7 +84,7 @@ function exportError(code, message, cause) {
 }
 
 // The faces a PDF may embed: the same permissive-license list as the SVG (`embeddableFonts`), as the bytes the converter reads. The fonts
-// handle itself is never given to `svgToPdf`: it would embed every face the registry holds, whatever its license.
+// handle itself is never given to `toPdf`: it would embed every face the registry holds, whatever its license.
 function pdfFontData(faces) {
   return faces.map((face) => {
     const text = String(face.dataUrl ?? "");
@@ -85,48 +97,84 @@ function pdfFontData(faces) {
 }
 
 const fontLabel = (face) => `${face.family} ${face.weight}${face.italic ? " italic" : ""}`;
+const scalar = (value) => value === null || ["string", "number", "boolean"].includes(typeof value);
 
-function slideOf(path) {
-  const match = /^slides\.(\d+)(?:\.|$)/.exec(String(path ?? ""));
-  return match ? Number(match[1]) : undefined;
-}
-
-/** A renderer or converter diagnostic as `{ code, severity, message, slide?, path? }` (`slide` is 0-based). */
-export function describeDiagnostic(diagnostic, source = "render") {
-  const code = diagnostic.code ?? `${source}-note`;
-  let message = diagnostic.message ?? code;
+// A renderer, PDF converter or editor note as core's Finding (finding.schema.json): `ruleId` is `<source>/<code>` and `category` the
+// source, as core's conversion reports them (`render/`, `pdf/`, `fonts/`); `path` is a JSON Pointer (core's `pointerFromPath`); `slide`
+// (zero-based, the Finding schema's convention) and `slideId` say which slide it belongs to; the note's own facts (font family, weight,
+// glyph count, ...) are `measured`.
+function findingOf(source, diagnostic, deck) {
+  const { code: rawCode, message: rawMessage, path: where, severity: _severity, ...details } = diagnostic ?? {};
+  const code = String(rawCode ?? "note").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "") || "note";
+  let message = rawMessage ?? code;
   let severity = "warning";
   if (code === "pdf-font-embedded") {
     severity = "info";
-    message = `Embedded ${diagnostic.family} ${diagnostic.weight}${diagnostic.italic ? " italic" : ""} (${diagnostic.embedding}, ${diagnostic.glyphs} glyphs).`;
+    message = `Embedded ${details.family} ${details.weight}${details.italic ? " italic" : ""} (${details.embedding}, ${details.glyphs} glyphs).`;
   } else if (code === "pdf-font-substituted" || code === "pdf-font-fallback") {
-    message = diagnostic.message ?? "A font was substituted in the PDF.";
-  } else if (source === "pdf" && !FONT_WARNINGS.has(code) && !/^pdf-unsupported-/.test(code)) {
+    message = rawMessage ?? "A font was substituted in the PDF.";
+  } else if (source === "pdf" && !PDF_WARNINGS.has(code) && !/^pdf-unsupported-/.test(code)) {
     severity = "info";
   }
-  const slide = slideOf(diagnostic.path);
-  return { code, severity, message, ...(slide === undefined ? {} : { slide }), ...(diagnostic.path ? { path: diagnostic.path } : {}), ...(diagnostic.family ? { family: diagnostic.family } : {}) };
+  const path = typeof where === "string" && where ? pointerFromPath(where) : "";
+  const slideMatch = /^\/slides\/(\d+)(?:\/|$)/.exec(path);
+  const slide = slideMatch ? Number(slideMatch[1]) : undefined;
+  const slideId = slide === undefined ? undefined : deck?.slides?.[slide]?.id;
+  const measured = {};
+  // A long text (an image's data URI) is cut: the finding names the fact, the deck holds the value.
+  const short = (value) => (typeof value === "string" && value.length > 200 ? `${value.slice(0, 199)}…` : value);
+  for (const [key, value] of Object.entries(details)) {
+    if (scalar(value)) measured[key] = short(value);
+    else if (Array.isArray(value) && value.length && value.every(scalar)) measured[key] = short(value.join(", "));
+  }
+  return {
+    ruleId: `${source}/${code}`,
+    severity,
+    category: source,
+    path,
+    scope: "document",
+    message: String(message),
+    ...(slide === undefined ? {} : { slide }),
+    ...(typeof slideId === "string" ? { slideId } : {}),
+    ...(Object.keys(measured).length ? { measured } : {}),
+  };
 }
 
+// The picture size in pixels: the SVG's width and height attributes, a PNG's IHDR.
+const svgSize = (svg) => {
+  const tag = /<svg\b[^>]*>/.exec(svg)?.[0] ?? "";
+  const width = Number(/\bwidth="([\d.]+)"/.exec(tag)?.[1]);
+  const height = Number(/\bheight="([\d.]+)"/.exec(tag)?.[1]);
+  return Number.isFinite(width) && Number.isFinite(height) ? { width, height } : {};
+};
+const pngSize = (bytes) => {
+  if (!(bytes instanceof Uint8Array) || bytes.length < 24) return {};
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+};
+
 async function loadConverters(options) {
-  if (options.convert) return options.convert;
+  if (options.converters) return options.converters;
   try {
     return await import("@openpresentation/opf-render/export-browser");
   } catch (cause) {
-    throw exportError("export-unavailable", "PDF and PNG export need @openpresentation/opf-render with its export-browser entry. SVG export works without it.", cause);
+    throw exportError("export-unavailable", "PDF and PNG output need @openpresentation/opf-render with its export-browser entry. SVG works without it.", cause);
   }
 }
 
 /**
- * Convert the deck's slides to a download.
+ * Convert the deck's slides to PDF, PNG or SVG files, in memory. The name and the result are core's in-memory `convert`.
  *
  * `options`:
  * - `format`: "pdf", "png" or "svg" (required).
- * - `slides`: "current" (with `slideIndex`), "all" (default; hidden slides only with `includeHidden`) or an array of slide numbers.
- * - `pdfMode`: "vector" (default: selectable text, vector shapes) or "raster" (each slide an image).
- * - `pdfLib`: for `pdfMode: "raster"` only, the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (RR-63, opf-render 0.16),
- *   so a host that offers the raster PDF imports pdf-lib itself; without it a raster PDF rejects with the renderer's `converter-missing` (its `details.install` names the package).
- *   Vector PDF, PNG and SVG need no option.
+ * - `slides`: core's slide selection, counted from 1 (`3`, `"1-3"`, `"1,3-5"`, `[1, 3]`): exactly those slides, hidden or not. Omitted:
+ *   every slide that is not hidden, or every slide with `includeHidden`.
+ * - `raster`: PDF only; each page an image of its slide instead of selectable text and vector shapes.
+ * - `pdfLib`: for `raster: true` only, the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry
+ *   imports no PDF library (RR-63, opf-render 0.16), so a host that offers the raster PDF imports pdf-lib itself; without it a raster
+ *   PDF rejects with the renderer's `converter-missing` (its `details.install` names the package). Vector PDF, PNG and SVG need no option.
+ * - `zip`: PNG and SVG only; one ZIP archive of the slides instead of one file per slide (even for one slide).
+ * - `name`: the base name of the files (`name.pdf`, `name-001.png`, `name.zip`). Omitted: the deck's `filename`, else its slugified `name`.
  * - `scale`: PNG pixel density, 1 to 4 (default 2); also the raster PDF's density.
  * - `renderOptions`: the render options the host draws with (`catalogs`, `date`, ...), the same as its preview.
  * - `catalogs`: the host's registered catalogs (`Catalog[]`, merged with `renderOptions.catalogs`). The deck is embedded first (core's
@@ -135,74 +183,114 @@ async function loadConverters(options) {
  *   `textMeasurement` lays the slides out, the faces the deck needs load through its `ensure` before anything is drawn, and its registry's
  *   faces are what gets embedded: the SVG carries the faces its slides draw, and the PDF embeds the registry's faces (script faces included).
  *   Both apply the same license rule (OFL-1.1, Apache-2.0, MIT or UFL-1.0): a face whose license text names none of them is left out of the SVG
- *   and the PDF and reported once as `export-font-license`. Text that needed it is drawn with another face the registry holds and
- *   reported by the converter (`pdf-font-substituted`, `pdf-glyph-missing`); when no face is left at all the PDF rejects with
+ *   and the PDF and reported once as `fonts/export-font-license`. Text that needed it is drawn with another face the registry holds and
+ *   reported by the converter (`pdf/pdf-font-substituted`, `pdf/pdf-glyph-missing`); when no face is left at all the PDF rejects with
  *   `export-fonts-unlicensed` (the converter's error is its `cause`).
- * - `signal`, `onProgress({ stage, done, total, message })`, `onDiagnostic(diagnostic)`.
- * Resolves `{ download, files, diagnostics, slides }`. Rejects with an error whose `code` is `export-aborted`,
- * `export-fonts-unlicensed`, `export-no-slides`, `export-unavailable`, `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
+ * - `converters`: `{ toPdf, toPng }` in place of the renderer's `export-browser` entry (tests, or a host with its own converter).
+ * - `signal`, `onProgress({ stage, done, total, message })`, `onFinding(finding)`.
+ * Resolves `{ files, findings }`. Rejects with an error whose `code` is `export-aborted`, `export-fonts-unlicensed`, `export-format`,
+ * `export-no-slides`, `export-unavailable`, `fonts-unavailable`, `invalid-option` (core's, for a malformed slide selection or a slide past
+ * the end; the editor's, for `zip` or `raster` with a format they do not apply to) or a renderer code (`converter-missing` for a raster
+ * PDF without `pdfLib`).
  */
-export async function exportDeck(input, options = {}) {
-  const format = EXPORT_FORMATS[options.format];
+export async function convert(input, options = {}) {
+  const format = EXPORT_FORMATS[options?.format];
   if (!format) throw exportError("export-format", `Choose a format: ${Object.keys(EXPORT_FORMATS).join(", ")}.`);
+  if (options.zip && format.extension === "pdf") throw exportError("invalid-option", "zip applies to format png and svg.");
+  if (options.raster && format.extension !== "pdf") throw exportError("invalid-option", "raster applies to format pdf.");
   const { signal } = options;
-  const diagnostics = [];
-  const note = (diagnostic) => { diagnostics.push(diagnostic); options.onDiagnostic?.(diagnostic); };
+  const findings = [];
+  const seen = new Set();
+  // One finding per rule, place and message: a deck of 200 slides reports one substituted font once, not 200 times.
+  const note = (finding) => {
+    const key = JSON.stringify([finding.ruleId, finding.path, finding.message]);
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push(finding);
+    options.onFinding?.(finding);
+  };
   const progress = (stage, done, total, message) => options.onProgress?.({ stage, done, total, message });
-  const check = () => { if (signal?.aborted) throw exportError("export-aborted", "The export was cancelled."); };
-  const indexes = slidesToExport(input, options);
-  if (!indexes.length) throw exportError("export-no-slides", "There are no slides to export.");
-  const selected = new Set(indexes);
-  const keep = (diagnostic) => diagnostic.slide === undefined || selected.has(diagnostic.slide);
+  const aborted = () => exportError("export-aborted", "The export was cancelled.");
+  const check = () => { if (signal?.aborted) throw aborted(); };
+  const numbers = slidesToConvert(input, options);
+  if (!numbers.length) throw exportError("export-no-slides", "There are no slides to export.");
+  // A note about a slide that is not converted is left out (finding slides are zero-based).
+  const selected = new Set(numbers.map((number) => number - 1));
   const scale = Math.min(MAX_PNG_SCALE, Math.max(1, Number(options.scale) || 2));
   const catalogs = mergeCatalogs(options.catalogs, options.renderOptions?.catalogs);
   const renderOptions = { ...(options.renderOptions ?? {}), catalogs };
   const deck = prepareSave(input, { catalogs }).document;
+  const record = (source, diagnostic) => {
+    const finding = findingOf(source, diagnostic, deck);
+    if (finding.slide === undefined || selected.has(finding.slide)) note(finding);
+  };
 
   check();
   const gate = fontGate(options.fonts);
   if (gate?.pending(deck, renderOptions).length) {
     progress("fonts", 0, 1, "Loading fonts…");
     try { await gate.ensure(deck, { signal, renderOptions }); }
-    catch (error) { if (signal?.aborted) throw exportError("export-aborted", "The export was cancelled."); throw error; }
+    catch (error) { if (signal?.aborted) throw aborted(); throw error; }
   }
   check();
   const converters = format.extension === "svg" ? null : await loadConverters(options);
 
   const dropped = [];
-  const embeddedFonts = options.embeddedFonts ?? embeddableFonts(options.fonts?.registry, (face) => { dropped.push(face); note({ code: "export-font-license", severity: "warning", message: `${fontLabel(face)} is not embedded: its license is not one of OFL-1.1, Apache-2.0, MIT or UFL-1.0.`, family: face.family }); });
-  progress("render", 0, indexes.length, "Drawing slides…");
+  const embeddedFonts = options.embeddedFonts ?? embeddableFonts(options.fonts?.registry, (face) => {
+    dropped.push(face);
+    const detail = { family: face.family, weight: face.weight, ...(face.italic ? { italic: true } : {}) };
+    note(findingOf("fonts", { code: "export-font-license", message: `${fontLabel(face)} is not embedded: its license is not one of OFL-1.1, Apache-2.0, MIT or UFL-1.0.`, ...detail }, deck));
+  });
+  progress("render", 0, numbers.length, "Drawing slides…");
   await yieldToHost();
-  const rendered = renderSvg(deck, {
+  // RR-65, RR-64: the handle's subset engine (a browser handle created with `subsetWasm`) cuts each face a standalone SVG embeds to the
+  // slide's glyphs, and its outline engine (`shapeWasm` shapes them with HarfBuzz) draws `renderOptions.text: "paths"`. Both are carried
+  // from the handle by hand because the face list above is the editor's licensed one, not the handle's. A PDF reads whole faces and
+  // the SVG's own @font-face data (its converter cuts its own subsets), and selectable text is its point, so it gets neither: a
+  // `text: "paths"` render option draws a PDF's text as text. A PNG is a picture of the SVG: it takes the outlines, not the subsets.
+  const toPdf = format.extension === "pdf";
+  const handle = options.fonts;
+  const drawFonts = {
+    textMeasurement: handle?.textMeasurement,
+    embeddedFonts,
+    ...(format.extension === "svg" && handle?.subsets ? { subsets: handle.subsets } : {}),
+    ...(!toPdf && handle?.outlines ? { outlines: handle.outlines } : {}),
+  };
+  const svgs = toSvg(deck, numbers, {
     ...renderOptions,
-    fonts: { textMeasurement: options.fonts?.textMeasurement, embeddedFonts },
+    ...(toPdf && renderOptions.text === "paths" ? { text: "fonts" } : {}),
+    fonts: drawFonts,
     // The PDF reports problems by element path; the SVG and PNG are the plain drawing.
-    trace: format.extension === "pdf",
+    trace: toPdf,
     onDiagnostic: (diagnostic) => {
-      const described = describeDiagnostic(diagnostic, "render");
-      if (keep(described)) note(described);
+      record("render", diagnostic);
       renderOptions.onDiagnostic?.(diagnostic);
     },
   });
   check();
-  const svgs = indexes.map((index) => rendered[index]);
-  progress("render", indexes.length, indexes.length, "Slides drawn");
+  progress("render", numbers.length, numbers.length, "Slides drawn");
 
-  const digits = Math.max(2, String(deck.slides.length).length);
-  const numbered = (index, extension) => exportFileName(deck, extension, `-${String(index + 1).padStart(digits, "0")}`);
+  const named = (extension, suffix = "") => exportFileName(options.name === undefined ? deck : { filename: String(options.name) }, extension, suffix);
+  // Slide files are numbered as core numbers them: three digits at least (`-001`), more for a longer deck.
+  const digits = Math.max(3, String(deck.slides.length).length);
+  const numbered = (number, extension) => named(extension, `-${String(number).padStart(digits, "0")}`);
+  const facts = (number) => {
+    const id = deck.slides[number - 1]?.id;
+    return { slide: number, ...(typeof id === "string" ? { id } : {}) };
+  };
   let files;
   if (format.extension === "svg") {
     const header = '<?xml version="1.0" encoding="UTF-8"?>\n';
-    files = svgs.map((svg, position) => ({ name: numbered(indexes[position], "svg"), type: format.type, bytes: new TextEncoder().encode(header + svg) }));
+    files = svgs.map((svg, position) => ({ name: numbered(numbers[position], "svg"), type: format.type, bytes: new TextEncoder().encode(header + svg), ...facts(numbers[position]), ...svgSize(svg) }));
   } else if (format.extension === "png") {
     files = [];
     for (const [position, svg] of svgs.entries()) {
       check();
-      progress("convert", position, svgs.length, `Slide ${indexes[position] + 1} of ${deck.slides.length}`);
+      progress("convert", position, svgs.length, `Slide ${numbers[position]} of ${deck.slides.length}`);
       let bytes;
-      try { bytes = await converters.svgToPng(svg, { scale, signal }); }
-      catch (error) { if (signal?.aborted) throw exportError("export-aborted", "The export was cancelled."); throw error; }
-      files.push({ name: numbered(indexes[position], "png"), type: format.type, bytes });
+      try { bytes = await converters.toPng(svg, { scale, signal }); }
+      catch (error) { if (signal?.aborted) throw aborted(); throw error; }
+      files.push({ name: numbered(numbers[position], "png"), type: format.type, bytes, ...facts(numbers[position]), ...pngSize(bytes) });
       await yieldToHost();
     }
     progress("convert", svgs.length, svgs.length, "Images ready");
@@ -210,43 +298,35 @@ export async function exportDeck(input, options = {}) {
     const metadata = { ...(deck.name ? { title: String(deck.name) } : {}), ...(deck.description ? { subject: String(deck.description) } : {}), ...(options.metadata ?? {}) };
     let bytes;
     try {
-      bytes = await converters.svgToPdf(svgs, {
-        mode: options.pdfMode === "raster" ? "raster" : "vector",
+      bytes = await converters.toPdf(svgs, {
+        ...(options.raster ? { raster: true } : {}),
         scale,
         metadata,
         signal,
         fontData: pdfFontData(embeddedFonts),
-        // RR-63: the renderer's browser entry imports no pdf-lib; raster mode takes the module the host imported.
-        ...(options.pdfMode === "raster" && options.pdfLib ? { pdfLib: options.pdfLib } : {}),
+        // RR-63: the renderer's browser entry imports no pdf-lib; a raster PDF takes the module the host imported.
+        ...(options.raster && options.pdfLib ? { pdfLib: options.pdfLib } : {}),
         ...(options.fallbackFamily ? { defaultFontFamily: options.fallbackFamily } : {}),
-        onDiagnostic: (diagnostic) => { const described = describeDiagnostic(diagnostic, "pdf"); if (keep(described)) note(described); },
+        onDiagnostic: (diagnostic) => record("pdf", diagnostic),
         onProgress: ({ page, pages }) => progress("convert", page, pages, `Page ${page} of ${pages}`),
       });
     } catch (error) {
-      if (signal?.aborted) throw exportError("export-aborted", "The export was cancelled.");
+      if (signal?.aborted) throw aborted();
       // The license rule can leave the converter with no face for some text (every face of a family was dropped): say why, not only what.
       if (dropped.length && /font face/i.test(String(error?.message))) {
         throw exportError("export-fonts-unlicensed", `The PDF could not be written: ${dropped.map(fontLabel).join(", ")} ${dropped.length === 1 ? "is" : "are"} not embedded because the license is not one of OFL-1.1, Apache-2.0, MIT or UFL-1.0, and no other face is available. ${error.message}`, error);
       }
       throw error;
     }
-    files = [{ name: exportFileName(deck, "pdf"), type: format.type, bytes }];
+    files = [{ name: named("pdf"), type: format.type, bytes, pages: numbers.length, slides: numbers }];
   }
 
   check();
-  let download = files[0];
-  if (files.length > 1) {
+  if (options.zip) {
     progress("archive", 0, files.length, "Packing files…");
     const bytes = await createZip(files.map(({ name, bytes: data }) => ({ name, bytes: data })), { signal });
-    download = { name: exportFileName(deck, "zip", `-${format.extension}`), type: "application/zip", bytes };
+    files = [{ name: named("zip"), type: ZIP_TYPE, bytes, entries: files.map((file) => file.name) }];
   }
   progress("done", 1, 1, "Ready");
-  // One note per kind: a deck of 200 slides reports one substituted font once, not 200 times.
-  const unique = [];
-  const seen = new Set();
-  for (const diagnostic of diagnostics) {
-    const key = `${diagnostic.code}|${diagnostic.message}|${diagnostic.path ?? ""}`;
-    if (!seen.has(key)) { seen.add(key); unique.push(diagnostic); }
-  }
-  return { download, files, diagnostics: unique, slides: indexes };
+  return { files, findings };
 }

package/dist/find-panel.js

@@ -147,8 +147,9 @@ export function createFindPanel(container, options) {
     matches.slice(0, MAX_LISTED).forEach((match, index) => {
       const mark = h(doc, "mark", { text: match.context.match });
       const text = h(doc, "span", { class: "opf-find-text" }, doc.createTextNode(match.context.before), mark, doc.createTextNode(match.context.after));
-      const button = h(doc, "button", { type: "button", class: "opf-find-result", "aria-current": index === current ? "true" : "false", "data-index": String(index), "aria-label": `${whereLabel(match)}: ${match.context.before}${match.context.match}${match.context.after}` },
-        h(doc, "span", { class: "opf-find-where", text: whereLabel(match) }), text);
+      const button = h(doc, "button", { type: "button", class: "opf-find-result", "aria-current": index === current ? "true" : "false", "data-index": String(index) },
+        // WCAG 2.5.3 (label in name): no aria-label. The name is the visible text, the place and then the matching line, kept apart by a space.
+        h(doc, "span", { class: "opf-find-where", text: whereLabel(match) }), " ", text);
       list.append(h(doc, "li", {}, button));
     });
     if (matches.length > MAX_LISTED) list.append(h(doc, "li", { class: "opf-find-more", text: `Showing the first ${MAX_LISTED} of ${matches.length}${result.truncated ? "+" : ""} matches.` }));

package/dist/font-gate.js

@@ -4,7 +4,7 @@
 // fails with "Intos Display cannot display U+65E5"), so nothing may render or measure a new document before `ensure`
 // resolves. The renderer's fonts handle (`loadFonts()` from `@openpresentation/opf-render/fonts-browser`) is the source of
 // truth: its `pending(presentation, renderOptions)` and `ensure(presentation, options)` know what is missing and load it. The
-// canvas and `exportDeck` take that handle as `fonts` and gate every document-replacing path through this module.
+// canvas and `convert` (`/export`) take that handle as `fonts` and gate every document-replacing path through this module.
 
 /** Error code of a document whose required faces are still loading. */
 export const FONTS_PENDING = "fonts-pending";

package/dist/review-panel.js

@@ -159,7 +159,8 @@ export function createReviewPanel(container, options) {
   const list = h(doc, "div", { class: "opf-review-list", role: "group", "aria-label": "Review findings" });
   const empty = h(doc, "p", { class: "opf-review-empty" });
   const ignoredBox = h(doc, "details", { class: "opf-review-ignored", hidden: true });
-  root.append(head, ...(hookStatus ? [hookStatus] : []), filters, list, empty, ignoredBox);
+  const gotoHint = h(doc, "span", { id: `${id}-goto-hint`, hidden: true, text: "Go to it." });
+  root.append(head, ...(hookStatus ? [hookStatus] : []), filters, list, empty, ignoredBox, gotoHint);
   container.append(root);
 
   const say = (message, error = false) => {
@@ -310,11 +311,13 @@ export function createReviewPanel(container, options) {
       type: "button",
       class: "opf-review-goto",
       "data-finding-id": finding.id,
-      "aria-label": `${SEVERITY_LABELS[finding.severity]}, ${where}: ${finding.message} Go to it.`,
+      // WCAG 2.5.3 (label in name): no aria-label. The name is the visible text (severity, message, where and rule), kept apart by spaces;
+      // what the button does is its description.
+      "aria-describedby": `${id}-goto-hint`,
       onclick: () => go(finding),
     },
-    h(doc, "span", { class: "opf-review-sev", text: SEVERITY_LABELS[finding.severity] }),
-    h(doc, "span", { class: "opf-review-msg", text: finding.message }),
+    h(doc, "span", { class: "opf-review-sev", text: SEVERITY_LABELS[finding.severity] }), " ",
+    h(doc, "span", { class: "opf-review-msg", text: finding.message }), " ",
     h(doc, "span", { class: "opf-review-meta", text: `${where} · ${finding.ruleId}${finding.source && finding.source !== CORE_SOURCE ? ` · ${finding.source}` : ""}` }));
     const li = h(doc, "li", { class: "opf-review-item", "data-finding-id": finding.id, "data-rule": finding.ruleId, "data-source": finding.source ?? CORE_SOURCE, "data-severity": finding.severity, "aria-current": String(finding.id === currentId) }, go_,
       finding.help ? h(doc, "p", { class: "opf-review-help", text: finding.help }) : undefined);
@@ -359,7 +362,7 @@ export function createReviewPanel(container, options) {
     ignoredBox.replaceChildren(
       h(doc, "summary", { text: `Hidden checks (${ignored.size})` }),
       h(doc, "ul", { class: "opf-review-ignored-list", style: "list-style:none;padding:0" }, ...[...ignored].map((ruleId) => h(doc, "li", {}, h(doc, "span", { text: ruleId }),
-        h(doc, "button", { type: "button", class: "opf-review-fix quiet", "data-restore": ruleId, text: "Show again", "aria-label": `Show ${ruleId} findings again`, onclick: () => setIgnored(ruleId, false) })))),
+        h(doc, "button", { type: "button", class: "opf-review-fix quiet", "data-restore": ruleId, text: "Show again", "aria-label": `Show again, ${ruleId} findings`, onclick: () => setIgnored(ruleId, false) })))),
     );
   }
 

package/dist/review.d.ts

@@ -61,8 +61,13 @@ export declare function groupFindings(findings: readonly ReviewFinding[]): { cat
 export declare function findingTarget(presentation: unknown, finding: Pick<ReviewFinding, "path">): ReviewTarget;
 /** Apply a `patch` fix as one undoable, validated session change; refuses a stale or unsafe patch. */
 export declare function applyReviewFix(editor: EditorSession, finding: Pick<ReviewFinding, "ruleId"> | undefined, fix: ReviewFix, meta?: Record<string, unknown>): EditorChange;
-/** The patch that sets (or, for `""`, marks decorative) the alt text of the picture at `pointer`; null when nothing changes. */
+/**
+ * The patch that sets (or, for `""`, marks decorative) the alt text of the picture at `pointer`; null when nothing changes. A
+ * logo reference (`var:organization.logo.icon`) stays a whole-field string: its alt is written on the organization logo
+ * asset(s) it draws, and a reference that names no logo is refused (`unresolved-logo-alt`).
+ */
 export declare function altTextPatch(presentation: unknown, pointer: string, text: string): JsonPatchOperation[] | null;
 export declare function setReviewAltText(editor: EditorSession, pointer: string, text: string, meta?: Record<string, unknown>): { changed: boolean } & Partial<EditorChange>;
 export declare function markDecorative(editor: EditorSession, pointer: string, meta?: Record<string, unknown>): { changed: boolean } & Partial<EditorChange>;
+/** The alt text a picture has now; for a logo reference, the alt of the organization asset it draws. */
 export declare function currentAltText(presentation: unknown, pointer: string): string;

package/dist/review.js

@@ -7,7 +7,9 @@
 // module needs no DOM.
 import { validationCategories } from "@openpresentation/opf";
 import { OPFEditorError, getValueAtPath, hasValueAtPath, jsonPointerToOpfPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
+import { resolveLogo } from "@openpresentation/opf/composition";
 import { assetIdOf, prepareAssetAlt } from "./assets.js";
+import { parseLogoReference } from "./design-options.js";
 
 function fail(code, message, details) {
   return new OPFEditorError(code, message, details);
@@ -158,10 +160,36 @@ export function applyReviewFix(editor, finding, fix, meta = {}) {
 
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
-/** The patch operations that give the asset value at `pointer` alt text (`""` marks it decorative), or `null` when it already has exactly this alt. */
+// RR-71: a logo reference (`var:organization.logo.icon`) is a whole-field string, so its alt text cannot be written beside
+// it ({ src: "var:…", alt } is an ordinary image whose source is no longer the logo). The logo's alt lives on the
+// organization's asset (Organization.logo, each shape and onLight/onDark value a path or Asset): these are the OPF paths of
+// the assets the reference draws, on a light and on a dark background (one path when both resolve to the same asset).
+function logoAltPaths(presentation, value) {
+  if (typeof value !== "string" || !parseLogoReference(value)) return null;
+  const paths = new Set();
+  for (const onDark of [false, true]) {
+    const logo = resolveLogo(presentation, undefined, { reference: value, onDark });
+    if (logo) paths.add(logo.path);
+  }
+  if (!paths.size) {
+    throw fail("unresolved-logo-alt", `${value} names no logo yet. Add the organization's logo first; its alt text is written on the logo in the organization.`, { reference: value });
+  }
+  return [...paths];
+}
+
+/**
+ * The patch operations that give the asset value at `pointer` alt text (`""` marks it decorative), or `null` when it already
+ * has exactly this alt. For a logo reference the alt is written on the organization logo asset(s) it draws.
+ */
 export function altTextPatch(presentation, pointer, text) {
   const value = getValueAtPath(presentation, pointer);
   if (value === undefined) throw fail("stale-finding", "The picture this finding is about no longer exists.", { pointer });
+  const logoPaths = logoAltPaths(presentation, value);
+  if (logoPaths) {
+    // Both backgrounds may name one registry asset (asset:<id>): write it once.
+    const operations = [...new Map(logoPaths.flatMap((path) => altTextPatch(presentation, opfPathToJsonPointer(splitOpfPath(path)), text) ?? []).map((operation) => [JSON.stringify(operation), operation])).values()];
+    return operations.length ? operations : null;
+  }
   const alt = String(text ?? "");
   const id = assetIdOf(value);
   const entry = id === undefined ? undefined : getValueAtPath(presentation, ["assets", id]);
@@ -202,6 +230,14 @@ export function markDecorative(editor, pointer, meta = {}) {
 /** The alt text a picture has now (own or through the assets registry), for pre-filling the field. */
 export function currentAltText(presentation, pointer) {
   const value = getValueAtPath(presentation, pointer);
+  // A logo reference shows the alt of the organization asset it draws (on a light background first).
+  if (typeof value === "string" && parseLogoReference(value)) {
+    for (const onDark of [false, true]) {
+      const logo = resolveLogo(presentation, undefined, { reference: value, onDark });
+      if (logo) return currentAltText(presentation, opfPathToJsonPointer(splitOpfPath(logo.path)));
+    }
+    return "";
+  }
   if (isObject(value) && typeof value.alt === "string") return value.alt;
   const id = assetIdOf(value);
   const entry = id === undefined ? undefined : getValueAtPath(presentation, ["assets", id]);

package/dist/slide-manager.js

@@ -139,10 +139,12 @@ export function createSlideManager(container, options) {
     const selected = selection.has(index);
     const title = slideTitle(slide) || "Untitled slide";
     const hidden = slide.hidden === true;
+    // WCAG 2.5.3 (label in name): the card has no aria-label. Its name is its own content (the number, the title and the "Hidden" badge;
+    // the thumbnail is aria-hidden), so the name always contains the visible text. The position and the selection are the description.
+    const position = `Slide ${index + 1} of ${slideCount}${selected && selection.size > 1 ? ", selected" : ""}`;
     const button = el("button", {
-      type: "button", class: "slide-card", draggable: "true", "data-index": index, "aria-current": String(index === current()),
-      "aria-label": `Slide ${index + 1} of ${slideCount}: ${title}${hidden ? ", hidden" : ""}${selected && selection.size > 1 ? ", selected" : ""}`,
-      "aria-describedby": `${id}-hint`, "aria-keyshortcuts": "Alt+ArrowUp Alt+ArrowDown Delete", tabindex: index === focusIndex ? "0" : "-1",
+      type: "button", class: "slide-card", draggable: "true", "data-index": index, "data-menu-label": `Slide ${index + 1} of ${slideCount}: ${title}`, "aria-current": String(index === current()),
+      "aria-describedby": `${id}-${index}-position ${id}-hint`, "aria-keyshortcuts": "Alt+ArrowUp Alt+ArrowDown Delete", tabindex: index === focusIndex ? "0" : "-1",
     });
     button.dataset.selected = String(selected);
     button.dataset.hidden = String(hidden);
@@ -156,8 +158,9 @@ export function createSlideManager(container, options) {
     thumbnail.querySelectorAll("[tabindex]").forEach((node) => node.removeAttribute("tabindex"));
     const label = el("span", { class: "thumbnail-title", text: slideTitle(slide) || "Untitled slide" });
     const content = el("span", { class: "thumbnail-content", draggable: "true" }, thumbnail, label);
-    if (hidden) content.append(el("span", { class: "slide-badge", text: "Hidden" }));
-    button.append(number, content);
+    if (hidden) content.append(" ", el("span", { class: "slide-badge", text: "Hidden" }));
+    // The explicit spaces keep the number, title and badge apart in the computed name; hidden elements still describe the button.
+    button.append(number, " ", content, el("span", { id: `${id}-${index}-position`, hidden: true, text: position }));
     button.addEventListener("click", (event) => choose(index, event));
     button.addEventListener("keydown", (event) => keydown(event, index));
     button.addEventListener("focus", () => { focusIndex = index; });
@@ -172,9 +175,11 @@ export function createSlideManager(container, options) {
     const name = sectionLabel(section.name);
     const header = el("div", { class: "slide-section", "data-section": section.index, "data-unnamed": String(section.unnamed) });
     const toggle = el("button", {
-      type: "button", class: "section-toggle", "aria-expanded": String(!isCollapsed), "aria-label": `${name}, ${plural(section.count, "slide")}`,
+      type: "button", class: "section-toggle", "aria-expanded": String(!isCollapsed), "aria-describedby": `${id}-section-${section.index}-count`,
       onclick: () => { if (isCollapsed) collapsed.delete(key); else collapsed.add(key); render(); },
-    }, el("span", { class: "section-caret", "aria-hidden": "true", text: isCollapsed ? "▸" : "▾" }), el("span", { class: "section-name", text: name }), el("span", { class: "section-count", "aria-hidden": "true", text: String(section.count) }));
+    }, el("span", { class: "section-caret", "aria-hidden": "true", text: isCollapsed ? "▸" : "▾" }), " ", el("span", { class: "section-name", text: name }), " ", el("span", { class: "section-count", "aria-hidden": "true", text: String(section.count) }),
+    // WCAG 2.5.3: no aria-label. The name is the visible section name; the slide count is the description.
+    el("span", { id: `${id}-section-${section.index}-count`, hidden: true, text: plural(section.count, "slide") }));
     const more = el("button", { type: "button", class: "section-more", "aria-label": `Section actions: ${name}`, "aria-haspopup": "menu", title: "Section actions" });
     more.append(icon("more"));
     more.addEventListener("click", () => { const box = more.getBoundingClientRect(); openMenu(box.left, box.bottom, more, sectionMenu(section)); });
@@ -424,7 +429,7 @@ export function createSlideManager(container, options) {
   }
   function openMenu(x, y, opener, items = slideMenu()) {
     closeMenu(false);
-    const root = el("div", { class: "opf-menu", role: "menu", "aria-label": opener.getAttribute?.("aria-label") ?? "Slide actions", tabindex: "-1" });
+    const root = el("div", { class: "opf-menu", role: "menu", "aria-label": opener.getAttribute?.("aria-label") ?? opener.dataset?.menuLabel ?? "Slide actions", tabindex: "-1" });
     const buttons = [];
     for (const item of items) {
       if (item.separator) { root.append(el("div", { class: "opf-menu-separator", role: "separator" })); continue; }