@ai-ecoverse/slicc-capture 1.0.0 → 1.2.0

package/README.md

@@ -13,13 +13,13 @@ 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
 ```
 
-On macOS and Linux:
+On a host, the installer puts `sccapture` in `~/.local/bin`, with Node 24 or later, which it downloads (`node-<version>-<os>-<arch>.tar.gz`, or the `.zip` on Windows, checked against nodejs.org's `SHASUMS256.txt`) when none is on `PATH`:
 
 ```sh
 curl -fsSL https://get.sliccy.ai/slicc-capture | sh
@@ -31,24 +31,30 @@ On Windows, in PowerShell:
 irm https://get.sliccy.ai/slicc-capture.ps1 | iex
 ```
 
-Or, on any machine with Node 24 or later:
+The installers are `install.sh` and `install.ps1`, attached to every [GitHub release](https://github.com/ai-ecoverse/slicc-capture/releases) with the package tarball (`slicc-capture-<version>.tgz`) and `SHA256SUMS`, which lists the tarball, `install.sh` and `install.ps1`, in the style of [mcpcat's](https://github.com/ai-ecoverse/mcpcat) `install.sh`. `@semantic-release/npm` packs the tarball into `release/` (`tarballDir`), and `@semantic-release/exec` runs `scripts/assets.mjs`, which renames it and writes `SHA256SUMS`. They check the tarball against `SHA256SUMS`, unpack it into a versioned directory (`${XDG_DATA_HOME:-~/.local/share}/slicc-capture/<version>`, or `%LOCALAPPDATA%\slicc-capture\<version>` on Windows), and write a `sccapture` launcher that runs it with that Node. Without get.sliccy.ai, the same installer comes straight from the release:
 
 ```sh
-npm install -g @ai-ecoverse/slicc-capture
+curl -fsSL https://github.com/ai-ecoverse/slicc-capture/releases/latest/download/install.sh | sh
 ```
 
-or without installing, `npx -p @ai-ecoverse/slicc-capture sccapture shot.png`.
+| `install.sh` | `install.ps1` | |
+| --- | --- | --- |
+| `--version VERSION` | `-Version VERSION` | the release to install (default: the latest) |
+| `--dir DIR` | `-Dir DIR` | where the launcher goes (default: `~/.local/bin`; on Windows `%LOCALAPPDATA%\slicc-capture\bin`, added to the user's `PATH`) |
+| `--help` | `-Help` | print the usage and exit 0 |
 
-### The installers
+Options reach `install.sh` after `sh -s --`, for example `curl -fsSL https://get.sliccy.ai/slicc-capture | sh -s -- --version 1.2.0 --dir ~/bin`, and `install.ps1` through a script block: `& ([scriptblock]::Create((irm https://get.sliccy.ai/slicc-capture.ps1))) -Version 1.2.0`. An unknown option, or `--dir` or `--version` without a value, prints `install.sh: <problem>` and the usage to stderr and exits 2; there are no environment overrides for the options. A failure is `install.sh: <problem>` (`install.ps1: <problem>`) on stderr and exit 1. `SLICC_INSTALL_BASE_URL` replaces the release download directory (by default `https://github.com/ai-ecoverse/slicc-capture/releases/latest/download`, or `…/download/v<version>` with `--version`), and `SLICC_NODE_DIST_BASE` replaces `https://nodejs.org/dist`. The installed command must answer `--version` with the version it was installed as (or the older `sccapture <version>`). On Windows the launcher is `sccapture.ps1`, next to a `sccapture.cmd` for `cmd.exe`; both only start `node.exe` with the entry script and the arguments, and `sccapture` itself never runs `cmd.exe`.
 
-Each release attaches `install.sh` and `install.ps1` next to the package tarball, `slicc-capture-<version>.tgz`, and a `SHA256SUMS` that lists all three. The PR that adds the installers also adds them, the tarball and `SHA256SUMS` to `@semantic-release/github`'s `assets` in `.releaserc.json`, with a test in `test/integration/repo.test.mjs`, so no release ships without them. get.sliccy.ai serves the latest release's installers. Both work like mcpcat's `install.sh`:
+The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
 
