@qilin-agent/client-ui-trajectory 0.0.0-stage → 3.1.3

package/lib/types/client/trajectory-graph-layout.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure layout for the trajectory graph: ledger order becomes the vertical axis
+ * and the actor swimlane becomes the horizontal one, so the agent loop reads as
+ * the curve that leaves the tool lane and comes back to the model lane.
+ *
+ * Three lanes run top to bottom, time flowing downward:
+ *
+ *   input (user, context)   model (request, assistant)   tool (calls, results)
+ *
+ * Every row holds exactly one record, and a turn boundary reserves a header
+ * band above its first row. The layout adapts to its canvas: lane centers
+ * stretch with the requested width while the chips grow at half that rate, so
+ * a wide pane spreads the swimlanes apart instead of stretching the chips
+ * across them. The module decides row heights, lane positions, nested-call
+ * offsets, band extents, and one cubic path per edge. It decides no
+ * copy and no colour, so it stays free of React and of the locale dictionaries
+ * and runs in a plain Node environment.
+ */
+import type { TrajectoryGraph, TrajectoryGraphEdgeKind, TrajectoryGraphNode } from './trajectory-graph.ts';
+/** Geometry overrides for one layout pass. */
+export interface TrajectoryGraphLayoutOptions {
+    /** Virtual canvas width in SVG user units, clamped into `DEFAULTS.width`..`WIDTH_MAX`. */
+    width?: number;
+    /** Vertical pitch of one record row. */
+    rowHeight?: number;
+    /** Node height. */
+    nodeHeight?: number;
+    /** Vertical space one turn header reserves. */
+    bandHeight?: number;
+    /** Space above the first row and below the last. */
+    padding?: number;
+}
+/** One positioned record. */
+export interface LaidOutGraphNode {
+    /** The record this node draws. */
+    readonly node: TrajectoryGraphNode;
+    /** The record's row, in ledger order — the replay cursor walks these. */
+    readonly index: number;
+    /** Left edge. */
+    readonly x: number;
+    /** Top edge. */
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** One routed edge. */
+export interface LaidOutGraphEdge {
+    readonly id: string;
+    readonly kind: TrajectoryGraphEdgeKind;
+    /** Whether the edge still carries moving data, which drives its animation. */
+    readonly live: boolean;
+    readonly from: string;
+    readonly to: string;
+    /** SVG path data, also usable as the motion path of a flowing packet. */
+    readonly d: string;
+}
+/** One placed turn band. */
+export interface LaidOutBand {
+    /** Turn number, or null for records outside every turn. */
+    readonly turn: number | null;
+    /** Top edge of the band, above its header when it has one. */
+    readonly y: number;
+    readonly height: number;
+    /** First record index inside the band. */
+    readonly from: number;
+    /** One past the last record index inside the band. */
+    readonly to: number;
+}
+/** The complete laid-out graph. */
+export interface TrajectoryGraphLayout {
+    readonly width: number;
+    readonly height: number;
+    readonly nodes: readonly LaidOutGraphNode[];
+    readonly edges: readonly LaidOutGraphEdge[];
+    readonly bands: readonly LaidOutBand[];
+    /** Center x of each swimlane, in `input, model, tool` order. */
+    readonly laneCenters: readonly number[];
+}
+/**
+ * Cut a chip label to the width the chip can actually draw.
+ *
+ * SVG has no text overflow, and a text node wider than its chip bleeds into the
+ * neighbouring lane. Counting CJK glyphs as two latin columns keeps both
+ * scripts inside the box.
+ * @param text - the label.
+ * @param maxWidth - available width in user units.
+ * @param fontSize - the chip's font size.
+ * @returns The label, ellipsized when it does not fit.
+ */
+export declare function ellipsize(text: string, maxWidth: number, fontSize: number): string;
+/**
+ * Lay out one graph projection.
+ * @param graph - the projection to place, already windowed by the caller.
+ * @param options - geometry overrides.
+ * @returns Positioned nodes, routed edges, and placed turn bands.
+ */
+export declare function layoutTrajectoryGraph(graph: TrajectoryGraph, options?: TrajectoryGraphLayoutOptions): TrajectoryGraphLayout;
+//# sourceMappingURL=trajectory-graph-layout.d.ts.map

package/lib/types/client/trajectory-graph-tab-definition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stage one of the trajectory-graph tab type: what it IS in the right Sidebar.
+ *
+ * The type is a page, not a viewer: it claims no address. It opens by kind from
+ * the guide page's entry box, and it sits beside the ledger type it draws.
+ */
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+import type { SidebarRightTabDefinition } from '@qilin-agent/client-ui-sidebar-right/client';
+/** The tab kind this package owns under the graph implementation; ctx.sidebarRight.openTab names it. */
+export declare const TRAJECTORY_GRAPH_KIND = "trajectory-graph";
+/** The graph implementation's identity in the tab system, and the key its body registers under. */
+export declare const TRAJECTORY_GRAPH_ID = "@qilin-agent/client-ui-trajectory/graph";
+/**
+ * The trajectory-graph type's registry definition.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns The definition to register.
+ */
+export declare function trajectoryGraphTabDefinition(t: TranslateNS<'trajectory'>): SidebarRightTabDefinition;
+//# sourceMappingURL=trajectory-graph-tab-definition.d.ts.map

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

@@ -0,0 +1,239 @@
+/**
+ * Pure projection from the Trajectory target snapshot to the trajectory graph:
+ * one node per ledger record, plus the links the ledger already records.
+ *
+ * Every edge is read back out of a durable fact, never invented:
+ * - `prompt`   - the last unconsumed input record (user, steering, context,
+ *                system prompt, or compaction checkpoint) before a request;
+ * - `result`   - the record named by `request.resultSeq` (`replacementSeq`
+ *                for a compaction checkpoint); a request still running reaches
+ *                the streaming assistant prefix instead;
+ * - `dispatch` - an assistant `tool-call` block reaches the tool record its
+ *                `callId` names;
+ * - `subcall`  - a tool record reaches each child call it dispatched itself;
+ * - `loop`     - a settling tool record reaches the next request, which is the
+ *                agent loop turning back to the model.
+ *
+ * The module carries no React and no DOM, so it runs in a plain Node
+ * environment, and it takes the namespace-bound translate so every string it
+ * emits stays locale-owned. A ledger record kind this client does not know
+ * degrades to an `unknown` node instead of throwing.
+ */
+import type { ImageMediaType } from '@qilin-agent/attachment';
+import type { TrajectoryTranslate } from './locales.ts';
+import type { TrajectorySnapshot } from './trajectory-contract.ts';
+/** Ledger record kinds the graph draws. */
+export type TrajectoryGraphNodeKind = 
+/** Loaded system-prompt state. */
+'system'
+/** A finalized user message. */
+ | 'user'
+/** A message admitted from the next-step inbox. */
+ | 'steering'
+/** A context injection surfaced in the flow. */
+ | 'context'
+/** A slash-command lifecycle. */
+ | 'command'
+/** One ordinary model request (an agent-loop step). */
+ | 'request'
+/** One compaction provider request. */
+ | 'compact-request'
+/** A finalized assistant message. */
+ | 'assistant'
+/** The in-flight streaming assistant prefix. */
+ | 'partial'
+/** A settled tool result, possibly a sub-call. */
+ | 'tool'
+/** A tool call whose result has not landed yet. */
+ | 'running-call'
+/** A landed compaction checkpoint. */
+ | 'compaction'
+/** A scheduled, started, or cancelled model retry. */
+ | 'retry'
+/** A turn that ended in failure. */
+ | 'error'
+/** A turn ended by the per-request output-token cap. */
+ | 'max-tokens'
+/** A surface event this client does not know. */
+ | 'unknown';
+/** The swimlane a node belongs to. */
+export type TrajectoryLane = 'input' | 'model' | 'tool';
+/** Node lifecycle as far as the graph presents it. */
+export type TrajectoryGraphNodeStatus = 'idle' | 'running' | 'complete' | 'error' | 'interrupted';
+/** Chain-of-data edge kinds. */
+export type TrajectoryGraphEdgeKind = 'prompt' | 'result' | 'dispatch' | 'subcall' | 'loop';
+/** Provider token buckets summed from one record's reported usage. */
+export interface TrajectoryTokens {
+    input?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    output?: number;
+    reasoning?: number;
+}
+/** One recorded attachment carried by a record's content or assistant blocks. */
+export interface TrajectoryAttachment {
+    readonly kind: 'image' | 'file';
+    /** Opaque storage id; never a filesystem path. */
+    readonly attachmentId: string;
+    /** Recorded display name; images may be unnamed. */
+    readonly name?: string;
+    /** Exact encoded byte length, when the reference carries it. */
+    readonly bytes?: number;
+    /** Verified media type, when the reference carries one. */
+    readonly mediaType?: ImageMediaType;
+    /** Intrinsic pixel dimensions, for images that report them. */
+    readonly width?: number;
+    readonly height?: number;
+    /** An image-offload decision replaced the bytes with placeholder text. */
+    readonly offloaded?: boolean;
+}
+/** Structured tool-call facts the inspector renders for tool-lane records. */
+export interface TrajectoryToolDetail {
+    readonly name: string;
+    /** Provider call id, when the record names one. */
+    readonly callId?: string;
+    /** Raw JSON arguments, when the call captured any. */
+    readonly argsRaw?: string;
+    /** Whether the call settled in error. */
+    readonly isError?: boolean;
+    /** Settled result text, verbatim; absent while the call is unsettled. */
+    readonly resultText?: string;
+}
+/** One graph node: one record of the ledger. */
+export interface TrajectoryGraphNode {
+    /** Stable identity: `req:<startSeq>`, `ev:<kind>:<seq>`, or `call:<callId>`. */
+    readonly id: string;
+    readonly kind: TrajectoryGraphNodeKind;
+    readonly lane: TrajectoryLane;
+    readonly status: TrajectoryGraphNodeStatus;
+    /** Ledger order key, fractional for a record synthesized between two events. */
+    readonly seq: number;
+    /** Unix epoch ms, or 0 when the ledger recorded none. */
+    readonly time: number;
+    /** Owning turn, or null for a record outside every turn. */
+    readonly turn: number | null;
+    /** Agent-loop step inside the turn, or null when the ledger records none. */
+    readonly step: number | null;
+    /** Chip label: the record's own text, or the localized name of its kind. */
+    readonly label: string;
+    /** Optional chip badge (status, call-id tail, shadowed token count). */
+    readonly badge?: string;
+    /** Free-form inspector body that is neither arguments nor result. */
+    readonly detail?: string;
+    /** Ordered attachments carried by the record's content or assistant blocks. */
+    readonly attachments?: readonly TrajectoryAttachment[];
+    /** Structured tool-call facts, present on tool-lane records. */
+    readonly toolDetail?: TrajectoryToolDetail;
+    readonly tokens?: TrajectoryTokens;
+    /** Wall time between the record's start and completion, when both are recorded. */
+    readonly durationMs?: number;
+    /** Whether the record is still moving, which drives the flow animation. */
+    readonly live: boolean;
+    /** Whether the record opens a new turn, which the view marks. */
+    readonly opensTurn?: boolean;
+}
+/** One chain-of-data edge. */
+export interface TrajectoryGraphEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly kind: TrajectoryGraphEdgeKind;
+    /** Whether data is moving into a live record across this edge. */
+    readonly live: boolean;
+}
+/**
+ * One contiguous run of ledger records that share a turn, plus the records
+ * outside every turn that the run surrounds: a turn-less record never splits
+ * the stripe of the turn it sits inside.
+ */
+export interface TrajectoryGraphBand {
+    /** Turn number, or null for records outside every turn. */
+    readonly turn: number | null;
+    /** Index of the band's first record. */
+    readonly from: number;
+    /** One past the index of the band's last record. */
+    readonly to: number;
+}
+/** One ledger step, with the edge that delivered the record. */
+export interface TrajectoryTimelineStep {
+    readonly nodeId: string;
+    /** The incoming edge to animate, or null for a root record. */
+    readonly edgeId: string | null;
+    /** Unix epoch ms of the record, or 0 when the ledger recorded none. */
+    readonly at: number;
+}
+/** Session totals shown above the canvas. */
+export interface TrajectoryGraphStats {
+    nodes: number;
+    edges: number;
+    /** Highest turn number seen, or 0 while no turn has opened. */
+    turns: number;
+    /** Tool records with an outcome: settled results and in-flight calls; the
+     * synthesized waiting placeholders stay uncounted. */
+    tools: number;
+    running: number;
+    errors: number;
+    /** Summed provider token buckets; an absent bucket is skipped. */
+    tokens: TrajectoryTokens;
+}
+/** The complete graph projection of one trajectory snapshot. */
+export interface TrajectoryGraph {
+    /** Nodes in ledger order. */
+    readonly nodes: readonly TrajectoryGraphNode[];
+    readonly edges: readonly TrajectoryGraphEdge[];
+    /** Turn runs over the nodes, by node index. */
+    readonly bands: readonly TrajectoryGraphBand[];
+    /** Ledger order with the incoming edge per record. */
+    readonly timeline: readonly TrajectoryTimelineStep[];
+    readonly stats: TrajectoryGraphStats;
+    /** Whether any record is still moving. */
+    readonly live: boolean;
+}
+/** One windowed view of a projection, for the render cap. */
+export interface TrajectoryGraphWindow {
+    graph: TrajectoryGraph;
+    /** How many leading records the window dropped. */
+    readonly hidden: number;
+}
+/**
+ * Project one Trajectory snapshot into the graph model.
+ * @param snapshot - the live Trajectory target snapshot, or null while none is assembled.
+ * @param t - namespace-bound translate for every string the nodes carry.
+ * @returns Nodes in ledger order with their edges, turn bands, timeline, and totals.
+ */
+export declare function buildTrajectoryGraph(snapshot: TrajectorySnapshot | null | undefined, t: TrajectoryTranslate): TrajectoryGraph;
+/**
+ * Keep only the most recent records, with the edges between them.
+ *
+ * A session's ledger is unbounded, so the view renders a tail window and
+ * reports how many leading records it dropped.
+ * @param graph - the full projection.
+ * @param limit - maximum records to keep; a non-positive limit keeps none.
+ * @returns The windowed graph and the number of dropped leading records.
+ */
+export declare function windowTrajectoryGraph(graph: TrajectoryGraph, limit: number): TrajectoryGraphWindow;
+/** One slowest-tools leader. */
+export interface TrajectorySlowTool {
+    /** The leader's node id, so a caller can select it. */
+    readonly id: string;
+    /** The record's chip label (the tool name). */
+    readonly name: string;
+    /** Recorded wall time in milliseconds. */
+    readonly durationMs: number;
+}
+/**
+ * The slowest settled tool records, descending by recorded duration.
+ * @param graph - the (windowed) graph projection.
+ * @param limit - how many leaders to keep; a non-positive limit keeps none.
+ * @returns The leaders, longest first; empty when no tool record carries a duration.
+ */
+export declare function slowestTools(graph: TrajectoryGraph, limit: number): readonly TrajectorySlowTool[];
+/**
+ * Search the graph's records by a case-insensitive substring of the chip
+ * label, the node kind, the node id, or a tool record's call id.
+ * @param graph - the (windowed) graph projection.
+ * @param query - raw user text; a blank query matches nothing.
+ * @returns Matching node ids in ledger order, for the search box's cursor to cycle.
+ */
+export declare function searchTrajectoryNodes(graph: TrajectoryGraph, query: string): readonly string[];
+//# sourceMappingURL=trajectory-graph.d.ts.map

