@openpresentation/opf-editor 0.16.0 → 0.18.0

package/dist/export.d.ts

@@ -1,58 +1,58 @@
-import type { RenderSvgOptions } from "@openpresentation/opf-render";
+import type { Catalog, ConvertResult, ConvertedFile, Finding, SlideSelection } from "@openpresentation/opf";
+import type { ToSvgOptions } from "@openpresentation/opf-render";
 import type { EditorFonts } from "./canvas.js";
 
+/** Core's result types: `convert` resolves exactly what core's in-memory `convert` resolves. */
+export type { ConvertResult, ConvertedFile };
+
 export type ExportFormat = "pdf" | "png" | "svg";
 export declare const EXPORT_FORMATS: Readonly<Record<ExportFormat, { extension: string; type: string; label: string }>>;
 /** Largest PNG scale offered (4: a 1280 x 720 slide is 5120 x 2880 pixels). */
 export declare const MAX_PNG_SCALE: 4;
 
 /**
- * The download name: the deck's `filename` (a trailing .pptx, .pdf, .png or .svg dropped), else the slugified `name`, else "presentation",
+ * The file name: the deck's `filename` (a trailing .pptx, .pdf, .png or .svg dropped), else the slugified `name`, else "presentation",
  * then `suffix` and `.extension`.
  */
 export declare function exportFileName(deck: { filename?: string; name?: string } | undefined, extension: string, suffix?: string): string;
-/** Slide numbers (0-based) an export covers; hidden slides are skipped in an "all" export unless `includeHidden`. */
-export declare function slidesToExport(deck: { slides?: Array<{ hidden?: boolean }> }, options?: { slides?: "current" | "all" | number[]; slideIndex?: number; includeHidden?: boolean }): number[];
+/**
+ * The slide numbers (one-based, ascending) a conversion covers: the `slides` selection (core's `parseSlideSelection`; hidden slides it
+ * names are included), else every slide that is not hidden (every slide with `includeHidden`). `[]` for a deck without slides. A malformed
+ * selection or a slide past the end throws core's `OPFApiError` `invalid-option`.
+ */
+export declare function slidesToConvert(deck: { slides?: Array<{ hidden?: boolean }> }, options?: { slides?: SlideSelection; includeHidden?: boolean }): number[];
 /** The registry's faces marked to embed only where a slide draws them; a face with a non-permissive license text is left out (`onSkip` is told). */
 export declare function embeddableFonts(registry: object | undefined, onSkip?: (face: { family: string; weight: number; italic?: boolean; license?: string }) => void): Array<Record<string, unknown>>;
 
