dsh-builtin-browser 0.4.6 → 0.4.8

package/src/browser-electron/provider.ts

@@ -217,6 +217,17 @@ export interface ElectronBrowserViewHost {
    *   which is only correct from a teardown that is itself global.
    */
   releasePage?(owner?: string): Promise<void>
+  /**
+   * Report that this carrier can no longer serve anything, so its owner may replace it.
+   *
+   * A carrier that borrows an outside process can lose it: the desktop shell exits, and every call
+   * after that would dial a port nobody owns. Without this signal the swap happens only at
+   * startup, so the choice made then is final for the process's life — which is what a user
+   * experiences as "the browser stopped working until I restart DSH". Optional: a carrier that
+   * owns its own lifetime has nothing to report.
+   * @param listener - called once, when the carrier concludes it is gone.
+   */
+  onLost?(listener: () => void): void
   /**
    * Fold the carrier's presentation away while keeping the page alive.
    *
@@ -312,10 +323,21 @@ export interface ElectronViewHandle {
   capture?(opts?: ScreenshotOptions): Promise<{ base64: string; mime: string; width?: number; height?: number }>
 }
 
-/** One tab inside a session: its view plus a stable id. */
+/**
+ * One tab inside a session: its view, a stable id, and the last URL this provider accepted.
+ *
+ * `url` does two jobs. It separates "never navigated" from "navigated, but the URL could not be
+ * read" — the two used to collapse into the same empty string — and it lets `listTabs` skip
+ * probing a tab it already knows is blank, where a probe is a round trip on an uncommitted view
+ * that can only answer nothing.
+ *
+ * `handle` is deliberately NOT readonly: a view that has wedged is replaced in place, and the tab
+ * keeps its public id across that replacement (see `replaceTabWithBlank`).
+ */
 interface Tab {
   readonly id: string
-  readonly handle: ElectronViewHandle
+  handle: ElectronViewHandle
+  url: string
 }
 
 /** One live browser session: an ordered list of tabs, one active. */
@@ -371,7 +393,7 @@ export interface ElectronBrowserProviderConfig {
    */
   readonly contentMaxChars?: number
   /**
-   * Directory `browser_download` save paths must resolve inside (prevents a
+   * Directory `dsh_browser_download` save paths must resolve inside (prevents a
    * prompt-injected agent from writing arbitrary machine paths). Default:
    * `~/Downloads`. NOTE: this default is a convenience, not a security
    * boundary — on Windows it may resolve to OneDrive/redirected paths;
@@ -455,7 +477,7 @@ export function layoutSize(metrics: Record<string, unknown>): { width: number; h
 }
 
 /**
- * Map CDP cookies onto the shape `browser_auth` exports.
+ * Map CDP cookies onto the shape `dsh_browser_auth` exports.
  *
  * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
  * milliseconds, so both are converted. Entries missing a name, value or domain are
@@ -717,7 +739,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // session), carrying the label for the window title. Hosts without
     // groupView keep the shared-window behavior.
     this.host.groupView?.(handle, id, label)
-    this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 })
+    this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle, url: '' }], activeIndex: 0, history: [], nextSeq: 1 })
     return Promise.resolve(id)
   }
 
@@ -737,9 +759,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
     for (let i = 0; i < s.tabs.length; i++) {
       const tab = s.tabs[i]
       if (tab === undefined) continue // defensive: array can shift under concurrency
+      // A tab we know has never navigated is NOT probed: its view has committed no document, so
+      // the round trip can only answer nothing — and it is the round trip that costs. A tab that
+      // HAS navigated is re-read, because the page may have moved itself since; a read that fails
+      // keeps the last accepted URL rather than reporting the tab as blank.
+      const liveUrl = tab.url === '' ? '' : await this.currentUrl(tab.handle).catch(() => tab.url)
+      if (liveUrl !== '') tab.url = liveUrl
       result.push({
         id: tab.id,
-        url: await this.currentUrl(tab.handle).catch(() => ''),
+        url: liveUrl,
         active: i === s.activeIndex,
       })
     }
@@ -825,7 +853,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
   async navigate(session: BrowserSessionId, request: { readonly url: string }, signal?: AbortSignal): Promise<void> {
     const s = this.session(session)
-    const { handle } = this.activeTab(s)
+    const tab = this.activeTab(s)
+    const { handle } = tab
     const url = request.url
     try {
       if (this.httpOnly) {
@@ -870,6 +899,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // the visit written to the persistent history for a navigation nobody awaits any more.
       signal?.throwIfAborted()
       this.record(s, 'navigate', { url }, true)
+      // The tab now holds a committed document, which is what the blank short-circuit in
+      // `snapshot`/`a11y` keys on. Recorded here rather than after the settle below: the
+      // navigation HAS committed, and a tab wrongly treated as blank would return empty results
+      // for a page that is really there.
+      tab.url = url
       await this.settleDocument(handle, before, signal)
       this.recordVisit(s, handle)
       this.showActive(s)
@@ -921,9 +955,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /**
    * Page.navigate resolves at navigation COMMIT, not at load: the new document
    * is already current (so location.href and document.title are the new page's)
-   * while its DOM is still being parsed. browser_open snapshots immediately
+   * while its DOM is still being parsed. dsh_browser_open snapshots immediately
    * after navigating, which is why it could report the right title with zero
-   * interactive elements — and why a separate browser_snapshot right after
+   * interactive elements — and why a separate dsh_browser_snapshot right after
    * always found them.
    *
    * Wait — bounded, best-effort — for the new document to settle: readyState
@@ -1043,7 +1077,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    *
    * A renderer only delivers key events to the view that holds web focus. A
    * view that was created but never clicked holds none — and `Input` events
-   * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+   * injected over CDP do not grant it — so the FIRST `dsh_browser_key` of a fresh
    * session vanished inside the renderer while the command still answered
    * success. Hosts that cannot focus a view (a test double, a different shell
    * adapter) simply have no `focus`, and nothing changes for them.
@@ -1052,7 +1086,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (handle.focus === undefined) return
     try {
       // Bounded, unlike the rest of this call: the child RPC has no timeout of its own,
-      // and this runs before typing, so an unresponsive child would hang browser_key for
+      // and this runs before typing, so an unresponsive child would hang dsh_browser_key for
       // good. A timeout is caught below exactly like any other focus failure, so the
       // best-effort contract is unchanged.
       await withTimeout(handle.focus(), 5_000, undefined, 'browser: focusing the view timed out')
@@ -1205,6 +1239,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const s = this.session(session)
     const tab = this.activeTab(s)
     signal?.throwIfAborted()
+    // A tab that has never navigated is a blank, uncommitted view. The collector cannot answer in
+    // it — there is no document to commit — so the call would sit out its whole budget before
+    // saying anything. Answering the empty page immediately is both faster and more truthful.
+    if (tab.url === '') return { url: '', elements: [], truncated: false }
     const script = `(() => {
       const cap = ${String(this.snapshotMaxElements)}
       const url = location.href
@@ -1277,13 +1315,31 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // Same hang guard as execute: a renderer that has not committed after
     // navigate would otherwise block snapshot forever.
     const timeoutMs = 30_000
-    const result = await withTimeout(
-      handleSendEvaluate(tab.handle, script),
-      timeoutMs,
-      signal,
-      `browser: snapshot timed out after ${timeoutMs}ms`,
-      () => terminatePage(tab.handle),
-    )
+    let result: { ok: true; value: unknown } | { ok: false; exception: string }
+    try {
+      result = await withTimeout(
+        handleSendEvaluate(tab.handle, script),
+        timeoutMs,
+        signal,
+        `browser: snapshot timed out after ${timeoutMs}ms`,
+        () => terminatePage(tab.handle),
+      ) as { ok: true; value: unknown } | { ok: false; exception: string }
+    } catch (error) {
+      // A timeout leaves the wedged view in the session, so every later read would pay the same
+      // 30 seconds again — and `terminatePage` only interrupts the running script, it does not
+      // make the view readable. Replacing it is what turns a permanent loss into one bad call:
+      // the tab keeps the id the caller holds, and the next dsh_browser_open with the real URL
+      // repopulates it.
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        this.replaceTabWithBlank(s, tab)
+        throw new BrowserError(
+          'browser: snapshot timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.',
+          'BROWSER_SNAPSHOT_TIMEOUT',
+          { cause: error },
+        )
+      }
+      throw error
+    }
     if (!result.ok) throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED')
     const value = result.value as BrowserSnapshotResult
     return value
@@ -1301,6 +1357,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const s = this.session(session)
     const tab = this.activeTab(s)
     signal?.throwIfAborted()
+    // Same short-circuit as `snapshot`: a tab that never navigated has no committed document, so
+    // the tree cannot be read and the call would spend its whole budget discovering that.
+    if (tab.url === '') return { url: '', title: undefined, count: 0, nodes: [], truncated: false }
     const includeHidden = request.includeHidden === true
     // 150 rather than 500. The cap fills on any real page, and 500 nodes measured 38,953
       // characters — 10k-13k tokens for a single call. A caller that needs more asks for it.
@@ -1462,13 +1521,28 @@ export class ElectronBrowserProvider implements BrowserProvider {
       return { url: location.href, title: document.title || undefined, count: out.length, nodes: out, truncated: out.length >= maxNodes }
     })()`
     const timeoutMs = 30_000
-    const result = await withTimeout(
-      handleSendEvaluate(tab.handle, script),
-      timeoutMs,
-      signal,
-      `browser: a11y timed out after ${timeoutMs}ms`,
-      () => terminatePage(tab.handle),
-    )
+    let result: { ok: true; value: unknown } | { ok: false; exception: string }
+    try {
+      result = await withTimeout(
+        handleSendEvaluate(tab.handle, script),
+        timeoutMs,
+        signal,
+        `browser: a11y timed out after ${timeoutMs}ms`,
+        () => terminatePage(tab.handle),
+      ) as { ok: true; value: unknown } | { ok: false; exception: string }
+    } catch (error) {
+      // As in `snapshot`: a timeout means the view is wedged, and leaving it in the session would
+      // charge every later read the same 30 seconds. Replaced in place, so the tab id survives.
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        this.replaceTabWithBlank(s, tab)
+        throw new BrowserError(
+          'browser: a11y timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.',
+          'BROWSER_A11Y_TIMEOUT',
+          { cause: error },
+        )
+      }
+      throw error
+    }
     if (!result.ok) throw new BrowserError(`browser: a11y evaluation failed: ${result.exception}`, 'BROWSER_A11Y_FAILED')
     const value = result.value as BrowserA11yResult
     this.record(s, 'a11y', { includeHidden, maxNodes }, true, { result: `${value.count} nodes` })
@@ -1929,7 +2003,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       placeholder: f.placeholder ?? null,
       // A field with NO kind is a field with no kind FILTER: absent, not 'text'. Defaulting
       // it to 'text' here made `if (spec.kind)` above always true, so every unspecified
-      // field was narrowed to an <input> — browser_fill on a <textarea> reported
+      // field was narrowed to an <input> — dsh_browser_fill on a <textarea> reported
       // `no "text" control matched`, and a contenteditable could not match any kind at all.
       // The value stays a string or null (never undefined): the in-page check tests truthiness,
       // and JSON drops an undefined member entirely, which is the same thing here.
@@ -2064,7 +2138,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
             el.dispatchEvent(new Event('change', { bubbles: true }))
             out.push({ ok: true, method: 'select', target: describe(spec) })
           } else if (type === 'file') {
-            out.push({ ok: false, error: 'file inputs cannot be set from script; use browser_download or ask the human', target: describe(spec) })
+            out.push({ ok: false, error: 'file inputs cannot be set from script; use dsh_browser_download or ask the human', target: describe(spec) })
           } else if (type === 'checkbox') {
             const want = spec.value === true || spec.value === 'true' || spec.value === 'on'
             if (el.checked !== want) el.click()
@@ -2518,7 +2592,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * Refuse an action the settings have switched off.
    *
    * These switches belong to the OPERATOR. The settings document is written through the
-   * plugin's own panel and no tool can reach it, so — unlike `browser_restrict`, which the
+   * plugin's own panel and no tool can reach it, so — unlike `dsh_browser_restrict`, which the
    * model owns and can lift at will — a refusal here stands for as long as the setting does.
    * That is the point of them: a deployment can take page-script execution, downloads, or
    * login-state writes off the table without relying on the model's cooperation.
@@ -2545,7 +2619,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /**
    * Admit a caller-supplied save path for a file the browser writes to disk.
-   * ONE gate for both `browser_download` and `browser_screenshot`: the path
+   * ONE gate for both `dsh_browser_download` and `dsh_browser_screenshot`: the path
    * must be absolute, must resolve inside `downloadDir`, and must not already
    * exist. Without it a prompt-injected agent could write — or silently
    * replace — any file the DSH process can reach, which also escapes the file
@@ -2979,7 +3053,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 
   /**
-   * List persisted visits, newest first — what `browser_visited` reads back.
+   * List persisted visits, newest first — what `dsh_browser_visited` reads back.
    * @param options - result cap and an optional hostname filter.
    * @returns the matching visits, or an empty list when history is disabled.
    */
@@ -3116,11 +3190,41 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const handle = this.host.createView(s.label)
     // Same window as the session's other tabs.
     this.host.groupView?.(handle, s.id, s.label)
-    s.tabs.push({ id: `tab:${randomUUID()}`, handle })
+    s.tabs.push({ id: `tab:${randomUUID()}`, handle, url: '' })
     s.activeIndex = s.tabs.length - 1
     this.showActive(s)
   }
 
+  /**
+   * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+   *
+   * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+   * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+   * callers hold stays valid, and the next `dsh_browser_open` with the real URL re-populates it.
+   *
+   * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+   * session holding a handle that is already gone.
+   * @param s - the session owning the tab.
+   * @param tab - the tab to reset.
+   */
+  private replaceTabWithBlank(s: Session, tab: Tab): void {
+    const index = s.tabs.indexOf(tab)
+    if (index < 0) return
+    let handle: ElectronViewHandle
+    try {
+      handle = this.host.createView(s.label)
+      this.host.groupView?.(handle, s.id, s.label)
+    } catch {
+      // Creating the replacement failed: leaving the wedged tab in place is worse than nothing
+      // only for the caller, who is about to be told the tab timed out either way.
+      return
+    }
+    const wedged = tab.handle
+    s.tabs[index] = { id: tab.id, handle, url: '' }
+    if (index === s.activeIndex) this.showActive(s)
+    this.host.destroyView(wedged)
+  }
+
   /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
   private tabByViewId(s: Session, viewId: string): Tab | undefined {
     return s.tabs.find(tab => tab.handle.id === viewId)

package/src/browser-electron/remote-host.ts

@@ -1327,7 +1327,7 @@ class DeferredRemoteView implements ElectronViewHandle {
    * with "browser host is not running". Instead: drop the cache, rebuild the
    * view against a freshly spawned child, and retry the operation exactly
    * once — so sessions that survive a host death self-heal on their FIRST
-   * call after it, without a manual browser_reset_session. Page-level errors
+   * call after it, without a manual dsh_browser_reset_session. Page-level errors
    * are never retried (the view itself is fine).
    */
   private async withRecovery<T>(op: (view: RemoteView) => Promise<T>): Promise<T> {

package/src/browser-electron/settings-store.ts

@@ -55,15 +55,15 @@ export interface BrowserSettings {
    *
    * These are OPERATOR switches: the settings panel is not reachable from the model, so a
    * value here refuses whatever the model asks for, and no tool can lift it. That is what
-   * separates them from `browser_restrict`, which is the model's own soft guardrail. All
+   * separates them from `dsh_browser_restrict`, which is the model's own soft guardrail. All
    * three default to on, which is the documented out-of-the-box behaviour.
    */
   readonly actions: {
-    /** Run arbitrary page scripts in the active tab (`browser_execute`). */
+    /** Run arbitrary page scripts in the active tab (`dsh_browser_execute`). */
     readonly allowExecute: boolean
-    /** Download a URL to disk (`browser_download`). */
+    /** Download a URL to disk (`dsh_browser_download`). */
     readonly allowDownload: boolean
-    /** Write cookies — importing login state (`browser_auth` restore). */
+    /** Write cookies — importing login state (`dsh_browser_auth` restore). */
     readonly allowCredentialWrite: boolean
   }
 }
@@ -129,16 +129,35 @@ const SETTINGS_WHEN_UNREADABLE: BrowserSettings = {
   actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
 }
 
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export const BROWSER_CHANNELS = ['chrome', 'edge', 'auto', 'bundled', 'sidebar'] as const
+
 /**
  * Coerce the browser channel, keeping the default when it is not one of the
  * known choices. A hand-edited typo must not silently select a different browser.
+ *
+ * Coercing is right; coercing QUIETLY is not. A typo and "the setting did nothing" look exactly
+ * the same to whoever typed it, which is why every discarded value is reported.
  * @param value - the raw value from the settings document.
+ * @param warn - where to report a discarded value, when the caller has somewhere to put it.
  * @returns a valid channel.
  */
-function resolveChannel(value: unknown): BrowserChannel {
-  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
-    ? value
-    : DEFAULT_SETTINGS.browser.channel
+function resolveChannel(value: unknown, warn?: (message: string) => void): BrowserChannel {
+  // Absent is the ordinary case, not a mistake: a document that never mentioned the channel gets
+  // the default without a word.
+  if (value === undefined) return DEFAULT_SETTINGS.browser.channel
+  if ((BROWSER_CHANNELS as readonly unknown[]).includes(value)) return value as BrowserChannel
+  warn?.(
+    `dsh-builtin-browser: browser.channel ${JSON.stringify(value)} is not a known channel, so the `
+    + `default "${DEFAULT_SETTINGS.browser.channel}" was used instead. Expected one of: `
+    + `${BROWSER_CHANNELS.join(', ')}.`,
+  )
+  return DEFAULT_SETTINGS.browser.channel
 }
 
 /** Coerce one positive-integer field, keeping the default when invalid. */
@@ -181,7 +200,7 @@ function section(source: Record<string, unknown>, key: string): Record<string, u
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export function resolveSettings(raw: unknown): BrowserSettings {
+export function resolveSettings(raw: unknown, warn?: (message: string) => void): BrowserSettings {
   const source = typeof raw === 'object' && raw !== null ? raw as Record<string, unknown> : {}
   const history = section(source, 'history')
   const cookies = section(source, 'cookies')
@@ -208,7 +227,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
       virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
     },
     vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-    browser: { channel: resolveChannel(browser?.channel) },
+    browser: { channel: resolveChannel(browser?.channel, warn) },
     credentials: {
       // `gate` returns false for anything present-and-not-a-boolean, so an unreadable section
       // is refused here for free: the section itself is the "present but wrong" value.
@@ -244,7 +263,7 @@ export class SettingsStore {
   /**
    * @param file - settings file path (defaults beside the browser profile).
    */
-  constructor(private readonly file: string = settingsPath()) {}
+  constructor(private readonly file: string = settingsPath(), private readonly log?: (message: string) => void) {}
 
   /** Path this store reads and writes. */
   path(): string {
@@ -291,7 +310,7 @@ export class SettingsStore {
       // value in it: the document looked correct, and the plugin quietly ran on
       // defaults — including switches the user had just turned off.
       const body = text?.replace(/^\uFEFF/, '')
-      this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body))
+      this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body), m => this.log?.(m))
     } catch {
       // A document that EXISTS but cannot be parsed is not the same as no document at all: the
       // first is a corrupted or half-written file whose contents were the operator's decisions,
@@ -311,7 +330,7 @@ export class SettingsStore {
    */
   update(patch: unknown): BrowserSettings {
     const current = this.get()
-    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
+    const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch), m => this.log?.(m))
     try {
       mkdirSync(dirname(this.file), { recursive: true })
       writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`)

package/src/index.ts

@@ -3,7 +3,7 @@
  * pieces. The cordis.patch.yml rows reference subpath exports:
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
- *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing dsh_browser_* tools
  * The capability itself is composed by those rows; this root entry exists for
  * programmatic imports AND because the host's client-module scan identifies a
  * package's browser half through a loader row whose specifier resolves to the

package/src/tool-browser/element-fields.ts

@@ -8,9 +8,9 @@
  * and the tool's `output.schema` declared the properties. Nothing connected them, and the
  * result is this project's most repeatable bug:
  *
- *   - `browser_a11y`'s `selector` — computed by the provider, declared by the schema,
+ *   - `dsh_browser_a11y`'s `selector` — computed by the provider, declared by the schema,
  *     printed by the renderer, and dropped by the projection. 134 tests stayed green.
- *   - `browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
+ *   - `dsh_browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
  *     schema, and dropped by the projection. 172 tests stayed green. It was found a round
  *     later, by reading the three places that agree and noticing the fourth did not.
  *
@@ -33,7 +33,7 @@ interface FieldSpec {
 }
 
 /**
- * The fields of one entry in `browser_snapshot` / `browser_open`'s `elements`.
+ * The fields of one entry in `dsh_browser_snapshot` / `dsh_browser_open`'s `elements`.
  *
  * `selector` is the reason this file exists; see the header. It was added to the schema and
  * the projection separately, and only one of them landed.
@@ -49,7 +49,7 @@ const ELEMENT_FIELDS = {
 } as const satisfies Record<string, FieldSpec>
 
 /**
- * The fields of one entry in `browser_a11y`'s `nodes`.
+ * The fields of one entry in `dsh_browser_a11y`'s `nodes`.
  *
  * Different shape from an element on purpose: a role and an accessible name carry meaning a
  * tag and a label string do not, and `depth` is what renders the tree.
@@ -91,7 +91,7 @@ function project(fields: Record<string, FieldSpec>, source: Record<string, unkno
 }
 
 /**
- * The `elements` item schema for browser_snapshot and browser_open.
+ * The `elements` item schema for dsh_browser_snapshot and dsh_browser_open.
  *
  * Written as a literal rather than generated, because `defineTool` validates the output schema
  * against its own `ValueSchemaSpec` and a generated `Record<string, …>` is too wide to satisfy
@@ -114,7 +114,7 @@ export const ELEMENT_ITEM_SCHEMA = {
 } as const
 
 /**
- * The `nodes` item schema for browser_a11y.
+ * The `nodes` item schema for dsh_browser_a11y.
  *
  * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
  * test.