gipity 1.0.428 → 1.0.429

package/dist/commands/page-screenshot.js

@@ -2,12 +2,13 @@ import { Command, Option } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
 import { dirname, join, resolve as resolvePath } from 'path';
 import { postForTarEntries } from '../api.js';
-import { getProjectRoot } from '../config.js';
+import { getConfig, getProjectRoot } from '../config.js';
 import { getAuth } from '../auth.js';
 import { brand, bold, muted, success, warning } from '../colors.js';
 import { formatSize } from '../utils.js';
 import { run } from '../helpers/index.js';
 import { withSpinner } from '../progress.js';
+import { uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
 /** `mobile` and `tablet` name a real handset/tablet rather than just a window size.
  *  The server emulates it end to end - mobile user-agent, DPR, and crucially TOUCH,
  *  so a page that gates its mobile UI on `'ontouchstart' in window` or
@@ -40,14 +41,36 @@ function printAuthLine(auth) {
         ? `${label('Auth')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
         : `${warning('Auth: session NOT established')}${auth.detail ? ` — ${auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
 }
-/** A failed --action still yields a screenshot - of the page the action never
+/** A failed pre-capture script still yields a screenshot - of the page it never
  *  touched. Silence there is the trap: the image looks plausible and the command
- *  reports success, so the caller trusts a capture of the wrong state. Say so. */
-function printActionErrorLine(actionError) {
+ *  reports success, so the caller trusts a capture of the wrong state. Say so —
+ *  and say WHICH half failed, since --wait-for and --action ride the same script:
+ *  a gate that never matched is a different problem (and a different fix) from a
+ *  click that threw. */
+export function printActionErrorLine(actionError) {
     if (!actionError)
         return;
+    if (/wait-for:/.test(actionError)) {
+        console.log(`${warning('⚠ --wait-for never matched:')} ${actionError.replace(/^EvalError:\s*/, '')} ${muted('(the image below is the state the page WAS in when the gate gave up)')}`);
+        return;
+    }
     console.log(`${warning('⚠ --action failed:')} ${actionError} ${muted('(this image shows the page BEFORE the action ran)')}`);
 }
+/** The browser sandbox has one wall-clock budget for the entire capture, and
+ *  --action's own runtime spends it. When the sandbox times out on a run that
+ *  passed --action, the server's message ("platform-side failure, the page was
+ *  never reached") is the whole story only if the action was cheap — so append
+ *  the lever the caller actually has. Exported for tests. */
+export function augmentSandboxTimeout(message) {
+    if (!/did not respond within/i.test(message))
+        return message;
+    return (`${message}\n` +
+        `A pre-capture script was set (--action and/or the --wait-for gate), and its runtime is spent INSIDE ` +
+        `that same sandbox budget — a script that waits on slow work (a WASM/model download, a network fetch, ` +
+        `a long animation) can exhaust the budget on its own. Keep --action to the interaction itself (a click, ` +
+        `a keypress), let the page do the slow work on load, and absorb that with --wait <ms> or a tighter ` +
+        `--wait-for '<selector>' gate instead.`);
+}
 function fmtPerformance(p) {
     const parts = [
         `TTFB ${fmtMs(p.ttfb)}`,
@@ -74,13 +97,15 @@ function dimSuffix(vp) {
     const dpr = vp.deviceScaleFactor ?? 1;
     return dpr === 1 ? `${vp.width}x${vp.height}` : `${vp.width}x${vp.height}@${dpr}`;
 }
-/** Default screenshot directory: `<project-root>/.gipity/screenshots`, falling
- *  back to `./.gipity/screenshots` in one-off mode (no linked project). `.gipity/`
- *  is sync-ignored, so these verification artifacts never sync to Gipity or
- *  deploy to the CDN - and they stay out of the project root. */
+/** Default screenshot directory: `<project-root>/screenshots`, falling back
+ *  to `./screenshots` in one-off mode (no linked project). Screenshots are
+ *  part of the project's build history: the dir syncs to Gipity (the server
+ *  also persists captures to VFS `screenshots/` directly — same names, so
+ *  sync reconciles by content hash) but is excluded from every deploy
+ *  server-side. Timestamped filenames make the history browsable. */
 function defaultScreenshotDir() {
     const root = getProjectRoot();
-    return join(root ?? '.', '.gipity', 'screenshots');
+    return join(root ?? '.', 'screenshots');
 }
 /** `yyyy-mm-dd_hh-mm-ss` per the repo timestamp convention - sorts chronologically,
  *  filesystem-safe. One stamp per invocation; viewport suffixes keep multi-shot
@@ -155,23 +180,60 @@ function appendOption(value, previous = []) {
 // the common guesses as hidden decoys (taking a value, so they swallow the
 // script) and redirect precisely — same pattern as `page eval`'s JS_DECOY_FLAGS.
 const ACTION_DECOY_FLAGS = ['--eval', '--js', '--javascript', '--script', '--code', '--exec'];
+/** A capture is worthless if it fires before the app reaches the state you meant
+ *  to photograph, and the only lever used to be a blind millisecond delay — so a
+ *  camera/vision app got screenshotted with a guessed duration (`--wait 22000`).
+ *  `--wait-for '<selector>'` is the same deterministic gate `page eval` and
+ *  `page inspect` take, and it runs here as the head of the pre-capture script:
+ *  poll for the element, then let any --action run. Timing out THROWS, so the
+ *  server reports it (the shot still happens) instead of silently handing back a
+ *  picture of the wrong moment. Exported for tests. */
+export function buildWaitForGate(selector, timeoutMs) {
+    const sel = JSON.stringify(selector);
+    return (`await (async () => { const __t0 = Date.now(); ` +
+        `while (Date.now() - __t0 < ${timeoutMs}) { ` +
+        `try { if (document.querySelector(${sel})) return; } catch (e) { throw new Error('wait-for: invalid selector ' + ${sel}); } ` +
+        `await new Promise((r) => setTimeout(r, 100)); } ` +
+        `throw new Error('wait-for: nothing matched ' + ${sel} + ' within ${timeoutMs}ms — the page never reached that state (raise --wait-timeout, fix the selector, or check the app actually gets there headlessly)'); })();`);
+}
+/** Max ms the selector gate may wait. The gate runs inside the capture's sandbox
+ *  exec budget (page load + delay + script + settle + render), and 15s is what
+ *  that budget actually covers — asking for more would blow the whole capture and
+ *  come back as "the browser sandbox did not respond", blaming the platform for a
+ *  wait the CLI accepted. A state that takes longer than this to appear is not a
+ *  screenshot problem: gate it on `page eval --wait-for` (30s) and read it there. */
+export const WAIT_FOR_MAX_MS = 15_000;
+export const WAIT_FOR_DEFAULT_MS = 15_000;
+/** The server's cap on the post-load delay. Over it, the request is rejected by
+ *  schema validation with no mention of the flag — clamp and explain instead. */
+export const MAX_POST_LOAD_DELAY_MS = 30_000;
+/** A camera app has nothing to photograph 1s after load: getUserMedia has to come
+ *  up and the vision model (WASM + weights) has to download before the app can
+ *  draw a single box or label. Same window `page eval --camera` takes — without it
+ *  every camera screenshot is a picture of a loading screen, and the caller is
+ *  left guessing a duration. */
+export const CAMERA_DEFAULT_DELAY_MS = 15_000;
 export const pageScreenshotCommand = new Command('screenshot')
     .description('Screenshot a web page')
     .argument('<url>', 'URL to screenshot')
-    // No commander default: a default here makes opts.postLoadDelay always set,
-    // so the `?? opts.wait` merge below would never see the --wait alias. Default
-    // is applied in the merge instead.
-    .option('--post-load-delay <ms>', 'Delay after DOMContentLoaded before capture, in ms (default: 1000)')
+    // No commander default: a default here would make the value always set, so the
+    // merge below could not tell "caller chose a delay" from "nobody did" — which
+    // is what --camera's model-load default and the --wait-for gate both hinge on.
+    .option('--wait <ms>', `Sleep this many ms after DOMContentLoaded before capturing (default 1000, max ${MAX_POST_LOAD_DELAY_MS}). With --camera it defaults to ${CAMERA_DEFAULT_DELAY_MS} so the vision model is up. Same flag as page eval/inspect.`)
+    .option('--wait-for <selector>', `Wait until this CSS selector appears before capturing, then capture (deterministic - beats guessing a --wait). Same flag as page eval/inspect. Gate on what you are photographing ('[data-vision="ready"]', '#verdict:not(:empty)'). Max ${WAIT_FOR_MAX_MS}ms (--wait-timeout).`)
+    .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (default ${WAIT_FOR_DEFAULT_MS}, max ${WAIT_FOR_MAX_MS}). Timing out is reported - the capture still happens, so you see the state it got stuck in.`)
     .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./…\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
     .option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
     .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
     .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device — touch events, mobile user-agent, DPR — so touch-gated mobile UI actually renders.`, appendOption, [])
     .option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag)', appendOption, [])
     .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
-    .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly (audio is a built-in tone, not real speech)')
+    .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern — to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
+    .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture — so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
     .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
+    .option('--ephemeral', 'Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.')
     .option('--json', 'Output JSON metadata instead of a friendly summary')
-    .addOption(new Option('--wait <ms>', 'Alias for --post-load-delay').hideHelp())
+    .addOption(new Option('--post-load-delay <ms>', 'Alias for --wait').hideHelp())
     // `--full-page` is the Puppeteer/Playwright name for this (their `fullPage`),
     // so agents reach for it by reflex. Accept it as a hidden alias for `--full`
     // rather than reject it as an unknown option and send them on a --help detour.
@@ -184,13 +246,41 @@ export const pageScreenshotCommand = new Command('screenshot')
         pageScreenshotCommand.error(`error: ${decoy} is not a flag on screenshot — use --action "<js>" to run JavaScript in the page ` +
             `before the capture, e.g. gipity page screenshot "<url>" --action "document.getElementById('play').click()"`);
     }
-    // --wait is a hidden alias for --post-load-delay (agents reach for it because
-    // sibling `page inspect`/`eval` name the flag --wait). Canonical name wins if
-    // both given; fall back to the 1000ms default when neither is set.
-    const delayRaw = opts.postLoadDelay ?? opts.wait ?? '1000';
-    const postLoadDelayMs = delayRaw !== undefined ? parseInt(String(delayRaw), 10) : undefined;
-    if (postLoadDelayMs !== undefined && (!Number.isFinite(postLoadDelayMs) || postLoadDelayMs < 0)) {
-        throw new Error('--post-load-delay must be a non-negative integer (ms)');
+    // --wait is the canonical name (it is what `page inspect`/`page eval` call it);
+    // --post-load-delay stays as a hidden alias. Whether the caller named EITHER is
+    // what decides the defaults below, so keep the raw "was it set" signal.
+    const delayRaw = opts.wait ?? opts.postLoadDelay;
+    const chosenDelay = delayRaw !== undefined;
+    let postLoadDelayMs = chosenDelay ? parseInt(String(delayRaw), 10) : 1000;
+    if (!Number.isFinite(postLoadDelayMs) || postLoadDelayMs < 0) {
+        throw new Error('--wait must be a non-negative integer (ms)');
+    }
+    if (postLoadDelayMs > MAX_POST_LOAD_DELAY_MS) {
+        console.error(warning(`--wait ${postLoadDelayMs}ms exceeds the ${MAX_POST_LOAD_DELAY_MS}ms cap — using ${MAX_POST_LOAD_DELAY_MS}ms. ` +
+            `Waiting longer is rarely the fix: gate on the state you want with --wait-for '<selector>' instead of guessing a duration.`));
+        postLoadDelayMs = MAX_POST_LOAD_DELAY_MS;
+    }
+    const waitForTimeoutRaw = opts.waitTimeout !== undefined ? parseInt(String(opts.waitTimeout), 10) : WAIT_FOR_DEFAULT_MS;
+    if (!Number.isFinite(waitForTimeoutRaw) || waitForTimeoutRaw < 0) {
+        throw new Error('--wait-timeout must be a non-negative integer (ms)');
+    }
+    const waitForTimeoutMs = Math.min(waitForTimeoutRaw, WAIT_FOR_MAX_MS);
+    if (waitForTimeoutRaw > WAIT_FOR_MAX_MS) {
+        console.error(warning(`--wait-timeout ${waitForTimeoutRaw}ms exceeds the ${WAIT_FOR_MAX_MS}ms the capture's browser budget covers — using ${WAIT_FOR_MAX_MS}ms. ` +
+            `A state that takes longer than that to appear is not a screenshot problem: watch for it with ` +
+            `\`gipity page eval <url> --wait-for '<selector>' --wait-timeout 30000\` (a wider budget), then capture it.`));
+    }
+    if (opts.waitTimeout !== undefined && !opts.waitFor) {
+        throw new Error("--wait-timeout only means something with --wait-for '<selector>' (it bounds that gate)");
+    }
+    // A camera app is a loading screen at the 1s default: the model has to come up
+    // first. Give it the same window `page eval --camera` takes, unless the caller
+    // said otherwise — either with their own --wait, or by gating on --wait-for,
+    // which ends the moment the app is actually ready.
+    if (opts.camera && !chosenDelay && !opts.waitFor) {
+        postLoadDelayMs = CAMERA_DEFAULT_DELAY_MS;
+        console.error(muted(`--camera: waiting ${CAMERA_DEFAULT_DELAY_MS / 1000}s before the capture so the camera and the app's vision ` +
+            `model finish loading. Override with --wait <ms>, or use --wait-for '<ready-selector>' to shoot the moment it's ready.`));
     }
     const deviceNames = splitCsv(opts.device);
     const viewportStrs = splitCsv(opts.viewport);
@@ -204,23 +294,79 @@ export const pageScreenshotCommand = new Command('screenshot')
     // Server defaults to 1280×720 when viewports is omitted - don't send it in
     // the no-flag case so the filename stays unsuffixed (no viewport segment).
     const userSpecifiedViewports = customViewports.length > 0;
+    // Filenames are decided before the request so the server can persist the
+    // captures to the project VFS under the SAME names the local files get —
+    // the local screenshots/ dir and the VFS screenshot history stay 1:1 and
+    // sync reconciles them by content hash instead of duplicating.
+    const slug = slugFromUrl(url);
+    const ts = timestampSlug();
+    const shotName = (vp) => defaultFilename(slug, ts, vp && userSpecifiedViewports ? dimSuffix(vp) : undefined);
+    const names = userSpecifiedViewports ? customViewports.map(shotName) : [shotName()];
+    const projectGuid = getConfig()?.projectGuid;
+    const save = !opts.ephemeral && projectGuid ? { project_guid: projectGuid, names } : undefined;
+    // The webcam frame is hosted in the project's public file store for the
+    // browser container to fetch, so it needs a linked project. Validate the
+    // file locally first — a bad file type costs one instant error, not an
+    // upload plus an opaque browser-side failure.
+    let camera;
+    if (opts.camera) {
+        assertCameraFile(opts.camera);
+        if (!projectGuid)
+            throw new Error('--camera needs a linked project (the frame is hosted for the browser to fetch) — run `gipity link` first.');
+        console.log(muted(`Hosting camera feed ${opts.camera}…`));
+        camera = await uploadCameraFeed(projectGuid, opts.camera);
+    }
+    // The pre-capture script the server runs after the post-load delay: the
+    // --wait-for gate first (so the shot waits for the state, deterministically),
+    // then the caller's --action. Both are the same in-page primitive, so they
+    // compose into one script rather than needing a second server round-trip.
+    const preCapture = [
+        opts.waitFor ? buildWaitForGate(opts.waitFor, waitForTimeoutMs) : '',
+        opts.action ?? '',
+    ].filter(Boolean).join('\n');
     const body = {
         url,
         postLoadDelayMs,
         full: !!(opts.full || opts.fullPage),
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
-        ...(opts.fakeMedia ? { fakeMedia: true } : {}),
+        // A camera feed is played into the synthetic devices, so --camera implies
+        // --fake-media rather than failing on the pairing.
+        ...(opts.fakeMedia || camera ? { fakeMedia: true } : {}),
+        ...(camera ? { cameraUrl: camera.url } : {}),
         ...(opts.auth ? { auth: true } : {}),
-        ...(opts.action ? { action: opts.action } : {}),
+        ...(preCapture ? { action: preCapture } : {}),
+        ...(save ? { save } : {}),
     };
     // Load + render across viewports runs server-side and can take many
     // seconds; animate the wait, then clear so the saved-files summary is the
     // result. JSON mode skips the spinner (shares stdout).
     const doShoot = () => postForTarEntries('/tools/browser/screenshot', body);
-    const entries = opts.json
-        ? await doShoot()
-        : await withSpinner('Capturing…', doShoot, { done: null });
+    let entries;
+    try {
+        try {
+            entries = opts.json
+                ? await doShoot()
+                : await withSpinner('Capturing…', doShoot, { done: null });
+        }
+        catch (err) {
+            // The sandbox budget covers the WHOLE capture — load, --action, settle,
+            // render. The server's timeout text (rightly) says the page was never
+            // reached, which reads as "nothing you can do" and leaves a long-running
+            // --action looking innocent. Name it, so the retry is an informed one.
+            throw preCapture ? new Error(augmentSandboxTimeout(err.message)) : err;
+        }
+    }
+    finally {
+        if (camera) {
+            try {
+                await deleteFixture(projectGuid, camera.guid);
+            }
+            catch (err) {
+                console.error(warning(`⚠ Could not auto-delete camera feed "${camera.name}" (${camera.guid}) — still hosted at ${camera.url}: ${err.message}`));
+            }
+        }
+    }
     const metaEntry = entries.find((e) => e.name === 'meta.json');
     if (!metaEntry)
         throw new Error('Server response missing meta.json');
@@ -229,16 +375,12 @@ export const pageScreenshotCommand = new Command('screenshot')
     if (pngs.length !== meta.screenshots.length) {
         throw new Error(`Server returned ${pngs.length} PNGs but ${meta.screenshots.length} metadata entries`);
     }
-    const slug = slugFromUrl(url);
-    const ts = timestampSlug();
     const dir = defaultScreenshotDir();
     const savedFiles = [];
     for (let i = 0; i < pngs.length; i++) {
-        const shot = meta.screenshots[i];
-        const suffix = userSpecifiedViewports ? dimSuffix(shot.viewport) : undefined;
         const target = opts.output
             ? opts.output
-            : join(dir, defaultFilename(slug, ts, suffix));
+            : join(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
         // Create the target's parent dir so a `-o` path under a not-yet-existing
         // directory (e.g. .gipity/screenshots/home.png) writes cleanly instead of
         // failing with a raw ENOENT and forcing a manual `mkdir -p`.
@@ -271,10 +413,22 @@ export const pageScreenshotCommand = new Command('screenshot')
                 size_bytes: s.screenshotSizeBytes,
                 full_page: meta.full,
                 phase: s.phase,
+                ...(s.vfs ? { gipity: s.vfs } : {}),
             })),
         }));
         return;
     }
