@khorsheed/dsh-message-timeline 0.1.0

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

@@ -0,0 +1,10 @@
+import type { TimelineRailProps } from './slots.ts';
+/**
+ * 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 declare function TimelineRail({ useSession, sessionId, includeSteering, panelWidth, initialPages, loadOlder, jumpTo, useRail, t, }: TimelineRailProps): import("react").ReactPortal | null;
+/** Memoized export for the slot machinery (stable component identity). */
+export declare const TimelineRailEntry: import("react").MemoExoticComponent<typeof TimelineRail>;
+//# sourceMappingURL=TimelineRail.d.ts.map

package/lib/types/client/TimelineRail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimelineRail.d.ts","sourceRoot":"","sources":["../../../src/client/TimelineRail.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAoBjE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,UAAU,EAAE,YAAY,EACzC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAC9B,EAAE,iBAAiB,sCA4InB;AAED,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,0DAAqB,CAAA"}

package/lib/types/client/TimelineRail.js

@@ -0,0 +1,152 @@
+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
+ * 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.
+ */
+import { memo, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { PANEL_WIDTH_MIN } from './config.js';
+import { previewText } from './preview.js';
+import css from './TimelineRail.module.css';
+/** Extract the preview blocks of one user/steering node (kind-checked by the caller). */
+function nodeContent(node) {
+    return node.data.content ?? [];
+}
+/**
+ * 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
+ * for {@link PANEL_GAP} to be the visible gap to the message flow.
+ */
+const PANEL_PADDING_X = 8;
+/** Visible breathing gap between the timeline text and the message flow (px). */
+const PANEL_GAP = 16;
+/** Degraded width cap (fraction of the scrollport) while the flow probe is unanswered. */
+const DEGRADED_WIDTH_RATIO = 0.4;
+/**
+ * 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({ useSession, sessionId, includeSteering, panelWidth, initialPages, loadOlder, jumpTo, useRail, t, }) {
+    const rail = useRail(s => s);
+    const order = useSession(s => s.chat.order);
+    const nodes = useSession(s => s.chat.nodes);
+    const hasMore = useSession(s => s.hasMore);
+    const loadingOlder = useSession(s => s.loadingOlder);
+    const items = useMemo(() => {
+        const result = [];
+        for (const key of order) {
+            const node = nodes.get(key);
+            if (node === undefined)
+                continue;
+            const kind = node.kind;
+            if (kind !== 'user' && !(includeSteering && kind === 'steering'))
+                continue;
+            result.push({ key, node });
+        }
+        return result;
+    }, [order, nodes, includeSteering]);
+    // 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.
+    const [focusKey, setFocusKey] = useState(null);
+    const current = focusKey ?? rail.activeKey ?? items.at(-1)?.key ?? null;
+    const panelRef = useRef(null);
+    // 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.
+    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
+    // preferred width capped by the scrollport's left gutter — the message
+    // flow's left edge minus the panel's left edge, less the panel's right
+    // padding and the visible breathing gap. A gutter too small for the minimum
+    // usable width hides the panel entirely (the timeline is an overlay
+    // affordance; squeezed into nothing it only intercepts the transcript).
+    // When the flow probe is unanswered (official structure change), the width
+    // degrades to a fraction of the scrollport instead — never throws, never
+    // covers more than the fallback.
+    const gutter = rail.flowLeft === null ? null : rail.flowLeft - rail.left - PANEL_PADDING_X - PANEL_GAP;
+    const width = gutter === null
+        ? Math.min(panelWidth, Math.max(PANEL_WIDTH_MIN, rail.scrollportWidth * DEGRADED_WIDTH_RATIO))
+        : Math.min(panelWidth, Math.max(0, gutter));
+    const tooNarrow = gutter !== null && width < PANEL_WIDTH_MIN;
+    // Keep the lit row in view: the panel follows the reading position (a new
+    // message scrolls its row in), and mouse browsing is never yanked because
+    // the hovered row is the current one and always visible under the pointer.
+    useEffect(() => {
+        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.
+    const prefetchedPagesRef = useRef(0);
+    useEffect(() => {
+        if (!active) {
+            prefetchedPagesRef.current = 0;
+            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.
+    const onPanelScroll = (event) => {
+        if (!hasMore || loadingOlder)
+            return;
+        if (event.currentTarget.scrollTop <= 8)
+            void loadOlder();
+    };
+    const confirm = (key) => {
+        setFocusKey(null);
+        jumpTo(key);
+    };
+    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 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);
+            }
+            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);
+            }
+        }, onBlur: () => { setFocusKey(null); }, children: items.map((item) => {
+            const isCurrent = item.key === current;
+            const isFocused = item.key === focusKey;
+            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));
+        }) }), document.body);
+}
+/** Memoized export for the slot machinery (stable component identity). */
+export const TimelineRailEntry = memo(TimelineRail);

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

@@ -0,0 +1,39 @@
+/**
+ * Browser-half configuration of the message-timeline plugin. The runner hands
+ * the plugin its validated entry config through the apply second parameter;
+ * this module supplies the defaults and clamps, so a composition that does not
+ * pass config still renders with the documented values and out-of-range input
+ * lands inside the legal bounds.
+ */
+/** Deployment-tunable rail behavior. */
+export interface TimelineConfig {
+    /** Master switch: false hides the toggle and the rail entirely. */
+    enabled: boolean;
+    /** Count steering messages (user text admitted mid-turn) as rows. */
+    includeSteering: boolean;
+    /**
+     * Preferred timeline panel width in px (clamped 120–640; long text
+     * ellipsizes). The panel's right edge never crosses the message flow: the
+     * width is capped by the scrollport's left gutter, so a narrow column
+     * shrinks the panel automatically, and a gutter too small for
+     * {@link PANEL_WIDTH_MIN} hides the panel entirely.
+     */
+    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.
+     */
+    initialPages: number;
+}
+/** Bounds of the deployment-tunable numbers (clamped in resolveConfig). */
+export declare const PANEL_WIDTH_MIN = 120;
+export declare const PANEL_WIDTH_MAX = 640;
+/**
+ * Normalize the entry config into the full {@link TimelineConfig}: every
+ * omitted field takes its documented default and every numeric field is
+ * clamped into its legal range.
+ * @param config - the unvalidated entry config, when the runner passes one.
+ * @returns the effective rail behavior.
+ */
+export declare function resolveConfig(config: Partial<TimelineConfig> | undefined): TimelineConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/client/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAA;IAChB,qEAAqE;IACrE,eAAe,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,2EAA2E;AAC3E,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,eAAO,MAAM,eAAe,MAAM,CAAA;AAQlC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,GAAG,cAAc,CAOzF"}

package/lib/types/client/config.js

@@ -0,0 +1,30 @@
+/**
+ * Browser-half configuration of the message-timeline plugin. The runner hands
+ * the plugin its validated entry config through the apply second parameter;
+ * this module supplies the defaults and clamps, so a composition that does not
+ * pass config still renders with the documented values and out-of-range input
+ * lands inside the legal bounds.
+ */
+/** Bounds of the deployment-tunable numbers (clamped in resolveConfig). */
+export const PANEL_WIDTH_MIN = 120;
+export const PANEL_WIDTH_MAX = 640;
+const INITIAL_PAGES_MIN = 1;
+const INITIAL_PAGES_MAX = 20;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Normalize the entry config into the full {@link TimelineConfig}: every
+ * omitted field takes its documented default and every numeric field is
+ * clamped into its legal range.
+ * @param config - the unvalidated entry config, when the runner passes one.
+ * @returns the effective rail behavior.
+ */
+export function resolveConfig(config) {
+    return {
+        enabled: config?.enabled ?? true,
+        includeSteering: config?.includeSteering ?? true,
+        panelWidth: clamp(config?.panelWidth ?? 360, PANEL_WIDTH_MIN, PANEL_WIDTH_MAX),
+        initialPages: clamp(config?.initialPages ?? 5, INITIAL_PAGES_MIN, INITIAL_PAGES_MAX),
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Message timeline plugin, browser half. Registers one entry into the
+ * 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.
+ * @module @khorsheed/dsh-message-timeline/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type TimelineConfig } from './config.ts';
+export type { TimelineConfig } from './config.ts';
+export { resolveConfig } from './config.ts';
+export type { TimelineKey } from './locales.ts';
+export { previewText } from './preview.ts';
+export type { TimelineItem, TimelineRailInjected, TimelineRailProps, TimelineRailState } from './slots.ts';
+/** Required services: the slot ledger, the session store, and the copy. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the header-utilities entry and install the DOM
+ * tracker that publishes rail geometry and answers jumps.
+ * @param ctx - client root context.
+ * @param config - entry config; defaults apply when the runner passes none.
+ */
+export declare function apply(ctx: ClientContext, config?: Partial<TimelineConfig>): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAM3E,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AAMhE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAK1G,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAkC,CAAA;AAErD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CA+BhF"}

package/lib/types/client/index.js

@@ -0,0 +1,49 @@
+import { resolveConfig } from './config.js';
+import { en, zh } from './locales.js';
+import { installRailTracker } from './rail-tracker.js';
+import { TimelineRailEntry } from './TimelineRail.js';
+export { resolveConfig } from './config.js';
+export { previewText } from './preview.js';
+/** Dictionary namespace owned by this plugin. */
+const NS = 'message-timeline';
+/** Required services: the slot ledger, the session store, and the copy. */
+export const inject = ['slots', 'sessions', 'locale'];
+/**
+ * Client plugin body: register the header-utilities entry and install the DOM
+ * tracker that publishes rail geometry and answers jumps.
+ * @param ctx - client root context.
+ * @param config - entry config; defaults apply when the runner passes none.
+ */
+export function apply(ctx, config) {
+    const options = resolveConfig(config);
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'message-timeline: dictionaries');
+    if (!options.enabled)
+        return;
+    const tracker = installRailTracker(ctx, options.includeSteering);
+    ctx.effect(() => () => { tracker.dispose(); }, 'message-timeline: rail tracker');
+    // The slot is declared by ui-conversation, whose apply order relative to
+    // this plugin is unconstrained: register through slots.inject so the entry
+    // waits for the declaration instead of crashing the loader at boot.
+    ctx.slots.inject('conversation.session.header.utilities', () => ctx.slots.register({
+        name: 'conversation.session.header.utilities',
+        id: 'message-timeline',
+        order: 100,
+        locale: NS,
+        inject: (sessionId) => {
+            const actx = ctx.sessions.scope(sessionId);
+            if (actx === undefined)
+                throw new Error('message-timeline: session resolved no scope');
+            const conversation = actx.get('conversation');
+            if (conversation === undefined)
+                throw new Error('message-timeline: conversation service unavailable');
+            return {
+                includeSteering: options.includeSteering,
+                panelWidth: options.panelWidth,
+                initialPages: options.initialPages,
+                loadOlder: () => conversation.loadOlder(),
+                jumpTo: (key) => { tracker.jumpTo(key); },
+                hooks: { rail: tracker.state },
+            };
+        },
+    }, TimelineRailEntry));
+}

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

@@ -0,0 +1,20 @@
+/** `message-timeline` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'rail.panel': string;
+    'rail.empty': string;
+};
+/** The message-timeline namespace key union. */
+export type TimelineKey = keyof typeof zh;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The message timeline panel's copy. */
+        'message-timeline': TimelineKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'rail.panel': string;
+    'rail.empty': string;
+};
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../../src/client/locales.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,mEAAmE;AACnE,eAAO,MAAM,EAAE;;;CAGmB,CAAA;AAElC,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAA;AAEzC,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,kBAAkB;QAC1B,yCAAyC;QACzC,kBAAkB,EAAE,WAAW,CAAA;KAChC;CACF;AAED,mEAAmE;AACnE,eAAO,MAAM,EAAE;;;CAGwB,CAAA"}

