browser-debugger-cli 0.10.0 → 0.12.0

package/dist/index.js

@@ -567,13 +567,13 @@ var require_common = __commonJS({
           }
         }
       }
-      function matchesTemplate(search, template) {
+      function matchesTemplate(search2, template) {
         let searchIndex = 0;
         let templateIndex = 0;
         let starIndex = -1;
         let matchIndex2 = 0;
-        while (searchIndex < search.length) {
-          if (templateIndex < template.length && (template[templateIndex] === search[searchIndex] || template[templateIndex] === "*")) {
+        while (searchIndex < search2.length) {
+          if (templateIndex < template.length && (template[templateIndex] === search2[searchIndex] || template[templateIndex] === "*")) {
             if (template[templateIndex] === "*") {
               starIndex = templateIndex;
               matchIndex2 = searchIndex;
@@ -2412,6 +2412,9 @@ function pageNavigationText(navigation) {
   const status = navigation.status === void 0 ? "" : ` (${navigation.status})`;
   return `navigated to ${navigation.url}${status}`;
 }
+function moreMessagesText(count) {
+  return `(+${count} more)`;
+}
 function newMessageText(message) {
   return `"${message.text}" (${message.element})`;
 }
@@ -2508,8 +2511,11 @@ function coverText(cover, transparent) {
 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 inspectPseudoOfNote(pseudo) {
+  return `Inspected the element of ${pseudo}: pseudo-elements cannot be selected; ${pseudo} is on the pseudo line (content, size, position, inset, colors)`;
+}
+function inspectDarkThemeBadge(emulated = false) {
+  return emulated ? "[dark theme, emulated; bdg page emulate --color-scheme light for light]" : "[dark theme from system; --color-scheme light for light]";
 }
 function inspectVisibilityBadges(visibility) {
   const reason = (text) => text ? `: ${text}` : "";
@@ -2636,8 +2642,16 @@ function emptyElementLine(children, count) {
   const more = count > children.length ? `, \u2026 ${count - children.length} more` : "";
   return `No text; holds ${pluralize(count, "element")}: ${children.join(", ")}${more} (see its HTML with --raw)`;
 }
-function screenshotGrownNote(box, captured) {
-  return `grown from ${box.width}\xD7${box.height} to ${captured.width}\xD7${captured.height} to include content overflowing the element`;
+function screenshotScaledNote(originalWidth, originalHeight, width, height) {
+  return `scaled from ${originalWidth}\xD7${originalHeight} to ${width}\xD7${height}; --no-resize for full size`;
+}
+function screenshotGrownNote(box, captured, padding = 0) {
+  const painted = { width: captured.width - 2 * padding, height: captured.height - 2 * padding };
+  const grew = painted.width > box.width + 0.5 || painted.height > box.height + 0.5;
+  const ink = `grown from ${box.width}\xD7${box.height} to ${painted.width}\xD7${painted.height} to include what it paints outside its box (overflowing content, shadows, outline)`;
+  const pad = `${padding}px of page around it (--padding)`;
+  if (!padding) return ink;
+  return grew ? `${ink}, plus ${pad}` : `with ${pad}: ${captured.width}\xD7${captured.height}`;
 }
 function queryNextSteps(index) {
   return `Next: bdg dom get ${index} (text), bdg dom get ${index} --raw (HTML), bdg dom layout ${index} (position)`;
@@ -2689,14 +2703,15 @@ function startCommandHelpMessage() {
 function pageEmulateNothingError() {
   return {
     message: "Nothing to emulate",
-    suggestion: "Give --viewport <WxH>, --color-scheme light|dark, or --reset, e.g. bdg page emulate --viewport 900x700"
+    suggestion: "Give --viewport <WxH>, --mobile, --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;
+  const phone = emulated.viewport?.mobile ? " (phone: mobile layout, touch, mobile user agent)" : "";
   return [
-    ["Viewport", emulated.viewport ? size(emulated.viewport) : "the browser window"],
+    ["Viewport", emulated.viewport ? `${size(emulated.viewport)}${phone}` : "the browser window"],
     ...result.viewport ? [["Layout", `${size(result.viewport)} (without scrollbars)`]] : [],
     [
       "Scheme",
@@ -2710,7 +2725,7 @@ function inspectAnimatingBadge(animating) {
 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 REQUIRED_FIELD_EMPTY_REASON, NO_VISIBLE_EFFECT, HOVER_OFF_DONE, HOVER_USAGE, 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, AUDIT_HELP_EXAMPLES, CSS_SEARCH_HELP_EXAMPLES;
 var init_commands = __esm({
   "src/ui/messages/commands.ts"() {
     "use strict";
@@ -2720,6 +2735,8 @@ var init_commands = __esm({
     init_strings();
     REQUIRED_FIELD_EMPTY_REASON = "Required field is empty";
     NO_VISIBLE_EFFECT = "no visible effect observed: no DOM change, requests or navigation within 300 ms";
+    HOVER_OFF_DONE = "\u2713 Mouse moved off the page (hover styles and menus that close on mouseleave are gone)";
+    HOVER_USAGE = "bdg dom hover <selector|index>, or bdg dom hover --off to move the mouse away";
     LAYOUT_REASONS = {
       /** Hidden: an `<option>` of a closed `<select>` has no box */
       option: "not rendered (an <option> is shown by its <select>)",
@@ -2748,8 +2765,14 @@ Output notation:
   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)
+                  (rendered "X") = drawn with another font than declared (a fallback);
+                  (resolves to "X") = the font a generic family (sans-serif, system-ui) became
   contrast 4.47   WCAG ratio, rounded down, against the background behind the text
+  text in X       the text is drawn by descendant X (the one with most of it): its font, color, contrast
+  truncated       the text is cut off (overflow clip, ellipsis or line clamp); a "\u2026" in the header is
+                  only bdg shortening the text
+  .a.b(+3)        the first two classes and how many more the element has
+  sizing content-box  padding and border add to the CSS size (shown only then; border-box is not)
   (+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)
@@ -2803,6 +2826,21 @@ Sessions follow the system color scheme; start with --color-scheme light|dark to
       "  bdg dom wait --load                       # the page finished loading"
     );
     FRAME_URL_MAX_LENGTH = 100;
+    AUDIT_HELP_EXAMPLES = `
+Examples:
+  bdg dom audit                       All checks
+  bdg dom audit contrast --level AAA  Text below WCAG AAA, weakest first
+  bdg dom audit overflow              What scrolls sideways, cut-off text, scaled images
+  bdg dom audit layers animations     Fixed/sticky elements and running animations
+
+Follow up on a finding with bdg dom inspect <element> (e.g. --why color).`;
+    CSS_SEARCH_HELP_EXAMPLES = `
+Examples:
+  bdg css search -- --brand       Where a custom property is set and used (-- before a text
+                                  that starts with -; options go before it:
+                                  bdg css search --limit 50 -- --brand)
+  bdg css search "oklch("         Rules that use oklch colors
+  bdg css search ".btn-primary"   Rules of a class, in every stylesheet`;
   }
 });
 
@@ -3248,6 +3286,7 @@ function noNodesFoundError(selector, context = {}) {
       joinLines(
         context.similar,
         context.shadowHost && shadowBoundaryLine(context.shadowHost),
+        shadowPseudoLine(selector),
         `${hidden}Verify the CSS selector is correct.`,
         note ? note : void 0
       ),
@@ -3256,6 +3295,13 @@ function noNodesFoundError(selector, context = {}) {
     )
   };
 }
+function shadowPseudoLine(selector) {
+  const part = /::part\(\s*([^)\s]+)\s*\)/.exec(selector)?.[1];
+  if (part) {
+    return `::part() styles a shadow part and selects nothing; bdg searches open shadow roots, so select the part itself: [part~="${part}"]`;
+  }
+  return /::slotted\(/.test(selector) ? "::slotted() selects nothing; select the slotted element itself (it is in the light DOM)" : void 0;
+}
 function shellQuote(value) {
   return `'${value.split("'").join(`'\\''`)}'`;
 }
@@ -3285,6 +3331,12 @@ function elementZeroDimensionsError() {
     suggestion: "It may be collapsed or empty; capture a visible ancestor instead"
   };
 }
+function hoverOffWithTargetError() {
+  return {
+    message: "--off moves the mouse off the page; it takes no element",
+    suggestion: "Use bdg dom hover --off alone, or bdg dom hover <selector> to hover an element"
+  };
+}
 function missingArgumentError(usage) {
   return {
     message: "Missing required argument or flag",
@@ -3358,6 +3410,27 @@ function formInIframeError(iframeUrl, crossOrigin) {
     suggestion: crossOrigin ? "Cross-origin iframes cannot be read or controlled; open the iframe URL directly: bdg <iframe url>" : 'dom form lists forms of the main document only; its fields are reachable directly: bdg dom query "input, select, textarea", then bdg dom fill <index> <value>'
   };
 }
+function skillSourceMissingError(source) {
+  return {
+    message: `The bdg skill is missing from the installed package (${source})`,
+    suggestion: "Reinstall bdg: npm install -g browser-debugger-cli"
+  };
+}
+function skillWriteFailedError(path6, reason) {
+  return {
+    message: `Could not write ${path6}: ${reason}`,
+    suggestion: "Check the permissions of that directory, or install for the other agent only (--claude or --agents)"
+  };
+}
+function intervalWithoutFollowError() {
+  return {
+    message: "--interval sets how often --follow refreshes",
+    suggestion: "Add --follow, e.g. bdg peek --follow --interval 500"
+  };
+}
+function unknownAuditCheckMessage(value, similar, checks) {
+  return `Unknown check "${value}"${similar.length > 0 ? `; did you mean ${similar[0]}?` : ""} (checks: ${checks.join(", ")})`;
+}
 var LAUNCHED_CHROME_DESCRIPTION, A11Y_NAME_QUERY_EXAMPLE, SCOPED_FILTER_EXAMPLES, PLAYWRIGHT_ONLY_SYNTAX, MALFORMED_SELECTOR_DETAILS, SESSION_DIR_SUGGESTION, SCROLL_PROBLEMS, VIA_LABEL_SUFFIX, NAME_QUERY_PLACEHOLDER, LABEL_WITHOUT_CONTROL;
 var init_messages = __esm({
   "src/errors/messages.ts"() {
@@ -3487,11 +3560,14 @@ function findSimilarNames(name, candidates) {
   const maxDistance2 = Math.max(2, Math.floor(name.length / 5));
   const minAffix = Math.max(4, Math.ceil(name.length / 3));
   const typos = findMatches(name, others, maxDistance2, false).map((match) => match.value);
-  const byAffix = (length) => others.map((candidate) => ({ candidate, length: length(candidate) })).filter((entry) => entry.length >= minAffix).sort((a, b) => b.length - a.length).map((entry) => entry.candidate);
+  const byAffix = (length, min = minAffix) => others.map((candidate) => ({ candidate, length: length(candidate) })).filter((entry) => entry.length >= min).sort((a, b) => b.length - a.length).map((entry) => entry.candidate);
   const ranked = [
     ...typos,
     ...byAffix((candidate) => commonSuffixLength(name, candidate)),
-    ...byAffix((candidate) => commonPrefixLength(name, candidate))
+    ...byAffix(
+      (candidate) => commonPrefixLength(name, candidate),
+      Math.max(minAffix, Math.ceil(name.length / 2))
+    )
   ];
   return [...new Set(ranked)].slice(0, MAX_SIMILAR_NAMES);
 }
@@ -3962,6 +4038,12 @@ async function domListeners(params) {
 async function domLayout(params) {
   return sendCommand("dom_layout", params);
 }
+async function domAudit(params) {
+  return sendCommand("dom_audit", params);
+}
+async function cssSearch(params) {
+  return sendCommand("css_search", params);
+}
 async function domInspect(params) {
   return sendCommand("dom_inspect", params);
 }
@@ -4150,7 +4232,12 @@ var init_elementInfo = __esm({
     doc = frame.ownerDocument;
   }
   const root = el.getRootNode();
-  if (root.host) parts.push('shadow root of <' + describe(root.host) + '>');
+  if (root.host) {
+    const host = root.host;
+    const label = describe(host) + (!host.id && host.classList.length ? '.' + host.classList[0] : '');
+    const text = (host.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 30);
+    parts.push('shadow root of <' + label + (text ? ' "' + text + '"' : '') + '>');
+  }
   return parts.join(' > ');
 }`;
   }
@@ -4159,8 +4246,9 @@ 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 part = attributes["part"];
+  if (!names) return part ? { part } : void 0;
+  const result = part ? { part } : {};
   const type = state.type ?? attributes["type"];
   if (type) result["type"] = type;
   for (const name of names) {
@@ -4227,8 +4315,9 @@ function axisScroll(start, size, viewSize, range, aim) {
   const scroll = Math.round(Math.min(range.forward, Math.max(-range.back, target))) || 0;
   return visibleLength(start, size, viewSize, scroll) >= fully ? scroll : null;
 }
-function classifyViewportPosition(geometry, viewport) {
-  if (geometry.hidden) return { inViewport: "hidden", hiddenReason: geometry.hidden };
+function classifyViewportPosition(measured, viewport) {
+  if (measured.hidden) return { inViewport: "hidden", hiddenReason: measured.hidden };
+  const geometry = measured.content ? { ...measured, rect: measured.content } : measured;
   const rect = edgesOf(geometry.rect);
   const screen = edgesOf({ x: 0, y: 0, ...viewport });
   const view = geometry.clip ? overlap(screen, edgesOf(geometry.clip)) : screen;
@@ -4473,7 +4562,20 @@ var init_elementGeometry = __esm({
     }
     return 'not rendered';
   };
-  const hiddenReason = (style, box) => {
+  const shownChildren = (node) => {
+    const s = styleOf(node);
+    if (s.overflowX !== 'visible' || s.overflowY !== 'visible') return null;
+    let union = null;
+    for (const c of Array.from(node.children).slice(0, 50)) {
+      const r = c.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0 || styleOf(c).visibility !== 'visible') continue;
+      union = union
+        ? { left: Math.min(union.left, r.left), top: Math.min(union.top, r.top), right: Math.max(union.right, r.right), bottom: Math.max(union.bottom, r.bottom) }
+        : { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+    }
+    return union;
+  };
+  const hiddenReason = (style, box, content) => {
     if (style.display === 'none') return 'display: none';
     if (style.display === 'contents') return 'display: contents (no box of its own)';
     if (el.getClientRects().length === 0) {
@@ -4482,7 +4584,7 @@ var init_elementGeometry = __esm({
     const skipped = skippedReason(el);
     if (skipped) return skipped;
     if (style.visibility !== 'visible') return 'visibility: ' + style.visibility;
-    if (box.width === 0 || box.height === 0) return 'zero size';
+    if ((box.width === 0 || box.height === 0) && !content) return 'zero size';
     return null;
   };
   const isSticky = () => {
@@ -4505,7 +4607,8 @@ var init_elementGeometry = __esm({
   let clipper = own.clipper;
   let fixed = own.fixed;
   let fixedBy = own.fixedBy;
-  let hidden = hiddenReason(styleOf(el), box) || own.collapsed;
+  let content = box.width === 0 || box.height === 0 ? shownChildren(el) : null;
+  let hidden = hiddenReason(styleOf(el), box, content) || own.collapsed;
   let x = 0;
   let y = 0;
   for (let view = el.ownerDocument.defaultView; view && view.frameElement; view = view.parent) {
@@ -4517,6 +4620,7 @@ var init_elementGeometry = __esm({
     overlay = { right: !!unframed && unframed.right <= clip.right && overlay.right, bottom: !!unframed && unframed.bottom <= clip.bottom && overlay.bottom };
     const offset = frameOffset(frame);
     rect = shift(rect, offset.x, offset.y);
+    content = shift(content, offset.x, offset.y);
     const outer = ancestorClip(frame, rect, describe);
     const inner = shift(clip, offset.x, offset.y);
     clip = intersect(inner, outer.clip);
@@ -4535,7 +4639,7 @@ var init_elementGeometry = __esm({
   const invisible = hidden ? null : invisibleReason(el, describe);
   const lock = scrollLock(top, describe);
   if (lock && fixedBy === top.document.body) fixed = false;
-  return { rect: toBox(rect), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
+  return { rect: toBox(rect), content: toBox(content), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
 }`;
     IN_VIEW_SLACK = 1;
   }
@@ -5538,18 +5642,34 @@ var init_errors5 = __esm({
   }
 });
 
+// src/runtime/page/userAgent.ts
+var init_userAgent = __esm({
+  "src/runtime/page/userAgent.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
 // src/runtime/page/emulation.ts
 function viewportOverride(viewport, deviceScaleFactor = 0) {
-  return { width: viewport.width, height: viewport.height, deviceScaleFactor, mobile: false };
+  const mobile = viewport.mobile === true;
+  return {
+    width: viewport.width,
+    height: viewport.height,
+    deviceScaleFactor: deviceScaleFactor || (mobile ? MOBILE_PIXEL_RATIO : 0),
+    mobile
+  };
 }
-var log16;
+var log16, MOBILE_PIXEL_RATIO;
 var init_emulation = __esm({
   "src/runtime/page/emulation.ts"() {
     "use strict";
     init_elementGeometry();
+    init_userAgent();
     init_logging();
     init_errors();
     log16 = createLogger("session");
+    MOBILE_PIXEL_RATIO = 3;
   }
 });
 
@@ -5726,13 +5846,18 @@ async function useUnitPixelRatio(devicePixelRatio, viewport) {
   const sessionViewport = readSessionMetadata()?.viewport;
   const size = sessionViewport ?? await windowSize(viewport);
   await callCDP("Emulation.setDeviceMetricsOverride", viewportOverride(size, 1));
-  return async () => {
-    if (sessionViewport) {
-      await callCDP("Emulation.setDeviceMetricsOverride", viewportOverride(sessionViewport));
-    } else {
-      await callCDP("Emulation.clearDeviceMetricsOverride", {});
-    }
-  };
+  return restoreSessionMetrics;
+}
+async function restoreSessionMetrics() {
+  const sessionViewport = readSessionMetadata()?.viewport;
+  if (!sessionViewport) {
+    await callCDP("Emulation.clearDeviceMetricsOverride", {});
+    return;
+  }
+  await callCDP("Emulation.setDeviceMetricsOverride", viewportOverride(sessionViewport));
+  if (sessionViewport.mobile) {
+    await callCDP("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
+  }
 }
 async function getElementBounds(ref) {
   const response = await callCDP("DOM.getBoxModel", ref);
@@ -5876,21 +6001,61 @@ async function visibleViewport() {
 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) {
+async function measureInView(ref, padding) {
   const view = await visibleViewport();
   let box = await getElementBounds(ref);
-  let bounds = await captureArea(ref, box);
+  let bounds = await captureArea(ref, box, padding);
   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})` });
+  if (!fits) {
+    await keepLayoutWithoutScrollbars(view);
+    box = await getElementBounds(ref);
+    return { box, bounds: await captureArea(ref, box, padding), inView: false };
+  }
+  if (insideView(bounds, view)) return { box, bounds, inView: true };
+  const scrolledFrom = await scrollPosition();
+  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})` });
+  try {
     box = await getElementBounds(ref);
-    bounds = await captureArea(ref, box);
+    bounds = await captureArea(ref, box, padding);
+  } catch (error) {
+    await restoreScrollPosition(scrolledFrom);
+    throw error;
   }
-  return { box, bounds, inView: insideView(bounds, view) };
+  return { box, bounds, inView: insideView(bounds, view), scrolledFrom };
 }
-async function captureArea(ref, bounds) {
+async function keepLayoutWithoutScrollbars(view) {
+  const phone = readSessionMetadata()?.viewport?.mobile;
+  await callCDP("Emulation.setScrollbarsHidden", { hidden: true });
+  await callCDP(
+    "Emulation.setDeviceMetricsOverride",
+    viewportOverride({ ...view, ...phone && { mobile: true } }, 1)
+  );
+}
+async function restoreViewport() {
+  await callCDP("Emulation.setScrollbarsHidden", { hidden: false });
+  await restoreSessionMetrics();
+}
+async function scrollPosition() {
+  const response = await callCDP("Runtime.evaluate", {
+    expression: "[window.scrollX, window.scrollY]",
+    returnByValue: true
+  });
+  const value = response.data?.result?.result?.value;
+  const [x, y] = Array.isArray(value) ? value : [];
+  return { x: x ?? 0, y: y ?? 0 };
+}
+async function captureArea(ref, bounds, padding) {
+  const area = await paintedArea(ref, bounds);
+  return padding > 0 ? {
+    x: area.x - padding,
+    y: area.y - padding,
+    width: area.width + 2 * padding,
+    height: area.height + 2 * padding
+  } : area;
+}
+async function paintedArea(ref, bounds) {
   const objectGroup = `bdg-shot-${process.pid}`;
   try {
     const resolved = await callCDP("DOM.resolveNode", { ...ref, objectGroup });
@@ -5934,15 +6099,18 @@ async function captureElementScreenshot(outputPath, ref, options = {}) {
     devicePixelRatio,
     before?.visualViewport ?? { clientWidth: 800, clientHeight: 600 }
   );
-  let box;
-  let bounds;
-  let inView;
+  const restore = async (wide, scrolledFrom2) => {
+    await (wide ? restoreViewport() : restoreMetrics());
+    if (scrolledFrom2) await restoreScrollPosition(scrolledFrom2);
+  };
+  let measured;
   try {
-    ({ box, bounds, inView } = await measureInView(ref));
+    measured = await measureInView(ref, options.padding ?? 0);
   } catch (error) {
-    await restoreMetrics();
+    await restoreViewport();
     throw error;
   }
+  const { box, bounds, inView, scrolledFrom } = measured;
   const originalWidth = bounds.width;
   const originalHeight = bounds.height;
   const resized = shouldResize(originalWidth, originalHeight, noResize);
@@ -5968,7 +6136,7 @@ async function captureElementScreenshot(outputPath, ref, options = {}) {
     });
     screenshotResult = screenshotResponse.data?.result;
   } finally {
-    await restoreMetrics();
+    await restore(!inView, scrolledFrom);
   }
   if (!screenshotResult?.data) {
     throw new CDPConnectionError("No screenshot data returned", new Error("Empty response"));
@@ -5985,7 +6153,8 @@ async function captureElementScreenshot(outputPath, ref, options = {}) {
     finalTokens: calculateImageTokens(finalWidth, finalHeight),
     element: {
       bounds: roundBounds(onPage(box)),
-      ...bounds !== box && { captured: roundBounds(clip) }
+      ...bounds !== box && { captured: roundBounds(clip) },
+      ...options.padding && { padding: options.padding }
     }
   };
   if (quality !== void 0) {
@@ -6051,8 +6220,37 @@ var init_screenshot = __esm({
       if (!clips(style)) walk(child);
     }
   };
-  if (!clips(view.getComputedStyle(this))) walk(this);
-  return { left: own.left - reach.left, top: own.top - reach.top, right: reach.right - own.right, bottom: reach.bottom - own.bottom };
+  const ownStyle = view.getComputedStyle(this);
+  if (!clips(ownStyle)) {
+    walk(this);
+    const scaleX = this.offsetWidth ? own.width / this.offsetWidth : 1;
+    const scaleY = this.offsetHeight ? own.height / this.offsetHeight : 1;
+    const wider = Math.max(0, this.scrollWidth - this.clientWidth) * scaleX;
+    const taller = Math.max(0, this.scrollHeight - this.clientHeight) * scaleY;
+    if (ownStyle.direction === 'rtl') reach.left = Math.min(reach.left, own.left - wider);
+    else reach.right = Math.max(reach.right, own.right + wider);
+    reach.bottom = Math.max(reach.bottom, own.bottom + taller);
+  }
+  const ink = { left: 0, top: 0, right: 0, bottom: 0 };
+  const grow = (side, amount) => { ink[side] = Math.max(ink[side], amount); };
+  for (const layer of ownStyle.boxShadow === 'none' ? [] : ownStyle.boxShadow.split(/,(?![^(]*\\))/)) {
+    if (/\\binset\\b/.test(layer)) continue;
+    const [x = 0, y = 0, blur = 0, spread = 0] = (layer.replace(/(rgba?|hsla?|color|oklch|lab|lch)\\([^)]*\\)/g, '').match(/-?[\\d.]+px/g) || []).map(parseFloat);
+    grow('left', blur + spread - x);
+    grow('right', blur + spread + x);
+    grow('top', blur + spread - y);
+    grow('bottom', blur + spread + y);
+  }
+  if (ownStyle.outlineStyle !== 'none') {
+    const outline = parseFloat(ownStyle.outlineWidth) + parseFloat(ownStyle.outlineOffset);
+    ['left', 'top', 'right', 'bottom'].forEach((side) => grow(side, outline));
+  }
+  return {
+    left: Math.max(own.left - reach.left, ink.left),
+    top: Math.max(own.top - reach.top, ink.top),
+    right: Math.max(reach.right - own.right, ink.right),
+    bottom: Math.max(reach.bottom - own.bottom, ink.bottom)
+  };
 }`;
     OVERFLOW_SLACK = 1;
   }
@@ -8040,18 +8238,18 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @private
    */
-  _prepareUserArgs(argv, parseOptions3) {
+  _prepareUserArgs(argv, parseOptions2) {
     if (argv !== void 0 && !Array.isArray(argv)) {
       throw new Error("first parameter to parse must be array or undefined");
     }
-    parseOptions3 = parseOptions3 || {};
-    if (argv === void 0 && parseOptions3.from === void 0) {
+    parseOptions2 = parseOptions2 || {};
+    if (argv === void 0 && parseOptions2.from === void 0) {
       if (process2.versions?.electron) {
-        parseOptions3.from = "electron";
+        parseOptions2.from = "electron";
       }
       const execArgv = process2.execArgv ?? [];
       if (execArgv.includes("-e") || execArgv.includes("--eval") || execArgv.includes("-p") || execArgv.includes("--print")) {
-        parseOptions3.from = "eval";
+        parseOptions2.from = "eval";
       }
     }
     if (argv === void 0) {
@@ -8059,7 +8257,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     this.rawArgs = argv.slice();
     let userArgs;
-    switch (parseOptions3.from) {
+    switch (parseOptions2.from) {
       case void 0:
       case "node":
         this._scriptPath = argv[1];
@@ -8081,7 +8279,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         break;
       default:
         throw new Error(
-          `unexpected parse option { from: '${parseOptions3.from}' }`
+          `unexpected parse option { from: '${parseOptions2.from}' }`
         );
     }
     if (!this._name && this._scriptPath)
@@ -8111,9 +8309,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} [parseOptions.from] - where the args are from: 'node', 'user', 'electron'
    * @return {Command} `this` command for chaining
    */
-  parse(argv, parseOptions3) {
+  parse(argv, parseOptions2) {
     this._prepareForParse();
-    const userArgs = this._prepareUserArgs(argv, parseOptions3);
+    const userArgs = this._prepareUserArgs(argv, parseOptions2);
     this._parseCommand([], userArgs);
     return this;
   }
@@ -8137,9 +8335,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} parseOptions.from - where the args are from: 'node', 'user', 'electron'
    * @return {Promise}
    */
-  async parseAsync(argv, parseOptions3) {
+  async parseAsync(argv, parseOptions2) {
     this._prepareForParse();
-    const userArgs = this._prepareUserArgs(argv, parseOptions3);
+    const userArgs = this._prepareUserArgs(argv, parseOptions2);
     await this._parseCommand([], userArgs);
     return this;
   }
@@ -9456,15 +9654,19 @@ init_schema();
 // src/commands/optionBehaviors.ts
 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 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, with "(+N more)" and moreMessages for the rest; 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": {
     default: "Captures the page (full page unless --no-full-page)",
-    whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". Both given and naming different elements exits 81',
-    automaticBehavior: "The capture covers the border box plus content overflowing it (uncleared floats, positioned children; not what an overflow: hidden ancestor cuts off, nor fixed descendants); JSON element.bounds is the border box and element.captured the larger area when it grew, which human output notes"
+    whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". With --index it picks that match of the selector (--selector ".item" --index 2). A positional and an option naming different elements exits 81',
+    automaticBehavior: "The capture covers the border box plus what overflows it: uncleared floats, positioned children, text past a tight line height, and the element's own box shadows and outline (a focus ring); not what an overflow: hidden ancestor cuts off, nor fixed descendants. JSON element.bounds is the border box and element.captured the larger area when it grew, which human output notes. An element smaller than the viewport is scrolled into view for the capture and the page scroll put back afterwards; a larger one is captured with the page laid out at its width without scrollbars, so it does not shift"
+  },
+  "screenshot:--padding": {
+    default: "The element capture is its painted area (border box, overflowing content, shadows, outline)",
+    whenEnabled: "Adds that many CSS px of the page around the element capture on every side (0-500); without an element it exits 81"
   },
   "screenshot:--no-resize": {
     default: `Images auto-resized to max ${MAX_EDGE_PX}px longest edge for Claude Vision optimization (~1,600 tokens)`,
@@ -9646,10 +9848,16 @@ var OPTION_BEHAVIORS = {
     whenEnabled: "Lists every listener of framework roots individually",
     tokenImpact: "On React pages --all adds a row per event type and phase (about 140 rows, 60 KB of JSON)"
   },
+  "audit:--level": {
+    default: "Text must reach WCAG AA: 4.5, or 3 for large text (24px, or 18.66px bold); every text-drawing element is checked, composited like dom inspect",
+    whenEnabled: "--level AAA asks 7, or 4.5 for large text",
+    automaticBehavior: "One walk over the rendered elements (open shadow roots included, at most 20000; capped says when it stopped). Findings are sorted weakest first; --limit (default 20) lists that many per check and the rest are counted. Overflow leaves out content inside horizontal scrollers and visually-hidden 1px text; identical findings are grouped (\xD7N)",
+    tokenImpact: "About one line per finding; --limit bounds it"
+  },
   "layout:--index": {
     default: "Reports every match of the selector (human output lists the first 20, JSON up to 100 plus an omitted count); a numeric argument reports that cached query element",
     whenEnabled: "Reports only the nth match (0-based); out of range exits 81",
-    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',
+    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 first element painted above it at the center of the largest visible box that paints there (the background of a sticky header rather than the transparent logo on it; inside a shadow host, what its shadow root paints), else the topmost one with coverTransparent (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": {
@@ -9724,11 +9932,11 @@ var OPTION_BEHAVIORS = {
   },
   "peek:-f": {
     default: "Shows snapshot of current data",
-    whenEnabled: "Continuous monitoring - refreshes every second (like tail -f)"
+    whenEnabled: "Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail"
   },
   "peek:--follow": {
     default: "Shows snapshot of current data",
-    whenEnabled: "Continuous monitoring - refreshes every second (like tail -f)"
+    whenEnabled: "Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail"
   },
   "peek:-v": {
     default: "Compact output (truncated URLs, no resource types)",
@@ -9764,6 +9972,11 @@ var OPTION_BEHAVIORS = {
     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 (emulated 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81"
   },
+  "bdg:--mobile": {
+    default: "A desktop viewport: classic scrollbars take ~15px of the width, no touch, a desktop user agent",
+    whenEnabled: "Emulates a phone for the whole session: a mobile viewport (390x844 unless --viewport) at pixel ratio 3 with mobile layout (meta viewport, overlay scrollbars, so 100vw fits), touch (pointer: coarse, maxTouchPoints 5) and an Android Chrome user agent with mobile client hints; bdg page emulate --mobile turns it on mid-session, --viewport WxH without --mobile or --reset turns it off",
+    automaticBehavior: 'Screenshots keep the mobile layout and are taken at pixel ratio 1 (CSS px = image px); bdg status shows "(emulated 390x844, phone)"'
+  },
   "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",
     whenEnabled: "Emulates prefers-color-scheme: light or dark for the whole session (Emulation.setEmulatedMedia); other values exit 81 with a suggestion",
@@ -10619,11 +10832,6 @@ var DECISION_TREES = {
         yesCommand: "peek --follow",
         noAction: "next"
       },
-      {
-        question: "Need continuous monitoring (like tail -f)?",
-        yesCommand: "tail",
-        noAction: "next"
-      },
       {
         question: "Need quick preview of recent data?",
         yesCommand: "peek",
@@ -10772,7 +10980,7 @@ var TASK_MAPPINGS = {
     cdpAlternative: "Multiple IPC queries to session state"
   },
   live_monitoring: {
-    commands: ["peek --follow", "tail"],
+    commands: ["peek --follow"],
     description: "Monitor data collection in real-time",
     cdpAlternative: "CDP event subscriptions with custom handler"
   },
@@ -10879,7 +11087,7 @@ function convertCommand(command) {
 }
 function generateRuntimeState() {
   const sessionActive = readLiveDaemonPid() !== null;
-  const availableCommands = sessionActive ? ["peek", "tail", "details", "dom", "network", "console", "cdp", "status", "sessions", "stop"] : ["bdg <url>", "sessions", "cleanup", "--help", "--version"];
+  const availableCommands = sessionActive ? ["peek", "details", "dom", "network", "console", "cdp", "status", "sessions", "stop"] : ["bdg <url>", "sessions", "cleanup", "--help", "--version"];
   return {
     sessionActive,
     daemonRunning: sessionActive,
@@ -11241,6 +11449,8 @@ var COMMANDS = {
   dom_form_discover: defineCommand(),
   dom_listeners: defineCommand(),
   dom_layout: defineCommand(),
+  dom_audit: defineCommand(),
+  css_search: defineCommand(),
   dom_inspect: defineCommand(),
   dom_wait: defineCommand()
 };
@@ -11852,7 +12062,7 @@ function verboseCommandsMessage() {
   return [
     "Commands:",
     `  Full preview:    ${sessionCommand("bdg peek --last 50")}`,
-    `  Watch live:      ${sessionCommand("bdg tail")}`,
+    `  Watch live:      ${sessionCommand("bdg peek --follow")}`,
     `  End session:     ${sessionCommand("bdg stop")}`
   ].join("\n");
 }
@@ -11869,6 +12079,9 @@ function connectionLostRetryMessage(timestamp, retryLabel) {
 function connectionLostStopHintMessage() {
   return "Press Ctrl+C to stop";
 }
+function tailDeprecatedNotice() {
+  return 'Note: "bdg tail" is deprecated and will be removed; use "bdg peek --follow" (same options: --last, --network, --console, --interval, --verbose)';
+}
 
 // src/commands/shared/daemonErrorHandler.ts
 init_exitCodes();
@@ -13675,9 +13888,17 @@ function registerFormInteractionCommands(program2) {
     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>", 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("hover").description(
+    "Move the mouse over an element (shows hover menus and tooltips); --off moves it off the page"
+  ).argument("[selectorOrIndex]", SELECTOR_OR_INDEX_ARGUMENT).option("--index <n>", "Element index if selector matches multiple (0-based)", integerOption(0)).option("--off", "Move the mouse off the page instead (closes menus that open on hover)").option("--strict", STRICT_OPTION_HELP).option("--no-wait", "Skip waiting for network stability after hovering").addOption(jsonOption()).action(
+    async (selectorOrIndex, options) => {
+      if (options.off || selectorOrIndex === void 0) {
+        await hoverOff(selectorOrIndex, options);
+        return;
+      }
+      await runPointerCommand(selectorOrIndex, options, "hover");
+    }
+  );
   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)",
@@ -13795,6 +14016,25 @@ function scrollOptionsProblem(selector, options) {
   if (!selector && vertical + horizontal === 0) return "no-target";
   return null;
 }
+async function hoverOff(selectorOrIndex, options) {
+  await runCommand(
+    async () => {
+      if (!options.off || selectorOrIndex !== void 0 || options.index !== void 0) {
+        const err = options.off ? hoverOffWithTargetError() : missingArgumentError(HOVER_USAGE);
+        return {
+          success: false,
+          error: err.message,
+          exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+          errorContext: { suggestion: err.suggestion }
+        };
+      }
+      await callCDP("Input.dispatchMouseEvent", { type: "mouseMoved", x: -1, y: -1 });
+      return { success: true, data: { pointer: "off" } };
+    },
+    options,
+    () => HOVER_OFF_DONE
+  );
+}
 async function runPointerCommand(selectorOrIndex, options, action) {
   await runCommand(
     () => options.double && options.right ? Promise.resolve({
@@ -13837,7 +14077,15 @@ function formatActionOutput(done, details, result, options = {}) {
   fmt.blank();
   fmt.keyValueList(details, keyWidth);
   if (result.navigation) fmt.keyValue("Page", pageNavigationText(result.navigation), keyWidth);
-  listRows(fmt, "New text", (result.messages ?? []).map(newMessageText), keyWidth);
+  listRows(
+    fmt,
+    "New text",
+    [
+      ...(result.messages ?? []).map(newMessageText),
+      ...result.moreMessages ? [moreMessagesText(result.moreMessages)] : []
+    ],
+    keyWidth
+  );
   listRows(fmt, "Shown", (result.shown ?? []).map(shownElementText), keyWidth);
   const omitted = result.triggeredRequestsOmitted;
   const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
@@ -14772,19 +15020,19 @@ function registerA11yCommands(domCmd) {
   const a11y = domCmd.command("a11y").description("Accessibility tree inspection and semantic queries").argument(
     "[search]",
     'Quick search: index (describe), CSS selector (#id, .class), pattern with ":" (query), or name search'
-  ).enablePositionalOptions().addOption(jsonOption()).action(async (search, options) => {
-    if (!search) {
+  ).enablePositionalOptions().addOption(jsonOption()).action(async (search2, options) => {
+    if (!search2) {
       return a11y.help({ error: true });
     }
-    const isNumericIndex = /^\d+$/.test(search);
-    const isCssSelector = /^[#.[]/u.test(search);
-    const isPatternQuery = /^(role|name|description|desc)\s*[:=]/i.test(search);
+    const isNumericIndex = /^\d+$/.test(search2);
+    const isCssSelector = /^[#.[]/u.test(search2);
+    const isPatternQuery = /^(role|name|description|desc)\s*[:=]/i.test(search2);
     if (isNumericIndex || isCssSelector) {
-      await handleA11yDescribe(search, options);
+      await handleA11yDescribe(search2, options);
     } else if (isPatternQuery) {
-      await handleA11yQuery(search, options);
+      await handleA11yQuery(search2, options);
     } else {
-      await handleA11yQuery(`name:${quoteQueryValue(search)}`, options);
+      await handleA11yQuery(`name:${quoteQueryValue(search2)}`, options);
     }
   });
   a11y.command("tree").description("Dump full accessibility tree (filters ignored nodes)").addOption(jsonOption()).action(async (options) => {
@@ -14888,7 +15136,10 @@ function formatDomScreenshot(data) {
     output += " (viewport only - page too tall)";
   }
   if (data.element?.captured) {
-    output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured)})`;
+    output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured, data.element.padding)})`;
+  }
+  if (data.resized && data.originalWidth !== void 0 && data.originalHeight !== void 0) {
+    output += ` (${screenshotScaledNote(data.originalWidth, data.originalHeight, data.width, data.height)})`;
   }
   return output;
 }
@@ -15676,11 +15927,11 @@ function inspectHeader(data) {
     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}`,
+    data.rect && `${data.rect.w}x${data.rect.h}${data.rect.screen ? ` (${data.rect.screen.w}x${data.rect.screen.h} on screen)` : ""} @${data.rect.x},${data.rect.y}${data.rect.in ? " (fixed: viewport position)" : ""}`,
     kind && `[${kind}]`,
     ...inspectVisibilityBadges(data.visibility),
     data.context && `in ${data.context}`,
-    data.theme === "dark" && inspectDarkThemeBadge(),
+    data.theme === "dark" && inspectDarkThemeBadge(data.themeFrom === "emulation"),
     data.animating && inspectAnimatingBadge(data.animating)
   ].filter(Boolean).join(" ");
 }
@@ -15755,6 +16006,7 @@ function parentLine(layout) {
 function fontParts(text) {
   const loaded = [
     text.rendered && `rendered "${text.rendered}"`,
+    text.resolved && `resolves to "${text.resolved}"`,
     text.webfont && "webfont loaded"
   ].filter(Boolean);
   const family = text.family && [text.family, loaded.length > 0 && `(${loaded.join(", ")})`];
@@ -15775,14 +16027,16 @@ function fontParts(text) {
 function contrastText(contrast) {
   if (!contrast) return void 0;
   return [
-    `contrast ${contrast.ratio} ${contrast.level}`,
-    contrast.inherited && `on ${contrast.background}`,
+    contrast.approximate ? `contrast \u2248${contrast.ratio} ${contrast.level}` : `contrast ${contrast.ratio} ${contrast.level}`,
+    `on ${contrast.background}`,
     contrast.overImage && "(over image)",
-    contrast.opacity !== void 0 && `(faded: opacity ${contrast.opacity})`
+    contrast.opacity !== void 0 && `(faded: opacity ${contrast.opacity})`,
+    contrast.approximate && `(approximate: ${contrast.approximate.join(", ")})`
   ].filter(Boolean).join(" ");
 }
 function textLine(text) {
   return groupLine("text", [
+    text.holder && `in ${text.holder}`,
     ...fontParts(text),
     text.color && `color ${text.color}`,
     contrastText(text.contrast),
@@ -15793,17 +16047,25 @@ function textLine(text) {
     text.whiteSpace && `ws ${text.whiteSpace}`,
     text.overflow && `text-overflow ${text.overflow}`,
     text.clamp && `clamp ${text.clamp}`,
+    text.truncated && "truncated",
+    text.gradientFill && "filled by its background (background-clip: text; no contrast)",
     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}` : ""}`;
+  return [
+    `bg-image ${fill.value}`,
+    fill.size && `size ${fill.size}`,
+    fill.position && `at ${fill.position}`
+  ].filter(Boolean).join(" ");
 }
 function fillLine(data) {
+  const paint = data.paint;
   return groupLine("fill", [
+    paint && `fill ${paint.fill}`,
+    paint && `stroke ${paint.stroke}${paint.strokeWidth !== void 0 ? ` ${paint.strokeWidth}` : ""}`,
     ...(data.fills ?? []).map(fillText),
     data.opacity !== void 0 && `opacity ${data.opacity}`,
     data.blend && `blend ${data.blend}`
@@ -15853,6 +16115,7 @@ function pseudoText(pseudo) {
     pseudo.content !== void 0 && `content ${pseudo.content}`,
     pseudo.display,
     pseudo.position,
+    pseudo.inset && `inset ${pseudo.inset}`,
     pseudo.size && `${pseudo.size.w}x${pseudo.size.h}`,
     pseudo.color && `color ${pseudo.color}`,
     pseudo.fontStyle,
@@ -15874,7 +16137,9 @@ function treeRow(node) {
   return [
     node.element,
     node.count !== void 0 && `\xD7${node.count}`,
-    `${node.w}x${node.h}`,
+    node.contents ? "(contents)" : `${node.w}x${node.h}`,
+    node.shadow && "(shadow root)",
+    node.via && `via ${node.via}`,
     node.layout && `[${node.layout}]`,
     node.text && `"${node.text}"`,
     node.childCount !== void 0 && `(${node.childCount})`
@@ -15896,7 +16161,7 @@ function ruleScope(entry) {
 }
 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}`
+    (hint) => `${hint.property}: ${hint.value} ${hint.kind === "not-inherited" ? "is the browser's" : hint.only ? `has no effect on ${hint.only.join(", ")}` : "has no effect"}: ${hint.reason} \u2192 ${hint.fix} \xB7 in ${hint.source}`
   );
   return [
     ...labelledLines("hints", data.hints?.length === 0 ? ["none"] : hints),
@@ -15927,7 +16192,8 @@ function whyLines(why, data) {
       truncateByLength(value, CASCADE_VALUE_WIDTH) + resolved,
       entry.important ? " !important" : "",
       `  ${entry.source}${entry.specificity ? ` [${entry.specificity.join(",")}]` : ""}${ruleScope(entry)}`,
-      entry.status === "inherited" ? " (inherited)" : ""
+      entry.status === "inherited" ? " (inherited)" : "",
+      entry.note ? ` (${entry.note})` : ""
     ].join("");
   });
   const variables = (why.variables ?? []).map(
@@ -15936,8 +16202,12 @@ function whyLines(why, data) {
   return [
     `${why.property} = ${why.computed}${midTransition(why.property, data.animating) ? ` ${inspectMidTransitionNote()}` : ""}`,
     ...entries.slice(0, 1),
+    ...why.chain[0]?.rule ? [`    in ${truncateByLength(why.chain[0].rule, RULE_LINE_WIDTH)}`] : [],
     ...variables,
     ...entries.slice(1),
+    ...(why.inactive ?? []).map(
+      (rule) => `  - ${truncateByLength(rule.value, CASCADE_VALUE_WIDTH)}  ${rule.selector} ${rule.condition} (does not apply now)`
+    ),
     ...why.chain.length === 0 ? ["  no author declaration: the default or inherited value"] : []
   ];
 }
@@ -15949,6 +16219,7 @@ function midTransition(property, animating) {
 function levelsUp(levels) {
   return levels === 1 ? "the parent" : `${levels} levels up`;
 }
+var RULE_LINE_WIDTH = 120;
 var CASCADE_VALUE_WIDTH = 60;
 function treeBlock(data) {
   if (!data.children && !data.hiddenChildren) return [];
@@ -15993,8 +16264,16 @@ function groupLines(data) {
 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);
+  const pseudoNote = data.pseudoOf && inspectPseudoOfNote(data.pseudoOf);
+  if (data.why) return joinLines(inspectHeader(data), ...cascadeBlock(data), note, pseudoNote);
+  return joinLines(
+    inspectHeader(data),
+    ...body,
+    ...cascadeBlock(data),
+    ...treeBlock(data),
+    note,
+    pseudoNote
+  );
 }
 
 // src/commands/dom/inspect.ts
@@ -16063,6 +16342,125 @@ async function inspectTarget(selectorOrIndex, options) {
   });
 }
 
+// src/commands/dom/audit.ts
+init_messages();
+init_client();
+
+// src/ipc/protocol/auditTypes.ts
+var AUDIT_CHECKS = ["contrast", "overflow", "layers", "animations"];
+
+// src/ui/formatters/audit.ts
+init_strings();
+var TEXT_WIDTH = 50;
+function formatAudit(data) {
+  const sections = [
+    data.contrast && contrastSection(data.contrast),
+    data.overflow && overflowSection(data.overflow),
+    data.layers && layersSection(data.layers),
+    data.animations && animationsSection(data.animations)
+  ].filter((section2) => section2 !== void 0);
+  const capped = data.capped ? [`(stopped after ${data.walked} elements; the page has more)`] : [];
+  return [...sections.flatMap((lines) => [...lines, ""]), ...capped].join("\n").trimEnd();
+}
+function contrastSection(contrast) {
+  const head = `Contrast (${contrast.level}): ${contrast.failing} of ${contrast.checked} text elements below`;
+  const rows = contrast.items.map(
+    (item) => `  ${item.ratio.toFixed(2).padStart(5)}  ${item.color} on ${item.background}  ${item.element} "${truncateByLength(item.text, TEXT_WIDTH)}" ${item.size}px${item.weight >= 700 ? " bold" : ""}${item.inView ? "" : " (out of view)"}${item.approximate ? ` (approximate: ${item.approximate.join(", ")})` : ""}`
+  );
+  const more = contrast.failing - contrast.items.length;
+  return [head, ...rows, ...more > 0 ? [`  (+${more} more; --limit to list them)`] : []];
+}
+function overflowSection(overflow) {
+  const head = overflow.scrollsSideways ? `Overflow: the page is ${overflow.pageWidth} wide in a ${overflow.viewportWidth} viewport (it scrolls sideways)` : `Overflow: nothing makes the page scroll sideways (${overflow.viewportWidth} wide)`;
+  return [
+    head,
+    ...overflow.wide.map(
+      (item) => `  past the right edge: ${item.element} (to ${item.right}, ${item.width} wide)`
+    ),
+    ...overflow.truncated.map(
+      (item) => `  cut off (${item.kind}): ${item.element}${times(item.count)} "${truncateByLength(item.text, TEXT_WIDTH)}"`
+    ),
+    ...overflow.scrollers.map(
+      (item) => `  scrolls sideways inside: ${item.element} (${item.scrollWidth} of content in ${item.width})`
+    ),
+    ...overflow.images.map(
+      (image) => `  image ${[image.upscaled && `upscaled ${image.scale}x${overflow.pixelRatio > 1 ? ` at pixel ratio ${overflow.pixelRatio}` : ""}`, image.distorted && "distorted"].filter(Boolean).join(", ")}: ${image.element}${times(image.count)} ${image.natural.w}x${image.natural.h} pixels drawn at ${image.rendered.w}x${image.rendered.h} CSS px`
+    )
+  ];
+}
+function times(count) {
+  return count ? ` \xD7${count}` : "";
+}
+function layersSection(layers) {
+  if (layers.length === 0) return ["Layers: no fixed or sticky elements"];
+  return [
+    `Layers: ${layers.length} fixed or sticky`,
+    ...layers.map(
+      (layer) => `  ${layer.position} z ${layer.zIndex}  ${layer.element} ${layer.rect.w}x${layer.rect.h} at ${layer.rect.x},${layer.rect.y} of the viewport${layer.inView ? "" : " (not in view now)"}`
+    )
+  ];
+}
+function animationsSection(animations) {
+  if (animations.length === 0) return ["Animations: none running"];
+  return [
+    `Animations: ${animations.length} running`,
+    ...animations.map(
+      (animation) => `  ${animation.name} on ${animation.element}${times(animation.count)} (${animation.type}, ${typeof animation.duration === "number" ? `${animation.duration}ms` : animation.duration}, ${animation.iterations === "infinite" ? "infinite" : `${animation.iterations}x`}${animation.scrollDriven ? ", scroll-driven" : ""})`
+    )
+  ];
+}
+function formatCssSearch(data) {
+  if (data.total === 0) return `"${data.query}" is not in the page's ${data.sheets} stylesheets`;
+  const more = data.total - data.matches.length;
+  return [
+    `"${data.query}": ${data.total} matches in ${data.sheets} stylesheets`,
+    ...data.matches.flatMap((match) => [`  ${match.source}`, `    ${match.text}`]),
+    ...more > 0 ? [`  (+${more} more; --limit to list them)`] : []
+  ].join("\n");
+}
+
+// src/commands/dom/audit.ts
+init_commands();
+init_exitCodes();
+init_suggestions();
+function registerAuditCommand(dom) {
+  dom.command("audit").description(
+    "Page-wide checks: text below WCAG contrast, sideways scroll and cut-off text, scaled images, fixed/sticky layers, animations"
+  ).argument("[checks...]", `Checks to run: ${AUDIT_CHECKS.join(", ")} (default: all)`, checkList).option("--level <level>", "WCAG level text must reach: AA or AAA (default: AA)", levelOption).option("--limit <n>", "Findings listed per check (default: 20)", integerOption(1, 500)).addOption(jsonOption()).addHelpText("after", AUDIT_HELP_EXAMPLES).action(async (checks, options) => {
+    await runCommand(() => audit(checks, options), options, formatAudit);
+  });
+}
+function checkList(value, previous = []) {
+  const check = AUDIT_CHECKS.find((name) => name === value.trim().toLowerCase());
+  if (!check) {
+    throw new InvalidArgumentError(
+      unknownAuditCheckMessage(value, findSimilar(value, [...AUDIT_CHECKS]), AUDIT_CHECKS)
+    );
+  }
+  return previous.includes(check) ? previous : [...previous, check];
+}
+function levelOption(value) {
+  const level = value.trim().toUpperCase();
+  if (level === "AA" || level === "AAA") return level;
+  throw new InvalidArgumentError("Use AA or AAA");
+}
+async function audit(checks, options) {
+  const response = await domAudit({
+    checks: checks && checks.length > 0 ? checks : [...AUDIT_CHECKS],
+    ...options.level && { level: options.level },
+    ...options.limit !== void 0 && { limit: options.limit }
+  });
+  if (response.status === "error" || !response.data) {
+    return {
+      success: false,
+      error: response.error ?? "Failed to audit the page",
+      exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+      ...response.suggestion && { errorContext: { suggestion: response.suggestion } }
+    };
+  }
+  return { success: true, data: response.data };
+}
+
 // src/commands/dom/layout.ts
 init_client();
 
@@ -16382,13 +16780,17 @@ function buildElementScreenshotOptions(options) {
   return filterDefined({
     format: options.format,
     quality: options.quality,
-    noResize: options.resize === false
+    noResize: options.resize === false,
+    padding: options.padding
   });
 }
 function hasElementTarget(options) {
   return options.selector !== void 0 || options.index !== void 0;
 }
 async function resolveElementNodeId(options) {
+  if (options.selector !== void 0 && options.index !== void 0) {
+    return { backendNodeId: await selectMatch(options.selector, options.index) };
+  }
   if (options.index !== void 0) {
     const resolver = DomElementResolver.getInstance();
     const node = await resolver.getNodeIdForIndex(options.index);
@@ -16523,8 +16925,8 @@ function reportSequenceError(error, captured, json) {
 }
 function assertScreenshotOptions(outputPath, options) {
   let message;
-  if (options.selector !== void 0 && options.index !== void 0) {
-    message = conflictingOptionsMessage("--selector", "--index");
+  if (options.padding !== void 0 && !hasElementTarget(options)) {
+    message = "--padding applies to element captures; name an element (selector or index)";
   } else if (options.quality !== void 0 && !options.follow && resolveImageFormat(outputPath, options.format) === "png") {
     message = "--quality applies to JPEG only; this screenshot is a PNG";
   }
@@ -16574,7 +16976,7 @@ function registerWaitCommand(dom) {
     "Wait until elements appear, become visible, contain a text or are gone (or the page loads)"
   ).argument(
     "[selector]",
-    "CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); optional with --load"
+    "CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); without one, waits for the page to load (--load)"
   ).option("--text <text>", "A match must contain this text (case-insensitive)").option("--visible", "Only count visible matches").option("--gone", "Wait until no element matches (none visible, with --visible)").option("--load", "Also wait for the page to finish loading (document.readyState complete)").option(
     "--timeout <ms>",
     "Give up after this many milliseconds (exit 102)",
@@ -16585,7 +16987,8 @@ function registerWaitCommand(dom) {
   });
 }
 async function waitFor(selector, options) {
-  const needsSelector = options.text !== void 0 || options.gone === true || !options.load;
+  const load = options.load === true || selector === void 0 && options.text === void 0 && !options.gone && !options.visible;
+  const needsSelector = options.text !== void 0 || options.gone === true || !load;
   if (selector === void 0 && needsSelector) {
     const err = waitTargetRequiredError();
     return {
@@ -16599,7 +17002,7 @@ async function waitFor(selector, options) {
     ...filterDefined({ selector, text: options.text }),
     ...options.gone && { gone: true },
     ...options.visible && { visible: true },
-    ...options.load && { load: true },
+    ...load && { load: true },
     timeout: options.timeout
   });
   if (response.status === "error" || !response.data) {
@@ -16623,6 +17026,7 @@ function registerDomCommands(program2) {
   registerFormCommand(dom);
   registerListenersCommand(dom);
   registerLayoutCommand(dom);
+  registerAuditCommand(dom);
   registerInspectCommand(dom);
   registerWaitCommand(dom);
   dom.command("query").description("Find elements by CSS selector").argument("<selector>", 'CSS selector (e.g., ".error", "#app", "button")').option("-j, --json", "Output as JSON").addHelpText("after", SELECTOR_SCOPE_HELP).action(async (selector, options) => {
@@ -16657,8 +17061,12 @@ function registerDomCommands(program2) {
     "Element to capture: CSS selector or index from a query (same as --selector / --index)"
   ).option("--selector <selector>", "CSS selector for element capture").option(
     "--index <number>",
-    "Cached element index (0-based) from previous query",
+    "Cached element index (0-based) from a previous query; with --selector, which match",
     integerOption(0)
+  ).option(
+    "--padding <px>",
+    "Element capture: extra space around it (shadows and focus rings are included anyway)",
+    integerOption(0, 500)
   ).option(
     "--format <format>",
     "Image format: png or jpeg/jpg (default: from the file extension, else png)",
@@ -16670,6 +17078,87 @@ function registerDomCommands(program2) {
   );
 }
 
+// src/commands/installSkill.ts
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname5, join as join6 } from "path";
+init_errors3();
+init_messages();
+
+// src/ui/formatters/installSkill.ts
+init_formatting();
+import { homedir as homedir2 } from "os";
+function tildePath(path6) {
+  const home = homedir2();
+  return path6.startsWith(`${home}/`) ? `~${path6.slice(home.length)}` : path6;
+}
+function formatInstalledSkills(data) {
+  const fmt = new OutputFormatter().text("bdg skill:");
+  for (const skill of data.skills) {
+    fmt.text(`  ${skill.target.padEnd(6)}  ${skill.status.padEnd(9)}  ${tildePath(skill.path)}`);
+  }
+  return fmt.hints("Next:", [
+    "Start a new agent session to load it (running sessions keep the old list)",
+    "After upgrading bdg, run bdg install-skill again"
+  ]).build();
+}
+
+// src/commands/installSkill.ts
+init_errors();
+init_exitCodes();
+var SKILL_SOURCE_PATH = join6(PACKAGE_ROOT, ".claude", "skills", "bdg", "SKILL.md");
+var SKILL_ROOTS = {
+  claude: join6(".claude", "skills"),
+  agents: join6(".agents", "skills")
+};
+function installSkill(targets, home = homedir3(), source = SKILL_SOURCE_PATH) {
+  if (!existsSync10(source)) {
+    const err = skillSourceMissingError(source);
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.RESOURCE_NOT_FOUND
+    );
+  }
+  const content = readFileSync8(source, "utf-8");
+  return targets.map(
+    (target) => writeSkill(target, join6(home, SKILL_ROOTS[target], "bdg", "SKILL.md"), content)
+  );
+}
+function writeSkill(target, path6, content) {
+  const existing = existsSync10(path6) ? readFileSync8(path6, "utf-8") : void 0;
+  if (existing === content) {
+    return { target, path: path6, status: "unchanged" };
+  }
+  try {
+    mkdirSync3(dirname5(path6), { recursive: true });
+    writeFileSync2(path6, content);
+  } catch (caught) {
+    const err = skillWriteFailedError(path6, getErrorMessage(caught));
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.PERMISSION_DENIED
+    );
+  }
+  return { target, path: path6, status: existing === void 0 ? "installed" : "updated" };
+}
+function selectedTargets(options) {
+  const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
+  return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
+}
+function registerInstallSkillCommand(program2) {
+  program2.command("install-skill").description(
+    "Install the bdg agent skill for Claude Code (~/.claude/skills) and agents reading ~/.agents/skills (Codex, Gemini CLI, ...); re-run after upgrading bdg"
+  ).option("--claude", "Only ~/.claude/skills (Claude Code)").option("--agents", "Only ~/.agents/skills (Codex, Gemini CLI and other agents)").addOption(jsonOption()).action(async (options) => {
+    await runCommand(
+      (opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }),
+      options,
+      formatInstalledSkills
+    );
+  });
+}
+
 // src/commands/network/har.ts
 import * as fs13 from "fs";
 import * as path5 from "path";
@@ -17434,7 +17923,7 @@ function appearanceLines(metadata, pageState) {
     ...viewport ? [
       [
         "Viewport",
-        `${viewport.width}\xD7${viewport.height}${metadata.viewport ? ` (emulated ${metadata.viewport.width}x${metadata.viewport.height})` : ""}`
+        `${viewport.width}\xD7${viewport.height}${metadata.viewport ? ` (emulated ${metadata.viewport.width}x${metadata.viewport.height}${metadata.viewport.mobile ? ", phone" : ""})` : ""}`
       ]
     ] : [],
     ...scheme ? [
@@ -18256,6 +18745,37 @@ function registerNetworkCommands(program2) {
   registerDocumentCommand(networkCmd);
 }
 
+// src/commands/css.ts
+init_client();
+init_commands();
+init_exitCodes();
+function registerCssCommands(program2) {
+  const css = program2.command("css").description("The page's stylesheets: search <text>");
+  css.command("search").description(
+    "Find text in every stylesheet of the page (cross-origin ones too), with the rule and file:line"
+  ).argument(
+    "<text>",
+    "Text to find (case-insensitive), e.g. oklch( or .btn-primary; put -- before one that starts with - (-- --brand)"
+  ).option("--limit <n>", "Matches listed (default: 20)", integerOption(1, 500)).addOption(jsonOption()).addHelpText("after", CSS_SEARCH_HELP_EXAMPLES).action(async (text, options) => {
+    await runCommand(() => search(text, options), options, formatCssSearch);
+  });
+}
+async function search(text, options) {
+  const response = await cssSearch({
+    query: text,
+    ...options.limit !== void 0 && { limit: options.limit }
+  });
+  if (response.status === "error" || !response.data) {
+    return {
+      success: false,
+      error: response.error ?? "Failed to search the stylesheets",
+      exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+      ...response.suggestion && { errorContext: { suggestion: response.suggestion } }
+    };
+  }
+  return { success: true, data: response.data };
+}
+
 // src/commands/start.ts
 import fs15 from "node:fs";
 import os3 from "node:os";
@@ -18300,7 +18820,7 @@ var SessionDirError = class extends DaemonError {
 // src/daemon/launcher.ts
 import { spawn } from "child_process";
 import fs14 from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 init_messages();
 init_paths();
 init_logging();
@@ -18321,7 +18841,7 @@ async function launchDaemon() {
     );
   }
   assertUsableSessionDir();
-  const logPath = join7(getSessionDir(), "daemon.log");
+  const logPath = join8(getSessionDir(), "daemon.log");
   rotateLog(logPath);
   const logFd = fs14.openSync(logPath, "a");
   log24.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
@@ -18382,7 +18902,7 @@ async function waitForDaemonReady(hasExited) {
     }
     if (hasExited() && !await isDaemonAlive()) {
       throw new DaemonStartupError(
-        `Daemon exited during startup. See ${join7(getSessionDir(), "daemon.log")}`,
+        `Daemon exited during startup. See ${join8(getSessionDir(), "daemon.log")}`,
         "DAEMON_EXITED"
       );
     }
@@ -18729,8 +19249,17 @@ function applyCollectorOptions(command) {
   ).option(
     "--color-scheme <scheme>",
     "Emulate prefers-color-scheme for the session: light or dark (default: the system setting)"
+  ).option(
+    "--mobile",
+    `Emulate a phone for the session: mobile viewport (${MOBILE_VIEWPORT.width}x${MOBILE_VIEWPORT.height} unless --viewport), touch, mobile user agent`
   );
 }
+var MOBILE_VIEWPORT = { width: 390, height: 844 };
+function requestedViewport(viewport, mobile) {
+  const size = viewport !== void 0 ? parseViewport(viewport) : void 0;
+  if (!mobile) return size;
+  return { ...size ?? MOBILE_VIEWPORT, mobile: true };
+}
 var MAX_VIEWPORT_SIDE = 1e4;
 var COLOR_SCHEMES = ["light", "dark"];
 function parseViewport(value) {
@@ -18778,7 +19307,7 @@ function buildSessionOptions(options) {
     quiet: options.quiet ?? false,
     json: options.json ?? false,
     chromeFlags,
-    viewport: options.viewport !== void 0 ? parseViewport(options.viewport) : void 0,
+    viewport: requestedViewport(options.viewport, options.mobile),
     colorScheme: options.colorScheme !== void 0 ? parseColorScheme(options.colorScheme) : void 0
   };
 }
@@ -19030,7 +19559,7 @@ async function showPageInfo(options) {
 }
 function emulationRequest(options) {
   if (options.reset) return { reset: true };
-  if (options.viewport === void 0 && options.colorScheme === void 0) {
+  if (options.viewport === void 0 && options.colorScheme === void 0 && !options.mobile) {
     const err = pageEmulateNothingError();
     throw new CommandError(
       err.message,
@@ -19038,8 +19567,9 @@ function emulationRequest(options) {
       EXIT_CODES.INVALID_ARGUMENTS
     );
   }
+  const viewport = requestedViewport(options.viewport, options.mobile);
   return {
-    ...options.viewport !== void 0 && { viewport: parseViewport(options.viewport) },
+    ...viewport && { viewport },
     ...options.colorScheme !== void 0 && {
       colorScheme: parseColorScheme(options.colorScheme)
     }
@@ -19076,10 +19606,17 @@ function registerPageCommands(program2) {
   ).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(
+  page.command("emulate").description(PAGE_EMULATE_DESCRIPTION).option(
+    "--viewport <WxH>",
+    "Viewport size in CSS px, e.g. 900x700 (a desktop one unless --mobile)"
+  ).option("--color-scheme <scheme>", "Emulate prefers-color-scheme: light or dark").option(
+    "--mobile",
+    "Emulate a phone: mobile viewport (390x844 unless --viewport), touch, mobile user agent"
+  ).addOption(
     new Option("--reset", "Back to the browser window size and the system setting").conflicts([
       "viewport",
-      "colorScheme"
+      "colorScheme",
+      "mobile"
     ])
   ).addOption(jsonOption()).action(async (options) => {
     await emulate(options);
@@ -19094,6 +19631,9 @@ function registerPageCommands(program2) {
 }
 
 // src/commands/peek.ts
+init_errors3();
+init_messages();
+init_exitCodes();
 function parseOptions(options) {
   const lastN = positiveIntRule({
     name: "--last",
@@ -19103,7 +19643,21 @@ function parseOptions(options) {
     allowZeroForAll: true
   }).validate(options.last);
   const resourceTypes = resourceTypeRule().validate(options.type);
-  return { lastN, resourceTypes };
+  if (options.interval !== void 0 && !options.follow) {
+    const err = intervalWithoutFollowError();
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.INVALID_ARGUMENTS
+    );
+  }
+  const interval = positiveIntRule({
+    name: "--interval",
+    min: 100,
+    max: 6e4,
+    default: 1e3
+  }).validate(options.interval);
+  return { lastN, resourceTypes, interval };
 }
 function peekSection(options) {
   if (options.network) return "network";
@@ -19137,11 +19691,12 @@ function createPreviewOptions(base, resourceTypes, unfilteredCount) {
   }
   return options;
 }
-async function runFollowMode3(options, lastN, resourceTypes, baseOptions) {
+async function runFollowMode3(options, parsed, baseOptions) {
+  const { lastN, resourceTypes, interval } = parsed;
   const showPreview = async () => {
     const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
     if (!result.success) {
-      return followFetchFailure(result, { json: options.json, retryIntervalMs: 1e3 });
+      return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
     }
     noteFollowConnected();
     if (!options.json) console.clear();
@@ -19156,11 +19711,34 @@ async function runFollowMode3(options, lastN, resourceTypes, baseOptions) {
   await setupFollowMode(showPreview, {
     startMessage: followingPreviewMessage,
     stopMessage: stoppedFollowingPreviewMessage,
-    intervalMs: 1e3
+    intervalMs: interval
   });
 }
+function parsePeekOptions(options) {
+  try {
+    return parseOptions(options);
+  } catch (error) {
+    handleValidationError(error, options.json ?? false);
+  }
+}
+function previewDisplayOptions(options, lastN) {
+  return {
+    json: options.json,
+    network: options.network,
+    console: options.console,
+    last: lastN,
+    verbose: options.verbose,
+    follow: options.follow
+  };
+}
+async function followPreview(options) {
+  const following = { ...options, follow: true };
+  showBothSectionsWhenBothRequested(following);
+  const parsed = parsePeekOptions(following);
+  await runFollowMode3(following, parsed, previewDisplayOptions(following, parsed.lastN));
+}
 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(
+  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("--interval <ms>", "Refresh interval of --follow in ms, 100-60000 (default: 1000)").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) => {
@@ -19170,25 +19748,11 @@ function registerPeekCommand(program2) {
         '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);
-    }
-    const baseOptions = {
-      json: options.json,
-      network: options.network,
-      console: options.console,
-      last: lastN,
-      verbose: options.verbose,
-      follow: options.follow
-    };
+    const parsed = parsePeekOptions(options);
+    const { lastN, resourceTypes } = parsed;
+    const baseOptions = previewDisplayOptions(options, lastN);
     if (options.follow) {
-      await runFollowMode3(options, lastN, resourceTypes, baseOptions);
+      await runFollowMode3(options, parsed, baseOptions);
       return;
     }
     await runCommand(
@@ -19657,62 +20221,14 @@ function registerStopCommand(program2) {
 }
 
 // src/commands/tail.ts
-function parseOptions2(options) {
-  const lastRule = positiveIntRule({
-    name: "--last",
-    min: 1,
-    max: MAX_LAST_ITEMS,
-    default: 10,
-    allowZeroForAll: true
-  });
-  const intervalRule = positiveIntRule({ name: "--interval", min: 100, max: 6e4, default: 1e3 });
-  return {
-    lastN: lastRule.validate(options.last),
-    interval: intervalRule.validate(options.interval)
-  };
-}
-function createPreviewOptions2(options, lastN) {
-  return {
-    json: options.json,
-    network: options.network,
-    console: options.console,
-    last: lastN,
-    verbose: options.verbose,
-    follow: true,
-    viewedAt: /* @__PURE__ */ new Date()
-  };
-}
 function registerTailCommand(program2) {
-  program2.command("tail").description("Continuously monitor session data (like tail -f)").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(
+  program2.command("tail").description('Deprecated: use "bdg peek --follow" (same options)').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(
     "--last <count>",
     "Show last N items (network requests + console messages), 0 for all",
     "10"
   ).option("--interval <ms>", "Update interval in milliseconds", "1000").action(async (options) => {
-    showBothSectionsWhenBothRequested(options);
-    let lastN;
-    let interval;
-    try {
-      const parsed = parseOptions2(options);
-      lastN = parsed.lastN;
-      interval = parsed.interval;
-    } catch (error) {
-      handleValidationError(error, options.json ?? false);
-    }
-    const showPreview = async () => {
-      const result = await fetchPreviewOutput({ lastN });
-      if (!result.success) {
-        return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
-      }
-      noteFollowConnected();
-      if (!options.json) console.clear();
-      console.log(formatPreview(result.data, createPreviewOptions2(options, lastN)));
-      return void 0;
-    };
-    await setupFollowMode(showPreview, {
-      startMessage: followingPreviewMessage,
-      stopMessage: stoppedFollowingPreviewMessage,
-      intervalMs: interval
-    });
+    console.error(tailDeprecatedNotice());
+    await followPreview({ ...options, follow: true });
   });
 }
 
@@ -19736,12 +20252,15 @@ var commandRegistry = [
   registerDomCommands,
   registerFormInteractionCommands,
   registerPageCommands,
+  registerCssCommands,
   addCommandGroup("CDP Commands:"),
   registerCdpCommand,
   addCommandGroup("Network Commands:"),
   registerNetworkCommands,
   addCommandGroup("Console Commands:"),
-  registerConsoleCommand
+  registerConsoleCommand,
+  addCommandGroup("Agent Setup:"),
+  registerInstallSkillCommand
 ];
 
 // src/index.ts