@ai-ecoverse/slicc-capture 1.1.0 → 1.3.0

package/README.md

@@ -13,7 +13,7 @@ screencapture -T 3 -R 0,0,800,600 -t jpg crop.jpg
 
 ## Install
 
-In SLICC, the package declares `screencapture` and `sccapture` in `slicc.commands`, so installing it puts both in `/usr/bin`:
+In SLICC, the package declares `screencapture` and `sccapture` in `slicc.commands` (POSIX `sh` scripts in `bin/`), so installing it puts both in `/usr/bin`. They need slicc-kernel 1.153.0 or later, for [`/dev/embedder`](#the-request) (`engines.slicc-kernel` is `>=1.153.0`; an older kernel refuses them with exit 126 and `<cmd>: @ai-ecoverse/slicc-capture@<version> needs slicc-kernel >=1.153.0; this kernel is <version>`):
 
 ```sh
 pnpm add -g @ai-ecoverse/slicc-capture
@@ -72,33 +72,78 @@ Short options may be grouped (`-xc`), an option's value may be attached or separ
 
 ### In SLICC
 
-`screencapture file` asks seven's page to capture. `getDisplayMedia` needs a user gesture, so the page first shows a prompt, `screencapture wants to capture your screen`, with **Choose…** and **Cancel**; **Choose…** opens Chrome's picker. After the user picks, the command waits for `-T` seconds, if given, takes one frame, crops it to `-R`, if given, encodes it and stops the capture.
+`screencapture file` asks seven's page to capture, as a `capture.screen` request on `/dev/embedder` ([below](#the-request)). `getDisplayMedia` needs a user gesture, so the page first shows a prompt, `screencapture wants to capture your screen`, with **Choose…** and **Cancel**; **Choose…** opens Chrome's picker. After the user picks, the page waits for `-T` seconds, if given, takes one frame, crops it to `-R`, if given, encodes it and stops the capture. The command writes the bytes it gets back unchanged; an existing file is replaced only once the capture has arrived.
 
 - **The file:** written as PNG, JPEG or WebP: `-t` decides, else the file's extension (`.png`, `.jpg` or `.jpeg`, `.webp`), else PNG. JPEG and WebP use quality 0.92. On success it prints `captured <n> KB to <file>`.
-- **`-c`:** copies the capture to the clipboard as `image/png`, through [slicc-clipboard](https://github.com/ai-ecoverse/slicc-clipboard), and prints `captured <n> KB to clipboard`. A file named with `-c` is ignored, as with macOS's `-c`, and so is `-t`. slicc-clipboard's device is text only today; `-c` needs its image path, which is being added there.
-- **`-v`:** shows the capture inline in the agent's tool result. With a file, it writes the file and prints `<path> (<n> KB)` followed by the image; without one, it prints only the image; with `-c`, it copies and shows. slicc 6 printed the image as `<img:data:<type>;base64,<data>>`; seven's marker for an inline image is being agreed with slicc-agent, and `-v` uses whatever that is. macOS's `-v` (record a video) is out of scope everywhere.
+- **`-c`:** captures a PNG and copies it to the clipboard as `image/png`, with a `clipboard.write` request on `/dev/embedder`, which seven's embedder (slicc-bios) answers; [slicc-clipboard](https://github.com/ai-ecoverse/slicc-clipboard)'s `/dev/clipboard` stays text only. It prints `captured <n> KB to clipboard`. A file named with `-c` is ignored, as with macOS's `-c`, and so is `-t`. The `clipboard.write` request is sent before the prompt, so a page that doesn't answer it fails at once, without a capture.
+- **`-v`:** shows the capture inline in the agent's tool result, by printing one line `<img:<absolute path>>` on stdout, the marker agreed in [ai-ecoverse/slicc-agent#713](https://github.com/ai-ecoverse/slicc-agent/issues/713): the agent reads that file, detects PNG, JPEG, GIF or WebP by its magic bytes, fits the image to 1600 px wide and 1 MB of base64, and replaces the line with `<path> (<mime>, <bytes> bytes)` and the image in the tool result (at most 4 per command). With a file, `-v` writes it and prints only the marker for it; without one, it writes the capture to a new `${TMPDIR:-/tmp}/screencapture-XXXXXX.<type>`, which it leaves there for the agent, and prints the marker for that; with `-c`, it copies, prints `captured <n> KB to clipboard`, and then the marker of such a file. slicc 6's `<img:data:<type>;base64,<data>>` is gone: base64 on stdout is scrubbed and cut by the output tail. The agent's side of #713 isn't shipped yet; until it is, the marker shows as the line itself. macOS's `-v` (record a video) is out of scope everywhere.
 - **No file:** without a file, `-c` or `-v`: `screencapture: output file required (or use -c for clipboard)` and the usage to stderr, exit 2.
 
 Errors, on stderr, from slicc 6 where they still apply:
 
 | error | exit |
 | --- | --- |
-| `screencapture: user cancelled or permission denied` (**Cancel**, the picker closed, or the capture refused) | 1 |
-| `screencapture: timed out waiting for the picker` (no answer within 5 minutes) | 1 |
-| `screencapture: browser APIs are unavailable in this environment` (an embedder that doesn't answer capture requests) | 1 |
-| `screencapture: screen capture is not supported in this browser` (no `getDisplayMedia`) | 1 |
-| `screencapture: -R: rectangle outside the capture` | 1 |
-| `screencapture: failed to write file: <message>` | 1 |
-| `screencapture: failed to copy to clipboard: <message>` | 1 |
+| `screencapture: user cancelled, permission denied, or the surface is protected` (`EACCES`: **Cancel**, the picker closed, the capture refused, or the embedder refused the surface the user picked) | 1 |
+| `screencapture: timed out waiting for the picker` (no answer within 5 minutes; the page's message) | 1 |
+| `screencapture: browser APIs are unavailable in this environment` (`ENOTSUP` for the header: no page answers `capture.screen`) | 1 |
+| `screencapture: screen capture is not supported in this browser` (`ENOTSUP` from the page, without a message of its own: no `getDisplayMedia`) | 1 |
+| `screencapture: -R: rectangle outside the capture` (the page's message) | 1 |
+| `screencapture: <message>` (any other error of the page, `EIO` or `ENOENT`: the first line of its message, else the errno's text, such as `I/O error`) | 1 |
+| `screencapture: the page sent no image` (an empty reply) | 1 |
+| `screencapture: interrupted` (`SIGHUP`, `SIGINT` or `SIGTERM` during the request: the command stops the reader, so the page's `signal` aborts with `interrupted`, removes its temporary files and writes no file) | `128 + n` |
+| `screencapture: failed to write file: <file>: <message>` | 1 |
+| `screencapture: failed to copy to clipboard: this page does not copy images (no clipboard.write)` (`ENOTSUP`: no page answers `clipboard.write`) | 1 |
+| `screencapture: failed to copy to clipboard: <message>` (the page's message, else the errno's text) | 1 |
+| `screencapture: /dev/embedder not available (needs slicc-kernel >= 1.153.0)` (a kernel that runs the commands without the device) | 1 |
 | `screencapture: unknown option: <arg>`, then the usage | 2 |
 | `screencapture: <opt>: not supported in SLICC` | 2 |
 | `screencapture: -t <format>: not supported in SLICC` | 2 |
 | `screencapture: -T: invalid delay: <value>`, `-R: invalid rectangle: <value>`, `-D: invalid display: <value>`, `-J: invalid style: <value>` | 2 |
 | `screencapture: more than one file: not supported in SLICC` | 2 |
 
-As `sccapture`, the messages start with `sccapture:`.
+As `sccapture`, the messages start with `sccapture:`. A line of progress from the page (`progress(line)`) reaches stderr as `<cmd>: <line>` while the command waits.
 
-**The bridge from the kernel to the page is not settled yet.** The commands run in a kernel worker, which has no `getDisplayMedia`, so a request has to reach seven's page and the frame has to come back. slicc-clipboard does this with a kernel character device that the kernel answers from its embedder's hook; slicc-open, slicc-capture and slicc-audio are agreeing one pattern for all three in [ai-ecoverse/slicc-kernel#1527](https://github.com/ai-ecoverse/slicc-kernel/issues/1527) (pending), with the kernel and seven's embedder (slicc-bios). Until then this section describes only what the user sees. The page side (the prompt, `getDisplayMedia`, the frame, the crop and the encoding) ships in this package for the embedder; its entry point, the transport and the `engines.slicc-kernel` it needs are added here once the pattern is agreed.
+### The request
+
+The commands run in a kernel worker, which has no `getDisplayMedia`, so they ask seven's page over [`/dev/embedder`](https://github.com/ai-ecoverse/slicc-kernel#devembedder) (slicc-kernel 1.153.0, [#1527](https://github.com/ai-ecoverse/slicc-kernel/issues/1527)): one open file description per request, a JSON header line `{ kind, …options }`, then the body, and the reply read to end-of-file. The page side, the prompt, `getDisplayMedia`, the frame, the crop and the encoding, is [a page module](#the-page-module) that slicc-bios registers for `capture.screen` and wraps with its own prompt, user activation, `selfBrowserSurface: 'exclude'` and a check of the picked surface against protected origins; it answers this contract:
+
+- **`capture.screen`:** the header is plain JSON, with no body, and the reply is the encoded image's bytes, nothing else. The command opens the device read-write (`exec 3<>/dev/embedder`), writes the header from a child `sh` that stays until the reply is read (so the page's progress reaches stderr), and reads the reply with a `cat <&3` that it starts in the background, so that a signal to the command can stop it.
+
+| header field | value | from |
+| --- | --- | --- |
+| `kind` | `"capture.screen"` | |
+| `type` | `"image/png"`, `"image/jpeg"` or `"image/webp"` | `-t`, else the file's extension, else PNG; always PNG with `-c` |
+| `quality` | `0.92`, only for JPEG and WebP | |
+| `cursor` | `"always"` or `"never"`, for `getDisplayMedia`'s `cursor` | `-C` |
+| `surface` | `"monitor"` or `"window"`, absent without one, for `displaySurface` (a hint: the user still picks) | `-m` and `-D` give `"monitor"`; `-w`, `-W` and `-J window` give `"window"`; the last one wins |
+| `delay` | seconds as a JSON number (`3`, `0.5`), absent without `-T`; the page waits that long after the picker | `-T` |
+| `rect` | `{ "x", "y", "width", "height" }`, whole numbers in the frame's pixels, absent without `-R`; outside the frame, the page rejects with `-R: rectangle outside the capture` | `-R` |
+
+For example, `screencapture -C -T 2 -R 0,0,800,600 shot.jpg` sends `{"kind":"capture.screen","type":"image/jpeg","quality":0.92,"cursor":"always","delay":2,"rect":{"x":0,"y":0,"width":800,"height":600}}`. The page rejects with a `NotAllowedError` or `AbortError` for **Cancel**, a closed picker, a refused permission or a protected surface (`EACCES`); a `NotSupportedError` without `getDisplayMedia` (`ENOTSUP`); and any other error, such as a `TimeoutError` `timed out waiting for the picker` after 5 minutes, with the message the command prints (`EIO`). It aborts the capture when its `signal` does.
+- **`clipboard.write`:** `-c` sends `{"kind":"clipboard.write","type":"image/png"}` and the PNG as the body, and reads the reply, which is empty, to end-of-file. slicc-bios answers it; with no page that does, the header write fails with `ENOTSUP`. The device is opened read-write and the reply read only after the whole body is written, so a page that answers without reading the body ([slicc-kernel#1536](https://github.com/ai-ecoverse/slicc-kernel/issues/1536)) is the only way a body over 1 MiB could block; the embedder's handler reads it.
+
+### The page module
+
+`@ai-ecoverse/slicc-capture/page` is that page module: one plain ES module (`page/index.mjs`), with no build step and no dependencies, which runs in Chrome and loads in Node. It answers `capture.screen` and nothing else; `clipboard.write` is the embedder's own.
+
+```js
+import capture, { create, handle, kinds } from '@ai-ecoverse/slicc-capture/page';
+
+createKernel({
+  requests: {
+    kinds: capture.kinds,
+    handle: (request) => capture.handle({ ...request, display: guardedGetDisplayMedia }),
+  },
+});
+```
+
+- **The exports:** `kinds` is `{ 'capture.screen': {} }`, with no policy; `handle(request)` is a [`/dev/embedder` hook](https://github.com/ai-ecoverse/slicc-kernel#devembedder)'s `handle`; the default export is `{ kinds, handle }`. `create({ ImageCapture, OffscreenCanvas, document, timeout })` returns another `{ kinds, handle }` that uses those instead of the page's globals, and `timeout` (in ms, 5 minutes by default) for the picker; the tests inject fakes through it.
+- **`display` is required:** the request is the kernel's (`{ kind, options, body, stamp, signal, progress }`) plus `display(constraints)`, the embedder's `getDisplayMedia`, which resolves to a `MediaStream`. The module never calls `navigator.mediaDevices.getDisplayMedia` itself; without `display`, or without `OffscreenCanvas` and a way to grab a frame (`ImageCapture`, else `document`), it rejects with a `NotSupportedError` `screen capture is not supported in this browser` (`ENOTSUP`).
+- **The header:** `type` (PNG by default), `quality`, `cursor`, `surface`, `delay` and `rect` as in [the table above](#the-request); other keys are ignored. A `type` it doesn't encode rejects with a `NotSupportedError` `unsupported type: <type>`, and a value of the wrong shape with a `TypeError` `invalid <field>: <json>` (`EIO`), before `display` is called.
+- **The capture:** it calls `display({ video: { cursor, displaySurface }, audio: false })` (each field only when the header has it: `cursor` as is, `surface` as `displaySurface`) after `progress('waiting for the picker…')`. No stream within the timeout rejects with a `TimeoutError` `timed out waiting for the picker`, one without a video track with a `NotFoundError` `the capture has no video track` (`ENOENT`), and one whose track has ended, or ends before the frame (the user's **Stop sharing**), with an `AbortError` `the capture was stopped` (`EACCES`). With a `delay`, it says `waiting <delay> s…` and waits that long. It grabs one frame with `ImageCapture.grabFrame()`, else from a muted `<video>` once it has data, crops it to `rect` (outside the frame: a `RangeError` `-R: rectangle outside the capture`), draws it on an `OffscreenCanvas` and encodes it with `convertToBlob({ type, quality })`. A browser that encodes another type than asked rejects with a `NotSupportedError` `<type> is not supported by this browser`. It resolves with the bytes, a `Uint8Array`.
+- **Stopping:** every track of the stream is stopped when `handle` settles, whether it resolved, failed or was aborted, and so is a stream that `display` delivers after the timeout or an abort. When `signal` aborts, `handle` rejects with an `AbortError` carrying the reason's message (`interrupted`, `closed`, or the embedder's own).
+
+**What slicc-bios does around it:** bios registers its own `kinds` table, of which the module's is a subset, and ignores the module's policies. It owns the prompt (`screencapture wants to capture your screen`, **Choose…**, **Cancel**), the user activation `getDisplayMedia` needs, the session tag and the protected origins, and calls `handle` only after its checks pass. Its `display` is a guarded `getDisplayMedia`: it adds `selfBrowserSurface: 'exclude'`, checks the picked surface's capture handle against the protected origins, and rejects with a `NotAllowedError` on a match. Its `signal` also aborts when its prompt is withdrawn.
 
 ### Options
 
@@ -109,8 +154,8 @@ Every option of macOS's `screencapture`, and what it does in SLICC and with `scc
 | `-a` | don't capture attached windows | no-op | passed | no-op | no-op |
 | `-b` | capture the Touch Bar | not supported | passed | not supported | not supported |
 | `-B <bundleid>` | open in that app | not supported | passed | not supported | not supported |
-| `-c` | to the clipboard | through slicc-clipboard, as `image/png` | passed | see [Linux](#linux) | `Clipboard.SetImage` |
-| `-C` | include the cursor | asks for `cursor: 'always'` (else `'never'`), which the browser may not honour | passed | see [Linux](#linux) | draws the cursor into the image |
+| `-c` | to the clipboard | a `clipboard.write` request, as `image/png` | passed | see [Linux](#linux) | `Clipboard.SetImage` |
+| `-C` | include the cursor | `"cursor": "always"` (else `"never"`), which the browser may not honour | passed | see [Linux](#linux) | draws the cursor into the image |
 | `-d` | show errors graphically | no-op | passed | no-op | no-op |
 | `-D <display>` | that display (1 is main) | prefers `displaySurface: 'monitor'`; the user picks the screen | passed | not supported | screen *n*: 1 is the primary, then the others in `AllScreens` order; no such screen is `sccapture: -D <n>: no such display`, exit 1 |
 | `-g` | record default audio input | not supported | not supported | not supported | not supported |
@@ -132,7 +177,7 @@ Every option of macOS's `screencapture`, and what it does in SLICC and with `scc
 | `-T <seconds>` | wait before capturing | waits after the picker | passed | `sccapture` waits, then runs the tool | `sccapture` waits, then captures |
 | `-u` | show the UI afterwards, file ignored | not supported | passed | not supported | not supported |
 | `-U` | the interactive toolbar | not supported | passed | not supported | not supported |
-| `-v` | record a video | inline in the tool result (slicc 6's `-v`) | not supported | not supported | not supported |
+| `-v` | record a video | inline in the tool result, as an `<img:<path>>` line ([slicc-agent#713](https://github.com/ai-ecoverse/slicc-agent/issues/713)) | not supported | not supported | not supported |
 | `-V <seconds>` | record a video for that long | not supported | not supported | not supported | not supported |
 | `-w` | window selection only | prefers `displaySurface: 'window'` | passed | see [Linux](#linux) | not supported |
 | `-W` | start in window selection | prefers `displaySurface: 'window'` | passed | as `-w` | not supported |
@@ -201,9 +246,10 @@ npm run test:unit
 ```
 
 - `npm install` also installs the git hooks into this worktree's own `node_modules/` through slicc-shared-web's `slicc-install-hooks` and the committed `.githooks/`.
-- `npm run lint`: Biome, the no-comment check and the other [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web) checks, then `shellcheck -s sh` and `dash -n` on `install.sh`.
-- `npm test`: the integration tests in `test/integration/`. `test/integration/repo.test.mjs` checks the workflow, the release config, the pinned devDependencies and what `npm pack` ships. The host tests run `host/` against fake `screencapture`, `grim`, `slurp`, `gnome-screenshot`, `import`, `scrot`, `wl-copy`, `xclip`, `xdg-open`, `powershell.exe` and `pwsh.exe` on a temporary `PATH`, and `--upgrade` against installers served from a local HTTP server, with the platform forced, so each branch is checked on any machine; only CI touches a real screen. `install.test.mjs` runs `install.sh` on a tarball packed from the tree, with the Node on `PATH` and with a Node download from a fake `nodejs.org`, and `--upgrade` against a release served from a local directory; `install.ps1` is checked statically, and run when `pwsh` is on `PATH`.
-- `npm run test:unit`: the unit tests in the gitignored `test/unit/`, with coverage in `coverage/unit/lcov.info`. The pre-commit hook wants 100% coverage of the changed lines, and runs `diff-cover` through `uvx`, so install [uv](https://docs.astral.sh/uv/) once.
+- `npm run lint`: Biome, the no-comment check and the other [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web) checks, then `shellcheck -s sh` and `dash -n` on `install.sh` and `bin/*`.
+- `npm test`: the integration tests in `test/integration/`. `commands.test.mjs` runs `screencapture` and `sccapture` on `@ai-ecoverse/slicc-kernel/node` (the version `engines.slicc-kernel` names, pinned) with wasm-bash and wasm-coreutils, and a fake `capture.screen` and `clipboard.write` handler (`createNodeKernel({ requests })`): every option's header, the bytes written unchanged, the errnos and their messages, `-c`, `-v`, and slicc-kernel 1.152.2, which has no `/dev/embedder`. `test/integration/repo.test.mjs` checks the workflow, the release config, the pinned devDependencies and what `npm pack` ships. The host tests run `host/` against fake `screencapture`, `grim`, `slurp`, `gnome-screenshot`, `import`, `scrot`, `wl-copy`, `xclip`, `xdg-open`, `powershell.exe` and `pwsh.exe` on a temporary `PATH`, and `--upgrade` against installers served from a local HTTP server, with the platform forced, so each branch is checked on any machine; only CI touches a real screen. `install.test.mjs` runs `install.sh` on a tarball packed from the tree, with the Node on `PATH` and with a Node download from a fake `nodejs.org`, and `--upgrade` against a release served from a local directory; `install.ps1` is checked statically, and run when `pwsh` is on `PATH`.
+- `page.test.mjs` registers [the page module](#the-page-module) through `createNodeKernel({ requests })`, with a fake `display` and fake `ImageCapture`, `OffscreenCanvas` and `<video>` injected through `create`, and runs the real `screencapture`: the constraints, the crop, the type and quality, the delay and its progress, an interrupt in the picker and in the delay, **Stop sharing**, the picker's timeout, the errnos and their messages end to end, and that every track is stopped. `browser.test.mjs` runs the module in Chrome, through slicc-shared-web's harness, with a `display` that returns a canvas's `captureStream()`: PNG, JPEG and WebP, the crop, the `<video>` fallback, an abort and the stopped track. It runs on CI only, and is skipped without `CI`.
+- `npm run test:unit`: the unit tests in the gitignored `test/unit/`, with coverage in `coverage/unit/lcov.info`. `npm run test:sh` runs the `test/unit/*.sh.mjs` ones, which trace `bin/` with `set -x` in the node kernel, and writes `coverage/sh/lcov.info`. The pre-commit hook wants 100% coverage of the changed lines of both, and runs `diff-cover` through `uvx`, so install [uv](https://docs.astral.sh/uv/) once.
 
 CI is `.github/workflows/ci.yml`, the only workflow, which runs [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline) at the devDependency's version: `npm run lint`, then `npm test`, then on a pull request the Claude and Codex reviews. The merge queue requires `ci / integration` and `ci / review`. On a push to `main`, semantic-release releases and publishes to npm through trusted publishing, with provenance from `ci.yml`, and attaches the installers.
 

package/bin/sccapture

@@ -0,0 +1,2 @@
+#!/bin/sh
+. "${0%/*}/screencapture"

package/bin/screencapture

@@ -0,0 +1,310 @@
+#!/bin/sh
+me=${0##*/}
+dev=/dev/embedder
+usage() {
+  printf 'usage: %s [-acdimorvwxCW] [-t format] [-T seconds] [-R x,y,w,h] [-D display] [-J style] [file]\n' "$me"
+}
+say() {
+  printf '%s: %s\n' "$me" "$1" >&2
+}
+bad() {
+  say "$1"
+  usage >&2
+  exit 2
+}
+refuse() {
+  say "$1"
+  exit 2
+}
+die() {
+  say "$1"
+  exit 1
+}
+first() {
+  [ -n "$problem" ] || problem=$1
+}
+num() {
+  n=$1
+  while :; do
+    case $n in
+      0[0-9]*) n=${n#0} ;;
+      *) break ;;
+    esac
+  done
+  printf '%s' "$n"
+}
+digits() {
+  case $1 in
+    '' | *[!0-9]*) return 1 ;;
+  esac
+}
+delay() {
+  case $1 in
+    '' | .* | *. | *.*.* | *[!0-9.]*) return 1 ;;
+  esac
+}
+rect() {
+  case $1 in
+    *,*,*,*,*) return 1 ;;
+    *,*,*,*) ;;
+    *) return 1 ;;
+  esac
+  rx=${1%%,*}
+  rest=${1#*,}
+  ry=${rest%%,*}
+  rest=${rest#*,}
+  rw=${rest%%,*}
+  rh=${rest#*,}
+  digits "$rx" && digits "$ry" && digits "$rw" && digits "$rh" || return 1
+  [ "$(num "$rw")" != 0 ] && [ "$(num "$rh")" != 0 ]
+}
+format() {
+  case $1 in
+    [pP][nN][gG]) printf png ;;
+    [jJ][pP][gG] | [jJ][pP][eE][gG]) printf jpeg ;;
+    [wW][eE][bB][pP]) printf webp ;;
+  esac
+}
+value() {
+  case $1 in
+    T)
+      delay "$2" || first "-T: invalid delay: $2"
+      wait=$2
+      ;;
+    R)
+      rect "$2" || first "-R: invalid rectangle: $2"
+      area=$2
+      ;;
+    D)
+      case $2 in
+        [1-9]*) digits "$2" || first "-D: invalid display: $2" ;;
+        *) first "-D: invalid display: $2" ;;
+      esac
+      surface=monitor
+      ;;
+    J)
+      case $2 in
+        window) surface=window ;;
+        selection | video) style=${style:-"-J $2: not supported in SLICC"} ;;
+        *) first "-J: invalid style: $2" ;;
+      esac
+      ;;
+    t) type=$2 ;;
+    *) off=${off:-"-$1"} ;;
+  esac
+}
+flag() {
+  case $1 in
+    c) clip=1 ;;
+    C) cursor=always ;;
+    v) view=1 ;;
+    m) surface=monitor ;;
+    w | W) surface=window ;;
+    a | d | i | o | r | x) ;;
+    *) off=${off:-"-$1"} ;;
+  esac
+}
+version() {
+  while IFS= read -r line; do
+    case $line in
+      *'"version": "'*)
+        line=${line#*'"version": "'}
+        printf '%s\n' "${line%%\"*}"
+        return
+        ;;
+    esac
+  done <"${0%/*}/../package.json"
+}
+relay() {
+  while IFS= read -r line; do
+    case $line in
+      *": $dev: "*) printf '%s\n' "${line#*": $dev: "}" >"$work/message" ;;
+      *": printf: write error: "*) printf '%s\n' "${line##*: }" >"$work/header" ;;
+      "cat: -: "* | "cat: write error: "*) printf '%s\n' "${line##*: }" >"$work/errno" ;;
+      *) printf '%s: %s\n' "$me" "${line#*: }" >&2 ;;
+    esac
+  done
+}
+ask() {
+  rm -f "$work/message" "$work/header" "$work/errno"
+  { { "$@"; } 2>&1 >&5 | relay; } 5>&1 &
+  wait "$!"
+  header=
+  errno=
+  message=
+  [ ! -f "$work/header" ] || header=$(cat "$work/header")
+  [ ! -f "$work/errno" ] || errno=$(cat "$work/errno")
+  [ ! -f "$work/message" ] || message=$(cat "$work/message")
+  errno=${errno:-$header}
+  [ -z "$errno" ]
+}
+because() {
+  printf '%s' "${message:-$errno}"
+}
+copyfail() {
+  case $header in
+    "Not supported") die "failed to copy to clipboard: this page does not copy images (no clipboard.write)" ;;
+  esac
+  die "failed to copy to clipboard: $(because)"
+}
+stop() {
+  [ ! -s "$work/pid" ] || kill -TERM "$(cat "$work/pid")" 2>/dev/null
+  wait
+  say interrupted
+  exit $((128 + $1))
+}
+absolute() {
+  case $1 in
+    */*) dir=${1%/*} base=${1##*/} ;;
+    *) dir=. base=$1 ;;
+  esac
+  dir=$(cd -- "${dir:-/}" && pwd)
+  printf '%s/%s' "${dir%/}" "$base"
+}
+cleanup() {
+  rm -rf "$work"
+}
+argc=$#
+clip=
+view=
+cursor=never
+surface=
+wait=
+area=
+type=
+style=
+off=
+problem=
+wrong=
+special=
+help=
+ended=
+files=0
+file=
+while [ $# -gt 0 ]; do
+  arg=$1
+  shift
+  if [ -n "$ended" ]; then
+    files=$((files + 1))
+    file=${file:-$arg}
+    continue
+  fi
+  case $arg in
+    --) ended=1 ;;
+    --help) help=1 ;;
+    --version | --upgrade) special=${special:-$arg} ;;
+    --clipboard) clip=1 ;;
+    --view) view=1 ;;
+    --*) wrong=${wrong:-"unknown option: $arg"} ;;
+    -?*)
+      rest=${arg#-}
+      while [ -n "$rest" ]; do
+        letter=${rest%"${rest#?}"}
+        rest=${rest#?}
+        case $letter in
+          h) help=1 ;;
+          [BDGJlRtTV])
+            if [ -n "$rest" ]; then
+              value "$letter" "$rest"
+            elif [ $# -gt 0 ]; then
+              value "$letter" "$1"
+              shift
+            else
+              wrong=${wrong:-"-$letter: option requires a value"}
+            fi
+            rest=
+            ;;
+          [abcCdgikmMoprPsSuUvwWx]) flag "$letter" ;;
+          *)
+            wrong=${wrong:-"unknown option: -$letter"}
+            rest=
+            ;;
+        esac
+      done
+      ;;
+    *)
+      files=$((files + 1))
+      file=${file:-$arg}
+      ;;
+  esac
+done
+if [ -n "$help" ]; then
+  usage
+  exit 0
+fi
+[ -z "$wrong" ] || bad "$wrong"
+if [ -n "$special" ]; then
+  [ "$argc" -eq 1 ] || bad "$special: takes no other arguments"
+  if [ "$special" = --upgrade ]; then
+    printf 'pnpm add -g @ai-ecoverse/slicc-capture@latest\n'
+  else
+    version
+  fi
+  exit 0
+fi
+[ -z "$off" ] || refuse "$off: not supported in SLICC"
+[ -z "$problem" ] || refuse "$problem"
+[ -z "$style" ] || refuse "$style"
+mime=png
+if [ -n "$clip" ]; then
+  file=
+  files=0
+elif [ -n "$type" ]; then
+  mime=$(format "$type")
+  [ -n "$mime" ] || refuse "-t $type: not supported in SLICC"
+else
+  case $file in
+    *.[jJ][pP][gG] | *.[jJ][pP][eE][gG]) mime=jpeg ;;
+    *.[wW][eE][bB][pP]) mime=webp ;;
+  esac
+fi
+[ "$files" -le 1 ] || refuse "more than one file: not supported in SLICC"
+[ -n "$file" ] || [ -n "$clip" ] || [ -n "$view" ] || bad "output file required (or use -c for clipboard)"
+[ -c "$dev" ] || die "$dev not available (needs slicc-kernel >= 1.153.0)"
+request="{\"kind\":\"capture.screen\",\"type\":\"image/$mime\""
+[ "$mime" = png ] || request="$request,\"quality\":0.92"
+request="$request,\"cursor\":\"$cursor\""
+[ -z "$surface" ] || request="$request,\"surface\":\"$surface\""
+[ -z "$wait" ] || request="$request,\"delay\":$(num "${wait%%.*}")${wait#"${wait%%.*}"}"
+[ -z "$area" ] || request="$request,\"rect\":{\"x\":$(num "$rx"),\"y\":$(num "$ry"),\"width\":$(num "$rw"),\"height\":$(num "$rh")}"
+request="$request}"
+work=$(mktemp -d)
+trap cleanup EXIT
+trap 'stop 1' HUP
+trap 'stop 2' INT
+trap 'stop 15' TERM
+if [ -n "$clip" ]; then
+  exec 4<>"$dev"
+  ask sh -c "printf '%s\\n' \"\$1\" >&4" sh '{"kind":"clipboard.write","type":"image/png"}' || copyfail
+fi
+exec 3<>"$dev"
+if ! ask sh -c "printf '%s\\n' \"\$1\" >&3 || exit 1; cat <&3 & echo \$! >\"\$2\"; wait \$!" sh "$request" "$work/pid" >"$work/image"; then
+  case $header in
+    "Not supported") die "browser APIs are unavailable in this environment" ;;
+  esac
+  case $errno in
+    "Permission denied") die "user cancelled, permission denied, or the surface is protected" ;;
+    "Not supported") die "${message:-screen capture is not supported in this browser}" ;;
+  esac
+  die "$(because)"
+fi
+exec 3<&-
+size=$(wc -c <"$work/image")
+[ "$size" -gt 0 ] || die "the page sent no image"
+kb=$(((size + 512) / 1024))
+if [ -n "$clip" ]; then
+  ask cat "$work/image" >&4 || copyfail
+  ask sh -c 'cat <&4' >/dev/null || copyfail
+  exec 4<&-
+  printf 'captured %s KB to clipboard\n' "$kb"
+fi
+if [ -z "$file" ]; then
+  [ -n "$view" ] || exit 0
+  file=$(mktemp "${TMPDIR:-/tmp}/screencapture-XXXXXX.$mime")
+fi
+err=$(tee -- "$file" <"$work/image" 2>&1 >/dev/null) || die "failed to write file: ${err#tee: }"
+if [ -n "$view" ]; then
+  printf '<img:%s>\n' "$(absolute "$file")"
+elif [ -z "$clip" ]; then
+  printf 'captured %s KB to %s\n' "$kb" "$file"
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "screencapture for SLICC, and sccapture for SLICC and any host",
   "type": "module",
   "license": "Apache-2.0",
