dsh-claude-desktop-theme 0.2.0 → 0.3.0

package/lib/types/host/context/pricing.d.ts

@@ -0,0 +1,99 @@
+/** One content block, as far as pricing reads it. */
+export interface PricedBlock {
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly arguments?: string;
+    /** Every other field the block carries; pricing only ever serializes them. */
+    readonly [field: string]: unknown;
+}
+/** One model-visible message, as far as pricing reads it. */
+export interface PricedMessage {
+    /** Absent for a `user/message` payload, which *is* the message. */
+    readonly role?: string;
+    readonly content: readonly PricedBlock[];
+}
+/** One tool schema, as far as pricing reads it. */
+export interface PricedTool {
+    readonly name: string;
+}
+/** The structural slice of one session event this fold reads. */
+export interface PricedEvent {
+    readonly type: string;
+    readonly seq: number;
+    readonly surfaceOp?: 'append' | {
+        readonly startSeq: number;
+        readonly endSeq: number;
+    };
+    readonly data?: {
+        readonly content?: readonly PricedBlock[];
+        readonly message?: PricedMessage;
+        readonly source?: {
+            readonly kind?: string;
+            readonly changes?: readonly {
+                readonly action?: string;
+                readonly path?: string;
+            }[];
+            readonly entries?: readonly {
+                readonly name?: string;
+                readonly description?: string;
+            }[];
+        };
+    };
+}
+/**
+ * Price one content block list.
+ *
+ * @param blocks - the message's content.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export declare function priceContent(blocks: readonly PricedBlock[]): number;
+/**
+ * Price one model-visible message.
+ *
+ * A system prompt is serialized as a plain string by every adapter, so the host
+ * prices it as text density plus role framing with no per-block overhead; every
+ * other role takes the per-block arm.
+ *
+ * @param message - the derived message, or null when the event produces none.
+ * @returns heuristic tokens.
+ */
+export declare function priceMessage(message: PricedMessage | null): number;
+/**
+ * The message one surface event projects to, or null when it produces none.
+ *
+ * @param event - one committed session event.
+ * @returns the message to price.
+ */
+export declare function derivedMessage(event: PricedEvent): PricedMessage | null;
+/** Whether an event carries a surface placement and therefore joins the fold. */
+export declare function isSurfaceEvent(event: PricedEvent): boolean;
+/**
+ * Price one tool schema on its own.
+ *
+ * The host prices the assembled array whole, so these per-tool numbers never
+ * add back up to it; {@link splitTools} is what keeps the two group rows
+ * summing to the host's own total.
+ *
+ * @param tool - one entry of `EpochHeader.tools`.
+ * @returns heuristic tokens for that entry alone.
+ */
+export declare function priceTool(tool: unknown): number;
+/**
+ * Price the assembled tool array exactly as the host does.
+ *
+ * @param tools - `EpochHeader.tools`.
+ * @returns the array's heuristic price; 0 when there are no tools.
+ */
+export declare function priceTools(tools: readonly PricedTool[] | undefined): number;
+/**
+ * Split one token total across weighted entries, preserving the total exactly.
+ *
+ * The last entry takes whatever rounding left over, so the rows a group draws
+ * always add back up to the group's own number.
+ *
+ * @param total - tokens to distribute.
+ * @param weights - one weight per entry; non-positive weights fall back to 1.
+ * @returns one token count per entry, summing to `total`.
+ */
+export declare function allocate(total: number, weights: readonly number[]): readonly number[];

package/lib/types/host/context/service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mount the context panel's projection unit.
+ *
+ * The unit is the only thing the host half adds: the browser half reads the
+ * host's own `contextPressure` / `contextBreakdown` straight off the session
+ * list, so there is no route, no polling and no second state store — one
+ * registration on the session-projection seam, riding this plugin's fiber like
+ * `stats/unit.ts` does.
+ *
+ * A plugin's `apply` runs as soon as its own fiber starts, which can be before
+ * the projection registry exists: the optional injection below waits for it,
+ * and a deployment that mounts no registry simply never gets the panel's
+ * per-tool rows — the card falls back to the host's three numbers alone.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Register the `ccdContext` unit, once the projection registry exists.
+ *
+ * @param ctx - host plugin context.
+ * @param isEnabled - current plugin switch, read at mount time.
+ */
+export declare function mountContextBreakdown(ctx: Context, isEnabled: () => boolean): void;

