@ai-ecoverse/slicc-serve 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -180,13 +180,14 @@ visitor tab ──wss /__slicc/bridge──► tray hub ──controller WS─
180
180
  - When a tab disconnects, its sessions end (`Target.detachedFromTarget`, `Target.targetDestroyed`) and its pending calls fail. When the preview stops, the hub closes its tabs' sockets. A CDP client closing its socket detaches its sessions and changes nothing for the visitor.
181
181
  - **When the relay's controller socket drops**, the visitor sockets stay on the hub. The relay keeps its targets, and when it is back the hub replays `bridge.connected {…, replay: true}` for the tabs still there: they keep their target ids and sessions. A tab the hub doesn't replay within 3 s of the reconnect closed meanwhile; the relay drops it (`Target.targetDestroyed`, a `disconnected` record with the reason `the tray hub no longer had it after the relay reconnected`).
182
182
 
183
- **What a client can do through the bridge.** The bootstrap the hub injects answers a small set of methods in the page itself, so the relay makes up the rest of what [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp)'s `playwright-cli` and `curlwright` need from a browser. With them, `tab-list`, `eval` (expressions and functions), `snapshot`, `screenshot`, `goto` and `curlwright` requests work on `preview:<token>:<connId>` targets (`playwright-cli --cdp <the endpoint's ws URL>`):
183
+ **What a client can do through the bridge.** The bootstrap the hub injects answers a small set of methods in the page itself, so the relay makes up the rest of what [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp)'s `playwright-cli` and `curlwright` need from a browser, using only the bootstrap's `Runtime.evaluate`. With it, `tab-list`, `eval` (expressions and functions), `snapshot`, `click`, `fill`, `type`, `press`, `screenshot`, `goto` and `curlwright` requests work on `preview:<token>:<connId>` targets (`playwright-cli --cdp <the endpoint's ws URL>`), each action exactly once:
184
184
 
