From f5dd99ed083ba9035f378438e7a9dc9c5ce1c674 Mon Sep 17 00:00:00 2001
From: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>
Date: Tue, 6 Oct 2026 22:07:55 +0900
Subject: [PATCH] feat(ui): add fit and zoom controls to trace viewer (#11490)

Co-authored-by: Hiroshi Ogawa <4232207+hi-ogawa@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../ui/client/components/trace/TraceView.vue  | 32 +++++++--
 .../client/components/trace/TraceViewPane.vue |  2 +
 .../components/trace/TraceZoomControl.vue     | 55 +++++++++++++++
 packages/ui/client/composables/trace-view.ts  | 42 ++++++++++-
 packages/ui/client/styles/main.css            | 16 +++++
 test/ui/fixtures/trace/basic.test.ts          | 41 +++++++++++
 test/ui/test/trace.spec.ts                    | 69 ++++++++++++++++++-
 7 files changed, 247 insertions(+), 10 deletions(-)
 create mode 100644 packages/ui/client/components/trace/TraceZoomControl.vue

diff --git a/packages/ui/client/components/trace/TraceView.vue b/packages/ui/client/components/trace/TraceView.vue
index cb51880bb..c9b9ce7ae 100644
--- a/packages/ui/client/components/trace/TraceView.vue
+++ b/packages/ui/client/components/trace/TraceView.vue
@@ -14,6 +14,7 @@ import {
   getTraceEntryClass,
   selectActiveTraceStep,
   showTraceSelectorHighlight,
+  useTraceZoom,
 } from '~/composables/trace-view'
 
 const props = defineProps<{
@@ -31,6 +32,17 @@ const iframeSandbox = computed(() => {
   return props.trace.recordCanvas ? 'allow-same-origin allow-scripts' : 'allow-same-origin'
 })
 
+const { level: zoomLevel, setFitContainer } = useTraceZoom()
+const viewport = computed(() => selectedStep.value?.snapshot.viewport)
+const scaledViewportStyle = computed(() =>
+  viewport.value
+    ? {
+        width: `${Math.floor(viewport.value.width * zoomLevel.value)}px`,
+        height: `${Math.floor(viewport.value.height * zoomLevel.value)}px`,
+      }
+    : undefined,
+)
+
 function onSelectStep(index: number) {
   selectActiveTraceStep(index)
   const step = entries.value[index]
@@ -254,14 +266,20 @@ function onSplitpanesResized({ panes }: SplitpanesResizedPayload) {
       </div>
     </Pane>
     <Pane :size="traceViewSplitSizes[1]" min-size="20">
-      <div class="h-full min-h-0 flex flex-col overflow-auto">
-        <iframe
+      <div :ref="setFitContainer" class="h-full min-h-0 flex flex-col overflow-auto">
+        <div
           v-if="selectedStep"
-          ref="iframeEl"
-          :key="iframeSandbox"
-          :sandbox="iframeSandbox"
-          style="background: white; border: none; color-scheme: normal; flex: none"
-        />
+          class="mx-auto flex-none overflow-hidden"
+          :style="scaledViewportStyle"
+        >
+          <iframe
+            ref="iframeEl"
+            :key="iframeSandbox"
+            :sandbox="iframeSandbox"
+            style="background: white; border: none; color-scheme: normal; transform-origin: 0 0"
+            :style="{ transform: `scale(${zoomLevel})` }"
+          />
+        </div>
         <div v-else class="text-sm opacity-50 p-4">No trace step found</div>
       </div>
     </Pane>
diff --git a/packages/ui/client/components/trace/TraceViewPane.vue b/packages/ui/client/components/trace/TraceViewPane.vue
index cb3cb749a..414983736 100644
--- a/packages/ui/client/components/trace/TraceViewPane.vue
+++ b/packages/ui/client/components/trace/TraceViewPane.vue
@@ -13,6 +13,7 @@ import {
 } from '~/composables/trace-view'
 import { getNames } from '../../../../vitest/src/utils/tasks.ts'
 import TraceView from './TraceView.vue'
+import TraceZoomControl from './TraceZoomControl.vue'
 
 const props = defineProps<{
   selection: TraceSelection
@@ -73,6 +74,7 @@ const traceLayoutPageUrl = computed(() => {
       <span v-else-if="attemptLabel" class="text-xs opacity-70">
         {{ attemptLabel }}
       </span>
+      <TraceZoomControl v-if="trace" />
       <label class="flex items-center gap-1 text-xs ws-nowrap select-none cursor-pointer">
         <input v-model="showTraceSelectorHighlight" type="checkbox" />
         <span>Show highlight</span>
diff --git a/packages/ui/client/components/trace/TraceZoomControl.vue b/packages/ui/client/components/trace/TraceZoomControl.vue
new file mode 100644
index 000000000..33c0ffb74
--- /dev/null
+++ b/packages/ui/client/components/trace/TraceZoomControl.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { Dropdown } from 'floating-vue'
+import IconButton from '~/components/IconButton.vue'
+import { useTraceZoom } from '~/composables/trace-view'
+
+const { level, percent, nextIn, nextOut, zoomIn, zoomOut, resetZoom, fit } = useTraceZoom()
+</script>
+
+<template>
+  <Dropdown placement="bottom-end">
+    <button
+      type="button"
+      aria-label="Trace zoom"
+      data-testid="trace-zoom-trigger"
+      class="flex items-center gap-1 rounded px-1 text-xs tabular-nums op70 hover:bg-active hover:op100"
+    >
+      <span class="i-carbon:zoom-in block" />
+      <span>{{ percent }}</span>
+    </button>
+    <template #popper>
+      <div data-testid="trace-zoom-popover" class="flex items-center gap-2 p-1 text-xs">
+        <span data-testid="trace-zoom-percent" class="w-10 text-right tabular-nums">{{
+          percent
+        }}</span>
+        <IconButton
+          title="Zoom Out"
+          icon="i-carbon:subtract"
+          :disabled="nextOut == null"
+          @click="zoomOut()"
+        />
+        <IconButton
+          title="Zoom In"
+          icon="i-carbon:add"
+          :disabled="nextIn == null"
+          @click="zoomIn()"
+        />
+        <button
+          type="button"
+          class="rounded border border-base px-2 py-0.5 hover:bg-active"
+          @click="fit()"
+        >
+          Fit
+        </button>
+        <button
+          type="button"
+          class="rounded border border-base px-2 py-0.5 enabled:hover:bg-active disabled:op40"
+          :disabled="level === 1"
+          @click="resetZoom()"
+        >
+          Reset
+        </button>
+      </div>
+    </template>
+  </Dropdown>
+</template>
diff --git a/packages/ui/client/composables/trace-view.ts b/packages/ui/client/composables/trace-view.ts
index 67ca60094..e0268e715 100644
--- a/packages/ui/client/composables/trace-view.ts
+++ b/packages/ui/client/composables/trace-view.ts
@@ -1,7 +1,7 @@
 import type { RunnerTestCase, RunnerTestFile, TestArtifact } from 'vitest'
 import type { BrowserTraceData, BrowserTraceEntry } from '../../../browser/src/client/tester/trace'
 import { useLocalStorage } from '@vueuse/core'
-import { computed, ref, watch, watchEffect } from 'vue'
+import { computed, ref, shallowRef, watch, watchEffect } from 'vue'
 import { getProjectConfigByName } from '~/utils/task'
 import { browserState, client, config } from './client'
 import { detailsPosition } from './navigation'
@@ -319,3 +319,43 @@ function parseTraceStep(value: unknown, entryCount: number): number {
   const step = typeof value === 'number' ? value : Number(value)
   return Number.isInteger(step) && step >= 0 && step < entryCount ? step : 0
 }
+
+const ZOOM_LEVELS = [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2]
+const traceZoomLevel = useLocalStorage('vitest-ui_trace-zoom', 1)
+const traceZoomFitContainer = shallowRef<HTMLElement>()
+
+export function useTraceZoom() {
+  const level = traceZoomLevel
+  const percent = computed(() => `${Math.round(level.value * 100)}%`)
+  const nextIn = computed(() => ZOOM_LEVELS.find((l) => l > level.value + 1e-3))
+  const nextOut = computed(() => ZOOM_LEVELS.findLast((l) => l < level.value - 1e-3))
+
+  function zoomIn() {
+    level.value = nextIn.value ?? level.value
+  }
+
+  function zoomOut() {
+    level.value = nextOut.value ?? level.value
+  }
+
+  function resetZoom() {
+    level.value = 1
+  }
+
+  function fit() {
+    const el = traceZoomFitContainer.value
+    const selection = activeTraceView.value
+    const viewport =
+      selection &&
+      getSelectedTrace(selection)?.entries[selection.selectedStepIndex]?.snapshot.viewport
+    if (el && viewport) {
+      level.value = Math.min(el.offsetWidth / viewport.width, el.offsetHeight / viewport.height, 1)
+    }
+  }
+
+  function setFitContainer(el: unknown) {
+    traceZoomFitContainer.value = el instanceof HTMLElement ? el : undefined
+  }
+
+  return { level, percent, nextIn, nextOut, zoomIn, zoomOut, resetZoom, fit, setFitContainer }
+}
diff --git a/packages/ui/client/styles/main.css b/packages/ui/client/styles/main.css
index 0c26592ea..7feb4a797 100644
--- a/packages/ui/client/styles/main.css
+++ b/packages/ui/client/styles/main.css
@@ -227,6 +227,22 @@ html.dark {
   border-color: var(--background-color);
 }
 
+/* floating-vue's dropdown theme only has light colors.
+   These dark colors mirror the bg-base and border-base shortcuts. */
+html.dark .v-popper--theme-dropdown .v-popper__inner {
+  background: #111;
+  color: var(--color-text);
+  border-color: #6b72801a;
+}
+
+html.dark .v-popper--theme-dropdown .v-popper__arrow-inner {
+  border-color: #111;
+}
+
+html.dark .v-popper--theme-dropdown .v-popper__arrow-outer {
+  border-color: #6b72801a;
+}
+
 .codemirror-busy > .CodeMirror > .CodeMirror-scroll > .CodeMirror-sizer .CodeMirror-lines {
   cursor: wait !important;
 }
diff --git a/test/ui/fixtures/trace/basic.test.ts b/test/ui/fixtures/trace/basic.test.ts
index 005b8544f..496855c17 100644
--- a/test/ui/fixtures/trace/basic.test.ts
+++ b/test/ui/fixtures/trace/basic.test.ts
@@ -99,3 +99,44 @@ test('image', async () => {
     .toHaveProperty('naturalWidth', 0)
   await page.getByAltText('local trace asset').mark('Render image')
 })
+
+test('zoom', async () => {
+  // three centered buttons on a grid background with a border to see zoom and cutoff
+  await page.viewport(400, 600)
+  document.body.innerHTML = `
+<style>
+  html,
+  body {
+    margin: 0;
+    height: 100vh;
+  }
+
+  body {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 16px;
+    border: 4px solid tomato;
+    background-color: lightskyblue;
+    background-image:
+      linear-gradient(to right, rgb(0 0 0 / 0.15) 1px, transparent 1px),
+      linear-gradient(to bottom, rgb(0 0 0 / 0.15) 1px, transparent 1px);
+    background-size: 50px 50px;
+    font-family: monospace;
+  }
+
+  .corner {
+    position: fixed;
+    padding: 6px 8px;
+  }
+</style>
+<span class="corner" style="top: 0; left: 0">0,0</span>
+<span class="corner" style="right: 0; bottom: 0">400,600</span>
+<button>One</button>
+<button>Two</button>
+<button>Three</button>
+`
+  await page.mark('Render zoom')
+})
diff --git a/test/ui/test/trace.spec.ts b/test/ui/test/trace.spec.ts
index 9c5577da4..df952e91d 100644
--- a/test/ui/test/trace.spec.ts
+++ b/test/ui/test/trace.spec.ts
@@ -26,7 +26,7 @@ test.describe('ui', () => {
 
   test.beforeEach(async ({ page }) => {
     await page.goto(baseURL)
-    await assertTestCounts(page, { pass: 14, fail: 0 })
+    await assertTestCounts(page, { pass: 15, fail: 0 })
   })
 
   test('basic', async ({ page }) => {
@@ -84,6 +84,10 @@ test.describe('ui', () => {
   test('persists resized trace panes across reloads', async ({ page }) => {
     await testPersistsResizedTracePanes(page)
   })
+
+  test('zoom', async ({ page }) => {
+    await testZoom(page)
+  })
 })
 
 test.describe('html reporter', () => {
@@ -120,7 +124,7 @@ test.describe('html reporter', () => {
 
   test.beforeEach(async ({ page }) => {
     await page.goto(baseURL)
-    await assertTestCounts(page, { pass: 14, fail: 0 })
+    await assertTestCounts(page, { pass: 15, fail: 0 })
   })
 
   test('basic', async ({ page }) => {
@@ -178,6 +182,10 @@ test.describe('html reporter', () => {
   test('persists resized trace panes across reloads', async ({ page }) => {
     await testPersistsResizedTracePanes(page)
   })
+
+  test('zoom', async ({ page }) => {
+    await testZoom(page)
+  })
 })
 
 async function testBasic(page: Page) {
@@ -272,6 +280,63 @@ async function testBasic(page: Page) {
   await expect(traceFrame.getByRole('button', { name: 'Switch Target' })).toBeVisible()
 }
 
+async function testZoom(page: Page) {
+  await openExplorerItem(page, 'zoom')
+
+  const traceView = page.getByTestId('trace-view')
+  const traceFrame = traceView.frameLocator('iframe')
+  const iframe = traceView.locator('iframe')
+  const zoomTrigger = traceView.getByTestId('trace-zoom-trigger')
+  const zoomPopover = page.getByTestId('trace-zoom-popover')
+  const zoomPercent = zoomPopover.getByTestId('trace-zoom-percent')
+  const zoomIn = zoomPopover.getByRole('button', { name: 'Zoom In' })
+  const zoomOut = zoomPopover.getByRole('button', { name: 'Zoom Out' })
+  const fitToPane = zoomPopover.getByRole('button', { name: 'Fit' })
+  const resetZoom = zoomPopover.getByRole('button', { name: 'Reset' })
+
+  // wait for the snapshot replay
+  await expect(traceFrame.getByRole('button', { name: 'Two' })).toBeVisible()
+
+  // verify zoom label and scaled iframe width of the 400px wide fixture viewport
+  async function expectZoom(scale: number) {
+    await expect(zoomTrigger).toHaveText(`${Math.round(scale * 100)}%`)
+    await expect.poll(async () => (await iframe.boundingBox())!.width).toBeCloseTo(400 * scale, 0)
+  }
+
+  // actual size by default
+  await expectZoom(1)
+  await zoomTrigger.click()
+  await expect(zoomPercent).toHaveText('100%')
+  await expect(resetZoom).toBeDisabled()
+
+  // step through levels and persist across reloads
+  await zoomOut.click()
+  await expectZoom(0.75)
+  await zoomOut.click()
+  await expectZoom(0.5)
+  await page.reload()
+  await expectZoom(0.5)
+
+  // fit to the 599x196 replay pane is limited by height and persists across reloads
+  const fitScale = 196 / 600
+  await zoomTrigger.click()
+  await fitToPane.click()
+  await expect(zoomTrigger).toHaveText('33%')
+  await expectZoom(fitScale)
+  await page.reload()
+  await expectZoom(fitScale)
+
+  // zoom in from fit goes to the next level
+  await zoomTrigger.click()
+  await zoomIn.click()
+  await expectZoom(0.5)
+
+  // back to actual size
+  await resetZoom.click()
+  await expectZoom(1)
+  await expect(resetZoom).toBeDisabled()
+}
+
 async function testViewport(page: Page) {
   await openExplorerItem(page, 'viewport')
 
-- 
2.54.0