@khorsheed/dsh-message-timeline 0.1.0

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

@@ -0,0 +1,240 @@
+/** Horizontal inset of the rail from the scrollport's left edge (px). */
+const RAIL_LEFT_INSET = 6;
+/** Vertical padding above and below the rail inside the scrollport (px). */
+const RAIL_VERTICAL_PADDING = 8;
+/** Keep the target row this far below the scrollport top after a jump (px). */
+const JUMP_OFFSET = 16;
+/** Idle state published before any session binds or while none is current. */
+const IDLE = {
+    sessionId: undefined, ready: false, left: 0, top: 0, height: 0, scrollportWidth: 0, flowLeft: null,
+    activeKey: null, chatView: false,
+};
+/**
+ * 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 function measureGeometry(scrollport) {
+    const rect = scrollport.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0)
+        return null;
+    const composer = scrollport.querySelector('[data-composer-seat]');
+    const composerHeight = composer?.getBoundingClientRect().height ?? 0;
+    let topInset = RAIL_VERTICAL_PADDING;
+    for (const tabs of scrollport.ownerDocument.querySelectorAll('[role="tablist"]')) {
+        const tabsRect = tabs.getBoundingClientRect();
+        // Only the strip adjacent to the scrollport's top edge counts as chrome.
+        if (tabsRect.height > 0 && Math.abs(tabsRect.bottom - rect.top) <= 80) {
+            topInset += tabsRect.height;
+            break;
+        }
+    }
+    return {
+        left: rect.left + RAIL_LEFT_INSET,
+        top: rect.top + topInset,
+        height: Math.max(0, rect.height - composerHeight - topInset - RAIL_VERTICAL_PADDING),
+        width: rect.width,
+    };
+}
+/**
+ * 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 function flowLeftX(scrollport) {
+    const row = scrollport.querySelector('[data-chat-flow-kind]');
+    return row === null ? null : row.getBoundingClientRect().left;
+}
+/**
+ * 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 function activeRowKey(scrollport, includeSteering) {
+    const viewTop = scrollport.getBoundingClientRect().top;
+    let lastAbove = null;
+    for (const row of scrollport.querySelectorAll('[data-chat-flow-kind]')) {
+        const kind = row.dataset.chatFlowKind;
+        if (kind !== 'user' && !(includeSteering && kind === 'steering'))
+            continue;
+        if (row.getBoundingClientRect().bottom <= viewTop) {
+            lastAbove = row.dataset.chatAnchorKey ?? lastAbove;
+            continue;
+        }
+        return row.dataset.chatAnchorKey ?? null;
+    }
+    return lastAbove;
+}
+/**
+ * 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 function jumpRow(scrollport, key) {
+    const row = scrollport.querySelector(`[data-chat-anchor-key=${JSON.stringify(key)}]`);
+    if (row === null)
+        return false;
+    const target = row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top
+        + scrollport.scrollTop - JUMP_OFFSET;
+    scrollport.scrollTop = Math.max(0, target);
+    return true;
+}
+/**
+ * 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 function installRailTracker(ctx, includeSteering) {
+    const listeners = new Set();
+    let state = IDLE;
+    let activeSession;
+    let scrollport = null;
+    let resizeObserver;
+    let rafPending = false;
+    let warned = false;
+    const nextFrame = typeof requestAnimationFrame === 'function'
+        ? requestAnimationFrame
+        : (callback) => { setTimeout(callback, 16); };
+    const same = (left, right) => left.sessionId === right.sessionId && left.ready === right.ready
+        && left.left === right.left && left.top === right.top
+        && left.height === right.height && left.scrollportWidth === right.scrollportWidth
+        && left.flowLeft === right.flowLeft
+        && left.activeKey === right.activeKey
+        && left.chatView === right.chatView;
+    const publish = (next) => {
+        if (same(state, next))
+            return;
+        state = next;
+        for (const fn of [...listeners])
+            fn();
+    };
+    const update = () => {
+        if (scrollport === null)
+            return;
+        const geometry = measureGeometry(scrollport);
+        if (geometry === null)
+            return;
+        publish({
+            sessionId: activeSession,
+            ready: true,
+            left: geometry.left,
+            top: geometry.top,
+            height: geometry.height,
+            scrollportWidth: geometry.width,
+            flowLeft: flowLeftX(scrollport),
+            activeKey: activeRowKey(scrollport, includeSteering),
+            chatView: scrollport.querySelector('[data-chat-flow]') !== null,
+        });
+    };
+    const scheduleUpdate = () => {
+        if (rafPending)
+            return;
+        rafPending = true;
+        nextFrame(() => {
+            rafPending = false;
+            update();
+        });
+    };
+    const onScroll = () => { scheduleUpdate(); };
+    const teardownBind = () => {
+        if (scrollport !== null)
+            scrollport.removeEventListener('scroll', onScroll);
+        scrollport = null;
+        resizeObserver?.disconnect();
+        resizeObserver = undefined;
+        rafPending = false;
+    };
+    const bind = (sessionId) => {
+        if (sessionId === activeSession && scrollport !== null)
+            return;
+        teardownBind();
+        activeSession = sessionId;
+        if (sessionId === undefined) {
+            publish(IDLE);
+            return;
+        }
+        nextFrame(() => {
+            const found = document.querySelector('[data-conversation-scroll]');
+            if (found === null) {
+                if (!warned) {
+                    warned = true;
+                    console.warn('message-timeline: [data-conversation-scroll] not found; the rail stays hidden');
+                }
+                publish(IDLE);
+                return;
+            }
+            scrollport = found;
+            scrollport.addEventListener('scroll', onScroll, { passive: true });
+            if (typeof ResizeObserver === 'function') {
+                resizeObserver = new ResizeObserver(scheduleUpdate);
+                resizeObserver.observe(scrollport);
+                const composer = scrollport.querySelector('[data-composer-seat]');
+                if (composer !== null)
+                    resizeObserver.observe(composer);
+            }
+            update();
+        });
+    };
+    const bindCurrent = () => {
+        bind(ctx.sessions.list.getSnapshot().current);
+    };
+    const stopList = ctx.sessions.list.subscribe(bindCurrent);
+    const stopProvide = ctx.sessions.currentProvideInfo.subscribe(bindCurrent);
+    bindCurrent();
+    // Layout fallbacks beyond the scrollport's own ResizeObserver: a window
+    // resize re-measures, and a body MutationObserver catches panel folds and
+    // other layout changes that resize the scrollport without a window event.
+    // Both go through the rAF-throttled scheduleUpdate, and publish() skips
+    // identical geometry, so the cost stays one measurement per changed frame.
+    const onWindowResize = () => { scheduleUpdate(); };
+    if (typeof window !== 'undefined')
+        window.addEventListener('resize', onWindowResize);
+    let mutationObserver;
+    if (typeof MutationObserver === 'function' && typeof document !== 'undefined') {
+        mutationObserver = new MutationObserver(scheduleUpdate);
+        mutationObserver.observe(document.body, { childList: true, subtree: true });
+    }
+    return {
+        state: {
+            getSnapshot: () => state,
+            subscribe: (fn) => {
+                listeners.add(fn);
+                return () => { listeners.delete(fn); };
+            },
+        },
+        jumpTo: (key) => {
+            if (scrollport !== null)
+                jumpRow(scrollport, key);
+        },
+        dispose: () => {
+            stopList();
+            stopProvide();
+            if (typeof window !== 'undefined')
+                window.removeEventListener('resize', onWindowResize);
+            mutationObserver?.disconnect();
+            teardownBind();
+        },
+    };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Slot-facing types of the message-timeline client half: the injected action
+ * face (jump/loadOlder plus the rail geometry hook) and the composed props of
+ * the `conversation.session.header.utilities` entry.
+ */
+import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-runtime/client';
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/**
+ * Live rail geometry plus the currently visible user message, published by
+ * the apply-world DOM tracker through the reserved hooks compartment.
+ */
+export interface TimelineRailState {
+    /** The session whose scrollport the state describes; undefined while none is current. */
+    sessionId: string | undefined;
+    /** False while the official DOM probe is unanswered (rail hidden). */
+    ready: boolean;
+    /** Viewport x of the rail's left edge. */
+    left: number;
+    /** Viewport y of the rail's top edge (below the session header). */
+    top: number;
+    /** Rail height in px (scrollport minus the composer seat). */
+    height: number;
+    /** Scrollport width in px (the degraded width cap when the flow probe fails). */
+    scrollportWidth: number;
+    /**
+     * Viewport x of the message flow's left edge (the official centered
+     * content column), or null while the probe is unanswered. The panel's
+     * right edge never crosses it, so the width adapts to the left gutter.
+     */
+    flowLeft: number | null;
+    /** Key of the user message row nearest the visible top, or null. */
+    activeKey: string | null;
+    /** Whether the chat view (not trajectory or another tab) is rendered. */
+    chatView: boolean;
+}
+/** Injected action face of the header-utilities entry. */
+export interface TimelineRailInjected {
+    /** Whether steering messages count as rows (config). */
+    includeSteering: boolean;
+    /** Timeline panel width in px (config). */
+    panelWidth: number;
+    /** History pages to prefetch when the panel opens (config). */
+    initialPages: number;
+    /** Pull one older history page for the rendered session. */
+    loadOlder: () => Promise<void>;
+    /** Scroll the transcript to the user message row addressed by `key`. */
+    jumpTo: (key: string) => void;
+    hooks: {
+        /** Live panel geometry and active marker for the current session. */
+        rail: HostObservable<TimelineRailState>;
+    };
+}
+/** One row's data: the addressed node key plus the node itself, for preview. */
+export interface TimelineItem {
+    /** Stable chat node key (the `data-chat-anchor-key` the jump targets). */
+    readonly key: string;
+    /** The underlying chat node, for content preview. */
+    readonly node: ChatConversationViewNode;
+}
+/** Full props of the header-utilities entry. */
+export type TimelineRailProps = PropsRuntime<'conversation.session.header.utilities'> & InjectFace<TimelineRailInjected> & PropsLocale<'message-timeline'>;
+//# sourceMappingURL=slots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/client/slots.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAA;AACtF,OAAO,KAAK,EACV,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EACtD,MAAM,kCAAkC,CAAA;AAOzC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAA;IACd,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAA;IACxB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,wEAAwE;IACxE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE;QACL,qEAAqE;QACrE,IAAI,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;KACxC,CAAA;CACF;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;CACxC;AAED,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAC3B,YAAY,CAAC,uCAAuC,CAAC,GACnD,UAAU,CAAC,oBAAoB,CAAC,GAChC,WAAW,CAAC,kBAAkB,CAAC,CAAA"}

