@projektemacher/vivliostyle-batch-cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,6 +10,9 @@ It runs the [Vivliostyle viewer](https://www.npmjs.com/package/@vivliostyle/view
10
10
  - Preview documents in the browser
11
11
  - Render with the real browser engine, so canvas charts, WebGL scenes and cross-origin iframes end up in the PDF
12
12
  - Stay sharp past 96dpi: `--pixel-ratio` redraws JS-painted content at higher backing resolution
13
+ - Stamp PDF metadata — title, author, subject, keywords, language — into the information dictionary and a matching XMP packet
14
+ - Label the output as PDF/A or PDF/X with `--pdfa` / `--pdfx`, embedding an ICC output intent (`--icc-profile`, bundled sRGB default)
15
+ - Metadata comes from the flags, the publication manifest or the document itself (`<title>`, `<meta>` tags)
13
16
  - Per-push showcase page (GitHub Pages) with the render fixtures next to their PDFs
14
17
  - Automatic detection and mapping of static assets from HTML (`<link>`, `<script>`, `<img>`, etc.)
15
18
  - Support for custom static asset mappings via `--static`
@@ -64,36 +67,43 @@ vivliostyle-cli -i index.html -o output.pdf -- --size A4 --viewer-param pixelRat
64
67
 
65
68
  ## Options
66
69
 
67
- | Option | Description |
68
- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
69
- | `-i, --input <input>` | Input HTML or publication manifest file (required) |
70
- | `-o, --output <file>` | Output file path (default: `output.pdf`) |
71
- | `--title <title>` | Document title (overrides source) |
72
- | `--author <author>` | Document author |
73
- | `--language <lang>` | Document language tag (e.g. `en`, `de`, `ja`) (default: `de`) |
74
- | `--static <mapping>` | Map virtual path to local path: `/virtual/path:/local/path` (repeatable) |
75
- | `--no-scripts` | Do not map `<script src>` tags as static assets |
76
- | `--asset-base <urlBase=localBase>` | Map URLs starting with `urlBase` to files under `localBase` (repeatable) |
77
- | `--ignore-asset <path>` | Skip specific virtual paths when deriving static mappings (repeatable) |
78
- | `--allow-remote` | Keep subresource references that would be fetched from the network (default: drop) |
79
- | `--executable-browser <path>` | Chrome/Chromium binary to render with (default: search puppeteer cache, then system) |
80
- | `--dump-html <dir>` | Write the rewritten input HTML into `<dir>` and keep it (debugging aid) |
81
- | `--fetch-missing` | Load references without a local file from the web (implies `--allow-remote`; drops gone remotes after a HEAD probe) |
82
- | `--wait-for-content [ms]` --------- | Delay pagination until the page finished its own async work (default limit 25000ms) |
83
- | `--quiet-ms <ms>` ----------------- | Quiet period before the layout gate opens (default 400) --------------------------- |
84
- | `--pixel-ratio <n>` --------------- | Render at `n` times the output resolution; redraws `__vivResize` pages at `n`× backing pixels |
85
- | `--timeout <ms>` ------------------ | Give up on a page after `<ms>` (default: 300000) --------------------------------- |
86
- | `--format <format>` | Output format: `pdf` (default: `pdf`) |
87
- | `--log-level <level>` | Log level: `silent`, `info`, `verbose`, or `debug` (default: `info`) |
88
- | `--mode <mode>` | Execution mode: `build` or `preview` (default: `build`) |
89
- | `--preview` | Shorthand for `--mode preview` — open result in browser |
90
- | `-d, --debug` | Enable debug mode (sets log level to `debug`) |
70
+ | Option | Description |
71
+ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
72
+ | `-i, --input <input>` | Input HTML or publication manifest file (required) |
73
+ | `-o, --output <file>` | Output file path (default: `output.pdf`) |
74
+ | `--title <title>` | Document title (overrides source) |
75
+ | `--author <author>` | Document author |
76
+ | `--subject <subject>` | Document subject (e.g. the page's description meta tag content) |
77
+ | `--keywords <keywords>` | Document keywords, comma separated |
78
+ | `--language <lang>` | Document language tag (e.g. `en`, `de`, `ja`); taken from the document or manifest when omitted, falling back to `de` |
79
+ | `--pdfa <level>` | Label the output as PDF/A: `1a`, `1b`, `2a`, `2b`, `2u`, `3a`, `3b`, `3u`, `4`. Embeds the sRGB output intent unless overridden |
80
+ | `--pdfx <version>` | Label the output as PDF/X: `X-4` or `X-1a:2003` (requires `--icc-profile`) |
81
+ | `--icc-profile <path>` | ICC profile embedded as the PDF output intent (required for `--pdfx`) |
82
+ | `--static <mapping>` | Map virtual path to local path: `/virtual/path:/local/path` (repeatable) |
83
+ | `--no-scripts` | Do not map `<script src>` tags as static assets |
84
+ | `--asset-base <urlBase=localBase>` | Map URLs starting with `urlBase` to files under `localBase` (repeatable) |
85
+ | `--ignore-asset <path>` | Skip specific virtual paths when deriving static mappings (repeatable) |
86
+ | `--allow-remote` | Keep subresource references that would be fetched from the network (default: drop) |
87
+ | `--executable-browser <path>` | Chrome/Chromium binary to render with (default: search puppeteer cache, then system) |
88
+ | `--dump-html <dir>` | Write the rewritten input HTML into `<dir>` and keep it (debugging aid) |
89
+ | `--fetch-missing` | Load references without a local file from the web (implies `--allow-remote`; drops gone remotes after a HEAD probe) |
90
+ | `--wait-for-content [ms]` --------- | Delay pagination until the page finished its own async work; pages with `<script>` wait automatically (10s default, `0` disables) |
91
+ | `--quiet-ms <ms>` ----------------- | Quiet period before the layout gate opens (default 400) --------------------------- |
92
+ | `--pixel-ratio <n>` --------------- | Render at `n` times the output resolution; redraws `__vivResize` pages at `n`× backing pixels |
93
+ | `--timeout <ms>` ------------------ | Give up on a page after `<ms>` (default: 300000) --------------------------------- |
94
+ | `--format <format>` | Output format: `pdf` (default: `pdf`) |
95
+ | `--log-level <level>` | Log level: `silent`, `info`, `verbose`, or `debug` (default: `info`) |
96
+ | `--mode <mode>` | Execution mode: `build` or `preview` (default: `build`) |
97
+ | `--preview` | Shorthand for `--mode preview` — open result in browser |
98
+ | `-d, --debug` | Enable debug mode (sets log level to `debug`) |
91
99
 
92
100
  ## Notes
93
101
 
102
+ - **PDF metadata and standards labeling**: every build stamps a producer/creator identity (`vivliostyle-batch-cli`) and a document language. Title, author, subject, keywords and language resolve with this precedence: CLI flags → publication manifest (`.json` input) → the document itself (`<title>`, `<meta name="author">`/`dc.creator`, `<meta name="description">`, `<meta name="keywords">`, `html[lang]`) → language fallback `de`. The values land in both the PDF information dictionary and an XMP metadata stream kept consistent with it, plus the catalog `/Lang` entry. `--pdfa <level>` and `--pdfx <version>` additionally write the standards identification (XMP `pdfaid`/`pdfxid` properties, an OutputIntent with an embedded ICC profile and a file identifier). This is a **label, not a conversion**: the rendered content is neither converted nor checked, so conformance of the content is the author's responsibility — verify with veraPDF when it matters. Chrome's output carries transparency, so `--pdfa 2b` (or newer) is the realistic level; PDF/A-1b will usually fail validation.
103
+ - The bundled `src/render/srgb.icc` is the ICC's `sRGB_v4_ICC_preference.icc`, redistributed unchanged under its license ("permission to use, copy and distribute this file for any purpose… provided that the file is not changed"), see <https://www.color.org/srgbprofiles.xalter>. Pass `--icc-profile` to embed a print provider's profile instead.
94
104
  - HTML input (`.html`/`.htm`) is auto-detected by file extension.
95
105
  - For HTML input, `<link href>` and `<script src>` tags are parsed and automatically mapped.
96
- - Everything else the document references (`<img src>`, `<source>`, `<iframe>`, `srcset`, …) is rewritten to the local static server as well, so only files from `--static` / `--asset-base` roots are ever loaded.
106
+ - Everything else the document references (`<img src>`, `<source>`, `<iframe>`, `srcset`, …) is rewritten to the local static server as well, so only files from `--static` / `--asset-base` roots are ever loaded. Relative URLs on custom elements (`<a-asset-item>`, `<model-viewer>`, …) are resolved to absolute server URLs up front, since the viewer mangles the ones it does not understand.
97
107
  - **Offline by default**: any subresource reference without a local file is removed from the document and reported as `[offline] Dropped remote reference: <url>`. Use `--allow-remote` to keep them and let the browser fetch them. Hyperlinks (`<a href>`) are never touched — a link is not a fetch.
98
108
  - Options after `--` are forwarded to the viewer as-is; `--size`, `--style`, `--user-style` and `--viewer-param key=value` are turned into viewer parameters.
99
109
  - `--debug` automatically sets `--log-level` to `debug`.
@@ -101,7 +111,7 @@ vivliostyle-cli -i index.html -o output.pdf -- --size A4 --viewer-param pixelRat
101
111
  - Both modes run a local HTTP server that serves the rewritten document, the mapped assets and the stock Vivliostyle viewer. The viewer page sits in the document's own directory, so URLs that page scripts build from relative paths resolve the way they do on the live site.
102
112
  - `--asset-base` local directories are also used as fallback roots for CSS-referenced assets (fonts, images, etc.).
103
113
  - `--dump-html` keeps the rewritten HTML outside the input directory, which is handy when a page does not render as expected.
104
- - `--wait-for-content` injects a gate image that the static server holds open until the page has no request in flight and its height stopped changing. Vivliostyle waits for every image of a document before it paginates, so this postpones the layout until charts and canvases are rendered. The tracker also logs `devicePixelRatio` and the canvas sizes, which makes resolution problems visible.
114
+ - `--wait-for-content` injects a gate image that the static server holds open until the page has no request in flight, no wasm compiling, no long task running and its height stopped changing. Vivliostyle waits for every image of a document before it paginates, so this postpones the layout until charts and canvases are rendered. The tracker also logs `devicePixelRatio` and the canvas sizes, which makes resolution problems visible. Pages with `<script>` tags arm this wait automatically (10s deadline); pass `--wait-for-content 0` to disable it or a value to raise the cap (max 25000ms).
105
115
  - Pages that paint asynchronously can set `window.__vivReady = true` when done; the layout gate and the renderer treat it as an immediate “painted” signal instead of guessing from network quietness.
106
116
  - Pages with resolution-dependent content (canvas, WebGL) can expose `window.__vivResize = (factor) => void` to redraw at `clientSize × factor` backing pixels. `--pixel-ratio <n>` calls that hook with `n` before printing, so output past 96dpi stays sharp while layout keeps its CSS size. Without the hook a `resize` event is still dispatched so chart libraries can re-layout.
107
117
  - `--fetch-missing` HEADs every remote reference without a local file and drops the ones that are definitively gone (404/410), so retired embeds do not stall the build. A reference that resolves to a local file is never probed: the live site may have moved on while the local copy still has what the page needs.
@@ -136,6 +146,12 @@ Cross-origin iframes are printed by the browser as they appear on screen, so map
136
146
  # Build a PDF from an HTML file
137
147
  vivliostyle-cli -i index.html -o output.pdf
138
148
 
149
+ # Build a PDF/A-2b-labeled file (metadata comes from the document itself)
150
+ vivliostyle-cli -i index.html -o output.pdf --pdfa 2b --title "Report" --author "Jane Doe"
151
+
152
+ # Label as PDF/X-4 with a print provider's ICC profile
153
+ vivliostyle-cli -i index.html -o output.pdf --pdfx X-4 --icc-profile ISOcoated_v2_eci.icc
154
+
139
155
  # Preview an HTML file in browser
140
156
  vivliostyle-cli -i index.html --preview
141
157
 
@@ -151,6 +167,11 @@ vivliostyle-cli -i index.html -o output.pdf \
151
167
  vivliostyle-cli -i index.html -o output.pdf -- --size A4
152
168
  ```
153
169
 
170
+ ## Citation
171
+
172
+ If you use this software, please cite it using the metadata from [CITATION.cff](CITATION.cff).
173
+ GitHub also offers a "Cite this repository" button based on this file.
174
+
154
175
  ## License
155
176
 
156
177
  MIT
package/dist/index.d.ts CHANGED
@@ -18,12 +18,65 @@ type SettleGate = {
18
18
  deadlineMs: number;
19
19
  };
20
20
 
21
+ /**
22
+ * XMP metadata packet builder for the PDF post-processing step
23
+ * (see src/render/pdf-postprocess.ts).
24
+ *
25
+ * The packet follows XMP Specification Part 1 (April 2012) the same way
26
+ * vivliostyle-cli builds it for PDF/X: a packet wrapper Acrobat's preflight
27
+ * accepts, Dublin Core for title/creator/description, the Adobe PDF and XMP
28
+ * namespaces for producer/creator/dates, and the identification namespaces
29
+ * pdfaid (PDF/A, ISO 19005) and pdfxid (PDF/X, ISO 15930).
30
+ */
31
+ /** PDF/A part (ISO 19005-1/-2/-3/-4). */
32
+ type PdfAPart = "1" | "2" | "3" | "4";
33
+ /** PDF/A conformance level. PDF/A-4 has no conformance levels. */
34
+ type PdfAConformance = "a" | "b" | "u";
35
+ /** PDF/A labeling request, e.g. `--pdfa 2b`. */
36
+ type PdfAIdentification = {
37
+ kind: "pdfa";
38
+ part: PdfAPart;
39
+ conformance?: PdfAConformance;
40
+ };
41
+ /** PDF/X conformance level (ISO 15930), e.g. `--pdfx X-4`. */
42
+ type PdfXVersion = "X-4" | "X-1a:2003";
43
+ type PdfXIdentification = {
44
+ kind: "pdfx";
45
+ version: PdfXVersion;
46
+ };
47
+ /** Standards label carried into the XMP packet and the PDF catalog. */
48
+ type PdfLabel = PdfAIdentification | PdfXIdentification;
49
+
50
+ /**
51
+ * Document metadata for the PDF information dictionary and XMP packet:
52
+ * extraction from the input (HTML document or publication manifest) and
53
+ * resolution against the CLI flags.
54
+ *
55
+ * Precedence: CLI flags > publication manifest > document > defaults.
56
+ * The only default is the language tag, which falls back to "de" when
57
+ * neither the flags nor the input provide one.
58
+ */
59
+
60
+ /** Metadata fields shared by every source (document, manifest, CLI flags). */
61
+ type DocumentMetadata = {
62
+ title?: string;
63
+ author?: string;
64
+ subject?: string;
65
+ keywords?: string;
66
+ language?: string;
67
+ };
68
+
21
69
  type CliOptions = {
22
70
  input: string;
23
71
  output: string;
24
72
  title?: string;
25
73
  author?: string;
74
+ subject?: string;
75
+ keywords?: string;
26
76
  language?: string;
77
+ pdfa?: string;
78
+ pdfx?: string;
79
+ iccProfile?: string;
27
80
  static: string[];
28
81
  scripts: boolean;
29
82
  format: string;
@@ -199,6 +252,20 @@ type AssetBaseMatch = {
199
252
  declare function mapAbsoluteUrlToLocal(url: string, assetBases: AssetBaseMapping[]): AssetBaseMatch;
200
253
  declare function rewriteAbsoluteUrlsInDom(document: Document, assetBases: AssetBaseMapping[], keepMissing?: boolean): boolean;
201
254
  declare function rewriteVirtualPathsToServerInDom(document: Document, staticMapKeys: string[], serverBaseUrl: string, isServable?: (virtualPath: string) => boolean): boolean;
255
+ /**
256
+ * Resolves relative URLs on custom elements (`<a-asset-item>`,
257
+ * `<model-viewer>`, and any tag name containing a dash) to absolute server
258
+ * URLs.
259
+ *
260
+ * Vivliostyle resolves the subresource attributes it knows (`<img>`,
261
+ * `<iframe>`, …) correctly, but mangles relative URLs on elements it does not
262
+ * understand — `../tiles/model.glb` on an `<a-asset-item>` came back as
263
+ * `http://tiles/model.glb`. Absolute server URLs always resolve, so pages hand
264
+ * the viewer those instead. Standard elements are left alone (the viewer and
265
+ * the runtime URL shim already handle them); only dash-tagged elements, whose
266
+ * attributes the viewer cannot be trusted with, are rewritten.
267
+ */
268
+ declare function rewriteCustomElementUrlsInDom(document: Document, documentDirUrl: string): boolean;
202
269
  /**
203
270
  * Returns a predicate that reports whether a root-relative path can be served
204
271
  * from one of the configured asset-base local roots.
@@ -253,7 +320,38 @@ declare function parseArgs(argv: string[]): {
253
320
  options: CliOptions;
254
321
  extraArgs: string[];
255
322
  } | null;
323
+ /** ICC profile bytes with the name they get in the PDF's OutputIntent. */
324
+ type IccProfile = {
325
+ bytes: Uint8Array;
326
+ name: string;
327
+ };
256
328
  declare function resolveSettleGate(options: CliOptions): SettleGate | null;
329
+ /**
330
+ * Settle gate that actually applies: an explicit `--wait-for-content` wins;
331
+ * otherwise pages that run scripts wait automatically (charts, wasm, WebGL
332
+ * would otherwise race pagination), static pages don't wait at all.
333
+ */
334
+ declare function resolveEffectiveSettle(options: CliOptions, hasScripts: boolean): {
335
+ gate: SettleGate | null;
336
+ autoArmed: boolean;
337
+ };
338
+ /**
339
+ * `--pdfa` / `--pdfx`: mutually exclusive standards labels for the output PDF.
340
+ */
341
+ declare function resolvePdfLabel(options: Pick<CliOptions, "pdfa" | "pdfx">): PdfLabel | undefined;
342
+ /**
343
+ * `--icc-profile <path>`: the profile the OutputIntent embeds. PDF/X always
344
+ * needs one; a PDF/A build without the flag embeds the bundled sRGB profile.
345
+ */
346
+ declare function resolveIccProfile(options: Pick<CliOptions, "iccProfile">, label: PdfLabel | undefined): IccProfile | undefined;
347
+ /**
348
+ * Document metadata for the PDF: the flags override values taken from the
349
+ * input (HTML meta tags or a publication manifest); the language falls back
350
+ * to "de" when no source provides one.
351
+ */
352
+ declare function resolvePdfMetadata(options: Pick<CliOptions, "title" | "author" | "subject" | "keywords" | "language">, inputAbs: string, htmlMode: boolean): DocumentMetadata & {
353
+ language: string;
354
+ };
257
355
  declare function execute(options: CliOptions, extraArgs?: string[]): Promise<void>;
258
356
  type PreviewTarget = {
259
357
  /** URL of the viewer, showing the document. */
@@ -270,5 +368,5 @@ type PreviewTarget = {
270
368
  */
271
369
  declare function startPreview(inputAbs: string, assetBases: AssetBaseMapping[], staticMap: StaticMap, htmlOptions: HtmlRewriteOptions, extraConfig: Record<string, unknown>): Promise<PreviewTarget>;
272
370
 
273
- export { EXPAND_DETAILS_SNIPPET, buildPreviewHtml, buildRuntimeScript, buildSettleGateImage, coerceExtraValue, collectRemoteReferences, collectUnservedVirtualPaths, createAssetBasePathProbe, deriveSitePath, dropRemoteReferencesInDom, dropUnavailableReferencesInDom, execute, extractUrlsFromHtml, injectRuntimeScriptInDom, isHtmlInput, isRemoteUrl, isStaticServerUrl, mapAbsoluteUrlToLocal, normalizeExtraKey, normalizeIgnoreAssetPath, normalizeUrlBase, parseArgs, parseAssetBaseMapping, parseExtraArgs, parseMetaRefreshTarget, parseStaticMapping, prepareInputHtmlForBuild, printHelp, probeRemoteReferences, referencesToProbe, resolveSettleGate, rewriteAbsoluteUrls, rewriteAbsoluteUrlsInDom, rewriteUrlAttributes, rewriteVirtualPathsToServer, rewriteVirtualPathsToServerInDom, shouldIgnoreVirtualPath, siteDirectory, splitArgsAtDoubleDash, startPreview, urlToStaticMapping };
371
+ export { EXPAND_DETAILS_SNIPPET, buildPreviewHtml, buildRuntimeScript, buildSettleGateImage, coerceExtraValue, collectRemoteReferences, collectUnservedVirtualPaths, createAssetBasePathProbe, deriveSitePath, dropRemoteReferencesInDom, dropUnavailableReferencesInDom, execute, extractUrlsFromHtml, injectRuntimeScriptInDom, isHtmlInput, isRemoteUrl, isStaticServerUrl, mapAbsoluteUrlToLocal, normalizeExtraKey, normalizeIgnoreAssetPath, normalizeUrlBase, parseArgs, parseAssetBaseMapping, parseExtraArgs, parseMetaRefreshTarget, parseStaticMapping, prepareInputHtmlForBuild, printHelp, probeRemoteReferences, referencesToProbe, resolveEffectiveSettle, resolveIccProfile, resolvePdfLabel, resolvePdfMetadata, resolveSettleGate, rewriteAbsoluteUrls, rewriteAbsoluteUrlsInDom, rewriteCustomElementUrlsInDom, rewriteUrlAttributes, rewriteVirtualPathsToServer, rewriteVirtualPathsToServerInDom, shouldIgnoreVirtualPath, siteDirectory, splitArgsAtDoubleDash, startPreview, urlToStaticMapping };
274
372
  export type { HtmlRewriteOptions, PreviewTarget, RuntimeScriptOptions };