@openpresentation/opf-render 0.17.1 → 0.18.0

package/dist/svg.d.ts

@@ -1,5 +1,6 @@
 import type { RenderFonts, ScriptFonts } from "./fonts.js";
-import type { Catalog, Finding, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
+import type { Catalog, Finding, SlideSelection, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
+export type { SlideSelection } from "@openpresentation/opf";
 import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
@@ -49,8 +50,8 @@ export type RenderDiagnostic = LayoutDiagnostic | {
   placeholder: "label" | "icon";
 };
 
-export interface RenderSvgOptions {
-  /** Leave out slides marked `hidden: true`, as the player does. Default false: one SVG per slide. With true the result holds only the visible slides, in order, so an index no longer names the slide at that index. Read by the deck-level `renderSvg`; `renderSlideSvg` draws the slide it is given. */
+export interface ToSvgOptions {
+  /** Leave out slides marked `hidden: true` when drawing the whole deck, as the player does. Default false: one SVG per slide. A slide number or selection draws exactly the slides it names. */
   skipHidden?: boolean;
   /**
    * The fonts the deck is laid out and drawn with: the handle `loadFonts()` returns (from `@openpresentation/opf-render/fonts-node` or
@@ -58,10 +59,12 @@ export interface RenderSvgOptions {
    * core's portable width estimate and the SVG names the design fonts without embedding them.
    */
   fonts?: RenderFonts;
-  /** `false` writes no `@font-face` data into the SVG (RR-61): the fonts handle still measures and the SVG still names the families, for a host whose page already has the faces (a browser `loadFonts` handle adds them to the document). Default true: each SVG embeds the faces of `fonts.embeddedFonts` its own text draws. */
-  embedFonts?: boolean;
   /**
-   * `true` draws every `<text>` as glyph outlines (RR-64): `<use>` of outlines kept once per slide in `<defs>`, so the SVG needs
+   * How the SVG draws text (RR-74). `"fonts"` (default): each SVG embeds, as `@font-face` data, the faces of `fonts.embeddedFonts` its
+   * own text draws (RR-61). `"system"`: no `@font-face` data; the fonts handle still measures and the SVG still names the families,
+   * for a host whose page already has the faces (a browser `loadFonts` handle adds them to the document).
+   *
+   * `"paths"`: every `<text>` drawn as glyph outlines (RR-64): `<use>` of outlines kept once per slide in `<defs>`, so the SVG needs
    * no font and looks the same in every viewer (about 40 KB a slide over the core example decks, against 0.5 to 4 MB of embedded
    * faces). Needs the fonts handle `loadFonts()` returns (`text-as-paths-needs-fonts` otherwise). The text is no longer text: it
    * cannot be edited in place. The glyphs are shaped by HarfBuzz (the browser's shaper; the Node handle always, a browser handle
@@ -70,9 +73,9 @@ export interface RenderSvgOptions {
    * A run stays text, reported as `text-as-paths-fallback` with a `reason`, when its font is a colour or bitmap font
    * (`"colour-font"`), its face's fsType restricts embedding (`"restricted"`), or it has no pinned width and HarfBuzz and the
    * layout's measurement disagree on it (`"shaping"`). Use it for thumbnails, previews and portable SVG files, not for an editing
-   * surface or the vector PDF (which keeps real text from `<text>` SVG). Default false.
+   * surface or the vector PDF (which keeps real text from `<text>` SVG).
    */
-  textAsPaths?: boolean;
+  text?: "fonts" | "system" | "paths";
   /**
    * `false` embeds whole faces (RR-65). By default, with a fonts handle that carries `subsets` (the Node `loadFonts` handle, a browser
    * handle given `subsetWasm`), each face an SVG embeds is cut to the characters the slide draws, keeping every layout feature, so the
@@ -119,20 +122,8 @@ export interface RenderSvgOptions {
   strictReferences?: boolean;
 }
 
-export interface SvgToPngOptions {
-  /** The fonts the conversion draws with (Node): see `SvgToPngOptions` in the main entry. */
-  fonts?: RenderFonts;
-  scale?: number;
-  background?: string;
-  dpi?: number;
-  /** Extra directories of font files to draw with. */
-  fontDirs?: string[];
-  defaultFontFamily?: string;
-  sansSerifFamily?: string;
-  monospaceFamily?: string;
-}
-
-export interface SvgToPdfOptions extends SvgToPngOptions {}
+/** The Node conversion options (types only: `toPng` and `toPdf` run in Node, or from `/export-browser`). */
+export type { ToPngOptions, ToPdfOptions } from "./index.js";
 
 export interface ResolvedPresentation {
   presentation: unknown;
@@ -185,12 +176,16 @@ export declare class OPFRenderError extends Error {
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 
-export declare function resolvePresentation(input: unknown, options?: RenderSvgOptions): ResolvedPresentation;
-
-/** The SVG of every slide of the deck, in order. */
-export declare function renderSvg(input: unknown, options?: RenderSvgOptions): string[];
-
-/** The SVG of one slide of the deck (`index` is zero-based; out of range throws `slide-index-out-of-range`). */
-export declare function renderSlideSvg(input: unknown, index: number, options?: RenderSvgOptions): string;
+export declare function resolvePresentation(input: unknown, options?: ToSvgOptions): ResolvedPresentation;
 
+/** An SVG slide the renderer drew: its text, or its bytes. */
+export type SvgSlide = string | Uint8Array;
 
+/**
+ * The deck as SVG (RR-73). `toSvg(deck)`: every slide, in order (without the hidden ones under `skipHidden`). `toSvg(deck, 3)`: the
+ * third slide (slides count from 1; out of range throws `slide-out-of-range`). `toSvg(deck, "1-3")` or `toSvg(deck, [1, 3])`: the
+ * selected slides (a malformed selection throws `invalid-slide-selection`). The second argument may be the options instead.
+ */
+export declare function toSvg(input: unknown, options?: ToSvgOptions): string[];
+export declare function toSvg(input: unknown, slide: number, options?: ToSvgOptions): string;
+export declare function toSvg(input: unknown, slides: Exclude<SlideSelection, number>, options?: ToSvgOptions): string[];

package/dist/svg.js

@@ -24,6 +24,7 @@ import { isDatasetChart, isDatasetTable, renderCatalogChart } from "./charts.js"
 import { renderCaption, renderFootnotes } from "./annotations.js";
 import { drawnFaces } from "./drawn-faces.js";
 import { dataUrlFsType, embeddingAllowed } from "./font-fstype.js";
+import { rejectRenamedOptions, selectSlides } from "./slide-sources.js";
 
 export const packageName = "@openpresentation/opf-render";
 
@@ -640,22 +641,24 @@ function bindSlide(presentation, index, context) {
 }
 
 // `options.fonts` is the handle `loadFonts()` returns (or any object with a `textMeasurement` and, to embed faces in the SVG, an
-// `embeddedFonts` list). The renderer reads the two as plain options from here on. `embedFonts: false` (RR-61) keeps the
-// measurement and drops the faces, for a host whose page already holds them.
-// `textAsPaths: true` (RR-64) draws text as glyph outlines with the handle's `outlines` engine (a `loadFonts` handle carries one).
-// `subsetFonts: false` (RR-65) embeds whole faces; by default a handle with a subset engine (`fonts.subsets`) cuts each embedded
-// face to the characters the slide draws.
+// `embeddedFonts` list). The renderer reads the two as plain options from here on. `text` (RR-74) says how the SVG draws text:
+// `"fonts"` (default) embeds the faces the slide draws, cut to its glyphs when the handle carries `subsets` (RR-61, RR-65);
+// `"system"` embeds no face and names the families, for a host whose page already holds them; `"paths"` draws glyph outlines with
+// the handle's `outlines` engine, so the SVG needs no font (RR-64). `subsetFonts: false` embeds whole faces.
+const TEXT_MODES = ["fonts", "system", "paths"];
 function normalizeOptions(options) {
-  const { fonts, embedFonts, textAsPaths, subsetFonts, ...rest } = options ?? {};
+  rejectRenamedOptions(options, "invalid-render-options");
+  const { fonts, text = "fonts", subsetFonts, ...rest } = options ?? {};
+  if (!TEXT_MODES.includes(text)) throw new OPFRenderError("invalid-render-options", 'text must be "fonts", "system" or "paths".', { option: "text", value: text });
   if (subsetFonts !== undefined && typeof subsetFonts !== "boolean") throw new OPFRenderError("invalid-render-options", "subsetFonts must be true or false.", { option: "subsetFonts" });
-  if (textAsPaths !== undefined && typeof textAsPaths !== "boolean") throw new OPFRenderError("invalid-render-options", "textAsPaths must be true or false.", { option: "textAsPaths" });
-  if (textAsPaths && typeof fonts?.outlines?.outlineSlideText !== "function") throw new OPFRenderError("text-as-paths-needs-fonts", "textAsPaths needs the fonts handle loadFonts() returns (from /fonts-node or /fonts-browser), passed as `fonts`.", { option: "textAsPaths" });
-  return { ...rest, textMeasurement: fonts?.textMeasurement, embeddedFonts: embedFonts === false ? undefined : fonts?.embeddedFonts, ...(textAsPaths ? { outlines: fonts.outlines } : {}), ...(subsetFonts !== false && fonts?.subsets ? { subsets: fonts.subsets } : {}) };
+  if (typeof fonts === "string" || Array.isArray(fonts)) throw new OPFRenderError("invalid-render-options", "Drawing a deck needs the fonts handle loadFonts() returns (from /fonts-node or /fonts-browser): it measures the text. Font folders are read by toPng and toPdf for SVG input.", { option: "fonts" });
+  if (text === "paths" && typeof fonts?.outlines?.outlineSlideText !== "function") throw new OPFRenderError("text-as-paths-needs-fonts", 'text: "paths" needs the fonts handle loadFonts() returns (from /fonts-node or /fonts-browser), passed as `fonts`.', { option: "text" });
+  return { ...rest, textMeasurement: fonts?.textMeasurement, embeddedFonts: text === "system" ? undefined : fonts?.embeddedFonts, ...(text === "paths" ? { outlines: fonts.outlines } : {}), ...(subsetFonts !== false && fonts?.subsets ? { subsets: fonts.subsets } : {}) };
 }
 
 /**
  * Resolve a presentation for drawing: template variables filled, the boundary check passed, and every slide bound to its
- * layout, design, script fonts and composed geometry. `renderSvg` and `renderSlideSvg` draw from this.
+ * layout, design, script fonts and composed geometry. `toSvg` draws from this.
  */
 export function resolvePresentation(input, options = {}) {
   return resolveDeck(input, normalizeOptions(options));
@@ -678,27 +681,24 @@ function resolveDeck(input, options) {
 }
 
 /**
- * The SVG of every slide of the deck, in order. `skipHidden: true` leaves out slides marked `hidden` (the sequence the player
- * presents); the result is then shorter than the deck, so an index no longer names the slide at that index.
+ * The deck as SVG (RR-73): `toSvg(deck)` gives every slide, in order, as an array; `toSvg(deck, 3)` the third slide as one string
+ * (slides count from 1); `toSvg(deck, "1-3")` (`"2,4"`, `"5-"`, the CLI's --slides syntax, or a list such as `[1, 3]`) the selected slides as an array. The
+ * second argument may be the options instead, told apart by type. `skipHidden: true` leaves slides marked `hidden` out of the
+ * whole deck (the sequence the player presents); a selection draws exactly the slides it names.
  */
-export function renderSvg(input, options = {}) {
-  const drawn = normalizeOptions(options);
+export function toSvg(input, slides, options) {
+  if (slides !== null && typeof slides === "object" && !Array.isArray(slides)) { options = slides; slides = undefined; }
+  const drawn = normalizeOptions(options ?? {});
   const resolved = resolveDeck(input, drawn);
-  const indexes = resolved.slides.map((_, index) => index).filter(index => !(options.skipHidden === true && resolved.presentation.slides[index]?.hidden === true));
-  return indexes.map(index => renderResolvedSlide(resolved, index, drawn));
-}
-
-/** The SVG of one slide of the deck (a zero-based index). */
-export function renderSlideSvg(input, index, options = {}) {
-  const drawn = normalizeOptions(options);
-  const resolved = resolveDeck(input, drawn);
-  if (!Number.isInteger(index) || index < 0 || index >= resolved.slides.length) {
-    throw new OPFRenderError("slide-index-out-of-range", `Slide index ${index} is out of range.`, {
-      slideIndex: index,
-      slideCount: resolved.slides.length
-    });
+  const count = resolved.slides.length;
+  if (typeof slides === "number") {
+    if (!Number.isInteger(slides) || slides < 1 || slides > count) throw new OPFRenderError("slide-out-of-range", `Slide ${slides} is not in the presentation, which has ${count} slide${count === 1 ? "" : "s"} (slides count from 1).`, { slide: slides, slideCount: count });
+    return renderResolvedSlide(resolved, slides - 1, drawn);
   }
-  return renderResolvedSlide(resolved, index, drawn);
+  const numbers = slides === undefined
+    ? resolved.slides.map((_, index) => index + 1).filter(number => !(options?.skipHidden === true && resolved.presentation.slides[number - 1]?.hidden === true))
+    : selectSlides(slides, count);
+  return numbers.map(number => renderResolvedSlide(resolved, number - 1, drawn));
 }
 
 function renderResolvedSlide(resolved, slideIndex, options) {
@@ -1697,12 +1697,27 @@ function renderBranding(bound,presentation,width,height,options) {
     // The group keeps its bare opacity attribute (opf-pptx's watermark parity test reads it); the picture itself is hidden.
     pieces.push(tag('g',{opacity:typeof design.watermark==='object'?design.watermark.opacity??.08:.08},renderImage({value:design.watermark,path:rootFor('watermark')},{x:width*.3,y:height*.3,width:width*.4,height:height*.4},bound,{...options,imageFit:'contain',imageDecorative:true})));
   }
-  // Cover and section slides: the deck logo core composed at the top-left of the free area, anchored left.
+  // Cover and section slides: the logo core composed (the primary organization's full logo, or the design.logo override, in the
+  // variant for this slide's background) at the top-left of the free area, anchored left. RR-71: the picture is named by its
+  // asset's alt text, else by the organization it belongs to ("Acme Corp logo"); an unnamed organization still says "Logo".
   const logo=bound.geometry.logo;
-  if(logo)pieces.push(renderImage({value:logo.source,path:logo.path},logo.box,bound,{...options,imageAnchor:logo.anchor??'left',imageLabel:'Logo',imageGenerated:true}));
+  if(logo)pieces.push(renderImage({value:logo.source,path:logo.path},logo.box,bound,{...options,imageAnchor:logo.anchor??'left',imageLabel:logoLabel(presentation,logo.path),imageGenerated:true}));
   return pieces.join('');
 }
 
+// The organization a logo path (`organization.logo.full`, `organization.1.logo.icon.onDark`) belongs to: the record at the index the path
+// names, else the single organization object.
+function logoOrganization(presentation,path){
+  const match=/^organization(?:\.(\d+))?\.logo(?:\.|$)/.exec(path??'');
+  if(!match)return undefined;
+  const organization=presentation?.organization;
+  return Array.isArray(organization)?organization[Number(match[1])]:match[1]===undefined?organization:undefined;
+}
+function logoLabel(presentation,path){
+  const name=logoOrganization(presentation,path)?.name;
+  return typeof name==='string'&&name.trim()?`${name.trim()} logo`:'Logo';
+}
+
 // A family name is written unquoted only when it is a valid sequence of CSS identifiers; a word that starts with a digit
 // ("Source Sans 3", "Noto Sans Symbols 2") or any other non-identifier character makes an unquoted name invalid CSS, which
 // drops the whole font-family in a browser (FF-45). Such names are single-quoted (the attribute is double-quoted).

package/dist/text-paths.js

@@ -1,4 +1,4 @@
-// RR-64: `textAsPaths: true` draws every <text> of a slide as glyph outlines, so the SVG needs no font. The renderer has
+// RR-64: `text: "paths"` draws every <text> of a slide as glyph outlines, so the SVG needs no font. The renderer has
 // already decided every line, position and width (x, y, text-anchor, textLength); the vector PDF export's SVG text layout
 // (layoutText: text chunks, bidirectional runs, per-character fallback, fontkit shaping, textLength) turns that into positioned
 // glyph runs, and this module writes each glyph as a <use> of its outline. Outlines are kept once per slide in <defs>, in font
@@ -316,14 +316,14 @@ function precise(value) { return String(Number(Number(value).toPrecision(6))); }
 
 
 /**
- * The outline engine a fonts handle carries as `outlines` (RR-64): `renderSvg(deck, { fonts, textAsPaths: true })` draws each
+ * The outline engine a fonts handle carries as `outlines` (RR-64): `toSvg(deck, { fonts, text: "paths" })` draws each
  * slide's text with it. The faces are read from the handle when a slide is outlined, so faces it loads later are used too.
  */
 export function textOutlines(fonts) {
   return Object.freeze({
     outlineSlideText: (content, options) => {
       const library = outlineLibrary(fonts);
-      if (!library) throw options.fail("text-as-paths-needs-fonts", "textAsPaths needs font faces to outline: pass the handle loadFonts() returns as `fonts`.");
+      if (!library) throw options.fail("text-as-paths-needs-fonts", 'text: "paths" needs font faces to outline: pass the handle loadFonts() returns as `fonts`.');
       return outlineSlideText(content, { ...options, library, shaper: fonts.shaper });
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-render",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Deterministic local OPF renderer for SVG, PNG, and PDF output.",
   "license": "MIT",
   "type": "module",
@@ -139,7 +139,7 @@
     "test:preview-a11y-browser": "node test/preview-a11y-browser.mjs"
   },
   "dependencies": {
-    "@openpresentation/opf": "^0.17.0",
+    "@openpresentation/opf": "^0.18.1",
     "bidi-js": "1.1.0",
     "fontkit": "^2.0.4",
     "harfbuzzjs": "1.6.2",