@qilin-agent/client-ui-chat 0.0.0-stage → 3.1.4

package/lib/types/client/chat/StatsPills.d.ts

@@ -0,0 +1,71 @@
+import type { UseProjection } from '@qilin-agent/api-session-controller/client';
+import type { InjectFace, SnapshotSelectorHook } from '@qilin-agent/client-ui-slots';
+import type { TokenUsageProjection } from '@qilin-agent/token-meter/client';
+import type { ChatViewSlotProps, PerformanceUsageInjected } from '../contract/slots.ts';
+import type { ChatSnapshot } from '../contract/snapshot.ts';
+interface WindowStats {
+    turns: number;
+    steps: number;
+    /** Summed request wall time (step/start → assistant/message); 0 when no node carries timing. */
+    llmMs: number;
+    /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */
+    toolMs: number;
+    /** Summed first-token latency over `ttftSteps`; 0 when no step records it. */
+    ttftMs: number;
+    /** Steps carrying a recorded TTFT. */
+    ttftSteps: number;
+    /** Summed decode wall time over steps that also report output tokens. */
+    decodeMs: number;
+    /** Summed output tokens over the same decode-timed steps. */
+    decodeTokens: number;
+}
+/**
+ * Fold assistant and tool-result nodes into window-scoped display totals —
+ * the FALLBACK for assemblies without the `sessionStats` projection.
+ *
+ * Every displayed figure rides that durable whole-log projection (and token
+ * accounting rides `tokenUsage`) because the window is paged and compaction
+ * rewrites it; this fold answers "what is on screen" only when no projection
+ * value is served. Its field names deliberately mirror the projection's so
+ * the two swap wholesale.
+ * @param nodes - snapshot nodes.
+ * @returns fallback counts and summed wall times.
+ */
+export declare function deriveStats(nodes: ChatSnapshot['legacy']['nodes']): WindowStats;
+/**
+ * Compact duration: 45.2s under a minute, 2m42s from there on.
+ * @param ms - duration in milliseconds.
+ * @returns display string.
+ */
+export declare function formatDuration(ms: number, t: ChatViewSlotProps['t']): string;
+/**
+ * Display-ready cache-hit share of prompt-side input over the whole durable log.
+ * @param usage - the session's token-usage projection value.
+ * @returns integer text when integer rounding stays below 100, otherwise the
+ * minimum decimal precision that still rounds below 100; a full hit returns
+ * 100, and no billed input returns null.
+ */
+export declare function cacheHitPercent(usage: TokenUsageProjection): string | null;
+/**
+ * Sum the three disjoint prompt-side billing buckets.
+ * @param usage - the session's token-usage projection value.
+ * @returns billed input tokens.
+ */
+export declare function billedInputTokens(usage: TokenUsageProjection): number;
+type Translate = ChatViewSlotProps['t'];
+/** Props shared by every composer stats pill: the conversation-snapshot selector plus the projection read seat. */
+export interface StatPillProps extends InjectFace<PerformanceUsageInjected> {
+    useChat: SnapshotSelectorHook<ChatSnapshot>;
+    useProjection: UseProjection;
+    /** The owning dock's locale seat. */
+    t: Translate;
+}
+/**
+ * Turn and step counts with whole-session speed, opening the time and speed
+ * dialog; Compact keeps only the speed reading.
+ */
+export declare const ActivityPill: import("react").MemoExoticComponent<({ useChat, useProjection, usePerformanceUsage, t }: StatPillProps) => import("react").JSX.Element | null>;
+/** Whole-log token total and cache hit; Compact keeps only the cache hit. */
+export declare const UsagePill: import("react").MemoExoticComponent<({ useProjection, usePerformanceUsage, t }: StatPillProps) => import("react").JSX.Element | null>;
+export {};
+//# sourceMappingURL=StatsPills.d.ts.map

package/lib/types/client/chat/SystemPromptRow.d.ts

