browser-debugger-cli 0.9.0 → 0.10.0

package/dist/commands/dom/helpers/screenshot.js

@@ -138,11 +138,32 @@ async function restoreScrollPosition(position) {
         returnByValue: true,
     });
 }
+/**
+ * The window's size with its scrollbars (`innerWidth`/`innerHeight`): an
+ * override at this size keeps the page's layout, where the visible size
+ * (without scrollbars) would narrow it and move centered content.
+ *
+ * @param viewport - Visible viewport size, used when the page does not answer
+ * @returns Width and height in CSS px
+ */
+async function windowSize(viewport) {
+    const response = await callCDP('Runtime.evaluate', {
+        expression: '[window.innerWidth, window.innerHeight]',
+        returnByValue: true,
+    });
+    const value = response.data?.result?.result?.value;
+    const [width, height] = Array.isArray(value) ? value : [];
+    return {
+        width: Math.round(width ?? viewport.clientWidth),
+        height: Math.round(height ?? viewport.clientHeight),
+    };
+}
 /**
  * Capture at a pixel ratio of 1 (CSS px = image px) on a high-DPI display:
- * the viewport is overridden at its size (the session's `--viewport`, else
- * the visible one) until the returned function puts back what was there
- * before, the session's viewport or none.
+ * the viewport is overridden at the window's size (the session's
+ * `--viewport`, else the window with its scrollbars, so the layout does not
+ * change) until the returned function puts back what was there before, the
+ * session's viewport or none.
  *
  * @param devicePixelRatio - Page's pixel ratio
  * @param viewport - Visible viewport size
@@ -152,10 +173,7 @@ async function useUnitPixelRatio(devicePixelRatio, viewport) {
     if (devicePixelRatio === 1)
         return () => Promise.resolve();
     const sessionViewport = readSessionMetadata()?.viewport;
-    const size = sessionViewport ?? {
-        width: Math.round(viewport.clientWidth),
-        height: Math.round(viewport.clientHeight),
-    };
+    const size = sessionViewport ?? (await windowSize(viewport));
     await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
     return async () => {
         if (sessionViewport) {
@@ -350,6 +368,53 @@ const CONTENT_OVERFLOW_JS = `function () {
   if (!clips(view.getComputedStyle(this))) walk(this);
   return { left: own.left - reach.left, top: own.top - reach.top, right: reach.right - own.right, bottom: reach.bottom - own.bottom };
 }`;
+/**
+ * The visible viewport (without scrollbars) in CSS px.
+ *
+ * @returns Width and height
+ */
+async function visibleViewport() {
+    const metrics = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
+    const view = metrics?.cssVisualViewport ?? metrics?.visualViewport;
+    return { width: view?.clientWidth ?? 0, height: view?.clientHeight ?? 0 };
+}
+/**
+ * Whether an area (viewport coordinates) lies inside the viewport.
+ *
+ * @param area - Area
+ * @param view - Viewport size
+ * @returns True when fully inside
+ */
+function insideView(area, view) {
+    return (area.x >= 0 &&
+        area.y >= 0 &&
+        area.x + area.width <= view.width &&
+        area.y + area.height <= view.height);
+}
+/**
+ * Measure the area to capture and, when it fits in the viewport but is not
+ * in view, scroll it to the middle first. A capture inside the viewport
+ * keeps the page as it is; one beyond it makes Chrome lay the page out
+ * without its scrollbar, which moves centered content by half the
+ * scrollbar's width, so it is used only for areas larger than the viewport.
+ *
+ * @param ref - Node reference
+ * @returns Border box, area to capture (viewport coordinates) and whether it is in view
+ */
+async function measureInView(ref) {
+    const view = await visibleViewport();
+    let box = await getElementBounds(ref);
+    let bounds = await captureArea(ref, box);
+    const fits = bounds.width <= view.width && bounds.height <= view.height;
+    if (fits && !insideView(bounds, view)) {
+        const dx = bounds.x + bounds.width / 2 - view.width / 2;
+        const dy = bounds.y + bounds.height / 2 - view.height / 2;
+        await callCDP('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+        box = await getElementBounds(ref);
+        bounds = await captureArea(ref, box);
+    }
+    return { box, bounds, inView: insideView(bounds, view) };
+}
 /** Overflow (px) below which the capture keeps to the border box (subpixel rounding) */
 const OVERFLOW_SLACK = 1;
 /**
@@ -403,8 +468,6 @@ async function captureArea(ref, bounds) {
  * (the reported bounds are page coordinates, like `dom layout`'s).
  */
 export async function captureElementScreenshot(outputPath, ref, options = {}) {
-    const box = await getElementBounds(ref);
-    const bounds = await captureArea(ref, box);
     const format = options.format ?? 'png';
     const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
     const noResize = options.noResize ?? false;
@@ -413,6 +476,18 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         returnByValue: true,
     });
     const devicePixelRatio = dprResponse.data?.result?.result?.value ?? 1;
