@peasant-labs/fairtrade 0.0.17 → 0.0.18

package/dist/lib/types/graph/index.d.ts

@@ -54,6 +54,20 @@ export type TimelineHighlight = import("./codeMapState.js").TimelineHighlight;
 export type RankInputNode = import("./ranking.js").RankInputNode;
 export type RankedRowData = import("./ranking.js").RankedRow;
 export type DebtState = import("./ranking.js").DebtState;
+export type TrajectoryGraphProps = import("../transcript/graph/engine/index.js").TrajectoryGraphProps;
+export type GraphControlsProps = import("../transcript/graph/engine/index.js").GraphControlsProps;
+export type TrajectoryGraphLegendProps = import("../transcript/graph/engine/index.js").TrajectoryGraphLegendProps;
+export type TurnsToFlowOptions = import("../transcript/graph/engine/index.js").TurnsToFlowOptions;
+export type TrajectoryCanvasProps = import("../transcript/graph/engine/index.js").TrajectoryCanvasProps;
+export type TurnNodeData = import("../transcript/graph/engine/index.js").TurnNodeData;
+export type ToolCallNodeData = import("../transcript/graph/engine/index.js").ToolCallNodeData;
+export type SubagentLaneData = import("../transcript/graph/engine/index.js").SubagentLaneData;
+export type NavCommand = import("../transcript/graph/engine/index.js").NavCommand;
+export type EdgeType = import("../transcript/graph/engine/index.js").EdgeType;
+export type CanvasEdgeData = import("../transcript/graph/engine/index.js").CanvasEdgeData;
+export type FlowNode = import("../transcript/graph/engine/index.js").FlowNode;
+export type FlowEdge = import("../transcript/graph/engine/index.js").FlowEdge;
+export type FlowGraph = import("../transcript/graph/engine/index.js").FlowGraph;
 export { default as CodeMap, codeMapPayloadToMapData } from "./CodeMap.jsx";
 export { default as CodeMapComposition, DefaultMapLegend } from "./CodeMapComposition.jsx";
 export { CODE_MAP_STATE_VERSION, CODE_MAP_VIEWPORT_SCALE, isCodeMapViewportScale, codeMapStatesEqual, createCodeMapState, reduceCodeMapState, deriveCodeMapView, deriveTimelineHighlight, resolveEscapeAction } from "./codeMapState.js";
@@ -62,3 +76,5 @@ export { buildChangesGraph, humanizeAge } from "./changeGraph.js";
 export { DOI_WEIGHTS, DEBT_VIEWED, COVERAGE_CAP, RECENCY_HALF_LIFE_DAYS, RANK_FLOOR, RANK_CAP, SCENT_TAGS, debtState, debt, coverage, hunkClears, partialReadHoverText, debtHoverText, scentTagsFor, rankMapNodesIntrinsic, deriveRankedRows, rankMapNodes, gateRankedRows } from "./ranking.js";
 export { assertChangeDetailPayloadEnums, assertChangeDiffPayloadEnums, assertCodeMapPayloadEnums, MAP_NODE_KINDS, CHANGE_BINDINGS, EDGE_VIOLATION_KINDS, FILE_CHANGE_STATUSES, DIFF_LINE_KINDS } from "./types.js";
 export { MapNodeKind, AllMapNodeKinds, isMapNodeKind, ChangeBinding, AllChangeBindings, isChangeBinding, EdgeViolationKind, AllEdgeViolationKinds, isEdgeViolationKind, FileChangeStatus, AllFileChangeStatuses, isFileChangeStatus, DiffLineKind, AllDiffLineKinds, isDiffLineKind, InsightKind, AllInsightKinds, isInsightKind, InsightProvenance, AllInsightProvenances, isInsightProvenance, ReadAttributionState, AllReadAttributionStates, isReadAttributionState, ReadStateGrade, AllReadStateGrades, isReadStateGrade } from "@peasant-labs/schema";
