@oh-my-pi/omp-stats 18.13.3 → 18.14.1

package/dist/types/chunked-insert.d.ts

@@ -0,0 +1,32 @@
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+/** Shape of one ingest table write; see {@link ChunkedInsert}. */
+export interface ChunkedInsertSpec {
+    /** `INSERT` or `INSERT OR IGNORE`. */
+    verb: "INSERT" | "INSERT OR IGNORE";
+    table: string;
+    columns: readonly string[];
+    /** Columns naming one transcript entry; fork copies repeat them under another `session_file`. */
+    identity: readonly string[];
+    /** Trailing `ON CONFLICT … DO UPDATE` clause, if any. */
+    upsert?: string;
+}
+/**
+ * Multi-row writer for one ingest table: buffers rows and writes them as
+ * `INSERT … VALUES (…), (…)` chunks, so the per-statement costs (trigger
+ * program setup, statement journal, the temp b-tree SQLite stages trigger
+ * inserts through) are paid per chunk instead of per row.
+ *
+ * Every row passes a first-writer-wins fork guard: forked transcripts copy
+ * their parent's entries verbatim, so a row whose identity another
+ * `session_file` already stored is skipped. Buffered rows are invisible to
+ * that lookup, so a row colliding with a buffered row of another transcript
+ * flushes the buffer first; the stored outcome equals writing row by row.
+ */
+export declare class ChunkedInsert {
+    #private;
+    constructor(database: Database, spec: ChunkedInsertSpec);
+    /** Buffer one row unless another transcript already owns `identity`. */
+    add(sessionFile: string, identity: readonly SQLQueryBindings[], values: readonly SQLQueryBindings[]): void;
+    /** Write the remaining rows; returns how many stored rows the writer inserted or updated. */
+    finish(): number;
+}

package/dist/types/client/traces/SpanDrawer.d.ts

@@ -1,14 +1,20 @@
 /**
- * Detail drawer for a selected trace span. Fetches the full journal entry on
- * demand (`/api/session/entry`) and renders per-kind detail: model usage grid
+ * Detail drawer for a selected trace span. Loads the full journal entry on
+ * demand (live API or embedded snapshot) and renders per-kind detail: model usage grid
  * + text blocks, tool args/result, user text, subagent task text.
  */
 import type { TraceSpan, TraceTrack } from "../types.js";
+export type TraceEntryLoader = (file: string, entryId: string, signal: AbortSignal) => Promise<{
+    entry: unknown;
+}>;
 export interface SpanDrawerProps {
     span: TraceSpan | null;
     track: TraceTrack | null;
     onClose: () => void;
     /** Selects the first span of the given child track ("open child track"). */
     onOpenChildTrack?: (childTrackId: string) => void;
+    loadEntry?: TraceEntryLoader;
+    inline?: boolean;
+    onNavigate?: (trackId: string, entryId: string) => void;
 }
-export declare function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawerProps): import("react").JSX.Element | null;
+export declare function SpanDrawer({ span, track, onClose, onOpenChildTrack, loadEntry, inline, onNavigate, }: SpanDrawerProps): import("react").JSX.Element | null;

package/dist/types/client/traces/TimelineCanvas.d.ts

