Host the trace player as a static page with no backend

Opening a trace zip needed the DevTools package installed and `show-trace`
run against it, which is a lot to ask of whoever the zip is sent to. The app
now builds a hosted mode (`vite build --mode hosted`) that opens a zip the
viewer drops or picks and parses it in the browser tab, and `vercel.json`
deploys it the way benchmark.webdriver.io is deployed.

A trace records everything the run showed or typed, so the zip never leaves
the tab: no upload, the trace is not written to browser storage, and the CSP
allows network calls only to the player's own origin. It does allow a
cross-origin `<base>`, styles, fonts and images, which the DOM replay needs
to load the recorded site's own stylesheets.

The reader had to become browser-safe: the disk read moved to
`read-trace-zip.ts`, source paths are hashed with a pure SHA-1 (native
`sha1Hex` stays for resource bytes, ~30x faster), and screenshots are
base64-encoded without `Buffer`. A test runs the reader on a recorded zip
with `Buffer` removed, since an import walk cannot see a global. The ESLint
rule barring the app from `trace` now allows `trace-reader` alone.

Refs #494

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: vishnuv688

.changeset/hosted-trace-player.md

@@ -0,0 +1,5 @@
+---
+'@wdio/devtools-app': minor
+---
+
+The trace player can now run as a static web page with no backend: built with `--mode hosted`, it opens a trace `.zip` the viewer drops on the page or picks, parsing it in the browser tab without uploading it or writing it to browser storage. This is the build trace.webdriver.io serves. The live dashboard is unchanged; the zip reader it does not use is loaded only when a file is opened.

.gitignore

@@ -10,6 +10,7 @@ lerna-debug.log*
 node_modules
 dist
 dist-ssr
+dist-hosted
 .tsup
 *.local
 
