@khorsheed/dsh-message-timeline 0.2.3 → 0.2.5

package/lib/types/client/TimelineRail.js

@@ -3,19 +3,30 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Message timeline panel, browser half. One entry in the official
  * conversation.session.header.utilities seat anchors the plugin into the
  * session scope and renders, through a body portal, the flat floating
- * timeline over the left edge of the chat scrollport: one row per loaded
- * user message — a tick plus an ellipsized one-line preview, no frame and no
+ * timeline over the left edge of the chat scrollport: one row per user
+ * message — a tick plus an ellipsized one-line preview, no frame and no
  * visible scrollbar. At rest only the dimmed ticks show, the reading
  * position's tick in blue (the latest message until the tracker answers);
  * hovering or keyboard-focusing the panel reveals the row texts with the
  * blue row on top, and clicking a row jumps the transcript to that message.
  * The panel is always on while the chat view shows; the `enabled` config is
  * the off switch.
+ *
+ * The row list is whole-session from the moment the session opens: the host
+ * `turnOutline` projection names every started turn, and the loaded chat
+ * window overlays richer previews (plus steering rows and message-tools
+ * bubbles) for the turns it covers. A turn outside the window renders as a
+ * dimmed outline row; confirming it pages history back through the turn's
+ * `turn/start` seq (the session jump loader) and lands on the freshly loaded
+ * row. When the host serves no turnOutline value the panel degrades to the
+ * loaded window alone, paged by prefetch and panel-top scrolls.
  */
 import { memo, useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { PANEL_WIDTH_MIN } from './config.js';
 import { chatHookOf } from './chat-hook.js';
+import { outlineEntries } from './outline.js';
+import { mergeRows, firstVisibleKeyInTurn } from './rows.js';
 import { previewText } from './preview.js';
 import { foldHiddenSpans, isSeqHidden } from './hidden-spans.js';
 import { isTimelineRowKind, EDIT_KIND, RESTORED_KIND } from './timeline-kinds.js';
@@ -24,6 +35,35 @@ import css from './TimelineRail.module.css';
 function nodeContent(node) {
     return node.data.content ?? [];
 }
+/**
+ * One row's display text: the loaded row's joined text blocks, or the outline
+ * entry's bounded first-prompt preview. `null` means the message carries no
+ * text (an image/attachment-only input, or an automated turn with no human
+ * prompt) — the row renders the `rail.empty` label instead.
+ */
+function rowPreview(row) {
+    return row.kind === 'loaded'
+        ? previewText(nodeContent(row.node))
+        : (row.prompt !== '' ? row.prompt : null);
+}
+/**
+ * The row's display label: the text preview when there is one, else a
+ * kind-aware fallback — the turn number for an outline-only turn, and an
+ * image/attachment label for a loaded message with no text blocks.
+ */
+function rowLabel(row, t) {
+    const preview = rowPreview(row);
+    if (preview !== null)
+        return preview;
+    if (row.kind === 'outline')
+        return t('rail.turn', { turn: row.turn });
+    const types = new Set(nodeContent(row.node).map(block => block.type));
+    if (types.has('image'))
+        return t('rail.image');
+    if (types.has('file'))
+        return t('rail.attachment');
+    return t('rail.empty');
+}
 /**
  * Horizontal panel padding, matching `.panel`'s `padding: 4px 8px`: the text
  * band sits this far inside the box, so the width budget must give it back
@@ -34,12 +74,18 @@ const PANEL_PADDING_X = 8;
 const PANEL_GAP = 16;
 /** Degraded width cap (fraction of the scrollport) while the flow probe is unanswered. */
 const DEGRADED_WIDTH_RATIO = 0.4;
+/**
+ * Frames an outline jump retries the DOM scroll after its row materializes in
+ * the chat store: the transcript renders the new page in the same commit or a
+ * near frame, and a half-second budget covers the skew without hanging.
+ */
+const JUMP_RETRY_FRAMES = 30;
 /**
  * The header-utilities entry: the portal timeline panel.
  * @param props - composed props (see {@link TimelineRailProps}).
  * @returns nothing visible in the seat; the floating panel while the chat view shows.
  */
-export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPages, loadOlder, jumpTo, useRail, t, ...standard }) {
+export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPages, loadOlder, loadThrough, jumpTo, useRail, t, ...standard }) {
     const rail = useRail(s => s);
     // Chat data lives in the `useChat` standard prop on 0.1.2 (the rc-line
     // session-snapshot seat is gone); the helper degrades to an empty slice
@@ -50,6 +96,13 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
     const nodes = useChatSlice(c => c.nodes);
     const hasMore = useSession(s => s.hasMore);
     const loadingOlder = useSession(s => s.loadingOlder);
+    // The host projection seat exists on every supported host; the VALUE is
+    // present only where the assembly mounts the turn-outline unit. Both reads
+    // degrade to undefined, which keeps the window-paging list. The narrow is
+    // memoized on the projection's reference-stable value so unrelated renders
+    // do not churn the merged list (or re-run the jump effect).
+    const outlineValue = standard.useProjection?.('turnOutline');
+    const outline = useMemo(() => outlineEntries(outlineValue), [outlineValue]);
     const items = useMemo(() => {
         // The node store is an in-memory snapshot; take it once so the span fold
         // and the message-tools append read the same snapshot.
@@ -74,7 +127,7 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
         // ordinary session carries no span node, so the fold is empty and every
         // order row still renders: this filter never alters the baseline.
         const hidden = (node) => isSeqHidden(spans, node.anchorSeq);
-        const result = [];
+        const loaded = [];
         const seen = new Set();
         for (const key of order) {
             const node = nodes.get(key);
@@ -84,7 +137,7 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
                 continue;
             if (hidden(node))
                 continue;
-            result.push({ key, node });
+            loaded.push({ key, node });
             seen.add(key);
         }
         // After a message-tools in-place edit the replacement materializes as a
@@ -105,7 +158,7 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
                 continue;
             if (hidden(node))
                 continue;
-            result.push({ key: node.key, node });
+            loaded.push({ key: node.key, node });
             seen.add(node.key);
         }
         // The order loop is seq-sorted, but the appended bubbles walked the store
@@ -116,22 +169,95 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
         // ordinary session has no appended bubbles, so this never reorders the
         // baseline (which is already seq-sorted). Dropped rows are gone before the
         // sort, so a withdrawn original never resurfaces.
-        result.sort((left, right) => left.node.anchorSeq - right.node.anchorSeq);
-        return result;
-    }, [order, nodes, includeSteering]);
+        loaded.sort((left, right) => left.node.anchorSeq - right.node.anchorSeq);
+        return mergeRows(loaded, outline);
+    }, [order, nodes, includeSteering, outline]);
     // The lit row: the hover/arrow preselection while it moves, otherwise the
     // live reading position the tracker publishes, defaulting to the latest
     // message before the tracker answers. ArrowUp/Down or hovering moves a
