browser-debugger-cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -2197,6 +2197,7 @@ function truncateUrl(url, maxLength = 60) {
   return `${host}/${rest.substring(0, start)}\u2026${rest.substring(rest.length - (room - start))}`;
 }
 function cutMiddle(text, maxLength) {
+  if (text.length <= maxLength) return text;
   const head = Math.ceil((maxLength - 1) / 2);
   return `${text.substring(0, head)}\u2026${text.substring(text.length - (maxLength - 1 - head))}`;
 }
@@ -2386,9 +2387,25 @@ function formReadinessMessage(summary) {
   if (summary.requiredTotal > 0 || summary.emptyFieldLabels.length === 0) return "READY to submit";
   return `READY to submit (no field is marked required; empty: ${fieldLabelList(summary.emptyFieldLabels)})`;
 }
-function actionStatusLine(done, warned, noEffect = false) {
-  if (noEffect) return `\u26A0 ${done} (${NO_VISIBLE_EFFECT})`;
-  return warned ? `\u26A0 ${done} (with warnings)` : `\u2713 ${done}`;
+function actionStatusLine(done, state) {
+  if (state.noEffect) return `\u26A0 ${done} (${NO_VISIBLE_EFFECT})`;
+  const notes = [state.warned && "with warnings", state.stillChanging && "page still changing"];
+  const shown = notes.filter((note) => typeof note === "string");
+  return shown.length > 0 ? `\u26A0 ${done} (${shown.join("; ")})` : `\u2713 ${done}`;
+}
+function stillChangingNote(action, pending) {
+  const parts = [
+    pending.requests !== void 0 && `${pluralize(pending.requests, "request")} pending`,
+    pending.navigation && "a new page still loading",
+    pending.loading !== void 0 && `loading indicator ${pending.loading} shown`,
+    pending.domChanging && "DOM still changing",
+    pending.busy && "page busy running a script"
+  ].filter((part) => typeof part === "string");
+  const wait = sessionCommand("bdg dom wait <selector>");
+  return `The page was still changing when the ${action} returned (${parts.join(", ")}); wait for the result with ${wait}`;
+}
+function shownElementText(element) {
+  return `${element.element} "${element.text}"`;
 }
 function pageNavigationText(navigation) {
   if (navigation.sameDocument) return `URL changed to ${navigation.url} (same document)`;
@@ -2466,7 +2483,7 @@ function layoutPositionLabel(element, viewport) {
   return note ? `${label} (${note})` : label;
 }
 function colorSchemeLabel(scheme, emulated) {
-  const source = emulated ? "emulated with --color-scheme" : "from the system setting";
+  const source = emulated ? "emulated" : "from the system setting";
   return `prefers-color-scheme: ${scheme} (${source})`;
 }
 function sessionActiveLine(page) {
@@ -2485,6 +2502,32 @@ function layoutHeadline(count, listed, selector) {
 function indexLayoutHeadline(target) {
   return `Element at ${target} (page x,y and size in CSS px):`;
 }
+function coverText(cover, transparent) {
+  return transparent ? `under transparent ${cover} (clicks land on it)` : `covered by ${cover}`;
+}
+function inspectCascadeNote(reason) {
+  return reason === "timeout" ? "CSS rules not read: the page's stylesheets took too long (hints wait 1 s; --rules and --why 5 s)" : "CSS rules not read: Chrome could not report the rules matching this element";
+}
+function inspectDarkThemeBadge() {
+  return "[dark theme from system; --color-scheme light for light]";
+}
+function inspectVisibilityBadges(visibility) {
+  const reason = (text) => text ? `: ${text}` : "";
+  if (visibility.notRendered) {
+    return [`[not rendered${reason(visibility.hidden?.replace(/^not rendered \((.*)\)$/, "$1"))}]`];
+  }
+  return [
+    visibility.hidden && `[hidden: ${visibility.hidden}]`,
+    visibility.offscreen && `[offscreen: ${visibility.offscreen}]`,
+    visibility.coveredBy && `[${coverText(visibility.coveredBy, visibility.coverTransparent)}]`
+  ].filter((badge) => Boolean(badge));
+}
+function inspectedMatchAction(picked, index) {
+  return picked === "first-visible" ? `inspected the first visible one ([${index}])` : "inspected the first";
+}
+function multipleMatchesWarning(count, action) {
+  return `${count} elements match; ${action} (use --index or a more specific selector)`;
+}
 function listenersHeadline(element, counts, context = {}) {
   const index = context.index === void 0 ? "" : ` [${context.index}]`;
   const frame = context.frame ? ` in ${context.frame}` : "";
@@ -2643,7 +2686,31 @@ function startCommandHelpMessage() {
     ""
   );
 }
-var REQUIRED_FIELD_EMPTY_REASON, NO_VISIBLE_EFFECT, LAYOUT_REASONS, SCROLL_LOCKED_PREFIX, VIEWPORT_POSITION_HINTS, COLLAPSED_LISTENERS_HEADING, NO_LISTENERS_HINT, NOTE_TYPES_SHOWN, POINTER_ACTION_DONE, PAGE_ACTION_DONE, PAGE_INFO_DESCRIPTION, PAGE_ACTION_DESCRIPTIONS, CLICK_RESULT_WAIT_HELP, WAIT_HELP_EXAMPLES, FRAME_URL_MAX_LENGTH;
+function pageEmulateNothingError() {
+  return {
+    message: "Nothing to emulate",
+    suggestion: "Give --viewport <WxH>, --color-scheme light|dark, or --reset, e.g. bdg page emulate --viewport 900x700"
+  };
+}
+function pageEmulationLines(result) {
+  const size = (v) => `${v.width}x${v.height}`;
+  const { emulated } = result;
+  return [
+    ["Viewport", emulated.viewport ? size(emulated.viewport) : "the browser window"],
+    ...result.viewport ? [["Layout", `${size(result.viewport)} (without scrollbars)`]] : [],
+    [
+      "Scheme",
+      emulated.colorScheme ?? `system setting${result.colorScheme ? ` (${result.colorScheme})` : ""}`
+    ]
+  ];
+}
+function inspectAnimatingBadge(animating) {
+  return `[animating: ${animating.join(", ")}; values are mid-way, inspect again]`;
+}
+function inspectMidTransitionNote() {
+  return "(mid-transition: inspect again for the final value)";
+}
+var REQUIRED_FIELD_EMPTY_REASON, NO_VISIBLE_EFFECT, LAYOUT_REASONS, SCROLL_LOCKED_PREFIX, VIEWPORT_POSITION_HINTS, INSPECT_OUTPUT_LEGEND, COLLAPSED_LISTENERS_HEADING, NO_LISTENERS_HINT, NOTE_TYPES_SHOWN, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, PAGE_ACTION_DONE, PAGE_INFO_DESCRIPTION, PAGE_EMULATE_DESCRIPTION, PAGE_ACTION_DESCRIPTIONS, CLICK_RESULT_WAIT_HELP, WAIT_HELP_EXAMPLES, FRAME_URL_MAX_LENGTH;
 var init_commands = __esm({
   "src/ui/messages/commands.ts"() {
     "use strict";
@@ -2674,6 +2741,24 @@ var init_commands = __esm({
       right: "right of viewport",
       hidden: "hidden"
     };
+    INSPECT_OUTPUT_LEGEND = `
+Output notation:
+  WxH @x,y        rendered border box size and page position (CSS px, no unit)
+  m / p / b       margin / padding / border widths, 1-4 values in CSS order (top right bottom left)
+  in-parent       distances to the parent's content edges (l t r b); sib: gaps to the sibling on each side
+  scroll WxH      the content (pseudo-elements too) is larger than the box
+  16/24           font size / line height; 'webfont loaded' = drawn with a downloaded font;
+                  (rendered "X") = drawn with another font than declared (a fallback)
+  contrast 4.47   WCAG ratio, rounded down, against the background behind the text
+  (+N not rendered)  children with display: none (or not in the layout)
+  hints           declarations on this element that have no effect, why, the fix and where they are
+                  ('none': checked, nothing found)
+  \u2190 sel (file:N)  --rules: the declaration that sets the value (file:line, or file:line:column in
+                  minified files); 'over X': rules it beats; '= v': the value of a var() expression
+  \u2713 / \u2717           --why: the winning declaration / ones it beats, highest precedence first;
+                  [0,2,0]: selector specificity (ids, classes, types); indented --name lines: where
+                  the winner's custom properties are set
+Sessions follow the system color scheme; start with --color-scheme light|dark to choose.`;
     COLLAPSED_LISTENERS_HEADING = "Framework roots (one line per node; --all lists each listener):";
     NO_LISTENERS_HINT = "Inline on\u2026 attributes and on\u2026 properties are included, and so are handlers frameworks delegate to ancestors (React, jQuery)";
     NOTE_TYPES_SHOWN = 5;
@@ -2683,6 +2768,12 @@ var init_commands = __esm({
       right: "Right-clicked",
       hover: "Hovered"
     };
+    POINTER_ACTION_NOUN = {
+      click: "click",
+      double: "double-click",
+      right: "right-click",
+      hover: "hover"
+    };
     PAGE_ACTION_DONE = {
       navigate: "Navigated",
       reload: "Reloaded",
@@ -2690,6 +2781,7 @@ var init_commands = __esm({
       forward: "Went forward"
     };
     PAGE_INFO_DESCRIPTION = "Show the URL and title of the session page";
+    PAGE_EMULATE_DESCRIPTION = "Change the viewport or color scheme mid-session (like --viewport and --color-scheme at start), or --reset both";
     PAGE_ACTION_DESCRIPTIONS = {
       reload: "Reload the page",
       back: "Go back one page (like the browser button)",
@@ -2698,7 +2790,8 @@ var init_commands = __esm({
     CLICK_RESULT_WAIT_HELP = joinLines(
       "",
       "Waits only for the requests the action starts (150 ms idle, up to 2 s), not for",
-      "results the page shows later (timers, spinners, animations). Wait for those with:",
+      "results the page shows later (timers, spinners, animations); the result says",
+      '"page still changing" when it saw such work pending. Wait for those with:',
       "  bdg dom wait '#result' --visible          # or --text 'Saved', or '.spinner' --gone"
     );
     WAIT_HELP_EXAMPLES = joinLines(
@@ -3142,6 +3235,9 @@ function similarSelectorsLine(kind, names) {
   const plural = names.length === 1 ? what : kind === "id" ? "ids" : "classes";
   return `Did you mean ${names.map((name) => sigil + name).join(", ")}? (similar ${plural} on the page)`;
 }
+function shadowBoundaryLine(host) {
+  return `${host.compound} hosts a shadow root, which a selector cannot cross into; bdg searches open shadow roots itself: use "${host.rest}"`;
+}
 function noNodesFoundError(selector, context = {}) {
   const hiddenMatches = context.hidden ?? 0;
   const hidden = hiddenMatches > 0 ? hiddenMatches === 1 ? "1 element matches without :visible but is hidden (check with bdg dom layout). " : `${hiddenMatches} elements match without :visible but are hidden (check with bdg dom layout). ` : "";
@@ -3151,6 +3247,7 @@ function noNodesFoundError(selector, context = {}) {
     suggestion: withLoadingHint(
       joinLines(
         context.similar,
+        context.shadowHost && shadowBoundaryLine(context.shadowHost),
         `${hidden}Verify the CSS selector is correct.`,
         note ? note : void 0
       ),
@@ -3853,6 +3950,9 @@ async function domScroll(params) {
 async function pageNavigate(params) {
   return sendCommand("page_navigate", params);
 }
+async function pageEmulate(params) {
+  return sendCommand("page_emulate", params);
+}
 async function domFormDiscover() {
   return sendCommand("dom_form_discover", {});
 }
@@ -3862,6 +3962,9 @@ async function domListeners(params) {
 async function domLayout(params) {
   return sendCommand("dom_layout", params);
 }
+async function domInspect(params) {
+  return sendCommand("dom_inspect", params);
+}
 async function domWait(params) {
   return sendCommand(
     "dom_wait",
@@ -3888,7 +3991,7 @@ function textPreview2(text, length = PREVIEW_LENGTH) {
   const characters = Array.from(collapsed);
   return characters.length > length ? characters.slice(0, length).join("") + "..." : collapsed;
 }
-var PREVIEW_LENGTH, ELEMENT_TEXT_LENGTH, WITHOUT_DECORATIONS_JS, ELEMENT_TEXT_JS, ELEMENT_DESCRIPTION_JS, SIBLING_POSITION_JS, ELEMENT_IDENTITY_JS, ELEMENT_CONTEXT_JS;
+var PREVIEW_LENGTH, ELEMENT_TEXT_LENGTH, WITHOUT_DECORATIONS_JS, ELEMENT_TEXT_JS, MASKED_VALUE, SENSITIVE_FIELD_JS, ELEMENT_STATE_JS, ELEMENT_DESCRIPTION_JS, SIBLING_POSITION_JS, ELEMENT_IDENTITY_JS, ELEMENT_CONTEXT_JS;
 var init_elementInfo = __esm({
   "src/runtime/dom/elementInfo.ts"() {
     "use strict";
@@ -3933,6 +4036,48 @@ var init_elementInfo = __esm({
     if (!parent || rendered(parent)) start += walker.currentNode.data;
   }
   return withoutDecorations(el, start);
+}`;
+    MASKED_VALUE = "\u2022\u2022\u2022\u2022";
+    SENSITIVE_FIELD_JS = `(el) => {
+  const autocomplete = el.getAttribute('autocomplete') || '';
+  if (/(^|\\s)(cc-[a-z-]+|one-time-code|current-password|new-password)(\\s|$)/i.test(autocomplete)) return true;
+  if (el.type === 'password' || /^password$/i.test(el.getAttribute('type') || '')) return true;
+  const names = [el.getAttribute('name'), el.id, autocomplete].join(' ');
+  if (/passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc/i.test(names)) return true;
+  try {
+    const security = el.ownerDocument.defaultView.getComputedStyle(el).getPropertyValue('-webkit-text-security');
+    return Boolean(security) && security !== 'none';
+  } catch (e) {
+    return false;
+  }
+}`;
+    ELEMENT_STATE_JS = `(el) => {
+  const isSensitive = ${SENSITIVE_FIELD_JS};
+  const mask = (value) => (value ? '${MASKED_VALUE}' : '');
+  const guarded = (state) => {
+    if (!isSensitive(el)) return state;
+    const result = { ...state, sensitive: true };
+    if ('value' in result) result.value = mask(result.value);
+    if ('selected' in result) result.selected = mask(result.selected);
+    return result;
+  };
+  switch (el.localName) {
+    case 'input':
+      if (el.type === 'hidden') return { type: 'hidden' };
+      return guarded(
+        /^(checkbox|radio)$/.test(el.type)
+          ? { type: el.type, checked: el.checked, value: el.getAttribute('value') || '' }
+          : { type: el.type, value: el.value }
+      );
+    case 'textarea':
+      return guarded({ value: el.value });
+    case 'select':
+      return guarded({ selected: Array.from(el.selectedOptions || [], (option) => option.label).join(', ') });
+    case 'button':
+      return el.form ? { type: el.type } : {};
+    default:
+      return {};
+  }
 }`;
     ELEMENT_DESCRIPTION_JS = `(node) => node.tagName.toLowerCase() +
   (node.id ? '#' + node.id : '') +
@@ -4011,6 +4156,42 @@ var init_elementInfo = __esm({
   }
 });
 
+// src/commands/dom/helpers/keyAttributes.ts
+function keyAttributes(tag, attributes, state = {}) {
+  const names = ATTRIBUTES_BY_TAG[tag];
+  if (!names) return void 0;
+  const result = {};
+  const type = state.type ?? attributes["type"];
+  if (type) result["type"] = type;
+  for (const name of names) {
+    const value = attributes[name];
+    if (value) result[name] = value;
+  }
+  if (type === "hidden") return result;
+  const secret = state.sensitive === true || type === "password";
+  if (state.value) result["value"] = secret ? MASKED_VALUE : state.value;
+  if (state.checked !== void 0) result["checked"] = state.checked;
+  if (state.selected) result["selected"] = secret ? MASKED_VALUE : state.selected;
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+var ATTRIBUTES_BY_TAG;
+var init_keyAttributes = __esm({
+  "src/commands/dom/helpers/keyAttributes.ts"() {
+    "use strict";
+    init_elementInfo();
+    ATTRIBUTES_BY_TAG = {
+      img: ["src", "alt"],
+      a: ["href"],
+      input: ["name", "placeholder"],
+      textarea: ["name", "placeholder"],
+      button: ["name"],
+      select: ["name"],
+      iframe: ["src"],
+      form: ["action", "method"]
+    };
+  }
+});
+
 // src/runtime/dom/elementGeometry.ts
 function edgesOf(box) {
   return { left: box.x, top: box.y, right: box.x + box.width, bottom: box.y + box.height };
@@ -4397,6 +4578,23 @@ function splitSelectorList(selector) {
   parts.push(selector.slice(partStart));
   return parts;
 }
+function leadingCompounds(selector) {
+  if (splitSelectorList(selector).length > 1) return [];
+  const text = selector.trim();
+  const found = [];
+  let start = 0;
+  scan(text, (index, depth) => {
+    const char = text[index] ?? "";
+    if (depth > 0 || !/[\s>+~]/.test(char)) return index;
+    const compound = text.slice(start, index).trim();
+    let next = index;
+    while (next + 1 < text.length && /[\s>+~]/.test(text[next + 1] ?? "")) next++;
+    if (compound) found.push({ compound, rest: text.slice(next + 1).trim() });
+    start = next + 1;
+    return next;
+  });
+  return found;
+}
 function scan(text, visit) {
   let depth = 0;
   for (let i = 0; i < text.length; i++) {
@@ -4864,15 +5062,24 @@ async function withSelection(selector, use) {
 async function noMatchesError(selector) {
   return noNodesFoundError(selector, await noMatchContext(selector));
 }
+function shadowHostJS(compounds) {
+  const plain = compounds.slice(0, MAX_HOST_COMPOUNDS).map((entry) => [withoutFilters(entry.compound), withoutFilters(entry.rest)]);
+  return `${JSON.stringify(plain)}.findIndex(([host, rest]) => { try { const deep = ${DEEP_QUERY_JS}; return deep(host, null).some((el) => el.shadowRoot) && deep(rest, null).length > 0; } catch (e) { return false; } })`;
+}
+function withoutFilters(selector) {
+  return selector.replace(/:visible\b|:(has-text|text-is)\((?:"[^"]*"|'[^']*'|[^)"'])*\)/g, "").trim() || "*";
+}
 async function noMatchContext(selector) {
   const parts = parseSelectorFilters(selector);
   const unfiltered = parts && withoutVisibleFilters(parts);
   const single = parseSingleNameSelector(selector);
   const hidden = unfiltered ? `(() => { try { return (${DEEP_QUERY_JS})(${JSON.stringify(selector)}, ${JSON.stringify(unfiltered)}).length; } catch (e) { return 0; } })()` : "0";
   const names = single ? pageNamesJS(single.kind) : "[]";
+  const compounds = leadingCompounds(selector);
+  const shadowHost = compounds.length > 0 ? shadowHostJS(compounds) : "-1";
   try {
     const evaluated = await callCDP("Runtime.evaluate", {
-      expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names} })`,
+      expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names}, shadowHost: ${shadowHost} })`,
       returnByValue: true
     });
     const { result } = evaluated.data?.result ?? {};
@@ -4893,7 +5100,8 @@ async function noMatchContext(selector) {
           embeds: value.unsearched.embeds === true
         }
       },
-      ...similar && { similar }
+      ...similar && { similar },
+      ...typeof value.shadowHost === "number" && compounds[value.shadowHost] && { shadowHost: compounds[value.shadowHost] }
     };
   } catch (error) {
     log15.debug(`Could not read the page after no match: ${getErrorMessage(error)}`);
@@ -4924,6 +5132,7 @@ async function elementsWithDetails(arrayObjectId) {
         backendNodeId,
         context: details?.context ?? "",
         text: details?.text ?? "",
+        state: details?.state ?? {},
         ...viewportHint(details?.geometry, viewport)
       }
     ];
@@ -4994,17 +5203,20 @@ async function queryDOMElements(selector) {
     log15.debug(`Querying ${elements.length} elements with selector: ${selector}`);
   }
   const nodes = await mapConcurrently(elements, async (element, index) => {
-    const { backendNodeId, context, text, inViewport, clippedBy } = element;
+    const { backendNodeId, context, text, state, inViewport, clippedBy } = element;
     const desc = await describeNode({ backendNodeId });
     if (!desc) return { index, nodeId: 0 };
     const attributes = unpackAttributes(desc.attributes);
     const classes = attributes["class"]?.split(/\s+/).filter(Boolean);
     const preview = textPreview2(text);
+    const tag = desc.nodeName.toLowerCase();
+    const keys = keyAttributes(tag, attributes, state);
     return {
       index,
       nodeId: desc.backendNodeId,
-      tag: desc.nodeName.toLowerCase(),
+      tag,
       ...identifyingAttributes(attributes, desc.nodeName),
+      ...keys && { attributes: keys },
       ...classes && { classes },
       ...preview && { preview },
       ...context && { context },
@@ -5023,20 +5235,23 @@ function identifyingAttributes(attributes, nodeName) {
     ...value !== void 0 && { value }
   };
 }
-async function elementText(ref, full) {
+async function elementTextAndState(ref, full) {
   const objectGroup = `bdg-text-${process.pid}-${++queryCount}`;
   const resolved = await callCDP("DOM.resolveNode", { ...ref, objectGroup });
   const objectId = resolved.data?.result?.object.objectId;
-  if (!objectId) return "";
+  if (!objectId) return { text: "", state: {} };
   try {
     const response = await callCDP("Runtime.callFunctionOn", {
       objectId,
-      functionDeclaration: `function (full) { return (${ELEMENT_TEXT_JS})(this, full); }`,
+      functionDeclaration: `function (full) { return { text: (${ELEMENT_TEXT_JS})(this, full), state: (${ELEMENT_STATE_JS})(this) }; }`,
       arguments: [{ value: full }],
       returnByValue: true
     });
     const value = response.data?.result?.result?.value;
-    return typeof value === "string" ? value : "";
+    return {
+      text: typeof value?.text === "string" ? value.text : "",
+      state: value?.state ?? {}
+    };
   } finally {
     await callCDP("Runtime.releaseObjectGroup", { objectGroup });
   }
@@ -5049,13 +5264,18 @@ async function getDomContext(ref, options = {}) {
     return null;
   }
   const full = options.full === true;
-  const classes = unpackAttributes(desc.attributes)["class"]?.split(/\s+/).filter(Boolean);
-  const text = await elementText(ref, full);
+  const attributes = unpackAttributes(desc.attributes);
+  const classes = attributes["class"]?.split(/\s+/).filter(Boolean);
+  const { text, state } = await elementTextAndState(ref, full);
   const preview = textPreview2(text);
   const longer = textPreview2(text, full ? Number.POSITIVE_INFINITY : ELEMENT_TEXT_LENGTH);
+  const tag = desc.nodeName.toLowerCase();
+  const keys = keyAttributes(tag, attributes, state);
   return {
-    tag: desc.nodeName.toLowerCase(),
+    tag,
     ...classes && classes.length > 0 && { classes },
+    ...keys && { attributes: keys },
+    ...state.sensitive && { sensitive: true },
     ...preview && { preview },
     ...longer !== preview && { text: longer },
     ...!preview && await childElements(ref)
@@ -5182,10 +5402,11 @@ async function assertNodeAttached(backendNodeId, source) {
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
   }
 }
-var log15, CDP_CONCURRENCY_LIMIT, queryCount, VIEWPORT_HINT_LIMIT, ELEMENT_DETAILS_FUNCTION, CHILDREN_LISTED;
+var log15, CDP_CONCURRENCY_LIMIT, queryCount, MAX_HOST_COMPOUNDS, VIEWPORT_HINT_LIMIT, ELEMENT_DETAILS_FUNCTION, CHILDREN_LISTED;
 var init_query = __esm({
   "src/commands/dom/helpers/query.ts"() {
     "use strict";
+    init_keyAttributes();
     init_errors3();
     init_messages();
     init_client();
@@ -5202,14 +5423,16 @@ var init_query = __esm({
     log15 = createLogger("dom");
     CDP_CONCURRENCY_LIMIT = 10;
     queryCount = 0;
+    MAX_HOST_COMPOUNDS = 4;
     VIEWPORT_HINT_LIMIT = 100;
     ELEMENT_DETAILS_FUNCTION = `function () {
   const contextOf = ${ELEMENT_CONTEXT_JS};
   const textOf = ${ELEMENT_TEXT_JS};
   const geometryOf = ${ELEMENT_GEOMETRY_JS};
+  const stateOf = ${ELEMENT_STATE_JS};
   const read = (el, index) => {
     try {
-      return { context: contextOf(el), text: textOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
+      return { context: contextOf(el), text: textOf(el), state: stateOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
     } catch (e) {
       return {};
     }
@@ -5486,13 +5709,22 @@ async function restoreScrollPosition(position) {
     returnByValue: true
   });
 }
+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)
+  };
+}
 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) {
@@ -5636,6 +5868,28 @@ async function capturePageScreenshot(outputPath, options = {}) {
   }
   return result;
 }
+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 };
+}
+function insideView(area, view) {
+  return area.x >= 0 && area.y >= 0 && area.x + area.width <= view.width && area.y + area.height <= view.height;
+}
+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) };
+}
 async function captureArea(ref, bounds) {
   const objectGroup = `bdg-shot-${process.pid}`;
   try {
@@ -5667,8 +5921,6 @@ async function captureArea(ref, bounds) {
   }
 }
 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 : void 0;
   const noResize = options.noResize ?? false;
@@ -5677,6 +5929,20 @@ 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);
@@ -5685,7 +5951,6 @@ 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,
@@ -5693,14 +5958,13 @@ 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 !== void 0 && { quality },
       clip: { ...clip, scale },
-      captureBeyondViewport: true
+      captureBeyondViewport: !inView
     });
     screenshotResult = screenshotResponse.data?.result;
   } finally {
@@ -9193,6 +9457,8 @@ init_schema();
 init_screenshotResize();
 var TRIGGERED_REQUESTS_BEHAVIOR = "Requests (and WebSocket connections) that start after the action begins are returned as triggeredRequests (method, url, status, durationMs; pending when still running at return, loading when the response arrived but its body is still streaming; with resourceType; human output lists documents, XHR/fetch and WebSockets first (up to 10) and counts static assets on one line; absent when network telemetry is off). Attribution is by time: requests a page timer or poller starts meanwhile are listed too, whether or not the action caused them";
 var ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "\u2026" (element); JSON messages [{ text, element }], at most 3; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
+var STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes kept coming in bursts over a second look 250 ms later; a single render, ticking text and style animations do not count), busy (the page did not answer within 250 ms: a long script) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
+var SHOWN_BEHAVIOR = `Elements the action showed are listed (Shown: <element> "<text>"; JSON shown [{ text, element }], at most 3, outermost first): elements with visible text added inside the target's form, search box, dialog or combobox (else its grandparent, or its parent when that is the body), and popups and messages added anywhere (tooltip, menu, listbox, dialog, alert, status roles, popover, aria-live, message-like classes); widgets elsewhere on the page and re-rendered elements whose text was there before do not count`;
 var NO_WAIT_TRIGGERED_REQUESTS = "Returns immediately without waiting for network; triggeredRequests lists only requests bdg saw start before returning (often none yet; check bdg network list later)";
 var OPTION_BEHAVIORS = {
   "screenshot:--selector": {
@@ -9252,7 +9518,7 @@ var OPTION_BEHAVIORS = {
   "eval:--frame": {
     default: "Evaluates in the page's main frame",
     whenEnabled: "Evaluates in one iframe's main world (its own globals), including cross-origin (out-of-process) iframes; output gains a frame field (its URL)",
-    automaticBehavior: "The value is matched as: a 0-based index (bdg dom frames order, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again)."
+    automaticBehavior: "The value is matched as: a 0-based index (bdg dom frames order: document order of the <iframe> elements, nested ones depth-first, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again). An index that names another frame than in the last bdg dom frames listing (iframes added, removed or moved, or the page navigated) fails with 87 STALE_CACHE: re-run bdg dom frames or pick the frame by name."
   },
   "console:-H": {
     default: "Shows messages from current page load only (most recent navigation)",
@@ -9294,7 +9560,7 @@ var OPTION_BEHAVIORS = {
   "click:--no-wait": {
     default: "Waits for network stability after click (150ms idle, up to 2s)",
     whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-    automaticBehavior: `Network wait helps ensure AJAX requests triggered by click complete. ${TRIGGERED_REQUESTS_BEHAVIOR}. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning). Results the page shows later without requests (timers, spinners) are not waited for: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. A click with no DOM change, no request and no navigation (checked again 300 ms later, which adds 300 ms plus at most 250 ms for the read) is reported as \u26A0 Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms) and effect: "none" in JSON (exit code stays 0); not claimed with --no-wait, for hover or right-click, after a copy or cut, or when the click hit a form control, label, media, iframe, popover button, a mailto:/tel:/javascript: or other non-http link, a link to another window or a custom element with a closed shadow root, or moved focus to an element that is not a button or link. Effects outside the DOM (CSS :hover/:focus-within styles, canvas, clipboard without a copy event) are not seen`,
+    automaticBehavior: `Network wait helps ensure AJAX requests triggered by click complete. ${TRIGGERED_REQUESTS_BEHAVIOR}. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning; --strict refuses instead). Results the page shows later (timers, spinners, slow renders) are not waited for but reported as pending work: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. ${STILL_CHANGING_BEHAVIOR}. A click with no DOM change, no request and no navigation (checked again 300 ms later, which adds 300 ms plus at most 250 ms for the read) is reported as \u26A0 Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms) and effect: "none" in JSON (exit code stays 0); not claimed with --no-wait, for hover or right-click, after a copy or cut, or when the click hit a form control, label, media, iframe, popover button, a mailto:/tel:/javascript: or other non-http link, a link to another window or a custom element with a closed shadow root, or moved focus to an element that is not a button or link. Effects outside the DOM (CSS :hover/:focus-within styles, canvas, clipboard without a copy event) are not seen`,
     tokenImpact: "A click that navigates lists the whole page load in JSON triggeredRequests"
   },
   "click:--double": {
@@ -9305,10 +9571,19 @@ var OPTION_BEHAVIORS = {
     default: "Left click",
     whenEnabled: "Right-click: the page gets contextmenu (custom context menus open); cannot be combined with --double"
   },
+  "click:--strict": {
+    default: 'A covered, hidden or zero-size element is clicked with DOM events (method "dom", with a warning, exit 0)',
+    whenEnabled: "Refuses with exit 90 (RESOURCE_CONFLICT: the page state blocks the request) when a real mouse cannot reach the element, naming what covers it and suggesting bdg dom layout <selector>; also when the mouse press never reached the element (it is released, no further presses for --double)",
+    automaticBehavior: "Applies to --double and --right too. Nothing is dispatched when the element is unreachable, so the page is unchanged"
+  },
   "hover:--no-wait": {
     default: "Waits for network stability after moving the mouse (menus may load content)",
     whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-    automaticBehavior: `The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`
+    automaticBehavior: `The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. ${SHOWN_BEHAVIOR}; for a hover also elements around it (its parent's subtree) and tooltips, menus, listboxes, dialogs and popovers anywhere that were hidden before, so captions shown by CSS :hover count (hidden elements noted by identity right before the mouse moves: up to 1500, within 8 ms). A hover never claims "no visible effect" and does not check whether the page was still changing`
+  },
+  "hover:--strict": {
+    default: 'A covered, hidden or zero-size element gets synthetic mouseover/mouseenter events (method "dom", with a warning)',
+    whenEnabled: "Refuses with exit 90 when a real mouse cannot reach the element, naming what covers it and suggesting bdg dom layout <selector>"
   },
   "navigate:--no-wait": {
     default: "Waits until the new page has loaded and the network and DOM are idle (up to 15 s)",
@@ -9318,7 +9593,7 @@ var OPTION_BEHAVIORS = {
   "pressKey:--no-wait": {
     default: "Waits for network stability after key press (150ms idle, up to 2s)",
     whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-    automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`
+    automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. ${SHOWN_BEHAVIOR}, such as the item Enter added to a list. ${STILL_CHANGING_BEHAVIOR}. A key press never claims "no visible effect"`
   },
   "pressKey:--times": {
     default: "Presses key once",
@@ -9363,7 +9638,7 @@ var OPTION_BEHAVIORS = {
   "listeners:--type": {
     default: "Lists listeners of every event type on the element, its ancestors (through open shadow roots), its document and window",
     whenEnabled: "Lists only these event types (comma-separated or repeated, case-sensitive like addEventListener); when none match, typeSuggestions names close types (Click, onclick \u2192 click)",
-    automaticBehavior: `Listeners are grouped by type, the element's own handlers first (types handled on the element before delegated ones; nearest first, no-ops last); JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). React's on\u2026 props that run for the element (its own and its React parents', through portals; onFocus/onBlur as focusin/focusout; parents' props for non-bubbling events left out) are listed with source and location (framework: "React", reactProp: "onClick"; at most 50 of the requested types, reactHandlersSkipped counts the rest). jQuery handlers are shown instead of jQuery's dispatcher (framework: "jQuery", delegateSelector for delegates the element matches; a dispatcher with no handler for the element is omitted; at most 50 are resolved, jqueryHandlersSkipped counts the rest). Empty handlers (React's onclick placeholder) are marked noop and do not count as the element's own handler. The Debugger domain is not enabled`,
+    automaticBehavior: `Listeners are grouped by type, the element's own handlers first (types handled on the element before delegated ones; nearest first, no-ops last); JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). React's on\u2026 props that run for the element (its own and its React parents', through portals and from a nested root into the outer root; onFocus/onBlur as focusin/focusout; parents' props for non-bubbling events left out) are listed with source and location (framework: "React", reactProp: "onClick"; at most 50 of the requested types, reactHandlersSkipped counts the rest). jQuery handlers are shown instead of jQuery's dispatcher (framework: "jQuery", delegateSelector for delegates the element matches; a dispatcher with no handler for the element is omitted; at most 50 are resolved, jqueryHandlersSkipped counts the rest). Preact's event proxy is replaced by the handler Preact runs (framework: "Preact"). Empty handlers (React's onclick placeholder) are marked noop and do not count as the element's own handler. The Debugger domain is not enabled`,
     tokenImpact: "Framework roots are already collapsed; --type keeps the output short on pages with many listeners"
   },
   "listeners:--all": {
@@ -9377,6 +9652,35 @@ var OPTION_BEHAVIORS = {
     automaticBehavior: 'Coordinates are CSS px: bounds relative to the top-level page (iframe offsets and page scroll included), viewport relative to the visible area. Iframes and overflow containers (scroll lists, overflow: hidden) clip what counts as visible (clippedBy names the one cutting it off). scrollBy brings the whole element into view and is limited to how far the page can scroll: for an element out of view it centres it (aligns its start when it is larger than the viewport; human output says "to centre it"), for a partly visible one it is the smallest scroll that shows all of it (the part cut off at the top or bottom; the start of one larger than the viewport; "partly visible (87%); scroll up 5px to see all of it"). Elements a page script moves on scroll (floating menus) may move again after it; fixed and sticky elements (page scroll does not move them, or only until they stick) and ones beyond that range get offScreenReason instead, which says "page scrolling is locked (\u2026)" when the page cannot scroll because body/html is position: fixed or overflow: hidden, so in-flow content is not called fixed; a visible dialog (dialog[open], [aria-modal=true], [role=dialog|alertdialog]) is named as the likely cause ("likely by dialog div#consent"). page.viewport is the layout viewport without scrollbars, as dom scroll reports it; page.colorScheme is the prefers-color-scheme media feature the page sees (not the theme it renders). Content in a closed <details> or under content-visibility: hidden is hidden. coveredBy is the topmost element at the center of the largest visible box (none for pointer-events: none, nor for an element of the same click target: an overlay inside the link, button or label the element is in, a link to the same URL, or the textless absolutely positioned overlay link spanning the card that holds plain content); inert elements are flagged, not hidden',
     tokenImpact: 'About one line per element; a cheap alternative to screenshots for "where is it?"'
   },
+  "inspect:--index": {
+    default: "Inspects the first rendered match (the first when none is rendered) and notes how many matched; a numeric argument inspects that cached element (from dom query, dom form or dom a11y query)",
+    whenEnabled: "Inspects the nth match (0-based); out of range exits 81",
+    automaticBehavior: `Answers "what does it look like" without a screenshot, grouped like Figma Dev Mode: header (element, text, size and page position, [flex]/[grid], [not rendered]/[hidden]/[offscreen]/[covered by \u2026], prefers-color-scheme), box (margin, padding, border widths, box-sizing, overflow, scroll size), layout (display, position, flex/grid container and item settings), parent (its display and layout, distances to its content edges, gaps to the neighbouring siblings), text (first font family \u2192 the font Chrome rendered, (webfont) or local; weight size/line-height; color; WCAG contrast against the composited background; only for elements with text), fill, border (sides, radius, outline), fx (shadow, transform, filter, opacity, blend), state (cursor, pointer-events, user-select, appearance), pseudo (::before/::after with content, ::placeholder) and a child tree (depth 2, 20 rows, identical siblings grouped). Values that change nothing (0, none, transparent, normal) are left out; colors are hex (lab/oklch from Tailwind converted), lengths px without the unit, rounded to 0.1. Secrets are never shown. JSON uses Figma-aligned names (rect, box, layout.sizing hug/fill/fixed, text, fills, strokes, radius, effects, children). Also by default: hints, the element's own declarations that have no effect (justify-content on a block, width on an inline element, top on a static one, var() of an unset custom property) with the reason, the fix and the rule's file:line`,
+    tokenImpact: "About 60\u201380 tokens for the styles and 30\u201370 more for the child tree (--tree 0 drops it), against about 1,500 for a screenshot or 3,000+ for raw computed styles"
+  },
+  "inspect:--all": {
+    default: "Shows the curated groups (the properties that define the look)",
+    whenEnabled: "Lists every computed property that differs from the default of the same element type, longhands collapsed into shorthands, noise (logical duplicates, currentColor echoes, custom properties) dropped",
+    tokenImpact: "About 80 tokens instead of 60\u201380"
+  },
+  "inspect:--props": {
+    default: "Shows the curated groups",
+    whenEnabled: 'Shows only the named properties (custom properties like --brand included, "(not set)" when no rule sets one; --* lists every custom property the element has, --bs-btn-* those with a prefix), each computed and normalized; an unknown name exits 81 with a suggestion'
+  },
+  "inspect:--rules": {
+    default: "Shows the values, not where they come from",
+    whenEnabled: "Adds a rules group: for each shown property the page's CSS sets, the value as written (with the computed value when it uses var()), selector, file:line (column for minified files), @media/@container condition, cascade layer, how many ancestors up it is inherited from, and the rules it beats. Sides one declaration sets are one row; browser defaults are left out. With --props, only those properties",
+    automaticBehavior: "The cascade is computed by bdg from CSS.getMatchedStylesForNode (origin, !important, style attribute, layers, specificity and order); reading it waits up to 5 s, then the output notes the cascade was not read",
+    tokenImpact: "About 15\u201325 tokens per row, 5\u201320 rows"
+  },
+  "inspect:--why": {
+    default: "Not shown",
+    whenEnabled: "Adds why <property> = computed value, then every declaration of it on the element, highest precedence first: \u2713 the winner (or the inherited ancestor's), \u2717 the ones it beats, browser defaults included. Each rule shows its selector specificity [ids,classes,types]. var() values are shown substituted (or invalid: --x not set), with where the winner's custom properties are set, followed up to :root. Logical names map to physical ones (margin-inline-start \u2192 margin-left); a shorthand (padding, border) gives one answer when one declaration sets all its sides, else one per side"
+  },
+  "inspect:--no-hints": {
+    default: "Hints at the element's own author declarations that have no effect (flex/grid properties without flex or grid, item properties without a flex or grid parent, offsets on static elements, sizes on inline ones, var() of an unset custom property, form controls in the browser's font), within a 1 s budget; hints none when nothing was found",
+    whenEnabled: "Skips the hints and does not read the matched rules"
+  },
   "scroll:--down": {
     whenEnabled: "Scrolls page down by specified pixel amount"
   },
@@ -9458,7 +9762,7 @@ var OPTION_BEHAVIORS = {
   "bdg:--viewport": {
     default: "A launched Chrome opens a 1920x1080 window (the viewport is smaller by the scrollbar, and in a visible window by the browser UI); an attached Chrome keeps its window",
     whenEnabled: "The page gets exactly that viewport (CSS px, e.g. 1280x800) for the whole session, through navigations and reloads (Emulation.setDeviceMetricsOverride at the display pixel ratio); a launched Chrome also opens its window at that size, so tabs the page opens get it too",
-    automaticBehavior: "Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265\xD7800 (--viewport 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81"
+    automaticBehavior: "Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265\xD7800 (emulated 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81"
   },
   "bdg:--color-scheme": {
     default: "The page sees the system setting for prefers-color-scheme (headless Chrome follows the OS, so a dark OS renders dark pages); bdg status and dom layout show which one",
@@ -10113,6 +10417,14 @@ init_logging();
 function delay2(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
+async function waitUntil(condition, timeoutMs, pollMs = 25) {
+  const deadline = Date.now() + timeoutMs;
+  while (!condition()) {
+    if (Date.now() >= deadline) return false;
+    await delay2(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+  }
+  return true;
+}
 
 // src/utils/file.ts
 init_logging();
@@ -10892,6 +11204,12 @@ function showBothSectionsWhenBothRequested(options) {
     options.console = false;
   }
 }
+var SELECTOR_SCOPE = "searches open shadow roots and same-origin iframes";
+var SELECTOR_OR_INDEX_ARGUMENT = `CSS selector (${SELECTOR_SCOPE}) or numeric index from query results (0-based)`;
+var SELECTOR_SCOPE_HELP = `
+Selectors search the page, open shadow roots and same-origin iframes (nested ones
+included). They cannot reach into closed shadow roots or cross-origin iframes:
+use bdg dom eval --frame <frame> for those (see bdg dom frames).`;
 
 // src/commands/cdp.ts
 init_errors3();
@@ -10919,9 +11237,11 @@ var COMMANDS = {
   dom_press_key: defineCommand(),
   dom_scroll: defineCommand(),
   page_navigate: defineCommand(),
+  page_emulate: defineCommand(),
   dom_form_discover: defineCommand(),
   dom_listeners: defineCommand(),
   dom_layout: defineCommand(),
+  dom_inspect: defineCommand(),
   dom_wait: defineCommand()
 };
 
@@ -11940,6 +12260,15 @@ function eventTypesOption(value, previous = []) {
   if (types.length > 0) return [.../* @__PURE__ */ new Set([...previous, ...types])];
   throw new InvalidArgumentError("Give at least one event type, e.g. click or click,keydown.");
 }
+function cssPropertiesOption(value, previous = []) {
+  const names = parseCommaSeparated(value).map(
+    (name) => name.startsWith("--") ? name : name.toLowerCase()
+  );
+  if (names.length > 0) return [.../* @__PURE__ */ new Set([...previous, ...names])];
+  throw new InvalidArgumentError(
+    "Give at least one CSS property, e.g. color or padding-top,color."
+  );
+}
 function parseCommaSeparated(value) {
   return value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
 }
@@ -12607,10 +12936,71 @@ function formatRequestStatus(request) {
   return request.errorText && request.errorText !== BODY_ABORTED ? `${request.status} (${request.errorText})` : String(request.status);
 }
 
+// src/ui/formatters/networkHeaders.ts
+init_formatting();
+
+// src/ui/messages/networkMessages.ts
+function followingNetworkMessage() {
+  return "Following network requests... (Ctrl+C to stop)";
+}
+function stoppedFollowingNetworkMessage() {
+  return "\nStopped following network requests.";
+}
+function headerRepeatedNote(count) {
+  return `(sent ${count} times)`;
+}
+function localProxyNote() {
+  return "(loopback; likely a local proxy)";
+}
+
+// src/ui/formatters/networkHeaders.ts
+function formatNetworkHeaders(data) {
+  const fmt = new OutputFormatter();
+  fmt.text("Network Request Headers").separator("\u2501", 60).blank();
+  fmt.text("URL:").text(`  ${data.url}`).blank();
+  fmt.text(`Status: ${requestStatusLine(data)}`).blank();
+  if (Object.keys(data.responseHeaders).length > 0) {
+    fmt.text("Response Headers:");
+    formatHeaderSection(fmt, data.responseHeaders);
+    fmt.blank();
+  }
+  if (Object.keys(data.requestHeaders).length > 0) {
+    fmt.text("Request Headers:");
+    formatHeaderSection(fmt, data.requestHeaders);
+    fmt.blank();
+  }
+  if (Object.keys(data.responseHeaders).length === 0 && Object.keys(data.requestHeaders).length === 0) {
+    fmt.text("No headers found").blank();
+  }
+  fmt.text(`Request ID: ${data.requestId}`);
+  return fmt.build();
+}
+function headerValueLines(name, value) {
+  if (name.toLowerCase() === "set-cookie") return value.split("\n");
+  const counts = /* @__PURE__ */ new Map();
+  for (const line of value.split("\n")) counts.set(line, (counts.get(line) ?? 0) + 1);
+  return [...counts].map(
+    ([line, count]) => count > 1 ? `${line} ${headerRepeatedNote(count)}` : line
+  );
+}
+function formatHeaderSection(fmt, headers) {
+  const entries = Object.entries(headers).sort(([a], [b]) => a.localeCompare(b));
+  const keyWidth = Math.max(...entries.map(([k]) => k.length)) + 4;
+  entries.forEach(([key, value]) => {
+    headerValueLines(key, value).forEach((line) => fmt.keyValue(`  ${key}`, line, keyWidth));
+  });
+}
+function requestStatusLine(data) {
+  const status = formatRequestStatus(data);
+  const text = data.statusText && /^\d+$/.test(status) ? ` ${data.statusText}` : "";
+  return [data.method, `${status}${text}`].filter(Boolean).join(" ");
+}
+
 // src/ui/formatters/details.ts
 init_formatting();
 init_sessionCommand();
 init_strings();
+init_url();
 var MESSAGE_PREVIEW_LENGTH = 200;
 var BINARY_OPCODE = 2;
 function formatWebSocketMessage(frame) {
@@ -12652,6 +13042,34 @@ function formatBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
+function isLoopback(ip) {
+  const bare = ip.replace(/^\[|\]$/g, "").toLowerCase();
+  return /^(::ffff:)?127\./.test(bare) || bare === "::1";
+}
+var DEFAULT_PORTS = {
+  "http:": "80",
+  "https:": "443",
+  "ws:": "80",
+  "wss:": "443"
+};
+function looksLikeLocalProxy(request) {
+  const url = safeParseUrl(request.url);
+  if (!url || request.serverPort === void 0 || !isLoopback(request.serverIPAddress ?? "")) {
+    return false;
+  }
+  const hostname = url.hostname.toLowerCase();
+  if (hostname === "localhost" || hostname.endsWith(".localhost") || isLoopback(hostname)) {
+    return false;
+  }
+  const urlPort = url.port || DEFAULT_PORTS[url.protocol];
+  return urlPort !== void 0 && String(request.serverPort) !== urlPort;
+}
+function remoteAddress(request) {
+  const ip = request.serverIPAddress ?? "";
+  const host = ip.includes(":") && !ip.startsWith("[") ? `[${ip}]` : ip;
+  const address = request.serverPort ? `${host}:${request.serverPort}` : host;
+  return looksLikeLocalProxy(request) ? `${address} ${localProxyNote()}` : address;
+}
 function requestSummaryRows(request) {
   const rows = [
     ["Request ID", request.requestId],
@@ -12670,13 +13088,15 @@ function requestSummaryRows(request) {
     rows.push(["Size", sizes.join(", ")]);
   }
   if (request.fromCache) rows.push(["From Cache", "yes"]);
-  if (request.serverIPAddress) rows.push(["Remote Address", request.serverIPAddress]);
+  if (request.serverIPAddress) rows.push(["Remote Address", remoteAddress(request)]);
   if (request.blockedReason) rows.push(["Blocked", request.blockedReason]);
   return rows;
 }
 function addHeaders(fmt, title, headers) {
   fmt.text(title).separator("\u2501", 70);
-  Object.entries(headers).forEach(([key, value]) => fmt.text(`  ${key}: ${value}`));
+  Object.entries(headers).forEach(
+    ([key, value]) => headerValueLines(key, value).forEach((line) => fmt.text(`  ${key}: ${line}`))
+  );
   fmt.blank();
 }
 function describeResponseBody(request) {
@@ -13065,7 +13485,12 @@ async function withNotFoundContext(failure, selector, searched) {
   const context = await noMatchContext(selector);
   const note = searched ? unreachableElementsNote(selector, context.unsearched) : "";
   const suggestion = withLoadingHint(
-    joinLines(context.similar, failure.errorContext?.suggestion, note ? note : void 0),
+    joinLines(
+      context.similar,
+      context.shadowHost && shadowBoundaryLine(context.shadowHost),
+      failure.errorContext?.suggestion,
+      note ? note : void 0
+    ),
     context.readyState,
     selector
   );
@@ -13211,6 +13636,7 @@ init_formatting();
 init_commands();
 init_sessionCommand();
 init_exitCodes();
+var STRICT_OPTION_HELP = "Fail (exit 90) instead of using DOM events when a real mouse cannot reach the element (covered, hidden, zero-size)";
 function modifiersOption(value) {
   const [unknown] = findUnknownModifiers(value);
   if (unknown !== void 0) {
@@ -13224,7 +13650,7 @@ function registerFormInteractionCommands(program2) {
     const err = internalError("DOM command group not found");
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
   }
-  domCommand.command("fill").description("Fill a form field with a value (React-compatible, waits for stability)").argument("<selectorOrIndex>", "CSS selector or numeric index from query results (0-based)").argument("<value>", 'Value to fill (file inputs: paths separated by commas, "" clears)').option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--no-blur", "Do not blur after filling (keeps focus on element)").option("--no-wait", "Skip waiting for network stability after fill").addOption(jsonOption()).action(async (selectorOrIndex, value, options) => {
+  domCommand.command("fill").description("Fill a form field with a value (React-compatible, waits for stability)").argument("<selectorOrIndex>", SELECTOR_OR_INDEX_ARGUMENT).argument("<value>", 'Value to fill (file inputs: paths separated by commas, "" clears)').option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--no-blur", "Do not blur after filling (keeps focus on element)").option("--no-wait", "Skip waiting for network stability after fill").addOption(jsonOption()).action(async (selectorOrIndex, value, options) => {
     await runCommand(
       () => runElementCommand({
         selectorOrIndex,
@@ -13245,14 +13671,14 @@ function registerFormInteractionCommands(program2) {
       formatFillOutput
     );
   });
-  domCommand.command("click").description("Click an element and wait for stability (accepts selector or index)").argument("<selectorOrIndex>", "CSS selector or numeric index from query results (0-based)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--double", "Double-click").option("--right", "Right-click (opens the context menu)").option("--no-wait", "Skip waiting for network stability after click").addOption(jsonOption()).addHelpText("after", CLICK_RESULT_WAIT_HELP).action(async (selectorOrIndex, options) => {
+  domCommand.command("click").description("Click an element and wait for stability (accepts selector or index)").argument("<selectorOrIndex>", SELECTOR_OR_INDEX_ARGUMENT).option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--double", "Double-click").option("--right", "Right-click (opens the context menu)").option("--strict", STRICT_OPTION_HELP).option("--no-wait", "Skip waiting for network stability after click").addOption(jsonOption()).addHelpText("after", CLICK_RESULT_WAIT_HELP).action(async (selectorOrIndex, options) => {
     const action = options.double ? "double" : options.right ? "right" : "click";
     await runPointerCommand(selectorOrIndex, options, action);
   });
-  domCommand.command("hover").description("Move the mouse over an element (shows hover menus and tooltips)").argument("<selectorOrIndex>", "CSS selector or numeric index from query results (0-based)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--no-wait", "Skip waiting for network stability after hovering").addOption(jsonOption()).action(async (selectorOrIndex, options) => {
+  domCommand.command("hover").description("Move the mouse over an element (shows hover menus and tooltips)").argument("<selectorOrIndex>", SELECTOR_OR_INDEX_ARGUMENT).option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--strict", STRICT_OPTION_HELP).option("--no-wait", "Skip waiting for network stability after hovering").addOption(jsonOption()).action(async (selectorOrIndex, options) => {
     await runPointerCommand(selectorOrIndex, options, "hover");
   });
-  domCommand.command("submit").description("Submit a form by clicking submit button and waiting for completion").argument("<selectorOrIndex>", "CSS selector or numeric index from query results (0-based)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--wait-navigation", "Wait for page navigation after submit").option(
+  domCommand.command("submit").description("Submit a form by clicking submit button and waiting for completion").argument("<selectorOrIndex>", SELECTOR_OR_INDEX_ARGUMENT).option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--wait-navigation", "Wait for page navigation after submit").option(
     "--wait-network <ms>",
     "Wait for network idle after submit (milliseconds)",
     integerOption(0),
@@ -13279,7 +13705,7 @@ function registerFormInteractionCommands(program2) {
       formatSubmitOutput
     );
   });
-  domCommand.command("pressKey").description("Press a key on an element (for Enter-to-submit, keyboard navigation)").argument("<selectorOrIndex>", "CSS selector or numeric index from query results (0-based)").argument("<key>", "Key to press (Enter, Tab, Escape, Space, ArrowUp, etc.)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--times <n>", "Press key multiple times (default: 1)", integerOption(1, 1e3)).option(
+  domCommand.command("pressKey").description("Press a key on an element (for Enter-to-submit, keyboard navigation)").argument("<selectorOrIndex>", SELECTOR_OR_INDEX_ARGUMENT).argument("<key>", "Key to press (Enter, Tab, Escape, Space, ArrowUp, etc.)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--times <n>", "Press key multiple times (default: 1)", integerOption(1, 1e3)).option(
     "--modifiers <mods>",
     "Modifier keys: shift,ctrl,alt,meta (comma-separated; aliases cmd, control, option)",
     modifiersOption
@@ -13381,7 +13807,8 @@ async function runPointerCommand(selectorOrIndex, options, action) {
       buildRequest: (target) => ({
         ...target,
         wait: options.wait !== false,
-        ...action !== "click" && { action }
+        ...action !== "click" && { action },
+        ...options.strict && { strict: true }
       }),
       call: domClick,
       command: action === "hover" ? "hover" : "click",
@@ -13392,18 +13819,26 @@ async function runPointerCommand(selectorOrIndex, options, action) {
     formatClickOutput
   );
 }
-function formatActionOutput(done, details, result, keyWidth = 15) {
+function formatActionOutput(done, details, result, options = {}) {
+  const keyWidth = options.keyWidth ?? 15;
   const fmt = new OutputFormatter();
-  fmt.text(actionStatusLine(done, result.warning !== void 0, result.effect === "none"));
+  const stillChanging = result.settled === false && result.pending !== void 0;
+  fmt.text(
+    actionStatusLine(done, {
+      warned: result.warning !== void 0,
+      noEffect: result.effect === "none",
+      stillChanging
+    })
+  );
   if (result.warning) fmt.text(`\u26A0 Warning: ${result.warning}`);
+  if (stillChanging && result.pending) {
+    fmt.text(`\u26A0 ${stillChangingNote(options.action ?? "action", result.pending)}`);
+  }
   fmt.blank();
   fmt.keyValueList(details, keyWidth);
   if (result.navigation) fmt.keyValue("Page", pageNavigationText(result.navigation), keyWidth);
-  (result.messages ?? []).forEach((message, index) => {
-    const text = newMessageText(message);
-    if (index === 0) fmt.keyValue("New text", text, keyWidth);
-    else fmt.text(" ".repeat(keyWidth) + text);
-  });
+  listRows(fmt, "New text", (result.messages ?? []).map(newMessageText), keyWidth);
+  listRows(fmt, "Shown", (result.shown ?? []).map(shownElementText), keyWidth);
   const omitted = result.triggeredRequestsOmitted;
   const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
   if (requests.length > 0) {
@@ -13415,6 +13850,12 @@ function formatActionOutput(done, details, result, keyWidth = 15) {
   }
   return fmt;
 }
+function listRows(fmt, label, texts, keyWidth) {
+  texts.forEach((text, index) => {
+    if (index === 0) fmt.keyValue(label, text, keyWidth);
+    else fmt.text(" ".repeat(keyWidth) + text);
+  });
+}
 function elementRow(result) {
   const source = result.indexSource ? ` (${indexSourceText(result.indexSource)})` : "";
   if (result.element === void 0) {
@@ -13445,7 +13886,8 @@ function formatClickOutput(result) {
       elementRow(result),
       ["Method", result.method === "dom" ? "DOM events" : "mouse events"]
     ],
-    result
+    result,
+    { action: POINTER_ACTION_NOUN[result.action ?? "click"] }
   ).build();
 }
 function formatSubmitOutput(result) {
@@ -13459,7 +13901,10 @@ function formatSubmitOutput(result) {
   if (result.navigationOccurred === false) details.push(["Navigation", "no"]);
   if (result.navigationOccurred && !result.navigation) details.push(["Navigation", "yes"]);
   if (result.waitTimeMs !== void 0) details.push(["Wait Time", `${result.waitTimeMs}ms`]);
-  const fmt = formatActionOutput("Form Submitted", details, result, 20);
+  const fmt = formatActionOutput("Form Submitted", details, result, {
+    keyWidth: 20,
+    action: "submit"
+  });
   fmt.hints("Next steps:", [
     `${sessionCommand("bdg network list --last 10").padEnd(32)} Check network requests`,
     `${sessionCommand("bdg console --last 5").padEnd(32)} Check console messages`,
@@ -13475,7 +13920,7 @@ function formatPressKeyOutput(result) {
   ];
   if (result.times && result.times > 1) details.push(["Times", result.times.toString()]);
   if (result.modifiers?.length) details.push(["Modifiers", result.modifiers.join("+")]);
-  return formatActionOutput("Key Pressed", details, result).build();
+  return formatActionOutput("Key Pressed", details, result, { action: "key press" }).build();
 }
 function formatScrollOutput(result) {
   const details = [["Scroll Type", result.scrollType]];
@@ -13494,38 +13939,247 @@ function formatScrollOutput(result) {
 
 // src/commands/dom/a11y.ts
 init_helpers();
-init_errors3();
-init_messages();
 
-// src/telemetry/a11y.ts
-init_errors3();
-init_messages();
-init_client();
+// src/commands/dom/semanticUtils.ts
+init_elementInfo();
 
-// src/runtime/dom/frameLayout.ts
-init_frameScopedConnection();
-init_logging();
-init_errors();
-var log19 = createLogger("dom");
-function childFrameIds(tree) {
-  return (tree?.childFrames ?? []).flatMap((child) => [child.frame.id, ...childFrameIds(child)]);
+// src/telemetry/roleInference.ts
+var IMPLICIT_ARIA_ROLES = {
+  // Interactive elements
+  a: "link",
+  button: "button",
+  input: "textbox",
+  select: "combobox",
+  textarea: "textbox",
+  option: "option",
+  // Headings
+  h1: "heading",
+  h2: "heading",
+  h3: "heading",
+  h4: "heading",
+  h5: "heading",
+  h6: "heading",
+  // Landmarks
+  nav: "navigation",
+  main: "main",
+  header: "banner",
+  footer: "contentinfo",
+  aside: "complementary",
+  section: "region",
+  article: "article",
+  form: "form",
+  search: "search",
+  // Media
+  img: "image",
+  figure: "figure",
+  figcaption: "caption",
+  video: "video",
+  audio: "audio",
+  // Lists
+  ul: "list",
+  ol: "list",
+  li: "listitem",
+  dl: "list",
+  dt: "term",
+  dd: "definition",
+  menu: "menu",
+  menuitem: "menuitem",
+  // Tables
+  table: "table",
+  thead: "rowgroup",
+  tbody: "rowgroup",
+  tfoot: "rowgroup",
+  tr: "row",
+  th: "columnheader",
+  td: "cell",
+  // Other semantic elements
+  dialog: "dialog",
+  details: "group",
+  summary: "button",
+  progress: "progressbar",
+  meter: "meter",
+  output: "status",
+  address: "group",
+  blockquote: "blockquote",
+  code: "code",
+  pre: "group",
+  hr: "separator"
+};
+var DEFAULT_ROLE = "generic";
+var MAX_NAME_LENGTH = 100;
+function inferRoleFromTag(tag) {
+  const normalizedTag = tag.toLowerCase();
+  return IMPLICIT_ARIA_ROLES[normalizedTag] ?? DEFAULT_ROLE;
 }
-
-// src/telemetry/a11y.ts
-init_exitCodes();
-init_levenshtein();
-function buildTreeFromRawNodes(rawNodes) {
-  const rawById = new Map(rawNodes.map((rawNode) => [rawNode.nodeId, rawNode]));
-  const rootRaw = rawNodes.find((rawNode) => !rawNode.ignored);
-  if (!rootRaw) {
-    throw new CommandError(
-      "No root node found in accessibility tree",
-      { suggestion: "The page may not be fully loaded. Wait and retry." },
-      EXIT_CODES.SOFTWARE_ERROR
-    );
+function extractHeadingLevel(tag) {
+  const match = tag.toLowerCase().match(/^h([1-6])$/);
+  const level = match?.[1];
+  if (!level) {
+    return null;
   }
-  const nodes = /* @__PURE__ */ new Map();
-  const visit = (rawNode) => {
+  return parseInt(level, 10);
+}
+function synthesizeA11yNode(domContext, nodeId) {
+  const role = inferRoleFromTag(domContext.tag);
+  const node = {
+    nodeId: String(nodeId),
+    role,
+    inferred: true,
+    backendDOMNodeId: nodeId
+  };
+  if (domContext.preview) {
+    const name = domContext.preview.length > MAX_NAME_LENGTH ? domContext.preview.slice(0, MAX_NAME_LENGTH - 3) + "..." : domContext.preview;
+    node.name = name;
+  }
+  const headingLevel = extractHeadingLevel(domContext.tag);
+  if (headingLevel !== null) {
+    node.properties = { level: headingLevel };
+  }
+  return node;
+}
+
+// src/ui/formatters/keyAttributes.ts
+init_formatting();
+init_url();
+var MAX_VALUE_LENGTH = 40;
+function fileName(src) {
+  if (/^(data|blob):/i.test(src)) return src;
+  const path6 = src.split(/[?#]/)[0] ?? src;
+  const name = path6.substring(path6.lastIndexOf("/") + 1);
+  return name && name !== path6 ? `\u2026/${name}` : src;
+}
+function hostOf(src) {
+  const parsed = /^https?:/i.test(src) ? safeParseUrl(src) : null;
+  if (!parsed) return src;
+  const more = parsed.pathname.length > 1 || parsed.search ? "/\u2026" : "";
+  return `//${parsed.host}${more}`;
+}
+function shortUrl(url) {
+  return /^https?:/i.test(url) ? `//${truncateUrl(url, MAX_VALUE_LENGTH - 2)}` : url;
+}
+function shortValue(tag, name, value) {
+  let short = value;
+  if (name === "src") short = tag === "iframe" ? hostOf(value) : fileName(value);
+  else if (name === "href" || name === "action") short = shortUrl(value);
+  return cutMiddle(escapeControlChars(short.replace(/\s+/g, " ").trim()), MAX_VALUE_LENGTH);
+}
+function keyAttributeItems(tag, attributes, leaveOut = /* @__PURE__ */ new Set()) {
+  return Object.entries(attributes ?? {}).flatMap(([name, value]) => {
+    if (leaveOut.has(name) || value === false) return [];
+    if (value === true) return [name];
+    return [`${name}="${shortValue(tag, name, value)}"`];
+  });
+}
+
+// src/commands/dom/semanticUtils.ts
+init_formatting();
+init_commands();
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function buildRoleText(node) {
+  if (node.role.toLowerCase() === "heading" && node.properties?.["level"] !== void 0) {
+    const level = node.properties["level"];
+    const levelNum = typeof level === "number" ? level : Number(level);
+    if (!isNaN(levelNum)) {
+      return `[Heading L${levelNum}]`;
+    }
+  }
+  return `[${capitalize(node.role)}]`;
+}
+function buildContextText(node, domContext) {
+  if (node.name) {
+    return ` "${node.name}"`;
+  }
+  if (domContext) {
+    const tagPart = `<${domContext.tag}`;
+    const classPart = domContext.classes && domContext.classes.length > 0 ? `.${domContext.classes.slice(0, 3).join(".")}` : "";
+    const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : "";
+    return ` ${tagPart}${classPart}>${previewPart}`;
+  }
+  return "";
+}
+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 !== void 0 && 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 !== void 0 && node.value !== "") props.push(`value: "${node.value}"`);
+  const checked = node.properties?.["checked"];
+  if (checked !== void 0) {
+    props.push(checked === "mixed" ? "partly checked" : checked ? "checked" : "unchecked");
+  }
+  const expanded = node.properties?.["expanded"];
+  if (expanded !== void 0) props.push(expanded ? "expanded" : "collapsed");
+  if (node.focusable) props.push("focusable");
+  if (node.focused) props.push("focused");
+  if (node.disabled) props.push("disabled");
+  if (node.required) props.push("required");
+  return props.length > 0 ? ` (${props.join(", ")})` : "";
+}
+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}${keysText}${propsText}${inferredText}`;
+  if (domContext?.text) return joinLines(line, elementTextLine(domContext.text));
+  if (domContext?.childCount !== void 0 && !node.name) {
+    return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
+  }
+  return line;
+}
+function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
+  if (a11yNode) return withSecretMasked(a11yNode, domContext);
+  if (domContext && nodeId) return synthesizeA11yNode(domContext, nodeId);
+  return null;
+}
+function withSecretMasked(node, domContext) {
+  if (!domContext?.sensitive || !node.value) return node;
+  return { ...node, value: MASKED_VALUE };
+}
+
+// src/commands/dom/a11y.ts
+init_errors3();
+init_messages();
+
+// src/telemetry/a11y.ts
+init_errors3();
+init_messages();
+init_client();
+init_elementInfo();
+
+// src/runtime/dom/frameLayout.ts
+init_frameScopedConnection();
+init_logging();
+init_errors();
+var log19 = createLogger("dom");
+function childFrameIds(tree) {
+  return (tree?.childFrames ?? []).flatMap((child) => [child.frame.id, ...childFrameIds(child)]);
+}
+
+// src/telemetry/a11y.ts
+init_concurrency();
+init_exitCodes();
+init_levenshtein();
+function buildTreeFromRawNodes(rawNodes) {
+  const rawById = new Map(rawNodes.map((rawNode) => [rawNode.nodeId, rawNode]));
+  const rootRaw = rawNodes.find((rawNode) => !rawNode.ignored);
+  if (!rootRaw) {
+    throw new CommandError(
+      "No root node found in accessibility tree",
+      { suggestion: "The page may not be fully loaded. Wait and retry." },
+      EXIT_CODES.SOFTWARE_ERROR
+    );
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  const visit = (rawNode) => {
     if (nodes.has(rawNode.nodeId)) return;
     const node = parseA11yNode(rawNode);
     const childIds = visibleChildIds(rawNode, rawById);
@@ -13562,11 +14216,60 @@ async function collectA11yTree() {
         EXIT_CODES.SOFTWARE_ERROR
       );
     }
-    return buildTreeFromRawNodes([...result.nodes, ...await collectFrameNodes(result.nodes)]);
+    const tree = buildTreeFromRawNodes([
+      ...result.nodes,
+      ...await collectFrameNodes(result.nodes)
+    ]);
+    return maskSecretValues(tree, await sensitiveNodeIds(tree));
   } finally {
     await callCDP("Accessibility.disable", {});
   }
 }
+var SENSITIVE_CHECK_CONCURRENCY = 10;
+async function sensitiveNodeIds(tree) {
+  const candidates = [...tree.nodes.values()].filter(
+    (node) => node.value !== void 0 && node.backendDOMNodeId !== void 0
+  );
+  const limiter = new ConcurrencyLimiter(SENSITIVE_CHECK_CONCURRENCY);
+  const checked = await Promise.all(
+    candidates.map(
+      (node) => limiter.run(
+        async () => await isSensitiveField(node.backendDOMNodeId ?? 0) ? node.nodeId : null
+      )
+    )
+  );
+  return new Set(checked.filter((id) => id !== null));
+}
+async function isSensitiveField(backendNodeId) {
+  const objectGroup = "bdg-a11y-secret";
+  const resolved = await callCDP("DOM.resolveNode", { backendNodeId, objectGroup });
+  const objectId = resolved.data?.result?.object?.objectId;
+  if (!objectId) return true;
+  try {
+    const response = await callCDP("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function () { return this.nodeType !== 1 || (${SENSITIVE_FIELD_JS})(this); }`,
+      returnByValue: true
+    });
+    const value = response.data?.result?.result?.value;
+    return value !== false;
+  } finally {
+    await callCDP("Runtime.releaseObjectGroup", { objectGroup });
+  }
+}
+function maskSecretValues(tree, secretIds) {
+  const hide = (nodeId, inside) => {
+    const node = tree.nodes.get(nodeId);
+    if (!node) return;
+    const { name: _name, value: _value, ...rest } = node;
+    const masked = inside ? rest : { ...node, ...node.value !== void 0 && { value: MASKED_VALUE } };
+    tree.nodes.set(nodeId, masked);
+    if (tree.root.nodeId === nodeId) tree.root = masked;
+    node.childIds?.forEach((childId) => hide(childId, true));
+  };
+  secretIds.forEach((nodeId) => hide(nodeId, false));
+  return tree;
+}
 async function collectFrameNodes(pageNodes) {
   const tree = (await callCDP("Page.getFrameTree", {})).data?.result;
   const known = [...pageNodes];
@@ -13913,7 +14616,7 @@ function formatA11yNodeWithContext(data) {
 }
 function formatA11yNodeOneLine(node) {
   const parts = [];
-  parts.push(`[${capitalize(node.role)}]`);
+  parts.push(`[${capitalize2(node.role)}]`);
   if (node.name) {
     parts.push(`"${node.name}"`);
   }
@@ -13942,7 +14645,7 @@ function formatA11yNodeOneLine(node) {
   }
   return parts.join(" ");
 }
-function capitalize(str) {
+function capitalize2(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 function truncate(str, maxLen) {
@@ -14051,7 +14754,7 @@ async function handleA11yDescribe(selectorOrIndex, options) {
     if (domNodeId) {
       domContext = await getDomContext({ backendNodeId: domNodeId });
     }
-    return { node, domContext };
+    return { node: withSecretMasked(node, domContext), domContext };
   }
   if (options.json) {
     await runJsonCommand(fetchA11yNodeData);
@@ -14118,13 +14821,7 @@ function formatDomQuery(data) {
   const { count, nodes, selector } = data;
   const fmt = new OutputFormatter();
   const nodeLines = nodes.slice(0, QUERY_DISPLAY_LIMIT).map((node) => {
-    const attributes = [
-      node.id && ` id="${node.id}"`,
-      node.name && ` name="${node.name}"`,
-      node.type && ` type="${node.type}"`,
-      node.value !== void 0 && ` value="${node.value}"`,
-      node.classes?.length && ` class="${node.classes.join(" ")}"`
-    ].filter(Boolean).join("");
+    const attributes = queryTagAttributes(node).map((item) => ` ${item}`).join("");
     const context = node.context ? ` (in ${node.context})` : "";
     const preview = node.preview ? ` ${node.preview}` : "";
     const position = node.inViewport && viewportPositionHint(node.inViewport, node.clippedBy);
@@ -14134,6 +14831,18 @@ function formatDomQuery(data) {
   const exampleIndex = nodes[0]?.index ?? 0;
   return fmt.text(`Found ${count} node${count === 1 ? "" : "s"} matching "${selector}":`).list(nodeLines).list(count > QUERY_DISPLAY_LIMIT ? [moreMatchesNote(count - QUERY_DISPLAY_LIMIT)] : []).tip(queryNextSteps(exampleIndex)).build();
 }
+function queryTagAttributes(node) {
+  const identifying = {
+    ...node.name && { name: node.name },
+    ...node.type && { type: node.type },
+    ...node.value !== void 0 && { value: node.value }
+  };
+  return [
+    ...node.id ? [`id="${node.id}"`] : [],
+    ...keyAttributeItems(node.tag ?? "", { ...identifying, ...node.attributes }),
+    ...node.classes?.length ? [`class="${node.classes.join(" ")}"`] : []
+  ];
+}
 function formatDomGet(data) {
   const { nodes } = data;
   if (nodes.length === 1) {
@@ -14820,190 +15529,31 @@ async function withReadyState(frames) {
 
 // src/commands/dom/get.ts
 init_helpers();
-
-// src/telemetry/roleInference.ts
-var IMPLICIT_ARIA_ROLES = {
-  // Interactive elements
-  a: "link",
-  button: "button",
-  input: "textbox",
-  select: "combobox",
-  textarea: "textbox",
-  option: "option",
-  // Headings
-  h1: "heading",
-  h2: "heading",
-  h3: "heading",
-  h4: "heading",
-  h5: "heading",
-  h6: "heading",
-  // Landmarks
-  nav: "navigation",
-  main: "main",
-  header: "banner",
-  footer: "contentinfo",
-  aside: "complementary",
-  section: "region",
-  article: "article",
-  form: "form",
-  search: "search",
-  // Media
-  img: "image",
-  figure: "figure",
-  figcaption: "caption",
-  video: "video",
-  audio: "audio",
-  // Lists
-  ul: "list",
-  ol: "list",
-  li: "listitem",
-  dl: "list",
-  dt: "term",
-  dd: "definition",
-  menu: "menu",
-  menuitem: "menuitem",
-  // Tables
-  table: "table",
-  thead: "rowgroup",
-  tbody: "rowgroup",
-  tfoot: "rowgroup",
-  tr: "row",
-  th: "columnheader",
-  td: "cell",
-  // Other semantic elements
-  dialog: "dialog",
-  details: "group",
-  summary: "button",
-  progress: "progressbar",
-  meter: "meter",
-  output: "status",
-  address: "group",
-  blockquote: "blockquote",
-  code: "code",
-  pre: "group",
-  hr: "separator"
-};
-var DEFAULT_ROLE = "generic";
-var MAX_NAME_LENGTH = 100;
-function inferRoleFromTag(tag) {
-  const normalizedTag = tag.toLowerCase();
-  return IMPLICIT_ARIA_ROLES[normalizedTag] ?? DEFAULT_ROLE;
-}
-function extractHeadingLevel(tag) {
-  const match = tag.toLowerCase().match(/^h([1-6])$/);
-  const level = match?.[1];
-  if (!level) {
-    return null;
+init_errors3();
+init_messages();
+init_exitCodes();
+var DOM_GET_DEFAULT_SELECTOR = "body";
+async function targetNodeId(selectorOrIndex, index) {
+  const resolver = DomElementResolver.getInstance();
+  if (resolver.isNumericIndex(selectorOrIndex)) {
+    return (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId;
   }
-  return parseInt(level, 10);
+  return selectMatch(selectorOrIndex, index ?? 0);
 }
-function synthesizeA11yNode(domContext, nodeId) {
-  const role = inferRoleFromTag(domContext.tag);
-  const node = {
-    nodeId: String(nodeId),
-    role,
-    inferred: true,
-    backendDOMNodeId: nodeId
-  };
-  if (domContext.preview) {
-    const name = domContext.preview.length > MAX_NAME_LENGTH ? domContext.preview.slice(0, MAX_NAME_LENGTH - 3) + "..." : domContext.preview;
-    node.name = name;
-  }
-  const headingLevel = extractHeadingLevel(domContext.tag);
-  if (headingLevel !== null) {
-    node.properties = { level: headingLevel };
-  }
-  return node;
-}
-
-// src/commands/dom/semanticUtils.ts
-init_formatting();
-init_commands();
-function capitalize2(str) {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-}
-function buildRoleText(node) {
-  if (node.role.toLowerCase() === "heading" && node.properties?.["level"] !== void 0) {
-    const level = node.properties["level"];
-    const levelNum = typeof level === "number" ? level : Number(level);
-    if (!isNaN(levelNum)) {
-      return `[Heading L${levelNum}]`;
-    }
-  }
-  return `[${capitalize2(node.role)}]`;
-}
-function buildContextText(node, domContext) {
-  if (node.name) {
-    return ` "${node.name}"`;
-  }
-  if (domContext) {
-    const tagPart = `<${domContext.tag}`;
-    const classPart = domContext.classes && domContext.classes.length > 0 ? `.${domContext.classes.slice(0, 3).join(".")}` : "";
-    const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : "";
-    return ` ${tagPart}${classPart}>${previewPart}`;
-  }
-  return "";
-}
-function buildPropertiesText(node) {
-  const props = [];
-  if (node.value !== void 0 && node.value !== "") props.push(`value: "${node.value}"`);
-  const checked = node.properties?.["checked"];
-  if (checked !== void 0) {
-    props.push(checked === "mixed" ? "partly checked" : checked ? "checked" : "unchecked");
-  }
-  const expanded = node.properties?.["expanded"];
-  if (expanded !== void 0) props.push(expanded ? "expanded" : "collapsed");
-  if (node.focusable) props.push("focusable");
-  if (node.focused) props.push("focused");
-  if (node.disabled) props.push("disabled");
-  if (node.required) props.push("required");
-  return props.length > 0 ? ` (${props.join(", ")})` : "";
-}
-function formatSemanticNodeWithContext(data) {
-  const { node, domContext } = data;
-  const roleText = buildRoleText(node);
-  const contextText = buildContextText(node, domContext);
-  const propsText = buildPropertiesText(node);
-  const inferredText = node.inferred ? " (inferred from DOM)" : "";
-  const line = `${roleText}${contextText}${propsText}${inferredText}`;
-  if (domContext?.text) return joinLines(line, elementTextLine(domContext.text));
-  if (domContext?.childCount !== void 0 && !node.name) {
-    return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
-  }
-  return line;
-}
-function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
-  if (a11yNode) return a11yNode;
-  if (domContext && nodeId) return synthesizeA11yNode(domContext, nodeId);
-  return null;
-}
-
-// src/commands/dom/get.ts
-init_errors3();
-init_messages();
-init_exitCodes();
-var DOM_GET_DEFAULT_SELECTOR = "body";
-async function targetNodeId(selectorOrIndex, index) {
-  const resolver = DomElementResolver.getInstance();
-  if (resolver.isNumericIndex(selectorOrIndex)) {
-    return (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId;
-  }
-  return selectMatch(selectorOrIndex, index ?? 0);
-}
-async function semanticElement(backendNodeId, full) {
-  const ref = { backendNodeId };
-  const [a11yNode, domContext] = await Promise.all([
-    resolveA11yNode(ref),
-    getDomContext(ref, { full })
-  ]);
-  const node = resolveNodeWithFallback(a11yNode, domContext, backendNodeId);
-  if (!node) {
-    const err = nodeIdNotFoundError(backendNodeId);
-    throw new CommandError(
-      err.message,
-      { suggestion: err.suggestion },
-      EXIT_CODES.RESOURCE_NOT_FOUND
-    );
+async function semanticElement(backendNodeId, full) {
+  const ref = { backendNodeId };
+  const [a11yNode, domContext] = await Promise.all([
+    resolveA11yNode(ref),
+    getDomContext(ref, { full })
+  ]);
+  const node = resolveNodeWithFallback(a11yNode, domContext, backendNodeId);
+  if (!node) {
+    const err = nodeIdNotFoundError(backendNodeId);
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.RESOURCE_NOT_FOUND
+    );
   }
   return { node, domContext };
 }
@@ -15078,6 +15628,441 @@ async function handleDomGet(selectorOrIndex, options) {
   else await handleSemanticGet(target, options);
 }
 
+// src/commands/dom/inspect.ts
+init_client();
+
+// src/utils/color.ts
+var D50_WHITE = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
+
+// src/utils/cssValues.ts
+function sidesShorthand(sides) {
+  const [top, right, bottom, left] = sides.map(String);
+  if (top === right && right === bottom && bottom === left) return `${top}`;
+  if (top === bottom && right === left) return `${top} ${right}`;
+  if (right === left) return `${top} ${right} ${bottom}`;
+  return `${top} ${right} ${bottom} ${left}`;
+}
+function shadowText(layer, withSpread = true) {
+  const lengths = [layer.x, layer.y, layer.blur, ...withSpread ? [layer.spread] : []];
+  return `${layer.inset ? "inset " : ""}${layer.color} ${lengths.join(" ")}`;
+}
+
+// src/runtime/dom/inspectLayoutModel.ts
+function containerKind(display) {
+  if (display === void 0) return void 0;
+  if (/(^|-)flex$/.test(display) || display === "-webkit-box") return "flex";
+  return /(^|-)grid$/.test(display) ? "grid" : void 0;
+}
+
+// src/runtime/dom/inspectTree.ts
+var DEFAULT_TREE_DEPTH = 2;
+var DEFAULT_TREE_LIMIT = 20;
+
+// src/ui/formatters/inspect.ts
+init_formatting();
+init_commands();
+init_strings();
+var PARENT_LABEL_MAX = 40;
+var LABEL_WIDTH = 7;
+var ALL_LINE_WIDTH = 100;
+function groupLine(label, parts) {
+  const shown = parts.filter((part) => Boolean(part));
+  return shown.length > 0 ? `${label.padEnd(LABEL_WIDTH)}${shown.join(" \xB7 ")}` : void 0;
+}
+function inspectHeader(data) {
+  const display = data.layout?.display ?? data.all?.["display"];
+  const kind = containerKind(display);
+  return [
+    data.element,
+    data.content !== void 0 && `"${data.content}"`,
+    data.placeholder !== void 0 && `placeholder "${data.placeholder}"`,
+    data.rect && `${data.rect.w}x${data.rect.h} @${data.rect.x},${data.rect.y}`,
+    kind && `[${kind}]`,
+    ...inspectVisibilityBadges(data.visibility),
+    data.context && `in ${data.context}`,
+    data.theme === "dark" && inspectDarkThemeBadge(),
+    data.animating && inspectAnimatingBadge(data.animating)
+  ].filter(Boolean).join(" ");
+}
+function zero(sides) {
+  return sides.every((side) => side === 0);
+}
+function limitParts(kind, limits) {
+  if (!limits) return [];
+  return [
+    limits.w !== void 0 ? `${kind}-w ${limits.w}` : "",
+    limits.h !== void 0 ? `${kind}-h ${limits.h}` : ""
+  ].filter(Boolean);
+}
+function boxLine(box) {
+  const padded = !zero(box.padding) || !zero(box.border);
+  return groupLine("box", [
+    !zero(box.margin) && `m ${sidesShorthand(box.margin)}`,
+    !zero(box.padding) && `p ${sidesShorthand(box.padding)}`,
+    !zero(box.border) && `b ${sidesShorthand(box.border)}`,
+    padded && box.sizing === "content-box" && "sizing content-box",
+    ...limitParts("min", box.min),
+    ...limitParts("max", box.max),
+    box.overflow && `overflow ${box.overflow}`,
+    box.scroll && `scroll ${box.scroll.w}x${box.scroll.h}`
+  ]);
+}
+function containerParts(container) {
+  const gap = Array.isArray(container.gap) ? container.gap.join(" ") : container.gap;
+  return [
+    container.wrap && `wrap ${container.wrap}`,
+    container.columns && `cols ${container.columns}`,
+    container.rows && `rows ${container.rows}`,
+    container.justify && `justify ${container.justify}`,
+    container.align && `align ${container.align}`,
+    gap !== void 0 && `gap ${gap}`
+  ].filter((part) => Boolean(part));
+}
+function displayWords(display, direction) {
+  return direction ? `${display} ${direction}` : display;
+}
+function layoutLine(layout) {
+  return groupLine("layout", [
+    displayWords(layout.display, layout.direction),
+    layout.position && `position ${layout.position}`,
+    layout.inset && `inset ${sidesShorthand(layout.inset)}`,
+    layout.z !== void 0 && `z ${layout.z}`,
+    ...containerParts(layout),
+    layout.flex && `flex ${layout.flex}`,
+    layout.self && `self ${layout.self}`,
+    layout.order !== void 0 && `order ${layout.order}`,
+    layout.area && `area ${layout.area}`,
+    layout.valign && `valign ${layout.valign}`,
+    layout.float && `float ${layout.float}`
+  ]);
+}
+function parentLine(layout) {
+  const parent = layout.parent;
+  const offsets = layout.inParent;
+  const gaps = Object.entries(layout.siblings ?? {}).map(([side, gap]) => `${side[0]}${gap}`);
+  const parentWords = parent && [
+    truncateByLength(parent.element, PARENT_LABEL_MAX),
+    displayWords(parent.display, parent.direction),
+    ...containerParts(parent),
+    parent.textAlign && `text-align ${parent.textAlign}`
+  ];
+  return groupLine("parent", [
+    parentWords?.filter(Boolean).join(" "),
+    offsets && `in-parent l${offsets.left} t${offsets.top} r${offsets.right} b${offsets.bottom}`,
+    gaps.length > 0 && `sib ${gaps.join(" ")}`
+  ]);
+}
+function fontParts(text) {
+  const loaded = [
+    text.rendered && `rendered "${text.rendered}"`,
+    text.webfont && "webfont loaded"
+  ].filter(Boolean);
+  const family = text.family && [text.family, loaded.length > 0 && `(${loaded.join(", ")})`];
+  const size = text.size !== void 0 && (text.lineHeight !== void 0 ? `${text.size}/${text.lineHeight}` : `${text.size}`);
+  if (family && text.weight !== void 0 && size) {
+    return [
+      [...family, text.weight, text.style, size].filter((part) => part !== void 0 && part !== false && part !== "").join(" ")
+    ];
+  }
+  return [
+    family && `font ${family.filter(Boolean).join(" ")}`,
+    text.weight !== void 0 && `weight ${text.weight}`,
+    text.style && `style ${text.style}`,
+    size && `size ${size}`,
+    !size && text.lineHeight !== void 0 && `line-height ${text.lineHeight}`
+  ].filter((part) => Boolean(part));
+}
+function contrastText(contrast) {
+  if (!contrast) return void 0;
+  return [
+    `contrast ${contrast.ratio} ${contrast.level}`,
+    contrast.inherited && `on ${contrast.background}`,
+    contrast.overImage && "(over image)",
+    contrast.opacity !== void 0 && `(faded: opacity ${contrast.opacity})`
+  ].filter(Boolean).join(" ");
+}
+function textLine(text) {
+  return groupLine("text", [
+    ...fontParts(text),
+    text.color && `color ${text.color}`,
+    contrastText(text.contrast),
+    text.align && `align ${text.align}`,
+    text.transform && `transform ${text.transform}`,
+    text.tracking !== void 0 && `tracking ${text.tracking}`,
+    text.decoration && `decoration ${text.decoration}`,
+    text.whiteSpace && `ws ${text.whiteSpace}`,
+    text.overflow && `text-overflow ${text.overflow}`,
+    text.clamp && `clamp ${text.clamp}`,
+    text.shadow && `shadow ${text.shadow}`,
+    text.features && `features ${text.features}`
+  ]);
+}
+function fillText(fill) {
+  if (fill.type === "solid") return `bg ${fill.color}`;
+  if (fill.type === "gradient") return `bg-image ${fill.value}`;
+  return `bg-image ${fill.value}${fill.size ? ` size ${fill.size}` : ""}`;
+}
+function fillLine(data) {
+  return groupLine("fill", [
+    ...(data.fills ?? []).map(fillText),
+    data.opacity !== void 0 && `opacity ${data.opacity}`,
+    data.blend && `blend ${data.blend}`
+  ]);
+}
+function borderLine(data) {
+  const outline = data.outline;
+  return groupLine("border", [
+    ...(data.strokes ?? []).map(
+      (s) => `${s.side === "all" ? "" : `${s.side} `}${s.width} ${s.style} ${s.color}`
+    ),
+    data.radius && `radius ${sidesShorthand(data.radius)}`,
+    outline && `outline ${outline.width} ${outline.style} ${outline.color}${outline.offset ? ` offset ${outline.offset}` : ""}`
+  ]);
+}
+function fxLine(data) {
+  const shadows = (data.effects ?? []).map(
+    (e) => shadowText({ ...e, inset: e.type === "inner-shadow" })
+  );
+  const fx = data.fx ?? {};
+  return groupLine("fx", [
+    shadows.length > 0 && `shadow ${shadows.join(", ")}`,
+    fx.transform && `transform ${fx.transform}`,
+    fx.filter && `filter ${fx.filter}`,
+    fx.backdrop && `backdrop ${fx.backdrop}`,
+    fx.clip && `clip ${fx.clip}`,
+    fx.mask && `mask ${fx.mask}`,
+    fx.animation && `animation ${fx.animation}`
+  ]);
+}
+function stateLine(data) {
+  const state = data.state ?? {};
+  return groupLine("state", [
+    state.cursor && `cursor ${state.cursor}`,
+    state.pointerEvents && `pointer-events ${state.pointerEvents}`,
+    state.visibility && `visibility ${state.visibility}`,
+    state.userSelect && `select ${state.userSelect}`,
+    state.appearance && `appearance ${state.appearance}`
+  ]);
+}
+function pseudoText(pseudo) {
+  const shadows = (pseudo.effects ?? []).map(
+    (e) => shadowText({ ...e, inset: e.type === "inner-shadow" })
+  );
+  return [
+    pseudo.type,
+    pseudo.content !== void 0 && `content ${pseudo.content}`,
+    pseudo.display,
+    pseudo.position,
+    pseudo.size && `${pseudo.size.w}x${pseudo.size.h}`,
+    pseudo.color && `color ${pseudo.color}`,
+    pseudo.fontStyle,
+    pseudo.fontWeight !== void 0 && `weight ${pseudo.fontWeight}`,
+    pseudo.contrast && `\xB7 ${contrastText(pseudo.contrast)}`,
+    ...(pseudo.fills ?? []).map(fillText),
+    pseudo.radius && `radius ${pseudo.radius}`,
+    shadows.length > 0 && `shadow ${shadows.join(", ")}`,
+    pseudo.transform && `transform ${pseudo.transform}`,
+    pseudo.opacity !== void 0 && `opacity ${pseudo.opacity}`
+  ].filter(Boolean).join(" ");
+}
+function pseudoLines(pseudo) {
+  return (pseudo ?? []).map(
+    (entry, i) => `${(i === 0 ? "pseudo" : "").padEnd(LABEL_WIDTH)}${pseudoText(entry)}`
+  );
+}
+function treeRow(node) {
+  return [
+    node.element,
+    node.count !== void 0 && `\xD7${node.count}`,
+    `${node.w}x${node.h}`,
+    node.layout && `[${node.layout}]`,
+    node.text && `"${node.text}"`,
+    node.childCount !== void 0 && `(${node.childCount})`
+  ].filter(Boolean).join(" ");
+}
+function treeLines2(nodes, hidden, depth) {
+  const indent = "  ".repeat(depth);
+  const lines = nodes.flatMap((node) => [
+    `${indent}${treeRow(node)}`,
+    ...treeLines2(node.children ?? [], node.hiddenChildren, depth + 1)
+  ]);
+  return hidden ? [...lines, `${indent}(+${hidden} not rendered)`] : lines;
+}
+function labelledLines(label, lines) {
+  return lines.map((line, i) => `${i === 0 ? label.padEnd(6) : "".padEnd(6)} ${line}`);
+}
+function ruleScope(entry) {
+  return [entry.condition && ` @${entry.condition}`, entry.layer && ` layer ${entry.layer}`].filter(Boolean).join("");
+}
+function cascadeBlock(data) {
+  const hints = (data.hints ?? []).map(
+    (hint) => `${hint.property}: ${hint.value} ${hint.kind === "not-inherited" ? "is the browser's" : "has no effect"}: ${hint.reason} \u2192 ${hint.fix} \xB7 in ${hint.source}`
+  );
+  return [
+    ...labelledLines("hints", data.hints?.length === 0 ? ["none"] : hints),
+    ...labelledLines("rules", (data.rules ?? []).map(ruleLine)),
+    ...labelledLines(
+      "why",
+      (data.why ?? []).flatMap((why) => whyLines(why, data))
+    ),
+    ...data.cascade ? [inspectCascadeNote(data.cascade)] : []
+  ];
+}
+function ruleLine(rule) {
+  return [
+    `${rule.property} ${truncateByLength(rule.value, CASCADE_VALUE_WIDTH)}`,
+    rule.computed !== void 0 && ` = ${truncateByLength(rule.computed, CASCADE_VALUE_WIDTH)}`,
+    `${rule.important ? " !important" : ""} \u2190 ${rule.source}`,
+    ruleScope(rule),
+    rule.inherited !== void 0 && ` (inherited from ${levelsUp(rule.inherited)})`,
+    rule.overrides && ` over ${rule.overrides.join(", ")}`
+  ].filter(Boolean).join("");
+}
+function whyLines(why, data) {
+  const entries = why.chain.map((entry) => {
+    const value = `${entry.via ? `${entry.via}: ` : ""}${entry.value}`;
+    const resolved = entry.unset ? ` = invalid: ${entry.unset.join(", ")} not set` : entry.resolved !== void 0 ? ` = ${truncateByLength(entry.resolved, CASCADE_VALUE_WIDTH)}` : "";
+    return [
+      `  ${entry.status === "overridden" ? "\u2717" : "\u2713"} `,
+      truncateByLength(value, CASCADE_VALUE_WIDTH) + resolved,
+      entry.important ? " !important" : "",
+      `  ${entry.source}${entry.specificity ? ` [${entry.specificity.join(",")}]` : ""}${ruleScope(entry)}`,
+      entry.status === "inherited" ? " (inherited)" : ""
+    ].join("");
+  });
+  const variables = (why.variables ?? []).map(
+    (variable) => `    ${variable.name}: ${truncateByLength(variable.value, CASCADE_VALUE_WIDTH)}  ${variable.source}${variable.inherited !== void 0 ? ` (inherited from ${levelsUp(variable.inherited)})` : ""}`
+  );
+  return [
+    `${why.property} = ${why.computed}${midTransition(why.property, data.animating) ? ` ${inspectMidTransitionNote()}` : ""}`,
+    ...entries.slice(0, 1),
+    ...variables,
+    ...entries.slice(1),
+    ...why.chain.length === 0 ? ["  no author declaration: the default or inherited value"] : []
+  ];
+}
+function midTransition(property, animating) {
+  return (animating ?? []).some(
+    (name) => name === "all" || name === property || property.startsWith(`${name}-`) || name.startsWith(`${property}-`)
+  );
+}
+function levelsUp(levels) {
+  return levels === 1 ? "the parent" : `${levels} levels up`;
+}
+var CASCADE_VALUE_WIDTH = 60;
+function treeBlock(data) {
+  if (!data.children && !data.hiddenChildren) return [];
+  return [
+    "tree",
+    ...treeLines2(data.children ?? [], data.hiddenChildren, 1),
+    ...data.moreRows ? [`  \u2026 +${data.moreRows} more`] : []
+  ];
+}
+function allLines(all) {
+  const lines = [];
+  let current = [];
+  for (const [name, value] of Object.entries(all)) {
+    current.push(`${name} ${value}`);
+    if (current.join(" \xB7 ").length > ALL_LINE_WIDTH) {
+      lines.push(current.join(" \xB7 "));
+      current = [];
+    }
+  }
+  if (current.length > 0) lines.push(current.join(" \xB7 "));
+  return lines.map((line, i) => `${(i === 0 ? "all" : "").padEnd(LABEL_WIDTH)}${line}`);
+}
+function propLines(props) {
+  if (Object.keys(props).length === 0) return ["(no matching custom properties)"];
+  return Object.entries(props).map(
+    ([name, prop]) => `${name}: ${prop.computed || (name.startsWith("--") ? "(not set)" : "(empty)")}${prop.value !== prop.computed ? ` = ${prop.value}` : ""}`
+  );
+}
+function groupLines(data) {
+  return [
+    data.box && boxLine(data.box),
+    data.layout && layoutLine(data.layout),
+    data.layout && parentLine(data.layout),
+    data.text && textLine(data.text),
+    fillLine(data),
+    borderLine(data),
+    fxLine(data),
+    stateLine(data),
+    ...pseudoLines(data.pseudo)
+  ];
+}
+function formatInspect(data) {
+  const body = data.props ? propLines(data.props) : data.all ? allLines(data.all) : groupLines(data);
+  const note = data.picked ? multipleMatchesWarning(data.count, inspectedMatchAction(data.picked, data.index)) : void 0;
+  if (data.why) return joinLines(inspectHeader(data), ...cascadeBlock(data), note);
+  return joinLines(inspectHeader(data), ...body, ...cascadeBlock(data), ...treeBlock(data), note);
+}
+
+// src/commands/dom/inspect.ts
+init_commands();
+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);
+  });
+}
+function propertyOption(value) {
+  return value.startsWith("--") ? value.trim() : value.trim().toLowerCase();
+}
+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>"'
+  });
+}
+
 // src/commands/dom/layout.ts
 init_client();
 
@@ -15086,13 +16071,13 @@ init_messages();
 init_formatting();
 init_commands();
 var LAYOUT_DISPLAY_LIMIT = 20;
-function layoutLine(element, viewport) {
+function layoutLine2(element, viewport) {
   const { bounds } = element;
   return [
     `[${element.index}] ${element.element}${element.text ? ` "${element.text}"` : ""}`,
     element.inViewport !== "hidden" && `${bounds.x},${bounds.y} ${bounds.width}\xD7${bounds.height}`,
     layoutPositionLabel(element, viewport),
-    element.coveredBy && `covered by ${element.coveredBy}`,
+    element.coveredBy && coverText(element.coveredBy, element.coverTransparent),
     element.inert && "inert",
     element.invisible,
     element.context && element.context !== element.clippedBy && `in ${element.context}`
@@ -15103,14 +16088,14 @@ function formatLayout(data) {
   const more = data.elements.length - shown.length + (data.omitted ?? 0);
   return new OutputFormatter().text(pageLayoutLine(data.page)).text(
     data.indexSource ? indexLayoutHeadline(indexSourceText(data.indexSource)) : layoutHeadline(data.count, data.elements.length + (data.omitted ?? 0), data.selector)
-  ).list(shown.map((element) => layoutLine(element, data.page.viewport))).list(more > 0 ? [moreMatchesNote(more, data.omitted ? data.elements.length : void 0)] : []).build();
+  ).list(shown.map((element) => layoutLine2(element, data.page.viewport))).list(more > 0 ? [moreMatchesNote(more, data.omitted ? data.elements.length : void 0)] : []).build();
 }
 
 // src/commands/dom/layout.ts
 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)").option("--index <n>", "Only this match of the selector (0-based)", integerOption(0)).addOption(jsonOption()).action(async (selectorOrIndex, options) => {
+  ).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) => {
     await runCommand(() => measureLayout(selectorOrIndex, options), options, formatLayout);
   });
 }
@@ -15295,7 +16280,7 @@ function appendListenerGroups(fmt, listeners) {
 
 // src/commands/dom/listeners.ts
 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)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option(
+  dom.command("listeners").description("List event listeners that run for an element (incl. delegated ones on ancestors)").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
@@ -15638,25 +16623,28 @@ function registerDomCommands(program2) {
   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").action(async (selector, options) => {
+  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);
   });
   dom.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)"
+    "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);
   });
   program2.command("eval", { hidden: true }).description("Shortcut for: bdg dom eval").argument("<script>", "JavaScript to execute").option("--frame <frame>", "Evaluate in an iframe (see dom frames)").option("-j, --json", "Output as JSON").action(async (script, options) => {
     await handleDomEval(script, options);
   });
-  dom.command("frames").description("List the page's iframes (nested and cross-origin ones included) for eval --frame").option("-j, --json", "Output as JSON").action(async (options) => {
+  dom.command("frames").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);
   });
   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}`
+    `${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)").option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).addOption(new Option("--nth <n>", "Alias of --index").argParser(integerOption(0)).hideHelp()).option(
     "--node-id <id>",
     "Get the element with this node id (from dom query/get --raw or a11y describe; implies --raw)",
@@ -16307,6 +17295,7 @@ init_commands();
 // src/ui/messages/session.ts
 init_formatting();
 init_commands();
+init_sessionCommand();
 function startNotices(options) {
   const { documentStatus, loading, autoStopAt, session } = options;
   return [
@@ -16353,6 +17342,13 @@ function lastSessionEndText(end) {
   const at = new Date(end.endedAt).toLocaleTimeString();
   return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
 }
+function daemonStillExitingHint(pid, waitedMs) {
+  const daemon = pid === void 0 ? "The daemon" : `The daemon (PID ${pid})`;
+  return `${daemon} was still shutting down after ${waitedMs / 1e3}s`;
+}
+function daemonStillExitingSuggestion() {
+  return `check with bdg sessions, or end it with ${sessionCommand("bdg cleanup --force")}`;
+}
 
 // src/ui/formatters/status.ts
 init_sessionCommand();
@@ -16438,7 +17434,7 @@ function appearanceLines(metadata, pageState) {
     ...viewport ? [
       [
         "Viewport",
-        `${viewport.width}\xD7${viewport.height}${metadata.viewport ? ` (--viewport ${metadata.viewport.width}x${metadata.viewport.height})` : ""}`
+        `${viewport.width}\xD7${viewport.height}${metadata.viewport ? ` (emulated ${metadata.viewport.width}x${metadata.viewport.height})` : ""}`
       ]
     ] : [],
     ...scheme ? [
@@ -16691,42 +17687,6 @@ function formatPreviewVerbose(output, options) {
   return fmt.build();
 }
 
-// src/ui/formatters/networkHeaders.ts
-init_formatting();
-function formatNetworkHeaders(data) {
-  const fmt = new OutputFormatter();
-  fmt.text("Network Request Headers").separator("\u2501", 60).blank();
-  fmt.text("URL:").text(`  ${data.url}`).blank();
-  fmt.text(`Status: ${requestStatusLine(data)}`).blank();
-  if (Object.keys(data.responseHeaders).length > 0) {
-    fmt.text("Response Headers:");
-    formatHeaderSection(fmt, data.responseHeaders);
-    fmt.blank();
-  }
-  if (Object.keys(data.requestHeaders).length > 0) {
-    fmt.text("Request Headers:");
-    formatHeaderSection(fmt, data.requestHeaders);
-    fmt.blank();
-  }
-  if (Object.keys(data.responseHeaders).length === 0 && Object.keys(data.requestHeaders).length === 0) {
-    fmt.text("No headers found").blank();
-  }
-  fmt.text(`Request ID: ${data.requestId}`);
-  return fmt.build();
-}
-function formatHeaderSection(fmt, headers) {
-  const entries = Object.entries(headers).sort(([a], [b]) => a.localeCompare(b));
-  const keyWidth = Math.max(...entries.map(([k]) => k.length)) + 4;
-  entries.forEach(([key, value]) => {
-    value.split("\n").forEach((line) => fmt.keyValue(`  ${key}`, line, keyWidth));
-  });
-}
-function requestStatusLine(data) {
-  const status = formatRequestStatus(data);
-  const text = data.statusText && /^\d+$/.test(status) ? ` ${data.statusText}` : "";
-  return [data.method, `${status}${text}`].filter(Boolean).join(" ");
-}
-
 // src/commands/network/shared.ts
 init_exitCodes();
 async function fetchFromLiveSession() {
@@ -17013,19 +17973,56 @@ function formatDuration2(ms) {
   if (ms === void 0) return "-";
   return ms < 1e3 ? `${Math.round(ms)}ms` : `${(ms / 1e3).toFixed(1)}s`;
 }
-function formatColumnHeader(idWidth) {
-  return `${"[ID]".padEnd(idWidth)} STS METH TYP ${"SIZE".padStart(8)} ${"TIME".padStart(6)}  URL`;
+function pageStartOf(requests) {
+  const navigationIds = requests.flatMap(
+    (r) => r.navigationId === void 0 ? [] : [r.navigationId]
+  );
+  const current = navigationIds.length > 0 ? Math.max(...navigationIds) : void 0;
+  const page = requests.filter((r) => r.navigationId === current);
+  const documents = page.filter((r) => r.resourceType === "Document");
+  const first = (documents.length > 0 ? documents : page).reduce(
+    (earliest, r) => earliest === void 0 || r.timestamp < earliest.timestamp ? r : earliest,
+    void 0
+  );
+  return first && {
+    timestamp: first.timestamp,
+    ...first.sentTime !== void 0 && { sentTime: first.sentTime }
+  };
+}
+function startOffsetMs(request, pageStart) {
+  if (request.sentTime !== void 0 && pageStart.sentTime !== void 0) {
+    return (request.sentTime - pageStart.sentTime) * 1e3;
+  }
+  return request.timestamp - pageStart.timestamp;
+}
+function formatStartOffset(request, pageStart) {
+  if (!pageStart) return "-";
+  const ms = startOffsetMs(request, pageStart);
+  const seconds = Math.abs(ms) / 1e3;
+  const sign = ms < -50 ? "-" : "+";
+  if (seconds < 99.95) return `${sign}${seconds.toFixed(1)}s`;
+  if (seconds < 999.5) return `${sign}${Math.round(seconds)}s`;
+  return `${sign}${Math.floor(seconds / 60)}m`;
 }
-function formatRequestLine(request, verbose, idWidth) {
-  const id = `[${request.requestId}]`.padEnd(idWidth);
+function formatColumnHeader(widths) {
+  return `${"[ID]".padEnd(widths.id)} ${"START".padStart(6)} STS ${"METH".padEnd(widths.method)} TYP ${"SIZE".padStart(8)} ${"TIME".padStart(6)}  URL`;
+}
+function formatRequestLine(request, options, widths) {
+  const id = `[${request.requestId}]`.padEnd(widths.id);
+  const start = formatStartOffset(request, options.pageStart).padStart(6);
   const status = formatStatus(request).padEnd(3);
-  const method = request.method.padEnd(4);
+  const method = request.method.padEnd(widths.method);
   const type = getResourceTypeAbbr(request.resourceType, request.mimeType).padEnd(3);
   const size = formatSize(request.encodedDataLength).padStart(8);
   const time = formatDuration2(request.duration).padStart(6);
-  const urlMaxLength = verbose ? 120 : 50;
-  const url = verbose ? request.url : truncateUrl(request.url, urlMaxLength);
-  return `${id} ${status} ${method} ${type} ${size} ${time}  ${url}`;
+  const url = options.verbose ? request.url : truncateUrl(request.url, 50);
+  return `${id} ${start} ${status} ${method} ${type} ${size} ${time}  ${url}`;
+}
+function columnWidths(requests, minIdWidth) {
+  return {
+    id: Math.max(minIdWidth, ...requests.map((r) => r.requestId.length + 2)),
+    method: Math.max("METH".length, ...requests.map((r) => r.method.length))
+  };
 }
 function buildHeader(showingCount, filteredCount, totalCount) {
   const shown = filteredCount > showingCount ? `last ${showingCount} of ` : "";
@@ -17044,40 +18041,30 @@ function formatNetworkListHuman(requests, options) {
     fmt.text("No matching requests found.");
     return fmt.build();
   }
-  const idWidth = Math.max("[ID]".length, ...requests.map((r) => r.requestId.length + 2));
-  fmt.text(formatColumnHeader(idWidth));
+  const widths = columnWidths(requests, "[ID]".length);
+  fmt.text(formatColumnHeader(widths));
   fmt.separator("\u2500", SEPARATOR_WIDTH2);
-  const verbose = options.verbose ?? false;
   for (const request of requests) {
-    fmt.text(formatRequestLine(request, verbose, idWidth));
+    fmt.text(formatRequestLine(request, options, widths));
   }
   return fmt.build();
 }
 var FOLLOW_ID_WIDTH = 14;
 function formatNetworkFollowRows(requests, options = {}) {
   const fmt = new OutputFormatter();
-  const idWidth = Math.max(FOLLOW_ID_WIDTH, ...requests.map((r) => r.requestId.length + 2));
+  const widths = columnWidths(requests, FOLLOW_ID_WIDTH);
   if (options.header) {
     fmt.text("Streaming network requests... (Ctrl+C to stop)");
-    fmt.text(formatColumnHeader(idWidth));
+    fmt.text(formatColumnHeader(widths));
     fmt.separator("\u2500", SEPARATOR_WIDTH2);
   }
-  for (const request of requests)
-    fmt.text(formatRequestLine(request, options.verbose ?? false, idWidth));
+  for (const request of requests) fmt.text(formatRequestLine(request, options, widths));
   return fmt.build();
 }
 function formatNetworkList(requests, options) {
   return formatNetworkListHuman(requests, options);
 }
 
-// src/ui/messages/networkMessages.ts
-function followingNetworkMessage() {
-  return "Following network requests... (Ctrl+C to stop)";
-}
-function stoppedFollowingNetworkMessage() {
-  return "\nStopped following network requests.";
-}
-
 // src/commands/network/list.ts
 init_exitCodes();
 var MIN_LAST2 = 0;
@@ -17132,7 +18119,8 @@ function buildFormatOptions2(options, result, lastLimit) {
     verbose: options.verbose ?? false,
     last: lastLimit,
     totalCount: result.totalCount,
-    filteredCount: result.filteredCount
+    filteredCount: result.filteredCount,
+    ...result.pageStart && { pageStart: result.pageStart }
   };
 }
 async function runFollowMode2(options, resourceTypes, lastN) {
@@ -17161,9 +18149,11 @@ async function runFollowMode2(options, resourceTypes, lastN) {
         console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
       }
     } else {
+      const pageStart = pageStartOf(result.data);
       const text = formatNetworkFollowRows(fresh, {
         header: !started,
-        verbose: options.verbose ?? false
+        verbose: options.verbose ?? false,
+        ...pageStart && { pageStart }
       });
       if (text) console.log(text);
     }
@@ -17176,6 +18166,11 @@ async function runFollowMode2(options, resourceTypes, lastN) {
     intervalMs: FOLLOW_INTERVAL
   });
 }
+var 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}`).join("\n");
 }
@@ -17195,11 +18190,16 @@ function registerListCommand(networkCmd) {
       "--type <types>",
       "Filter by resource type (comma-separated: Document,XHR,Fetch,etc.)"
     )
-  ).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", `
+  ).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",
+    `
+${COLUMNS_HELP}
+
 ${getFilterHelpText()}
 
 Presets:
-${formatPresetHelp()}`).action(async (options) => {
+${formatPresetHelp()}`
+  ).action(async (options) => {
     let resourceTypes;
     let lastN;
     try {
@@ -17229,12 +18229,14 @@ ${formatPresetHelp()}`).action(async (options) => {
           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
+            filteredCount: filtered.length,
+            ...pageStart && { pageStart }
           }
         };
       },
@@ -17254,1075 +18256,1169 @@ function registerNetworkCommands(program2) {
   registerDocumentCommand(networkCmd);
 }
 
-// src/commands/page.ts
-init_messages();
-init_client();
-init_formatting();
-init_commands();
+// src/commands/start.ts
+import fs15 from "node:fs";
+import os3 from "node:os";
+
+// src/daemon/errors.ts
 init_exitCodes();
-init_url();
-function formatPageResult(result) {
-  const fmt = new OutputFormatter().text(`\u2713 ${PAGE_ACTION_DONE[result.action]}`).keyValueList(
-    [
-      ["URL", result.url],
-      ["Title", result.title],
-      ...result.status !== void 0 ? [["Status", String(result.status)]] : []
-    ],
-    8
-  );
-  if (result.warning) fmt.text(`\u26A0 ${result.warning}`);
-  if (result.loading) fmt.text(`\u26A0 ${pageLoadingWarning(result.loading)}`);
-  return fmt.build();
+var DaemonError = class _DaemonError extends Error {
+  exitCode;
+  code;
+  constructor(message, code, exitCode = EXIT_CODES.SOFTWARE_ERROR) {
+    super(message);
+    this.name = "DaemonError";
+    this.exitCode = exitCode;
+    if (code !== void 0) {
+      this.code = code;
+    }
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _DaemonError);
+    }
+  }
+};
+var DaemonStartupError = class extends DaemonError {
+  name = "DaemonStartupError";
+  constructor(message, code) {
+    super(message, code, EXIT_CODES.SOFTWARE_ERROR);
+  }
+};
+var SessionDirError = class extends DaemonError {
+  /**
+   * @param message - What is wrong with the directory
+   * @param suggestion - How to fix it
+   * @param exitCode - 82 for permissions, 81 for a too-long path, 103 otherwise
+   */
+  constructor(message, suggestion, exitCode = EXIT_CODES.SESSION_FILE_ERROR) {
+    super(message, "SESSION_DIR_UNUSABLE", exitCode);
+    this.suggestion = suggestion;
+  }
+  suggestion;
+  name = "SessionDirError";
+};
+
+// src/daemon/launcher.ts
+import { spawn } from "child_process";
+import fs14 from "fs";
+import { join as join7 } from "path";
+init_messages();
+init_paths();
+init_logging();
+init_errors();
+init_exitCodes();
+var log24 = createLogger("launcher");
+var DAEMON_READY_TIMEOUT_MS = 5e3;
+var DAEMON_READY_POLL_MS = 20;
+async function launchDaemon() {
+  if (await isDaemonAlive()) {
+    log24.debug("Daemon already running");
+    return void 0;
+  }
+  if (!fs14.existsSync(DAEMON_SCRIPT_PATH)) {
+    throw new DaemonStartupError(
+      `Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`,
+      "DAEMON_SCRIPT_NOT_FOUND"
+    );
+  }
+  assertUsableSessionDir();
+  const logPath = join7(getSessionDir(), "daemon.log");
+  rotateLog(logPath);
+  const logFd = fs14.openSync(logPath, "a");
+  log24.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
+  const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd]
+  });
+  fs14.closeSync(logFd);
+  let exited = false;
+  daemon.once("exit", () => {
+    exited = true;
+  });
+  daemon.unref();
+  await waitForDaemonReady(() => exited);
+  return { pid: daemon.pid, hasExited: () => exited };
 }
-function isScriptUrl(url) {
-  const [scheme = ""] = url.trim().split(":", 1);
-  return url.includes(":") && scheme.toLowerCase() === "javascript";
+function assertUsableSessionDir() {
+  const dir = getSessionDir();
+  const fail = (err, exitCode) => {
+    throw new SessionDirError(err.message, err.suggestion, exitCode);
+  };
+  if (fs14.existsSync(dir) && !fs14.statSync(dir).isDirectory()) fail(sessionDirIsFileError(dir));
+  const socketPath = getSessionFilePath("DAEMON_SOCKET");
+  if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+    fail(
+      socketPathTooLongError(socketPath, MAX_DAEMON_SOCKET_PATH_BYTES),
+      EXIT_CODES.INVALID_ARGUMENTS
+    );
+  }
+  try {
+    ensureSessionDir();
+    fs14.accessSync(dir, fs14.constants.W_OK);
+  } catch (error) {
+    const code = error.code;
+    const denied = code === "EACCES" || code === "EPERM" || code === "EROFS";
+    fail(
+      sessionDirNotWritableError(dir, code ?? getErrorMessage(error)),
+      denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR
+    );
+  }
 }
-async function runPageAction(action, options, url) {
-  await runCommand(
-    async () => {
-      if (url !== void 0 && isScriptUrl(url)) {
-        const err = javascriptNavigationError();
-        return {
-          success: false,
-          error: err.message,
-          exitCode: EXIT_CODES.INVALID_URL,
-          errorContext: { suggestion: err.suggestion }
-        };
-      }
-      if (url !== void 0) {
-        const check = validateUrl(url);
-        if (!check.valid) {
-          return {
-            success: false,
-            error: check.error,
-            exitCode: EXIT_CODES.INVALID_URL,
-            ...check.suggestion && { errorContext: { suggestion: check.suggestion } }
-          };
-        }
-      }
-      const response = await pageNavigate({
-        action,
-        ...url !== void 0 && { url },
-        wait: options.wait !== false
-      });
-      if (response.status === "error" || !response.data) {
-        return {
-          success: false,
-          error: response.error ?? `Failed to ${action}`,
-          exitCode: response.exitCode ?? EXIT_CODES.SOFTWARE_ERROR,
-          ...response.suggestion && { errorContext: { suggestion: response.suggestion } }
-        };
-      }
-      return { success: true, data: response.data };
-    },
-    options,
-    formatPageResult
-  );
+var MAX_LOG_BYTES = 5 * 1024 * 1024;
+function rotateLog(logPath) {
+  try {
+    if (fs14.statSync(logPath).size > MAX_LOG_BYTES) {
+      fs14.renameSync(logPath, `${logPath}.1`);
+    }
+  } catch (error) {
+    log24.debug(`Daemon log not rotated: ${getErrorMessage(error)}`);
+  }
 }
-async function showPageInfo(options) {
-  await runCommand(
-    async () => {
-      const response = await getStatus();
-      if (response.status === "error") {
-        return {
-          success: false,
-          error: response.error ?? "Failed to read the page",
-          exitCode: EXIT_CODES.SOFTWARE_ERROR
-        };
-      }
-      const page = response.data?.sessionPid ? response.data.pageState : void 0;
-      if (!page) throw noActiveSessionError();
-      return { success: true, data: { url: page.url, title: page.title } };
-    },
-    options,
-    (page) => new OutputFormatter().keyValueList(
-      [
-        ["URL", page.url],
-        ["Title", page.title]
-      ],
-      8
-    ).build()
+async function waitForDaemonReady(hasExited) {
+  const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await isDaemonAlive()) {
+      log24.debug("Daemon is ready");
+      return;
+    }
+    if (hasExited() && !await isDaemonAlive()) {
+      throw new DaemonStartupError(
+        `Daemon exited during startup. See ${join7(getSessionDir(), "daemon.log")}`,
+        "DAEMON_EXITED"
+      );
+    }
+    await delay2(DAEMON_READY_POLL_MS);
+  }
+  throw new DaemonStartupError(
+    `Daemon failed to start within ${DAEMON_READY_TIMEOUT_MS / 1e3} seconds`,
+    "DAEMON_START_TIMEOUT"
   );
 }
-function registerPageCommands(program2) {
-  const page = program2.command("page").description("The session page: info (URL and title), navigate <url>, reload, back, forward");
-  page.command("info").description(PAGE_INFO_DESCRIPTION).addOption(jsonOption()).action(async (options) => {
-    await showPageInfo(options);
-  });
-  const withCommon = (command) => command.option("--no-wait", "Return without waiting for the page to load").addOption(jsonOption());
-  withCommon(
-    page.command("navigate").description("Load a URL in the session page").argument("<url>", "URL to load")
-  ).action(async (url, options) => {
-    await runPageAction("navigate", options, url);
-  });
-  for (const action of ["reload", "back", "forward"]) {
-    withCommon(page.command(action).description(PAGE_ACTION_DESCRIPTIONS[action])).action(
-      async (options) => {
-        await runPageAction(action, options);
-      }
-    );
+
+// src/commands/shared/startHelpers.ts
+init_messages();
+init_client();
+init_transport();
+init_errors2();
+init_paths();
+init_formatting();
+init_logging();
+init_sessionCommand();
+init_errors();
+init_exitCodes();
+var log25 = createLogger("bdg");
+var SPAWNED_DAEMON_EXIT_WAIT_MS = 3e3;
+var DEFAULT_START_DEPS = {
+  launch: launchDaemon,
+  send: startSession,
+  exitWaitMs: SPAWNED_DAEMON_EXIT_WAIT_MS
+};
+async function startSessionViaDaemon(url, options, telemetry) {
+  process.once("SIGINT", () => reportStartOutcome(interruptedOutcome("SIGINT"), options));
+  process.once("SIGTERM", () => reportStartOutcome(interruptedOutcome("SIGTERM"), options));
+  reportStartOutcome(await attemptStart(url, options, telemetry), options);
+}
+async function attemptStart(url, options, telemetry, deps = DEFAULT_START_DEPS) {
+  const spawned = [];
+  const attempt = async () => {
+    const outcome2 = await requestSession(url, options, telemetry, deps);
+    if (!outcome2.ok && outcome2.spawned) spawned.push(outcome2.spawned);
+    return outcome2;
+  };
+  let outcome = await attempt();
+  const deadline = Date.now() + SHUTDOWN_WAIT_MS;
+  while (isShuttingDown(outcome) && Date.now() < deadline) {
+    await delay2(SHUTDOWN_POLL_MS);
+    outcome = await attempt();
   }
+  return afterSpawnedDaemonExit(outcome, spawned, deps.exitWaitMs);
 }
-
-// src/commands/peek.ts
-function parseOptions(options) {
-  const lastN = positiveIntRule({
-    name: "--last",
-    min: 1,
-    max: MAX_LAST_ITEMS,
-    default: 10,
-    allowZeroForAll: true
-  }).validate(options.last);
-  const resourceTypes = resourceTypeRule().validate(options.type);
-  return { lastN, resourceTypes };
+async function afterSpawnedDaemonExit(outcome, spawned, waitMs) {
+  if (outcome.ok) return outcome;
+  const { spawned: _spawned, daemonExiting: _exiting, ...failure } = outcome;
+  if (spawned.length === 0) return failure;
+  if (await waitUntil(() => spawned.every((daemon) => daemon.hasExited()), waitMs)) {
+    return failure;
+  }
+  const running = spawned.filter((daemon) => !daemon.hasExited()).pop();
+  const suggestion = daemonStillExitingSuggestion();
+  const previous = failure.details?.["suggestion"];
+  return {
+    ...failure,
+    human: joinLines(
+      failure.human,
+      `${daemonStillExitingHint(running?.pid, waitMs)}; ${suggestion}`
+    ),
+    details: {
+      ...failure.details,
+      daemonStillRunning: true,
+      ...running?.pid !== void 0 && { daemonPid: running.pid },
+      suggestion: typeof previous === "string" && previous ? `${previous}; ${suggestion}` : suggestion
+    }
+  };
 }
-function peekSection(options) {
-  if (options.network) return "network";
-  return options.console ? "console" : void 0;
+function interruptedOutcome(signal) {
+  const message = `Start cancelled (${signal === "SIGINT" ? "interrupted" : "terminated"})`;
+  const exitCode = signal === "SIGINT" ? EXIT_CODES.INTERRUPTED : EXIT_CODES.TERMINATED;
+  return { ok: false, error: message, human: message, exitCode };
 }
-async function fetchAndFilterPreview(lastN, resourceTypes, only) {
-  const result = await fetchPreviewOutput({
-    lastN: resourceTypes.length > 0 ? 0 : lastN,
-    ...only && { only }
+var SHUTDOWN_WAIT_MS = 15e3;
+var SHUTDOWN_POLL_MS = 200;
+function isShuttingDown(outcome) {
+  return !outcome.ok && (outcome.retryable === true || outcome.errorCode === "SESSION_SHUTTING_DOWN" /* SESSION_SHUTTING_DOWN */);
+}
+async function requestSession(url, options, telemetry, deps) {
+  let spawned;
+  try {
+    spawned = await deps.launch();
+  } catch (error) {
+    if (error instanceof SessionDirError) {
+      return {
+        ok: false,
+        error: error.message,
+        human: joinLines(genericError(error.message), error.suggestion),
+        exitCode: error.exitCode,
+        details: { suggestion: error.suggestion }
+      };
+    }
+    const message = `Failed to start daemon: ${getErrorMessage(error)}`;
+    const exitCode = error instanceof DaemonError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
+    return { ok: false, error: message, human: genericError(message), exitCode };
+  }
+  const outcome = await sendStart(url, options, telemetry, deps.send);
+  return !outcome.ok && outcome.daemonExiting && spawned ? { ...outcome, spawned } : outcome;
+}
+async function sendStart(url, options, telemetry, send) {
+  try {
+    log25.debug("Connecting to daemon...");
+    const response = await send(
+      url,
+      filterDefined({
+        port: options.port,
+        timeout: options.timeout,
+        telemetry: telemetry.length > 0 ? telemetry : void 0,
+        includeAll: options.includeAll,
+        userDataDir: options.userDataDir,
+        maxBodySize: options.maxBodySize,
+        headless: options.headless,
+        chromeWsUrl: options.chromeWsUrl,
+        chromeFlags: options.chromeFlags,
+        viewport: options.viewport,
+        colorScheme: options.colorScheme
+      })
+    );
+    if (response.status === "error") {
+      return { ...describeStartFailure(response, options), daemonExiting: true };
+    }
+    if (!response.data) {
+      const message = "Invalid response from daemon: missing data";
+      return {
+        ok: false,
+        error: message,
+        human: invalidResponseError("missing data"),
+        exitCode: EXIT_CODES.SOFTWARE_ERROR
+      };
+    }
+    return { ok: true, data: response.data };
+  } catch (error) {
+    if (error instanceof IPCTimeoutError) {
+      const timeout = timeoutError(error);
+      return {
+        ok: false,
+        error: timeout.message,
+        human: joinLines(genericError(timeout.message), String(timeout.metadata.suggestion)),
+        exitCode: timeout.exitCode,
+        details: { suggestion: timeout.metadata.suggestion }
+      };
+    }
+    if (isConnectionError(error)) {
+      return {
+        ok: false,
+        error: `${noActiveSessionMessage()} (daemon not running)`,
+        human: daemonNotRunningError({ suggestStatus: true, suggestRetry: true }),
+        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+        retryable: true,
+        daemonExiting: true
+      };
+    }
+    const message = getErrorMessage(error);
+    return {
+      ok: false,
+      error: message,
+      human: genericError(message),
+      exitCode: EXIT_CODES.SOFTWARE_ERROR
+    };
+  }
+}
+function omitDuration(existing) {
+  const { duration: _duration, ...rest } = existing;
+  return rest;
+}
+function describeStartFailure(response, options) {
+  const exitCode = response.exitCode ?? getExitCodeForIPCError(response.errorCode);
+  const existing = response.existingSession;
+  const details = filterDefined({
+    existingSession: existing && {
+      ...omitDuration(existing),
+      ...existing.duration !== void 0 && { durationMs: existing.duration * 1e3 }
+    }
   });
-  if (!result.success) return result;
-  const output = result.data;
-  const unfilteredNetworkCount = output.totals?.network ?? output.data.network?.length ?? 0;
-  if (resourceTypes.length === 0 || !output.data.network) {
-    return { success: true, data: { output, unfilteredNetworkCount } };
+  if (response.errorCode === "SESSION_ALREADY_RUNNING" /* SESSION_ALREADY_RUNNING */ && existing) {
+    const { pid, targetUrl, duration } = existing;
+    return {
+      ok: false,
+      error: response.message ?? "Session already running",
+      human: sessionAlreadyRunningError(pid, duration ? duration * 1e3 : 0, targetUrl),
+      exitCode,
+      errorCode: response.errorCode,
+      details: { ...details, suggestion: alreadyRunningSuggestion() }
+    };
   }
-  const network = filterByResourceType(output.data.network, resourceTypes);
-  const filteredOutput = {
-    ...output,
-    data: { ...output.data, network },
-    ...output.totals && { totals: { ...output.totals, network: network.length } }
-  };
-  return { success: true, data: { output: filteredOutput, unfilteredNetworkCount } };
-}
-function createPreviewOptions(base, resourceTypes, unfilteredCount) {
-  const options = { ...base };
-  if (base.follow) options.viewedAt = /* @__PURE__ */ new Date();
-  if (resourceTypes.length > 0) {
-    options.filteredTypes = resourceTypes;
-    options.unfilteredNetworkCount = unfilteredCount;
+  if (response.errorCode === "SESSION_TARGET_MISMATCH" /* SESSION_TARGET_MISMATCH */) {
+    const current = response.existingSession?.targetUrl ?? LAUNCHED_CHROME_DESCRIPTION;
+    const requested = options.chromeWsUrl ?? LAUNCHED_CHROME_DESCRIPTION;
+    return {
+      ok: false,
+      error: response.message ?? "Session target mismatch",
+      human: sessionTargetMismatchError(current, requested),
+      exitCode,
+      errorCode: response.errorCode,
+      details
+    };
   }
-  return options;
-}
-async function runFollowMode3(options, lastN, resourceTypes, baseOptions) {
-  const showPreview = async () => {
-    const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
-    if (!result.success) {
-      return followFetchFailure(result, { json: options.json, retryIntervalMs: 1e3 });
+  const message = response.message ?? "Unknown error";
+  const [error = message, ...hint] = message.split("\n");
+  return {
+    ok: false,
+    error,
+    human: genericError(message),
+    exitCode,
+    errorCode: response.errorCode,
+    details: {
+      ...details,
+      ...hint.join("\n").trim() && { suggestion: hint.join("\n").trim() }
     }
-    noteFollowConnected();
-    if (!options.json) console.clear();
-    const previewOptions = createPreviewOptions(
-      baseOptions,
-      resourceTypes,
-      result.data.unfilteredNetworkCount
-    );
-    console.log(formatPreview(result.data.output, previewOptions));
-    return void 0;
   };
-  await setupFollowMode(showPreview, {
-    startMessage: followingPreviewMessage,
-    stopMessage: stoppedFollowingPreviewMessage,
-    intervalMs: 1e3
-  });
 }
-function registerPeekCommand(program2) {
-  program2.command("peek").description("Preview collected data without stopping the session").addOption(jsonOption()).option("-v, --verbose", "Use verbose output with full URLs and formatting", false).option("-n, --network", "Show only network requests", false).option("-c, --console", "Show only console messages", false).option("-f, --follow", "Watch for updates (like tail -f)", false).option("--last <count>", "Show last N items, 0 for all", "10").option(
-    "--type <types>",
-    "Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)"
-  ).action(async (options) => {
-    showBothSectionsWhenBothRequested(options);
-    if (options.network && !options.json) {
-      console.error(
-        'Note: "bdg peek --network" is deprecated. Use "bdg network list" for enhanced filtering.'
-      );
-    }
-    let lastN;
-    let resourceTypes;
-    try {
-      const parsed = parseOptions(options);
-      lastN = parsed.lastN;
-      resourceTypes = parsed.resourceTypes;
-    } catch (error) {
-      handleValidationError(error, options.json ?? false);
+function reportStartOutcome(outcome, options) {
+  if (!outcome.ok) {
+    if (options.json) {
+      const envelope = OutputBuilder.buildJsonError(outcome.error, {
+        exitCode: outcome.exitCode,
+        ...outcome.details
+      });
+      console.log(JSON.stringify(envelope, null, 2));
+    } else {
+      console.error(escapeControlChars(outcome.human));
     }
-    const baseOptions = {
-      json: options.json,
-      network: options.network,
-      console: options.console,
-      last: lastN,
-      verbose: options.verbose,
-      follow: options.follow
+    process.exit(outcome.exitCode);
+  }
+  const { data } = outcome;
+  const autoStopAt = options.timeout !== void 0 ? new Date(Date.now() + options.timeout * 1e3) : void 0;
+  const session = getSessionName() ?? void 0;
+  if (options.json) {
+    const result = {
+      ...session && { session },
+      targetUrl: data.targetUrl,
+      ...data.targetTitle !== void 0 && { targetTitle: data.targetTitle },
+      ...data.documentStatus !== void 0 && { documentStatus: data.documentStatus },
+      ...data.loading && { loading: data.loading },
+      port: data.port,
+      ...data.chromePid > 0 ? { chromePid: data.chromePid } : { externalChrome: true },
+      daemonPid: data.daemonPid,
+      ...autoStopAt && { autoStopAt: autoStopAt.toISOString() }
     };
-    if (options.follow) {
-      await runFollowMode3(options, lastN, resourceTypes, baseOptions);
-      return;
-    }
-    await runCommand(
-      async () => {
-        const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
-        if (!result.success) {
-          return createErrorResult(result.error, result.exitCode, result.suggestion);
-        }
-        const { output } = result.data;
-        return {
-          success: true,
-          data: options.json ? buildPreviewJsonData(output, baseOptions) : output
-        };
-      },
-      options,
-      (data) => {
-        const output = data;
-        const previewOptions = createPreviewOptions(
-          baseOptions,
-          resourceTypes,
-          output.data.network?.length ?? 0
-        );
-        return formatPreview(output, previewOptions);
-      }
-    );
-  });
+    console.log(JSON.stringify(buildSuccessResponse(result), null, 2));
+  } else {
+    const page = {
+      url: data.targetUrl,
+      ...data.documentStatus !== void 0 && { documentStatus: data.documentStatus },
+      ...data.loading && { loading: data.loading },
+      ...autoStopAt && { autoStopAt },
+      ...session && { session }
+    };
+    const text = options.quiet ? [`Session started: ${data.targetUrl}`, ...startNotices(page)].join("\n") : landingPage(page);
+    console.error(escapeControlChars(text));
+  }
+  process.exit(EXIT_CODES.SUCCESS);
 }
 
-// src/session/sessionList.ts
-init_client();
-import * as fs15 from "fs";
-init_paths();
+// src/commands/start.ts
+init_constants();
+init_errors3();
+init_messages();
+init_commands();
+init_exitCodes();
 
-// src/session/portClaims.ts
-import * as fs14 from "fs";
-init_paths();
-init_logging();
-var log24 = createLogger("session");
-function readPortFile(portPath) {
+// src/utils/http.ts
+init_constants();
+init_errors();
+var CDP_HTTP_TIMEOUT_MS = 5e3;
+async function probeDevToolsEndpoint(port, logger, options) {
+  const url = `${options?.secure ? "https" : "http"}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
+  let response;
   try {
-    const port = parseInt(fs14.readFileSync(portPath, "utf-8").trim(), 10);
-    return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+    response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
   } catch (error) {
-    logDebugError(log24, `read ${portPath}`, error);
-    return null;
+    logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
+    return { kind: "unreachable" };
+  }
+  try {
+    const data = await response.json();
+    const wsUrl = data?.webSocketDebuggerUrl;
+    if (response.ok && typeof wsUrl === "string") return { kind: "devtools", wsUrl };
+  } catch (error) {
+    logger?.debug(`Chrome version response is not JSON: ${getErrorMessage(error)} (${url})`);
   }
+  return { kind: "not-devtools" };
 }
 
-// src/session/sessionName.ts
-init_errors3();
-init_messages();
-init_paths();
-init_exitCodes();
-var MAX_SESSION_NAME_LENGTH = 40;
-var SESSION_NAME_PATTERN = new RegExp(
-  `^[A-Za-z0-9][A-Za-z0-9_-]{0,${MAX_SESSION_NAME_LENGTH - 1}}$`
-);
-function isValidSessionName(name) {
-  return SESSION_NAME_PATTERN.test(name);
+// src/commands/start.ts
+init_suggestions();
+init_url();
+function hasDisplay() {
+  const display = process.env["DISPLAY"];
+  const wayland = process.env["WAYLAND_DISPLAY"];
+  return display !== void 0 && display !== "" || wayland !== void 0 && wayland !== "";
+}
+function expandHome(value) {
+  return value.startsWith("~/") ? value.replace(/^~/, os3.homedir()) : value;
+}
+function extractUserDataDirFromFlags(flags) {
+  const rest = [];
+  let userDataDir;
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (flag.startsWith("--user-data-dir=")) {
+      userDataDir = flag.slice("--user-data-dir=".length);
+      continue;
+    }
+    if (flag === "--user-data-dir" && i + 1 < flags.length) {
+      userDataDir = flags[i + 1];
+      i++;
+      continue;
+    }
+    rest.push(flag);
+  }
+  return {
+    userDataDir: userDataDir ? expandHome(userDataDir) : void 0,
+    rest
+  };
+}
+function applyCollectorOptions(command) {
+  const defaultHeadless = !hasDisplay();
+  return command.option("-p, --port <number>", PORT_OPTION_DESCRIPTION).option(
+    "-t, --timeout <seconds>",
+    "Stop the session this many seconds after the page has loaded (unlimited if not specified)"
+  ).option("-u, --user-data-dir <path>", "Chrome user data directory (defaults to session dir)").option(
+    "-a, --all",
+    "Include all data: no tracking/analytics filtering, and capture every response body (incl. binary)",
+    false
+  ).option("-m, --max-body-size <megabytes>", "Maximum response body size in MB", "5").addOption(new Option("--compact", "No effect; kept for compatibility").hideHelp()).option(
+    "--headless",
+    "Run Chrome without a window (default unless DISPLAY or WAYLAND_DISPLAY is set)",
+    defaultHeadless
+  ).option("--no-headless", "Show browser window").option(
+    "--chrome-ws-url <url>",
+    "Connect to an existing Chrome: its DevTools port (9222, host:port, http://host:port), or a WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)"
+  ).option("-q, --quiet", "Quiet mode - minimal output for AI agents", false).addOption(jsonOption()).option(
+    "--chrome-flags <flags>",
+    'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")'
+  ).option(
+    "--viewport <WxH>",
+    "Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)"
+  ).option(
+    "--color-scheme <scheme>",
+    "Emulate prefers-color-scheme for the session: light or dark (default: the system setting)"
+  );
 }
-function normalizeSessionName(name) {
-  return name.toLowerCase();
+var MAX_VIEWPORT_SIDE = 1e4;
+var COLOR_SCHEMES = ["light", "dark"];
+function parseViewport(value) {
+  const match = /^\s*(\d+)\s*[xX×,]\s*(\d+)\s*$/.exec(value);
+  const width = Number(match?.[1]);
+  const height = Number(match?.[2]);
+  const valid2 = (side) => side >= 1 && side <= MAX_VIEWPORT_SIDE;
+  if (match && valid2(width) && valid2(height)) return { width, height };
+  const err = invalidViewportError(value, MAX_VIEWPORT_SIDE);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function validateSessionName(name) {
-  if (!isValidSessionName(name)) {
-    throwInvalid(invalidSessionNameError(name, MAX_SESSION_NAME_LENGTH));
-  }
-  const shortest = namedSocketPath("a");
-  if (Buffer.byteLength(shortest) > MAX_DAEMON_SOCKET_PATH_BYTES) {
-    throwInvalid(socketPathTooLongError(shortest, MAX_DAEMON_SOCKET_PATH_BYTES));
-  }
-  const socketPath = namedSocketPath(name);
-  if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
-    throwInvalid(sessionNameSocketTooLongError(name, socketPath, MAX_DAEMON_SOCKET_PATH_BYTES));
-  }
+function parseColorScheme(value) {
+  const scheme = COLOR_SCHEMES.find((candidate) => candidate === value.trim().toLowerCase());
+  if (scheme) return scheme;
+  const err = invalidColorSchemeError(value, findSimilar(value, [...COLOR_SCHEMES]), COLOR_SCHEMES);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function namedSocketPath(name) {
-  return sessionFilePathIn(getNamedSessionDir(name), "DAEMON_SOCKET");
+function buildSessionOptions(options) {
+  const maxBodySizeRule = positiveIntRule({
+    name: "--max-body-size",
+    min: 1,
+    max: 100,
+    required: false
+  });
+  const timeoutRule = positiveIntRule({ name: "--timeout", min: 1, max: 3600, required: false });
+  const portRule = positiveIntRule({ name: "--port", min: 1024, max: 65535, required: false });
+  const maxBodySizeMB = options.maxBodySize !== void 0 ? maxBodySizeRule.validate(options.maxBodySize) : void 0;
+  const timeout = options.timeout !== void 0 ? timeoutRule.validate(options.timeout) : void 0;
+  const envFlags = process.env["BDG_CHROME_FLAGS"]?.split(" ").filter(Boolean) ?? [];
+  const cliFlags = options.chromeFlags?.split(" ").filter(Boolean) ?? [];
+  const { userDataDir: flagUserDataDir, rest: combinedFlags } = extractUserDataDirFromFlags([
+    ...envFlags,
+    ...cliFlags
+  ]);
+  const userDataDir = options.userDataDir ? expandHome(options.userDataDir) : flagUserDataDir;
+  const chromeFlags = combinedFlags.length > 0 ? combinedFlags : void 0;
+  return {
+    port: options.port !== void 0 ? portRule.validate(options.port) : void 0,
+    timeout,
+    userDataDir,
+    includeAll: options.all ?? false,
+    maxBodySize: maxBodySizeMB !== void 0 ? maxBodySizeMB * 1024 * 1024 : void 0,
+    headless: options.headless ?? !hasDisplay(),
+    chromeWsUrl: options.chromeWsUrl,
+    quiet: options.quiet ?? false,
+    json: options.json ?? false,
+    chromeFlags,
+    viewport: options.viewport !== void 0 ? parseViewport(options.viewport) : void 0,
+    colorScheme: options.colorScheme !== void 0 ? parseColorScheme(options.colorScheme) : void 0
+  };
 }
-function throwInvalid(err) {
+var SESSION_TELEMETRY = ["dom", "network", "console"];
+var FLAG_WORDS = { version: "--version", help: "--help" };
+function assertNotCommandTypo(arg, commandNames) {
+  if (!/^[a-z][a-z0-9_-]*$/i.test(arg) || arg.toLowerCase() === "localhost") return;
+  const flag = FLAG_WORDS[arg.toLowerCase()];
+  const err = unknownCommandError(arg, flag ? [flag] : findSimilar(arg, commandNames));
   throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function selectSession(optionValue) {
-  const name = optionValue ?? process.env[SESSION_NAME_ENV]?.trim();
-  if (name === void 0 || optionValue === void 0 && name === "") {
-    delete process.env[SESSION_NAME_ENV];
-    return;
+function assertNotGroupSubcommand(program2, argv) {
+  const [first] = argv.slice(2).filter((arg) => !arg.startsWith("-"));
+  if (first === void 0 || program2.commands.some((command) => command.name() === first)) return;
+  const group = program2.commands.find(
+    (command) => command.commands.some((sub) => sub.name() === first)
+  );
+  if (!group) return;
+  const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+function validateStartInput(url, options, program2) {
+  if (url === void 0) {
+    const err = missingStartUrlError();
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.INVALID_ARGUMENTS
+    );
   }
-  validateSessionName(name);
-  process.env[SESSION_NAME_ENV] = normalizeSessionName(name);
+  assertNotCommandTypo(
+    url,
+    program2.commands.map((command) => command.name())
+  );
+  assertValidUrl(url);
+  if (options.chromeWsUrl !== void 0) {
+    assertValidChromeWsUrl(options.chromeWsUrl);
+    assertNoLaunchOptions(options, program2);
+  }
+  if (options.userDataDir !== void 0) assertUserDataDir(options.userDataDir);
+  if (options.chromeWsUrl === void 0)
+    assertChromeFlags([
+      ...process.env["BDG_CHROME_FLAGS"]?.split(" ") ?? [],
+      ...options.chromeFlags?.split(" ") ?? []
+    ]);
+  return { url, sessionOptions: buildSessionOptions(options) };
 }
-
-// src/session/sessionList.ts
-init_logging();
-init_sessionCommand();
-var log25 = createLogger("session");
-function toRunningSession(name, data) {
-  const meta = data.sessionMetadata;
-  const state = meta ? "active" : data.ending ? "ending" : "starting";
-  const url = data.pageState?.url ?? data.starting?.url;
-  return {
-    name,
-    state,
-    ...url !== void 0 && { url },
-    ...meta && { port: meta.port },
-    daemonPid: data.daemonPid,
-    ...meta?.chromePid && { chromePid: meta.chromePid }
-  };
+function registerStartCommands(program2) {
+  applyCollectorOptions(
+    program2.argument("[url]", "Target URL (example.com or localhost:3000)")
+  ).action(async (url, options) => {
+    if (url === void 0 && !hasUserOptions(program2)) {
+      console.error(startCommandHelpMessage());
+      process.exit(0);
+    }
+    let validated;
+    try {
+      validated = validateStartInput(url, options, program2);
+      validated.sessionOptions.chromeWsUrl = await resolveChromeWsUrl(
+        validated.sessionOptions.chromeWsUrl
+      );
+    } catch (error) {
+      handleValidationError(error, options.json ?? false);
+    }
+    await startSessionViaDaemon(validated.url, validated.sessionOptions, SESSION_TELEMETRY);
+  });
 }
-async function describeSession(entry) {
-  const { name, dir } = entry;
-  const socketPath = sessionFilePathIn(dir, "DAEMON_SOCKET");
-  const probe = await probeDaemonSocket(socketPath);
-  if (probe !== "alive") return describeWithoutSocket(entry, probe);
-  try {
-    const response = await getStatus(socketPath);
-    if (response.status === "ok" && response.data) return toRunningSession(name, response.data);
-  } catch (error) {
-    logDebugError(log25, `get status of ${dir}`, error);
-  }
-  return { name, state: "unresponsive" };
+async function resolveChromeWsUrl(value) {
+  const endpoint = value === void 0 ? null : devToolsHttpEndpoint(value);
+  if (endpoint === null) return value;
+  const { hostname, port, protocol } = new URL(endpoint);
+  const secure = protocol === "https:";
+  const defaultPort = secure ? 443 : 80;
+  const probe = await probeDevToolsEndpoint(Number(port) || defaultPort, void 0, {
+    host: hostname,
+    secure
+  });
+  if (probe.kind === "devtools") return atEndpoint(probe.wsUrl, endpoint);
+  const err = probe.kind === "not-devtools" ? notDevToolsEndpointError(endpoint) : externalChromeUnreachableError(endpoint, false);
+  throw new CommandError(
+    err.message,
+    { suggestion: err.suggestion },
+    EXIT_CODES.CDP_CONNECTION_FAILURE
+  );
 }
-function describeWithoutSocket(entry, probe) {
-  const daemonPid = readLiveDaemonPid(entry.dir);
-  if (daemonPid !== null) return { name: entry.name, state: "starting", daemonPid };
-  return describeLeftovers(entry, probe);
+function atEndpoint(wsUrl, endpoint) {
+  const resolved = new URL(wsUrl);
+  const target = new URL(endpoint);
+  resolved.protocol = target.protocol === "https:" ? "wss:" : "ws:";
+  resolved.host = target.host;
+  return resolved.toString();
 }
-function describeLeftovers({ name, dir }, probe) {
-  const chromePid = readPidFromFile(sessionFilePathIn(dir, "CHROME_PID"));
-  const orphan = chromePid !== null && isProcessAlive(chromePid) && isSessionChrome(chromePid, dir);
-  const leftover = probe === "stale" || SESSION_STATE_FILES.some((type) => fs15.existsSync(sessionFilePathIn(dir, type)));
-  if (!orphan && !leftover) return null;
-  const port = leftoverPort(dir);
-  return {
-    name,
-    state: orphan ? "crashed" : "stale",
-    ...port !== null && { port },
-    ...orphan && { chromePid },
-    cleanup: sessionCommand("bdg cleanup", name)
-  };
+function hasUserOptions(program2) {
+  return program2.options.some(
+    (option) => program2.getOptionValueSource(option.attributeName()) === "cli"
+  );
 }
-function leftoverPort(dir) {
-  try {
-    const meta = JSON.parse(fs15.readFileSync(sessionFilePathIn(dir, "METADATA"), "utf8"));
-    if (typeof meta.port === "number") return meta.port;
-  } catch (error) {
-    logDebugError(log25, `read the metadata in ${dir}`, error);
-  }
-  return readPortFile(sessionFilePathIn(dir, "PORT"));
+function assertUserDataDir(value) {
+  const resolved = expandHome(value);
+  let reason;
+  if (!value.trim()) reason = "the path is empty";
+  else if (value.startsWith("-")) reason = "it looks like an option; -u needs a directory path";
+  else if (fs15.existsSync(resolved) && !fs15.statSync(resolved).isDirectory()) reason = "it is a file";
+  if (reason === void 0) return;
+  const err = invalidUserDataDirError(value, reason);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function isSelectable({ name }) {
-  return name === null || isValidSessionName(name) && name === normalizeSessionName(name);
+function launchOptionConflicts(options, program2) {
+  const headlessGiven = program2.getOptionValueSource("headless") === "cli";
+  return [
+    ...options.port !== void 0 ? ["--port"] : [],
+    ...options.userDataDir !== void 0 ? ["--user-data-dir"] : [],
+    ...headlessGiven ? [options.headless ? "--headless" : "--no-headless"] : []
+  ];
 }
-function isSameDir(a, b) {
-  try {
-    const first = fs15.statSync(a);
-    const second = fs15.statSync(b);
-    return first.ino === second.ino && first.dev === second.dev;
-  } catch (error) {
-    logDebugError(log25, `compare ${a} with ${b}`, error);
-    return false;
-  }
+function assertNoLaunchOptions(options, program2) {
+  const conflicts = launchOptionConflicts(options, program2);
+  if (conflicts.length === 0) return;
+  const err = chromeWsUrlConflictError(conflicts);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function selectableEntry(entry) {
-  if (isSelectable(entry) || entry.name === null) return entry;
-  const lower = normalizeSessionName(entry.name);
-  if (!isValidSessionName(lower)) return null;
-  return isSameDir(entry.dir, getNamedSessionDir(lower)) ? { name: lower, dir: entry.dir } : null;
+var BDG_OPTION_WORDS = /* @__PURE__ */ new Set([
+  "--json",
+  "-j",
+  "--port",
+  "-p",
+  "--no-headless",
+  "-q",
+  "--quiet"
+]);
+function assertChromeFlags(flags) {
+  const flag = flags.find(
+    (value) => /^--remote-debugging-(port|pipe)\b/.test(value) || BDG_OPTION_WORDS.has(value)
+  );
+  if (flag === void 0) return;
+  const err = invalidChromeFlagError(flag);
+  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-async function describeUnselectable(entry) {
-  const socketPath = sessionFilePathIn(entry.dir, "DAEMON_SOCKET");
-  if (await probeDaemonSocket(socketPath) === "alive") return describeSession(entry);
-  return { name: entry.name, state: "stale", cleanup: removeDirCommand(entry.dir) };
+function assertValidUrl(url) {
+  const result = validateUrl(url);
+  if (result.valid) return;
+  throw new CommandError(
+    result.error,
+    result.suggestion ? { suggestion: result.suggestion } : {},
+    EXIT_CODES.INVALID_URL
+  );
 }
-async function listRunningSessions() {
-  const listed = /* @__PURE__ */ new Set();
-  const sessions = await Promise.all(
-    listSessionDirs().map((entry) => {
-      const selectable = selectableEntry(entry);
-      if (selectable === null) return describeUnselectable(entry);
-      if (listed.has(selectable.name)) return Promise.resolve(null);
-      listed.add(selectable.name);
-      return describeSession(selectable);
-    })
+function assertValidChromeWsUrl(url) {
+  const result = validateChromeWsUrl(url);
+  if (result.valid) return;
+  throw new CommandError(
+    result.error,
+    result.suggestion ? { suggestion: result.suggestion } : {},
+    EXIT_CODES.INVALID_URL
   );
-  return sessions.filter((session) => session !== null);
 }
 
-// src/ui/formatters/sessions.ts
+// src/commands/page.ts
+init_errors3();
+init_messages();
+init_client();
 init_formatting();
-var DEFAULT_SESSION_LABEL = "(default)";
-function formatSessionList(data) {
-  const fmt = new OutputFormatter();
-  if (data.sessions.length === 0) {
-    return fmt.text("No running sessions").hints("Suggestions:", ["Start one:  bdg <url> [--session <name>]"]).build();
-  }
-  const rows = data.sessions.map((session) => [
-    session.name ?? DEFAULT_SESSION_LABEL,
-    session.state,
-    session.port?.toString() ?? "-",
-    session.daemonPid?.toString() ?? "-",
-    session.url ?? "-"
-  ]);
-  const header = ["SESSION", "STATE", "PORT", "PID", "URL"];
-  const widths = header.map(
-    (title, column) => Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0))
+init_commands();
+init_exitCodes();
+init_url();
+function formatPageResult(result) {
+  const fmt = new OutputFormatter().text(`\u2713 ${PAGE_ACTION_DONE[result.action]}`).keyValueList(
+    [
+      ["URL", result.url],
+      ["Title", result.title],
+      ...result.status !== void 0 ? [["Status", String(result.status)]] : []
+    ],
+    8
   );
-  for (const row of [header, ...rows]) {
-    fmt.text(
-      row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd()
-    );
-  }
-  const cleanups = data.sessions.flatMap((session) => session.cleanup ? [session.cleanup] : []);
-  if (cleanups.length > 0) {
-    fmt.hints("Crashed or stale sessions; clean up with:", cleanups);
-  }
+  if (result.warning) fmt.text(`\u26A0 ${result.warning}`);
+  if (result.loading) fmt.text(`\u26A0 ${pageLoadingWarning(result.loading)}`);
   return fmt.build();
 }
-
-// src/commands/sessions.ts
-function registerSessionsCommand(program2) {
-  program2.command("sessions").description(
-    "List sessions (default and named) with their state, URL, port and PID, including crashed ones to clean up"
-  ).addOption(jsonOption()).action(async (options) => {
-    await runCommand(
-      async () => ({ success: true, data: { sessions: await listRunningSessions() } }),
-      options,
-      formatSessionList
-    );
-  });
+function isScriptUrl(url) {
+  const [scheme = ""] = url.trim().split(":", 1);
+  return url.includes(":") && scheme.toLowerCase() === "javascript";
 }
-
-// src/commands/start.ts
-import fs17 from "node:fs";
-import os3 from "node:os";
-
-// src/daemon/errors.ts
-init_exitCodes();
-var DaemonError = class _DaemonError extends Error {
-  exitCode;
-  code;
-  constructor(message, code, exitCode = EXIT_CODES.SOFTWARE_ERROR) {
-    super(message);
-    this.name = "DaemonError";
-    this.exitCode = exitCode;
-    if (code !== void 0) {
-      this.code = code;
-    }
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _DaemonError);
-    }
-  }
-};
-var DaemonStartupError = class extends DaemonError {
-  name = "DaemonStartupError";
-  constructor(message, code) {
-    super(message, code, EXIT_CODES.SOFTWARE_ERROR);
-  }
-};
-var SessionDirError = class extends DaemonError {
-  /**
-   * @param message - What is wrong with the directory
-   * @param suggestion - How to fix it
-   * @param exitCode - 82 for permissions, 81 for a too-long path, 103 otherwise
-   */
-  constructor(message, suggestion, exitCode = EXIT_CODES.SESSION_FILE_ERROR) {
-    super(message, "SESSION_DIR_UNUSABLE", exitCode);
-    this.suggestion = suggestion;
-  }
-  suggestion;
-  name = "SessionDirError";
-};
-
-// src/daemon/launcher.ts
-import { spawn } from "child_process";
-import fs16 from "fs";
-import { join as join7 } from "path";
-init_messages();
-init_paths();
-init_logging();
-init_errors();
-init_exitCodes();
-var log26 = createLogger("launcher");
-var DAEMON_READY_TIMEOUT_MS = 5e3;
-var DAEMON_READY_POLL_MS = 20;
-async function launchDaemon() {
-  if (await isDaemonAlive()) {
-    log26.debug("Daemon already running");
-    return;
-  }
-  if (!fs16.existsSync(DAEMON_SCRIPT_PATH)) {
-    throw new DaemonStartupError(
-      `Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`,
-      "DAEMON_SCRIPT_NOT_FOUND"
-    );
-  }
-  assertUsableSessionDir();
-  const logPath = join7(getSessionDir(), "daemon.log");
-  rotateLog(logPath);
-  const logFd = fs16.openSync(logPath, "a");
-  log26.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
-  const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd]
-  });
-  fs16.closeSync(logFd);
-  let exited = false;
-  daemon.once("exit", () => {
-    exited = true;
-  });
-  daemon.unref();
-  await waitForDaemonReady(() => exited);
+async function runPageAction(action, options, url) {
+  await runCommand(
+    async () => {
+      if (url !== void 0 && isScriptUrl(url)) {
+        const err = javascriptNavigationError();
+        return {
+          success: false,
+          error: err.message,
+          exitCode: EXIT_CODES.INVALID_URL,
+          errorContext: { suggestion: err.suggestion }
+        };
+      }
+      if (url !== void 0) {
+        const check = validateUrl(url);
+        if (!check.valid) {
+          return {
+            success: false,
+            error: check.error,
+            exitCode: EXIT_CODES.INVALID_URL,
+            ...check.suggestion && { errorContext: { suggestion: check.suggestion } }
+          };
+        }
+      }
+      const response = await pageNavigate({
+        action,
+        ...url !== void 0 && { url },
+        wait: options.wait !== false
+      });
+      if (response.status === "error" || !response.data) {
+        return {
+          success: false,
+          error: response.error ?? `Failed to ${action}`,
+          exitCode: response.exitCode ?? EXIT_CODES.SOFTWARE_ERROR,
+          ...response.suggestion && { errorContext: { suggestion: response.suggestion } }
+        };
+      }
+      return { success: true, data: response.data };
+    },
+    options,
+    formatPageResult
+  );
 }
-function assertUsableSessionDir() {
-  const dir = getSessionDir();
-  const fail = (err, exitCode) => {
-    throw new SessionDirError(err.message, err.suggestion, exitCode);
-  };
-  if (fs16.existsSync(dir) && !fs16.statSync(dir).isDirectory()) fail(sessionDirIsFileError(dir));
-  const socketPath = getSessionFilePath("DAEMON_SOCKET");
-  if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
-    fail(
-      socketPathTooLongError(socketPath, MAX_DAEMON_SOCKET_PATH_BYTES),
+async function showPageInfo(options) {
+  await runCommand(
+    async () => {
+      const response = await getStatus();
+      if (response.status === "error") {
+        return {
+          success: false,
+          error: response.error ?? "Failed to read the page",
+          exitCode: EXIT_CODES.SOFTWARE_ERROR
+        };
+      }
+      const page = response.data?.sessionPid ? response.data.pageState : void 0;
+      if (!page) throw noActiveSessionError();
+      return { success: true, data: { url: page.url, title: page.title } };
+    },
+    options,
+    (page) => new OutputFormatter().keyValueList(
+      [
+        ["URL", page.url],
+        ["Title", page.title]
+      ],
+      8
+    ).build()
+  );
+}
+function emulationRequest(options) {
+  if (options.reset) return { reset: true };
+  if (options.viewport === void 0 && options.colorScheme === void 0) {
+    const err = pageEmulateNothingError();
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
       EXIT_CODES.INVALID_ARGUMENTS
     );
   }
-  try {
-    ensureSessionDir();
-    fs16.accessSync(dir, fs16.constants.W_OK);
-  } catch (error) {
-    const code = error.code;
-    const denied = code === "EACCES" || code === "EPERM" || code === "EROFS";
-    fail(
-      sessionDirNotWritableError(dir, code ?? getErrorMessage(error)),
-      denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR
-    );
-  }
-}
-var MAX_LOG_BYTES = 5 * 1024 * 1024;
-function rotateLog(logPath) {
-  try {
-    if (fs16.statSync(logPath).size > MAX_LOG_BYTES) {
-      fs16.renameSync(logPath, `${logPath}.1`);
-    }
-  } catch (error) {
-    log26.debug(`Daemon log not rotated: ${getErrorMessage(error)}`);
-  }
-}
-async function waitForDaemonReady(hasExited) {
-  const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    if (await isDaemonAlive()) {
-      log26.debug("Daemon is ready");
-      return;
-    }
-    if (hasExited() && !await isDaemonAlive()) {
-      throw new DaemonStartupError(
-        `Daemon exited during startup. See ${join7(getSessionDir(), "daemon.log")}`,
-        "DAEMON_EXITED"
-      );
+  return {
+    ...options.viewport !== void 0 && { viewport: parseViewport(options.viewport) },
+    ...options.colorScheme !== void 0 && {
+      colorScheme: parseColorScheme(options.colorScheme)
     }
-    await delay2(DAEMON_READY_POLL_MS);
-  }
-  throw new DaemonStartupError(
-    `Daemon failed to start within ${DAEMON_READY_TIMEOUT_MS / 1e3} seconds`,
-    "DAEMON_START_TIMEOUT"
+  };
+}
+async function emulate(options) {
+  await runCommand(
+    async () => {
+      const response = await pageEmulate(emulationRequest(options));
+      if (response.status === "error" || !response.data) {
+        return {
+          success: false,
+          error: response.error ?? "Failed to change the emulation",
+          exitCode: response.exitCode ?? EXIT_CODES.SOFTWARE_ERROR,
+          ...response.suggestion && { errorContext: { suggestion: response.suggestion } }
+        };
+      }
+      return { success: true, data: response.data };
+    },
+    options,
+    (result) => new OutputFormatter().text("\u2713 Page emulation changed").keyValueList(pageEmulationLines(result), 10).build()
   );
 }
-
-// src/commands/shared/startHelpers.ts
-init_messages();
-init_client();
-init_transport();
-init_errors2();
-init_paths();
-init_formatting();
-init_logging();
-init_sessionCommand();
-init_errors();
-init_exitCodes();
-var log27 = createLogger("bdg");
-async function startSessionViaDaemon(url, options, telemetry) {
-  process.once("SIGINT", () => reportStartOutcome(interruptedOutcome("SIGINT"), options));
-  process.once("SIGTERM", () => reportStartOutcome(interruptedOutcome("SIGTERM"), options));
-  let outcome = await requestSession(url, options, telemetry);
-  const deadline = Date.now() + SHUTDOWN_WAIT_MS;
-  while (isShuttingDown(outcome) && Date.now() < deadline) {
-    await delay2(SHUTDOWN_POLL_MS);
-    outcome = await requestSession(url, options, telemetry);
+function registerPageCommands(program2) {
+  const page = program2.command("page").description(
+    "The session page: info (URL and title), navigate <url>, reload, back, forward, emulate (viewport, color scheme)"
+  );
+  page.command("info").description(PAGE_INFO_DESCRIPTION).addOption(jsonOption()).action(async (options) => {
+    await showPageInfo(options);
+  });
+  const withCommon = (command) => command.option("--no-wait", "Return without waiting for the page to load").addOption(jsonOption());
+  withCommon(
+    page.command("navigate").description("Load a URL in the session page").argument("<url>", "URL to load")
+  ).action(async (url, options) => {
+    await runPageAction("navigate", options, url);
+  });
+  page.command("emulate").description(PAGE_EMULATE_DESCRIPTION).option("--viewport <WxH>", "Viewport size in CSS px, e.g. 900x700").option("--color-scheme <scheme>", "Emulate prefers-color-scheme: light or dark").addOption(
+    new Option("--reset", "Back to the browser window size and the system setting").conflicts([
+      "viewport",
+      "colorScheme"
+    ])
+  ).addOption(jsonOption()).action(async (options) => {
+    await emulate(options);
+  });
+  for (const action of ["reload", "back", "forward"]) {
+    withCommon(page.command(action).description(PAGE_ACTION_DESCRIPTIONS[action])).action(
+      async (options) => {
+        await runPageAction(action, options);
+      }
+    );
   }
-  reportStartOutcome(outcome, options);
 }
-function interruptedOutcome(signal) {
-  const message = `Start cancelled (${signal === "SIGINT" ? "interrupted" : "terminated"})`;
-  const exitCode = signal === "SIGINT" ? EXIT_CODES.INTERRUPTED : EXIT_CODES.TERMINATED;
-  return { ok: false, error: message, human: message, exitCode };
+
+// src/commands/peek.ts
+function parseOptions(options) {
+  const lastN = positiveIntRule({
+    name: "--last",
+    min: 1,
+    max: MAX_LAST_ITEMS,
+    default: 10,
+    allowZeroForAll: true
+  }).validate(options.last);
+  const resourceTypes = resourceTypeRule().validate(options.type);
+  return { lastN, resourceTypes };
 }
-var SHUTDOWN_WAIT_MS = 15e3;
-var SHUTDOWN_POLL_MS = 200;
-function isShuttingDown(outcome) {
-  return !outcome.ok && (outcome.retryable === true || outcome.errorCode === "SESSION_SHUTTING_DOWN" /* SESSION_SHUTTING_DOWN */);
+function peekSection(options) {
+  if (options.network) return "network";
+  return options.console ? "console" : void 0;
 }
-async function requestSession(url, options, telemetry) {
-  try {
-    await launchDaemon();
-  } catch (error) {
-    if (error instanceof SessionDirError) {
-      return {
-        ok: false,
-        error: error.message,
-        human: joinLines(genericError(error.message), error.suggestion),
-        exitCode: error.exitCode,
-        details: { suggestion: error.suggestion }
-      };
-    }
-    const message = `Failed to start daemon: ${getErrorMessage(error)}`;
-    const exitCode = error instanceof DaemonError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
-    return { ok: false, error: message, human: genericError(message), exitCode };
-  }
-  try {
-    log27.debug("Connecting to daemon...");
-    const response = await startSession(
-      url,
-      filterDefined({
-        port: options.port,
-        timeout: options.timeout,
-        telemetry: telemetry.length > 0 ? telemetry : void 0,
-        includeAll: options.includeAll,
-        userDataDir: options.userDataDir,
-        maxBodySize: options.maxBodySize,
-        headless: options.headless,
-        chromeWsUrl: options.chromeWsUrl,
-        chromeFlags: options.chromeFlags,
-        viewport: options.viewport,
-        colorScheme: options.colorScheme
-      })
-    );
-    if (response.status === "error") return describeStartFailure(response, options);
-    if (!response.data) {
-      const message = "Invalid response from daemon: missing data";
-      return {
-        ok: false,
-        error: message,
-        human: invalidResponseError("missing data"),
-        exitCode: EXIT_CODES.SOFTWARE_ERROR
-      };
-    }
-    return { ok: true, data: response.data };
-  } catch (error) {
-    if (error instanceof IPCTimeoutError) {
-      const timeout = timeoutError(error);
-      return {
-        ok: false,
-        error: timeout.message,
-        human: joinLines(genericError(timeout.message), String(timeout.metadata.suggestion)),
-        exitCode: timeout.exitCode,
-        details: { suggestion: timeout.metadata.suggestion }
-      };
-    }
-    if (isConnectionError(error)) {
-      return {
-        ok: false,
-        error: `${noActiveSessionMessage()} (daemon not running)`,
-        human: daemonNotRunningError({ suggestStatus: true, suggestRetry: true }),
-        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
-        retryable: true
-      };
-    }
-    const message = getErrorMessage(error);
-    return {
-      ok: false,
-      error: message,
-      human: genericError(message),
-      exitCode: EXIT_CODES.SOFTWARE_ERROR
-    };
+async function fetchAndFilterPreview(lastN, resourceTypes, only) {
+  const result = await fetchPreviewOutput({
+    lastN: resourceTypes.length > 0 ? 0 : lastN,
+    ...only && { only }
+  });
+  if (!result.success) return result;
+  const output = result.data;
+  const unfilteredNetworkCount = output.totals?.network ?? output.data.network?.length ?? 0;
+  if (resourceTypes.length === 0 || !output.data.network) {
+    return { success: true, data: { output, unfilteredNetworkCount } };
   }
+  const network = filterByResourceType(output.data.network, resourceTypes);
+  const filteredOutput = {
+    ...output,
+    data: { ...output.data, network },
+    ...output.totals && { totals: { ...output.totals, network: network.length } }
+  };
+  return { success: true, data: { output: filteredOutput, unfilteredNetworkCount } };
 }
-function omitDuration(existing) {
-  const { duration: _duration, ...rest } = existing;
-  return rest;
+function createPreviewOptions(base, resourceTypes, unfilteredCount) {
+  const options = { ...base };
+  if (base.follow) options.viewedAt = /* @__PURE__ */ new Date();
+  if (resourceTypes.length > 0) {
+    options.filteredTypes = resourceTypes;
+    options.unfilteredNetworkCount = unfilteredCount;
+  }
+  return options;
 }
-function describeStartFailure(response, options) {
-  const exitCode = response.exitCode ?? getExitCodeForIPCError(response.errorCode);
-  const existing = response.existingSession;
-  const details = filterDefined({
-    existingSession: existing && {
-      ...omitDuration(existing),
-      ...existing.duration !== void 0 && { durationMs: existing.duration * 1e3 }
+async function runFollowMode3(options, lastN, resourceTypes, baseOptions) {
+  const showPreview = async () => {
+    const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
+    if (!result.success) {
+      return followFetchFailure(result, { json: options.json, retryIntervalMs: 1e3 });
     }
+    noteFollowConnected();
+    if (!options.json) console.clear();
+    const previewOptions = createPreviewOptions(
+      baseOptions,
+      resourceTypes,
+      result.data.unfilteredNetworkCount
+    );
+    console.log(formatPreview(result.data.output, previewOptions));
+    return void 0;
+  };
+  await setupFollowMode(showPreview, {
+    startMessage: followingPreviewMessage,
+    stopMessage: stoppedFollowingPreviewMessage,
+    intervalMs: 1e3
   });
-  if (response.errorCode === "SESSION_ALREADY_RUNNING" /* SESSION_ALREADY_RUNNING */ && existing) {
-    const { pid, targetUrl, duration } = existing;
-    return {
-      ok: false,
-      error: response.message ?? "Session already running",
-      human: sessionAlreadyRunningError(pid, duration ? duration * 1e3 : 0, targetUrl),
-      exitCode,
-      errorCode: response.errorCode,
-      details: { ...details, suggestion: alreadyRunningSuggestion() }
-    };
-  }
-  if (response.errorCode === "SESSION_TARGET_MISMATCH" /* SESSION_TARGET_MISMATCH */) {
-    const current = response.existingSession?.targetUrl ?? LAUNCHED_CHROME_DESCRIPTION;
-    const requested = options.chromeWsUrl ?? LAUNCHED_CHROME_DESCRIPTION;
-    return {
-      ok: false,
-      error: response.message ?? "Session target mismatch",
-      human: sessionTargetMismatchError(current, requested),
-      exitCode,
-      errorCode: response.errorCode,
-      details
-    };
-  }
-  const message = response.message ?? "Unknown error";
-  const [error = message, ...hint] = message.split("\n");
-  return {
-    ok: false,
-    error,
-    human: genericError(message),
-    exitCode,
-    errorCode: response.errorCode,
-    details: {
-      ...details,
-      ...hint.join("\n").trim() && { suggestion: hint.join("\n").trim() }
+}
+function registerPeekCommand(program2) {
+  program2.command("peek").description("Preview collected data without stopping the session").addOption(jsonOption()).option("-v, --verbose", "Use verbose output with full URLs and formatting", false).option("-n, --network", "Show only network requests", false).option("-c, --console", "Show only console messages", false).option("-f, --follow", "Watch for updates (like tail -f)", false).option("--last <count>", "Show last N items, 0 for all", "10").option(
+    "--type <types>",
+    "Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)"
+  ).action(async (options) => {
+    showBothSectionsWhenBothRequested(options);
+    if (options.network && !options.json) {
+      console.error(
+        'Note: "bdg peek --network" is deprecated. Use "bdg network list" for enhanced filtering.'
+      );
     }
-  };
-}
-function reportStartOutcome(outcome, options) {
-  if (!outcome.ok) {
-    if (options.json) {
-      const envelope = OutputBuilder.buildJsonError(outcome.error, {
-        exitCode: outcome.exitCode,
-        ...outcome.details
-      });
-      console.log(JSON.stringify(envelope, null, 2));
-    } else {
-      console.error(escapeControlChars(outcome.human));
+    let lastN;
+    let resourceTypes;
+    try {
+      const parsed = parseOptions(options);
+      lastN = parsed.lastN;
+      resourceTypes = parsed.resourceTypes;
+    } catch (error) {
+      handleValidationError(error, options.json ?? false);
     }
-    process.exit(outcome.exitCode);
-  }
-  const { data } = outcome;
-  const autoStopAt = options.timeout !== void 0 ? new Date(Date.now() + options.timeout * 1e3) : void 0;
-  const session = getSessionName() ?? void 0;
-  if (options.json) {
-    const result = {
-      ...session && { session },
-      targetUrl: data.targetUrl,
-      ...data.targetTitle !== void 0 && { targetTitle: data.targetTitle },
-      ...data.documentStatus !== void 0 && { documentStatus: data.documentStatus },
-      ...data.loading && { loading: data.loading },
-      port: data.port,
-      ...data.chromePid > 0 ? { chromePid: data.chromePid } : { externalChrome: true },
-      daemonPid: data.daemonPid,
-      ...autoStopAt && { autoStopAt: autoStopAt.toISOString() }
-    };
-    console.log(JSON.stringify(buildSuccessResponse(result), null, 2));
-  } else {
-    const page = {
-      url: data.targetUrl,
-      ...data.documentStatus !== void 0 && { documentStatus: data.documentStatus },
-      ...data.loading && { loading: data.loading },
-      ...autoStopAt && { autoStopAt },
-      ...session && { session }
+    const baseOptions = {
+      json: options.json,
+      network: options.network,
+      console: options.console,
+      last: lastN,
+      verbose: options.verbose,
+      follow: options.follow
     };
-    const text = options.quiet ? [`Session started: ${data.targetUrl}`, ...startNotices(page)].join("\n") : landingPage(page);
-    console.error(escapeControlChars(text));
-  }
-  process.exit(EXIT_CODES.SUCCESS);
+    if (options.follow) {
+      await runFollowMode3(options, lastN, resourceTypes, baseOptions);
+      return;
+    }
+    await runCommand(
+      async () => {
+        const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
+        if (!result.success) {
+          return createErrorResult(result.error, result.exitCode, result.suggestion);
+        }
+        const { output } = result.data;
+        return {
+          success: true,
+          data: options.json ? buildPreviewJsonData(output, baseOptions) : output
+        };
+      },
+      options,
+      (data) => {
+        const output = data;
+        const previewOptions = createPreviewOptions(
+          baseOptions,
+          resourceTypes,
+          output.data.network?.length ?? 0
+        );
+        return formatPreview(output, previewOptions);
+      }
+    );
+  });
 }
 
-// src/commands/start.ts
-init_constants();
-init_errors3();
-init_messages();
-init_commands();
-init_exitCodes();
+// src/session/sessionList.ts
+init_client();
+import * as fs17 from "fs";
+init_paths();
 
-// src/utils/http.ts
-init_constants();
-init_errors();
-var CDP_HTTP_TIMEOUT_MS = 5e3;
-async function probeDevToolsEndpoint(port, logger, options) {
-  const url = `${options?.secure ? "https" : "http"}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
-  let response;
-  try {
-    response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
-  } catch (error) {
-    logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
-    return { kind: "unreachable" };
-  }
+// src/session/portClaims.ts
+import * as fs16 from "fs";
+init_paths();
+init_logging();
+var log26 = createLogger("session");
+function readPortFile(portPath) {
   try {
-    const data = await response.json();
-    const wsUrl = data?.webSocketDebuggerUrl;
-    if (response.ok && typeof wsUrl === "string") return { kind: "devtools", wsUrl };
+    const port = parseInt(fs16.readFileSync(portPath, "utf-8").trim(), 10);
+    return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
   } catch (error) {
-    logger?.debug(`Chrome version response is not JSON: ${getErrorMessage(error)} (${url})`);
+    logDebugError(log26, `read ${portPath}`, error);
+    return null;
   }
-  return { kind: "not-devtools" };
 }
 
-// src/commands/start.ts
-init_suggestions();
-init_url();
-function hasDisplay() {
-  const display = process.env["DISPLAY"];
-  const wayland = process.env["WAYLAND_DISPLAY"];
-  return display !== void 0 && display !== "" || wayland !== void 0 && wayland !== "";
+// src/session/sessionName.ts
+init_errors3();
+init_messages();
+init_paths();
+init_exitCodes();
+var MAX_SESSION_NAME_LENGTH = 40;
+var SESSION_NAME_PATTERN = new RegExp(
+  `^[A-Za-z0-9][A-Za-z0-9_-]{0,${MAX_SESSION_NAME_LENGTH - 1}}$`
+);
+function isValidSessionName(name) {
+  return SESSION_NAME_PATTERN.test(name);
 }
-function expandHome(value) {
-  return value.startsWith("~/") ? value.replace(/^~/, os3.homedir()) : value;
+function normalizeSessionName(name) {
+  return name.toLowerCase();
 }
-function extractUserDataDirFromFlags(flags) {
-  const rest = [];
-  let userDataDir;
-  for (let i = 0; i < flags.length; i++) {
-    const flag = flags[i];
-    if (flag.startsWith("--user-data-dir=")) {
-      userDataDir = flag.slice("--user-data-dir=".length);
-      continue;
-    }
-    if (flag === "--user-data-dir" && i + 1 < flags.length) {
-      userDataDir = flags[i + 1];
-      i++;
-      continue;
-    }
-    rest.push(flag);
+function validateSessionName(name) {
+  if (!isValidSessionName(name)) {
+    throwInvalid(invalidSessionNameError(name, MAX_SESSION_NAME_LENGTH));
+  }
+  const shortest = namedSocketPath("a");
+  if (Buffer.byteLength(shortest) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+    throwInvalid(socketPathTooLongError(shortest, MAX_DAEMON_SOCKET_PATH_BYTES));
+  }
+  const socketPath = namedSocketPath(name);
+  if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+    throwInvalid(sessionNameSocketTooLongError(name, socketPath, MAX_DAEMON_SOCKET_PATH_BYTES));
   }
-  return {
-    userDataDir: userDataDir ? expandHome(userDataDir) : void 0,
-    rest
-  };
-}
-function applyCollectorOptions(command) {
-  const defaultHeadless = !hasDisplay();
-  return command.option("-p, --port <number>", PORT_OPTION_DESCRIPTION).option(
-    "-t, --timeout <seconds>",
-    "Stop the session this many seconds after the page has loaded (unlimited if not specified)"
-  ).option("-u, --user-data-dir <path>", "Chrome user data directory (defaults to session dir)").option(
-    "-a, --all",
-    "Include all data: no tracking/analytics filtering, and capture every response body (incl. binary)",
-    false
-  ).option("-m, --max-body-size <megabytes>", "Maximum response body size in MB", "5").addOption(new Option("--compact", "No effect; kept for compatibility").hideHelp()).option(
-    "--headless",
-    "Run Chrome without a window (default unless DISPLAY or WAYLAND_DISPLAY is set)",
-    defaultHeadless
-  ).option("--no-headless", "Show browser window").option(
-    "--chrome-ws-url <url>",
-    "Connect to an existing Chrome: its DevTools port (9222, host:port, http://host:port), or a WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)"
-  ).option("-q, --quiet", "Quiet mode - minimal output for AI agents", false).addOption(jsonOption()).option(
-    "--chrome-flags <flags>",
-    'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")'
-  ).option(
-    "--viewport <WxH>",
-    "Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)"
-  ).option(
-    "--color-scheme <scheme>",
-    "Emulate prefers-color-scheme for the session: light or dark (default: the system setting)"
-  );
-}
-var MAX_VIEWPORT_SIDE = 1e4;
-var COLOR_SCHEMES = ["light", "dark"];
-function parseViewport(value) {
-  const match = /^\s*(\d+)\s*[xX×,]\s*(\d+)\s*$/.exec(value);
-  const width = Number(match?.[1]);
-  const height = Number(match?.[2]);
-  const valid2 = (side) => side >= 1 && side <= MAX_VIEWPORT_SIDE;
-  if (match && valid2(width) && valid2(height)) return { width, height };
-  const err = invalidViewportError(value, MAX_VIEWPORT_SIDE);
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-}
-function parseColorScheme(value) {
-  const scheme = COLOR_SCHEMES.find((candidate) => candidate === value.trim().toLowerCase());
-  if (scheme) return scheme;
-  const err = invalidColorSchemeError(value, findSimilar(value, [...COLOR_SCHEMES]), COLOR_SCHEMES);
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-}
-function buildSessionOptions(options) {
-  const maxBodySizeRule = positiveIntRule({
-    name: "--max-body-size",
-    min: 1,
-    max: 100,
-    required: false
-  });
-  const timeoutRule = positiveIntRule({ name: "--timeout", min: 1, max: 3600, required: false });
-  const portRule = positiveIntRule({ name: "--port", min: 1024, max: 65535, required: false });
-  const maxBodySizeMB = options.maxBodySize !== void 0 ? maxBodySizeRule.validate(options.maxBodySize) : void 0;
-  const timeout = options.timeout !== void 0 ? timeoutRule.validate(options.timeout) : void 0;
-  const envFlags = process.env["BDG_CHROME_FLAGS"]?.split(" ").filter(Boolean) ?? [];
-  const cliFlags = options.chromeFlags?.split(" ").filter(Boolean) ?? [];
-  const { userDataDir: flagUserDataDir, rest: combinedFlags } = extractUserDataDirFromFlags([
-    ...envFlags,
-    ...cliFlags
-  ]);
-  const userDataDir = options.userDataDir ? expandHome(options.userDataDir) : flagUserDataDir;
-  const chromeFlags = combinedFlags.length > 0 ? combinedFlags : void 0;
-  return {
-    port: options.port !== void 0 ? portRule.validate(options.port) : void 0,
-    timeout,
-    userDataDir,
-    includeAll: options.all ?? false,
-    maxBodySize: maxBodySizeMB !== void 0 ? maxBodySizeMB * 1024 * 1024 : void 0,
-    headless: options.headless ?? !hasDisplay(),
-    chromeWsUrl: options.chromeWsUrl,
-    quiet: options.quiet ?? false,
-    json: options.json ?? false,
-    chromeFlags,
-    viewport: options.viewport !== void 0 ? parseViewport(options.viewport) : void 0,
-    colorScheme: options.colorScheme !== void 0 ? parseColorScheme(options.colorScheme) : void 0
-  };
 }
-var SESSION_TELEMETRY = ["dom", "network", "console"];
-var FLAG_WORDS = { version: "--version", help: "--help" };
-function assertNotCommandTypo(arg, commandNames) {
-  if (!/^[a-z][a-z0-9_-]*$/i.test(arg) || arg.toLowerCase() === "localhost") return;
-  const flag = FLAG_WORDS[arg.toLowerCase()];
-  const err = unknownCommandError(arg, flag ? [flag] : findSimilar(arg, commandNames));
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+function namedSocketPath(name) {
+  return sessionFilePathIn(getNamedSessionDir(name), "DAEMON_SOCKET");
 }
-function assertNotGroupSubcommand(program2, argv) {
-  const [first] = argv.slice(2).filter((arg) => !arg.startsWith("-"));
-  if (first === void 0 || program2.commands.some((command) => command.name() === first)) return;
-  const group = program2.commands.find(
-    (command) => command.commands.some((sub) => sub.name() === first)
-  );
-  if (!group) return;
-  const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+function throwInvalid(err) {
   throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function validateStartInput(url, options, program2) {
-  if (url === void 0) {
-    const err = missingStartUrlError();
-    throw new CommandError(
-      err.message,
-      { suggestion: err.suggestion },
-      EXIT_CODES.INVALID_ARGUMENTS
-    );
+function selectSession(optionValue) {
+  const name = optionValue ?? process.env[SESSION_NAME_ENV]?.trim();
+  if (name === void 0 || optionValue === void 0 && name === "") {
+    delete process.env[SESSION_NAME_ENV];
+    return;
   }
-  assertNotCommandTypo(
-    url,
-    program2.commands.map((command) => command.name())
-  );
-  assertValidUrl(url);
-  if (options.chromeWsUrl !== void 0) {
-    assertValidChromeWsUrl(options.chromeWsUrl);
-    assertNoLaunchOptions(options, program2);
+  validateSessionName(name);
+  process.env[SESSION_NAME_ENV] = normalizeSessionName(name);
+}
+
+// src/session/sessionList.ts
+init_logging();
+init_sessionCommand();
+var log27 = createLogger("session");
+function toRunningSession(name, data) {
+  const meta = data.sessionMetadata;
+  const state = meta ? "active" : data.ending ? "ending" : "starting";
+  const url = data.pageState?.url ?? data.starting?.url;
+  return {
+    name,
+    state,
+    ...url !== void 0 && { url },
+    ...meta && { port: meta.port },
+    daemonPid: data.daemonPid,
+    ...meta?.chromePid && { chromePid: meta.chromePid }
+  };
+}
+async function describeSession(entry) {
+  const { name, dir } = entry;
+  const socketPath = sessionFilePathIn(dir, "DAEMON_SOCKET");
+  const probe = await probeDaemonSocket(socketPath);
+  if (probe !== "alive") return describeWithoutSocket(entry, probe);
+  try {
+    const response = await getStatus(socketPath);
+    if (response.status === "ok" && response.data) return toRunningSession(name, response.data);
+  } catch (error) {
+    logDebugError(log27, `get status of ${dir}`, error);
   }
-  if (options.userDataDir !== void 0) assertUserDataDir(options.userDataDir);
-  if (options.chromeWsUrl === void 0)
-    assertChromeFlags([
-      ...process.env["BDG_CHROME_FLAGS"]?.split(" ") ?? [],
-      ...options.chromeFlags?.split(" ") ?? []
-    ]);
-  return { url, sessionOptions: buildSessionOptions(options) };
+  return { name, state: "unresponsive" };
 }
-function registerStartCommands(program2) {
-  applyCollectorOptions(
-    program2.argument("[url]", "Target URL (example.com or localhost:3000)")
-  ).action(async (url, options) => {
-    if (url === void 0 && !hasUserOptions(program2)) {
-      console.error(startCommandHelpMessage());
-      process.exit(0);
-    }
-    let validated;
-    try {
-      validated = validateStartInput(url, options, program2);
-      validated.sessionOptions.chromeWsUrl = await resolveChromeWsUrl(
-        validated.sessionOptions.chromeWsUrl
-      );
-    } catch (error) {
-      handleValidationError(error, options.json ?? false);
-    }
-    await startSessionViaDaemon(validated.url, validated.sessionOptions, SESSION_TELEMETRY);
-  });
+function describeWithoutSocket(entry, probe) {
+  const daemonPid = readLiveDaemonPid(entry.dir);
+  if (daemonPid !== null) return { name: entry.name, state: "starting", daemonPid };
+  return describeLeftovers(entry, probe);
 }
-async function resolveChromeWsUrl(value) {
-  const endpoint = value === void 0 ? null : devToolsHttpEndpoint(value);
-  if (endpoint === null) return value;
-  const { hostname, port, protocol } = new URL(endpoint);
-  const secure = protocol === "https:";
-  const defaultPort = secure ? 443 : 80;
-  const probe = await probeDevToolsEndpoint(Number(port) || defaultPort, void 0, {
-    host: hostname,
-    secure
-  });
-  if (probe.kind === "devtools") return atEndpoint(probe.wsUrl, endpoint);
-  const err = probe.kind === "not-devtools" ? notDevToolsEndpointError(endpoint) : externalChromeUnreachableError(endpoint, false);
-  throw new CommandError(
-    err.message,
-    { suggestion: err.suggestion },
-    EXIT_CODES.CDP_CONNECTION_FAILURE
-  );
+function describeLeftovers({ name, dir }, probe) {
+  const chromePid = readPidFromFile(sessionFilePathIn(dir, "CHROME_PID"));
+  const orphan = chromePid !== null && isProcessAlive(chromePid) && isSessionChrome(chromePid, dir);
+  const leftover = probe === "stale" || SESSION_STATE_FILES.some((type) => fs17.existsSync(sessionFilePathIn(dir, type)));
+  if (!orphan && !leftover) return null;
+  const port = leftoverPort(dir);
+  return {
+    name,
+    state: orphan ? "crashed" : "stale",
+    ...port !== null && { port },
+    ...orphan && { chromePid },
+    cleanup: sessionCommand("bdg cleanup", name)
+  };
 }
-function atEndpoint(wsUrl, endpoint) {
-  const resolved = new URL(wsUrl);
-  const target = new URL(endpoint);
-  resolved.protocol = target.protocol === "https:" ? "wss:" : "ws:";
-  resolved.host = target.host;
-  return resolved.toString();
+function leftoverPort(dir) {
+  try {
+    const meta = JSON.parse(fs17.readFileSync(sessionFilePathIn(dir, "METADATA"), "utf8"));
+    if (typeof meta.port === "number") return meta.port;
+  } catch (error) {
+    logDebugError(log27, `read the metadata in ${dir}`, error);
+  }
+  return readPortFile(sessionFilePathIn(dir, "PORT"));
 }
-function hasUserOptions(program2) {
-  return program2.options.some(
-    (option) => program2.getOptionValueSource(option.attributeName()) === "cli"
-  );
+function isSelectable({ name }) {
+  return name === null || isValidSessionName(name) && name === normalizeSessionName(name);
 }
-function assertUserDataDir(value) {
-  const resolved = expandHome(value);
-  let reason;
-  if (!value.trim()) reason = "the path is empty";
-  else if (value.startsWith("-")) reason = "it looks like an option; -u needs a directory path";
-  else if (fs17.existsSync(resolved) && !fs17.statSync(resolved).isDirectory()) reason = "it is a file";
-  if (reason === void 0) return;
-  const err = invalidUserDataDirError(value, reason);
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+function isSameDir(a, b) {
+  try {
+    const first = fs17.statSync(a);
+    const second = fs17.statSync(b);
+    return first.ino === second.ino && first.dev === second.dev;
+  } catch (error) {
+    logDebugError(log27, `compare ${a} with ${b}`, error);
+    return false;
+  }
 }
-function launchOptionConflicts(options, program2) {
-  const headlessGiven = program2.getOptionValueSource("headless") === "cli";
-  return [
-    ...options.port !== void 0 ? ["--port"] : [],
-    ...options.userDataDir !== void 0 ? ["--user-data-dir"] : [],
-    ...headlessGiven ? [options.headless ? "--headless" : "--no-headless"] : []
-  ];
+function selectableEntry(entry) {
+  if (isSelectable(entry) || entry.name === null) return entry;
+  const lower = normalizeSessionName(entry.name);
+  if (!isValidSessionName(lower)) return null;
+  return isSameDir(entry.dir, getNamedSessionDir(lower)) ? { name: lower, dir: entry.dir } : null;
 }
-function assertNoLaunchOptions(options, program2) {
-  const conflicts = launchOptionConflicts(options, program2);
-  if (conflicts.length === 0) return;
-  const err = chromeWsUrlConflictError(conflicts);
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+async function describeUnselectable(entry) {
+  const socketPath = sessionFilePathIn(entry.dir, "DAEMON_SOCKET");
+  if (await probeDaemonSocket(socketPath) === "alive") return describeSession(entry);
+  return { name: entry.name, state: "stale", cleanup: removeDirCommand(entry.dir) };
 }
-var BDG_OPTION_WORDS = /* @__PURE__ */ new Set([
-  "--json",
-  "-j",
-  "--port",
-  "-p",
-  "--no-headless",
-  "-q",
-  "--quiet"
-]);
-function assertChromeFlags(flags) {
-  const flag = flags.find(
-    (value) => /^--remote-debugging-(port|pipe)\b/.test(value) || BDG_OPTION_WORDS.has(value)
+async function listRunningSessions() {
+  const listed = /* @__PURE__ */ new Set();
+  const sessions = await Promise.all(
+    listSessionDirs().map((entry) => {
+      const selectable = selectableEntry(entry);
+      if (selectable === null) return describeUnselectable(entry);
+      if (listed.has(selectable.name)) return Promise.resolve(null);
+      listed.add(selectable.name);
+      return describeSession(selectable);
+    })
   );
-  if (flag === void 0) return;
-  const err = invalidChromeFlagError(flag);
-  throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+  return sessions.filter((session) => session !== null);
 }
-function assertValidUrl(url) {
-  const result = validateUrl(url);
-  if (result.valid) return;
-  throw new CommandError(
-    result.error,
-    result.suggestion ? { suggestion: result.suggestion } : {},
-    EXIT_CODES.INVALID_URL
+
+// src/ui/formatters/sessions.ts
+init_formatting();
+var DEFAULT_SESSION_LABEL = "(default)";
+function formatSessionList(data) {
+  const fmt = new OutputFormatter();
+  if (data.sessions.length === 0) {
+    return fmt.text("No running sessions").hints("Suggestions:", ["Start one:  bdg <url> [--session <name>]"]).build();
+  }
+  const rows = data.sessions.map((session) => [
+    session.name ?? DEFAULT_SESSION_LABEL,
+    session.state,
+    session.port?.toString() ?? "-",
+    session.daemonPid?.toString() ?? "-",
+    session.url ?? "-"
+  ]);
+  const header = ["SESSION", "STATE", "PORT", "PID", "URL"];
+  const widths = header.map(
+    (title, column) => Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0))
   );
+  for (const row of [header, ...rows]) {
+    fmt.text(
+      row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd()
+    );
+  }
+  const cleanups = data.sessions.flatMap((session) => session.cleanup ? [session.cleanup] : []);
+  if (cleanups.length > 0) {
+    fmt.hints("Crashed or stale sessions; clean up with:", cleanups);
+  }
+  return fmt.build();
 }
-function assertValidChromeWsUrl(url) {
-  const result = validateChromeWsUrl(url);
-  if (result.valid) return;
-  throw new CommandError(
-    result.error,
-    result.suggestion ? { suggestion: result.suggestion } : {},
-    EXIT_CODES.INVALID_URL
-  );
+
+// src/commands/sessions.ts
+function registerSessionsCommand(program2) {
+  program2.command("sessions").description(
+    "List sessions (default and named) with their state, URL, port and PID, including crashed ones to clean up"
+  ).addOption(jsonOption()).action(async (options) => {
+    await runCommand(
+      async () => ({ success: true, data: { sessions: await listRunningSessions() } }),
+      options,
+      formatSessionList
+    );
+  });
 }
 
 // src/commands/status.ts