@@ -0,0 +1,22 @@
+import type { ChatNodeViewProps, ChatViewSlotProps } from '../contract/slots.ts';
+/** Props for one complete system prompt disclosure. */
+export interface SystemPromptRowProps {
+    /** Complete model-visible prompt text. */
+    text: string;
+    /** True when the prompt replaced an earlier one from this position in the history. */
+    update?: boolean;
+    /** The owning view's locale seat. */
+    t: ChatViewSlotProps['t'];
+}
+/**
+ * Render one complete system prompt as a collapsed disclosure whose expanded
+ * body is the same opaque context chrome: 141px code-block scrollport and
+ * model-facing text with its real line breaks. An in-history update uses the
+ * same row under its own title.
+ * @param props - Complete prompt text, whether it is an update, and the locale seat.
+ * @returns The system-prompt disclosure row.
+ */
+export declare function SystemPromptRow({ text, update, t }: SystemPromptRowProps): import("react").JSX.Element;
+/** System-prompt keyed Chat renderer. */
+export declare const SystemPromptNodeView: import("react").MemoExoticComponent<({ node, t, }: Pick<ChatNodeViewProps<"system-prompt">, "node" | "t">) => import("react").JSX.Element>;
+//# sourceMappingURL=SystemPromptRow.d.ts.map

package/lib/types/client/chat/TurnNavigator.d.ts

@@ -0,0 +1,28 @@
+import type { ChatViewSlotProps } from '../contract/slots.ts';
+import type { TurnRailItem } from './turn-rail-items.ts';
+interface TurnNavigatorProps {
+    readonly items: readonly TurnRailItem[];
+    readonly activeTurn: number | null;
+    /** Turn whose jump is still paging history in; its mark pulses. */
+    readonly busyTurn: number | null;
+    readonly onNavigate: (item: TurnRailItem) => void;
+    readonly t: ChatViewSlotProps['t'];
+}
+/** Imperative controls for known turns; unknown turn numbers are ignored. */
+export interface TurnNavigatorHandle {
+    /** @param turn - turn to activate through the navigation callback. */
+    activateTurn(turn: number): void;
+    /** @param turn - turn to center in the rail without navigating the transcript. */
+    scrollToTurn(turn: number): void;
+}
+/**
+ * Fixed-pitch rail of every known Turn — loaded marks scroll, unloaded marks
+ * page history in first — with hover and focus previews. Overflow scrolls
+ * inside the frame, gradient fades marking each scrollable end, and the
+ * active mark centers only outside the fade-free band while the pointer is
+ * elsewhere. Previews follow pointer movement or focus, not scrolling under
+ * a stationary pointer.
+ */
+export declare const TurnNavigator: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<TurnNavigatorProps & import("react").RefAttributes<TurnNavigatorHandle>>>;
+export {};
+//# sourceMappingURL=TurnNavigator.d.ts.map

package/lib/types/client/chat/TurnProcessNodeView.d.ts

@@ -0,0 +1,4 @@
+import type { ChatNodeViewProps } from '../contract/slots.ts';
+/** Settled Turn duration and process disclosure above its content. */
+export declare const TurnProcessNodeView: import("react").MemoExoticComponent<({ node, turnProcess, t, }: ChatNodeViewProps<"turn-process">) => import("react").JSX.Element | null>;
+//# sourceMappingURL=TurnProcessNodeView.d.ts.map

package/lib/types/client/chat/TurnTailNodeView.d.ts

@@ -0,0 +1,7 @@
+import type { InjectFace, PropsRenderSlots } from '@qilin-agent/client-ui-slots';
+import type { ChatNodeViewProps, PerformanceUsageInjected } from '../contract/slots.ts';
+type TurnTailNodeViewProps = ChatNodeViewProps<'turn-tail'> & PropsRenderSlots<'conversation.chat.turnTail' | 'conversation.chat.assistant-actions'> & InjectFace<PerformanceUsageInjected>;
+/** Turn-local actions and feature tail over the Location index, independent of Assistant placement. */
+export declare const TurnTailNodeView: import("react").MemoExoticComponent<({ node, openFile, forkAt, renderSlot, t, useChat, usePerformanceUsage, }: TurnTailNodeViewProps) => import("react").JSX.Element | null>;
+export {};
+//# sourceMappingURL=TurnTailNodeView.d.ts.map

