@prettier-ai/dsh-client-ui-trajectory 0.1.2-alpha.1

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

@@ -0,0 +1,87 @@
+import type { AssistantMessageNode, ConversationLocation, ConversationNode, ConversationPromptSnapshot, ConversationViewNode, MessageImagesOwnerProps, PartialAssistant, RequestPromptChange, RequestView, RunningToolCall, ToolCallBlock } from '@prettier-ai/dsh-client-ui-conversation/client';
+import type { SnapshotSelectorHook } from '@prettier-ai/dsh-client-ui-slots';
+/** Request-header facts retained by the Trajectory target. */
+export interface TrajectoryRequestHeaderState {
+    readonly seq: number;
+    readonly time: number;
+    readonly prompt: ConversationPromptSnapshot;
+    readonly change?: RequestPromptChange;
+    readonly location: ConversationLocation;
+}
+/** One independently assembled contribution to the legacy Trajectory ledger. */
+export type TrajectoryContribution = {
+    readonly kind: 'node';
+    readonly node: ConversationNode;
+} | {
+    readonly kind: 'assistant';
+    readonly node?: AssistantMessageNode;
+    readonly partial: PartialAssistant | null;
+    readonly request?: Extract<RequestView, {
+        purpose: 'assistant';
+    }>;
+} | {
+    readonly kind: 'tool';
+    readonly root: ToolCallBlock;
+} | {
+    readonly kind: 'request-header';
+    readonly header: TrajectoryRequestHeaderState;
+} | {
+    readonly kind: 'compaction';
+    readonly request: Extract<RequestView, {
+        purpose: 'compaction';
+    }>;
+} | {
+    readonly kind: 'session-end';
+    readonly seq: number;
+    readonly time: number;
+} | {
+    readonly kind: 'turn-end';
+    readonly turn: number;
+    readonly time: number;
+    readonly error?: string;
+    readonly errorCode?: string;
+};
+/** Target envelope consumed by the Trajectory snapshot builder. */
+export interface TrajectoryConversationViewNode extends ConversationViewNode {
+    readonly target: 'trajectory';
+    readonly anchorSeq: number;
+    readonly location: ConversationLocation;
+    readonly data: TrajectoryContribution;
+}
+/** Stage-oriented Trajectory data assembled from registered business Contexts. */
+export interface TrajectorySnapshot {
+    readonly eventNodes: readonly ConversationNode[];
+    readonly eventLocations: ReadonlyMap<number, ConversationLocation>;
+    readonly requests: readonly RequestView[];
+    readonly callSchemas: ReadonlyMap<string, ConversationPromptSnapshot['tools'][number]>;
+    readonly partial: PartialAssistant | null;
+    readonly runningCalls: readonly RunningToolCall[];
+}
+/** Selector hook over the current Conversation binding's Trajectory target. */
+export type UseTrajectory = SnapshotSelectorHook<TrajectorySnapshot>;
+declare module '@prettier-ai/dsh-client-ui-conversation/client' {
+    interface ConversationViewSnapshotMap {
+        /** Independently assembled data consumed by the Trajectory view. */
+        trajectory: TrajectorySnapshot;
+    }
+}
+declare module '@prettier-ai/dsh-client-ui-slots' {
+    interface SessionStandardProps {
+        /** Selector hook over the current Conversation binding's Trajectory target. */
+        useTrajectory: UseTrajectory;
+    }
+    interface SlotMap {
+        /**
+         * Renderer for one group of durable record images in the Trajectory
+         * ledger. The owner supplies image references, an authorized loader, and
+         * alignment. A registration replaces the shipped gallery; without one,
+         * images are omitted.
+         */
+        'conversation.trajectory.images': {
+            kind: 'single';
+            scope: 'session';
+            owner: MessageImagesOwnerProps;
+        };
+    }
+}
+//# sourceMappingURL=trajectory-contract.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { ConversationNodeContext } from '@prettier-ai/dsh-client-ui-conversation/client';
+import type { TrajectoryContribution, TrajectoryConversationViewNode } from './trajectory-contract.ts';
+/**
+ * Wrap one contribution in the Engine-owned target envelope.
+ *
+ * @param context - Context that owns the contribution identity.
+ * @param anchorSeq - Sequence used to order the contribution.
+ * @param data - Trajectory-specific contribution payload.
+ * @returns The contribution wrapped as a Trajectory view node.
+ */
+export declare function trajectoryNode(context: ConversationNodeContext, anchorSeq: number, data: TrajectoryContribution): TrajectoryConversationViewNode;
+//# sourceMappingURL=trajectory-definition-common.d.ts.map