@@ -35,6 +36,7 @@ __pycache__/
 /*.json
 !/vitest.config.ts
 !/tsconfig.dts.json
+!/vercel.json
 *.tgz
 examples/wdio/wdio-*.json
 examples/wdio/wdio-*.webm

ARCHITECTURE.md

@@ -67,9 +67,9 @@ Contains:
 - `buildImageFrameSnapshots` / `upsertRichestSnapshot` / `buildDenseScreencast` / `thinScreencastFrames` — filmstrip and per-action frame snapshots.
 - `buildMutationsNdjson` / `reattributeDomAnchors` — the DOM mutation stream and its anchor repositioning.
 - `buildConsoleEvents`, `networkRequestToHar`, `buildSourceResources` / `sourceResourceName` / `callSourceToStack`, `generateTranscript`, `sha1Hex`.
-- `parseTraceZip` / `readTraceZip` (`trace-reader.ts` and its `trace-reader-*` siblings) — the reverse direction: a `trace.zip`, ours or a foreign one, back into the `TracePlayerData` the player renders. Imported by subpath (`@wdio/devtools-trace/trace-reader`) and kept out of the package index, so adapters that reach `trace` through `core` never inline it.
+- `parseTraceZip` (`trace-reader.ts` and its `trace-reader-*` siblings) — the reverse direction: a `trace.zip`, ours or a foreign one, back into the `TracePlayerData` the player renders. Imported by subpath (`@wdio/devtools-trace/trace-reader`) and kept out of the package index, so adapters that reach `trace` through `core` never inline it. It reaches no Node built-in, because the hosted player runs it in the browser (`tests/trace-reader-browser-safe.test.ts` walks its imports); the disk read is `readTraceZip` in `read-trace-zip.ts`, and source paths are hashed with the pure `portableSha1Hex` so the reader needs no `node:crypto`; resource bytes keep native `sha1Hex`, ~30x faster.
 
-Imports from: `shared`. Imported by: `core` (which re-exports it, so adapters reach it unchanged) and `backend`.
+Imports from: `shared`. Imported by: `core` (which re-exports it, so adapters reach it unchanged), `backend`, and `app`, which may import `trace-reader` alone (ESLint enforces it).
 
 ### `packages/core`
 

CLAUDE.md

@@ -31,6 +31,7 @@ Run from repo root unless noted.
 | `pnpm dev` | Run all packages in parallel dev mode. |
 | `pnpm smoke:fixtures [--port N]` | Serve the local fixture site the desktop examples drive (a copy of the-internet's login flow: `/`, `/login`, `/secure`, `/logout`; default `http://127.0.0.1:4567`). Every desktop login example reads `DEVTOOLS_EXAMPLE_BASE_URL` (trailing slash ignored); unset, they drive the public site. |
 | `pnpm smoke:assert --expect <name> [--exit-code N] [--log file] <zip-or-dir>...` | Check trace zips against `packages/conformance/smoke/expectations/<name>.json`: the listed rows under each test's own tracing group (or the whole run for an entry with `scope: "run"` and a `reason`), an error row on each deliberately failing test, a retried test's attempt count with its other checks read from its final attempt alone (`attempts`), title fragments such as a failed wait's condition, a call site on every row of a per-test entry (at least one for a run-scoped entry) and every call site inside the example's own `sourceFiles`, the run's exit code, and no wait timeout, in any adapter's wording (`TIMEOUT_PATTERNS` in `smoke/constants.ts`), in the trace's stdout or the run log other than the lines of a test marked `allowTimeoutError`. |
+| `pnpm player:hosted` | Build the hosted trace player (the app with `--mode hosted`, no backend) and serve it at `http://localhost:4173` under the headers `vercel.json` sends from trace.webdriver.io. |
 | `pnpm docs:capabilities` | Render the per-adapter capability tables from `packages/conformance/src/features.ts` into `README.md`; `--website <webdriverio checkout>` also renders the docs-site tables, `--check` fails instead of writing, and `--parity` lists every feature some adapter lacks plus the evidence counts. |
 | `python3 packages/selenium-devtools-py/scripts/changes.py next-version` | The version a Python-adapter release would publish, from the fragments pending in `changes/`. `check --base <ref>` is the CI gate; `apply` is what the release runs. |
 
@@ -103,7 +104,7 @@ They import from `shared` and `core`, never from each other. They aren't importe
 
 ### Backend and app are framework-agnostic
 
-`backend` and `app` import from `shared` only (for contracts) and from each other via the WS/HTTP boundary. Neither imports an adapter package.
+`backend` and `app` import from `shared` (for contracts) and from each other via the WS/HTTP boundary. Neither imports an adapter package. `backend` also imports `trace`, to write and read zips; `app` imports only `trace`'s reader, which the hosted player (`trace.webdriver.io`, built with `pnpm player:hosted`, deployed by Vercel from `vercel.json`) runs in the browser to open a dropped zip with no backend at all. That build is `HOSTED_PLAYER` in `app/src/controller/constants.ts`; it never writes the trace to browser storage, and `vercel.json` is also what `vite preview` serves, so its CSP is checked locally before it ships.
 
 Framework-specific behavior in the backend is contained in two files: `runner.ts` and `framework-filters.ts`. Both branch on a typed `TestRunnerId` from shared, never on a magic string. The `framework-filters` dispatch is a `switch` over `TestRunnerId` (not a table lookup) so CodeQL's `unvalidated-dynamic-method-call` query trusts the call site.
 

README.md

@@ -262,6 +262,12 @@ The player exposes everything captured in the archive:
 
 The `show-trace` bin is exposed by each JavaScript adapter (`@wdio/devtools-service`, `@wdio/nightwatch-devtools`, `@wdio/selenium-devtools`), so `pnpm show-trace <zip>` / `npx show-trace <zip>` work in any project that installs one — no extra dependency.
 
+**Hosted player: [trace.webdriver.io](https://trace.webdriver.io).** The same player as a web page, for opening a trace without installing anything: drop a `.zip` on the page or pick one. The archive is parsed in the browser tab and never uploaded, which matters because a trace records everything the run showed or typed. Run controls are absent, as in `show-trace`. A replayed page still loads its own stylesheets and images from the site under test, as it does in `show-trace`; from an `https` page the browser blocks the `http` ones, so a trace of an `http` site can render unstyled there and fully in `show-trace`. To try the hosted build locally:
+
+```sh
+pnpm player:hosted   # builds it and serves it at http://localhost:4173 under the production headers
+```
+
 **Other viewers.** The trace uses a portable NDJSON schema, so the same `.zip` also opens in other compatible standalone trace viewers that read the format, and — because it shares that on-disk format — is what an Allure report's **embedded trace viewer** (Allure ≥ 2.35) reads. See the [backend README](./packages/backend/README.md#trace-serving--show-trace) for the reader details.
 
 #### Options

eslint.config.cjs

@@ -12,6 +12,7 @@ module.exports = [
     ignores: [
       'node_modules/**',
       '**/dist/**',
+      '**/dist-hosted/**',
       '**/.tsup/**',
       '**/allure-report/**',
       '**/allure-results/**'
@@ -298,6 +299,13 @@ module.exports = [
       'no-restricted-imports': [
         'error',
         {
+          paths: [
+            {
+              name: '@wdio/devtools-trace',
+              message:
+                'App may import only trace-reader from trace (CLAUDE.md §2.2), which the hosted player runs in the browser. The writers need Node; the backend writes zips with them.'
+            }
+          ],
           patterns: [
             {
               group: ['@wdio/devtools-service', '@wdio/devtools-service/*'],
@@ -328,9 +336,13 @@ module.exports = [
                 'App must not import from core (CLAUDE.md §2.2). core is framework-agnostic adapter logic; the app receives normalized events over WS.'
             },
             {
-              group: ['@wdio/devtools-trace', '@wdio/devtools-trace/*'],
+              // The bare name is in `paths`: here it would exclude the directory, which `!` cannot undo.
+              group: [
+                '@wdio/devtools-trace/*',
+                '!@wdio/devtools-trace/trace-reader'
+              ],
               message:
-                'App must not import from trace (CLAUDE.md §2.2). The backend writes and parses zips with it; the app receives a parsed trace over HTTP.'
+                'App may import only trace-reader from trace (CLAUDE.md §2.2), which the hosted player runs in the browser. The writers need Node; the backend writes zips with them.'
             }
           ]
         }

package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "build": "pnpm -r build",
     "show-trace": "node packages/backend/dist/show-trace.js",
+    "player:hosted": "pnpm --filter @wdio/devtools-app build:hosted && pnpm --filter @wdio/devtools-app preview:hosted",
     "backend": "node packages/backend/dist/server.js",
     "demo:wdio": "wdio run ./examples/wdio/cucumber/wdio.conf.ts",
     "demo:wdio:mobile": "wdio run ./examples/wdio/mobile/wdio.conf.ts",

packages/app/hosting-headers.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import url from 'node:url'
+
+interface HostingConfig {
+  headers: { headers: { key: string; value: string }[] }[]
+}
+
+const VERCEL_JSON = path.resolve(
+  path.dirname(url.fileURLToPath(import.meta.url)),
+  '../../vercel.json'
+)
+
+/** The response headers trace.webdriver.io sends, as `vercel.json` declares them. */
+export function hostingHeaders(): Record<string, string> {
+  const config = JSON.parse(readFileSync(VERCEL_JSON, 'utf8')) as HostingConfig
+  return Object.fromEntries(
+    config.headers.flatMap(({ headers }) =>
+      headers.map(({ key, value }) => [key, value])
+    )
+  )
+}