package/lib/types/client/chat/TurnTriggerNodeView.d.ts

@@ -0,0 +1,4 @@
+import type { ChatNodeViewProps } from '../contract/slots.ts';
+/** Render recorded trigger attribution above the whole-Turn disclosure. */
+export declare function TurnTriggerNodeView({ node, t }: Pick<ChatNodeViewProps<'turn-trigger'>, 'node' | 't'>): import("react").JSX.Element;
+//# sourceMappingURL=TurnTriggerNodeView.d.ts.map

package/lib/types/client/chat/TurnUsagePanel.d.ts

@@ -0,0 +1,15 @@
+/** Completed-Turn token usage action and its accounting details dialog. */
+import type { TurnTokenUsage } from '../contract/chat-nodes.ts';
+import type { ChatViewSlotProps } from '../contract/slots.ts';
+export interface TurnUsagePanelProps {
+    usage: TurnTokenUsage;
+    /** The owning view's locale seat, passed down as a plain prop. */
+    t: ChatViewSlotProps['t'];
+}
+/**
+ * Turn-usage IconActions pill with a click-open Turn-usage details dialog.
+ * @param props - Turn usage buckets and locale seat.
+ * @returns The trigger and, while open, its portaled dialog anchored above the trigger.
+ */
+export declare function TurnUsagePanel({ usage, t }: TurnUsagePanelProps): import("react").JSX.Element;
+//# sourceMappingURL=TurnUsagePanel.d.ts.map

package/lib/types/client/chat/flow-motion.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fade-then-close transitions owned by one Chat viewport. Rows fade before their boxes close;
+ * the owner reserves removed height and holds scrolling until that viewport's folds finish.
+ * Motion is opt-in under `[data-chat-motion]`, respects reduced motion, and clears temporary styles.
+ */
+import { type RefObject } from 'react';
+/** Row-local operations supplied by the containing viewport. */
+export interface FlowMotionRows {
+    /** @param element - visible row. @param done - commits hidden state before idle callbacks run. */
+    collapse(element: HTMLElement, done: () => void): void;
+    /** @param element - newly visible row to grow to its natural size. */
+    reveal(element: HTMLElement): void;
+    /** @param element - row whose active transition should be cancelled without hiding it. */
+    cancelMotion(element: HTMLElement): void;
+}
+/** Animation lifetime and fold coordination for one viewport. */
+export interface FlowMotion extends FlowMotionRows {
+    /** @returns whether a row owned by this viewport is closing. */
+    foldActive(): boolean;
+    /** @param listener - callback after the last fold. @returns cancellation for a pending callback. */
+    onFoldIdle(listener: () => void): () => void;
+    /** Cancel owned animations and pending work when the viewport detaches. */
+    clear(): void;
+}
+/**
+ * Decide whether a row may animate: inside a live scope and not under reduced motion.
+ * @param element - row about to be hidden.
+ * @returns whether the fade-then-close transition applies.
+ */
+export declare function motionEnabled(element: HTMLElement): boolean;
+/**
+ * Whether a row is already hidden or on its way there.
+ * @param element - row under Turn-level visibility control.
+ * @returns hidden attribute present or a collapse transition outstanding.
+ */
+export declare function hiddenOrCollapsing(element: HTMLElement): boolean;
+/**
+ * Create animation coordination without cross-viewport broadcasts.
+ * @param reserve - reserve the deduplicated removed height in this viewport.
+ * @param foldingChanged - disable or restore this viewport's native scroll anchoring.
+ * @returns stable callbacks and cleanup for this viewport's animations.
+ */
+export declare function createFlowMotion(reserve: (px: number) => void, foldingChanged: (active: boolean) => void): FlowMotion;
+/**
+ * Apply searchable hiding with the containing Chat viewport's optional fold animation.
+ * @param hidden - desired visibility.
+ * @param reveal - browser-find and focus-protection callback.
+ * @param motion - owning viewport's row callbacks; absent in standalone rendering.
+ * @returns the stable subtree ref.
+ */
+export declare function useFlowHidden(hidden: boolean, reveal: () => void, motion: FlowMotionRows | undefined): RefObject<HTMLDivElement>;
+/**
+ * Toggle a plain hidden attribute on the fold clock, growing newly revealed headers.
+ * @param ref - element whose visibility follows hidden.
+ * @param hidden - desired hidden state.
+ * @param motion - containing viewport's row callbacks.
+ */
+export declare function useMotionHidden(ref: RefObject<HTMLElement | null>, hidden: boolean, motion: FlowMotionRows): void;
+//# sourceMappingURL=flow-motion.d.ts.map

