@deepseek-harness-tui/dsh-tui 0.8.8 → 0.9.1

package/lib/types/ink/render-node-to-output.d.ts

@@ -1,4 +1,5 @@
 import type { DOMElement } from './dom.js';
+import type { Rectangle } from './layout/geometry.js';
 import type Output from './output.js';
 import type { Screen } from './screen.js';
 import { type StyledSegment } from './squash-text-nodes.js';
@@ -22,6 +23,15 @@ export type ScrollHint = {
     bottom: number;
     delta: number;
 };
+export type AbsoluteHitEntry = {
+    node: DOMElement;
+    rect: Rectangle;
+};
+/**
+ * The current frame's absolute-positioned nodes in paint order.
+ * @returns read-only list; reverse-iterate for topmost-first hit-testing.
+ */
+export declare function getAbsoluteHitList(): readonly AbsoluteHitEntry[];
 /** Reset the scroll hint for the next frame and rotate the absolute-rect buffers. */
 export declare function resetScrollHint(): void;
 /**

package/lib/types/ink/render-node-to-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-node-to-output.d.ts","sourceRoot":"","sources":["../../../src/ink/render-node-to-output.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAK1C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAqBxC,6CAA6C;AAC7C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAOD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAWvE,qFAAqF;AACrF,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AASD,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,GAAG,IAAI,CAEtD;AAgBD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAGD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,EAAE,CAIpD;AAoFD;;;;;GAKG;AACH,iBAAS,qBAAqB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CASlE;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,wBAAwB,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,MAAM,EAAE,EACvB,aAAa,EAAE,MAAM,EACrB,WAAW,GAAE,OAAe,GAC3B,MAAM,CA0GR;AA+DD;;;;;;;;;GASG;AACH,iBAAS,kBAAkB,CACzB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAM9B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,wBAAwB,CAAC,EAAE,KAAK,CAAA;CACjC,GACA,IAAI,CAo4BN;AAyOD,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,CAAA;AAE1D,eAAe,kBAAkB,CAAA"}
+{"version":3,"file":"render-node-to-output.d.ts","sourceRoot":"","sources":["../../../src/ink/render-node-to-output.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAGrD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAqBxC,6CAA6C;AAC7C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAOD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAkBvE,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAGpE;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,gBAAgB,EAAE,CAEhE;AAED,qFAAqF;AACrF,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AASD,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,GAAG,IAAI,CAEtD;AAgBD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAGD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,EAAE,CAIpD;AAoFD;;;;;GAKG;AACH,iBAAS,qBAAqB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CASlE;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,wBAAwB,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,MAAM,EAAE,EACvB,aAAa,EAAE,MAAM,EACrB,WAAW,GAAE,OAAe,GAC3B,MAAM,CA0GR;AA+DD;;;;;;;;;GASG;AACH,iBAAS,kBAAkB,CACzB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAM9B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,wBAAwB,CAAC,EAAE,KAAK,CAAA;CACjC,GACA,IAAI,CAq9BN;AA0OD,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,CAAA;AAE1D,eAAe,kBAAkB,CAAA"}

package/lib/types/ink/render-node-to-output.js

@@ -1,5 +1,6 @@
 import indentString from 'indent-string';
 import { applyTextStyles } from './colorize.js';
+import { GEOMETRY_TRACE_ENABLED, noteScrollGeometry } from './geometry-trace.js';
 import getMaxWidth from './get-max-width.js';
 import { LayoutDisplay, LayoutEdge } from './layout/node.js';
 import { nodeCache, pendingClears } from './node-cache.js';
@@ -41,11 +42,20 @@ let scrollHint = null;
 // still have the rect.
 let absoluteRectsPrev = [];
 let absoluteRectsCur = [];
+let absoluteHitList = [];
+/**
+ * The current frame's absolute-positioned nodes in paint order.
+ * @returns read-only list; reverse-iterate for topmost-first hit-testing.
+ */
+export function getAbsoluteHitList() {
+    return absoluteHitList;
+}
 /** Reset the scroll hint for the next frame and rotate the absolute-rect buffers. */
 export function resetScrollHint() {
     scrollHint = null;
     absoluteRectsPrev = absoluteRectsCur;
     absoluteRectsCur = [];
+    absoluteHitList = [];
 }
 /**
  * The scroll hint captured this frame, or null.
@@ -359,18 +369,34 @@ function renderNodeToOutput(node, output, options) {
         let y = offsetY + yogaTop;
         const width = yogaNode.getComputedWidth();
         const height = yogaNode.getComputedHeight();
-        // Absolute-positioned overlays (e.g. autocomplete menus with bottom='100%')
-        // can compute negative screen y when they extend above the viewport. Without
-        // clamping, setCellAt drops cells at y<0, clipping the TOP of the content
-        // (best matches in an autocomplete). By clamping to 0, we shift the element
-        // down so the top rows are visible and the bottom overflows below — the
-        // opaque prop ensures it paints over whatever is underneath.
-        if (y < 0 && node.style.position === 'absolute') {
-            y = 0;
-        }
+        // Absolute-positioned overlays anchored above their parent
+        // (bottom='100%') compute negative screen y when their content is
+        // taller than the space above the anchor. Do NOT clamp y to 0 here:
+        // shifting the node down breaks the bottom-anchoring contract — the
+        // panel's BOTTOM would overflow past the anchor and paint over the
+        // composer/status rows below it (small-terminal overlay reports).
+        // Instead let the y<0 rows clip naturally: setCellAt drops cells above
+        // row 0 and blitRegion clamps in screen space, so the panel keeps its
+        // bottom pinned at the anchor and only loses its topmost rows — the
+        // same semantics as CSS clipping above the containing block. Producers
+        // prevent the case entirely by maxHeight-ing the overlay to the actual
+        // space above the anchor (OverlayAbove), so clipping is the last
+        // resort, not the layout.
         // Check if we can skip this subtree (clean node with unchanged layout).
         // Blit cells from previous screen instead of re-rendering.
         const cached = nodeCache.get(node);
+        // The node's EFFECTIVE background = its own + the inherited one. When it
+        // changed since the last frame (hover on/off toggles a row's
+        // backgroundColor, a parent's bg swap changes every child's inherited
+        // value), prevScreen still holds the OLD background — a clean child
+        // blitting it would resurrect the stale color (stuck hover highlights:
+        // the row's fill is skipped once the bg is removed, its clean children
+        // then blit the previous bg'd cells, the frame equals prevScreen, the
+        // diff finds nothing, and the highlight never clears). Compare against
+        // the value recorded at the previous render and refuse the blit when it
+        // moved.
+        const effectiveBg = node.style.backgroundColor ?? inheritedBackgroundColor;
+        const bgChanged = cached?.bg !== effectiveBg;
         if (!node.dirty &&
             !skipSelfBlit &&
             node.pendingScrollDelta === undefined &&
@@ -379,6 +405,7 @@ function renderNodeToOutput(node, output, options) {
             cached.y === y &&
             cached.width === width &&
             cached.height === height &&
+            !bgChanged &&
             prevScreen) {
             const fx = Math.floor(x);
             const fy = Math.floor(y);
@@ -387,6 +414,7 @@ function renderNodeToOutput(node, output, options) {
             output.blit(prevScreen, fx, fy, fw, fh);
             if (node.style.position === 'absolute') {
                 absoluteRectsCur.push(cached);
+                absoluteHitList.push({ node, rect: cached });
             }
             // Absolute descendants can paint outside this node's layout bounds
             // (e.g. a slash menu with position='absolute' bottom='100%' floats
@@ -593,7 +621,29 @@ function renderNodeToOutput(node, output, options) {
                 // within the viewport (equal to the scroll container's
                 // paddingTop), and innerHeight already subtracts padding, so
                 // including it double-counts padding and inflates maxScroll.
-                const scrollHeight = contentYoga?.getComputedHeight() ?? 0;
+                let scrollHeight = contentYoga?.getComputedHeight() ?? 0;
+                // Defensive extent floor: the wrapper's Yoga height can land ONE LINE
+                // short of its children's laid-out extent (the engine's flex-basis
+                // measure cache and the child's final subtree layout can disagree by
+                // a row — measured on resume of a long session: wrapper 286 while the
+                // last row's bottom sat at 287, stable across forced re-layouts). A
+                // short scrollHeight clamps maxScroll below the real bottom, so the
+                // sticky pin parks the viewport a line up and the tail line culls
+                // against the viewport edge — permanently invisible AND unreachable
+                // (no scroll position ever shows it; the user loses the newest
+                // message). The children's real extent is the authoritative floor.
+                // O(direct children) — the windowed list keeps this tiny, and the
+                // painter walks the same nodes right below.
+                if (content !== undefined) {
+                    for (const child of content.childNodes) {
+                        const childYoga = child.yogaNode;
+                        if (childYoga === undefined)
+                            continue;
+                        const bottom = childYoga.getComputedTop() + childYoga.getComputedHeight();
+                        if (bottom > scrollHeight)
+                            scrollHeight = bottom;
+                    }
+                }
                 // Capture previous scroll bounds BEFORE overwriting — the at-bottom
                 // follow check compares against last frame's max.
                 const prevScrollHeight = node.scrollHeight ?? scrollHeight;
@@ -735,7 +785,17 @@ function renderNodeToOutput(node, output, options) {
                 // Keep the pre-frame position on a shrink frame (measurement
                 // artifact) instead of clamping to the shrunken maxScroll — the
                 // clamp would persist the yank even after content grows back.
-                let scrollTop = shrunk ? cur : Math.max(0, Math.min(cur, maxScroll));
+                // Exception: a STICKY view must stay pinned to the bottom. A width
+                // change clears MessageList's row-height cache, collapsing the
+                // estimated scrollHeight; freezing the pre-shrink scrollTop then
+                // parks it PAST the whole shrunken content — every child culls and
+                // the frame paints only the bottom chrome. With the resize erase
+                // (needsEraseBeforePaint) that lands as a pure blank screen with
+                // just the input box, and an idle app produces no follow-up frame
+                // to heal it (user-reported full-screen loss on pane-width jitter —
+                // issue #421; repro-resize-blank). Clamping a sticky view to the shrunken
+                // maxScroll is exactly its contract — show the bottom.
+                let scrollTop = shrunk && !sticky ? cur : Math.max(0, Math.min(cur, maxScroll));
                 // Virtual-scroll clamp: if scrollTop raced past the currently-mounted
                 // range (burst PageUp before React re-renders), render at the EDGE of
                 // the mounted children instead of blank spacer. Do NOT write back to
@@ -744,7 +804,15 @@ function renderNodeToOutput(node, output, options) {
                 // the right range. Not scheduling scrollDrainNode here keeps the
                 // clamp passive — React's commit → resetAfterCommit → onRender will
                 // paint again with fresh bounds.
-                const clamped = Math.max(cMin ?? -Infinity, Math.min(scrollTop, cMax ?? Infinity));
+                // Cap both bounds at maxScroll: the clamp bounds come from
+                // MessageList's height ESTIMATES while maxScroll comes from the
+                // frame's actual Yoga height. A width change resets the estimates
+                // (row-height cache clear), and a stale bound can point PAST the
+                // shrunken content bottom — the painted viewport then sits entirely
+                // below the content and every child culls to blank (the sticky
+                // full-screen loss — issue #421; repro-resize-blank). Nothing renderable exists
+                // below maxScroll regardless of what the estimates claim.
+                const clamped = Math.max(Math.min(cMin ?? -Infinity, maxScroll), Math.min(scrollTop, Math.min(cMax ?? Infinity, maxScroll)));
                 node.scrollTop = scrollTop;
                 // Clamp hitting top/bottom consumes any remainder. Set drainPending
                 // only after clamp so a wasted no-op frame isn't scheduled.
@@ -752,6 +820,28 @@ function renderNodeToOutput(node, output, options) {
                     node.pendingScrollDelta = undefined;
                 if (node.pendingScrollDelta !== undefined)
                     scrollDrainNode = node;
+                // Geometry forensics (#421/#433): everything that decides where this
+                // viewport painted — captured AFTER all clamps so the trace shows the
+                // final renderScrollTop, not the requested one.
+                if (GEOMETRY_TRACE_ENABLED) {
+                    noteScrollGeometry({
+                        sticky,
+                        shrunk,
+                        grew,
+                        atBottom,
+                        scrollTopBeforeFollow,
+                        cur,
+                        scrollTop,
+                        renderScrollTop: clamped,
+                        scrollHeight,
+                        prevScrollHeight,
+                        innerHeight,
+                        maxScroll,
+                        prevMaxScroll,
+                        clampMin: cMin ?? null,
+                        clampMax: cMax ?? null,
+                    });
+                }
                 // Wheel-drain selection translate (#438): the drain moved content
                 // by (scrollTop - scrollTopBeforeFollow) rows this frame, minus
                 // what at-bottom follow already reported above (followDelta is 0
@@ -1092,11 +1182,12 @@ function renderNodeToOutput(node, output, options) {
                 // backgroundColor and opaque both disable child blit: the fill
                 // overwrites the entire interior each render, so any child whose
                 // layout position shifted would blit stale cells from prevScreen
-                // on top of the fresh fill. Previously opaque kept blit enabled
-                // on the assumption that plain-space fill + unchanged children =
-                // valid composite, but children CAN reposition (ScrollBox remeasure
-                // on re-render → /permissions body blanked on Down arrow, #25436).
-                ownBackgroundColor || node.style.opaque ? undefined : prevScreen, boxBackgroundColor);
+                // on top of the fresh fill. bgChanged (effective background moved,
+                // e.g. a hover highlight removed) must disable child blit for the
+                // same reason: the old fill lives in prevScreen and the children's
+                // blits would resurrect it — the frame then equals prevScreen and
+                // the diff never clears the stale highlight.
+                ownBackgroundColor || node.style.opaque || bgChanged ? undefined : prevScreen, boxBackgroundColor);
             }
             if (needsClip) {
                 output.unclip();
@@ -1110,10 +1201,11 @@ function renderNodeToOutput(node, output, options) {
             renderChildren(node, output, x, y, hasRemovedChild, prevScreen, inheritedBackgroundColor);
         }
         // Cache layout bounds for dirty tracking
-        const rect = { x, y, width, height, top: yogaTop };
+        const rect = { x, y, width, height, top: yogaTop, bg: effectiveBg };
         nodeCache.set(node, rect);
         if (node.style.position === 'absolute') {
             absoluteRectsCur.push(rect);
+            absoluteHitList.push({ node, rect });
         }
         node.dirty = false;
     }
@@ -1227,6 +1319,7 @@ function blitEscapingAbsoluteDescendants(node, output, prevScreen, px, py, pw, p
             const cached = nodeCache.get(elem);
             if (cached) {
                 absoluteRectsCur.push(cached);
+                absoluteHitList.push({ node: elem, rect: cached });
                 const cx = Math.floor(cached.x);
                 const cy = Math.floor(cached.y);
                 const cw = Math.floor(cached.width);

package/lib/types/ink/timeline-rail.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Timeline rail — the pure geometry model behind the fullscreen
+ * transcript's turn navigator (a port of Grok Build's timeline sidebar
+ * semantics onto the dsh Ink tree).
+ *
+ * The rail is a 2-column gutter REPLACING the classic scrollbar: one tick
+ * per user turn, where tick position encodes CONVERSATION ORDER, not
+ * scroll proportion. Geometry is computed into a single frozen structure
+ * consumed by both the renderer and mouse hit-testing, so what you see is
+ * always what you can click ("看得到但点不中" impossible by construction).
+ *
+ * Viewport semantics (all derived from the same turn-top list, mirroring
+ * grok-pager's ScrollbackState):
+ *
+ *  - active: the LAST turn whose prompt top is at-or-above the viewport
+ *    top (the turn whose content owns the top row — "the turn being
+ *    read"). When pre-turn content (logo / loaded-context panel) owns the
+ *    top, the FIRST turn stands in. Never the newest-turn clamp: its
+ *    one-step-off-bottom highlight leap is exactly what this rule avoids.
+ *  - up target: the last turn STRICTLY above the viewport top. From
+ *    mid-turn it first aligns the current turn's own prompt, and it can
+ *    never name a trailing turn no scroll could bring to the top
+ *    (the stuck-▲ bug).
+ *  - down target: the FIRST turn whose prompt top is strictly below the
+ *    viewport top AND reachable (top ≤ maxScroll — the renderer clamps
+ *    scrollTop to maxScroll, so a turn below it could never own the top
+ *    row; naming it would make ▼ repeat itself forever).
+ *
+ * Not ported (deliberately): ratatui Buffer drawing and Rust state
+ * organization — algorithms only, per the reference report.
+ */
+/** Columns the rail reserves (widest tick glyph). */
+export declare const RAIL_WIDTH = 2;
+/** Terminals narrower than this hide the rail (transcript needs the cols). */
+export declare const RAIL_MIN_TERMINAL_WIDTH = 60;
+/** Fewer turns than this and the rail is noise. */
+export declare const RAIL_MIN_TURNS = 2;
+/** Stored preview cap (chars). Render paths re-truncate to card width. */
+export declare const PREVIEW_MAX_CHARS = 120;
+/** One user turn, as the rail sees it. Identity is the row id — never an
+ *  array index (deletion / rewind / loadOlder would mis-target it). */
+export interface TimelineTurn {
+    /** ChatRow id of the user message (jump/preview target). */
+    id: number;
+    /** Content-space top of the prompt TEXT (scrollTo(target) pins it to
+     *  the viewport top). */
+    top: number;
+    /** First non-empty prompt line, char-capped (see clipPreview). */
+    preview: string;
+    /**
+     * True while the row sits BEFORE the fold window (older than the most
+     * recent MAX_RENDERED_ROWS rows): its top is unknown (unmounted since
+     * before the fold; `top` carries −1) and clicking the tick must first
+     * reveal the folded history (Chat: showAll + force-mount + seek) rather
+     * than scrollTo(−1). Rendering a tick for it is still correct — the
+     * turn EXISTS and is navigable, it is just folded away right now
+     * (drawing only window turns read as "the rail covers just 2-3 nodes"
+     * on tool-heavy sessions where 300 rows ≈ a handful of turns).
+     */
+    folded?: boolean;
+}
+/** The per-commit snapshot MessageList reports and the rail + sticky
+ *  header consume — one source so the two can never disagree. */
+export interface TimelineSnapshot {
+    /** Turns in conversation order. */
+    turns: ReadonlyArray<TimelineTurn>;
+    /** Turn owning the viewport top row; first turn while pre-turn content
+     *  owns the top; null only when there are no turns. */
+    activeId: number | null;
+    /** ▲ target (strictly above the top), null at the first turn. */
+    upId: number | null;
+    /** ▼ target (below the top and reachable), null at the end. */
+    downId: number | null;
+}
+/** Per-render rail geometry: where the ticks and chevrons landed. */
+export interface RailGeometry {
+    /** Turn-index window shown as ticks: [windowStart, windowEnd). */
+    windowStart: number;
+    windowEnd: number;
+    /** Row of the ▲ chevron (block-local, within the rail column). */
+    upRow: number;
+    /** Row of the first tick. */
+    tickTop: number;
+    /** Row of the ▼ chevron. */
+    downRow: number;
+}
+/** What a rail row is. */
+export type RailHit = {
+    kind: 'up';
+} | {
+    kind: 'down';
+} | {
+    kind: 'tick';
+    index: number;
+};
+/** Single eligibility policy: setting, terminal width, turn count, and
+ *  geometric feasibility in one place. */
+export declare function railEligible(opts: {
+    turnCount: number;
+    terminalWidth: number;
+    viewportRows: number;
+    /** False when the content fits the viewport (inline mode / fresh
+     *  session): nothing to navigate, the terminal's own scrollback owns
+     *  the wheel. */
+    scrollable: boolean;
+}): boolean;
+/**
+ * Compute rail geometry, or null when the rail must not render.
+ *
+ * Windowing: when turns outnumber tick rows (viewport − 2 chevrons), slide
+ * a window around the ACTIVE turn; at the bottom prefer the tail so the
+ * newest ticks stay visible — but never exclude the active turn, or no
+ * tick would highlight. The chevron+tick block is vertically centered in
+ * the rail column.
+ */
+export declare function computeRailGeometry(turnCount: number, viewportRows: number, activeIndex: number | null, atBottom: boolean): RailGeometry | null;
+/**
+ * Which rail interaction a block-local row lands on. The whole rail width
+ * is the hit target (no pixel-hunting the glyph).
+ */
+export declare function railHit(geo: RailGeometry, row: number): RailHit | null;
+/**
+ * First non-empty line, char-capped with a `…` marker. Bounded work: the
+ * scan stops at the first non-empty line and slices at the cap, so a huge
+ * one-line prompt costs O(cap), not O(line length). Char cap (not display
+ * width) on purpose — this bounds the stored snapshot; the hover card
+ * re-wraps to its own width (wrapPreviewLines).
+ */
+export declare function clipPreview(text: string, maxChars?: number): string;
+/**
+ * Wrap a preview to at most 2 lines by DISPLAY width (CJK-aware — a
+ * terminal cell column budget, not a char count). The last line is
+ * ellipsized when content remains. Char-by-char accumulation keeps
+ * surrogate pairs and (best-effort) combining sequences intact by never
+ * splitting below a low surrogate.
+ */
+export declare function wrapPreviewLines(preview: string, maxWidth: number): string[];
+//# sourceMappingURL=timeline-rail.d.ts.map

