@cbxss/eoka 0.1.0-beta.3 → 0.1.0-beta.4

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
@@ -1,579 +1,155 @@
1
1
  # @cbxss/eoka
2
2
 
3
- The Node.js SDK for the eoka NDJSON browser sidecar. Beta `0.1.0-beta.2` is published under the npm `next` tag; this source checkout prepares **`0.1.0-beta.3`, not yet published or qualified**. The repository source package remains private, with public artifacts staged only by the publication workflow. It supports **Node.js 24 LTS, starting at 24.21.0** (`^24.21.0`) and exports compiled ESM and TypeScript declarations. Node 22 and Current/non-LTS lines are outside the support policy. CommonJS `require` is not an export.
3
+ Node.js SDK for eoka, a stealth Chrome automation sidecar.
4
4
 
5
5
  ```sh
6
6
  npm install @cbxss/eoka@next
7
7
  ```
8
8
 
9
- ## Current scope and platform qualification
9
+ Requires Node.js 24.21+ (ESM only). Supported platforms: Linux x64/arm64 (glibc 2.35+), macOS x64/arm64, Windows x64.
10
10
 
11
- The SDK provides correlated subprocess transport, typed browser/page operations, durable operation handles, pinned full Chrome for Testing installation, verified native server resolution, PNG/JPEG/WebP capture, native MP4 recording, and bounded disposal. It does not provide deterministic scenario replay or video transcoding. Importing the package and installing with `--ignore-scripts` do not launch processes, download Chrome, or create a browser cache. There are no install lifecycle scripts, Cargo requirements, or package command-line binaries.
12
-
13
- Managed targets are `linux-x64-gnu`, `linux-arm64-gnu`, `darwin-x64`, `darwin-arm64`, and `win32-x64`. Linux managed selection requires glibc >= 2.35 and rejects musl/Alpine; Windows arm64 and unknown combinations are rejected before downloads. GNU release artifacts are built on Ubuntu 22.04 and checked for GLIBC requirements no higher than 2.35. Arbitrary source-built or host-development binaries are not qualified by that result.
14
-
15
- Both explicit server and Chrome paths are an expert override for managed platform checks, not a new support guarantee. Node.js support does not imply Bun, Deno, browser-side JavaScript, or drop-in Puppeteer compatibility. Packed npm consumption and credential-free registry installation with a Linux Chrome smoke are verified for beta.2; beta.3 requires fresh qualification. pnpm/Yarn remain unqualified.
16
-
17
- ## Managed launch and explicit preparation
11
+ ## Quick start
18
12
 
19
13
  ```js
20
- import { Browser, installBrowser } from "@cbxss/eoka";
21
-
22
- await installBrowser({
23
- browserCacheDir: "/opt/eoka/cache",
24
- timeoutMs: 300000,
25
- onProgress: ({ downloadedBytes, totalBytes, buildId }) => {
26
- process.stderr.write(`${buildId}: ${downloadedBytes}/${totalBytes} bytes\n`);
27
- },
28
- });
14
+ import { Browser } from "@cbxss/eoka";
29
15
 
30
- const browser = await Browser.launch({
31
- browserCacheDir: "/opt/eoka/cache",
32
- download: "never",
33
- sandbox: true,
34
- timeoutMs: 30000,
35
- });
16
+ const browser = await Browser.launch();
36
17
  try {
37
- const page = await browser.newPage("data:text/html,%3Ctitle%3Eoffline%3C/title%3E");
38
- console.log(await page.invoke("page.evaluate", { pageId: page.id, js: "document.title" }));
18
+ const page = await browser.newPage("https://example.com");
19
+ console.log(await page.title());
20
+ await page.screenshotToFile({ path: "./example.png" });
39
21
  } finally {
40
22
  await browser.close();
41
23
  }
42
24
  ```
43
25
 
