dsh-builtin-browser 0.4.2 → 0.4.5

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

@@ -136,20 +136,42 @@ const SETTINGS_WHEN_UNREADABLE: BrowserSettings = {
  * @returns a valid channel.
  */
 function resolveChannel(value: unknown): BrowserChannel {
-  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
     ? value
     : DEFAULT_SETTINGS.browser.channel
 }
 
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  const floored = Math.floor(value)
+  // A fractional value below 1 floors to 0, and 0 is not "very few" in either place these are
+  // used: as a history entry cap it means `slice(len - 0)`, i.e. keep nothing, so a hand-typed
+  // `0.5` silently wiped the history file on the next rewrite. Anything that survives the
+  // floor has to still be a usable limit.
+  return floored > 0 ? floored : fallback
 }
 
 /** Read one nested section of an unknown document, or an empty object. */
-function section(source: Record<string, unknown>, key: string): Record<string, unknown> {
+/**
+ * Read one section of the document, distinguishing ABSENT from UNREADABLE.
+ *
+ * Absent (the key is not there at all) is a document written before the section existed, and
+ * the defaults apply — that is the documented behaviour. Present-but-not-an-object
+ * (`"actions": false`, `null` from a truncated write, a stray string) is a document this code
+ * cannot read, and returning `{}` for it made every gate inside look absent, so each one took
+ * its permissive default. A whole section mistyped is exactly the shape a careless hand edit
+ * produces, and it opened every capability the section was there to bound.
+ * @param source - the parsed document.
+ * @param key - the section name.
+ * @returns the section, or undefined when it is present but not an object.
+ */
+function section(source: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
   const value = source[key]
-  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {}
+  if (value === undefined) return {}
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
 }
 
 /**
@@ -168,25 +190,42 @@ export function resolveSettings(raw: unknown): BrowserSettings {
   const credentials = section(source, 'credentials')
   const browser = section(source, 'browser')
   const actions = section(source, 'actions')
+  // A section that is present but unreadable refuses its gates rather than defaulting them
+  // open. The rest of a broken section keeps its defaults: refusing history or presentation
+  // would punish the user for a bad file without protecting anything.
+  const credentialsUsable = credentials ?? {}
+  const actionsUsable = actions ?? {}
   return {
     history: {
-      enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
-      maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
-      maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+      enabled: bool(history?.enabled, DEFAULT_SETTINGS.history.enabled),
+      maxEntries: count(history?.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+      maxAgeDays: count(history?.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
     },
-    cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+    cookies: { persist: bool(cookies?.persist, DEFAULT_SETTINGS.cookies.persist) },
     ui: {
-      autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
-      closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
-      virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+      autoExpandOnce: bool(ui?.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+      closeWithSession: bool(ui?.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+      virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+    },
+    vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+    browser: { channel: resolveChannel(browser?.channel) },
+    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.
+      allowRead: credentials === undefined
+        ? false
+        : gate(credentialsUsable.allowRead, DEFAULT_SETTINGS.credentials.allowRead),
     },
-    vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-    browser: { channel: resolveChannel(browser.channel) },
-    credentials: { allowRead: gate(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
     actions: {
-      allowExecute: gate(actions.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
-      allowDownload: gate(actions.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
-      allowCredentialWrite: gate(actions.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
+      allowExecute: actions === undefined
+        ? false
+        : gate(actionsUsable.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
+      allowDownload: actions === undefined
+        ? false
+        : gate(actionsUsable.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
+      allowCredentialWrite: actions === undefined
+        ? false
+        : gate(actionsUsable.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
     },
   }
 }

package/src/browser-electron/system-browser.ts

@@ -39,6 +39,23 @@ import { join } from 'node:path'
  */
 const EXIT_GRACE_MS = 3_000
 
+/**
+ * Ceiling on one attempt to ask a discovered CDP port who it is.
+ *
+ * The launch loop below polls: it reads `DevToolsActivePort`, tries `/json/version` on the port
+ * inside it, and waits 250 ms between attempts under a 30 s deadline. An unbounded fetch can
+ * park inside one iteration for the whole budget, so a bound is needed — but it has to be
+ * small enough that the loop still behaves like a loop.
+ *
+ * The usual case is NOT a slow answer, it is NO answer: a browser that has written the file but
+ * is not listening yet refuses the connection instantly, and that immediacy is what lets the
+ * loop spin. Any timeout added here is paid on every iteration in which the port is not ready,
+ * so an earlier attempt at this used 2000 ms — eight times the poll interval — and cut the
+ * attempts available in the budget from roughly 120 to 15. This value is the same size as the
+ * interval, so a worst-case iteration costs 500 ms and the budget still affords ~60 attempts.
+ */
+const PORT_PROBE_MS = 250
+
 /**
  * Starts a browser process and returns a handle to it.
  *
@@ -58,7 +75,7 @@ import { randomUUID } from 'node:crypto'
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
 
 /** Which browser the user asked for. */
-export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto'
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar'
 
 /** A resolved browser installation. */
 export interface DetectedBrowser {
@@ -475,6 +492,19 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     }
   }
 