@@ -27,6 +27,8 @@ export interface TimelineCanvasProps {
     collapsed: ReadonlySet<string>;
     onToggleCollapse: (trackId: string) => void;
     traceStart: number;
+    /** Live route focuses immediately; embedded viewers wait for user interaction. */
+    autoFocus?: boolean;
 }
 /** Per-lane span positions on the virtual axis, parallel to `LaneRow.spans`. */
 interface LaneAxis {
@@ -42,5 +44,5 @@ export declare function buildLaneAxes(layout: {
 }, scale: Pick<TraceScale, "toU">): LaneAxis[];
 /** First index whose running-max end reaches `u0`: every earlier span ends before the viewport. */
 export declare function firstVisible(maxEndU: Float64Array, u0: number): number;
-export declare function TimelineCanvas({ tracks, scale, viewport, onViewportChange, selected, onSelect, matchIds, collapsed, onToggleCollapse, traceStart, }: TimelineCanvasProps): import("react").JSX.Element;
+export declare function TimelineCanvas({ tracks, scale, viewport, onViewportChange, selected, onSelect, matchIds, collapsed, onToggleCollapse, traceStart, autoFocus, }: TimelineCanvasProps): import("react").JSX.Element;
 export {};

package/dist/types/client/traces/TraceView.d.ts

@@ -3,9 +3,22 @@
  * flamegraph canvas, transcript list, tool aggregates, and the span drawer.
  * Owns the shared viewport/selection state so all pieces stay in sync.
  */
+import type { SessionTrace } from "../types.js";
+import { type TraceEntryLoader } from "./SpanDrawer.js";
 export interface TraceViewProps {
     file: string;
     active: boolean;
     onBack: () => void;
 }
 export declare function TraceView({ file, active, onBack }: TraceViewProps): import("react").JSX.Element;
+/** Data and host integration supplied to the shared live/offline trace viewer. */
+export interface SessionTraceViewProps {
+    trace: SessionTrace;
+    view?: "timeline" | "full";
+    loadEntry?: TraceEntryLoader;
+    /** Embedded viewers keep details inside their own layout, without a modal. */
+    embedded?: boolean;
+    onNavigate?: (trackId: string, entryId: string) => void;
+}
+/** Data-driven viewer shared by the live route and self-contained HTML exports. */
+export declare function SessionTraceView({ trace, view, loadEntry, embedded, onNavigate, }: SessionTraceViewProps): import("react").JSX.Element;

package/dist/types/client/traces/index.d.ts

@@ -0,0 +1,5 @@
+/** Shared trace UI for live dashboards and embedded offline viewers. */
+export type { SessionTrace } from "../types.js";
+export type { TraceEntryLoader } from "./SpanDrawer.js";
+export { SessionTraceView, type SessionTraceViewProps } from "./TraceView.js";
+export { TraceThemeRoot } from "./trace-colors.js";

package/dist/types/client/traces/trace-colors.d.ts

@@ -3,6 +3,8 @@
  * design tokens so canvas drawing follows the active theme.
  */
 import type { TraceSpanKind } from "../types.js";
+/** Embedded viewers resolve canvas colors from their scoped style root. */
+export declare const TraceThemeRoot: import("react").Context<HTMLElement | null>;
 export interface TraceTheme {
     /** Span fill per category. */
     category: Record<TraceSpanKind, string>;
@@ -32,6 +34,6 @@ export interface TraceTheme {
 export declare const CATEGORY_VARS: Record<TraceSpanKind, string>;
 /**
  * Current trace palette. Re-reads the tokens whenever the resolved theme
- * changes (store or a direct `data-theme` attribute write).
+ * changes, without loading the live dashboard's theme preference store.
  */
 export declare function useTraceTheme(): TraceTheme;

package/dist/types/client/ui/SearchInput.d.ts

@@ -2,7 +2,8 @@ export interface SearchInputProps {
     value: string;
     onChange: (value: string) => void;
     placeholder?: string;
+    label?: string;
     width?: number;
 }
 /** Text filter with a leading search glyph. */
-export declare function SearchInput({ value, onChange, placeholder, width }: SearchInputProps): import("react").JSX.Element;
+export declare function SearchInput({ value, onChange, placeholder, label, width }: SearchInputProps): import("react").JSX.Element;

package/dist/types/db.d.ts

@@ -77,7 +77,7 @@ export declare function completeSessionSync(reconcile: boolean): void;
  * `provider`, token counts, and `responseId`. The `UNIQUE(session_file,
  * entry_id)` constraint alone keys each row by file, so without the guard
  * below the same provider request would land twice and inflate every
- * aggregate. The `WHERE NOT EXISTS` clause skips inserts whose
+ * aggregate. The {@link ChunkedInsert} fork guard skips inserts whose
  * `(entry_id, timestamp)` already exists under a different `session_file` —
  * first-write-wins across the lineage. Same-file re-syncs still hit the
  * `ON CONFLICT(session_file, entry_id)` upsert below, which re-derives the
@@ -111,9 +111,9 @@ export declare function getDailyActivity(days?: number): Promise<DailyActivityPo
 export declare function markSessionBackfillsComplete(): void;
 /**
  * Insert user-message stats. Idempotent via UNIQUE(session_file, entry_id).
- * The `WHERE NOT EXISTS` clause matches {@link insertMessageStats}: forks
- * copy user entries verbatim into the child JSONL, so the same
- * `(entry_id, timestamp)` must not land twice across different session files.
+ * The fork guard matches {@link insertMessageStats}: forks copy user entries
+ * verbatim into the child JSONL, so the same `(entry_id, timestamp)` must not
+ * land twice across different session files.
  */
 export declare function insertUserMessageStats(stats: Iterable<UserMessageStats>): number;
 /**
@@ -172,7 +172,7 @@ export declare function getPendingFrustrationTotals(cutoff?: number | null): {
 export declare function upsertFrustrationVerdicts(verdicts: readonly FrustrationVerdict[]): void;
 /**
  * Insert tool-call rows. Idempotent via UNIQUE(session_file, tool_call_id);
- * the `WHERE NOT EXISTS` guard mirrors {@link insertMessageStats}: forked
+ * the fork guard mirrors {@link insertMessageStats}: forked
  * sessions deep-copy assistant entries (same `entry_id`, `timestamp`, and
  * tool-call ids under a new file), so first-write-wins across the lineage
  * keeps aggregates from double counting. Keyed on the assistant entry

package/dist/types/port-conflict.d.ts

@@ -7,10 +7,16 @@ export declare const STATS_DASHBOARD_SECURITY_VERSION = "3";
 /** IPv4 loopback address shared by the dashboard server and reuse probe. */
 export declare const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
 /**
- * Reuse a secure dashboard or reclaim an insecure HTTP dashboard before binding.
+ * How {@link startServer} proceeds with the requested port: bind it, reuse the
+ * dashboard already serving it, or fall back to an ephemeral port because the
+ * holder is neither reusable nor safe to stop.
+ */
+export type StatsPortClaim = "bind" | "reuse" | "fallback";
+/**
+ * Reuse a current dashboard, or upgrade an older one, before binding.
  * The preflight is needed on platforms that permit wildcard and loopback-specific
  * listeners to coexist on one port.
  */
-export declare function prepareStatsPort(port: number, hostname?: string): Promise<"retry" | "reuse">;
+export declare function prepareStatsPort(port: number, hostname?: string): Promise<StatsPortClaim>;
 /** Reuse or reclaim a listener found after the server bind reports EADDRINUSE. */
-export declare function recoverStatsPort(port: number, hostname?: string): Promise<"retry" | "reuse">;
+export declare function recoverStatsPort(port: number, hostname?: string): Promise<StatsPortClaim>;

package/dist/types/server.d.ts

@@ -5,9 +5,7 @@ import { type StatsJudgeProvider } from "./frustration.js";
 export declare function handleApi(req: Request): Promise<Response>;
 /** Format a dashboard origin, including brackets required by IPv6 literals. */
 export declare function formatStatsDashboardUrl(hostname: string, port: number): string;
-/**
- * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
- */
+/** A dashboard this process started or found; `port` is where it listens, which may differ from the one requested. */
 export interface StatsServerHandle {
     hostname: string;
     port: number;
@@ -17,4 +15,10 @@ export interface StartServerOptions {
     /** Host judge for the Frustration dashboard's judge runs; replaces any previously registered one. */
     judge?: StatsJudgeProvider;
 }
+/**
+ * Start the dashboard on `port`, or reuse the current dashboard already serving it.
+ * An older dashboard there is stopped and replaced; any other holder (a foreign
+ * program, or a dashboard too busy to answer the identity probe) is left running
+ * and the dashboard binds an ephemeral port instead.
+ */
 export declare function startServer(port?: number, hostname?: string, options?: StartServerOptions): Promise<StatsServerHandle>;

package/dist/types/shared-types.d.ts

@@ -566,7 +566,7 @@ export interface TraceTrack {
     agent: string | null;
     /** session_init.resolvedModel ?? first assistant model. */
     model: string | null;
-    /** Absolute transcript path (for entry fetch). */
+    /** Absolute transcript path for live entry fetch, or the embedded snapshot key. */
     file: string;
     /** Sorted by start. */
     spans: TraceSpan[];
@@ -607,12 +607,13 @@ export interface SessionTrace {
     cwd: string | null;
     startedAt: number;
     endedAt: number;
-    /** Root transcript mtime; doubles as the ETag. */
+    /** Root transcript mtime, or recorded root activity/header time for offline snapshots. */
     mtimeMs: number;
     /**
      * Conditional-request fingerprint `"<rootMs>:<childHighMs>"` (see
      * traceFingerprintForEtag): the server ETag is built from this, so a
      * subagent-only append changes the ETag even when the root is untouched.
+     * Offline snapshots use "snapshot" and do not support HTTP revalidation.
      */
     etag: string;
     /** DFS order, main first. */

package/dist/types/trace.d.ts

@@ -17,7 +17,7 @@ export declare class TracePathError extends Error {
  * span assembly changes so browsers don't revalidate stale cached bodies
  * against an unchanged transcript mtime.
  */
-export declare const TRACE_ETAG_VERSION = 3;
+export declare const TRACE_ETAG_VERSION = 4;
 /** Freshness of a root trace: root mtime plus the child-transcript set fingerprint. */
 export interface TraceFingerprint {
     rootMtimeMs: number;
@@ -42,6 +42,32 @@ export declare function traceMemoForTests(): {
  * file (its ETag pre-check), sparing a second walk.
  */
 export declare function buildSessionTrace(fileParam: string, fingerprint?: TraceFingerprint): Promise<SessionTrace>;
+/** Header metadata used by snapshot traces, including journals without a schema version. */
+export interface TraceSnapshotHeader {
+    timestamp?: string;
+    cwd?: string;
+    title?: string;
+}
+/** The journal data for one embedded transcript; its header may be stored separately. */
+export interface SessionTraceSnapshot {
+    header?: TraceSnapshotHeader | null;
+    entries: readonly SessionEntry[];
+}
+/** A collected child transcript, keyed by its slash-joined path from the root. */
+export interface SubSessionTraceSnapshot extends SessionTraceSnapshot {
+    parent: string | null;
+}
+/**
+ * Assemble an offline trace using the same timing joins and rollups as the live
+ * filesystem builder. Only supplied snapshots participate: no filesystem, DB,
+ * network, or wall-clock reads. Track files are snapshot keys, never disk paths.
+ *
+ * Missing parent transcripts attach their readable descendants to main. Unlike
+ * filesystem discovery, already-collected snapshots need no depth limit.
+ * `mtimeMs` is the root's last activity (or header time, then 0); the constant
+ * `etag` identifies a snapshot, not a conditional HTTP response.
+ */
+export declare function buildSessionTraceFromSnapshots(root: SessionTraceSnapshot, subSessions?: Readonly<Record<string, SubSessionTraceSnapshot>>): SessionTrace;
 /** Fetch one full journal entry by id from a transcript, for the span drawer. */
 export declare function getTraceEntry(fileParam: string, entryId: string): Promise<SessionEntry | null>;
 /**

package/dist/types/types.d.ts

@@ -216,11 +216,16 @@ export interface ToolCallStats {
     callsInTurn: number;
     /** Serialized argument characters */
     argsChars: number;
+    /** Result text characters, when the same parse also read the call's `toolResult` */
+    resultChars?: number;
+    /** Result error flag, set together with `resultChars` */
+    isError?: boolean;
 }
 /**
  * Result linkage emitted when the parser sees a `toolResult` message entry.
  * Applied as an UPDATE on the persisted tool-call row — results can land in a
- * later incremental sync pass than the call that produced them.
+ * later incremental sync pass than the call that produced them (calls parsed
+ * in the same pass already carry the result, so their UPDATE is a no-op).
  */
 export interface ToolResultLink {
     sessionFile: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "18.13.3",
+	"version": "18.14.1",
 	"description": "Local observability dashboard for omp AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -42,9 +42,9 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.13.3",
-		"@oh-my-pi/pi-catalog": "18.13.3",
-		"@oh-my-pi/pi-utils": "18.13.3",
+		"@oh-my-pi/pi-ai": "18.14.1",
+		"@oh-my-pi/pi-catalog": "18.14.1",
+		"@oh-my-pi/pi-utils": "18.14.1",
 		"lucide-react": "^1.24.0",
 		"react": "19.2.7",
 		"react-dom": "19.2.7"
@@ -63,7 +63,6 @@
 		"README.md",
 		"CHANGELOG.md",
 		"LICENSE",
-		"THIRD-PARTY-NOTICES.txt",
 		"dist/types",
 		"dist/client"
 	],
@@ -80,6 +79,12 @@
 			"types": "./dist/types/client/index.d.ts",
 			"import": "./src/client/index.tsx"
 		},
+		"./client/traces": {
+			"types": "./dist/types/client/traces/index.d.ts",
+			"import": "./src/client/traces/index.ts"
+		},
+		"./client/styles.css": "./src/client/styles.css",
+		"./client/traces/traces.css": "./src/client/traces/traces.css",
 		"./client/*": {
 			"types": "./dist/types/client/*.d.ts",
 			"import": "./src/client/*.ts"

package/src/chunked-insert.ts

@@ -0,0 +1,89 @@
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+
+/** Bind parameters per statement; SQLite builds older than 3.32 cap a statement at 999. */
+const MAX_BINDS = 999;
+
+/** Shape of one ingest table write; see {@link ChunkedInsert}. */
+export interface ChunkedInsertSpec {
+	/** `INSERT` or `INSERT OR IGNORE`. */
+	verb: "INSERT" | "INSERT OR IGNORE";
+	table: string;
+	columns: readonly string[];
+	/** Columns naming one transcript entry; fork copies repeat them under another `session_file`. */
+	identity: readonly string[];
+	/** Trailing `ON CONFLICT … DO UPDATE` clause, if any. */
+	upsert?: string;
+}
+
+/**
+ * Multi-row writer for one ingest table: buffers rows and writes them as
+ * `INSERT … VALUES (…), (…)` chunks, so the per-statement costs (trigger
+ * program setup, statement journal, the temp b-tree SQLite stages trigger
+ * inserts through) are paid per chunk instead of per row.
+ *
+ * Every row passes a first-writer-wins fork guard: forked transcripts copy
+ * their parent's entries verbatim, so a row whose identity another
+ * `session_file` already stored is skipped. Buffered rows are invisible to
+ * that lookup, so a row colliding with a buffered row of another transcript
+ * flushes the buffer first; the stored outcome equals writing row by row.
+ */
+export class ChunkedInsert {
+	readonly #database: Database;
+	readonly #spec: ChunkedInsertSpec;
+	readonly #chunkRows: number;
+	readonly #chunkSql: string;
+	readonly #claimed: string;
+	#params: SQLQueryBindings[] = [];
+	#rows = 0;
+	/** Identity → `session_file` of each buffered row. */
+	#buffered = new Map<string, string>();
+	#changes = 0;
+
+	constructor(database: Database, spec: ChunkedInsertSpec) {
+		this.#database = database;
+		this.#spec = spec;
+		this.#chunkRows = Math.floor(MAX_BINDS / spec.columns.length);
+		this.#chunkSql = this.#sql(this.#chunkRows);
+		this.#claimed = `SELECT 1 FROM ${spec.table} WHERE ${spec.identity.map(column => `${column} = ?`).join(" AND ")} AND session_file <> ? LIMIT 1`;
+	}
+
+	/** Buffer one row unless another transcript already owns `identity`. */
+	add(sessionFile: string, identity: readonly SQLQueryBindings[], values: readonly SQLQueryBindings[]): void {
+		const key = identity.join("\0");
+		const owner = this.#buffered.get(key);
+		if (owner !== sessionFile) {
+			if (owner !== undefined) this.#flush();
+			if (this.#database.query(this.#claimed).get(...identity, sessionFile)) return;
+			this.#buffered.set(key, sessionFile);
+		}
+		for (const value of values) this.#params.push(value);
+		if (++this.#rows === this.#chunkRows) this.#flush();
+	}
+
+	/** Write the remaining rows; returns how many stored rows the writer inserted or updated. */
+	finish(): number {
+		this.#flush();
+		return this.#changes;
+	}
+
+	#flush(): void {
+		if (this.#rows === 0) return;
+		if (this.#rows === this.#chunkRows) {
+			this.#changes += this.#database.query(this.#chunkSql).run(...this.#params).changes;
+		} else {
+			// Partial chunks vary in size; keep them out of the statement cache.
+			using statement = this.#database.prepare(this.#sql(this.#rows));
+			this.#changes += statement.run(...this.#params).changes;
+		}
+		this.#params = [];
+		this.#rows = 0;
+		this.#buffered.clear();
+	}
+
+	#sql(rows: number): string {
+		const { verb, table, columns, upsert } = this.#spec;
+		const row = `(${columns.map(() => "?").join(", ")})`;
+		const values = Array.from({ length: rows }, () => row).join(", ");
+		return `${verb} INTO ${table} (${columns.join(", ")}) VALUES ${values}${upsert ? ` ${upsert}` : ""}`;
+	}
+}

package/src/client/traces/SpanDrawer.tsx

@@ -1,15 +1,17 @@
 /**
- * Detail drawer for a selected trace span. Fetches the full journal entry on
- * demand (`/api/session/entry`) and renders per-kind detail: model usage grid
+ * Detail drawer for a selected trace span. Loads the full journal entry on
+ * demand (live API or embedded snapshot) and renders per-kind detail: model usage grid
  * + text blocks, tool args/result, user text, subagent task text.
  */
 
-import { Check, Copy } from "lucide-react";
+import { Check, Copy, X } from "lucide-react";
 import { type ReactNode, useEffect, useRef, useState } from "react";
 import { getSessionEntryDetail } from "../api";
 import { formatDurationMs, formatInteger } from "../data/formatters";
 import type { TraceSpan, TraceTrack } from "../types";
-import { Badge, Drawer, ErrorState, JsonBlock, KeyValues, Skeleton } from "../ui";
+import { Badge, Drawer, type DrawerProps, ErrorState, JsonBlock, KeyValues, Skeleton } from "../ui";
+
+export type TraceEntryLoader = (file: string, entryId: string, signal: AbortSignal) => Promise<{ entry: unknown }>;
 
 export interface SpanDrawerProps {
 	span: TraceSpan | null;
@@ -17,6 +19,9 @@ export interface SpanDrawerProps {
 	onClose: () => void;
 	/** Selects the first span of the given child track ("open child track"). */
 	onOpenChildTrack?: (childTrackId: string) => void;
+	loadEntry?: TraceEntryLoader;
+	inline?: boolean;
+	onNavigate?: (trackId: string, entryId: string) => void;
 }
 
 /** Loose structural view of a fetched journal entry (validated field-by-field). */
@@ -60,7 +65,33 @@ function textBlocks(content: unknown): Array<{ kind: string; text: string }> {
 	return blocks;
 }
 
-export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawerProps) {
+function InlineSpanDetail({ title, subtitle, actions, onClose, children }: DrawerProps) {
+	return (
+		<section className="traces-inline-detail" aria-label="Selected span details">
+			<header className="drawer-header">
+				<div className="drawer-titles">
+					<h2 className="drawer-title">{title}</h2>
+					{subtitle !== undefined && <div className="drawer-subtitle">{subtitle}</div>}
+				</div>
+				{actions}
+				<button type="button" className="btn" data-icon="true" onClick={onClose} aria-label="Close span details">
+					<X size={16} />
+				</button>
+			</header>
+			<div className="drawer-body">{children}</div>
+		</section>
+	);
+}
+
+export function SpanDrawer({
+	span,
+	track,
+	onClose,
+	onOpenChildTrack,
+	loadEntry = getSessionEntryDetail,
+	inline = false,
+	onNavigate,
+}: SpanDrawerProps) {
 	const [entry, setEntry] = useState<unknown>(null);
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState<Error | null>(null);
@@ -75,7 +106,7 @@ export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawe
 		if (!span || !track || !span.entryId) return;
 		setLoading(true);
 		const controller = new AbortController();
-		getSessionEntryDetail(track.file, span.entryId, controller.signal)
+		loadEntry(track.file, span.entryId, controller.signal)
 			.then(data => {
 				if (!controller.signal.aborted) setEntry(data.entry);
 			})
@@ -87,7 +118,7 @@ export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawe
 				if (!controller.signal.aborted) setLoading(false);
 			});
 		return () => controller.abort();
-	}, [span, track]);
+	}, [span, track, loadEntry]);
 
 	useEffect(() => () => window.clearTimeout(copyResetRef.current), []);
 
@@ -151,8 +182,10 @@ export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawe
 			metrics.push({ key: "stop", label: "Stop reason", value: <span className="mono">{msg.stopReason}</span> });
 	}
 
+	const DetailShell = inline ? InlineSpanDetail : Drawer;
+
 	return (
-		<Drawer
+		<DetailShell
 			open
 			onClose={onClose}
 			title={span.label}
@@ -179,6 +212,20 @@ export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawe
 		>
 			<div className="stack traces-drawer">
 				<KeyValues items={metrics} />
+				{onNavigate && track && span.entryId && (
+					<div>
+						<button
+							type="button"
+							className="btn"
+							data-size="sm"
+							onClick={() => {
+								if (span.entryId) onNavigate(track.id, span.entryId);
+							}}
+						>
+							Jump to transcript
+						</button>
+					</div>
+				)}
 
 				{msg?.errorMessage && (
 					<div className="stack" style={{ gap: 6 }}>
@@ -238,6 +285,6 @@ export function SpanDrawer({ span, track, onClose, onOpenChildTrack }: SpanDrawe
 
 				{!loading && entry !== null && <JsonBlock data={entry} title="Raw entry" initialCollapsed={true} />}
 			</div>
-		</Drawer>
+		</DetailShell>
 	);
 }

package/src/client/traces/TimelineCanvas.tsx

@@ -32,6 +32,8 @@ export interface TimelineCanvasProps {
 	collapsed: ReadonlySet<string>;
 	onToggleCollapse: (trackId: string) => void;
 	traceStart: number;
+	/** Live route focuses immediately; embedded viewers wait for user interaction. */
+	autoFocus?: boolean;
 }
 
 const RULER_H = 28;
@@ -222,6 +224,7 @@ export function TimelineCanvas({
 	collapsed,
 	onToggleCollapse,
 	traceStart,
+	autoFocus = true,
 }: TimelineCanvasProps) {
 	const colors = useTraceTheme();
 	const containerRef = useRef<HTMLDivElement>(null);
@@ -463,12 +466,12 @@ export function TimelineCanvas({
 				return;
 		}
 		event.preventDefault();
+		event.stopPropagation();
 	};
 
-	// Focus the canvas on mount so keyboard navigation works immediately.
 	useEffect(() => {
-		canvasRef.current?.focus({ preventScroll: true });
-	}, []);
+		if (autoFocus) canvasRef.current?.focus({ preventScroll: true });
+	}, [autoFocus]);
 
 	// Scene: everything except hover/selection, so pointer moves never repaint it.
 	useEffect(() => {
@@ -603,7 +606,13 @@ export function TimelineCanvas({
 				)}
 			</div>
 
-			{tooltip && createPortal(tooltip, document.body)}
+			{tooltip &&
+				createPortal(
+					tooltip,
+					containerRef.current?.getRootNode() instanceof ShadowRoot
+						? (containerRef.current.getRootNode() as ShadowRoot)
+						: document.body,
+				)}
 		</div>
 	);
 }