@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/trajectory/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Trajectory projection — the data contract shared by the adapter-side fold
+ * and the UI-side scene (issue #80 evolution).
+ *
+ * Two rules shape every type here, and both exist because the projection
+ * feeds a terminal that repaints on a keystroke:
+ *
+ * 1. **Nodes carry references, never derived copies.** A node's `detail` is
+ *    the raw event string exactly as the log holds it — JS strings are
+ *    immutable and shared, so keeping one costs a pointer, while flattening
+ *    or truncating it at fold time would allocate a second copy of every
+ *    tool argument in the session AND bake in a width the terminal has not
+ *    chosen yet. The view calls {@link previewText} on the ~15 rows it is
+ *    about to paint; everything else stays untouched.
+ * 2. **Full content is never held at all.** `seq`/`endSeq` address the
+ *    owning events, and the inspector re-reads them from the session's own
+ *    immutable snapshot on demand. The projection is an index, not a mirror.
+ */
+/** The row kinds a trajectory node can carry. */
+export type TrajKind = 'turn' | 'step' | 'user' | 'assistant' | 'thinking' | 'tool' | 'subtool' | 'retry' | 'approval' | 'compaction' | 'system' | 'context' | 'todo';
+/** Bracket outcome; open brackets stay `running` until their closer lands. */
+export type TrajStatus = 'running' | 'ok' | 'error';
+/** Per-message token accounting, present only when the adapter reported it. */
+export interface TrajTokens {
+    readonly input: number;
+    readonly output: number;
+    readonly think: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+/**
+ * A run of consecutive same-name calls folded into one ledger row.
+ *
+ * The fold replaces the run with a *synthetic* node that carries this burst;
+ * `members` holds the original nodes, still live and still the objects the
+ * bracket-pairing maps mutate when their closers land. Totals are therefore
+ * derived on read ({@link burstDurationMs}, {@link burstErrors}) rather than
+ * maintained incrementally — a member closing after the fold needs no
+ * bookkeeping, and there is no head/member self-reference to trip a walker.
+ */
+export interface TrajBurst {
+    /** Tool name shared by every member. */
+    readonly name: string;
+    /** Every folded call, in log order. */
+    readonly members: readonly TrajNode[];
+}
+/** Summed own-duration of the burst members whose brackets have closed. */
+export declare function burstDurationMs(burst: TrajBurst): number;
+/** Number of burst members that failed. */
+export declare function burstErrors(burst: TrajBurst): number;
+/** True while any burst member is still running. */
+export declare function burstRunning(burst: TrajBurst): boolean;
+/**
+ * One row of the trajectory ledger.
+ *
+ * Fields filled when the opening event is consumed are `readonly`; fields a
+ * later closing event completes (`endSeq`, `durationMs`, `status`, …) are
+ * mutable, matching the fold's in-place bracket pairing.
+ */
+export interface TrajNode {
+    /** Seq of the opening event — the inspector's lookup key. */
+    readonly seq: number;
+    /** Epoch-ms timestamp of the opening event. */
+    readonly time: number;
+    readonly kind: TrajKind;
+    /** Owning turn; 0 for events that precede the first `turn/start`. */
+    readonly turn: number;
+    /** Owning step, when the event carried one. */
+    readonly step?: number;
+    /**
+     * Short, already-bounded label: a tool name, `turn 3`, a retry code. Safe
+     * to render as-is — it never holds user or model prose.
+     */
+    readonly label: string;
+    /** Raw one-line-preview source (arguments, message text). Never flattened. */
+    readonly detail?: string;
+    /** Raw result-preview source rendered after the `→`. Never flattened. */
+    outcome?: string;
+    /** Seq of the closing event, once it lands. */
+    endSeq?: number;
+    /** Own wall-clock duration, filled when the bracket closes. */
+    durationMs?: number;
+    status?: TrajStatus;
+    /** Message-level token accounting (assistant rows only). */
+    tokens?: TrajTokens;
+    /** Tool-call identity, used for `tool/call` ↔ `tool/result` pairing. */
+    readonly callId?: string;
+    /** Code-runner sub-call identity (`tool/code-dispatch*` pre-0.1.5, `tool/ptc-dispatch*` since). */
+    readonly subCallId?: string;
+    /** Failure identity when `status === 'error'` (e.g. `RATE_LIMIT`). */
+    errorCode?: string;
+    /** Attempt count on a `retry` row (one row per retry sequence). */
+    attempts?: number;
+    /**
+     * Set on the synthetic node that stands in for a folded run of same-name
+     * calls. The node itself is not one of the members.
+     */
+    readonly burst?: TrajBurst;
+    /**
+     * True while this node belongs to seed history — events replayed from a
+     * resumed/forked log rather than produced by this lifecycle. The scene
+     * dims them so a resumed session's inherited past is visually distinct.
+     * Mutable because only the LAST `session/end-seed` bounds the inherited
+     * range, so a re-seeded log re-marks the rows folded before it.
+     */
+    seed?: boolean;
+}
+/** Minimum run length that folds into a {@link TrajBurst}. */
+export declare const BURST_MIN = 3;
+/** Timeline channel a node contributes to in the wave band. */
+export type WaveChannel = 'input' | 'model' | 'tool';
+/** One column of the wave band. */
+export interface WaveBucket {
+    /** Total weight in this column, before normalization. */
+    weight: number;
+    /**
+     * Rows in this column, regardless of cost.
+     *
+     * Separate from `weight` because structural rows (turn/step) deliberately
+     * contribute no cost — their span is their children's — yet a column holding
+     * one is NOT empty. Conflating the two rendered such columns as gaps, which
+     * at status-line scale made the strip look broken rather than quiet.
+     */
+    count: number;
+    /** Per-channel weights; the dominant one drives the column's color. */
+    readonly channels: {
+        input: number;
+        model: number;
+        tool: number;
+    };
+    /** Any member failed. */
+    error: boolean;
+    /** Any member is an `llm/retry`. */
+    retry: boolean;
+    /** Any member is still running. */
+    running: boolean;
+    /** Ledger index of the first node in this column, for click-to-seek. */
+    firstIndex: number;
+}
+/** The wave band projected at one specific column count. */
+export interface WaveBand {
+    readonly buckets: readonly WaveBucket[];
+    /**
+     * Weight that maps to the tallest glyph — the 95th percentile of non-empty
+     * columns, not the maximum. Columns above it clamp to a full block.
+     */
+    readonly peak: number;
+    /**
+     * Lowest NON-EMPTY bucket weight. Glyph levels are normalized between this
+     * and {@link peak} rather than from zero: a typical bucket already sits near
+     * half of `log1p(peak)`, so a zero-based scale leaves the lower half of the
+     * glyph ramp permanently unused and the band reads as a flat smear.
+     */
+    readonly floor: number;
+    /** Turn-boundary markers as `[turn, bucketIndex]`, for the ruler row. */
+    readonly turns: readonly (readonly [number, number])[];
+}
+/** How the wave band maps nodes onto columns. */
+export type WaveProjection = 
+/** One column per equal slice of the node index range. */
+'sequence'
+/** Columns proportional to wall-clock, idle gaps included. */
+ | 'time'
+/** Columns proportional to wall-clock with idle gaps compressed out. */
+ | 'compressed';
+/** Ordered cycle for the `m` key. */
+export declare const WAVE_PROJECTIONS: readonly WaveProjection[];
+/** One row of the hotspot view: a named cost bucket. */
+export interface HotspotRow {
+    readonly label: string;
+    /** Summed wall-clock across every member. */
+    readonly totalMs: number;
+    readonly count: number;
+    /** Summed tokens where the group carries accounting. */
+    readonly tokens: number;
+    /** True for rows that represent a failure cost (retry backoff). */
+    readonly error?: boolean;
+    /** Ledger index of the group's first member, for `Enter` to seek. */
+    readonly firstIndex: number;
+}
+/** The hotspot view's three sections plus the session totals. */
+export interface TrajAggregate {
+    /** Per tool name, descending by `totalMs`. */
+    readonly tools: readonly HotspotRow[];
+    /** Model-side cost: decode, time-to-first-token, retry backoff. */
+    readonly model: readonly HotspotRow[];
+    /** Per turn, descending by `totalMs`. */
+    readonly turns: readonly HotspotRow[];
+    readonly totals: TrajTotals;
+}
+/** Session-level counters shown in the scene header and the status badge. */
+export interface TrajTotals {
+    readonly turns: number;
+    readonly steps: number;
+    /** Ledger rows, after burst folding. */
+    readonly rows: number;
+    /** Tool + subtool call count, before burst folding. */
+    readonly calls: number;
+    readonly errors: number;
+    readonly retries: number;
+    /** Wall-clock from the first to the last event. */
+    readonly spanMs: number;
+    /** Summed tool own-duration. */
+    readonly toolMs: number;
+    /** Summed assistant decode duration (first token → completion). */
+    readonly decodeMs: number;
+    /** Summed time-to-first-token. */
+    readonly ttftMs: number;
+    /** Number of steps that contributed a TTFT sample. */
+    readonly ttftSamples: number;
+    /** Summed retry backoff. */
+    readonly retryMs: number;
+    readonly tokens: TrajTokens;
+}
+/** Hotspot sort keys, cycled by the `t` key. */
+export type HotspotSort = 'duration' | 'count' | 'tokens';
+/** Ordered cycle for the `t` key. */
+export declare const HOTSPOT_SORTS: readonly HotspotSort[];
+/**
+ * Collapse whitespace and cap a raw detail string for one-line display.
+ *
+ * The scan is bounded: only the first `limit * 4 + 16` code units are ever
+ * examined, so a 200 KB tool result costs the same as a 200-byte one. This
+ * is the ONLY place raw detail becomes a display string, and it runs per
+ * painted row, never per stored node.
+ *
+ * @param raw - Untrusted message, argument, or result text.
+ * @param limit - Maximum characters to return, excluding the ellipsis.
+ * @returns Flattened preview, suffixed with `…` when the source was longer.
+ */
+export declare function previewText(raw: string, limit: number): string;
+//# sourceMappingURL=types.d.ts.map

package/lib/types/dsh-adapter/trajectory/types.d.ts.map

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

package/lib/types/dsh-adapter/trajectory/types.js

@@ -0,0 +1,70 @@
+/**
+ * Trajectory projection — the data contract shared by the adapter-side fold
+ * and the UI-side scene (issue #80 evolution).
+ *
+ * Two rules shape every type here, and both exist because the projection
+ * feeds a terminal that repaints on a keystroke:
+ *
+ * 1. **Nodes carry references, never derived copies.** A node's `detail` is
+ *    the raw event string exactly as the log holds it — JS strings are
+ *    immutable and shared, so keeping one costs a pointer, while flattening
+ *    or truncating it at fold time would allocate a second copy of every
+ *    tool argument in the session AND bake in a width the terminal has not
+ *    chosen yet. The view calls {@link previewText} on the ~15 rows it is
+ *    about to paint; everything else stays untouched.
+ * 2. **Full content is never held at all.** `seq`/`endSeq` address the
+ *    owning events, and the inspector re-reads them from the session's own
+ *    immutable snapshot on demand. The projection is an index, not a mirror.
+ */
+/** Summed own-duration of the burst members whose brackets have closed. */
+export function burstDurationMs(burst) {
+    let total = 0;
+    for (const member of burst.members)
+        total += member.durationMs ?? 0;
+    return total;
+}
+/** Number of burst members that failed. */
+export function burstErrors(burst) {
+    let count = 0;
+    for (const member of burst.members)
+        if (member.status === 'error')
+            count += 1;
+    return count;
+}
+/** True while any burst member is still running. */
+export function burstRunning(burst) {
+    return burst.members.some(member => member.status === 'running');
+}
+/** Minimum run length that folds into a {@link TrajBurst}. */
+export const BURST_MIN = 3;
+/** Ordered cycle for the `m` key. */
+export const WAVE_PROJECTIONS = ['sequence', 'time', 'compressed'];
+/** Ordered cycle for the `t` key. */
+export const HOTSPOT_SORTS = ['duration', 'count', 'tokens'];
+/**
+ * Collapse whitespace and cap a raw detail string for one-line display.
+ *
+ * The scan is bounded: only the first `limit * 4 + 16` code units are ever
+ * examined, so a 200 KB tool result costs the same as a 200-byte one. This
+ * is the ONLY place raw detail becomes a display string, and it runs per
+ * painted row, never per stored node.
+ *
+ * @param raw - Untrusted message, argument, or result text.
+ * @param limit - Maximum characters to return, excluding the ellipsis.
+ * @returns Flattened preview, suffixed with `…` when the source was longer.
+ */
+export function previewText(raw, limit) {
+    if (limit <= 0)
+        return '';
+    // Bounded window: enough slack that collapsing runs of whitespace still
+    // yields `limit` visible characters in the worst realistic case.
+    const window = raw.slice(0, limit * 4 + 16);
+    const flat = window.replace(/\s+/g, ' ').trim();
+    if (flat.length <= limit) {
+        // Only authoritative when the window covered the whole source; a source
+        // longer than the window is still truncated even if the window collapsed
+        // below the limit.
+        return raw.length <= window.length ? flat : `${flat}…`;
+    }
+    return `${flat.slice(0, limit)}…`;
+}

package/lib/types/dsh-adapter/trajectory/wave.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Wave band projection — the whole session compressed onto one row of glyphs.
+ *
+ * The band answers, without reading a single word: how long was this session,
+ * where was it dense, where did it idle, where did it fail, and where am I
+ * looking right now. It is the trajectory's coarse navigation axis — a few
+ * keypresses cross a session that would take dozens of scrolls in the ledger.
+ *
+ * ## Three projections, one shape
+ *
+ * `sequence` gives every row equal width — best for scanning *what* happened.
+ * `time` maps real wall-clock, so a five-minute tool call is visibly five
+ * minutes and idle gaps are visibly idle. `compressed` keeps wall-clock
+ * proportions but caps each inter-row gap, which is what you want on a session
+ * that sat idle overnight between two bursts of work.
+ *
+ * ## Purity and cost
+ *
+ * {@link projectWave} is pure and O(nodes + columns). It is recomputed only
+ * when the node count, the column count, or the projection changes — the
+ * caller memoizes on exactly those three, which is why no cache lives here.
+ */
+import { type TrajNode, type WaveBand, type WaveBucket, type WaveChannel, type WaveProjection } from './types.js';
+/** Which band channel a row contributes its weight to. */
+export declare function channelOf(kind: TrajNode['kind']): WaveChannel;
+/**
+ * Project the ledger onto a fixed number of columns.
+ *
+ * @param nodes - The folded ledger, in log order.
+ * @param columns - Column count; normally the band's rendered width.
+ * @param projection - Horizontal domain (see the module comment).
+ * @returns The band, with `peak` for glyph scaling and turn markers for the
+ *   ruler row. An empty ledger yields zero buckets and `peak` 0.
+ */
+export declare function projectWave(nodes: readonly TrajNode[], columns: number, projection?: WaveProjection): WaveBand;
+/** The dominant channel of a column, or `undefined` for an empty column. */
+export declare function dominantChannel(bucket: WaveBucket): WaveChannel | undefined;
+/**
+ * Map a ledger index back to its column — the inverse used to draw the
+ * viewport bracket under the band.
+ *
+ * @returns Column index, clamped into range; 0 for an empty band.
+ */
+export declare function columnOfIndex(band: WaveBand, ledgerIndex: number): number;
+//# sourceMappingURL=wave.d.ts.map

package/lib/types/dsh-adapter/trajectory/wave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/trajectory/wave.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAe,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAS9H,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,WAAW,CAe7D;AAiED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,cAA2B,GACtC,QAAQ,CA6DV;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAM3E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CASzE"}

package/lib/types/dsh-adapter/trajectory/wave.js

@@ -0,0 +1,210 @@
+/**
+ * Wave band projection — the whole session compressed onto one row of glyphs.
+ *
+ * The band answers, without reading a single word: how long was this session,
+ * where was it dense, where did it idle, where did it fail, and where am I
+ * looking right now. It is the trajectory's coarse navigation axis — a few
+ * keypresses cross a session that would take dozens of scrolls in the ledger.
+ *
+ * ## Three projections, one shape
+ *
+ * `sequence` gives every row equal width — best for scanning *what* happened.
+ * `time` maps real wall-clock, so a five-minute tool call is visibly five
+ * minutes and idle gaps are visibly idle. `compressed` keeps wall-clock
+ * proportions but caps each inter-row gap, which is what you want on a session
+ * that sat idle overnight between two bursts of work.
+ *
+ * ## Purity and cost
+ *
+ * {@link projectWave} is pure and O(nodes + columns). It is recomputed only
+ * when the node count, the column count, or the projection changes — the
+ * caller memoizes on exactly those three, which is why no cache lives here.
+ */
+import { burstErrors } from './types.js';
+/**
+ * Longest inter-row gap the `compressed` projection preserves. Beyond this a
+ * gap contributes a fixed width, so an overnight pause reads as "a pause"
+ * instead of flattening the entire session into one column.
+ */
+const GAP_CAP_MS = 2_000;
+/** Which band channel a row contributes its weight to. */
+export function channelOf(kind) {
+    switch (kind) {
+        case 'user':
+        case 'context':
+        case 'todo':
+            return 'input';
+        case 'tool':
+        case 'subtool':
+        case 'approval':
+        case 'compaction':
+            return 'tool';
+        default:
+            // turn / step / assistant / thinking / retry / system
+            return 'model';
+    }
+}
+/**
+ * Nominal cost of a row that brackets no wall-clock (a message, a mode
+ * switch). Without it a stretch of pure conversation would read as idle.
+ */
+const NOMINAL_MS = 120;
+/**
+ * Cost one row contributes to its column, in milliseconds.
+ *
+ * **Height is time, not tally.** An earlier version summed one unit per row,
+ * which made the band perfectly flat in the sequence projection — buckets hold
+ * equal numbers of rows there *by construction*, so the only thing the height
+ * could express was the constant it was built from. Summing own-duration
+ * instead gives every projection a real reading: along the event axis, tall
+ * means "these steps were expensive"; along the wall-clock axis, tall means
+ * "this stretch was busy" (occupancy), and idle gaps genuinely flatten.
+ *
+ * Structural rows (turn/step) contribute nothing: their duration is the sum of
+ * their children's, and counting both would double every span.
+ */
+function costOf(node) {
+    if (node.kind === 'turn' || node.kind === 'step')
+        return 0;
+    if (node.burst !== undefined) {
+        let total = 0;
+        for (const member of node.burst.members)
+            total += (member.durationMs ?? 0) + NOMINAL_MS;
+        return total;
+    }
+    return (node.durationMs ?? 0) + NOMINAL_MS;
+}
+/** Positions of each row along the projection's horizontal domain, in [0, 1]. */
+function positions(nodes, projection) {
+    const count = nodes.length;
+    if (count === 0)
+        return [];
+    if (count === 1)
+        return [0];
+    /** Equal spacing — the fallback whenever a time domain would divide by zero. */
+    const even = () => Array.from({ length: count }, (_, index) => index / (count - 1));
+    if (projection === 'sequence')
+        return even();
+    if (projection === 'time') {
+        const first = nodes[0].time;
+        const span = nodes[count - 1].time - first;
+        // A zero span (every row inside the same millisecond) has no meaningful
+        // time axis; fall back to equal spacing rather than dividing by zero.
+        if (span <= 0)
+            return even();
+        return Array.from({ length: count }, (_, index) => (nodes[index].time - first) / span);
+    }
+    // compressed: accumulate inter-row gaps, each capped.
+    let accumulated = 0;
+    const cumulative = Array.from({ length: count }, (_, index) => {
+        if (index > 0) {
+            const gap = nodes[index].time - nodes[index - 1].time;
+            accumulated += Math.min(Math.max(0, gap), GAP_CAP_MS);
+        }
+        return accumulated;
+    });
+    if (accumulated <= 0)
+        return even();
+    return cumulative.map(value => value / accumulated);
+}
+/**
+ * Project the ledger onto a fixed number of columns.
+ *
+ * @param nodes - The folded ledger, in log order.
+ * @param columns - Column count; normally the band's rendered width.
+ * @param projection - Horizontal domain (see the module comment).
+ * @returns The band, with `peak` for glyph scaling and turn markers for the
+ *   ruler row. An empty ledger yields zero buckets and `peak` 0.
+ */
+export function projectWave(nodes, columns, projection = 'sequence') {
+    const width = Math.max(0, Math.floor(columns));
+    if (width === 0 || nodes.length === 0)
+        return { buckets: [], peak: 0, floor: 0, turns: [] };
+    const buckets = Array.from({ length: width }, () => ({
+        weight: 0,
+        count: 0,
+        channels: { input: 0, model: 0, tool: 0 },
+        error: false,
+        retry: false,
+        running: false,
+        firstIndex: -1,
+    }));
+    const pos = positions(nodes, projection);
+    const turns = [];
+    for (let index = 0; index < nodes.length; index++) {
+        const node = nodes[index];
+        // `pos` is in [0, 1]; the final row must land inside the last column.
+        const column = Math.min(width - 1, Math.floor(pos[index] * width));
+        const slot = buckets[column];
+        const weight = costOf(node);
+        slot.count += 1;
+        slot.weight += weight;
+        slot.channels[channelOf(node.kind)] += weight;
+        if (slot.firstIndex === -1)
+            slot.firstIndex = index;
+        if (node.status === 'error' || (node.burst !== undefined && burstErrors(node.burst) > 0)) {
+            slot.error = true;
+        }
+        if (node.kind === 'retry')
+            slot.retry = true;
+        if (node.status === 'running')
+            slot.running = true;
+        if (node.kind === 'turn')
+            turns.push([node.turn, column]);
+    }
+    // Empty columns inherit the previous column's seek target, so clicking or
+    // scanning across an idle stretch lands on the row that started it rather
+    // than on nothing.
+    let carry = 0;
+    for (const slot of buckets) {
+        if (slot.firstIndex === -1)
+            slot.firstIndex = carry;
+        else
+            carry = slot.firstIndex;
+    }
+    // Log-scale the peak, not the buckets: a session holding one three-minute
+    // call next to hundreds of millisecond ones would otherwise render as a
+    // single spike over a flat line. The view divides log1p(weight) by
+    // log1p(peak), so four orders of magnitude still fit eight glyph levels.
+    // Scale between the smallest non-empty column and the 95th percentile
+    // rather than the maximum. One three-minute call among hundreds of
+    // millisecond ones is a genuine outlier, and letting it own the top of the
+    // scale flattens everything else into two glyph levels; clamping the top
+    // few columns to a full block keeps the rest of the session readable, which
+    // is the same trade every flame graph and latency histogram makes.
+    const weights = buckets.map(slot => slot.weight).filter(weight => weight > 0).sort((a, b) => a - b);
+    const floor = weights[0] ?? 0;
+    const peak = weights.length === 0
+        ? 0
+        : weights[Math.min(weights.length - 1, Math.floor(weights.length * 0.95))];
+    return { buckets, peak, floor, turns };
+}
+/** The dominant channel of a column, or `undefined` for an empty column. */
+export function dominantChannel(bucket) {
+    const { input, model, tool } = bucket.channels;
+    if (input === 0 && model === 0 && tool === 0)
+        return undefined;
+    if (tool >= model && tool >= input)
+        return 'tool';
+    if (model >= input)
+        return 'model';
+    return 'input';
+}
+/**
+ * Map a ledger index back to its column — the inverse used to draw the
+ * viewport bracket under the band.
+ *
+ * @returns Column index, clamped into range; 0 for an empty band.
+ */
+export function columnOfIndex(band, ledgerIndex) {
+    if (band.buckets.length === 0)
+        return 0;
+    // Buckets are monotonic in `firstIndex` after the carry pass, so a linear
+    // scan from the right finds the owning column in one pass without needing a
+    // parallel index array.
+    for (let column = band.buckets.length - 1; column >= 0; column--) {
+        if (band.buckets[column].firstIndex <= ledgerIndex)
+            return column;
+    }
+    return 0;
+}

package/lib/types/dsh-adapter/transcript-images.d.ts

@@ -0,0 +1,17 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { TranscriptImage } from '../adapter/ports/channel-view.js';
+export type { TranscriptImage };
+export declare function rememberImagePath(attachmentId: string, path: string): void;
+/**
+ * Project durable image blocks without leaking the DSH attachment service
+ * into UI code. The returned reader resolves the service at call time so a
+ * late-mounted attachment provider still works.
+ */
+export declare function transcriptImagesOf(content: readonly ContentBlock[] | undefined, resolveAttachments: () => unknown): readonly TranscriptImage[];
+/**
+ * Build the UI facade for one durable image reference. Shared by the
+ * transcript projection and the staged-composer path, so both hand the UI
+ * the same lazily-read shape (and the same per-object decode cache key).
+ */
+export declare function transcriptImageFromAttachment(value: unknown, resolveAttachments: () => unknown): TranscriptImage | undefined;
+//# sourceMappingURL=transcript-images.d.ts.map

package/lib/types/dsh-adapter/transcript-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-images.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/transcript-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AAKvE,YAAY,EAAE,eAAe,EAAE,CAAA;AAU/B,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ1E;AASD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAC5C,kBAAkB,EAAE,MAAM,OAAO,GAChC,SAAS,eAAe,EAAE,CAiB5B;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,MAAM,OAAO,GAChC,eAAe,GAAG,SAAS,CAyB7B"}