Niklhut/browser run accessibility tree types

[niklhut]

Summary

Adds the missing accessibilityTree quick action to the BrowserRun binding types, and corrects the snapshot action's response shape.

The accessibilityTree quick action is live and documented, but has no overload in types/defines/browser-run.d.ts, so the binding snippet published on the docs page does not compile:

// Argument of type '"accessibilityTree"' is not assignable to parameter of type '"markdown"'
await env.BROWSER.quickAction("accessibilityTree", { url });

quickAction is declared as explicit overloads, one per action, so a missing action surfaces as a mismatch against whichever overload happens to be last. The "markdown" in the message is incidental — the action is simply absent from the overload set.

Changes

accessibilityTree overload. Adds the overload plus three supporting types:

Type	Notes
BrowserRunAccessibilityTreeOptions	BrowserRunCommonOptions plus interestingOnly? and root?
BrowserRunAccessibilityTreeSuccessResponse	accessibilityTree is nullable — see below
BrowserRunSerializedAXNode	Recursive ARIA node, 26 fields; role required, all others optional

Two API behaviours worth noting in review:

• A root selector matching no element returns accessibilityTree: null with HTTP 200, so the field is typed as nullable rather than optional.
• interestingOnly has no static default. The server computes interestingOnly ?? (root ? false : true), so no default is documented on the field.

snapshot response shape. The existing declaration omitted formats and typed result.content / result.screenshot as always present. Per the API, formats selects which keys appear, and result plus every field in it is optional. Adds BrowserRunSnapshotFormat ("content" | "screenshot" | "markdown" | "accessibilityTree") and makes the result fields optional.

The server requires at least two distinct formats and rejects a single-format request, directing callers to that format's dedicated action. That constraint is documented in JSDoc rather than encoded in the type, matching how scrape.elements handles its own minimum. A tuple type would enforce length while the server actually checks distinctness, so it would give false confidence and break dynamically built formats arrays.

Notes

• Types-only. src/cloudflare/internal/br-api.ts wraps fetcher.fetch() and has no per-action code, so there is no runtime change.
• The action name is camelCase accessibilityTree, matching POST /v1/accessibilityTree. Only the SDK method is kebab-case.
• Generated snapshots regenerated with just generate-types; no unrelated churn.

Validation

• BrowserRunSerializedAXNode mirrors the server's SerializedAxNodeSchema field for field, including role as the only required field and value as a string | number union.
• tsc --strict against the defines, with @ts-expect-error assertions covering unknown option keys, wrong option types, and a missing url. Verified the assertions actually bite by making one case valid and confirming TS2578.
• Cross-checked the declared node shape against live API responses; no undeclared fields returned.
• Confirmed formats: ["markdown", "accessibilityTree"] returns only those keys, and that a root selector matching nothing yields accessibilityTree: null at HTTP 200.
• Built these types into a real Worker project via wrangler types and exercised quickAction("accessibilityTree", { url }) through a deployed binding.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[niklhut]

I have read the CLA Document and I hereby sign the CLA