packages/app/package.json

@@ -14,7 +14,9 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "lint": "eslint .",
-    "prepublishOnly": "pnpm build"
+    "prepublishOnly": "pnpm build",
+    "build:hosted": "tsc && vite build --mode hosted --outDir dist-hosted",
+    "preview:hosted": "vite preview --mode hosted --outDir dist-hosted"
   },
   "author": "Christian Bromann <mail@bromann.dev>",
   "license": "MIT",
@@ -28,6 +30,7 @@
     "@tailwindcss/postcss": "^4.3.3",
     "@wdio/browser-runner": "^10.0.2",
     "@wdio/devtools-shared": "workspace:^",
+    "@wdio/devtools-trace": "workspace:^",
     "@wdio/globals": "^10.0.2",
     "@wdio/mocha-framework": "^10.0.1",
     "@wdio/protocols": "10.0.2",

packages/app/src/app.ts

@@ -5,9 +5,11 @@ import { TraceType, type CommandLog } from '@wdio/devtools-shared'
 
 import { Element } from '@core/element'
 import { DataManagerController } from './controller/DataManager.js'
+import { TraceOpenController } from './controller/trace-open.js'
 import { KeyboardController, KBD } from './controller/keyboard.js'
 import { DragController, Direction } from './utils/DragController.js'
 import {
+  HOSTED_PLAYER,
   SIDEBAR_MIN_WIDTH,
   SIDEBAR_DEFAULT_WIDTH
 } from './controller/constants.js'
