@brett_lamy/docstream 1.22.1 → 1.24.0

package/dist/styles.css

@@ -4260,6 +4260,24 @@
     transform: translateY(5px);
   }
 
+  /* The time window: a band under the track, on the same geometry as the markers (4px padding, half a thumb). */
+  :where([data-slot="replay-preview-window"]) {
+    position: absolute;
+    top: 50%;
+    left: calc(10px + (100% - 20px) * var(--replay-window-start, 0));
+    width: max(4px, calc((100% - 20px) * var(--replay-window-size, 1)));
+    height: 10px;
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--primary, #4f46e5) 34%, transparent);
+    box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--primary, #4f46e5) 60%, transparent);
+    translate: 0 -50%;
+    pointer-events: none;
+  }
+
+  :where([data-slot="replay-preview-scrubber"][data-markers] > [data-slot="replay-preview-window"]) {
+    translate: 0 calc(-50% + 5px);
+  }
+
   :where([data-slot="replay-preview-markers"] > button) {
     position: absolute;
     top: 50%;
@@ -4309,6 +4327,8 @@
   }
 
   :where([data-slot="replay-preview-scrubber"] > input[type="range"]) {
+    /* Above the time-window band. */
+    position: relative;
     --replay-track: 4px;
     --replay-thumb: 12px;
     appearance: none;
@@ -4331,8 +4351,11 @@
   [data-slot="replay-preview-scrubber"] > input[type="range"]::-webkit-slider-runnable-track {
     height: var(--replay-track);
     border-radius: 999px;
+    /* Played: from the time window's start (0 without one) to the playhead. */
     background: linear-gradient(
       to right,
+      color-mix(in srgb, var(--muted-foreground, #71717a) 26%, transparent) var(--replay-progress-start, 0%),
+      var(--primary, #4f46e5) var(--replay-progress-start, 0%),
       var(--primary, #4f46e5) var(--replay-progress, 0%),
       color-mix(in srgb, var(--muted-foreground, #71717a) 26%, transparent) var(--replay-progress, 0%)
     );
@@ -4601,19 +4624,17 @@
     box-shadow: inset 0 0 0 2px var(--ring, #6366f1);
   }
 
-  :where([data-slot="replay-devtools-tabs"] [data-part="at"]) {
-    display: inline-flex;
-    align-items: center;
-    margin-inline-start: auto;
-    padding-inline: 8px;
-    color: var(--replay-devtools-dim);
-    font-variant-numeric: tabular-nums;
-  }
+
+
 
   :where([data-slot="replay-devtools-tabs"] > [data-slot="replay-devtools-close"], [data-slot="replay-devtools-detail-tabs"] > [data-slot="replay-devtools-close"]) {
     padding: 0 8px;
   }
 
+  :where([data-slot="replay-devtools-tabs"] > [data-slot="replay-devtools-close"]) {
+    margin-inline-start: auto;
+  }
+
   :where([data-slot="replay-devtools-pane"]) {
     display: flex;
     flex: 1 1 0%;
@@ -4882,6 +4903,11 @@
   :where([data-slot="replay-devtools-table"] tbody tr:focus-visible) {
     box-shadow: inset 0 0 0 2px var(--ring, #6366f1);
   }
+  /* The inspected request or message: a bar down its leading edge (the selection tint shows it's open). */
+  :where([data-slot="replay-devtools-table"] tbody tr[data-inspected], [data-slot="replay-devtools-message"][data-inspected]) {
+    box-shadow: inset 3px 0 0 var(--primary, #2563eb);
+  }
+
 
   :where([data-slot="replay-devtools-table"] tr[data-failed]) {
     color: var(--replay-devtools-red);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "1.22.1",
+  "version": "1.24.0",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -90,7 +90,7 @@ export type {
 } from "./replay/ReplayPreview"
 export type { ReplayEvent } from "./replay/types"
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay/url"
-export { ReplayFile, isRrwebUrl } from "./replay/ReplayFile"
+export { ReplayFile, isRrwebUrl, splitReplayFragment } from "./replay/ReplayFile"
 export { ImageThumbnail, leadingThumbnail, thumbnailLabel } from "./docs/ImageThumbnail"
 export type { ReplayFileProps } from "./replay/ReplayFile"
 export { VideoEmbed } from "./video"

package/src/replay/ReplayDevtools.tsx

@@ -5,10 +5,12 @@
    waiting at the playhead shows as pending), and a request's row opens its headers, payload and response.
 
    Everything is a function of the playhead: scrub back and the lists shrink to what DevTools showed then. A row's
-   time jumps the player there. Esc closes the panel. Plain React + plain CSS, like the player. */
+   time jumps the player there. Esc closes the panel. An inspection (inspections.ts) selects its request or
+   message and marks it. Plain React + plain CSS, like the player. */
 import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent, type PointerEvent as ReactPointerEvent } from 'react'
 import { ChevronRight, CircleX, Info, Network, SquareTerminal, TriangleAlert, X } from 'lucide-react'
 import type { ReplayConsoleEntry, ReplayDevtoolsState, ReplayRequest } from './devtools'
+import type { ResolvedReplayInspection } from './inspections'
 
 export type ReplayDevtoolsTab = 'console' | 'network'
 
@@ -55,14 +57,16 @@ export function DevtoolsButtons({ state, open, onOpen }: {
   )
 }
 
-/** The panel over the page: Console and Network, cut at the playhead. */
-export function DevtoolsPanel({ state, at, tab, onTab, onClose, onSeek }: {
-  state: ReplayDevtoolsState; at: number; tab: ReplayDevtoolsTab; onTab: (tab: ReplayDevtoolsTab) => void
-  onClose: () => void; onSeek: (ms: number) => void
+/** The panel over the page: Console and Network, cut at the playhead. `inspection` selects and marks its target;
+ *  `autoFocus` (default true) moves focus into the panel as it opens — off when an inspection opened it mid-play. */
+export function DevtoolsPanel({ state, tab, onTab, onClose, onSeek, inspection, autoFocus = true }: {
+  state: ReplayDevtoolsState; tab: ReplayDevtoolsTab; onTab: (tab: ReplayDevtoolsTab) => void
+  onClose: () => void; onSeek: (ms: number) => void; inspection?: ResolvedReplayInspection | null; autoFocus?: boolean
 }) {
   const panel = useRef<HTMLDivElement>(null)
-  const [height, setHeight] = useState(58)
-  useEffect(() => { panel.current?.focus({ preventScroll: true }) }, [])
+  // Opened by an inspection, the panel starts taller: its point is the request's details.
+  const [height, setHeight] = useState(inspection ? 72 : 58)
+  useEffect(() => { if (autoFocus) panel.current?.focus({ preventScroll: true }) }, [autoFocus])
 
   // Drag the top edge to resize, as a fraction of the stage.
   const resize = (e: ReactPointerEvent<HTMLDivElement>) => {
@@ -116,10 +120,11 @@ export function DevtoolsPanel({ state, at, tab, onTab, onClose, onSeek }: {
           </button>
         ))}
         </div>
-        <span data-part="at">As of {time(at)}</span>
         <button type="button" data-slot="replay-devtools-close" aria-label="Close DevTools" onClick={onClose}><X size={14} /></button>
       </div>
-      {tab === 'console' ? <ConsolePane state={state} onSeek={onSeek} /> : <NetworkPane state={state} onSeek={onSeek} />}
+      {tab === 'console'
+        ? <ConsolePane state={state} onSeek={onSeek} inspected={inspection?.tab === 'console' ? inspection : null} />
+        : <NetworkPane state={state} onSeek={onSeek} inspected={inspection?.tab === 'network' ? inspection : null} />}
     </div>
   )
 }
@@ -129,7 +134,9 @@ export function DevtoolsPanel({ state, at, tab, onTab, onClose, onSeek }: {
 type LevelFilter = 'all' | 'error' | 'warn' | 'info'
 const LEVEL_ICON = { error: CircleX, warn: TriangleAlert, info: Info } as const
 
-function ConsolePane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (ms: number) => void }) {
+function ConsolePane({ state, onSeek, inspected }: {
+  state: ReplayDevtoolsState; onSeek: (ms: number) => void; inspected: ResolvedReplayInspection | null
+}) {
   const [query, setQuery] = useState('')
   const [level, setLevel] = useState<LevelFilter>('all')
   const list = useRef<HTMLDivElement>(null)
@@ -139,12 +146,17 @@ function ConsolePane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (m
       (level === 'all' || (level === 'info' ? e.level === 'info' || e.level === 'log' || e.level === 'debug' : e.level === level)) &&
       (!q || e.message.toLowerCase().includes(q)))
   }, [state.console, query, level])
-  // Follow new messages as they're logged, unless you've scrolled up to read.
+  // Follow new messages as they're logged, unless you've scrolled up to read (or an inspection is showing one).
   const pinned = useRef(true)
+  const inspectedId = inspected?.messageId
+  const shown = inspectedId !== undefined && rows.some((r) => r.id === inspectedId)
   useEffect(() => {
     const el = list.current
-    if (el && pinned.current) el.scrollTop = el.scrollHeight
-  }, [rows.length])
+    if (el && pinned.current && !shown) el.scrollTop = el.scrollHeight
+  }, [rows.length, shown])
+  useEffect(() => {
+    if (shown) list.current?.querySelector('[data-inspected]')?.scrollIntoView?.({ block: 'nearest' })
+  }, [shown, inspected?.id])
   return (
     <div data-slot="replay-devtools-pane" data-pane="console">
       <div data-slot="replay-devtools-toolbar">
@@ -167,7 +179,7 @@ function ConsolePane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (m
         aria-label="Console messages"
         onScroll={(e) => { const el = e.currentTarget; pinned.current = el.scrollHeight - el.scrollTop - el.clientHeight < 8 }}
       >
-        {rows.map((entry) => <ConsoleRow key={entry.id} entry={entry} onSeek={onSeek} />)}
+        {rows.map((entry) => <ConsoleRow key={entry.id} entry={entry} onSeek={onSeek} inspected={entry.id === inspectedId} />)}
         {!rows.length ? <p data-slot="replay-devtools-empty">{state.console.length ? 'No messages match the filter' : 'Nothing logged yet'}</p> : null}
         {state.counts.laterMessages ? <p data-slot="replay-devtools-later">{state.counts.laterMessages} more later in the recording</p> : null}
       </div>
@@ -175,7 +187,7 @@ function ConsolePane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (m
   )
 }
 
-function ConsoleRow({ entry, onSeek }: { entry: ReplayConsoleEntry; onSeek: (ms: number) => void }) {
+function ConsoleRow({ entry, onSeek, inspected }: { entry: ReplayConsoleEntry; onSeek: (ms: number) => void; inspected: boolean }) {
   const Glyph = entry.level === 'error' || entry.level === 'warn' || entry.level === 'info' ? LEVEL_ICON[entry.level] : null
   const body = (
     <>
@@ -184,7 +196,7 @@ function ConsoleRow({ entry, onSeek }: { entry: ReplayConsoleEntry; onSeek: (ms:
     </>
   )
   return (
-    <div data-slot="replay-devtools-message" data-level={entry.level}>
+    <div data-slot="replay-devtools-message" data-level={entry.level} data-inspected={inspected || undefined}>
       {entry.trace?.length ? (
         <details>
           <summary>{body}</summary>
@@ -203,10 +215,20 @@ type Row = ReplayRequest & { pending: boolean }
 
 const statusText = (r: Row) => (r.pending ? '(pending)' : r.status === undefined ? (r.failed ? '(failed)' : '—') : r.status === 0 ? '(failed)' : String(r.status))
 
-function NetworkPane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (ms: number) => void }) {
+function NetworkPane({ state, onSeek, inspected }: {
+  state: ReplayDevtoolsState; onSeek: (ms: number) => void; inspected: ResolvedReplayInspection | null
+}) {
   const [query, setQuery] = useState('')
   const [filter, setFilter] = useState<RequestFilter>('all')
-  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const inspectedId = inspected?.requestId
+  const [selectedId, setSelectedId] = useState<string | null>(inspectedId ?? null)
+  const table = useRef<HTMLDivElement>(null)
+  // A new inspection selects its request (once it has been sent) and brings its row into view.
+  useEffect(() => { if (inspectedId) setSelectedId(inspectedId) }, [inspected?.id, inspectedId])
+  const sent = inspectedId !== undefined && state.network.some((r) => r.id === inspectedId)
+  useEffect(() => {
+    if (sent) table.current?.querySelector('[data-inspected]')?.scrollIntoView?.({ block: 'nearest' })
+  }, [sent, inspected?.id])
   const rows = useMemo(() => {
     const q = query.trim().toLowerCase()
     return state.network.filter((r) =>
@@ -235,7 +257,7 @@ function NetworkPane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (m
         </div>
       </div>
       <div data-slot="replay-devtools-network">
-        <div data-slot="replay-devtools-table-wrap">
+        <div ref={table} data-slot="replay-devtools-table-wrap">
           <table data-slot="replay-devtools-table">
             <thead>
               <tr>
@@ -251,6 +273,7 @@ function NetworkPane({ state, onSeek }: { state: ReplayDevtoolsState; onSeek: (m
                   data-failed={(r.failed && !r.pending) || undefined}
                   data-pending={r.pending || undefined}
                   aria-selected={r.id === selectedId}
+                  data-inspected={r.id === inspectedId || undefined}
                   tabIndex={0}
                   onClick={() => setSelectedId(r.id === selectedId ? null : r.id)}
                   onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setSelectedId(r.id === selectedId ? null : r.id) } }}

package/src/replay/ReplayFile.tsx

@@ -11,10 +11,12 @@ export interface ReplayFileProps extends Omit<ReplayPlayerOptions, 'url'> {
 /**
  * An rrweb recording file (a JSON event array, or `{ events }`), played in the replay browser frame.
  * The URL goes through `AssetResolverProvider`, and the file is fetched only once the frame nears the
- * viewport, so a page of recordings doesn't download them all up front.
+ * viewport, so a page of recordings doesn't download them all up front. A media fragment on the URL,
+ * `recording.rrweb#t=4.7,7.4` (seconds), is its `timeWindow`.
  */
 export function ReplayFile({ url, ...options }: ReplayFileProps) {
-  const src = useAsset(url);
+  const { file, segment } = splitReplayFragment(url);
+  const src = useAsset(file);
   const ref = useRef<HTMLDivElement>(null);
   const [near, setNear] = useState(false);
 
@@ -28,7 +30,18 @@ export function ReplayFile({ url, ...options }: ReplayFileProps) {
   }, [near]);
 
   if (!near || src === undefined) return <div ref={ref} className="docstream-asset-pending" data-slot="replay-file" aria-busy="true" />;
-  return <ReplayPreview source={{ kind: 'events-url', url: src }} chrome="browser" {...options} />;
+  return <ReplayPreview source={{ kind: 'events-url', url: src }} chrome="browser" timeWindow={segment} {...options} />;
+}
+
+/** Splits `#t=start,end` (a media fragment, in seconds; `#t=start` runs to the end) off a recording's URL. */
+export function splitReplayFragment(url: string): { file: string; segment?: [number, number] } {
+  const hash = url.indexOf('#');
+  if (hash < 0) return { file: url };
+  const m = url.slice(hash + 1).match(/(?:^|&)t=(?:npt:)?([\d.]*)(?:,([\d.]+))?(?:&|$)/);
+  if (!m) return { file: url };
+  const start = m[1] ? Number(m[1]) * 1000 : 0;
+  const end = m[2] ? Number(m[2]) * 1000 : Infinity;
+  return { file: url.slice(0, hash), segment: Number.isFinite(start) && end > start ? [start, end] : undefined };
 }
 
 const RRWEB = /\.rrweb(?:[?#]|$)/i;

package/src/replay/ReplayPlayer.tsx

@@ -2,7 +2,9 @@
    plays the recording (rrweb loads lazily, on first render); this adds the chrome around it: a URL bar that
    follows the recording's navigations, play/pause, a scrubber with the recording's moments on a rail above
    it, a speed control, fullscreen, a drawn cursor whose clicks ripple, and DevTools: Console and Network buttons
-   in the top bar with what had been logged and requested by the playhead, which open a DevTools panel over the page. Until the player is ready a
+   in the top bar with what had been logged and requested by the playhead, which open a DevTools panel over the page,
+   and inspections (inspections.ts) that open it on a request or message as playback reaches them. A time window
+   highlights a segment on the scrubber, opens there and plays just that, until you scrub outside it. Until the player is ready a
    poster (a page-shaped skeleton by default) holds the frame's exact size, so nothing jumps.
 
    Plain React + plain CSS (`@layer docstream.replay` in styles.css, `[data-slot]` hooks). Keys (focus inside
@@ -18,6 +20,7 @@ import { Lock, Maximize, Minimize, Pause, Play, RotateCcw } from 'lucide-react'
 import { ReplayStage } from './ReplayStage'
 import { DevtoolsButtons, DevtoolsPanel, type ReplayDevtoolsTab } from './ReplayDevtools'
 import { getReplayDevtools, replayDevtoolsAt } from './devtools'
+import { getReplayInspections, replayInspectionAt, resolveReplayInspections, type ReplayInspection } from './inspections'
 import { getReplayMarkers, getReplayMeta, getReplayPointerTrack, replayPointerAt } from './markers'
 import type { ReplayMarker, ReplayMarkerKind, ReplayPointerTrack } from './markers'
 import type { ReplayStageHandle } from './stage-types'
@@ -36,6 +39,8 @@ export interface ReplayPreviewHandle {
   seek(ms: number): void
   toggle(): void
   getCurrentTime(): number
+  /** Jump to an inspection (by its id) and open DevTools on what it found. */
+  inspect(id: string): void
 }
 
 /** Options shared by every `ReplayPreview` (an `events` player or a `source` embed). */
@@ -52,9 +57,14 @@ export interface ReplayPlayerOptions {
   /** Play/pause, scrubber, speed and fullscreen (default true). */
   controls?: boolean
   autoplay?: boolean
+  /** Restart at the end (with a `timeWindow`, at the window's end, from its start). */
   loop?: boolean
-  /** Where the player starts, in ms from the start. */
+  /** Where the player starts, in ms from the start (default 0, or the `timeWindow`'s start). */
   initialTime?: number
+  /** `[start, end]` in ms: the segment that matters. The player opens at `start` with the segment highlighted on the
+   *  scrubber, and playing from inside it stops at `end` (play again to replay it). Scrub or seek outside it and
+   *  playback runs on through the rest of the recording. */
+  timeWindow?: readonly [number, number]
   /** Speeds the speed button cycles through; the first is the initial speed (default 1, 2, 4, 0.5). */
   speeds?: number[]
   /** Markers on the scrubber rail: `true` (default) reads them from the recording, `false` hides the rail,
@@ -63,11 +73,17 @@ export interface ReplayPlayerOptions {
   /** Which recorded marker kinds to show (default all). */
   markerKinds?: ReplayMarkerKind[]
   /** Console and Network buttons (in the top bar, or beside the controls without the browser chrome) that open a
-   *  DevTools panel cut at the playhead. `true` (default) shows them when the recording has console messages or
-   *  requests; `false` hides them. */
+   *  DevTools panel cut at the playhead, shown when the recording has console messages, requests or inspections.
+   *  `disableDevtools` removes them, the panel and the inspections. */
+  disableDevtools?: boolean
+  /** @deprecated Use `disableDevtools`. `false` is the same as `disableDevtools`. */
   devtools?: boolean
   /** Open the DevTools panel on this tab at mount. */
   defaultDevtoolsTab?: ReplayDevtoolsTab
+  /** Moments where a request or console message was inspected. As playback reaches one, DevTools opens on its
+   *  tab with that request or message selected and the label above it; playback doesn't stop. Added to the
+   *  recording's own `inspect` custom events, and to the rail as checkpoints. */
+  inspections?: ReplayInspection[]
   /** Draw the recorded pointer and click ripples (default true). */
   cursor?: boolean
   /** `width` (default): the page scales to the frame's width and sets its height. `contain`: fill the frame's
@@ -97,8 +113,8 @@ const MARKER_NOUN: Record<ReplayMarkerKind, string> = {
 
 export function ReplayPlayer({
   events, url, title = 'Session replay', chrome = 'browser', trafficLights = true, controls = true,
-  autoplay = false, loop = false, initialTime = 0, speeds = DEFAULT_PLAYER_SPEEDS, markers = true, markerKinds,
-  cursor = true, devtools = true, defaultDevtoolsTab, fit = 'width', poster, lazy = true, playerRef, onTimeUpdate, onPlayingChange, onMarkerPress,
+  autoplay = false, loop = false, initialTime: initialTimeProp, timeWindow, speeds = DEFAULT_PLAYER_SPEEDS, markers = true, markerKinds,
+  cursor = true, disableDevtools = false, devtools = true, defaultDevtoolsTab, inspections, fit = 'width', poster, lazy = true, playerRef, onTimeUpdate, onPlayingChange, onMarkerPress,
   className, style,
 }: ReplayPlayerOptions & { events: ReplayEvent[] }) {
   const rootRef = useRef<HTMLDivElement>(null)
@@ -107,14 +123,35 @@ export function ReplayPlayer({
   const meta = useMemo(() => getReplayMeta(events), [events])
   const track = useMemo(() => getReplayPointerTrack(events), [events])
   const recorded = useMemo(() => getReplayMarkers(events), [events])
-  const shown = useMemo(() => {
-    const list = Array.isArray(markers) ? markers : markers ? recorded : []
-    return markerKinds ? list.filter((m) => markerKinds.includes(m.kind)) : list
-  }, [markers, recorded, markerKinds])
 
+  const toolsOn = devtools && !disableDevtools
   const tools = useMemo(() => getReplayDevtools(events), [events])
-  const showTools = devtools && (tools.console.length > 0 || tools.network.length > 0)
+  const resolved = useMemo(
+    () => (toolsOn ? resolveReplayInspections([...getReplayInspections(events), ...(inspections ?? [])], tools) : []),
+    [toolsOn, events, inspections, tools],
+  )
+  const showTools = toolsOn && (tools.console.length > 0 || tools.network.length > 0 || resolved.length > 0)
   const [panel, setPanel] = useState<ReplayDevtoolsTab | null>(defaultDevtoolsTab ?? null)
+  // Whether an inspection (rather than a press) opened the panel: it then leaves focus where it was.
+  const [autoOpened, setAutoOpened] = useState(false)
+
+  const shown = useMemo(() => {
+    // Inspections from the prop join the rail as checkpoints (the recording's own are already among `recorded`).
+    const own: ReplayMarker[] = toolsOn ? (inspections ?? []).map((inspection, i) => ({
+      id: `inspection-${i}`, kind: 'custom', time: Math.max(0, inspection.time), label: inspection.label ?? 'Inspected',
+    })) : []
+    const list = Array.isArray(markers) ? markers : markers ? [...recorded, ...own].sort((a, b) => a.time - b.time) : []
+    return markerKinds ? list.filter((m) => markerKinds.includes(m.kind)) : list
+  }, [markers, recorded, markerKinds, inspections, toolsOn])
+
+  // The time window, clamped to the recording; dropped when it's empty.
+  const span = useMemo(() => {
+    if (!timeWindow) return null
+    const start = Math.max(0, Math.min(timeWindow[0], meta.duration))
+    const end = Math.max(start, Math.min(timeWindow[1], meta.duration))
+    return end - start >= 1 ? { start, end } : null
+  }, [timeWindow, meta.duration])
+  const initialTime = initialTimeProp ?? span?.start ?? 0
 
   const [visible, setVisible] = useState(!lazy)
   const [ready, setReady] = useState(false)
@@ -122,6 +159,8 @@ export function ReplayPlayer({
   const [time, setTime] = useState(initialTime)
   const [playing, setPlaying] = useState(false)
   const [finished, setFinished] = useState(false)
+  // Stopped at the window's end: the center button replays the segment.
+  const [windowDone, setWindowDone] = useState(false)
   const [speedIndex, setSpeedIndex] = useState(0)
   const [fullscreen, setFullscreen] = useState(false)
   const duration = meta.duration
@@ -151,17 +190,73 @@ export function ReplayPlayer({
     return () => clearTimeout(timer)
   }, [ready, reduced])
 
-  const handle = useMemo<ReplayPreviewHandle>(() => ({
-    play: (offset) => { setFinished(false); stage.current?.play(offset) },
-    pause: (offset) => stage.current?.pause(offset),
-    seek: (ms) => { setFinished(false); stage.current?.seek(ms) },
-    toggle: () => { setFinished(false); stage.current?.toggle() },
-    getCurrentTime: () => stage.current?.getCurrentTime() ?? 0,
-  }), [])
+  const resolvedRef = useRef(resolved)
+  resolvedRef.current = resolved
+  // The window, the playhead and the play state, for the handle (which never re-creates) and onTime.
+  const spanRef = useRef(span)
+  spanRef.current = span
+  const timeRef = useRef(initialTime)
+  const playingRef = useRef(false)
+  // Whether playback is held to the window: it is when it starts (or is moved) inside it.
+  const inWindow = (ms: number) => !!spanRef.current && ms >= spanRef.current.start && ms < spanRef.current.end
+  const held = useRef(inWindow(initialTime))
+  const handle = useMemo<ReplayPreviewHandle>(() => {
+    const play = (offset?: number) => {
+      const w = spanRef.current
+      if (!w) { setFinished(false); return stage.current?.play(offset) }
+      let from = offset ?? timeRef.current
+      // Play at the window's end replays the window.
+      if (w && offset === undefined && Math.abs(from - w.end) < 60) from = w.start
+      held.current = inWindow(from)
+      setFinished(false)
+      setWindowDone(false)
+      if (from !== timeRef.current) stage.current?.play(from)
+      else stage.current?.play(offset)
+    }
+    const seek = (ms: number) => {
+      held.current = inWindow(ms)
+      setFinished(false)
+      setWindowDone(false)
+      stage.current?.seek(ms)
+    }
+    return {
+      play,
+      pause: (offset) => stage.current?.pause(offset),
+      seek,
+      toggle: () => {
+        if (!spanRef.current) { setFinished(false); return stage.current?.toggle() }
+        return playingRef.current ? stage.current?.pause() : play()
+      },
+      getCurrentTime: () => stage.current?.getCurrentTime() ?? 0,
+      inspect: (id) => {
+        const inspection = resolvedRef.current.find((x) => x.id === id)
+        if (!inspection) return
+        seek(inspection.time)
+        setPanel(inspection.tab)
+        setAutoOpened(false)
+      },
+    }
+  }, [])
   useImperativeHandle(playerRef, () => handle, [handle])
 
-  const onTime = useCallback((ms: number) => { setTime(ms); onTimeUpdate?.(ms) }, [onTimeUpdate])
+  const onTime = useCallback((ms: number) => {
+    timeRef.current = ms
+    // Held to the window: stop at its end, or go round again with `loop`.
+    const w = spanRef.current
+    if (w && held.current && playingRef.current && ms >= w.end) {
+      if (loop) stage.current?.seek(w.start)
+      else {
+        stage.current?.pause(w.end)
+        setWindowDone(true)
+        ms = w.end
+        timeRef.current = ms
+      }
+    }
+    setTime(ms)
+    onTimeUpdate?.(ms)
+  }, [onTimeUpdate, loop])
   const onPlaying = useCallback((p: boolean) => {
+    playingRef.current = p
     setPlaying(p)
     if (p) setFinished(false)
     onPlayingChange?.(p)
@@ -209,7 +304,23 @@ export function ReplayPlayer({
   }, [url, meta.href, recorded, time])
 
   const toolsState = useMemo(() => replayDevtoolsAt(tools, time), [tools, time])
-  const openTools = (tab: ReplayDevtoolsTab) => setPanel((p) => (p === tab ? null : tab))
+  const openTools = (tab: ReplayDevtoolsTab) => { setAutoOpened(false); setPanel((p) => (p === tab ? null : tab)) }
+
+  // Inspect mode: the inspection at the playhead opens DevTools on what it found. Only a change of inspection does
+  // (closing the panel keeps it closed until the next one); scrubbing back before the first closes what it opened.
+  const inspection = showTools ? replayInspectionAt(resolved, time) : undefined
+  const inspectionId = inspection?.id
+  const inspectionTab = inspection?.tab
+  const lastInspection = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (inspectionId === lastInspection.current) return
+    const had = lastInspection.current
+    lastInspection.current = inspectionId
+    if (inspectionTab) {
+      setPanel(inspectionTab)
+      setAutoOpened(true)
+    } else if (had !== undefined && autoOpened) setPanel(null)
+  }, [inspectionId, inspectionTab, autoOpened])
   const toolButtons = showTools ? <DevtoolsButtons state={toolsState} open={panel} onOpen={openTools} /> : null
 
   const w = meta.width || 1280
@@ -247,7 +358,7 @@ export function ReplayPlayer({
             events={events}
             fit="contain"
             speed={speed}
-            loop={loop}
+            loop={loop && !span}
             autoplay={autoplay}
             initialTime={initialTime}
             showMouse={false}
@@ -269,11 +380,12 @@ export function ReplayPlayer({
         {showTools && panel ? (
           <DevtoolsPanel
             state={toolsState}
-            at={time}
             tab={panel}
             onTab={setPanel}
             onClose={() => { setPanel(null); rootRef.current?.focus({ preventScroll: true }) }}
             onSeek={(ms) => handle.seek(ms)}
+            inspection={inspection}
+            autoFocus={!autoOpened}
           />
         ) : null}
 
@@ -282,11 +394,11 @@ export function ReplayPlayer({
             <button
               type="button"
               tabIndex={-1}
-              aria-label={finished ? 'Replay from the start' : 'Play'}
+              aria-label={finished ? 'Replay from the start' : windowDone ? 'Replay the segment' : 'Play'}
               // The overlay leaves as playback starts; keep focus (and the keys) in the player.
               onClick={() => { rootRef.current?.focus({ preventScroll: true }); toggle() }}
             >
-              {finished ? <RotateCcw size={22} strokeWidth={2.4} /> : <Play size={22} strokeWidth={2.4} fill="currentColor" />}
+              {finished || windowDone ? <RotateCcw size={22} strokeWidth={2.4} /> : <Play size={22} strokeWidth={2.4} fill="currentColor" />}
             </button>
           </div>
         ) : null}
@@ -303,6 +415,7 @@ export function ReplayPlayer({
           <Scrubber
             time={time}
             duration={duration}
+            span={span}
             markers={shown}
             disabled={!ready}
             onSeek={(ms) => handle.seek(ms)}
@@ -391,8 +504,8 @@ const PointerOverlay = memo(function PointerOverlay({ track, time, reduced }: {
   )
 })
 
-function Scrubber({ time, duration, markers, disabled, onSeek, onMarker }: {
-  time: number; duration: number; markers: ReplayMarker[]; disabled: boolean
+function Scrubber({ time, duration, span, markers, disabled, onSeek, onMarker }: {
+  time: number; duration: number; span: { start: number; end: number } | null; markers: ReplayMarker[]; disabled: boolean
   onSeek: (ms: number) => void; onMarker: (m: ReplayMarker) => void
 }) {
   const max = Math.max(1, duration)
@@ -411,6 +524,14 @@ function Scrubber({ time, duration, markers, disabled, onSeek, onMarker }: {
   }, [markers, max])
   return (
     <div data-slot="replay-preview-scrubber" data-markers={markers.length ? '' : undefined}>
+      {span ? (
+        <div
+          data-slot="replay-preview-window"
+          aria-hidden="true"
+          title={`${formatReplayTime(span.start)}–${formatReplayTime(span.end)}`}
+          style={{ '--replay-window-start': span.start / max, '--replay-window-size': (span.end - span.start) / max } as CSSProperties}
+        />
+      ) : null}
       {markers.length ? (
         <div data-slot="replay-preview-markers">
           {markers.map((m) => (
@@ -430,13 +551,16 @@ function Scrubber({ time, duration, markers, disabled, onSeek, onMarker }: {
       <input
         type="range"
         aria-label="Playback position"
-        aria-valuetext={`${formatReplayTime(value)} of ${formatReplayTime(duration)}`}
+        aria-valuetext={`${formatReplayTime(value)} of ${formatReplayTime(duration)}${span ? `, segment ${formatReplayTime(span.start)} to ${formatReplayTime(span.end)}` : ''}`}
         min={0}
         max={max}
         step={10}
         value={value}
         disabled={disabled}
-        style={{ '--replay-progress': `${(value / max) * 100}%` } as CSSProperties}
+        style={{
+          '--replay-progress': `${(value / max) * 100}%`,
+          ...(span ? { '--replay-progress-start': `${(span.start / max) * 100}%` } : {}),
+        } as CSSProperties}
         onChange={(e) => onSeek(Number(e.currentTarget.value))}
       />
     </div>

package/src/replay/devtools.ts

@@ -17,6 +17,8 @@ export type ReplayConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug'
 export interface ReplayConsoleEntry {
   /** Stable id (`console-<n>`). */
   id: string
+  /** The recording's own id for the message (`payload.id` of a custom event), which an inspection can name. */
+  key?: string
   /** Milliseconds from the start of the recording. */
   time: number
   level: ReplayConsoleLevel
@@ -33,6 +35,9 @@ export interface ReplayConsoleEntry {
 export interface ReplayRequest {
   /** Stable id (`request-<n>`). */
   id: string
+  /** The recording's own id for the request (`id` / `requestId`, e.g. a Replay request id), which an
+   *  inspection can name. */
+  key?: string
   /** When the request was sent, in ms from the start of the recording. */
   time: number
   /** How long it took, when known: the response arrived at `time + duration`. */
@@ -153,6 +158,7 @@ export function getReplayDevtools(events: readonly ReplayEvent[]): ReplayDevtool
     // request was sent that far before it (its own duration, for a lone request).
     const sent = Math.max(0, startTime !== undefined && batchEnd !== undefined ? at - (batchEnd - startTime) : at - (duration ?? 0))
     requests.push({
+      key: str(raw.requestId) ?? str(raw.id),
       time: sent,
       duration,
       method: (str(raw.method) ?? 'GET').toUpperCase(),
@@ -197,10 +203,10 @@ export function getReplayDevtools(events: readonly ReplayEvent[]): ReplayDevtool
         const detail = str(payload.message) ?? str(payload.detail)
         const message = detail ? `Uncaught ${label}: ${detail}` : `Uncaught ${label}`
         const trace = Array.isArray(payload.stack) ? payload.stack.map(String) : str(payload.stack)?.split('\n').map((l) => l.trim()).filter(Boolean)
-        consoleEntries.push({ time, level: 'error', message, args: [message], trace: trace?.length ? trace : undefined, source: 'exception' })
+        consoleEntries.push({ key: str(payload.id), time, level: 'error', message, args: [message], trace: trace?.length ? trace : undefined, source: 'exception' })
       } else if (CONSOLE_TAGS.has(tag)) {
         const args = Array.isArray(payload.args) ? payload.args.map((a) => asText(a) ?? '') : [str(payload.message) ?? str(payload.label) ?? asText(payload.detail) ?? '']
-        consoleEntries.push({ time, level: levelOf(payload.level ?? tag), message: args.join(' '), args, source: 'custom' })
+        consoleEntries.push({ key: str(payload.id), time, level: levelOf(payload.level ?? tag), message: args.join(' '), args, source: 'custom' })
       }
     }
   }