Shotlog - Screenshot Log

@@ -0,0 +1,91 @@+# adom-shotlog++**See the shots your AI never showed you.**++Your AI screenshots your app constantly while it builds and tests — but it's text-centric, so those shots get buried in tool output and you never actually see them. adom-shotlog is the fix: a tiny Rust CLI + server where the AI drops each screenshot into a **channel**, and you watch them stream into a newest-first **gallery** — open it in a Hydrogen webview, a pup window, your native browser, or on your phone. Every shot records its description, source, and **original capture resolution**, so you always know exactly what the AI saw. It's the simplest, most-reached-for tool in the Adom toolbox: if your AI is doing anything visual, adom-shotlog lets you see it.++## Install++```+adompkg install adom/adom-shotlog+```++The CLI installs as `adom-shotlog` (with a back-compat `shotlog` alias).++## The on-the-road superpower: `/remote-control` + your phone++You're away from your desk. You ask your AI to do something long — build a board, run a setup, render a viewer. You tell it to **shotlog the whole thing**, and it sends you one URL. You open that URL **on your phone** and watch every step stream in as it happens — then scroll back through the whole run whenever you want.++![adom-shotlog on a phone](screenshots/mobile.png)++Combined with **`/remote-control`**, you can kick off real work from anywhere and keep vibe-coding from the passenger seat. Your AI does the work, shotlogs it, and hands you a link. No screen-share, no VNC, no "send me a screenshot" back-and-forth.++## Other things people use it for every day++- **Verifying long-running jobs without babysitting them.** Start a 20-minute build or a multi-step install, have the AI shotlog each milestone, then review the whole sequence at your own pace. We shotlog the **entire Hydrogen Desktop setup-step sequence** this way.+- **Capturing every state of a complex feature.** When building HD's screenshot pipeline we shotlogged **all of the screenshotting states** — full window, VS Code panel, wiki webview — side by side.+- **Gathering the images for public READMEs.** Point the AI at a channel, let it shotlog each view, then pick the best ones straight from the gallery.+- **Proof-of-work debug loops.** "Prove it's working" → the AI drives the UI, shotlogs each state, and hands you the gallery as evidence.++## Quick start++```+adom-shotlog serve &                               # start the server (port 8820)+adom-shotlog open -c my-project                     # open the gallery viewer+adom-shotlog inject -c my-project \+  -d "Board layout after routing power traces" \+  -s pup_screenshot --orig-w 1920 --orig-h 1080 /tmp/shot.png+```++## It refuses to log a shot blind++adom-shotlog **always** records the original capture resolution, so the gallery never shows a mystery "what size was this really?" — it shows `1400×788 · orig 1920×1080`. Resizing before inject is expected (oversized images crash AI vision analysis), so most screenshot tools hand back a shrunk copy. adom-shotlog just requires the original size to travel with it — via `--orig-w/--orig-h`, `--orig-file`, `--native`, or `--meta`. A bare inject of a pre-shrunk image is rejected with a hint.++## Captures the popups too (`--meta`)++Adom Desktop's `desktop_screenshot_window` returns the primary window **plus an array of owned popups** (autofill dropdowns, confirm bubbles, native dialogs) and coordMap / DPI / screen metadata. Pass the whole response through `--meta`:++```+adom-shotlog inject -c checkout -d "checkout form with autofill open" primary.png --meta ad-response.json+```++The gallery card gets a **+N popups** badge; the zoom modal shows each popup as a viewable thumbnail; and an **ⓘ meta** chip opens a copyable panel with shotId, screenRect, dpiScale, imageToScreen, and screen resolution.++![Popup array + capture metadata in the zoom modal](screenshots/popups.png)++## Gallery — desktop++![Desktop gallery](screenshots/gallery-desktop.png)++Newest-first cards, each with a prominent description, dual-size metadata, source, and KB. Tap any card to zoom to the full image. A green LED shows when a viewer is connected; new shots appear at the top instantly over WebSocket. If a shot lands in a channel nobody is watching, the server force-opens a viewer so nothing is ever logged invisibly.++## Features++- **Channels** — group shots by project, task, or debug session+- **Enforced original-resolution tracking** — every shot's true capture size, never lost+- **Owned-popup arrays** — `--meta` ingests Adom Desktop popup captures + coordMap; the viewer reveals each popup + the metadata+- **Gallery viewer** — newest-first, prominent descriptions, dual-size metadata, tap-to-zoom, mobile layout, tooltips+- **Phone-ready** — open the same URL on your phone; the layout adapts+- **Live updates + presence LED** — new shots stream in; a green dot shows you're connected+- **Force-open safety net** — an unwatched channel auto-opens a viewer+- **Clipboard paste** — Ctrl+V anywhere pastes a screenshot++## CLI reference++| Command | Description |+|---|---|+| `adom-shotlog inject` | Inject a screenshot into a channel (records the original resolution; `--meta` adds popups) |+| `adom-shotlog open` | Open the gallery viewer as a Hydrogen webview tab |+| `adom-shotlog serve` | Start the HTTP server (port 8820) |+| `adom-shotlog health` | Check if the server is running |+| `adom-shotlog resize` | Resize an image (rarely needed — inject auto-resizes) |+| `adom-shotlog install` | Install skill + bash completions + the `shotlog` alias |++## Dependencies++| Dependency | Required? | Why |+|---|---|---|+| **adom-cli** | For the viewer | `adom-shotlog open` adds the gallery as a Hydrogen webview tab. |+| **adom-desktop** | Optional | AI agents use it to capture screenshots (and popup arrays) that get injected. Humans can Ctrl+V paste instead. |++No `adompkg` package dependencies — adom-shotlog is a self-contained Rust binary.