+export { TrajectoryGraph, GraphControls, TrajectoryGraphLegend, TurnCardNode, ToolPillNode, SubagentBranchNode, useCanvasSync, turnsToFlow, computeLaneHeaders, NODE_DIMENSIONS, EDGE_DEFAULTS } from "../transcript/graph/engine/index.js";
+export { GraphTurnNode, GraphToolNode, GraphSubagentBranch, GraphLegend, GRAPH_LEGEND_ITEMS } from "../transcript/graph/index.js";

package/dist/lib/types/transcript/OutcomeChip.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render a session outcome as a semantically-toned chip. Renders nothing for
+ * an unknown / absent outcome, so a caller can gate on the element rather than
+ * pre-checking the value (matching the prior inline `session.outcome &&` guard).
+ *
+ * @param {object} props
+ * @param {string} [props.outcome]     outcome / label string — see `OUTCOME_VISUALS`
+ * @param {string} [props.className]   extra classes appended after the chip classes
+ */
+export default function TranscriptOutcomeChip({ outcome, className }: {
+    outcome?: string;
+    className?: string;
+}): import("react").JSX.Element;
+export type OutcomeVisual = {
+    icon: React.ElementType;
+    chipTone: "ok" | "warn" | "err";
+    label: string;
+};

package/dist/lib/types/transcript/graph/engine/GraphControls.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @typedef {object} GraphControlsProps
+ * @property {string} [className]
+ */
+/**
+ * The trajectory-graph viewport controls. Must render inside a `<ReactFlowProvider>`.
+ * @param {GraphControlsProps} props
+ * @returns {JSX.Element}
+ */
+export function GraphControls({ className }: GraphControlsProps): JSX.Element;
+export type GraphControlsProps = {
+    className?: string;
+};

package/dist/lib/types/transcript/graph/engine/TrajectoryGraph.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @typedef {import('./types.js').TrajectoryCanvasProps & {
+ *   provider?: import('@peasant-labs/schema').Harness,
+ *   className?: string,
+ * }} TrajectoryGraphProps
+ */
+/**
+ * The trajectory graph. Owns its own `<ReactFlowProvider>`, so a host can mount
+ * it directly (for example into the transcript viewer's graph slot).
+ * @param {TrajectoryGraphProps} props
+ * @returns {JSX.Element}
+ */
+export function TrajectoryGraph(props: TrajectoryGraphProps): JSX.Element;
+export type TrajectoryGraphProps = import("./types.js").TrajectoryCanvasProps & {
+    provider?: import("@peasant-labs/schema").Harness;
+    className?: string;
+};
+export type TurnNodeData = import("./types.js").TurnNodeData;

package/dist/lib/types/transcript/graph/engine/TrajectoryGraphLegend.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @typedef {object} TrajectoryGraphLegendProps
+ * @property {import('@peasant-labs/schema').Harness} [provider]
+ *   canonical harness; sets the assistant swatch accent + label to match the turn cards
+ * @property {string} [className]
+ */
+/**
+ * @param {TrajectoryGraphLegendProps} props
+ * @returns {JSX.Element}
+ */
+export function TrajectoryGraphLegend({ provider, className }: TrajectoryGraphLegendProps): JSX.Element;
+export type TrajectoryGraphLegendProps = {
+    /**
+     * canonical harness; sets the assistant swatch accent + label to match the turn cards
+     */
+    provider?: import("@peasant-labs/schema").Harness;
+    className?: string;
+};

