dsh-claude-desktop-theme 0.2.0

package/lib/types/client/compat/pet-anchor.d.ts

@@ -0,0 +1,30 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** Where the frame-wide seat is drawn, in viewport coordinates. */
+export interface PetAnchor {
+    readonly left: number;
+    readonly top: number;
+}
+/** One observed, disposable source of the seat's position. */
+export interface PetAnchorSource {
+    /** Current position, or null while the seat has no card to sit on. */
+    getSnapshot(): PetAnchor | null;
+    /** Observe position changes; returns the releaser. */
+    subscribe(listener: () => void): Disposer;
+    /** Release every observer and listener this source installed. */
+    dispose(): void;
+}
+/** The artwork's box: a 32 × 24 pixel grid drawn at 1:1, as `Whale.tsx` renders it. */
+export declare const PET_BOX: Readonly<{
+    width: 32;
+    height: 24;
+}>;
+/** Inset from the Composer card's trailing edge; `pet.css` draws the seat with
+    the measured numbers, and the test asserts the two agree. */
+export declare const PET_INSET = 12;
+/**
+ * Publish the top trailing corner of the hero Composer card in viewport
+ * coordinates for shell.overlay. The DSH conversation root's data-phase=hero
+ * selects new sessions; hidden, missing or unlaid-out cards publish null.
+ * @returns position source whose dispose releases all listeners and observers.
+ */
+export declare function createPetAnchor(document: Document, report: (error: unknown) => void): PetAnchorSource;

package/lib/types/client/compat/plugin-manager.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReactElement } from 'react';
+import type { Disposer } from '../contracts/ports.ts';
+/**
+ * The Plugins panel's row configuration slot.
+ *
+ * `@deepseek-ai/dsh-client-ui-plugin-manager` declares it in the child table of
+ * its `main` panel registration as `{ kind: 'keyed', scope: 'root' }` and keys
+ * it by `<package>#<row id>`; the row then grows a configuration page. The
+ * package is not part of this plugin's type baseline, so the two members used
+ * here are declared structurally and the real service object is passed through
+ * unchanged — the same treatment `contracts/ports.ts` gives the other
+ * out-of-baseline providers. Registration waits for the declaration, so a
+ * deployment without that panel simply keeps the page unmounted.
+ */
+export declare const ROW_CONFIG_SLOT = "plugins.row.config";
+/** Props the panel renders a row configuration page with. */
+export interface RowConfigPageProps {
+    /** `summary` beside a row title without a description, `page` for the form. */
+    readonly view?: string;
+    /** Locale seat synthesized from the registration's namespace. */
+    readonly t?: (key: string, params?: Record<string, unknown>) => string;
+}
+/**
+ * Register one row configuration page and wait for the slot to exist.
+ * @param ctx - context carrying the slots service.
+ * @param key - `<package>#<row id>` of the row whose page this is.
+ * @param locale - dictionary namespace for the page's `t` seat, when available.
+ * @param component - the page component.
+ * @returns the injection's disposer.
+ */
+export declare function mountRowConfigPage(ctx: Context, key: string, locale: string | undefined, component: (props: RowConfigPageProps) => ReactElement | null): Disposer;

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

