Shotlog - Screenshot Log

@@ -10,7 +10,7 @@ checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"  [[package]] name = "adom-shotlog"-version = "0.28.7"+version = "0.29.0" dependencies = [  "axum",  "base64",

@@ -1,6 +1,6 @@ [package] name = "adom-shotlog"-version = "0.28.7"+version = "0.29.0" edition = "2021" description = "Screenshot log viewer and CLI for Adom" license = "MIT"

@@ -26,6 +26,8 @@ shotlog ships a Claude Code `PostToolUse(Read)` hook (`hooks/shotlog-on-read.sh`  `adom-shotlog install` deploys the hook and registers it in `~/.claude/settings.json` (surgically, never touching your other hooks), and **every `serve` startup re-verifies both**, healing them if missing, so the pipeline cannot silently rot. The hook also self-heals the broker if it is not running. +**The send-hook: what the AI said about it.** A capture taken on read only knows the file name. When an AI then sends that image to you with a caption ("Domino with bottom pours: 0.3 mm gap, two vias per pad..."), the companion `PostToolUse(SendUserFile)` hook (`hooks/shotlog-on-send.sh`) makes the caption the shot's description, matched to the shot by the image's content, and the card updates live. The automatic description is kept as `auto_description`. Images sent without being read are added with their caption. `adom-shotlog annotate -d "..." <file>` does the same by hand.+ Related guarantees: the broker is **single-instance per port** (a second `serve` detects the healthy broker and defers gracefully, warning if versions differ), and `read-captures` stays disk-bounded by the retention policy.  ## It adapts to your surface

@@ -72,6 +72,23 @@ broker (from `$SHOTLOG_HOME`, default `~/project`) if it is down. If you see `read-captures` filling up: that is this hook working as designed, and retention keeps it bounded. +## The send-hook: your caption becomes the shot's description++A read-hook capture only knows the file name ("Auto-captured screenshot Claude+read for analysis: x.png"). What you SAY about the image comes later, when you+send it to the human. shotlog also ships a `PostToolUse(SendUserFile)` hook:+when you send an image with a `caption`, that caption replaces the description+of the shot made from the same file (matched by content, not name), the+automatic text is kept as `auto_description`, and open viewers update that card+in place. An image you send without having read it is injected with the+caption. So: give image sends a real caption; it is what the human reads in+shotlog. Installed and re-verified with the read-hook; off when the read-hook+is off.++By hand: `adom-shotlog annotate -d "<what it shows>" <file>` re-describes the+newest shot made from `<file>` (exit 3 when there is none; `--inject-missing`+adds it instead).+ ## Preferences and canvas control (AI-drivable)  Everything the human can click, YOU can do - and the human is told the matching

@@ -1 +1 @@-0.28.7+0.29.0

⋯ 1 unchanged line ⋯

@@ -482,3 +482,7 @@ When you fix something Ray reported (issue or PR), DM him one simple line on Goo  The viewer's `<base>` is derived from the page's own path: everything in front of `/log/`. Never match a fixed `/proxy/N/` prefix: code-server serves `/proxy/8820/`, Mac Hydrogen serves `/__cs/proxy/8820/`, and a direct open has none. With the wrong base every relative fetch and the WebSocket go to the host app instead of the broker and the gallery sits empty with a gray LED. `open --webview` now polls `viewer-status` for 8s after the tab opens and prints WARN + the direct `localhost:<port>/log/` URL when nothing connects; `broker_viewer_count(port, channel)` is the helper. Filelog carries the identical derivation. ++## Send-hook and annotate (Ray, 2026-10-16)++A read-hook shot is taken BEFORE the AI writes anything about the image, so its only description is the file name. `hooks/shotlog-on-send.sh` (PostToolUse SendUserFile, registered by `ensure_hook` next to the read-hook) runs `annotate --inject-missing` with the send's caption for each image. Matching is by `image::fingerprint` (FNV-1a 64 + length over the bytes AS THE CALLER HAD THEM, before any broker resize), stored on the entry and its sidecar; never match by filename (shotlog renames files from the description). `Store::annotate` replaces `description`, keeps the first automatic one in `auto_description`, fills thread/context only when empty, rewrites the sidecar and re-broadcasts the entry; the viewer's existing same-id branch replaces the card. Shots from before 0.29.0 have no fingerprint and cannot be annotated (the hook then injects a new captioned shot).

@@ -0,0 +1,59 @@+#!/bin/bash+# PostToolUse(SendUserFile) hook - SHIPPED AND MANAGED BY adom-shotlog.+# When an AI SENDS an image to the human with a caption, that caption becomes+# the description of the shot made from the same file (matched by content via+# `shotlog annotate`), so the shotlog card says what the AI said about it -+# not just "Auto-captured screenshot Claude read for analysis: <file>".+# An image that was sent but never Read is injected with the caption.+# Installed by `adom-shotlog install` and re-verified at every+# `adom-shotlog serve` startup; edits here are overwritten.+#+# Reads the hook JSON on stdin:+#   {"tool_name":"SendUserFile","tool_input":{"files":[...],"caption":"..."},"cwd":"..."}+# Always exits 0 so it can never block a send.++# Same switch as the read-hook: auto-capture off in the viewer's Preferences.+[ -f "$HOME/.claude/hooks/.shotlog-read-hook-off" ] && exit 0++INPUT="$(cat)"+[ "$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)" = "SendUserFile" ] || exit 0+CAPTION="$(echo "$INPUT" | jq -r '.tool_input.caption // empty' 2>/dev/null)"+# No caption: nothing to carry over (the file name is all the read-hook had too).+[ -z "$(printf '%s' "$CAPTION" | tr -d '[:space:]')" ] && exit 0+command -v shotlog >/dev/null 2>&1 || exit 0+CWD="$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)"++# Thread + context exactly as the read-hook derives them (used only where the+# shot has none, or when the image was never read and is injected here).+SID="$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)"+TP="$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)"+THREAD=""; CONTEXT=""+if [ -n "$TP" ] && [ -f "$TP" ]; then+  THREAD="$(grep '"type":"custom-title"' "$TP" 2>/dev/null | tail -1 | jq -r '.customTitle // empty' 2>/dev/null)"+  [ -z "$THREAD" ] && THREAD="$(grep '"type":"ai-title"' "$TP" 2>/dev/null | tail -1 | jq -r '.aiTitle // empty' 2>/dev/null)"+  CONTEXT="$(grep '"type":"last-prompt"' "$TP" 2>/dev/null | tail -1 | jq -r '.lastPrompt // empty' 2>/dev/null | head -c 220)"+fi+[ -z "$THREAD" ] && [ -n "$SID" ] && THREAD="thread ${SID:0:8}"++shotlog health >/dev/null 2>&1 || { (cd "${SHOTLOG_HOME:-$HOME/project}" && shotlog serve >/dev/null 2>&1 &) ; sleep 1; }++echo "$INPUT" | jq -r '.tool_input.files[]? // empty' 2>/dev/null | while IFS= read -r f; do+  [ -z "$f" ] && continue+  case "$f" in /*) ;; *) [ -n "$CWD" ] && f="$CWD/$f" ;; esac+  case "$f" in+    *.png|*.jpg|*.jpeg|*.PNG|*.JPG|*.JPEG) ;;   # the same types the read-hook captures+    *) continue ;;+  esac+  [ -f "$f" ] || continue+  # A file already inside shotlog's own store is a stored COPY (possibly+  # resized): its fingerprint never matches the original, so --inject-missing+  # would add a duplicate card. Same skip as the read-hook.+  case "$f" in */screenshots/shotlog/*) continue ;; esac+  for attempt in 1 2 3; do+    shotlog annotate -c read-captures --inject-missing -d "$CAPTION" \+      ${THREAD:+--thread "$THREAD"} ${CONTEXT:+--context "$CONTEXT"} "$f" >/dev/null 2>&1 && break+    sleep 2+  done+done++exit 0

@@ -1,6 +1,6 @@ {   "slug": "adom-shotlog",-  "version": "0.28.7",+  "version": "0.29.0",   "type": "app",   "title": "Shotlog - Screenshot Log",   "description": "See the shots your AI never showed you, and know it actually SAW them. adom-shotlog streams every screenshot the AI gathers into a live gallery (webview/pup/browser/phone), reports whether a human is really watching and on which surface, and ingests Adom Bridge child-window arrays via --meta.",

@@ -1,6 +1,6 @@ {   "slug": "adom-shotlog",-  "version": "0.28.7",+  "version": "0.29.0",   "type": "app",   "title": "Shotlog - Screenshot Log",   "description": "See the shots your AI never showed you, and know it actually SAW them. adom-shotlog streams every screenshot the AI gathers into a live gallery (webview/pup/browser/phone), reports whether a human is really watching and on which surface, and ingests Adom Bridge child-window arrays via --meta.",

@@ -269,6 +269,15 @@ body.compact .card-popups .ph { padding-top: 4px; } @media (hover: none) { .card-refbar .rb-copy { opacity: .8; } } .card-refbar .rb-tag { color: var(--accent-bright); background: rgba(0,184,176,.12); border: 1px solid rgba(0,184,176,.45);   border-radius: 5px; padding: 0 6px; max-width: 70%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }+/* caption pill (gold): an annotated shot carries a longer caption from the+   AI that sent it. It starts the caption here, cut to fit the narrow+   sidebar, and hovering it reveals the full info overlay, like the ⓘ. */+.card-refbar .rb-cap { color: #e3b341; background: rgba(227,179,65,.10); border: 1px solid rgba(227,179,65,.45);+  border-radius: 5px; padding: 0 6px; flex: 1 1 0; min-width: 0; overflow: hidden; text-overflow: ellipsis;+  white-space: nowrap; cursor: help; font-family: 'Satoshi', sans-serif; font-weight: 600; }+/* classic mode already shows the caption above the image */+body:not(.compact) .card-refbar .rb-cap { display: none; }+.card-refbar .rb-cap:hover { background: rgba(227,179,65,.18); border-color: rgba(227,179,65,.7); } .shot-card:not(.has-refbar) .card-refbar { } .chip { display: inline-block; padding: 1px 6px; border-radius: 5px; background: var(--overlay);   border: 1px solid var(--border-muted); font-family: 'JetBrains Mono', monospace;@@ -1175,7 +1184,25 @@ body.compact .card-popups .ph { padding-top: 4px; }     // was serving, and demote the generic "auto-captured: file.png" to a     // small mono sub-line. Deliberate injects keep their description first.     const isAuto=(e.source||'').startsWith('read-hook');-    if (isAuto && e.context) {+    if (e.auto_description) {+      // Annotated (send-hook / `annotate`): the caption the AI wrote when it+      // SENT this image is the headline; the prompt and the file name it was+      // auto-captured as become the small sub-lines.+      // .shot-card-why styling, not .shot-card-desc: captions run long and+      // the desc style clips at 76px, which in the narrow sidebar's ⓘ overlay+      // cut the caption to a few words. The overlay sizes to its content.+      const desc=document.createElement('div'); desc.className='shot-card-why shot-card-caption';+      desc.textContent=e.description;+      info.appendChild(desc);+      if (e.context) {+        const why=document.createElement('div'); why.className='shot-card-sub';+        why.textContent='prompt: '+e.context;+        info.appendChild(why);+      }+      const sub=document.createElement('div'); sub.className='shot-card-sub';+      sub.textContent='auto-captured: '+(e.filename||'').replace(/^auto-captured-screenshot-claude-read-for-analysis-/,'');+      info.appendChild(sub);+    } else if (isAuto && e.context) {       const why=document.createElement('div'); why.className='shot-card-why';       why.textContent=e.context;       why.setAttribute('data-tooltip','The prompt this AI thread was working on when it read the image - the REASON this capture exists.');@@ -1256,6 +1283,14 @@ body.compact .card-popups .ph { padding-top: 4px; }       if (e.tag){ const tg=document.createElement('span'); tg.className='rb-tag'; tg.textContent=e.tag;         tg.setAttribute('data-tooltip','Handle "'+e.tag+'" given by the AI that injected this shot (--tag). Say "'+e.tag+'" to mean exactly this shot.');         rb.appendChild(tg); }+      if (e.auto_description && e.description) {+        const cp=document.createElement('span'); cp.className='rb-cap'; cp.textContent=e.description;+        cp.setAttribute('aria-label','Caption: '+e.description);+        // Same reveal as the ⓘ: hover shows the full info overlay (caption,+        // prompt, file, chips); click toggles it for touch.+        cp.addEventListener('mouseenter', ()=>{ info.classList.add('show'); window._hideTip&&window._hideTip(); });+        cp.addEventListener('click', ev=>{ ev.stopPropagation(); info.classList.toggle('show'); });+        rb.appendChild(cp); }       // Copy the WHOLE reference, "#158 hero-final", not just one half (Ray,       // PR #5): the ref is globally unambiguous and the handle is what a human       // actually says, so pasting both lets the AI resolve it either way and

@@ -118,3 +118,16 @@ pub fn parse_data_url(data_url: &str) -> Result<(String, Vec<u8>), String> {     Ok((mime, bytes)) } ++/// Content FINGERPRINT of an image file as the caller had it (before any+/// broker resize): FNV-1a 64 over the bytes, plus the length. Stable across+/// versions and hosts (no std hasher), so a later step that only has the FILE+/// (the send-hook, `shotlog annotate`) can find the shot made from it.+pub fn fingerprint(bytes: &[u8]) -> String {+    let mut h: u64 = 0xcbf29ce484222325;+    for b in bytes {+        h ^= *b as u64;+        h = h.wrapping_mul(0x100000001b3);+    }+    format!("{h:016x}-{}", bytes.len())+}

@@ -196,6 +196,7 @@ pub fn create_router(state: Arc<AppState>) -> Router {         .route("/api/clear-all", delete(clear_all))         .route("/api/clear-everything", delete(clear_everything))         .route("/api/delete", delete(delete_entry))+        .route("/api/annotate", post(post_annotate))         .route("/ws/{channel}", get(ws_handler))         .route("/shots/{channel}/{filename}", get(serve_image))         .route("/health", get(health))@@ -1177,6 +1178,35 @@ struct InjectResponse {     hints: Vec<String>, } +#[derive(Deserialize)]+struct AnnotateRequest {+    /// image::fingerprint of the file (the CLI computes it from FILE).+    fingerprint: String,+    /// The new description (e.g. the caption an AI wrote when it sent the image).+    description: String,+    /// Channel to search first; every channel is searched after it.+    channel: Option<String>,+    thread: Option<String>,+    context: Option<String>,+}++/// Re-describe an existing shot by the fingerprint of the file it was made+/// from. {ok:false, found:false} when no shot has it (the caller may inject).+async fn post_annotate(+    State(state): State<Arc<AppState>>,+    Json(req): Json<AnnotateRequest>,+) -> Json<serde_json::Value> {+    let desc = req.description.trim();+    if desc.is_empty() {+        return Json(serde_json::json!({"ok": false, "error": "empty description"}));+    }+    match state.store.annotate(&req.fingerprint, req.channel.as_deref(), desc, req.thread, req.context).await {+        Some((channel, e)) => Json(serde_json::json!({"ok": true, "found": true, "channel": channel,+            "id": e.id, "description": e.description, "auto_description": e.auto_description})),+        None => Json(serde_json::json!({"ok": false, "found": false})),+    }+}+ async fn post_shots(     State(state): State<Arc<AppState>>,     Json(req): Json<InjectRequest>,@@ -1185,6 +1215,9 @@ async fn post_shots(         parse_data_url(&req.image).map_err(|e| (StatusCode::BAD_REQUEST, e))?;      let (incoming_w, incoming_h) = read_png_dimensions(&raw_bytes);+    // Fingerprint the file AS THE CALLER HAD IT (before our resize), so a later+    // `annotate` that only has that file can find this shot.+    let fingerprint = crate::image::fingerprint(&raw_bytes);      // Auto-resize anything over the limit, recording the TRUE original. This is     // how orig dims get captured at the source: shotlog owns the resize, so it@@ -1234,7 +1267,7 @@ async fn post_shots(      let entry = state         .store-        .add_entry(&req.channel, bytes, filename, req.description, source, w, h, orig_w, orig_h, req.meta, popups_stored, req.thread.clone(), req.context.clone(), req.orig_path.clone(), req.tag.clone().map(|t| t.trim().chars().take(40).collect::<String>()).filter(|t| !t.is_empty()))+        .add_entry(&req.channel, bytes, filename, req.description, source, w, h, orig_w, orig_h, req.meta, popups_stored, req.thread.clone(), req.context.clone(), req.orig_path.clone(), req.tag.clone().map(|t| t.trim().chars().take(40).collect::<String>()).filter(|t| !t.is_empty()), Some(fingerprint))         .await;      // Presence at inject time — the caller uses this to know if the human is@@ -1371,6 +1404,7 @@ async fn post_paste(      let (orig_w, orig_h) = read_png_dimensions(&raw_bytes);     let orig_bytes = raw_bytes.len() as u64;+    let fingerprint = crate::image::fingerprint(&raw_bytes);      let (bytes, w, h) =         resize_png(raw_bytes, RESIZE_TO).map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e))?;@@ -1401,7 +1435,7 @@ async fn post_paste(             &req.channel, bytes, filename, description, source, w, h,             if was_resized { Some(orig_w) } else { None },             if was_resized { Some(orig_h) } else { None },-            None, None, req.thread.clone(), req.context.clone(), None, None,+            None, None, req.thread.clone(), req.context.clone(), None, None, Some(fingerprint),         )         .await;