codsh-bundle 0.4.0 → 0.6.0

package/lib/types/clipboard-image.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Reading an image off the system clipboard.
+ *
+ * An image never arrives through the terminal: bracketed paste is text by
+ * construction, and a screenshot sitting on the clipboard has no byte channel
+ * into stdin at all. So — exactly as Claude Code does — Ctrl+V asks the
+ * platform for the clipboard's image directly: `osascript` on macOS,
+ * `wl-paste`/`xclip` on Linux, PowerShell on Windows. A machine without the
+ * helper, or a clipboard holding text, reads as "no image" rather than an
+ * error, the same silent tolerance the clipboard WRITE path has.
+ * @module codsh-bundle/src/clipboard-image
+ */
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment/types';
+/** An image read off the clipboard, plus what the flash line wants to say. */
+export interface ClipboardImage {
+    /** The raw bytes. */
+    data: Buffer;
+    /** The type the bytes actually are, sniffed rather than trusted. */
+    mediaType: ImageMediaType;
+    /** Pixel width, when the header could be read. */
+    width?: number;
+    /** Pixel height, when the header could be read. */
+    height?: number;
+}
+/**
+ * What image type these bytes are, from their magic numbers.
+ *
+ * Sniffed rather than taken from the reader's word: the store verifies the
+ * declared type against the decoded bytes and refuses a mismatch, so lying
+ * here would only defer the failure to a worse moment.
+ * @param data - the bytes.
+ * @returns the media type, or undefined for anything that is not an image.
+ */
+export declare function sniffImageType(data: Buffer): ImageMediaType | undefined;
+/**
+ * The image on the system clipboard, or undefined when it holds none.
+ *
+ * `CODSH_CLIPBOARD_IMAGE_CMD` overrides the platform reader with a shell
+ * command whose stdout is the image bytes — the seam the tests use, exactly
+ * as `CODSH_CLIPBOARD=osc52` keeps the write path off the real clipboard.
+ * @param env - the environment, for the override and the display probes.
+ * @returns the image with its sniffed type and dimensions, or undefined.
+ */
+export declare function readClipboardImage(env: Record<string, string | undefined>): Promise<ClipboardImage | undefined>;

package/lib/types/console.d.ts

@@ -14,6 +14,7 @@
  * same code path as a person typing.
  * @module codsh-bundle/src/console
  */