-    // bold preselection; Enter or a click confirms it and jumps.
+    // bold preselection; Enter or a click confirms it and jumps. Loaded rows
+    // identify by their node key (the tracker's active marker speaks the same
+    // key); outline rows identify as `turn:<n>`.
     const [focusKey, setFocusKey] = useState(null);
-    const current = focusKey ?? rail.activeKey ?? items.at(-1)?.key ?? null;
+    const current = focusKey ?? rail.activeKey ?? items.at(-1)?.id ?? null;
     const panelRef = useRef(null);
+    const [pendingJump, setPendingJump] = useState(null);
+    // A jump never crosses sessions; the entry's session identity switches
+    // without a remount when the main view moves.
+    useEffect(() => { setPendingJump(null); }, [sessionId]);
+    // The window head: the first visible node's anchorSeq (ChatView's firstSeq
+    // derivation), the coverage line for the outline jump's re-request guard.
+    const firstSeq = useMemo(() => {
+        const firstKey = order[0];
+        if (firstKey === undefined)
+            return null;
+        return nodes.get(firstKey)?.anchorSeq ?? null;
+    }, [order, nodes]);
+    // The outline-jump state machine. Fire (click) only arms the jump; this
+    // effect owns every loadThrough request, the landing scroll, and the give-
+    // up fallback, re-running as the window, the paging flags, or the jump
+    // itself change. The loop converges because loadThrough pages until the
+    // window covers the target seq (or history runs out), and a settle that
+    // moved nothing falls through to the fallback instead of re-requesting.
+    useEffect(() => {
+        if (pendingJump === null || pendingJump.sessionId !== sessionId)
+            return;
+        // Scroll to a key once its transcript row renders (the same commit or a
+        // near frame); the returned cleanup cancels the retries.
+        const landOn = (key) => {
+            let cancelled = false;
+            let frames = 0;
+            const attempt = () => {
+                if (cancelled)
+                    return;
+                frames += 1;
+                if (jumpTo(key) || frames >= JUMP_RETRY_FRAMES) {
+                    setPendingJump(null);
+                    return;
+                }
+                (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : setTimeout)(attempt);
+            };
+            attempt();
+            return () => { cancelled = true; };
+        };
+        const landed = items.find((row) => row.kind === 'loaded' && row.turn === pendingJump.turn);
+        if (landed !== undefined)
+            return landOn(landed.key);
+        // No user-kind row for the turn: an automated turn (a restart/scheduled
+        // trigger renders as `turn-trigger`, not a user row) or a withdraw-hidden
+        // prompt. Land on the turn's first visible loaded node of any kind — the
+        // official rail's `user ?? loaded[0]` anchor.
+        const end = outline?.find(entry => entry.turn > pendingJump.turn)?.seq ?? Number.POSITIVE_INFINITY;
+        const anyKey = firstVisibleKeyInTurn(order, nodes, pendingJump.seq, end);
+        if (anyKey !== null)
+            return landOn(anyKey);
+        if (pendingJump.awaiting || loadingOlder)
+            return;
+        // Settled (or freshly armed) without any visible row for the turn: page
+        // again while the window head still moves and history remains; a stalled
+        // head lands on the nearest loaded row at/after the turn instead.
+        const uncovered = firstSeq === null || firstSeq > pendingJump.seq;
+        if (uncovered && hasMore && (!pendingJump.requested || pendingJump.fromHead !== firstSeq)) {
+            const jump = pendingJump;
+            setPendingJump({ ...jump, requested: true, awaiting: true, fromHead: firstSeq });
+            void loadThrough(jump.seq).then(() => {
+                setPendingJump(current => current !== null && current.sessionId === jump.sessionId && current.turn === jump.turn
+                    ? { ...current, awaiting: false }
+                    : current);
+            });
+            return;
+        }
+        const fallback = items.find((row) => row.kind === 'loaded' && row.anchorSeq >= pendingJump.seq);
+        if (fallback !== undefined)
+            jumpTo(fallback.key);
+        setPendingJump(null);
+    }, [items, pendingJump, sessionId, loadingOlder, hasMore, firstSeq, jumpTo, loadThrough, order, nodes, outline]);
     // The panel is a chat-view affordance: hide it while the session shows
     // another tab (trajectory etc.), detected through ChatView's data-chat-flow