@@ -9,11 +9,16 @@
     "url": "git+https://github.com/ai-ecoverse/slicc-capture.git"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24",
+    "slicc-kernel": ">=1.153.0"
   },
   "bin": {
     "sccapture": "host/sccapture.mjs"
   },
+  "exports": {
+    "./page": "./page/index.mjs",
+    "./package.json": "./package.json"
+  },
   "fledgling": {
     "provider": "github",
     "workflow": "ci.yml",
@@ -25,30 +30,47 @@
     "provenance": true
   },
   "slicc": {
+    "commands": {
+      "screencapture": {
+        "script": "bin/screencapture"
+      },
+      "sccapture": {
+        "script": "bin/sccapture"
+      }
+    },
     "unitSources": [
-      "host"
+      "host",
+      "page"
     ]
   },
   "files": [
-    "host"
+    "bin",
+    "host",
+    "page"
   ],
   "scripts": {
     "prepare": "slicc-install-hooks",
-    "lint": "slicc-lint && shellcheck -s sh install.sh && dash -n install.sh",
+    "lint": "slicc-lint && shellcheck -s sh -e SC1091 install.sh bin/* && for f in install.sh bin/*; do dash -n \"$f\" || exit 1; done",
     "format": "biome check --write .",
     "test": "node --test --test-timeout=120000 test/integration/*.test.mjs",
     "test:unit": "mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'",
+    "test:sh": "node scripts/cover.mjs",
     "build": "npm pack --dry-run",
     "trust": "npx fledgling sync -y --skip-publish",
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "2.11.3",
+    "@ai-ecoverse/slicc-cdp": "1.40.0",
+    "@ai-ecoverse/slicc-kernel": "1.153.0",
+    "@ai-ecoverse/slicc-shared-web": "2.12.0",
+    "@ai-ecoverse/wasm-bash": "5.3.0-23",
+    "@ai-ecoverse/wasm-coreutils": "9.12.0-15",
     "@biomejs/biome": "2.5.15",
     "@semantic-release/exec": "7.1.0",
     "lefthook": "2.2.2",
     "monocart-coverage-reports": "2.13.2",
-    "semantic-release": "25.0.9"
+    "semantic-release": "25.0.9",
+    "slicc-kernel-without-embedder": "npm:@ai-ecoverse/slicc-kernel@1.152.2"
   }
 }

