dsh-diff-approval 0.29.1 → 0.31.0

package/lib/types/client/PendingPanel.d.ts

@@ -7,7 +7,7 @@ import type { PendingPanelFace } from './slots.ts';
 import type { Translator } from './locales.ts';
 import { computeWholeFileDiff } from './whole-file-diff.ts';
 import type { Discussion } from './discussion.ts';
-import type { ChangeBlock, IntraRun } from './whole-file-diff.ts';
+import type { ChangeBlock, IntraRun, WholeFileDiffRow } from './whole-file-diff.ts';
 import type { HighlightSides } from './highlight.ts';
 import type { VisibleLines } from './windowed-highlight.ts';
 /**
@@ -22,15 +22,12 @@ import type { VisibleLines } from './windowed-highlight.ts';
  * floor is not just a drag limit, it is the width at which the footer is still itself.
  */
 export declare const MIN_LIST_WIDTH_PX = 260;
-/** Normalize a path for comparison: forward slashes, no trailing slash. */
-export declare function normalizeDiffPath(p: string): string;
-/** Whether a produced-file chip path and a pending file path refer to the same
- *  file, tolerant of separator style (\\ vs /) and of a workspace-relative vs
- *  absolute form. `chipPath` is typically the harness's workspace-relative
- *  forward-slash path; `filePath` is the host's absolute native-separator path.
- *  Matching is case-insensitive so a Windows drive/segment case difference does
- *  not miss the file the user clicked. */
-export declare function diffPathsMatch(chipPath: string, filePath: string, workspacePath: string | undefined): boolean;
+/**
+ * Path comparison, re-exported from its own module so every existing importer keeps working: the panel's
+ * own jump, the plugin's press bridge and the store reader all ask the same question, and they must not
+ * each carry their own answer (see `path-match.ts`).
+ */
+export { diffPathsMatch, normalizeDiffPath } from './path-match.ts';
 /** The dsh shell's sidebar auto-collapse breakpoint (ui-layout columns.ts):
  * below it the sidebar auto-collapses, and the file list floats on the same
  * breakpoint so the two stay consistent. */
