@openpresentation/opf-render 0.11.8 → 0.12.0

package/dist/pdf-writer.js

@@ -0,0 +1,154 @@
+import pako from "pako";
+import { sha256Bytes } from "./sha256.js";
+
+// A small PDF object writer for the vector export (RR-12). Everything it emits is a pure function of the objects
+// added to it: objects are numbered in the order they are added, written in number order, compressed with pako
+// (pure JavaScript, so the bytes do not depend on the platform's zlib build), and the file identifier is a hash
+// of the content. There is no clock, no random data and no locale-dependent formatting.
+
+const encoder = new TextEncoder();
+
+/** A coordinate or other real number: at most `digits` decimals, no exponent, no negative zero. */
+export function num(value, digits = 3) {
+  if (!Number.isFinite(value)) return "0";
+  // PDF readers keep reals in single precision and some reject exponents: clamp absurd coordinates to a sane range.
+  if (Math.abs(value) > 1e9) value = Math.sign(value) * 1e9;
+  const scale = 10 ** digits;
+  let rounded = Math.round(value * scale) / scale;
+  if (Object.is(rounded, -0)) rounded = 0;
+  let text = String(rounded);
+  if (/e/i.test(text)) text = rounded.toFixed(digits).replace(/\.?0+$/, "") || "0";
+  return text;
+}
+
+/** PDF name object (`/Name`), escaping every byte outside the regular printable range. */
+export function name(value) {
+  let out = "/";
+  for (const byte of encoder.encode(String(value))) {
+    out += byte < 0x21 || byte > 0x7e || "#()<>[]{}/%".includes(String.fromCharCode(byte))
+      ? "#" + byte.toString(16).toUpperCase().padStart(2, "0")
+      : String.fromCharCode(byte);
+  }
+  return out;
+}
+
+/** A PDF text string: PDFDocEncoding-safe ASCII as a literal string, everything else as UTF-16BE with a byte order mark. */
+export function textString(value) {
+  const text = String(value);
+  if (/^[\x20-\x7e]*$/.test(text)) return "(" + text.replace(/[\\()]/g, "\\$&") + ")";
+  let hex = "FEFF";
+  for (let index = 0; index < text.length; index++) hex += text.charCodeAt(index).toString(16).toUpperCase().padStart(4, "0");
+  return "<" + hex + ">";
+}
+
+/** A 7-bit ASCII literal string (URIs); non-ASCII must already be percent-encoded. */
+export function asciiString(value) {
+  return "(" + String(value).replace(/[\\()]/g, "\\$&").replace(/[\r\n]/g, " ") + ")";
+}
+
+export function hex(bytes) {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).toUpperCase().padStart(2, "0");
+  return out;
+}
+
+export function utf16Hex(text) {
+  let out = "";
+  for (let index = 0; index < text.length; index++) out += text.charCodeAt(index).toString(16).toUpperCase().padStart(4, "0");
+  return out;
+}
+
+export function ref(number) {
+  return `${number} 0 R`;
+}
+
+export function flate(bytes) {
+  return pako.deflate(bytes, { level: 9 });
+}
+
+export function sha256(bytes) {
+  return sha256Bytes(bytes);
+}
+
+export class PdfFile {
+  constructor({ compress = true } = {}) {
+    this.compress = compress;
+    this.objects = [];
+  }
+
+  /** Reserve an object number to fill later (forward references). */
+  reserve() {
+    this.objects.push(null);
+    return this.objects.length;
+  }
+
+  /** Fill a reserved object. `dict` is the dictionary body without delimiters; `stream` makes it a stream object. */
+  set(number, dict, stream) {
+    this.objects[number - 1] = { dict, stream };
+  }
+
+  add(dict, stream) {
+    const number = this.reserve();
+    this.set(number, dict, stream);
+    return number;
+  }
+
+  /** A stream object, Flate-compressed unless the file was created uncompressed or `raw` is set. */
+  addStream(dict, bytes, { raw = false } = {}) {
+    const data = typeof bytes === "string" ? encoder.encode(bytes) : bytes;
+    if (this.compress && !raw && data.length > 32) {
+      return this.add(`${dict}/Filter/FlateDecode`, flate(data));
+    }
+    return this.add(dict, data);
+  }
+
+  /** The complete file. `catalog`, `info` are object numbers. */
+  serialize({ catalog, info }) {
+    const chunks = [];
+    let offset = 0;
+    const push = (data) => {
+      const bytes = typeof data === "string" ? latin1(data) : data;
+      chunks.push(bytes);
+      offset += bytes.length;
+    };
+    push("%PDF-1.7\n%\xE2\xE3\xCF\xD3\n");
+    const offsets = [];
+    for (let index = 0; index < this.objects.length; index++) {
+      const object = this.objects[index];
+      if (!object) throw new Error(`PDF object ${index + 1} was reserved but never filled.`);
+      offsets.push(offset);
+      if (object.stream) {
+        push(`${index + 1} 0 obj\n<<${object.dict}/Length ${object.stream.length}>>\nstream\n`);
+        push(object.stream);
+        push("\nendstream\nendobj\n");
+      } else {
+        push(`${index + 1} 0 obj\n<<${object.dict}>>\nendobj\n`);
+      }
+    }
+    const startxref = offset;
+    let table = `xref\n0 ${this.objects.length + 1}\n0000000000 65535 f \n`;
+    for (const position of offsets) table += String(position).padStart(10, "0") + " 00000 n \n";
+    push(table);
+    // The identifier is a hash of everything before the trailer: identical input, identical file.
+    const digest = hex(sha256(concat(chunks)).subarray(0, 16));
+    push(`trailer\n<</Size ${this.objects.length + 1}/Root ${ref(catalog)}${info ? `/Info ${ref(info)}` : ""}/ID[<${digest}><${digest}>]>>\nstartxref\n${startxref}\n%%EOF\n`);
+    return concat(chunks);
+  }
+}
+
+function latin1(text) {
+  const bytes = new Uint8Array(text.length);
+  for (let index = 0; index < text.length; index++) bytes[index] = text.charCodeAt(index) & 0xff;
+  return bytes;
+}
+
+export function concat(chunks) {
+  let length = 0;
+  for (const chunk of chunks) length += chunk.length;
+  const out = new Uint8Array(length);
+  let position = 0;
+  for (const chunk of chunks) { out.set(chunk, position); position += chunk.length; }
+  return out;
+}
+
+export { encoder as utf8Encoder };

