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

package/lib/types/screens/chatOverlay.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The chat screen's transient-dialog layer (the pickers, dialogs and panels
+ * that float above the prompt in `<OverlayAbove>`, plus /tips) as one
+ * explicit state machine.
+ *
+ * Previously this layer lived in ~28 sibling `useState` booleans+indices in
+ * Chat.tsx, with mutual exclusion emerging from "an open picker makes the
+ * prompt inert, so no second open command can be typed", and with two
+ * hand-maintained OR-aggregates (`promptSelectionActive`,
+ * `dialogOverlayOpen`) whose comments warned they must stay exactly in sync
+ * with the per-panel render conditions. A single discriminated union makes
+ * the exclusion structural — one variable can only hold one variant — and
+ * turns both aggregates into derivations that cannot drift.
+ *
+ * Design constraints, in order:
+ *   1. Behavior-preserving: every keyboard path, open/close side effect and
+ *      async-callback landing keeps its observable behavior. The one
+ *      deliberate change: an async OPEN landing while another overlay is up
+ *      (e.g. `/effort`'s listEfforts resolving after the user opened
+ *      `/model`) now REPLACES it instead of stacking two panels — the
+ *      stacked rendering was an unreachable-by-keyboard race, not a feature.
+ *   2. Pure and total: the reducer is a plain function, unit-tested by
+ *      scripts/verify-chat-overlay.ts without a renderer. Actions that no
+ *      longer apply (an async result landing after the overlay changed) are
+ *      ignored rather than writing orphan state.
+ *   3. Async data caches (model list, preset roster, …) stay OUTSIDE the
+ *      union in Chat.tsx: they persist across open/close so a reopened
+ *      picker can paint the previous list while the fresh one loads,
+ *      exactly as before.
+ */
+import type { ChatRow } from '../dsh-adapter/channel.js';
+import type { TuiRewindMode } from '../dsh-adapter/extension-events.js';
+import type { TuiWorkspaceCommandResult } from '../workspaces.js';
+/** The `kind: 'choices'` result a workspace command can return. */
+export type WorkspaceFlowChoices = Extract<TuiWorkspaceCommandResult, {
+    kind: 'choices';
+}>;
+/** Text-entry sub-state of the workspace flow (Tab into a choice's input). */
+export type WorkspaceFlowInput = {
+    choiceId: string;
+    value: string;
+    cursor: number;
+    placeholder?: string;
+};
+export type ChatOverlay = {
+    kind: 'none';
+} | {
+    kind: 'thinking';
+    focus: number;
+} | {
+    kind: 'workspace-picker';
+    index: number;
+} | {
+    kind: 'workspace-menu';
+    index: number;
+} | {
+    kind: 'workspace-flow';
+    flow: WorkspaceFlowChoices;
+    index: number;
+    busy: boolean;
+    input: WorkspaceFlowInput | null;
+} | {
+    kind: 'model';
+    index: number;
+} | {
+    kind: 'skills';
+    index: number;
+} | {
+    kind: 'activity';
+    index: number;
+} | {
+    kind: 'effort';
+    index: number;
+} | {
+    kind: 'preset';
+    index: number;
+} | {
+    kind: 'theme';
+    index: number;
+} | {
+    kind: 'permission';
+    index: number;
+} | {
+    kind: 'plan';
+    index: number;
+} | {
+    kind: 'lang';
+    index: number;
+} | {
+    kind: 'history';
+    query: string;
+    cursor: number;
+    focus: number;
+} | {
+    kind: 'rewind';
+    index: number;
+    confirm: ChatRow | null;
+    modes: readonly TuiRewindMode[] | null;
+    modeIndex: number;
+    busy: boolean;
+} | {
+    kind: 'search';
+} | {
+    kind: 'tips';
+};
+export declare const NO_OVERLAY: ChatOverlay;
+export type ChatOverlayAction = 
+/** Open a variant, replacing whatever is up (including `none`). */
+{
+    type: 'open';
+    overlay: ChatOverlay;
+}
+/** Close unconditionally (only dispatched from the open overlay's own keys). */
+ | {
+    type: 'close';
+}
+/** Close only if the given kind is still up — the safe form for async
+ *  callbacks (a loader failing after the user already moved on). */
+ | {
+    type: 'close-if';
+    kind: ChatOverlay['kind'];
+}
+/**
+ * Open only while the current kind is one of `when` — the safe form for an
+ * OPEN that arrives from an async callback (`/effort`'s level list, the
+ * workspace target list, a workspace command's choices). A user who opened
+ * something else during the round trip keeps what they opened; the stale
+ * open is dropped. Synchronous opens keep using plain `open`.
+ */
+ | {
+    type: 'open-if';
+    overlay: ChatOverlay;
+    when: readonly ChatOverlay['kind'][];
+}
+/**
+ * Move the focused row by one with wrap-around, over a list of `count`
+ * entries. On `rewind` this targets whichever cursor the sub-state focuses
+ * (mode list when a plugin offered modes, else the candidate list). A
+ * `count <= 0` move is a no-op (an empty list has no focus to move).
+ */
+ | {
+    type: 'move';
+    delta: 1 | -1;
+    count: number;
+}
+/** Set the focused row to an absolute index — an async loader landing
+ *  with the authoritative focus (model list / preset roster), or a mouse
+ *  click on a row of a panel that stays open (effort slider, workspace
+ *  flow). Ignored unless that panel is still up. */
+ | {
+    type: 'set-index';
+    kind: 'model' | 'preset' | 'effort' | 'workspace-flow' | 'rewind';
+    index: number;
+}
+/** Edit the history-search draft (query text, caret, focused match). */
+ | {
+    type: 'history-edit';
+    query?: string;
+    cursor?: number;
+    focus?: number;
+}
+/** Workspace flow: an action is running (keys except Esc are swallowed). */
+ | {
+    type: 'flow-busy';
+    busy: boolean;
+}
+/** Workspace flow: enter (object) or leave (null) the text-input state. */
+ | {
+    type: 'flow-input';
+    input: WorkspaceFlowInput | null;
+}
+/** Workspace flow: edit the text-input draft in place. */
+ | {
+    type: 'flow-input-edit';
+    value: string;
+    cursor: number;
+}
+/** Rewind: the plugin decision round-trip started / was abandoned. */
+ | {
+    type: 'rewind-busy';
+    busy: boolean;
+}
+/** Rewind: the plugin decision landed — show the confirm pane (modes turn
+ *  it into a choice list). Stale decisions are dropped by the caller's
+ *  request token before dispatch; a changed overlay drops them here. */
+ | {
+    type: 'rewind-decision';
+    confirm: ChatRow;
+    modes: readonly TuiRewindMode[] | null;
+}
+/** Rewind: Esc from the confirm/modes pane back to the candidate list. */
+ | {
+    type: 'rewind-back';
+};
+/**
+ * One-step wrap-around cursor move — the single source of the wrapping rule
+ * every list overlay uses (Chat.tsx's effort slider reads it too, to apply
+ * the newly focused level in the same keystroke that dispatches the move).
+ */
+export declare function wrapIndex(index: number, delta: 1 | -1, count: number): number;
+export declare function chatOverlayReducer(state: ChatOverlay, action: ChatOverlayAction): ChatOverlay;
+/**
+ * Whether the `<OverlayAbove>` wrapper mounts. Mounting is all-or-nothing:
+ * the renderer's removed-absolute-node blit detection only fires when the
+ * removed subtree itself is `position: absolute` (dom.ts
+ * collectRemovedRects), so the whole overlay must leave the tree when its
+ * last panel closes — see the mount-site comment in Chat.tsx.
+ *
+ * The per-kind data gates mirror the per-panel render conditions verbatim:
+ * a picker whose async list has not landed (or came back trivially small)
+ * paints nothing, so the wrapper must not mount for it either. `tips`
+ * returns true even though the panel renders in the prompt slot rather than
+ * inside the overlay — preserved verbatim from the boolean-era aggregate
+ * (the empty absolute wrapper is zero-size and paints nothing).
+ */
+export declare function dialogOverlayVisible(overlay: ChatOverlay, gates: {
+    workspaceTargetCount: number;
+    effortOptionCount: number;
+    presetOptionCount: number;
+}): boolean;
+//# sourceMappingURL=chatOverlay.d.ts.map