+    const before = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
+    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, before?.visualViewport ?? { clientWidth: 800, clientHeight: 600 });
+    let box;
+    let bounds;
+    let inView;
+    try {
+        ({ box, bounds, inView } = await measureInView(ref));
+    }
+    catch (error) {
+        await restoreMetrics();
+        throw error;
+    }
     const originalWidth = bounds.width;
     const originalHeight = bounds.height;
     const resized = shouldResize(originalWidth, originalHeight, noResize);
@@ -421,7 +496,6 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const finalHeight = Math.round(originalHeight * scale);
     const metricsResponse = await callCDP('Page.getLayoutMetrics', {});
     const metricsResult = metricsResponse.data?.result;
-    const viewport = metricsResult?.visualViewport ?? { clientWidth: 800, clientHeight: 600 };
     const scroll = metricsResult?.cssLayoutViewport ?? { pageX: 0, pageY: 0 };
     const onPage = (area) => ({
         ...area,
@@ -429,14 +503,13 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         y: area.y + scroll.pageY,
     });
     const clip = onPage(bounds);
-    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     let screenshotResult;
     try {
         const screenshotResponse = await callCDP('Page.captureScreenshot', {
             format,
             ...(quality !== undefined && { quality }),
             clip: { ...clip, scale },
-            captureBeyondViewport: true,
+            captureBeyondViewport: !inView,
         });
         screenshotResult = screenshotResponse.data?.result;
     }

package/dist/commands/dom/index.d.ts

@@ -9,6 +9,7 @@
  * - `frames.ts` — list the page's iframes
  * - `listeners.ts` — list event listeners that run for an element
  * - `layout.ts` — positions, sizes and visibility of elements
+ * - `inspect.ts` — what one element looks like (styles, box, layout, child tree)
  * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.

package/dist/commands/dom/index.js

@@ -9,6 +9,7 @@
  * - `frames.ts` — list the page's iframes
  * - `listeners.ts` — list event listeners that run for an element
  * - `layout.ts` — positions, sizes and visibility of elements
+ * - `inspect.ts` — what one element looks like (styles, box, layout, child tree)
  * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.
@@ -20,11 +21,13 @@ import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
+import { registerInspectCommand } from './inspect.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
 import { handleDomQuery } from './query.js';
 import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