package/dist/pdf-xml.js

@@ -0,0 +1,78 @@
+// A minimal, dependency-free XML reader for the SVG the renderer (and other SVG producers) emit. It builds
+// {name, attrs, children, parent} elements and {text} nodes, decodes the predefined and numeric entities, keeps
+// CDATA as text, and ignores comments, processing instructions and the DOCTYPE. It does not validate.
+
+const TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<\?[\s\S]*?\?>|<!DOCTYPE(?:[^>[]|\[[\s\S]*?\])*>|<(\/?)([A-Za-z_][\w:.-]*)((?:"[^"]*"|'[^']*'|[^'">])*?)(\/?)>|[^<]+|</g;
+const ATTRIBUTE = /([^\s=/>"']+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const MAX_DEPTH = 1000;
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+export function decodeEntities(text) {
+  if (!text.includes("&")) return text;
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, code) => {
+    if (code[0] === "#") {
+      const point = code[1].toLowerCase() === "x" ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10);
+      return Number.isInteger(point) && point >= 0 && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff) ? String.fromCodePoint(point) : match;
+    }
+    return ENTITIES[code] ?? match;
+  });
+}
+
+export function parseXml(source) {
+  const root = { name: "#document", attrs: {}, children: [], parent: null };
+  let current = root;
+  let depth = 0;
+  for (const match of source.matchAll(TOKEN)) {
+    const [token, cdata, closing, tagName, attrText, selfClosing] = match;
+    if (tagName !== undefined) {
+      const local = tagName.includes(":") ? tagName.slice(tagName.indexOf(":") + 1) : tagName;
+      if (closing) {
+        // Tolerate stray end tags: close up to the nearest matching open element.
+        let node = current;
+        while (node && node.name !== local) node = node.parent;
+        if (node?.parent) { let up = current; while (up !== node) { up = up.parent; depth--; } depth--; current = node.parent; }
+        continue;
+      }
+      const attrs = {};
+      for (const attribute of attrText.matchAll(ATTRIBUTE)) attrs[attribute[1]] = decodeEntities(attribute[2] ?? attribute[3] ?? "");
+      const element = { name: local, attrs, children: [], parent: current };
+      current.children.push(element);
+      if (!selfClosing) {
+        current = element;
+        // Every walk over the tree is recursive: refuse trees deep enough to overflow the stack.
+        if (++depth > MAX_DEPTH) throw new RangeError(`SVG elements are nested more than ${MAX_DEPTH} deep.`);
+      }
+    } else if (cdata !== undefined) {
+      current.children.push({ text: cdata });
+    } else if (token[0] !== "<" || token === "<") {
+      current.children.push({ text: decodeEntities(token) });
+    }
+  }
+  return root.children.find((child) => child.name === "svg") ?? null;
+}
+
+export function isElement(node) {
+  return node && node.name !== undefined;
+}
+
+/** Serialize an element subtree back to XML (used to rasterize the few effects the PDF cannot draw as vectors). */
+export function serialize(node, keepAttribute = () => true) {
+  if (node.text !== undefined) return escapeText(node.text);
+  const attrs = Object.entries(node.attrs).filter(([key, value]) => keepAttribute(key, value, node)).map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`).join("");
+  if (!node.children.length) return `<${node.name}${attrs}/>`;
+  return `<${node.name}${attrs}>${node.children.map((child) => serialize(child, keepAttribute)).join("")}</${node.name}>`;
+}
+
+export function escapeText(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function escapeAttribute(value) {
+  return escapeText(value).replace(/"/g, "&quot;");
+}
+
+/** Text content of an element, concatenated in document order. */
+export function textContent(node) {
+  if (node.text !== undefined) return node.text;
+  return node.children.map(textContent).join("");
+}

package/dist/player.d.ts

@@ -0,0 +1,79 @@
+import type { BrowserFontRegistry } from "./fonts-browser.js";
+import type { RenderSvgOptions } from "./svg.js";
+
+/**
+ * Why a deck could not be loaded, drawn or presented. `code` is stable: `invalid-document`, `fetch-failed`, `fonts-unavailable`,
+ * `render-failed`, `no-slides`, `no-document`, `not-ready`, `no-dom`, `present-failed`, `load-failed`.
+ */
+export declare class DeckError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string, options?: { cause?: unknown });
+}
+
+/** The slide that is showing, in the sequence that plays (hidden slides are not counted). `notes` is plain text. */
+export interface PlayerSlideChange { slide: number; total: number; index: number; id?: string; title: string; notes: string; section?: string }
+
+export type BlankMode = "none" | "black" | "white";
+
+export interface PresentOptions {
+  /** The self-hosted font root URL (see `copyPreviewFonts`), or a browser font registry the page already has. Without it layout uses estimated widths and system fonts. */
+  fonts?: string | BrowserFontRegistry;
+  /** Extra `renderSvg` options (catalogs, imageResolver, date, ...). */
+  renderOptions?: Partial<RenderSvgOptions>;
+  /** 1-based slide to start on, in the sequence that plays. Default 1. */
+  startSlide?: number;
+  /** Play hidden slides too. Default false. */
+  includeHidden?: boolean;
+  /** Ask for full screen (needs a user gesture). Default true. */
+  fullscreen?: boolean;
+  /** Open the speaker view window too (needs a user gesture). */
+  presenterView?: boolean;
+  /** `"presenter"` makes this window the speaker view (for a second tab or window of your page). Default `"audience"`. */
+  role?: "audience" | "presenter";
+  /** BroadcastChannel name, or `false` for none. Default: derived from the deck, so windows of one deck (same origin) follow each other. */
+  channel?: string | false;
+  /** Where the player is mounted. Default `document.body`. */
+  container?: HTMLElement;
+  /** Where focus returns when the show ends. Default: the element focused when it started. */
+  returnFocus?: HTMLElement | null;
+  signal?: AbortSignal;
+  /** An injectable clock (milliseconds since the epoch) for the speaker view's timer and clock. */
+  now?: () => number;
+  /** A deck store shared with an `<opf-deck>` (advanced). */
+  store?: unknown;
+}
+
+/** A running slideshow. Events: `slidechange` (PlayerSlideChange), `blank` ({ mode }), `presenterview` ({ open }), `close` ({ slide, index }). */
+export declare class PlayerSession extends EventTarget {
+  /** The 1-based number of the showing slide. */
+  readonly slide: number;
+  readonly total: number;
+  readonly blankMode: BlankMode;
+  readonly closed: boolean;
+  readonly presenterViewOpen: boolean;
+  next(): boolean;
+  previous(): boolean;
+  first(): boolean;
+  last(): boolean;
+  goto(number: number): boolean;
+  blank(mode?: BlankMode): boolean;
+  toggleFullscreen(): void;
+  /** Open the speaker view window (from a user gesture). Returns the window, or null when the browser blocked it. */
+  openPresenterView(): Window | null;
+  closePresenterView(): void;
+  /** End the show: leave full screen, close the speaker view, restore focus. Safe to call twice. */
+  close(): void;
+  addEventListener(type: "slidechange", listener: (event: CustomEvent<PlayerSlideChange>) => void, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: "blank", listener: (event: CustomEvent<{ mode: BlankMode }>) => void, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: "presenterview", listener: (event: CustomEvent<{ open: boolean }>) => void, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: "close", listener: (event: CustomEvent<{ slide: number; index?: number }>) => void, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+
+/**
+ * Start a slideshow over the page. `source` is an OPF document (object or JSON text), the URL of one, or an `<opf-deck>`
+ * element. Keys: arrows, Page Up/Down, Space, Enter, N and P (next, previous), Home/End, a slide number then Enter, B and W
+ * (black and white screen), S (speaker view), F (full screen), Escape to leave. Hidden slides are skipped. Call it from a
+ * click or key handler: full screen and the speaker view need a user gesture.
+ */
+export declare function present(source: unknown, options?: PresentOptions): Promise<PlayerSession>;