@@ -23,6 +25,7 @@ import './components/header.js'
 import './components/sidebar.js'
 import './components/workbench.js'
 import './components/onboarding/start.js'
+import './components/onboarding/open-trace.js'
 import './components/workbench/compare.js'
 import './components/shortcuts-overlay.js'
 
@@ -37,6 +40,11 @@ onThemeChange(applyDarkMode)
 @customElement('wdio-devtools')
 export class WebdriverIODevtoolsApplication extends Element {
   dataManager = new DataManagerController(this)
+  #traceOpen = HOSTED_PLAYER
+    ? new TraceOpenController(this, (file) =>
+        this.dataManager.openTraceArchive(file)
+      )
+    : undefined
 
   @state() showShortcuts = false
 
@@ -112,6 +120,9 @@ export class WebdriverIODevtoolsApplication extends Element {
     window.addEventListener('show-command', this.#onShowCommand)
     window.addEventListener(KBD.step, this.#onKbdStep)
     window.addEventListener(KBD.jump, this.#onKbdJump)
+    if (HOSTED_PLAYER) {
+      document.title = 'WebdriverIO Trace Viewer'
+    }
     // In popout mode, the URL carries the test uid the parent window was
     // viewing. Push it into the context so the Compare component finds the
     // matching baseline as soon as the WS reconnects in this new window.
@@ -219,7 +230,35 @@ export class WebdriverIODevtoolsApplication extends Element {
     this.dataManager.clearExecutionData(detail?.uid, detail?.entryType)
   }
 
+  #traceOpenBanner() {
+    const error = this.#traceOpen?.error
+    if (!error) {
+      return nothing
+    }
+    return html`<div
+      role="alert"
+      class="absolute top-2 left-1/2 -translate-x-1/2 z-30 flex items-center gap-3 px-3 py-2 rounded border shadow"
+      style="background: var(--vscode-editor-background); border-color: var(--vscode-charts-red); color: var(--vscode-charts-red);"
+    >
+      <span>${error}</span>
+      <button
+        aria-label="Dismiss"
+        @click="${() => this.#traceOpen?.dismissError()}"
+      >
+        ✕
+      </button>
+    </div>`
+  }
+
   #mainContent() {
+    const traceOpen = this.#traceOpen
+    // Once a trace is loaded, a failed open keeps it and reports in a banner.
+    if (traceOpen && (traceOpen.opening || !this.dataManager.hasConnection)) {
+      return html`<wdio-devtools-open-trace
+        .busy="${traceOpen.opening}"
+        .error="${traceOpen.error}"
+      ></wdio-devtools-open-trace>`
+    }
     if (!this.dataManager.hasConnection) {
       return html`<wdio-devtools-start></wdio-devtools-start>`
     }
@@ -245,6 +284,7 @@ export class WebdriverIODevtoolsApplication extends Element {
           class="basis-auto"
           .playerMode="${this.dataManager.playerMode}"
         ></wdio-devtools-workbench>
+        ${this.#traceOpenBanner()}
       </section>
     `
   }