@@ -61,7 +58,17 @@ export declare function wrapChipRows(line: string, room: number, measure: (text:
 /** Create a measurer bound to `font`; falls back to a rough char estimate. */
 export declare function makeMeasurer(font: string | undefined): ((text: string) => number) | undefined;
 /** Full panel props composed by the sidebar footer-action slot. */
-export type PendingPanelProps = PropsRuntime<'sidebar.footer.action'> & InjectFace<PendingPanelFace> & PropsLocale<'diff-approval'> & PendingPanelDockProps;
+export type PendingPanelProps = PropsRuntime<'sidebar.footer.action'> & InjectFace<PendingPanelFace> & PropsLocale<'diff-approval'> & PendingPanelDockProps & PendingPanelSeat;
+/**
+ * The session this mount is for, when the shell composes one into the seat.
+ *
+ * Session-scoped seats are handed it on 0.1.7; the root-scoped footer slot that hosts this panel is
+ * not, and neither is the dock tab. The other two sources are read where this is absent (see
+ * `session-seat.ts`).
+ */
+export interface PendingPanelSeat {
+    sessionId?: SessionId | undefined;
+}
 /** How the panel is hosted when it is not the footer's floating overlay: the
  *  right sidebar's tab renders it docked, filling the tab and portaling its
  *  content into `dockHost` (the element the tab body owns). */
@@ -72,17 +79,27 @@ export interface PendingPanelDockProps {
     docked?: boolean;
     /** The element the docked panel portals its content into. */
     dockHost?: HTMLElement;
+    /**
+     * Whether this seat is SHOWING anything, and so whether it should read the host at all.
+     *
+     * A seat that is not on screen — a docked tab the reader has switched away from — draws nothing, so
+     * its poll reads a list nobody is looking at, once a second, for a session the reader may not even be
+     * in. `false` stops that read; the seat keeps what it last read and starts again the moment it is
+     * shown. Absent means "always showing", which is what the footer entry is: its badge is the reader's
+     * at-a-glance count, and a badge that never read would simply show nothing.
+     */
+    showing?: boolean;
+    /**
+     * Ask the host how many rows this session has, WITHOUT reading the list (`list-count`).
+     *
+     * This is what the tick asks while this seat has no surface on screen: the badge is the thing that has
+     * to keep working while the panel is shut, and the full read is what makes it slow (it ships every
+     * visible entry's whole old and new text). A seat that IS on screen keeps the full read, and so does a
+     * face that offers no counter at all — absent means "this face cannot count", which is today's
+     * behaviour: one full read per tick.
+     */
+    onRefreshCount?: ((sessionId: SessionId | undefined) => void) | undefined;
 }
-/**
- * Open the DSH settings dialog and switch to this plugin's section. The
- * settings shell keeps its open state and the active section id as
- * component-local viewing state with no cross-plugin service, so the dialog
- * is opened by clicking the sidebar's settings trigger and then the nav cell
- * for this section. `element.click()` still fires React's delegated click
- * handlers, reaching the same state transitions a user gesture would.
- * @param sectionLabel - the nav label of this plugin's settings section.
- */
-export declare function openSettingsSection(sectionLabel: string): void;
 /**
  * How much of the window the app itself occupies on each side of the conversation
  * — how far the floating panel has to start from an edge to leave that part
@@ -103,6 +120,27 @@ export declare function frameInsets(): {
     left: number;
     right: number;
 };
+/**
+ * The model row that holds one new-file line, or the last row that reads before it.
+ *
+ * The list's comments tab names a comment by the LINES it was written on (it draws no rows, so it has
+ * no row index to give), and a jump has to land the way every other jump does. A line the model no
+ * longer holds — an outdated thread — lands on the last row before it, which is exactly where
+ * `remapDiscussion` hangs a thread whose range is gone, so the box the reader came for is on screen.
+ *
+ * A row the file STILL HAS wins over one it is offering to take away, because a modified file numbers
+ * both sides and the same number is often carried by each: the row for old line 378 sits in the row
+ * stream just above the row for new line 378 (that is what a four-line deletion above the line looks
+ * like), and reading `newLine ?? oldLine` in one pass answers with the DELETED row. Landing there put
+ * the view above the code the number names — which is a comment's box with its top edge cut off by the
+ * viewport, the report this answers. The deleted row is still the right answer when the line exists
+ * nowhere else, and the last row before it when the file has moved past the number altogether.
+ *
+ * @param rows - the current model's rows.
+ * @param line - the new-file line to find.
+ * @returns the row index, or undefined when no row reads before that line.
+ */
+export declare function rowOfLine(rows: readonly WholeFileDiffRow[], line: number, oldSide?: boolean): number | undefined;
 /** One file's synchronous view: diff rows and change blocks. */
 interface RowModel {
     diff: ReturnType<typeof computeWholeFileDiff>;
@@ -123,7 +161,7 @@ interface RowRange {
  *  shared toolbar/keyboard in split mode (its own `focus` is private here). */
 export interface SplitDiffHandle {
     jump: (direction: -1 | 1, wrapGuard?: boolean, singleToast?: boolean) => void;
-    land: (row: number, toCard?: boolean, flash?: boolean) => void;
+    land: (row: number, toCard?: boolean, flash?: boolean, comment?: string | undefined) => void;
     openSearch: () => void;
     toggleSearch: () => void;
     closeSearch: () => boolean;
@@ -134,6 +172,10 @@ export interface SplitDiffHandle {
 /** The two-column (side-by-side) whole-file diff view. */
 export declare const SplitDiff: import("react").ForwardRefExoticComponent<{
     file: PendingFileDiff;
+    /** The session the panel is VIEWING, which owns every decision made in this view (see
+     *  `PendingDiffProps.sessionId`). Not `file.sessionId`, which names the session that most
+     *  recently touched the file. */
+    sessionId: SessionId;
     model: RowModel;
     runs: HighlightSides | undefined;
     langWrap: boolean;
@@ -174,6 +216,32 @@ interface RulerRun {
     end: number;
     kind: 'del' | 'add';
 }
+/**
+ * How many leading toolbar items fit in `available` px, with `gap` between neighbours.
+ *
+ * The decisions at the right end of the row (Keep / Revert) are what the row is for, so the
+ * informational buttons on its left are the ones that give way. An item that has not been measured
+ * yet costs nothing here and is settled by the next pass.
+ *
+ * @param widths - each item's own width in px, in the order they are drawn.
+ * @param available - the width the items may occupy.
+ * @param gap - the space between two neighbouring items.
+ * @returns the number of leading items that fit; 0 when even the first one does not.
+ */
+export declare function fittingItems(widths: readonly number[], available: number, gap: number): number;
+/**
+ * How many leading items the toolbar draws inline, given the room the group has.
+ *
+ * When they do not all fit, room has to be made for the overflow button that holds the rest — which
+ * can push one more item out — so the answer is asked twice, the second time with that button's
+ * width reserved. Reserving space can only shrink the count, so two passes settle it.
+ *
+ * @param widths - each item's own width in px, in the order they are drawn.
+ * @param available - the width the group may occupy.
+ * @param gap - the space between two neighbouring items.
+ * @param overflowWidth - the overflow button's width, reserved only when something is left over.
+ * @returns how many leading items to draw inline.
+ */
+export declare function inlineItemCount(widths: readonly number[], available: number, gap: number, overflowWidth: number): number;
 /** Render the pending-edit review panel and its unified footer action. */
-export declare function PendingPanel({ wide, useSessions, usePending, onRefresh, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onAskAgent, watchChat, onUndo, onRedo, onImportVcs, onRefreshVcs, onBrowse, onAddPath, onKeepAll, onRevertAll, onAckRedoCleared, collapseSidebar, t, docked, dockHost, onOpenDock, closeDock, useDock, }: PendingPanelProps): import("react").JSX.Element;
-export {};
+export declare function PendingPanel({ wide, useSessions, sessionId, usePending, pendingView, showing, onRefresh, onRefreshCount, onMarkSeen, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onCommentAdd, onCommentRemove, onCommentRemoveMany, onCommentAsk, onCommentSeen, onUndo, onRedo, onImportVcs, onRefreshVcs, onBrowse, onAddPath, onKeepAll, onKeepMany, onRevertMany, onAckRedoCleared, onAckUndoNotice, collapseSidebar, t, docked, dockHost, onOpenDock, closeDock, useDock, onCheckUpdate, }: PendingPanelProps): import("react").JSX.Element;

package/lib/types/client/category-color.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The colour a comment's CATEGORY is drawn as: one round dot per class of annotation.
+ *
+ * An agent annotating several passes over the same review (a call-chain walk, then the findings, then a
+ * second round of questions) can pass the same `category` id for every annotation of one kind and a
+ * different id for the next — and the reader then sees at a glance which class each comment belongs to,
+ * without reading a word. The id itself is opaque here: this module never parses it, only hashes it.
+ *
+ * The mapping is a plain hash into a fixed palette, so it is the SAME colour on any host and after any
+ * reload, with nothing persisted beyond the id the record already carries. Two ids can collide on one
+ * colour — 12 buckets cannot promise otherwise — which is why the reader also gets the id in words
+ * (`title`/`aria-label`): colour is a fast cue, never the only one.
+ *
+ * @module dsh-diff-approval/src/client/category-color
+ */
+/**
+ * The twelve colours, in the order the hash indexes them — and THE ORDER IS PART OF THE CONTRACT, because
+ * the index is the bucket (see `categoryColorIndex`).
+ *
+ * The SET was chosen by CIEDE2000, not by eye and not by hue angle: it is a coordinate-ascent result over
+ * twelve colour families, and its MINIMUM pairwise ΔE00 is **18.82** — owned by the light blue and the grey
+ * — with every entry between L* 42 and 70, so each reads as a mark on the panel's light and dark surfaces
+ * alike. An earlier palette looked well spaced on the hue wheel and was not: indigo `#6E56CF` against
+ * purple `#8E4EC6` sat 20° apart at the same lightness and chroma — ΔE00 **6.94** on a 3px mark — and a
+ * near-duplicate green `#57a751` would have passed a hue-angle floor at ΔE00 2.65.
+ *
+ * THE ORDER was then solved for SEPARATELY (2026-10-06), because the set's spacing says nothing about the
+ * spacing of NEIGHBOURING buckets: the array used to be a hue ramp, so two categories whose hashes landed
+ * on adjacent indices — 2 times out of 12, which is the reader's own pair at indices 7 and 8 — differed by
+ * as little as ΔE00 19.28. The sequence below is the bottleneck Hamiltonian path over those same twelve
+ * colours: the order that MAXIMISES the MINIMUM ΔE00 over the eleven consecutive pairs, proved optimal by
+ * a DP over (mask, last) in the scratch script that chose it. Its consecutive minimum is **32.7475** — the
+ * full value is 32.74748843826888, which is why the test's floor is 32.7474 and not the rounded figure —
+ * owned by the grey and the red, against 19.2835 for the shipped order, and the set itself is byte-identical,
+ * so the whole-palette floor above is still 18.82. `tests/category-color.client.spec.ts` asserts BOTH numbers
+ * (whole-set and consecutive) plus the L* band, so a thirteenth colour or a reshuffle fails a test rather
+ * than shipping.
+ *
+ * Two categories can still collide EXACTLY — twelve buckets cannot promise otherwise, and `alpha`/`beta` in
+ * the spec do — so the promise this order keeps is "adjacent buckets differ a lot", never "different ids
+ * always differ"; colour is a fast cue, and the id in the mark's own `title`/`aria-label` is the exact one.
+ */
+export declare const CATEGORY_COLORS: readonly ["#7F888E", "#C33D41", "#6A5CA4", "#7AAB83", "#B8A3CA", "#1D6F66", "#DC54B9", "#80A5EB", "#8D711B", "#13A9BF", "#577F11", "#C19784"];
+/**
+ * Which palette entry a category id maps to: FNV-1a (32-bit) over the id's UTF-16 code units, mod 12.
+ *
+ * FNV-1a because it is four lines, has no dependencies, and spreads uuid-shaped ids (the reader's own
+ * suggestion: "passing a uuid per call") well enough that a handful of categories rarely collide. It is
+ * pinned by a test with a fixed id, so changing the hash is a visible decision rather than a silent
+ * recolouring of every existing annotation.
+ *
+ * @param category - the category id, as it was stored (already trimmed and capped by the tool rule).
+ * @returns the index into {@link CATEGORY_COLORS}, 0..11.
+ */
+export declare function categoryColorIndex(category: string): number;
+/**
+ * The colour one category is drawn as.
+ *
+ * @param category - the category id.
+ * @returns a `#RRGGBB` string from {@link CATEGORY_COLORS}.
+ */
+export declare function categoryColor(category: string): string;

package/lib/types/client/chords.d.ts

@@ -9,13 +9,6 @@
  * @module dsh-diff-approval/client/chords
  */
 import type { Translator } from './locales.ts';
-/**
- * One stored chord as a hint renders it: modifiers as written, arrow keys as
- * glyphs (`Ctrl+ArrowUp` → `Ctrl+↑`).
- * @param chord - the stored chord.
- * @returns the hint text; `''` for an unbound action.
- */
-export declare function chordHint(chord: string): string;
 /**
  * One action's chord as a hint.
  * @param action - the keybinding action id (see `DEFAULT_KEYBINDINGS`).
@@ -31,19 +24,79 @@ export declare function chordLabel(action: string): string;
  * @returns the label, with ` (chord)` appended when one is configured.
  */
 export declare function withChord(label: string, action: string): string;
+/** One chord in both the forms a tooltip needs, read from a single setting so the two cannot drift. */
+export interface ChordShortcut {
+    /**
+     * The keycaps, in order, with a literal `'+'` between the parts: the shell renders one `<kbd>` per
+     * entry and groups a combination into a single keycap when the array carries a separator (see the
+     * primitives' `ShortcutKeys`).
+     */
+    keys: string[];
+    /** The `aria-keyshortcuts` value: the same chord spelled in DOM key names. */
+    aria: string;
+}
+/**
+ * One action's shortcut, as a tooltip's `shortcutKeys` and the anchor's `aria-keyshortcuts`.
+ * @param action - the keybinding action id (see `DEFAULT_KEYBINDINGS`).
+ * @returns the two forms, or `undefined` when the action is unbound.
+ */
+export declare function shortcutOf(action: string): ChordShortcut | undefined;
+/**
+ * The quick-summon chord: its own setting rather than one of `DEFAULT_KEYBINDINGS`, since it is the
+ * one chord the panel is opened BY rather than one it answers inside.
+ * @returns the two forms, or `undefined` when the chord is unbound.
+ */
+export declare function summonShortcut(): ChordShortcut | undefined;
+/**
+ * Escape alone: the key the INNERMOST dismissible answers to (the search bar, a dialog), which no
+ * panel chord stands behind — the quick-summon chord closes the panel, not the bar inside it.
+ * @returns the keycaps and the aria form.
+ */
+export declare function escapeShortcut(): ChordShortcut;
+/**
+ * The panel's close button: Escape always, plus the quick-summon chord while one is bound.
+ *
+ * This is the one place the shell's one-chord model needs a judgment: these are two WAYS out, not a
+ * sequence, so they stay two keycaps (`['Esc', 'Ctrl+D']`) and two space-separated aria shortcuts —
+ * grouping them into one cap with separators would read as "press Esc, then Ctrl+D".
+ * @returns the keycaps and the aria form.
+ */
+export declare function closeShortcut(): ChordShortcut;
+/** What one tooltip site hands the shell, decided here so that no call site ever branches. */
+export interface TooltipChord {
+    /**
+     * The label for the shell's `Tooltip`: the action's own name where the shell draws keycaps, and the
+     * label this plugin spelled before the primitives' 0.1.7-rc.2 — chord glued in — where it cannot.
+     */
+    label: string;
+    /** The keycaps to pass, or `undefined` when there is no chord or this host cannot draw one. */
+    shortcutKeys: readonly string[] | undefined;
+    /** The anchor's `aria-keyshortcuts`: plain text, and the same on every host. */
+    aria: string | undefined;
+}
+/**
+ * A tooltip for one action's chord.
+ * @param label - the translated action label.
+ * @param action - the keybinding action id, or `undefined` for a control that has no chord at all.
+ * @returns the label, keycaps and aria; an unbound or absent action keeps the plain label.
+ */
+export declare function actionTooltip(label: string, action: string | undefined): TooltipChord;
+/**
+ * The entry buttons that open the panel (the session header's, the footer badge): what it holds, and
+ * the chord that does the same. With the chord unbound the plain label is the whole hint.
+ * @param t - the panel's translator.
+ * @returns the label, keycaps and aria.
+ */
+export declare function summonTooltip(t: Translator): TooltipChord;
 /**
- * How the panel's close button names its two ways out: Escape, and the
- * quick-summon chord when the user still has one bound. Unbinding the chord
- * leaves Escape as the only answer, so the hint then says just that.
+ * The panel's close button: Escape, plus the quick-summon chord while one is bound.
  * @param t - the panel's translator.
- * @returns the tooltip label.
+ * @returns the label, keycaps and aria.
  */
-export declare function closeHint(t: Translator): string;
+export declare function closeTooltip(t: Translator): TooltipChord;
 /**
- * How an entry button names what it opens: the pending-changes panel, plus the
- * chord that does the same. With the chord unbound the plain label is the whole
- * hint — never an empty parenthetical.
+ * A control only Escape dismisses — the search bar — which no panel chord stands behind.
  * @param t - the panel's translator.
- * @returns the tooltip label.
+ * @returns the label, keycaps and aria.
  */
-export declare function summonHint(t: Translator): string;
+export declare function escapeTooltip(t: Translator): TooltipChord;

package/lib/types/client/discussion.d.ts

@@ -7,6 +7,7 @@
  *
  * @module dsh-diff-approval/client/discussion
  */
+import type { CommentQuoteLine } from '../types.ts';
 /** One row range in the current diff model (inclusive, 0-based row indices). */
 export interface DiscussionAnchor {
     /** First row of the range, in the model this block is currently drawn against. */
@@ -97,23 +98,8 @@ export interface Discussion {
     lost?: boolean;
     /** The answer being streamed for the question in flight. */
     reply?: string;
-    /**
-     * Where the session's transcript stood when the last question was sent — its node count.
-     *
-     * Kept with the block rather than only in the panel's refs, so a question still waiting
-     * for its answer can be picked up again after the panel is closed and reopened: the search
-     * for our own prompt starts here, which is what keeps an older, identical-looking prompt
-     * from being mistaken for it.
-     */
-    baseline?: number;
     /** The turn for the last question is running. */
     asking?: boolean;
-    /**
-     * The question is sent but still behind another turn of the session, so nothing
-     * streamed yet belongs to this discussion. The block says it is waiting instead
-     * of showing the other turn's answer.
-     */
-    queued?: boolean;
     /** The answer failed (the session recorded a prompt error). */
     failed?: boolean;
     /**
@@ -141,6 +127,13 @@ export interface Discussion {
     quoteWrap?: boolean;
     /** How many older messages the row cap left out of the render. */
     hidden?: number;
+    /**
+     * Something the reader has not looked at yet arrived in this thread — an agent's own annotation, or
+     * an answer to one of its questions — so the card wears the dot. Host truth, carried through from
+     * the stored record (see `CommentRecord.unseen`): the block draws it and the card's own visibility
+     * is what asks the host to take it down.
+     */
+    unseen?: boolean;
 }
 /** Rows a folded block occupies: its header line. */
 export declare const DISCUSSION_HEADER_ROWS = 1;
@@ -234,6 +227,25 @@ export declare function discussionRows(discussion: Discussion): number;
  * @returns a map from row index to the rows added below it.
  */
 export declare function discussionRowExtras(discussions: readonly Discussion[], rowCount: number): Map<number, number>;
+/**
+ * Where each block's own box starts, in rows, measured from the BASE of the stack it hangs in.
+ *
+ * Several blocks can end on one row, and then they are drawn one below the other under it, in the
+ * order they are held: `discussionRowExtras` charges the row the sum of them all, and the row stream
+ * (and the split view's card layer) draws one reserving box per block, in that same order. So the
+ * first block of a stack starts at the base, the second one box down, and so on — and a jump that
+ * names a block has to add that many boxes to the base, or it lands the top of the stack whatever
+ * block the reader asked for.
+ *
+ * Nothing is reordered here and no height changes: this is a reading of the drawing order the views
+ * already use, keyed by block id so a jump can ask for the box it was sent for.
+ *
+ * @param discussions - the blocks currently attached to this file, in the order they are drawn.
+ * @param anchorOf - the row the block hangs under, clamped exactly as the caller's row stream clamps
+ *   it (its own height table and its own idea of the last row are what the base below is measured in).
+ * @returns a map from block id to the block's own start, in whole rows below its stack's base.
+ */
+export declare function discussionStackOffsets(discussions: readonly Discussion[], anchorOf: (discussion: Discussion) => number): Map<string, number>;
 /**
  * The discussion attached to exactly this range, if there is one.
  *
@@ -271,7 +283,12 @@ export declare function discussionOverlapping(discussions: readonly Discussion[]
  * is what says whether they still hold the code the comment was written about. When they do
  * not — the lines were edited under it, or the hunk moved — the quote is looked for elsewhere
  * in the model and the thread follows it, nearest occurrence first when the same code shows up
- * more than once. When nothing matches, the block keeps the rows it last matched and is marked
+ * more than once. A match farther from the stored rows than `REANCHOR_MAX_LINES` is not that code
+ * having moved but another place in the file that happens to read the same — a look-alike
+ * declaration, which the recorded ±1 context cannot tell apart — so it is refused and the block is
+ * marked outdated instead. That is the one bound the host half applies in lines as well, so the
+ * figure the list ships and the place this half draws the card cannot come from two rules. When
+ * nothing matches, the block keeps the rows it last matched and is marked
  * outdated: it says so and keeps its quote for the reader, rather than being silently moved
  * onto whatever took those lines. Only when the whole range is gone from the model does the
  * block move, and then by line number, back to where the range used to be (see `gone`). The mark
@@ -301,6 +318,49 @@ export declare function remapDiscussion(discussion: Discussion, lineOf: (row: nu
  * @returns the re-anchored blocks, in the order they came in.
  */
 export declare function remapDiscussions(discussions: readonly Discussion[], lineOf: (row: number) => number | undefined, textOf: (row: number) => string, rowCount: number, hasNewLine?: (row: number) => boolean): readonly Discussion[];
+/**
+ * The frame the reader drew, as a block of quoted lines for the question to carry.
+ *
+ * A reference is one number, and one number cannot say what the comment is about: a reader annotating
+ * a DELETED line produced `a.txt:2`, and the agent read line 2 of the file — which is another line
+ * entirely, because a removed line has no number in the file as it reads now (its `2` is the old
+ * file's). This block says what the number cannot: every row of the frame, in order, with the side it
+ * was on (`-` removed, `+` added, a space for context) and the number THAT side's file gave it.
+ *
+ * `quote` and `quoteLines` are what the record already holds — one entry per frame row, in row order —
+ * so nothing new is recorded for this: the question is built from the same snapshot the re-anchor uses.
+ * A record from before `quoteLines` was kept (or one the agent annotated, which names current lines
+ * only) has the text alone, and the block is that text with no numbers rather than a made-up side.
+ *
+ * @param quote - the anchored lines as they read when the comment was written.
+ * @param quoteLines - their gutter numbers and sides, in the same order.
+ * @returns the block, or `''` when there is nothing to show.
+ */
+export declare function quotedFrame(quote: string | undefined, quoteLines: readonly DiscussionQuoteLine[] | undefined): string;
+/**
+ * Whether a frame's numbers all come from the OLD file.
+ *
+ * A frame of removed rows alone names no line the file still has, so the numbers its record carries
+ * (`anchor`, and the line a jump is handed) are the old file's. Everything that would otherwise
+ * present them as current lines asks this first: the label a card and a list item wear, and the
+ * landing a jump to that comment makes. A record that kept no sides answers false — what it holds is
+ * read exactly as it always was.
+ *
+ * @param quoteLines - the frame's gutter numbers and sides, when the record kept them.
+ * @returns true when the frame holds at least one row and none of them has a new-file line.
+ */
+export declare function frameNamesNoCurrentLine(quoteLines: readonly DiscussionQuoteLine[] | readonly CommentQuoteLine[] | undefined): boolean;
+/**
+ * Whether a frame covers a line the file no longer has.
+ *
+ * The one thing a frame can hide behind its numbers: `anchor` is documented as new-file lines, but a
+ * frame of removed rows alone has none of those, so the numbers it carries are the old file's. A
+ * caller that must not present them as current lines asks this.
+ *
+ * @param quoteLines - the frame's gutter numbers and sides, when the record kept them.
+ * @returns true when at least one row of the frame is a removed line.
+ */
+export declare function frameCoversRemovedRow(quoteLines: readonly DiscussionQuoteLine[] | undefined): boolean;
 /** What the selection frame shows for the current selection. */
 export interface SelectionFrameActions {
     /** Whether keep/revert apply (the selection fully covers change blocks). */

package/lib/types/client/dock.d.ts

@@ -14,7 +14,8 @@
  */
 import type { ReactNode } from 'react';
 import type { HostObservable, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
-import type { PendingDiffSnapshot } from './slots.ts';
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { PendingDiffSnapshot, PendingViewHooks } from './slots.ts';
 /** The tab type's `kind`: what `openTab` names. */
 export declare const DIFF_DOCK_KIND = "diff-approval";
 /** The registration's `id`: the key its body and title register under. The
@@ -120,11 +121,15 @@ type TabInfoHook = () => {
         readonly visible: boolean;
     };
 };
-export interface DiffDockBodyProps extends PropsLocale<'diff-approval'> {
+export interface DiffDockBodyProps extends PropsLocale<'diff-approval'>, PendingViewHooks {
     /** The seat's own tab hook (the sidebar framework injects it). */
     readonly useTabInfo?: TabInfoHook;
-    /** This plugin's pending store hook, for the chip's count. */
+    /** This plugin's pending store hook, for the chip's count where no per-session reader reaches it. */
     readonly usePending?: (select: (snapshot: PendingDiffSnapshot) => unknown) => unknown;
+    /** The session seat, when this host composes one into the tab (see `session-seat.ts`). */
+    readonly useSessions?: ((select: (state: unknown) => unknown) => unknown) | undefined;
+    /** The session this dock tab belongs to, when the shell composes one. */
+    readonly sessionId?: SessionId | undefined;
     /** Whether the panel renders as the docked body (set by the tab seat's face). */
     readonly docked?: boolean;
     /** Report this body's visibility to the dock state (see {@link DockFace}). */
@@ -133,11 +138,6 @@ export interface DiffDockBodyProps extends PropsLocale<'diff-approval'> {
     readonly onDockClose?: ((close: (() => void) | undefined) => void) | undefined;
     [key: string]: unknown;
 }
-/** One live dock adapter: the face, and the teardown that unsubscribes. */
-export interface DiffDock {
-    readonly face: DockFace;
-    dispose(): void;
-}
 /** The cordis pieces this adapter uses, structurally: optional service lookup and
  *  a scoped effect. Both are what the plugin sandbox always forwards — its
  *  whitelist covers `effect`/`on`/timers but NOT cordis's dynamic `inject`, and it

package/lib/types/client/dsh-icons.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The shell's own icons and controls, fetched by every name the shells have given them.
+ *
+ * 0.1.7 renamed the whole product icon set: `IconCloseOutline16` and `IconChevronDownOutline14` became
+ * `IconCloseOutlineMedium` and `IconChevronDownOutlineMedium` (the `Medium`/`Regular` stroke pair,
+ * where the numbers used to say the size). A static import of the old name survives compilation and
+ * then hands React `undefined` to render, which is a crash of the whole mount — React #130, measured
+ * here on 0.1.7-rc.2: `DiffApprovalHeaderEntry` took the panel down with it, and nothing in the plugin
+ * worked until the shell was changed again.
+ *
+ * So each glyph is resolved in two steps, and neither step can throw:
+ *
+ * 1. the NEW name, looked up on the module namespace at run time — present on 0.1.7 and later, and
+ *    absent (harmlessly) anywhere else;
+ * 2. the legacy name, imported statically, which is what every shell before 0.1.7 exports.
+ *
+ * A glyph no shell offers renders nothing rather than failing. That is the point of this module: a
+ * rename in the shell becomes a shell that draws fewer icons, not a plugin that dies. The plugin's
+ * peer floor stays `0.1.0-rc.5`.
+ *
+ * The exports carry the names this plugin's code already uses (`IconCloseOutline16` and the rest), so
+ * a caller changes only where it imports from.
+ *
+ * @module dsh-diff-approval/client/dsh-icons
+ */
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives';
+import type { ReactElement } from 'react';
+/** The pending-changes glyph: the sidebar's badge and the header entry carry it. */
+export declare const IconListPenOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The list's fold chevrons. */
+export declare const IconChevronDownOutline14: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconChevronUpOutline14: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The path picker's tree disclosure. */
+export declare const IconChevronRightOutline14: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** Closing a card, a dialog or a search bar. */
+export declare const IconCloseOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The thread's own overflow menu. */
+export declare const IconEllipsisOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The add-path dialog's browse button. */
+export declare const IconBrowseOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** A folder in the picker's tree, open and closed. */
+export declare const IconFolderOpenOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconFolderOpen16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconFolderClose16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The presentation switch: dock the panel in the sidebar. */
+export declare const IconPanelLeftOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** The settings tab's refresh, which the older set spelled with the small size. */
+export declare const IconRefreshOutline14: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/** Adding a path, the diff refresh, the search box, and Settings. */
+export declare const IconPlusOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconRefreshOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconSearchOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+export declare const IconSettingsOutline16: ({ size, className }: primitives.IconProps) => import("react").JSX.Element;
+/**
+ * The package's own menus, toasts and clipboard helper.
+ *
+ * Re-exported so one module names everything this plugin takes from the shell's primitives: these
+ * names have survived both releases, and a caller has no reason to reach past this file.
+ */
+export { Menu, Toast, writeClipboard } from '@deepseek-ai/dsh-client-ui-primitives';
+export type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives';
+/** The tooltip props this plugin uses, including the one the installed types do not know yet. */
+export interface ShellTooltipProps {
+    label: string;
+    side?: 'right' | 'bottom' | 'top' | undefined;
+    delayMs?: number | undefined;
+    maxWidth?: number | undefined;
+    disabled?: boolean | undefined;
+    /**
+     * The keycaps the bubble renders AFTER its label, one `<kbd>` per entry, with a literal `'+'`
+     * between the parts so the shell groups a combination into a single keycap. `undefined` (or an
+     * empty array) renders no keycaps at all — which is what an unbound action passes.
+     */
+    shortcutKeys?: readonly string[] | undefined;
+    children: ReactElement;
+}
+/**
+ * The primitives' `Tooltip`, typed with the props above.
+ *
+ * `shortcutKeys` arrived in the primitives' 0.1.7-rc.2 — the release the host runs — while what this
+ * repo COMPILES against is 0.1.0-rc.6, whose `Tooltip.d.ts` predates it. Passing the prop at a call
+ * site is therefore a type error even though the running component accepts it (and an older one simply
+ * ignores an unknown prop). The cast lives here, once, at the same boundary this module already uses
+ * to bridge shell versions, rather than at every call site.
+ */
+export declare const Tooltip: (props: ShellTooltipProps) => ReactElement;
+/**
+ * Whether the running shell can draw a shortcut beside a tooltip's label.
+ *
+ * `ShortcutKeys` and the `Tooltip.shortcutKeys` prop shipped together in the primitives'
+ * **0.1.7-rc.2**: across all 24 installed versions this plugin is tested against, the component is
+ * absent from every release up to and including 0.1.7-rc.1 (`lib/index.js` does not contain the name
+ * at all, and `Tooltip.d.ts` takes no `shortcutKeys`) and present from 0.1.7-rc.2 on (`function
+ * ShortcutKeys(...)`, exported, and `shortcutKeys?: readonly string[]` on `Tooltip`) — the same
+ * release the prop arrived in, so the two can never disagree. An older host ignores an unknown prop
+ * silently, which is why a caller must not rely on the prop alone (see `chords.ts`).
+ */
+export declare const SHELL_DRAWS_SHORTCUTS: boolean;