-    // marker. `active` splits from `visible` so history paging can bootstrap: a
-    // session whose loaded event window holds no user message yet (a huge
-    // assistant turn pushed it past the first page) renders no rows but must
-    // still pull pages until one materializes.
+    // marker. With the outline the list starts whole; without it a session
+    // whose loaded event window holds no user message yet (a huge assistant
+    // turn pushed it past the first page) renders no rows but must still pull
+    // pages until one materializes — hence `active` splits from `visible`.
     const active = rail.chatView && rail.ready && rail.sessionId === sessionId;
     const visible = active && items.length > 0;
     // The panel must never cover the message flow: its width is the configured
@@ -155,61 +281,81 @@ export function TimelineRail({ sessionId, includeSteering, panelWidth, initialPa
         panelRef.current?.querySelector(`[data-item-key=${JSON.stringify(current)}]`)
             ?.scrollIntoView({ block: 'nearest' });
     }, [current]);
-    // Prefetch history while the panel is on a chat view: keep pulling pages
-    // until the first user message materializes (bootstrap), then until
-    // initialPages pages arrived, so the list starts near-complete. Older
-    // pages load on demand when the panel scrolls to its top.
+    // Fallback mode (no outline) prefetches history while the panel is on a
+    // chat view: keep pulling pages until the first user message materializes
+    // (bootstrap), then until initialPages pages arrived, so the list starts
+    // near-complete. Older pages load on demand when the panel scrolls to its
+    // top. The outline mode skips this entirely — the projection already names
+    // every turn, so no page has to arrive for the list to be complete.
     const prefetchedPagesRef = useRef(0);
     useEffect(() => {
         if (!active) {
             prefetchedPagesRef.current = 0;
             return;
         }
+        if (outline !== undefined)
+            return;
         if (!hasMore || loadingOlder)
             return;
         if (items.length > 0 && prefetchedPagesRef.current >= initialPages)
             return;
         prefetchedPagesRef.current += 1;
         void loadOlder();
-    }, [active, hasMore, loadingOlder, items.length, initialPages, loadOlder]);
-    // Older history loads by scrolling the panel to its top; the official chat
-    // view owns the load-older button, so the panel stays chromeless.
+    }, [active, hasMore, loadingOlder, items.length, initialPages, loadOlder, outline]);
+    // Fallback mode loads older history by scrolling the panel to its top; the
+    // official chat view owns the load-older button, so the panel stays
+    // chromeless. The outline mode's list is already complete.
     const onPanelScroll = (event) => {
+        if (outline !== undefined)
+            return;
         if (!hasMore || loadingOlder)
             return;
         if (event.currentTarget.scrollTop <= 8)
             void loadOlder();
     };