+  /**
+   * Forget which browser issued what, after that browser is gone.
+   *
+   * The two maps must move together: `views` maps a view id to a session id and `sessions`
+   * maps a session id to a target id, so clearing one alone leaves a mapping the next command
+   * will act on. Every path that abandons a browser calls this rather than spelling the pair
+   * out — four separate copies is how the third one came to be missing.
+   */
+  private forgetBrowserState(): void {
+    this.views.clear()
+    this.sessions.clear()
+  }
+
   private async ensureClient(): Promise<CdpClient> {
     // A disposed host must never start a browser: doing so would spawn a process
     // nobody owns and nobody will kill.
@@ -501,8 +531,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // child left to kill: the process already exited, its exit listener already set
       // `this.child` to undefined, so start() skips that branch and publishes a new browser
       // while the views still point at the dead one. That is the state that never recovers.
-      this.views.clear()
-      this.sessions.clear()
+      this.forgetBrowserState()
     }
     // Concurrent first calls share one startup rather than racing two browsers.
     this.starting ??= this.start().finally(() => { this.starting = undefined })
@@ -545,8 +574,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // heard of them — the "Session with given id not found" loop, which never clears.
       this.client?.close()
       this.client = undefined
-      this.views.clear()
-      this.sessions.clear()
+      this.forgetBrowserState()
 
       // Wait for it to actually die. kill() only sends the signal: on Windows it is
       // TerminateProcess, which is asynchronous, and the browser may still hold this profile's
@@ -607,8 +635,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // The pages this client opened belong to the process that just died; keeping their
       // session ids means every later command is sent to a browser that never issued them.
       // Clearing these is what makes the restart usable rather than merely alive.