package/lib/types/client/slots.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Message timeline plugin, node half. Pure UI plugin: the empty apply exists
+ * so the plugin appears in the host cordis.yml / Loader; the browser half
+ * ships via exports["./client"], discovered through the package.json
+ * dsh.client declaration.
+ */
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wEAAwE;AACxE,wBAAgB,KAAK,IAAI,IAAI,CAAG"}

package/lib/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * Message timeline plugin, node half. Pure UI plugin: the empty apply exists
+ * so the plugin appears in the host cordis.yml / Loader; the browser half
+ * ships via exports["./client"], discovered through the package.json
+ * dsh.client declaration.
+ */
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export function apply() { }

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-message-timeline`.
+ * @module @khorsheed/dsh-message-timeline/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-message-timeline-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,sCAAsC,CAAA;AACvD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAapC;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAS,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -0,0 +1,26 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-message-timeline`.
+ * @module @khorsheed/dsh-message-timeline/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-message-timeline';
+/** Cordis companion plugin name. */
+export const name = 'client-message-timeline-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the rail contribution is one slot entry whose disposal
+ * is proven by the HMR-safety spec — the plugin writes no session state, emits
+ * no cordis events, and reads the conversation snapshot through the framework
+ * hook only. Its DOM probe targets the official chat row attributes
+ * ([data-chat-anchor-key] / [data-conversation-scroll]) read-only and
+ * degrades to a hidden rail when they change, so no second authority exists to
+ * check at runtime.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@khorsheed/dsh-message-timeline",
+  "description": "Message timeline: a flat floating list over the conversation scrollport that jumps to any user message, with a tick-only rest state",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    },
+    "compat": {
+      "minHost": "0.1.0-rc.6",
+      "verifiedHost": "0.1.1-rc.2"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.1",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^26.2.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "message-timeline"
+  ]
+}