gipity 1.0.428 → 1.1.1

package/dist/commands/page-inspect.js

@@ -41,9 +41,9 @@ export const pageInspectCommand = new Command('inspect')
     .option('--no-reprobe', 'Skip the automatic second probe that filters one-time transient console errors - roughly halves inspect time on a page with any console error, at the cost of possibly reporting a cold-load transient as real')
     .option('--no-truncate', 'Show full URLs instead of truncating long ones with middle-ellipsis')
     .option('--all', 'Include render-blocking, large resources, oversized images, overflow culprits, and LCP detail')
-    .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps run headlessly (audio is a built-in tone, not real speech)')
+    .option('--no-fake-media', "Inspect with NO camera or microphone present, so a getUserMedia app takes its no-device error path (use this only when that fallback IS what you're inspecting)")
     .option('--device <name>', `Inspect as a real touch device: ${INSPECT_DEVICES.join(', ')}. Emulates touch events, mobile user-agent and DPR, so a touch-gated mobile layout is what gets inspected.`)
-    .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
+    .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
     // Hidden redirect: agents reach for `page inspect --screenshot`. We don't take
     // an image here (`page screenshot` is the single path for that) — just point there.
     .addOption(new Option('--screenshot [path]', 'Capture a screenshot').hideHelp())