+import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
 import { integerOption, screenshotFormatOption } from '../shared/validation.js';
 /**
  * Register DOM telemetry commands on the root Commander program.
@@ -38,12 +41,14 @@ export function registerDomCommands(program) {
     registerFormCommand(dom);
     registerListenersCommand(dom);
     registerLayoutCommand(dom);
+    registerInspectCommand(dom);
     registerWaitCommand(dom);
     dom
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
         .option('-j, --json', 'Output as JSON')
+        .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {
         await handleDomQuery(selector, options);
     });
@@ -51,7 +56,7 @@ export function registerDomCommands(program) {
         .command('eval')
         .description('Evaluate JavaScript expression in the page context')
         .argument('<script>', 'JavaScript to execute (e.g., "document.title", "window.location.href")')
-        .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index, name/id attribute, or part of the name, id or URL (see dom frames)')
+        .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index (from dom frames; 87 when stale), name/id attribute, or part of the name, id or URL')
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -67,7 +72,7 @@ export function registerDomCommands(program) {
     });
     dom
         .command('frames')
-        .description("List the page's iframes (nested and cross-origin ones included) for eval --frame")
+        .description("List the page's iframes in document order (nested and cross-origin ones included) for eval --frame")
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         await handleDomFrames(options);
@@ -75,7 +80,7 @@ export function registerDomCommands(program) {
     dom
         .command('get')
         .description('Get semantic accessibility structure (default) or raw HTML (--raw)')
-        .argument('[selectorOrIndex]', `CSS selector or numeric index from query results (0-based; e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
+        .argument('[selectorOrIndex]', `${SELECTOR_OR_INDEX_ARGUMENT} (e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
         .option('--raw', 'Output raw HTML with all filtering options')
         .option('--full', 'Show all of the element text (default: the first 500 characters)')
         .option('--all', 'Get all matches (only with --raw)')

package/dist/commands/dom/inspect.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `bdg dom inspect <selector|index>` - what one element looks like, without a
+ * screenshot: its box, layout (and its place in the parent), typography with
+ * the rendered font and contrast, fills, borders, effects, CSS state,
+ * pseudo-elements and a compact child tree, as grouped lines (`--json`:
+ * Figma-aligned fields).
+ */
+import { type Command } from 'commander';
+/**
+ * Register `bdg dom inspect`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerInspectCommand(dom: Command): void;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/commands/dom/inspect.js

@@ -0,0 +1,82 @@
+/**
+ * `bdg dom inspect <selector|index>` - what one element looks like, without a
+ * screenshot: its box, layout (and its place in the parent), typography with
+ * the rendered font and contrast, fills, borders, effects, CSS state,
+ * pseudo-elements and a compact child tree, as grouped lines (`--json`:
+ * Figma-aligned fields).
+ */
+import { Option } from 'commander';
+import { runElementCommand } from './helpers/runElementCommand.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
+import { cssPropertiesOption, integerOption } from '../shared/validation.js';
+import { domInspect } from '../../ipc/client.js';
+import { DEFAULT_TREE_DEPTH, DEFAULT_TREE_LIMIT } from '../../runtime/dom/inspectTree.js';
+import { formatInspect } from '../../ui/formatters/inspect.js';
+import { INSPECT_OUTPUT_LEGEND } from '../../ui/messages/commands.js';
+import { filterDefined } from '../../utils/objects.js';
+/**
+ * Register `bdg dom inspect`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerInspectCommand(dom) {
+    dom
+        .command('inspect')
+        .description('What one element looks like without a screenshot: box, layout, font (rendered, contrast), colors, borders, effects, pseudo-elements and child tree')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
+        .option('--index <n>', 'Which match to inspect (0-based; default: the first rendered one)', integerOption(0))
+        .option('--tree <depth>', `Child tree depth (default ${DEFAULT_TREE_DEPTH}; 0 for none)`, integerOption(0, 10))
+        .option('--tree-limit <n>', `Child tree rows at most (default ${DEFAULT_TREE_LIMIT})`, integerOption(1, 500))
+        .addOption(new Option('--all', 'Every computed property that is not its default, collapsed into shorthands, instead of the groups').conflicts('props'))
+        .addHelpText('after', INSPECT_OUTPUT_LEGEND)
+        .option('--props <names>', "Only these properties, computed and normalized (comma-separated, e.g. padding,color,--brand; '--*' or '--bs-btn-*' lists custom properties)", cssPropertiesOption)
+        .addOption(new Option('--rules', 'Also show which CSS rule sets each shown property (selector, file:line, what it overrides); with --props, those properties').conflicts('all'))
+        .addOption(new Option('--why <property>', 'Every declaration of one property: the one that applies and those it overrides (e.g. --why color)')
+        .conflicts('all')
+        .argParser(propertyOption))
+        .option('--no-hints', 'Skip the check for declarations that have no effect')
+        .addOption(jsonOption())
+        .action(async (selectorOrIndex, options) => {
+        await runCommand(() => inspectTarget(selectorOrIndex, options), options, formatInspect);
+    });
+}
+/**
+ * Parse `--why`: a property name, lowercased (custom properties as given).
+ *
+ * @param value - Property name
+ * @returns Name
+ */
+function propertyOption(value) {
+    return value.startsWith('--') ? value.trim() : value.trim().toLowerCase();
+}
+/**
+ * Resolve the target and ask the daemon to inspect it.
+ *
+ * @param selectorOrIndex - CSS selector or cached query index
+ * @param options - Command options
+ * @returns Command result
+ */
+async function inspectTarget(selectorOrIndex, options) {
+    return runElementCommand({
+        selectorOrIndex,
+        index: options.index,
+        buildRequest: (target) => ({
+            ...target,
+            ...filterDefined({
+                tree: options.tree,
+                treeLimit: options.treeLimit,
+                all: options.all,
+                props: options.props,
+                rules: options.rules,
+                why: options.why,
+                ...(options.hints === false && { hints: false }),
+            }),
+        }),
+        call: domInspect,
+        command: 'inspect',
+        action: 'inspect the element',
+        failureSuggestion: 'Verify the selector matches an element: bdg dom query "<selector>"',
+    });
+}
+//# sourceMappingURL=inspect.js.map

package/dist/commands/dom/layout.js

