browser-debugger-cli 0.13.0 → 0.15.0

package/dist/runtime/dom/targetNode.d.ts

@@ -26,16 +26,20 @@ export declare const UNBIND_TARGET_SCRIPT = "delete window.__bdgTarget; delete w
  * the text nodes of hidden ones (display or visibility; not those of
  * `<script>`, `<style>` or `<noscript>`), so text filters match hidden
  * elements like Playwright's and `:visible` decides visibility; button inputs
- * use their value. Whitespace is collapsed; filter texts arrive normalized
- * (`has-text` lowercased). `:visible` is checked before the text filters,
- * which read the text.
+ * use their value. Text is read in the flat tree, as `bdg dom query` shows
+ * it: the text a web component's open shadow root renders, slotted content
+ * in place of its slots. A visible component, slot or element holding either
+ * ({@link COMPOSED_JS}) is read with {@link FLAT_TEXT_JS}, including the
+ * selects and editable regions `innerText` reads. Whitespace is collapsed;
+ * filter texts arrive normalized (`has-text` lowercased). `:visible` is
+ * checked before the text filters, which read the text.
  *
  * Steps and `:has()` match CSS relative to an element (`:scope > css`). A
  * descendant step also searches the open shadow roots under the element (the
  * whole step CSS inside one shadow tree); a child step stays in the
  * element's own tree.
  */
-export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n}";
+export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n}";
 /**
  * Page-side selector search that also reaches into open shadow roots and
  * same-origin iframes (recursively), like a user sees the page.
@@ -49,7 +53,7 @@ export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const skipped =
  * reached. Cross-origin iframes are separate processes and cannot be
  * searched. Throws a `SyntaxError` for an invalid selector.
  */
-export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n}";
+export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n}";
 /**
  * Page-side element lookup shared by the interaction scripts.
  *
@@ -58,7 +62,7 @@ export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css
  * built-ins ({@link bindMatches}), otherwise all matches of the selector
  * ({@link DEEP_QUERY_JS}).
  */
-export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  const bound = window.__bdgMatches;\n  if (bound && bound.selector === selector) {\n    const connected = [];\n    for (let i = 0; i < bound.nodes.length; i++) {\n      if (bound.nodes[i] && bound.nodes[i].isConnected) connected[connected.length] = bound.nodes[i];\n    }\n    return connected;\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n})(selector, parts);\n}";
+export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  const bound = window.__bdgMatches;\n  if (bound && bound.selector === selector) {\n    const connected = [];\n    for (let i = 0; i < bound.nodes.length; i++) {\n      if (bound.nodes[i] && bound.nodes[i].isConnected) connected[connected.length] = bound.nodes[i];\n    }\n    return connected;\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n})(selector, parts);\n}";
 /**
  * Page-side check of what selectors cannot search in the top document:
  * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`

package/dist/runtime/dom/targetNode.js

@@ -10,6 +10,7 @@
  */
 import { CommandError } from '../../errors/index.js';
 import { actionBrokenByPageError, actionScriptFailedError, emptySelectorError, indexOutOfRangeError, noNodesFoundError, staleNodeError, } from '../../errors/messages.js';
+import { COMPOSED_JS, FLAT_TEXT_JS } from './elementInfo.js';
 import { ActionScriptError, throwIfInvalidSelector } from './formFillHelpers/shared.js';
 import { frameScopedConnection } from './frameScopedConnection.js';
 import { evaluateInBdgWorld } from '../page/bdgWorld.js';
@@ -102,9 +103,13 @@ const log = createLogger('dom');
  * the text nodes of hidden ones (display or visibility; not those of
  * `<script>`, `<style>` or `<noscript>`), so text filters match hidden
  * elements like Playwright's and `:visible` decides visibility; button inputs