package/lib/types/client/trajectory-event-projection.d.ts

@@ -0,0 +1,51 @@
+/** Trajectory-owned conversion from durable Session events to ledger view data. */
+import type { ContentBlock, StreamChunk } from '@prettier-ai/dsh-llm/types';
+import type { AssistantBlock, ContextProvenanceView, KnownContextForm } from '@prettier-ai/dsh-client-ui-conversation/client';
+/**
+ * Read the target-supported presentation form from a durable message source.
+ * @param source - Logged `user/message` source.
+ * @returns Supported form, or null for the opaque presentation.
+ */
+export declare function contextForm(source: unknown): KnownContextForm | null;
+/**
+ * Project a durable message source to the Trajectory row's role and producer label.
+ * @param source - Logged `user/message` source.
+ * @returns Role and label rendered by Trajectory.
+ */
+export declare function contextProvenance(source: unknown): ContextProvenanceView;
+/**
+ * Classify finalized Assistant content for Trajectory rendering.
+ * @param content - Core content blocks.
+ * @returns Trajectory blocks in source order.
+ */
+export declare function toAssistantBlocks(content: readonly ContentBlock[]): AssistantBlock[];
+/**
+ * Classify one finalized Assistant block for Trajectory rendering.
+ * @param block - Core content block.
+ * @returns Trajectory block.
+ */
+export declare function toAssistantBlock(block: ContentBlock): AssistantBlock;
+/**
+ * Create the initial Trajectory block for one streamed Assistant block kind.
+ * @param blockType - Wire block kind.
+ * @returns Empty block ready to receive deltas.
+ */
+export declare function emptyAssistantBlock(blockType: string): AssistantBlock;
+/** Display-safe failure fields retained by Trajectory projections. */
+export interface DisplayFailure {
+    readonly code?: string;
+    readonly message: string;
+}
+/**
+ * Convert a durable failure to locale-independent fields safe for Trajectory.
+ * @param failure - Failure preserved by a Session event.
+ * @returns Sanitized message and optional stable provider code.
+ */
+export declare function displayFailure(failure: unknown): DisplayFailure;
+/**
+ * Whether a stream chunk carries visible model output for Trajectory timing.
+ * @param chunk - Stream chunk to inspect.
+ * @returns true for a non-empty text, reasoning, or Tool-call delta.
+ */
+export declare function isTokenDelta(chunk: StreamChunk): boolean;
+//# sourceMappingURL=trajectory-event-projection.d.ts.map

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

@@ -0,0 +1,8 @@
+import type { Context } from '@prettier-ai/cordis';
+/**
+ * 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,108 @@
+/** Shared trajectory record data and formatting contracts. */
+import type { HTMLAttributes } from 'react';
+import type { ImageAttachmentRef } from '@prettier-ai/dsh-attachment';
+import type { ConversationPromptSnapshot } from '@prettier-ai/dsh-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;
+    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;
+    /** 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;
+    /** 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,8 @@
+import type { Context } from '@prettier-ai/cordis';
+/**
+ * Register Trajectory request-header facts.
+ *
+ * @param ctx - Plugin context receiving the Definition.
+ */
+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 '@prettier-ai/cordis';
+import type { ConversationViewBuilder, ConversationViewDefinition } from '@prettier-ai/dsh-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-tool-definition.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@prettier-ai/cordis';
+/**
+ * Register the Trajectory Tool lifecycle.
+ *
+ * @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

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@prettier-ai/dsh-client-ui-trajectory`.
+ * @module @prettier-ai/dsh-client-ui-trajectory/invariant
+ */
+import type { Context } from '@prettier-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,98 @@
+{
+  "name": "@prettier-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.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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": [
+        "@prettier-ai/dsh-api-session-controller",
+        "@prettier-ai/dsh-client-locale",
+        "@prettier-ai/dsh-client-ui-conversation",
+        "@prettier-ai/dsh-client-ui-renderer",
+        "@prettier-ai/dsh-client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@tanstack/react-virtual": "^3.14.9",
+    "diff": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-agent": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-compaction": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-tools": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-session": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-api-session-controller": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-renderer": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-session": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-llm": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-conversation": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-attachment": "^0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@prettier-ai/dsh-agent": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-test-runtime": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-primitives": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-conversation": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-slots": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-compaction": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-tools": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-client-store": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-session": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-chat": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-api-session-controller": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-renderer": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-llm": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-session": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-attachment": "^0.1.2-alpha.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}