@brett_lamy/docstream 1.22.1 → 1.24.0

package/src/replay/index.ts

@@ -18,9 +18,11 @@ export type { ReplayMarker, ReplayMarkerKind, ReplayMeta, ReplayPointerPoint, Re
 export { getReplayDevtools, replayDevtoolsAt, requestName } from './devtools';
 export type { ReplayConsoleEntry, ReplayConsoleLevel, ReplayDevtools, ReplayDevtoolsState, ReplayRequest } from './devtools';
 export type { ReplayDevtoolsTab } from './ReplayDevtools';
+export { getReplayInspections, replayInspectionAt, resolveReplayInspections } from './inspections';
+export type { ReplayInspection, ReplayInspectionTab, ResolvedReplayInspection } from './inspections';
 export { ReplayEventType, ReplayIncrementalSource, ReplayMouseInteraction } from './types';
 export type { ReplayEvent } from './types';
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from './url';
-export { ReplayFile, isRrwebUrl } from './ReplayFile';
+export { ReplayFile, isRrwebUrl, splitReplayFragment } from './ReplayFile';
 export type { ReplayFileProps } from './ReplayFile';
 export { sanitizeReplayEvent } from './sanitize';

package/src/replay/inspections.ts

@@ -0,0 +1,105 @@
+/* Inspections: moments in a recording where someone (a person, a debugging agent) looked at a request or a console
+   message — "at 0:35 we inspected GET /api/search?q=te". The player follows them by default: as the playhead
+   reaches one, DevTools opens on its tab with that request (or message) selected and the inspection's label above
+   it, and playback carries on.
+
+   They come from the `inspections` prop or from the recording itself, as custom events tagged `inspect`
+   (`record.addCustomEvent('inspect', { tab, request, message, label })`), so an .rrweb file can carry its own.
+   An inspection names its target by the recording's id for it (a request's `requestId` / `id`, a custom console
+   event's `id`) or, failing that, by URL (the request with that URL sent nearest the inspection) or by text (the
+   last message containing it). Pure readers, no rrweb import. */
+import type { ReplayConsoleEntry, ReplayDevtools, ReplayRequest } from './devtools'
+import { ReplayEventType, type ReplayEvent } from './types'
+
+export type ReplayInspectionTab = 'network' | 'console'
+
+export interface ReplayInspection {
+  /** Stable id; defaults to `inspect-<n>`. */
+  id?: string
+  /** Milliseconds from the start of the recording. */
+  time: number
+  /** The DevTools tab to open (default: `network` when `request` is set, else `console`). */
+  tab?: ReplayInspectionTab
+  /** The request to select: the recording's id for it (`key`), or its URL. */
+  request?: string
+  /** The console message to select: the recording's id for it (`key`), or text it contains. */
+  message?: string
+  /** What was found, shown above the panel while the inspection is current. */
+  label?: string
+}
+
+/** An inspection with its defaults filled in and its target resolved against the recording's DevTools. */
+export interface ResolvedReplayInspection {
+  id: string
+  time: number
+  tab: ReplayInspectionTab
+  label?: string
+  /** The `ReplayRequest.id` to select, when the target was found. */
+  requestId?: string
+  /** The `ReplayConsoleEntry.id` to select, when the target was found. */
+  messageId?: string
+}
+
+export const INSPECT_TAG = 'inspect'
+
+const str = (value: unknown): string | undefined => (typeof value === 'string' && value ? value : undefined)
+
+/** The `inspect` custom events in a recording, as inspections (times in ms from its first event). */
+export function getReplayInspections(events: readonly ReplayEvent[]): ReplayInspection[] {
+  const list = [...events].sort((a, b) => a.timestamp - b.timestamp)
+  const start = list[0]?.timestamp ?? 0
+  const out: ReplayInspection[] = []
+  for (const event of list) {
+    if (event.type !== ReplayEventType.Custom) continue
+    const data = (event.data ?? {}) as { tag?: unknown; payload?: Record<string, unknown> }
+    if (data.tag !== INSPECT_TAG) continue
+    const p = data.payload ?? {}
+    const tab = p.tab === 'network' || p.tab === 'console' ? p.tab : undefined
+    out.push({ id: str(p.id), time: event.timestamp - start, tab, request: str(p.request), message: str(p.message), label: str(p.label) })
+  }
+  return out
+}
+
+function findRequest(network: readonly ReplayRequest[], target: string, time: number): ReplayRequest | undefined {
+  const byKey = network.find((r) => r.key === target)
+  if (byKey) return byKey
+  // By URL (exact, else the address without its origin): the one sent nearest the inspection.
+  const matches = network.filter((r) => r.url === target || r.url.replace(/^\w+:\/\/[^/]+/, '') === target)
+  return matches.sort((a, b) => Math.abs(a.time - time) - Math.abs(b.time - time))[0]
+}
+
+function findMessage(messages: readonly ReplayConsoleEntry[], target: string, time: number): ReplayConsoleEntry | undefined {
+  const byKey = messages.find((m) => m.key === target)
+  if (byKey) return byKey
+  const matches = messages.filter((m) => m.message.includes(target))
+  // The last one logged by the inspection, else the first after it.
+  return matches.filter((m) => m.time <= time).at(-1) ?? matches[0]
+}
+
+/** Fills in each inspection's id and tab and finds its request or message; sorted by time. */
+export function resolveReplayInspections(inspections: readonly ReplayInspection[], tools: ReplayDevtools): ResolvedReplayInspection[] {
+  return inspections
+    .map((inspection, i) => {
+      const request = inspection.request ? findRequest(tools.network, inspection.request, inspection.time) : undefined
+      const message = inspection.message ? findMessage(tools.console, inspection.message, inspection.time) : undefined
+      return {
+        id: inspection.id ?? `inspect-${i}`,
+        time: Math.max(0, inspection.time),
+        tab: inspection.tab ?? (inspection.request ? 'network' : 'console'),
+        label: inspection.label,
+        requestId: request?.id,
+        messageId: message?.id,
+      } satisfies ResolvedReplayInspection
+    })
+    .sort((a, b) => a.time - b.time)
+}
+
+/** The inspection current at `time`: the latest at or before it. */
+export function replayInspectionAt(inspections: readonly ResolvedReplayInspection[], time: number): ResolvedReplayInspection | undefined {
+  let current: ResolvedReplayInspection | undefined
+  for (const inspection of inspections) {
+    if (inspection.time > time) break
+    current = inspection
+  }
+  return current
+}

package/src/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);