[v4]: add index to selector schemas

Merged
SE
8mo ago
+33-0

why

  • selectors can resolve to multiple nodes
  • we need to give the user freedom to optionally provide an index, indicating the desired element if multiple are found

what changed

  • added an optional index field to XPathSelectorSchema, CssSelectorSchema & TextSelectorSchema
  • note: CoordinateSelectorSchema remains unchanged, since coordinates are inherently specific

selector schema before:

Screenshot 2026-03-19 at 4 31 50 PM

selector schema after:

Screenshot 2026-03-19 at 4 33 32 PM

test plan

  • added new test case in packages/server-v4/src/schemas/v4/page.ts

Summary by cubic

Adds an optional non-negative idx to XPath, CSS, and text selectors so callers can target a specific element when a selector matches multiple nodes. Updates the v4 schema and OpenAPI spec without breaking existing clients.

  • New Features
    • Added optional non-negative idx to XPathSelectorSchema, CssSelectorSchema, and TextSelectorSchema.
    • Left CoordinateSelectorSchema unchanged.
    • Updated openapi.v4.yaml with the new idx field and examples.
    • Expanded integration tests to cover css, xpath, and text selectors with idx.