dsh-claude-desktop-theme 0.2.0 → 0.4.0

package/lib/types/client/compat/permission-menu.d.ts

@@ -0,0 +1,88 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** Names the preset a tagged row switches to; `theme/menus.css` keys the two-line cell off it. */
+export declare const PERMISSION_MODE_ATTRIBUTE = "data-ccd-permission-mode";
+/** Tags the card those rows sit in, so the stylesheet can reach the card itself. */
+export declare const PERMISSION_MENU_ATTRIBUTE = "data-ccd-permission-menu";
+/** One preset as the card draws it. */
+export interface PermissionPresetCopy {
+    /** DSH's machine value for the preset (`read-only`, `auto`, …): the row's identity, never shown. */
+    readonly value: string;
+    /** The name DSH renders, which is what a row is recognised by. */
+    readonly name: string;
+    /** The name to draw — the same wording wherever the host's is already the one to use. */
+    readonly label: string;
+    /** The preset's trailing badge: the word DSH prints, and the word to print instead. */
+    readonly badge?: {
+        readonly host: string;
+        readonly text: string;
+    };
+    /** The row's second line, saying what the mode does. */
+    readonly description: string;
+}
+/** The card's copy in one language. */
+export interface PermissionCopy {
+    /** The group's name, above the rows — the one thing the reference writes that the host does not. */
+    readonly heading: string;
+    readonly presets: readonly PermissionPresetCopy[];
+}
+/**
+ * The card's copy for the document on screen.
+ *
+ * DSH localises its own strings through `ctx.locale`; a third-party plugin may
+ * not borrow another package's namespace, so the second line follows the
+ * document language instead — the same rule `compat/header-labels.ts` follows.
+ *
+ * @param document - renderer document whose language DSH sets from the locale.
+ * @returns Chinese copy for a Chinese document, English otherwise.
+ */
+export declare function permissionCopy(document: Document): PermissionCopy;
+/**
+ * The permission picker's card, drawn the way the reference draws it.
+ *
+ * DSH's card is four flat rows of a preset's name — `仅可查看` / `工作区内修改`
+ * / `完全权限` / `Auto review` — one 20px line each, and the only thing that
+ * tells them apart is the name itself. The reference draws the same four
+ * choices as two-line cells: the mode's name over a sentence saying what the
+ * mode does, with the one flagged preset carrying a badge beside its name. The
+ * names are the host's and stay the host's; what this module adds is the second
+ * line, and its home is a node the host never renders — `optionDescription`
+ * exists in the permission catalog, but the picker passes it to the trigger's
+ * `title` and prints nothing in the row.
+ *
+ * So this is the one compat module that *writes* copy rather than rewriting
+ * what the host rendered, and the copy is this plugin's own: see
+ * `permissionCopy` above. It is kept in one table per document language, so a
+ * wording change is one edit in one place.
+ *
+ * Three facts decide how the rows are reached, and each is worth stating:
+ *
+ * - **A row is recognised by its name.** `Menu` rows carry no identity of their
+ *   own — no id, no data attribute, and the preset's own glyph is a thing this
+ *   plugin removes (`theme/menus.css` hides the icon seat) — so the name the
+ *   host localised is the only handle there is. That is the same fact
+ *   `compat/workspace-menu.ts` reads for its own row, and it fails safe: a
+ *   deployment that configured its own preset names matches nothing, and its
+ *   card keeps the host's single-line rows exactly as they are.
+ * - **The card is recognised by its rows.** The picker's trigger carries no
+ *   `aria-expanded` (unlike the account trigger and the hero chips), so the
+ *   portalled card cannot be tied back to the control that opened it; the card
+ *   a recognised row sits in is therefore the card this module tags. A card
+ *   none of whose rows is recognised is left whole — its heading with it, since
+ *   a heading over four unrecognised rows names nothing.
+ * - **Nothing here reorders a row.** The second line is inserted as the label's
+ *   next sibling and the heading as the row group's first child, so the
+ *   primitive's own keyboard walk — which collects `button`s out of the group,
+ *   not its children — steps over both, and every click target, focus order and
+ *   accessible name the host built is left where it was. The row keeps its own
+ *   name too: the inserted line widens what a screen reader reads out of the
+ *   row, which is the point of the sentence.
+ *
+ * The host mounts the card afresh on every open, so every pass is idempotent
+ * and every write is undone on release: a disabled plugin leaves DSH's own card
+ * on screen.
+ *
+ * @param document - renderer document carrying the status bar and the portal.
+ * @param report - sink for observer failures; the native card stays untouched.
+ * @returns disposer that disconnects the observers and takes every write back.
+ */
+export declare function mountPermissionMenu(document: Document, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/relative-file-path.d.ts

@@ -0,0 +1,2 @@
+/** Display a host file relative to the session's working directory on either platform. */
+export declare function relativeFilePath(path: string, cwd: string): string;

package/lib/types/client/compat/right-panes.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Disposer } from '../contracts/ports.ts';
+/** DockLayout can only render two horizontal dock panes. Its floating leaves
+ * have no such limit: retain those host-rendered bodies and controls, and give
+ * them session-owned column geometry. No React-owned node is reparented. */
+export declare const PANES_ATTRIBUTE = "data-ccd-panes";
+export declare const PANE_ATTRIBUTE = "data-ccd-pane";
+export declare const SEAM_ATTRIBUTE = "data-ccd-pane-seam";
+export declare const SEAM_AXIS_ATTRIBUTE = "data-ccd-pane-axis";
+export declare const SEAM_INDEX_ATTRIBUTE = "data-ccd-pane-seam-index";
+export declare const DRAGGING_ATTRIBUTE = "data-ccd-pane-dragging";
+export declare const PANE_LEFT_PROPERTY = "--ccd-pane-left";
+export declare const PANE_TOP_PROPERTY = "--ccd-pane-top";
+export declare const PANE_WIDTH_PROPERTY = "--ccd-pane-width";
+export declare const PANE_HEIGHT_PROPERTY = "--ccd-pane-height";
+export declare function mountRightPanes(ctx: Context, document: Document, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/scroll-pill.d.ts

@@ -0,0 +1,70 @@
+import type { Disposer } from '../contracts/ports.ts';
+/**
+ * The window's scrollbars: thin, dark, and there only while something moves
+ * (DESIGN.md §三).
+ *
+ * Two mechanisms, one look.
+ *
+ * **The ink.** Every scroller inside `theme/scrollbars.css`'s scope keeps the
+ * host's own track, thumb box and navigation, and this module publishes the
+ * moment one is moving as {@link SCROLLING_ATTRIBUTE}; the sheet keeps the ink
+ * switched off until it sees that attribute, so no surface in the window
+ * carries a bar at rest. A listener on the document's capture phase sees every
+ * element scroll in one place — scroll events do not bubble, but they do travel
+ * down — and clears the mark again once the surface has been still for
+ * {@link IDLE_MS}.
+ *
+ * **The pill.** The five page-level surfaces — the Conversation page, the
+ * transcript column, the sidebar's tree, the Files pane and the agent-team panel
+ * — go one step further and keep no ink at all: {@link PILL_SURFACE_ATTRIBUTE}
+ * takes their track's thumb out of the painting, and a floating pill
+ * ({@link PILL_ATTRIBUTE}, all of them in one fixed layer) follows the scroll
+ * position instead. That pill is the short capsule the reference draws. The
+ * painted thumb cannot be it: its length is the content's share of the track, so
+ * a surface that only just overflows — a short conversation, a panel with one
+ * page of content — paints a bar the height of its own viewport. The pill is
+ * capped at {@link PILL_MAX} instead, and never shorter than {@link PILL_MIN}.
+ *
+ * The pill is centred on the painted thumb it stands in for, and sits inside the
+ * track's own strip at the edge, so it is where the pointer expects: the host's
+ * thumb — invisible, but still laid out and still the thing that drags — is
+ * directly underneath it, and a drag that starts anywhere on the pill grabs
+ * that bar.
+ *
+ * Everything here is written on elements the host owns, so the disposer puts
+ * each mark back: attributes off, layer gone, listeners removed.
+ */
+/** Marks a surface whose bar is the floating pill rather than the track's ink. */
+export declare const PILL_SURFACE_ATTRIBUTE = "data-ccd-scroll-pill";
+/** Marks a surface in motion — and, on a pill, the pill that belongs to it. */
+export declare const SCROLLING_ATTRIBUTE = "data-ccd-scrolling";
+/** The one fixed layer every pill is painted in. */
+export declare const PILL_LAYER_ATTRIBUTE = "data-ccd-scroll-layer";
+/** Identifies one floating pill. */
+export declare const PILL_ATTRIBUTE = "data-ccd-scroll-thumb";
+/**
+ * How long a mark survives after the last scroll event. The reference's own
+ * overlay scroller fades out about this long after the wheel stops; long enough
+ * to read the position between two flicks, short enough that a resting window
+ * carries no ink.
+ */
+export declare const IDLE_MS = 800;
+/**
+ * The surfaces the pill replaces the ink on. All five are page-level chrome the
+ * reader scrolls by the screenful; the host's popup cards and this plugin's own
+ * panels keep the painted bar (it appears while they scroll, like every other
+ * surface in the sheet's scope), because they are short-lived and their tracks
+ * are narrower.
+ * @param document - renderer document carrying the interface.
+ * @returns the selectors, resolved for the build on screen.
+ */
+export declare function pillSurfaces(document: Document): readonly string[];
+/**
+ * Follow the interface's five page-level scrollers with a floating pill each,
+ * and mark every other scroller while it moves.
+ *
+ * @param document - renderer document carrying the interface.
+ * @param report - sink for observer failures; the host's own bars stay usable.
+ * @returns disposer that removes every pill, mark and listener.
+ */
+export declare function mountScrollPills(document: Document, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/sidebar-navigation.d.ts

@@ -0,0 +1,11 @@
+import type { Disposer } from '../contracts/ports.ts';
+export interface SidebarNavigationIcons {
+    readonly newSession: string;
+    readonly plugins: string;
+    readonly routines: string;
+}
+export declare const SIDEBAR_NAV_ATTRIBUTE = "data-ccd-nav";
+/** Rename and decorate the native buttons without replacing React-owned nodes
+ * or handlers. Every write is conditional and reversible, including delayed
+ * mounts, locale changes, wide/rail rerenders and the native tooltip portals. */
+export declare function mountSidebarNavigation(document: Document, icons: SidebarNavigationIcons, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/stats-values.d.ts

@@ -7,14 +7,31 @@ export declare const TRAILING_WIDTH_PROPERTY = "--ccd-trailing-width";
 export declare const MODEL_MAX_WIDTH_PROPERTY = "--ccd-model-max-width";
 /** The one gap the trailing cluster uses, read to budget the model button. */
 export declare const CLUSTER_GAP_PROPERTY = "--ccd-cluster-gap";
+/**
+ * Root attribute carrying whether the readouts are drawn, whose values are
+ * `on` and `off`.
+ *
+ * Both states are published rather than only the off one: the stylesheet that
+ * hides the cluster keys on `off`, so a document where this module never ran —
+ * a frame the observers could not attach to — keeps the host's own readouts
+ * instead of losing them to a stylesheet default it cannot correct.
+ */
+export declare const STATS_ATTRIBUTE = "data-ccd-composer-stats";
 /**
  * The responsive statistics cluster sits before the model selector. Its dock is
  * a sibling of the card rather than a row child, so its wide-layout offset needs
  * the trailing group's live width. Readouts and their detail dialogs stay owned
  * by the host; wide columns mirror one short segment without changing the host label.
  *
+ * The cluster is the configuration's to keep or drop (`features.composer-stats`,
+ * off by default): its state is published on the root for the stylesheet, which
+ * draws it only while the readouts are on. The width measurements below are
+ * outside that switch — they budget the row whether or not the readouts are
+ * drawn, and a hidden cluster simply hands its width back to the model button.
+ *
  * @param document - renderer document carrying the Composer.
  * @param report - sink for observer failures; the native readouts stay.
+ * @param readouts - whether the configuration asks for the plugin's readouts.
  * @returns disposer that disconnects the observers and clears every property.
  */
-export declare function mountComposerStats(document: Document, report: (error: unknown) => void): Disposer;
+export declare function mountComposerStats(document: Document, report: (error: unknown) => void, readouts: boolean): Disposer;

package/lib/types/client/compat/view-options.d.ts

@@ -0,0 +1,58 @@
+import type { ViewOptionsPort, ViewOptionsSettingsPort } from '../contracts/ports.ts';
+/**
+ * The sidebar's view-options menu, driven instead of replaced.
+ *
+ * DSH's card is a `ui-primitives` `Menu` holding three labelled option groups —
+ * grouping mode, ordering, archived visibility — with the current option marked
+ * by the primitive's trailing check. The three values live in the workspace
+ * browser's own browser-local store, and nothing on the public face writes them:
+ * `UiWorkspace` (`dsh-client-ui-workspace/client` `navigation.d.ts`) publishes
+ * navigation, archive and directory operations only, and the store it keeps
+ * (`stores.d.ts`) exports its factory alone, so a second instance would hold a
+ * copy rather than the browser's state. The one handle that *does* write them is
+ * the host's own row: `WorkspaceBrowser`'s `onSelect` calls `setOpen(false)`
+ * after it applies the choice.
+ *
+ * So this module treats that card as the state API it effectively is. Opening
+ * the card reads it — the host's own menu is opened through the trigger's click
+ * with `DRIVING_ATTRIBUTE` keeping the sheet from drawing it — and choosing an
+ * option clicks the host's own row. Nothing is shown, nothing is synthesised
+ * beyond the clicks the host's control already answers, and the card the reader
+ * sees is the one `features/view-options` draws.
+ *
+ * Three details decide how the drive is written:
+ *
+ * - **The trigger's click is intercepted.** The host opens its card from the
+ *   trigger's `onClick`; a listener on the button that stops propagation keeps
+ *   React's delegated handler from running, so the card opens only when this
+ *   module drives it. The one flag `driving` is what lets our own clicks
+ *   through.
+ * - **React flushes a discrete event synchronously**, so the card is in the
+ *   document by the time the driving click returns; `settle` still waits a
+ *   microtask and then polls, because a build that mounts the card later must
+ *   not turn into a failed read — the card is off screen either way.
+ * - **A card that is not the pinned shape hands the click back.** `readCard`
+ *   refuses anything that is not three groups of at least two rows with exactly
+ *   one check each, and the click that opened it is then passed to DSH so its
+ *   own menu opens. A later build keeps its own interface instead of a card
+ *   with nothing in it.
+ */
+/** Marks the host popup this module is driving; the sheet keeps it off screen. */
+export declare const DRIVING_ATTRIBUTE = "data-ccd-view-options-driving";
+/** Marks the trigger while this plugin's card is the one on screen. */
+export declare const OPEN_ATTRIBUTE = "data-ccd-view-options-open";
+/** The driver's own face, plus the release the mounting scope holds. */
+export interface ViewOptionsDriver {
+    readonly port: ViewOptionsPort;
+    readonly settings: ViewOptionsSettingsPort;
+    /** Read persisted native preferences without showing either menu. */
+    inspect(): Promise<void>;
+    dispose(): void;
+}
+/**
+ * Watch the sidebar's view-options trigger and drive the host's card for it.
+ * @param document - renderer document carrying the sidebar and the portal.
+ * @param report - sink for observer failures; the native menu stays in charge.
+ * @returns the port the card reads through, and the release of every observer.
+ */
+export declare function createViewOptionsDriver(document: Document, report: (error: unknown) => void): ViewOptionsDriver;

package/lib/types/client/compat/view-switch.d.ts

@@ -6,9 +6,50 @@ export declare const VIEW_WIDTH_PROPERTY = "--ccd-view-w";
 /** Animate selection changes; layout corrections must be immediate. */
 export declare const VIEW_DURATION_PROPERTY = "--ccd-view-duration";
 /**
- * Measure the selected ui-conversation tab and publish slider geometry.
- * MutationObserver handles tablist replacement and layout changes synchronously,
- * including occluded windows where animation frames are throttled.
- * @returns disposer that clears the observer and published properties.
+ * Marker on the tablist while it is parked in the sidebar's window-control row.
+ * `conversation.css` draws the fixed-position state from it; its absence means
+ * the host's own row (the header, or whatever the platform still offers) keeps
+ * the switcher.
  */
-export declare function mountViewSwitch(document: Document, report: (error: unknown) => void): Disposer;
+export declare const VIEW_DOCK_ATTRIBUTE = "data-ccd-view-dock";
+/** Custom property carrying the parked tablist's inset from the window's right edge. */
+export declare const VIEW_DOCK_RIGHT_PROPERTY = "--ccd-view-dock-right";
+/** Marker on a tab whose label is drawn as artwork, naming the View it selects. */
+export declare const VIEW_TAB_ATTRIBUTE = "data-ccd-view";
+/** Marker on the artwork seat injected into a decorated tab. */
+export declare const VIEW_GLYPH_ATTRIBUTE = "data-ccd-view-glyph";
+/**
+ * The parked pill's inset from the sidebar column's right edge, in px. Measured
+ * at @2x on the reference: the column's divider sits 16 device px right of the
+ * pill's right edge (docs/issues/img/todo-sidebar-sessions-target.webp).
+ */
+export declare const VIEW_DOCK_INSET = 8;
+/** Bundled artwork, one per shipped View; see features/conversation/view-switch-icons.ts. */
+export interface ViewSwitchIcons {
+    readonly chat: string;
+    readonly trajectory: string;
+}
+/**
+ * Shape the host's View switcher, and park it where the reference has it.
+ *
+ * Three jobs, one observer:
+ * - Publish the selected segment's geometry for the sliding thumb
+ *   (`--ccd-view-x` / `-w` / `-duration`), measured against the tablist.
+ * - Replace each shipped tab's text label with bundled artwork (the host draws
+ *   the labels itself; a tab has no icon of its own), reversibly.
+ * - Park the tablist in the sidebar column's top-right corner — the reference
+ *   keeps the View switcher on the window-control row — by measuring the
+ *   column and publishing its inset (`data-ccd-view-dock` +
+ *   `--ccd-view-dock-right`). The node stays where React put it: only CSS moves
+ *   it, exactly as the macOS sidebar toggle is parked.
+ *
+ * The mutation observer covers tablist replacement, selection, frame drags
+ * (inline grid tracks) and the collapse flag, synchronously, including occluded
+ * windows where animation frames are throttled. A ResizeObserver on the sidebar
+ * column covers what no attribute says: the column's own width while the grid
+ * track animates between 0 and its settled value.
+ *
+ * @returns disposer that clears the observers, every injected node, every
+ *     written attribute and every published property.
+ */
+export declare function mountViewSwitch(document: Document, icons: ViewSwitchIcons, report: (error: unknown) => void): Disposer;

package/lib/types/client/contracts/ports.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ThemePreference, ThemeRuntime } from '@deepseek-ai/dsh-client-ui-theme/client';
 import type { UiWorkspace } from '@deepseek-ai/dsh-client-ui-workspace/client';
+import type { ContextBreakdown, ContextBreakdownView, ContextEntry } from '../../shared/context.ts';
 export type { ThemePreference };
 export type Disposer = () => void;
 /**
@@ -81,9 +82,16 @@ export interface SidebarRightPort {
     }): void;
     /** Focus a tab and the pane holding it; a missing tab is left alone. */
     focus(tabId: string): void;
-    /** Open tab metadata across adopted Sessions. */
+    /**
+     * Open tab metadata across adopted Sessions — and, in the shipped face, the
+     * snapshot store behind it: the plugin's pane layer re-reads the layout
+     * whenever that list changes, which covers every way a tab opens, closes or
+     * changes pane. A build whose source cannot be observed is read once per
+     * mutation instead.
+     */
     readonly openTabs: {
         getSnapshot(): readonly SidebarTabRecord[];
+        subscribe?(listener: () => void): Disposer;
     };
     /**
      * Collapse the column, or expand it and focus its active dock pane.
@@ -94,6 +102,27 @@ export interface SidebarRightPort {
      * keeps that row out rather than offering one that cannot act.
      */
     toggleExpanded?(): void;
+    /**
+     * Take one docked tab out into a floating pane, and put one back.
+     *
+     * The panel's own renderer draws at most one pane or two horizontal panes —
+     * its layout component throws on anything else — so a vertical split or a
+     * third pane cannot be asked of it. A floating pane has no such limit (the
+     * layout stores a rectangle per float and the package allows any number), so
+     * `compat/right-panes.ts` builds the panel's panes out of these two calls and
+     * draws their boxes itself. A missing `float` means a build that cannot host
+     * panes at all: the panel keeps its tabs, exactly as it does today.
+     * Source: packages/client/ui-sidebar-right/src/client/controller.ts
+     * (`float(tabId, rect)`, `dock(paneId)`).
+     */
+    float?(tabId: string, rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /** Return one floating pane's tab to the panel's docked column. */
+    dock?(paneId: string): void;
 }
 /**
  * The tab-type registry that face publishes as `ctx.sidebarRightTabs`. A header
@@ -124,6 +153,146 @@ export interface BlankSessionsPort {
     /** Observe list replacements and row-state changes; returns the releaser. */
     subscribe(listener: () => void): Disposer;
 }
+/** One group of the host's view-options menu, as the host drew it. */
+export interface ViewOptionsGroupRead {
+    /** The heading the host drew above this group, in the document's language. */
+    readonly label: string;
+    /** Every row's own label, in the host's order. */
+    readonly labels: readonly string[];
+    /** Index of the row the host marks as current, or −1 when none is marked. */
+    readonly selected: number;
+}
+/** The host's view-options menu, read out of its own card. */
+export interface ViewOptionsRead {
+    /** The three groups in the host's own order: group by, order by, archived filter. */
+    readonly groups: readonly ViewOptionsGroupRead[];
+}
+/** Which of the host's three groups a choice belongs to. */
+export type ViewOptionsGroup = 0 | 1 | 2;
+/** What the card is drawn from: whether it is up, what it hangs from, and the
+    host's three values as they were read when it opened. */
+export interface ViewOptionsSnapshot {
+    readonly open: boolean;
+    readonly anchor: Element | null;
+    /** Null before the first open, and after the host's card could not be read. */
+    readonly values: ViewOptionsRead | null;
+}
+/**
+ * The sidebar's view-options menu, as this plugin's card needs it.
+ *
+ * DSH keeps the three view settings in the browser and publishes no way to read
+ * or write them, so the only handle is the host's own menu: opening this card
+ * reads it, and `choose` clicks one of its rows. `getSnapshot`/`subscribe`
+ * carry the whole of what the DOM side owns — the trigger, whether the card is
+ * up, and the values read for it.
+ */
+export interface ViewOptionsPort {
+    /** The current state; the object identity changes only when the state does. */
+    getSnapshot(): ViewOptionsSnapshot;
+    /** Observe opening, closing, and the trigger being replaced. */
+    subscribe(listener: () => void): Disposer;
+    /** Put the card away; the trigger's own state follows. */
+    close(): void;
+    /** Choose one option by driving the host's own row; false when it could not be reached. */
+    choose(group: ViewOptionsGroup, index: number): Promise<boolean>;
+}
+/** Native view preferences also used by the sidebar's empty-group policy. */
+export interface ViewOptionsSettingsPort {
+    getSnapshot(): ViewOptionsRead | null;
+    subscribe(listener: () => void): Disposer;
+}
+/** Authoritative membership, including sessions omitted from collapsed DOM. */
+export interface SidebarSessionsPort {
+    /** Durable history across all groups and filters; null while loading. */
+    hasHistory(): boolean | null;
+    /** Null while either catalog is still arriving; null filter keeps all history. */
+    populatedGroups(filter: number | null, nested: boolean): ReadonlySet<string> | null;
+    subscribe(listener: () => void): Disposer;
+}
+/**
+ * One session's context readings, as the client session list holds them.
+ *
+ * The host computes all of this itself: `contextPressure` is the ring's own
+ * occupancy and `contextBreakdown` its three-way composition, and both travel
+ * to the browser as wire projections on the session list. The panel reads them
+ * rather than recomputing them, so its header can never disagree with the ring
+ * beside it.
+ */
+export interface ContextProjectionRead {
+    /** `contextPressure.contextWindow`. */
+    readonly window: number;
+    /** Occupancy: `projectedTokens ?? pressureTokens`. */
+    readonly used: number;
+    /** `contextBreakdown.systemTokens`. */
+    readonly systemTokens: number;
+    /** `contextBreakdown.toolsTokens`. */
+    readonly toolsTokens: number;
+    /** `contextBreakdown.messageTokens`. */
+    readonly messageTokens: number;
+    /** This plugin's own `ccdContext` value, or null while it is not there. */
+    readonly breakdown: ContextBreakdownView | null;
+}
+/**
+ * The host's context projections, read off the client session list.
+ *
+ * `ctx.sessions.list` publishes every registered wire value per session
+ * (`SessionListState.projectionsBySession`) and carries rows for sessions that
+ * were never opened, so this is a plain snapshot read with no I/O. A build that
+ * does not publish the list yields null and the ring keeps DSH's own panel.
+ */
+export interface ContextProjectionPort {
+    /** One session's readings, or null when the list has nothing for it yet. */
+    read(sessionId: string): ContextProjectionRead | null;
+    /** Observe list replacements and live projection frames. */
+    subscribe(listener: () => void): Disposer;
+}
+/** One entry of a drill-down group, as the panel draws it. */
+export interface ContextDetailGroup {
+    /** The group's own name, in the document's language. */
+    readonly label: string;
+    /** The group's total, which is the authoritative number above it. */
+    readonly tokens: number;
+    /** The rows, largest first. */
+    readonly rows: readonly ContextEntry[];
+}
+/** What the context panel is drawn from. */
+export interface ContextPanelSnapshot {
+    readonly open: boolean;
+    /** The ring trigger the panel hangs from; null before the shell renders it. */
+    readonly anchor: Element | null;
+    /** The whole reading, or null while the ring has no numbers for this session. */
+    readonly breakdown: ContextBreakdown | null;
+    /** `mcp__` tools, largest first. */
+    readonly mcp: readonly ContextEntry[];
+    /** Built-in tools, largest first. */
+    readonly tools: readonly ContextEntry[];
+    /** Retained instruction files, largest first. */
+    readonly files: readonly ContextEntry[];
+    /** Retained skill-catalog entries, largest first. */
+    readonly skills: readonly ContextEntry[];
+    /** The panel's own expansion; it lives only while the panel is open. */
+    readonly expanded: boolean;
+}
+/**
+ * The context ring's breakdown panel, as this plugin's card needs it.
+ *
+ * DSH opens its own 264px panel from the ring's click, and that panel is the
+ * whole of its own affordance — no public face reads or drives it. So this port
+ * owns the interaction instead: the driver intercepts the trigger's click
+ * (DSH's handler is React-delegated at the root, so stopping the event on the
+ * button keeps the host's panel from ever opening), holds the open and expanded
+ * state, and publishes the host's own numbers beside this plugin's rows.
+ */
+export interface ContextPanelPort {
+    /** The current state; the object identity changes only when the state does. */
+    getSnapshot(): ContextPanelSnapshot;
+    /** Observe opening, closing, expanding, and the trigger being replaced. */
+    subscribe(listener: () => void): Disposer;
+    /** Put the panel away; the trigger's own state follows. */
+    close(): void;
+    /** Flip the panel between its collapsed and expanded states. */
+    toggleExpanded(): void;
+}
 /** Actual SDK types, never a second definition of DSH component props. */
 export interface HostServices {
     readonly slots: Context['slots'];
@@ -142,6 +311,12 @@ export interface HostServices {
      * session list; a null port leaves the native rows exactly as they are.
      */
     readonly blankSessions: BlankSessionsPort | null;
+    readonly sidebarSessions: SidebarSessionsPort | null;
+    /**
+     * The host's context projections, or null on a build that does not publish
+     * the session list; a null port leaves the ring's own panel in charge.
+     */
+    readonly contextProjections: ContextProjectionPort | null;
     /** The settings transport carrying this plugin's own configuration section. */
     readonly configForms: ConfigFormsPort;
 }

package/lib/types/client/features/context-panel/ContextPanel.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from 'react';
+import type { ContextPanelPort } from '../../contracts/ports.ts';
+export interface ContextPanelProps {
+    readonly port: ContextPanelPort;
+}
+/**
+ * The panel, in whichever of its two states the port says.
+ *
+ * @param props - the driver's port.
+ * @returns the card, or null while it is closed.
+ */
+export declare function ContextPanel({ port }: ContextPanelProps): ReactElement | null;

package/lib/types/client/features/context-panel/mount.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { FeatureEnvironment } from '../../contracts/feature.ts';
+import type { CleanupScope } from '../../core/cleanup.ts';
+/**
+ * Put the context ring's breakdown panel in the frame-wide overlay.
+ *
+ * The panel is this plugin's own surface, so it is registered like one: a React
+ * entry in `shell.overlay`, holding the driver that watches the ring's trigger
+ * and takes its click (`compat/context-panel.ts`). Nothing here writes session
+ * state — the numbers are the host's own projections, read off the session list
+ * — so a write can never re-mount the plugin behind the panel.
+ *
+ * A build that does not publish the session list yields no port, and the ring
+ * keeps DSH's own panel: the feature loses a richer reading, not the control.
+ *
+ * @param ctx - client root context carrying the slot service.
+ * @param environment - configuration, ports and logging for this activation.
+ * @param cleanup - scope owning the styles, the driver and the registration.
+ */
+export declare function mountContextPanel(ctx: Context, environment: FeatureEnvironment, cleanup: CleanupScope): void;

package/lib/types/client/features/conversation/index.d.ts

@@ -5,9 +5,11 @@ import type { ImplementedFeature } from '../../contracts/feature.ts';
  * adapts the header chrome, the transcript column and the message surfaces.
  *
  * The header keeps DSH's own View switcher: the host still owns which View is
- * selected and how it is rendered, and this module only moves the tablist onto
- * the title line and publishes the selected segment's geometry so the
- * stylesheet can slide the thumb onto it.
+ * selected and how it is rendered. This module swaps the two shipped Views'
+ * text labels for bundled artwork, publishes the selected segment's geometry so
+ * the stylesheet can slide the thumb onto it, and parks the tablist in the
+ * sidebar's window-control row while that column has a corner to hold it
+ * (`compat/view-switch.ts`).
  *
  * The transcript's own edge fade is published the same way: the host owns the
  * scroll position, `compat/conversation-fade.ts` turns it into two attributes,

package/lib/types/client/features/conversation/view-switch-icons.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The two View switcher glyphs, bundled as trusted static markup.
+ *
+ * Drawn to the reference's own segments (docs/issues/img/todo-sidebar-sessions-target.webp,
+ * @2x): a pair of speech bubbles for the chat View and the `</>` pair for the
+ * trajectory View, both on the CCD 16 grid — 1–1.2px stroke (each glyph's own
+ * weight read off the reference), round caps and joins, `currentColor` ink,
+ * ink box ≈ 12.5 × 11px inside the 16px artwork.
+ */
+export declare const VIEW_SWITCH_ICONS: Readonly<{
+    chat: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\" width=\"16\" height=\"16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\">\n  <path d=\"M10.4 8.3a2.6 2.6 0 0 1-2.6 2.6H5.7L3.3 12.5V5.9a2.6 2.6 0 0 1 2.6-2.6h1.9a2.6 2.6 0 0 1 2.6 2.6Z\"/>\n  <path d=\"M10.3 5.9H12.1a2.1 2.1 0 0 1 2.1 2.1V10.4a2.1 2.1 0 0 1-2.1 2.1H10.25L9.1 13.1\"/>\n</svg>";
+    trajectory: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\" width=\"16\" height=\"16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\">\n  <path d=\"M5.3 5.8 3.05 8l2.25 2.2\"/>\n  <path d=\"M9.1 3.8 6.9 12.2\"/>\n  <path d=\"M10.7 5.8 12.95 8l-2.25 2.2\"/>\n</svg>";
+}>;

package/lib/types/client/features/settings/locales.d.ts

@@ -14,6 +14,9 @@ export declare const zh: {
     readonly 'section.features': '模块';
     readonly 'section.appearance': '外观';
     readonly 'section.fonts': '字体';
+    readonly 'section.view': '视图';
+    readonly 'field.showEmptyGroups': '显示空分组';
+    readonly 'hint.showEmptyGroups': '关掉时没有会话的工作区不再显示；视图选项菜单里的同一项';
     readonly 'field.enabled': '启用 CCD 风格界面';
     readonly 'field.theme': '主题';
     readonly 'theme.system': '跟随系统';
@@ -49,6 +52,10 @@ export declare const zh: {
     readonly 'feature.tool-calls': '工具调用展示';
     readonly 'feature.statistics': '统计卡片';
     readonly 'feature.composer-pet': '输入框小鲸鱼';
+    readonly 'feature.composer-stats': '状态栏统计读数';
+    readonly 'hint.composer-stats': '输出速度与缓存命中率，关掉时这两项不显示（默认）';
+    readonly 'feature.context-panel': '上下文分解面板';
+    readonly 'hint.context-panel': '点环打开的分段面板；关掉时环点开的是 DSH 原生面板';
 };
 export type SettingsKey = keyof typeof zh;
 /** English dictionary; every Chinese key has a counterpart. */