package/lib/types/ink/timeline-rail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-rail.d.ts","sourceRoot":"","sources":["../../../src/ink/timeline-rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,qDAAqD;AACrD,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,mDAAmD;AACnD,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;uEACuE;AACvE,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAA;IACV;6BACyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;iEACiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAClC;2DACuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,0BAA0B;AAC1B,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC;0CAC0C;AAC1C,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB;;qBAEiB;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB,GAAG,OAAO,CAOV;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,QAAQ,EAAE,OAAO,GAChB,YAAY,GAAG,IAAI,CAuBrB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAUtE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAkB9E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA+B5E"}

package/lib/types/ink/timeline-rail.js

@@ -0,0 +1,179 @@
+/**
+ * Timeline rail — the pure geometry model behind the fullscreen
+ * transcript's turn navigator (a port of Grok Build's timeline sidebar
+ * semantics onto the dsh Ink tree).
+ *
+ * The rail is a 2-column gutter REPLACING the classic scrollbar: one tick
+ * per user turn, where tick position encodes CONVERSATION ORDER, not
+ * scroll proportion. Geometry is computed into a single frozen structure
+ * consumed by both the renderer and mouse hit-testing, so what you see is
+ * always what you can click ("看得到但点不中" impossible by construction).
+ *
+ * Viewport semantics (all derived from the same turn-top list, mirroring
+ * grok-pager's ScrollbackState):
+ *
+ *  - active: the LAST turn whose prompt top is at-or-above the viewport
+ *    top (the turn whose content owns the top row — "the turn being
+ *    read"). When pre-turn content (logo / loaded-context panel) owns the
+ *    top, the FIRST turn stands in. Never the newest-turn clamp: its
+ *    one-step-off-bottom highlight leap is exactly what this rule avoids.
+ *  - up target: the last turn STRICTLY above the viewport top. From
+ *    mid-turn it first aligns the current turn's own prompt, and it can
+ *    never name a trailing turn no scroll could bring to the top
+ *    (the stuck-▲ bug).
+ *  - down target: the FIRST turn whose prompt top is strictly below the
+ *    viewport top AND reachable (top ≤ maxScroll — the renderer clamps
+ *    scrollTop to maxScroll, so a turn below it could never own the top
+ *    row; naming it would make ▼ repeat itself forever).
+ *
+ * Not ported (deliberately): ratatui Buffer drawing and Rust state
+ * organization — algorithms only, per the reference report.
+ */
+import { stringWidth } from './stringWidth.js';
+/** Columns the rail reserves (widest tick glyph). */
+export const RAIL_WIDTH = 2;
+/** Terminals narrower than this hide the rail (transcript needs the cols). */
+export const RAIL_MIN_TERMINAL_WIDTH = 60;
+/** Fewer turns than this and the rail is noise. */
+export const RAIL_MIN_TURNS = 2;
+/** Stored preview cap (chars). Render paths re-truncate to card width. */
+export const PREVIEW_MAX_CHARS = 120;
+/** Single eligibility policy: setting, terminal width, turn count, and
+ *  geometric feasibility in one place. */
+export function railEligible(opts) {
+    return (opts.scrollable &&
+        opts.turnCount >= RAIL_MIN_TURNS &&
+        opts.terminalWidth >= RAIL_MIN_TERMINAL_WIDTH &&
+        opts.viewportRows >= 3);
+}
+/**
+ * Compute rail geometry, or null when the rail must not render.
+ *
+ * Windowing: when turns outnumber tick rows (viewport − 2 chevrons), slide
+ * a window around the ACTIVE turn; at the bottom prefer the tail so the
+ * newest ticks stay visible — but never exclude the active turn, or no
+ * tick would highlight. The chevron+tick block is vertically centered in
+ * the rail column.
+ */
+export function computeRailGeometry(turnCount, viewportRows, activeIndex, atBottom) {
+    if (turnCount < RAIL_MIN_TURNS)
+        return null;
+    const maxTicks = viewportRows - 2;
+    if (maxTicks < 1)
+        return null;
+    let start = 0;
+    if (turnCount > maxTicks) {
+        const tailStart = turnCount - maxTicks;
+        const anchor = activeIndex ?? turnCount - 1;
+        start = atBottom
+            ? Math.min(anchor, tailStart)
+            : Math.min(Math.max(0, anchor - Math.floor(maxTicks / 2)), tailStart);
+    }
+    const shown = Math.min(turnCount, maxTicks);
+    // Vertically center the ▲ + ticks + ▼ stack, like the web rail.
+    const blockTop = Math.max(0, Math.floor((viewportRows - (shown + 2)) / 2));
+    return {
+        windowStart: start,
+        windowEnd: start + shown,
+        upRow: blockTop,
+        tickTop: blockTop + 1,
+        downRow: blockTop + 1 + shown,
+    };
+}
+/**
+ * Which rail interaction a block-local row lands on. The whole rail width
+ * is the hit target (no pixel-hunting the glyph).
+ */
+export function railHit(geo, row) {
+    if (row === geo.upRow)
+        return { kind: 'up' };
+    if (row === geo.downRow)
+        return { kind: 'down' };
+    if (row >= geo.tickTop) {
+        const rel = row - geo.tickTop;
+        if (rel < geo.windowEnd - geo.windowStart) {
+            return { kind: 'tick', index: geo.windowStart + rel };
+        }
+    }
+    return null;
+}
+/**
+ * First non-empty line, char-capped with a `…` marker. Bounded work: the
+ * scan stops at the first non-empty line and slices at the cap, so a huge
+ * one-line prompt costs O(cap), not O(line length). Char cap (not display
+ * width) on purpose — this bounds the stored snapshot; the hover card
+ * re-wraps to its own width (wrapPreviewLines).
+ */
+export function clipPreview(text, maxChars = PREVIEW_MAX_CHARS) {
+    let line = '';
+    let rest = text;
+    while (rest.length > 0) {
+        const nl = rest.indexOf('\n');
+        const head = nl === -1 ? rest : rest.slice(0, nl);
+        rest = nl === -1 ? '' : rest.slice(nl + 1);
+        const trimmed = head.trim();
+        if (trimmed.length > 0) {
+            line = trimmed;
+            break;
+        }
+    }
+    if (line.length <= maxChars)
+        return line;
+    // Keep the cap INCLUDING the ellipsis marker, like grok's preview. Slice
+    // by CODE POINTS, not UTF-16 units — a surrogate pair split mid-pair
+    // would emit a lone surrogate to the terminal.
+    return `${[...line].slice(0, maxChars - 1).join('')}…`;
+}
+/**
+ * Wrap a preview to at most 2 lines by DISPLAY width (CJK-aware — a
+ * terminal cell column budget, not a char count). The last line is
+ * ellipsized when content remains. Char-by-char accumulation keeps
+ * surrogate pairs and (best-effort) combining sequences intact by never
+ * splitting below a low surrogate.
+ */
+export function wrapPreviewLines(preview, maxWidth) {
+    const widthOf = stringWidth;
+    const lines = [];
+    let current = '';
+    let currentW = 0;
+    for (const ch of preview) {
+        const w = widthOf(ch);
+        if (w <= 0) {
+            // Zero-width (combining marks, ZWJ): attach for free.
+            current += ch;
+            continue;
+        }
+        if (currentW + w > maxWidth) {
+            if (lines.length === 1) {
+                // Second line full → ellipsize in place and stop.
+                return [lines[0], ellipsize(current, maxWidth)];
+            }
+            lines.push(current);
+            current = ch;
+            currentW = w;
+            continue;
+        }
+        current += ch;
+        currentW += w;
+    }
+    if (current.length > 0 || lines.length === 0)
+        lines.push(current);
+    if (lines.length > 2) {
+        // Cannot happen (we stop after the second), kept for exhaustiveness.
+        return [lines[0], ellipsize(lines[1], maxWidth)];
+    }
+    return lines.slice(0, 2);
+}
+function ellipsize(line, maxWidth) {
+    // Make room for '…' (1 col) then hard-cut by display width.
+    let out = '';
+    let w = 0;
+    for (const ch of line) {
+        const cw = stringWidth(ch);
+        if (cw > 0 && w + cw > maxWidth - 1)
+            break;
+        out += ch;
+        w += cw;
+    }
+    return `${out}…`;
+}

package/lib/types/ink/wrap-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap-text.d.ts","sourceRoot":"","sources":["../../../src/ink/wrap-text.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAqCzC;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,GAC3B,MAAM,CA8BR"}
+{"version":3,"file":"wrap-text.d.ts","sourceRoot":"","sources":["../../../src/ink/wrap-text.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAoFzC;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,GAC3B,MAAM,CAoCR"}