dsh-claude-desktop-theme 0.2.0

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

@@ -0,0 +1,115 @@
+/**
+ * Pure `ccdUsage` fold over committed session events. The host owns watermarks
+ * and checkpoints. Skip the inherited prefix of forks, attribute messages to
+ * the latest request/header model, and use normalizeUsage token accounting:
+ * reasoning is part of output, while cache-inclusive totals and raw in/out
+ * counters are retained for the Models view.
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionHeader, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+import type { StatsSessionUsage } from '../../shared/stats.ts';
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        ccdUsage: UsageState;
+    }
+    interface SessionProjectionMap {
+        ccdUsage: StatsSessionUsage;
+    }
+}
+/** Projection key this plugin owns; it must not collide with a host key. */
+export declare const USAGE_KEY = "ccdUsage";
+/** Persisted-cache invalidation version for {@link UsageState}. */
+export declare const USAGE_STATE_VERSION = 2;
+/** Bucket for usage that arrived before the session logged its first header. */
+export declare const UNKNOWN_MODEL = "unknown";
+/** Hours in a local day. */
+export declare const HOURS_PER_DAY = 24;
+/** One model's counters: cache-inclusive tokens, raw input, raw output. */
+export interface ModelUsage {
+    /** Tokens at the provider's scale, cache hits included. */
+    readonly t: number;
+    /** Raw `inputTokens` as the adapter reported them. */
+    readonly i: number;
+    /** Raw `outputTokens` as the adapter reported them. */
+    readonly o: number;
+}
+/** Fold state: plain JSON, one value per session. */
+export interface UsageState {
+    /** Events below this seq belong to the fork-inherited prefix, never to this session. */
+    readonly seedSeq: number;
+    /** Human prompts (`user/message` with source kind `user`). */
+    readonly prompts: number;
+    /** Tokens at the provider's scale, cache hits included. */
+    readonly tokens: number;
+    /** Local day key → prompts. */
+    readonly days: Readonly<Record<string, number>>;
+    /** 24 local-hour buckets → prompts. */
+    readonly hours: readonly number[];
+    /** `provider/model` → counters. */
+    readonly models: Readonly<Record<string, ModelUsage>>;
+    /** Local day key → `provider/model` → tokens produced that day. */
+    readonly modelDays: Readonly<Record<string, Readonly<Record<string, number>>>>;
+    /** Model in effect for the next assembled message. */
+    readonly model: string | null;
+}
+/** Local `YYYY-MM-DD`, the day key the reference heatmap buckets by. */
+export { localDayKey as dayKey } from '../../shared/stats.ts';
+/**
+ * Tokens at the provider's scale for one assembled message.
+ *
+ * @param usage - the step's reported usage.
+ * @returns the message's token total, never negative.
+ */
+export declare function rawTokens(usage: TokenUsage): number;
+/**
+ * Empty state for one session.
+ *
+ * @param _header - immutable session metadata (unused: the fold is event-driven).
+ * @param inheritedEventCount - exact fork-inherited prefix length.
+ * @returns the initial state.
+ */
+export declare function initUsageState(_header: SessionHeader, inheritedEventCount: SessionLogOffset): UsageState;
+/**
+ * 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 counted.
+ */
+export declare function applyUsageEvent(state: UsageState, event: SessionEvent): UsageState;
+/**
+ * Project one state onto the client-visible value.
+ *
+ * @param state - current fold state.
+ * @returns the whole current value, identity-stable for a given state.
+ */
+export declare function viewUsage(state: UsageState): StatsSessionUsage;
+/**
+ * Read one persisted state row.
+ *
+ * Deliberately lenient: the registry's own `ver` check already discards rows
+ * from another state version, and a read must never throw into the host's
+ * session list or a cold-start fold.
+ *
+ * @param value - row value from the projection cache.
+ * @returns a usable state.
+ */
+export declare function readUsageState(value: unknown): UsageState;
+/**
+ * Read one persisted or wire view row.
+ *
+ * @param value - view value from the projection cache or the change feed.
+ * @returns a usable view.
+ */
+export declare function readUsageView(value: unknown): StatsSessionUsage;
+/**
+ * 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. Declaring it here keeps `register` callable without a cast.
+ */
+type WireUnit = Omit<ProjectionDefinition<typeof USAGE_KEY>, 'wire'> & {
+    wire: NonNullable<ProjectionDefinition<typeof USAGE_KEY>['wire']>;
+};
+/** The unit this plugin registers on `ctx.sessionProjections`. */
+export declare const usageProjection: WireUnit;

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

