@brett_lamy/docstream 0.1.0 → 0.3.0

package/src/replay/ReplayPreview.tsx

@@ -0,0 +1,398 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { EventType, Replayer } from 'rrweb';
+import type { eventWithTime } from 'rrweb';
+import { normalizeReplayEmbedUrl } from './url';
+import { sanitizeReplayEvent } from './sanitize';
+import 'rrweb/dist/style.css';
+import './styles.css';
+
+export interface ReplayPageSource {
+  kind: 'url';
+  url: string;
+  title?: string;
+}
+
+export interface ReplayEventsSource {
+  kind: 'events';
+  events: eventWithTime[];
+}
+
+export interface ReplayEventsUrlSource {
+  kind: 'events-url';
+  url: string;
+  fetchInit?: RequestInit;
+}
+
+export type ReplaySource =
+  | string
+  | eventWithTime[]
+  | ReplayPageSource
+  | ReplayEventsSource
+  | ReplayEventsUrlSource;
+
+export interface ReplayPreviewProps {
+  /** A public Loop QA URL, a public event endpoint, or an in-memory rrweb event list. */
+  source: ReplaySource;
+  /** Avoid mounting the rrweb player until the editor block is visible. */
+  active?: boolean;
+  /** Public-page embeds default to lazy loading; native rrweb playback defaults to paused. */
+  autoplay?: boolean;
+  loop?: boolean;
+  className?: string;
+  title?: string;
+  /** Playback speed options mirror the Loop QA player. */
+  speeds?: number[];
+}
+
+const DEFAULT_SPEEDS = [0.5, 1, 2, 4, 8];
+const SKIP_IDLE_THRESHOLD_MS = 5_000;
+
+function sourcePage(source: ReplaySource): ReplayPageSource | null {
+  if (typeof source === 'string') return { kind: 'url', url: source };
+  if (Array.isArray(source)) return null;
+  return source.kind === 'url' ? source : null;
+}
+
+function sourceEvents(source: ReplaySource): ReplayEventsSource | null {
+  if (Array.isArray(source)) return { kind: 'events', events: source };
+  if (typeof source === 'string') return null;
+  return source.kind === 'events' ? source : null;
+}
+
+function sourceEventsUrl(source: ReplaySource): ReplayEventsUrlSource | null {
+  if (Array.isArray(source) || typeof source === 'string') return null;
+  return source.kind === 'events-url' ? source : null;
+}
+
+function ReplayFrame({ source, title }: { source: ReplayPageSource; title?: string }) {
+  const url = normalizeReplayEmbedUrl(source.url);
+  if (!url) {
+    return (
+      <a className="replay-preview__invalid" href={source.url} target="_blank" rel="noreferrer">
+        Open replay
+      </a>
+    );
+  }
+  return (
+    <iframe
+      className="replay-preview__frame"
+      src={url}
+      title={title ?? source.title ?? 'Replay preview'}
+      loading="lazy"
+      allow="autoplay; fullscreen"
+      allowFullScreen
+      referrerPolicy="strict-origin-when-cross-origin"
+    />
+  );
+}
+
+function NativeReplay({
+  events,
+  autoplay = false,
+  loop = false,
+  speeds = DEFAULT_SPEEDS,
+}: {
+  events: eventWithTime[];
+  autoplay?: boolean;
+  loop?: boolean;
+  speeds?: number[];
+}) {
+  const stageRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<HTMLDivElement>(null);
+  const replayerRef = useRef<Replayer | null>(null);
+  const fedCountRef = useRef(0);
+  const [playing, setPlaying] = useState(false);
+  const [speed, setSpeed] = useState(1);
+  const [dims, setDims] = useState<{ w: number; h: number } | null>(null);
+  const [scale, setScale] = useState(1);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [totalTime, setTotalTime] = useState(0);
+  const [scrubbing, setScrubbing] = useState<number | null>(null);
+  const speedRef = useRef(speed);
+  const loopRef = useRef(loop);
+  const autoplayRef = useRef(autoplay);
+
+  const prepared = useMemo(
+    () => events.map((event) => sanitizeReplayEvent(event)).sort((a, b) => a.timestamp - b.timestamp),
+    [events],
+  );
+  const hasSnapshot = prepared.some((event) => event.type === EventType.FullSnapshot);
+
+  useEffect(() => {
+    if (replayerRef.current && prepared.length < fedCountRef.current) {
+      try {
+        replayerRef.current.destroy();
+      } catch {
+        // Ignore stale player teardown.
+      }
+      replayerRef.current = null;
+      fedCountRef.current = 0;
+    }
+    if (!hasSnapshot || !playerRef.current) return;
+
+    if (!replayerRef.current) {
+      const replayer = new Replayer(prepared, {
+        root: playerRef.current,
+        liveMode: false,
+        speed: speedRef.current,
+        skipInactive: true,
+        inactivePeriodThreshold: SKIP_IDLE_THRESHOLD_MS,
+        mouseTail: false,
+        showWarning: false,
+      });
+      replayer.on('resize', (payload) => {
+        const size = payload as { width?: number; height?: number };
+        if (size.width && size.height) setDims({ w: size.width, h: size.height });
+      });
+      replayer.on('finish', () => {
+        if (loopRef.current) {
+          replayer.play(0);
+          setPlaying(true);
+        } else {
+          setPlaying(false);
+        }
+      });
+      replayer.pause(0);
+      replayerRef.current = replayer;
+      fedCountRef.current = prepared.length;
+      if (autoplayRef.current) {
+        replayer.play(0);
+        setPlaying(true);
+      }
+    } else if (prepared.length > fedCountRef.current) {
+      for (let i = fedCountRef.current; i < prepared.length; i++) {
+        replayerRef.current.addEvent(prepared[i]!);
+      }
+      fedCountRef.current = prepared.length;
+    }
+  }, [hasSnapshot, prepared]);
+
+  useEffect(
+    () => () => {
+      try {
+        replayerRef.current?.destroy();
+      } catch {
+        // Ignore unmount teardown errors from rrweb.
+      }
+      replayerRef.current = null;
+      fedCountRef.current = 0;
+    },
+    [],
+  );
+
+  useEffect(() => {
+    speedRef.current = speed;
+    replayerRef.current?.setConfig({ speed });
+  }, [speed]);
+
+  useEffect(() => {
+    loopRef.current = loop;
+  }, [loop]);
+
+  useEffect(() => {
+    autoplayRef.current = autoplay;
+  }, [autoplay]);
+
+  const recalcScale = useCallback(() => {
+    if (!dims || !stageRef.current || dims.w <= 0) return;
+    setScale(Math.min(1, stageRef.current.clientWidth / dims.w));
+  }, [dims]);
+
+  useEffect(() => {
+    recalcScale();
+    window.addEventListener('resize', recalcScale);
+    return () => window.removeEventListener('resize', recalcScale);
+  }, [recalcScale]);
+
+  useEffect(() => {
+    if (!hasSnapshot) return;
+    const interval = window.setInterval(() => {
+      const replayer = replayerRef.current;
+      if (!replayer) return;
+      try {
+        const total = replayer.getMetaData().totalTime;
+        const current = Math.max(0, Math.min(replayer.getCurrentTime(), total));
+        setTotalTime(total);
+        if (scrubbing === null) setCurrentTime(current);
+      } catch {
+        // rrweb can briefly be unready while a full snapshot is applied.
+      }
+    }, 200);
+    return () => window.clearInterval(interval);
+  }, [hasSnapshot, scrubbing]);
+
+  const seek = useCallback(
+    (value: number) => {
+      const replayer = replayerRef.current;
+      if (!replayer) return;
+      const next = Math.max(0, Math.min(value, totalTime));
+      if (playing) replayer.play(next);
+      else replayer.pause(next);
+      setCurrentTime(next);
+    },
+    [playing, totalTime],
+  );
+
+  const toggle = () => {
+    const replayer = replayerRef.current;
+    if (!replayer) return;
+    if (playing) {
+      replayer.pause();
+      setPlaying(false);
+      return;
+    }
+    let offset = currentTime;
+    try {
+      if (offset >= replayer.getMetaData().totalTime - 1) offset = 0;
+    } catch {
+      offset = 0;
+    }
+    replayer.play(offset);
+    setPlaying(true);
+  };
+
+  const restart = () => {
+    replayerRef.current?.play(0);
+    setCurrentTime(0);
+    setPlaying(true);
+  };
+
+  if (!hasSnapshot) {
+    return (
+      <div className="replay-preview__empty">
+        {events.length ? `Captured ${events.length} events, but no full DOM snapshot is available.` : 'Replay data is not available yet.'}
+      </div>
+    );
+  }
+
+  return (
+    <div className="replay-preview__native">
+      <div
+        ref={stageRef}
+        className="replay-preview__stage"
+        style={dims ? { height: Math.max(1, Math.round(dims.h * scale)) } : undefined}
+      >
+        <div
+          className="replay-preview__scaler"
+          style={{ transform: `scale(${scale})`, transformOrigin: 'top left' }}
+        >
+          <div ref={playerRef} className="replay-preview__player" aria-hidden="true" />
+        </div>
+      </div>
+      <div className="replay-preview__controls">
+        <button type="button" onClick={toggle} aria-label={playing ? 'Pause replay' : 'Play replay'}>
+          {playing ? 'Pause' : 'Play'}
+        </button>
+        <button type="button" onClick={restart} aria-label="Restart replay">
+          Restart
+        </button>
+        <input
+          type="range"
+          min={0}
+          max={Math.max(totalTime, 1)}
+          step={1}
+          value={scrubbing ?? currentTime}
+          onChange={(event) => setScrubbing(Number(event.target.value))}
+          onPointerUp={(event) => {
+            seek(Number((event.currentTarget as HTMLInputElement).value));
+            setScrubbing(null);
+          }}
+          aria-label="Replay position"
+        />
+        <select value={speed} onChange={(event) => setSpeed(Number(event.target.value))} aria-label="Replay speed">
+          {speeds.map((option) => (
+            <option key={option} value={option}>
+              {option}×
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  );
+}
+
+function RemoteReplay({
+  source,
+  autoplay,
+  loop,
+  speeds,
+}: {
+  source: ReplayEventsUrlSource;
+  autoplay?: boolean;
+  loop?: boolean;
+  speeds?: number[];
+}) {
+  const [events, setEvents] = useState<eventWithTime[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setEvents(null);
+    setError(null);
+    fetch(source.url, { ...source.fetchInit, signal: controller.signal })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`Replay event request failed (${response.status})`);
+        const body = (await response.json()) as unknown;
+        const value = Array.isArray(body)
+          ? body
+          : body && typeof body === 'object' && Array.isArray((body as { events?: unknown }).events)
+            ? (body as { events: unknown[] }).events
+            : null;
+        if (!value) throw new Error('Replay event endpoint must return an event array or { events }');
+        return value as eventWithTime[];
+      })
+      .then(setEvents)
+      .catch((reason: unknown) => {
+        if (reason instanceof DOMException && reason.name === 'AbortError') return;
+        setError(reason instanceof Error ? reason.message : 'Unable to load replay data');
+      });
+    return () => controller.abort();
+  }, [source.url, source.fetchInit]);
+
+  if (error) return <div className="replay-preview__error" role="alert">{error}</div>;
+  if (!events) return <div className="replay-preview__empty">Loading replay…</div>;
+  return <NativeReplay events={events} autoplay={autoplay} loop={loop} speeds={speeds} />;
+}
+
+export function ReplayPreview({
+  source,
+  active = true,
+  autoplay = false,
+  loop = false,
+  className,
+  title,
+  speeds = DEFAULT_SPEEDS,
+}: ReplayPreviewProps) {
+  if (!active) return <div className={`replay-preview ${className ?? ''}`.trim()} data-replay-preview="paused" />;
+
+  const page = sourcePage(source);
+  const events = sourceEvents(source);
+  const eventsUrl = sourceEventsUrl(source);
+  const rootClass = `replay-preview ${className ?? ''}`.trim();
+
+  if (page) {
+    return (
+      <div className={rootClass} data-replay-preview="iframe">
+        <ReplayFrame source={page} title={title} />
+      </div>
+    );
+  }
+  if (events) {
+    return (
+      <div className={rootClass} data-replay-preview="rrweb">
+        <NativeReplay events={events.events} autoplay={autoplay} loop={loop} speeds={speeds} />
+      </div>
+    );
+  }
+  if (eventsUrl) {
+    return (
+      <div className={rootClass} data-replay-preview="rrweb">
+        <RemoteReplay source={eventsUrl} autoplay={autoplay} loop={loop} speeds={speeds} />
+      </div>
+    );
+  }
+  return null;
+}
+
+/** Semantic alias for markdown/document renderers. */
+export const ReplayEmbed = ReplayPreview;

