@procedures/browser 0.0.0-bootstrap.0 → 0.54.1
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/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +78 -1
- package/dist/browser.d.ts +37 -0
- package/dist/browser.d.ts.map +1 -0
- package/dist/browser.js +84 -0
- package/dist/browser.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -0
- package/dist/pdf.d.ts +28 -0
- package/dist/pdf.d.ts.map +1 -0
- package/dist/pdf.js +38 -0
- package/dist/pdf.js.map +1 -0
- package/dist/run.d.ts +69 -0
- package/dist/run.d.ts.map +1 -0
- package/dist/run.js +111 -0
- package/dist/run.js.map +1 -0
- package/dist/screenshot.d.ts +63 -0
- package/dist/screenshot.d.ts.map +1 -0
- package/dist/screenshot.js +108 -0
- package/dist/screenshot.js.map +1 -0
- package/package.json +61 -5
- package/src/browser.ts +99 -0
- package/src/index.ts +5 -0
- package/src/pdf.ts +52 -0
- package/src/run.ts +152 -0
- package/src/screenshot.ts +141 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# @procedures/browser
|
|
2
|
+
|
|
3
|
+
## 0.54.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- a3efa7e: The new package `@procedures/browser` is the home of the renders of a page with a Chromium browser that is already installed. It has `findBrowser`, one headless run for each render, `renderPdf` and the new `renderScreenshot`.
|
|
8
|
+
|
|
9
|
+
- `renderScreenshot` loads an address, an HTML text or an HTML file in a window of a given size. It writes a PNG, JPEG or WebP picture of the window. The extension of the output sets the format.
|
|
10
|
+
- It accepts only an `http:`, `https:` or `file:` address, so a flag cannot get into the argv of the browser.
|
|
11
|
+
- The headless run is written one time. The two renders give only their flags and the check of their file.
|
|
12
|
+
|
|
13
|
+
`@procedures/pdf` gives the same names again from `@procedures/browser`, so no caller breaks. Its procedure `pdf.render` does not change.
|
|
14
|
+
|
|
15
|
+
PATCH: before 1.0.0, a new package and a new feature raise PATCH. The exports and the behavior of `@procedures/pdf` do not change.
|
|
16
|
+
- @procedures/shell@0.54.1
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025-2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,80 @@
|
|
|
1
1
|
# @procedures/browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@procedures/browser)
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @procedures/browser
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
This package finds a Chromium browser that is already on the host: Microsoft Edge, Google Chrome or Chromium. It renders a page with that browser: a PDF file or a screenshot. The package does not download a browser.
|
|
10
|
+
|
|
11
|
+
Each render uses one headless run. The run starts the browser one time, with argv, in a new temporary folder with its own profile. The renders give only their flags and the check of their file.
|
|
12
|
+
|
|
13
|
+
The package has no procedures. The procedure `pdf.render` is in [`@procedures/pdf`](../pdf).
|
|
14
|
+
|
|
15
|
+
## A screenshot
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { renderScreenshot } from "@procedures/browser";
|
|
19
|
+
|
|
20
|
+
const { path, bytes, format } = await renderScreenshot({
|
|
21
|
+
url: "https://example.com/",
|
|
22
|
+
output: "example.jpg",
|
|
23
|
+
size: { width: 1280, height: 800 },
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- Give one of `url`, `html` and `file`. The address of `url` starts with `http:`, `https:` or `file:`. The function refuses other addresses.
|
|
28
|
+
- The format is PNG, JPEG or WebP. The extension of `output` sets the format: `.png`, `.jpg`, `.jpeg` or `.webp`. Without `output`, the option `format` sets it, and the default is PNG.
|
|
29
|
+
- The option `format` and the extension of `output` must agree. Otherwise the function gives an error before it starts the browser.
|
|
30
|
+
- The default size of the window is 1280 by 800 CSS pixels. Each side is an integer from 1 to 16384.
|
|
31
|
+
- The option `budget` gives the scripts and the timers of the page more virtual time before the picture, in milliseconds. Without it, the picture follows the load event.
|
|
32
|
+
- The page can load each address that it names. Give an address that you trust, or a page of your own.
|
|
33
|
+
|
|
34
|
+
## A PDF file
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { renderPdf } from "@procedures/browser";
|
|
38
|
+
|
|
39
|
+
const { path, bytes } = await renderPdf({ html: "<h1>Menu</h1><p>Soup of the day</p>", output: "menu.pdf" });
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- Give `html` or `file`, not the two.
|
|
43
|
+
- After the print, the function examines the file. A file that does not start with `%PDF` gives an error.
|
|
44
|
+
|
|
45
|
+
## The options of each render
|
|
46
|
+
|
|
47
|
+
| Option | What it does |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `output` | The path of the file. The default is a file in a new temporary folder. The caller moves or deletes it. |
|
|
50
|
+
| `executable` | The browser program. When it is set, the search does not occur. |
|
|
51
|
+
| `args` | More flags for the browser, after the default flags. A browser that runs as root, for example in a container, needs `["--no-sandbox"]`. |
|
|
52
|
+
| `timeout` | The time limit, in milliseconds. The default is 60000. |
|
|
53
|
+
| `signal` | When the signal aborts, the browser stops. |
|
|
54
|
+
| `runner` | The function that runs the browser. The default is `runCommand` of `@procedures/shell`. The tests give their own. |
|
|
55
|
+
|
|
56
|
+
- The browser starts through `runCommand` of `@procedures/shell`, not through a shell. At the time limit, or when the signal aborts, `runCommand` stops the process tree of the browser.
|
|
57
|
+
- The temporary profile keeps the render apart from a browser that the user has open.
|
|
58
|
+
- A missing file, an empty file or a file of the wrong kind gives an error.
|
|
59
|
+
- An existing output file changes only after the check of the new file. Thus a failed render keeps an old output file.
|
|
60
|
+
|
|
61
|
+
## The browser
|
|
62
|
+
|
|
63
|
+
`findBrowser(options)` gives the path of the browser program, or `undefined`. The search uses the first of these:
|
|
64
|
+
|
|
65
|
+
1. The option `executable`.
|
|
66
|
+
2. The environment variable `PDF_BROWSER`, then `CHROME_PATH`.
|
|
67
|
+
3. On Windows: Edge, then Chrome, in `Program Files`, `Program Files (x86)` and `LOCALAPPDATA`.
|
|
68
|
+
4. On macOS: the app bundles of Chrome, Edge and Chromium in `/Applications` and `~/Applications`.
|
|
69
|
+
5. The `PATH`: `google-chrome`, `google-chrome-stable`, `chromium`, `chromium-browser`, `microsoft-edge` and `microsoft-edge-stable`. On Windows, `msedge.exe` and `chrome.exe`.
|
|
70
|
+
|
|
71
|
+
When the search finds no browser, each render gives an error that names `PDF_BROWSER`. The name comes from `@procedures/pdf`, the first home of the search.
|
|
72
|
+
|
|
73
|
+
## The other functions
|
|
74
|
+
|
|
75
|
+
- `browserCandidates(platform, env)` gives the paths that the search examines.
|
|
76
|
+
- `pdfArgs(page, output, profile, extra)` gives the argv of a print.
|
|
77
|
+
- `screenshotArgs(page, output, profile, size, budget, extra)` gives the argv of a screenshot.
|
|
78
|
+
- `screenshotFormatOf(output, format)` gives the format of a screenshot.
|
|
79
|
+
- `isPdfFile(path)` tells if a file starts with `%PDF`.
|
|
80
|
+
- `isImageFile(path, format)` tells if a file starts with the signature of a PNG, JPEG or WebP file.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Find a Chromium browser that is already installed: Microsoft Edge, Google Chrome or Chromium.
|
|
3
|
+
* The package does not download a browser.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* The environment variable that names the browser program. It comes before the search. The name
|
|
7
|
+
* comes from `@procedures/pdf`, the first home of the search, and each render reads it.
|
|
8
|
+
*/
|
|
9
|
+
export declare const BROWSER_ENV = "PDF_BROWSER";
|
|
10
|
+
/** The second environment variable for the browser program. Other tools use this name too. */
|
|
11
|
+
export declare const CHROME_PATH_ENV = "CHROME_PATH";
|
|
12
|
+
/** The program names that the search looks for on the `PATH`, in order. */
|
|
13
|
+
export declare const BROWSER_NAMES: readonly string[];
|
|
14
|
+
/** The program names on the `PATH` of Windows, in order. */
|
|
15
|
+
export declare const WINDOWS_BROWSER_NAMES: readonly string[];
|
|
16
|
+
/** The options of `findBrowser`. Each one has a default from the host. */
|
|
17
|
+
export interface FindBrowserOptions {
|
|
18
|
+
/** The browser program. When it is set, the search does not occur. */
|
|
19
|
+
readonly executable?: string | undefined;
|
|
20
|
+
/** The environment (default: `process.env`). */
|
|
21
|
+
readonly env?: Readonly<Record<string, string | undefined>> | undefined;
|
|
22
|
+
/** The operating system (default: `process.platform`). */
|
|
23
|
+
readonly platform?: NodeJS.Platform | undefined;
|
|
24
|
+
/** The function that tells if a file exists (default: `existsSync`). */
|
|
25
|
+
readonly exists?: ((path: string) => boolean) | undefined;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* This function gives the paths that the search examines on an operating system, in order. The
|
|
29
|
+
* install folders come first, then the folders of the `PATH`.
|
|
30
|
+
*/
|
|
31
|
+
export declare function browserCandidates(platform: NodeJS.Platform, env: Readonly<Record<string, string | undefined>>): string[];
|
|
32
|
+
/**
|
|
33
|
+
* This function finds the browser program. The order is `executable`, then `PDF_BROWSER`, then
|
|
34
|
+
* `CHROME_PATH`, then the install folders and the `PATH`. It gives `undefined` when it finds none.
|
|
35
|
+
*/
|
|
36
|
+
export declare function findBrowser(options?: FindBrowserOptions): string | undefined;
|
|
37
|
+
//# sourceMappingURL=browser.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;GAGG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,8FAA8F;AAC9F,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAO1C,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAiC,CAAC;AAErF,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IACxE,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CAC3D;AASD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,MAAM,EAAE,CA8BxH;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,GAAG,SAAS,CAShF"}
|
package/dist/browser.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Find a Chromium browser that is already installed: Microsoft Edge, Google Chrome or Chromium.
|
|
3
|
+
* The package does not download a browser.
|
|
4
|
+
*/
|
|
5
|
+
import { existsSync } from "node:fs";
|
|
6
|
+
import { posix, win32 } from "node:path";
|
|
7
|
+
/**
|
|
8
|
+
* The environment variable that names the browser program. It comes before the search. The name
|
|
9
|
+
* comes from `@procedures/pdf`, the first home of the search, and each render reads it.
|
|
10
|
+
*/
|
|
11
|
+
export const BROWSER_ENV = "PDF_BROWSER";
|
|
12
|
+
/** The second environment variable for the browser program. Other tools use this name too. */
|
|
13
|
+
export const CHROME_PATH_ENV = "CHROME_PATH";
|
|
14
|
+
/** The program names that the search looks for on the `PATH`, in order. */
|
|
15
|
+
export const BROWSER_NAMES = [
|
|
16
|
+
"google-chrome",
|
|
17
|
+
"google-chrome-stable",
|
|
18
|
+
"chromium",
|
|
19
|
+
"chromium-browser",
|
|
20
|
+
"microsoft-edge",
|
|
21
|
+
"microsoft-edge-stable",
|
|
22
|
+
];
|
|
23
|
+
/** The program names on the `PATH` of Windows, in order. */
|
|
24
|
+
export const WINDOWS_BROWSER_NAMES = ["msedge.exe", "chrome.exe"];
|
|
25
|
+
/** This function gives the folders of the `PATH`, in order. */
|
|
26
|
+
function pathFolders(env, windows) {
|
|
27
|
+
const value = windows ? (env["Path"] ?? env["PATH"]) : env["PATH"];
|
|
28
|
+
if (value === undefined)
|
|
29
|
+
return [];
|
|
30
|
+
return value.split(windows ? ";" : ":").filter((folder) => folder.length > 0);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* This function gives the paths that the search examines on an operating system, in order. The
|
|
34
|
+
* install folders come first, then the folders of the `PATH`.
|
|
35
|
+
*/
|
|
36
|
+
export function browserCandidates(platform, env) {
|
|
37
|
+
if (platform === "win32") {
|
|
38
|
+
const programFiles = env["ProgramFiles"] ?? env["PROGRAMFILES"] ?? "C:\\Program Files";
|
|
39
|
+
const programFilesX86 = env["ProgramFiles(x86)"] ?? env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)";
|
|
40
|
+
const localAppData = env["LOCALAPPDATA"];
|
|
41
|
+
const installed = [
|
|
42
|
+
win32.join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"),
|
|
43
|
+
win32.join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"),
|
|
44
|
+
win32.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"),
|
|
45
|
+
win32.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"),
|
|
46
|
+
...(localAppData !== undefined
|
|
47
|
+
? [win32.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"), win32.join(localAppData, "Chromium", "Application", "chrome.exe")]
|
|
48
|
+
: []),
|
|
49
|
+
];
|
|
50
|
+
const onPath = pathFolders(env, true).flatMap((folder) => WINDOWS_BROWSER_NAMES.map((name) => win32.join(folder, name)));
|
|
51
|
+
return [...installed, ...onPath];
|
|
52
|
+
}
|
|
53
|
+
const installed = [];
|
|
54
|
+
if (platform === "darwin") {
|
|
55
|
+
const bundles = [
|
|
56
|
+
"Google Chrome.app/Contents/MacOS/Google Chrome",
|
|
57
|
+
"Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
|
|
58
|
+
"Chromium.app/Contents/MacOS/Chromium",
|
|
59
|
+
];
|
|
60
|
+
const home = env["HOME"];
|
|
61
|
+
installed.push(...bundles.map((bundle) => posix.join("/Applications", bundle)));
|
|
62
|
+
if (home !== undefined)
|
|
63
|
+
installed.push(...bundles.map((bundle) => posix.join(home, "Applications", bundle)));
|
|
64
|
+
}
|
|
65
|
+
const onPath = pathFolders(env, false).flatMap((folder) => BROWSER_NAMES.map((name) => posix.join(folder, name)));
|
|
66
|
+
return [...installed, ...onPath];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* This function finds the browser program. The order is `executable`, then `PDF_BROWSER`, then
|
|
70
|
+
* `CHROME_PATH`, then the install folders and the `PATH`. It gives `undefined` when it finds none.
|
|
71
|
+
*/
|
|
72
|
+
export function findBrowser(options = {}) {
|
|
73
|
+
if (options.executable !== undefined && options.executable.length > 0)
|
|
74
|
+
return options.executable;
|
|
75
|
+
const env = options.env ?? process.env;
|
|
76
|
+
for (const name of [BROWSER_ENV, CHROME_PATH_ENV]) {
|
|
77
|
+
const value = env[name];
|
|
78
|
+
if (value !== undefined && value.length > 0)
|
|
79
|
+
return value;
|
|
80
|
+
}
|
|
81
|
+
const exists = options.exists ?? existsSync;
|
|
82
|
+
return browserCandidates(options.platform ?? process.platform, env).find((candidate) => exists(candidate));
|
|
83
|
+
}
|
|
84
|
+
//# sourceMappingURL=browser.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export * from "./browser.js";
|
|
2
|
+
export { DEFAULT_TIMEOUT_MS, type CommandRunner, type HeadlessOptions, type RenderResult } from "./run.js";
|
|
3
|
+
export { isPdfFile, pdfArgs, renderPdf, type RenderPdfOptions, type RenderPdfResult } from "./pdf.js";
|
|
4
|
+
export * from "./screenshot.js";
|
|
5
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AACtG,cAAc,iBAAiB,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// The package has no procedures. It gives functions only: the search, the run and the renders.
|
|
2
|
+
export * from "./browser.js";
|
|
3
|
+
export { DEFAULT_TIMEOUT_MS } from "./run.js";
|
|
4
|
+
export { isPdfFile, pdfArgs, renderPdf } from "./pdf.js";
|
|
5
|
+
export * from "./screenshot.js";
|
|
6
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAA+D,MAAM,UAAU,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAA+C,MAAM,UAAU,CAAC;AACtG,cAAc,iBAAiB,CAAC"}
|
package/dist/pdf.d.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTML to PDF with a headless Chromium browser that is already installed. The render uses the
|
|
3
|
+
* headless run of `run.ts`.
|
|
4
|
+
*/
|
|
5
|
+
import { type HeadlessOptions, type RenderResult } from "./run.js";
|
|
6
|
+
/** The options of `renderPdf`. Give `html` or `file`, not the two. */
|
|
7
|
+
export interface RenderPdfOptions extends HeadlessOptions {
|
|
8
|
+
/** The HTML text. The function writes it to a temporary file. */
|
|
9
|
+
readonly html?: string | undefined;
|
|
10
|
+
/** The path of an HTML file. */
|
|
11
|
+
readonly file?: string | undefined;
|
|
12
|
+
}
|
|
13
|
+
/** The result of `renderPdf`: the path and the size of the PDF file, and the browser program. */
|
|
14
|
+
export type RenderPdfResult = RenderResult;
|
|
15
|
+
/**
|
|
16
|
+
* This function gives the argv of the browser. The argv has the flags of a headless print, the
|
|
17
|
+
* profile folder, the extra flags and the address of the page.
|
|
18
|
+
*/
|
|
19
|
+
export declare function pdfArgs(page: string, output: string, profile: string, extra?: readonly string[]): string[];
|
|
20
|
+
/** This function tells if a file starts with the signature of a PDF file (`%PDF`). */
|
|
21
|
+
export declare function isPdfFile(path: string): boolean;
|
|
22
|
+
/**
|
|
23
|
+
* This function prints an HTML page to a PDF file with a headless browser. It gives the path and
|
|
24
|
+
* the size of the file. It throws when it finds no browser, at the time limit, and when the file
|
|
25
|
+
* is not a PDF file.
|
|
26
|
+
*/
|
|
27
|
+
export declare function renderPdf(options: RenderPdfOptions): Promise<RenderPdfResult>;
|
|
28
|
+
//# sourceMappingURL=pdf.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pdf.d.ts","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA4B,KAAK,eAAe,EAAuB,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAElH,sEAAsE;AACtE,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,iGAAiG;AACjG,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAW9G;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAInF"}
|
package/dist/pdf.js
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTML to PDF with a headless Chromium browser that is already installed. The render uses the
|
|
3
|
+
* headless run of `run.ts`.
|
|
4
|
+
*/
|
|
5
|
+
import { headlessRender, readHead } from "./run.js";
|
|
6
|
+
/**
|
|
7
|
+
* This function gives the argv of the browser. The argv has the flags of a headless print, the
|
|
8
|
+
* profile folder, the extra flags and the address of the page.
|
|
9
|
+
*/
|
|
10
|
+
export function pdfArgs(page, output, profile, extra = []) {
|
|
11
|
+
return [
|
|
12
|
+
"--headless",
|
|
13
|
+
"--disable-gpu",
|
|
14
|
+
"--no-pdf-header-footer",
|
|
15
|
+
// A separate profile keeps the print apart from a browser that the user has open
|
|
16
|
+
`--user-data-dir=${profile}`,
|
|
17
|
+
`--print-to-pdf=${output}`,
|
|
18
|
+
...extra,
|
|
19
|
+
page,
|
|
20
|
+
];
|
|
21
|
+
}
|
|
22
|
+
/** This function tells if a file starts with the signature of a PDF file (`%PDF`). */
|
|
23
|
+
export function isPdfFile(path) {
|
|
24
|
+
return readHead(path, 4).toString("latin1") === "%PDF";
|
|
25
|
+
}
|
|
26
|
+
const PDF = { prefix: "procedures-pdf-", file: "page.pdf", noun: "PDF file", argv: pdfArgs, isValid: isPdfFile };
|
|
27
|
+
/**
|
|
28
|
+
* This function prints an HTML page to a PDF file with a headless browser. It gives the path and
|
|
29
|
+
* the size of the file. It throws when it finds no browser, at the time limit, and when the file
|
|
30
|
+
* is not a PDF file.
|
|
31
|
+
*/
|
|
32
|
+
export async function renderPdf(options) {
|
|
33
|
+
const { html, file } = options;
|
|
34
|
+
if ((html === undefined) === (file === undefined))
|
|
35
|
+
throw new Error("renderPdf needs html or file, and not the two");
|
|
36
|
+
return headlessRender(PDF, html !== undefined ? { html } : { file: file }, options);
|
|
37
|
+
}
|
|
38
|
+
//# sourceMappingURL=pdf.js.map
|
package/dist/pdf.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pdf.js","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAgE,MAAM,UAAU,CAAC;AAalH;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,MAAc,EAAE,OAAe,EAAE,KAAK,GAAsB,EAAE;IAClG,OAAO;QACL,YAAY;QACZ,eAAe;QACf,wBAAwB;QACxB,iFAAiF;QACjF,mBAAmB,OAAO,EAAE;QAC5B,kBAAkB,MAAM,EAAE;QAC1B,GAAG,KAAK;QACR,IAAI;KACL,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC;AACzD,CAAC;AAED,MAAM,GAAG,GAAmB,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAEjI;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB;IACvD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACpH,OAAO,cAAc,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAK,EAAE,EAAE,OAAO,CAAC,CAAC;AACvF,CAAC"}
|
package/dist/run.d.ts
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The headless run of a browser that is already installed. The run starts the browser one time with
|
|
3
|
+
* argv, in a new temporary folder with its own profile. Each render of this package (the PDF file,
|
|
4
|
+
* the screenshot) uses this run, and gives only its flags and the check of its file.
|
|
5
|
+
*
|
|
6
|
+
* The browser starts through `runCommand` of `@procedures/shell`, not through a shell. A time limit
|
|
7
|
+
* and the signal of the call stop its process tree.
|
|
8
|
+
*/
|
|
9
|
+
import { type CommandOptions, type CommandResult } from "@procedures/shell/command";
|
|
10
|
+
import { type FindBrowserOptions } from "./browser.js";
|
|
11
|
+
/** The default time limit of one render, in milliseconds. */
|
|
12
|
+
export declare const DEFAULT_TIMEOUT_MS = 60000;
|
|
13
|
+
/** The function that runs a program. The default is `runCommand` of `@procedures/shell`. */
|
|
14
|
+
export type CommandRunner = (command: string, options: CommandOptions) => Promise<CommandResult>;
|
|
15
|
+
/** The options of each render. */
|
|
16
|
+
export interface HeadlessOptions extends FindBrowserOptions {
|
|
17
|
+
/** The path of the output file. The default is a file in a new temporary folder. */
|
|
18
|
+
readonly output?: string | undefined;
|
|
19
|
+
/** More flags for the browser, after the default flags. */
|
|
20
|
+
readonly args?: readonly string[] | undefined;
|
|
21
|
+
/** The time limit, in milliseconds (default: 60000). */
|
|
22
|
+
readonly timeout?: number | undefined;
|
|
23
|
+
/** When the signal aborts, the browser stops. */
|
|
24
|
+
readonly signal?: AbortSignal | undefined;
|
|
25
|
+
/** The function that runs the browser (default: `runCommand`). The tests give their own. */
|
|
26
|
+
readonly runner?: CommandRunner | undefined;
|
|
27
|
+
}
|
|
28
|
+
/** The result of a render. */
|
|
29
|
+
export interface RenderResult {
|
|
30
|
+
/** The absolute path of the output file. */
|
|
31
|
+
readonly path: string;
|
|
32
|
+
/** The size of the output file, in bytes. */
|
|
33
|
+
readonly bytes: number;
|
|
34
|
+
/** The browser program that made the file. */
|
|
35
|
+
readonly browser: string;
|
|
36
|
+
}
|
|
37
|
+
/** The page of a render: an address, an HTML text or the path of an HTML file. */
|
|
38
|
+
export type PageSource = {
|
|
39
|
+
readonly url: string;
|
|
40
|
+
} | {
|
|
41
|
+
readonly html: string;
|
|
42
|
+
} | {
|
|
43
|
+
readonly file: string;
|
|
44
|
+
};
|
|
45
|
+
/** One kind of render: its flags, the name of its file and the check of the file. */
|
|
46
|
+
export interface HeadlessRender {
|
|
47
|
+
/** The start of the name of the temporary folder, for example `procedures-pdf-`. */
|
|
48
|
+
readonly prefix: string;
|
|
49
|
+
/** The name of the file that the browser writes in the temporary folder, for example `page.pdf`. */
|
|
50
|
+
readonly file: string;
|
|
51
|
+
/** The kind of the file in an error, for example `PDF file`. */
|
|
52
|
+
readonly noun: string;
|
|
53
|
+
/** This function gives the argv of the browser: the flags, the extra flags, then the page. */
|
|
54
|
+
argv(page: string, output: string, profile: string, extra: readonly string[]): string[];
|
|
55
|
+
/** This function tells if the file that the browser wrote is a file of this kind. */
|
|
56
|
+
isValid(path: string): boolean;
|
|
57
|
+
}
|
|
58
|
+
/** This function gives the first bytes of a file, at most `count` bytes. */
|
|
59
|
+
export declare function readHead(path: string, count: number): Buffer;
|
|
60
|
+
/**
|
|
61
|
+
* This function starts the browser one time for a render, and gives the path and the size of the
|
|
62
|
+
* file. It throws when it finds no browser, at the time limit and after a cancel. It also throws
|
|
63
|
+
* when the file is missing, empty or not of the kind of the render.
|
|
64
|
+
*
|
|
65
|
+
* An existing output file changes only after the check of the new file. Thus a failed render keeps
|
|
66
|
+
* an old output file.
|
|
67
|
+
*/
|
|
68
|
+
export declare function headlessRender(render: HeadlessRender, source: PageSource, options: HeadlessOptions): Promise<RenderResult>;
|
|
69
|
+
//# sourceMappingURL=run.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEjF,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAEjG,kCAAkC;AAClC,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC7C;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1G,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACxF,qFAAqF;IACrF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS5D;AAcD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAwDhI"}
|
package/dist/run.js
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The headless run of a browser that is already installed. The run starts the browser one time with
|
|
3
|
+
* argv, in a new temporary folder with its own profile. Each render of this package (the PDF file,
|
|
4
|
+
* the screenshot) uses this run, and gives only its flags and the check of its file.
|
|
5
|
+
*
|
|
6
|
+
* The browser starts through `runCommand` of `@procedures/shell`, not through a shell. A time limit
|
|
7
|
+
* and the signal of the call stop its process tree.
|
|
8
|
+
*/
|
|
9
|
+
import { closeSync, copyFileSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
10
|
+
import { tmpdir } from "node:os";
|
|
11
|
+
import { dirname, join, resolve } from "node:path";
|
|
12
|
+
import { pathToFileURL } from "node:url";
|
|
13
|
+
import { runCommand } from "@procedures/shell/command";
|
|
14
|
+
import { BROWSER_ENV, findBrowser } from "./browser.js";
|
|
15
|
+
/** The default time limit of one render, in milliseconds. */
|
|
16
|
+
export const DEFAULT_TIMEOUT_MS = 60_000;
|
|
17
|
+
/** This function gives the first bytes of a file, at most `count` bytes. */
|
|
18
|
+
export function readHead(path, count) {
|
|
19
|
+
const fd = openSync(path, "r");
|
|
20
|
+
try {
|
|
21
|
+
const head = Buffer.alloc(count);
|
|
22
|
+
const read = readSync(fd, head, 0, count, 0);
|
|
23
|
+
return head.subarray(0, read);
|
|
24
|
+
}
|
|
25
|
+
finally {
|
|
26
|
+
closeSync(fd);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
function fileSize(path) {
|
|
30
|
+
try {
|
|
31
|
+
return statSync(path).size;
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
function lastLines(text, count = 5) {
|
|
38
|
+
return text.trim().split(/\r?\n/).slice(-count).join("\n");
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* This function starts the browser one time for a render, and gives the path and the size of the
|
|
42
|
+
* file. It throws when it finds no browser, at the time limit and after a cancel. It also throws
|
|
43
|
+
* when the file is missing, empty or not of the kind of the render.
|
|
44
|
+
*
|
|
45
|
+
* An existing output file changes only after the check of the new file. Thus a failed render keeps
|
|
46
|
+
* an old output file.
|
|
47
|
+
*/
|
|
48
|
+
export async function headlessRender(render, source, options) {
|
|
49
|
+
const browser = findBrowser(options);
|
|
50
|
+
if (browser === undefined) {
|
|
51
|
+
throw new Error(`No browser found. Install Microsoft Edge, Google Chrome or Chromium, or set ${BROWSER_ENV} to the browser program.`);
|
|
52
|
+
}
|
|
53
|
+
const work = mkdtempSync(join(tmpdir(), render.prefix));
|
|
54
|
+
const profile = join(work, "profile");
|
|
55
|
+
const htmlFile = join(work, "page.html");
|
|
56
|
+
const output = resolve(options.output ?? join(work, render.file));
|
|
57
|
+
const written = join(work, render.file);
|
|
58
|
+
let made = false;
|
|
59
|
+
try {
|
|
60
|
+
let page;
|
|
61
|
+
if ("html" in source) {
|
|
62
|
+
writeFileSync(htmlFile, source.html, "utf8");
|
|
63
|
+
page = pathToFileURL(htmlFile).href;
|
|
64
|
+
}
|
|
65
|
+
else if ("file" in source) {
|
|
66
|
+
page = pathToFileURL(resolve(source.file)).href;
|
|
67
|
+
}
|
|
68
|
+
else {
|
|
69
|
+
page = source.url;
|
|
70
|
+
}
|
|
71
|
+
mkdirSync(dirname(output), { recursive: true });
|
|
72
|
+
const run = options.runner ?? runCommand;
|
|
73
|
+
const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
|
|
74
|
+
const result = await run(browser, {
|
|
75
|
+
args: render.argv(page, written, profile, options.args ?? []),
|
|
76
|
+
timeout,
|
|
77
|
+
signal: options.signal,
|
|
78
|
+
maxOutputBytes: 64 * 1024,
|
|
79
|
+
keep: "tail",
|
|
80
|
+
});
|
|
81
|
+
if (result.error !== undefined)
|
|
82
|
+
throw new Error(`The browser did not start: ${result.error}`);
|
|
83
|
+
if (result.timedOut === true)
|
|
84
|
+
throw new Error(`The browser did not finish in ${timeout} ms`);
|
|
85
|
+
if (result.aborted === true)
|
|
86
|
+
throw new Error("The render was cancelled");
|
|
87
|
+
const bytes = fileSize(written);
|
|
88
|
+
if (bytes === undefined || bytes === 0) {
|
|
89
|
+
const detail = lastLines(result.stderr || result.stdout);
|
|
90
|
+
throw new Error(`The browser made no ${render.noun} (exit code ${result.exitCode})${detail ? `: ${detail}` : ""}`);
|
|
91
|
+
}
|
|
92
|
+
if (!render.isValid(written))
|
|
93
|
+
throw new Error(`The file ${output} is not a ${render.noun}`);
|
|
94
|
+
// The temporary folder goes in `finally`, so a copy is enough, also across two drives
|
|
95
|
+
if (written !== output)
|
|
96
|
+
copyFileSync(written, output);
|
|
97
|
+
made = true;
|
|
98
|
+
return { path: output, bytes, browser };
|
|
99
|
+
}
|
|
100
|
+
finally {
|
|
101
|
+
// The temporary page and profile go. A default output stays in its folder after a success.
|
|
102
|
+
if (made && options.output === undefined) {
|
|
103
|
+
rmSync(profile, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
|
|
104
|
+
rmSync(htmlFile, { force: true });
|
|
105
|
+
}
|
|
106
|
+
else {
|
|
107
|
+
rmSync(work, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
//# sourceMappingURL=run.js.map
|
package/dist/run.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A screenshot of a page with a headless Chromium browser that is already installed. The render
|
|
3
|
+
* uses the headless run of `run.ts`. The browser loads the page in a window of the given size, and
|
|
4
|
+
* writes a PNG, JPEG or WebP picture of the window.
|
|
5
|
+
*/
|
|
6
|
+
import { type HeadlessOptions, type RenderResult } from "./run.js";
|
|
7
|
+
/** The formats of a screenshot. The browser chooses the format from the extension of the file. */
|
|
8
|
+
export type ScreenshotFormat = "png" | "jpeg" | "webp";
|
|
9
|
+
/** The size of the window of a screenshot, in CSS pixels. */
|
|
10
|
+
export interface ScreenshotSize {
|
|
11
|
+
readonly width: number;
|
|
12
|
+
readonly height: number;
|
|
13
|
+
}
|
|
14
|
+
/** The default size of the window: a common size of a desktop screen. */
|
|
15
|
+
export declare const DEFAULT_SCREENSHOT_SIZE: ScreenshotSize;
|
|
16
|
+
/** The largest side of the window, in CSS pixels. */
|
|
17
|
+
export declare const MAX_SCREENSHOT_SIDE = 16384;
|
|
18
|
+
/** The extension of the temporary file of each format. */
|
|
19
|
+
export declare const SCREENSHOT_EXTENSIONS: Readonly<Record<ScreenshotFormat, string>>;
|
|
20
|
+
/** The options of `renderScreenshot`. Give one of `url`, `html` and `file`. */
|
|
21
|
+
export interface RenderScreenshotOptions extends HeadlessOptions {
|
|
22
|
+
/** The address of the page: `http`, `https` or `file`. */
|
|
23
|
+
readonly url?: string | undefined;
|
|
24
|
+
/** The HTML text. The function writes it to a temporary file. */
|
|
25
|
+
readonly html?: string | undefined;
|
|
26
|
+
/** The path of an HTML file. */
|
|
27
|
+
readonly file?: string | undefined;
|
|
28
|
+
/** The format. The default is the format of the extension of `output`, else `png`. */
|
|
29
|
+
readonly format?: ScreenshotFormat | undefined;
|
|
30
|
+
/** The size of the window (default: 1280 by 800). */
|
|
31
|
+
readonly size?: ScreenshotSize | undefined;
|
|
32
|
+
/**
|
|
33
|
+
* The virtual time that the scripts and the timers of the page get before the picture, in
|
|
34
|
+
* milliseconds. Without it, the picture follows the load event.
|
|
35
|
+
*/
|
|
36
|
+
readonly budget?: number | undefined;
|
|
37
|
+
}
|
|
38
|
+
/** The result of `renderScreenshot`: the path and the size of the picture, the browser program and the format. */
|
|
39
|
+
export interface RenderScreenshotResult extends RenderResult {
|
|
40
|
+
readonly format: ScreenshotFormat;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* This function gives the format of a screenshot from the option `format` and the extension of
|
|
44
|
+
* the output file. It throws when the extension is not of a format, or when the two disagree.
|
|
45
|
+
*/
|
|
46
|
+
export declare function screenshotFormatOf(output?: string, format?: ScreenshotFormat): ScreenshotFormat;
|
|
47
|
+
/**
|
|
48
|
+
* This function gives the argv of the browser. The argv has the flags of a headless screenshot,
|
|
49
|
+
* the profile folder, the window size and the time budget. The extra flags and the page follow.
|
|
50
|
+
*/
|
|
51
|
+
export declare function screenshotArgs(page: string, output: string, profile: string, size: ScreenshotSize, budget?: number, extra?: readonly string[]): string[];
|
|
52
|
+
/** This function tells if a file starts with the signature of a picture of the format. */
|
|
53
|
+
export declare function isImageFile(path: string, format: ScreenshotFormat): boolean;
|
|
54
|
+
/**
|
|
55
|
+
* This function loads a page in a headless browser, and writes a picture of the window. It gives
|
|
56
|
+
* the path and the size of the file and its format. It throws when it finds no browser, at the time
|
|
57
|
+
* limit, and when the file is not a picture of the format.
|
|
58
|
+
*
|
|
59
|
+
* The page can load each address that it names. Give an address that you trust, or a page of your
|
|
60
|
+
* own.
|
|
61
|
+
*/
|
|
62
|
+
export declare function renderScreenshot(options: RenderScreenshotOptions): Promise<RenderScreenshotResult>;
|
|
63
|
+
//# sourceMappingURL=screenshot.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAA4B,KAAK,eAAe,EAAwC,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAEnI,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,EAAE,cAA6C,CAAC;AAEpF,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAgD,CAAC;AAQ9H,+EAA+E;AAC/E,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,kHAAkH;AAClH,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAO/F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAe5J;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAK3E;AAoBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAexG"}
|