package/lib/types/screens/chatOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatOverlay.d.ts","sourceRoot":"","sources":["../../../src/screens/chatOverlay.ts"],"names":[],"mappings":"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"}

package/lib/types/screens/chatOverlay.js

@@ -0,0 +1,114 @@
+export const NO_OVERLAY = { kind: 'none' };
+/**
+ * One-step wrap-around cursor move — the single source of the wrapping rule
+ * every list overlay uses (Chat.tsx's effort slider reads it too, to apply
+ * the newly focused level in the same keystroke that dispatches the move).
+ */
+export function wrapIndex(index, delta, count) {
+    return delta === -1
+        ? (index <= 0 ? count - 1 : index - 1)
+        : (index >= count - 1 ? 0 : index + 1);
+}
+export function chatOverlayReducer(state, action) {
+    switch (action.type) {
+        case 'open':
+            return action.overlay;
+        case 'close':
+            return NO_OVERLAY;
+        case 'close-if':
+            return state.kind === action.kind ? NO_OVERLAY : state;
+        case 'open-if':
+            return action.when.includes(state.kind) ? action.overlay : state;
+        case 'move': {
+            if (action.count <= 0)
+                return state;
+            if (state.kind === 'rewind') {
+                // The confirm pane with plugin modes has its own cursor; the plain
+                // confirm pane has none (Enter/Esc only — a move must not disturb
+                // the list index behind it).
+                if (state.confirm !== null) {
+                    return state.modes !== null
+                        ? { ...state, modeIndex: wrapIndex(state.modeIndex, action.delta, action.count) }
+                        : state;
+                }
+                return { ...state, index: wrapIndex(state.index, action.delta, action.count) };
+            }
+            if (state.kind === 'thinking') {
+                return { ...state, focus: wrapIndex(state.focus, action.delta, action.count) };
+            }
+            if (state.kind === 'workspace-picker'
+                || state.kind === 'workspace-menu'
+                || state.kind === 'workspace-flow'
+                || state.kind === 'model'
+                || state.kind === 'skills'
+                || state.kind === 'activity'
+                || state.kind === 'effort'
+                || state.kind === 'preset'
+                || state.kind === 'theme'
+                || state.kind === 'permission'
+                || state.kind === 'plan'
+                || state.kind === 'lang') {
+                return { ...state, index: wrapIndex(state.index, action.delta, action.count) };
+            }
+            if (state.kind === 'history') {
+                return { ...state, focus: wrapIndex(state.focus, action.delta, action.count) };
+            }
+            return state;
+        }
+        case 'set-index':
+            return state.kind === action.kind ? { ...state, index: action.index } : state;
+        case 'history-edit':
+            return state.kind === 'history'
+                ? {
+                    ...state,
+                    ...(action.query === undefined ? {} : { query: action.query }),
+                    ...(action.cursor === undefined ? {} : { cursor: action.cursor }),
+                    ...(action.focus === undefined ? {} : { focus: action.focus }),
+                }
+                : state;
+        case 'flow-busy':
+            return state.kind === 'workspace-flow' ? { ...state, busy: action.busy } : state;
+        case 'flow-input':
+            return state.kind === 'workspace-flow' ? { ...state, input: action.input } : state;
+        case 'flow-input-edit':
+            return state.kind === 'workspace-flow' && state.input !== null
+                ? { ...state, input: { ...state.input, value: action.value, cursor: action.cursor } }
+                : state;
+        case 'rewind-busy':
+            return state.kind === 'rewind' ? { ...state, busy: action.busy } : state;
+        case 'rewind-decision':
+            return state.kind === 'rewind'
+                ? { ...state, busy: false, confirm: action.confirm, modes: action.modes, modeIndex: 0 }
+                : state;
+        case 'rewind-back':
+            return state.kind === 'rewind' ? { ...state, confirm: null, modes: null } : state;
+    }
+}
+/**
+ * Whether the `<OverlayAbove>` wrapper mounts. Mounting is all-or-nothing:
+ * the renderer's removed-absolute-node blit detection only fires when the
+ * removed subtree itself is `position: absolute` (dom.ts
+ * collectRemovedRects), so the whole overlay must leave the tree when its
+ * last panel closes — see the mount-site comment in Chat.tsx.
+ *
+ * The per-kind data gates mirror the per-panel render conditions verbatim:
+ * a picker whose async list has not landed (or came back trivially small)
+ * paints nothing, so the wrapper must not mount for it either. `tips`
+ * returns true even though the panel renders in the prompt slot rather than
+ * inside the overlay — preserved verbatim from the boolean-era aggregate
+ * (the empty absolute wrapper is zero-size and paints nothing).
+ */
+export function dialogOverlayVisible(overlay, gates) {
+    switch (overlay.kind) {
+        case 'none':
+            return false;
+        case 'workspace-picker':
+            return gates.workspaceTargetCount > 0;
+        case 'effort':
+            return gates.effortOptionCount > 1;
+        case 'preset':
+            return gates.presetOptionCount > 0;
+        default:
+            return true;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../src/tips.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AAEhF,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,QAAQ,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;CACX;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAMzE,CAAA;AAED,eAAO,MAAM,IAAI,EAAE,SAAS,GAAG,EAwjB9B,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAM,MAAoB,GAAG,GAAG,CAErE;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,GAAG,EAAE,CAElD"}
+{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../src/tips.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AAEhF,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,QAAQ,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;CACX;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAMzE,CAAA;AAED,eAAO,MAAM,IAAI,EAAE,SAAS,GAAG,EA4lB9B,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAM,MAAoB,GAAG,GAAG,CAErE;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,GAAG,EAAE,CAElD"}

package/lib/types/tips.js

@@ -146,8 +146,14 @@ export const TIPS = [
     {
         id: 'keys-mouse-click',
         group: 'keys',
-        zh: '单击消息行展开/收起；点链接直接打开浏览器',
-        en: 'Click a message row to expand it; click links to open the browser',
+        zh: '工具卡/thinking/摘要点击展开，子代理卡点击看详情；输入框点击定位光标',
+        en: 'Click tool/thinking/summary rows to fold; subagent cards open detail; click input to move caret',
+    },
+    {
+        id: 'keys-mouse-scenes',
+        group: 'keys',
+        zh: '轨迹与 /settings 支持鼠标：行点击跳转/编辑，滚轮移动光标或焦点',
+        en: 'Trajectory and /settings take the mouse: row clicks jump/edit, the wheel moves cursor or focus',
     },
     // ── 命令 ──────────────────────────────────────────────────
     {
@@ -327,8 +333,8 @@ export const TIPS = [
     {
         id: 'cmd-permission',
         group: 'commands',
-        zh: '/permission 切换权限预设（read-only/workspace/full）',
-        en: '/permission switches permission presets (read-only/workspace/full)',
+        zh: '/permission 弹出权限预设选择器（只读/工作区读写/完全访问）',
+        en: '/permission opens the permission-preset picker (read-only/workspace-write/full)',
     },
     {
         id: 'cmd-plan-goal',
@@ -410,6 +416,36 @@ export const TIPS = [
         zh: '底栏 TPS、轨迹条、上下文条默认关，/settings 里打开',
         en: 'TPS, trajectory, context bars are off by default — enable in /settings',
     },
+    {
+        id: 'disp-statusbar-session-id',
+        group: 'display',
+        zh: '底栏可显示短会话 ID（# 前 8 位），与日志文件名对应，/settings 里开',
+        en: 'Footer can show the short session id (# + 8 chars, matches the log filename) — enable in /settings',
+    },
+    {
+        id: 'disp-statusbar-title',
+        group: 'display',
+        zh: '底栏可显示会话标题；/rename 随时改',
+        en: 'Footer can show the session title; rename anytime with /rename',
+    },
+    {
+        id: 'disp-statusbar-fields',
+        group: 'display',
+        zh: '底栏字段逐项开关：token 总量、git 分支、模式、活动摘要…… /settings 里配',
+        en: 'Footer fields are per-field switches: token totals, git branch, mode, activity — set in /settings',
+    },
+    {
+        id: 'disp-statusbar-compact',
+        group: 'display',
+        zh: '底栏 compact 开=单行收纳；关=左右分组（指标在左、位置在右）',
+        en: 'Footer compact on = one merged line; off = metrics left, location right',
+    },
+    {
+        id: 'disp-statusbar-hint',
+        group: 'display',
+        zh: "空闲时 '? 查看快捷键' 常驻提示也是底栏开关（shortcutHint）",
+        en: 'The idle "? for shortcuts" reminder is itself a footer switch (shortcutHint)',
+    },
     {
         id: 'disp-context-warn',
         group: 'display',
@@ -558,8 +594,8 @@ export const TIPS = [
     {
         id: 'pit-mouse-mode',
         group: 'pitfalls',
-        zh: '鼠标操作仅在全屏模式（fullscreen）下生效',
-        en: 'Mouse support only works in fullscreen mode',
+        zh: '主界面鼠标需开 fullscreen；轨迹/resume 整屏页两种模式都带鼠标',
+        en: 'Main-chat mouse needs fullscreen; full-page screens (trajectory, /resume) have it in both modes',
     },
     {
         id: 'pit-env-rename',

package/lib/types/tuiDisplayPrefs.d.ts

@@ -1,5 +1,14 @@
 /** Background treatment applied to tool-call cards. */
 export type ToolBackground = 'none' | 'subtle' | 'strong';
+/**
+ * What the fullscreen transcript's right gutter shows:
+ *  - `timeline`: Grok-style turn rail — one tick per user turn (conversation
+ *    order, not scroll proportion), active turn highlighted, click to jump;
+ *  - `scrollbar`: classic proportional thumb — position/size of the visible
+ *    window over the whole content, click the track to scroll there;
+ *  - `hidden`: no gutter; the transcript takes the full width.
+ */
+export type ScrollGutterMode = 'timeline' | 'scrollbar' | 'hidden';
 /** Individually selectable fields in the status footer. */
 export interface StatusBarConfig {
     /** Prefer the compact, single-line presentation when space permits. */
@@ -22,6 +31,10 @@ export interface StatusBarConfig {
     gitBranch: boolean;
     /** Current session title. */
     sessionTitle: boolean;
+    /** Short session id (# + first 8 chars), matching the session log filename. */
+    sessionId: boolean;
+    /** Compact goal chip (phase glyph + rounds) while a goal exists. */
+    goal: boolean;
     /** Non-default session mode. */
     mode: boolean;
     /** Segmented context progress bar on its own footer row. */
@@ -37,6 +50,8 @@ export interface StatusBarConfig {
 export declare const DEFAULT_STATUS_BAR: Readonly<StatusBarConfig>;
 /** Normalize untrusted/config-layer values without mutating the input. */
 export declare function normalizeToolBackground(value: unknown): ToolBackground;
+/** Same normalize contract as toolBackground; `timeline` is the default. */
+export declare function normalizeScrollGutter(value: unknown): ScrollGutterMode;
 /** Merge a partial settings value over the stable status-bar defaults. */
 export declare function normalizeStatusBar(value: unknown): StatusBarConfig;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"tuiDisplayPrefs.d.ts","sourceRoot":"","sources":["../../src/tuiDisplayPrefs.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEzD,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,qBAAqB;IACrB,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAA;IACjB,iCAAiC;IACjC,GAAG,EAAE,OAAO,CAAA;IACZ,0CAA0C;IAC1C,YAAY,EAAE,OAAO,CAAA;IACrB,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAA;IACd,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;IACf,oCAAoC;IACpC,GAAG,EAAE,OAAO,CAAA;IACZ,0BAA0B;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,6BAA6B;IAC7B,YAAY,EAAE,OAAO,CAAA;IACrB,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;IACnB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAA;IACjB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAA;IACnB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAgBvD,CAAA;AAKF,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAItE;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CASlE;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,OAAO,UAAO,GACb,MAAM,GAAG,SAAS,CASpB"}
+{"version":3,"file":"tuiDisplayPrefs.d.ts","sourceRoot":"","sources":["../../src/tuiDisplayPrefs.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEzD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElE,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,qBAAqB;IACrB,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAA;IACjB,iCAAiC;IACjC,GAAG,EAAE,OAAO,CAAA;IACZ,0CAA0C;IAC1C,YAAY,EAAE,OAAO,CAAA;IACrB,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAA;IACd,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;IACf,oCAAoC;IACpC,GAAG,EAAE,OAAO,CAAA;IACZ,0BAA0B;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,6BAA6B;IAC7B,YAAY,EAAE,OAAO,CAAA;IACrB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAA;IAClB,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAA;IACb,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;IACnB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAA;IACjB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAA;IACnB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAkBvD,CAAA;AAMF,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAItE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAItE;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CASlE;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,OAAO,UAAO,GACb,MAAM,GAAG,SAAS,CASpB"}

package/lib/types/tuiDisplayPrefs.js

@@ -10,6 +10,8 @@ export const DEFAULT_STATUS_BAR = Object.freeze({
     tps: false,
     gitBranch: false,
     sessionTitle: false,
+    sessionId: false,
+    goal: true,
     mode: false,
     contextBar: false,
     activity: false,
@@ -17,6 +19,7 @@ export const DEFAULT_STATUS_BAR = Object.freeze({
     shortcutHint: false,
 });
 const TOOL_BACKGROUNDS = new Set(['none', 'subtle', 'strong']);
+const SCROLL_GUTTERS = new Set(['timeline', 'scrollbar', 'hidden']);
 const STATUS_BAR_KEYS = Object.keys(DEFAULT_STATUS_BAR);
 /** Normalize untrusted/config-layer values without mutating the input. */
 export function normalizeToolBackground(value) {
@@ -24,6 +27,12 @@ export function normalizeToolBackground(value) {
         ? value
         : 'none';
 }
+/** Same normalize contract as toolBackground; `timeline` is the default. */
+export function normalizeScrollGutter(value) {
+    return typeof value === 'string' && SCROLL_GUTTERS.has(value)
+        ? value
+        : 'timeline';
+}
 /** Merge a partial settings value over the stable status-bar defaults. */
 export function normalizeStatusBar(value) {
     const normalized = { ...DEFAULT_STATUS_BAR };

package/lib/types/utils/debug.d.ts

@@ -5,4 +5,14 @@
  * @param fields - Optional JSON-serialized fields appended to the line.
  */
 export declare function logForDebugging(message: string, fields?: Record<string, unknown>): void;
+/**
+ * Mouse-chain diagnostics: appends to `~/.dsh-cc/mouse-debug.log` when
+ * `DSH_TUI_DEBUG_MOUSE` is set. Unlike logForDebugging (stderr), a file
+ * keeps the fullscreen alt screen unpolluted and survives the session for
+ * post-mortem reading. Every append is try/catch-guarded — diagnostics
+ * must never take the UI down.
+ * @param message - Stage name (e.g. 'mouse arrive', 'dispatchClick').
+ * @param fields - Optional JSON-serialized fields appended to the line.
+ */
+export declare function logMouseDebug(message: string, fields?: Record<string, unknown>): void;
 //# sourceMappingURL=debug.d.ts.map

package/lib/types/utils/debug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIvF"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/utils/debug.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASrF"}

package/lib/types/utils/debug.js

@@ -1,3 +1,6 @@
+import { appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 /**
  * Debug logger for the ported Ink core. Writes to stderr only when
  * `DSH_TUI_DEBUG` is set, so normal runs stay quiet.
@@ -10,3 +13,24 @@ export function logForDebugging(message, fields) {
     const suffix = fields === undefined ? '' : ` ${JSON.stringify(fields)}`;
     process.stderr.write(`[dsh-tui] ${message}${suffix}\n`);
 }
+/**
+ * Mouse-chain diagnostics: appends to `~/.dsh-cc/mouse-debug.log` when
+ * `DSH_TUI_DEBUG_MOUSE` is set. Unlike logForDebugging (stderr), a file
+ * keeps the fullscreen alt screen unpolluted and survives the session for
+ * post-mortem reading. Every append is try/catch-guarded — diagnostics
+ * must never take the UI down.
+ * @param message - Stage name (e.g. 'mouse arrive', 'dispatchClick').
+ * @param fields - Optional JSON-serialized fields appended to the line.
+ */
+export function logMouseDebug(message, fields) {
+    if (!process.env.DSH_TUI_DEBUG_MOUSE)
+        return;
+    const suffix = fields === undefined ? '' : ` ${JSON.stringify(fields)}`;
+    try {
+        const line = `${new Date().toISOString()} ${message}${suffix}\n`;
+        appendFileSync(join(homedir(), '.dsh-cc', 'mouse-debug.log'), line);
+    }
+    catch {
+        // ignore — see doc comment
+    }
+}

package/lib/types/utils/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/utils/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,qEAAqE;AACrE,eAAO,MAAM,QAAQ,QAA8B,CAAA;AAEnD,wEAAwE;AACxE,eAAO,MAAM,eAAe,QAA6B,CAAA;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,GAAE,MAAwB,EAChC,MAAM,GAAE,MAAiB,GACxB,OAAO,CAOT;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxD,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAEV"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/utils/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,qEAAqE;AACrE,eAAO,MAAM,QAAQ,QAA8B,CAAA;AAEnD,wEAAwE;AACxE,eAAO,MAAM,eAAe,QAA6B,CAAA;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,GAAE,MAAwB,EAChC,MAAM,GAAE,MAAiB,GACxB,OAAO,CAOT;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxD,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAEV"}

package/lib/types/utils/paths.js

@@ -57,6 +57,7 @@ export const RENAMED_ENV = {
     CC_TUI_COMPACT_RETAIN: 'DSH_TUI_COMPACT_RETAIN',
     DSH_CC_UPDATED_FROM: 'DSH_TUI_UPDATED_FROM',
     DSH_CC_RENDER_LOG: 'DSH_TUI_RENDER_LOG',
+    DSH_CC_GEOMETRY_TRACE: 'DSH_TUI_GEOMETRY_TRACE',
     DSH_CC_SESSION_ROOT: 'DSH_TUI_SESSION_ROOT',
     DSH_CC_WORKSPACE: 'DSH_TUI_WORKSPACE',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-harness-tui/dsh-tui",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "Claude Code style interactive TUI front door for DeepSeek Harness agents, built on the ported Ink core.",
   "license": "MIT",
   "repository": {
@@ -93,7 +93,7 @@
     "prompt:debug": "node scripts/read-prompt-debug.mjs",
     "tui": "node --import tsx/esm scripts/run.ts",
     "smoke": "node --import tsx/esm scripts/smoke.tsx",
-    "verify:build": "npm run verify:boundary && npm run verify:contract && npm run verify:herdr && npm run verify:manifest-deps && npm run verify:patch-surface && npm run verify:web-coexistence && npm run verify:plugin-spec && npm run verify:plugin-grants && npm run verify:plugin-storage && npm run verify:plugin-messages && npm run verify:plugin-ledger && npm run verify:plugin-commands && npm run verify:plugin-negotiation && npm run verify:plugin-lifecycle && npm run verify:packaged-presets && npm run verify:minimal-preset-tools && npm run verify:liangshen-bootstrap && npm run verify:wheel-selection",
+    "verify:build": "npm run verify:boundary && npm run verify:contract && npm run verify:herdr && npm run verify:manifest-deps && npm run verify:patch-surface && npm run verify:web-coexistence && npm run verify:plugin-spec && npm run verify:plugin-grants && npm run verify:plugin-storage && npm run verify:plugin-messages && npm run verify:plugin-ledger && npm run verify:plugin-commands && npm run verify:plugin-negotiation && npm run verify:plugin-lifecycle && npm run verify:packaged-presets && npm run verify:minimal-preset-tools && npm run verify:liangshen-bootstrap && npm run verify:wheel-selection && npm run verify:pointer-events && npm run verify:chat-overlay",
     "verify:boundary": "node --import tsx/esm scripts/verify-adapter-boundary.ts",
     "verify:contract": "node --import tsx/esm scripts/verify-upstream-contract.ts",
     "verify:herdr": "node --import tsx/esm scripts/verify-herdr-integration.ts",
@@ -119,6 +119,8 @@
     "verify:tips": "node --import tsx/esm scripts/verify-tips.tsx",
     "verify:thinking-preview": "node --import tsx/esm scripts/verify-thinking-preview.tsx",
     "verify:wheel-selection": "node --import tsx/esm scripts/verify-wheel-selection.ts",
+    "verify:pointer-events": "node --import tsx/esm scripts/verify-pointer-events.ts",
+    "verify:chat-overlay": "node --import tsx/esm scripts/verify-chat-overlay.ts",
     "sync:profile": "node scripts/sync-profile.mjs",
     "sync:profile:check": "node scripts/sync-profile.mjs --check"
   },