package/lib/types/client/trajectory-message-definitions.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@qilin-agent/kylin';
+/**
+ * Register Trajectory-owned inbox classification and message records.
+ *
+ * @param ctx - Plugin context receiving the Definitions.
+ */
+export declare function registerTrajectoryMessageDefinitions(ctx: Context): void;
+//# sourceMappingURL=trajectory-message-definitions.d.ts.map

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

@@ -0,0 +1,8 @@
+/** Bounded Markdown-to-text projection shared by trajectory consumers. */
+/**
+ * Build a bounded one-line preview without parsing the complete Markdown document.
+ * @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=trajectory-preview.d.ts.map

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

@@ -0,0 +1,114 @@
+/** Shared trajectory record data and formatting contracts. */
+import type { HTMLAttributes } from 'react';
+import type { FileAttachmentRef, ImageAttachmentRef } from '@qilin-agent/attachment';
+import type { ConversationPromptSnapshot } from '@qilin-agent/client-ui-conversation/client';
+import type { TrajectoryTranslate } from './locales.ts';
+/** 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;
+    attachment?: ImageAttachmentRef;
+    /** Ordinary file metadata; never passed to the image loader. */
+    file?: FileAttachmentRef;
+    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;
+    /** Non-Markdown summary or prefix; CSS ellipsis when it overflows. */
+    text: string;
+    /** Raw Markdown source converted into the single-line summary at its consumer. */
+    previewMarkdown?: 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;
+    /** Known prompt text without a loaded request config or tool catalog. */
+    systemPromptDetail?: string;
+    /** 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;
+    /** Raw Markdown source converted into the tool-result summary at its consumer. */
+    resultPreviewMarkdown?: string;
+    /** Tool call id used to link message source blocks to tool records. */
+    callId?: string;
+    /** Recorded tool name; independent of the display summary. */
+    toolName?: 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.
+ * @param t - Trajectory locale translator.
+ * @returns `—` when unknown, otherwise an integer-millisecond label.
+ */
+export declare function formatDurationMillis(milliseconds: number | null, t: TrajectoryTranslate): string;
+/**
+ * Format an elapsed duration given in seconds as a millisecond label.
+ * @param seconds - Duration seconds, or `null` when absent.
+ * @param t - Trajectory locale translator.
+ * @returns `—` when unknown, otherwise an integer-millisecond label.
+ */
+export declare function formatElapsedSeconds(seconds: number | null, t: TrajectoryTranslate): string;
+//# sourceMappingURL=trajectory-record.d.ts.map

