Shotlog - Screenshot Log

@@ -0,0 +1,140 @@+---+name: adom-shotlog+description: "Screenshot log viewer and injector. Use when: logging screenshots during debug loops, documenting visual progress, reviewing screenshot history, opening the screenshot log panel, injecting a screenshot into the log, ingesting an Adom Desktop screenshot response with owned popups. Trigger words: adom-shotlog, shotlog, screenshot log, shot log, visual log, screenshot history, log screenshot, open shotlog, screenshot viewer."+---++# adom-shotlog — Screenshot Log++A Rust CLI + HTTP server (port **8820**) that captures, stores, and displays+screenshots in channels. AI agents inject screenshots as they work; you watch+them arrive live in a gallery (desktop or mobile), newest first, each with its+description, source, and **both** the stored and original resolution.++Binary: `/usr/local/bin/adom-shotlog` (the `shotlog` command is a back-compat alias).++## Inject — one command++```bash+adom-shotlog inject -c CHANNEL -d "what you see and why" -s SOURCE /path/to/image.png+```++adom-shotlog **always** records the original capture resolution — and **rejects any+inject that doesn't establish it**, so the viewer never shows "orig missing".++**Resizing before inject is fine and expected.** Oversized images crash Claude's+vision analysis, so most Adom screenshot verbs return a shrunk copy on purpose.+adom-shotlog doesn't fight that — it just requires the original size to travel with+the shot. Ways through:++1. **Pre-shrunk + the original dimensions** (the common case — your screenshot+   step reports the pre-resize W×H, you pass them through).+   ```bash+   adom-shotlog inject -c proj -d "…" --orig-w 1920 --orig-h 1080 /tmp/shrunk.png+   ```+2. **Pre-shrunk + the original image** — adom-shotlog measures it (keep the full-res+   file around for this).+   ```bash+   adom-shotlog inject -c proj -d "…" --orig-file /tmp/fullres.png /tmp/shrunk.png+   ```+3. **`--native`** — assert the image is at original capture resolution (never+   resized). Use only when true.+4. **Hand it the full-res image** — adom-shotlog resizes anything over 1500px (either+   edge) down to 1400px and records the original automatically.+5. **`--meta <ad-response.json>`** — ingest an Adom Desktop screenshot response+   (see below). The original W×H comes from the response's `origWidth/origHeight`,+   so this satisfies the original-resolution rule on its own.++**The rejection:** if FILE is ≤1500px (so adom-shotlog won't resize it) and you give+none of `--orig-w`+`--orig-h` / `--orig-file` / `--native` / `--meta`, the inject is+refused with exit 1 and a hint.++## `--meta` — Adom Desktop popup arrays++As of adom-desktop 1.8.177, `desktop_screenshot_window {hwnd}` returns the primary+window image **plus an array of owned popups** (autofill dropdowns, confirm+bubbles, native dialogs), each captured separately, plus coordMap / DPI / screen+metadata. Pass that whole response JSON via `--meta`:++```bash+adom-shotlog inject -c CH -d "checkout form with autofill open" primary.png --meta ad-response.json+```++adom-shotlog will:+- store the coordMap / DPI / screenRect / screen-resolution as a sidecar (revealed+  in the viewer's **⌗ capture metadata** panel, copyable as JSON),+- read each popup PNG by its `localSafePath`, save it next to the primary, and+  attach it — the card shows a **+N popups** badge and the zoom modal shows each+  popup as a viewable thumbnail,+- derive the original resolution from `origWidth/origHeight`.++The response shape it reads (extra fields are ignored, all optional except a+primary image + `screenshots[]` for popups):++```json+{+  "shotId": "…", "origWidth": 1920, "origHeight": 1200,+  "width": 1400, "height": 875,+  "coordMap": { "screenRect": {…}, "dpiScale": 1.25, "imageToScreen": {…}, "screenResolution": "1920x1200" },+  "ownedPopupCount": 2,+  "screenshots": [+    { "localSafePath": "/path/popup1.png", "hwnd": 12345, "title": "Autofill", "kind": "dropdown", "coordMap": {…} }+  ]+}+```++Plain single-image injects (no `--meta`) work exactly as before — popups/metadata+are additive.++| Flag | Required | Description |+|------|----------|-------------|+| `-c` | yes | Channel name (groups screenshots by task) |+| `-d` | yes | **Why this screenshot was taken** (becomes the filename, min 6 chars) |+| `-s` | no | Source: `pup_screenshot`, `desktop_screenshot_window`, `hd_shot`, etc. (default `cli`) |+| `--orig-file` | for pre-shrunk images | Path to the original full-res image; measured |+| `--orig-w` / `--orig-h` | for pre-shrunk images | Original dims (alternative to `--orig-file`) |+| `--native` | for unresized small images | Assert FILE is at original resolution |+| `--meta` | optional | Adom Desktop screenshot-response JSON: popups + coordMap + orig dims |+| `FILE` | yes | Primary image path (use `-` for stdin) |++## CRITICAL: Always write great descriptions++The `-d` description becomes the filename (slugified) and is shown prominently on+every gallery card. Make it specific.++**Bad:** `"screenshot"`, `"test"`, `"after fix"`+**Good:** `"PCB layout after routing power traces"`, `"Checkout form with autofill dropdown open"`++## The viewer++```bash+adom-shotlog open -c my-project          # opens the gallery as a Hydrogen webview tab+```++- **Gallery**, newest-first. Each card: description, timestamp, size (shown as+  `1400×788 · orig 1920×1080` when they differ), KB, source, a **+N popups** badge+  when the shot carried owned popups, and an **ⓘ meta** chip when it has capture+  metadata. Tap a card to zoom to the full image + popup thumbnails + the copyable+  metadata panel.+- **Mobile-ready**, **green LED** = a viewer is connected, **Ctrl+V** pastes a+  screenshot, **live updates** over WebSocket.++> **Do not place a shotlog tab on the VS Code pane.** Prefer computing a+> non-VS-Code `--panel-id` and calling `adom-cli hydrogen workspace add-tab`.++### Force-open safety net++If a screenshot is injected into a channel with **no viewer connected**, the+server auto-opens a viewer tab so the shot is never logged invisibly.++## Other commands++```bash+adom-shotlog serve                # start the server (port 8820)+adom-shotlog health               # check server status+adom-shotlog resize FILE          # rarely needed — inject auto-resizes+adom-shotlog install              # install binary + this skill + completions + `shotlog` alias+```++## Channel naming++Use the project or task name: `board-review`, `hd-setup-steps`, `debug-session`.