@@ -7,7 +7,7 @@
 import { DomElementResolver } from './DomElementResolver.js';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { jsonOption } from '../shared/commonOptions.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
 import { domLayout } from '../../ipc/client.js';
 import { formatLayout } from '../../ui/formatters/layout.js';
@@ -20,7 +20,7 @@ export function registerLayoutCommand(dom) {
     dom
         .command('layout')
         .description('Positions, sizes and visibility of elements (above/below the fold, hidden, covered) without a screenshot')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Only this match of the selector (0-based)', integerOption(0))
         .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {

package/dist/commands/dom/listeners.js

@@ -13,7 +13,7 @@
 import { DomElementResolver } from './DomElementResolver.js';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { jsonOption } from '../shared/commonOptions.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
 import { eventTypesOption, integerOption } from '../shared/validation.js';
 import { domListeners } from '../../ipc/client.js';
 import { formatListeners } from '../../ui/formatters/listeners.js';
@@ -26,7 +26,7 @@ export function registerListenersCommand(dom) {
     dom
         .command('listeners')
         .description('List event listeners that run for an element (incl. delegated ones on ancestors)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--type <types>', 'Only these event types (comma-separated, e.g. click,keydown; repeatable)', eventTypesOption)
         .option('--all', 'List every listener of framework roots (React) instead of one line per node')

package/dist/commands/dom/semanticUtils.d.ts

@@ -17,7 +17,9 @@ export interface SemanticNodeWithContext {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
- * The role line is followed by up to 500 characters of the element's text
+ * The role line names the element's key attributes (an image's file name, a
+ * link's href, a field's type and name), like `dom query` does, and is
+ * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
  * preview, or, for an element without text or name, what it holds.
  *
@@ -34,4 +36,15 @@ export declare function formatSemanticNodeWithContext(data: SemanticNodeWithCont
  * @param nodeId - CDP nodeId for synthesis
  */
 export declare function resolveNodeWithFallback(a11yNode: A11yNode | null, domContext: DomContext | null, nodeId: number | undefined): A11yNode | null;
+/**
+ * The accessibility node with its value masked when the element holds a
+ * secret (`domContext.sensitive`): Chrome reports a password field's value
+ * as one bullet per character, and a field switched to text by a "show
+ * password" button in clear.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context of the same element
+ * @returns The node, with {@link MASKED_VALUE} as its value for a secret
+ */
+export declare function withSecretMasked(node: A11yNode, domContext: DomContext | null): A11yNode;
 //# sourceMappingURL=semanticUtils.d.ts.map

package/dist/commands/dom/semanticUtils.js

@@ -5,7 +5,9 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
+import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
+import { keyAttributeItems } from '../../ui/formatters/keyAttributes.js';
 import { joinLines } from '../../ui/formatting.js';
 import { elementTextLine, emptyElementLine } from '../../ui/messages/commands.js';
 function capitalize(str) {
@@ -35,6 +37,27 @@ function buildContextText(node, domContext) {
     }
     return '';
 }
+/**
+ * Key attributes of the element (src, href, a field's type and name, ...),
+ * leaving out what the role line already shows: values equal to the
+ * accessible name (an image's alt, a field's placeholder) and the value
+ * when the accessibility node has one.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context with the key attributes
+ * @returns ` src="…/logo.png"`-style text, or empty
+ */
+function buildKeyAttributesText(node, domContext) {
+    if (!domContext?.attributes)
+        return '';
+    const shown = Object.entries(domContext.attributes)
+        .filter(([, value]) => Boolean(node.name) && value === node.name)
+        .map(([name]) => name);
+    if (node.value !== undefined && node.value !== '')
+        shown.push('value');
+    const items = keyAttributeItems(domContext.tag, domContext.attributes, new Set(shown));
+    return items.length > 0 ? ` ${items.join(' ')}` : '';
+}
 function buildPropertiesText(node) {
     const props = [];
     if (node.value !== undefined && node.value !== '')
@@ -59,7 +82,9 @@ function buildPropertiesText(node) {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
- * The role line is followed by up to 500 characters of the element's text
+ * The role line names the element's key attributes (an image's file name, a
+ * link's href, a field's type and name), like `dom query` does, and is
+ * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
  * preview, or, for an element without text or name, what it holds.
  *
@@ -70,9 +95,10 @@ export function formatSemanticNodeWithContext(data) {
     const { node, domContext } = data;
     const roleText = buildRoleText(node);
     const contextText = buildContextText(node, domContext);
+    const keysText = buildKeyAttributesText(node, domContext);
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
-    const line = `${roleText}${contextText}${propsText}${inferredText}`;
+    const line = `${roleText}${contextText}${keysText}${propsText}${inferredText}`;
     if (domContext?.text)
         return joinLines(line, elementTextLine(domContext.text));
     if (domContext?.childCount !== undefined && !node.name) {
@@ -90,9 +116,24 @@ export function formatSemanticNodeWithContext(data) {
  */
 export function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
     if (a11yNode)
-        return a11yNode;
+        return withSecretMasked(a11yNode, domContext);
     if (domContext && nodeId)
         return synthesizeA11yNode(domContext, nodeId);
     return null;
 }
+/**
+ * The accessibility node with its value masked when the element holds a
+ * secret (`domContext.sensitive`): Chrome reports a password field's value
+ * as one bullet per character, and a field switched to text by a "show
+ * password" button in clear.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context of the same element
+ * @returns The node, with {@link MASKED_VALUE} as its value for a secret
+ */
+export function withSecretMasked(node, domContext) {
+    if (!domContext?.sensitive || !node.value)
+        return node;
+    return { ...node, value: MASKED_VALUE };
+}
 //# sourceMappingURL=semanticUtils.js.map

package/dist/commands/network/list.js

@@ -13,7 +13,7 @@ import { applyFilters, getFilterHelpText, validateFilterString } from '../../tel
 import { resolvePreset, FILTER_PRESETS } from '../../telemetry/filterPresets.js';
 import { filterByResourceType } from '../../telemetry/filters.js';
 import { buildSuccessResponse } from '../../ui/OutputBuilder.js';
-import { formatNetworkFollowRows, formatNetworkList, } from '../../ui/formatters/networkList.js';
+import { formatNetworkFollowRows, formatNetworkList, pageStartOf, } from '../../ui/formatters/networkList.js';
 import { followingNetworkMessage, stoppedFollowingNetworkMessage, } from '../../ui/messages/networkMessages.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { validateFilterOption } from './shared.js';
@@ -110,6 +110,7 @@ function buildFormatOptions(options, result, lastLimit) {
         last: lastLimit,
         totalCount: result.totalCount,
         filteredCount: result.filteredCount,
+        ...(result.pageStart && { pageStart: result.pageStart }),
     };
 }
 /**
@@ -148,9 +149,11 @@ async function runFollowMode(options, resourceTypes, lastN) {
             }
         }
         else {
+            const pageStart = pageStartOf(result.data);
             const text = formatNetworkFollowRows(fresh, {
                 header: !started,
                 verbose: options.verbose ?? false,
+                ...(pageStart && { pageStart }),
             });
             if (text)
                 console.log(text);
@@ -164,6 +167,12 @@ async function runFollowMode(options, resourceTypes, lastN) {
         intervalMs: FOLLOW_INTERVAL,
     });
 }
+/** What the less obvious columns of the list mean */
+const COLUMNS_HELP = `Columns:
+  START  When the request started, from the start of the current page (its document
+         request): +1.2s. Requests of earlier pages are negative. --json has the
+         absolute time (timestamp, epoch ms) and data.pageStart.
+  TIME   How long it took (to its last byte or failure); - while pending`;
 function formatPresetHelp() {
     return Object.entries(FILTER_PRESETS)
         .map(([name, preset]) => `  ${name.padEnd(12)} ${preset.description}`)
@@ -180,7 +189,7 @@ export function registerListCommand(networkCmd) {
         .addOption(networkLastOption)
         .addOption(new Option('-f, --follow', 'Stream network requests in real-time').default(false))
         .addOption(new Option('-v, --verbose', 'Show full URLs and additional details').default(false))
-        .addHelpText('after', `\n${getFilterHelpText()}\n\nPresets:\n${formatPresetHelp()}`)
+        .addHelpText('after', `\n${COLUMNS_HELP}\n\n${getFilterHelpText()}\n\nPresets:\n${formatPresetHelp()}`)
         .action(async (options) => {
         let resourceTypes;
         let lastN;
@@ -211,12 +220,14 @@ export function registerListCommand(networkCmd) {
                 return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
             const filtered = filterRequests(result.data, options, resourceTypes);
+            const pageStart = pageStartOf(result.data);
             return {
                 success: true,
                 data: {
                     requests: lastN === 0 ? filtered : filtered.slice(-lastN),
                     totalCount: result.data.length,
                     filteredCount: filtered.length,
+                    ...(pageStart && { pageStart }),
                 },
             };
         }, options, (data) => formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)));