package/dist/lib/types/transcript/graph/engine/constants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Canvas geometry for the trajectory graph, in canvas units.
+ * @type {Readonly<{
+ *   turnWidth: number, turnBaseHeight: number, toolCallWidth: number,
+ *   toolCallHeight: number, laneGap: number, verticalGap: number,
+ *   toolSideGap: number, subagentIndent: number, phasePadding: number,
+ * }>}
+ */
+export const NODE_DIMENSIONS: Readonly<{
+    turnWidth: number;
+    turnBaseHeight: number;
+    toolCallWidth: number;
+    toolCallHeight: number;
+    laneGap: number;
+    verticalGap: number;
+    toolSideGap: number;
+    subagentIndent: number;
+    phasePadding: number;
+}>;
+/**
+ * Default edge stroke roles. Colours are token-backed custom properties
+ * (`--edge` / `--edge-error`) declared on the `.tb-graph` root.
+ * @type {Readonly<{
+ *   sequentialColor: string, sequentialColorDark: string, sequentialWidth: number,
+ *   phaseTransitionWidth: number, subagentSpawnColor: string,
+ *   subagentReturnColor: string, errorColor: string,
+ * }>}
+ */
+export const EDGE_DEFAULTS: Readonly<{
+    sequentialColor: string;
+    sequentialColorDark: string;
+    sequentialWidth: number;
+    phaseTransitionWidth: number;
+    subagentSpawnColor: string;
+    subagentReturnColor: string;
+    errorColor: string;
+}>;

package/dist/lib/types/transcript/graph/engine/index.d.ts

@@ -0,0 +1,23 @@
+export { TrajectoryGraph } from "./TrajectoryGraph.jsx";
+export { GraphControls } from "./GraphControls.jsx";
+export { TrajectoryGraphLegend } from "./TrajectoryGraphLegend.jsx";
+export { TurnCardNode } from "./nodes/TurnCardNode.jsx";
+export { ToolPillNode } from "./nodes/ToolPillNode.jsx";
+export { SubagentBranchNode } from "./nodes/SubagentBranchNode.jsx";
+export { useCanvasSync } from "./useCanvasSync.js";
+export type TrajectoryGraphProps = import("./TrajectoryGraph.jsx").TrajectoryGraphProps;
+export type GraphControlsProps = import("./GraphControls.jsx").GraphControlsProps;
+export type TrajectoryGraphLegendProps = import("./TrajectoryGraphLegend.jsx").TrajectoryGraphLegendProps;
+export type TurnsToFlowOptions = import("./turnsToFlow.js").TurnsToFlowOptions;
+export type TrajectoryCanvasProps = import("./types.js").TrajectoryCanvasProps;
+export type TurnNodeData = import("./types.js").TurnNodeData;
+export type ToolCallNodeData = import("./types.js").ToolCallNodeData;
+export type SubagentLaneData = import("./types.js").SubagentLaneData;
+export type NavCommand = import("./types.js").NavCommand;
+export type EdgeType = import("./types.js").EdgeType;
+export type CanvasEdgeData = import("./types.js").CanvasEdgeData;
+export type FlowNode = import("./types.js").FlowNode;
+export type FlowEdge = import("./types.js").FlowEdge;
+export type FlowGraph = import("./types.js").FlowGraph;
+export { turnsToFlow, computeLaneHeaders } from "./turnsToFlow.js";
+export { NODE_DIMENSIONS, EDGE_DEFAULTS } from "./constants.js";

package/dist/lib/types/transcript/graph/engine/nodes/SubagentBranchNode.d.ts

@@ -0,0 +1,11 @@
+export const SubagentBranchNode: import("react").MemoExoticComponent<typeof SubagentBranchNodeImpl>;
+export type SubagentLaneData = import("../types.js").SubagentLaneData;
+/** @typedef {import('../types.js').SubagentLaneData} SubagentLaneData */
+/**
+ * @param {{ data: SubagentLaneData }} props
+ * @returns {JSX.Element}
+ */
+declare function SubagentBranchNodeImpl({ data }: {
+    data: SubagentLaneData;
+}): JSX.Element;
+export {};

package/dist/lib/types/transcript/graph/engine/nodes/ToolPillNode.d.ts

@@ -0,0 +1,11 @@
+export const ToolPillNode: import("react").MemoExoticComponent<typeof ToolPillNodeImpl>;
+export type ToolCallNodeData = import("../types.js").ToolCallNodeData;
+/** @typedef {import('../types.js').ToolCallNodeData} ToolCallNodeData */
+/**
+ * @param {{ data: ToolCallNodeData }} props
+ * @returns {JSX.Element}
+ */
+declare function ToolPillNodeImpl({ data }: {
+    data: ToolCallNodeData;
+}): JSX.Element;
+export {};