-    const confirm = (key) => {
+    const confirm = (row) => {
         setFocusKey(null);
-        jumpTo(key);
+        if (row.kind === 'loaded') {
+            // A direct jump supersedes any armed outline jump (its landing would
+            // otherwise yank the transcript later).
+            setPendingJump(null);
+            jumpTo(row.key);
+            return;
+        }
+        // An outline row arms the jump; the effect above runs the paging and the
+        // landing scroll. Re-clicking another outline row retargets the jump.
+        setPendingJump({ sessionId, turn: row.turn, seq: row.seq, requested: false, awaiting: false, fromHead: null });
     };
     if (!visible || tooNarrow)
         return null;
     return createPortal(_jsx("div", { ref: panelRef, className: css.panel, role: "navigation", "aria-label": t('rail.panel'), tabIndex: 0, "data-timeline-panel": "", style: { left: rail.left, top: rail.top, height: rail.height, width }, onScroll: onPanelScroll, onKeyDown: (event) => {
             if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
                 event.preventDefault();
-                const anchor = items.findIndex(item => item.key === current);
+                const anchor = items.findIndex(item => item.id === current);
                 const next = event.key === 'ArrowDown'
                     ? items[Math.min(anchor + 1, items.length - 1)]
                     : items[Math.max(anchor - 1, 0)];
                 /* v8 ignore next -- a non-empty item list keeps the clamped index inside bounds */
                 if (next !== undefined)
-                    setFocusKey(next.key);
+                    setFocusKey(next.id);
             }
             else if (event.key === 'Enter' || event.key === ' ') {
                 event.preventDefault();
-                /* v8 ignore next -- the panel only renders with at least one item, so a current key always exists */
-                if (current !== null)
-                    confirm(current);
+                const row = items.find(item => item.id === current);
+                if (row !== undefined)
+                    confirm(row);
             }
-        }, onBlur: () => { setFocusKey(null); }, children: items.map((item) => {
-            const isCurrent = item.key === current;
-            const isFocused = item.key === focusKey;
+        }, onBlur: () => { setFocusKey(null); }, children: items.map((row) => {
+            const isCurrent = row.id === current;
+            const isFocused = row.id === focusKey;
+            const isPending = row.kind === 'outline' && pendingJump !== null && pendingJump.turn === row.turn;
             const className = isFocused
                 ? `${css.item} ${css.itemFocused}`
                 : isCurrent ? `${css.item} ${css.itemCurrent}` : css.item;
-            return (_jsxs("button", { type: "button", "data-item-key": item.key, "aria-current": isCurrent || undefined, className: className, onClick: () => { confirm(item.key); }, onMouseEnter: () => { setFocusKey(item.key); }, onMouseLeave: () => { setFocusKey(key => key === item.key ? null : key); }, children: [_jsx("span", { className: isCurrent ? `${css.tick} ${css.tickCurrent}` : css.tick, "aria-hidden": "true" }), _jsx("span", { className: css.itemText, children: previewText(nodeContent(item.node)) ?? t('rail.empty') })] }, item.key));
+            // Outline rows share the plain styling; the pending pulse is the only
+            // transient cue that a row pages history in before landing.
+            const classNames = isPending ? `${className} ${css.itemPending}` : className;
+            return (_jsxs("button", { type: "button", "data-item-key": row.id, "aria-current": isCurrent || undefined, "aria-busy": isPending || undefined, className: classNames, onClick: () => { confirm(row); }, onMouseEnter: () => { setFocusKey(row.id); }, onMouseLeave: () => { setFocusKey(key => key === row.id ? null : key); }, children: [_jsx("span", { className: isCurrent ? `${css.tick} ${css.tickCurrent}` : css.tick, "aria-hidden": "true" }), _jsx("span", { className: css.itemText, children: rowLabel(row, t) })] }, row.id));
         }) }), document.body);
 }
 /** Memoized export for the slot machinery (stable component identity). */

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

