@polotno/pdf-export 0.1.42 → 0.2.0

package/README.md

@@ -1,46 +1,63 @@
 # Polotno to Vector PDF
 
-Convert polotno JSON into vector PDF file from NodeJS with optional PDF/X-1a print-ready export.
+Convert Polotno JSON into a vector PDF, in **Node.js** or directly in the **browser**. Optional PDF/X-1a print-ready export (Node only).
 
 ```bash
 npm install @polotno/pdf-export
 ```
 
-## Basic Usage
+## Node usage
 
 ```js
-import fs from 'fs';
+import fs from 'node:fs';
 import { jsonToPDF } from '@polotno/pdf-export';
 
-async function run() {
-  const json = JSON.parse(fs.readFileSync('./polotno.json'));
+const json = JSON.parse(fs.readFileSync('./polotno.json', 'utf8'));
+await jsonToPDF(json, './output.pdf');
+```
 
-  // Standard PDF export
-  await jsonToPDF(json, './output.pdf');
-}
+`jsonToPDFBytes(json, attrs)` is also exported on the Node entry — useful when you want raw bytes (to upload, attach, etc.) without writing to disk.
 
-run();
+## Browser usage
+
+```js
+import { jsonToPDFBlob } from '@polotno/pdf-export/browser';
+
+async function exportToPDF(store) {
+  const blob = await jsonToPDFBlob(store.toJSON());
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'design.pdf';
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
 ```
 
-## PDF/X-1a Print-Ready Export
+Also exported: `jsonToPDFBytes(json, attrs): Promise<Uint8Array>` — for cases where you want raw bytes (to push to IndexedDB, send via WebTransport, share via `navigator.share`, etc.).
+
+The browser entry **does not** support `attrs.pdfx1a` / `attrs.validate` — those rely on Ghostscript, which has no browser-side equivalent. Pass them and you'll get a clear runtime error pointing at the Node entry.
+
+### CORS
+
+When polotno designs reference remote images, fonts, or SVG sources, the browser fetches those assets at export time. They must be reachable with CORS:
 
-For professional printing, use the PDF/X-1a option which ensures:
+- **Google Fonts** (`fonts.googleapis.com` and `fonts.gstatic.com`) work out of the box.
+- **Custom asset URLs** must be served with `Access-Control-Allow-Origin: *` (or your origin), or pre-fetched and passed as `data:` URLs in the JSON.
 
-- CMYK color space conversion
-- Transparency flattening
-- Font embedding/outlining
-- Print industry compliance
+## PDF/X-1a print-ready export (Node only)
+
+For professional printing:
 
 ```js
-// PDF/X-1a export
-await jsonToPDF(json, './print-ready.pdf', {
-  pdfx1a: true,
-});
+await jsonToPDF(json, './print-ready.pdf', { pdfx1a: true });
 
-// PDF/X-1a with custom metadata
+// With custom metadata and validation
 await jsonToPDF(json, './book-cover.pdf', {
   pdfx1a: true,
-  validate: true, // Optional validation
+  validate: true,
   metadata: {
     title: 'My Book Cover',
     author: 'Author Name',
@@ -49,20 +66,25 @@ await jsonToPDF(json, './book-cover.pdf', {
 });
 ```
 