package/dist/lib/types/transcript/graph/engine/nodes/TurnCardNode.d.ts

@@ -0,0 +1,11 @@
+export const TurnCardNode: import("react").MemoExoticComponent<typeof TurnCardNodeImpl>;
+export type TurnNodeData = import("../types.js").TurnNodeData;
+/**
+ * @param {{ data: TurnNodeData, selected?: boolean }} props
+ * @returns {JSX.Element}
+ */
+declare function TurnCardNodeImpl({ data, selected }: {
+    data: TurnNodeData;
+    selected?: boolean;
+}): JSX.Element;
+export {};

package/dist/lib/types/transcript/graph/engine/turnsToFlow.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @typedef {object} TurnsToFlowOptions
+ * @property {TurnDetail[]} turns
+ * @property {Map<number, ToolCallVM[]>} [toolVMsByTurn] cooked tool calls by turn index; supplies each tool node's preview
+ * @property {Phase[]} phases
+ * @property {TranscriptAnnotation[]} annotations
+ * @property {number[]} searchMatches
+ * @property {Set<number>} filteredIndices
+ * @property {string} [searchQuery]
+ * @property {Set<number>} [selectedTurns]
+ */
+/**
+ * Build the trajectory graph's nodes and edges from a turn list.
+ * @param {TurnsToFlowOptions} options
+ * @returns {FlowGraph}
+ */
+export function turnsToFlow({ turns, toolVMsByTurn, phases, annotations, searchMatches, filteredIndices, searchQuery, selectedTurns, }: TurnsToFlowOptions): FlowGraph;
+/**
+ * Compute the lane-header nodes for the subagent swimlanes. The main lane
+ * (depth 0) carries no header.
+ * @param {FlowNode[]} turnNodes
+ * @returns {FlowNode[]}
+ */
+export function computeLaneHeaders(turnNodes: FlowNode[]): FlowNode[];
+export type TurnsToFlowOptions = {
+    turns: TurnDetail[];
+    /**
+     * cooked tool calls by turn index; supplies each tool node's preview
+     */
+    toolVMsByTurn?: Map<number, ToolCallVM[]>;
+    phases: Phase[];
+    annotations: TranscriptAnnotation[];
+    searchMatches: number[];
+    filteredIndices: Set<number>;
+    searchQuery?: string;
+    selectedTurns?: Set<number>;
+};
+export type TurnDetail = import("./types.js").TurnDetail;
+export type Phase = import("./types.js").Phase;
+export type PhaseType = import("./types.js").PhaseType;
+export type TranscriptAnnotation = import("./types.js").TranscriptAnnotation;
+export type ToolCallVM = import("./types.js").ToolCallVM;
+export type TurnNodeData = import("./types.js").TurnNodeData;
+export type ToolCallNodeData = import("./types.js").ToolCallNodeData;
+export type FlowNode = import("./types.js").FlowNode;
+export type FlowEdge = import("./types.js").FlowEdge;
+export type FlowGraph = import("./types.js").FlowGraph;

package/dist/lib/types/transcript/graph/engine/types.d.ts