@@ -20,8 +20,11 @@ export interface TimelineConfig {
      */
     panelWidth: number;
     /**
-     * History pages to prefetch when the rail opens (50 events each); older
-     * pages load on demand when the rail or the panel is scrolled to its top.
+     * History pages to prefetch when the rail opens (50 events each), in the
+     * window-paging fallback only: when the host serves the turnOutline
+     * projection the list starts whole and nothing prefetches. In the fallback,
+     * older pages load on demand when the rail or the panel is scrolled to its
+     * top.
      */
     initialPages: number;
 }

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

@@ -3,11 +3,15 @@
  * official `conversation.session.header.utilities` seat (a right-aligned
  * optional-utility slot) that anchors the plugin into the session scope; the
  * component itself renders only through a body portal: the flat floating
- * timeline panel over the chat scrollport's left edge — one row per loaded
- * user message, no frame, no visible scrollbar. The
- * panel reads the session chat snapshot through the framework `useSession`
- * hook, jumps through the official row anchor attributes, and degrades to a
- * hidden panel when those attributes change — no official code is modified.
+ * timeline panel over the chat scrollport's left edge — one row per user
+ * message of the whole session, no frame, no visible scrollbar. The row list
+ * merges the host `turnOutline` projection (every started turn, served whole)
+ * with the loaded chat window; confirming a not-yet-loaded row pages history
+ * through the session's jump loader (`loadThrough`) before scrolling. When
+ * the projection is absent the panel reads the loaded window alone, paged
+ * through the session conversation service, jumps through the official row
+ * anchor attributes, and degrades to a hidden panel when those attributes
+ * change — no official code is modified.
  * @module @khorsheed/dsh-message-timeline/client
  */
 import type { Context } from '@deepseek-ai/cordis';

package/lib/types/client/index.js

@@ -36,12 +36,16 @@ export function apply(ctx, config) {
             const conversation = actx.get('conversation');
             if (conversation === undefined)
                 throw new Error('message-timeline: conversation service unavailable');
+            const binding = ctx.sessions.binding(sessionId);
+            if (binding === undefined)
+                throw new Error('message-timeline: session resolved no binding');
             return {
                 includeSteering: options.includeSteering,
                 panelWidth: options.panelWidth,
                 initialPages: options.initialPages,
                 loadOlder: () => conversation.loadOlder(),
-                jumpTo: (key) => { tracker.jumpTo(key); },
+                loadThrough: seq => binding.session.loadThrough(seq),
+                jumpTo: (key) => tracker.jumpTo(key),
                 hooks: { rail: tracker.state },
             };
         },

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

@@ -3,6 +3,9 @@
 export declare const zh: {
     'rail.panel': string;
     'rail.empty': string;
+    'rail.turn': string;
+    'rail.image': string;
+    'rail.attachment': string;
 };
 /** The message-timeline namespace key union. */
 export type TimelineKey = keyof typeof zh;