package/src/replay/index.ts

@@ -0,0 +1,10 @@
+export { ReplayEmbed, ReplayPreview } from './ReplayPreview';
+export type {
+  ReplayEventsSource,
+  ReplayEventsUrlSource,
+  ReplayPageSource,
+  ReplayPreviewProps,
+  ReplaySource,
+} from './ReplayPreview';
+export { isReplayQaUrl, normalizeReplayEmbedUrl } from './url';
+export { sanitizeReplayEvent } from './sanitize';

package/src/replay/sanitize.ts

@@ -0,0 +1,83 @@
+import { EventType, IncrementalSource } from 'rrweb';
+import type { eventWithTime } from 'rrweb';
+
+const TRANSPARENT_PIXEL =
+  'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==';
+const EMPTY_STYLESHEET = 'data:text/css,';
+
+function isLocalNetworkUrl(value: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local')) return true;
+  if (host === '0.0.0.0' || host === '::1' || host.startsWith('127.') || host.startsWith('10.')) {
+    return true;
+  }
+  if (host.startsWith('192.168.')) return true;
+  const private172 = host.match(/^172\.(\d{1,3})\./);
+  if (private172 && Number(private172[1]) >= 16 && Number(private172[1]) <= 31) return true;
+  return host.includes(':') && (host.startsWith('fc') || host.startsWith('fd'));
+}
+
+function sanitizeCss(value: string): string {
+  return value.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi, (whole, quote: string, raw: string) =>
+    isLocalNetworkUrl(raw.trim()) ? `url(${quote}${TRANSPARENT_PIXEL}${quote})` : whole,
+  );
+}
+
+function sanitizeAttributes(attributes: Record<string, unknown>): void {
+  for (const key of Object.keys(attributes)) {
+    const value = attributes[key];
+    if (typeof value !== 'string') continue;
+    const lower = key.toLowerCase();
+    if (lower === 'src' || lower === 'poster' || lower === 'background') {
+      if (isLocalNetworkUrl(value)) attributes[key] = TRANSPARENT_PIXEL;
+    } else if (lower === 'data') {
+      if (isLocalNetworkUrl(value)) attributes[key] = 'about:blank';
+    } else if (lower === 'style' || lower === '_csstext') {
+      attributes[key] = sanitizeCss(value);
+    } else if (lower === 'href' || lower === 'xlink:href') {
+      if (isLocalNetworkUrl(value)) attributes[key] = EMPTY_STYLESHEET;
+    }
+  }
+}
+
+function walkNode(node: unknown): void {
+  if (!node || typeof node !== 'object') return;
+  const value = node as { attributes?: unknown; childNodes?: unknown };
+  if (value.attributes && typeof value.attributes === 'object') {
+    sanitizeAttributes(value.attributes as Record<string, unknown>);
+  }
+  if (Array.isArray(value.childNodes)) value.childNodes.forEach(walkNode);
+}
+
+/** Prevent a replay iframe from making the viewer fetch localhost/private assets. */
+export function sanitizeReplayEvent(event: eventWithTime): eventWithTime {
+  try {
+    if (event.type === EventType.FullSnapshot) {
+      walkNode((event.data as { node?: unknown }).node);
+    } else if (event.type === EventType.IncrementalSnapshot) {
+      const data = event.data as {
+        source?: number;
+        adds?: Array<{ node?: unknown }>;
+        attributes?: Array<{ attributes?: unknown }>;
+      };
+      if (data.source === IncrementalSource.Mutation) {
+        data.adds?.forEach((item) => walkNode(item.node));
+        data.attributes?.forEach((item) => {
+          if (item.attributes && typeof item.attributes === 'object') {
+            sanitizeAttributes(item.attributes as Record<string, unknown>);
+          }
+        });
+      }
+    }
+  } catch {
+    // A malformed asset must never take down the player.
+  }
+  return event;
+}

