gipity 1.0.422 → 1.0.425

package/dist/commands/page-inspect.js

@@ -1,8 +1,9 @@
 import { Command, Option } from 'commander';
 import { post } from '../api.js';
 import { formatSize } from '../utils.js';
-import { brand, bold, error as clrError, warning, muted, info } from '../colors.js';
+import { brand, bold, error as clrError, warning, muted, info, success } from '../colors.js';
 import { run } from '../helpers/index.js';
+import { getAuth } from '../auth.js';
 import { capWaitMs } from './page-eval.js';
 import { TOUCH_DEVICES as INSPECT_DEVICES, resolveTouchDevice } from './page-screenshot.js';
 /** A console line is an error-level entry (page error or console.error). */
@@ -31,12 +32,13 @@ function shortUrl(url, truncate = true, maxLen = 100) {
     return result.slice(0, headLen) + '…' + result.slice(-tailLen);
 }
 export const pageInspectCommand = new Command('inspect')
-    .description('Inspect a web page (console, failed resources, timing, layout overflow)')
+    .description('Inspect a web page (console, failed resources, timing, layout overflow). ONE passive load - to verify realtime/presence across concurrent clients use `page test --observe`')
     .argument('<url>', 'URL to inspect')
     .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before capturing (lets late async/LCP work settle; max 30000)', '500')
     .option('--wait-for <selector>', 'Wait until this CSS selector appears before capturing (deterministic; replaces --wait)')
     .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
     .option('--json', 'Output as JSON')
+    .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)')
@@ -51,206 +53,219 @@ export const pageInspectCommand = new Command('inspect')
         console.error(`  gipity page screenshot ${url}${typeof opts.screenshot === 'string' ? ` -o ${opts.screenshot}` : ''}`);
         process.exit(1);
     }