package/lib/types/client/trajectory-request-header-definition.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { SystemPromptState } from '@qilin-agent/client-ui-conversation/client';
+import type { TrajectoryRequestHeaderState } from './trajectory-contract.ts';
+/** Loaded system surface plus the latest request facts changed by an append or compaction. */
+export interface TrajectorySystemMessageState extends SystemPromptState {
+    /**
+     * Latest synthetic header, retained across unrelated replacements. Only the
+     * Context whose start seq equals this header's seq contributes a view Node.
+     */
+    readonly header?: TrajectoryRequestHeaderState;
+}
+/**
+ * Register Trajectory system-prompt node and request-header facts.
+ *
+ * @param ctx - Plugin context receiving the Definitions.
+ */
+export declare function registerTrajectoryRequestHeaderDefinition(ctx: Context): void;
+//# sourceMappingURL=trajectory-request-header-definition.d.ts.map

package/lib/types/client/trajectory-search-index.d.ts

@@ -0,0 +1,20 @@
+/** Incremental full-text index for the trajectory ledger. */
+import type { TrajectoryTurnModel } from './layout.ts';
+/** Session-view-local index that reparses Markdown only when one record's source changes. */
+export declare class TrajectorySearchIndex {
+    private readonly entries;
+    private layouts;
+    /**
+     * Incrementally synchronize one or more current trajectory layout slices.
+     * @param layouts - Finalized and optional streaming layouts from the same view.
+     * @returns Whether the indexed layout version changed.
+     */
+    update(layouts: readonly (readonly TrajectoryTurnModel[])[]): boolean;
+    /**
+     * Match a query against the latest committed index version.
+     * @param query - Space-separated case-insensitive search terms.
+     * @returns Matching stable record identities, or `null` without a query.
+     */
+    search(query: string): ReadonlySet<string> | null;
+}
+//# sourceMappingURL=trajectory-search-index.d.ts.map