package/src/replay/styles.css

@@ -0,0 +1,87 @@
+.replay-preview {
+  width: 100%;
+  min-width: 0;
+  color: var(--replay-preview-fg, #e5e7eb);
+  background: var(--replay-preview-bg, #0f172a);
+  border: 1px solid var(--replay-preview-border, rgba(148, 163, 184, 0.28));
+  border-radius: 12px;
+  overflow: hidden;
+}
+
+.replay-preview__frame {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border: 0;
+  background: #0f172a;
+}
+
+.replay-preview__invalid,
+.replay-preview__empty,
+.replay-preview__error {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 140px;
+  padding: 20px;
+  color: var(--replay-preview-muted, #94a3b8);
+  font: 13px/1.5 ui-sans-serif, system-ui, sans-serif;
+  text-align: center;
+}
+
+.replay-preview__invalid {
+  color: var(--replay-preview-link, #7dd3fc);
+}
+
+.replay-preview__error {
+  color: #fda4af;
+}
+
+.replay-preview__native {
+  width: 100%;
+  background: #0f172a;
+}
+
+.replay-preview__stage {
+  position: relative;
+  width: 100%;
+  min-height: 160px;
+  overflow: hidden;
+  background: #020617;
+}
+
+.replay-preview__scaler {
+  position: absolute;
+  inset: 0 auto auto 0;
+}
+
+.replay-preview__player {
+  position: relative;
+  overflow: hidden;
+}
+
+.replay-preview__controls {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-top: 1px solid rgba(148, 163, 184, 0.2);
+  background: #111827;
+  font: 12px/1.2 ui-sans-serif, system-ui, sans-serif;
+}
+
+.replay-preview__controls button,
+.replay-preview__controls select {
+  border: 1px solid rgba(148, 163, 184, 0.3);
+  border-radius: 6px;
+  padding: 5px 8px;
+  color: inherit;
+  background: #1e293b;
+  cursor: pointer;
+}
+
+.replay-preview__controls input[type='range'] {
+  min-width: 60px;
+  flex: 1;
+  accent-color: #38bdf8;
+}

package/src/replay/url.ts

@@ -0,0 +1,41 @@
+/**
+ * Convert a normal Loop QA project URL to its chrome-free public embed route.
+ * The application owns auth/public-access decisions; this helper only changes
+ * the route shape that Loop QA already exposes for cross-site iframes.
+ */
+export function normalizeReplayEmbedUrl(input: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (parts[0] === 'projects' && parts.length >= 4) {
+    const projectId = decodeURIComponent(parts[1] ?? '');
+    const kind = parts[2] === 'explorations' ? 'tasks' : parts[2];
+    const resourceId = decodeURIComponent(parts[3] ?? '');
+    if (
+      projectId &&
+      resourceId &&
+      (kind === 'tasks' || kind === 'journeys' || kind === 'test-runs')
+    ) {
+      url.pathname = `/p/${encodeURIComponent(projectId)}/${kind}/${encodeURIComponent(resourceId)}`;
+    }
+  }
+
+  return url.toString();
+}
+
+export function isReplayQaUrl(input: string): boolean {
+  const normalized = normalizeReplayEmbedUrl(input);
+  if (!normalized) return false;
+  try {
+    const url = new URL(normalized);
+    return url.pathname.startsWith('/p/') || url.hostname.endsWith('.replay.io');
+  } catch {
+    return false;
+  }
+}