package/lib/types/client/chat/message-chrome.d.ts

@@ -0,0 +1,50 @@
+import type { Translate } from '@qilin-agent/client-ui-slots';
+/** The date-template share of the conversation dictionary the clock consumes. */
+export type ClockTranslate = Translate<'clock.md' | 'clock.ymd'>;
+/** The elapsed-duration share of the conversation dictionary. */
+export type RunDurationTranslate = Translate<'duration.secondUnit' | 'duration.minuteUnit' | 'duration.hourUnit'>;
+/** Refresh interval for whole-second live run clocks. */
+export declare const LIVE_RUN_CLOCK_INTERVAL_MS = 1000;
+/**
+ * Local calendar-day epoch (ms at local midnight) for an instant.
+ * @param ms - Unix epoch ms.
+ * @returns Midnight of that local calendar day.
+ */
+export declare function startOfLocalDay(ms: number): number;
+/**
+ * Delay until the next local midnight after `ms` (at least 1ms).
+ * @param ms - Unix epoch ms.
+ * @returns Milliseconds until the following local midnight.
+ */
+export declare function msUntilNextLocalMidnight(ms: number): number;
+/** One numeric value or localized unit in an elapsed-time label. */
+export interface RunDurationPart {
+    readonly text: string;
+    readonly numeric: boolean;
+}
+/**
+ * Build elapsed-time fragments for both live and completed Turn labels.
+ * @param ms - elapsed milliseconds; negatives clamp to zero and fractions floor.
+ * @param t - translate seat supplying units and their trailing spacing.
+ * @returns numbers and localized units in display order, without leading zeros;
+ * minutes start at 60 seconds and hours at 60 minutes.
+ */
+export declare function formatRunDuration(ms: number, t: RunDurationTranslate): RunDurationPart[];
+/**
+ * Decode-throughput figure: whole tokens from ten up, one decimal below.
+ * @param tps - Tokens per second.
+ * @returns Display number without unit.
+ */
+export declare function formatTokensPerSecond(tps: number): string;
+/**
+ * Compact local timestamp for message IconActions. Same calendar day →
+ * `HH:mm`; earlier this year → the `clock.md` date template + clock; other
+ * years → the `clock.ymd` template + clock. Pure: the date templates arrive
+ * through the caller's locale seat.
+ * @param time - Unix epoch ms from the source session event.
+ * @param t - translate seat supplying the `clock.md` / `clock.ymd` templates.
+ * @param now - Reference instant for the day/year cut (defaults to wall clock).
+ * @returns Date-aware clock string (24-hour, zero-padded time).
+ */
+export declare function formatMessageClock(time: number, t: ClockTranslate, now?: number): string;
+//# sourceMappingURL=message-chrome.d.ts.map

package/lib/types/client/chat/register-node-renderers.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { PerformanceUsageMode } from '../../chat-settings.ts';
+import type { ChatPresentationPolicy } from '../presentation-policy.ts';
+/**
+ * Register this package's business renderers behind the keyed Chat Node seat.
+ * Renderers whose output depends on the work-details mode receive the policy
+ * through their own registration; the seat and the other renderers do not.
+ * @param ctx - owning UI Conversation context.
+ * @param performanceUsage - live statistics detail preference.
+ * @param presentation - live presentation policy.
+ */
+export declare function registerChatNodeRenderers(ctx: Context, performanceUsage: ObservableSnapshot<PerformanceUsageMode>, presentation: ObservableSnapshot<ChatPresentationPolicy>): void;
+//# sourceMappingURL=register-node-renderers.d.ts.map