package/lib/types/host/context/unit.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure `ccdContext` fold over committed session events.
+ *
+ * The host already publishes `contextBreakdown` — system prompt, tools,
+ * conversation — and `contextPressure`. Neither says *which* tool, *which*
+ * instruction file or *which* skill holds the tokens, and nothing outside the
+ * token meter can answer that from a wire value. So this unit mirrors the
+ * meter's own surface fold: it prices every message-producing event with the
+ * same heuristic, honours `surfaceOp` replacements exactly as
+ * `contextBreakdown` does, and keeps the priced surface so the two classified
+ * kinds can be summed at read time.
+ *
+ * The mirror is exact rather than approximate — against a real 19 MB session
+ * log it reproduces the host's persisted `{systemTokens: 1953, toolsTokens:
+ * 7492, messageTokens: 93461}` to the token — and `tests/context-pricing.test.ts`
+ * pins that. What it deliberately does *not* do is restate the whole
+ * breakdown: the system prompt and the conversation are the host's numbers, and
+ * this unit only re-derives the two shares that come out of `messageTokens`.
+ *
+ * @module
+ */
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+import { CONTEXT_KEY, type ContextBreakdownView, type ContextEntry } from '../../shared/context.ts';
+import { type PricedEvent } from './pricing.ts';
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        ccdContext: ContextState;
+    }
+    interface SessionProjectionMap {
+        ccdContext: ContextBreakdownView;
+    }
+}
+/** The autocompaction policy this deployment runs, as the loader declares it. */
+export interface CompactionPolicy {
+    /** `thresholdRatio`; the window share a compaction may fill. */
+    readonly ratio: number;
+    /** `headroomTokens`; room kept above the summary budget. */
+    readonly headroom: number;
+}
+/** Node kinds the fold classifies; everything else is `OTHER`. */
+export declare const KIND_OTHER = 0;
+/** A retained `agent-instructions` message. */
+export declare const KIND_INSTRUCTIONS = 1;
+/** A retained `skill-catalog` message. */
+export declare const KIND_SKILLS = 2;
+/**
+ * One retained surface node: `[seq, tokens, kind, entries]`.
+ *
+ * `entries` is empty for anything but the two classified kinds; for those it is
+ * the node's own price already split across the files or skills it names, so
+ * summing a kind's entries is summing its nodes.
+ */
+export type ContextNode = readonly [
+    seq: number,
+    tokens: number,
+    kind: number,
+    entries: readonly ContextEntry[]
+];
+/** Fold state: plain JSON, one value per session. */
+export interface ContextState {
+    /** Every retained surface node, in model-visible order. */
+    readonly nodes: readonly ContextNode[];
+    /** Per-tool prices from the latest request envelope, largest first. */
+    readonly tools: readonly ContextEntry[];
+    /** `request/context` capacity, 0 until one is logged. */
+    readonly window: number;
+    /** The envelope's own output cap, or null when it declares none. */
+    readonly reserved: number | null;
+}
+/** Empty state for one session. */
+export declare function initContextState(): ContextState;
+/**
+ * One instruction message's price, split across the files it names.
+ *
+ * The paths come from `source.changes` — the structured record of what that
+ * message carries — and the split weights come from each file's own section, so
+ * a message carrying two files of very different size does not report them as
+ * equal. A path whose section cannot be located takes an even weight.
+ *
+ * @param event - the retained `agent-instructions` message.
+ * @param tokens - the message's own heuristic price.
+ * @returns one row per named file, summing to `tokens`.
+ */
+export declare function instructionEntries(event: PricedEvent, tokens: number): readonly ContextEntry[];
+/**
+ * One skill catalog's price, split across the entries it lists.
+ *
+ * The catalog's structured `entries` are the names; their descriptions are the
+ * only per-entry size the message carries, so they are what the split weighs.
+ *
+ * @param event - the retained `skill-catalog` message.
+ * @param tokens - the message's own heuristic price.
+ * @returns one row per listed skill, summing to `tokens`.
+ */
+export declare function skillEntries(event: PricedEvent, tokens: number): readonly ContextEntry[];
+/**
+ * Advance the fold by one committed event.
+ *
+ * @param state - state covering every earlier event.
+ * @param event - the next committed session event.
+ * @returns the next state, or the same reference when the event is not ours.
+ */
+export declare function applyContextEvent(state: ContextState, event: PricedEvent): ContextState;
+/**
+ * Project one state onto the client-visible value.
+ *
+ * @param state - current fold state.
+ * @param policy - the deployment's autocompaction policy, or null when none runs.
+ * @returns the whole current value.
+ */
+export declare function viewContext(state: ContextState, policy: CompactionPolicy | null): ContextBreakdownView;
+/** Read one persisted state row; lenient, because a read must never throw. */
+export declare function readContextState(value: unknown): ContextState;
+/** Read one wire view row, leniently — the schema slot never throws. */
+export declare function readContextView(value: unknown): ContextBreakdownView;
+/**
+ * The registry's wire-unit shape: the definition with its optional `wire`
+ * field made required, which is the overload a client-visible key registers
+ * through.
+ */
+type WireUnit = Omit<ProjectionDefinition<typeof CONTEXT_KEY>, 'wire'> & {
+    wire: NonNullable<ProjectionDefinition<typeof CONTEXT_KEY>['wire']>;
+};
+/**
+ * Build the unit this plugin registers on `ctx.sessionProjections`.
+ *
+ * The policy is read through a callback rather than captured once: the unit is
+ * registered while the plugin is on, and a settings write that enables or
+ * reconfigures compaction lands in the loader's entry tree without remounting
+ * this plugin.
+ *
+ * @param policy - reads the deployment's autocompaction policy, or null.
+ * @returns the projection unit.
+ */
+export declare function createContextProjection(policy: () => CompactionPolicy | null): WireUnit;
+export {};

package/lib/types/host/index.d.ts

@@ -24,6 +24,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         'tool-calls': z<boolean, boolean, "defined">;
         statistics: z<boolean, boolean, "defined">;
         'composer-pet': z<boolean, boolean, "defined">;
+        'composer-stats': z<boolean, boolean, "defined">;
+        'context-panel': z<boolean, boolean, "defined">;
     }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
         shell: z<boolean, boolean, "defined">;
         sidebar: z<boolean, boolean, "defined">;
@@ -32,6 +34,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         'tool-calls': z<boolean, boolean, "defined">;
         statistics: z<boolean, boolean, "defined">;
         'composer-pet': z<boolean, boolean, "defined">;
+        'composer-stats': z<boolean, boolean, "defined">;
+        'context-panel': z<boolean, boolean, "defined">;
     }>>>, "volatile-defined">;
     appearance: z<NoInfer<Schemastery.ObjectS<NoInfer<{
         canvas: z<string, string, "defined">;
@@ -49,6 +53,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         uiCjk: z<string, string, "defined">;
         code: z<string, string, "defined">;
     }>>>, "volatile-defined">;
+    view: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        showEmptyGroups: z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        showEmptyGroups: z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     enabled: z<boolean, boolean, "volatile-defined">;
     debug: z<boolean, boolean, "volatile-defined">;
@@ -60,6 +69,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         'tool-calls': z<boolean, boolean, "defined">;
         statistics: z<boolean, boolean, "defined">;
         'composer-pet': z<boolean, boolean, "defined">;
+        'composer-stats': z<boolean, boolean, "defined">;
+        'context-panel': z<boolean, boolean, "defined">;
     }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
         shell: z<boolean, boolean, "defined">;
         sidebar: z<boolean, boolean, "defined">;
@@ -68,6 +79,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         'tool-calls': z<boolean, boolean, "defined">;
         statistics: z<boolean, boolean, "defined">;
         'composer-pet': z<boolean, boolean, "defined">;
+        'composer-stats': z<boolean, boolean, "defined">;
+        'context-panel': z<boolean, boolean, "defined">;
     }>>>, "volatile-defined">;
     appearance: z<NoInfer<Schemastery.ObjectS<NoInfer<{
         canvas: z<string, string, "defined">;
@@ -85,6 +98,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         uiCjk: z<string, string, "defined">;
         code: z<string, string, "defined">;
     }>>>, "volatile-defined">;
+    view: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        showEmptyGroups: z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        showEmptyGroups: z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
 }>>, "plain">;
 /**
  * Host half: the configuration surface the interface reads, plus the read-only

package/lib/types/shared/config.d.ts

@@ -1,20 +1,35 @@
-export declare const FEATURE_IDS: readonly ['shell', 'sidebar', 'new-session', 'conversation', 'tool-calls', 'statistics', 'composer-pet'];
+/**
+ * The interface modules a configuration switch turns on.
+ *
+ * `composer-stats` is the one entry that mounts nothing of its own: it is the
+ * Composer status bar's statistics readouts — `compat/stats-values.ts` plus the
+ * Composer sheet — and it is off by default, so a fresh install shows the row
+ * without the host's readout cluster. Turning it on mirrors one short value per
+ * pill (the output rate, or the cache-hit share) in place of the host's own
+ * label.
+ */
+export declare const FEATURE_IDS: readonly ['shell', 'sidebar', 'new-session', 'conversation', 'tool-calls', 'statistics', 'composer-pet', 'composer-stats', 'context-panel'];
 export type FeatureId = typeof FEATURE_IDS[number];
 export type FeatureFlags = Readonly<Record<FeatureId, boolean>>;
 /** Fields of the background-colour section; an empty string means "built-in palette". */
 export declare const APPEARANCE_FIELDS: readonly ['canvas', 'sidebar'];
 /** Fields of the typeface section; an empty string means "system stack". */
 export declare const FONT_FIELDS: readonly ['uiLatin', 'uiCjk', 'code'];
+/** Fields of the view-options section. */
+export declare const VIEW_FIELDS: readonly ['showEmptyGroups'];
 export type AppearanceField = typeof APPEARANCE_FIELDS[number];
 export type FontField = typeof FONT_FIELDS[number];
+export type ViewField = typeof VIEW_FIELDS[number];
 export type AppearanceConfig = Readonly<Record<AppearanceField, string>>;
 export type FontsConfig = Readonly<Record<FontField, string>>;
+export type ViewConfig = Readonly<Record<ViewField, boolean>>;
 export interface StyleConfig {
     readonly enabled: boolean;
     readonly debug: boolean;
     readonly features: FeatureFlags;
     readonly appearance: AppearanceConfig;
     readonly fonts: FontsConfig;
+    readonly view: ViewConfig;
 }
 export interface StyleOptions {
     readonly enabled?: boolean;
@@ -22,11 +37,21 @@ export interface StyleOptions {
     readonly features?: Partial<FeatureFlags>;
     readonly appearance?: Partial<Record<AppearanceField, unknown>>;
     readonly fonts?: Partial<Record<FontField, unknown>>;
+    readonly view?: Partial<Record<ViewField, unknown>>;
 }
 export declare const DEFAULT_FEATURES: FeatureFlags;
 /** Empty strings keep the built-in palette and the system font stack in charge. */
 export declare const DEFAULT_APPEARANCE: AppearanceConfig;
 export declare const DEFAULT_FONTS: FontsConfig;
+/**
+ * The view-options section's defaults.
+ *
+ * `showEmptyGroups` is off, which means the sidebar hides a Workspace that has
+ * no Session under the current filter — the reference's own default for that
+ * switch, and the reason the row in the view-options card reads as "off" on a
+ * fresh install.
+ */
+export declare const DEFAULT_VIEW: ViewConfig;
 /** Font names longer than this are a pasted paragraph, not a family. */
 export declare const FONT_NAME_MAX_LENGTH = 64;
 /**

package/lib/types/shared/context.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The context-breakdown contract both halves share.
+ *
+ * The host half re-derives what the host's own three-number breakdown cannot
+ * say — per-tool rows, per-file rows, per-skill rows, the autocompaction
+ * threshold — and ships it as the `ccdContext` projection; the browser half
+ * reads the host's authoritative `contextPressure` / `contextBreakdown` beside
+ * it and turns all of it into the panel's rows and bar with the pure functions
+ * below. Keeping the arithmetic here is what lets the card be a pure function
+ * of its inputs and lets the tests price a real session log without a browser.
+ *
+ * The pricing constants are the host's own (`@deepseek-ai/dsh-token-meter`
+ * `estimate.ts`): four characters per token, four tokens of structural overhead
+ * per content block and per message. They are restated rather than imported —
+ * that package is not part of this plugin's runtime baseline — and every number
+ * they produce is a re-derivation of a value the host also computed, never a
+ * second authority beside it.
+ */
+/** Projection key this plugin owns; it must not collide with a host key. */
+export declare const CONTEXT_KEY = "ccdContext";
+/** Persisted-cache invalidation version for the fold state. */
+export declare const CONTEXT_STATE_VERSION = 1;
+/** Characters per token in the host's density heuristic. */
+export declare const CHARS_PER_TOKEN = 4;
+/** Structural overhead the host adds per content block and per message. */
+export declare const BLOCK_OVERHEAD = 4;
+/** Default autocompaction threshold ratio (`compaction-basic`). */
+export declare const DEFAULT_THRESHOLD_RATIO = 0.8;
+/** Default autocompaction headroom, in tokens (`compaction-basic`). */
+export declare const DEFAULT_HEADROOM_TOKENS = 65536;
+/** The public-name prefix DSH gives every MCP tool. */
+export declare const MCP_PREFIX = "mcp__";
+/** Distinct entries one fold group keeps before it drops the smallest. */
+export declare const CONTEXT_ENTRY_LIMIT = 200;
+/** Detail rows a group renders before its list scrolls. */
+export declare const DETAIL_ROW_LIMIT = 200;
+/** The narrowest segment the bar draws; anything under this is left out. */
+export declare const MIN_SEGMENT_PX = 2;
+/** One priced row, as it travels on the wire: `[name, tokens]`. */
+export type ContextEntry = readonly [name: string, tokens: number];
+/** The `ccdContext` projection's client-visible value. */
+export interface ContextBreakdownView {
+    /** Every assembled tool schema, largest first. */
+    readonly tools: readonly ContextEntry[];
+    /** Every retained instruction file, largest first. */
+    readonly files: readonly ContextEntry[];
+    /** Every retained skill-catalog entry, largest first. */
+    readonly skills: readonly ContextEntry[];
+    /** Tokens every retained skill catalog contributes to the surface. */
+    readonly skillTokens: number;
+    /** Tokens every retained instruction message contributes to the surface. */
+    readonly fileTokens: number;
+    /** Effective autocompaction threshold, or null when no policy is readable. */
+    readonly compaction: number | null;
+}
+/** One row of the panel, and one segment of the bar, in the reference's order. */
+export type ContextSliceKey = 'mcp' | 'tools' | 'system' | 'skills' | 'memory' | 'messages' | 'autocompact' | 'free';
+/** One priced slice of the context window. */
+export interface ContextSlice {
+    readonly key: ContextSliceKey;
+    /** Tokens this slice holds; never negative. */
+    readonly tokens: number;
+}
+/**
+ * Everything the panel draws from: the host's two authoritative projections,
+ * this plugin's re-derived rows, and the session's capacity.
+ */
+export interface ContextSource {
+    /** `contextPressure.contextWindow`. */
+    readonly window: number;
+    /** Occupancy: `projectedTokens ?? pressureTokens` — the ring's own number. */
+    readonly used: number;
+    /** `contextBreakdown.systemTokens`. */
+    readonly systemTokens: number;
+    /** `contextBreakdown.toolsTokens`. */
+    readonly toolsTokens: number;
+    /** Per-tool rows, used only to split the authoritative total in two. */
+    readonly tools?: readonly ContextEntry[];
+    /** `contextBreakdown.messageTokens`. */
+    readonly messageTokens: number;
+    /** Tokens in every retained skill catalog, re-derived. */
+    readonly skillTokens: number;
+    /** Tokens in every retained instruction message, re-derived. */
+    readonly fileTokens: number;
+    /** Effective autocompaction threshold, or null when it is not readable. */
+    readonly compaction: number | null;
+}
+/** The panel's whole reading, ready to draw. */
+export interface ContextBreakdown {
+    /** The session's capacity. */
+    readonly window: number;
+    /** Occupancy, exactly as the ring reads it. */
+    readonly used: number;
+    /** The ring's own integer percentage. */
+    readonly percent: number;
+    /** Every row, in the bar's own order; `free` is last. */
+    readonly slices: readonly ContextSlice[];
+    /** The slices the bar draws, without `free` — the track is the remainder. */
+    readonly segments: readonly ContextSlice[];
+    /** `used − Σ rows`: the sampled reading's distance from the heuristic tree. */
+    readonly residual: number;
+}
+/** Read a non-negative integer, or null when the value is not one. */
+export declare function readCount(value: unknown): number | null;
+/** Read one `[name, tokens]` list, dropping everything else. */
+export declare function readEntries(value: unknown): readonly ContextEntry[];
+/**
+ * Read one `ccdContext` value, from the wire or from a hand-written fixture.
+ *
+ * Deliberately lenient — a build that carries no such key, or a value from a
+ * later state version, must read as "this plugin's rows are not here" rather
+ * than throw into a render — and deliberately strict about *that*: a value that
+ * is not an object is null, so the panel can tell "no rows" from "zero rows".
+ *
+ * @param value - the raw projection value.
+ * @returns a usable view, or null when there is nothing to read.
+ */
+export declare function readContextView(value: unknown): ContextBreakdownView | null;
+/** The empty view, for a build or a state version that carries no rows. */
+export declare function emptyContextView(): ContextBreakdownView;
+/**
+ * Split the authoritative tool total across the MCP and built-in groups.
+ *
+ * The host prices the assembled tool array whole (`ceil(JSON.length / 4) + 4`),
+ * so per-tool prices cannot be summed back to it — 37 real tools came to 7657
+ * against the array's 7492. The authoritative total is therefore split in the
+ * ratio the per-tool prices report, which keeps the two rows summing to the
+ * host's own number with the rounding difference absorbed here.
+ *
+ * @param tools - per-tool rows, `[name, tokens]`.
+ * @param total - the host's authoritative `toolsTokens`.
+ * @returns the MCP share and the built-in share, summing to `total`.
+ */
+export declare function splitTools(tools: readonly ContextEntry[], total: number): {
+    readonly mcp: number;
+    readonly tools: number;
+};
+/**
+ * The panel's rows, bar segments and residual.
+ *
+ * @param source - the host's projections plus this plugin's re-derived rows.
+ * @returns the whole reading; rows that price at zero are left out.
+ */
+export declare function contextBreakdown(source: ContextSource): ContextBreakdown;
+/**
+ * The autocompaction segment's own height: what the policy holds back.
+ *
+ * `compaction-basic` resolves `floor(min(window × ratio, window − reserved −
+ * headroom))`; the segment is the distance from that threshold to the window,
+ * which is the room the window keeps for the summary it will write. A session
+ * with no readable policy, or one already past its threshold, draws nothing.
+ *
+ * @param window - the session's capacity.
+ * @param compaction - the resolved threshold, or null when unreadable.
+ * @param used - current occupancy, which the segment never overstates.
+ * @returns the segment's token height; 0 when it is not drawn.
+ */
+export declare function autocompactTokens(window: number, compaction: number | null, used: number): number;
+/**
+ * The autocompaction threshold a request envelope implies.
+ *
+ * `reservedCompletionTokens` is the request's own output cap; a route that
+ * advertises none leaves the reservation unknown, and the row is then left out
+ * rather than guessed at.
+ *
+ * @param window - the session's capacity.
+ * @param reserved - the request's `maxTokens`, or null when it declares none.
+ * @param ratio - the policy's threshold ratio.
+ * @param headroom - the policy's headroom, in tokens.
+ * @returns the threshold, or null when it cannot be resolved.
+ */
+export declare function compactionThreshold(window: number, reserved: number | null, ratio?: number, headroom?: number): number | null;
+/**
+ * The bar's segments and the free weight beside them, all in tokens.
+ *
+ * The reference drops a category whose share is under 2px instead of drawing a
+ * hairline. The bar's weights have to add up to the window for a segment's
+ * share to be its share of the window — and the rows deliberately do not, since
+ * the sampled reading and the heuristic tree differ — so the remainder is
+ * measured against the window rather than summed from the rows.
+ *
+ * @param breakdown - the panel's reading.
+ * @param barWidth - the bar's measured width in CSS pixels.
+ * @returns the drawn segments and the free weight, all in tokens.
+ */
+export declare function barSegments(breakdown: ContextBreakdown, barWidth: number): {
+    readonly drawn: readonly ContextSlice[];
+    readonly free: number;
+};
+/**
+ * The reference's compact token count: `342`, `4.6k`, `216.7k`, `1M`.
+ *
+ * One decimal place, with a trailing `.0` dropped — which is what the
+ * reference's own readings show (`48k`, `32.5k`, `216.7k`, `878k`, `1M`). The
+ * host's own formatter rounds to a whole number above 100 and would print
+ * `217k` where the reference prints `216.7k`; the panel follows the reference,
+ * and the header still agrees with the ring because both read the same
+ * `contextPressure` value.
+ *
+ * @param value - token count.
+ * @returns the compact reading.
+ */
+export declare function formatTokens(value: number): string;
+/**
+ * One row's share of the window, at the reference's one decimal.
+ *
+ * @param tokens - the row's tokens.
+ * @param window - the session's capacity.
+ * @returns e.g. `4.8%`.
+ */
+export declare function formatPercent(tokens: number, window: number): string;
+/**
+ * An MCP tool's two names, as the reference writes them.
+ *
+ * DSH gives every MCP tool the public name `mcp__<server>__<tool>`; the panel
+ * shows `<server> · <tool>`. A name that does not follow the convention is
+ * returned unchanged, so a build that renames the prefix loses the split and
+ * nothing else.
+ *
+ * @param name - the tool's public name.
+ * @returns the display label.
+ */
+export declare function toolLabel(name: string): string;
+/** The MCP server one tool name belongs to, or null for a built-in tool. */
+export declare function mcpServer(name: string): string | null;
+/**
+ * Shorten a path from the middle, keeping its own file name.
+ *
+ * The reference writes `/Users/zoukai/code/dsh-ccd-…AGENTS.md`: the tail is what
+ * identifies the file, so the head gives way first. A path that already fits is
+ * returned unchanged.
+ *
+ * The budget is the panel's own label column: a fixed 360px card leaves about
+ * 208px for a detail row's name, which is this many characters of a path at
+ * 13px with room to spare. It is deliberately conservative — the row carries
+ * the full path in its `title`, and CSS's own ellipsis would eat the tail this
+ * function exists to keep.
+ *
+ * @param path - the path as the instruction message named it.
+ * @param budget - characters to keep, the ellipsis included.
+ * @returns the shortened path.
+ */
+export declare function shortenPath(path: string, budget?: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-claude-desktop-theme",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Claude Code Desktop-style theme for DeepSeek Harness (DSH) Desktop on macOS and Windows, with light/dark themes, model/effort pickers and an interactive pixel whale",
   "author": "zkforge",
@@ -81,10 +81,12 @@
     "typecheck": "tsc --noEmit",
     "check:architecture": "node scripts/check-architecture.mjs",
     "check:package": "node scripts/check-package.mjs",
-    "test": "node --test tests/*.test.ts",
+    "test": "node --test tests/*.test.ts tests/*.test.mjs",
     "check": "npm run typecheck && npm run check:architecture && npm test && npm run build && npm run check:package",
     "prepack": "npm run check",
-    "pack:local": "npm pack --pack-destination artifacts"
+    "pack:local": "npm pack --pack-destination artifacts",
+    "pet:gifs": "node scripts/pet-gifs.mjs",
+    "effort:gifs": "node scripts/effort-gif.mjs"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4"
@@ -110,6 +112,7 @@
     "@types/react": "18.3.1",
     "esbuild": "0.28.2",
     "react": "18.3.1",
+    "react-dom": "18.3.1",
     "typescript": "7.0.2",
     "yaml": "2.9.1"
   }