@oar-sh/oar 0.9.0

package/server/public/app/tmux-inspector-view.js

@@ -0,0 +1,422 @@
+import { currentConvId, conversations, showTransientRelayNotice } from './store.js';
+import { getSocket } from './socket-handlers.js';
+
+let inspectorState = {
+  open: false,
+  sdkSessionId: '',
+  terminal: null,
+  fitAddon: null,
+  plainOutput: null,
+  usesPlainOutput: false,
+  lastResizeCols: null,
+  lastResizeRows: null,
+  socket: null,
+  listenersBound: false,
+};
+
+const XTERM_STYLE_CANDIDATES = [
+  'https://cdn.jsdelivr.net/npm/xterm@5.5.0/css/xterm.min.css',
+  'https://unpkg.com/xterm@5.5.0/css/xterm.min.css',
+];
+const XTERM_SCRIPT_CANDIDATES = [
+  'https://cdn.jsdelivr.net/npm/xterm@5.5.0/lib/xterm.min.js',
+  'https://unpkg.com/xterm@5.5.0/lib/xterm.min.js',
+];
+const XTERM_FIT_SCRIPT_CANDIDATES = [
+  'https://cdn.jsdelivr.net/npm/xterm-addon-fit@0.10.0/lib/xterm-addon-fit.min.js',
+  'https://unpkg.com/xterm-addon-fit@0.10.0/lib/xterm-addon-fit.min.js',
+];
+
+let xtermLoadPromise = null;
+let resizeDebounceTimer = null;
+
+function resolveCurrentSessionId() {
+  const convId = String(currentConvId || '').trim();
+  if (!convId) return '';
+  const conversation = conversations?.[convId] || null;
+  return String(conversation?.sdkSessionId || conversation?.sdk_session_id || '').trim();
+}
+
+function setStatus(text = '', isError = false) {
+  const statusEl = document.getElementById('tmux-inspector-status');
+  if (!statusEl) return;
+  statusEl.textContent = String(text || '').trim();
+  statusEl.dataset.state = isError ? 'error' : 'ok';
+}
+
+function resolveTerminalRuntime() {
+  const TerminalCtor = window?.Terminal;
+  return typeof TerminalCtor === 'function' ? TerminalCtor : null;
+}
+
+function stripAnsiControlCodes(input = '') {
+  return String(input || '')
+    // OSC ... BEL or ST
+    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/g, '')
+    // CSI sequence
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, '')
+    // 2-byte escape
+    .replace(/\u001B[@-_]/g, '')
+    // C1 control CSI (single-byte 0x9B)
+    .replace(/\u009B[0-?]*[ -/]*[@-~]/g, '')
+    // other non-printing controls except LF/TAB
+    .replace(/[\u0000-\u0008\u000B-\u001A\u001C-\u001F\u007F]/g, '')
+    .replace(/\r(?!\n)/g, '');
+}
+
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    const timeoutMs = 3500;
+    let settled = false;
+    const finishResolve = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    const finishReject = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    };
+    const timer = setTimeout(() => {
+      finishReject(new Error(`Timed out loading ${src}`));
+    }, timeoutMs);
+
+    const existing = Array.from(document.querySelectorAll('script[src]'))
+      .find((node) => String(node.getAttribute('src') || '').trim() === src);
+    if (existing) {
+      if (existing.dataset.loaded === 'true') {
+        finishResolve();
+        return;
+      }
+      if (existing.dataset.failed === 'true') {
+        finishReject(new Error(`Failed to load ${src}`));
+        return;
+      }
+      existing.addEventListener('load', () => finishResolve(), { once: true });
+      existing.addEventListener('error', () => finishReject(new Error(`Failed to load ${src}`)), { once: true });
+      return;
+    }
+    const script = document.createElement('script');
+    script.src = src;
+    script.async = true;
+    script.onload = () => {
+      script.dataset.loaded = 'true';
+      finishResolve();
+    };
+    script.onerror = () => {
+      script.dataset.failed = 'true';
+      finishReject(new Error(`Failed to load ${src}`));
+    };
+    document.head.appendChild(script);
+  });
+}
+
+function ensureStylesheet(urlCandidates = []) {
+  for (const href of urlCandidates) {
+    const hrefText = String(href || '').trim();
+    if (!hrefText) continue;
+    const already = Array.from(document.querySelectorAll('link[rel="stylesheet"]'))
+      .some((node) => String(node.getAttribute('href') || '').trim() === hrefText);
+    if (already) return;
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = hrefText;
+    document.head.appendChild(link);
+    return;
+  }
+}
+
+async function loadFirstSuccessful(candidates = []) {
+  let lastError = null;
+  for (const candidate of candidates) {
+    const src = String(candidate || '').trim();
+    if (!src) continue;
+    try {
+      await loadScript(src);
+      return true;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (lastError) throw lastError;
+  return false;
+}
+
+async function ensureTerminalRuntimeLoaded() {
+  const existing = resolveTerminalRuntime();
+  if (existing) return existing;
+  if (!xtermLoadPromise) {
+    xtermLoadPromise = (async () => {
+      ensureStylesheet(XTERM_STYLE_CANDIDATES);
+      await loadFirstSuccessful(XTERM_SCRIPT_CANDIDATES);
+      await loadFirstSuccessful(XTERM_FIT_SCRIPT_CANDIDATES);
+      return resolveTerminalRuntime();
+    })().catch(() => {
+      xtermLoadPromise = null;
+      return null;
+    });
+  }
+  return xtermLoadPromise;
+}
+
+function fitTerminal() {
+  if (inspectorState.usesPlainOutput) return;
+  try {
+    inspectorState.fitAddon?.fit?.();
+  } catch {}
+  scheduleTmuxResizeSync();
+}
+
+function ensureSocketListeners(socket) {
+  if (!socket || inspectorState.listenersBound) return;
+  inspectorState.listenersBound = true;
+  socket.on('tmux_inspector_chunk', (event = {}) => {
+    if (!inspectorState.open) return;
+    const sessionId = String(event?.sdkSessionId || '').trim();
+    if (!sessionId || sessionId !== inspectorState.sdkSessionId) return;
+    const data = String(event?.data || '');
+    if (!data) return;
+    if (inspectorState.usesPlainOutput) {
+      if (inspectorState.plainOutput) {
+        inspectorState.plainOutput.textContent += stripAnsiControlCodes(data);
+        inspectorState.plainOutput.scrollTop = inspectorState.plainOutput.scrollHeight;
+      }
+      return;
+    }
+    inspectorState.terminal?.write(data);
+  });
+  socket.on('tmux_inspector_status', (event = {}) => {
+    if (!inspectorState.open) return;
+    const sessionId = String(event?.sdkSessionId || '').trim();
+    if (!sessionId || sessionId !== inspectorState.sdkSessionId) return;
+    const state = String(event?.state || '').trim().toLowerCase();
+    const reason = String(event?.reason || '').trim();
+    if (state === 'ended') {
+      setStatus(reason || 'Session stream ended', true);
+      return;
+    }
+    if (state === 'error') {
+      setStatus(reason || 'Session stream error', true);
+      return;
+    }
+    setStatus(reason || 'Streaming', false);
+  });
+}
+
+function hideModal() {
+  const modal = document.getElementById('tmux-inspector-modal');
+  if (!modal) return;
+  modal.classList.remove('visible');
+  modal.setAttribute('aria-hidden', 'true');
+}
+
+function showModal() {
+  const modal = document.getElementById('tmux-inspector-modal');
+  if (!modal) return;
+  modal.classList.add('visible');
+  modal.setAttribute('aria-hidden', 'false');
+}
+
+function closeTmuxInspector({ notifyServer = true } = {}) {
+  const socket = inspectorState.socket;
+  const sessionId = inspectorState.sdkSessionId;
+  if (notifyServer && socket && sessionId) {
+    try {
+      socket.emit('tmux_inspector_close', { sdkSessionId: sessionId });
+    } catch {}
+  }
+  try {
+    inspectorState.terminal?.dispose?.();
+  } catch {}
+  if (resizeDebounceTimer) {
+    clearTimeout(resizeDebounceTimer);
+    resizeDebounceTimer = null;
+  }
+  inspectorState = {
+    ...inspectorState,
+    open: false,
+    sdkSessionId: '',
+    terminal: null,
+    fitAddon: null,
+    plainOutput: null,
+    usesPlainOutput: false,
+    lastResizeCols: null,
+    lastResizeRows: null,
+  };
+  setStatus('');
+  const sessionEl = document.getElementById('tmux-inspector-session');
+  if (sessionEl) sessionEl.textContent = '';
+  hideModal();
+}
+
+async function attachTmuxInspector(sessionId) {
+  const socket = getSocket();
+  if (!socket) throw new Error('Socket connection unavailable');
+  inspectorState.socket = socket;
+  ensureSocketListeners(socket);
+
+  const payload = await new Promise((resolve, reject) => {
+    socket.timeout(6000).emit('tmux_inspector_open', { sdkSessionId: sessionId }, (error, response) => {
+      if (error) {
+        reject(new Error('Timed out while opening tmux inspector'));
+        return;
+      }
+      resolve(response || null);
+    });
+  });
+  if (!payload?.ok) {
+    throw new Error(String(payload?.reason || payload?.code || 'Unable to open tmux inspector'));
+  }
+  return payload;
+}
+
+function sendTmuxResize(cols, rows) {
+  const socket = inspectorState.socket || getSocket();
+  const sdkSessionId = String(inspectorState.sdkSessionId || '').trim();
+  if (!socket || !sdkSessionId) return;
+  const nextCols = Math.trunc(Number(cols));
+  const nextRows = Math.trunc(Number(rows));
+  if (!Number.isFinite(nextCols) || !Number.isFinite(nextRows)) return;
+  if (nextCols < 80 || nextRows < 24) return;
+  if (inspectorState.lastResizeCols === nextCols && inspectorState.lastResizeRows === nextRows) return;
+  inspectorState.lastResizeCols = nextCols;
+  inspectorState.lastResizeRows = nextRows;
+  try {
+    socket.emit('tmux_inspector_resize', {
+      sdkSessionId,
+      cols: nextCols,
+      rows: nextRows,
+    });
+  } catch {}
+}
+
+function scheduleTmuxResizeSync() {
+  if (!inspectorState.open || inspectorState.usesPlainOutput) return;
+  const cols = Number(inspectorState.terminal?.cols || 0);
+  const rows = Number(inspectorState.terminal?.rows || 0);
+  if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols <= 0 || rows <= 0) return;
+  if (resizeDebounceTimer) clearTimeout(resizeDebounceTimer);
+  resizeDebounceTimer = setTimeout(() => {
+    resizeDebounceTimer = null;
+    sendTmuxResize(cols, rows);
+  }, 90);
+}
+
+async function openTmuxInspector() {
+  const sdkSessionId = resolveCurrentSessionId();
+  if (!sdkSessionId) {
+    showTransientRelayNotice('Select a conversation with a bound SDK session first.');
+    return;
+  }
+  closeTmuxInspector({ notifyServer: true });
+  showModal();
+  setStatus('Connecting…', false);
+  const sessionEl = document.getElementById('tmux-inspector-session');
+  if (sessionEl) sessionEl.textContent = sdkSessionId;
+  const mount = document.getElementById('tmux-inspector-term');
+  if (!mount) throw new Error('Terminal container missing');
+  mount.innerHTML = '';
+  const TerminalCtor = resolveTerminalRuntime();
+  if (!TerminalCtor) {
+    // Warm up renderer loading in the background without blocking first paint/connect.
+    void ensureTerminalRuntimeLoaded();
+  }
+  if (TerminalCtor) {
+    const terminal = new TerminalCtor({
+      convertEol: false,
+      disableStdin: true,
+      cursorBlink: false,
+      scrollback: 8000,
+    });
+    const FitAddonCtor = window?.FitAddon?.FitAddon;
+    const fitAddon = typeof FitAddonCtor === 'function' ? new FitAddonCtor() : null;
+    if (fitAddon) terminal.loadAddon(fitAddon);
+    terminal.open(mount);
+    inspectorState.terminal = terminal;
+    inspectorState.fitAddon = fitAddon;
+    inspectorState.plainOutput = null;
+    inspectorState.usesPlainOutput = false;
+  } else {
+    const plain = document.createElement('pre');
+    plain.className = 'tmux-inspector-plain-output';
+    plain.setAttribute('aria-label', 'tmux console stream');
+    mount.appendChild(plain);
+    inspectorState.terminal = null;
+    inspectorState.fitAddon = null;
+    inspectorState.plainOutput = plain;
+    inspectorState.usesPlainOutput = true;
+  }
+  inspectorState.open = true;
+  inspectorState.sdkSessionId = sdkSessionId;
+  fitTerminal();
+
+  const attached = await attachTmuxInspector(sdkSessionId);
+  const snapshot = String(attached?.snapshot || '');
+  if (snapshot) {
+    if (inspectorState.usesPlainOutput && inspectorState.plainOutput) {
+      inspectorState.plainOutput.textContent = stripAnsiControlCodes(snapshot);
+      inspectorState.plainOutput.scrollTop = inspectorState.plainOutput.scrollHeight;
+    } else {
+      inspectorState.terminal?.write(snapshot);
+    }
+  }
+  setStatus(
+    inspectorState.usesPlainOutput
+      ? 'Read-only stream attached (plain renderer fallback)'
+      : 'Read-only stream attached',
+    false,
+  );
+  fitTerminal();
+  scheduleTmuxResizeSync();
+}
+
+function bindCloseControls() {
+  const closeBtn = document.getElementById('tmux-inspector-close');
+  const modal = document.getElementById('tmux-inspector-modal');
+  if (closeBtn && closeBtn.dataset.bound !== '1') {
+    closeBtn.dataset.bound = '1';
+    closeBtn.addEventListener('click', () => closeTmuxInspector({ notifyServer: true }));
+  }
+  if (modal && modal.dataset.bound !== '1') {
+    modal.dataset.bound = '1';
+    modal.addEventListener('click', (event) => {
+      const dialog = modal.querySelector('.tmux-inspector-dialog');
+      if (!dialog || dialog.contains(event.target)) return;
+      closeTmuxInspector({ notifyServer: true });
+    });
+  }
+  if (!window.__tmuxInspectorResizeBound) {
+    window.__tmuxInspectorResizeBound = true;
+    window.addEventListener('resize', () => {
+      if (!inspectorState.open) return;
+      fitTerminal();
+    });
+  }
+}
+
+export function initTmuxInspectorView({
+  bindMenuAction,
+  lockChatActionsMenuShield,
+  closeChatActionsMenu,
+} = {}) {
+  bindCloseControls();
+  const menuBtn = document.getElementById('chat-menu-inspect-tmux');
+  if (!menuBtn || typeof bindMenuAction !== 'function') return;
+  bindMenuAction(menuBtn, (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    lockChatActionsMenuShield?.(350);
+    closeChatActionsMenu?.();
+    openTmuxInspector().catch((error) => {
+      setStatus(String(error?.message || 'Failed to open tmux inspector'), true);
+      showTransientRelayNotice(String(error?.message || 'Failed to open tmux inspector'));
+    });
+  });
+}
+
+export function closeTmuxInspectorView() {
+  closeTmuxInspector({ notifyServer: true });
+}

package/server/public/app/transcript-separators.mjs

@@ -0,0 +1,282 @@
+// Full-width transcript break rows: once-per-day date separators and the
+// Claude auto-compaction boundary. Both kinds go through ONE idempotent DOM
+// pass (syncTranscriptSeparators), because every insertion path — a full
+// render, an appended live message, a prepended older history page — can
+// invalidate separators that are already in the DOM. The planning half
+// (buildSeparatorPlan) is pure and carries the whole decision, so the rules
+// are testable without a DOM.
+//
+// Separator rows deliberately carry neither the `msg` class nor
+// data-message-id: the render bookkeeping (rendered-fingerprint collection,
+// seen-message ids, the "first row" anchors) walks `.msg`, and a separator
+// that answered those selectors would be mistaken for a message.
+import { parseTimestampMs } from './store.js';
+
+export const SEPARATOR_CLASS = 'transcript-separator';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function startOfLocalDay(ms) {
+  const date = new Date(ms);
+  date.setHours(0, 0, 0, 0);
+  return date.getTime();
+}
+
+function dayKeyOf(ms) {
+  const date = new Date(ms);
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/**
+ * `Today` / `Yesterday` for the two most recent local days, `Mon, 18 Aug`
+ * within the current calendar year, `Mon, 18 Aug 2025` before it.
+ */
+export function formatDayLabel(value, nowMs = Date.now()) {
+  const timestampMs = typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : parseTimestampMs(value);
+  if (!timestampMs) return '';
+  const now = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
+  const dayStart = startOfLocalDay(timestampMs);
+  const todayStart = startOfLocalDay(now);
+  if (dayStart === todayStart) return 'Today';
+  if (dayStart === startOfLocalDay(todayStart - DAY_MS)) return 'Yesterday';
+  const date = new Date(timestampMs);
+  const sameYear = date.getFullYear() === new Date(now).getFullYear();
+  const base = date.toLocaleDateString([], {
+    weekday: 'short',
+    day: 'numeric',
+    month: 'short',
+    ...(sameYear ? {} : { year: 'numeric' }),
+  });
+  return base;
+}
+
+function formatCompactTokens(value) {
+  if (value == null || value === '') return '';
+  const count = Number(value);
+  if (!Number.isFinite(count) || count < 0) return '';
+  if (count < 1000) return String(Math.round(count));
+  return `${(count / 1000).toFixed(1).replace(/\.0$/, '')}k`;
+}
+
+/**
+ * Parses the `data-compact-boundary` stamp (`"<pre>|<post>"`, either side
+ * possibly empty) into token counts.
+ */
+export function parseCompactBoundaryValue(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (!text) return null;
+  const [rawPre, rawPost] = text.split('|');
+  const toCount = (raw) => {
+    const digits = String(raw || '').trim();
+    if (!digits) return null;
+    const parsed = Number(digits);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.round(parsed) : null;
+  };
+  return { preTokens: toCount(rawPre), postTokens: toCount(rawPost) };
+}
+
+export function formatCompactBoundaryLabel(boundary) {
+  const preTokens = formatCompactTokens(boundary?.preTokens);
+  const postTokens = formatCompactTokens(boundary?.postTokens);
+  if (preTokens && postTokens) return `Context compacted · ${preTokens} → ${postTokens} tokens`;
+  // Auto-compact payloads carry no post_tokens — optional in the SDK type and
+  // absent from the on-disk transcript of every compaction inspected — so the
+  // pre-only count is the whole story the break can tell.
+  if (preTokens) return `Context compacted · was ${preTokens} tokens`;
+  return 'Context compacted';
+}
+
+/**
+ * Pure planner: rows in transcript order →
+ * `[{ key, kind, label, beforeIndex, messageId }]`, each separator keyed by
+ * the row it precedes. A day separator opens the transcript and repeats on
+ * every local-day rollover; a compaction separator sits immediately before
+ * the message whose activities recorded the boundary (after that message's
+ * day separator, when both land on the same row).
+ */
+export function buildSeparatorPlan(rows, nowMs = Date.now()) {
+  const list = Array.isArray(rows) ? rows : [];
+  const plan = [];
+  let previousDayKey = '';
+  list.forEach((row, index) => {
+    const messageId = String(row?.messageId || '').trim();
+    const timestampMs = Number.isFinite(Number(row?.timestampMs)) && Number(row?.timestampMs)
+      ? Number(row.timestampMs)
+      : parseTimestampMs(row?.timestamp);
+    if (timestampMs) {
+      const dayKey = dayKeyOf(timestampMs);
+      if (dayKey !== previousDayKey) {
+        previousDayKey = dayKey;
+        plan.push({
+          key: `day:${dayKey}`,
+          kind: 'day',
+          label: formatDayLabel(timestampMs, nowMs),
+          beforeIndex: index,
+          messageId,
+        });
+      }
+    }
+    const boundary = row?.compactBoundary && typeof row.compactBoundary === 'object'
+      ? row.compactBoundary
+      : parseCompactBoundaryValue(row?.compactBoundary);
+    if (boundary && (boundary.preTokens != null || boundary.postTokens != null || row?.compactBoundary)) {
+      plan.push({
+        key: `compact:${messageId || index}:${boundary.preTokens ?? ''}-${boundary.postTokens ?? ''}`,
+        kind: 'compact',
+        label: formatCompactBoundaryLabel(boundary),
+        beforeIndex: index,
+        messageId,
+      });
+    }
+  });
+  return plan;
+}
+
+function readRowFromNode(node) {
+  const dataset = node?.dataset || {};
+  return {
+    messageId: String(dataset.messageId || '').trim(),
+    timestamp: String(dataset.messageTimestamp || '').trim(),
+    compactBoundary: String(dataset.compactBoundary || '').trim(),
+  };
+}
+
+function createSeparatorNode(doc, separator) {
+  const node = doc.createElement('div');
+  node.className = separator.kind === 'compact'
+    ? `${SEPARATOR_CLASS} is-compact`
+    : `${SEPARATOR_CLASS} is-day`;
+  node.dataset.separatorKey = separator.key;
+  node.dataset.separatorKind = separator.kind;
+  node.setAttribute('role', 'separator');
+  node.setAttribute('aria-label', separator.label);
+  const label = doc.createElement('span');
+  label.className = 'transcript-separator-label';
+  // textContent, never innerHTML: labels are generated here but the row sits
+  // in the same container as user content.
+  label.textContent = separator.label;
+  node.appendChild(label);
+  return node;
+}
+
+function isSeparatorNode(node) {
+  return node?.nodeType === 1 && node.classList?.contains(SEPARATOR_CLASS);
+}
+
+/**
+ * Idempotent DOM pass: reconciles the separators already in `container`
+ * against the plan for the messages it currently holds. Safe to call after
+ * any insertion path; runs no DOM writes when nothing changed.
+ */
+export function syncTranscriptSeparators(container, nowMs = Date.now()) {
+  if (!container || typeof container.querySelectorAll !== 'function') return 0;
+  const doc = container.ownerDocument || (typeof document !== 'undefined' ? document : null);
+  if (!doc || typeof doc.createElement !== 'function') return 0;
+  const nodes = Array.from(container.querySelectorAll('.msg[data-message-timestamp]'))
+    .filter((node) => node.parentNode === container);
+  const plan = buildSeparatorPlan(nodes.map(readRowFromNode), nowMs);
+  const planByIndex = new Map();
+  for (const separator of plan) {
+    const list = planByIndex.get(separator.beforeIndex) || [];
+    list.push(separator);
+    planByIndex.set(separator.beforeIndex, list);
+  }
+  const kept = new Set();
+  let changed = 0;
+  nodes.forEach((node, index) => {
+    const desired = planByIndex.get(index) || [];
+    const existing = [];
+    let cursor = node.previousSibling;
+    while (isSeparatorNode(cursor)) {
+      existing.unshift(cursor);
+      cursor = cursor.previousSibling;
+    }
+    const matches = existing.length === desired.length
+      && existing.every((el, i) => el.dataset.separatorKey === desired[i].key
+        && el.dataset.separatorLabel === desired[i].label);
+    if (matches) {
+      for (const el of existing) kept.add(el);
+      return;
+    }
+    for (const el of existing) el.remove();
+    for (const separator of desired) {
+      const created = createSeparatorNode(doc, separator);
+      created.dataset.separatorLabel = separator.label;
+      container.insertBefore(created, node);
+      kept.add(created);
+      changed += 1;
+    }
+    changed += existing.length;
+  });
+  // Anything left over (a stale row above a removed message, or a separator
+  // stranded at the tail) goes.
+  for (const el of Array.from(container.querySelectorAll(`.${SEPARATOR_CLASS}`))) {
+    if (kept.has(el)) continue;
+    el.remove();
+    changed += 1;
+  }
+  syncSeparatorRail(container);
+  return changed;
+}
+
+export const RAIL_ID = 'transcript-separator-rail';
+
+function ensureRail(container) {
+  const parent = container.parentNode;
+  const doc = container.ownerDocument;
+  if (!parent || typeof parent.appendChild !== 'function' || typeof doc?.createElement !== 'function') return null;
+  const existing = typeof parent.querySelector === 'function' ? parent.querySelector(`#${RAIL_ID}`) : null;
+  if (existing) return existing;
+  const rail = doc.createElement('div');
+  rail.id = RAIL_ID;
+  // Decoration only: the separators themselves carry the accessible labels.
+  rail.setAttribute('aria-hidden', 'true');
+  parent.appendChild(rail);
+  return rail;
+}
+
+/**
+ * One dot per separator, floated beside the scrollbar at the separator's
+ * proportional position in the scroll content.
+ *
+ * The rail is a sibling of the scroll container, not a child: children of a
+ * scroller scroll away with the content. Positions are read from the
+ * separator rows this module already inserted, so there is no second source
+ * of truth — and offsets only mean anything once the container is laid out,
+ * which is why every read is guarded (the unit-test node model reports none).
+ */
+export function syncSeparatorRail(container) {
+  if (!container || typeof container.querySelectorAll !== 'function') return 0;
+  const rail = ensureRail(container);
+  if (!rail || typeof rail.replaceChildren !== 'function') return 0;
+  const scrollHeight = Number(container.scrollHeight) || 0;
+  const rows = Array.from(container.querySelectorAll(`.${SEPARATOR_CLASS}`))
+    .filter((node) => node.parentNode === container);
+  // A conversation with no boundaries gets no rail rather than an empty stripe.
+  if (!rows.length || scrollHeight <= 0) {
+    rail.replaceChildren();
+    rail.hidden = true;
+    return 0;
+  }
+  const doc = container.ownerDocument;
+  rail.hidden = false;
+  // The rail spans the scroll viewport, which is only part of the positioned
+  // parent (the header and composer sit outside it).
+  rail.style.top = `${Number(container.offsetTop) || 0}px`;
+  rail.style.height = `${Number(container.clientHeight) || 0}px`;
+  const fragment = doc.createDocumentFragment();
+  for (const row of rows) {
+    const dot = doc.createElement('div');
+    const isCompact = row.dataset?.separatorKind === 'compact';
+    dot.className = `transcript-rail-dot${isCompact ? ' is-compact' : ''}`;
+    dot.style.top = `${((Number(row.offsetTop) || 0) / scrollHeight) * 100}%`;
+    dot.title = row.dataset?.separatorLabel || '';
+    fragment.appendChild(dot);
+  }
+  rail.replaceChildren(fragment);
+  return rows.length;
+}