@@ -0,0 +1,131 @@
+export type TurnDetail = import("@peasant-labs/schema").TurnDetail;
+export type ToolCallDetail = import("@peasant-labs/schema").ToolCallDetail;
+export type Harness = import("@peasant-labs/schema").Harness;
+export type TranscriptAnnotation = import("../../analytics.js").TranscriptAnnotation;
+export type Phase = import("../../analytics.js").PhaseSegment;
+export type PhaseType = import("../../analytics.js").PhaseType;
+export type ToolCallVM = import("../../view-model.js").ToolCallVM;
+/**
+ * A positioned graph node in canvas coordinates.
+ */
+export type FlowNode = {
+    id: string;
+    /**
+     * custom node type key ('turn' | 'toolCall' | 'subagentLane')
+     */
+    type?: string;
+    /**
+     * canvas coordinates
+     */
+    position: {
+        x: number;
+        y: number;
+    };
+    /**
+     * the node's cooked payload
+     */
+    data: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    selectable?: boolean;
+    draggable?: boolean;
+};
+/**
+ * A connector between two `FlowNode`s.
+ */
+export type FlowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    type?: string;
+    animated?: boolean;
+    style?: Record<string, unknown>;
+    data?: CanvasEdgeData;
+};
+/**
+ * How an edge came about. Drives stroke colour, width, and dash pattern.
+ */
+export type EdgeType = "sequential" | "phase-transition" | "spawn" | "return" | "turn-to-tool" | "error";
+export type CanvasEdgeData = {
+    edgeType: EdgeType;
+    phaseColor?: string;
+};
+/**
+ * The mapper's output: a complete node-link graph.
+ */
+export type FlowGraph = {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+};
+export type TurnNodeData = {
+    turn: TurnDetail;
+    annotations: TranscriptAnnotation[];
+    phaseType: PhaseType | undefined;
+    isSearchMatch: boolean;
+    isFilteredOut: boolean;
+    isSelected: boolean;
+    turnNumber: number;
+    tokensCumulative: number;
+    searchQuery?: string;
+    /**
+     * threaded in by the graph so the card accent matches the host
+     */
+    provider?: Harness;
+};
+export type ToolCallNodeData = {
+    turnIndex: number;
+    toolCalls: ToolCallDetail[];
+    /**
+     *   cooked one-line previews keyed by tool-call id (the adapter's `ToolCallVM.preview`),
+     *   threaded in so the node renders the same arg summary as the list view WITHOUT
+     *   parsing wire (`ToolCallDetail.arguments`) in the node
+     */
+    previewById: Record<string, string>;
+    totalDurationMs: number;
+    hasError: boolean;
+    isFilteredOut: boolean;
+    phaseType: PhaseType | undefined;
+};
+export type SubagentLaneData = {
+    depth: number;
+    agentName: string;
+};
+/**
+ * A navigation command carrying a nonce, so the same target can be re-triggered.
+ */
+export type NavCommand = {
+    target: number;
+    seq: number;
+};
+export type TrajectoryCanvasProps = {
+    turns: TurnDetail[];
+    /**
+     * cooked tool calls keyed by turn index; absent means tool nodes render without arg previews
+     */
+    toolVMsByTurn?: Map<number, ToolCallVM[]>;
+    filteredTurns: TurnDetail[];
+    phases: Phase[];
+    annotations: TranscriptAnnotation[];
+    searchMatches: number[];
+    searchQuery?: string;
+    activeMatchIndex?: number;
+    /**
+     * external command to pan the canvas to a turn index
+     */
+    focusTurn?: NavCommand;
+    /**
+     * external command to fit the canvas to a phase index
+     */
+    focusPhase?: NavCommand;
+    onPhaseActivate?: (phaseIndex: number) => void;
+    onViewportChange?: (range: {
+        start: number;
+        end: number;
+    }) => void;
+    /**
+     * selected turn indices, for marquee highlighting
+     */
+    selectedTurns?: Set<number>;
+    onMarqueeSelect?: (indices: number[]) => void;
+};

package/dist/lib/types/transcript/graph/engine/useCanvasSync.d.ts