-      this.views.clear()
-      this.sessions.clear()
+      this.forgetBrowserState()
     })
     const portFile = join(this.profileDir, 'DevToolsActivePort')
     /**
@@ -645,15 +672,29 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       if (this.disposed) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'released'; break }
       if (launchError !== undefined) { if (this.child === child) this.child = undefined; stopped = 'launch-failed'; break }
       if (Date.now() > deadline) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'timeout'; break }
-      if (child.exitCode !== null) { if (this.child === child) this.child = undefined; stopped = 'exited'; break }
+      // signalCode too: a browser killed by a signal never sets exitCode, so checking exitCode
+      // alone made a killed browser look alive and the launch run out its full 30s deadline
+      // before reporting "did not expose CDP" — a timeout for something that died at once.
+      // The sibling check on the release path already looked at both.
+      if (child.exitCode !== null || child.signalCode !== null) { if (this.child === child) this.child = undefined; stopped = 'exited'; break }
       // Only a port THIS launch wrote: reading whatever file happened to be there is how a
           // restart could adopt the previous browser, or any process now holding that port.
           const port = freshPort()
           if (port !== undefined) {
         try {
-            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json() as { webSocketDebuggerUrl?: string }
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+              // Bounded: an unanswered loopback request would otherwise park inside this
+              // iteration for the rest of the budget, and the deadline above is only re-checked
+              // between iterations. Deliberately no larger than the 250 ms sleep — see
+              // PORT_PROBE_MS.
+              signal: AbortSignal.timeout(PORT_PROBE_MS),
+            })).json() as { webSocketDebuggerUrl?: string }
             if (typeof version.webSocketDebuggerUrl === 'string') {
               const client = new CdpClient(version.webSocketDebuggerUrl)
+              // `whenReady` has its own 30 s ceiling, and it is reached only after the port
+              // answered above — so the browser is listening and this is a handshake, not a
+              // discovery. A handshake that outlives the launch is reported as the timeout it
+              // is, by the same deadline that governs everything else here.
               await client.whenReady()
               // Still wanted? A dispose() during the handshake has already killed the
               // process, so publishing the client would leave a dangling connection.
@@ -675,15 +716,23 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`)
     }
     if (stopped === 'exited') {
-      // Exit code 0 is the whole story here: the browser decided to hand the request to an
-      // instance that already owns this profile directory and quit, rather than failing. That is
-      // what a leftover browser from a previous run (or a second DSH on the same profile) looks
-      // like. "Check that the path is a runnable browser" pointed at the one cause that is almost
-      // never it, and sent people looking for a broken install that was not there.
+      // Only exit code 0 is the hand-off story. A non-zero code or a signal means the browser
+      // died on its own — a crash, a missing library, a sandbox refusal — and asserting the
+      // profile story for those sent people looking for a leftover process that was not there,
+      // which is the same mistake this message was written to correct, pointing the other way.
+      const code = child.exitCode
+      const signal = child.signalCode
+      const clean = code === 0 && signal === null
       throw new Error(
-        `dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}). `
-        + 'That exit code means it handed the request to an instance already using this profile '
-        + 'directory and quit — look for a leftover browser process from an earlier run, then retry.',
+        clean
+          ? `dsh-builtin-browser: ${target} exited immediately after launch (exit code 0). `
+            + 'That means it handed the request to an instance already using this profile '
+            + 'directory and quit — look for a leftover browser process from an earlier run, then retry.'
+          : `dsh-builtin-browser: ${target} exited immediately after launch `
+            + `(${signal !== null ? `killed by ${signal}` : `exit code ${String(code)}`}), so it did not `
+            + 'hand the request anywhere — the browser failed to start rather than deferring to another '
+            + 'instance. Check that it can run at all: run it by hand, and look for a crash or a missing '
+            + 'dependency rather than a leftover process.',
       )
     }
     if (stopped === 'released') {
@@ -750,7 +799,17 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
           if (!client.isAlive()) {
             // Only THIS call's client. Under concurrency the field may already hold a
             // connection another call just published, and closing that would kill a healthy one.
-            if (this.client === client) this.client = undefined
+            if (this.client === client) {
+              this.client = undefined
+              // This is the third of the three paths that discard a client, and it was the one
+              // that did not retire what the client had issued. A view holding a session id
+              // from the dead browser kept handing it to the replacement, which had never heard
+              // of it: every page command then failed with "Session with given id not found"
+              // and no later call could clear it, because the cached session was returned
+              // unconditionally. Gated on the same identity check as the field itself, so a
+              // concurrent call that just published a healthy client does not lose its maps.
+              this.forgetBrowserState()
+            }
             client.close()
           }
           throw error
@@ -778,11 +837,32 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** Nothing to show: the browser owns its own windows. */
   showView(): void {}
 
-  /** Same as {@link showView}. */
-  async presentView(): Promise<void> {}
+  /**
+   * Bring the target's page to the front, then report success.
+   *
+   * The comment on `focus` below used to say this was impossible — that raising the page needs
+   * `Page.bringToFront` on a target session, which is a view-level concern the host cannot
+   * reach. The handle this method is handed IS that view, and it can send commands, so the
+   * capability was here all along; it just was not used. Without it `presentView` was an empty
+   * async method, so the provider's whole presentation barrier — the one that stops
+   * `Input.*` from being silently dropped for a view with no display surface, and reports
+   * `BROWSER_VIEW_NOT_PRESENTED` when it cannot present — never ran on this carrier.
+   *
+   * A failure is swallowed rather than propagated: a real Chrome window that refuses to come
+   * forward is not a reason to refuse the click that follows. The barrier exists to order the
+   * two, and the order is honoured either way.
+   * @param handle - the view to present.
+   */
+  async presentView(handle: ElectronViewHandle): Promise<void> {
+    try {
+      await handle.sendCommand('Page.bringToFront')
+    } catch {
+      // Backgrounded, minimised, or a target that went away between the snapshot and the
+      // click. The command that called this will report its own failure if the page is gone.
+    }
+  }
+
 