- * use their value. Whitespace is collapsed; filter texts arrive normalized
- * (`has-text` lowercased). `:visible` is checked before the text filters,
- * which read the text.
+ * use their value. Text is read in the flat tree, as `bdg dom query` shows
+ * it: the text a web component's open shadow root renders, slotted content
+ * in place of its slots. A visible component, slot or element holding either
+ * ({@link COMPOSED_JS}) is read with {@link FLAT_TEXT_JS}, including the
+ * selects and editable regions `innerText` reads. Whitespace is collapsed;
+ * filter texts arrive normalized (`has-text` lowercased). `:visible` is
+ * checked before the text filters, which read the text.
  *
  * Steps and `:has()` match CSS relative to an element (`:scope > css`). A
  * descendant step also searches the open shadow roots under the element (the
@@ -112,14 +117,15 @@ const log = createLogger('dom');
  * element's own tree.
  */
 export const FILTER_MATCHING_JS = `(shadowRoots) => {
+  const composed = ${COMPOSED_JS};
+  const flatText = ${FLAT_TEXT_JS};
   const skipped = /^(script|style|noscript|template)$/;
   const hiddenText = (el) => {
-    const walker = el.ownerDocument.createTreeWalker(el, 5, {
-      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)
-    });
+    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;
     let text = '';
-    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    for (const node of nodes) {
       if (node.nodeType === 3) text += node.data;
+      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);
     }
     return text;
   };
@@ -127,7 +133,8 @@ export const FILTER_MATCHING_JS = `(shadowRoots) => {
     if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;
     const rendered = typeof el.innerText === 'string' &&
       (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));
-    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();
+    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;
+    return text.replace(/\\s+/g, ' ').trim();
   };
   const passes = (el, filter) => {
     if (filter.kind === 'visible') {

package/dist/runtime/page/emulation.js

@@ -60,12 +60,13 @@ export async function applySessionEmulation(cdp, emulation) {
  */
 async function emulatePhone(cdp, on) {
     await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: on, maxTouchPoints: on ? 5 : 1 });
-    const { userAgent } = (await cdp.send('Browser.getVersion', {}));
+    const version = (await cdp.send('Browser.getVersion', {}));
+    const { userAgent } = version;
     if (!on) {
-        const headless = userAgent.includes('HeadlessChrome');
-        await cdp.send('Emulation.setUserAgentOverride', { userAgent: headless ? userAgent : '' });
-        if (headless)
-            await hideHeadlessUserAgent(cdp, log);
+        if (userAgent.includes('HeadlessChrome'))
+            await hideHeadlessUserAgent(cdp, log, version);
+        else
+            await cdp.send('Emulation.setUserAgentOverride', { userAgent: '' });
         return;
     }
     const major = /Chrome\/(\d+)/.exec(userAgent)?.[1] ?? '';

package/dist/runtime/page/userAgent.d.ts

@@ -3,15 +3,99 @@
  * client hints, so sites serve the page a user sees.
  */
 import type { CDPConnection } from '../../connection/cdp.js';
-import type { Logger } from '../../ui/logging/index.js';
+import { type Logger } from '../../ui/logging/index.js';
+/** A brand in the client hints (`Sec-CH-UA`, `navigator.userAgentData.brands`) */
+export interface BrandVersion {
+    brand: string;
+    version: string;
+}
+/** CDP `Emulation.UserAgentMetadata`: the client hints Chrome sends and reports */
+export interface UserAgentMetadata {
+    brands: BrandVersion[];
+    fullVersionList: BrandVersion[];
+    fullVersion: string;
+    platform: string;
+    platformVersion: string;
+    architecture: string;
+    bitness: string;
+    model: string;
+    mobile: boolean;
+    wow64: boolean;
+    formFactors: string[];
+}
+/** The machine the daemon runs on, as client hints name it */
+export interface HostPlatform {
+    /** Client-hint platform (`macOS`, `Windows`, `Linux`) */
+    platform: string;
+    /** OS version as Chrome reports it */
+    platformVersion: string;
+    /** `arm` or `x86` */
+    architecture: string;
+    /** `64` or `32` */
+    bitness: string;
+}
+/** `Browser.getVersion` fields the metadata is built from */
+export interface BrowserVersion {
+    product: string;
+    userAgent: string;
+}
+/**
+ * Chrome's brand list for a version, built the way Chrome builds it
+ * (`GenerateBrandVersionList` in Chromium's `user_agent_utils.cc`): a
+ * made-up brand, Chromium and the browser's brand, in an order and with a
+ * made-up name and version that depend on the major version.
+ *
+ * @param major - Major version (the seed)
+ * @param chromium - Chromium version to list
+ * @param browser - Browser brand and version
+ * @param greaseSuffix - Appended to the made-up version (`.0.0.0` in full versions)
+ * @returns Brand list
+ */
+export declare function chromeBrandList(major: number, chromium: string, browser: BrandVersion, greaseSuffix?: string): BrandVersion[];
+/**
+ * The client hints regular Chrome sends, for the browser `Browser.getVersion`
+ * describes. The browser brand is Microsoft Edge when the user agent says
+ * `Edg/`, Google Chrome otherwise (Chromium and Chrome for Testing look the
+ * same over CDP). Edge's Chromium version is only known to the major
+ * version. The OS version, architecture and bitness are the host's when it
+ * runs the platform the user agent names, empty otherwise (a remote Chrome).
+ *
+ * @param version - `Browser.getVersion` product and user agent
+ * @param host - The daemon's machine
+ * @returns Metadata for `Emulation.setUserAgentOverride`
+ */
+export declare function regularChromeMetadata(version: BrowserVersion, host: HostPlatform): UserAgentMetadata;
+/**
+ * The OS version Chrome reports on Linux or Windows, from `os.release()`:
+ * the kernel version's first three numbers on Linux, and on Windows `13.0.0`
+ * for Windows 11 and `10.0.0` before it (Chrome reports a Windows API
+ * version there, not the OS build).
+ *
+ * @param platform - `process.platform`
+ * @param release - `os.release()`
+ * @returns OS version, or empty when unknown
+ */
+export declare function releasePlatformVersion(platform: string, release: string): string;
+/**
+ * The daemon's machine as client hints describe it.
+ *
+ * @returns Platform, OS version, architecture and bitness
+ */
+export declare function hostPlatform(): HostPlatform;
 /**
  * Send the user agent and client hints of regular Chrome from headless
  * Chrome: sites serve "HeadlessChrome" a different page (or a bot
  * challenge), so the page would not be the one a user sees. Not for a
  * session emulating a phone, whose emulation sets a mobile user agent.
  *
+ * The client hints are built from `Browser.getVersion` and the host
+ * ({@link regularChromeMetadata}) rather than read from the page: the page is
+ * still `about:blank`, which has no `navigator.userAgentData`, and an
+ * override without metadata empties the client hints.
+ *
  * @param cdp - CDP connection
  * @param logger - Logger for failures (the session works without it)
+ * @param known - `Browser.getVersion` result, when the caller has it
  */
-export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger): Promise<void>;
+export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger, known?: BrowserVersion): Promise<void>;
 //# sourceMappingURL=userAgent.d.ts.map

