@aiwayds/dsh-tui-pi 1.0.8 → 1.2.0

package/README.md

@@ -24,6 +24,7 @@ https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 - [**Model profiles & favorites**](#model-profiles-and-favorites) — switch a whole model setup per project and keep the picker small.
 - [**Sessions & resume**](#sessions-and-resume) — sessions stay tidy automatically and resume in a few keystrokes.
 - [**Themes**](#themes) — GitHub light/dark palettes, hot-switchable; `auto` follows your terminal.
+- [**Search, selection & images**](#search-selection-and-images) — `Ctrl+Shift+F` over the whole transcript, drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
 
 ---
 
@@ -107,6 +108,15 @@ GitHub light/dark palettes, hot-switched with `/theme`; `auto` detects your term
 
 ---
 
+## Search, selection and images
+
+- **Transcript search** — `Ctrl+Shift+F` opens an input overlay over the transcript; `Enter`/`Ctrl+G` and `Shift+Enter`/`Ctrl+Shift+G` walk the matches, `Esc` closes. While it is open the search owns the keys, so your Esc/Ctrl+C gestures stay untouched.
+- **Selection copy** — drag to select anywhere in the transcript; releasing copies through the OS clipboard (`pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip`, with OSC 52 riding along for terminals that honor it). `DSH_TUI_COPY_ON_SELECT=0` keeps selection visual-only. Mouse tracking is still tuned by `DSH_TUI_MOUSE` (default `buttons`: clicks, wheel, drag-selection and scrollbar dragging, no idle-motion noise).
+- **Images from other surfaces** — messages sent with attachments from the web UI or Feishu render inline in the transcript: a real bitmap on Kitty / Ghostty / WezTerm (kitty graphics) and iTerm2, a clickable filename fallback elsewhere, and a muted "unavailable" note if the stored attachment fails verification. Session resume re-renders past images too.
+- **LaTeX in replies** — `$e^{i\pi}+1=0$` and `$$\int_0^1 x\,dx$$` render as terminal-friendly Unicode math (`e^(iπ)+1 = 0`, `∫₀¹ x dx`). Quirk inherited from upstream: a literal `$$` pair in prose is treated as display math.
+
+---
+
 ## Slash commands
 
 | Command | What it does |
@@ -116,6 +126,7 @@ GitHub light/dark palettes, hot-switched with `/theme`; `auto` detects your term
 | `/session` | Read-only info: id, cwd, model, token usage, event count. |
 | `/resume` | Pick a persisted session (newest first), validate its log, restore it. |
 | `/new` | Detach the current session; the next prompt opens a fresh one. |
+| `/btw` | By-the-way side question while the main task runs — one tool-less model call over a recent-conversation snapshot, streamed into a temporary overlay. Never kept in the session; idle main line refuses it; `--model provider/model` overrides the route; bare `/btw` reopens the last answer (`DSH_TUI_BTW_CONTEXT_MESSAGES` sizes the snapshot). |
 | `/settings` | Text-based settings browser (namespaces, schema walk, secrets masked). |
 | `/export` | Write the current session log as JSONL. |
 | `/permission` | Permission-preset picker (read-only / workspace-write / danger-full-access). |
@@ -151,6 +162,7 @@ Anything else falls through to the model as an ordinary prompt; dsh-native comma
 | `Ctrl+L` | Open the model/think picker |
 | `Ctrl+G` | Open the subagent picker (viewer `Enter` opens steer) |
 | `Ctrl+O` | Pending-message queue (s steer now · d remove) |
+| `Ctrl+Shift+F` | Transcript search (`Enter`/`Ctrl+G` next · `Shift+Enter`/`Ctrl+Shift+G` previous · `Esc` close) |
 | `Tab` | Cycle agent presets |
 | `↑` / `↓` | Browse submitted-message history |
 
@@ -173,7 +185,7 @@ dsh-tui:
     minBytes: 20480
 ```
 
-Other knobs: `dsh-tui.panelHeight` (think/tool panel height), `dsh-tui.iconSet` (`auto`/`nerdfont`/`plain` — powerline glyphs adapt to your font; install a Nerd Font with `node scripts/install-font.mjs`), `~/.dsh/keybindings.json` (key remaps).
+Other knobs: `dsh-tui.panelHeight` (think/tool panel height), `dsh-tui.iconSet` (`auto`/`nerdfont`/`plain` — powerline glyphs adapt to your font; install a Nerd Font with `node scripts/install-font.mjs`), `dsh-tui.footerHints` (toggle each footer hint segment, incl. `search`), `DSH_TUI_COPY_ON_SELECT=0` (keep drag-selection visual-only), `~/.dsh/keybindings.json` (key remaps).
 
 ---
 

package/README.zh-CN.md

@@ -116,6 +116,7 @@ GitHub 明/暗配色，`/theme` 热切换；`auto` 检测你的终端并跟随
 | `/session` | 只读信息：id、cwd、model、token 用量、事件数。 |
 | `/resume` | 选择持久化的 session（新的在前），校验日志后恢复。 |
 | `/new` | 分离当前 session；下一条 prompt 开启新会话。 |
+| `/btw` | 主线任务运行中的「顺带一问」——一次无工具的单次模型调用（带最近对话快照），答案流式呈现在临时浮层里。不进会话记录；主线空闲时拒绝使用；`--model provider/model` 临时换路由；空参 `/btw` 回看上一条问答（`DSH_TUI_BTW_CONTEXT_MESSAGES` 控制快照条数）。 |
 | `/settings` | 文本式设置浏览器（命名空间、schema 遍历、密钥脱敏）。 |
 | `/export` | 把当前会话日志写成 JSONL。 |
 | `/permission` | 权限预设选择器（read-only / workspace-write / danger-full-access）。 |

package/lib/attachments.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Transcript rendering for user-message image attachments (pi-tui Image).
+ *
+ * dsh records attached images in user content as `ImageBlock`s whose
+ * attachment is a REFERENCE (attachmentId/mediaType/bytes/width/height),
+ * never inline bytes. The reference is content-addressed: the attachmentId
+ * embeds the sha256 of the stored bytes, and the durable store lives at
+ * `$DSH_HOME/attachments/v1/objects/<aa>/<sha256>` (dsh-attachment-local).
+ * The TUI renders a muted placeholder the moment the event arrives, then
+ * loads the bytes out of band and swaps the placeholder for a pi-tui
+ * `Image` component — kitty/iterm2 terminals paint the real bitmap,
+ * everything else falls back to the component's text placeholder
+ * (shortened path-style name + OSC 8 file:// link). A failed load (missing
+ * object, corrupt digest, metadata mismatch) degrades to a muted
+ * "unavailable" note; the transcript never blocks or throws on images.
+ *
+ * Session replay covers this automatically: resume feeds historical
+ * `user/message` events through the same TranscriptRenderer.applyEvent
+ * path, so past images render (and re-load) like live ones.
+ *
+ * Budget: alt-screen image surfaces cost real rows and (under kitty)
+ * placements, so a message renders at most {@link MAX_IMAGES_PER_MESSAGE}
+ * bitmaps; the rest collapse into a single "+N more" line.
+ */
+import { Container } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+/** Bitmaps rendered per message; extra image blocks collapse to a "+N more" line. */
+export declare const MAX_IMAGES_PER_MESSAGE = 8;
+/** The versioned attachment storage root (`$DSH_HOME/attachments/v1`). */
+export declare function attachmentsRoot(home?: string): string;
+/** The image block shape dsh carries in user-message content (structural). */
+export interface ImageBlockLike {
+    type: 'image';
+    attachment: {
+        attachmentId: string;
+        mediaType: string;
+        bytes: number;
+        width: number;
+        height: number;
+        name?: string;
+    };
+}
+export declare function isImageBlock(block: unknown): block is ImageBlockLike;
+/** Verified stored bytes — the slice of dsh-attachment-local's result we use. */
+interface StoredImage {
+    data: Uint8Array;
+}
+export declare function __setImageReaderForTest(reader: AttachmentReader | undefined): void;
+/**
+ * The byte-loading seam. Structural twin of dsh-attachment-local's
+ * `readImageFile(root, ref, signal)` (its branded `ImageAttachmentRef` is
+ * the same shape; the cast lives at the default-deps site below).
+ */
+export type AttachmentReader = (root: string, ref: ImageBlockLike['attachment'], signal?: AbortSignal) => Promise<StoredImage>;
+export interface ImageRenderDeps {
+    /** Attachment storage root; defaults to {@link attachmentsRoot}. */
+    root?: string;
+    /** Byte loader; defaults to dsh-attachment-local's verified reader. */
+    read?: AttachmentReader;
+    /** Repaint hook fired when an async load settles; defaults to a no-op. */
+    requestRender?: () => void;
+}
+/**
+ * Render a message's image blocks into the transcript doc: one slot per
+ * image (placeholder → loaded bitmap / unavailable note), then a trailing
+ * Spacer. Never throws — a bad attachment degrades to a note.
+ */
+export declare function renderImageAttachments(doc: Container, blocks: readonly ImageBlockLike[], theme: TuiTheme, deps?: ImageRenderDeps): void;
+export {};

package/lib/attachments.js

@@ -0,0 +1,110 @@
+/**
+ * Transcript rendering for user-message image attachments (pi-tui Image).
+ *
+ * dsh records attached images in user content as `ImageBlock`s whose
+ * attachment is a REFERENCE (attachmentId/mediaType/bytes/width/height),
+ * never inline bytes. The reference is content-addressed: the attachmentId
+ * embeds the sha256 of the stored bytes, and the durable store lives at
+ * `$DSH_HOME/attachments/v1/objects/<aa>/<sha256>` (dsh-attachment-local).
+ * The TUI renders a muted placeholder the moment the event arrives, then
+ * loads the bytes out of band and swaps the placeholder for a pi-tui
+ * `Image` component — kitty/iterm2 terminals paint the real bitmap,
+ * everything else falls back to the component's text placeholder
+ * (shortened path-style name + OSC 8 file:// link). A failed load (missing
+ * object, corrupt digest, metadata mismatch) degrades to a muted
+ * "unavailable" note; the transcript never blocks or throws on images.
+ *
+ * Session replay covers this automatically: resume feeds historical
+ * `user/message` events through the same TranscriptRenderer.applyEvent
+ * path, so past images render (and re-load) like live ones.
+ *
+ * Budget: alt-screen image surfaces cost real rows and (under kitty)
+ * placements, so a message renders at most {@link MAX_IMAGES_PER_MESSAGE}
+ * bitmaps; the rest collapse into a single "+N more" line.
+ */
+import { Container, Image, Spacer, Text } from '@earendil-works/pi-tui';
+import { readImageFile } from '@deepseek-ai/dsh-attachment-local';
+import { join } from 'node:path';
+import { dshHome } from "./append-system.js";
+import { ansiFg, RESET } from "./theme/index.js";
+/** Bitmaps rendered per message; extra image blocks collapse to a "+N more" line. */
+export const MAX_IMAGES_PER_MESSAGE = 8;
+/** The versioned attachment storage root (`$DSH_HOME/attachments/v1`). */
+export function attachmentsRoot(home = dshHome()) {
+    return join(home, 'attachments', 'v1');
+}
+export function isImageBlock(block) {
+    return (typeof block === 'object' && block !== null
+        && block.type === 'image'
+        && typeof block.attachment === 'object');
+}
+/**
+ * Test seam for the byte loader: TranscriptRenderer calls the render path
+ * without deps, so tests swap the loader here instead of faking a dsh
+ * attachment store. `undefined` restores the real verified reader.
+ */
+let testReader;
+export function __setImageReaderForTest(reader) {
+    testReader = reader;
+}
+/**
+ * Render a message's image blocks into the transcript doc: one slot per
+ * image (placeholder → loaded bitmap / unavailable note), then a trailing
+ * Spacer. Never throws — a bad attachment degrades to a note.
+ */
+export function renderImageAttachments(doc, blocks, theme, deps = {}) {
+    if (blocks.length === 0)
+        return;
+    const read = deps.read ?? testReader ?? readImageFile;
+    const root = deps.root ?? attachmentsRoot();
+    const requestRender = deps.requestRender ?? (() => { });
+    const muted = (text) => new Text(ansiFg(theme.palette.fgMuted) + text + RESET, 1, 0);
+    // The component's own text fallback (unsupported terminal) carries the
+    // same muted paint as our loading/unavailable notes.
+    const imageTheme = { fallbackColor: (str) => ansiFg(theme.palette.fgMuted) + str + RESET };
+    const shown = blocks.slice(0, MAX_IMAGES_PER_MESSAGE);
+    for (const block of shown) {
+        const slot = new Container();
+        const name = block.attachment.name ?? block.attachment.attachmentId;
+        const placeholder = muted(`🖼 ${name} — loading (${block.attachment.width}×${block.attachment.height})`);
+        slot.addChild(placeholder);
+        doc.addChild(slot);
+        void loadImageSlot(slot, placeholder, block, { read, root, requestRender, muted, imageTheme });
+    }
+    if (blocks.length > shown.length) {
+        doc.addChild(muted(`🖼 +${blocks.length - shown.length} more images not shown`));
+    }
+    doc.addChild(new Spacer(1));
+}
+/**
+ * Settle one slot: swap the placeholder for the loaded Image (the
+ * component itself decides bitmap vs text fallback by terminal capability)
+ * or, on failure, for a muted "unavailable" note carrying the attachment
+ * error code. Fire-and-forget by contract — every rejection is caught.
+ */
+async function loadImageSlot(slot, placeholder, block, deps) {
+    const name = block.attachment.name ?? block.attachment.attachmentId;
+    let loaded;
+    try {
+        loaded = await deps.read(deps.root, block.attachment);
+    }
+    catch (error) {
+        const code = error?.code
+            ?? error?.detailCode;
+        slot.removeChild(placeholder);
+        slot.addChild(deps.muted(`🖼 ${name} — unavailable${code ? ` (${code})` : ''}`));
+        try {
+            deps.requestRender();
+        }
+        catch { /* TUI already disposed */ }
+        return;
+    }
+    const base64 = Buffer.from(loaded.data).toString('base64');
+    slot.removeChild(placeholder);
+    slot.addChild(new Image(base64, block.attachment.mediaType, deps.imageTheme, { filename: block.attachment.name }));
+    try {
+        deps.requestRender();
+    }
+    catch { /* TUI already disposed */ }
+}
+//# sourceMappingURL=attachments.js.map

package/lib/attachments.js.map

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

package/lib/btw-overlay.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The btw overlay — framed floating panel presenting one side-call exchange
+ * (CONTEXT.md: Btw overlay). Bound to a single BtwRunState object: a live
+ * run is the controller's own mutable state (setText streaming, Markdown
+ * once on settle), a review is a plain snapshot object from the Last-btw
+ * slot. Esc closes through the shared overlay focus contract — closing
+ * never stops the run; it delivers into the slot regardless.
+ *
+ * Pure rendering + key routing only; all decisions live in btw.ts. This file
+ * is the PanelHost glue and is exercised on a terminal, not in unit tests
+ * (same split as route-dialog).
+ */
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+import type { BtwController, BtwRunState } from './btw.ts';
+export declare class BtwOverlayPanel implements Component {
+    private readonly run;
+    private readonly controller;
+    private readonly theme;
+    private readonly onClose;
+    private readonly question;
+    /** Streaming view — one Text, setText per change (AGENTS.md #2). */
+    private readonly answerText;
+    private streamedText;
+    /** Built once when the run settles; never re-parsed per frame. */
+    private finalMarkdown;
+    constructor(run: BtwRunState, controller: BtwController, theme: () => TuiTheme, onClose: () => void);
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+}
+/**
+ * Overlay lifecycle for btw runs: `open(run)` shows/swaps the framed panel
+ * bound to that run state; Esc and cancelAll close it through restoreFocus.
+ * Two-step wiring — construct first, `attach(controller)` once it exists
+ * (the panel needs the controller for the queued count; the controller needs
+ * these callbacks at construction).
+ */
+export declare class BtwOverlayWire {
+    private readonly tui;
+    private readonly theme;
+    private readonly restoreFocus;
+    private host;
+    private controller;
+    constructor(deps: {
+        tui: TUI;
+        theme: () => TuiTheme;
+        restoreFocus: () => void;
+    });
+    attach(controller: BtwController): void;
+    /** Called by the controller for every launched or reviewed run. */
+    open(run: BtwRunState): void;
+    /** Called by cancelAll — the overlay's run is gone either way. */
+    requestClose(): void;
+}

package/lib/btw-overlay.js

@@ -0,0 +1,153 @@
+/**
+ * The btw overlay — framed floating panel presenting one side-call exchange
+ * (CONTEXT.md: Btw overlay). Bound to a single BtwRunState object: a live
+ * run is the controller's own mutable state (setText streaming, Markdown
+ * once on settle), a review is a plain snapshot object from the Last-btw
+ * slot. Esc closes through the shared overlay focus contract — closing
+ * never stops the run; it delivers into the slot regardless.
+ *
+ * Pure rendering + key routing only; all decisions live in btw.ts. This file
+ * is the PanelHost glue and is exercised on a terminal, not in unit tests
+ * (same split as route-dialog).
+ */
+import { getKeybindings, Markdown, Text } from '@earendil-works/pi-tui';
+import { PanelHost, panelThemeFns } from "./panels.js";
+import { BOLD, RESET, ansiFg } from "./theme/index.js";
+import { clipToWidth } from "./text.js";
+/**
+ * Answer row budget, sized so the panel NEVER overflows the 24-row e2e
+ * terminal (AGENTS.md matrix floor): maxHeight '80%' ≈ 19 rows there, the
+ * FramedOverlay chrome eats 4, fixed rows are 4 (title + 2 blanks + status),
+ * and the question rows come out of the remainder per frame — an overlay
+ * taller than that just shows a roomier answer. Overflow of the answer
+ * itself is a named tail window (the newest rows stay visible).
+ */
+const BTW_ANSWER_BASE_BUDGET = 11;
+const BTW_ANSWER_MIN_BUDGET = 3;
+export class BtwOverlayPanel {
+    run;
+    controller;
+    theme;
+    onClose;
+    question;
+    /** Streaming view — one Text, setText per change (AGENTS.md #2). */
+    answerText;
+    streamedText = '';
+    /** Built once when the run settles; never re-parsed per frame. */
+    finalMarkdown;
+    constructor(run, controller, theme, onClose) {
+        this.run = run;
+        this.controller = controller;
+        this.theme = theme;
+        this.onClose = onClose;
+        this.question = new Text(run.question, 1, 0);
+        this.answerText = new Text('', 1, 0);
+    }
+    invalidate() { }
+    render(width) {
+        const fns = panelThemeFns(this.theme());
+        const wrap = Math.max(2, width - 2);
+        const questionLines = this.question.render(wrap);
+        const budget = Math.max(BTW_ANSWER_MIN_BUDGET, BTW_ANSWER_BASE_BUDGET - questionLines.length);
+        const lines = [
+            fns.accent(BOLD + clipToWidth(`⌘ btw — ${this.run.modelLabel}`, wrap) + RESET),
+            ...questionLines,
+            '',
+        ];
+        const queued = this.controller.queuedCount;
+        if (this.run.status === 'streaming') {
+            if (this.run.answerText !== this.streamedText) {
+                this.answerText.setText(this.run.answerText);
+                this.streamedText = this.run.answerText;
+            }
+            if (this.run.answerText !== '') {
+                lines.push(...tailWindow(this.answerText.render(wrap), budget, wrap));
+            }
+            else {
+                lines.push(fns.muted(clipToWidth('Thinking…', wrap)));
+            }
+            lines.push('');
+            lines.push(fns.subtle(clipToWidth(`Running alongside the main task · Esc close${queued > 0 ? ` · ${queued} queued` : ''}`, wrap)));
+            return lines;
+        }
+        if (this.run.status === 'error') {
+            lines.push(fns.muted(clipToWidth(`✘ ${this.run.error ?? 'btw failed.'}`, wrap)));
+        }
+        else if (this.run.answerText === '') {
+            lines.push(fns.muted(clipToWidth('(no answer text)', wrap)));
+        }
+        else {
+            if (this.finalMarkdown === undefined) {
+                // Parses ONCE on the settled answer — never per frame, per token.
+                this.finalMarkdown = new Markdown(this.run.answerText, 1, 0, this.theme().markdown, {
+                    color: text => ansiFg(this.theme().palette.fgDefault) + text + RESET,
+                });
+            }
+            lines.push(...tailWindow(this.finalMarkdown.render(wrap), budget, wrap));
+        }
+        lines.push('');
+        lines.push(fns.subtle(clipToWidth(`Not kept in the session · /btw reopens this answer${queued > 0 ? ` · ${queued} queued` : ''}`, wrap)));
+        return lines;
+    }
+    handleInput(data) {
+        if (getKeybindings().matches(data, 'tui.select.cancel'))
+            this.onClose();
+    }
+}
+/** Last rows that fit the budget; the hidden count is named above the tail. */
+function tailWindow(rendered, budget, wrap) {
+    if (rendered.length <= budget)
+        return rendered;
+    const hidden = rendered.length - budget;
+    return [clipToWidth(`… ${hidden} lines above`, wrap), ...rendered.slice(-budget)];
+}
+/**
+ * Overlay lifecycle for btw runs: `open(run)` shows/swaps the framed panel
+ * bound to that run state; Esc and cancelAll close it through restoreFocus.
+ * Two-step wiring — construct first, `attach(controller)` once it exists
+ * (the panel needs the controller for the queued count; the controller needs
+ * these callbacks at construction).
+ */
+export class BtwOverlayWire {
+    tui;
+    theme;
+    restoreFocus;
+    host;
+    controller;
+    constructor(deps) {
+        this.tui = deps.tui;
+        this.theme = deps.theme;
+        this.restoreFocus = deps.restoreFocus;
+    }
+    attach(controller) {
+        this.controller = controller;
+    }
+    /** Called by the controller for every launched or reviewed run. */
+    open(run) {
+        const controller = this.controller;
+        if (controller === undefined)
+            return;
+        // A failed PanelHost.open releases the keyboard exactly like a normal
+        // close (PanelHost calls onError first); the run itself is unaffected.
+        const close = () => {
+            this.host?.close();
+            this.host = undefined;
+            controller.setOverlayOpen(false);
+            this.restoreFocus();
+        };
+        this.host?.close();
+        this.host = new PanelHost(this.tui, this.theme(), close);
+        controller.setOverlayOpen(true);
+        this.host.open(new BtwOverlayPanel(run, controller, this.theme, close), '70%', '80%');
+    }
+    /** Called by cancelAll — the overlay's run is gone either way. */
+    requestClose() {
+        if (this.host !== undefined) {
+            this.host.close();
+            this.host = undefined;
+            this.controller?.setOverlayOpen(false);
+            this.restoreFocus();
+        }
+    }
+}
+//# sourceMappingURL=btw-overlay.js.map

package/lib/btw-overlay.js.map

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