185
- - **Results by value:** a `Runtime.evaluate` with `returnByValue` goes to the tab as `Promise.resolve((0, eval)(<the expression>)).then((v) => JSON.stringify({t: typeof v, v}))`, and the relay answers with the value. Without `returnByValue`, the tab returns a description (type, subtype, class, description, and the value of a primitive), from which the relay builds the remote object.
186
- - **Object handles:** an object result gets an `objectId` that stands for the expression that produced it. `Runtime.callFunctionOn` on it evaluates that expression again and calls the function on the result (`(<function>).apply((0, eval)(<expression>), [<arguments>])`), so a handle is only as stable as its expression: one with side effects runs them again. `Runtime.getProperties` of a handle is empty, and `DOM.describeNode`, `DOM.resolveNode` and `DOM.requestNode` of one are `-32000`, `the preview bridge can't hold objects of the visitor's page`: there are no DOM node ids, so `playwright-cli`'s refs are found by their selectors.
185
+ - **Results:** every `Runtime.evaluate` goes to the tab wrapped as `(0, eval)(<the expression>)` whose awaited result the page describes as JSON: with `returnByValue`, its value (with `NaN`, `Infinity`, `-0` and BigInts as `unserializableValue`, and inside arrays and objects as `JSON.stringify` writes them); without, its type, subtype (`null`, `array`, `node`, `error`), class and description, and for an object or a function a handle.
186
+ - **Object handles:** the page keeps each object a result hands out in a registry of its own (`globalThis[Symbol.for('scserve.bridge')]`), and its `objectId` names that entry. `Runtime.callFunctionOn` calls the function on the object itself, with handles and values as arguments, so the expression that produced a handle never runs again; the function is compiled by the page's indirect `eval`, at its global scope, so it sees the page's globals and none of the bridge's names. `Runtime.getProperties` lists a handle's own string-keyed properties from their descriptors, reporting an accessor's `get` and `set` without calling them (and only accessors with `accessorPropertiesOnly`); `DOM.describeNode` (by `objectId` or `backendNodeId`) and `DOM.resolveNode` (by `backendNodeId`) work for DOM nodes, with backend node ids the page numbers itself. `Runtime.releaseObject` and `Runtime.releaseObjectGroup` drop entries (a handle joins the `objectGroup` of the `Runtime.evaluate`, `Runtime.callFunctionOn` or `DOM.resolveNode` that made it); a navigation drops them all, and a handle used after that is `-32000` (`the object is gone from the visitor's page`). Other methods that take an `objectId` of the bridge are `-32000`.
187
187
  - **One world:** the page has one execution context, renewed by each navigation. `Page.createIsolatedWorld` answers that context, so scripts meant for an isolated world run in the page's own (and see its globals).
188
+ - **No trusted input:** a page script can only dispatch events with `isTrusted` false, so `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent` and `Input.insertText` answer `{}` and dispatch nothing (the bootstrap's own, which clicks on a mouse press, would act a second time). `playwright-cli` checks whether its trusted input landed and otherwise dispatches the events in the page itself, which is what happens here, once. A client that relies on `Input.*` alone does nothing through the bridge, and a page that ignores untrusted events (`if (!event.isTrusted) return`) doesn't react.
188
189
  - **No network domain:** `Inspector.enable`, `Fetch.enable`, `Fetch.disable`, `Network.enable`, `Network.disable` and `Network.setBypassServiceWorker` answer `{}` and no event ever follows; `Network.getAllCookies`, `Network.getCookies` and `Storage.getCookies` answer no cookies. The visitor's cookie jar, requests and responses don't reach the relay.
189
- - **Not through the bridge:** console, network and dialog events, DOM node ids, PDF, screencasts, downloads, and a page whose own CSP forbids `eval` (the bootstrap's evaluation is the page's indirect `eval`). Input commands (`click`, `fill`, `type`) go through the bootstrap's `Input.dispatchMouseEvent` and `Input.dispatchKeyEvent`; their checks run in the page, so they depend on the visitor's page as any page script does.
190
+ - **Not through the bridge:** console, network and dialog events, the `DOM` domain's node ids (`DOM.getDocument` and `DOM.querySelector` are the bootstrap's), PDF, screencasts, downloads, and a page whose own CSP forbids `eval` (the bootstrap's evaluation is the page's indirect `eval`).
190
191
 
191
192
  **The lifecycle records.** The relay keeps the last 500 records of all its bridged previews, in memory (they are gone when the relay exits): `connected` (with the visitor's `origin`, `userAgent` and `connectedAt`), `disconnected` (with the `reason` when the hub gives one) and `emit` (the `name` and the `detail`, as JSON, cut to 1,000 characters). An emit, like a visitor's `origin`, `userAgent` and `reason`, is untrusted text from a stranger's browser; the hub already limits each emit to 16 KiB and 20 per tab every 10 s. Every line `scserve` prints for a person (`--foreground`'s event lines, `--logs`, the first-visit line) writes those fields with control characters (C0, DEL and C1) escaped as JSON escapes them (`\u001b`), so a visitor can't send escape sequences to the terminal; `--json` output is JSON already.
192
193
 
@@ -195,7 +196,7 @@ visitor tab ──wss /__slicc/bridge──► tray hub ──controller WS─
195
196
  **Where events go:**
196
197
 
197
198
  - A `--foreground` `scserve --bridge` prints one line per event to stderr, `scserve: connected <connId> <origin> <userAgent>`, `scserve: disconnected <connId> <reason>`, `scserve: emit <connId> <name> <detail>`; with `--json`, stdout has one JSON object per event after the record: `{"event": "connected"|"disconnected"|"emit", "previewToken", "connId", "at", …}`, the record's fields.
198
- - `scserve --logs [TOKEN|URL] [--lines N]` asks the relay for them: `Preview lifecycle records (oldest to newest):`, then `<at> <event> <announced|suppressed|-> preview=<token> conn=<connId> <origin=… userAgent=…|reason=…|name=… detail=…>` per record, or `no lifecycle records (the relay keeps them in memory, so they are gone when it restarts)`; `--json` prints the array. A target that matches no bridged preview is `scserve: no preview matches X` (exit 1); no relay running is no records.
199
+ - `scserve --logs [TOKEN|URL] [--lines N]` asks the relay for them: `Preview lifecycle records (oldest to newest):`, then `<at> <event> <announced|suppressed|-> preview=<token> conn=<connId> <origin=… userAgent=…|reason=…|name=… detail=…>` per record, or `no lifecycle records (the relay keeps them in memory, so they are gone when it restarts)`; `--json` prints the array. A target that matches no preview the relay bridged is `scserve: no preview matches X` (exit 1); no relay running is no records. A stopped preview's records stay until `--truncate` or until the relay exits.
199
200
  - `scserve --truncate [TOKEN|URL]` clears them (of that preview, or all), re-arms the first-visit announcement of each matching bridged preview (`preview.state.update {announced: false}`), and prints `cleared <n> records, re-armed <m> previews` (`--json`: `{"cleared": n, "rearmed": m}`).
200
201
 
201
202
  ## The tray hub
@@ -417,7 +418,7 @@ npm run build:wasm
417
418
 
418
419
  - `crates/serve` is the binary (`scserve`, and `scserve.wasm` for the kernel); `crates/serve-core` has no host-only dependency and builds for `wasm32-wasip1-threads`; `crates/serve-hub` (native only) is the hub client, the tray, the relay and the CLI.
419
420
  - `npm run lint`: Biome, the no-comment check, `slicc-lint`, `shellcheck` and `dash -n` on `install.sh`, `cargo fmt`, and `cargo clippy` for the host and `wasm32-wasip1-threads`.
420
- - `npm test` builds `scserve` and runs `test/integration/` with Node's test runner. The hub there is `fake-hub.mjs`: trays, leader election, the controller WebSocket (`preview.request` to the relay and the chunks back, `preview.revoked`), mint, upload, finalize, stop and list, a visitor path that resolves `<label>.localhost` hosts like the preview worker, and injected answers per route for every class of error. Tests never reach `www.sliccy.ai`. `seven.test.mjs` installs the package (its staged `package.json`, from `scripts/targets.mjs`) with `bin/serve.wasm` (after `npm run build:wasm`), wasm-bash and wasm-coreutils in a node kernel from `@ai-ecoverse/slicc-kernel` (Node 26), behind a fake page that answers `serve.publish`, `serve.list`, `serve.stop` and `open.url` and records each request: the background `serve`, the page ending a preview, a killed holder revoking, `--port`, `--foreground`, `--open`, `--list` and `--stop` by token, URL and port, each errno and each class of hub failure, and a hostile directory name in the header; then a kernel no page answers, and slicc-kernel 1.152.2 (the devDependency `slicc-kernel-without-embedder`), which refuses the package and, with `engines` stripped, has no `/dev/embedder`. `seven-ttl.test.mjs` does the same for `--ttl`, with a fake page that implements `serve.snapshot` against `fake-hub.mjs` (it reads the body, mints, uploads, finalizes, and stops what it minted on a failure): the files that reach the hub, `--json`, `--entry`, `--open`, a file past the request window, the limits checked before the page is asked, each hub failure (mint, upload, finalize, with a 3 MiB body answered early), the page's refusals, and a `serve` killed before the finalize. `slicc-cdp.test.mjs` downloads `playwright-cli` and `curlwright` for the platform from a pinned [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp) release (checked against its `SHA256SUMS`, cached in `node_modules/.cache/`) and runs them against a visitor tab (`visitor.mjs`, which answers as the hub's bootstrap does, evaluating in a `node:vm` context with a stand-in `document`): `tab-list`, `eval`, `snapshot`, `screenshot`, `goto`, a `curlwright` request, and a relay reconnect that keeps one tab's target id and drops a tab that closed meanwhile. `bridge.test.mjs` plays the visitor's tab against the fake hub's `/__slicc/bridge` (`hub.tab(url)`, answering `cdp.req` frames and sending emits) and drives the relay's CDP endpoint with Node's `WebSocket`: the guards (secret, `Host`, `Origin`), `/json/*`, discovery, attach and auto-attach, the synthetic and forwarded methods, navigation events, a tab that goes away mid-call, `closeTarget`, `--stop`, `--max-tabs`, `--quiet`, the first-visit latch through `preview.state.update`, `--logs`, `--truncate`, and an emit full of escape sequences. `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
421
+ - `npm test` builds `scserve` and runs `test/integration/` with Node's test runner. The hub there is `fake-hub.mjs`: trays, leader election, the controller WebSocket (`preview.request` to the relay and the chunks back, `preview.revoked`), mint, upload, finalize, stop and list, a visitor path that resolves `<label>.localhost` hosts like the preview worker, and injected answers per route for every class of error. Tests never reach `www.sliccy.ai`. `seven.test.mjs` installs the package (its staged `package.json`, from `scripts/targets.mjs`) with `bin/serve.wasm` (after `npm run build:wasm`), wasm-bash and wasm-coreutils in a node kernel from `@ai-ecoverse/slicc-kernel` (Node 26), behind a fake page that answers `serve.publish`, `serve.list`, `serve.stop` and `open.url` and records each request: the background `serve`, the page ending a preview, a killed holder revoking, `--port`, `--foreground`, `--open`, `--list` and `--stop` by token, URL and port, each errno and each class of hub failure, and a hostile directory name in the header; then a kernel no page answers, and slicc-kernel 1.152.2 (the devDependency `slicc-kernel-without-embedder`), which refuses the package and, with `engines` stripped, has no `/dev/embedder`. `seven-ttl.test.mjs` does the same for `--ttl`, with a fake page that implements `serve.snapshot` against `fake-hub.mjs` (it reads the body, mints, uploads, finalizes, and stops what it minted on a failure): the files that reach the hub, `--json`, `--entry`, `--open`, a file past the request window, the limits checked before the page is asked, each hub failure (mint, upload, finalize, with a 3 MiB body answered early), the page's refusals, and a `serve` killed before the finalize. `browser.test.mjs` opens the preview in a real Chrome for Testing (a pinned version, installed with `@ai-ecoverse/slicc-cdp`'s `installBrowser` into `node_modules/.cache/browsers` and launched headless with `launchBrowser`), where the fake hub injects slicc 6's real bridge bootstrap (`@ai-ecoverse/cherry`'s `preview-bridge.js`, the bundle slicc's worker serves); `playwright-cli` then snapshots, clicks, fills, types and presses Enter in it through `scserve --bridge`, and the test reads the page's own state to check each happened exactly once, and that `Runtime.callFunctionOn` on a handle doesn't run the handle's expression again. `slicc-cdp.test.mjs` downloads `playwright-cli` and `curlwright` for the platform from a pinned [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp) release (checked against its `SHA256SUMS`, cached in `node_modules/.cache/`) and runs them against a visitor tab (`visitor.mjs`, which answers as the hub's bootstrap does, evaluating in a `node:vm` context with a stand-in `document`): `tab-list`, `eval`, `snapshot`, `screenshot`, `goto`, a `curlwright` request, and a relay reconnect that keeps one tab's target id and drops a tab that closed meanwhile. `bridge.test.mjs` plays the visitor's tab against the fake hub's `/__slicc/bridge` (`hub.tab(url)`, answering `cdp.req` frames and sending emits) and drives the relay's CDP endpoint with Node's `WebSocket`: the guards (secret, `Host`, `Origin`), `/json/*`, discovery, attach and auto-attach, the synthetic and forwarded methods, navigation events, a tab that goes away mid-call, `closeTarget`, `--stop`, `--max-tabs`, `--quiet`, the first-visit latch through `preview.state.update`, `--logs`, `--truncate`, and an emit full of escape sequences. `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
421
422
  - `npm run test:unit` runs the unit tests in the gitignored `test/unit/` with `cargo llvm-cov`; the pre-commit hook wants 100% coverage of the changed lines in the crates it measures.
422
423
 
423
424
  CI is `.github/workflows/ci.yml` on [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web): lint, the integration tests on Linux, `npm run test:windows` on Windows, the same tests on macOS, `cargo check` for every release target, and the reviews. On a push to `main`, semantic-release tags a release; then the binaries are built for every target (the darwin ones signed and notarized), collected with `serve.wasm` into `SHA256SUMS` (attested), attached to the release with both installers, installed once through `install.sh`, and published to npm as `@ai-ecoverse/slicc-serve` and its six platform packages.
package/bin/serve.wasm CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-ecoverse/slicc-serve",
3
- "version": "1.3.0",
3
+ "version": "1.3.1",
4
4
  "description": "serve and scserve: publish a directory or a local server at a public capability URL through the SLICC tray hub, on any host and inside SLICC",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -31,11 +31,11 @@
31
31
  }
32
32
  },
33
33
  "optionalDependencies": {
34
- "@ai-ecoverse/slicc-serve-darwin-arm64": "1.3.0",
35
- "@ai-ecoverse/slicc-serve-darwin-x64": "1.3.0",
36
- "@ai-ecoverse/slicc-serve-linux-arm64": "1.3.0",
37
- "@ai-ecoverse/slicc-serve-linux-x64": "1.3.0",
38
- "@ai-ecoverse/slicc-serve-win32-arm64": "1.3.0",
39
- "@ai-ecoverse/slicc-serve-win32-x64": "1.3.0"
34
+ "@ai-ecoverse/slicc-serve-darwin-arm64": "1.3.1",
35
+ "@ai-ecoverse/slicc-serve-darwin-x64": "1.3.1",
36
+ "@ai-ecoverse/slicc-serve-linux-arm64": "1.3.1",
37
+ "@ai-ecoverse/slicc-serve-linux-x64": "1.3.1",
38
+ "@ai-ecoverse/slicc-serve-win32-arm64": "1.3.1",
39
+ "@ai-ecoverse/slicc-serve-win32-x64": "1.3.1"
40
40
  }
41
41
  }