@@ -16,5 +19,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export declare const en: {
     'rail.panel': string;
     'rail.empty': string;
+    'rail.turn': string;
+    'rail.image': string;
+    'rail.attachment': string;
 };
 //# sourceMappingURL=locales.d.ts.map

package/lib/types/client/locales.js

@@ -2,10 +2,16 @@
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
     'rail.panel': '消息导览',
-    'rail.empty': '暂无用户消息',
+    'rail.empty': '无文本预览',
+    'rail.turn': '第 {turn} 轮',
+    'rail.image': '图片消息',
+    'rail.attachment': '附件消息',
 };
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
     'rail.panel': 'Message timeline',
-    'rail.empty': 'No user messages',
+    'rail.empty': 'No text preview',
+    'rail.turn': 'Turn {turn}',
+    'rail.image': 'Image message',
+    'rail.attachment': 'Attachment message',
 };

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

@@ -0,0 +1,12 @@
+import type { TurnOutlineEntry } from '@deepseek-ai/dsh-session-turn-outline/client';
+export type { TurnOutlineEntry };
+/**
+ * Narrow one wire projection value to outline entries. `turn` and `seq` are
+ * load-bearing — a row cannot exist or jump without them — so damage there
+ * drops the entry; the previews are decorative and degrade to ''. A non-array
+ * value (absent unit included) narrows to undefined.
+ * @param value - the raw `useProjection('turnOutline')` read.
+ * @returns the surviving entries in wire order, or undefined when absent.
+ */
+export declare function outlineEntries(value: unknown): readonly TurnOutlineEntry[] | undefined;
+//# sourceMappingURL=outline.d.ts.map

package/lib/types/client/outline.js

@@ -0,0 +1,40 @@
+/**
+ * Narrow one wire projection value to outline entries. `turn` and `seq` are
+ * load-bearing — a row cannot exist or jump without them — so damage there
+ * drops the entry; the previews are decorative and degrade to ''. A non-array
+ * value (absent unit included) narrows to undefined.
+ * @param value - the raw `useProjection('turnOutline')` read.
+ * @returns the surviving entries in wire order, or undefined when absent.
+ */
+export function outlineEntries(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = [];
+    for (const raw of value) {
+        const entry = outlineEntry(raw);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * Narrow one wire entry. `turn` and `seq` must be non-negative safe integers
+ * (seq additionally rejects -0); the previews default to '' when malformed.
+ * @param value - one raw wire entry.
+ * @returns the entry, or undefined when a load-bearing field is damaged.
+ */
+function outlineEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const entry = value;
+    if (typeof entry.turn !== 'number' || !Number.isSafeInteger(entry.turn) || entry.turn < 0)
+        return undefined;
+    if (typeof entry.seq !== 'number' || !Number.isSafeInteger(entry.seq) || entry.seq < 0 || Object.is(entry.seq, -0))
+        return undefined;
+    return {
+        turn: entry.turn,
+        seq: entry.seq,
+        prompt: typeof entry.prompt === 'string' ? entry.prompt : '',
+        response: typeof entry.response === 'string' ? entry.response : '',
+    };
+}

package/lib/types/client/rail-tracker.d.ts

@@ -78,8 +78,11 @@ export declare function jumpRow(scrollport: HTMLElement, key: string): boolean;
 export interface RailTracker {
     /** Live rail geometry and active marker for the current session. */
     readonly state: HostObservable<TimelineRailState>;
-    /** Scroll the transcript to the message addressed by `key` (no-op while unbound). */
-    jumpTo(key: string): void;
+    /**
+     * Scroll the transcript to the message addressed by `key`.
+     * @returns whether the row was found and scrolled (false while unbound).
+     */
+    jumpTo(key: string): boolean;
     /** Unbind every listener and observer. */
     dispose(): void;
 }

package/lib/types/client/rail-tracker.js

@@ -294,10 +294,7 @@ export function installRailTracker(ctx, includeSteering) {
                 return () => { listeners.delete(fn); };
             },
         },