+    /** One-line VFS-history status for a screenshot ("saved to Gipity" or why not). */
+    const printVfsLine = (s) => {
+        if (!s.vfs)
+            return;
+        if ('error' in s.vfs) {
+            console.log(`${warning('⚠ Gipity save failed:')} ${s.vfs.error} ${muted('(local file is fine)')}`);
+        }
+        else {
+            console.log(`${label('Gipity history')} ${s.vfs.path} ${muted('(synced, not deployed)')}`);
+        }
+    };
     if (meta.screenshots.length === 1) {
         const s = meta.screenshots[0];
         console.log(`${brand('Screenshot')} ${bold(url)}`);
@@ -295,6 +449,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         if (s.width && s.height)
             console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
         console.log(`${label('Screenshot file')} ${success(savedFiles[0])}`);
+        printVfsLine(s);
         return;
     }
     console.log(`${brand('Loading')} ${bold(url)} ${muted(`once → ${meta.screenshots.length} viewports`)}`);
@@ -318,20 +473,21 @@ export const pageScreenshotCommand = new Command('screenshot')
         if (s.width && s.height)
             console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
         console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
+        printVfsLine(s);
     }
 }));
 // Register the JS-intent guesses as hidden decoys (value-taking, so they swallow
 // the script) — the action turns any of them into the "--action" redirect above.
 for (const f of ACTION_DECOY_FLAGS)
     pageScreenshotCommand.addOption(new Option(`${f} <value>`).hideHelp());
