diff --git a/api/browser/commands.md b/api/browser/commands.md
index 0293fe51..65595d6c 100644
--- a/api/browser/commands.md
+++ b/api/browser/commands.md
@@ -126,7 +126,30 @@ declare module 'vitest/browser' {
 如果自定义命令具有相同的名称，则它们将覆盖内置命令。
 :::
 
+<<<<<<< HEAD
 ### 自定义 `playwright` 命令  {#custom-playwright-commands}
+=======
+### Recording trace markers
+
+Custom commands can record [trace markers](/api/browser/context#mark) for the test that triggered them through `context.mark`. This is the server-side equivalent of `page.mark` and helps annotate the [trace view](/guide/browser/trace-view) with custom actions performed inside a command.
+
+```ts
+import type { BrowserCommand } from 'vitest/node'
+
+export const uploadFixture: BrowserCommand<[name: string]> = async (
+  context,
+  name,
+) => {
+  await context.mark(`upload start: ${name}`, { kind: 'action' })
+  // ... do server-side work
+  await context.mark(`upload done: ${name}`, { kind: 'action' })
+}
+```
+
+`context.mark` is a no-op when browser tracing is not enabled or no test is currently running in the session. Unlike `page.mark`, it does not accept a callback form.
+
+### Custom `playwright` commands
+>>>>>>> 7df7a657dc941d7c21aac6ec9b42769a30a98ff0
 
 Vitest 在命令上下文中公开了几个`playwright`特定属性。
 
diff --git a/api/browser/context.md b/api/browser/context.md
index 7f7cea35..cf5d398f 100644
--- a/api/browser/context.md
+++ b/api/browser/context.md
@@ -157,6 +157,8 @@ await page.mark('submit flow', async () => {
 
 ::: tip
 This method is useful only when [`browser.trace`](/config/browser/trace) is enabled.
+
+A server-side equivalent is available on the [`BrowserCommandContext`](/api/browser/commands#recording-trace-markers) so [custom commands](/api/browser/commands#custom-commands) can record markers attributed to the test that triggered them.
 :::
 
 ### frameLocator
diff --git a/guide/browser/trace-view.md b/guide/browser/trace-view.md
index 52aa8b5e..1748b7b4 100644
--- a/guide/browser/trace-view.md
+++ b/guide/browser/trace-view.md
@@ -101,7 +101,7 @@ Trace entries are recorded automatically for:
 
 Each entry captures the DOM state at that point, along with timing information, the selector, and the source location that triggered it.
 
-Element highlighting is best-effort. Some provider-specific selectors, shadow DOM selectors, or elements that are not present in the captured snapshot may not be highlighted.
+In Vitest UI, trace entries are streamed as the test runs, so you can inspect recorded steps before the test finishes. Long-running actions, `expect.element(...)` assertions, and callback `page.mark()` entries appear as in-progress steps first, then update with their final status and duration.
 
 ## Custom Trace Entries