-## Spot Color / Foil Support
+**Requires Ghostscript:**
+
+- macOS: `brew install ghostscript`
+- Ubuntu: `apt-get install ghostscript`
+- Windows: download from [ghostscript.com](https://www.ghostscript.com/)
+
+## Spot color / foil support
 
-For professional printing with special inks like metallic foils, Pantone colors, or other spot colors:
+For professional printing with special inks like metallic foils or Pantone colors:
 
 ```js
 await jsonToPDF(json, './output.pdf', {
   pdfx1a: true,
   spotColors: {
-    // Map any color to a spot color
     'rgba(255,215,0,1)': {
       name: 'Gold Foil',
-      pantoneCode: 'Pantone 871 C', // Optional reference
-      cmyk: [0, 0.15, 0.5, 0], // CMYK fallback (0-1 range)
-      overprint: true, // Recommended for foils — see below
+      pantoneCode: 'Pantone 871 C', // optional reference
+      cmyk: [0, 0.15, 0.5, 0],      // CMYK fallback (0–1 range)
+      overprint: true,              // recommended for foils — see below
     },
     '#C0C0C0': {
       name: 'Silver Foil',
@@ -73,44 +95,24 @@ await jsonToPDF(json, './output.pdf', {
 });
 ```
 
-**How it works:**
+Any element with a matching fill or stroke color is automatically converted. Color matching is flexible — `'#FFD700'`, `'#ffd700'`, `'rgb(255,215,0)'`, and `'rgba(255,215,0,1)'` all match. CMYK fallback values are used by viewers that don't support spot colors.
 
-- Any element with a matching fill or stroke color is automatically converted to use the spot color
-- Colors are matched flexibly — `'#FFD700'`, `'#ffd700'`, and `'rgba(255,215,0,1)'` all match
-- Spot colors are preserved as Separation color spaces in both standard and PDF/X-1a output
-- CMYK fallback values are used when viewers don't support spot colors
-- Supported on text, lines, figures (rect, circle, star, blobs, and other subTypes), and SVG elements
-
-**Color Format Support:**
-
-- Hex: `'#FFD700'` or `'#ffd700'`
-- RGB: `'rgb(255,215,0)'`
-- RGBA: `'rgba(255,215,0,1)'`
+Supported on text, lines, figures, and SVG elements.
 
 ### Overprint
 
-`overprint: true` emits the PDF graphics state `/OP true /op true /OPM 1` whenever the spot color is painted. This tells the press to **add** the spot ink on top of any underlying CMYK rather than knocking it out:
-
-- **Without overprint** (default): the spot region knocks out CMYK underneath. If the foil die is misaligned by even a fraction of a millimetre, you get a visible white halo at the edge.
-- **With overprint**: CMYK prints continuously through the spot region; the foil is stamped over it. No halo at edges, and the underlying artwork stays intact.
-
-Overprint is the standard choice for foil stamps and varnishes. Acrobat's *Output Preview → Simulate Overprinting* shows how the press will composite the layers.
-
-**Tips:**
+`overprint: true` emits the PDF graphics state `/OP true /op true /OPM 1` whenever the spot color is painted, telling the press to **add** the spot ink on top of any underlying CMYK rather than knocking it out:
 
-- Use professional color references (like Pantone codes) to communicate exact requirements to printers
-- Provide accurate CMYK fallback values for preview and proof prints — values closer to the real ink (e.g. `[0, 0, 0, 0.4]` for silver) make digital proofs more representative
-- Verify spot colors in Adobe Acrobat Pro: **Tools → Print Production → Output Preview → Separations**
+- **Without overprint** (default): the spot region knocks out CMYK underneath. A misaligned foil die produces a visible white halo at the edge.
+- **With overprint**: CMYK prints continuously through the spot region; the foil is stamped over it. No halo, underlying artwork stays intact.
 
-**Caveats:**
+Acrobat's *Output Preview → Simulate Overprinting* shows how the press will composite the layers. Verify spot colors in **Tools → Print Production → Output Preview → Separations**.
 
-- Spot color preservation through PDF/X-1a relies on Ghostscript not flattening transparency in the spot region. Plain figures, lines, text, and simple SVGs all work. SVGs that internally use `<clipPath>` or `<mask>` may have their spot color flattened to CMYK during pdfx1a conversion (a Ghostscript limitation around transparency groups). For foil regions, prefer plain shapes or simple SVG paths over masked artwork.
+For foil regions, prefer plain shapes or simple SVG paths — SVGs that internally use `<clipPath>` or `<mask>` may have their spot color flattened to CMYK during PDF/X-1a conversion.
 
-## Bleed and Crop Marks (print-ready output)
+## Bleed and crop marks
 
-For print production you usually want extra paper around the trim edge so
-that ink covers the cut line, plus crop marks indicating where the print
-shop should trim:
+For print production you usually want extra paper around the trim edge so that ink covers the cut line, plus crop marks for the print shop:
 
 ```js
 await jsonToPDF(json, './print-ready.pdf', {
@@ -120,78 +122,40 @@ await jsonToPDF(json, './print-ready.pdf', {
 });
 ```
 
-**Source data** — set `bleed` in pixels on each page in the JSON:
+Set `bleed` in pixels on each page in the JSON:
 
 ```js
-{
-  width: 1080,
-  height: 1080,
-  pages: [{ background: '...', bleed: 36, children: [...] }]
-}
+{ width: 1080, height: 1080, pages: [{ background: '...', bleed: 36, children: [...] }] }
 ```
 
-**Page-box metadata.** When `includeBleed` or `cropMarkSize` is set the
-generated PDF has correct PDF/X page boxes:
-
-- `MediaBox` — full sheet (trim + bleed + crop-mark margin)
-- `BleedBox` — trim + bleed (where ink may cover)
-- `TrimBox` — final cut size
-- `ArtBox` — same as `TrimBox`
+Element coordinates stay **relative to the trim corner** — `(0, 0)` still lands at the top-left of the trim. Backgrounds automatically extend into the bleed strip.
 
-`TrimBox ⊆ BleedBox ⊆ MediaBox` per PDF/X spec, which lets RIPs and proofers
-identify the live area and the bleed strip without guessing.
+The output PDF gets correct PDF/X page boxes (`MediaBox` ⊇ `BleedBox` ⊇ `TrimBox` = `ArtBox`) so RIPs and proofers can identify the live area without guessing.
 
-**How content is positioned.** Element coordinates in the JSON stay
-**relative to the trim corner** — the renderer translates origin so a
-`(0, 0)` element still lands at the top-left of the trim. Backgrounds
-automatically extend into the bleed strip; the crop-mark margin remains
-unprinted.
+Works on both Node and browser entries — no Ghostscript required if you skip `pdfx1a`.
 
-## DPI Handling
+## DPI handling
 
-The library automatically handles DPI conversion to ensure correct physical dimensions in the output PDF. By default, it uses the `dpi` value from your JSON file (or 72 DPI if not specified).
+The library converts pixel coordinates to PDF points using the `dpi` value from your JSON (default 72):
 
 ```js
-// JSON with dpi specified
-const json = {
-  width: 1920,
-  height: 1080,
-  dpi: 300, // 300 DPI input
-  // ... rest of JSON
-};
-
-// Use JSON dpi automatically
+const json = { width: 1920, height: 1080, dpi: 300, /* ... */ };
+
+// Uses JSON dpi automatically
 await jsonToPDF(json, './output.pdf');
 
-// Override DPI via attrs (takes precedence over JSON dpi)
-await jsonToPDF(json, './output.pdf', {
-  dpi: 150, // Override to 150 DPI
-});
+// Or override
+await jsonToPDF(json, './output.pdf', { dpi: 150 });
 ```
 
-**How it works:**
-
-- Input JSON coordinates are in **pixels** at the specified DPI
-- PDF uses **points** (1 point = 1/72 inch)
-- The library converts: `points = pixels × (72 / dpi)`
-- This ensures the PDF has correct physical dimensions for printing
-- All element positions, sizes, and coordinates are automatically scaled
-
-**Example:**
-
-- A 1920×1080 pixel canvas at 300 DPI = 6.4" × 3.6" in the PDF
-- The same canvas at 72 DPI = 26.67" × 15" in the PDF
-
-## Requirements
-
-- **GhostScript** must be installed for PDF/X-1a conversion
-- macOS: `brew install ghostscript`
-- Ubuntu: `apt-get install ghostscript`
-- Windows: Download from [ghostscript.com](https://www.ghostscript.com/)
+A 1920×1080 canvas at 300 DPI is 6.4″ × 3.6″ in the PDF; at 72 DPI it's 26.67″ × 15″.
 
 ## Development
 
 ```bash
-npm run build  # Build the library
-npm test       # Run tests
+npm install            # postinstall applies patches/ to node_modules
+npm run build          # builds the Node and browser bundles
+npm test               # Node-side fixture tests
+npm run test:browser   # real-Chromium smoke suite (Vitest browser mode)
+npm run dev            # demo Polotno editor for manual export testing
 ```

package/lib/browser.d.ts

@@ -0,0 +1,102 @@
+interface SpotColorDefinition {
+    name?: string;
+    cmyk?: number[];
+    /**
+     * If true, the spot color is painted with overprint enabled
+     * (PDF graphics state /OP true /op true /OPM 1). This prevents
+     * underlying inks from being knocked out, so the spot ink mixes
+     * with the colors beneath it on press. Typically used for
+     * varnishes, foils and Pantone overlays.
+     */
+    overprint?: boolean;
+}
+interface SpotColorConfig {
+    [color: string]: SpotColorDefinition;
+}
+
+/**
+ * One CSS @font-face style variant for a custom font. Mirrors Polotno's
+ * `FontStyleVariant` (`node_modules/polotno/model/schema.d.ts`): `src` is
+ * the CSS-style source string (e.g. `url("https://example.com/foo.woff2")`),
+ * and `fontStyle`/`fontWeight` qualify which (style, weight) the variant
+ * is for. Missing means normal/400.
+ */
+interface FontStyleVariant {
+    src: string;
+    fontStyle?: string;
+    fontWeight?: string;
+}
+/**
+ * Custom font definition. Three valid shapes (matching polotno):
+ *   1. `{ fontFamily }` alone → fetched from Google Fonts per variant
+ *   2. `{ fontFamily, url }` → one URL applied to all variants (regular
+ *      file used for bold/italic; not ideal but matches polotno fallback)
+ *   3. `{ fontFamily, styles: [...] }` → per-variant URLs (preferred)
+ */
+interface FontDefinition {
+    fontFamily: string;
+    url?: string;
+    styles?: FontStyleVariant[];
+}
+interface PolotnoJSON {
+    width: number;
+    height: number;
+    fonts: FontDefinition[];
+    pages: Array<{
+        background?: string;
+        children: any[];
+    }>;
+    dpi?: number;
+}
+interface RenderAttrs {
+    pdfx1a?: boolean;
+    validate?: boolean;
+    metadata?: {
+        title?: string;
+        author?: string;
+        application?: string;
+        producer?: string;
+    };
+    spotColors?: SpotColorConfig;
+    /**
+     * @deprecated No-op. Text always shrinks to fit `element.height` and
+     * `verticalAlign` is always honored — both are properties of the polotno
+     * element model, not render-time options. This field is kept for
+     * backwards compatibility with callers that used to pass it.
+     */
+    textVerticalResizeEnabled?: boolean;
+    dpi?: number;
+    /**
+     * When true, expand each page's PDF dimensions to include the per-page
+     * `bleed` value (read from `page.bleed` in the JSON, in pixels). Background
+     * and content drawn outside the trim area are preserved into the bleed
+     * strip — exactly matching what print shops expect.
+     */
+    includeBleed?: boolean;
+    /**
+     * Reserve `cropMarkSize` pixels of additional margin around each page and
+     * draw 8 corner crop marks at the trim line (matching polotno's bitmap
+     * PDF export). 0 (default) = no crop marks. Independent of `includeBleed`
+     * — a print-ready PDF typically wants both.
+     */
+    cropMarkSize?: number;
+}
+/**
+ * Render `json` and return the resulting PDF as raw bytes. Works on both
+ * Node and browser (the browser entry re-exports this with the browser
+ * platform shim swapped in by the bundler). PDF/X-1a is rejected — that
+ * conversion needs Ghostscript and a real file path.
+ */
+declare function jsonToPDFBytes(json: PolotnoJSON, attrs?: RenderAttrs): Promise<Uint8Array>;
+
+/**
+ * Render `json` into a PDF and return it as a `Blob` ready for download
+ * (`URL.createObjectURL`), upload, or `navigator.share`.
+ *
+ * The `Blob`'s MIME type is `application/pdf`. PDF/X-1a (`attrs.pdfx1a`)
+ * is unsupported in browsers — pass it and you'll get a clear runtime
+ * error pointing you at the Node entry.
+ */
+declare function jsonToPDFBlob(json: PolotnoJSON, attrs?: RenderAttrs): Promise<Blob>;
+
+export { type FontDefinition, type FontStyleVariant, type PolotnoJSON, type RenderAttrs, type SpotColorConfig, jsonToPDFBlob, jsonToPDFBytes };