package/lib/types/client/chat/render-entry.d.ts

@@ -0,0 +1,9 @@
+/** Stable React identities for the two grouping reference kinds. */
+import type { RenderEntry } from '@qilin-agent/client-ui-conversation/client';
+/**
+ * Identify a rendering position independently of presentation mode.
+ * @param entry - mode-independent rendering reference.
+ * @returns its collision-free React key.
+ */
+export declare function chatRenderKey(entry: RenderEntry): string;
+//# sourceMappingURL=render-entry.d.ts.map

package/lib/types/client/chat/searchable-hidden.d.ts

@@ -0,0 +1,17 @@
+import { type RefObject } from 'react';
+/**
+ * Optional visibility operation; its caller owns cancellation and eventually commits the attribute.
+ * @param element - stable subtree root.
+ * @param hidden - desired hidden state.
+ * @param commit - apply the final visibility before reporting the operation complete.
+ */
+export type HiddenTransition = (element: HTMLElement, hidden: boolean, commit: () => void) => void;
+/**
+ * Apply searchable hidden state without unmounting a stable subtree.
+ * @param hidden - whether the subtree is currently hidden.
+ * @param reveal - callback for browser find's beforematch reveal.
+ * @param transition - optional caller-owned visibility operation; otherwise apply synchronously.
+ * @returns ref for the stable subtree root.
+ */
+export declare function useSearchableHidden(hidden: boolean, reveal: () => void, transition?: HiddenTransition): RefObject<HTMLDivElement>;
+//# sourceMappingURL=searchable-hidden.d.ts.map

package/lib/types/client/chat/stat-dialog.d.ts

@@ -0,0 +1,20 @@
+import { type CSSProperties, type MutableRefObject } from 'react';
+/**
+ * Unplaced portal panel: hidden but laid out so the clamp measures real
+ * dimensions (the `useAnchoredPosition` measure pass).
+ */
+export declare const MEASURE_STYLE: CSSProperties;
+/** Open state, refs, and clamped placement for one stat dialog. */
+export interface StatDialogSeat {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    rootRef: MutableRefObject<HTMLSpanElement | null>;
+    panelRef: MutableRefObject<HTMLDivElement | null>;
+    pos: CSSProperties | null;
+}
+/**
+ * One trigger-anchored dialog seat: open state, viewport-clamped placement, outside-close.
+ * @returns the seat; spread `pos ?? MEASURE_STYLE` onto the portaled panel.
+ */
+export declare function useStatDialog(): StatDialogSeat;
+//# sourceMappingURL=stat-dialog.d.ts.map

package/lib/types/client/chat/step-process.d.ts

@@ -0,0 +1,11 @@
+/** Localized titles for projected step-process activity. */
+import type { ChatViewSlotProps } from '../contract/slots.ts';
+import type { ProcessActivitySummary } from '../contract/process-groups.ts';
+/**
+ * Compose a closed group's localized title from its top three categories without counts.
+ * @param summary - ranked work and phase evidence for this range.
+ * @param t - Chat namespace translator.
+ * @returns the secondary disclosure title.
+ */
+export declare function processTitle(summary: ProcessActivitySummary, t: ChatViewSlotProps['t']): string;
+//# sourceMappingURL=step-process.d.ts.map

package/lib/types/client/chat/token-format.d.ts