@@ -0,0 +1,61 @@
+export declare const FEATURE_IDS: readonly ['shell', 'sidebar', 'new-session', 'conversation', 'tool-calls', 'statistics', 'composer-pet'];
+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'];
+export type AppearanceField = typeof APPEARANCE_FIELDS[number];
+export type FontField = typeof FONT_FIELDS[number];
+export type AppearanceConfig = Readonly<Record<AppearanceField, string>>;
+export type FontsConfig = Readonly<Record<FontField, string>>;
+export interface StyleConfig {
+    readonly enabled: boolean;
+    readonly debug: boolean;
+    readonly features: FeatureFlags;
+    readonly appearance: AppearanceConfig;
+    readonly fonts: FontsConfig;
+}
+export interface StyleOptions {
+    readonly enabled?: boolean;
+    readonly debug?: boolean;
+    readonly features?: Partial<FeatureFlags>;
+    readonly appearance?: Partial<Record<AppearanceField, unknown>>;
+    readonly fonts?: Partial<Record<FontField, 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;
+/** Font names longer than this are a pasted paragraph, not a family. */
+export declare const FONT_NAME_MAX_LENGTH = 64;
+/**
+ * Normalize one user-entered colour to lowercase `#rrggbb`.
+ *
+ * The settings boundary accepts the short form as well, so a hand-edited patch
+ * file and the colour input both land on one spelling.
+ * @param value - raw section value of any type.
+ * @returns the normalized colour, or an empty string when it is not a hex colour.
+ */
+export declare function normalizeColour(value: unknown): string;
+/**
+ * Normalize one user-entered font family name.
+ *
+ * A comma or a parenthesis would turn the value into a stack or a `url()`; the
+ * theme layer composes the stack itself, so a single family is all that is
+ * accepted. Quotes are dropped because the composer adds its own.
+ * @param value - raw section value of any type.
+ * @returns the collapsed family name, or an empty string when it is not one.
+ */
+export declare function normalizeFontName(value: unknown): string;
+export declare function resolveConfig(input?: StyleOptions): StyleConfig;
+/**
+ * Fold the Host-served configuration section into a validated StyleConfig.
+ * The client half reads its configuration through the settings transport, so
+ * the value arrives as untyped JSON from a user-editable patch file: unknown
+ * keys, wrong types and an absent section all fall back to the declared
+ * defaults instead of failing the whole activation.
+ * @param value - the section value from the Host, or undefined before it loads.
+ * @returns the validated configuration; never throws.
+ */
+export declare function adoptConfig(value: unknown): StyleConfig;

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

@@ -0,0 +1,5 @@
+export declare const PLUGIN_ID = "dsh-claude-desktop-theme";
+/** Loader entry id declared by this package's bundle patch (cordis.patch.yml). */
+export declare const ENTRY_ID = "ui-skin-ccd-style";
+export declare const TARGET_DSH_VERSION = "0.2.0-rc.2";
+export declare const ROOT_ATTRIBUTE = "data-dsh-ccd-style";

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

@@ -0,0 +1,133 @@
+/**
+ * Statistics-card contract shared by the plugin's two halves.
+ *
+ * The host half folds every stored session log into one sparse summary per
+ * session (a project unit of the host's own projection seam, so incremental
+ * folding and durable checkpoints stay the host's business) and aggregates
+ * those summaries into a {@link StatsSnapshot}. The browser half reads that
+ * snapshot from the host's authenticated route and paints the card. Both
+ * halves import this file, so the wire vocabulary lives here rather than in
+ * either half.
+ *
+ * Since the card grew the reference's `Models` view and its `All`/`30d`/`7d`
+ * switch, a session's summary has to answer two more questions: which model
+ * produced which tokens on which day, and how many tokens arrived with each
+ * model in total (the legend prints lifetime in/out counters, exactly as the
+ * reference does). The per-session value therefore carries a model table plus
+ * a sparse `date → model index → tokens` list; the index keeps that list small
+ * enough to ride the session payloads it is published on.
+ */
+/** Authenticated host route serving {@link StatsSnapshot}. */
+export declare const STATS_PATH = "/api/ccd-stats";
+/** Snapshot revision; a client that does not know the version ignores the body. */
+export declare const STATS_VERSION = 2;
+/** Days of history one snapshot ships; the card itself draws 26 weeks. */
+export declare const STATS_DAY_LIMIT = 366;
+/** The reference's three date ranges, in the order it draws them. */
+export declare const STATS_RANGES: readonly ['all', '30d', '7d'];
+/** One of the reference's range switches. */
+export type StatsRangeId = (typeof STATS_RANGES)[number];
+/** Days each range covers, counting back from today; `all` has no cutoff. */
+export declare const STATS_RANGE_DAYS: Readonly<Record<StatsRangeId, number | null>>;
+/** Local `YYYY-MM-DD` for one instant, the day key both halves bucket by. */
+export declare function localDayKey(time: number): string;
+/**
+ * The first local day a range covers.
+ *
+ * The reference counts back from today inclusive: `30d` starts 29 days ago.
+ * Both halves need the same bound — the host to total a range, the browser to
+ * cut the chart's days — so the rule lives here.
+ *
+ * @param range - the range switch.
+ * @param now - the instant "today" is read from, epoch ms.
+ * @returns the first day key, or null when the range has no cutoff.
+ */
+export declare function rangeStart(range: StatsRangeId, now: number): string | null;
+/** One local calendar day (`YYYY-MM-DD`) and its prompt count. */
+export type StatsDay = readonly [string, number];
+/** One local hour and its prompt count. */
+export type StatsHour = readonly [number, number];
+/** One `provider/model` with its tokens: total, input, output. */
+export type StatsModelUsage = readonly [string, number, number, number];
+/** One `provider/model` and the tokens attributed to it inside a range. */
+export type StatsModelTokens = readonly [string, number];
+/** One day of one session: local day, index into the value's model table, tokens. */
+export type StatsModelDay = readonly [string, number, number];
+/** One day of the whole library: local day, `provider/model`, tokens. */
+export type StatsModelDayRow = readonly [string, string, number];
+/** Lifetime input/output counters for one model, as the legend prints them. */
+export type StatsModelIO = readonly [string, number, number];
+/**
+ * One session's contribution to the aggregate.
+ *
+ * `models` doubles as the index table for {@link StatsModelDay}: the day rows
+ * point at their model's position in this list, which keeps the per-day data
+ * from repeating a `provider/model` string for every day it appears on.
+ */
+export interface StatsSessionUsage {
+    /** Human prompts: `user/message` events whose source kind is `user`. */
+    readonly prompts: number;
+    /** Tokens at the provider's scale, cache hits included. */
+    readonly tokens: number;
+    /** Per local day, sparse; only days with prompts appear. */
+    readonly days: readonly StatsDay[];
+    /** Per local hour, sparse; only hours with prompts appear. */
+    readonly hours: readonly StatsHour[];
+    /** Per model, sparse and sorted by name; the day rows index into this list. */
+    readonly models: readonly StatsModelUsage[];
+    /** Per day and model, sparse, sorted by day then model index. */
+    readonly modelDays: readonly StatsModelDay[];
+}
+/** What one date range shows in the tiles, and the models the legend draws. */
+export interface StatsRangeTotals {
+    /** Sessions that did work inside the range. */
+    readonly sessions: number;
+    /** Human prompts inside the range. */
+    readonly messages: number;
+    /** Tokens produced inside the range, cache hits included. */
+    readonly tokens: number;
+    /** Local days with any activity inside the range. */
+    readonly activeDays: number;
+    /** The range's busiest model by tokens, or null when it saw no tokens. */
+    readonly topModel: string | null;
+    /** Every model inside the range, busiest first. */
+    readonly models: readonly StatsModelTokens[];
+}
+/** The three ranges, keyed by {@link StatsRangeId}. */
+export type StatsRanges = Readonly<Record<StatsRangeId, StatsRangeTotals>>;
+/** Everything the card needs, aggregated over every visible stored session. */
+export interface StatsSnapshot {
+    readonly version: number;
+    /** Totals for each range switch; `all` also feeds the heatmap's own scale. */
+    readonly ranges: StatsRanges;
+    /**
+     * Busiest local hour over all time. The reference's tiles read this from its
+     * unfiltered statistics while every other tile is range-filtered, so the card
+     * does the same: switching range must not move `Peak hour`.
+     */
+    readonly busyHour: number | null;
+    /** Local days and prompt counts, oldest first, capped at {@link STATS_DAY_LIMIT}. */
+    readonly days: readonly StatsDay[];
+    /** Tokens per day and model, oldest first, capped at {@link STATS_DAY_LIMIT} days. */
+    readonly modelDays: readonly StatsModelDayRow[];
+    /** Lifetime input/output counters per model, for the legend's middle column. */
+    readonly modelIO: readonly StatsModelIO[];
+    /** Sessions still being folded; the card polls faster while this is non-zero. */
+    readonly pending: number;
+    /** Sessions whose logs could not be read and are therefore missing from the totals. */
+    readonly missed: number;
+    /** When the host computed this snapshot (epoch ms). */
+    readonly computedAt: number;
+}
+/**
+ * Read one snapshot from untrusted JSON.
+ *
+ * The browser half treats the host route as the one data source it does not
+ * compile against, so the response is validated structurally before it can
+ * reach the card: a body that is not a snapshot at this version is refused and
+ * the card simply stays hidden.
+ *
+ * @param value - parsed response body.
+ * @returns the snapshot, or null when the body is not one.
+ */
+export declare function readStatsSnapshot(value: unknown): StatsSnapshot | null;

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "dsh-claude-desktop-theme",
+  "version": "0.2.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zkforge/dsh-claude-desktop-theme.git"
+  },
+  "homepage": "https://github.com/zkforge/dsh-claude-desktop-theme#readme",
+  "bugs": {
+    "url": "https://github.com/zkforge/dsh-claude-desktop-theme/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-desktop",
+    "deepseek",
+    "deepseek-harness",
+    "claude",
+    "claude-code",
+    "claude-desktop",
+    "claude-code-desktop",
+    "dsh-theme",
+    "desktop-theme",
+    "ui-theme",
+    "theme",
+    "skin",
+    "dark-mode",
+    "light-theme",
+    "macos",
+    "windows",
+    "cordis-plugin",
+    "ccd"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/host/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/host/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": "=0.2.0-rc.2"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-theme",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-ui-model-selection",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "dev": "node scripts/build.mjs --watch",
+    "typecheck": "tsc --noEmit",
+    "check:architecture": "node scripts/check-architecture.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "test": "node --test tests/*.test.ts",
+    "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"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "devDependencies": {
+    "@babel/parser": "7.29.9",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-model-selection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-theme": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.2.0-rc.2",
+    "@types/node": "26.6.3",
+    "@types/react": "18.3.1",
+    "esbuild": "0.28.2",
+    "react": "18.3.1",
+    "typescript": "7.0.2",
+    "yaml": "2.9.1"
+  }
+}