@openpresentation/opf-editor 0.17.0 → 0.18.0

package/dist/export.js

@@ -1,13 +1,16 @@
-// 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.
 //
-//   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 +20,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 +37,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 +48,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 +82,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 +95,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 +181,100 @@ 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, {
+  const svgs = toSvg(deck, numbers, {
     ...renderOptions,
     fonts: { textMeasurement: options.fonts?.textMeasurement, embeddedFonts },
     // The PDF reports problems by element path; the SVG and PNG are the plain drawing.
     trace: format.extension === "pdf",
     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 +282,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/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.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/template-panel.d.ts

@@ -5,7 +5,7 @@ export interface TemplatePanelOptions {
   editor: EditorSession;
   /**
    * Draw the live preview: return the SVG of one slide of `presentation` with `variables` (the values typed so far)
-   * as an SVG string, or a promise of one. Typically `renderSlideSvg(presentation, slideIndex, { variables, ... })` from
+   * as an SVG string, or a promise of one. Typically `toSvg(presentation, slideIndex + 1, { variables, ... })` from
    * `@openpresentation/opf-render` with the host's fonts. Omit for no preview.
    */
   renderPreview?: (input: { presentation: unknown; variables: Record<string, unknown>; slideIndex: number }) => string | Promise<string>;

package/dist/template-panel.js

@@ -67,7 +67,7 @@ export function createTemplatePanel(container, options) {
   const builtinList = h(doc, "ul", { class: "opf-template-builtin-list" });
   const builtinSection = h(doc, "details", { class: "opf-template-builtins", "data-opf-component": "template-builtins" },
     h(doc, "summary", { text: "Built-in variables" }),
-    h(doc, "p", { class: "opf-template-help", text: "Read from the presentation's own speaker, organization and deck fields; edit those fields to change them. Use them like any variable: {{speaker.name}} inside text, or var:speaker.photo as a whole image field. Slide number, section and slide count vary per slide: write them as {{slide.number}}, {{slide.section}} and {{deck.slideCount}} inside any text, not as a whole var: field." }),
+    h(doc, "p", { class: "opf-template-help", text: "Read from the presentation's own speaker, organization and deck fields; edit those fields to change them. Use them like any variable: {{speaker.name}} inside text, or var:speaker.photo as a whole image field. Slide number, section and slide count vary per slide: write them as {{slide.number}}, {{slide.section}} and {{deck.slideCount}} inside any text, not as a whole var: field. The organization logos are images that follow each slide's background (light or dark artwork): place one as a whole image field, for example var:organization.logo.icon in a header or footer zone's image, or choose it with Insert logo." }),
     builtinList);
   const live = h(doc, "p", { class: "opf-template-live", role: "status", "aria-live": "polite" });
   const applyButton = h(doc, "button", { type: "button", class: "opf-template-apply primary", text: "Fill the presentation" });
@@ -230,16 +230,19 @@ export function createTemplatePanel(container, options) {
     const builtins = listBuiltins(editor.presentation);
     insertSelect.replaceChildren(
       ...fields.map((field) => h(doc, "option", { value: field.id, text: `${field.label} (${KIND_LABELS[field.kind]})` })),
-      ...(builtins.length ? [h(doc, "optgroup", { label: "Built-in variables" }, ...builtins.map((entry) => h(doc, "option", { value: entry.name, text: `${entry.label} (${entry.name})` })))] : []),
+      // A slide-scoped image (an organization logo) is a whole-field var: reference, not a {{ }} token for text.
+      ...(builtins.length ? [h(doc, "optgroup", { label: "Built-in variables" }, ...builtins.filter((entry) => !(entry.scope === "slide" && entry.kind === "image")).map((entry) => h(doc, "option", { value: entry.name, text: `${entry.label} (${entry.name})` })))] : []),
     );
     builtinSection.hidden = !builtins.length;
     builtinList.replaceChildren(...builtins.map((entry) => {
       const uses = entry.uses.length;
       // A slide-scoped built-in has no single value: each slide gets its own when it is drawn or exported (FA-31).
       const slideScoped = entry.scope === "slide";
-      const shown = slideScoped ? h(doc, "em", { text: "varies per slide" }) : entry.available ? builtinValueText(entry) : h(doc, "em", { text: "not set" });
+      // RR-71: an organization logo is an image placed by var:, and the artwork follows each slide's background.
+      const logoImage = slideScoped && entry.kind === "image";
+      const shown = logoImage ? h(doc, "em", { text: "image; light or dark artwork per slide" }) : slideScoped ? h(doc, "em", { text: "varies per slide" }) : entry.available ? builtinValueText(entry) : h(doc, "em", { text: "not set" });
       return h(doc, "li", { "data-builtin": entry.name, "data-kind": entry.kind, "data-scope": entry.scope, "data-available": entry.available ? "true" : "false" },
-        h(doc, "code", { text: `{{${entry.name}}}` }), ` ${entry.label}: `, shown, slideScoped && !entry.available ? " (no slide has one yet)" : "", uses ? ` (used ${uses} time${uses === 1 ? "" : "s"})` : "");
+        h(doc, "code", { text: logoImage ? `var:${entry.name}` : `{{${entry.name}}}` }), ` ${entry.label}: `, shown, slideScoped && !logoImage && !entry.available ? " (no slide has one yet)" : "", logoImage && !entry.available ? " (no logo yet)" : "", uses ? ` (used ${uses} time${uses === 1 ? "" : "s"})` : "");
     }));
     slideSelect.replaceChildren(...(editor.presentation.slides ?? []).map((slide, index) => h(doc, "option", { value: String(index), text: `${index + 1}. ${slideTitle(slide) || "Untitled"}` })));
     previewSlide = Math.min(previewSlide, Math.max(0, (editor.presentation.slides?.length ?? 1) - 1));

package/dist/templates.js

@@ -8,7 +8,7 @@ import { OPFEditorError, getValueAtPath, opfPathToJsonPointer } from "./index.js
 
 const VARIABLE_ID = /^[a-z][a-z0-9-]*$/;
 // A built-in variable name (core FA-04): `speakers`, or deck/speaker/organization plus one or two dotted segments.
-const BUILTIN_NAME = /^(?:speakers|(?:deck|slide|speaker|organization)(?:\.[A-Za-z0-9_-]+){1,2})$/;
+const BUILTIN_NAME = /^(?:speakers|(?:deck|slide|speaker|organization)(?:\.[A-Za-z0-9_-]+){1,3})$/;
 const KINDS = ["color", "text", "number", "date", "image", "url", "list"];
 
 /** The form control each variable kind uses. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-editor",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
   "license": "MIT",
   "type": "module",
@@ -258,11 +258,11 @@
     "@codemirror/state": "6.7.6",
     "@codemirror/view": "6.43.13",
     "@lezer/highlight": "1.2.4",
-    "@openpresentation/opf": "^0.17.0",
+    "@openpresentation/opf": "^0.18.1",
     "jsonc-parser": "3.3.1"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.17.0"
+    "@openpresentation/opf-render": "^0.18.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
@@ -314,8 +314,9 @@
     "@expo-google-fonts/roboto-mono": "0.4.2",
     "@expo-google-fonts/stix-two-math": "0.4.0",
     "@expo-google-fonts/tinos": "0.4.2",
-    "@openpresentation/opf-pptx": "^0.17.0",
-    "@openpresentation/opf-render": "^0.17.0",
+    "@openpresentation/opf-pptx": "^0.18.0",
+    "@openpresentation/opf-render": "^0.18.0",
+    "@resvg/resvg-js": "2.6.2",
     "axe-core": "4.13.0",
     "esbuild": "0.28.2",
     "jszip": "3.10.2",