-  /** The browser owns window grouping. */
-  groupView(): void {}
 
   /**
    * Best effort at bringing the browser's window forward.
@@ -800,11 +880,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     try { this.child?.kill('SIGCONT') } catch { /* Windows has no SIGCONT; nothing to do */ }
   }
 
-  /** The browser reports its own window lifecycle. */
-  onUserAction(): void {}
 
-  /** The browser reports its own window lifecycle. */
-  onViewClosed(): void {}
 
   /**
    * Close the browser we launched, if we ever launched one.
@@ -816,8 +892,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
-    this.views.clear()
-    this.sessions.clear()
+    this.forgetBrowserState()
     this.client?.close()
     try { this.child?.kill() } catch { /* already gone */ }
     // And anything that ignored an earlier kill. They hold this profile, so leaving them
@@ -854,6 +929,21 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * a second copy of that rule.
    */
   private async ensureSession(viewId: string): Promise<string> {
+    // One target per view, even when two commands arrive together. The two CDP round trips
+    // below are awaits, so without this a second caller entering during the first's flight saw
+    // no session in `views` and created its own target — leaving an orphan page that nothing
+    // closes, because only the last id survives in the map.
+    const inFlight = this.sessionBuilding.get(viewId)
+    if (inFlight !== undefined) return await inFlight
+    const building = this.buildSession(viewId).finally(() => {
+      this.sessionBuilding.delete(viewId)
+    })
+    this.sessionBuilding.set(viewId, building)
+    return await building
+  }
+
+  /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
+  private async buildSession(viewId: string): Promise<string> {
     const client = await this.ensureClient()
     const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
     const targetId = created?.targetId
@@ -867,6 +957,9 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     return sessionId
   }
 
+  /** Views whose session is being created right now, so a second caller waits for the first. */
+  private readonly sessionBuilding = new Map<string, Promise<string>>()
+
   /** sessionId -> targetId, so a destroyed view can close the right page. */
   private readonly sessions = new Map<string, string>()
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * dsh-builtin-browser plugin entry: aggregates the shared-browser capability
  * pieces. The cordis.patch.yml rows reference subpath exports:
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
@@ -14,6 +14,7 @@
  */
 
 /** Plugin identity for the root row (the composition surface is the subpath rows). */
+
 export const name = 'dsh-builtin-browser'
 
 /**
@@ -24,9 +25,9 @@ export const name = 'dsh-builtin-browser'
  * never reaches the browser (the plugin works, its client half is invisible).
  */
 export function apply(): void {
-  // Intentionally empty: see the module comment above.
 }
 
