@parcha/pi-browser 0.1.0-beta.35 → 0.1.0-beta.37
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 +19 -0
- package/README.md +20 -25
- package/dist/core/driving-guard.d.ts +1 -1
- package/dist/core/driving-guard.js +1 -1
- package/dist/core/host.d.ts +1 -12
- package/dist/core/images.d.ts +32 -4
- package/dist/core/images.js +81 -16
- package/dist/core/page-scan.d.ts +69 -0
- package/dist/core/page-scan.js +467 -10
- package/dist/core/public-fetch.js +3 -0
- package/dist/core/read-page.js +20 -4
- package/dist/core/tools.js +4 -1
- package/dist/core/vault.d.ts +0 -10
- package/dist/core/vault.js +0 -13
- package/dist/driver/cdp.js +3 -3
- package/dist/driver/page-driver.js +7 -3
- package/dist/durable/store.d.ts +1 -1
- package/dist/durable.d.ts +6 -1
- package/dist/durable.js +24 -5
- package/dist/index.d.ts +1 -0
- package/dist/index.js +3 -0
- package/dist/live-view/index.d.ts +2 -0
- package/dist/live-view/index.js +4 -0
- package/dist/live-view/server.d.ts +11 -0
- package/dist/live-view/server.js +13 -2
- package/dist/providers/cdp.js +2 -2
- package/dist/providers/profiles.d.ts +1 -15
- package/dist/providers/profiles.js +1 -64
- package/dist/providers/shared.d.ts +1 -47
- package/dist/providers/shared.js +1 -82
- package/dist/providers/worker-extension.js +1 -1
- package/dist/testing/backend.d.ts +4 -3
- package/dist/testing/backend.js +6 -5
- package/dist/vault-session.d.ts +4 -7
- package/dist/vault-session.js +26 -81
- package/dist/vendor/browser-use-pi/page.d.ts +3 -12
- package/dist/vendor/browser-use-pi/page.js +6 -19
- package/package.json +7 -20
- package/dist/providers/browserbase-net.d.ts +0 -12
- package/dist/providers/browserbase-net.js +0 -95
- package/dist/providers/browserbase.d.ts +0 -138
- package/dist/providers/browserbase.js +0 -294
- package/dist/providers/kernel.d.ts +0 -58
- package/dist/providers/kernel.js +0 -291
- /package/dist/{providers → core}/cdp-call.d.ts +0 -0
- /package/dist/{providers → core}/cdp-call.js +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,25 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.1.0-beta.37 (2026-11-13)
|
|
6
|
+
|
|
7
|
+
- A run's live view (its browser, desktop or phone, watched and taken over) works when its runner is on another host than the server, as in the compose stack's server and runners. Breaking for a SQLite store: its schema version moves to 9, so a server refuses a SQLite store an earlier version made; start it on a fresh data directory. A Postgres store migrates itself (migration 0007). A runner names the host the server reaches it at (`AGENTRUN_RUNNER_LIVE_HOST`, listening there or on `AGENTRUN_RUNNER_LIVE_BIND`), and each viewer's row in the store carries that host (a new nullable `computer_viewers.host`). The server dials a row's host only when it is one of its runners' (`AGENTRUN_RUNNER_HOSTS`), and signs each request it makes of the viewer with an HMAC under a key derived from the seal key; a runner's viewer off loopback refuses, before any WebSocket, a request with no good, fresh proof for its own viewer, and the viewer's token still decides who watches. The hop between server and runner is plain HTTP, for a private network. With neither setting, every viewer stays on loopback as before. `@parcha/pi-browser`'s `createLiveView` takes `listen` (the address its own server listens on and the host its links name) and `admit` (a host's own check of every page request and upgrade).
|
|
8
|
+
- A desktop's or a phone's screen is watched and taken over live, as the browser's is. The runner opens its view as it claims the run's computer: `openComputerView` (computer-live.ts) starts the computer's viewer on loopback and hands it over in the store under the run's claim (`computer_viewers`, the token sealed); a stale claim is refused `fenced`, and an open that fails is refused `failed` in words with nothing left listening. Its WebSocket speaks the browser viewer's protocol: hello, ready with Take over, the screen's frames (JPEG or PNG) each sent once the viewer acked the one before (a frame held back for a slow viewer is replaced by a newer one, and the replaced frame is acked), and Take over and Hand back through the run's hold, the same take-over and hand-back the routes write. Input is mapped by one `createActionMapper` per take and reaches the computer only while the person holds it, as the run's own hold says at that moment, so input stops as soon as a take ends; otherwise it is answered `held` ("Take over to drive."), and what a desktop refuses (ctrl+alt+F1, ctrl+alt+Backspace) comes back in words. The mouse buttons a take holds are let go when the viewer loses focus, before a hand back, and once when a take ends on the run's side or the viewer goes. One viewer per computer; a viewer that goes mid-take hands the take back (`away`). The runner now journals the hold of every run's desktop or phone (computerForClaim hands it to the run's spec), so `GET /v2/runs/{id}/computer` answers live with `kind` `desktop` or `phone` and who drives, and the viewer's own page (Take over and Hand back; a phone's back, home and recents) is served under `/v2/runs/{id}/computer/live/`, its socket proxied to the runner's endpoint with the same checks as the browser's. `@parcha/pi-browser/live-view` exports its WebSocket server and token helpers for it. A desktop or phone run whose screen is not open answers `GET /v2/runs/{id}/computer` `none` with its kind, no longer `off` with "this run's agent has no computer" (#2170). The viewer types from a phone's or tablet's soft keyboard too (its `beforeinput` text, deletes and Enter), with a desktop's keys still sent once. Under `--faux`, a run on the faux desktop starts and is claimed by the runner (its start check and the runner's claim read `--faux`'s computers beside the package's), and its screen is watched and taken over through this same viewer; the faux desktop's old page under `/faux/desktops/` is gone.
|
|
9
|
+
- The pi family and Chord move from 1.5.0 to 1.5.2 together (pi-ai, pi-agent-core, pi-coding-agent, pi-codemode, pi-durable, chord). Pi's model catalog now lists `claude-fable-5-2`, so a pi run can use it. Chord's package root no longer exports `Context` or `JsonValue`; they come from `@earendil-works/chord/context` and `@earendil-works/chord/json`, which a host that imports them from the root must follow.
|
|
10
|
+
- `web_fetch`'s text (a page read directly, `readPage`) leaves out what the page hides from everyone who reads it: an element with the `hidden` attribute, an inline `display:none` or `visibility:hidden`, a closed `<dialog>`, a class the page's own `<style>` sets to `display:none` or `visibility:hidden`, and the common pop-up and display-none utility classes (`mfp-hide`, `modal`, `d-none`, `hidden`, `hide`, `invisible`, `is-hidden`, `u-hidden`). A record page's help pop-ups, hidden until a click, were read as the record, so an agent took their boilerplate ("notice of intent to dissolve") for the company's own. Text only a screen reader reads (`sr-only`, `visually-hidden`, `wb-inv`, `screen-reader-text`) and text marked `aria-hidden` stay in the text: each is shown to someone. Only the page's live style elements count (none in a comment, a script, a template or a noscript, and only those for the screen); a later declaration or rule that shows the element wins (inline over a class, an author `display` over the `hidden` attribute), and where the outcome is unclear (an `!important` mix, classes in conflict, a class a compound selector shows) the text is kept. An element hidden by visibility alone is kept whole when anything shown inside it is set visible again (visibility is inherited and a descendant can override it; one that is itself, or sits inside, a `display:none` element shows nothing); `display:none` is not, so its element always goes. A class or style value is read with its character references decoded. A hidden element that no end tag closes is still read. Pages read through Parallel's extract are unchanged.
|
|
11
|
+
|
|
12
|
+
## 0.1.0-beta.36 (2026-11-13)
|
|
13
|
+
|
|
14
|
+
- The browser tool has one stack: whether the agent's computer is a browser or the tool plane picks the vendor, every session is a browser computer of the computer registry's providers, made at the tool's call under the run's labels, and pi-browser's raw-CDP driver (`cdpDriver()`) drives it. Stagehand drives no run's browser now. Breaking: Browserbase and Kernel browsers now refuse run code and file uploads (browser_upload), and their snapshot is the raw-CDP list; every browser computer uses one driver. Breaking: pi-browser's `./providers/browserbase` and `./providers/kernel` exports and its `@browserbasehq/sdk` peer dependency are gone (a hosted browser is a browser computer provider of `@parcha/agentrun-computer`), and so are Browserbase's and Kernel's `create(spec, { settings })` vendor-field bag and its `BrowserbaseSessionSettings` and `KernelBrowserSettings` types (put a session's options in `spec.browser`).
|
|
15
|
+
- `@parcha/agentrun-computer`: a browser's own options ride the spec, `spec.browser` (`viewport`, `profile: { pointer, save }`, `stealth`, `headless`), and `capabilities().browser` declares what a provider's sessions offer (`timeout`, `profiles: { settleMs }`, `stealth`, `headless`, `downloads: { path }`). `check()` refuses an option the provider does not declare, in words. Browserbase and Kernel gain the optional `profiles { create, remove }` member, and Browserbase `downloads { list, read }`. Local Chrome declares `{ timeout: "wall-clock" }` and opens its window at the spec's viewport.
|
|
16
|
+
- `@parcha/pi-browser`: `ProviderCaps` is `profiles`, `sharedBrowser`, `settings`, `fixedSession` and `navigationAllow`; the session vault keeps a local Chrome's sessions alone. `cdpCall` is exported from the package root.
|
|
17
|
+
- agentrun-serve: on Browserbase and Kernel, the browser tool's `run` now takes actions only, as it does on Local Chrome (code is refused in words, and navigation is a `goto` action), its `snapshot` is the raw-CDP driver's, and `browser_upload` is refused (the driver sets no file input). A session carries the run's labels and its custody tag, as an agent's browser computer's does.
|
|
18
|
+
- `ScreenshotOptions.scale` (and `FakeScreenshotOptions.scale`) is a number, the fraction of the device-pixel capture to take, in place of `"css" | "device"`; a driver that passed `scale: "css"` passes `1 / devicePixelRatio`, and a custom `PageDriver.screenshot` honors a number below 1, else `captureWithinBudget` throws `ScreenshotBudgetError` for a capture over budget that it does not take smaller.
|
|
19
|
+
|
|
20
|
+
A screenshot over the 2,000 px long edge now shrinks to fit (CDP `clip.scale`) before its JPEG quality drops, so a long page on a device scale of 2 (stripe.com/pricing, a 2576x1248 viewport) comes back as a 1977x969 viewport in place of `ScreenshotBudgetError`; a full page whose fit would leave its short edge under 600 px is taken as the viewport, and the error is left for a browser that gives no capture that fits. On the runner, an image block in a tool's answer whose data is a PNG, JPEG, GIF or WebP of the type it names, with no held key in its bytes, is no longer cut to `[redacted]` by the run's key cut (any other `data` is cut as before) (which sent the model a `data:image/png;base64,[redacted]` URL and failed the run with a 400), and every image a model request carries is checked where it is attached: one with an unknown type, no data, data that is not base64, bytes of another type or a header that does not say its size goes as `[the image could not be attached: <why>]`.
|
|
21
|
+
- A run that asks its person a question with its browser open keeps that browser while it waits, for the person's window, `AGENTRUN_BROWSER_PERSON_WAIT_MIN` (15 minutes by default; the same setting now bounds a take-over with no input and an agent's hand-over ask). Before, the browser's own 3-minute idle release let it go while the run waited, so the page, the live view and Take over were gone just when the person might use them. At the window's end the browser is released with a timeline row saying so ("The browser was released after 15 min waiting for you"), and an answer after that opens a new browser. The Screen tab says the browser was released, and when, instead of "Waiting for the browser" (GET /v2/runs/{id}/computer's `none` carries `ended: {at, why}`). pi-browser's extension handle gains `keepForPerson(tag)`, which holds a session from its idle release until let go.
|
|
22
|
+
- The server and Pi browser READMEs state the Node minimum the packages enforce: 24.22.3 (the server image and the test suites run on it), not Node 22.
|
|
23
|
+
|
|
5
24
|
## 0.1.0-beta.35 (2026-11-11)
|
|
6
25
|
|
|
7
26
|
- The `use_website` tool is removed from the durable adapter: no host passed `sites`. Gone with it: `createBrowserExtension`'s `sites` option, the handle's `docs.Children`, the root exports `useWebsite`, `useWebsiteContract` and `localSites`, and the types `SiteInfo`, `SiteRunPort` and `ChildRunner`. A host that wants an agent to hand a task to another agent runs that agent itself.
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Your agent gets its own browser, and you can take over and hand it back.
|
|
4
4
|
|
|
5
|
-
- **Its own browser.** The agent drives a Chrome of its own: a local Chrome, Browserbase
|
|
5
|
+
- **Its own browser.** The agent drives a Chrome of its own: a local Chrome, or a hosted browser its host provides (agentrun-serve's Browserbase and Kernel, through its computer providers). It reads pages, clicks, types and takes screenshots. A local Chrome needs no key.
|
|
6
6
|
- **You can take over and hand it back.** A host mounts the live view in a few lines, and then a person sees the agent's page, uses the mouse and keys, and lets the agent go on. While the person is driving, the agent's browser calls are refused. The agent can also ask a person for a step only a person can do, and wait for the answer. See [Take over and hand back](#take-over-and-hand-back). For now, use the live view with test accounts on practice sites only: the model's own page code can read what a person types there.
|
|
7
7
|
- **Credentials you register stay out of what the model sees.** Credentials you register, and keys of the common shapes, are replaced with `[redacted]` in every tool result, failure, filed page and log. See [Credentials](#credentials).
|
|
8
8
|
- **Every page the agent reads is filed as evidence.** The file holds the page's URL, its title and its SHA-256.
|
|
@@ -10,7 +10,7 @@ Your agent gets its own browser, and you can take over and hand it back.
|
|
|
10
10
|
|
|
11
11
|
If the process dies, a pi-durable host recovers the session and does not repeat an action. See [For hosts](#for-hosts).
|
|
12
12
|
|
|
13
|
-
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=24.22.3`, pi 1.5.
|
|
13
|
+
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=24.22.3`, pi 1.5.2 exactly (its
|
|
14
14
|
pi-durable and chord peers). ESM only: the
|
|
15
15
|
package has `import` entries and no `require` entry.
|
|
16
16
|
|
|
@@ -18,7 +18,7 @@ package has `import` entries and no `require` entry.
|
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
20
|
npm install @parcha/pi-browser@latest # the library: providers, driver, durable adapter
|
|
21
|
-
npm install @parcha/pi-browser@latest @earendil-works/pi-durable@1.5.
|
|
21
|
+
npm install @parcha/pi-browser@latest @earendil-works/pi-durable@1.5.2 @earendil-works/chord@1.5.2 @earendil-works/pi-ai@1.5.2 # a pi-durable host: its peers, pinned to 1.5.2
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
## Quick start
|
|
@@ -76,23 +76,23 @@ It prints the page's accessibility tree, the same text `snapshot` gives a model:
|
|
|
76
76
|
|
|
77
77
|
## Demos
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
Two runnable demos live in `examples/` in the repository. They are not in the npm package. Build once with `npm ci && npm run build`, then run one from the repository root. Each needs Chrome or Chromium (`CHROME_PATH` names it) except where it says otherwise.
|
|
80
80
|
|
|
81
81
|
| Demo | Run | What it shows |
|
|
82
82
|
|---|---|---|
|
|
83
|
-
| [`examples/one-script-three-providers.mjs`](examples/one-script-three-providers.mjs) | `node packages/pi-browser/examples/one-script-three-providers.mjs https://example.com` | The same script on a local Chrome, Browserbase or Kernel. `PI_BROWSER_PROVIDER=browserbase` needs `BROWSERBASE_API_KEY` and the Browserbase SDK; `kernel` needs `KERNEL_API_KEY`. The tests run the local Chrome path only. |
|
|
84
83
|
| [`examples/hold-an-irreversible-action.mjs`](examples/hold-an-irreversible-action.mjs) | `node packages/pi-browser/examples/hold-an-irreversible-action.mjs` | Under the `ask` policy a form post is held until a person approves it. The demo refuses, and the local server it posts to counts zero requests. |
|
|
85
84
|
| [`examples/crash-and-resume.mjs`](examples/crash-and-resume.mjs) | `node packages/pi-browser/examples/crash-and-resume.mjs`, twice | The first run sets a page title and kills itself with SIGKILL between two tool calls. The second recovers the same Chrome from the run's own store and reads the title back. A scripted model stands in for a real one. It uses the pi-durable packages the repository already installs. Delete `$TMPDIR/pi-browser-crash-demo` to start over. |
|
|
86
85
|
|
|
87
86
|
## Providers
|
|
88
87
|
|
|
89
|
-
The same tools run on
|
|
88
|
+
The same tools run on any browser a `BrowserProvider` gives. The package carries the local one; a hosted browser is the
|
|
89
|
+
host's, through a provider of its own (agentrun-serve drives Browserbase and Kernel through its computer providers, so the
|
|
90
|
+
package names no vendor).
|
|
90
91
|
|
|
91
92
|
| Provider | What it is | What it needs |
|
|
92
93
|
|---|---|---|
|
|
93
94
|
| Local Chrome (`/providers/cdp`) | A Chrome the package starts and stops by exact pid, with its own profile directory and a free debugging port. It can also attach to a Chrome you already run, at a CDP endpoint. | Chrome or Chromium 137 or later. No key. |
|
|
94
|
-
|
|
|
95
|
-
| Kernel (`/providers/kernel`) | A Kernel browser, through its REST API. | `KERNEL_API_KEY`. No SDK. |
|
|
95
|
+
| A host's own (`BrowserProvider`, `core/host.ts`) | Any browser that answers CDP: the host makes, finds and releases its sessions and hands over a CDP URL. | Whatever the host's vendor needs. |
|
|
96
96
|
|
|
97
97
|
The local Chrome's options, in `cdpProvider({ chrome: { ... } })`:
|
|
98
98
|
|
|
@@ -103,7 +103,7 @@ The local Chrome's options, in `cdpProvider({ chrome: { ... } })`:
|
|
|
103
103
|
| `args` | Extra Chrome flags, added after the package's own. |
|
|
104
104
|
| `sandbox` | Chrome's own sandbox, on unless `false`. When absent, `PI_BROWSER_NO_SANDBOX=1` turns it off. Turn it off only where Chrome cannot start its sandbox (root, a container, restricted user namespaces), and only for pages you trust. A Chrome that exits before it opens its debugging port fails the create with its last lines of stderr, and with this hint when it aborted or named the sandbox. |
|
|
105
105
|
|
|
106
|
-
A host passes the provider it wants; see [For hosts](#for-hosts).
|
|
106
|
+
A host passes the provider it wants; see [For hosts](#for-hosts).
|
|
107
107
|
|
|
108
108
|
## Take over and hand back
|
|
109
109
|
|
|
@@ -187,12 +187,11 @@ This section says where a profile's state lives. A host can ask for a browser pr
|
|
|
187
187
|
Where the profile lives:
|
|
188
188
|
|
|
189
189
|
- **Local Chrome:** a directory `.profiles/<name>` under the profile root you give the provider. A session that saves runs on that directory. A session that does not save runs on a copy, and the profile stays as it was.
|
|
190
|
-
- **
|
|
191
|
-
- **Kernel:** a Kernel profile of that name, created if it is not there.
|
|
190
|
+
- **A host's provider:** wherever its vendor keeps one (agentrun-serve opens a vendor's saved profile by the pointer it holds for the run's sign-in).
|
|
192
191
|
|
|
193
192
|
It is never your own browser's profile.
|
|
194
193
|
|
|
195
|
-
One session at a time may save to a profile in one process. A second saver is refused, and the message says why. Across processes, the last session to end wins.
|
|
194
|
+
One session at a time may save to a profile in one process. A second saver is refused, and the message says why. Across processes, the last session to end wins.
|
|
196
195
|
|
|
197
196
|
|
|
198
197
|
## The tools
|
|
@@ -259,9 +258,8 @@ Stagehand, undici, zod and the two HTML packages are dependencies. Three optiona
|
|
|
259
258
|
| Peer | Needed for |
|
|
260
259
|
|---|---|
|
|
261
260
|
| `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
|
|
262
|
-
| `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
|
|
263
261
|
|
|
264
|
-
The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.
|
|
262
|
+
The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.2` exactly. CI tests pi 1.5.2.
|
|
265
263
|
|
|
266
264
|
## Entries
|
|
267
265
|
|
|
@@ -284,7 +282,9 @@ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly. CI te
|
|
|
284
282
|
sealed: no inference, no cache, and no trace endpoint, so no trace is exported. Stagehand attaches one client to a browser
|
|
285
283
|
at a time: closing a driver disconnects it, so the next attach is allowed.
|
|
286
284
|
- `/driver/cdp`: `cdpDriver()`, the driver of every AgentRun browser computer (Browserbase's, Kernel's, or the computer
|
|
287
|
-
package's `local-chrome` provider's Chrome on this machine), over its CDP URL.
|
|
285
|
+
package's `local-chrome` provider's Chrome on this machine), over its CDP URL. Browserbase and Kernel browsers now
|
|
286
|
+
refuse run code and file uploads (`browser_upload`), and their snapshot is the raw-CDP list; every browser computer
|
|
287
|
+
uses one driver, this one, which runs no code and sets no file input. It is raw CDP: no Stagehand, and nothing loaded into the browser. `snapshot` is Chrome's
|
|
288
288
|
accessibility tree with the same "frame-node" ids (`[0-42]`: the frame's place, then Chrome's backend node id). `run`
|
|
289
289
|
takes actions only. Each action is scrolled into view, hit-tested at its centre, and pressed and released there, or
|
|
290
290
|
typed with inserted text and a real last key. Each answers one line: `[ok] click [0-42] button "Add" -> page changed`
|
|
@@ -292,9 +292,8 @@ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly. CI te
|
|
|
292
292
|
`{"op":"goto","url":"https://..."}`. A frame another site runs in its own process (a cross-origin iframe) is not read:
|
|
293
293
|
the snapshot names each one it left out. Adapted from Browser Use Pi's `ax.ts`, `cdp.ts` and `page.ts` under its MIT
|
|
294
294
|
license, in `src/vendor/browser-use-pi/` (see NOTICE and that folder's `UPSTREAM.json`).
|
|
295
|
-
- `/providers/
|
|
296
|
-
|
|
297
|
-
Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
|
|
295
|
+
- `/providers/cdp`: where the package's own browsers come from: any CDP endpoint, or a local Chrome the provider starts and
|
|
296
|
+
kills by exact pid. A hosted browser is the host's provider (agentrun-serve's, over its computer providers).
|
|
298
297
|
- `/providers/chrome-args`: `chromeArgs()`, the arguments the cdp provider starts a local Chrome with, and `extensionOrigin()`,
|
|
299
298
|
the one Origin its DevTools socket allows (Stagehand's extension). A host that starts its own Chrome for Stagehand takes them
|
|
300
299
|
from here rather than copying Stagehand's `--remote-allow-origins=*`. `findChrome()` finds the Chrome to start: the one
|
|
@@ -334,8 +333,8 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
|
|
|
334
333
|
`createBrowserExtension` takes no key and sends nothing anywhere but the provider you give it. The options:
|
|
335
334
|
|
|
336
335
|
- `driver`: `stagehandDriver()`, or your own `DriverFactory`.
|
|
337
|
-
- `provider`:
|
|
338
|
-
|
|
336
|
+
- `provider`: the local Chrome (`cdpProvider`), or your own `BrowserProvider` over a hosted vendor, with your own metadata
|
|
337
|
+
stamped on every session.
|
|
339
338
|
- `evidence`: a sink that files each read where your receipts already are.
|
|
340
339
|
- `onSession`: the host channel. It receives each session's row and, only there, the live-view URLs. Nothing in the run log, a
|
|
341
340
|
result or a log line carries them.
|
|
@@ -389,10 +388,6 @@ Two things to know before you give a model a browser:
|
|
|
389
388
|
|
|
390
389
|
- **What a model may reach is your decision.** `publicFetch` refuses private addresses, but a driven browser goes
|
|
391
390
|
wherever its network goes. A host that must not let a model reach internal addresses restricts that network or the URLs it passes.
|
|
392
|
-
- **The Browserbase provider changes the process.** Its first call that needs the Browserbase client adds Browserbase's hosts to `NO_PROXY` and `no_proxy`, and
|
|
393
|
-
the first attach replaces `globalThis.WebSocket` with a wrapper that dials a bound credential proxy instead of the raw
|
|
394
|
-
connect URL. Both are process-wide. The wrapper passes every other URL through unchanged. Importing the package does
|
|
395
|
-
neither.
|
|
396
391
|
|
|
397
392
|
## Development
|
|
398
393
|
|
|
@@ -406,7 +401,7 @@ The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-ch
|
|
|
406
401
|
`readme_example`) skip with a typed reason where no Chrome can load Stagehand's extension, and fail instead under
|
|
407
402
|
`AGENTRUN_REQUIRE_LOCAL_CHROME=1`, which CI sets. The crash matrix (`test/custody.test.mjs`) SIGKILLs a child process at each
|
|
408
403
|
cut point of a session's life against the shared fake and reopens the run's SQLite file. The wire checks (`test/wire/`) plant
|
|
409
|
-
sentinel credentials in a fake provider and scan every byte a run produced. The suites run on Node 22
|
|
404
|
+
sentinel credentials in a fake provider and scan every byte a run produced. The suites run on Node 24.22.3, the minimum the package supports.
|
|
410
405
|
|
|
411
406
|
Apache-2.0. Copyright 2026 Parcha Labs, Inc. `NOTICE` records the Stagehand (MIT) code this package copies: the Chrome launch
|
|
412
407
|
flags and the vendored facade.
|
|
@@ -10,7 +10,7 @@ export declare const PERSON_HAD = "This call waited while the person had the bro
|
|
|
10
10
|
export declare const PERSON_HAD_UNUSED = "This call waited while the person had the browser: they took it over through the live view and handed it back without using it, so the page is as you left it.";
|
|
11
11
|
/** The mark (in a call's result details) of an act the person's take made stale: the person drove the session through the
|
|
12
12
|
* live view while the call waited, so the snapshot its element ids came from no longer stands. Its timeline row reads
|
|
13
|
-
* neutral, in plain words (
|
|
13
|
+
* neutral, in plain words (serve's timeline), never as a failure. */
|
|
14
14
|
export declare const PAGE_CHANGED_WHILE_HELD = "page_changed_while_held";
|
|
15
15
|
/** Told to the model by such an act: nothing was done, and its next step is a snapshot. */
|
|
16
16
|
export declare const PAGE_CHANGED_FOR_MODEL = "The person changed the page while they had the browser, so this action was not done. Take a snapshot first, then act on the page as it is now.";
|
|
@@ -10,7 +10,7 @@ export const PERSON_HAD = "This call waited while the person had the browser: th
|
|
|
10
10
|
export const PERSON_HAD_UNUSED = "This call waited while the person had the browser: they took it over through the live view and handed it back without using it, so the page is as you left it.";
|
|
11
11
|
/** The mark (in a call's result details) of an act the person's take made stale: the person drove the session through the
|
|
12
12
|
* live view while the call waited, so the snapshot its element ids came from no longer stands. Its timeline row reads
|
|
13
|
-
* neutral, in plain words (
|
|
13
|
+
* neutral, in plain words (serve's timeline), never as a failure. */
|
|
14
14
|
export const PAGE_CHANGED_WHILE_HELD = "page_changed_while_held";
|
|
15
15
|
/** Told to the model by such an act: nothing was done, and its next step is a snapshot. */
|
|
16
16
|
export const PAGE_CHANGED_FOR_MODEL = "The person changed the page while they had the browser, so this action was not done. Take a snapshot first, then act on the page as it is now.";
|
package/dist/core/host.d.ts
CHANGED
|
@@ -92,12 +92,8 @@ export type AttachTarget = {
|
|
|
92
92
|
extensionCdpUrl?: string;
|
|
93
93
|
};
|
|
94
94
|
export type ProviderCaps = {
|
|
95
|
-
|
|
96
|
-
maxLifetimeS: number;
|
|
97
|
-
survivesDisconnect: boolean;
|
|
98
|
-
releaseIsAsync: boolean;
|
|
95
|
+
/** The provider can open a session on a saved sign-in (`SessionSpec.profile`); without it such a session is refused. */
|
|
99
96
|
profiles: boolean;
|
|
100
|
-
extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
|
|
101
97
|
/** Every session attaches to the same browser (an endpoint the host named), so two at once would drive the same pages. */
|
|
102
98
|
sharedBrowser?: boolean;
|
|
103
99
|
/** The session settings this provider applies; a setting left out is applied. */
|
|
@@ -140,13 +136,6 @@ export type RemoteFile = {
|
|
|
140
136
|
/** What a session vault may keep of this provider's sessions. Absent: nothing (a browser the package cannot read, or one the host shares). */
|
|
141
137
|
export type ProviderVault = {
|
|
142
138
|
kind: "cdp";
|
|
143
|
-
} | {
|
|
144
|
-
kind: "context";
|
|
145
|
-
provider: "browserbase" | "kernel";
|
|
146
|
-
/** True when this provider writes the context ids it makes to a clear file: a vault refuses such a provider, so an id never lands outside it. */
|
|
147
|
-
contextIdsInClear: boolean;
|
|
148
|
-
/** The context or profile this session runs on, or null. A capability: it goes to the host's vault only. */
|
|
149
|
-
contextOf(ref: LeaseRef): string | null;
|
|
150
139
|
};
|
|
151
140
|
export interface BrowserProvider {
|
|
152
141
|
readonly name: string;
|
package/dist/core/images.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
export declare const SCREENSHOT_MAX_EDGE_PX = 2000;
|
|
2
2
|
export declare const SCREENSHOT_MAX_BASE64_BYTES = 900000;
|
|
3
|
+
/** A full page shrunk to the long edge that would be narrower than this (its short edge) is unreadable: the viewport is
|
|
4
|
+
* taken in its place. */
|
|
5
|
+
export declare const SCREENSHOT_MIN_SHORT_EDGE_PX = 600;
|
|
3
6
|
export type ImageSize = {
|
|
4
7
|
type: "png" | "jpeg";
|
|
5
8
|
width: number;
|
|
@@ -13,12 +16,13 @@ export type Clip = {
|
|
|
13
16
|
width: number;
|
|
14
17
|
height: number;
|
|
15
18
|
};
|
|
16
|
-
/** `
|
|
19
|
+
/** `clip` captures that region alone, `fullPage` the whole document. `scale` is the image's size as a share of the
|
|
20
|
+
* browser's own capture of the same region (its device pixels): 0.5 is half as wide and half as high; absent, 1. */
|
|
17
21
|
export type ScreenshotOptions = {
|
|
18
22
|
fullPage?: boolean;
|
|
19
23
|
type?: "png" | "jpeg";
|
|
20
24
|
quality?: number;
|
|
21
|
-
scale?:
|
|
25
|
+
scale?: number;
|
|
22
26
|
clip?: Clip;
|
|
23
27
|
};
|
|
24
28
|
export type Capture = (options: ScreenshotOptions) => Promise<{
|
|
@@ -31,14 +35,38 @@ export type BudgetedScreenshot = {
|
|
|
31
35
|
size: ImageSize;
|
|
32
36
|
options: ScreenshotOptions;
|
|
33
37
|
adjusted: {
|
|
34
|
-
why: "long_edge" | "base64_bytes";
|
|
38
|
+
why: "long_edge" | "base64_bytes" | "unreadable";
|
|
35
39
|
first: ImageSize | null;
|
|
36
40
|
} | null;
|
|
37
41
|
};
|
|
42
|
+
/** What CDP's Page.getLayoutMetrics says of a page, in CSS pixels: where the viewport is scrolled to and its size, and
|
|
43
|
+
* the whole document's size. */
|
|
44
|
+
export type Layout = {
|
|
45
|
+
cssVisualViewport: {
|
|
46
|
+
pageX: number;
|
|
47
|
+
pageY: number;
|
|
48
|
+
clientWidth: number;
|
|
49
|
+
clientHeight: number;
|
|
50
|
+
};
|
|
51
|
+
cssContentSize: {
|
|
52
|
+
width: number;
|
|
53
|
+
height: number;
|
|
54
|
+
};
|
|
55
|
+
};
|
|
56
|
+
/** CDP's Page.captureScreenshot parameters for `options` on a page laid out as `layout`. Chrome scales a clip alone, its
|
|
57
|
+
* image `clip.scale` times its device pixels: a clip (from the viewport) is moved to the document, a full page is the
|
|
58
|
+
* document's clip captured beyond the viewport, and a scaled viewport is the viewport's own clip. */
|
|
59
|
+
export declare function captureParams(options: ScreenshotOptions, layout: Layout): Record<string, unknown>;
|
|
38
60
|
export declare class ScreenshotBudgetError extends Error {
|
|
39
61
|
name: string;
|
|
40
62
|
}
|
|
41
|
-
/**
|
|
63
|
+
/**
|
|
64
|
+
* A capture as requested, held to the budget. Over the long edge, the same region is retaken scaled to fit it (a full
|
|
65
|
+
* page that would come out narrower than SCREENSHOT_MIN_SHORT_EDGE_PX is the viewport instead, itself scaled to fit);
|
|
66
|
+
* over the byte budget, as a JPEG at quality 40, 25 and 10 (at most the requested quality), then smaller still. A capture
|
|
67
|
+
* whose size cannot be read is retaken once as a viewport JPEG. Throws ScreenshotBudgetError only when no capture it can
|
|
68
|
+
* measure is made, or none fits within MAX_CAPTURES.
|
|
69
|
+
*/
|
|
42
70
|
export declare function captureWithinBudget(capture: Capture, requested: ScreenshotOptions, budget?: {
|
|
43
71
|
maxEdgePx: number;
|
|
44
72
|
maxBase64Bytes: number;
|
package/dist/core/images.js
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
// Tool images are stored verbatim and resent on every later request, and routes reject oversize ones: a capture is held
|
|
2
|
-
// to a long edge and a base64 size
|
|
2
|
+
// to a long edge and a base64 size, by shrinking its pixels and then its JPEG quality, never by failing while a capture
|
|
3
|
+
// can be made.
|
|
3
4
|
export const SCREENSHOT_MAX_EDGE_PX = 2_000;
|
|
4
5
|
export const SCREENSHOT_MAX_BASE64_BYTES = 900_000;
|
|
6
|
+
/** A full page shrunk to the long edge that would be narrower than this (its short edge) is unreadable: the viewport is
|
|
7
|
+
* taken in its place. */
|
|
8
|
+
export const SCREENSHOT_MIN_SHORT_EDGE_PX = 600;
|
|
5
9
|
const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
|
|
6
10
|
/** JPEG start-of-frame markers; C4 (DHT), C8 (JPG) and CC (DAC) are not frames. */
|
|
7
11
|
const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
|
|
@@ -34,27 +38,88 @@ export function imageSize(bytes) {
|
|
|
34
38
|
}
|
|
35
39
|
return null;
|
|
36
40
|
}
|
|
41
|
+
/** CDP's Page.captureScreenshot parameters for `options` on a page laid out as `layout`. Chrome scales a clip alone, its
|
|
42
|
+
* image `clip.scale` times its device pixels: a clip (from the viewport) is moved to the document, a full page is the
|
|
43
|
+
* document's clip captured beyond the viewport, and a scaled viewport is the viewport's own clip. */
|
|
44
|
+
export function captureParams(options, layout) {
|
|
45
|
+
const format = options.type ?? "png";
|
|
46
|
+
const scale = options.scale ?? 1;
|
|
47
|
+
const view = layout.cssVisualViewport;
|
|
48
|
+
const region = options.clip ? { ...options.clip, x: options.clip.x + view.pageX, y: options.clip.y + view.pageY }
|
|
49
|
+
: options.fullPage ? { x: 0, y: 0, width: Math.ceil(layout.cssContentSize.width), height: Math.ceil(layout.cssContentSize.height) }
|
|
50
|
+
: scale !== 1 ? { x: view.pageX, y: view.pageY, width: view.clientWidth, height: view.clientHeight }
|
|
51
|
+
: null;
|
|
52
|
+
return {
|
|
53
|
+
format,
|
|
54
|
+
// CDP takes a quality for jpeg only, and only as an integer.
|
|
55
|
+
...(format === "jpeg" && options.quality !== undefined ? { quality: Math.round(options.quality) } : {}),
|
|
56
|
+
...(options.fullPage && !options.clip ? { captureBeyondViewport: true } : {}),
|
|
57
|
+
...(region ? { clip: { ...region, scale } } : {}),
|
|
58
|
+
};
|
|
59
|
+
}
|
|
37
60
|
export class ScreenshotBudgetError extends Error {
|
|
38
61
|
name = "ScreenshotBudgetError";
|
|
39
62
|
}
|
|
40
|
-
/**
|
|
63
|
+
/** The most captures one screenshot takes before it gives up. */
|
|
64
|
+
const MAX_CAPTURES = 12;
|
|
65
|
+
const QUALITIES = [40, 25, 10];
|
|
66
|
+
/**
|
|
67
|
+
* A capture as requested, held to the budget. Over the long edge, the same region is retaken scaled to fit it (a full
|
|
68
|
+
* page that would come out narrower than SCREENSHOT_MIN_SHORT_EDGE_PX is the viewport instead, itself scaled to fit);
|
|
69
|
+
* over the byte budget, as a JPEG at quality 40, 25 and 10 (at most the requested quality), then smaller still. A capture
|
|
70
|
+
* whose size cannot be read is retaken once as a viewport JPEG. Throws ScreenshotBudgetError only when no capture it can
|
|
71
|
+
* measure is made, or none fits within MAX_CAPTURES.
|
|
72
|
+
*/
|
|
41
73
|
export async function captureWithinBudget(capture, requested, budget = { maxEdgePx: SCREENSHOT_MAX_EDGE_PX, maxBase64Bytes: SCREENSHOT_MAX_BASE64_BYTES }) {
|
|
42
74
|
const ceiling = requested.type === "png" ? 40 : (requested.quality ?? 40);
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
const attempts = ladder.filter((o, i) => ladder.findIndex((other) => key(other) === key(o)) === i);
|
|
49
|
-
let adjusted = null;
|
|
50
|
-
for (const options of attempts) {
|
|
75
|
+
// The clip and the scale asked are kept on every capture; a retake only scales further down.
|
|
76
|
+
const clip = { ...(requested.clip ? { clip: requested.clip } : {}), ...(requested.scale === undefined ? {} : { scale: requested.scale }) };
|
|
77
|
+
let taken = 0;
|
|
78
|
+
const take = async (options) => {
|
|
79
|
+
taken += 1;
|
|
51
80
|
const image = await capture(options);
|
|
52
81
|
const size = imageSize(Buffer.from(image.data, "base64"));
|
|
53
|
-
const why = size === null
|
|
54
|
-
:
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
82
|
+
const why = size === null ? "unreadable"
|
|
83
|
+
: Math.max(size.width, size.height) > budget.maxEdgePx ? "long_edge"
|
|
84
|
+
: Buffer.byteLength(image.data, "utf8") > budget.maxBase64Bytes ? "base64_bytes" : null;
|
|
85
|
+
return { image, size, why, options };
|
|
86
|
+
};
|
|
87
|
+
const fit = (size) => budget.maxEdgePx / Math.max(size.width, size.height);
|
|
88
|
+
const viewport = (options) => ({ fullPage: false, type: "jpeg", quality: Math.min(ceiling, options.type === "jpeg" ? options.quality ?? 40 : 40), ...clip });
|
|
89
|
+
let shot = await take({ fullPage: requested.fullPage ?? false, type: requested.type ?? "jpeg", ...(requested.type === "png" ? {} : { quality: ceiling }), ...clip });
|
|
90
|
+
const adjusted = shot.why === null ? null : { why: shot.why, first: shot.size };
|
|
91
|
+
if (shot.why === "unreadable")
|
|
92
|
+
shot = await take(viewport(shot.options));
|
|
93
|
+
// A full page that fits only narrower than a page can be read: the viewport, which the steps below fit.
|
|
94
|
+
if (shot.why === "long_edge" && shot.options.fullPage && shot.size && Math.min(shot.size.width, shot.size.height) * fit(shot.size) < SCREENSHOT_MIN_SHORT_EDGE_PX) {
|
|
95
|
+
shot = await take(viewport(shot.options));
|
|
96
|
+
}
|
|
97
|
+
while (shot.why !== null) {
|
|
98
|
+
if (shot.why === "unreadable" || !shot.size)
|
|
99
|
+
throw new ScreenshotBudgetError("The browser's capture is not a PNG or JPEG whose size can be read, and a viewport JPEG retake is not either.");
|
|
100
|
+
if (taken >= MAX_CAPTURES)
|
|
101
|
+
throw new ScreenshotBudgetError(`No capture fits ${budget.maxEdgePx} px on its long edge and ${budget.maxBase64Bytes} base64 bytes after ${taken} captures; the last was ${shot.size.width}x${shot.size.height}.`);
|
|
102
|
+
const { options, size } = shot;
|
|
103
|
+
const scale = options.scale ?? 1;
|
|
104
|
+
let next;
|
|
105
|
+
if (shot.why === "long_edge") {
|
|
106
|
+
next = { ...options, scale: scale * fit(size) };
|
|
107
|
+
}
|
|
108
|
+
else {
|
|
109
|
+
const quality = options.type === "png" ? undefined : options.quality ?? 40;
|
|
110
|
+
const lower = QUALITIES.map((q) => Math.min(ceiling, q)).find((q) => quality === undefined || q < quality);
|
|
111
|
+
// Its bytes go roughly with its area: a scale that takes them to nine tenths of the budget.
|
|
112
|
+
const smaller = scale * Math.min(0.9, 0.9 * Math.sqrt(budget.maxBase64Bytes / Buffer.byteLength(shot.image.data, "utf8")));
|
|
113
|
+
next = lower !== undefined ? { ...options, type: "jpeg", quality: lower } : { ...options, scale: smaller };
|
|
114
|
+
}
|
|
115
|
+
shot = await take(next);
|
|
116
|
+
// A driver that does not take the scale asked (Stagehand's, past one image pixel per CSS pixel): a full page is the
|
|
117
|
+
// viewport instead, and anything else is as small as this browser makes it.
|
|
118
|
+
if ((next.scale ?? 1) < scale && shot.size && Math.max(shot.size.width, shot.size.height) >= Math.max(size.width, size.height)) {
|
|
119
|
+
if (!options.fullPage)
|
|
120
|
+
throw new ScreenshotBudgetError(`The browser does not take this capture smaller than ${shot.size.width}x${shot.size.height}, which is over ${budget.maxEdgePx} px on its long edge or ${budget.maxBase64Bytes} base64 bytes.`);
|
|
121
|
+
shot = await take(viewport(options));
|
|
122
|
+
}
|
|
58
123
|
}
|
|
59
|
-
|
|
124
|
+
return { data: shot.image.data, mimeType: shot.image.mimeType, size: shot.size, options: shot.options, adjusted };
|
|
60
125
|
}
|
package/dist/core/page-scan.d.ts
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
/** An entity decoder for a run of text or an attribute value: node-html-parser's in the worker, entities.ts's on the
|
|
2
2
|
* event loop. */
|
|
3
3
|
export type Decode = (text: string) => string;
|
|
4
|
+
/** A style element of a page: what its start tag holds between its name and its ">" (insideOf), and its text. */
|
|
5
|
+
export type Style = {
|
|
6
|
+
inside: string;
|
|
7
|
+
css: string;
|
|
8
|
+
};
|
|
4
9
|
/** A page without its script, style, svg, noscript and template elements and its comments, in steps so a caller on the
|
|
5
10
|
* event loop can yield between them (dropInert, all at once). One whose end is missing runs to the end of the page, as
|
|
6
11
|
* a browser reads it; but an svg's start tag goes alone, since a browser lets the HTML that follows out of an unclosed
|
|
@@ -19,9 +24,72 @@ export declare class InertDrop {
|
|
|
19
24
|
step(chars: number): boolean;
|
|
20
25
|
/** The page as dropped so far (the whole of it once step has answered true). */
|
|
21
26
|
result(): string;
|
|
27
|
+
/** The page's own style elements dropped so far, in page order: what each start tag holds (insideOf) and its text. */
|
|
28
|
+
styles(): readonly Style[];
|
|
22
29
|
}
|
|
23
30
|
/** `html` without its inert blocks, all at once (see InertDrop). */
|
|
24
31
|
export declare function dropInert(html: string): string;
|
|
32
|
+
/**
|
|
33
|
+
* The classes common frameworks hide an element from everyone with, whatever the page's own style says (it is often an
|
|
34
|
+
* external stylesheet a page read never fetches): mfp-hide (Magnific Popup: a pop-up's content until it opens, as on
|
|
35
|
+
* Canada.ca's record pages), modal (Bootstrap: a modal until it opens), d-none (Bootstrap 4+), hidden (Tailwind, Bootstrap
|
|
36
|
+
* 3), hide (Bootstrap 2), invisible (Tailwind, Bootstrap: visibility), is-hidden (Bulma), u-hidden (SUIT utilities). The
|
|
37
|
+
* classes that hide text from the screen only (sr-only, visually-hidden, wb-inv, screen-reader-text) are not here: a
|
|
38
|
+
* screen reader reads them, and they are often a record's field labels and table captions, the words its values hang
|
|
39
|
+
* on. aria-hidden is read for the same reason the other way: it hides from a screen reader only, and is usually shown.
|
|
40
|
+
*/
|
|
41
|
+
export declare const HIDING_CLASSES: ReadonlySet<string>;
|
|
42
|
+
/** The two properties that hide an element from everyone. */
|
|
43
|
+
type Showing = "display" | "visibility";
|
|
44
|
+
/** What a property comes to: "hide" (display none, visibility hidden or collapse), "show" (any other value that
|
|
45
|
+
* decides it), or "doubt" (a value that hands it elsewhere, or declarations whose winner is unclear). */
|
|
46
|
+
type Outcome = "hide" | "show" | "doubt";
|
|
47
|
+
/** A property's last declaration: its outcome, and whether it was !important. */
|
|
48
|
+
type Declared = {
|
|
49
|
+
outcome: Outcome;
|
|
50
|
+
important: boolean;
|
|
51
|
+
};
|
|
52
|
+
/** What a declaration list, a class or an element declares of each property it sets. */
|
|
53
|
+
export type Declarations = Partial<Record<Showing, Declared>>;
|
|
54
|
+
/** What a page's own live styles declare of each class, by its one-class rules in page order. */
|
|
55
|
+
export type PageHiding = ReadonlyMap<string, Declarations>;
|
|
56
|
+
/**
|
|
57
|
+
* What `styles` (a page's own live style elements, InertDrop's styles) declare of each class's display and visibility:
|
|
58
|
+
* a rule at the top level whose selector is that one class (`.x` in `.x, .y { … }`) declares for it, a later rule's
|
|
59
|
+
* declaration after an earlier one's (after); a class a selector names otherwise (`.open .x`, `.x:hover`, `div.x`) is in
|
|
60
|
+
* doubt for each property that rule sets, since when it applies is not known here. A rule inside an at-rule (`@media`)
|
|
61
|
+
* is passed, and a style element not for the screen (forScreen) counts for nothing. Its style text is read once, at
|
|
62
|
+
* most STYLE_READ_CHARS of it, each character a bounded number of times.
|
|
63
|
+
*/
|
|
64
|
+
export declare function pageHidingOf(styles: readonly Style[]): PageHiding;
|
|
65
|
+
/**
|
|
66
|
+
* A page without the elements it hides from everyone (hides), in steps so a caller on the event loop can yield between
|
|
67
|
+
* them (dropHidden, all at once). Run on a page its inert blocks are dropped from (InertDrop), with what its own live
|
|
68
|
+
* styles declare (pageHidingOf). A hidden element goes from its start tag to the end tag that closes it, a same-name
|
|
69
|
+
* element inside it counted; one that no end tag closes hides nothing, since where it ends is not known without a full
|
|
70
|
+
* tree. A hidden element that holds no content (VOID) goes alone. Visibility is inherited and a descendant can set it
|
|
71
|
+
* back: an element hidden by visibility alone goes only if nothing inside it shows itself again (hides' `shows`), and is
|
|
72
|
+
* kept whole otherwise. Only a descendant that is shown counts: one display-hidden itself, or inside a display-hidden
|
|
73
|
+
* element within the visibility-hidden one, shows nothing. display:none is not undone by a descendant, so its element
|
|
74
|
+
* always goes. Linear: one pass pairs each start tag with its end tag (an open-tag stack per name), marking the
|
|
75
|
+
* innermost open visibility-hidden element when a shown start tag inside it shows itself, and handing the mark to the
|
|
76
|
+
* element around it (its `outer`) as each closes; each tag costs a bounded amount of work, however the page nests or
|
|
77
|
+
* fails to (an element closed out of order is kept, and its stack entry left to be popped when it reaches the top).
|
|
78
|
+
* Then the hidden ranges are cut, the outermost of each nest.
|
|
79
|
+
*/
|
|
80
|
+
export declare class HiddenDrop {
|
|
81
|
+
#private;
|
|
82
|
+
readonly html: string;
|
|
83
|
+
readonly page: PageHiding;
|
|
84
|
+
readonly decode: Decode;
|
|
85
|
+
constructor(html: string, page: PageHiding, decode: Decode);
|
|
86
|
+
/** Pairs the tags found in the next `chars` characters or so; true once the whole page is read. */
|
|
87
|
+
step(chars: number): boolean;
|
|
88
|
+
/** The page without its hidden ranges (once step has answered true; the page as it is before that). */
|
|
89
|
+
result(): string;
|
|
90
|
+
}
|
|
91
|
+
/** `html` without the elements it hides from everyone, all at once (see HiddenDrop); `page` and `decode` as there. */
|
|
92
|
+
export declare function dropHidden(html: string, page: PageHiding, decode: Decode): string;
|
|
25
93
|
/** `html` cut to at most `max` characters, after the last tag that ends before the cut, so no tag is left half; at
|
|
26
94
|
* `max` itself when that tag ends more than 64 KiB before it (a page of one long text), or one before it when `max`
|
|
27
95
|
* falls between the two halves of a character written as a surrogate pair, so no half of one is left. */
|
|
@@ -93,3 +161,4 @@ export declare class PageScan {
|
|
|
93
161
|
text: string;
|
|
94
162
|
};
|
|
95
163
|
}
|
|
164
|
+
export {};
|