-    return run('Page inspect', async () => {
-        const waitMs = capWaitMs(opts.wait, url);
-        const parsedTimeout = parseInt(opts.waitTimeout, 10);
-        const waitForTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 0 ? parsedTimeout : 5000;
-        const truncate = opts.truncate !== false;
-        const showAll = opts.all === true;
-        const inspectBody = {
-            url, waitMs,
-            waitForSelector: opts.waitFor || undefined,
-            waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
-            fakeMedia: opts.fakeMedia || undefined,
-            device: opts.device ? resolveTouchDevice(opts.device) : undefined,
-            auth: opts.auth || undefined,
-        };
-        const res = await post(`/tools/browser/inspect`, inspectBody);
-        const b = res.data;
-        // ── Move resource-load failures out of the console, where they're noise ──
-        // A sub-resource that returns an HTTP 4xx/5xx is reported twice: once in
-        // `failedResources` (CDP network layer — carries the full URL, method, and
-        // status) and once as a generic, URL-less console echo ("Failed to load
-        // resource: the server responded with a status of 404 ()"). The echo names
-        // nothing, so it can't be triaged on its own and only duplicates — worse —
-        // what `failedResources` already says with a URL. Drop one echo per failed
-        // resource we actually have, so every attributed failure (a real app 404 AND
-        // the platform's own injected-SDK telemetry-beacon 404, which 404s on
-        // essentially every deployed page) is surfaced exactly once, under Failed
-        // resources, with its URL — never as a bare, unattributable console line.
-        // Count BEFORE stripping the platform log endpoints below, so their echoes go
-        // too. Any SURPLUS echo (a failure the network drain missed, leaving
-        // failedResources short) is KEPT — a real problem is never hidden just because
-        // we couldn't name it.
-        const isPlatformLog = (entry) => {
-            const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
-            try {
-                const u = new URL(urlPart);
-                return /(^|\.)gipity\.ai$/.test(u.hostname) && /\/log\/(traffic|error)$/.test(u.pathname);
-            }
-            catch {
-                return false;
-            }
-        };
-        let resourceEchoesToDrop = (b.failedResources || []).length;
-        if (resourceEchoesToDrop > 0) {
-            const isHttpStatusResourceError = (l) => /^error:\s*Failed to load resource: the server responded with a status of \d{3}/i.test(l);
-            b.console = (b.console || []).filter((l) => {
-                if (resourceEchoesToDrop > 0 && isHttpStatusResourceError(l)) {
-                    resourceEchoesToDrop--;
-                    return false;
-                }
-                return true;
-            });
+    return run('Page inspect', () => inspectPage(url, opts));
+});
+/** Run the full inspect pipeline (probe, transient-error re-probe, noise
+ *  filtering) against a URL and print the report. Shared by `page inspect`
+ *  and `deploy --inspect`, so a build agent can deploy + verify in ONE
+ *  command instead of two round trips through the model. */
+export async function inspectPage(url, opts = {}) {
+    const waitMs = capWaitMs(opts.wait ?? '500', url);
+    const parsedTimeout = parseInt(opts.waitTimeout ?? '5000', 10);
+    const waitForTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 0 ? parsedTimeout : 5000;
+    const truncate = opts.truncate !== false;
+    const showAll = opts.all === true;
+    const inspectBody = {
+        url, waitMs,
+        waitForSelector: opts.waitFor || undefined,
+        waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
+        fakeMedia: opts.fakeMedia || undefined,
+        device: opts.device ? resolveTouchDevice(opts.device) : undefined,
+        auth: opts.auth || undefined,
+    };
+    const res = await post(`/tools/browser/inspect`, inspectBody);
+    const b = res.data;
+    // ── Move resource-load failures out of the console, where they're noise ──
+    // A sub-resource that returns an HTTP 4xx/5xx is reported twice: once in
+    // `failedResources` (CDP network layer — carries the full URL, method, and
+    // status) and once as a generic, URL-less console echo ("Failed to load
+    // resource: the server responded with a status of 404 ()"). The echo names
+    // nothing, so it can't be triaged on its own and only duplicates — worse —
+    // what `failedResources` already says with a URL. Drop one echo per failed
+    // resource we actually have, so every attributed failure (a real app 404 AND
+    // the platform's own injected-SDK telemetry-beacon 404, which 404s on
+    // essentially every deployed page) is surfaced exactly once, under Failed
+    // resources, with its URL — never as a bare, unattributable console line.
+    // Count BEFORE stripping the platform log endpoints below, so their echoes go
+    // too. Any SURPLUS echo (a failure the network drain missed, leaving
+    // failedResources short) is KEPT — a real problem is never hidden just because
+    // we couldn't name it.
+    const isPlatformLog = (entry) => {
+        const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
+        try {
+            const u = new URL(urlPart);
+            return /(^|\.)gipity\.ai$/.test(u.hostname) && /\/log\/(traffic|error)$/.test(u.pathname);
         }
-        // The injected analytics SDK POSTs to `/log/{traffic,error}` on the Gipity
-        // host; a failure there is platform infrastructure, not the app's, so strip it
-        // from the failed-resource list entirely (its console echo is already gone,
-        // dropped above with every other attributed failure).
-        b.failedResources = (b.failedResources || []).filter((r) => !isPlatformLog(r));
-        // Pull message-less cross-origin "Script error." lines out first. They carry
-        // no source/stack, so they're never actionable as app-code defects, and on a
-        // Gipity-deployed page the platform's own injected SDK is itself a
-        // cross-origin script — so these are reported separately (not as app console
-        // errors, and not folded into the re-probe count) instead of misleading the
-        // agent into chasing its own code.
-        const crossOriginErrors = (b.console || []).filter(isMessagelessCrossOrigin);
-        b.console = (b.console || []).filter((l) => !isMessagelessCrossOrigin(l));
-        // Self-verify the remaining console errors before flagging them. A
-        // freshly-deployed page's first hit can throw a one-time, non-reproducible
-        // error from an asset still propagating — and reporting it as a real defect
-        // sends agents chasing a phantom. So when the first probe reports error-level
-        // console lines, re-probe once (the sticky session is now warm) and keep only
-        // the errors that recur; errors seen on a single probe are surfaced
-        // separately as transient noise.
-        let transientErrors = [];
-        if ((b.console || []).some(isErrorLine)) {
-            try {
-                const verify = await post(`/tools/browser/inspect`, inspectBody);
-                const recurring = new Set((verify.data.console || []).filter(isErrorLine));
-                transientErrors = (b.console || []).filter((l) => isErrorLine(l) && !recurring.has(l));
-                b.console = (b.console || []).filter((l) => !isErrorLine(l) || recurring.has(l));
-            }
-            catch {
-                // Re-probe failed (timeout / browser error) — report the first probe's
-                // console as-is rather than hiding anything.
-            }
+        catch {
+            return false;
         }
-        if (opts.json) {
-            console.log(JSON.stringify({
-                ...b,
-                ...(transientErrors.length ? { transientConsole: transientErrors } : {}),
-                ...(crossOriginErrors.length ? { crossOriginConsole: crossOriginErrors } : {}),
-            }));
-            return;
+    };
+    let resourceEchoesToDrop = (b.failedResources || []).length;
+    if (resourceEchoesToDrop > 0) {
+        const isHttpStatusResourceError = (l) => /^error:\s*Failed to load resource: the server responded with a status of \d{3}/i.test(l);
+        b.console = (b.console || []).filter((l) => {
+            if (resourceEchoesToDrop > 0 && isHttpStatusResourceError(l)) {
+                resourceEchoesToDrop--;
+                return false;
+            }
+            return true;
+        });
+    }
+    // The injected analytics SDK POSTs to `/log/{traffic,error}` on the Gipity
+    // host; a failure there is platform infrastructure, not the app's, so strip it
+    // from the failed-resource list entirely (its console echo is already gone,
+    // dropped above with every other attributed failure).
+    b.failedResources = (b.failedResources || []).filter((r) => !isPlatformLog(r));
+    // Pull message-less cross-origin "Script error." lines out first. They carry
+    // no source/stack, so they're never actionable as app-code defects, and on a
+    // Gipity-deployed page the platform's own injected SDK is itself a
+    // cross-origin script — so these are reported separately (not as app console
+    // errors, and not folded into the re-probe count) instead of misleading the
+    // agent into chasing its own code.
+    const crossOriginErrors = (b.console || []).filter(isMessagelessCrossOrigin);
+    b.console = (b.console || []).filter((l) => !isMessagelessCrossOrigin(l));
+    // Self-verify the remaining console errors before flagging them. A
+    // freshly-deployed page's first hit can throw a one-time, non-reproducible
+    // error from an asset still propagating — and reporting it as a real defect
+    // sends agents chasing a phantom. So when the first probe reports error-level
+    // console lines, re-probe once (the sticky session is now warm) and keep only
+    // the errors that recur; errors seen on a single probe are surfaced
+    // separately as transient noise.
+    let transientErrors = [];
+    if (opts.reprobe !== false && (b.console || []).some(isErrorLine)) {
+        try {
+            const verify = await post(`/tools/browser/inspect`, inspectBody);
+            const recurring = new Set((verify.data.console || []).filter(isErrorLine));
+            transientErrors = (b.console || []).filter((l) => isErrorLine(l) && !recurring.has(l));
+            b.console = (b.console || []).filter((l) => !isErrorLine(l) || recurring.has(l));
         }
-        const timing = b.timing || { ttfb: 0, domReady: 0, load: 0 };
-        // ── Page Info ──
-        console.log(`${brand('Inspecting')} ${bold(b.url || url)}`);
-        if (b.navigationIncomplete) {
-            console.log(`${warning('⚠ Navigation incomplete:')} ${b.note || 'page did not reach full load'}`);
+        catch {
+            // Re-probe failed (timeout / browser error) — report the first probe's
+            // console as-is rather than hiding anything.
         }
-        console.log(`${muted('Title:')} ${b.title || '(none)'}`);
-        console.log(`${muted('Elements:')} ${b.elementCount || 0}`);
-        console.log(`${muted('Page weight:')} ${info(formatSize(b.totalBytes || 0))}`);
-        // ── Timing ──
-        console.log(`\n${bold('Timing:')}`);
-        console.log(`${muted('TTFB:')} ${timing.ttfb}ms`);
-        console.log(`${muted('DOM ready:')} ${timing.domReady}ms`);
-        console.log(`${muted('Load:')} ${timing.load}ms`);
-        if (showAll && b.lcp) {
-            console.log(`LCP: ${b.lcp.time}ms (${b.lcp.element}${b.lcp.url ? ' ' + shortUrl(b.lcp.url, truncate) : ''})`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ...b,
+            ...(transientErrors.length ? { transientConsole: transientErrors } : {}),
+            ...(crossOriginErrors.length ? { crossOriginConsole: crossOriginErrors } : {}),
+        }));
+        return;
+    }
+    const timing = b.timing || { ttfb: 0, domReady: 0, load: 0 };
+    // ── Page Info ──
+    console.log(`${brand('Inspecting')} ${bold(b.url || url)}`);
+    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".
+    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)')}`);
+    }
+    console.log(`${muted('Title:')} ${b.title || '(none)'}`);
+    console.log(`${muted('Elements:')} ${b.elementCount || 0}`);
+    console.log(`${muted('Page weight:')} ${info(formatSize(b.totalBytes || 0))}`);
+    // ── Timing ──
+    console.log(`\n${bold('Timing:')}`);
+    console.log(`${muted('TTFB:')} ${timing.ttfb}ms`);
+    console.log(`${muted('DOM ready:')} ${timing.domReady}ms`);
+    console.log(`${muted('Load:')} ${timing.load}ms`);
+    if (showAll && b.lcp) {
+        console.log(`LCP: ${b.lcp.time}ms (${b.lcp.element}${b.lcp.url ? ' ' + shortUrl(b.lcp.url, truncate) : ''})`);
+    }
+    // ── Console ──
+    if (b.console?.length > 0) {
+        console.log(`\n${bold('Console')} ${muted(`(${b.console.length})`)}:`);
+        for (const line of b.console) {
+            console.log(`${warning(line)}`);
         }
-        // ── Console ──
-        if (b.console?.length > 0) {
-            console.log(`\n${bold('Console')} ${muted(`(${b.console.length})`)}:`);
-            for (const line of b.console) {
-                console.log(`${warning(line)}`);
-            }
+    }
+    else {
+        console.log(`\n${bold('Console:')} ${muted('(clean)')}`);
+    }
+    // ── Transient console errors (seen on first probe, gone on re-probe) ──
+    if (transientErrors.length > 0) {
+        console.log(`\n${bold('Transient console errors')} ${muted(`(${transientErrors.length}, not reproduced on re-probe)`)}:`);
+        for (const line of transientErrors) {
+            console.log(muted(line));
         }
-        else {
-            console.log(`\n${bold('Console:')} ${muted('(clean)')}`);
+        console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets) — not reproducible, not in your app code. Ignore unless it recurs.'));
+    }
+    // ── Cross-origin console errors (message-less; source hidden by the browser) ──
+    if (crossOriginErrors.length > 0) {
+        console.log(`\n${bold('Cross-origin console errors')} ${muted(`(${crossOriginErrors.length}, source hidden by the browser)`)}:`);
+        console.log(muted("Message-less — the throwing <script> lacks CORS, so the browser hides its source and there's no own-code stack to chase. Gipity's injected SDK is itself cross-origin, so if your app loads no third-party CDN scripts these are platform noise — ignore them. If your app DOES load a third-party <script>, add crossorigin=\"anonymous\" to that tag to surface the real error."));
+    }
+    // ── Failed Resources ──
+    // Browsers auto-request /favicon.ico at the site root for every page, so a
+    // 404 there isn't a resource the page actually links — it's noise on any
+    // app served under a subpath. Split that implicit request out of the failure
+    // list into a harmless note rather than flagging it as an error.
+    const isImplicitFavicon = (entry) => {
+        const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
+        try {
+            return new URL(urlPart).pathname === '/favicon.ico';
         }
-        // ── Transient console errors (seen on first probe, gone on re-probe) ──
-        if (transientErrors.length > 0) {
-            console.log(`\n${bold('Transient console errors')} ${muted(`(${transientErrors.length}, not reproduced on re-probe)`)}:`);
-            for (const line of transientErrors) {
-                console.log(muted(line));
-            }
-            console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets) — not reproducible, not in your app code. Ignore unless it recurs.'));
+        catch {
+            return false;
         }
-        // ── Cross-origin console errors (message-less; source hidden by the browser) ──
-        if (crossOriginErrors.length > 0) {
-            console.log(`\n${bold('Cross-origin console errors')} ${muted(`(${crossOriginErrors.length}, source hidden by the browser)`)}:`);
-            console.log(muted("Message-less — the throwing <script> lacks CORS, so the browser hides its source and there's no own-code stack to chase. Gipity's injected SDK is itself cross-origin, so if your app loads no third-party CDN scripts these are platform noise — ignore them. If your app DOES load a third-party <script>, add crossorigin=\"anonymous\" to that tag to surface the real error."));
+    };
+    const failed = (b.failedResources || []).filter((r) => !isImplicitFavicon(r));
+    const rootFaviconMissing = (b.failedResources || []).some(isImplicitFavicon);
+    if (failed.length > 0) {
+        console.log(`\n${clrError(`Failed resources (${failed.length}):`)}`);
+        for (const r of failed) {
+            console.log(`${clrError(r)}`);
         }
-        // ── Failed Resources ──
-        // Browsers auto-request /favicon.ico at the site root for every page, so a
-        // 404 there isn't a resource the page actually links — it's noise on any
-        // app served under a subpath. Split that implicit request out of the failure
-        // list into a harmless note rather than flagging it as an error.
-        const isImplicitFavicon = (entry) => {
-            const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
-            try {
-                return new URL(urlPart).pathname === '/favicon.ico';
-            }
-            catch {
-                return false;
+    }
+    if (rootFaviconMissing) {
+        console.log(`\n${muted('No root /favicon.ico (browsers request this automatically; harmless for app pages served under a subpath)')}`);
+    }
+    // ── Layout (horizontal overflow) ──
+    if (b.overflow) {
+        if (b.overflow.overflowX) {
+            console.log(`\n${clrError(`Horizontal overflow: +${b.overflow.amount}px`)} ${muted(`(content ${b.overflow.scrollWidth}px vs viewport ${b.overflow.clientWidth}px)`)}`);
+            if (showAll && b.overflow.culprits.length > 0) {
+                console.log(`${muted('Overflowing elements:')}`);
+                for (const c of b.overflow.culprits) {
+                    const sel = c.cls ? `${c.tag}.${c.cls.split(/\s+/)[0]}` : c.tag;
+                    console.log(`${sel} ${muted(`(right ${c.right}px, width ${c.width}px)`)}`);
+                }
             }
-        };
-        const failed = (b.failedResources || []).filter((r) => !isImplicitFavicon(r));
-        const rootFaviconMissing = (b.failedResources || []).some(isImplicitFavicon);
-        if (failed.length > 0) {
-            console.log(`\n${clrError(`Failed resources (${failed.length}):`)}`);
-            for (const r of failed) {
-                console.log(`${clrError(r)}`);
+            else if (b.overflow.culprits.length > 0) {
+                console.log(`${muted(`${b.overflow.culprits.length} overflowing element(s) - use --all to list`)}`);
             }
         }
-        if (rootFaviconMissing) {
-            console.log(`\n${muted('No root /favicon.ico (browsers request this automatically; harmless for app pages served under a subpath)')}`);
+        else {
+            console.log(`\n${bold('Layout:')} ${muted('no horizontal overflow')}`);
         }
-        // ── Layout (horizontal overflow) ──
-        if (b.overflow) {
-            if (b.overflow.overflowX) {
-                console.log(`\n${clrError(`Horizontal overflow: +${b.overflow.amount}px`)} ${muted(`(content ${b.overflow.scrollWidth}px vs viewport ${b.overflow.clientWidth}px)`)}`);
-                if (showAll && b.overflow.culprits.length > 0) {
-                    console.log(`${muted('Overflowing elements:')}`);
-                    for (const c of b.overflow.culprits) {
-                        const sel = c.cls ? `${c.tag}.${c.cls.split(/\s+/)[0]}` : c.tag;
-                        console.log(`${sel} ${muted(`(right ${c.right}px, width ${c.width}px)`)}`);
-                    }
-                }
-                else if (b.overflow.culprits.length > 0) {
-                    console.log(`${muted(`${b.overflow.culprits.length} overflowing element(s) - use --all to list`)}`);
-                }
-            }
-            else {
-                console.log(`\n${bold('Layout:')} ${muted('no horizontal overflow')}`);
+    }
+    if (showAll) {
+        // ── Render Blocking ──
+        if (b.renderBlocking?.length > 0) {
+            console.log(`\n${warning(`Render-blocking (${b.renderBlocking.length}):`)}`);
+            for (const r of b.renderBlocking) {
+                console.log(`${shortUrl(r, truncate)}`);
             }
         }
-        if (showAll) {
-            // ── Render Blocking ──
-            if (b.renderBlocking?.length > 0) {
-                console.log(`\n${warning(`Render-blocking (${b.renderBlocking.length}):`)}`);
-                for (const r of b.renderBlocking) {
-                    console.log(`${shortUrl(r, truncate)}`);
-                }
-            }
-            // ── Large Resources ──
-            if (b.largeResources?.length > 0) {
-                console.log(`\n${warning(`Large resources >100KB (${b.largeResources.length}):`)}`);
-                for (const r of b.largeResources) {
-                    console.log(`${info(formatSize(r.size).padEnd(10))} ${muted(r.type.padEnd(8))} ${shortUrl(r.url, truncate)}`);
-                }
+        // ── Large Resources ──
+        if (b.largeResources?.length > 0) {
+            console.log(`\n${warning(`Large resources >100KB (${b.largeResources.length}):`)}`);
+            for (const r of b.largeResources) {
+                console.log(`${info(formatSize(r.size).padEnd(10))} ${muted(r.type.padEnd(8))} ${shortUrl(r.url, truncate)}`);
             }
-            // ── Oversized Images ──
-            if (b.oversizedImages?.length > 0) {
-                console.log(`\n${warning(`Oversized images (${b.oversizedImages.length}):`)}`);
-                for (const img of b.oversizedImages) {
-                    console.log(`${img.natural} served, ${img.displayed} displayed - ${shortUrl(img.src, truncate)}`);
-                }
+        }
+        // ── Oversized Images ──
+        if (b.oversizedImages?.length > 0) {
+            console.log(`\n${warning(`Oversized images (${b.oversizedImages.length}):`)}`);
+            for (const img of b.oversizedImages) {
+                console.log(`${img.natural} served, ${img.displayed} displayed - ${shortUrl(img.src, truncate)}`);
             }
         }
-    });
-});
+    }
+}
 //# sourceMappingURL=page-inspect.js.map

package/dist/commands/page-screenshot.js

@@ -3,7 +3,8 @@ import { mkdirSync, writeFileSync } from 'fs';
 import { dirname, join, resolve as resolvePath } from 'path';
 import { postForTarEntries } from '../api.js';
 import { getProjectRoot } from '../config.js';
-import { brand, bold, muted, success } from '../colors.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';
@@ -28,6 +29,25 @@ 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". */
+function printAuthLine(auth) {
+    if (!auth?.requested)
+        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
+ *  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) {
+    if (!actionError)
+        return;
+    console.log(`${warning('⚠ --action failed:')} ${actionError} ${muted('(this image shows the page BEFORE the action ran)')}`);
+}
 function fmtPerformance(p) {
     const parts = [
         `TTFB ${fmtMs(p.ttfb)}`,
@@ -137,7 +157,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     // 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)')
-    .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs after the post-load delay, then settles again before the shot.')
+    .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, [])
@@ -223,6 +243,7 @@ export const pageScreenshotCommand = new Command('screenshot')
                 final_url: meta.finalUrl,
                 status: meta.status,
                 performance: meta.performance,
+                ...(meta.auth ? { auth: meta.auth } : {}),
             },
             screenshots: meta.screenshots.map((s, i) => ({
                 file: savedFiles[i],
@@ -253,6 +274,8 @@ export const pageScreenshotCommand = new Command('screenshot')
             console.log(`${label('Web page status')} ${meta.status}`);
         if (meta.performance)
             console.log(`${label('Web page perf')} ${fmtPerformance(meta.performance)}`);
+        printAuthLine(meta.auth);
+        printActionErrorLine(meta.actionError);
         if (s.viewport.device)
             console.log(`${label('Emulated device')} ${s.viewport.device} ${muted('(touch events, mobile user-agent)')}`);
         const sizePart = formatSize(s.screenshotSizeBytes) + (meta.full ? ' (full page)' : '');
@@ -271,6 +294,8 @@ export const pageScreenshotCommand = new Command('screenshot')
         console.log(`${label('Web page status')} ${meta.status}`);
     if (meta.performance)
         console.log(`${label('Web page perf')} ${fmtPerformance(meta.performance)}`);
+    printAuthLine(meta.auth);
+    printActionErrorLine(meta.actionError);
     for (let i = 0; i < meta.screenshots.length; i++) {
         const s = meta.screenshots[i];
         const dims = `${s.viewport.width}×${s.viewport.height}${s.viewport.deviceScaleFactor > 1 ? ` @${s.viewport.deviceScaleFactor}x` : ''}`;

package/dist/commands/page.js

@@ -10,7 +10,7 @@ import { pageFetchCommand } from './page-fetch.js';
 // top-level surface lean and makes the siblings discoverable via `page --help`.
 // `inspect` is the rendered DOM (browser); `fetch` is the raw asset (plain HTTP).
 export const pageCommand = new Command('page')
-    .description('Inspect web pages')
+    .description('Inspect, drive, and test web pages in a real browser (page test = N concurrent clients for realtime/presence verification)')
     .addCommand(pageInspectCommand)
     .addCommand(pageEvalCommand)
     .addCommand(pageScreenshotCommand)

package/dist/commands/push.js

@@ -3,13 +3,13 @@ import { resolve } from 'path';
 import { pushFile } from '../sync.js';
 import { error as clrError, success } from '../colors.js';
 export const pushCommand = new Command('push')
-    .description('Push a file')
-    .argument('<file>', 'File path to push')
+    .description('Push one or more files')
+    .argument('<files...>', 'File path(s) to push')
     .option('--quiet', 'Suppress output')
     .option('--background', 'Fork and exit immediately')
-    .action(async (file, opts) => {
+    .action(async (files, opts) => {
     try {
-        const fullPath = resolve(file);
+        const fullPaths = files.map(f => resolve(f));
         if (opts.background) {
             // Detach a background `gipity push` and exit immediately. Goes through
             // spawnCommand (Node binary running our own entry script - no IPC
@@ -17,16 +17,21 @@ export const pushCommand = new Command('push')
             // `windowsHide: true` so the detached child never flashes a console
             // window on Windows.
             const { spawnCommand } = await import('../platform.js');
-            const child = spawnCommand(process.execPath, [process.argv[1], 'push', fullPath, '--quiet'], {
+            const child = spawnCommand(process.execPath, [process.argv[1], 'push', ...fullPaths, '--quiet'], {
                 detached: true,
                 stdio: 'ignore',
             });
             child.unref();
             return;
         }
-        await pushFile(fullPath);
+        // Sequential on purpose: pushFile takes the per-project sync lock, so
+        // parallel pushes would just contend on it. One process pushing N files
+        // still beats the old N processes × N lock acquisitions.
+        for (const fullPath of fullPaths) {
+            await pushFile(fullPath);
+        }
         if (!opts.quiet) {
-            console.log(success(`Pushed ${file}`));
+            console.log(success(files.length === 1 ? `Pushed ${files[0]}` : `Pushed ${files.length} files`));
         }
     }
     catch (err) {