feat: Introduce Vibium-tracing into the WebdriverIO ecosystem

[Winify]

Proposed changes

Adds Vibium-compatible trace recording for both browser and mobile (iOS/Android) sessions.

When a session is started with trace: true, every tool call is captured as a structured trace event: before/after timestamps, action class and method, parameters, and screenshots.

Its exported to a .zip file on session close. The zip is playable directly in the Vibium player (player.vibium.dev) with a full action timeline and screenshot filmstrip.

Key design decisions:

• Pre-action screenshots serve as both the settle window for animations and the "result" frame for the preceding action. Frames are timestamped at the previous action's endTime so the player associates each screenshot with the action that produced it, not the one about to fire.
• Mobile sessions use chromium as the browserName (Vibium is Playwright-derived) and platform-appropriate viewport defaults (390×844 iOS, 412×915 Android), with device name and OS version in the trace title.
• Before events emit bare method names (click, fill, navigate) rather than namespaced ones, which is what the player expects for correct tooltip rendering.
• A show-trace CLI entry point is bundled separately for serving and previewing trace zips locally without leaving the terminal.

Types of changes

• Polish (an improvement for an existing feature)
• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (improvements to the project's docs)
• Specification changes (updates to WebDriver command specifications)
• Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

• I have squashed commits that belong together
• I have tested with Claude Desktop (or another MCP-compatible client)
• I have read the CONTRIBUTING doc
• I have added the necessary documentation for new/changed tools (if appropriate)
• I have added proper type definitions for new commands (if appropriate)

Further comments

Reviewers: @webdriverio/project-committers

[greptile-apps]

Greptile Summary

This PR introduces Vibium-compatible trace recording for both browser and mobile (iOS/Android) WebdriverIO sessions. When a session is started with trace: true, every instrumented tool call is captured as a structured Playwright-compatible trace event and exported as a .zip on session close, playable at player.vibium.dev.

• New src/trace/ module provides withTrace, recorder, state, tool-mapping, types, and zip-writer — plus a src/show-trace.ts CLI entry point for serving and previewing local trace zips.
• src/session/lifecycle.ts gains a finalizeTrace helper called on both normal close and orphaned-session cleanup, correctly passing the explicit browser reference in both paths.
• src/server.ts composes the new instrument helper (withTrace + withRecording) for all mapped tools; start_session intentionally remains outside this wrapper per the design notes.

Confidence Score: 5/5

Safe to merge; the new trace recording path is well-isolated, correctly cleans up session state in all exit branches, and does not affect existing tool execution when tracing is disabled.

All three session-close paths correctly pass an explicit browser reference rather than relying on global session state. The tracing infrastructure is opt-in behind a trace flag, so existing sessions are completely unaffected. All findings are non-blocking quality improvements.

src/trace/zip-writer.ts (trailing newline), src/show-trace.ts (exec error handling and CORS preflight headers)

Important Files Changed

Filename	Overview
src/trace/recorder.ts	Core tracing wrapper: withTrace instruments tool callbacks with before/after events and pre-action screenshots. Screenshot fallback via getBrowser() is safe in withTrace, and screenshotChain correctly serializes the final screenshot in finalizeTrace.
src/trace/zip-writer.ts	Builds Playwright-compatible trace zip; NDJSON events joined without a trailing newline, which may cause the last event to be dropped by line-buffered parsers.
src/show-trace.ts	Local dev CLI that serves a trace zip on localhost and opens the Vibium player. exec errors are silently swallowed and the CORS preflight response omits Access-Control-Allow-Headers.
src/session/lifecycle.ts	Adds finalizeTrace called in both closeSession and orphaned-session cleanup; both paths correctly pass the explicit browser reference rather than relying on getBrowser().
src/trace/state.ts	Module-level traceSessions Map with create/get/delete helpers; monotonic time via process.hrtime.bigint(). Clean and straightforward.
src/trace/tool-mapping.ts	Maps tool names to Playwright trace action classes/methods. The start_session entry is unreachable (flagged in a prior review thread).
src/tools/session.tool.ts	Adds trace parameter to start_session; correctly calls startTrace after registerSession and records initial navigation for all three session modes.
src/trace/types.ts	Well-typed definitions for all four Playwright-compatible trace event shapes plus TraceSession state. No issues found.
src/server.ts	Introduces the instrument helper composing withTrace over withRecording; all mapped tools upgraded consistently.

Sequence Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Server as server.ts
    participant WTrace as withTrace
    participant Tool as Tool Callback
    participant TState as TraceSession
    participant Browser as WebdriverIO.Browser

    Client->>Server: start_session(trace:true)
    Server->>Tool: startSessionTool
    Tool->>TState: createTraceSession
    Tool->>Browser: url(navigationUrl)
    Tool->>TState: recordInitialNavigation

    loop Each instrumented tool call
        Client->>Server: tool call
        Server->>WTrace: instrument(name, cb)(params)
        WTrace->>Browser: takeScreenshot
        WTrace->>TState: push screencast-frame + before
        WTrace->>Tool: callback(params, extra)
        Tool-->>WTrace: result
        WTrace->>TState: push after event
    end

    Client->>Server: close_session
    Server->>Browser: takeScreenshot (final)
    Server->>TState: await screenshotChain
    Server->>Server: buildTraceZip + writeFileSync
    Server->>TState: deleteTraceSession

Loading

_{Reviews (2): Last reviewed commit: "fix(trace): Ensure `finalizeTrace` handl..." | Re-trigger Greptile}