@ai-ecoverse/slicc-capture 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,205 @@
-# Temporary Holding Version
+# slicc-capture
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Screen capture for SLICC: `screencapture`, with the options of macOS's `screencapture(1)` wherever they make sense in a browser, and slicc 6's `-c` (to the clipboard) and `-v` (inline in the agent's tool result). Seven's page shows a prompt, the user picks a screen, window or tab in Chrome's `getDisplayMedia` picker, and the command writes a PNG (or JPEG or WebP).
+
+`sccapture` is the same command under a name that works everywhere: in SLICC it is `screencapture`, and on macOS, Linux and Windows it hands off to the platform's own screenshot tool (see [On a host](#on-a-host)). A host's own `screencapture` is never shadowed.
+
+```sh
+screencapture shot.png
+screencapture -c
+screencapture -v
+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`:
+
+```sh
+pnpm add -g @ai-ecoverse/slicc-capture
+```
+
+On macOS and Linux:
+
+```sh
+curl -fsSL https://get.sliccy.ai/slicc-capture | sh
+```
+
+On Windows, in PowerShell:
+
+```powershell
+irm https://get.sliccy.ai/slicc-capture.ps1 | iex
+```
+
+Or, on any machine with Node 24 or later:
+
+```sh
+npm install -g @ai-ecoverse/slicc-capture
+```
+
+or without installing, `npx -p @ai-ecoverse/slicc-capture sccapture shot.png`.
+
+### The installers
+
+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`:
+
+- **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.
+
+The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
+
+## Commands
+
+| command | where | what |
+| --- | --- | --- |
+| `screencapture` | SLICC | captures through seven's page, as below |
+| `sccapture` | SLICC | the same as `screencapture` |
+| `sccapture` | macOS, Linux, Windows | hands off to the platform's tool, as in [On a host](#on-a-host) |
+
+```
+usage: screencapture [-acdimorvwxCW] [-t format] [-T seconds] [-R x,y,w,h] [-D display] [-J style] [file]
+```
+
+Short options may be grouped (`-xc`), an option's value may be attached or separate (`-T3`, `-T 3`), and `--` ends the options. `--clipboard` is `-c` and `--view` is `-v`, as in slicc 6. `-h` or `--help` anywhere prints the usage to stdout and exits 0. `--version` and `--upgrade` are described [below](#--upgrade); either must be the only argument, else `<cmd>: <opt>: takes no other arguments` and the usage to stderr, exit 2. An option without its value prints `<cmd>: <opt>: option requires a value` and the usage to stderr, exit 2.
+
+### 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.
+
+- **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.
+- **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: 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:`.
+
+**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.
+
+### Options
+
+Every option of macOS's `screencapture`, and what it does in SLICC and with `sccapture` on each host. On macOS, `sccapture` passes the options through to `screencapture` unchanged, except the ones the macOS column names. "No-op" means the option is accepted and changes nothing. "Not supported" means `<cmd>: <opt>: not supported in SLICC` (or `on Linux`, `on Windows`, `on macOS`) on stderr, exit 2, before anything is captured; "not with `<tool>`" means `sccapture: <opt>: not supported with <tool>`, exit 2, when no tool on `PATH` supports every option given (it names the first one tried).
+
+| option | macOS `screencapture` | SLICC | macOS `sccapture` | Linux `sccapture` | Windows `sccapture` |
+| --- | --- | --- | --- | --- | --- |
+| `-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 |
+| `-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 |
+| `-G <id>` | record that audio source | not supported | not supported | not supported | not supported |
+| `-i` | interactive, by selection or window | no-op: the picker is the interaction | passed | see [Linux](#linux) | not supported |
+| `-J <style>` | start in `selection`, `window` or `video` | `window` as `-W`; `selection` and `video` not supported | passed | `selection` as `-s`, `window` as `-w`, `video` not supported | not supported |
+| `-k` | show clicks in a recording | not supported | not supported | not supported | not supported |
+| `-l <windowid>` | that window | not supported | passed | see [Linux](#linux) | not supported |
+| `-m` | the main monitor only | prefers `displaySurface: 'monitor'`; the user picks the screen | passed | not supported | the primary screen |
+| `-M` | open in a new Mail message | not supported | passed | not supported | not supported |
+| `-o` | no window shadow | no-op: the browser captures none | passed | no-op | no-op |
+| `-p` | default settings, file ignored | not supported | passed | not supported | not supported |
+| `-P` | open in Preview | not supported | passed | `xdg-open <file>` afterwards; without it, `sccapture: no viewer found (tried xdg-open)`, exit 1, after the file is written | `Invoke-Item <file>` afterwards |
+| `-r` | no dpi metadata | no-op: none is written | passed | no-op | no-op |
+| `-R <x,y,w,h>` | that rectangle | crops the frame, in its pixels | passed | see [Linux](#linux) | that rectangle of the virtual screen |
+| `-s` | mouse selection only | not supported: use `-R` | passed | see [Linux](#linux) | not supported |
+| `-S` | the screen, in window mode | not supported | passed | not supported | not supported |
+| `-t <format>` | the image format, `png` by default | `png`, `jpg` or `jpeg`, `webp`; others not supported | passed | see [Linux](#linux) | `png`, `jpg` or `jpeg`, `bmp`, `gif`, `tiff`; others not supported |
+| `-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 <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 |
+| `-x` | no sounds | no-op | passed | no-op | no-op |
+| `file ...` | one file per screen | one file; more not supported | passed | one file; more not supported | one file; more not supported |
+
+Video recording (`-v`, `-V`, `-g`, `-G`, `-k`) is out of scope on every platform, macOS included; a later release may add it, sharing an encoder with whatever replaces `ffmpeg` in SLICC. `--clipboard` and `--view` are `-c` and `-v` on every platform; on macOS, `sccapture` passes `--clipboard` on as `-c`.
+
+## On a host
+
+Only `sccapture` is installed on a host (the package's `bin`, a small Node script, `host/sccapture.mjs`); the host's own `screencapture`, `grim` and the rest are never shadowed. It runs the platform's tool with a fixed argv and no shell: of the tools below, in this order, the first one on `PATH` that supports every option given (so on GNOME under X11, `-l` picks `import` over `gnome-screenshot`):
+
+| platform | tool | `-c` |
+| --- | --- | --- |
+| macOS | `screencapture`, with the options passed through as above | `screencapture -c` |
+| Linux, under Wayland (`WAYLAND_DISPLAY` set) | `grim` (with `slurp` to select), else `gnome-screenshot` | `wl-copy --type image/png`, else `xclip -selection clipboard -t image/png` |
+| Linux, X11 | `gnome-screenshot`, else ImageMagick `import`, else `scrot` | `xclip -selection clipboard -t image/png` |
+| Windows | PowerShell, `powershell.exe` else `pwsh.exe`, with System.Drawing and System.Windows.Forms | `Clipboard.SetImage` |
+
+- **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
+
+How each option reaches the tool. "Not with `<tool>`" is the error only when no tool on `PATH` supports every option given, and it names the first one tried. `<file>` is the file, or a temporary PNG that is then copied with `-c` and deleted.
+
+| option | `grim` | `gnome-screenshot` | `import` | `scrot` |
+| --- | --- | --- | --- | --- |
+| none | `grim <file>` | `gnome-screenshot -f <file>` | `import -window root <file>` | `scrot -o <file>` |
+| `-i`, `-s` | `grim -g <slurp's output> <file>`; without `slurp`, `sccapture: no region selector found (tried slurp)`, exit 1 | `-a` | `import <file>`: click a window or drag a region | `-s` |
+| `-w`, `-W` | not with `grim` | not with `gnome-screenshot` | `import <file>` | `-s` |
+| `-R x,y,w,h` | `-g "x,y wxh"` | not with `gnome-screenshot` | `-crop wxh+x+y +repage` | `-a x,y,w,h` |
+| `-C` | `-c` | `-p` | not with `import` | `-p` |
+| `-l <windowid>` | not with `grim` | not with `gnome-screenshot` | `-window <windowid>` | not with `scrot` |
+| `-t png`, `jpg` | `-t png`, `-t jpeg`; without `-t`, `-t jpeg` for a `.jpg` or `.jpeg` file, since grim writes PNG whatever the extension | `png` only, else not with `gnome-screenshot` | `png:<file>`, `jpg:<file>`; without `-t`, `png:<file>` for a file without an extension, which `import` can't guess | by the file's extension; a `-t` that differs from it is not with `scrot` |
+
+Under Wayland, `grim` needs a compositor with wlr-screencopy (sway, Hyprland and other wlroots ones); elsewhere it fails with its own message, so install `gnome-screenshot` there. `import` and `scrot` aren't tried under Wayland, where they would see only XWayland windows.
+
+### Windows
+
+`sccapture` runs `powershell.exe` (else `pwsh.exe`) with `-NoProfile -NonInteractive -STA -EncodedCommand` and a fixed script; the file name and the option values reach it as data, in `SCCAPTURE_*` environment variables, never as script. (PowerShell reads a script on stdin line by line, as if typed, so a multi-line block in it can stop at the first blank line; `-EncodedCommand` is what slicc-clipboard uses.) The process is made per-monitor DPI-aware first (system DPI-aware before Windows 10 1703), so a scaled display is captured at its real resolution, even when the monitors' scales differ. It copies the virtual screen (every monitor), or the screen `-m`/`-D` names, or the `-R` rectangle of that (its `x,y` from the top left of the virtual screen, or of the screen `-m`/`-D` names), with `Graphics.CopyFromScreen`, draws the cursor for `-C`, and saves with the `-t` format's `ImageFormat`, or `Clipboard.SetImage` for `-c`.
+
+### In SLICC, the SLICC commands win
+
+The package has both `bin` and `slicc.commands`, and both name `sccapture`. As with slicc-clipboard, the kernel ignores a package's `bin` entry when the same package declares that name in `slicc.commands`, and bios removes the `$PNPM_HOME/bin` link pnpm makes for it, so the Node script, which SLICC has no Node to run, never shadows the SLICC command.
+
+## `--upgrade`
+
+Every host command takes `--upgrade`. It runs the latest release's installer (`install.sh`, or `install.ps1` on Windows) with `--dir` set to the directory the command is installed in, so the new version replaces the old one in place, then prints `<cmd>: <old> → <new>` (for example `sccapture: 1.2.0 → 1.3.0`), or `<cmd>: already up to date (<version>)`, to stdout and exits 0. If the installer fails, its stderr is passed through and the command exits 1. A command installed with npm prints `npm install -g @ai-ecoverse/slicc-capture@latest` to run instead, and exits 0. In SLICC, `--upgrade` prints `pnpm add -g @ai-ecoverse/slicc-capture@latest` to run, and exits 0; it installs nothing itself. `--upgrade` takes no other arguments.
+
+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.
+
+## Development
+
+```sh
+npm install
+npm run lint
+npm test
+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.
+
+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.
+
+## License
+
+Apache-2.0

package/host/capture.mjs

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { darwin } from './darwin.mjs';
+import { linux } from './linux.mjs';
+import { check, names, parse, settings, usage } from './options.mjs';
+import { say } from './tools.mjs';
+import { upgrade } from './upgrade.mjs';
+import { windows } from './windows.mjs';
+
+const optional = 'puPMB';
+
+export async function run({
+  argv = process.argv.slice(2),
+  env = process.env,
+  platform = process.platform,
+  fds = [0, 1, 2],
+  entry = fileURLToPath(new URL('sccapture.mjs', import.meta.url)),
+  wait = (seconds) => setTimeout(seconds * 1000),
+} = {}) {
+  const os = names[platform] ? platform : 'linux';
+  const parsed = parse(argv);
+  if (parsed.help) {
+    say(fds[1], usage);
+    return 0;
+  }
+  if (parsed.error) {
+    say(fds[2], `sccapture: ${parsed.error}\n${usage}`);
+    return 2;
+  }
+  if (parsed.special.length) {
+    if (argv.length > 1) {
+      say(fds[2], `sccapture: ${parsed.special[0]}: takes no other arguments\n${usage}`);
+      return 2;
+    }
+    if (parsed.special[0] === '--upgrade') return upgrade({ entry, env, platform: os, fds });
+    const pkg = JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8'));
+    say(fds[1], `${pkg.version}\n`);
+    return 0;
+  }
+  const problem = check(parsed.options, os);
+  if (problem) {
+    say(fds[2], `sccapture: ${problem}\n`);
+    return 2;
+  }
+  const o = settings(parsed.options);
+  const free = os === 'darwin' && parsed.options.some((option) => optional.includes(option.letter));
+  if (!parsed.files.length && !o.clipboard && !free) {
+    say(fds[2], `sccapture: output file required (or use -c for clipboard)\n${usage}`);
+    return 2;
+  }
+  if (os === 'darwin') return darwin({ parsed, o, env, platform: os, fds });
+  if (parsed.files.length > 1 && !o.clipboard) {
+    say(fds[2], `sccapture: more than one file: not supported on ${names[os]}\n`);
+    return 2;
+  }
+  const file = parsed.files.length ? resolve(parsed.files[0]) : undefined;
+  const context = { o, file, env, platform: os, fds, wait };
+  return os === 'win32' ? windows(context) : linux(context);
+}

package/host/darwin.mjs

@@ -0,0 +1,26 @@
+import { extname } from 'node:path';
+import { lookup, say, step } from './tools.mjs';
+
+const extensions = {
+  '.jpg': 'jpg',
+  '.jpeg': 'jpg',
+  '.pdf': 'pdf',
+  '.tiff': 'tiff',
+  '.gif': 'gif',
+  '.bmp': 'bmp',
+};
+
+export async function darwin({ parsed, o, env, platform, fds }) {
+  const path = lookup('screencapture', platform, env);
+  if (!path) {
+    say(fds[2], 'sccapture: no screenshot tool found (tried screencapture)\n');
+    return 1;
+  }
+  const args = [...parsed.tokens];
+  const type =
+    !o.last.t && parsed.files.length && extensions[extname(parsed.files[0]).toLowerCase()];
+  if (type) args.push('-t', type);
+  if (parsed.files.some((file) => file.startsWith('-'))) args.push('--');
+  args.push(...parsed.files);
+  return (await step('screencapture', path, args, { env }, fds)) ? 0 : 1;
+}

package/host/linux.mjs

@@ -0,0 +1,131 @@
+import { closeSync, mkdtempSync, openSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { lookup, say, step } from './tools.mjs';
+
+const extensions = { '.png': 'png', '.jpg': 'jpg', '.jpeg': 'jpg' };
+
+const builders = {
+  grim(o, file) {
+    if (o.window) return { unsupported: o.windowLabel };
+    if (o.id) return { unsupported: '-l' };
+    const args = o.cursor ? ['-c'] : [];
+    const type = o.type ?? extensions[extname(file).toLowerCase()];
+    if (o.type === 'png') args.push('-t', 'png');
+    else if (type === 'jpg') args.push('-t', 'jpeg');
+    if (o.rect) {
+      const [x, y, w, h] = o.rect;
+      args.push('-g', `${x},${y} ${w}x${h}`);
+    }
+    return { args: [...args, file], slurp: o.select && !o.rect };
+  },
+  'gnome-screenshot'(o, file) {
+    if (o.window) return { unsupported: o.windowLabel };
+    if (o.rect) return { unsupported: '-R' };
+    if (o.id) return { unsupported: '-l' };
+    if (o.type && o.type !== 'png') return { unsupported: `-t ${o.last.t.value}` };
+    const args = [];
+    if (o.select) args.push('-a');
+    if (o.cursor) args.push('-p');
+    return { args: [...args, '-f', file] };
+  },
+  import(o, file) {
+    if (o.cursor) return { unsupported: '-C' };
+    const args = [];
+    if (o.id) args.push('-window', o.id);
+    else if (!o.select && !o.window) args.push('-window', 'root');
+    if (o.rect) {
+      const [x, y, w, h] = o.rect;
+      args.push('-crop', `${w}x${h}+${x}+${y}`, '+repage');
+    }
+    const type = o.type ?? (extname(file) ? undefined : 'png');
+    return { args: [...args, type ? `${type}:${file}` : file] };
+  },
+  scrot(o, file) {
+    if (o.id) return { unsupported: '-l' };
+    if (o.type && extensions[extname(file).toLowerCase()] !== o.type) {
+      return { unsupported: `-t ${o.last.t.value}` };
+    }
+    const args = [];
+    if (o.select || o.window) args.push('-s');
+    if (o.rect) args.push('-a', o.rect.join(','));
+    if (o.cursor) args.push('-p');
+    return { args: [...args, '-o', file] };
+  },
+};
+
+function pick(names, o, file, platform, env) {
+  let first;
+  for (const name of names) {
+    const path = lookup(name, platform, env);
+    if (!path) continue;
+    const built = builders[name](o, file);
+    if (!built.unsupported) return { name, path, ...built };
+    first ??= `${built.unsupported}: not supported with ${name}`;
+  }
+  return { error: first };
+}
+
+function clipboard(wayland, platform, env) {
+  const xclip = { name: 'xclip', args: ['-selection', 'clipboard', '-t', 'image/png'] };
+  const clips = wayland ? [{ name: 'wl-copy', args: ['--type', 'image/png'] }, xclip] : [xclip];
+  for (const clip of clips) {
+    const path = lookup(clip.name, platform, env);
+    if (path) return { ...clip, path };
+  }
+  return { error: `no clipboard tool found (tried ${clips.map((c) => c.name).join(', ')})` };
+}
+
+export async function linux({ o, file, env, platform, fds, wait }) {
+  const wayland = Boolean(env.WAYLAND_DISPLAY);
+  const names = wayland ? ['grim', 'gnome-screenshot'] : ['gnome-screenshot', 'import', 'scrot'];
+  const scratch = o.clipboard ? mkdtempSync(join(tmpdir(), 'sccapture-')) : undefined;
+  const target = scratch ? join(scratch, 'capture.png') : file;
+  try {
+    const tool = pick(names, o, target, platform, env);
+    if (!tool.name) {
+      if (tool.error) {
+        say(fds[2], `sccapture: ${tool.error}\n`);
+        return 2;
+      }
+      say(fds[2], `sccapture: no screenshot tool found (tried ${names.join(', ')})\n`);
+      return 1;
+    }
+    const clip = o.clipboard ? clipboard(wayland, platform, env) : undefined;
+    if (clip?.error) {
+      say(fds[2], `sccapture: ${clip.error}\n`);
+      return 1;
+    }
+    const slurp = tool.slurp ? lookup('slurp', platform, env) : undefined;
+    if (tool.slurp && !slurp) {
+      say(fds[2], 'sccapture: no region selector found (tried slurp)\n');
+      return 1;
+    }
+    await wait(o.delay);
+    let args = tool.args;
+    if (slurp) {
+      const region = await step('slurp', slurp, [], { env, capture: true }, fds);
+      if (!region) return 1;
+      args = ['-g', region.stdout.trim(), ...args];
+    }
+    if (!(await step(tool.name, tool.path, args, { env }, fds))) return 1;
+    if (clip) {
+      const fd = openSync(target, 'r');
+      try {
+        if (!(await step(clip.name, clip.path, clip.args, { env, stdin: fd }, fds))) return 1;
+      } finally {
+        closeSync(fd);
+      }
+      return 0;
+    }
+    if (!o.open) return 0;
+    const viewer = lookup('xdg-open', platform, env);
+    if (!viewer) {
+      say(fds[2], 'sccapture: no viewer found (tried xdg-open)\n');
+      return 1;
+    }
+    return (await step('xdg-open', viewer, [file], { env }, fds)) ? 0 : 1;
+  } finally {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/host/options.mjs

@@ -0,0 +1,111 @@
+const flags = 'abcCdgiklmMoprPsSuUvwWx';
+const valued = 'BDGJlRtTV';
+
+export const usage =
+  'usage: sccapture [-acdimorvwxCW] [-t format] [-T seconds] [-R x,y,w,h] [-D display] [-J style] [file]\n';
+
+const long = { '--clipboard': 'c', '--view': 'v' };
+
+function group(argv, i, result, fail) {
+  const arg = argv[i];
+  let at = i;
+  for (let j = 1; j < arg.length; j++) {
+    const letter = arg[j];
+    if (letter === 'h') result.help = true;
+    else if (valued.includes(letter)) {
+      const value = j + 1 < arg.length ? arg.slice(j + 1) : argv[++at];
+      if (value === undefined) fail(`-${letter}: option requires a value`);
+      else result.options.push({ letter, label: `-${letter}`, value });
+      break;
+    } else if (flags.includes(letter)) result.options.push({ letter, label: `-${letter}` });
+    else fail(`unknown option: -${letter}`);
+  }
+  result.tokens.push(...argv.slice(i, at + 1));
+  return at;
+}
+
+export function parse(argv) {
+  const result = { help: false, error: undefined, special: [], options: [], files: [], tokens: [] };
+  const fail = (message) => {
+    result.error ??= message;
+  };
+  let ended = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (ended) result.files.push(arg);
+    else if (arg === '--') ended = true;
+    else if (arg === '--help') result.help = true;
+    else if (arg === '--version' || arg === '--upgrade') result.special.push(arg);
+    else if (long[arg]) {
+      result.options.push({ letter: long[arg], label: arg });
+      result.tokens.push(`-${long[arg]}`);
+    } else if (arg.startsWith('--')) fail(`unknown option: ${arg}`);
+    else if (arg.startsWith('-') && arg.length > 1) i = group(argv, i, result, fail);
+    else result.files.push(arg);
+  }
+  return result;
+}
+
+const unsupported = {
+  darwin: 'gGkvV',
+  linux: 'bBDgGkmMpSuUvV',
+  win32: 'bBgGiJklMpsSuUvVwW',
+};
+
+const formats = {
+  linux: ['png', 'jpg', 'jpeg'],
+  win32: ['png', 'jpg', 'jpeg', 'bmp', 'gif', 'tiff'],
+};
+
+const checks = {
+  T: [/^\d+(\.\d+)?$/, 'invalid delay'],
+  R: [/^\d+,\d+,[1-9]\d*,[1-9]\d*$/, 'invalid rectangle'],
+  D: [/^[1-9]\d*$/, 'invalid display'],
+  J: [/^(selection|window|video)$/, 'invalid style'],
+  l: [/^(\d+|0x[0-9a-fA-F]+)$/, 'invalid window'],
+};
+
+export const names = { darwin: 'macOS', linux: 'Linux', win32: 'Windows' };
+
+export function check(options, platform) {
+  const where = `on ${names[platform]}`;
+  const own = options.find((option) => unsupported[platform].includes(option.letter));
+  if (own) return `${own.label}: not supported ${where}`;
+  for (const option of options) {
+    const rule = checks[option.letter];
+    if (rule && !rule[0].test(option.value))
+      return `-${option.letter}: ${rule[1]}: ${option.value}`;
+  }
+  if (platform === 'darwin') return undefined;
+  const style = options.find((option) => option.letter === 'J' && option.value === 'video');
+  if (style) return `-J video: not supported ${where}`;
+  if (options.some((option) => option.letter === 'c')) return undefined;
+  const type = options.find(
+    (option) => option.letter === 't' && !formats[platform].includes(option.value.toLowerCase())
+  );
+  if (type) return `-t ${type.value}: not supported ${where}`;
+  return undefined;
+}
+
+export function settings(options) {
+  const last = {};
+  for (const option of options) last[option.letter] = option;
+  const style = last.J?.value;
+  const label = (...letters) => letters.map((letter) => last[letter]?.label).find(Boolean);
+  const rect = last.R?.value.split(',').map(Number);
+  return {
+    last,
+    clipboard: Boolean(last.c),
+    cursor: Boolean(last.C),
+    open: Boolean(last.P),
+    main: Boolean(last.m),
+    display: last.D?.value,
+    delay: last.T ? Number(last.T.value) : 0,
+    rect,
+    id: last.l?.value,
+    type: last.c ? undefined : last.t?.value.toLowerCase().replace('jpeg', 'jpg'),
+    select: Boolean(last.s || last.i || style === 'selection'),
+    window: Boolean(last.w || last.W || style === 'window'),
+    windowLabel: label('w', 'W') ?? (style === 'window' ? '-J window' : undefined),
+  };
+}

package/host/sccapture.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './capture.mjs';
+
+process.exitCode = await run();

package/host/tools.mjs

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants, statSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function say(fd, text) {
+  writeSync(fd, text);
+}
+
+function runnable(path, platform) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, platform === 'win32' ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function dirs(platform, env) {
+  const path = (platform === 'win32' ? (env.PATH ?? env.Path) : env.PATH) ?? '';
+  return path.split(platform === 'win32' ? ';' : ':').filter(Boolean);
+}
+
+export function lookup(file, platform, env) {
+  for (const dir of dirs(platform, env)) {
+    if (runnable(join(dir, file), platform)) return join(dir, file);
+  }
+  return undefined;
+}
+
+export function spawned(path, args, { env, stdin = 'ignore', capture = false }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(path, args, {
+        env,
+        stdio: [stdin, capture ? 'pipe' : 'ignore', 'pipe'],
+        shell: false,
+        windowsHide: true,
+      });
+    } catch (error) {
+      resolve({ error });
+      return;
+    }
+    const out = [];
+    const errors = [];
+    let code;
+    let outClosed = !capture;
+    let errClosed = false;
+    const settle = () => {
+      if (code === undefined || !outClosed) return;
+      if (code === 0) {
+        child.stderr.destroy();
+        resolve({ code, stdout: Buffer.concat(out).toString('utf8') });
+      } else if (errClosed) resolve({ code, stderr: Buffer.concat(errors) });
+    };
+    if (capture) {
+      child.stdout.on('data', (chunk) => out.push(chunk));
+      child.stdout.on('close', () => {
+        outClosed = true;
+        settle();
+      });
+    }
+    child.stderr.on('data', (chunk) => errors.push(chunk));
+    child.stderr.on('close', () => {
+      errClosed = true;
+      settle();
+    });
+    child.on('error', (error) => resolve({ error }));
+    child.on('exit', (status) => {
+      code = status ?? 1;
+      settle();
+    });
+  });
+}
+
+export async function step(name, path, args, options, fds) {
+  const result = await spawned(path, args, options);
+  if (result.error) {
+    say(fds[2], `sccapture: ${name}: ${result.error.message}\n`);
+    return undefined;
+  }
+  if (result.code === 0) return result;
+  if (result.stderr.length) say(fds[2], result.stderr);
+  else say(fds[2], `sccapture: ${name} failed\n`);
+  return undefined;
+}

package/host/upgrade.mjs

@@ -0,0 +1,110 @@
+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';
+
+const base = 'https://github.com/ai-ecoverse/slicc-capture/releases/latest/download';
+
+function version(dir) {
+  return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+}
+
+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 real(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+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;
+  }
+  return fallback;
+}
+
+export function installed(entry) {
+  const data = dirname(dirname(dirname(real(entry))));
+  if (basename(data) !== 'slicc-capture' || !existsSync(join(data, 'current'))) return undefined;
+  return data;
+}
+
+export async function upgrade({ entry, env, platform, fds }) {
+  const root = dirname(dirname(entry));
+  const old = version(root);
+  const data = installed(entry);
+  if (!data) {
+    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 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'));
+    say(
+      fds[1],
+      now === old ? `sccapture: already up to date (${old})\n` : `sccapture: ${old} → ${now}\n`
+    );
+    return 0;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/host/windows.mjs

@@ -0,0 +1,125 @@
+import { extname } from 'node:path';
+import { lookup, say, step } from './tools.mjs';
+
+const extensions = {
+  '.png': 'png',
+  '.jpg': 'jpg',
+  '.jpeg': 'jpg',
+  '.bmp': 'bmp',
+  '.gif': 'gif',
+  '.tif': 'tiff',
+  '.tiff': 'tiff',
+};
+
+const native = [
+  'using System;',
+  'using System.Runtime.InteropServices;',
+  'public static class SccaptureNative {',
+  '[StructLayout(LayoutKind.Sequential)] public struct POINT { public int X; public int Y; }',
+  '[StructLayout(LayoutKind.Sequential)] public struct CURSORINFO { public int cbSize; public int flags; public IntPtr hCursor; public POINT pt; }',
+  '[StructLayout(LayoutKind.Sequential)] public struct ICONINFO { public bool fIcon; public int xHotspot; public int yHotspot; public IntPtr hbmMask; public IntPtr hbmColor; }',
+  '[DllImport("user32.dll")] static extern bool SetProcessDPIAware();',
+  '[DllImport("user32.dll")] static extern bool SetProcessDpiAwarenessContext(IntPtr context);',
+  'public static void Aware() {',
+  'try { if (SetProcessDpiAwarenessContext(new IntPtr(-4))) return; } catch (EntryPointNotFoundException) { }',
+  'SetProcessDPIAware();',
+  '}',
+  '[DllImport("user32.dll")] static extern bool GetCursorInfo(ref CURSORINFO info);',
+  '[DllImport("user32.dll")] static extern bool GetIconInfo(IntPtr icon, out ICONINFO info);',
+  '[DllImport("user32.dll")] static extern bool DrawIconEx(IntPtr hdc, int x, int y, IntPtr icon, int w, int h, int step, IntPtr brush, int flags);',
+  '[DllImport("gdi32.dll")] static extern bool DeleteObject(IntPtr handle);',
+  'public static void DrawCursor(IntPtr hdc, int left, int top) {',
+  'CURSORINFO info = new CURSORINFO();',
+  'info.cbSize = Marshal.SizeOf(typeof(CURSORINFO));',
+  'if (!GetCursorInfo(ref info) || info.flags != 1) return;',
+  'ICONINFO icon;',
+  'if (!GetIconInfo(info.hCursor, out icon)) return;',
+  'DrawIconEx(hdc, info.pt.X - icon.xHotspot - left, info.pt.Y - icon.yHotspot - top, info.hCursor, 0, 0, 0, IntPtr.Zero, 3);',
+  'if (icon.hbmMask != IntPtr.Zero) DeleteObject(icon.hbmMask);',
+  'if (icon.hbmColor != IntPtr.Zero) DeleteObject(icon.hbmColor);',
+  '}',
+  '}',
+].join(' ');
+
+export const script = [
+  "$ErrorActionPreference = 'Stop'",
+  "$ProgressPreference = 'SilentlyContinue'",
+  'try {',
+  '  Add-Type -AssemblyName System.Drawing',
+  '  Add-Type -AssemblyName System.Windows.Forms',
+  `  Add-Type -TypeDefinition '${native}'`,
+  '  [SccaptureNative]::Aware()',
+  '  $screen = $env:SCCAPTURE_SCREEN',
+  "  if ($screen -eq 'all') {",
+  '    $bounds = [System.Windows.Forms.SystemInformation]::VirtualScreen',
+  "  } elseif ($screen -eq 'primary') {",
+  '    $bounds = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds',
+  '  } else {',
+  '    $screens = @([System.Windows.Forms.Screen]::PrimaryScreen) + @([System.Windows.Forms.Screen]::AllScreens | Where-Object { -not $_.Primary })',
+  '    $index = [int]$screen',
+  '    if ($index -gt $screens.Count) {',
+  "      [Console]::Error.WriteLine(('sccapture: -D {0}: no such display' -f $index))",
+  '      exit 1',
+  '    }',
+  '    $bounds = $screens[$index - 1].Bounds',
+  '  }',
+  '  if ($env:SCCAPTURE_RECT) {',
+  "    $rect = [int[]]($env:SCCAPTURE_RECT -split ',')",
+  '    $bounds = New-Object System.Drawing.Rectangle ($bounds.X + $rect[0]), ($bounds.Y + $rect[1]), $rect[2], $rect[3]',
+  '  }',
+  '  $bitmap = New-Object System.Drawing.Bitmap $bounds.Width, $bounds.Height',
+  '  $graphics = [System.Drawing.Graphics]::FromImage($bitmap)',
+  '  $graphics.CopyFromScreen($bounds.Location, [System.Drawing.Point]::Empty, $bounds.Size)',
+  "  if ($env:SCCAPTURE_CURSOR -eq '1') {",
+  '    $hdc = $graphics.GetHdc()',
+  '    [SccaptureNative]::DrawCursor($hdc, $bounds.X, $bounds.Y)',
+  '    $graphics.ReleaseHdc($hdc)',
+  '  }',
+  '  $graphics.Dispose()',
+  "  if ($env:SCCAPTURE_CLIPBOARD -eq '1') {",
+  '    [System.Windows.Forms.Clipboard]::SetImage($bitmap)',
+  '  } else {',
+  "    $formats = @{ png = 'Png'; jpg = 'Jpeg'; bmp = 'Bmp'; gif = 'Gif'; tiff = 'Tiff' }",
+  '    $bitmap.Save($env:SCCAPTURE_FILE, [System.Drawing.Imaging.ImageFormat]::($formats[$env:SCCAPTURE_FORMAT]))',
+  "    if ($env:SCCAPTURE_OPEN -eq '1') { Invoke-Item -LiteralPath $env:SCCAPTURE_FILE }",
+  '  }',
+  '  $bitmap.Dispose()',
+  '} catch {',
+  '  [Console]::Error.WriteLine($_.Exception.Message)',
+  '  exit 1',
+  '}',
+].join('\n');
+
+export const encoded = Buffer.from(script, 'utf16le').toString('base64');
+
+export async function windows({ o, file, env, platform, fds, wait }) {
+  const names = ['powershell.exe', 'pwsh.exe'];
+  const name = names.find((candidate) => lookup(candidate, platform, env));
+  if (!name) {
+    say(fds[2], `sccapture: no screenshot tool found (tried ${names.join(', ')})\n`);
+    return 1;
+  }
+  let screen = 'all';
+  if (o.display) screen = o.display;
+  else if (o.main) screen = 'primary';
+  const data = {
+    SCCAPTURE_FILE: o.clipboard ? undefined : file,
+    SCCAPTURE_FORMAT: o.clipboard
+      ? 'png'
+      : (o.type ?? extensions[extname(file).toLowerCase()] ?? 'png'),
+    SCCAPTURE_CLIPBOARD: o.clipboard ? '1' : undefined,
+    SCCAPTURE_CURSOR: o.cursor ? '1' : undefined,
+    SCCAPTURE_SCREEN: screen,
+    SCCAPTURE_RECT: o.rect?.join(','),
+    SCCAPTURE_OPEN: o.open && !o.clipboard ? '1' : undefined,
+  };
+  const child = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.toUpperCase().startsWith('SCCAPTURE_')) child[key] = value;
+  }
+  for (const [key, value] of Object.entries(data)) if (value !== undefined) child[key] = value;
+  await wait(o.delay);
+  const args = ['-NoProfile', '-NonInteractive', '-STA', '-EncodedCommand', encoded];
+  const done = await step(name, lookup(name, platform, env), args, { env: child }, fds);
+  return done ? 0 : 1;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "screencapture for SLICC, and sccapture for SLICC and any host",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-ecoverse/slicc-capture.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "sccapture": "host/sccapture.mjs"
+  },
+  "fledgling": {
+    "provider": "github",
+    "workflow": "ci.yml",
+    "repo": "ai-ecoverse/slicc-capture",
+    "publish": true
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "slicc": {
+    "unitSources": [
+      "host"
+    ]
+  },
+  "files": [
+    "host"
+  ],
+  "scripts": {
+    "prepare": "slicc-install-hooks",
+    "lint": "slicc-lint",
+    "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'",
+    "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",
+    "@biomejs/biome": "2.5.15",
+    "lefthook": "2.2.2",
+    "monocart-coverage-reports": "2.13.2",
+    "semantic-release": "25.0.9"
+  }
+}