44
- `Browser.launch()` resolves its server **before** installing Chrome. Server precedence is `serverPath` > `EOKA_SERVER_BIN` > exact optional platform package. It never searches PATH, builds Rust, or downloads a server. Browser precedence is `executablePath` > `EOKA_CHROME_PATH` > the managed pin. There is no fallback to a system browser or a different build. `Browser.connect()` resolves/starts the server but does not install or access the managed Chrome cache.
45
-
46
- `installBrowser` prepares only Chrome; it does not install system libraries or native server packages. Its options are `browserCacheDir`, `download` (`"auto"` by default or `"never"`), `signal`, `timeoutMs` (300000 ms by default), and `onProgress`. It returns `{ executablePath, cacheDir, buildId, platform, source }`, with `source: "cache"` or `"download"`. Cancellation/deadlines terminate the owned installer worker before cleaning its own staging resources. One launch deadline covers server resolution, Chrome installation, handshake, and native launch.
47
-
48
- `onProgress` receives download byte counts without writing to stdout. Without a callback, the first actual download chunk emits one diagnostic to stderr; verified cache hits and imports remain silent.
49
-
50
- ## Cache, runtime, and offline operation
51
-
52
- Cache root precedence is `browserCacheDir` > `EOKA_BROWSER_CACHE_DIR` > the per-user OS default:
53
-
54
- | OS | Default cache root |
55
- | --- | --- |
56
- | Linux | `${XDG_CACHE_HOME}/eoka`, or `~/.cache/eoka` |
57
- | macOS | `~/Library/Caches/eoka` |
58
- | Windows | `${LOCALAPPDATA}/eoka/Cache`, or `~/AppData/Local/eoka/Cache` |
59
-
60
- The installer keeps the complete distribution, including resources, libraries, and macOS bundle contents. It hashes the archive against the release pin, inventories the full installed tree, stages publication atomically, and coordinates concurrent installs per build. Cache validation detects missing/corrupt companion files as well as executable changes. Local writable inventory metadata is a same-user trust boundary, not protection against a malicious account that can replace both data and metadata.
61
-
62
- Preinstall using the same platform/build and cache root as the eventual runtime. Preserve the **whole** cache entry and its metadata; copying just Chrome's executable is insufficient. A verified cache hit requires no network or writes, including on a read-only image. `download: "never"` fails with `BrowserNotInstalled` on an absent entry and does not repair corruption by downloading. Cache integrity failures are explicit. Default cache retention is persistent; `Browser.close()` never removes installed Chrome. Remove unused cache roots only as an explicit administrator action when no session is using them.
63
-
64
- Runtime root precedence is `runtimeDir` > `EOKA_RUNTIME_DIR` > the OS temporary directory. Every launch gets a private child beneath that root. Child-only `TMPDIR`/`TMP`/`TEMP` direct native scratch work there without changing the Node process's environment. Keep runtime writable even when the browser cache is read-only. Owned child directories are cleaned only after owned-process termination is confirmed; uncertain termination retains the directory and reports its path through `RuntimeCleanupUncertain`. Caller roots, persistent `userDataDir` profiles, and the cache are not deleted. On POSIX keep the root short enough for Chrome's singleton Unix socket. Do not share persistent profiles concurrently; they contain cookies and other private session data.
65
-
66
- From an installed SDK application, run the shipped examples directly:
67
-
68
- ```sh
69
- node node_modules/@cbxss/eoka/examples/install-browser.mjs /opt/eoka/cache
70
- EOKA_RUNTIME_DIR=/tmp/eoka node node_modules/@cbxss/eoka/examples/offline.mjs /opt/eoka/cache
71
- ```
72
-
73
- The offline example uses a data URL, so its page also requires no network. `download: "never"` governs installation, not web page requests; use an OS/container network policy to prevent application traffic.
74
-
75
- ## Download pins, size, and proxy configuration
76
-
77
- This source pins full Chrome for Testing **155.0.8059.39**, not ChromeDriver or a runtime-selected latest version. `releaseManifest` and `@cbxss/eoka/release-manifest.json` expose the release metadata. The archive SHA-256 values were computed from full HTTPS archives during controlled release preparation; they are reviewed integrity pins, **not vendor signatures**. Runtime installation uses those embedded pins and never looks up a hash or substitutes a mirror/build. Browser updates require a deliberate new release and fresh native gates.
78
-
79
- Measured compressed archive sizes for this pin:
80
-
81
- | Chrome platform | Bytes |
82
- | --- | ---: |
83
- | linux64 | 198195769 |
84
- | linux-arm64 | 198202003 |
85
- | mac-x64 | 203101743 |
86
- | mac-arm64 | 192634606 |
87
- | win64 | 207197429 |
88
-
89
- Budget additional space for the expanded distribution, temporary archive/staging, and concurrent runtime profiles. The SDK does not download browser drivers.
90
-
91
- The installer honors `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, and `NO_PROXY` through its pinned proxy dependency. Configure them in the setup process environment, or in `serverEnv` for a launch-scoped child environment. Do not put proxy credentials in progress logs. Standard Node trust configuration such as `NODE_EXTRA_CA_CERTS` must be set before starting Node when an enterprise CA is required. TLS failures and hash mismatches fail closed; do not disable certificate verification.
92
-
93
- ```sh
94
- HTTPS_PROXY=http://proxy.example:8080 NO_PROXY=localhost,127.0.0.1 \
95
- node node_modules/@cbxss/eoka/examples/install-browser.mjs /opt/eoka/cache
96
- ```
97
-
98
- ## Linux libraries, sandbox, and containers
99
-
100
- The SDK does not install privileged OS packages. Chrome requires its host libraries and fonts even in headless mode: NSS/NSPR, ATK/AT-SPI, CUPS, DRM/GBM, X11/XCB/Xcomposite/Xdamage/Xfixes/Xrandr, xkbcommon, ALSA, GLib, Cairo/Pango, and fonts. The native server's dependencies are artifact-specific; current Linux staging also needs OpenSSL 3 (`libssl.so.3` and `libcrypto.so.3`). Inspect actual release binaries and qualify the chosen distribution rather than treating this list as an ABI certification.
101
-
102
- Sandboxing is enabled by default. Run as an unprivileged user with Chrome's sandbox requirements satisfied (including the host/container user-namespace and seccomp policy). A sandbox failure is an error; the SDK never retries with sandbox disabled. `sandbox: false` is an explicit security-reducing expert choice for a separately isolated environment, not the default container recipe.
103
-
104
- Ubuntu 23.10+ can deny unprivileged user namespaces through AppArmor even when
105
- Chrome itself is sandbox-enabled. An administrator must provide a narrowly
106
- scoped executable-path policy for the owned Chrome runtime, as described in
107
- [Chromium's AppArmor guidance](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md).
108
- Any process able to replace an executable at an allowed path gains that
109
- permission; use a private runtime directory, not a broad `/tmp/**/chrome` rule.
110
- The SDK neither installs privileged policies nor disables the host restriction.
111
- ARM release CI uses a private per-job path exception, removes it afterward,
112
- and checks Chrome's actual PID/network namespace and seccomp status.
113
-
114
- For example, prepare a Linux x64 image with Node 24.21.0 and a distribution new enough for the **actual staged binary**. The following Debian trixie setup is a recipe to qualify, not a statement of completed container support. Supply the two locally staged tarballs described below as build inputs:
115
-
116
- ```dockerfile
117
- FROM node:24.21.0-trixie
118
- RUN apt-get update && apt-get install -y --no-install-recommends \
119
- ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
120
- libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 libnspr4 \
121
- libnss3 libpango-1.0-0 libssl3t64 libx11-6 libxcb1 libxcomposite1 libxdamage1 \
122
- libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
123
- && rm -rf /var/lib/apt/lists/*
124
- WORKDIR /app
125
- RUN chown node:node /app
126
- COPY --chown=node:node cbxss-eoka-0.1.0-beta.3.tgz cbxss-eoka-server-linux-x64-gnu-0.1.0-beta.3.tgz ./
127
- USER node
128
- RUN npm init -y && npm install --ignore-scripts --omit=optional --no-audit --no-fund \
129
- ./cbxss-eoka-server-linux-x64-gnu-0.1.0-beta.3.tgz ./cbxss-eoka-0.1.0-beta.3.tgz
130
- ENV EOKA_BROWSER_CACHE_DIR=/app/browser-cache
131
- ENV EOKA_RUNTIME_DIR=/tmp/eoka
132
- RUN node node_modules/@cbxss/eoka/examples/install-browser.mjs
133
- CMD ["node", "node_modules/@cbxss/eoka/examples/offline.mjs"]
134
- ```
135
-
136
- Network is needed during image preparation for npm dependencies and the pinned Chrome ZIP. Runtime can then be isolated with `docker run --init --network=none --read-only --tmpfs /tmp:rw,nosuid,size=1g IMAGE`, provided the host's sandbox policy permits Chrome. Use an init process to reap orphaned browser children. Preserve cache ownership/metadata in the image and keep `/tmp` writable. Adapt library names, resource limits, and sandbox policy to the deployment; never use an Alpine/musl base for managed mode.
137
-
138
- ## Build, source staging, and local consumption
139
-
140
- This SDK and its five native packages share reserved npm version `0.1.0-beta.3`. The native server is pinned separately to `0.6.1`, published registry core to `0.7.2`, and the protocol to `1.3`; npm version equality is not wire compatibility. Release manifests accept exact semantic versions, including prereleases, but reject floating ranges, tags, and malformed versions. Packaged servers are checked against their name/version/platform, staged release metadata, actual binary digest, and expected handshake version. Explicit servers still must pass the protocol handshake.
141
-
142
- The source manifest intentionally has no fabricated hashes for unprepared native artifacts. The source package omits native optional dependencies so a clean `npm ci` does not need unpublished packages. Staging derives all five exact native dependencies from the validated release manifest and adds them to the staged SDK's package metadata. Packing the source SDK alone is useful for import/type gates, but is **not** a ready managed server distribution. Missing native packages (including after `--omit=optional`) raise `ServerPackageMissing`; a present package with an unstaged SDK pin raises `ReleaseNotPrepared`. There is no compile/download fallback.
143
-
144
- Run `mise install` at the repository root to install the pinned Node 24.21.0 toolchain. With mise activated, prepare local artifacts from this package directory without publishing:
145
-
146
- ```sh
147
- npm ci --ignore-scripts --omit=optional
148
- npm run build
149
- npm run stage:release -- --artifacts /absolute/path/to/release-server-artifacts \
150
- --output /absolute/path/to/new-stage --host-only
151
- npm pack --ignore-scripts --pack-destination /absolute/path/to/tarballs \
152
- /absolute/path/to/new-stage/platforms/linux-x64-gnu
153
- npm pack --ignore-scripts --pack-destination /absolute/path/to/tarballs \
154
- /absolute/path/to/new-stage/sdk
155
- ```
156
-
157
- Use the detected host ID in the platform path. `--host-only` is a local gate, not qualification of unbuilt targets: it marks the stage as development and embeds the Linux artifact's measured minimum glibc, which may exceed 2.35. Without that flag, staging requires all five target artifacts and rejects Linux binaries whose `readelf` GLIBC requirements exceed 2.35; repeated `--platform ID` selects specific preparation targets. Staging consumes existing server release binaries, computes their real digest/size, and writes matching SDK/platform metadata; it does not invoke Cargo or build alternate binaries. Use the same controlled artifacts as the server release and retain their provenance. Unstaged targets remain explicitly unavailable.
158
-
159
- The artifact directory uses the existing server release asset names:
160
-
161
- | Platform ID | Required server artifact |
162
- | --- | --- |
163
- | linux-x64-gnu | `eoka-server-linux-amd64` |
164
- | linux-arm64-gnu | `eoka-server-linux-arm64` |
165
- | darwin-x64 | `eoka-server-darwin-amd64` |
166
- | darwin-arm64 | `eoka-server-darwin-arm64` |
167
- | win32-x64 | `eoka-server-windows-amd64.exe` |
168
-
169
- In a separate ESM application, install the matching native tarball as a direct dependency together with the staged SDK:
170
-
171
- ```sh
172
- npm install --ignore-scripts --omit=optional \
173
- /absolute/path/to/cbxss-eoka-server-linux-x64-gnu-0.1.0-beta.3.tgz \
174
- /absolute/path/to/cbxss-eoka-0.1.0-beta.3.tgz
175
- npm install --save-dev typescript@5.9.3 @types/node@24.19.2
176
- ```
177
-
178
- The local direct dependency deliberately avoids relying on unpublished optional packages being available in a registry. A future qualified published release will install the exact matching optional package normally; do not omit it unless supplying an explicit server path. No publishing is performed or authorized by source staging.
179
-
180
- Use `"type": "module"`, TypeScript `target: "ES2024"`, and `module`/`moduleResolution: "NodeNext"`. The root export supplies runtime SDK classes, installation APIs/errors, release/platform metadata, options, and common protocol types. `@cbxss/eoka/protocol` exposes the complete wire map. CommonJS consumers use dynamic `import()`. Runtime dependencies pin AJV `8.17.1`, `@puppeteer/browsers` `3.2.4`, `yauzl` `3.4.0`, and `proxy-agent` `8.0.1`; their engine requirements are compatible with the SDK's Node 24 LTS baseline.
26
+ The first launch downloads a pinned Chrome for Testing build (about 200 MB) into a per-user cache. Later launches reuse it.
181
27
 
182
- ## Explicit-path launch and verified receipts
28
+ ## Pages
183
29
 
184
30
  ```js
185
- import { randomUUID } from "node:crypto";
186
- import { Browser } from "@cbxss/eoka";
187
-
188
- const browser = await Browser.launch({
189
- serverPath: "/absolute/path/to/eoka-server",
190
- executablePath: "/absolute/path/to/chrome",
191
- headless: true,
192
- sandbox: true,
193
- viewport: { width: 1024, height: 768, deviceScaleFactor: 1 },
194
- timeoutMs: 15000,
31
+ await page.goto("https://example.com/login");
32
+ await page.fill("#email", "ada@example.com");
33
+ await page.click("button[type=submit]", {
34
+ actionOptions: { expect: { kind: "url", value: "/home", contains: true } },
195
35
  });
196
36
 
197
- try {
198
- const html = '<!doctype html><label>Name <input id="name"></label>';
199
- const page = await browser.newPage(`data:text/html,${encodeURIComponent(html)}`);
200
- const target = { query: { kind: "css", selector: "#name" } };
201
- const operationId = randomUUID();
202
- const receipt = await page.fill(target, "Ada", {
203
- operationId,
204
- timeoutMs: 10000,
205
- actionOptions: {
206
- expect: { kind: "value", target, value: "Ada" },
207
- timeout_ms: 5000,
208
- },
209
- });
210
- console.log({ operationId, receipt });
211
- console.log(await page.invoke("page.evaluate", {
212
- pageId: page.id,
213
- js: '({name: document.querySelector("#name").value})',
214
- }));
215
- } finally {
216
- await browser.close();
217
- }
37
+ await page.waitForText("Welcome");
38
+ const heading = await page.getText("h1");
39
+ const count = await page.evaluate("document.querySelectorAll('li').length");
218
40
  ```
219
41
 
220
- `fill`, `goto`, `select`, `hover`, and the other action conveniences resolve with an actual canonical `ActionReceipt` only after terminal verified completion. Admission is not completion. `click`, `type`, `pressKey`, `submit`, `drag`, and consequential actions passed to `perform` require an explicit `actionOptions.expect` before dispatch. Locator strings mean CSS selectors; generated `LocatorSpec` objects retain the canonical query/frame/index semantics.
42
+ String targets are CSS selectors. An action resolves only after its result is verified. `click`, `type`, `pressKey`, `submit` and `drag` need an `expect` that describes the result.
221
43
 
222
- `newPage(url)` and `goto(url)` verify a navigation commit, not DOM parsing or application readiness. Before parser-dependent reads, use `evaluate` to await `DOMContentLoaded` only while `document.readyState === "loading"`; resolve the promise to a JSON-compatible value such as `true`. `goto` accepts an explicit `actionOptions.expect` when navigation must also establish application readiness.
44
+ - **Reads:** `text`, `content`, `title`, `url`, `getText`, `getAttribute`, `exists`, `evaluate`
45
+ - **Waits:** `waitFor`, `waitForVisible`, `waitForText`
46
+ - **Actions:** `goto`, `fill`, `select`, `hover`, `click`, `type`, `pressKey`, `submit`, `drag`
223
47
 
224
- Run the included example after building:
48
+ ## Shadow DOM and Turnstile
225
49
 
226
- ```sh
227
- npm run example -- /absolute/path/to/eoka-server /absolute/path/to/chrome
228
- ```
229
-
230
- Alternatively set `EOKA_SERVER_BIN` and `EOKA_CHROME_PATH`. Explicit options take precedence. Providing both paths bypasses managed installation/platform selection; no arbitrary system discovery is performed. `userDataDir` remains caller-owned. A temporary profile belongs to its owned session.
231
-
232
- ## Durable operations and uncertainty
50
+ `page.frames()` lists every frame, including cross-origin OOPIFs. `page.clickShadow(selector, { frameId?, resolveTimeoutMs? })` searches the frame's light DOM and every shadow root (closed roots included), maps the matched node's center to viewport coordinates, and clicks with human-like movement. `resolveTimeoutMs` bounds the server-side resolution; `CallOptions.timeoutMs` remains the RPC deadline and defaults to the resolution deadline plus 10 seconds when omitted:
233
51
 
234
52
  ```js
235
- const operationId = randomUUID();
236
- const operation = await page.perform(
237
- { kind: "fill", target, value: "Ada" },
238
- { operationId, actionOptions: { expect: { kind: "value", target, value: "Ada" } } },
239
- );
240
- const record = await operation.wait({ waitTimeoutMs: 1000, timeoutMs: 2000 });
241
- console.log({ operationId, state: record.state, outcome: record.outcome, receipt: record.receipt });
242
- ```
243
-
244
- `perform` returns an `Operation` after admission. `Operation.get`, `wait`, and `cancel` return canonical operation records. A bounded `wait` may return a still-running record; it does not assert success. `waitTimeoutMs` bounds the server wait, while `timeoutMs` and `signal` govern the local call. Cancellation is not rollback.
245
-
246
- Get/cancel for an already-admitted operation remain responsive while an unrelated page request waits. Unknown IDs retain ordering behind earlier queued admissions. Operation lists are independent snapshots of currently admitted records, not barriers for queued mutations. These controls still obey the negotiated in-flight limit.
247
-
248
- Persist a caller-known UUID before dispatch when recovery matters. After a lost response or local timeout, recover the same operation using `browser.operation(operationId).get()` or `page.operation(operationId).get()`. The operation must still exist in the same sidecar runtime; its ledger is not a restart-persistent store. Do not automatically replay an action with an unknown outcome.
249
-
250
- ```js
251
- import { EokaError } from "@cbxss/eoka";
252
-
253
- try {
254
- await page.fill(target, "Ada", { operationId, timeoutMs: 1000 });
255
- } catch (error) {
256
- if (!(error instanceof EokaError)) throw error;
257
- console.error({
258
- code: error.code,
259
- requestId: error.requestId,
260
- operationId: error.operationId,
261
- requestState: error.requestState,
262
- receipt: error.receipt,
263
- });
264
- if (error.operationId) {
265
- console.log(await browser.operation(error.operationId).get({ timeoutMs: 5000 }));
266
- }
53
+ const challenge = (await page.frames()).find(frame =>
54
+ frame.url.includes("challenges.cloudflare.com"));
55
+ if (challenge) {
56
+ await page.clickShadow('input[type="checkbox"]', { frameId: challenge.id });
267
57
  }
268
58
  ```
269
59
 
270
- `EokaError` is the base for `ConfigurationError`, `InstallationError`, `TransportError`, `ProtocolError`, `ServerOperationError`, and `OperationError`. Installation errors expose stable codes including `UnsupportedPlatform`, `BrowserNotInstalled`, `IntegrityMismatch`, `InstallationFailed`, `InstallationAborted`, `InstallationTimeout`, `ServerPackageMissing`, `ServerPackageMismatch`, and `ReleaseNotPrepared`. Errors preserve available request/operation IDs, dispatch uncertainty, receipt, structured server data, stderr, and cause. `OperationError` also exposes the latest record. These fields are evidence, not a promise that dispatch was prevented. `ServerError` is a generated wire type, not the runtime exception class.
271
-
272
- Stderr diagnostics retain bounded complete lines while redacting credentials, configured proxy secrets, and DevTools endpoint capability details. Truncated partial lines are discarded rather than exposed as potentially unredacted fragments.
273
-
274
- When both an operation/lifecycle failure and its cleanup fail, the SDK reports an `AggregateError`. Its `cause` preserves the primary error (also `errors[0]`), including any `operationId`, request state, and receipt; inspect that cause when recovering an operation. The remaining `errors` preserve cleanup failures rather than replacing the original evidence.
275
-
276
- ## Typed reads and invocation
60
+ `page.solveTurnstile({ timeoutMs })` is a best-effort helper for interactive Cloudflare challenge pages. It finds the challenge frame, clicks the checkbox, and waits for the page to leave the challenge state. It is not a general CAPTCHA solver.
277
61
 
278
- `Browser` and `Page` implement the generated `InvokeClient` contract:
62
+ ## Screenshots and recording
279
63
 
280
- ```ts
281
- import type { MethodResults } from "@cbxss/eoka";
282
- import { protocolVersion } from "@cbxss/eoka/protocol";
64
+ ```js
65
+ const png = await page.screenshot(); // Buffer
66
+ await page.screenshot({ format: "webp", quality: 80 });
67
+ await page.screenshotToFile({ path: "./full.png", fullPage: true });
283
68
 
284
- const result: MethodResults["page.evaluate"] = await page.invoke(
285
- "page.evaluate",
286
- { pageId: page.id, js: "({answer: 42, items: [1, null]})" },
287
- { timeoutMs: 5000 },
288
- );
289
- console.log(protocolVersion, result.result);
69
+ const recording = await page.record({ path: "./session.mp4" });
70
+ // ...
71
+ await recording.stop();
290
72
  ```
291
73
 
292
- The method map is generated from the canonical sidecar schemas, including dynamic JSON evaluation results. Use `browser.supports(method)` and `browser.hasCapability(name)` to inspect the actual handshake rather than assuming every generated method is available on an older sidecar. `hello`, `sessionInfo`, `ownership`, and `browserVersion` expose negotiated/session metadata.
293
-
294
- Page conveniences cover text/content/title/URL, element reads/waits, evaluation/execution, screenshots, viewport, browser state, and agent observation/steps. `page.fetch` is the legacy unbounded response API. Prefer `page.fetchBounded` for response-body reads: its default body budget is 8192 bytes and maximum is 1048576 bytes; inspect `truncated`, `bytesRead`, and `bodyOmitted` along with the body/status/headers. The `boundedFetch` capability indicates sidecar support. A bounded read is not the same as a complete response.
74
+ File output never overwrites an existing file, and the directory must already exist. Recordings are silent MP4s. For screenshots larger than 16 MiB, use `screenshotToFile`.
295
75
 
296
- ## Screenshots and native recording
76
+ ## Options
297
77
 
298
78
  ```js
299
- const image = await page.screenshot({
300
- format: "webp",
301
- quality: 80,
302
- clip: { x: 0, y: 0, width: 640, height: 360 },
303
- timeoutMs: 10000,
304
- });
305
- const screenshot = await page.screenshotToFile({
306
- path: "./captures/page.png",
307
- fullPage: true,
308
- });
309
- const recording = await page.record({
310
- path: "./captures/session.mp4",
311
- maxWidth: 1280,
312
- maxHeight: 720,
313
- fps: 30,
79
+ await Browser.launch({
80
+ headless: true, // default
81
+ sandbox: true, // default; leave it on
82
+ download: "auto", // "never" fails when Chrome isn't cached
83
+ browserCacheDir: "/opt/eoka/cache",
84
+ viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
85
+ timeoutMs: 30000,
314
86
  });
315
- console.log(recording.id, await recording.status());
316
- const video = await recording.stop({ timeoutMs: 60000 });
317
- console.log(screenshot.path, screenshot.bytes, video.path, video.container);
318
87
  ```
319
88
 
320
- Create destination directories first. Relative paths resolve once in the Node caller, not in the sidecar's working directory. File output stages privately beside the destination, flushes/closes, and publishes without overwriting an existing file; there is no overwrite option. An `Artifact` contains `path`, `bytes`, and `mimeType`; completed videos also report `container: "mp4"`. No video Buffer/base64 API is offered.
321
-
322
- Returned artifact paths are canonical and may use Windows' `\\?\` namespace
323
- prefix. Compare filesystem identity, not the spelling of the requested path.
324
-
325
- `screenshot()` returns a PNG Buffer by default and still accepts the original `{signal, timeoutMs}` call options. `format` supports `png`, `jpeg`, and `webp` where Chrome supports them. `quality` is an integer from 0 through 100 for JPEG/WebP and is invalid for PNG. `clip` uses nonnegative CSS-pixel positions and positive sizes. `fullPage` and `clip` are mutually exclusive. Viewport `deviceScaleFactor` is the only render-scale control. Full-page dimensions depend on current layout and Chrome's image limits; prefer a fixed viewport/crop for deterministic output. In-memory screenshots are bounded to 16 MiB raw bytes; `ScreenshotTooLarge` directs callers to `screenshotToFile`, with no automatic retry or fallback.
326
-
327
- Direct file output bypasses the 16 MiB sidecar response limit, not Chrome's image limits or the core's 64 MiB CDP message/frame budget (which includes base64 encoding and JSON). It is not an unbounded streaming screenshot API.
328
-
329
- Capture dispatch requires negotiated methods and capabilities: `screenshotOptions`, `screenshotFile`, and `nativeRecording`. Native recording additionally requires a ready active page and an encoder supported by the actual Chrome build. Unsupported recording raises `RecordingUnsupported`; the SDK never switches engines/browser versions. Video is silent native MP4 with Chrome-selected codec, not a promise of H.264. FFmpeg is not an SDK runtime dependency. `fps` is an integral ceiling from 1 through 120, not deterministic fixed-rate playback; optional `maxWidth`/`maxHeight` are positive integers no greater than 2147483647. Screenshot crops/quality are not recording options.
330
-
331
- Chrome 155.0.8059.39 can emit duplicate MP4 decoding timestamps, including
332
- zero-duration prefixes and terminal tails. The sidecar validates the fragmented
333
- MP4 before publication and applies bounded, lossless timing corrections.
334
- Within a fragment, a run of `k` explicit zero durations becomes `k` one-tick
335
- durations; the following duration decreases by `k` and must remain positive.
336
- The run endpoint and later timestamps remain unchanged. A duplicate final sample
337
- starting a new fragment advances by one tick, with its duration reduced by one
338
- tick and matching fragment decode/index times corrected.
339
- Encoded packets, sample count, file length and the final presentation endpoint
340
- are preserved; clean recordings stay byte-identical.
341
-
342
- This changes container timing metadata, not the codec or encoded frames. It
343
- requires neither a Chrome fork nor FFmpeg. Unsupported or malformed containers,
344
- insufficient donor duration and unresolved cross-fragment timing collisions
345
- fail finalization without publishing a success-named file. Validation/repair uses the original
346
- staging descriptor under a five-second deadline; failure retains partial-file
347
- evidence. The core Rust raw-stream primitive remains unmodified Chrome output.
348
- Release checks require strictly increasing finalized packet DTS and semantically
349
- verified diagnostics, not merely a successful decoder exit. The
350
- [qualification policy](#prerelease-qualification-and-publication) distinguishes
351
- proven frame-rate-estimation advisories from failures without retiming the video.
352
-
353
- `page.record` generates a UUID before dispatch, or accepts a caller-provided `recordingId`. There is one active recorder per target. A repeated start with the same ID and equivalent parameters recovers the existing record; changed parameters conflict instead of restarting. After a lost response use the ID rather than starting another recorder:
89
+ To install Chrome ahead of time, for example while building a Docker image:
354
90
 
355
91
  ```js
356
- import { RecordingError } from "@cbxss/eoka";
357
-
358
- try {
359
- const recording = await page.record({ path: "./captures/session.mp4" });
360
- await recording.stop();
361
- } catch (error) {
362
- if (!(error instanceof RecordingError)) throw error;
363
- const recording = browser.recording(error.recordingId);
364
- const record = await recording.status();
365
- console.log(record.state, record.failure?.stage, record.failure?.partialPath);
366
- }
92
+ import { installBrowser } from "@cbxss/eoka";
93
+ await installBrowser({ browserCacheDir: "/opt/eoka/cache" });
367
94
  ```
368
95
 
369
- Recovery is scoped to the live sidecar session, not crash resume. `Recording.status()` returns the current `RecordingRecord`; `.record` retains the latest observed evidence. States are `running`, `finalizing`, `completed`, `cancelled`, and `failed`. Unknown IDs fail explicitly. `stop()` shares server-side finalization and fulfills only with a completed, published native artifact. Repeated/concurrent stop calls do not stop Chrome twice. Each local waiter has its own signal/deadline; aborting or timing out a waiter does **not** cancel the recorder or finalizer. Recover status or wait again. `cancel()` explicitly releases capture/stream resources and returns a terminal record, including `completed` if publication won the race or `failed` if cleanup failed.
96
+ To drive a Chrome you already run, use `Browser.connect({ browserWSEndpoint })`. Closing the SDK leaves that browser running.
370
97
 
371
- A sidecar retains at most 1,024 distinct recording IDs and 16 MiB of cumulative
372
- UTF-8 `recordingId`, `pageId`, and resolved `path` bytes. The byte limit bounds
373
- retained start parameters, not exact process memory. Completed, cancelled, and
374
- failed records keep their capacity; IDs are never evicted or reused. At capacity,
375
- new IDs fail with `ServerBusy` before recording or file staging starts. Existing
376
- IDs still recover, and changed parameters still conflict. Start a new
377
- `Browser`/sidecar session for fresh capacity; stopping or cancelling does not
378
- reset history.
379
-
380
- `RecordingError` preserves `recordingId`, `record`, `failure`, `path`, `partialPath`, and `cleanupUncertain`, plus the normal request state/ID, cause, server data, and stderr evidence. Failed/cancelled stop outcomes are errors, never completed artifacts. A retained partial file is not the destination success name. Closing a tab/browser cancels unfinished recordings by default; explicitly await stop to save first. Disconnect/target-loss outcomes preserve honest failure/cleanup uncertainty; closing a borrowed session never kills the borrowed browser.
381
-
382
- Error-carried recording records receive the same identity, output-path and completed-artifact checks as successful responses. Inconsistent records raise `Protocol`, retain the rejected wire evidence, and do not replace a handle's known record. Valid later evidence for the same failed terminal recording may still add partial-file or publication details.
98
+ | Environment variable | Purpose |
99
+ | --- | --- |
100
+ | `EOKA_BROWSER_CACHE_DIR` | Where Chrome is cached |
101
+ | `EOKA_RUNTIME_DIR` | Scratch directory for sessions |
102
+ | `EOKA_CHROME_PATH` | Use your own Chrome binary |
103
+ | `EOKA_SERVER_BIN` | Use your own `eoka-server` binary |
104
+ | `HTTPS_PROXY`, `NO_PROXY` | Proxy for the Chrome download |
383
105
 
384
- `examples/capture.mjs OUTPUT_DIRECTORY [BROWSER_CACHE_DIRECTORY]` captures a local animated scene using an installed managed Chrome. It writes fresh screenshots and a silent native MP4 without requiring network or an alternate recorder. Existing output names intentionally fail instead of being replaced.
106
+ ## Errors
385
107
 
386
- ## Connect and cleanup
108
+ Every SDK error extends `EokaError` and has a stable `code`:
387
109
 
388
110
  ```js
389
- const browser = await Browser.connect({
390
- serverPath: "/absolute/path/to/eoka-server",
391
- browserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/your-browser-id",
392
- });
111
+ import { EokaError } from "@cbxss/eoka";
112
+
393
113
  try {
394
- console.log(browser.ownership, await browser.tabs());
395
- } finally {
396
- await browser.close();
114
+ await page.fill("#name", "Ada");
115
+ } catch (error) {
116
+ if (error instanceof EokaError) console.error(error.code, error.message);
117
+ throw error;
397
118
  }
398
119
  ```
399
120
 
400
- `connect` borrows Chrome; closing the SDK stops its owned sidecar and detaches without closing the borrowed browser. `launch` owns its Chrome session. `close()` is idempotent and must be awaited; async disposal is also supported. Pending local calls are rejected when closing starts. Teardown requests graceful shutdown, then waits within `shutdownTimeoutMs` (45000 ms by default) before terminating the SDK-owned process tree: a private process group on POSIX, or the owned PID tree on Windows. This escalation does not target a separately running borrowed Chrome process.
401
-
402
- Cleanup failures remain errors. The normal owned-Chrome cleanup path is graceful shutdown/sidecar EOF. Forced termination reports cleanup uncertainty: it cannot guarantee removal of runtime files or termination of descendants that left the owned process group/tree. Caller-owned profiles are never an SDK installation cache.
121
+ ## Linux and Docker
403
122
 
404
- If `newPage` was dispatched before a local abort/deadline, the SDK retains its native completion so it can close the exact late-created tab. If that response does not arrive within the bounded cleanup deadline, it closes the owned sidecar and reports `CleanupUncertain`; a borrowed Chrome may retain an unknown tab. That uncertainty is also retained in `Browser.close()` failures and is not evidence that the tab was removed.
123
+ Chrome needs its usual system libraries even in headless mode. On Debian:
405
124
 
406
- ## Development checks
407
-
408
- ```sh
409
- npm run generate:check
410
- npm run typecheck
411
- npm test
412
- npm run test:consumer
125
+ ```dockerfile
126
+ FROM node:24-trixie
127
+ RUN apt-get update && apt-get install -y --no-install-recommends \
128
+ ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
129
+ libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 libnspr4 \
130
+ libnss3 libpango-1.0-0 libssl3t64 libx11-6 libxcb1 libxcomposite1 libxdamage1 \
131
+ libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
132
+ && rm -rf /var/lib/apt/lists/*
133
+ USER node
413
134
  ```
414
135
 
415
- `build` emits JavaScript/declarations (including the installer worker), the pinned release manifest, canonical runtime schema bundle, and license; it does not regenerate protocol outputs. SDK source builds reject unused locals, unused parameters, and switch fallthrough. `typecheck` checks accepted/rejected fixtures and the public SDK consumer against compiled exports. The packed-consumer regression installs with `--ignore-scripts --omit=optional`, checks silent/no-side-effect imports and actionable missing-server errors, compiles the public API consumer, and runs it. The native capture fixture checks the published MP4's file size and container signature rather than accepting a nonempty artifact count.
136
+ Run as a non-root user. On Ubuntu 23.10 and later, AppArmor may block Chrome's sandbox; see [Chromium's AppArmor notes](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md). Alpine (musl) isn't supported.
416
137
 
417
- For the real outside-repository managed/offline consumer gate, supply a prepared stage and an already verified host Chrome cache:
138
+ ## Examples
418
139
 
419
140
  ```sh
420
- EOKA_RELEASE_STAGE_DIR=/absolute/path/to/new-stage \
421
- EOKA_BROWSER_CACHE_DIR=/absolute/path/to/cache npm run test:consumer
141
+ node node_modules/@cbxss/eoka/examples/install-browser.mjs
142
+ node node_modules/@cbxss/eoka/examples/offline.mjs
143
+ node node_modules/@cbxss/eoka/examples/capture.mjs ./captures
422
144
  ```
423
145
 
424
- Without both variables the staged native/browser test is skipped; import/type tests are not evidence of a native browser launch. The native test packs/installs only local staged SDK/platform tarballs and launches with `download: "never"`. It exercises PNG/JPEG/WebP, DPR/crop/full-page dimensions, equivalent Buffer/file images, existing-file protection, native MP4 stop/recovery/repeated stop, and explicit cancel with no success-named partial. A deterministic 2500×2500 RGB-noise scene verifies that screenshots larger than 16 MiB raise `ScreenshotTooLarge` with direct-file guidance, remain usable through `screenshotToFile`, and do not disconnect the page. Container decoding/observed codec and duration require the separate ffprobe/ffmpeg release smoke; those tools are not SDK runtime dependencies. Actual no-network enforcement, sandbox, container, and all-platform qualification remain separate release gates.
425
-
426
- From the repository root use `mise run node-build`, `node-check`, or `node-consumer`; `node-stage-release -- --artifacts DIR --output NEWDIR --host-only`, `node-install-browser -- CACHE`, and `node-offline -- CACHE` expose the preparation/offline workflows. `npm run example:schema` retains the generated-schema example.
427
-
428
- `mise.toml` pins the development and CI runtime to Node 24.21.0; CI reads that configuration rather than maintaining another Node version. Node types are pinned to `@types/node` 24.19.2. SDK and consumer fixtures target ES2024. Native-package staging inherits the SDK's `engines` field. The Node CI job checks the committed schema projection, accepted/rejected consumers, runtime regressions, and packed imports without requiring Rust or Chrome; the full local `node-check` additionally checks the schema against the Rust exporter. Native gates still require the explicit environment above.
429
-
430
- ## Prerelease qualification and publication
431
-
432
- Core `0.7.2` is published on crates.io. Reserved prerelease versions are
433
- server crate `0.6.1`, protocol crate `0.6.0`, wire protocol `1.3`, and SDK/native
434
- npm packages `0.1.0-beta.3`. Source and ordinary staged packages remain private;
435
- `--publication` is a separate, fail-closed staging mode.
436
-
437
- ### Pending beta.3
438
-
439
- Beta.2 was published under `next` on 2026-10-18 from
440
- `bd346b47d907ba9b71c603c4c94e77024c9f0fdd` (server `0.6.0`, core `0.7.0`).
441
- Beta.3 rebuilds the native server as `0.6.1` against published core `0.7.2`,
442
- which removes reflection-visible headless and platform leaks
443
- ([eoka#37](https://github.com/shrimp-software/eoka/pull/37)). No protocol, Chrome,
444
- or SDK API changes are required. Native binaries must be rebuilt from the new
445
- release source; repacking beta.2 binaries would omit the core fixes.
446
-
447
- Beta.3 has not been published. Release authorization requires local SDK checks
448
- and fresh five-platform native qualification (including Windows live-owner
449
- recovery) in the publication workflow at the exact current protected `main` commit.
450
- The readiness record's `ready` status means no recorded source defect blocks
451
- qualification; it is not beta.3 runtime evidence or permission to publish.
452
- The historical evidence below is retained and does not qualify beta.3.
453
-
454
- `.github/workflows/qualify-node-release.yml` builds all five native targets and
455
- qualifies installed tarballs outside the repository. GNU builds use Ubuntu 22.04
456
- and enforce glibc ≤2.35; runtime checks use non-root hosted runners with Chrome's
457
- sandbox enabled. Evidence includes fresh/cache/offline installation, artifact
458
- rejection, verified input, image dimensions, finalized MP4 packet timestamps and
459
- decode diagnostics, headed launch, owned cleanup, and borrowed-browser survival.
460
- Failures retain recordings and diagnostics as workflow artifacts. FFmpeg/ffprobe
461
- are qualification tools, not consumer dependencies.
462
-
463
- The [lossless-repair preview](https://github.com/shrimp-software/eoka-tools/actions/runs/38612635401)
464
- at tools `70b47e0ff27b271407c3073f5c1a389d87a5fd0a` and core
465
- `9bae96b9cefa02794a4058ae54b67273ad453490` completed every runtime check on
466
- Ubuntu 22.04 x64, Ubuntu 24.04 ARM64, macOS 15 x64/ARM64, and Windows 2025 x64.
467
- All 50 one-attempt finalized recordings passed strict packet DTS and empty
468
- decoder diagnostics; all 28 deterministic repair regressions passed on each
469
- architecture. Image, sandbox, headed-launch and ownership checks also passed.
470
- Those jobs ended **blocked** solely by the then-closed source readiness record.
471
- The recording blocker is now cleared using that native evidence plus retained
472
- defective-file repair/preservation proof, not passing live samples alone.
473
- Registry-backed qualification and npm publication prerequisites remain separate.
474
- Live recording still does not promise fixed-cadence export.
475
-
476
- For local host-development evidence, not release qualification:
146
+ ## Development
477
147
 
478
148
  ```sh
479
- mise run node-qualify-release -- --stage /absolute/stage \
480
- --cache /absolute/cache --output /absolute/evidence --preview
149
+ mise install
150
+ npm ci --ignore-scripts --omit=optional
151
+ npm run build
152
+ npm test
481
153
  ```
482
154
 
483
- The workflow resolves `source_ref` to an immutable tools revision and builds
484
- against published registry core `0.7.2`, without a sibling checkout or Cargo
485
- patch. It checks every native build's core identity and exact source lockfile,
486
- including registry checksum
487
- `bb088753bbef0585bcbaa1e868e4e59b5ee99db40844ba9cb3ec4822ca95e019`.
488
- Local host-development staging and `--preview` remain separate from release
489
- qualification and cannot authorize publication.
490
-
491
- Every native build runs the live-runtime recovery regression, including Windows.
492
- A held owner lock must preserve running operations; releasing it permits
493
- interruption recovery. Only the platform's lock-contention error means the owner
494
- is still alive; other lock failures remain errors.
495
-
496
- `scripts/publication-readiness.json` records unresolved release defects. Clearing
497
- a recording blocker requires deterministic repair/preservation regressions and
498
- fresh five-platform qualification, not passing samples alone. Every Chrome pin
499
- update must pass the complete recording suite on each architecture and ten
500
- single-attempt native captures: four short/default-rate clips, two short
501
- 120-fps clips, one 1-fps clip, two two-second clips, and one multi-fragment clip.
502
- Both artifact collection and publication independently require the actual running
503
- Chrome version to match the pin, the complete schedule, published MP4 records,
504
- strictly increasing packet DTS, and successful full decoding. A `passed` summary
505
- alone is insufficient. One known FFmpeg MOV input-rate-estimation diagnostic may
506
- be retained as a VFR advisory only when its adjacent packet indices and exact
507
- timestamps match the probe and the declared positive packet duration exactly
508
- reaches the next timestamp. Missing or inexact timing evidence, unknown
509
- diagnostics, and nonzero decoder exits remain fatal. Raw probe/decoder logs are
510
- preserved, and collection/publication independently recompute advisory
511
- classifications; labels alone cannot authorize release. Probe logging includes
512
- warnings. There is no retry-to-pass, hidden warning filtering, or retiming to
513
- satisfy a frame-rate heuristic. The private MP4 correction remains limited to
514
- the documented native timing defects; changing Chrome's container layout requires
515
- renewed qualification, not an implicit generic muxer or transcoder.
516
-
517
- `publish-node.yml` is manual, restricted to an exact current protected `main`
518
- commit, and publishes only `0.1.0-beta.3` under `next` with npm provenance.
519
- It requires an existing `npm-prerelease` environment with required reviewers
520
- and a single allowed deployment branch, `main`. By default it uses only npm
521
- trusted publishing through OIDC, requires self-review to be disabled, and
522
- requires all six scoped package names to exist with trusted publishers configured
523
- for this repository, workflow, and environment. There is no automatic token fallback.
524
-
525
- For the first release, explicitly dispatch with `bootstrap: true` and an
526
- environment-scoped `NPM_BOOTSTRAP_TOKEN` secret. Use a short-lived npm granular
527
- token authorized to create and publish these scoped packages, with the permissions
528
- required for unattended publication under the account's 2FA policy. Never commit
529
- the token or pass it as a workflow input. Bootstrap still requires environment
530
- reviewer approval, but permits the owner to approve their own deployment; this
531
- exception does not apply to normal OIDC publication.
532
-
533
- Only the bootstrap publish step receives the token. Its temporary private npm
534
- configuration contains an environment-variable reference, not the token value.
535
- Package verification and the final registry installation remain credential-free.
536
- Bootstrap accepts an absent name only when both public and authenticated registry
537
- reads return 404; an existing private package or an authorization failure aborts.
538
- Both modes retain GitHub OIDC provenance and the same qualification checks.
539
-
540
- Normal trusted publication still requires operator setup. On 2026-10-15, the
541
- GitHub `npm-prerelease` environment allowed only branch `main`, but its sole
542
- required reviewer was `cbxss` and `prevent_self_review` was `false`. The normal
543
- publication gate therefore rejects that configuration. Before beta.3 publication,
544
- an operator must enable `prevent_self_review: true`, arrange an independent
545
- required reviewer, and confirm npm trusted publishers on all six existing packages
546
- for owner `shrimp-software`, repository `eoka-tools`, workflow `publish-node.yml`,
547
- and environment `npm-prerelease`. npm publisher settings were not independently
548
- verified from public registry metadata; a provenance attestation does not prove
549
- trusted-publisher configuration. Remove any remaining bootstrap environment
550
- secret and revoke its token after confirming the migration. No environment,
551
- secret, token, or npm setting is changed by this release preparation.
552
-
553
- The bootstrap procedure above is historical first-publication guidance, not the
554
- normal beta.3 release path or an automatic fallback. A bootstrap rerun after a
555
- partial upload still needs the token and must follow same-run recovery below.
556
-
557
- The publish job accepts only same-run, same-source qualified artifacts and
558
- preflights all six registry versions before writing anything. Existing versions
559
- are skipped only when their SHA-512 integrity matches the qualified tarball,
560
- `next` already points at that version, npm registry signatures verify, and
561
- keyless Sigstore provenance binds the exact artifact, source commit, protected
562
- main workflow, manual event, and original workflow run. The pinned public Sigstore
563
- verifier is release-tooling-only, not an SDK runtime dependency. Registry signature
564
- checks use isolated installs with lifecycle scripts disabled; foreign-platform
565
- packages are installed only for verification, never executed.
566
-
567
- After a partial publication or lost publish response, rerun the failed jobs of
568
- the **same workflow run**, retaining its qualified artifacts and unchanged current
569
- `main` source. Verified existing uploads are preserved; only missing native
570
- packages are published, followed by the SDK. Mismatched integrity, provenance,
571
- tags, source, or unavailable registry evidence abort before any new upload.
572
- There is no automatic publish retry or retagging. If source or artifacts changed,
573
- do not bypass these checks: use a separately reviewed roll-forward release.
574
- The final smoke checks a credential-free registry installation and provenance.
575
- Its private runtime root stays short for Chrome's POSIX socket-path limits;
576
- cache/state isolation and sandboxing remain enabled.
577
-
578
- No tag, merge, or publication is part of PR preparation. Existing Rust publishing
579
- workflows trigger on `main`; merging the version changes is a release action.
155
+ Releases are automatic: merge a version bump to `main` and approve the `npm-prerelease` deployment.
@@ -1945,6 +1945,20 @@ export type MethodPageClickResult__ActionReceipt = {
1945
1945
  };
1946
1946
  export type MethodPageClickResult__DispatchState = (("not_sent" & string) | ("may_have_been_sent" & string) | ("acknowledged" & string));
1947
1947
  export type MethodPageClickResult__OperationState = (("running" | "finished" | "interrupted" | "expired") & string);
1948
+ export type MethodPageClickShadowParams = {
1949
+ "frameId"?: (string | null);
1950
+ "pageId": string;
1951
+ "selector": string;
1952
+ "timeoutMs"?: number;
1953
+ [key: string]: unknown;
1954
+ };
1955
+ export type MethodPageClickShadowResult = {
1956
+ "frameId": string;
1957
+ "selector": string;
1958
+ "x": number;
1959
+ "y": number;
1960
+ [key: string]: unknown;
1961
+ };
1948
1962
  export type MethodPageClickTextParams = {
1949
1963
  "operation_id": string;
1950
1964
  "options"?: MethodPageClickTextParams__ActionOptions;
@@ -3793,6 +3807,7 @@ export type MethodParams = {
3793
3807
  "operations.wait": MethodOperationsWaitParams;
3794
3808
  "page.capture_state": MethodPageCaptureStateParams;
3795
3809
  "page.click": MethodPageClickParams;
3810
+ "page.click_shadow": MethodPageClickShadowParams;
3796
3811
  "page.click_text": MethodPageClickTextParams;
3797
3812
  "page.close": MethodPageCloseParams;
3798
3813
  "page.content": MethodPageContentParams;
@@ -3855,6 +3870,7 @@ export type MethodResults = {
3855
3870
  "operations.wait": MethodOperationsWaitResult;
3856
3871
  "page.capture_state": MethodPageCaptureStateResult;
3857
3872
  "page.click": MethodPageClickResult;
3873
+ "page.click_shadow": MethodPageClickShadowResult;
3858
3874
  "page.click_text": MethodPageClickTextResult;
3859
3875
  "page.close": MethodPageCloseResult;
3860
3876
  "page.content": MethodPageContentResult;
@@ -3926,4 +3942,4 @@ export declare const protocolVersion: {
3926
3942
  readonly major: 1;
3927
3943
  readonly minor: 3;
3928
3944
  };
3929
- export declare const methodNames: readonly ["actions.perform", "agent.observe", "agent.step", "browser.close", "browser.close_tab", "browser.connect", "browser.launch", "browser.new_page", "browser.tabs", "operations.cancel", "operations.get", "operations.list", "operations.wait", "page.capture_state", "page.click", "page.click_text", "page.close", "page.content", "page.evaluate", "page.evaluate_in_frame", "page.execute", "page.exists", "page.fetch", "page.fetch_bounded", "page.fill", "page.frames", "page.get_attribute", "page.get_text", "page.goto", "page.hover", "page.human_click", "page.human_click_text", "page.human_fill", "page.key_down", "page.key_up", "page.mouse_down", "page.mouse_move", "page.mouse_up", "page.press_key", "page.release_all_inputs", "page.reset_viewport", "page.restore_state", "page.screenshot", "page.screenshot_to_file", "page.select", "page.set_viewport", "page.solve_captcha", "page.text", "page.title", "page.type_into", "page.url", "page.wait_for", "page.wait_for_text", "page.wait_for_visible", "recording.cancel", "recording.get", "recording.start", "recording.stop", "server.hello", "server.shutdown"];
3945
+ export declare const methodNames: readonly ["actions.perform", "agent.observe", "agent.step", "browser.close", "browser.close_tab", "browser.connect", "browser.launch", "browser.new_page", "browser.tabs", "operations.cancel", "operations.get", "operations.list", "operations.wait", "page.capture_state", "page.click", "page.click_shadow", "page.click_text", "page.close", "page.content", "page.evaluate", "page.evaluate_in_frame", "page.execute", "page.exists", "page.fetch", "page.fetch_bounded", "page.fill", "page.frames", "page.get_attribute", "page.get_text", "page.goto", "page.hover", "page.human_click", "page.human_click_text", "page.human_fill", "page.key_down", "page.key_up", "page.mouse_down", "page.mouse_move", "page.mouse_up", "page.press_key", "page.release_all_inputs", "page.reset_viewport", "page.restore_state", "page.screenshot", "page.screenshot_to_file", "page.select", "page.set_viewport", "page.solve_captcha", "page.text", "page.title", "page.type_into", "page.url", "page.wait_for", "page.wait_for_text", "page.wait_for_visible", "recording.cancel", "recording.get", "recording.start", "recording.stop", "server.hello", "server.shutdown"];
@@ -1,2 +1,2 @@
1
1
  export const protocolVersion = { "major": 1, "minor": 3 };
2
- export const methodNames = ["actions.perform", "agent.observe", "agent.step", "browser.close", "browser.close_tab", "browser.connect", "browser.launch", "browser.new_page", "browser.tabs", "operations.cancel", "operations.get", "operations.list", "operations.wait", "page.capture_state", "page.click", "page.click_text", "page.close", "page.content", "page.evaluate", "page.evaluate_in_frame", "page.execute", "page.exists", "page.fetch", "page.fetch_bounded", "page.fill", "page.frames", "page.get_attribute", "page.get_text", "page.goto", "page.hover", "page.human_click", "page.human_click_text", "page.human_fill", "page.key_down", "page.key_up", "page.mouse_down", "page.mouse_move", "page.mouse_up", "page.press_key", "page.release_all_inputs", "page.reset_viewport", "page.restore_state", "page.screenshot", "page.screenshot_to_file", "page.select", "page.set_viewport", "page.solve_captcha", "page.text", "page.title", "page.type_into", "page.url", "page.wait_for", "page.wait_for_text", "page.wait_for_visible", "recording.cancel", "recording.get", "recording.start", "recording.stop", "server.hello", "server.shutdown"];
2
+ export const methodNames = ["actions.perform", "agent.observe", "agent.step", "browser.close", "browser.close_tab", "browser.connect", "browser.launch", "browser.new_page", "browser.tabs", "operations.cancel", "operations.get", "operations.list", "operations.wait", "page.capture_state", "page.click", "page.click_shadow", "page.click_text", "page.close", "page.content", "page.evaluate", "page.evaluate_in_frame", "page.execute", "page.exists", "page.fetch", "page.fetch_bounded", "page.fill", "page.frames", "page.get_attribute", "page.get_text", "page.goto", "page.hover", "page.human_click", "page.human_click_text", "page.human_fill", "page.key_down", "page.key_up", "page.mouse_down", "page.mouse_move", "page.mouse_up", "page.press_key", "page.release_all_inputs", "page.reset_viewport", "page.restore_state", "page.screenshot", "page.screenshot_to_file", "page.select", "page.set_viewport", "page.solve_captcha", "page.text", "page.title", "page.type_into", "page.url", "page.wait_for", "page.wait_for_text", "page.wait_for_visible", "recording.cancel", "recording.get", "recording.start", "recording.stop", "server.hello", "server.shutdown"];
@@ -4198,6 +4198,65 @@
4198
4198
  "type": "object"
4199
4199
  }
4200
4200
  },
4201
+ "page.click_shadow": {
4202
+ "params": {
4203
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
4204
+ "properties": {
4205
+ "frameId": {
4206
+ "type": [
4207
+ "string",
4208
+ "null"
4209
+ ]
4210
+ },
4211
+ "pageId": {
4212
+ "type": "string"
4213
+ },
4214
+ "selector": {
4215
+ "type": "string"
4216
+ },
4217
+ "timeoutMs": {
4218
+ "default": 10000,
4219
+ "format": "uint64",
4220
+ "maximum": 9007199254740991,
4221
+ "minimum": 0,
4222
+ "type": "integer"
4223
+ }
4224
+ },
4225
+ "required": [
4226
+ "pageId",
4227
+ "selector"
4228
+ ],
4229
+ "title": "ClickShadowParams",
4230
+ "type": "object"
4231
+ },
4232
+ "result": {
4233
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
4234
+ "properties": {
4235
+ "frameId": {
4236
+ "type": "string"
4237
+ },
4238
+ "selector": {
4239
+ "type": "string"
4240
+ },
4241
+ "x": {
4242
+ "format": "double",
4243
+ "type": "number"
4244
+ },
4245
+ "y": {
4246
+ "format": "double",
4247
+ "type": "number"
4248
+ }
4249
+ },
4250
+ "required": [
4251
+ "frameId",
4252
+ "selector",
4253
+ "x",
4254
+ "y"
4255
+ ],
4256
+ "title": "ClickShadowResult",
4257
+ "type": "object"
4258
+ }
4259
+ },
4201
4260
  "page.click_text": {
4202
4261
  "params": {
4203
4262
  "$defs": {
package/dist/page.d.ts CHANGED
@@ -62,6 +62,26 @@ export declare class Page implements InvokeClient {
62
62
  waitForText(text: string, options?: PageWaitOptions): Promise<void>;
63
63
  evaluate(js: string, options?: CallOptions): Promise<unknown>;
64
64
  execute(js: string, options?: CallOptions): Promise<void>;
65
+ /** List every frame in the page, including cross-origin OOPIFs. */
66
+ frames(options?: CallOptions): Promise<MethodResults['page.frames']>;
67
+ /**
68
+ * Click an element inside a closed shadow root in the top frame or a child
69
+ * frame. `frameId` comes from `frames()`. The selector is searched through
70
+ * the frame's light DOM and every shadow root; the node's center is mapped
71
+ * to viewport coordinates and clicked with human-like movement.
72
+ */
73
+ clickShadow(selector: string, options?: {
74
+ frameId?: string;
75
+ resolveTimeoutMs?: number;
76
+ } & CallOptions): Promise<MethodResults['page.click_shadow']>;
77
+ /**
78
+ * Best-effort helper for interactive Cloudflare challenge pages: find the
79
+ * `challenges.cloudflare.com` frame, click its checkbox through the closed
80
+ * shadow root, and wait for the page to leave the challenge state.
81
+ */
82
+ solveTurnstile(options?: {
83
+ timeoutMs?: number;
84
+ } & CallOptions): Promise<void>;
65
85
  captureState(options?: CallOptions): Promise<BrowserState>;