-- **Options:** `--version <version>` installs that release instead of the latest; `--dir <dir>` puts the launcher there instead of the default; `--help` prints the usage and exits 0. An unknown option prints `slicc-capture: unknown option: <arg>` to stderr and exits 1. The environment variables `VERSION` and `INSTALL_DIR` do the same as the options. Through a pipe, `sh -s -- --dir ~/bin` passes options to `install.sh`, and `& ([scriptblock]::Create((irm https://get.sliccy.ai/slicc-capture.ps1))) --dir C:\tools` to `install.ps1`.
-- **Node 24 or later:** the `node` on `PATH` if it is new enough, else the one the installer downloaded before; else it downloads the current Node LTS from nodejs.org, checks it against that release's `SHASUMS256.txt`, and keeps it in the data directory. On musl Linux, where nodejs.org has no build, it says to install Node with the package manager and exits 1.
-- **Where it goes:** the tarball is checked against `SHA256SUMS`, unpacked into `<data>/<version>`, and `<data>/current` points at it. `<data>` is `${XDG_DATA_HOME:-~/.local/share}/slicc-capture` on macOS and Linux, `%LOCALAPPDATA%\slicc-capture` on Windows. The launcher, `sccapture` (`sccapture.cmd` on Windows), goes into `~/.local/bin` (`%LOCALAPPDATA%\slicc-capture\bin` on Windows) and runs that Node on `<data>/<version>/host/sccapture.mjs`, so the launcher keeps working when the `node` on `PATH` changes.
-- **Output:** `sccapture <version> installed to <launcher>`, and, when the directory isn't on `PATH`, the line that adds it. Any failure (no `curl` or `wget`, a checksum mismatch, an unsupported OS or architecture) is one line on stderr and exit 1; on an unsupported OS it names `npm install -g @ai-ecoverse/slicc-capture` instead.
+With npm, on a machine with Node 24 or later:
 
-The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
+```sh
+npm install -g @ai-ecoverse/slicc-capture
+sccapture shot.png
+```
+
+or without installing, `npx -p @ai-ecoverse/slicc-capture sccapture shot.png`.
 
 ## Commands
 
@@ -66,33 +72,55 @@ 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 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 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:
 
-**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.
+- **`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.
 
 ### Options
 
@@ -103,8 +131,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 |
@@ -126,7 +154,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 |
@@ -149,7 +177,6 @@ Only `sccapture` is installed on a host (the package's `bin`, a small Node scrip
 - **The file and its format:** without `-t`, the file's extension picks the format (on macOS, `sccapture` adds `-t` for `.jpg`, `.jpeg`, `.pdf`, `.tiff`, `.gif` and `.bmp`), else PNG. `-c` copies PNG; a file, `-t` and `-P` are then ignored, except on macOS, where `screencapture` decides. Success prints nothing, as `screencapture` does.
 - **A file is required**, as in SLICC (`sccapture: output file required (or use -c for clipboard)`, exit 2), except on macOS with `-p`, `-u`, `-P`, `-M` or `-B`, which `screencapture` handles without one.
 - **Errors:** with no tool on `PATH`, `sccapture: no screenshot tool found (tried grim, gnome-screenshot)` (the names tried on that platform) to stderr, exit 1; with `-c` and no clipboard tool, `sccapture: no clipboard tool found (tried wl-copy, xclip)`, exit 1. A tool that fails, a cancelled selection included, has its stderr passed through, exit 1. An unknown option prints `sccapture: unknown option: <arg>` and the usage to stderr, exit 2; an option the table marks as not supported on that platform prints `sccapture: <opt>: not supported on <platform>`, exit 2. The values of `-T`, `-R`, `-D` and `-J` are checked as in SLICC, and `-l` takes a window id in decimal or `0x` hex, else `sccapture: -l: invalid window: <value>`, exit 2. `-h` and `--help` print the usage to stdout and exit 0.
-- **`--upgrade`:** the command counts as installed by the installer when it runs from `<data>/<version>/host/sccapture.mjs` with a `<data>/current` next to it, and as installed with npm otherwise. `--dir` is the directory on `PATH` whose `sccapture` (`sccapture.cmd` on Windows) names `<data>`, else the installer's default. It downloads the installer with `curl`, else `wget` (`curl.exe` on Windows), and without one prints `sccapture: no downloader found (tried curl, wget)`, exit 1; a failed download has its stderr passed through, exit 1. The installer runs with `sh` (`powershell.exe`, else `pwsh.exe`, with `-ExecutionPolicy Bypass -File` on Windows), without `VERSION` and `INSTALL_DIR` in its environment, so it installs the latest release where the command is; the new version is read from `<data>/current/package.json`.
 - **Other Unix systems** are treated as Linux.
 
 ### Linux
@@ -182,7 +209,9 @@ Every host command takes `--upgrade`. It runs the latest release's installer (`i
 
 For slicc-capture, the commands are `sccapture` on a host and `screencapture` and `sccapture` in SLICC.
 