package/lib/types/client/trajectory-snapshot-builder.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { ConversationViewBuilder, ConversationViewDefinition } from '@qilin-agent/client-ui-conversation/client';
+import type { TrajectoryConversationViewNode, TrajectorySnapshot } from './trajectory-contract.ts';
+/** Stable empty target used until a Session has assembled Trajectory records. */
+export declare const EMPTY_TRAJECTORY_SNAPSHOT: TrajectorySnapshot;
+/** Simple keyed adapter retaining the old Trajectory snapshot and stage layout. */
+export declare class TrajectorySnapshotBuilder implements ConversationViewBuilder<TrajectoryConversationViewNode, TrajectorySnapshot> {
+    private readonly nodes;
+    private readonly positions;
+    private contributions;
+    readonly empty: TrajectorySnapshot;
+    replace(input: {
+        readonly nodes: readonly TrajectoryConversationViewNode[];
+    }): TrajectorySnapshot;
+    apply(input: {
+        readonly upserts: readonly TrajectoryConversationViewNode[];
+    }): TrajectorySnapshot;
+    private snapshot;
+    private rebuildContributions;
+}
+/** Trajectory target factory preserving the existing stage-oriented view model. */
+export declare const trajectoryViewDefinition: ConversationViewDefinition<TrajectoryConversationViewNode, TrajectorySnapshot>;
+/**
+ * Register the stage-oriented Trajectory target builder.
+ *
+ * @param ctx - Plugin context receiving the view Definition.
+ */
+export declare function registerTrajectoryConversationView(ctx: Context): void;
+//# sourceMappingURL=trajectory-snapshot-builder.d.ts.map