package/lib/types/client/locales.js

@@ -0,0 +1,11 @@
+/** `message-timeline` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+    'rail.panel': '消息导览',
+    'rail.empty': '暂无用户消息',
+};
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+    'rail.panel': 'Message timeline',
+    'rail.empty': 'No user messages',
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Pure text extraction for the timeline panel rows: user message content is a
+ * block list (text, image, …); the preview concatenates the text blocks so
+ * long messages ellipsize through CSS instead of dropping their first lines.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+/**
+ * Join the text blocks of one message into a single preview string.
+ * @param content - the message's content block list.
+ * @returns the concatenated text, or null when the message carries none.
+ */
+export declare function previewText(content: readonly ContentBlock[]): string | null;
+//# sourceMappingURL=preview.d.ts.map

package/lib/types/client/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/client/preview.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,IAAI,CAM3E"}

package/lib/types/client/preview.js

@@ -0,0 +1,13 @@
+/**
+ * Join the text blocks of one message into a single preview string.
+ * @param content - the message's content block list.
+ * @returns the concatenated text, or null when the message carries none.
+ */
+export function previewText(content) {
+    const parts = [];
+    for (const block of content) {
+        if (block.type === 'text' && block.text !== '')
+            parts.push(block.text);
+    }
+    return parts.length === 0 ? null : parts.join('\n');
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Rail DOM tracker, apply world. The floating timeline panel needs the
+ * official chat scrollport's live geometry and the currently visible
+ * user-message row, so
+ * this module owns the only DOM the plugin touches — read-only probes plus
+ * the scroll write the jump performs — and publishes the result through the
+ * reserved hooks compartment (components never see the DOM or the sources).
+ *
+ * The probed attributes ([data-conversation-scroll], [data-chat-anchor-key],
+ * [data-chat-flow-kind]) are official render output, not a declared API: when
+ * they change, the tracker degrades — a missing scrollport hides the rail
+ * (one console.warn), missing rows only clear the active marker and make
+ * jumps no-ops. Nothing throws and no official code is modified.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { TimelineRailState } from './slots.ts';
+/**
+ * Measure the panel's viewport box from one scrollport: its rect inset by the
+ * panel padding, minus the sticky composer seat at the bottom and the
+ * conversation tab strip at the top. The tabs render just above the
+ * scrollport, but centering reads against the whole window, so the strip
+ * height leaves the box either way — otherwise the list sits visibly high.
+ * The scrollport's own width rides along for the width-cap fallback when the
+ * message-flow probe is unanswered.
+ * @param scrollport - the official conversation scrollport element.
+ * @returns the panel box plus the scrollport width, or null while the
+ * scrollport has no laid-out size.
+ */
+export declare function measureGeometry(scrollport: HTMLElement): {
+    left: number;
+    top: number;
+    height: number;
+    width: number;
+} | null;
+/**
+ * The viewport x of the message flow's left edge: the left of the first
+ * rendered `[data-chat-flow-kind]` row, which sits flush inside the official
+ * centered content column (max 748px, `margin: 0 auto`). Every flow row
+ * shares that edge, so the first one found suffices. The panel's right edge
+ * stays left of it — the panel may only occupy the scrollport's left gutter.
+ * @param scrollport - the official conversation scrollport element.
+ * @returns the flow's left edge, or null while no flow row is rendered.
+ */
+export declare function flowLeftX(scrollport: HTMLElement): number | null;
+/**
+ * Resolve the key of the user-message row the reading position belongs to:
+ * the first matching row whose bottom is still inside the viewport, or —
+ * while the reader sits inside a long assistant answer with no user row
+ * visible — the nearest user row above the viewport, so the lit tick stays
+ * anchored to the question being answered instead of jumping to the
+ * session's latest message.
+ * @param scrollport - the official conversation scrollport element.
+ * @param includeSteering - whether steering rows count as user messages.
+ * @returns the row's anchor key, or null when no user row is rendered.
+ */
+export declare function activeRowKey(scrollport: HTMLElement, includeSteering: boolean): string | null;
+/**
+ * Scroll one user-message row to the top of the transcript scrollport.
+ * @param scrollport - the official conversation scrollport element.
+ * @param key - the target node's anchor key.
+ * @returns whether the row was found and scrolled.
+ */
+export declare function jumpRow(scrollport: HTMLElement, key: string): boolean;
+/** The tracker's outward face: the observable state, the jump verb, and the disposer. */
+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;
+    /** Unbind every listener and observer. */
+    dispose(): void;
+}
+/**
+ * Install the rail tracker: bind the current session's scrollport, publish
+ * geometry/active updates on scroll and resize, and answer jump requests.
+ * Follows the current session through the sessions list and provide channels
+ * (the interface renders one conversation at a time, so one tracker suffices).
+ * @param ctx - client root context (sessions service).
+ * @param includeSteering - whether steering rows count as user dots.
+ * @returns the tracker face.
+ */
+export declare function installRailTracker(ctx: ClientContext, includeSteering: boolean): RailTracker;
+//# sourceMappingURL=rail-tracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rail-tracker.d.ts","sourceRoot":"","sources":["../../../src/client/rail-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,wCAAwC,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAenD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoB5H;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAa7F;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrE;AAED,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACjD,qFAAqF;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,0CAA0C;IAC1C,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,GAAG,WAAW,CAoI5F"}