-`--version` prints the version (`0.1.0`) to stdout and exits 0, on a host and in SLICC; the installers call the launcher with it. It takes no other arguments either.
+The launcher the installer writes sets `SCCAPTURE_INSTALL_DIR` to its own directory; that is how `sccapture` knows the installer put it there (it removes the variable before it starts anything else), and without it `sccapture` counts as installed with npm. The installer is downloaded with Node's `fetch` from `https://github.com/ai-ecoverse/slicc-capture/releases/latest/download/` and run as `sh install.sh --dir DIR`, or `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File install.ps1 -Dir DIR` (else `pwsh.exe`); its stderr is passed through, and the line it prints, `sccapture <version> installed to <launcher>`, names the new version. Without `sh` (or PowerShell) it prints `sccapture: no shell found to run install.sh (tried sh)`, and a failed download `sccapture: could not download <url>: <reason>`, and exits 1. `SLICC_INSTALL_BASE_URL`, when set, replaces that release URL for `--upgrade` and for the installers' own downloads.
+
+`--version` prints the version (`0.1.0`) to stdout and exits 0, on a host and in SLICC; the installers run the installed command with it and check it reports the version they installed. It takes no other arguments either.
 
 ## Development
 
@@ -194,9 +223,9 @@ 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.
-- `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`, `pwsh.exe`, `curl`, `wget` and a fake installer on a temporary `PATH`, with the platform forced, so each branch is checked on any machine; only CI touches a real screen.
-- `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`.
+- `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/host/tools.mjs

@@ -33,7 +33,7 @@ export function spawned(path, args, { env, stdin = 'ignore', capture = false })
     let child;
     try {
       child = spawn(path, args, {
-        env,
+        env: { ...env, SCCAPTURE_INSTALL_DIR: undefined },
         stdio: [stdin, capture ? 'pipe' : 'ignore', 'pipe'],
         shell: false,
         windowsHide: true,

package/host/upgrade.mjs

@@ -1,107 +1,101 @@
-import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
-import { dirs, lookup, say, step } from './tools.mjs';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { lookup, say } from './tools.mjs';
 
-const base = 'https://github.com/ai-ecoverse/slicc-capture/releases/latest/download';
+const latest = 'https://github.com/ai-ecoverse/slicc-capture/releases/latest/download';
 
-function version(dir) {
-  return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+function fail(fds, text) {
+  say(fds[2], `sccapture: ${text}\n`);
+  return 1;
 }
 
-function home(platform, env) {
-  if (platform === 'win32') return join(env.LOCALAPPDATA ?? homedir(), 'slicc-capture');
-  return join(env.XDG_DATA_HOME || join(env.HOME ?? homedir(), '.local', 'share'), 'slicc-capture');
+function version(entry) {
+  return JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8')).version;
 }
 
-function real(path) {
+async function download(url) {
   try {
-    return realpathSync(path);
-  } catch {
-    return path;
+    const response = await fetch(url, { redirect: 'follow' });
+    if (!response.ok) return { error: `HTTP ${response.status}` };
+    return { text: await response.text() };
+  } catch (error) {
+    return { error: error.cause?.message ?? error.message };
   }
 }
 
-function launcher(platform, env, data) {
-  const fallback =
-    platform === 'win32'
-      ? join(home(platform, env), 'bin')
-      : join(env.HOME ?? homedir(), '.local', 'bin');
-  const name = platform === 'win32' ? 'sccapture.cmd' : 'sccapture';
-  const marks = [data];
-  if (real(home(platform, env)) === data) marks.push(home(platform, env));
-  for (const dir of [...dirs(platform, env), fallback]) {
-    let text;
-    try {
-      text = readFileSync(join(dir, name), 'utf8');
-    } catch {
-      continue;
-    }
-    if (marks.some((mark) => text.includes(mark))) return dir;
+function first(files, platform, env) {
+  for (const file of files) {
+    const path = lookup(file, platform, env);
+    if (path) return { file, path };
   }
-  return fallback;
+  return undefined;
 }
 
-export function installed(entry) {
-  const data = dirname(dirname(dirname(real(entry))));
-  if (basename(data) !== 'slicc-capture' || !existsSync(join(data, 'current'))) return undefined;
-  return data;
+function installer(platform, env, path, dir) {
+  if (platform === 'win32') {
+    const tool = first(['powershell.exe', 'pwsh.exe'], platform, env);
+    const args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', path];
+    return tool && { tool, args: [...args, '-Dir', dir] };
+  }
+  const tool = first(['sh'], platform, env);
+  return tool && { tool, args: [path, '--dir', dir] };
+}
+
+function wait(path, args, { env, stderr }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(path, args, {
+        env,
+        stdio: ['ignore', 'pipe', stderr],
+        shell: false,
+        windowsHide: true,
+      });
+    } catch (error) {
+      resolve({ error });
+      return;
+    }
+    const out = [];
+    child.stdout.on('data', (chunk) => out.push(chunk));
+    child.on('error', (error) => resolve({ error }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout: Buffer.concat(out) }));
+  });
 }
 
 export async function upgrade({ entry, env, platform, fds }) {
-  const root = dirname(dirname(entry));
-  const old = version(root);
-  const data = installed(entry);
-  if (!data) {
+  const dir = env.SCCAPTURE_INSTALL_DIR;
+  if (!dir) {
     say(fds[1], 'npm install -g @ai-ecoverse/slicc-capture@latest\n');
     return 0;
   }
-  const windows = platform === 'win32';
-  const getters = windows ? ['curl.exe'] : ['curl', 'wget'];
-  const getter = getters
-    .map((name) => ({ name, path: lookup(name, platform, env) }))
-    .find((g) => g.path);
-  if (!getter) {
-    say(fds[2], `sccapture: no downloader found (tried ${getters.join(', ')})\n`);
-    return 1;
-  }
-  const shells = windows ? ['powershell.exe', 'pwsh.exe'] : ['sh'];
-  const shell =
-    shells.map((name) => lookup(name, platform, env)).find(Boolean) ??
-    (windows ? undefined : '/bin/sh');
-  if (!shell) {
-    say(fds[2], `sccapture: no PowerShell found (tried ${shells.join(', ')})\n`);
-    return 1;
-  }
-  const child = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (!['VERSION', 'INSTALL_DIR'].includes(key.toUpperCase())) child[key] = value;
-  }
+  const name = platform === 'win32' ? 'install.ps1' : 'install.sh';
+  const url = `${(env.SLICC_INSTALL_BASE_URL || latest).replace(/\/+$/, '')}/${name}`;
+  const fetched = await download(url);
+  if (fetched.error) return fail(fds, `could not download ${url}: ${fetched.error}`);
   const scratch = mkdtempSync(join(tmpdir(), 'sccapture-upgrade-'));
   try {
-    const name = windows ? 'install.ps1' : 'install.sh';
-    const script = join(scratch, name);
-    const url = `${base}/${name}`;
-    const fetch = getter.name === 'wget' ? ['-q', '-O', script, url] : ['-fsSL', '-o', script, url];
-    if (!(await step(getter.name, getter.path, fetch, { env: child }, fds))) return 1;
-    const dir = launcher(platform, env, data);
-    const args = windows
-      ? [
-          '-NoProfile',
-          '-NonInteractive',
-          '-ExecutionPolicy',
-          'Bypass',
-          '-File',
-          script,
-          '--dir',
-          dir,
-        ]
-      : [script, '--dir', dir];
-    if (!(await step(name, shell, args, { env: child }, fds))) return 1;
-    const now = version(join(data, 'current'));
+    const path = join(scratch, name);
+    writeFileSync(path, fetched.text);
+    const run = installer(platform, env, path, dir);
+    if (!run) {
+      const tried = platform === 'win32' ? 'powershell.exe, pwsh.exe' : 'sh';
+      return fail(fds, `no shell found to run ${name} (tried ${tried})`);
+    }
+    const child = { ...env };
+    delete child.SCCAPTURE_INSTALL_DIR;
+    const result = await wait(run.tool.path, run.args, { env: child, stderr: fds[2] });
+    if (result.error) return fail(fds, `${run.tool.file}: ${result.error.message}`);
+    if (result.code !== 0) return 1;
+    const installed = /^sccapture (\S+) installed to /m.exec(result.stdout.toString())?.[1];
+    if (!installed) return fail(fds, `${name} did not say which version it installed`);
+    const old = version(entry);
     say(
       fds[1],
-      now === old ? `sccapture: already up to date (${old})\n` : `sccapture: ${old} → ${now}\n`
+      installed === old
+        ? `sccapture: already up to date (${old})\n`
+        : `sccapture: ${old} → ${installed}\n`
     );
     return 0;
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "screencapture for SLICC, and sccapture for SLICC and any host",
   "type": "module",
   "license": "Apache-2.0",
@@ -9,7 +9,8 @@
     "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"
@@ -25,29 +26,44 @@
     "provenance": true
   },
   "slicc": {
+    "commands": {
+      "screencapture": {
+        "script": "bin/screencapture"
+      },
+      "sccapture": {
+        "script": "bin/sccapture"
+      }
+    },
     "unitSources": [
       "host"
     ]
   },
   "files": [
+    "bin",
     "host"
   ],
   "scripts": {
     "prepare": "slicc-install-hooks",
-    "lint": "slicc-lint",
+    "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-kernel": "1.153.0",
     "@ai-ecoverse/slicc-shared-web": "2.11.3",
+    "@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"
   }
 }