package/dist/runtime/page/userAgent.js

@@ -2,52 +2,173 @@
  * The session's user agent in headless Chrome: regular Chrome's string and
  * client hints, so sites serve the page a user sees.
  */
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
-/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
-const USER_AGENT_METADATA_SCRIPT = `(async () => {
-  const data = navigator.userAgentData;
-  if (!data) return null;
-  const values = await data.getHighEntropyValues(
-    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
-  );
-  const rename = (list) => (list || []).map((entry) => ({
-    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
-    version: entry.version,
-  }));
-  return {
-    brands: rename(values.brands),
-    fullVersionList: rename(values.fullVersionList),
-    platform: values.platform,
-    platformVersion: values.platformVersion,
-    architecture: values.architecture,
-    model: values.model,
-    mobile: values.mobile,
-    bitness: values.bitness,
-    wow64: values.wow64,
-  };
-})()`;
+const log = createLogger('session');
+/** Characters Chrome picks from for its made-up ("GREASE") brand name */
+const GREASE_CHARS = [' ', '(', ':', '-', '.', '/', ')', ';', '=', '?', '_'];
+/** Versions Chrome picks from for its made-up brand */
+const GREASE_VERSIONS = ['8', '99', '24'];
+/** Positions of the made-up brand, Chromium and the browser brand, by major version */
+const BRAND_ORDERS = [
+    [0, 1, 2],
+    [0, 2, 1],
+    [1, 0, 2],
+    [1, 2, 0],
+    [2, 0, 1],
+    [2, 1, 0],
+];
+/** Client-hint platform for each `process.platform` Chrome runs on */
+const HOST_PLATFORMS = {
+    darwin: 'macOS',
+    win32: 'Windows',
+    linux: 'Linux',
+};
+/** Client-hint platform for each platform token of the user agent string */
+const USER_AGENT_PLATFORMS = [
+    [/Android/, 'Android'],
+    [/CrOS/, 'Chrome OS'],
+    [/Macintosh/, 'macOS'],
+    [/Windows/, 'Windows'],
+    [/Linux|X11/, 'Linux'],
+];
+/**
+ * Chrome's brand list for a version, built the way Chrome builds it
+ * (`GenerateBrandVersionList` in Chromium's `user_agent_utils.cc`): a
+ * made-up brand, Chromium and the browser's brand, in an order and with a
+ * made-up name and version that depend on the major version.
+ *
+ * @param major - Major version (the seed)
+ * @param chromium - Chromium version to list
+ * @param browser - Browser brand and version
+ * @param greaseSuffix - Appended to the made-up version (`.0.0.0` in full versions)
+ * @returns Brand list
+ */
+export function chromeBrandList(major, chromium, browser, greaseSuffix = '') {
+    const grease = {
+        brand: `Not${GREASE_CHARS[major % GREASE_CHARS.length]}A${GREASE_CHARS[(major + 1) % GREASE_CHARS.length]}Brand`,
+        version: `${GREASE_VERSIONS[major % GREASE_VERSIONS.length]}${greaseSuffix}`,
+    };
+    const [greaseAt, chromiumAt, browserAt] = BRAND_ORDERS[major % BRAND_ORDERS.length] ?? [0, 1, 2];
+    const list = [];
+    list[greaseAt] = grease;
+    list[chromiumAt] = { brand: 'Chromium', version: chromium };
+    list[browserAt] = browser;
+    return list;
+}
+/**
+ * The client hints regular Chrome sends, for the browser `Browser.getVersion`
+ * describes. The browser brand is Microsoft Edge when the user agent says
+ * `Edg/`, Google Chrome otherwise (Chromium and Chrome for Testing look the
+ * same over CDP). Edge's Chromium version is only known to the major
+ * version. The OS version, architecture and bitness are the host's when it
+ * runs the platform the user agent names, empty otherwise (a remote Chrome).
+ *
+ * @param version - `Browser.getVersion` product and user agent
+ * @param host - The daemon's machine
+ * @returns Metadata for `Emulation.setUserAgentOverride`
+ */
+export function regularChromeMetadata(version, host) {
+    const fullVersion = /\/([\d.]+)/.exec(version.product)?.[1] ?? '';
+    const major = Number.parseInt(fullVersion, 10) || 0;
+    const isEdge = / Edg\//.test(version.userAgent);
+    const chromiumVersion = isEdge ? `${major}.0.0.0` : fullVersion;
+    const brand = isEdge ? 'Microsoft Edge' : 'Google Chrome';
+    const platform = USER_AGENT_PLATFORMS.find(([token]) => token.test(version.userAgent))?.[1] ?? host.platform;
+    const isHost = platform === host.platform;
+    return {
+        brands: chromeBrandList(major, String(major), { brand, version: String(major) }),
+        fullVersionList: chromeBrandList(major, chromiumVersion, { brand, version: fullVersion }, '.0.0.0'),
+        fullVersion,
+        platform,
+        platformVersion: isHost ? host.platformVersion : '',
+        architecture: isHost ? host.architecture : '',
+        bitness: isHost ? host.bitness : '',
+        model: '',
+        mobile: false,
+        wow64: false,
+        formFactors: ['Desktop'],
+    };
+}
+/** First Windows build of Windows 11, which client hints report as version 13 */
+const WINDOWS_11_BUILD = 22000;
+/**
+ * The OS version Chrome reports on Linux or Windows, from `os.release()`:
+ * the kernel version's first three numbers on Linux, and on Windows `13.0.0`
+ * for Windows 11 and `10.0.0` before it (Chrome reports a Windows API
+ * version there, not the OS build).
+ *
+ * @param platform - `process.platform`
+ * @param release - `os.release()`
+ * @returns OS version, or empty when unknown
+ */
+export function releasePlatformVersion(platform, release) {
+    if (platform === 'win32') {
+        const build = Number(release.split('.')[2]);
+        if (!build)
+            return '';
+        return build >= WINDOWS_11_BUILD ? '13.0.0' : '10.0.0';
+    }
+    return /^\d+(\.\d+){0,2}/.exec(release)?.[0] ?? '';
+}
+/**
+ * The OS version as Chrome reports it: the macOS product version (from
+ * `SystemVersion.plist`, as `sw_vers` prints it), or
+ * {@link releasePlatformVersion} elsewhere.
+ *
+ * @returns OS version, or empty when unknown
+ */
+function hostPlatformVersion() {
+    if (process.platform !== 'darwin')
+        return releasePlatformVersion(process.platform, os.release());
+    try {
+        const plist = readFileSync('/System/Library/CoreServices/SystemVersion.plist', 'utf8');
+        return /<key>ProductVersion<\/key>\s*<string>([\d.]+)<\/string>/.exec(plist)?.[1] ?? '';
+    }
+    catch (error) {
+        log.debug(`macOS version unknown: ${getErrorMessage(error)}`);
+        return '';
+    }
+}
+/**
+ * The daemon's machine as client hints describe it.
+ *
+ * @returns Platform, OS version, architecture and bitness
+ */
+export function hostPlatform() {
+    const arch = process.arch;
+    return {
+        platform: HOST_PLATFORMS[process.platform] ?? '',
+        platformVersion: hostPlatformVersion(),
+        architecture: arch.startsWith('arm') ? 'arm' : 'x86',
+        bitness: arch === 'arm64' || arch === 'x64' ? '64' : '32',
+    };
+}
 /**
  * Send the user agent and client hints of regular Chrome from headless
  * Chrome: sites serve "HeadlessChrome" a different page (or a bot
  * challenge), so the page would not be the one a user sees. Not for a
  * session emulating a phone, whose emulation sets a mobile user agent.
  *
+ * The client hints are built from `Browser.getVersion` and the host
+ * ({@link regularChromeMetadata}) rather than read from the page: the page is
+ * still `about:blank`, which has no `navigator.userAgentData`, and an
+ * override without metadata empties the client hints.
+ *
  * @param cdp - CDP connection
  * @param logger - Logger for failures (the session works without it)
+ * @param known - `Browser.getVersion` result, when the caller has it
  */