@@ -65,11 +65,17 @@ export async function inspectPage(url, opts = {}) {
     const waitForTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 0 ? parsedTimeout : 5000;
     const truncate = opts.truncate !== false;
     const showAll = opts.all === true;
+    // The headless browser has a synthetic camera + mic BY DEFAULT. A real user
+    // inspecting a camera app has a camera; a browser without one makes every
+    // getUserMedia app report a NotFoundError that is an artifact of the probe,
+    // not a defect in the page — and worse, the app stops at its error path, so
+    // the pipeline the agent actually wanted inspected never runs. A synthetic
+    // device costs a page that never asks for media exactly nothing.
     const inspectBody = {
         url, waitMs,
         waitForSelector: opts.waitFor || undefined,
         waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
-        fakeMedia: opts.fakeMedia || undefined,
+        fakeMedia: opts.fakeMedia !== false ? true : undefined,
         device: opts.device ? resolveTouchDevice(opts.device) : undefined,
         auth: opts.auth || undefined,
     };
@@ -158,14 +164,18 @@ export async function inspectPage(url, opts = {}) {
     if (b.navigationIncomplete) {
         console.log(`${warning('⚠ Navigation incomplete:')} ${b.note || 'page did not reach full load'}`);
     }
-    // Auth state: without this line an agent can't distinguish "signed-in render"
-    // from "--auth silently no-op'd and I'm looking at the anonymous page".
+    // Identity line on EVERY run: without it an agent can't distinguish
+    // "signed-in render" from "--auth silently no-op'd and I'm looking at the
+    // anonymous page" — or assume an unflagged run carried a signed-in session.
     if (b.auth?.requested) {
         const who = getAuth()?.email;
         console.log(b.auth.established
             ? `${muted('Auth:')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
             : `${warning('Auth: session NOT established')}${b.auth.detail ? ` — ${b.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
     }
+    else {
+        console.log(muted('Auth: anonymous visitor (signed out; pass --auth to load as your Gipity account)'));
+    }
     console.log(`${muted('Title:')} ${b.title || '(none)'}`);
     console.log(`${muted('Elements:')} ${b.elementCount || 0}`);
     console.log(`${muted('Page weight:')} ${info(formatSize(b.totalBytes || 0))}`);

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
@@ -29,25 +30,50 @@ function label(text) {
 function fmtMs(ms) {
     return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
 }
-/** Auth state line (same format as page inspect/eval): without it an agent
- *  can't tell a signed-in capture from "--auth silently no-op'd and this is
- *  the anonymous page". */
+/** Identity line on EVERY capture (same format as page inspect/eval): without
+ *  it an agent can't tell a signed-in capture from "--auth silently no-op'd and
+ *  this is the anonymous page" — or assumes an unflagged capture carried a
+ *  signed-in session. */
 function printAuthLine(auth) {
-    if (!auth?.requested)
+    if (!auth?.requested) {
+        console.log(`${label('Auth')} ${muted('anonymous visitor (signed out; pass --auth to capture as your Gipity account)')}`);
         return;
+    }
     const who = getAuth()?.email;
     console.log(auth.established
         ? `${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 +100,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
@@ -151,49 +179,149 @@ function appendOption(value, previous = []) {
     return [...previous, value];
 }
 // Pre-capture scripting lives on --action, but agents reach for the JS-intent
-// names first and an "unknown option" alone doesn't name the right flag. Capture
-// 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'];
+// names first — --eval above all, the name they already know from `page eval`.
+// The intent is unambiguous (run this JS in the page before the shot), so these
+// are working hidden aliases, not errors — same accept-the-reflex-guess pattern
+// as --full-page and --width/--height. (Supersedes the earlier decoy approach,
+// which swallowed the script and errored with a redirect: when the guess is
+// unambiguous, making it WORK beats making it a better error.)
+const ACTION_ALIAS_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)')
+    // --device / --viewport lead the options: "how does this look on a phone?" is
+    // the single most common reason to screenshot, and agents routinely read the
+    // help through `--help | head -N` — buried below the timing flags, these two
+    // fell off the bottom and the run proceeded at desktop width.
+    .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), e.g. --viewport 390x844 for a phone-sized window', appendOption, [])
+    // 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('--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('--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. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
+    .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())
+    // (--eval and the other JS-intent guesses are registered in one place from
+    // ACTION_ALIAS_FLAGS below — a second standalone registration here makes
+    // commander throw "conflicting flag" at startup.)
     // `--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.
     .addOption(new Option('--full-page', 'Alias for --full').hideHelp())
+    // `--width 390 --height 844` is the setViewport vocabulary agents guess first
+    // when asked for a phone-sized shot. Accept the pair as a working alias for
+    // --viewport WxH instead of bouncing the guess into a --help detour.
+    .addOption(new Option('--width <px>', 'Alias: --viewport WxH').hideHelp())
+    .addOption(new Option('--height <px>', 'Alias: --viewport WxH').hideHelp())
     .action((url, opts) => run('Page screenshot', async () => {
-    // A JS-intent flag guess (captured as a hidden decoy below): name the real
-    // flag before any other arg-shape check fires.
-    const decoy = ACTION_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
-    if (decoy) {
-        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()"`);
+    // A JS-intent alias guess (--eval et al., hidden): fold it into the action
+    // script so the reflex guess just works, and name the canonical flag once
+    // so the next call uses it.
+    const aliasFlag = ACTION_ALIAS_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
+    if (aliasFlag) {
+        console.error(muted(`Note: treating ${aliasFlag} as --action — it runs your JS in the page before the capture. --action is the canonical flag.`));
+    }
+    const actionScript = [opts.action, ...ACTION_ALIAS_FLAGS.map((f) => opts[f.slice(2)])]
+        .filter(Boolean).join('\n');
+    // --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)");
     }
-    // --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)');
+    // 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);
+    // --width/--height: fold the alias pair into a --viewport entry. Half a
+    // pair is a mis-invocation worth one precise line, not a range error.
+    if (opts.width !== undefined || opts.height !== undefined) {
+        if (opts.width === undefined || opts.height === undefined) {
+            pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH) — ' +
+                'or use a preset like --device mobile for a real handset (touch events, mobile user-agent, DPR)');
+        }
+        if (!/^\d+$/.test(String(opts.width)) || !/^\d+$/.test(String(opts.height))) {
+            pageScreenshotCommand.error('error: --width and --height must be integers (px)');
+        }
+        viewportStrs.push(`${opts.width}x${opts.height}`);
+        // A raw phone-sized window is NOT a phone: touch-gated mobile UI still
+        // renders its desktop variant. Say so once, on the path where the caller
+        // was clearly after a phone.
+        if (parseInt(String(opts.width), 10) <= 500) {
+            console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR) — a raw viewport only resizes the window.'));
+        }
+    }
     const customViewports = [
         ...deviceNames.map(resolveDevice),
         ...viewportStrs.map(parseViewportString),
@@ -204,23 +332,80 @@ 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 (with any alias-flag scripts folded in by
+    // actionScript above). All 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) : '',
+        actionScript,
+    ].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 +414,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 +452,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 +488,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 +512,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.
+// Register the JS-intent guesses as hidden aliases for --action (value-taking,
+// so they capture the script) — the action folds them into the pre-capture body.
+for (const f of ACTION_ALIAS_FLAGS)
+    pageScreenshotCommand.addOption(new Option(`${f} <js>`, 'Alias for --action').hideHelp());
+// `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 +534,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/commands/project.js

@@ -134,7 +134,7 @@ projectCommand
         console.log(`${muted('Next:')} switch to "${project.name}" in the sidebar.`);
     }
     else {
-        console.log(`${muted('Next:')} exit Claude (Ctrl+D), then run:  ${brand('gipity claude')}`);
+        console.log(`${muted('Next:')} exit Claude (Ctrl+D), then run:  ${brand('gipity build')}`);
         console.log(`${muted('Pick')} "${project.name}" ${muted(`- it'll be at the top of the list.`)}`);
     }
 }));

package/dist/commands/relay-install.js

@@ -6,7 +6,7 @@ import { installAutostart, removeAutostart, resolveCliPath } from '../relay/setu
 function requirePaired() {
     const device = state.getDevice();
     if (!device) {
-        console.error(`${clrError('No paired device.')} Run ${bold('gipity claude')} to pair this machine.`);
+        console.error(`${clrError('No paired device.')} Run ${bold('gipity connect')} to pair this machine.`);
         process.exit(1);
     }
     return device;

package/dist/commands/relay.js

@@ -121,7 +121,7 @@ relayCommand
         return;
     }
     if (!s.device) {
-        console.log(`${muted('No paired device.')} Run ${brand('gipity claude')} to pair this machine.`);
+        console.log(`${muted('No paired device.')} Run ${brand('gipity connect')} to pair this machine.`);
         return;
     }
     console.log(`${bold('Device:')}      ${brand(s.device.name)} ${muted(`(${s.device.guid})`)}`);
@@ -380,7 +380,7 @@ registerInstallCommands(relayCommand);
 function requirePaired() {
     const device = state.getDevice();
     if (!device) {
-        console.error(`${clrError('No paired device.')} Run ${brand('gipity claude')} to pair this machine.`);
+        console.error(`${clrError('No paired device.')} Run ${brand('gipity connect')} to pair this machine.`);
         process.exit(1);
     }
     return device;