66
86
  restoreState(state: BrowserState, options?: CallOptions): Promise<void>;
67
87
  fetch(url: string, fetchOptions?: FetchOptions, options?: CallOptions): Promise<MethodResults['page.fetch']>;
package/dist/page.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { Buffer } from 'node:buffer';
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { resolve } from 'node:path';
4
+ import { ProtocolError } from './errors.js';
4
5
  import { Operation, OperationError, operationFailure, validateOperationRecord } from './operations.js';
5
6
  import { Recording, RecordingError, recordingFailure, requireCaptureCapability, validateRecordingRecord } from './recording.js';
6
7
  const recordingIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -137,6 +138,63 @@ export class Page {
137
138
  async execute(js, options) {
138
139
  await this.invoke('page.execute', { pageId: this.id, js }, options);
139
140
  }
141
+ /** List every frame in the page, including cross-origin OOPIFs. */
142
+ async frames(options) {
143
+ return this.invoke('page.frames', { pageId: this.id }, options);
144
+ }
145
+ /**
146
+ * Click an element inside a closed shadow root in the top frame or a child
147
+ * frame. `frameId` comes from `frames()`. The selector is searched through
148
+ * the frame's light DOM and every shadow root; the node's center is mapped
149
+ * to viewport coordinates and clicked with human-like movement.
150
+ */
151
+ async clickShadow(selector, options = {}) {
152
+ const { frameId, resolveTimeoutMs, ...callOptions } = options;
153
+ // `CallOptions.timeoutMs` is the RPC deadline; `resolveTimeoutMs` is the
154
+ // server-side resolution deadline. Derive an RPC deadline that cannot
155
+ // outlive a long resolution when the caller did not set one explicitly.
156
+ if (callOptions.timeoutMs === undefined && resolveTimeoutMs !== undefined) {
157
+ callOptions.timeoutMs = resolveTimeoutMs + 10_000;
158
+ }
159
+ return this.invoke('page.click_shadow', {
160
+ pageId: this.id,
161
+ selector,
162
+ ...(frameId === undefined ? {} : { frameId }),
163
+ ...(resolveTimeoutMs === undefined ? {} : { timeoutMs: resolveTimeoutMs }),
164
+ }, callOptions);
165
+ }
166
+ /**
167
+ * Best-effort helper for interactive Cloudflare challenge pages: find the
168
+ * `challenges.cloudflare.com` frame, click its checkbox through the closed
169
+ * shadow root, and wait for the page to leave the challenge state.
170
+ */
171
+ async solveTurnstile(options = {}) {
172
+ const { timeoutMs = 30_000, ...callOptions } = options;
173
+ const deadline = performance.now() + timeoutMs;
174
+ while (performance.now() < deadline) {
175
+ const frames = await this.frames(callOptions);
176
+ const challenge = frames.find(frame => frame.url.includes('challenges.cloudflare.com'));
177
+ if (challenge !== undefined) {
178
+ const remaining = Math.max(1, Math.floor(deadline - performance.now()));
179
+ try {
180
+ await this.clickShadow('input[type="checkbox"]', {
181
+ ...callOptions,
182
+ frameId: challenge.id,
183
+ resolveTimeoutMs: Math.min(remaining, 2_000),
184
+ });
185
+ }
186
+ catch (error) {
187
+ if (performance.now() >= deadline)
188
+ throw error;
189
+ }
190
+ }
191
+ else if (!(await this.title(callOptions)).includes('moment')) {
192
+ return;
193
+ }
194
+ await new Promise(resolve => setTimeout(resolve, 500));
195
+ }
196
+ throw new ProtocolError('Turnstile challenge did not resolve before the deadline');
197
+ }
140
198
  async captureState(options) {
141
199
  return (await this.invoke('page.capture_state', { pageId: this.id }, options)).state;
142
200
  }
@@ -1,63 +1,63 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "sdkVersion": "0.1.0-beta.3",
3
+ "sdkVersion": "0.1.0-beta.4",
4
4
  "installerVersion": "3.2.4",
5
5
  "server": {
6
- "version": "0.6.1",
6
+ "version": "0.6.2",
7
7
  "protocolVersion": "1.3",
8
8
  "platforms": {
9
9
  "linux-x64-gnu": {
10
10
  "packageName": "@cbxss/eoka-server-linux-x64-gnu",
11
- "packageVersion": "0.1.0-beta.3",
11
+ "packageVersion": "0.1.0-beta.4",
12
12
  "target": "x86_64-unknown-linux-gnu",
13
13
  "asset": "eoka-server-linux-amd64",
14
14
  "executablePath": "bin/eoka-server",
15
- "sha256": "445c2f1dfb84df9ad6d868d78b2ba67a1b107d1fc96ae3d7a1ce9fc97e8c2089",
16
- "size": 16968272,
15
+ "sha256": "0f84e0f05c7243cb0f2f0390df8ccf54a71bb9bdd3bd79ff28238ed4f866ccab",
16
+ "size": 17166424,
17
17
  "minimumGlibc": "2.35",
18
18
  "development": false
19
19
  },
20
20
  "linux-arm64-gnu": {
21
21
  "packageName": "@cbxss/eoka-server-linux-arm64-gnu",
22
- "packageVersion": "0.1.0-beta.3",
22
+ "packageVersion": "0.1.0-beta.4",
23
23
  "target": "aarch64-unknown-linux-gnu",
24
24
  "asset": "eoka-server-linux-arm64",
25
25
  "executablePath": "bin/eoka-server",
26
- "sha256": "291df6255ab1b98ffe1f0fc8c0473d508cdd2d26d46f0517b7fe060a8949ed78",
27
- "size": 16247368,
26
+ "sha256": "55fe53844f0e8dc5a7d8cd995b546be4162045aac51e63143af82f0f7932da68",
27
+ "size": 16418664,
28
28
  "minimumGlibc": "2.35",
29
29
  "development": false
30
30
  },
31
31
  "darwin-x64": {
32
32
  "packageName": "@cbxss/eoka-server-darwin-x64",
33
- "packageVersion": "0.1.0-beta.3",
33
+ "packageVersion": "0.1.0-beta.4",
34
34
  "target": "x86_64-apple-darwin",
35
35
  "asset": "eoka-server-darwin-amd64",
36
36
  "executablePath": "bin/eoka-server",
37
- "sha256": "e73e1048854a2671e63ff0ea86e30dd7d15df50f6328958fa35f0a71fb088ea8",
38
- "size": 15055664,
37
+ "sha256": "eda5a8b139d3a71647ab5ae72f3dca204fba3ac8ec0f76a296709e5173c574be",
38
+ "size": 15238912,
39
39
  "minimumGlibc": null,
40
40
  "development": false
41
41
  },
42
42
  "darwin-arm64": {
43
43
  "packageName": "@cbxss/eoka-server-darwin-arm64",
44
- "packageVersion": "0.1.0-beta.3",
44
+ "packageVersion": "0.1.0-beta.4",
45
45
  "target": "aarch64-apple-darwin",
46
46
  "asset": "eoka-server-darwin-arm64",
47
47
  "executablePath": "bin/eoka-server",
48
- "sha256": "faba395aef1347ddce39cb3ce1fa52029a801a172d19c1632c0256a15a83022c",
49
- "size": 14604368,
48
+ "sha256": "1e495252790f86d5e6ee6ed1d32208813b6c287065724cd22a6105b753ba61b2",
49
+ "size": 14750112,
50
50
  "minimumGlibc": null,
51
51
  "development": false
52
52
  },
53
53
  "win32-x64": {
54
54
  "packageName": "@cbxss/eoka-server-win32-x64",
55
- "packageVersion": "0.1.0-beta.3",
55
+ "packageVersion": "0.1.0-beta.4",
56
56
  "target": "x86_64-pc-windows-msvc",
57
57
  "asset": "eoka-server-windows-amd64.exe",
58
58
  "executablePath": "bin/eoka-server.exe",
59
- "sha256": "57829a23155279220964b4d3e07ab6d87c500818d92aed86c23d4fa4b59b74c4",
60
- "size": 14133248,
59
+ "sha256": "f153941879b49f905278628947f330605cef037a3201b93ac0d7fe467dbbc8c7",
60
+ "size": 14304256,
61
61
  "minimumGlibc": null,
62
62
  "development": false
63
63
  }
package/dist/release.js CHANGED
@@ -29,7 +29,7 @@ export function validateReleaseManifest(value) {
29
29
  const chrome = object(manifest.chrome);
30
30
  const servers = object(server.platforms);
31
31
  const browsers = object(chrome.platforms);
32
- if (manifest.schemaVersion !== 1 || !exactNpmVersion(manifest.sdkVersion) || manifest.installerVersion !== '3.2.4' || server.version !== '0.6.1' || server.protocolVersion !== `${protocolVersion.major}.${protocolVersion.minor}` || chrome.buildId !== '155.0.8059.39')
32
+ if (manifest.schemaVersion !== 1 || !exactNpmVersion(manifest.sdkVersion) || manifest.installerVersion !== '3.2.4' || server.version !== '0.6.2' || server.protocolVersion !== `${protocolVersion.major}.${protocolVersion.minor}` || chrome.buildId !== '155.0.8059.39')
33
33
  throw new Error('Incompatible release versions');
34
34
  if (Object.keys(servers).length !== platformIds.length || Object.keys(browsers).length !== platformIds.length)
35
35
  throw new Error('Incomplete platform mapping');
@@ -8,4 +8,5 @@ export interface ServerBinaryResolution {
8
8
  source: 'explicit' | 'environment' | 'package';
9
9
  expectedServerVersion?: string;
10
10
  }
11
+ export declare function nodeEngineMismatch(range: string, version: string): boolean;
11
12
  export declare function resolveServerBinary(options?: ServerBinaryOptions): Promise<ServerBinaryResolution>;
@@ -14,6 +14,29 @@ function checkAbort(signal) {
14
14
  function isSingleton(value, expected) {
15
15
  return Array.isArray(value) && value.length === 1 && value[0] === expected;
16
16
  }
17
+ // npm skips an optional dependency whose engines range rejects the running
18
+ // Node, so a missing platform package often means the wrong Node version.
19
+ export function nodeEngineMismatch(range, version) {
20
+ const required = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range)?.slice(1).map(Number);
21
+ const current = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version)?.slice(1).map(Number);
22
+ if (!required || !current || required[0] === 0)
23
+ return false;
24
+ if (current[0] !== required[0])
25
+ return true;
26
+ return current[1] < required[1] || (current[1] === required[1] && current[2] < required[2]);
27
+ }
28
+ function unsupportedNodeHint() {
29
+ let range;
30
+ try {
31
+ range = createRequire(import.meta.url)('../package.json').engines?.node;
32
+ }
33
+ catch {
34
+ return '';
35
+ }
36
+ if (typeof range !== 'string' || !nodeEngineMismatch(range, process.versions.node))
37
+ return '';
38
+ return ` npm skips it on unsupported Node versions: this is Node ${process.versions.node}, but @cbxss/eoka requires ${range}. Switch Node (for example \`mise use node@24\` or \`nvm install 24\`) and reinstall.`;
39
+ }
17
40
  export async function resolveServerBinary(options = {}) {
18
41
  const { signal } = options;
19
42
  checkAbort(signal);
@@ -41,7 +64,7 @@ export async function resolveServerBinary(options = {}) {
41
64
  packagePath = createRequire(import.meta.url).resolve(`${pin.packageName}/package.json`);
42
65
  }
43
66
  catch (cause) {
44
- throw new InstallationError('ServerPackageMissing', `The exact optional dependency ${pin.packageName}@${pin.packageVersion} is missing. Reinstall @cbxss/eoka with optional dependencies enabled (do not use --omit=optional), or install that exact platform package. There is no Cargo, PATH or network fallback.`, { cause });
67
+ throw new InstallationError('ServerPackageMissing', `The exact optional dependency ${pin.packageName}@${pin.packageVersion} is missing.${unsupportedNodeHint()} Reinstall @cbxss/eoka with optional dependencies enabled (do not use --omit=optional), or install that exact platform package. There is no Cargo, PATH or network fallback.`, { cause });
45
68
  }
46
69
  if (pin.sha256 === null || pin.size === null)
47
70
  throw new InstallationError('ReleaseNotPrepared', `The SDK has no staged server integrity pin for ${platform}. Use a prepared SDK plus its matching platform package, or set serverPath explicitly.`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbxss/eoka",
3
- "version": "0.1.0-beta.3",
3
+ "version": "0.1.0-beta.4",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Node.js SDK with pinned Chrome installation and verified eoka sidecar resolution",
@@ -58,11 +58,11 @@
58
58
  "typescript": "5.9.3"
59
59
  },
60
60
  "optionalDependencies": {
61
- "@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.3",
62
- "@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.3",
63
- "@cbxss/eoka-server-darwin-x64": "0.1.0-beta.3",
64
- "@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.3",
65
- "@cbxss/eoka-server-win32-x64": "0.1.0-beta.3"
61
+ "@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.4",
62
+ "@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.4",
63
+ "@cbxss/eoka-server-darwin-x64": "0.1.0-beta.4",
64
+ "@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.4",
65
+ "@cbxss/eoka-server-win32-x64": "0.1.0-beta.4"
66
66
  },
67
67
  "repository": {
68
68
  "type": "git",