package/page/index.mjs

@@ -0,0 +1,199 @@
+const types = ['image/png', 'image/jpeg', 'image/webp'];
+const cursors = ['always', 'motion', 'never'];
+const surfaces = ['monitor', 'window', 'browser'];
+const unsupported = 'screen capture is not supported in this browser';
+
+export const kinds = { 'capture.screen': {} };
+
+function fail(name, message) {
+  return new DOMException(message, name);
+}
+
+function aborted(signal) {
+  const reason = signal.reason;
+  if (reason?.name === 'AbortError') return reason;
+  return fail('AbortError', String(reason?.message ?? reason));
+}
+
+function race(promise, signal) {
+  return new Promise((resolve, reject) => {
+    const stop = () => reject(aborted(signal));
+    if (signal.aborted) stop();
+    signal.addEventListener('abort', stop, { once: true });
+    Promise.resolve(promise)
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener('abort', stop));
+  });
+}
+
+function sleep(ms, signal) {
+  let timer;
+  const wait = new Promise((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  return race(wait, signal).finally(() => clearTimeout(timer));
+}
+
+function stopAll(stream) {
+  for (const track of stream?.getTracks?.() ?? []) track.stop();
+}
+
+function invalid(field, value) {
+  return new TypeError(`invalid ${field}: ${JSON.stringify(value)}`);
+}
+
+const whole = (value, least) => Number.isInteger(value) && value >= least;
+
+function parse(options = {}) {
+  const { type = 'image/png', quality, cursor, surface, delay, rect } = options;
+  if (!types.includes(type)) throw fail('NotSupportedError', `unsupported type: ${type}`);
+  if (quality !== undefined && !(typeof quality === 'number' && quality >= 0 && quality <= 1)) {
+    throw invalid('quality', quality);
+  }
+  if (cursor !== undefined && !cursors.includes(cursor)) throw invalid('cursor', cursor);
+  if (surface !== undefined && !surfaces.includes(surface)) throw invalid('surface', surface);
+  if (delay !== undefined && !(Number.isFinite(delay) && delay >= 0)) throw invalid('delay', delay);
+  if (
+    rect !== undefined &&
+    !(whole(rect?.x, 0) && whole(rect?.y, 0) && whole(rect?.width, 1) && whole(rect?.height, 1))
+  ) {
+    throw invalid('rect', rect);
+  }
+  const video = {};
+  if (cursor !== undefined) video.cursor = cursor;
+  if (surface !== undefined) video.displaySurface = surface;
+  return {
+    constraints: { video, audio: false },
+    type,
+    quality,
+    delay: delay ?? 0,
+    rect,
+  };
+}
+
+async function pick(display, constraints, signal, timeout) {
+  const pending = Promise.resolve().then(() => display(constraints));
+  let timer;
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(fail('TimeoutError', 'timed out waiting for the picker')),
+      timeout
+    );
+  });
+  try {
+    return await race(Promise.race([pending, late]), signal);
+  } catch (error) {
+    pending.then(stopAll, () => {});
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function grab(stream, track, env, signal) {
+  const ImageCapture = env('ImageCapture');
+  if (ImageCapture) {
+    const bitmap = await race(new ImageCapture(track).grabFrame(), signal);
+    return {
+      source: bitmap,
+      width: bitmap.width,
+      height: bitmap.height,
+      close: () => bitmap.close?.(),
+    };
+  }
+  const video = env('document').createElement('video');
+  const close = () => {
+    video.pause();
+    video.srcObject = null;
+  };
+  const ready = new Promise((resolve, reject) => {
+    video.onloadedmetadata = () => video.play().catch(reject);
+    video.onloadeddata = resolve;
+    video.onerror = () => reject(new Error('the capture could not be played'));
+  });
+  video.muted = true;
+  video.playsInline = true;
+  video.srcObject = stream;
+  try {
+    await race(ready, signal);
+  } catch (error) {
+    close();
+    throw error;
+  }
+  return { source: video, width: video.videoWidth, height: video.videoHeight, close };
+}
+
+async function encode(frame, request, env, signal) {
+  const { type, quality, rect } = request;
+  const { x, y, width, height } = rect ?? { x: 0, y: 0, width: frame.width, height: frame.height };
+  if (!(frame.width > 0 && frame.height > 0)) throw new Error('the capture has no frame');
+  if (x + width > frame.width || y + height > frame.height) {
+    throw new RangeError('-R: rectangle outside the capture');
+  }
+  const canvas = new (env('OffscreenCanvas'))(width, height);
+  canvas.getContext('2d').drawImage(frame.source, x, y, width, height, 0, 0, width, height);
+  const blob = await race(
+    canvas.convertToBlob(quality === undefined ? { type } : { type, quality }),
+    signal
+  );
+  if (blob.type !== type)
+    throw fail('NotSupportedError', `${type} is not supported by this browser`);
+  return new Uint8Array(await race(blob.arrayBuffer(), signal));
+}
+
+export function create(overrides = {}) {
+  const env = (name) => (name in overrides ? overrides[name] : globalThis[name]);
+  const timeout = overrides.timeout ?? 300000;
+
+  async function handle({
+    options,
+    signal = new AbortController().signal,
+    progress = () => {},
+    display,
+  }) {
+    const request = parse(options);
+    if (typeof display !== 'function') throw fail('NotSupportedError', unsupported);
+    if (!env('OffscreenCanvas') || !(env('ImageCapture') || env('document'))) {
+      throw fail('NotSupportedError', unsupported);
+    }
+    const local = new AbortController();
+    const forward = () => local.abort(signal.reason);
+    if (signal.aborted) forward();
+    signal.addEventListener('abort', forward, { once: true });
+    let stream;
+    let frame;
+    try {
+      if (local.signal.aborted) throw aborted(local.signal);
+      progress('waiting for the picker…');
+      stream = await pick(display, request.constraints, local.signal, timeout);
+      const track = stream?.getVideoTracks?.()[0];
+      if (!track) throw fail('NotFoundError', 'the capture has no video track');
+      if (track.readyState === 'ended') throw fail('AbortError', 'the capture was stopped');
+      track.addEventListener(
+        'ended',
+        () => local.abort(fail('AbortError', 'the capture was stopped')),
+        {
+          once: true,
+        }
+      );
+      if (request.delay > 0) {
+        progress(`waiting ${request.delay} s…`);
+        await sleep(request.delay * 1000, local.signal);
+      }
+      frame = await grab(stream, track, env, local.signal);
+      return await encode(frame, request, env, local.signal);
+    } finally {
+      signal.removeEventListener('abort', forward);
+      frame?.close();
+      stopAll(stream);
+    }
+  }
+
+  return { kinds, handle };
+}
+
+const page = create();
+
+export const handle = page.handle;
+
+export default page;