Release Notes - v0.9.0¶

Vibium feature parity release with element mapping (@refs) for AI agents and clock manipulation tools.

Highlights¶

Element Mapping (@refs) for AI Agents

Human-friendly element references that make browser automation more intuitive for AI agents. Instead of complex CSS selectors, agents can use simple refs like @e1, @e2, etc.

# Map all interactive elements on the page
w3pilot map

# Output:
# @e1 [button] "Submit Form"
# @e2 [button] "Cancel"
# @e3 [input]  "Username" (placeholder)
# @e4 [input]  "Password" (placeholder)
# @e5 [a]      "Forgot password?"

# Use refs in subsequent commands
w3pilot click @e1
w3pilot fill @e3 "john@example.com"

Clock Manipulation Tools

Control time in the browser for testing time-dependent functionality. Install fake timers that replace Date, setTimeout, setInterval, and other time-related APIs.

# Via MCP tools
clock_install       # Install fake timers
clock_set_time      # Set fixed time
clock_fast_forward  # Advance time (no timers)
clock_run_for       # Advance time (fire timers)
clock_pause_at      # Pause at timestamp
clock_resume        # Resume from paused
clock_set_timezone  # Set browser timezone

Diff Mapping for Change Detection

Compare page elements before and after actions to detect what changed:

w3pilot map                  # Store initial refs
w3pilot click @e1            # Perform action
w3pilot map diff             # See what changed

# Output:
# ADDED (1):
#   + @e6 [div] "Success message"
# REMOVED (1):
#   - @e2 [button] "Submit"

New Features¶

Element Mapping SDK¶

New types and functions for element mapping:

// Map interactive elements
refs, err := pilot.MapElements(ctx, &w3pilot.MapOptions{
    IncludeHidden: false,
    MaxElements:   100,
    Scope:         "#main-content",
})

// Each ref contains:
// - Ref: "@e1", "@e2", etc.
// - Tag: "button", "input", "a", etc.
// - Role: ARIA role if present
// - Text: Visible text content
// - Label: Associated label text
// - Placeholder: Input placeholder
// - Type: Input type (text, password, etc.)
// - Selector: CSS selector for the element
// - Visible: Whether element is visible
// - Enabled: Whether element is enabled

// Compare refs to detect changes
diff := w3pilot.DiffRefs(before, after)
fmt.Printf("Added: %d, Removed: %d, Changed: %d\n",
    diff.Summary.Added, diff.Summary.Removed, diff.Summary.Changed)

Ref Storage and Resolution¶

Thread-safe ref storage with resolution:

// Store refs
store := w3pilot.NewRefStore()
store.Store(refs)

// Check if string is a ref
if w3pilot.IsRef("@e1") {
    // Resolve ref to selector
    selector, err := store.ResolveRef("@e1")
}

// Get specific ref
ref, ok := store.Get("@e1")

// Clear all refs
store.Clear()

CLI Map Commands¶

Command	Description
`w3pilot map`	Map interactive elements to @refs
`w3pilot map list`	List stored refs without re-scanning
`w3pilot map get @e1`	Get details about a specific ref
`w3pilot map clear`	Clear stored refs
`w3pilot map diff`	Compare current page vs previous mapping

CLI @ref Resolution¶

Element commands now accept @refs in place of CSS selectors:

# Using refs
w3pilot click @e1
w3pilot fill @e3 "value"

# Still works with selectors
w3pilot click "#submit"
w3pilot fill "#email" "user@example.com"

MCP Element Mapping Tools¶

Tool	Description
`page_map`	Map interactive elements to @refs
`page_map_get`	Get details about a specific ref
`page_map_clear`	Clear stored refs
`page_map_diff`	Compare current vs previous mapping

MCP Clock Tools¶

Tool	Description
`clock_install`	Install fake timers (Date, setTimeout, etc.)
`clock_set_time`	Set fixed time for Date.now()
`clock_fast_forward`	Advance time without firing timers
`clock_run_for`	Advance time and fire pending timers
`clock_pause_at`	Pause time at specific timestamp
`clock_resume`	Resume from paused state
`clock_set_timezone`	Set browser timezone (IANA names)

API Additions¶

Element Mapping Types¶

Type	Description
`ElementRef`	Element reference with ref, tag, text, selector, etc.
`MapOptions`	Options for MapElements (scope, hidden, max)
`RefStore`	Thread-safe storage for element refs
`RefDiff`	Diff result with added, removed, changed elements
`RefChange`	Single element change (before/after)
`RefDiffSummary`	Summary counts of changes

Element Mapping Functions¶

Function	Description
`Pilot.MapElements(ctx, opts)`	Map interactive elements on page
`NewRefStore()`	Create new ref store
`IsRef(s)`	Check if string is a @ref
`DiffRefs(before, after)`	Compare two element mappings
`ElementRef.FormatRef()`	Format ref for display

RefStore Methods¶

Method	Description
`Store(refs)`	Store refs
`Get(ref)`	Get ref by string
`ResolveRef(s)`	Resolve @ref to selector
`Clear()`	Clear all refs

MCP Tool Count¶

This release adds 11 new MCP tools, bringing the total to 180 tools across 25 namespaces.

Namespace	Tools Added
`page_`	+4 (map, map_get, map_clear, map_diff)
`clock_`	+7 (new namespace)

Breaking Changes¶

None. All changes are backwards compatible.

Installation¶

go get github.com/plexusone/w3pilot@v0.9.0