-// `screenshot` captures the page AFTER load + settle (+ optional --action). There
-// is no scroll-to-a-position or wait-for-a-selector lever (agents reach for
-// --scroll/--selector and get an unknown-option detour) — but `--full` does walk
-// the page top→bottom→top before the shot so scroll-reveal content paints in.
-// State the supported levers right here, so the help (rendered on any bad flag,
-// and this 'after' block survives `| tail`/`| grep`) ends the hunt in one shot.
-// --action covers "click, then shoot"; --full + crop covers off-screen regions
-// (and triggers reveals); `page eval` reads data without a picture.
+// `screenshot` captures the page AFTER load + settle (+ optional --wait-for gate
+// and --action). There is no scroll-to-a-position lever (agents reach for
+// --scroll and get an unknown-option detour) — but `--full` does walk the page
+// top→bottom→top before the shot so scroll-reveal content paints in. State the
+// supported levers right here, so the help (rendered on any bad flag, and this
+// 'after' block survives `| tail`/`| grep`) ends the hunt in one shot.
+// --wait-for covers "shoot once it's ready"; --action covers "click, then shoot";
+// --full + crop covers off-screen regions; `page eval` reads data, no picture.
 pageScreenshotCommand.addHelpText('after', `
 Examples:
   gipity page screenshot "https://dev.gipity.ai/me/app/"
@@ -339,11 +495,21 @@ Examples:
   gipity page screenshot "https://dev.gipity.ai/me/app/" --device mobile,desktop
   gipity page screenshot "https://dev.gipity.ai/me/app/" \\
     --action "document.getElementById('play').click()"                   # capture an in-game frame
+  # Camera / vision app: play a real frame in as the webcam and shoot once the app
+  # says it's ready — same --camera / --wait-for flags as 'page eval', no guessed delay:
+  gipity page screenshot "https://dev.gipity.ai/me/app/" --camera fist.png \\
+    --wait-for '[data-vision="ready"]'
+
+Waiting for the page to reach a state before the shot?
+  --wait-for '<selector>' gates the capture on the app's own signal (deterministic).
+  Reach for --wait <ms> only when there is nothing to gate on — a guessed duration
+  either shoots too early or wastes the difference.
 
 Capturing a state that needs an interaction (start a game, open a menu, dismiss a modal)?
-  Use --action to run JS in the page before the shot — it fires after the post-load
-  delay, then settles again so the result has painted. Do NOT hand-roll a 'page eval'
-  that returns a base64 image: the eval result is capped (~16KB) and truncates the PNG.
+  Use --action to run JS in the page before the shot — it fires after the wait
+  (and after any --wait-for gate), then settles again so the result has painted. Do
+  NOT hand-roll a 'page eval' that returns a base64 image: the eval result is capped
+  (~16KB) and truncates the PNG.
 
 Capturing an off-screen region or reading element data?
     • --full captures the ENTIRE scrollable page (then crop to the region).

package/dist/hooks/capture-runner.js

@@ -41,6 +41,7 @@ import { homedir } from 'os';
 import { join } from 'path';
 import { getDevice } from '../relay/state.js';
 import { deviceFetch } from '../relay/device-http.js';
+import { ImageBlockRewriter } from '../relay/media-upload.js';
 import { getConfig } from '../config.js';
 import { parseTranscript, } from '../capture/sources/claude-code.js';
 const CAPTURE_DIR = join(homedir(), '.gipity', 'capture-state');
@@ -360,7 +361,14 @@ async function handleStopFamily(convGuid, hook, isSubagent, minIntervalMs = 0) {
             // Replay from top; server dedupes via the source_uuid unique index.
             result = parseTranscript(content, null);
         }
-        const ok = await postEntries(convGuid, result.entries);
+        // Base64 image blocks (Read-of-image tool results) upload to VFS and
+        // become image_ref blocks — same no-inline-base64 chokepoint as the
+        // daemon's stream path. Content-hash storage keeps replays idempotent.
+        const rewriter = new ImageBlockRewriter(convGuid);
+        if (hook.cwd)
+            rewriter.setCwd(hook.cwd);
+        const entries = await rewriter.rewrite(result.entries);
+        const ok = await postEntries(convGuid, entries);
         if (ok) {
             // Stamp the flush time even when no new lines landed, so the throttle
             // above measures from the last attempt. Keep the watermark if unchanged.