+
 export { BrowserError } from './browser/types.js'
 export type {
   BrowserA11yNode,

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

@@ -0,0 +1,167 @@
+/**
+ * The element and node field sets, declared once.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * The same field set used to be written out in four places: the page script produced an
+ * object, `types.ts` declared its shape, a tool's `execute` rebuilt it as an explicit list,
+ * 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,
+ *     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
+ *     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.
+ *
+ * A hand-written allow-list is invisible to the type checker (it is an object literal) and to
+ * the tests (nothing ran a tool). The fix is not a careful list; it is one list. Both the
+ * schema fragment and the projection are derived from the tables below, so a field cannot be
+ * present in one and absent from the other.
+ *
+ * The schema is the dangerous half: `additionalProperties: false` means a field the schema
+ * does NOT declare causes the ENTIRE result to be rejected at run time, while a field the
+ * projection forgets is silently dropped. One table cannot get either wrong on its own.
+ */
+
+/** A single declared field: how the schema describes it, and whether callers always get it. */
+interface FieldSpec {
+  /** The JSON Schema fragment for this property. */
+  readonly schema: Record<string, unknown>
+  /** True when the value is always present, so both the schema and the result promise it. */
+  readonly required?: boolean
+}
+
+/**
+ * The fields of one entry in `browser_snapshot` / `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.
+ */
+const ELEMENT_FIELDS = {
+  ref: { schema: { type: 'number' }, required: true },
+  kind: { schema: { type: 'string' }, required: true },
+  label: { schema: { type: 'string' }, required: true },
+  selector: { schema: { type: 'string' } },
+  x: { schema: { type: 'number' }, required: true },
+  y: { schema: { type: 'number' }, required: true },
+  frame: { schema: { type: 'boolean' } },
+} as const satisfies Record<string, FieldSpec>
+
+/**
+ * The fields of one entry in `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.
+ */
+const NODE_FIELDS = {
+  ref: { schema: { type: 'number' }, required: true },
+  role: { schema: { type: 'string' }, required: true },
+  name: { schema: { type: 'string' }, required: true },
+  value: { schema: { type: 'string' } },
+  states: { schema: { type: 'array', items: { type: 'string' } }, required: true },
+  depth: { schema: { type: 'number' }, required: true },
+  tag: { schema: { type: 'string' }, required: true },
+  // Always present: the provider derives it for every node and yields an empty string when the
+  // element has neither an id nor a name. Declaring it optional described a shape the provider
+  // never produced, and the type said required — the same disagreement, one level down.
+  selector: { schema: { type: 'string' }, required: true },
+  x: { schema: { type: 'number' }, required: true },
+  y: { schema: { type: 'number' }, required: true },
+  frame: { schema: { type: 'boolean' } },
+} as const satisfies Record<string, FieldSpec>
+
+/**
+ * Copy the declared fields out of a source value.
+ *
+ * Reads the table rather than naming fields, so anything the provider produces that the table
+ * declares is carried through, and anything the table does not declare is left out — which is
+ * what keeps the result and the schema in agreement in both directions.
+ * @param fields - the field table to project through.
+ * @param source - the value the provider produced.
+ * @returns a new object holding exactly the declared fields that are present.
+ */
+function project(fields: Record<string, FieldSpec>, source: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const name of Object.keys(fields)) {
+    const value = source[name]
+    if (value !== undefined && value !== null) out[name] = value
+  }
+  return out
+}
+
+/**
+ * The `elements` item schema for browser_snapshot and 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
+ * it. The field table above remains the single source of truth: `tests/element-fields.test.mjs`
+ * asserts that these properties and `projectElement`'s output are exactly the table's keys, so
+ * the two cannot drift even though one is typed by hand.
+ */
+export const ELEMENT_ITEM_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    ref: { type: 'number', required: true },
+    kind: { type: 'string', required: true },
+    label: { type: 'string', required: true },
+    selector: { type: 'string' },
+    x: { type: 'number', required: true },
+    y: { type: 'number', required: true },
+    frame: { type: 'boolean' },
+  },
+} as const
+
+/**
+ * The `nodes` item schema for browser_a11y.
+ *
+ * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
+ * test.
+ */
+export const NODE_ITEM_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    ref: { type: 'number', required: true },
+    role: { type: 'string', required: true },
+    name: { type: 'string', required: true },
+    value: { type: 'string' },
+    states: { type: 'array', required: true, items: { type: 'string' } },
+    depth: { type: 'number', required: true },
+    tag: { type: 'string', required: true },
+    selector: { type: 'string', required: true },
+    x: { type: 'number', required: true },
+    y: { type: 'number', required: true },
+    frame: { type: 'boolean' },
+  },
+} as const
+
+/**
+ * Project one snapshot element into the shape the schema declares.
+ *
+ * Generic in the source type so the caller keeps the precise shape `defineTool` inferred from
+ * the schema: the projection decides which fields survive at run time, and the field table is
+ * what guarantees that set matches the schema. Widening the return type here would only move
+ * the mismatch to the call site.
+ * @param element - the element as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export function projectElement<T extends object>(element: T): T {
+  return project(ELEMENT_FIELDS as Record<string, FieldSpec>, element as Record<string, unknown>) as T
+}
+
+/**
+ * Project one accessibility node into the shape the schema declares.
+ * @param node - the node as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export function projectNode<T extends object>(node: T): T {
+  return project(NODE_FIELDS as Record<string, FieldSpec>, node as Record<string, unknown>) as T
+}
+
+/** The field names each table declares, for tests that check the two stay in step. */
+export const DECLARED_FIELDS = {
+  element: Object.keys(ELEMENT_FIELDS),
+  node: Object.keys(NODE_FIELDS),
+} as const