@@ -0,0 +1,25 @@
+import type { ChatViewSlotProps } from '../contract/slots.ts';
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M.
+ * @param value - non-negative token count.
+ * @param t - Chat locale seat.
+ * @returns locale-owned compact display string.
+ */
+export declare function formatTokens(value: number, t: ChatViewSlotProps['t']): string;
+/**
+ * Exact integer token count with locale-owned digit grouping.
+ * @param value - non-negative safe integer token count.
+ * @param t - Chat locale seat.
+ * @returns an unrounded display string.
+ */
+export declare function formatExactTokens(value: number, t: ChatViewSlotProps['t']): string;
+/**
+ * Display-ready cache-hit share without rounding a partial hit to 100%.
+ * @param cacheReadTokens - exact prompt tokens served from cache.
+ * @param promptTokens - exact aggregate prompt tokens.
+ * @param decimalPlaces - ordinary-ratio precision; partial hits that would
+ * round to 100 automatically use enough additional precision to stay honest.
+ * @returns percentage text, or null when there was no prompt input.
+ */
+export declare function formatCacheHitPercent(cacheReadTokens: number, promptTokens: number, decimalPlaces?: 0 | 1): string | null;
+//# sourceMappingURL=token-format.d.ts.map

package/lib/types/client/chat/turn-assistant.d.ts

@@ -0,0 +1,8 @@
+import type { AssistantBlock } from '../contract/snapshot.ts';
+/**
+ * Collect visible prose from one Assistant lifecycle.
+ * @param blocks - Assistant content blocks.
+ * @returns concatenated text blocks.
+ */
+export declare function assistantText(blocks: readonly AssistantBlock[]): string;
+//# sourceMappingURL=turn-assistant.d.ts.map

package/lib/types/client/chat/turn-rail-items.d.ts

@@ -0,0 +1,37 @@
+/**
+ * View-layer union of the host turn outline and the loaded rail items. The
+ * conversation snapshot never carries projection values, so this merge is the
+ * one place the rail's two sources meet: the `turnOutline` projection names
+ * every turn of the session, and the loaded window supplies anchors and
+ * richer previews for the turns it holds.
+ */
+import { SessionSeq } from '@qilin-agent/session/types';
+import type { TurnNavigationItem } from '../contract/snapshot.ts';
+/** One rail mark: a loaded Turn scrolls to its row; an unloaded one pages history through its seq first. */
+export interface TurnRailItem {
+    readonly turn: number;
+    /** Bounded prompt preview (loaded window first, outline fallback). */
+    readonly prompt: string;
+    /** Bounded response preview (loaded window first, outline fallback). */
+    readonly response: string;
+    /** How the rail reaches the Turn. */
+    readonly anchor: {
+        readonly kind: 'loaded';
+        readonly key: string;
+    } | {
+        readonly kind: 'unloaded';
+        readonly seq: SessionSeq;
+    };
+}
+/**
+ * Merge the host outline with the loaded rail items into the full ladder.
+ * A turn present in both sides keeps the loaded anchor, taking an outline
+ * preview only where the window's own is empty (a mid-Turn window head, or a
+ * turn whose loaded nodes carry no text); turns on one side only pass
+ * through. Result ascends by turn.
+ * @param loaded - loaded-window rail items (timeline order).
+ * @param outline - `turnOutline` projection value, treated as wire data.
+ * @returns every known turn, ascending; a stable empty array when none.
+ */
+export declare function mergeTurnRailItems(loaded: readonly TurnNavigationItem[], outline: unknown): readonly TurnRailItem[];
+//# sourceMappingURL=turn-rail-items.d.ts.map

package/lib/types/client/chat/turn-trigger.d.ts

@@ -0,0 +1,15 @@
+/** Presentation of durable non-human messages claimed to begin a Turn. */
+import type { ContextMessageNode } from '../contract/snapshot.ts';
+import type { ChatKey } from '../locale.ts';
+/** Existing primitive glyph selected for a Turn trigger's source family. */
+export type TurnTriggerIcon = 'agent' | 'github' | 'goal' | 'job' | 'plugin' | 'request' | 'schedule' | 'subagent' | 'team' | 'webhook';
+/**
+ * Describe a waking message using its source and recognized producer framing.
+ * @param node - durable context, including the original notification body.
+ * @returns localized title key and source-family icon.
+ */
+export declare function turnTriggerDetails(node: ContextMessageNode): {
+    title: ChatKey;
+    icon: TurnTriggerIcon;
+};
+//# sourceMappingURL=turn-trigger.d.ts.map