package/lib/types/client/trajectory-tab-definition.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Stage one of the trajectory tab type: what it IS in the right Sidebar.
+ *
+ * The type is a page, not a viewer: it claims no address, and it offers no
+ * guide entry, so the Sidebar never lists the ledger beside the graph. It opens
+ * by kind from the two actions that ask for it: a Chat tool card's inspect
+ * action, which addresses the call to focus through `params.focus`, and the
+ * graph page's Ledger control.
+ */
+import type { SidebarRightTabDefinition } from '@qilin-agent/client-ui-sidebar-right/client';
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+/** The tab kind this package owns; `ctx.sidebarRight.openTab` names it. */
+export declare const TRAJECTORY_KIND = "trajectory";
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export declare const TRAJECTORY_ID = "@qilin-agent/client-ui-trajectory/trajectory";
+/** Navigation parameters the trajectory page accepts: the tool-call identity to focus. */
+export interface TrajectoryTabParams {
+    readonly focus?: string;
+}
+declare module '@qilin-agent/client-ui-sidebar-right/client' {
+    interface SidebarRightTabParamsMap {
+        /** The trajectory page focuses the ledger on this call when opened from Chat. */
+        trajectory: TrajectoryTabParams;
+    }
+}
+/**
+ * The trajectory type's registry definition.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns the definition to register.
+ */
+export declare function trajectoryTabDefinition(t: TranslateNS<'trajectory'>): SidebarRightTabDefinition;
+//# sourceMappingURL=trajectory-tab-definition.d.ts.map

package/lib/types/client/trajectory-tool-definition.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@qilin-agent/kylin';
+/**
+ * Register the Trajectory Tool lifecycle with raw native and PTC error details.
+ *
+ * @param ctx - Plugin context receiving the Definition.
+ */
+export declare function registerTrajectoryToolDefinition(ctx: Context): void;
+//# sourceMappingURL=trajectory-tool-definition.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