@@ -0,0 +1,47 @@
+import type { Disposer } from '../contracts/ports.ts';
+/**
+ * The Session header's own ⋮ menu, extended with one row.
+ *
+ * `session-log-export` owns that menu: a `ui-primitives` `Menu` whose rows are
+ * data (`下载 Session 日志`, `反馈`) and whose list is rendered in place, as the
+ * second child of the menu's own root span beside its trigger. There is no slot
+ * a third-party row could register into, so this module adds one to the list the
+ * host drew — its first row, ahead of the host's own — cloned from a native row,
+ * which is what makes the addition look native without pinning a single menu
+ * class: the clone carries the host's own classes, so whatever draws that menu
+ * draws this row too (today `theme/menus.css`), and the primitive's keyboard
+ * walk (`Menu` walks `button:not(:disabled)` inside the list) and its
+ * post-selection focus return reach it without any shared state.
+ *
+ * The row exists only while it is wanted: `wanted()` answers from the document,
+ * and the plugin retires the shipped re-entry control this row replaces
+ * (`ui-sidebar-right`'s `ExpandButton`, shadowed in the header's corner cell by
+ * an entry that renders nothing), so the two never stand side by side.
+ *
+ * Closing the menu stays the owner's decision, exactly as it is for the host's
+ * own data rows: the trigger is clicked again, which is what its own
+ * `setOpen(value => !value)` handler does for a second click. Nothing is
+ * dispatched at the document — a synthetic Escape or outside pointerdown would
+ * be a gesture the reader never made.
+ */
+/** Marker the added row carries, so a later pass finds its own node. */
+export declare const MENU_ROW_ATTRIBUTE = "data-ccd-menu-row";
+/** One row this module adds to the Session header's menu. */
+export interface SessionMenuRow {
+    /** Localised row label, written over the cloned row's own copy. */
+    readonly label: string;
+    /** Whether the row belongs in the open menu right now. */
+    readonly wanted: () => boolean;
+    /** Runs when the row is chosen, before the menu is dismissed. */
+    readonly act: () => void;
+}
+/**
+ * Keep one row in the Session header's menu for as long as it is wanted.
+ *
+ * @param document - the renderer document whose header menu is extended.
+ * @param row - the label, the predicate that decides whether the row exists,
+ *   and the action it runs.
+ * @param report - receives a failure from the action or from one observer pass.
+ * @returns disposer that removes the row and stops the observer.
+ */
+export declare function mountSessionMenuRow(document: Document, row: SessionMenuRow, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/slots.d.ts

@@ -0,0 +1,21 @@
+/** Verified names; ownership and props must be read from the SDK before registration. */
+export declare const DSH_SLOTS: Readonly<{
+    readonly sidebar: 'sidebar';
+    readonly workspaces: 'sidebar.workspaces';
+    readonly settings: 'sidebar.settings';
+    readonly main: 'main';
+    readonly conversation: 'main.conversation';
+    readonly header: 'conversation.header';
+    readonly sessionHeader: 'conversation.session.header';
+    /** Trailing header seats: `utilities` is a list the native actions occupy too. */
+    readonly sessionHeaderUtilities: 'conversation.session.header.utilities';
+    readonly sessionHeaderCorner: 'conversation.session.header.corner';
+    readonly composerBar: 'conversation.composer.bar';
+    readonly inputDock: 'conversation.input.dock';
+    readonly composerDock: 'conversation.composer.dock';
+    readonly toolView: 'tool.call.toolview';
+    readonly leading: 'shell.leading';
+    /** Frame-wide floating layer, click-through until an entry opts back in. */
+    readonly shellOverlay: 'shell.overlay';
+}>;
+export declare const OVERRIDE_PRIORITY = -10;

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

@@ -0,0 +1,20 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** Short readout mirrored from native text for wide columns only. */
+export declare const STAT_VALUE_PROPERTY = "--ccd-stat-value";
+/** Custom property carrying the width of the Composer's trailing control group. */
+export declare const TRAILING_WIDTH_PROPERTY = "--ccd-trailing-width";
+/** Remaining model-button space after leading controls, statistics and gaps. */
+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";
+/**
+ * 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.
+ *
+ * @param document - renderer document carrying the Composer.
+ * @param report - sink for observer failures; the native readouts stay.
+ * @returns disposer that disconnects the observers and clears every property.
+ */
+export declare function mountComposerStats(document: Document, report: (error: unknown) => void): Disposer;

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

@@ -0,0 +1,14 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** Custom property carrying the active View segment's offset inside the tablist. */
+export declare const VIEW_OFFSET_PROPERTY = "--ccd-view-x";
+/** Custom property carrying the active View segment's width. */
+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.
+ */
+export declare function mountViewSwitch(document: Document, report: (error: unknown) => void): Disposer;

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

@@ -0,0 +1,15 @@
+import type { Disposer } from '../contracts/ports.ts';
+/**
+ * Print the workspace picker's "add workspace" row with spaced dots.
+ *
+ * The card is watched only while the picker is open, and every write is undone
+ * on release, so a disabled plugin leaves the host's own label on screen. The
+ * observer runs synchronously from the mutation batch (never on an animation
+ * frame, which an occluded window throttles), so the row is rewritten in the
+ * commit that mounts it and never shows the host's glyph first.
+ *
+ * @param document - renderer document carrying the hero chip and the portal.
+ * @param report - sink for observer failures; the native label stays untouched.
+ * @returns disposer that disconnects every observer and restores each label.
+ */
+export declare function mountWorkspaceMenu(document: Document, report: (error: unknown) => void): Disposer;

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

@@ -0,0 +1,22 @@
+import type { FeatureId, StyleConfig } from '../../shared/config.ts';
+import type { CleanupScope } from '../core/cleanup.ts';
+import type { DomPort, HostServices, Logger } from './ports.ts';
+export interface FeatureEnvironment {
+    readonly config: StyleConfig;
+    readonly host: HostServices;
+    readonly dom: DomPort;
+    readonly logger: Logger;
+}
+interface FeatureMetadata {
+    readonly id: FeatureId;
+    readonly task: string;
+}
+export interface PlannedFeature extends FeatureMetadata {
+    readonly status: 'planned';
+}
+export interface ImplementedFeature extends FeatureMetadata {
+    readonly status: 'implemented';
+    mount(environment: FeatureEnvironment, scope: CleanupScope): void;
+}
+export type FeatureDefinition = PlannedFeature | ImplementedFeature;
+export {};

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

@@ -0,0 +1,169 @@
+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';
+export type { ThemePreference };
+export type Disposer = () => void;
+/**
+ * One settings-path operation, the shape `remote.settings.mutate` accepts on
+ * the wire. A nested field is addressed by its path segments — `set()` only
+ * ever sends a one-segment path — and `unset` removes the profile override so
+ * the schema default takes over again.
+ * Source: packages/client/ui-settings/src/client/config-forms.ts and
+ * packages/api/settings-controller (`SettingsPathOp`).
+ */
+export type SettingsPathOp = {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+} | {
+    readonly op: 'unset';
+    readonly path: readonly string[];
+};
+/** Read side of one namespace's form; only the members this plugin uses. */
+export interface ConfigFormSnapshot {
+    /** `loading` until the describe view arrives, `ready` once a valid value is served, `unavailable` without one. */
+    readonly status: string;
+    /** The effective section, projected to the volatile fields; undefined until `ready`. */
+    readonly value: unknown;
+    /** Host revision of this namespace, the fence every write carries. */
+    readonly revision?: number;
+    /** Whether the Host will persist a write from this page. */
+    readonly writable?: boolean;
+}
+/**
+ * One namespace's configuration form, structurally matching
+ * `@deepseek-ai/dsh-client-ui-settings`' `ConfigForm` — the service every
+ * settings-backed client plugin reads its own section through. Only the
+ * members this plugin uses are declared, and the real service object is passed
+ * through unchanged, so no second definition of its behaviour lives here.
+ * Source: packages/client/ui-settings/src/client/config-forms.ts.
+ */
+export interface ConfigFormPort {
+    /** Current section snapshot; `value` is the effective section until it is served. */
+    getSnapshot(): ConfigFormSnapshot;
+    /** Observe snapshot replacements. */
+    subscribe(listener: () => void): Disposer;
+    /** Queue one scalar write into the section; resolves with the Host's verdict. */
+    set(field: string, value: unknown): Promise<boolean>;
+    /** Queue one field clear, restoring the inherited or default value. */
+    unset(field: string): Promise<boolean>;
+    /** Queue one atomic namespace mutation, fenced by the revision it was read at. */
+    mutate(ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+/** Namespace-addressed access to the settings transport. */
+export interface ConfigFormsPort {
+    /** @param namespace - the loader entry id whose section is wanted. */
+    get(namespace: string): ConfigFormPort;
+}
+/**
+ * One right-Sidebar tab as the cross-plugin face reports it: membership only,
+ * independent of visible panes.
+ * Source: packages/client/ui-sidebar-right/src/client/persistence.ts.
+ */
+export interface SidebarTabRecord {
+    readonly sessionId: string;
+    readonly tabId: string;
+    readonly kind: string;
+    readonly contentId?: string;
+}
+/**
+ * The cross-plugin right-Sidebar face the official panel plugins publish as
+ * `ctx.sidebarRight`, a reflect-provided service
+ * (`dsh-client-ui-sidebar-right`, "Cross-plugin right-Sidebar face"). That
+ * package is not part of this plugin's type baseline, so only the members the
+ * header uses are declared here and the real object is passed through
+ * unchanged; a partial service means no header views rather than a dead button.
+ */
+export interface SidebarRightPort {
+    /** Open one page kind for the on-screen Session; an unregistered kind throws. */
+    openTab(kind: string, options?: {
+        readonly params?: Record<string, string>;
+    }): 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. */
+    readonly openTabs: {
+        getSnapshot(): readonly SidebarTabRecord[];
+    };
+    /**
+     * Collapse the column, or expand it and focus its active dock pane.
+     *
+     * The header's shipped re-entry control (`ExpandButton`) is shadowed by this
+     * plugin's corner entry, so the Session menu's own row is what reveals a
+     * collapsed column again; a build whose face does not carry this member
+     * keeps that row out rather than offering one that cannot act.
+     */
+    toggleExpanded?(): void;
+}
+/**
+ * The tab-type registry that face publishes as `ctx.sidebarRightTabs`. A header
+ * view is only offered while its kind is registered, so a build without the
+ * terminal or browser plugin keeps no dead button. Membership is read by
+ * presence and observed through the registry's own low-frequency signal.
+ * Source: packages/client/ui-sidebar-right/src/client/tab-registry.ts.
+ */
+export interface SidebarRightTabsPort {
+    /** @param kind - page type the panel can place; undefined when unregistered. */
+    get(kind: string): unknown;
+    /** @param listener - synchronous invalidation callback. */
+    subscribe(listener: () => void): Disposer;
+}
+/**
+ * The host's provisional New Sessions, as the sidebar column reads them.
+ *
+ * DSH creates the Session the moment its New Session entry is used and keeps
+ * the row in the list while `SessionSummary.blank` is true — the host's own
+ * fact for "created, no message yet". The Workspace browser shows the selected
+ * blank entry; the CCD column keeps every blank row out of the list, so the
+ * entry arrives with the first sent message. Filtering is presentation: the
+ * plugin writes no session state and hides nothing the host would call durable.
+ */
+export interface BlankSessionsPort {
+    /** Session ids the host still presents as a provisional New Session. */
+    ids(): ReadonlySet<string>;
+    /** Observe list replacements and row-state changes; returns the releaser. */
+    subscribe(listener: () => void): Disposer;
+}
+/** Actual SDK types, never a second definition of DSH component props. */
+export interface HostServices {
+    readonly slots: Context['slots'];
+    readonly theme: Pick<ThemeRuntime, 'overrideTokens'>;
+    /**
+     * The native light／dark／system preference as the configuration page sees it,
+     * or null on a build whose theme service does not publish it. DSH owns the
+     * value (the user-settings document owns the durable preference and
+     * `prefers-color-scheme` answers for `system`), so the page reads and writes
+     * it instead of holding a copy.
+     */
+    readonly themePreference: ThemePreferencePort | null;
+    readonly workspace: Pick<UiWorkspace, 'openSession' | 'openWorkspace' | 'startSession'>;
+    /**
+     * Provisional New Sessions, or null on a build that does not publish the
+     * session list; a null port leaves the native rows exactly as they are.
+     */
+    readonly blankSessions: BlankSessionsPort | null;
+    /** The settings transport carrying this plugin's own configuration section. */
+    readonly configForms: ConfigFormsPort;
+}
+/**
+ * Read／write face of the theme service's preference: the same members the
+ * official Appearance row uses (`getTheme`／`setTheme`／`theme/change`), so a
+ * second control cannot disagree with the first one.
+ */
+export interface ThemePreferencePort {
+    /** The persisted preference — never the resolved active theme. */
+    preference(): ThemePreference;
+    /** Switch the preference through the theme service's only write entry. */
+    set(preference: ThemePreference): void;
+    /** Observe preference, registry and OS-scheme changes; returns the releaser. */
+    subscribe(listener: () => void): Disposer;
+}
+export interface DomPort {
+    activate(): Disposer;
+    mountStyles(css: string): Disposer;
+}
+export interface Logger {
+    debug(message: string): void;
+    /** `error` carries a cause when there is one; a report without one is fine. */
+    error(message: string, error?: unknown): void;
+}

package/lib/types/client/core/cleanup.d.ts

@@ -0,0 +1,10 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** Own resources per activation; release in reverse acquisition order. */
+export declare class CleanupScope {
+    private readonly cleanups;
+    private disposed;
+    private readonly onError;
+    constructor(onError?: (error: unknown) => void);
+    add(cleanup: Disposer): Disposer;
+    dispose(): void;
+}

package/lib/types/client/core/mount-features.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition, FeatureEnvironment } from '../contracts/feature.ts';
+import { CleanupScope } from './cleanup.ts';
+export declare function mountFeatures(features: readonly FeatureDefinition[], environment: FeatureEnvironment, parent: CleanupScope): void;

package/lib/types/client/features/composer-pet/BlankPet.d.ts

@@ -0,0 +1,17 @@
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PetAnchor } from '../../compat/pet-anchor.ts';
+/** Business face the frame overlay injects: the measured new-session corner. */
+export interface BlankPetFace {
+    /** Selector hook over the compat layer's measurement. */
+    readonly useAnchor: () => PetAnchor | null;
+}
+export type BlankPetProps = PropsRuntime<'shell.overlay'> & BlankPetFace;
+/**
+ * The whale's only seat, drawn from the frame-wide overlay at the measured
+ * corner of the new-session Composer card. Renders nothing until the anchor
+ * finds a card — and the anchor only finds one on a page the host marks
+ * `data-phase="hero"`, so a conversation never shows the pet.
+ * @param props - injected measurement.
+ * @returns the positioned whale, or null.
+ */
+export declare function BlankPet({ useAnchor }: BlankPetProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/types/client/features/composer-pet/ComposerPet.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The hero-page whale. Accepted clicks choose one of three local reactions;
+ * busy clicks do nothing, and hiding or unmounting cancels all active frames.
+ * It reads no session state and does not trigger any Composer action.
+ * @returns the whale mark.
+ */
+export declare function ComposerPet(): import("react/jsx-runtime").JSX.Element;

package/lib/types/client/features/composer-pet/Whale.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hand-drawn 32 × 24 pixel interpretation of the DeepSeek whale.
+ *
+ * Brand reference: deepseek-ai/DeepSeek-V2/figures/logo.svg (blue body, pale
+ * belly, light eye, swept pectoral fin and raised split tail). The mark is
+ * drawn at 1:1 with the grid and rendered at 32 × 24 CSS px, so one artwork
+ * pixel is one CSS pixel (two device pixels on a Retina display) and
+ * `crispEdges` keeps every step on a whole device pixel. The eye sits near the
+ * tail, as in the mark; the head is the blunt left end.
+ *
+ * ComposerPet owns the local click reactions. The spray is offset three grid
+ * pixels towards the middle of the head, matching the approved preview.
+ *
+ * The parts are classes, not fixed fills: `pet.css` paints the body from
+ * `--ccd-pet-blue` and the belly／eye from `--ccd-pet-light`, so the mark
+ * follows the palette in both schemes.
+ */
+export declare function Whale(): import("react/jsx-runtime").JSX.Element;

package/lib/types/client/features/composer-pet/mount.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { FeatureEnvironment } from '../../contracts/feature.ts';
+import type { CleanupScope } from '../../core/cleanup.ts';
+/**
+ * Mount the new-session whale in shell.overlay at the measured Composer corner.
+ * pet-anchor selects the DSH conversation root's data-phase=hero state.
+ * @param cleanup - scope owning the styles, slot registration and anchor.
+ */
+export declare function mountComposerPet(ctx: Context, environment: FeatureEnvironment, cleanup: CleanupScope): void;

package/lib/types/client/features/composer-pet/reactions.d.ts

@@ -0,0 +1,15 @@
+/** Local reactions only: the pet does not read or change a session. */
+export type PetReaction = 'spout' | 'hop' | 'wag';
+/** Equal thirds, sampled once per accepted click. */
+export declare function pickPetReaction(random?: () => number): PetReaction;
+export interface PetPlayback {
+    /** Resolves on completion or cancellation, including component disposal. */
+    readonly finished: Promise<void>;
+    cancel(): void;
+}
+/**
+ * Play the approved preview's poses on the existing 32 × 24 artwork. Per-frame
+ * easing keeps pixel swaps discrete without quantizing the whole timeline.
+ * No filled final frames: cancellation and completion restore the idle art.
+ */
+export declare function playPetReaction(art: SVGSVGElement, reaction: PetReaction, reducedMotion: boolean): PetPlayback;

package/lib/types/client/features/conversation/header-actions/HeaderActionButton.d.ts

@@ -0,0 +1,25 @@
+import type { ReactElement } from 'react';
+/** Props the registration layer derives; the component never sees `ctx`. */
+export interface HeaderActionProps {
+    /** Localised accessible name, also used as the native tooltip. */
+    readonly label: string;
+    /** Which right-panel view this button opens; selects the glyph in CSS. */
+    readonly kind: 'terminal' | 'browser' | 'files';
+    /** Opens or focuses the native right-panel view. */
+    readonly open: () => void;
+}
+/**
+ * One view button for the conversation header.
+ *
+ * All three sit in the utilities group beside the native actions, led by the
+ * project folder; the corner seat past them holds nothing (the panel's shipped
+ * expand control is retired there and its action moves into the Session menu).
+ * All three are the same control: the box size, hover surface and spacing
+ * belong to the seat's own stylesheet
+ * (`features/conversation/conversation.css`) so every control in the row shares
+ * one rhythm; this component only carries the glyph, the name and the click.
+ *
+ * @param props - Derived label, view kind and callback.
+ * @returns The header button.
+ */
+export declare function HeaderActionButton({ label, kind, open }: HeaderActionProps): ReactElement;

package/lib/types/client/features/conversation/header-actions/entries.d.ts

@@ -0,0 +1,101 @@
+import type { SessionMenuRow } from '../../../compat/session-menu.ts';
+import type { SidebarRightPort } from '../../../contracts/ports.ts';
+import type { HeaderActionProps } from './HeaderActionButton.tsx';
+/**
+ * What this plugin contributes to the conversation header.
+ *
+ * The mounts in `mount.ts` are wiring: they resolve the panel's face, keep one
+ * registration per seat, and hand it a component. *What* is offered — which
+ * slot, in what order, at what shadowing rank, under which condition — is
+ * decided here, so the contract can be read and tested without a renderer.
+ */
+/**
+ * The right panel's own file list (`ui-sidebar-files`): the Session's project
+ * directory, as a tree, in the same panel the terminal and browser views open
+ * into.
+ */
+export declare const FILES_KIND = "files";
+/**
+ * List orders inside `conversation.session.header.utilities`.
+ *
+ * The project folder leads the row, so it carries the lowest order of every
+ * entry there is — below the retired open-in-app control (-10) and the native
+ * scheduled-tasks entry (-5), not only below this plugin's own views: the
+ * reference draws the folder as the cluster's first control, whatever a Session
+ * happens to carry. The two views then land directly before the native session
+ * menu at 0 and keep it as the cluster's closing entry.
+ */
+export declare const FOLDER_ORDER = -11;
+export declare const TERMINAL_ORDER = -2;
+export declare const BROWSER_ORDER = -1;
+/** The views this plugin exposes in the utilities group, in cluster order. */
+export declare const VIEWS: readonly [{
+    readonly id: 'ccd-folder';
+    readonly kind: "files";
+    readonly order: -11;
+}, {
+    readonly id: 'ccd-terminal';
+    readonly kind: 'terminal';
+    readonly order: -2;
+}, {
+    readonly id: 'ccd-browser';
+    readonly kind: 'browser';
+    readonly order: -1;
+}];
+/**
+ * Registration key of the corner retirement. The seat is a *single* cell, so
+ * the entry carries no id of its own — this key names it in the mount's own
+ * bookkeeping, where a registration is replaced at most once.
+ */
+export declare const CORNER_ENTRY = "header-corner";
+/** Opens or focuses one right-panel view for the Session whose header was used. */
+export type OpenViewKind = (kind: string, sessionId: string) => void;
+/**
+ * The utilities entry for one right-panel view.
+ *
+ * `id` and `order` are what make the entry a *list* cell: the panel's existing
+ * entries keep their own seats, and this one takes the position its order names.
+ *
+ * @param view - the entry's identity and the page kind it opens.
+ * @param labels - localised copy, by view kind.
+ * @param open - opens the kind for the slot's own Session id.
+ * @returns the options the registry is called with.
+ */
+export declare function utilitiesEntry(view: (typeof VIEWS)[number], labels: Record<(typeof VIEWS)[number]['kind'] | typeof FILES_KIND, string>, open: OpenViewKind): {
+    name: "conversation.session.header.utilities";
+    id: "ccd-browser" | "ccd-folder" | "ccd-terminal";
+    order: -11 | -2 | -1;
+    inject: (sessionId: string) => HeaderActionProps;
+};
+/**
+ * The corner seat's retirement: the cell the reference leaves empty.
+ *
+ * That seat's shipped occupant is `ui-sidebar-right`'s collapsed-panel expand
+ * control, and this interface does not want it: hovering it drew a control the
+ * reference has no room for, and the action it carries lives in the Session menu
+ * instead ({@link sidebarExpandRow}). Registering below the occupant's rank
+ * ({@link OVERRIDE_PRIORITY}) takes the cell, and the entry's component renders
+ * nothing — a structural retirement rather than a control hidden in place, so
+ * nothing of the displaced button stays behind: no hover surface, no tooltip and
+ * no hit area.
+ *
+ * @returns the options the registry is called with.
+ */
+export declare function cornerRetirement(): {
+    name: "conversation.session.header.corner";
+    priority: number;
+};
+/**
+ * The Session menu's row that puts a collapsed right panel back on screen.
+ *
+ * Two facts decide it, and both are read fresh: the frame carries the host's own
+ * `data-rightbar-collapsed` (the panel's column has no width) and the panel's
+ * face can expand it again. The action is the panel's own method rather than a
+ * click on a hidden control, so the column's state stays entirely the panel's.
+ *
+ * @param sidebar - the right-Sidebar face the header was built over.
+ * @param document - the renderer document whose frame reports the panel's state.
+ * @param label - localised row copy.
+ * @returns the row the menu module keeps in the header's ⋮ list while it holds.
+ */
+export declare function sidebarExpandRow(sidebar: SidebarRightPort, document: Document, label: string): SessionMenuRow;

package/lib/types/client/features/conversation/header-actions/mount.d.ts

@@ -0,0 +1,28 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { FeatureEnvironment } from '../../../contracts/feature.ts';
+import type { CleanupScope } from '../../../core/cleanup.ts';
+/**
+ * Add the right panel's views to the conversation header — the project folder
+ * first, then terminal and browser, all in the utilities group — and move the
+ * collapsed panel's re-entry action into the Session menu.
+ *
+ * The header's trailing group is a native list slot — `ui-open-in-app`,
+ * `ui-schedule` and `session-log-export` all register into `utilities` — so the
+ * plugin takes three more entries rather than replacing or reordering anything.
+ * Each entry appears only while its tab kind is registered in the panel's own
+ * registry, so a build without that view keeps the native cluster intact and
+ * never shows a button that cannot open anything.
+ *
+ * The corner seat is different, and deliberately so. It is a *single* cell whose
+ * shipped occupant is `ui-sidebar-right`'s collapsed-panel expand control; the
+ * reference draws nothing there, so the plugin shadows that occupant with an
+ * entry that renders nothing and puts the expand action into the Session menu's
+ * own ⋮ list (`compat/session-menu.ts`), where it appears only while the panel
+ * is collapsed. Nothing about the panel's own state changes hands: the menu row
+ * calls the panel's own service method.
+ *
+ * @param ctx - client context carrying the injected services.
+ * @param environment - feature environment for logging and style mounting.
+ * @param cleanup - scope owning the stylesheet, the registrations and their Fiber.
+ */
+export declare function mountHeaderActions(ctx: Context, environment: FeatureEnvironment, cleanup: CleanupScope): void;

package/lib/types/client/features/conversation/header-actions/sidebar-view.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { SidebarRightPort, SidebarRightTabsPort } from '../../../contracts/ports.ts';
+/** Read the cross-plugin right-Sidebar face, or nothing when this build lacks it. */
+export declare function resolveSidebarRight(scope: Context): SidebarRightPort | undefined;
+/** Read the tab-type registry that decides which views exist in this build. */
+export declare function resolveSidebarTabs(scope: Context): SidebarRightTabsPort | undefined;
+/**
+ * Focus the Session's existing view of this kind, or open a new one.
+ *
+ * `openTab` places a page at the address the panel records pages under, which
+ * would front an already-open view for kinds that allow one instance; the
+ * inventory snapshot lets the header focus that tab instead of stacking a
+ * second one. Terminal views may legitimately be multiple, so the first match
+ * wins — the panel's own guide still offers a new one. A build whose face does
+ * not carry the inventory falls back to plain `openTab`.
+ *
+ * @param sidebar - the right-Sidebar face.
+ * @param kind - page type to reveal.
+ * @param sessionId - Session whose header was clicked.
+ */
+export declare function openView(sidebar: SidebarRightPort, kind: string, sessionId: string): void;