@@ -0,0 +1,17 @@
+/** @typedef {import('./types.js').TurnDetail} TurnDetail */
+/** @typedef {import('./types.js').Phase} Phase */
+/** @typedef {import('./types.js').TurnNodeData} TurnNodeData */
+/**
+ * Focus helpers bound to the enclosing `<ReactFlowProvider>`.
+ * @param {Phase[]} phases
+ * @param {TurnDetail[]} turns
+ * @param {(phaseIndex: number) => void} [onPhaseActivate]
+ * @returns {{ focusPhase: (phaseIndex: number) => void, focusTurn: (turnIndex: number) => void }}
+ */
+export function useCanvasSync(phases: Phase[], turns: TurnDetail[], onPhaseActivate?: (phaseIndex: number) => void): {
+    focusPhase: (phaseIndex: number) => void;
+    focusTurn: (turnIndex: number) => void;
+};
+export type TurnDetail = import("./types.js").TurnDetail;
+export type Phase = import("./types.js").Phase;
+export type TurnNodeData = import("./types.js").TurnNodeData;

package/dist/lib/types/transcript/index.d.ts

@@ -1,10 +1,12 @@
 export { TOOL_GROUPS } from "./view-model.js";
+export { nextNavTurn } from "./turnNav.js";
 export { default as TranscriptTurnCard } from "./TurnCard.jsx";
 export { default as TranscriptThinking } from "./Thinking.jsx";
 export { default as TranscriptMarkdown } from "./Markdown.jsx";
 export { default as TranscriptToolCall } from "./ToolCall.jsx";
 export { default as TranscriptToolBody } from "./ToolBody.jsx";
 export { default as TranscriptTaskBody } from "./TaskBody.jsx";
+export { default as TranscriptOutcomeChip } from "./OutcomeChip.jsx";
 export { default as TranscriptViewer } from "./TranscriptViewer.jsx";
 export { default as TranscriptOutlineRail } from "./OutlineRail.jsx";
 export { default as TranscriptFiltersRail } from "./FiltersRail.jsx";
@@ -61,6 +63,7 @@ export type FileEntryVM = import("./view-model.js").FileEntryVM;
 export type TaskGroupVM = import("./view-model.js").TaskGroupVM;
 export type HighlightVM = import("./view-model.js").HighlightVM;
 export type AnnotationVM = import("./view-model.js").AnnotationVM;
+export type TurnLabel = import("./view-model.js").TurnLabel;
 export type FilterIndexVM = import("./view-model.js").FilterIndexVM;
 export type PhaseVM = import("./view-model.js").PhaseVM;
 export type ScorecardBandVM = import("./view-model.js").ScorecardBandVM;
@@ -68,5 +71,7 @@ export type TranscriptAnalyticsVM = import("./view-model.js").TranscriptAnalytic
 export { ROLES, ENTRY_TYPES, TOOL_CALL_KINDS, STOP_REASONS, SESSION_OUTCOMES, HARNESSES } from "./wire-types.js";
 export { adaptTranscript, prefilterTurns, diffLines } from "./adapter.js";
 export { computeTasks, computeTurnLabels, buildTaskWaterfall, annotateTranscript, computePersonalMedians, detectPhases, assessScorecard, computeAnalytics, computeTaskGroups, phaseLabel } from "./analytics.js";
+export { formatRelative, formatDurationMins, formatDateLong } from "./time.js";
+export { summarizePrompt, composeSessionTitle, projectLabel } from "./title.js";
 export { default as TranscriptDiffEntryCard, DiffHunks as TranscriptDiffHunks } from "./DiffEntryCard.jsx";
 export { advanceTranscriptInitialPositionConsumption, normalizeTranscriptInitialPosition, resolveTranscriptInitialPosition, shouldApplyTranscriptInitialPosition, transcriptInitialPositionReadiness, transcriptInitialPositionToken } from "./initial-position.js";

package/dist/lib/types/transcript/time.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Human-readable relative time: "3m ago", "2h ago", "4d ago", "Jan 12".
+ *
+ * @param {string} iso        an ISO 8601 timestamp
+ * @param {number} [now]      reference "now" in epoch millis (defaults to `Date.now()`; pass explicitly for deterministic tests)
+ * @returns {string}
+ */
+export function formatRelative(iso: string, now?: number): string;
+/**
+ * A duration expressed in minutes → "1h 16m" / "9m" / "42s".
+ *
+ * @param {number | undefined} mins
+ * @returns {string}
+ */
+export function formatDurationMins(mins: number | undefined): string;
+/**
+ * "Jan 12, 4:23 PM" — long datetime for tooltips.
+ *
+ * @param {string} iso
+ * @returns {string}
+ */
+export function formatDateLong(iso: string): string;