-        jumpTo: (key) => {
-            if (scrollport !== null)
-                jumpRow(scrollport, key);
-        },
+        jumpTo: (key) => scrollport !== null && jumpRow(scrollport, key),
         dispose: () => {
             stopList();
             stopProvide?.();

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

@@ -0,0 +1,77 @@
+/**
+ * Rail row assembly: the merge of the loaded chat window's user rows with the
+ * host turnOutline projection into the full timeline. The outline names every
+ * started turn (its `turn/start` seq plus a bounded first-prompt preview); the
+ * loaded window supplies richer previews, steering rows, and message-tools
+ * bubbles for the turns it covers. A turn seen in the window renders its
+ * loaded rows and drops out of the outline; a turn outside the window renders
+ * as an outline row that pages history in on click.
+ * @module @khorsheed/dsh-message-timeline/client/rows
+ */
+import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { TurnOutlineEntry } from './outline.ts';
+import type { TimelineItem } from './slots.ts';
+/** One loaded-window row: jumps straight to its transcript anchor. */
+export interface LoadedRailRow {
+    readonly kind: 'loaded';
+    /** Row identity: the node key, which the tracker's active marker also speaks. */
+    readonly id: string;
+    /** The chat node key (the `data-chat-anchor-key` the jump targets). */
+    readonly key: string;
+    /** The underlying chat node, for content preview. */
+    readonly node: ChatConversationViewNode;
+    /** Transcript position (the node's anchor seq) — the merge key. */
+    readonly anchorSeq: number;
+    /** The owning outline turn, or undefined outside every outline range (a stale outline). */
+    readonly turn: number | undefined;
+}
+/**
+ * One outline-only row: the turn's events are outside the loaded window, so
+ * the row previews from the wire entry and confirming it pages history back
+ * through the turn's `turn/start` seq before landing.
+ */
+export interface OutlineRailRow {
+    readonly kind: 'outline';
+    /** Row identity (`turn:<n>` — the prefix cannot collide with a node key). */
+    readonly id: string;
+    readonly turn: number;
+    /** The turn's `turn/start` seq — the loadThrough target. */
+    readonly seq: TurnOutlineEntry['seq'];
+    /** Same position as `seq`, as the merge key. */
+    readonly anchorSeq: number;
+    /** Bounded first-prompt preview ('' for a textless prompt). */
+    readonly prompt: string;
+}
+/** One timeline row. */
+export type RailRow = LoadedRailRow | OutlineRailRow;
+/**
+ * The first visible loaded row of a turn, of any node kind: the landing
+ * target for a turn with no user-kind row (an automated turn renders a
+ * `turn-trigger` card, not a user bubble), mirroring the official rail's
+ * `user ?? loaded[0]` anchor. Only nodes in the host's visible `order`
+ * qualify — a store-only or hidden node is not a jump target.
+ * @param order - visible chat node keys in render order.
+ * @param nodes - the live node store.
+ * @param seq - the turn's `turn/start` seq (inclusive).
+ * @param end - the next turn's start seq (exclusive), or Infinity for the last turn.
+ * @returns the anchor key, or null when the turn has no visible loaded row.
+ */
+export declare function firstVisibleKeyInTurn(order: readonly string[], nodes: {
+    get(key: string): ChatConversationViewNode | undefined;
+}, seq: number, end: number): string | null;
+/**
+ * Merge loaded rows with the outline into the full row list. Both inputs are
+ * transcript-ordered (loaded rows anchorSeq-ascending, the outline strictly
+ * increasing by turn), so one pass interleaves them without a final sort: an
+ * outline entry whose seq range holds at least one loaded row is covered and
+ * emits nothing; every other entry emits its outline row at the range's
+ * position. A loaded row belongs to the last entry whose start it follows —
+ * when the window runs ahead of the projection feed, the newest rows read as
+ * the last named turn until the feed catches up (suppressing its outline row
+ * beats duplicating the turn).
+ * @param loaded - the window's user rows, anchorSeq-ascending.
+ * @param outline - narrowed outline entries, or undefined (capability absent).
+ * @returns the merged row list, transcript-ordered.
+ */
+export declare function mergeRows(loaded: readonly TimelineItem[], outline: readonly TurnOutlineEntry[] | undefined): readonly RailRow[];
+//# sourceMappingURL=rows.d.ts.map