-export interface ExportDiagnostic {
-  code: string;
-  severity: "info" | "warning";
-  message: string;
-  /** 0-based slide number, when the note belongs to one slide. */
-  slide?: number;
-  path?: string;
-  family?: string;
-}
-export declare function describeDiagnostic(diagnostic: { code?: string; message?: string; path?: string; family?: string; [key: string]: unknown }, source?: "render" | "pdf"): ExportDiagnostic;
-
-export interface ExportProgress {
+export interface ConvertProgress {
   stage: "fonts" | "render" | "convert" | "archive" | "done";
   done: number;
   total: number;
   message?: string;
 }
-export interface ExportFile { name: string; type: string; bytes: Uint8Array }
-export interface ExportOptions {
+export interface ConvertOptions {
   format: ExportFormat;
-  /** "all" (default), "current" (with `slideIndex`) or slide numbers (0-based). */
-  slides?: "current" | "all" | number[];
-  slideIndex?: number;
+  /** The slides, counted from 1: `3`, `"1-3"`, `"1,3-5"`, `"2-"`, `[1, 3]` (core's `SlideSelection`). Exactly those slides, hidden or not. Omitted: every slide that is not hidden. */
+  slides?: SlideSelection;
+  /** With `slides` omitted, hidden slides too. */
   includeHidden?: boolean;
-  /** "vector" (default): selectable text and vector shapes; "raster": an image per slide. */
-  pdfMode?: "vector" | "raster";
+  /** PDF only: each page an image of its slide (larger, text not selectable). Default: selectable text and vector shapes. */
+  raster?: boolean;
   /**
    * Raster PDF only: the pdf-lib module (`import * as pdfLib from "pdf-lib"`). The renderer's `export-browser` entry imports no PDF library (opf-render 0.16), so the host passes it;
-   * without it a `pdfMode: "raster"` PDF rejects with the renderer's `converter-missing`. Vector PDF, PNG and SVG need no option.
+   * without it a `raster: true` PDF rejects with the renderer's `converter-missing`. Vector PDF, PNG and SVG need no option.
    */
   pdfLib?: { PDFDocument: { create(options?: { updateMetadata?: boolean }): Promise<any> } };
+  /** PNG and SVG only: one ZIP archive of the slide files (its `entries` name them), even for one slide. Default: one file per slide. */
+  zip?: boolean;
+  /** The base name of the files (`name.pdf`, `name-001.png`, `name.zip`). Default: the deck's `filename`, else its slugified `name`, else "presentation". */
+  name?: string;
   /** PNG pixel density (and the raster PDF's), 1 to 4; default 2. */
   scale?: number;
   /** The options the host draws its preview with (`catalogs`, `date`, ...); the fonts go in `fonts`. */
-  renderOptions?: RenderSvgOptions;
+  renderOptions?: ToSvgOptions;
   /** Host catalogs (merged with `renderOptions.catalogs`). The deck is embedded first (core `embed`), like a saved file. */
-  catalogs?: readonly import("@openpresentation/opf").Catalog[];
+  catalogs?: readonly Catalog[];
   /** The renderer's fonts handle (`loadFonts()`): it measures the text, loads the faces the deck needs before anything is drawn, and its registry's faces are what gets embedded. */
   fonts?: EditorFonts;
   /** Faces to embed instead of the registry's. */
@@ -61,22 +61,23 @@ export interface ExportOptions {
   metadata?: Record<string, unknown>;
   /** The family the PDF uses when a requested one is missing; default "Roboto". */
   fallbackFamily?: string;
-  /** Replace the renderer's `export-browser` entry (tests, or a host with its own converter). */
-  convert?: { svgToPdf(svgs: string[], options?: object): Promise<Uint8Array>; svgToPng(svg: string, options?: object): Promise<Uint8Array> };
+  /** Replace the renderer's `export-browser` entry (tests, or a host with its own converter). Each takes the SVG the renderer drew. */
+  converters?: { toPdf(svgs: string[], options?: object): Promise<Uint8Array>; toPng(svg: string, options?: object): Promise<Uint8Array> };
   signal?: AbortSignal;
-  onProgress?: (progress: ExportProgress) => void;
-  onDiagnostic?: (diagnostic: ExportDiagnostic) => void;
-}
-export interface ExportResult {
-  /** One PDF, PNG or SVG, or a ZIP of several. */
-  download: ExportFile;
-  files: ExportFile[];
-  diagnostics: ExportDiagnostic[];
-  /** The slide numbers (0-based) exported. */
-  slides: number[];
+  onProgress?: (progress: ConvertProgress) => void;
+  /** Each finding as it is made (also in the result's `findings`). */
+  onFinding?: (finding: Finding) => void;
 }
 /**
- * Draw the deck with the renderer the preview uses and convert it. Rejects with an error whose `code` is `export-aborted`, `export-fonts-unlicensed` (the license rule left the PDF converter no face for some text), `export-no-slides`,
- * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable` or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
+ * Draw the deck with the renderer the preview uses and convert it, in memory: core's `convert(deck, { format })` for the editor.
+ *
+ * `files`: one PDF (`pages`, and the one-based `slides` it shows); one PNG or SVG per slide (`slide`, one-based, `id`, `width`, `height`);
+ * or with `zip` one archive (`entries`). `findings`: core's Finding shape, `ruleId` `render/<code>` (the renderer), `pdf/<code>` (the PDF
+ * converter) or `fonts/export-font-license` (a face left out under the license rule); `slide` on a finding is zero-based, as the Finding
+ * schema defines it.
+ *
+ * Rejects with an error whose `code` is `export-aborted`, `export-fonts-unlicensed` (the license rule left the PDF converter no face for some text), `export-no-slides`,
+ * `export-format`, `export-unavailable` (PDF and PNG need the renderer's `export-browser` entry), `fonts-unavailable`, `invalid-option` (a malformed slide selection or a
+ * slide past the end, from core's `parseSlideSelection`; `zip` with PDF; `raster` with PNG or SVG) or a renderer code (`converter-missing` for a raster PDF without `pdfLib`).
  */
-export declare function exportDeck(deck: unknown, options: ExportOptions): Promise<ExportResult>;
+export declare function convert(deck: unknown, options: ConvertOptions): Promise<ConvertResult>;

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/find-replace.js

@@ -21,6 +21,11 @@ const REGION_KEY = /^(?:top|middle|bottom|left|center|right)(?:[+:]|$)/;
 const WORD_BEFORE = "(?<![\\p{L}\\p{N}_])";
 const WORD_AFTER = "(?![\\p{L}\\p{N}_])";
 
+// A variable token (`{{customer}}`, `{{slide.number}}`, `{{ deck.slideCount }}`, `{{revenue|0.0}}`). It is an instruction, not text: a match inside it is
+// never offered, because replacing part of a name would either break the variable or silently change which value it shows (FA-31). An
+// escaped `\{{` is literal text and is searched like the rest.
+const VARIABLE_TOKEN = /(?<!\\)\{\{\s*[A-Za-z][A-Za-z0-9_.-]*\s*(?:\|[^{}]*)?\}\}/g;
+
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const runText = (run) => (typeof run === "string" ? run : isObject(run) && typeof run.text === "string" ? run.text : "");
 const isRuns = (value) => Array.isArray(value) && value.length > 0 && value.every((run) => typeof run === "string" || (isObject(run) && typeof run.text === "string"));
@@ -205,7 +210,8 @@ function snippet(text, start, end) {
  * Search a document. Returns `{ matches, fieldCount, slideCount, truncated, error }`. A match is `{ id, pointer, path,
  * slideIndex, label, runs, start, end, text, groups, named, context: { before, match, after } }` where `start` and `end`
  * are offsets into the field's text. Options: those of `compileSearch`, plus `notes` and `slideIndex` of
- * `collectSearchFields`. Matches that are empty (a regular expression that matches nothing) are skipped.
+ * `collectSearchFields`. Matches that are empty (a regular expression that matches nothing) are skipped, and so is a match that
+ * touches a variable token (`{{slide.number}}`): the token is not text, and replacing part of it would break or change the variable.
  */
 export function findMatches(presentation, query, options = {}) {
   const compiled = compileSearch(query, options);
@@ -217,11 +223,13 @@ export function findMatches(presentation, query, options = {}) {
     compiled.regex.lastIndex = 0;
     let found;
     let hit = false;
+    const tokens = item.text.includes("{{") ? [...item.text.matchAll(VARIABLE_TOKEN)].map((token) => [token.index, token.index + token[0].length]) : [];
     while ((found = compiled.regex.exec(item.text))) {
       if (found[0] === "") {
         compiled.regex.lastIndex += 1;
         continue;
       }
+      if (tokens.some(([from, to]) => found.index < to && found.index + found[0].length > from)) continue;
       if (result.matches.length >= MAX_MATCHES) {
         result.truncated = true;
         break outer;

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/index.d.ts

@@ -72,6 +72,7 @@ export interface EditorHistory { undo: EditorHistoryEntry[]; redo: EditorHistory
 
 export interface EditorSession {
   paginateSlide(slideIndex: number, options?: PaginationOptions & EditorDiagnosticOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
+  /** Composes the slide with `{{slide.number}}`, `{{slide.section}}` and `{{deck.slideCount}}` substituted for `options.slideNumber` and `options.slideCount` (default: its place in the open deck and the deck's slide count); the document keeps the tokens. */
   composeSlide(slideIndex: number, options?: ComposeSlideOptions & EditorDiagnosticOptions): SlideComposition;
   setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   readonly presentation: unknown;

package/dist/index.js

@@ -32,12 +32,14 @@ export {
 // theme, engine default), with the session's registered catalogs, so the editor measures and composes what the renderer draws
 // and the exporter writes. `options.fonts` is the renderer's fonts handle (its `textMeasurement` measures); `options.catalogs`
 // adds catalogs for this call; `options.onDiagnostic` hears each diagnostic (`unresolved-reference`);
-// any other option overrides the resolved one (`layout`, ...).
+// any other option overrides the resolved one (`layout`, ...). FA-31: `slide` is the slide to compose and draw, with `{{slide.number}}`,
+// `{{slide.section}}` and `{{deck.slideCount}}` substituted for `slideNumber` and `slideCount` (default: its place in the open deck and the
+// deck's length), the same numbers the options carry. Pagination takes the source slide instead and substitutes while it measures.
 function slideContext(presentation, slideIndex, catalogs, { fonts, catalogs: _extra, onDiagnostic, ...overrides } = {}) {
   if (!Number.isInteger(slideIndex) || !presentation.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
-  const { options, diagnostics } = resolveSlideContext(presentation, slideIndex, { fonts, catalogs });
+  const { slide, options, diagnostics } = resolveSlideContext(presentation, slideIndex, { fonts, catalogs, slideNumber: overrides.slideNumber, slideCount: overrides.slideCount });
   for (const diagnostic of diagnostics) onDiagnostic?.(diagnostic);
-  return { ...options, ...overrides };
+  return { slide, options: { ...options, ...overrides } };
 }
 
 export const packageName = "@openpresentation/opf-editor";
@@ -276,12 +278,13 @@ export function createEditorSession(input, options = {}) {
       });
     },
     composeSlide(slideIndex, options = {}) {
-      return composeSlide(presentation.slides?.[slideIndex], slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options));
+      const { slide, options: resolved } = slideContext(presentation, slideIndex, mergeCatalogs(catalogs, options.catalogs), options);
+      return composeSlide(slide, resolved);
     },
     paginateSlide(slideIndex, options = {}, meta = {}) {
       const list = mergeCatalogs(catalogs, options.catalogs);
       // Core pagination reads the measurement from `fonts`, so the resolved context hands it over that way.
-      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options);
+      const { textMeasurement, ...resolved } = slideContext(presentation, slideIndex, list, options).options;
       const pagination = paginateSlide(presentation.slides[slideIndex], {
         ...resolved,
         catalogs: list,