package/lib/types/client/chat/use-calendar-day.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Local calendar-day epoch that advances at each local midnight.
+ * @returns Midnight ms for the current local day; updates after the boundary.
+ */
+export declare function useCalendarDay(): number;
+//# sourceMappingURL=use-calendar-day.d.ts.map

package/lib/types/client/chat/use-chat-navigation.d.ts

@@ -0,0 +1,69 @@
+import type { ChatNode } from '../contract/chat-nodes.ts';
+import type { ChatViewSlotProps } from '../contract/slots.ts';
+import type { TurnRailItem } from './turn-rail-items.ts';
+import type { ChatReading, ReadingSample } from './use-chat-reading.ts';
+import type { ChatViewport } from './use-chat-viewport.ts';
+/** History availability and loading operations for the committed Chat window. */
+export interface ChatNavigationInput extends Pick<ChatViewSlotProps, 'loadOlder' | 'loadThrough'> {
+    readonly firstSeq: ChatNode['anchorSeq'] | null;
+    readonly hasMore: boolean;
+    readonly loadingOlder: boolean;
+}
+/** Owns one replaceable turn jump and the anchor retained while history loads. */
+export declare class ChatNavigation {
+    private readonly viewport;
+    private readonly reading;
+    private input;
+    private readonly onBusyTurn;
+    private jump;
+    private settleFrame;
+    constructor(viewport: ChatViewport, reading: ChatReading, input: ChatNavigationInput, onBusyTurn: (turn: number | null) => void);
+    /**
+     * Adopt committed history availability without starting a request.
+     * @param input - history state from the latest committed render.
+     */
+    setInput(input: ChatNavigationInput): void;
+    /** Cancel navigation when opening a Chat view. */
+    reset(): void;
+    /** Cancel local callbacks; late history completions cannot revive a task. */
+    dispose(): void;
+    /** Release the jump, paging anchor, and busy indicator without cancelling shared history I/O. */
+    cancel(): void;
+    private clearTask;
+    /**
+     * Replace the current jump with an explicit turn selection.
+     * @param item - loaded anchor or unloaded turn to fetch before landing.
+     */
+    readonly navigateToTurn: (item: TurnRailItem) => void;
+    /** Request one older page while retaining the current semantic position. */
+    readonly loadEarlier: () => void;
+    /**
+     * Preserve reader ownership across pending history work.
+     * @param sample - settled reader movement that can update or interrupt an anchor.
+     */
+    readerSampled(sample: ReadingSample): void;
+    /**
+     * Preserve one paging anchor after a commit or a later size change, regardless of head identity.
+     * @returns whether the retained anchor handled the layout change.
+     */
+    contentCommitted(): boolean;
+    /** Retarget a still-loading page only after inner or outer reader scrolling ends. */
+    readerSettled(): void;
+    /** Land, retry, or complete the current jump against the committed window. */
+    reconcile(): void;
+    private landJump;
+    private request;
+    private cancelFrame;
+}
+/**
+ * Retain one navigation owner for the component's lifetime.
+ * @param viewport - turn-aware DOM operations.
+ * @param reading - reading and follow policy receiving navigation landings.
+ * @param input - committed history state and load operations.
+ * @returns the navigation owner and its visible busy turn.
+ */
+export declare function useChatNavigation(viewport: ChatViewport, reading: ChatReading, input: ChatNavigationInput): {
+    navigation: ChatNavigation;
+    busyTurn: number | null;
+};
+//# sourceMappingURL=use-chat-navigation.d.ts.map

package/lib/types/client/chat/use-chat-reading.d.ts

