@khorsheed/dsh-message-timeline 0.2.4 → 0.2.6

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

package/lib/types/client/rows.js

@@ -0,0 +1,86 @@
+/**
+ * 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 function firstVisibleKeyInTurn(order, nodes, seq, end) {
+    for (const key of order) {
+        const node = nodes.get(key);
+        if (node === undefined)
+            continue;
+        if (node.anchorSeq < seq)
+            continue;
+        if (node.anchorSeq >= end)
+            break;
+        if (node.visibility === 'hidden')
+            continue;
+        return key;
+    }
+    return null;
+}
+/**
+ * Wrap one loaded item as a rail row.
+ * @param item - the window row.
+ * @param turn - its owning outline turn, or undefined.
+ * @returns the loaded rail row.
+ */
+function toLoadedRow(item, turn) {
+    return { kind: 'loaded', id: item.key, key: item.key, node: item.node, anchorSeq: item.node.anchorSeq, turn };
+}
+/**
+ * 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 function mergeRows(loaded, outline) {
+    if (outline === undefined)
+        return loaded.map(item => toLoadedRow(item, undefined));
+    const rows = [];
+    let cursor = 0;
+    for (const [index, entry] of outline.entries()) {
+        const end = outline.at(index + 1)?.seq ?? Number.POSITIVE_INFINITY;
+        let covered = false;
+        for (;;) {
+            const item = loaded[cursor];
+            if (item === undefined || item.node.anchorSeq >= end)
+                break;
+            rows.push(toLoadedRow(item, item.node.anchorSeq >= entry.seq ? entry.turn : undefined));
+            covered = covered || item.node.anchorSeq >= entry.seq;
+            cursor += 1;
+        }
+        if (!covered) {
+            rows.push({
+                kind: 'outline',
+                id: `turn:${entry.turn}`,
+                turn: entry.turn,
+                seq: entry.seq,
+                anchorSeq: entry.seq,
+                prompt: entry.prompt,
+            });
+        }
+    }
+    for (;;) {
+        const item = loaded[cursor];
+        if (item === undefined)
+            break;
+        rows.push(toLoadedRow(item, undefined));
+        cursor += 1;
+    }
+    return rows;
+}

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

@@ -4,6 +4,7 @@
  * the `conversation.session.header.utilities` entry.
  */
 import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { ISession } from '@deepseek-ai/dsh-api-session-controller/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
@@ -43,12 +44,24 @@ export interface TimelineRailInjected {
     includeSteering: boolean;
     /** Timeline panel width in px (config). */
     panelWidth: number;
-    /** History pages to prefetch when the panel opens (config). */
+    /**
+     * History pages to prefetch when the panel opens (config). Applies only to
+     * the window-paging fallback: when the host serves the turnOutline
+     * projection the list starts complete and nothing prefetches.
+     */
     initialPages: number;
-    /** Pull one older history page for the rendered session. */
+    /** Pull one older history page for the rendered session (fallback path). */
     loadOlder: () => Promise<void>;
-    /** Scroll the transcript to the user message row addressed by `key`. */
-    jumpTo: (key: string) => void;
+    /**
+     * Page history back until the window covers `seq` (the session jump
+     * loader): how an outline-only row's turn becomes loaded.
+     */
+    loadThrough: ISession['loadThrough'];
+    /**
+     * Scroll the transcript to the user message row addressed by `key`.
+     * @returns whether the row was found and scrolled.
+     */
+    jumpTo: (key: string) => boolean;
     hooks: {
         /** Live panel geometry and active marker for the current session. */
         rail: HostObservable<TimelineRailState>;

package/lib/types/client/timeline-kinds.d.ts

@@ -12,10 +12,15 @@
 export declare const EDIT_KIND = "message-tools-edited";
 /** A message-tools restored row (a withdrawn message replayed at the tail). */
 export declare const RESTORED_KIND = "message-tools-restored";
+/** An automated turn's trigger card (restart recovery, scheduled job, …). */
+export declare const TRIGGER_KIND = "turn-trigger";
 /**
  * Whether a node kind renders as a timeline row. The rail lists user messages
- * (and optionally steering), plus the message-tools edited/restored bubbles
- * that the host `order` does not always surface.
+ * (and optionally steering), the message-tools edited/restored bubbles that
+ * the host `order` does not always surface, and automated-turn trigger cards
+ * (whose turns have no human prompt but real transcript content). The same
+ * set drives the reading-position anchor, so landing on a trigger card keeps
+ * the selection on its turn instead of moving to the next user row.
  * @param kind - the node's kind string.
  * @param includeSteering - whether steering rows count as user messages.
  * @returns true when the kind belongs on the timeline.

package/lib/types/client/timeline-kinds.js

@@ -12,17 +12,22 @@
 export const EDIT_KIND = 'message-tools-edited';
 /** A message-tools restored row (a withdrawn message replayed at the tail). */
 export const RESTORED_KIND = 'message-tools-restored';
+/** An automated turn's trigger card (restart recovery, scheduled job, …). */
+export const TRIGGER_KIND = 'turn-trigger';
 /**
  * Whether a node kind renders as a timeline row. The rail lists user messages
- * (and optionally steering), plus the message-tools edited/restored bubbles
- * that the host `order` does not always surface.
+ * (and optionally steering), the message-tools edited/restored bubbles that
+ * the host `order` does not always surface, and automated-turn trigger cards
+ * (whose turns have no human prompt but real transcript content). The same
+ * set drives the reading-position anchor, so landing on a trigger card keeps
+ * the selection on its turn instead of moving to the next user row.
  * @param kind - the node's kind string.
  * @param includeSteering - whether steering rows count as user messages.
  * @returns true when the kind belongs on the timeline.
  */
 export function isTimelineRowKind(kind, includeSteering) {
     return kind === 'user' || (includeSteering && kind === 'steering')
-        || kind === EDIT_KIND || kind === RESTORED_KIND;
+        || kind === EDIT_KIND || kind === RESTORED_KIND || kind === TRIGGER_KIND;
 }
 /**
  * Whether a node kind carries a hidden span (`{ hiddenStartSeq, seq }`) that

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.2.4",
+  "version": "0.2.6",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -10,10 +10,6 @@
       "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"
@@ -36,19 +32,28 @@
     },
     "compat": {
       "minHost": "0.1.2-rc.1",
-      "verifiedHost": "0.1.2-rc.1"
+      "notes": "Whole-session list relies on the host turnOutline projection (dsh-session-turn-outline, mounted by the official web bundle since 0.1.2-alpha.3 — below the minHost floor); assemblies without the unit degrade to window paging (prefetch on open plus panel-top loadOlder), fully functional but the first message appears only once paged in.",
+      "verifiedHost": "0.2.1-rc.1"
     }
   },
   "license": "MIT",
+  "engines": {
+    "dsh": ">=0.1.2-rc.1 <0.3.0-0"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session-turn-outline": "^0.1.2-alpha.3 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "react": "^18.2.0"
   },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-turn-outline": {
+      "optional": true
+    }
+  },
   "files": [
     "lib",
     "cordis.patch.yml",

package/lib/invariant.js

@@ -1,28 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* 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. */
-const name = "client-message-timeline-invariant";
-/** Service required before the companion can reserve package ownership. */
-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.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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.js

@@ -1,26 +0,0 @@
-/**
- * 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 */