-export async function hideHeadlessUserAgent(cdp, logger) {
+export async function hideHeadlessUserAgent(cdp, logger, known) {
     try {
-        const { userAgent } = (await cdp.send('Browser.getVersion'));
-        if (!userAgent.includes('HeadlessChrome'))
+        const version = known ?? (await cdp.send('Browser.getVersion'));
+        if (!version.userAgent.includes('HeadlessChrome'))
             return;
-        const metadata = (await cdp.send('Runtime.evaluate', {
-            expression: USER_AGENT_METADATA_SCRIPT,
-            awaitPromise: true,
-            returnByValue: true,
-        }));
         await cdp.send('Emulation.setUserAgentOverride', {
-            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
-            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
+            userAgent: version.userAgent.replace('HeadlessChrome', 'Chrome'),
+            userAgentMetadata: regularChromeMetadata(version, hostPlatform()),
         });
     }
     catch (error) {

package/dist/session/paths.d.ts

@@ -5,6 +5,7 @@
  * (or `~/.bdg/sessions/<name>/` for a named session).
  * WHY: Single source of truth for file locations prevents path inconsistencies.
  */
+import { type DirTrustKind } from '../utils/directories.js';
 /**
  * Session file paths relative to ~/.bdg/
  * Centralized definition for all session-related files.
@@ -123,12 +124,46 @@ export declare function getDaemonSocketPath(): string;
 /**
  * Ensure the session directory exists.
  *
- * Creates ~/.bdg/ if it doesn't exist. Safe to call multiple times (idempotent).
- * A path that cannot hold a directory is refused before `mkdir`, which
- * would spin on a pseudo-filesystem ({@link makeDirectory}).
+ * Creates it, and missing parents (the base directory, `sessions/`), with
+ * mode 0700. Safe to call multiple times (idempotent). A path that cannot
+ * hold a directory is refused before `mkdir`, which would spin on a
+ * pseudo-filesystem ({@link makeDirectory}).
  *
  * @throws Error if the directory cannot be created
  */
 export declare function ensureSessionDir(): void;
+/** A session directory (or one above it) that cannot be trusted */
+export interface UntrustedSessionDir {
+    /** The untrusted directory */
+    dir: string;
+    /** Why, e.g. `writable by others (mode 777)` */
+    reason: string;
+    kind: DirTrustKind;
+    /** bdg owns it by convention (`~/.bdg`, `sessions/`, `sessions/<name>`) */
+    bdgOwned: boolean;
+}
+/**
+ * Check that a session directory and the directories above it up to the base
+ * directory can be trusted before a daemon is started there or its socket is
+ * connected to: another user who can write to one of them could replace the
+ * socket (and receive every command) or plant files. Each existing directory
+ * must be a real directory (not a symlink), owned by the user, and not
+ * writable by others ({@link dirTrustProblem}); group write is accepted, since
+ * under umask 002 (per-user groups) older versions created `~/.bdg` 0775.
+ * The base directory may be a symlink whose target passes the same rule
+ * ({@link chainDirProblem}). A directory owned by another uid (a bind mount,
+ * `sudo -E`) is refused.
+ *
+ * Trusted directories bdg owns (the default `~/.bdg`, `sessions/` and named
+ * session directories) that group or others can still use are tightened to
+ * 0700; a base directory chosen with `$BDG_SESSION_DIR`, or a symlinked base
+ * (opened without following links), is never changed.
+ * Missing paths are skipped (as is a path through a file, which fails on its
+ * own): {@link ensureSessionDir} creates them 0700.
+ *
+ * @param dir - Session directory (default: the selected session's)
+ * @returns The first untrusted directory and why, or null
+ */
+export declare function secureSessionDir(dir?: string): UntrustedSessionDir | null;
 export {};
 //# sourceMappingURL=paths.d.ts.map