+import type { HoverBlock } from './screen.ts';
 import type { Key } from './keys.ts';
 /** The output stream this surface writes to. */
 export interface OutputStream extends NodeJS.WritableStream {
@@ -145,8 +146,10 @@ export declare class TerminalConsole {
      * what lets the transcript scroll under a prompt that does not move. Off one
      * it is written straight out, because a pipe's reader wants exactly that.
      * @param line - the line, without its terminator.
+     * @param rule - a styled left rule to draw down the line, `''` for none. Off
+     *   a terminal it is dropped: a pipe's reader wants the text, not the frame.
      */
-    write(line: string): void;
+    write(line: string, rule?: string): void;
     /**
      * Replace the rows pinned below the transcript.
      *
@@ -166,8 +169,11 @@ export declare class TerminalConsole {
      * with, and scripts want the digest.
      * @param summary - the collapsed lines.
      * @param full - the expanded lines.
+     * @param rule - a styled left rule for the whole block, `''` for none.
+     * @param label - what the block is, for the readout naming what the pointer
+     * is over.
      */
-    appendFold(summary: readonly string[], full: readonly string[]): void;
+    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string): void;
     /**
      * Swap every collapsible block between summary and full form.
      * @returns false when there is nothing to toggle.
@@ -184,6 +190,14 @@ export declare class TerminalConsole {
      * @param column - terminal column, 1-based.
      */
     mouseDrag(row: number, column: number): void;
+    /**
+     * Note where the pointer is resting, nothing held down.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     * @returns the block now under the pointer when it changed, undefined
+     * otherwise.
+     */
+    mouseMove(row: number, column: number): HoverBlock | undefined;
     /**
      * Finish the mouse selection.
      * @returns the selected text, or undefined for a bare click.
@@ -208,8 +222,10 @@ export declare class TerminalConsole {
      * summary would subtract from it.
      * @param count - how many trailing lines the block owns.
      * @param summary - the collapsed lines, already styled.
+     * @param label - what the block is, for the readout naming what the pointer
+     * is over.
      */
-    foldRecent(count: number, summary: readonly string[]): void;
+    foldRecent(count: number, summary: readonly string[], label?: string): void;
     toggleFolds(): boolean;
     /** Return every block to its summary. */
     collapseFolds(): void;

package/lib/types/keys.d.ts

@@ -58,6 +58,8 @@ export type Key = {
     kind: 'clear-screen';
 } | {
     kind: 'expand-output';
+} | {
+    kind: 'toggle-todos';
 } | {
     kind: 'page';
     direction: -1 | 1;
@@ -69,6 +71,8 @@ export type Key = {
 } | {
     kind: 'paste';
     text: string;
+} | {
+    kind: 'paste-image';
 } | {
     kind: 'mouse-down';
     row: number;
@@ -77,6 +81,10 @@ export type Key = {
     kind: 'mouse-drag';
     row: number;
     column: number;
+} | {
+    kind: 'mouse-move';
+    row: number;
+    column: number;
 } | {
     kind: 'mouse-up';
     row: number;

package/lib/types/prompt.d.ts

@@ -8,10 +8,13 @@
  * pipe and draws nothing. Callers ask for the next submission either way.
  * @module codsh-bundle/src/prompt
  */
+import type { EncodedImageAttachment } from '@deepseek-ai/dsh-attachment/types';
+import type { ClipboardImage } from './clipboard-image.ts';
 import type { TerminalConsole } from './console.ts';
 import type { EditorSources } from './editor.ts';
 import type { SelectOutcome, SelectSpec } from './selector.ts';
 import type { Theme } from './theme.ts';
+import type { TodoList } from './todos.ts';
 /** What the prompt reports to its owner. */
 export interface PromptHandlers {
     /** Ctrl-C: stop the work, or leave. */
@@ -24,6 +27,27 @@ export interface PromptHandlers {
     shiftTab?(): void;
     /** Ctrl-O: show the last clipped tool output in full. */
     expandOutput?(): void;
+    /**
+     * Ctrl-V: the system clipboard's image, or undefined for none.
+     *
+     * Injected rather than imported so the pure-module tests can hand the
+     * prompt a fixture instead of a machine's clipboard.
+     */
+    readClipboardImage?(): Promise<ClipboardImage | undefined>;
+}
+/**
+ * One pasted image awaiting its submission.
+ *
+ * The wire form the runtime admits, plus the dimensions the paste already
+ * probed — the submission pipeline says them back without re-decoding.
+ */
+export interface PendingImage {
+    /** The number the `[Image #N]` token wears, for context that names it back. */
+    id: number;
+    /** Base64 bytes and their sniffed media type. */
+    image: EncodedImageAttachment;
+    width?: number;
+    height?: number;
 }
 /** Drives the input box and answers reads and selections. */
 export declare class Prompt {
@@ -42,13 +66,31 @@ export declare class Prompt {
      * not be lost; the queue is what a line reader provides for free.
      */
     private readonly queued;
+    /** Images pasted into the box, by the number their `[Image #N]` token wears. */
+    private readonly pendingImages;
+    /** Numbers are never reused within a session: a recalled token must not
+     * silently pick up a different image. */
+    private imageCounter;
+    /** The images belonging to the line the last read handed out. */
+    private submittedImages;
+    /** Whether a clipboard read is already in flight; a second Ctrl+V waits. */
+    private pastingImage;
     /** The working indicator shown under the box. */
     private hint;
     /** A short-lived notice that borrows the hint row, e.g. the copy toast. */
     private flash;
+    /** What the pointer is resting on, borrowing the hint row while it rests. */
+    private hover;
     private flashTimer;
     /** The always-current session facts shown as the region's last row. */
     private status;
+    /**
+     * The agent's current todo list, kept in the chrome rather than only in the
+     * transcript: the card that announced it scrolls away, this does not.
+     */
+    private todos;
+    /** Whether the todo readout shows every item or only the one in flight. */
+    private todosExpanded;
     /** The assistant line still arriving, shown above the box. */
     private streaming;
     /** Frame styling for the current mode, e.g. plan mode's accent. */
@@ -106,6 +148,14 @@ export declare class Prompt {
      * @param text - the styled row, or undefined to drop it.
      */
     setStatus(text: string | undefined): void;
+    /**
+     * Set the todo readout to the list the session now holds.
+     *
+     * Compared by content, not identity: this is pushed on every session event,
+     * and a repaint per event would flicker the chrome for nothing.
+     * @param todos - the current list, empty to drop the readout.
+     */
+    setTodos(todos: TodoList): void;
     /**
      * Set the frame accent, which is how a mode shows on the box itself.
      * @param accent - the styling, or undefined for the default frame.
@@ -119,8 +169,9 @@ export declare class Prompt {
     /**
      * Write one finished transcript line above the region.
      * @param line - the line to keep.
+     * @param rule - a styled left rule marking which block the line belongs to.
      */
-    write(line: string): void;
+    write(line: string, rule?: string): void;
     /**
      * Wait for the next submitted text.
      * @param signal - abandons the read, which an aborted tool call does.
@@ -145,6 +196,40 @@ export declare class Prompt {
      * @param key - the decoded keystroke.
      */
     private onKey;
+    /**
+     * Read the clipboard and attach its image behind an `[Image #N]` token.
+     *
+     * The read shells out and takes real time, so it runs off the key handler;
+     * a second Ctrl+V during it is dropped rather than raced. Numbers count up
+     * for the whole session — a token in a recalled line must never quietly
+     * name a different image than the one it was minted for.
+     */
+    private pasteImage;
+    /**
+     * The images a submitted line actually references, in token order.
+     *
+     * The tokens are the source of truth: a token the person deleted drops its
+     * image, a token duplicated by editing still names one attachment once.
+     * Claimed images leave the pending pool, so a token recalled from history
+     * later submits as plain text rather than resurrecting consumed bytes.
+     * @param text - the submitted line.
+     * @returns the referenced images, ready to ride the submission.
+     */
+    private claimImages;
+    /**
+     * The images belonging to the line the last read returned.
+     *
+     * A drain, in the transcript's `take*` idiom: the caller reads the line,
+     * then takes its images exactly once.
+     * @returns the images in token order, empty for a plain line.
+     */
+    takeAttachments(): PendingImage[];
+    /**
+     * The todo readout's rows: the one in flight, or the whole list once opened.
+     * @param columns - display columns available.
+     * @returns the rows, empty when no list is live.
+     */
+    private todoRows;
     /** Recompose and redraw the bottom region. */
     private render;
 }

package/lib/types/screen.d.ts

@@ -8,7 +8,7 @@
  * viewport while the input box stays where it is, at the bottom.
  *
  * Owning the viewport means doing three jobs the terminal used to do. Lines are
- * wrapped here ({@link wrapAll}), because a line that overflows would otherwise
+ * wrapped here ({@link wrapStyled}), because a line that overflows would otherwise
  * overwrite the row below. Scrolling is ours, because the terminal's scrollback
  * does not exist on the alternate screen. And every frame is painted as a
  * whole, diffed against the last one — which is what removes the class of bug
@@ -20,6 +20,15 @@ export interface ChromeCursor {
     row: number;
     column: number;
 }
+/** What the pointer is resting on, for a surface that names it. */
+export interface HoverBlock {
+    /** What the block is, e.g. `thinking`. */
+    label: string;
+    /** Lines its full form holds. */
+    lines: number;
+    /** Whether it is showing that full form now. */
+    expanded: boolean;
+}
 /** What the screen writes to and measures itself against. */
 export interface ScreenHost {
     /** Emit raw bytes to the terminal. */
@@ -34,8 +43,18 @@ export declare class Screen {
     private readonly host;
     /** Logical transcript lines, unwrapped, oldest first. */
     private logical;
+    /**
+     * The left rule each logical line carries, `''` for none.
+     *
+     * Kept beside the text rather than inside it: a rule has to repeat on every
+     * row a line wraps to, and it must never reach the clipboard — it is a mark
+     * the surface draws, not something the person wrote.
+     */
+    private rules;
     /** The same lines wrapped to the current width — what the viewport slices. */
     private physical;
+    /** Display columns the rule occupies on each physical row, for copy and hits. */
+    private ruleWidths;
     /** The bottom rows: input box, menu, indicator, status. */
     private chrome;
     private chromeCursor;
@@ -49,6 +68,18 @@ export declare class Screen {
     private selection;
     /** Collapsed blocks in the transcript, in order, with both of their forms. */
     private folds;
+    /** The block the pointer rests on, or undefined when it rests on none. */
+    private hovered;
+    /**
+     * Physical row ranges the blocks occupy, or undefined when they need
+     * measuring again.
+     *
+     * Motion arrives a report per cell crossed, and measuring a block's row from
+     * the wrapped height of everything above it is a walk over the buffer — far
+     * too much to redo per report. The walk happens once after the buffer
+     * changes instead, and every report in between is a lookup.
+     */
+    private ranges;
     /** Whether the folds currently show their full form. */
     private expanded;
     /** The last painted frame, so a repaint only touches rows that changed. */
@@ -77,7 +108,7 @@ export declare class Screen {
      * where they are, and the new rows accumulate below them.
      * @param lines - the lines to keep, already styled.
      */
-    append(lines: readonly string[]): void;
+    append(lines: readonly string[], rule?: string): void;
     /**
      * Append one collapsible block: its summary now, its full form on demand.
      *
@@ -86,8 +117,10 @@ export declare class Screen {
      * place, exactly like a details/summary element.
      * @param summary - the collapsed lines, already styled.
      * @param full - the expanded lines, already styled.
+     * @param rule - a styled left rule for the whole block, `''` for none.
+     * @param label - what the block is, for the hover readout that names it.
      */
-    appendFold(summary: readonly string[], full: readonly string[]): void;
+    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string): void;
     /**
      * Turn the last `count` appended lines into a collapsible block after the
      * fact.
@@ -98,19 +131,63 @@ export declare class Screen {
      * collapses with the rest when the conversation moves on.
      * @param count - how many trailing lines the block owns.
      * @param summary - the collapsed lines, already styled.
+     * @param label - what the block is, for the hover readout that names it.
      */
-    foldBack(count: number, summary: readonly string[]): void;
+    foldBack(count: number, summary: readonly string[], label?: string): void;
     /** Whether any collapsible block exists. */
     get hasFolds(): boolean;
     /** Whether the folds currently show their full form. */
     get foldsExpanded(): boolean;
     /**
      * Swap every fold between its summary and its full form.
+     *
+     * What the blocks show decides the direction, not what the last Ctrl+O did:
+     * clicking blocks open one at a time would otherwise leave the key pointing
+     * the wrong way, and a press that visibly does nothing reads as broken.
      * @returns false when there is nothing to toggle.
      */
     toggleFolds(): boolean;
     /** Return every fold to its summary, the way moving on reads as dismissal. */
     collapseFolds(): void;
+    /**
+     * Work the block a bare click landed on, the way a details element opens.
+     *
+     * The whole block is the target, in both forms: collapsed, the `+N lines`
+     * line is what a person aims at, and open, anywhere inside the text folds it
+     * back — hunting for a head row that has scrolled off the top is not an
+     * affordance. Selecting text inside a block is a drag, which never reaches
+     * here, so reading is unaffected.
+     * @param row - physical buffer row the press anchored on.
+     */
+    private clickFold;
+    /**
+     * Where each block sits in physical rows.
+     *
+     * Blocks are recorded in logical lines while the mouse reports physical
+     * rows, so the wrapped height of everything above a block is what bridges
+     * the two — measured under each line's own rule, which costs columns and so
+     * changes the height.
+     * @returns one range per block, in buffer order.
+     */
+    private foldRanges;
+    /**
+     * The block covering a physical row.
+     * @param row - physical buffer row, 0-based.
+     * @returns the block, or undefined when the row is not in one.
+     */
+    private foldAt;
+    /**
+     * Swap one block, leaving the reader where they were.
+     *
+     * Someone who opened a block halfway up their history did not ask to be
+     * moved to the tail: the rows above the block keep their screen positions,
+     * and the transcript grows or shrinks below them. Following the tail there
+     * is nothing to hold on to, so the frame keeps following it — which is what
+     * Ctrl+O does for every block at once.
+     * @param fold - the block to swap.
+     * @param expanded - the form to put on screen.
+     */
+    private setFold;
     /** Put every fold into one form, whatever mix of states they are in now. */
     private setFolds;
     /**
@@ -150,6 +227,19 @@ export declare class Screen {
     clearTranscript(): void;
     /** Re-wrap and repaint after the terminal changed size. */
     resize(): void;
+    /**
+     * Note where the pointer is resting, with nothing held down.
+     *
+     * A block is clickable, so it says so while the pointer is on it rather
+     * than only once it is hit. Reports arrive a cell at a time, so the frame is
+     * only touched when the block under the pointer actually changes — moving
+     * along one block, or across the chrome, costs a lookup and nothing else.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     * @returns the block under the pointer, or undefined for none — reported
+     * every time, so a caller need not track the changes itself.
+     */
+    mouseMove(row: number, column: number): HoverBlock | undefined;
     /**
      * Anchor a selection where the left button went down.
      *
@@ -170,7 +260,9 @@ export declare class Screen {
      * Finish the gesture.
      *
      * The highlight stays up — the copy already happened, and the marks show
-     * what it took — until the next click or reflow dismisses it.
+     * what it took — until the next click or reflow dismisses it. A press that
+     * never moved is not a selection but a click, and a click on a collapsible
+     * block works that one block: open it, or fold it back.
      * @returns the selected text, or undefined for a bare click.
      */
     mouseUp(): string | undefined;
@@ -191,6 +283,20 @@ export declare class Screen {
     private viewportHeight;
     /** Columns content is laid out for, one short of the width so no row wraps. */
     private contentColumns;
+    /**
+     * Wrap one logical line, repeating its rule on every row.
+     *
+     * The rule costs columns, so the text wraps inside what is left of the width;
+     * a continuation row without the rule would break the block's left edge
+     * exactly where a long line made it matter most.
+     * @param line - the styled logical line.
+     * @param rule - the styled left rule, `''` for none.
+     * @param columns - display columns available for rule and text together.
+     * @returns the physical rows, rule included.
+     */
+    private wrapLine;
+    /** Re-wrap every kept line at the current width, rules and all. */
+    private wrapBuffer;
     /** Re-wrap every kept line at the current width. */
     private rewrap;
     /**

package/lib/types/ship.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `/ship` prompt: a canned workflow that takes a one-sentence requirement
+ * from idea to shipped, verified code — a research-grounded interview, a
+ * confirmed spec (gate 1), an approved plan (gate 2), then autonomous landing
+ * until the spec's acceptance criteria pass.
+ *
+ * The spec FILE is the workflow's memory, not the conversation: the approved
+ * plan is written into it, its Status line names the phase, its checkboxes
+ * are the progress, and a bare /ship offers to resume whatever it finds
+ * unfinished. Conversations get interrupted, compacted, and cleared; the file
+ * survives all three, which is what makes the landing reliable rather than
+ * merely well-intentioned.
+ */
+/** The `/ship` prompt body; `$ARGUMENTS` is the typed one-sentence requirement. */
+export declare const SHIP_PROMPT = "Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:\n\n<idea>\n$ARGUMENTS\n</idea>\n\nIf the idea between the <idea> tags is empty, that is not an error. First look for unfinished work: scan the repository's spec directory (docs/specs/, or the repo's own design-document convention) for a spec whose Status line is not `shipped` \u2014 a bare /ship most likely means \"carry on\", so offer through ask_user_question to resume that spec from the phase its Status names, with everything below applying from that phase onward. Only when there is nothing to resume, ask for the one-sentence requirement with ask_user_question and use the answer as the idea. Images accompanying the command \u2014 [Image #N] tokens, <pasted-image> context, attached image blocks \u2014 are part of the requirement: a mockup or a screenshot is requirements material, so read it and cite what it shows in the interview.\n\nPhase 1 \u2014 grounded interview. Research before you ask: read the repository layout, the docs, and the code paths the idea touches, so every question is informed by what actually exists. Then interrogate the idea with ask_user_question, one focused question per call, never a batch. Cover, as far as they are genuinely open: who this is for and what success looks like, scope and explicit non-goals, constraints (compatibility, performance, security, dependencies), edge cases and failure behavior, and how the result should be verified. Prefer concrete options grounded in what you found over open-ended prompts. Do not ask what inspection can answer \u2014 where code lives or how current behavior works is yours to find out. Stop when answers stop changing the design; do not pad the interview to look thorough.\n\nPhase 2 \u2014 the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion names the exact command that proves it and the output that counts as passing \u2014 the final phase runs those commands verbatim, so a criterion without a command is not finished. Give the file a `Status:` line (interviewing, confirmed, planned, landing, shipped) and keep it current at every phase change: it is what lets an interrupted /ship resume instead of starting over. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.\n\nPhase 3 \u2014 the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Once approved, write the plan into the spec file as a `## Plan` section with one checkbox per milestone \u2014 an approved plan lives on disk, not in a conversation that can be compacted or lost. Then, still before any implementation code, establish the ground: check the working tree is clean (uncommitted unrelated changes are the user's to decide about \u2014 ask), and run the plan's proof commands once, recording the baseline in the spec. A baseline that is already red changes what \"green\" will mean, so surface it here rather than discovering it under your own diff. Write no implementation code before this gate passes, and do not use todo_write before it either \u2014 it tracks landing, not the interview.\n\nPhase 4 \u2014 landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Either way the spec file \u2014 not this conversation \u2014 is the working memory: re-read it before starting each milestone, tick the milestone's checkbox and update Status as you go, and commit after each milestone turns green \u2014 small commits are the progress that survives a crash and the history a reviewer can walk. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, fix until green, then commit before moving on. If it is larger \u2014 four or more substantially independent milestones, or work you expect to exceed what one session can hold \u2014 the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the single source of truth, instructs each round to read the spec from disk (plan, checkboxes, baseline), pick the first unchecked milestone, implement and test it, then commit and tick its checkbox, and defines completion as every acceptance criterion in the spec passing. Bound the loop: budget about three rounds per milestone, and instruct it to stop and report rather than continue past two consecutive rounds that tick nothing.\n\nPhase 5 \u2014 done means verified. The workflow ends only when every acceptance criterion passes with you actually running its named command and reading the real output. After a Ralph loop returns, run every proof command again yourself \u2014 the loop's word is a report, not a verification. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Set Status to shipped only after that final run, and close with an honest report listing each criterion, the command that proved it, and what it printed \u2014 plus anything left open.\n\nIf the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.";

package/lib/types/todos.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The todo readout: the pinned row that keeps the agent's list in view after
+ * the write that produced it has scrolled away, and the full list that row
+ * expands into.
+ *
+ * One renderer serves all three places the list shows — the transcript card,
+ * the pinned row, and `/todos` — so the glyphs and counts cannot drift apart.
+ * Nothing is tracked here: every figure comes from the `todos` projection, so a
+ * resumed session reports the list it left off with.
+ * @module codsh-bundle/src/todos
+ */
+import type { TodoItem } from '@deepseek-ai/dsh-session';
+import type { Theme } from './theme.ts';
+/** The list as the projection holds it: whole-value, latest write wins. */
+export type TodoList = readonly TodoItem[];
+/** How the full list may be shortened for a surface that cannot scroll. */
+export interface TodoReportOptions {
+    /** A trailing note for the header, e.g. the key that collapses the list. */
+    hint?: string | undefined;
+    /** Most items to print; the rest are counted on one tail line. */
+    limit?: number | undefined;
+}
+/**
+ * Render the pinned row: one line naming the work in flight and the progress
+ * around it.
+ *
+ * This row is the whole point of reading from a projection rather than from the
+ * write event: the card that announced the list scrolls away, the row does not,
+ * so the list stays answerable at a glance for the rest of the session.
+ * @param todos - the current list.
+ * @param theme - styling for the segments.
+ * @param columns - display columns available; a longer row is cut, never wrapped.
+ * @param hint - a trailing note, e.g. the key that expands the list.
+ * @returns the row, or undefined when there is no list to report.
+ */
+export declare function todoRow(todos: TodoList, theme: Theme, columns: number, hint?: string): string | undefined;
+/**
+ * Render the whole list: the header, then every item under it.
+ *
+ * A surface that cannot scroll passes `limit`, and the items past it are
+ * counted rather than dropped in silence — a list that looks complete but is
+ * not is worse than an honest tail.
+ * @param todos - the current list.
+ * @param theme - styling for the marks and text.
+ * @param columns - display columns available; longer lines are cut.
+ * @param options - header note and item cap.
+ * @returns the lines, empty when there is no list.
+ */
+export declare function todoReport(todos: TodoList, theme: Theme, columns: number, options?: TodoReportOptions): string[];

package/lib/types/transcript.d.ts

@@ -37,6 +37,69 @@ export interface TranscriptOptions {
     /** Session workspace, stripped from absolute paths so cards stay short. */
     cwd: string;
 }
+/**
+ * The left rules the transcript draws down a block's edge, one per kind.
+ *
+ * A rule is how a segment shows where it starts and ends without a frame or a
+ * background fill: the references converge on a left border (Claude Code's
+ * `borderLeft`, opencode's `border: ["left"]`), and a border costs one column
+ * where a fill costs the terminal's own background — which is the theme's to
+ * decide, not this surface's (ADR-0001).
+ *
+ * The person's own words get the heavy mark; a tool block gets the light one,
+ * in the error colour when the call failed. What a person actually reads — an
+ * answer, a thinking summary — stays flush, so the rules mark the machinery
+ * around it rather than everything equally.
+ * @param theme - styling for the marks.
+ * @returns the rule per block kind.
+ */
+export declare function blockRules(theme: Theme): {
+    user: string;
+    tool: string;
+    error: string;
+};
+/**
+ * What the two nameless block kinds are called when a readout names them.
+ *
+ * A tool block answers with its card's own title, which is already on screen;
+ * thinking and an answer have no title of their own, so these are theirs.
+ */
+export declare const FOLD_LABELS: {
+    readonly thinking: "thinking";
+    readonly answer: "answer";
+};
+/** A finished answer longer than this many rendered lines becomes a fold. */
+export declare const ANSWER_FOLD_LINES = 24;
+/** How many of its head lines a collapsed answer keeps visible. */
+export declare const ANSWER_HEAD_LINES = 8;
+/**
+ * The collapsed form of a finished answer, when it is long enough to fold.
+ *
+ * Shared by the live turn and by replay: a resumed session must offer the same
+ * summary the turn itself left behind, or history would read as a different
+ * conversation from the one that happened.
+ * @param lines - the answer's rendered lines, without its trailing blank.
+ * @param theme - styling for the count line.
+ * @returns the collapsed lines, or undefined when the answer is short enough
+ *   to stand as it is.
+ */
+export declare function answerSummary(lines: readonly string[], theme: Theme): string[] | undefined;
+/**
+ * The two forms of a thinking block: one dim line, and the deliberation behind
+ * it.
+ *
+ * Pages of reasoning would bury the conversation, so the transcript keeps the
+ * summary and hands the rest to Ctrl+O — live and on replay alike.
+ * @param lines - the rendered thinking lines, already styled.
+ * @param theme - styling for the header.
+ * @param seconds - how long the thinking took, when the surface timed it; a
+ *   replayed log carries no clock, so the header simply says it thought.
+ * @returns the collapsed and expanded forms.
+ */
+export declare function thinkingFold(lines: readonly string[], theme: Theme, seconds?: number): {
+    summary: string[];
+    full: string[];
+};
 /** Renders one session's appended events as terminal lines. */
 export declare class Transcript {
     private readonly options;
@@ -44,6 +107,10 @@ export declare class Transcript {
     private readonly calls;
     /** The full form of the event just rendered, when its body was collapsed. */
     private fold;
+    /** What the block {@link render} just returned is, for a hover readout. */
+    private label;
+    /** The left rule the block {@link render} just returned belongs to. */
+    private rule;
     constructor(options: TranscriptOptions, presenters: ToolPresenters);
     /**
      * Shorten an absolute path inside the workspace to a workspace-relative one.
@@ -96,6 +163,23 @@ export declare class Transcript {
      * @returns the full lines, or undefined when nothing was collapsed.
      */
     takeFold(): string[] | undefined;
+    /**
+     * What the block {@link takeFold} just described is called.
+     *
+     * The card's title, so the readout that names what the pointer rests on says
+     * the same thing the block's own head line says.
+     * @returns the label, or `''` when the block has no name of its own.
+     */
+    takeLabel(): string;
+    /**
+     * The left rule for the block {@link render} just returned, `''` when the
+     * block stands flush.
+     *
+     * Paired with the lines rather than baked into them: the rule repeats on
+     * every row the block wraps to, which only the buffer that wraps them knows.
+     * @returns the styled rule, or `''`.
+     */
+    takeRule(): string;
     /**
      * Render one completed call's status suffix and body from its declared view.
      * @param view - the result view, absent when no presenter answered.