@@ -0,0 +1,110 @@
+import type { ChatScrollPosition, ChatViewSlotProps } from '../contract/slots.ts';
+import type { ChatViewport, ViewportLanding, ViewportScroll } from './use-chat-viewport.ts';
+import { type ScrollFollow } from './use-scroll-follow.ts';
+/** Reading facts that affect Chat chrome and initial rail placement. */
+export interface ChatReadingState {
+    readonly initialized: boolean;
+    readonly followingTail: boolean;
+    readonly activeTurn: number | null;
+}
+/** Settled reader position delivered to history-navigation policy. */
+export interface ReadingSample {
+    readonly position: ChatScrollPosition | null;
+    readonly movedByReader: boolean;
+    readonly followingTail: boolean;
+}
+type PositionStore = ChatViewSlotProps['chatScroll'];
+/** Owns reading policy and its cancellable sampling work, without DOM access. */
+export declare class ChatReading {
+    private readonly viewport;
+    private store;
+    private state;
+    private readonly onChange;
+    private readonly follow;
+    private sampleTimer;
+    private probeFrame;
+    /** Settled reader row and offset, re-aligned when a layout change moves it. */
+    private readerPosition;
+    private sampled;
+    constructor(viewport: ChatViewport, store: PositionStore, state: ChatReadingState, onChange: (state: ChatReadingState) => void, follow: ScrollFollow);
+    /**
+     * Expose pending reader ownership to navigation and resize handlers.
+     * @returns whether reader input still awaits interval or scrollend sampling.
+     */
+    get pending(): boolean;
+    /**
+     * Expose the active follow policy.
+     * @returns whether content growth retains bottom-follow ownership.
+     */
+    get followingTail(): boolean;
+    /**
+     * Adopt the committed Session's scroll memory.
+     * @param store - scroll memory for the current Session.
+     */
+    setStore(store: PositionStore): void;
+    /**
+     * Connect history policy to settled reading observations.
+     * @param sampled - receives settled reader positions.
+     * @returns a disposer that disconnects only this listener.
+     */
+    connect(sampled: (sample: ReadingSample) => void): () => void;
+    /** Cancel timers and animation frames and detach the sample listener. */
+    dispose(): void;
+    /** Release bottom follow and pending sampling for an explicit navigation. */
+    pauseFollowing(): void;
+    /**
+     * Land at the current floor and clear saved reader position.
+     * @param behavior - immediate positioning, or one native animation when the reader's own input moved the tail.
+     */
+    followTail(behavior?: 'instant' | 'smooth'): void;
+    /** Stop a native follow animation where it is; the next sampled position decides follow intent. */
+    interruptFollow(): void;
+    /** Restore the Session's semantic position, or follow the tail when none is saved. */
+    restore(): void;
+    /**
+     * Adopt a known landing without rediscovering its anchor.
+     * @param landing - measured navigation result that replaces pending reader input.
+     */
+    acceptNavigation(landing: ViewportLanding): void;
+    /**
+     * Retain reading policy while history changes the anchor's geometry.
+     * @param landing - compensated position that retains the current reading policy.
+     */
+    preservePosition(landing: ViewportLanding): void;
+    /**
+     * Handle pinned layout movement and reader arrivals at the floor immediately.
+     * @param scroll - attributed scroll delivery; other reader movement remains pending until sampled.
+     */
+    readonly onScroll: (scroll: ViewportScroll) => void;
+    /**
+     * Settle pending reader movement; only the outer scroller can finish its native follow animation.
+     * @param outer - whether the event belongs to the outer scroller rather than a process body.
+     */
+    readonly onScrollEnd: (outer?: boolean) => void;
+    /**
+     * Reconcile a layout change without overriding unsampled reader input.
+     * A resize the reader did not cause moves their row; put it back on its
+     * sampled offset before resolving the reading line from the new layout.
+     */
+    onResize(): void;
+    /** Resolve the active turn from tail ownership or a coalesced reading-line probe. */
+    refreshActiveTurn(): void;
+    private commit;
+    private publish;
+    private cancelPending;
+    private readonly probe;
+    private readonly flushSample;
+}
+/**
+ * Retain reading policy and expose only changes in visible reading state.
+ * @param viewport - turn-aware DOM operations.
+ * @param store - Session-owned semantic scroll memory.
+ * @param initialTurn - latest loaded turn before the first landing.
+ * @returns the reading owner and its React-visible state.
+ */
+export declare function useChatReading(viewport: ChatViewport, store: PositionStore, initialTurn: number | null): {
+    reading: ChatReading;
+    state: ChatReadingState;
+};
+export {};
+//# sourceMappingURL=use-chat-reading.d.ts.map