package/dist/lib/types/transcript/title.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Produce a short, human-readable summary of a raw prompt. Heuristic, in order:
+ *   1. Strip leading <system-reminder> blocks and leading fenced code blocks.
+ *   2. Pull out a <command-name> (e.g. `/mcp`) if present, keep following prose.
+ *   3. Strip remaining XML-ish tags, collapse whitespace, take the first sentence.
+ *   4. Capitalize the first letter and cap at `limit` chars with `…`.
+ *
+ * @param {string | undefined} raw
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function summarizePrompt(raw: string | undefined, limit?: number): string;
+/**
+ * Last path segment of a project string. `/Users/x/Projects/phaze` → `phaze`.
+ * Falls back to the whole string if there's no separator. Returns `''` when the
+ * input is empty/undefined.
+ *
+ * @param {string | undefined} project
+ * @returns {string}
+ */
+export function projectLabel(project: string | undefined): string;
+/**
+ * Compose the session detail h1.
+ *
+ *   • {project}: {Summary}   — project + meaningful prompt
+ *   • {project} · {shortId}  — project, no usable prompt
+ *   • {shortId} — {Summary}  — no project, but a prompt
+ *   • Session {shortId}      — nothing useful at all
+ *
+ * The full prompt text (or composed title) is returned alongside as a tooltip
+ * string so `<h1 title=…>` can expose the raw prompt on hover.
+ *
+ * @param {object} args
+ * @param {string} args.id
+ * @param {string | undefined} args.project
+ * @param {string | undefined} args.promptContent
+ * @param {number} [args.limit]
+ * @returns {{ title: string, tooltip: string }}
+ */
+export function composeSessionTitle(args: {
+    id: string;
+    project: string | undefined;
+    promptContent: string | undefined;
+    limit?: number;
+}): {
+    title: string;
+    tooltip: string;
+};

package/dist/lib/types/transcript/turnNav.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve the next visible turn index for a keyboard-nav step.
+ *
+ * @param {readonly number[]} turnIndices  ordered visible turn indices (display order)
+ * @param {number | undefined} current     the current anchor turn (typically the top visible turn)
+ * @param {1 | -1} dir                     +1 = down/next, -1 = up/prev
+ * @returns {number | undefined}           the turn to move to; `undefined` when there are no turns
+ */
+export function nextNavTurn(turnIndices: readonly number[], current: number | undefined, dir: 1 | -1): number | undefined;

package/dist/lib/types/transcript/view-model.d.ts

@@ -328,6 +328,28 @@ export type AnnotationVM = {
     preview?: string;
     isPrimary?: boolean;
 };
+/**
+ * A manual label applied to a single turn (entry), in the general host-defined
+ * taxonomy shape (arbitrary `typeId`/`typeName`/`value`) — distinct from the
+ * composite viewer's own `SavedLabel` (state-capabilities.js), which is the
+ * narrower fixed outcome/flag shape `LabelPopover` writes into `savedLabels`.
+ * `TurnLabel` is the framework-agnostic wire shape a host app's own annotation
+ * model maps to/from when it manages labelling outside the composite viewer.
+ * `id` is empty for an optimistic, not-yet-persisted label.
+ */
+export type TurnLabel = {
+    /**
+     * the entry index this label targets (`turn.index`)
+     */
+    entryIndex: number;
+    typeId: string;
+    typeName: string;
+    value: string;
+    /**
+     * host-assigned id; empty string for an optimistic pre-save
+     */
+    id: string;
+};
 /**
  * One file in the Files tab, with cooked churn. The adapter aggregates per-file
  * reads/writes/edits/deletes across all tool calls.