@deepseek-ai/dsh-client-ui-trajectory 0.0.1-rc.1

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only trajectory plugin. */
+/** Provides no host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-trajectory`.
+* @module @deepseek-ai/dsh-client-ui-trajectory/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-trajectory";
+/** Cordis companion plugin name. */
+const name = "client-ui-trajectory-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a pure-consumer plugin — it emits no cordis events
+* and owns no mutable cross-plugin state; its view-slot registration is a
+* plain effect whose disposal the slot ledger's own specs and this
+* package's behavior specs observe directly.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/TrajectoryCell.d.ts

@@ -0,0 +1,10 @@
+import { formatElapsedSeconds, type TrajectoryCellProps } from './trajectory-record.ts';
+export { formatElapsedSeconds };
+export type { AssistantMetricDetail, TrajectoryCellKind, TrajectoryCellProps, } from './trajectory-record.ts';
+/**
+ * Render one trajectory step cell.
+ * @param props - index, kind, text, time, and optional Message metrics.
+ * @returns the cell element.
+ */
+export declare function TrajectoryCell({ index, kind, text, inputDetail: _inputDetail, promptDetail: _promptDetail, previousPromptDetail: _previousPromptDetail, outputDetail: _outputDetail, thinkingDetail: _thinkingDetail, sourceBlocks: _sourceBlocks, outputBlocks: _outputBlocks, schemaDetail: _schemaDetail, assistantMetrics: _assistantMetrics, result: _result, callId: _callId, isError: _isError, timeSeconds, startedAt: _startedAt, input, output, think, selected, className, ...rest }: TrajectoryCellProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryCell.d.ts.map

package/lib/types/client/TrajectoryGroupHeader.d.ts

@@ -0,0 +1,13 @@
+export interface TrajectoryGroupHeaderProps {
+    /** Group title (`Message`, `Step 1`, …). */
+    title: string;
+    /** Secondary summary (`49 s`, `2.2 s skill`, …). */
+    description?: string;
+}
+/**
+ * Render a Message/Step group header inside a turn body.
+ * @param props - title and optional description.
+ * @returns the group header element.
+ */
+export declare function TrajectoryGroupHeader({ title, description }: TrajectoryGroupHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryGroupHeader.d.ts.map

package/lib/types/client/TrajectoryTable.d.ts

@@ -0,0 +1,98 @@
+/** Turn-aware trajectory event ledger with a local record inspector. */
+import type { AssistantRequestConfig } from '@deepseek-ai/dsh-client-runtime/client';
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+import { type TrajectoryTurnModel } from './layout.ts';
+/** Props for the trajectory ledger. */
+export interface TrajectoryTableProps {
+    /** Session-global request numbers for the request groups visible in this context. */
+    requestNumbers?: readonly TrajectoryRequestNumber[];
+    /** Grouped records in display order. */
+    turns: readonly TrajectoryTurnModel[];
+    /** In-flight cells whose content replaces the matching structural record index. */
+    streamingCells?: readonly TrajectoryCellProps[];
+    /** Record indexes emphasized by the active timeline focus. */
+    timelineFocusIndexes?: ReadonlySet<number> | null;
+    /** Record indexes retained by the active live search, or null without a query. */
+    searchMatchIndexes?: ReadonlySet<number> | null;
+    /** Report the record currently selected in the local inspector. */
+    onSelectedIndexChange?: (index: number | null) => void;
+    /** Report a direct user selection from a ledger row. */
+    onRecordSelect?: (index: number) => void;
+    /** One externally requested record selection; a new object repeats the request. */
+    recordSelection?: {
+        readonly index: number;
+    } | null;
+    /** One externally requested record focus without changing inspector selection. */
+    recordFocus?: {
+        readonly index: number;
+    } | null;
+    /** Whether the initial history tail is still loading. */
+    historyLoading?: boolean;
+    /** First loaded raw event, used to preserve scroll position after prepending a page. */
+    historyStartSeq?: number | undefined;
+    /** Whether one older history page can be requested. */
+    hasOlderRecords?: boolean;
+    /** Load one older history page. */
+    onLoadOlder?: () => Promise<boolean>;
+    /** Clear selection state owned by the ledger host. */
+    onClearSelection?: () => void;
+    /** Turn ids whose rows after the first are folded into a summary. */
+    collapsedTurns: ReadonlySet<number>;
+    /** Toggle one turn between folded and expanded. */
+    onToggleTurn: (turn: number) => void;
+    /** Stable Assistant record ids whose tool calls are folded. */
+    collapsedAssistants: ReadonlySet<string>;
+    /** Toggle tool calls under one assistant record. */
+    onToggleAssistant: (id: string) => void;
+    /** One-shot cross-view inspect: open and scroll to this call's record. */
+    inspectCallId?: string | null;
+    /** Acknowledge a consumed (or unresolvable) inspect request. */
+    onInspectApplied?: (() => void) | undefined;
+}
+/** Request-inspector fields shared by ordinary generation and compaction. */
+interface TrajectoryRequestNumberBase {
+    /** Request anchor event sequence; absent for the currently streaming ordinary request. */
+    seq?: number;
+    group: string;
+    number: number;
+    status?: 'complete' | 'running' | 'error';
+    startedAt?: number;
+    completedAt?: number | null;
+    error?: string;
+    retry?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    resultSeq?: number;
+    provider?: string;
+    model?: string;
+    requestConfig?: AssistantRequestConfig;
+    usage?: TrajectoryUsage;
+    cumulativeUsage?: TrajectoryUsage;
+}
+/** One purpose-discriminated request identity paired with its session-global number. */
+export type TrajectoryRequestNumber = TrajectoryRequestNumberBase & ({
+    purpose?: 'assistant';
+    turn: number;
+    step: number;
+} | {
+    purpose: 'compaction';
+    turn: number | null;
+    step: 0;
+});
+/** Disjoint provider token buckets for one request or a session prefix. */
+export interface TrajectoryUsage {
+    input?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    output?: number;
+    reasoning?: number;
+}
+/**
+ * Render trajectory events as a dense ledger with turn and step separators.
+ * Clicking ledger whitespace clears the active record or request selection.
+ * @param props - Grouped trajectory data and whole-ledger fold state.
+ * @returns The ledger and an optional local record inspector.
+ */
+export declare function TrajectoryTable({ requestNumbers: sessionRequestNumbers, turns, streamingCells, timelineFocusIndexes, searchMatchIndexes, onSelectedIndexChange, onRecordSelect, recordSelection, recordFocus, historyLoading, historyStartSeq, hasOlderRecords, onLoadOlder, onClearSelection, collapsedTurns, onToggleTurn, collapsedAssistants, onToggleAssistant, inspectCallId, onInspectApplied, }: TrajectoryTableProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=TrajectoryTable.d.ts.map

package/lib/types/client/TrajectoryTimeline.d.ts

@@ -0,0 +1,24 @@
+/** Chrome-Network-style overview timeline for focusing the trajectory ledger. */
+import type { TrajectoryTurnModel } from './layout.ts';
+import { type TrajectoryTimelineMode, type TrajectoryTimeRange } from './timeline.ts';
+/** Props for the fixed full-domain overview above the trajectory ledger. */
+export interface TrajectoryTimelineProps {
+    turns: readonly TrajectoryTurnModel[];
+    mode: TrajectoryTimelineMode;
+    range: TrajectoryTimeRange | null;
+    /** Whether the loaded timeline omits an earlier history prefix. */
+    hasEarlierRecords?: boolean;
+    /** Load one earlier history page from the truncation control. */
+    onLoadEarlier?: () => Promise<boolean>;
+    selectedIndex?: number | null;
+    /** Record indexes matching the active ledger search, or null without a query. */
+    searchMatchIndexes?: ReadonlySet<number> | null;
+    onRangeChange: (range: TrajectoryTimeRange | null) => void;
+    /** Select a directly clicked timeline block. */
+    onRecordSelect?: (index: number) => void;
+    /** Bring the nearest record into view after clicking timeline whitespace. */
+    onRecordFocus?: (index: number) => void;
+}
+/** Overview renderer with drag ranges, click-sized focus, and Escape reset. */
+export declare const TrajectoryTimeline: import("react").MemoExoticComponent<({ turns, mode, range, hasEarlierRecords, onLoadEarlier, selectedIndex, searchMatchIndexes, onRangeChange, onRecordSelect, onRecordFocus, }: TrajectoryTimelineProps) => import("react").JSX.Element>;
+//# sourceMappingURL=TrajectoryTimeline.d.ts.map

package/lib/types/client/TrajectoryToolbar.d.ts

@@ -0,0 +1,30 @@
+/** Trajectory toolbar: timeline and ledger fold controls. */
+export interface TrajectoryToolbarProps {
+    /** Whether timeline blocks use recorded durations instead of equal widths. */
+    actualDuration: boolean;
+    /** Select recorded-duration or equal-width blocks. */
+    onActualDurationChange: (actualDuration: boolean) => void;
+    /** Whether recorded timing retains idle gaps between operations. */
+    actualTime: boolean;
+    /** Select complete wall-clock timing or idle-compressed timing. */
+    onActualTimeChange: (actualTime: boolean) => void;
+    /** Whether every collapsible turn is currently folded. */
+    allTurnsCollapsed: boolean;
+    /** Fold or expand every collapsible turn. */
+    onToggleAllTurns: () => void;
+    /** Whether every collapsible assistant's tool calls are currently folded. */
+    allAssistantsCollapsed: boolean;
+    /** Fold or expand tool calls under every collapsible assistant. */
+    onToggleAllAssistants: () => void;
+    /** Current live ledger search query. */
+    searchQuery: string;
+    /** Update the live ledger search query. */
+    onSearchQueryChange: (query: string) => void;
+}
+/**
+ * Render the sticky trajectory toolbar.
+ * @param props - rendered counts and whole-list fold state.
+ * @returns the toolbar element.
+ */
+export declare function TrajectoryToolbar({ actualDuration, onActualDurationChange, actualTime, onActualTimeChange, allTurnsCollapsed, onToggleAllTurns, allAssistantsCollapsed, onToggleAllAssistants, searchQuery, onSearchQueryChange, }: TrajectoryToolbarProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryToolbar.d.ts.map

package/lib/types/client/TrajectoryTurn.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export interface TrajectoryTurnProps {
+    /** 1-based turn index for the sticky header. */
+    turn: number;
+    /** Message / Step headers and TrajectoryCell rows. */
+    children?: ReactNode;
+}
+/**
+ * Render one turn section (sticky header + body).
+ * @param props - turn index and body children.
+ * @returns the turn section element.
+ */
+export declare function TrajectoryTurn({ turn, children }: TrajectoryTurnProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryTurn.d.ts.map

package/lib/types/client/TrajectoryTurnHeader.d.ts

@@ -0,0 +1,11 @@
+export interface TrajectoryTurnHeaderProps {
+    /** 1-based turn index shown as `Turn N`. */
+    turn: number;
+}
+/**
+ * Render the sticky turn header row.
+ * @param props.turn - turn index.
+ * @returns the sticky header element.
+ */
+export declare function TrajectoryTurnHeader({ turn }: TrajectoryTurnHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryTurnHeader.d.ts.map

package/lib/types/client/TrajectoryView.d.ts

@@ -0,0 +1,16 @@
+/** Trajectory view: compact summary over a turn-aware event ledger. */
+import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionHistoryFace, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** Session-history paging needed by the event-complete trajectory view. */
+export interface TrajectoryViewInjected {
+    hooks: {
+        history: SessionHistoryFace;
+        duration: SnapshotStore<boolean>;
+    };
+    loadHistoryTail: (signal: AbortSignal) => Promise<void>;
+    loadOlderHistory: (signal: AbortSignal) => Promise<boolean>;
+    setActualDuration: (actualDuration: boolean) => void;
+}
+export declare function TrajectoryView({ useHistory, useDuration, loadHistoryTail, loadOlderHistory, setActualDuration, inspect, onInspectDone, }: ConvViewProps & InjectFace<TrajectoryViewInjected>): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryView.d.ts.map

package/lib/types/client/context-branches.d.ts

@@ -0,0 +1,29 @@
+/** Rewind-delimited trajectory branches assembled across surface rewrites. */
+import type { ConversationContext, ConversationNode, RequestView } from '@deepseek-ai/dsh-client-runtime/client';
+/** One continuous context branch; compactions stay inline while rewinds start a successor branch. */
+export interface TrajectoryContextBranch {
+    id: number;
+    /** Identity stable when older context generations are prepended. */
+    key: string;
+    contexts: readonly ConversationContext[];
+    latest: ConversationContext;
+    nodes: readonly ConversationNode[];
+    /** Seq that opened this branch; earlier requests require retained cited surface events. */
+    startSeq: number;
+    /** Exact pre-rewind surface records inherited by this branch. */
+    retainedSurfaceSeqs: ReadonlySet<number>;
+}
+/**
+ * Join context generations across compaction/rewrite operations and split only at rewind.
+ * @param contexts - Append-only context generations from the runtime fold.
+ * @returns Rewind-delimited branches in creation order.
+ */
+export declare function deriveTrajectoryContextBranches(contexts: readonly ConversationContext[]): readonly TrajectoryContextBranch[];
+/**
+ * Test whether a provider request belongs to one rewind branch.
+ * @param branch - Branch carrying the exact inherited surface event seqs.
+ * @param request - Provider request to classify.
+ * @returns Whether the request began on this branch or produced a retained surface record.
+ */
+export declare function trajectoryBranchContainsRequest(branch: TrajectoryContextBranch, request: RequestView): boolean;
+//# sourceMappingURL=context-branches.d.ts.map

package/lib/types/client/duration-store.d.ts

@@ -0,0 +1,7 @@
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/**
+ * Create the browser-wide trajectory duration preference source.
+ * @returns a persisted source shared by every session view in one plugin lifecycle.
+ */
+export declare function createTrajectoryDurationStore(): SnapshotStore<boolean>;
+//# sourceMappingURL=duration-store.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser trajectory plugin contributing one entry to the conversation view
+ * slot without defining a service.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Required services: the conversation view slot and independent history source. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the trajectory view tab. The registration
+ * rides the slot service's effect wrapper, so plugin unload removes the tab.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/layout.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Trajectory list fold: expand assistant blocks, attach usage to Message,
+ * own-duration times, in-flight partial/runningCalls, and group descriptions.
+ */
+import type { ConversationSnapshot, RequestInspectionSnapshot, RequestView } from '@deepseek-ai/dsh-client-runtime/client';
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+/** One Message or Step group inside a turn. */
+export interface TrajectoryGroupModel {
+    title: string;
+    description?: string;
+    cells: readonly TrajectoryCellProps[];
+}
+/** One sticky turn, or a standalone compaction section between turns. */
+export interface TrajectoryTurnModel {
+    turn: number | null;
+    groups: readonly TrajectoryGroupModel[];
+}
+/** Snapshot slice the trajectory view folds. */
+export interface TrajectoryLayoutInput {
+    nodes: ConversationSnapshot['nodes'];
+    partial: ConversationSnapshot['partial'];
+    runningCalls: ConversationSnapshot['runningCalls'];
+    requests?: readonly RequestView[];
+    callSchemas?: RequestInspectionSnapshot['callSchemas'];
+}
+/**
+ * Fold a snapshot into turn → Message/Step groups with expanded cells.
+ * @param input - nodes plus in-flight partial/runningCalls.
+ * @returns turns ordered by first appearance.
+ */
+export declare function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly TrajectoryTurnModel[];
+/**
+ * Append the changing in-flight assistant cells to a stable finalized layout.
+ * @param turns - Finalized layout derived with an empty-block partial anchor.
+ * @param partial - Current in-flight assistant projection.
+ * @param lastIndex - Highest cell index in the finalized layout.
+ * @returns The original layout without a partial, otherwise a layout sharing every unaffected turn.
+ */
+export declare function appendTrajectoryPartialLayout(turns: readonly TrajectoryTurnModel[], partial: ConversationSnapshot['partial'], lastIndex: number): readonly TrajectoryTurnModel[];
+/**
+ * Build a bounded one-line ledger preview without parsing the complete Markdown document.
+ * Full source remains on the cell for the inspector.
+ * @param text - Untrusted message, reasoning, payload, or result text.
+ * @returns A compact preview capped independently from the retained source.
+ */
+export declare function trajectoryPreviewText(text: string): string;
+//# sourceMappingURL=layout.d.ts.map

package/lib/types/client/timeline.d.ts

@@ -0,0 +1,50 @@
+/** Operation-sequence and recorded-time projections for the trajectory overview. */
+import type { TrajectoryTurnModel } from './layout.ts';
+import type { TrajectoryCellKind } from './trajectory-record.ts';
+/** Horizontal projection used by the trajectory timeline. */
+export type TrajectoryTimelineMode = 'sequence' | 'duration' | 'time' | 'actual';
+/** Inclusive selection in the active timeline projection's domain. */
+export interface TrajectoryTimeRange {
+    start: number;
+    end: number;
+}
+/** One ledger record projected into the active timeline domain. */
+export interface TrajectoryTimelineSpan extends TrajectoryTimeRange {
+    index: number;
+    isError: boolean;
+    kind: TrajectoryCellKind;
+    label: string;
+    lane: number;
+}
+/** One turn boundary in the active timeline domain. */
+export interface TrajectoryTimelineTurnBoundary {
+    turn: number;
+    time: number;
+}
+/** Full-domain model used by the overview. */
+export interface TrajectoryTimelineModel extends TrajectoryTimeRange {
+    spans: readonly TrajectoryTimelineSpan[];
+    turnBoundaries: readonly TrajectoryTimelineTurnBoundary[];
+}
+/**
+ * Format a timeline duration as an integer-millisecond label.
+ * @param milliseconds - Non-negative duration in milliseconds.
+ * @returns Millisecond label with thousands separators.
+ */
+export declare function formatTimelineOffset(milliseconds: number): string;
+/**
+ * Project every visible record into a stable three-lane timeline.
+ * @param turns - Unfiltered trajectory layout.
+ * @param mode - Independent equal/recorded duration and compressed/complete time projection.
+ * @returns Timeline model, or `null` when no record is visible.
+ */
+export declare function deriveTrajectoryTimeline(turns: readonly TrajectoryTurnModel[], mode?: TrajectoryTimelineMode): TrajectoryTimelineModel | null;
+/**
+ * Identify records active at any point inside an inclusive selected interval.
+ * @param turns - Unfiltered trajectory layout.
+ * @param range - Selected interval in the active projection.
+ * @param mode - Independent equal/recorded duration and compressed/complete time projection.
+ * @returns Record indexes inside the focus interval.
+ */
+export declare function trajectoryTimelineFocusIndexes(turns: readonly TrajectoryTurnModel[], range: TrajectoryTimeRange, mode?: TrajectoryTimelineMode): ReadonlySet<number>;
+//# sourceMappingURL=timeline.d.ts.map

package/lib/types/client/trajectory-record.d.ts

@@ -0,0 +1,101 @@
+/** Shared trajectory record data and formatting contracts. */
+import type { HTMLAttributes } from 'react';
+import type { ConversationPromptSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+/** Closed set of trajectory record kinds. */
+export type TrajectoryCellKind = 'system' | 'user' | 'context' | 'compacted' | 'message' | 'tool' | 'subtool';
+/** Recorded inputs needed to derive assistant TTFT and decode throughput. */
+export interface AssistantMetricDetail {
+    timingRecorded: boolean;
+    stepStartTime: number | null;
+    firstTokenTime: number | null;
+    completedTime: number | null;
+    usageProvided: boolean;
+    outputTokens: number | null;
+}
+/** One source content block preserved in model order for the details panel. */
+export interface TrajectorySourceBlock {
+    type: string;
+    content: string;
+    imageSrc?: string;
+    imageAlt?: string;
+    callId?: string;
+    toolName?: string;
+}
+/** Data and optional presentation attributes for one trajectory record. */
+export interface TrajectoryCellProps extends HTMLAttributes<HTMLDivElement> {
+    /** 1-based record index shown as `#N`. */
+    index: number;
+    /** Projection-stable identity when no single source event owns the record lifecycle. */
+    recordId?: string;
+    kind: TrajectoryCellKind;
+    /** Single-line summary; CSS ellipsis when it overflows. */
+    text: string;
+    /** Whether this user record opens a new model turn. */
+    opensTurn?: boolean;
+    /** Source session-event seq for cross-record navigation. */
+    sourceSeq?: number;
+    /** Producer role and name from a user-role message or context injection. */
+    messageSource?: unknown;
+    /** Producer-owned model-hidden metadata carried beside the message source. */
+    /** A separator-only anchor for an auxiliary request with no visible record. */
+    requestOnly?: boolean;
+    /** Full request/message content for the details panel. */
+    inputDetail?: string;
+    /** Complete system-prompt/tool-catalog state introduced by a SYSTEM record. */
+    promptDetail?: ConversationPromptSnapshot;
+    /** System-prompt/tool-catalog state replaced by a SYSTEM update. */
+    previousPromptDetail?: ConversationPromptSnapshot;
+    /** Full assistant/tool result content for the details panel. */
+    outputDetail?: string;
+    /** Full assistant reasoning content for the details panel. */
+    thinkingDetail?: string;
+    /** Original message blocks in source order for the details panel. */
+    sourceBlocks?: readonly TrajectorySourceBlock[];
+    /** Original tool result blocks in source order for the details panel. */
+    outputBlocks?: readonly TrajectorySourceBlock[];
+    /** Call-time model-visible tool schema for the details panel. */
+    schemaDetail?: string;
+    /** Assistant-only timing and token facts for the details panel. */
+    assistantMetrics?: AssistantMetricDetail;
+    /** Tool-only result summary paired with the call in the same record. */
+    result?: string;
+    /** Tool call id used to link message source blocks to tool records. */
+    callId?: string;
+    /** Tool-only result failure state. */
+    isError?: boolean;
+    /** Own duration in seconds, or `null` when no duration is known. */
+    timeSeconds: number | null;
+    /** Unix epoch milliseconds when this operation actually started, when known. */
+    startedAt?: number | null;
+    /** Message-only prompt token count. */
+    input?: number;
+    /** Message-only input tokens served from a provider cache. */
+    cacheRead?: number;
+    /** Message-only input tokens written into a provider cache. */
+    cacheWrite?: number;
+    /** Message-only completion token count. */
+    output?: number;
+    /** Message-only reasoning token count. */
+    think?: number;
+    /** Whether the legacy standalone cell renders its selection treatment. */
+    selected?: boolean;
+}
+/**
+ * Resolve the identity that survives prepending older projected records.
+ * @param cell - Projected trajectory record.
+ * @returns Stable identity from the owning event or tool call, with a fixture fallback.
+ */
+export declare function trajectoryRecordId(cell: TrajectoryCellProps): string;
+/**
+ * Format a duration in milliseconds with thousands separators.
+ * @param milliseconds - Duration in milliseconds, or `null` when absent.
+ * @returns `—` when unknown, otherwise an integer-millisecond label.
+ */
+export declare function formatDurationMillis(milliseconds: number | null): string;
+/**
+ * Format an elapsed duration given in seconds as a millisecond label.
+ * @param seconds - Duration seconds, or `null` when absent.
+ * @returns `—` when unknown, otherwise an integer-millisecond label.
+ */
+export declare function formatElapsedSeconds(seconds: number | null): string;
+//# sourceMappingURL=trajectory-record.d.ts.map

package/lib/types/client/trajectory-virtual-rows.d.ts

@@ -0,0 +1,34 @@
+/** Pure projection from trajectory records to measurable virtual ledger rows. */
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+/** Minimal record shape required by the trajectory virtual-row projection. */
+export interface VirtualizableTrajectoryRecord {
+    cell: TrajectoryCellProps;
+    collapsedSummaryKind?: 'turn' | 'assistant';
+}
+/** One logical record retained inside a measurable virtual row. */
+export interface TrajectoryVirtualRowEntry<T extends VirtualizableTrajectoryRecord> {
+    logicalIndex: number;
+    record: T;
+}
+/** One virtualizer item, which may carry zero-height request boundaries. */
+export interface TrajectoryVirtualRow<T extends VirtualizableTrajectoryRecord> {
+    entries: readonly TrajectoryVirtualRowEntry<T>[];
+    height: number;
+    key: string;
+}
+/**
+ * Derive the DOM-safe row identity shared by React, the virtualizer, and
+ * browser scroll contracts.
+ * @param record - Display record whose identity is required.
+ * @returns Stable record identity with a suffix for synthetic fold summaries.
+ */
+export declare function trajectoryVirtualRecordKey(record: VirtualizableTrajectoryRecord): string;
+/**
+ * Attach separator-only records to the next content row so the virtualizer
+ * never owns a zero-height item. A terminal separator retains its CSS-owned
+ * lower-marker clearance as a standalone item.
+ * @param records - Final search/fold projection in ledger order.
+ * @returns Measurable virtual rows with original logical positions retained.
+ */
+export declare function groupTrajectoryVirtualRows<T extends VirtualizableTrajectoryRecord>(records: readonly T[]): readonly TrajectoryVirtualRow<T>[];
+//# sourceMappingURL=trajectory-virtual-rows.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only trajectory plugin. */
+/** Provides no host-side behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-trajectory`.
+ * @module @deepseek-ai/dsh-client-ui-trajectory/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-trajectory-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-trajectory",
+  "description": "Trajectory event ledger with an interactive timing overview: pure-consumer plugin registering into the conversation ViewMap (no service)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-trajectory"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@tanstack/react-virtual": "^3.14.9",
+    "diff": "^9.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}