dsh-claude-desktop-theme 0.2.0

package/lib/types/client/features/statistics/card.d.ts

@@ -0,0 +1,143 @@
+/**
+ * New-session statistics card, rebuilt as plain DOM.
+ *
+ * The reference panel (Claude Desktop's Code tab) is a 480px card: a header
+ * with two segmented controls (`Overview`/`Models`, `All`/`30d`/`7d`), then
+ * either a 3×2 grid of stat tiles with a 26×7 contribution heatmap and one
+ * footer sentence, or the `Models` view's stacked daily bar chart and its
+ * legend. It is drawn imperatively because the card lives in its own container
+ * next to the host's greeting, not in a slot the host renders — so there is no
+ * React root to render into and no shared-library dependency to declare.
+ *
+ * Geometry and colour come from the reference, measured against its own
+ * Tailwind classes and the @2x screenshots (see theme/tokens.css): a
+ * 20px segmented control with 6px padding, a 160px chart whose bars are 72% of
+ * their day column, an 8px legend swatch, and a dark tooltip placed 4px above
+ * its anchor. Everything visible is a theme variable (see
+ * `theme/tokens.css`).
+ */
+import type { StatsRangeId } from '../../../shared/stats.ts';
+/** Marks the card container; the compatibility layer positions it. */
+export declare const CARD_ATTRIBUTE = "data-ccd-stats-card";
+/** Heatmap columns and rows. 26×7 = 182 days, as the reference draws it. */
+export declare const HEAT_COLUMNS = 26;
+export declare const HEAT_ROWS = 7;
+/** Legend rows the reference shows before it offers "Show N more". */
+export declare const LEGEND_LIMIT = 6;
+/** Distance the reference leaves between an anchor and its tooltip. */
+export declare const TIP_OFFSET_PX = 4;
+/** Gap the chart's x-axis labels keep from each other when they are thinned. */
+export declare const CHART_LABEL_GAP_PX = 8;
+/** The card's two views. */
+export type StatsTabId = 'overview' | 'models';
+/** One segmented-control choice. */
+export interface StatsOption<T extends string> {
+    readonly id: T;
+    readonly label: string;
+}
+/** One stat tile: a footnote label above a semibold value. */
+export interface StatsTile {
+    readonly label: string;
+    readonly value: string;
+    /** The reference prints `Favorite model` one size down; long ids need it. */
+    readonly small?: boolean;
+}
+/** One heatmap cell: a day with its count, or a future cell left blank. */
+export interface HeatCell {
+    readonly date: string;
+    readonly count: number;
+    /** 0 = no activity, 1-4 = the reference's four steps, null = after today. */
+    readonly level: number | null;
+}
+/** One model's slice of one chart bar. */
+export interface ChartSegment {
+    readonly model: string;
+    readonly tokens: number;
+    /** Theme variable holding this model's colour. */
+    readonly color: string;
+}
+/** One bar: a day with tokens, its slices, and the tooltip it opens. */
+export interface ChartDay {
+    readonly date: string;
+    readonly label: string;
+    readonly tokens: number;
+    readonly segments: readonly ChartSegment[];
+}
+/** One legend row, exactly as the reference composes it. */
+export interface LegendRow {
+    readonly model: string;
+    readonly color: string;
+    /** `40.4M in · 3.6M out`, from the lifetime counters. */
+    readonly usage: string;
+    /** Share of the range's tokens, one decimal place. */
+    readonly percent: string;
+}
+/** Everything the `Overview` view draws. */
+export interface StatsOverviewData {
+    readonly tiles: readonly StatsTile[];
+    /** One level per cell, column-major: `column * 7 + row`, Sunday first. */
+    readonly heat: readonly HeatCell[];
+    /** First index drawn after today; those cells stay transparent. */
+    readonly futureFrom: number;
+    /** Footer sentence, or null when the reference would draw none. */
+    readonly note: string | null;
+}
+/** Everything the `Models` view draws. */
+export interface StatsModelsData {
+    /** Axis labels, lowest first; empty when the range saw no tokens. */
+    readonly ticks: readonly string[];
+    /** Top of the axis; bar heights are a share of it. */
+    readonly top: number;
+    /** One bar per day with usage in the range, oldest first. */
+    readonly days: readonly ChartDay[];
+    readonly legend: readonly LegendRow[];
+    /** Legend rows past {@link LEGEND_LIMIT}, behind "Show N more". */
+    readonly moreCount: number;
+}
+/** Everything the card needs to draw itself. */
+export interface StatsCardData {
+    readonly tab: StatsTabId;
+    readonly tabs: readonly StatsOption<StatsTabId>[];
+    readonly ranges: readonly StatsOption<StatsRangeId>[];
+    readonly range: StatsRangeId;
+    /** Present when {@link tab} is `overview`. */
+    readonly overview: StatsOverviewData | null;
+    /** Present when {@link tab} is `models`. */
+    readonly models: StatsModelsData | null;
+}
+/** What the card reports back to its owner. */
+export interface StatsCardHandlers {
+    readonly onTab: (id: StatsTabId) => void;
+    readonly onRange: (id: StatsRangeId) => void;
+}
+/** The mounted card. */
+export interface StatsCard {
+    readonly element: HTMLElement;
+    /** Fit the chart's x-axis labels to the card's current width. */
+    layout(): void;
+}
+/**
+ * Level for one day: `ceil(day / busiest day * 4)` clamped to 0-4, which is the
+ * reference's own rule (`L = 80 - ceil(ratio * 4) * 8`).
+ *
+ * @param value - that day's count.
+ * @param peak - the busiest day in the window.
+ */
+export declare function heatLevel(value: number, peak: number): number;
+/**
+ * The heatmap's tooltip line, exactly the reference's copy: `Sep 30 — 1,387`.
+ *
+ * @param date - local day key.
+ * @param count - that day's count.
+ * @returns the line the tooltip shows.
+ */
+export declare function heatTip(date: string, count: number): string;
+/**
+ * Build the card.
+ *
+ * @param document - renderer document the card belongs to.
+ * @param data - header state plus the active view's content.
+ * @param handlers - tab and range selections.
+ * @returns the detached card and its layout hook.
+ */
+export declare function createStatsCard(document: Document, data: StatsCardData, handlers: StatsCardHandlers): StatsCard;

package/lib/types/client/features/statistics/format.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Number and date formatting for the statistics card.
+ *
+ * The card's copy is English, so its separators and its 12-hour clock are too:
+ * every formatter here is fixed to `en-US`, which is what the reference uses.
+ * They live in their own module because both the data layer (`view.ts`) and the
+ * DOM layer (`card.ts`) need them, and neither should import the other.
+ */
+/**
+ * One metric as the reference writes it: `1,556`.
+ *
+ * @param value - the raw count.
+ * @returns the display string.
+ */
+export declare function formatCount(value: number): string;
+/**
+ * Token totals, scaled the way the reference scales them.
+ *
+ * @param value - raw token total.
+ * @returns `493.1M`, `12k`, or a plain count below a thousand.
+ */
+export declare function formatTokens(value: number): string;
+/**
+ * One hour of the day, as the reference labels it (`11 AM`).
+ *
+ * @param hour - local hour, 0-23.
+ * @returns the label.
+ */
+export declare function formatHour(hour: number): string;
+/**
+ * One `YYYY-MM-DD` key as the reference labels a chart day (`Sep 30`).
+ *
+ * @param date - local day key.
+ * @returns the short label.
+ */
+export declare function formatDayLabel(date: string): string;

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

@@ -0,0 +1,8 @@
+import type { ImplementedFeature } from '../../contracts/feature.ts';
+/**
+ * New-session statistics card. DSH sells no cross-session aggregate, so the
+ * host half folds the session logs through a projection unit of its own and
+ * serves one snapshot on `/api/ccd-stats`; the card renders that snapshot with
+ * the card's presentation rules.
+ */
+export declare const statisticsFeature: ImplementedFeature;

package/lib/types/client/features/statistics/mount.d.ts

@@ -0,0 +1,12 @@
+import type { CleanupScope } from '../../core/cleanup.ts';
+import type { Logger } from '../../contracts/ports.ts';
+import type { StatsSource } from './source.ts';
+/**
+ * Keep one card mounted inside the hero stack.
+ *
+ * @param document - renderer document carrying the conversation page.
+ * @param scope - cleanup scope owning the observer, the subscription and the card node.
+ * @param logger - sink for observer failures; the native page stays without a card.
+ * @param source - snapshot reader the card redraws from.
+ */
+export declare function mountStatisticsCard(document: Document, scope: CleanupScope, logger: Logger, source: StatsSource): void;

package/lib/types/client/features/statistics/source.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The card's data source: one host route, polled on a scope-owned timer.
+ *
+ * The host serves `/api/ccd-stats` on its authenticated channel, so the read
+ * is an ordinary same-origin fetch — the session cookie the page already holds
+ * is what authorizes it, and the host applies its own trust fence before the
+ * handler runs. Nothing here holds a socket or a second copy of the data.
+ *
+ * The poll cadence follows the host's progress counters: while cold sessions
+ * are still being folded (`pending > 0`) the card is genuinely incomplete, so
+ * it refreshes every couple of seconds; once the snapshot is complete it drops
+ * to a slow poll. A missing route (the host half is off) hides the card rather
+ * than failing the mount.
+ */
+import { type StatsSnapshot } from '../../../shared/stats.ts';
+import type { Logger } from '../../contracts/ports.ts';
+/** One snapshot reader the card subscribes to. */
+export interface StatsSource {
+    /** The last accepted snapshot, or null while there is none. */
+    readonly current: StatsSnapshot | null;
+    /** Observe snapshots; returns the unsubscribe function. */
+    subscribe(listener: (snapshot: StatsSnapshot | null) => void): () => void;
+    /** Stop polling and abort any read in flight. */
+    dispose(): void;
+}
+/**
+ * Start polling the host's statistics route.
+ *
+ * @param options - logger and an optional route override (tests).
+ * @returns the live source.
+ */
+export declare function createStatsSource(options: {
+    logger: Logger;
+    url?: string;
+}): StatsSource;

package/lib/types/client/features/statistics/view.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Snapshot → card data: the reference's own presentation rules.
+ *
+ * Two views share one snapshot. `Overview` draws 182 days (26 columns × 7 rows)
+ * ending on the Saturday of the current week, with the day rows running
+ * Sunday-first — the window the reference computes — and levels of
+ * `ceil(count / busiest day * 4)`; days after today are transparent rather than
+ * empty, which is why the card data marks them instead of giving them a level.
+ * `Models` draws one bar per day that produced tokens, stacked by model and
+ * scaled to the axis the reference derives from the busiest day.
+ *
+ * The range switch filters the tiles, the chart and the footer sentence, but
+ * not the heatmap or `Peak hour`: the reference feeds both from unfiltered
+ * statistics, and its heatmap is a fixed 182-day window.
+ */
+import { type StatsDay, type StatsRangeId, type StatsSnapshot } from '../../../shared/stats.ts';
+import { type HeatCell, type StatsCardData, type StatsModelsData, type StatsOption, type StatsOverviewData, type StatsTabId } from './card.ts';
+import { formatCount, formatDayLabel, formatHour, formatTokens } from './format.ts';
+export { formatCount, formatDayLabel, formatHour, formatTokens };
+/** Days the heatmap draws: 26 weeks. */
+export declare const HEAT_DAYS: number;
+/** The reference's own tabs, in its order. */
+export declare const STATS_TABS: readonly StatsOption<StatsTabId>[];
+/** The reference's own ranges, in its order. */
+export declare const STATS_RANGE_OPTIONS: readonly StatsOption<StatsRangeId>[];
+/** Which view and range the card is showing. */
+export interface StatsViewState {
+    readonly tab: StatsTabId;
+    readonly range: StatsRangeId;
+}
+/** What a freshly mounted card shows, matching the reference's defaults. */
+export declare const INITIAL_STATS_VIEW: StatsViewState;
+/** What the card draws for the 182-day window. */
+export interface HeatWindow {
+    /** One cell per day, column-major: `column * 7 + row`, Sunday first. */
+    readonly heat: readonly HeatCell[];
+    /** First index drawn after today; those cells stay transparent. */
+    readonly futureFrom: number;
+}
+/**
+ * Lay the host's sparse day counts out on the reference's 26-week grid.
+ *
+ * @param days - local day keys with their counts.
+ * @param now - the current instant (injectable for tests).
+ * @returns the cells and where "today" ends.
+ */
+export declare function heatWindow(days: readonly StatsDay[], now?: Date): HeatWindow;
+/**
+ * The reference's y-axis steps: from `1/2/5/10/20/50` scaled to the magnitude
+ * of `max / 6`, keep the candidates that fit in six steps and take the one
+ * whose top is lowest, preferring four steps on a tie.
+ *
+ * @param max - the busiest day's tokens.
+ * @returns the tick values, lowest first; empty when there is nothing to scale.
+ */
+export declare function tokenTicks(max: number): number[];
+/**
+ * The colour of the n-th busiest model.
+ *
+ * The reference computes `hsl(217 70% min(88, 58 + 7n)%)`, which flattens into
+ * six shades; the theme carries those six so both themes can express them.
+ *
+ * @param index - position in the range's model list.
+ * @returns a theme variable holding that shade.
+ */
+export declare function modelColor(index: number): string;
+/**
+ * The `Overview` body for one range.
+ *
+ * @param snapshot - the host's aggregate.
+ * @param range - the selected range.
+ * @param random - stable draw for the footer's book choice.
+ * @param now - the current instant (injectable for tests).
+ * @returns tiles, heat cells and the footer sentence.
+ */
+export declare function buildOverview(snapshot: StatsSnapshot, range: StatsRangeId, random: () => number, now?: Date): StatsOverviewData;
+/**
+ * The `Models` body for one range.
+ *
+ * @param snapshot - the host's aggregate.
+ * @param range - the selected range.
+ * @param now - the current instant (injectable for tests).
+ * @returns the chart and its legend.
+ */
+export declare function buildModels(snapshot: StatsSnapshot, range: StatsRangeId, now?: Date): StatsModelsData;
+/**
+ * Build everything the card draws for one snapshot and view state.
+ *
+ * @param snapshot - the host's aggregate.
+ * @param state - the selected tab and range.
+ * @param random - stable draw for the footer's book choice.
+ * @param now - the current instant (injectable for tests).
+ * @returns the card data.
+ */
+export declare function buildCardData(snapshot: StatsSnapshot, state: StatsViewState, random: () => number, now?: Date): StatsCardData;

package/lib/types/client/features/tool-calls/index.d.ts

@@ -0,0 +1,2 @@
+import type { PlannedFeature } from '../../contracts/feature.ts';
+export declare const toolCallsFeature: PlannedFeature;

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

@@ -0,0 +1 @@
+export { apply, inject } from './apply.ts';

package/lib/types/client/theme/mount.d.ts

@@ -0,0 +1,15 @@
+import type { FeatureEnvironment } from '../contracts/feature.ts';
+import type { CleanupScope } from '../core/cleanup.ts';
+/**
+ * Plugin-scoped presentation base: the root activation marker, the design
+ * variables, the shared Composer geometry two features depend on (siblings must
+ * not import each other), the host popup chrome (DESIGN.md §6.7) and the
+ * semantic token overrides.
+ *
+ * The override layer is recomputed on every mount, so a configuration change
+ * releases the previous layer through the same scope that owns the stylesheets
+ * and stacks the new one; `overrideTokens` replaces a source's layer wholesale.
+ * @param environment - activation services and configuration.
+ * @param scope - activation scope owning every resource mounted here.
+ */
+export declare function mountTheme(environment: FeatureEnvironment, scope: CleanupScope): void;

package/lib/types/client/theme/palette.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Colour arithmetic behind the configurable surfaces.
+ *
+ * The plugin ships one light palette; a user-supplied background therefore has
+ * to bring its own hover, selection and line steps, or a dark canvas would keep
+ * light grey rows. Every value here is derived from the two configured colours
+ * with fixed ratios, so the result is deterministic and testable — and no other
+ * stylesheet gains a literal colour (see `scripts/check-architecture.mjs`).
+ *
+ * The dark palette is not derived: it is a fixed set of values measured for the
+ * dark canvas and mirrored by `theme/tokens.css`, because a colour the user
+ * picked for a light canvas says nothing about the dark one.
+ */
+export interface Rgb {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+/** The surfaces a configured background produces. */
+export interface Palette {
+    readonly canvas: string;
+    readonly sidebar: string;
+    readonly card: string;
+    readonly track: string;
+    readonly raised: string;
+    readonly hover: string;
+    readonly selected: string;
+    readonly border: string;
+    readonly borderStrong: string;
+    readonly borderSoft: string;
+    readonly tableHeadLine: string;
+}
+/**
+ * Built-in surfaces, byte-identical to the fallback declarations in
+ * `theme/tokens.css` (`--ccd-canvas`, `--ccd-sidebar`, `--ccd-border`); a local
+ * test parses that stylesheet and fails when the two drift apart.
+ */
+export declare const BUILT_IN_SURFACES: Readonly<{
+    canvas: "#fcfcfb";
+    sidebar: "#fbfbfa";
+    border: "#e3e3e1";
+}>;
+/**
+ * Built-in dark palette, byte-identical to the dark block of
+ * `theme/tokens.css`; a local test parses that stylesheet and fails when the two
+ * drift apart. Configured backgrounds do not reach this mode (see the file
+ * comment), so the theme layer can publish these values as the `dark` side of
+ * every surface pair.
+ */
+export declare const BUILT_IN_DARK: Palette;
+/**
+ * Parse one normalized `#rrggbb` colour.
+ * @param value - the colour to parse.
+ * @returns its channels, or undefined when it is not a six-digit hex colour.
+ */
+export declare function parseColour(value: string): Rgb | undefined;
+/**
+ * Format channels as lowercase `#rrggbb`.
+ * @param rgb - channels to format.
+ * @returns the CSS colour.
+ */
+export declare function formatColour(rgb: Rgb): string;
+/**
+ * Mix one colour toward another.
+ * @param base - the colour being adjusted.
+ * @param toward - the colour mixed in.
+ * @param ratio - share of `toward`, from 0 to 1.
+ * @returns the mixed colour.
+ */
+export declare function mixColour(base: Rgb, toward: Rgb, ratio: number): Rgb;
+/**
+ * Derive every surface step from the two configured backgrounds.
+ *
+ * An empty or unusable value falls back to the built-in surface, so the theme
+ * layer can call this with raw configuration and still get usable colours.
+ * @param canvas - normalized conversation/canvas background, or empty.
+ * @param sidebar - normalized sidebar background, or empty.
+ * @returns the palette the theme layer publishes as tokens.
+ */
+export declare function derivePalette(canvas: string, sidebar: string): Palette;

package/lib/types/client/theme/tokens.d.ts

@@ -0,0 +1,27 @@
+import type { ThemeTokenOverrides } from '@deepseek-ai/dsh-client-ui-theme/client';
+import type { StyleConfig } from '../../shared/config.ts';
+/**
+ * Compose host semantic tokens and configured --ccd-* overrides as light/dark
+ * pairs. The theme presenter writes the active values onto body. Configured
+ * backgrounds affect light mode; dark mode uses the built-in palette. Font
+ * choices apply to both schemes. Other values come from theme/tokens.css.
+ */
+export declare const THEME_OVERRIDE_SOURCE = "dsh-ccd-style";
+/** Host semantic surfaces the CCD canvas replaces. */
+export declare const HOST_SURFACE_TOKENS: Readonly<{
+    base: "--dsw-alias-bg-base";
+    sidebar: "--dsw-specific-sidebar-fill";
+    border: "--dsw-alias-border-l3";
+}>;
+/** Host typography tokens; both drive app-wide stacks. */
+export declare const HOST_FONT_TOKENS: Readonly<{
+    ui: "--dsw-font-family";
+    code: "--ds-font-family-code";
+}>;
+/**
+ * Resolve the whole override layer for one configuration.
+ * @param config - the adopted configuration section.
+ * @returns token overrides keyed by custom-property name; never empty, because
+ * the host surface tokens always travel with the plugin's own canvas.
+ */
+export declare function resolveThemeTokens(config: StyleConfig): ThemeTokenOverrides;

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

@@ -0,0 +1,106 @@
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Fields are marked `.volatile()` so the DSH settings layer projects them into
+ * a configuration form: only volatile paths are served to the client
+ * (`dsh-settings` `volatileForm`/`projectForm`), and the generated form is what
+ * the browser half reads through `ctx.configForms.get(entryId)`. Marking them
+ * also gives the plugin a real settings surface: the row configuration page
+ * registered by the browser half writes these paths back through the same
+ * transport, and the Host validates the whole candidate before touching disk.
+ *
+ * The `pattern` guards are the first of three: the settings boundary rejects an
+ * unusable candidate, the configuration page validates before it submits, and
+ * `adoptConfig` falls back to the defaults for a hand-edited patch file.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    debug: z<boolean, boolean, "volatile-defined">;
+    features: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        shell: z<boolean, boolean, "defined">;
+        sidebar: z<boolean, boolean, "defined">;
+        'new-session': z<boolean, boolean, "defined">;
+        conversation: z<boolean, boolean, "defined">;
+        'tool-calls': z<boolean, boolean, "defined">;
+        statistics: z<boolean, boolean, "defined">;
+        'composer-pet': z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        shell: z<boolean, boolean, "defined">;
+        sidebar: z<boolean, boolean, "defined">;
+        'new-session': z<boolean, boolean, "defined">;
+        conversation: z<boolean, boolean, "defined">;
+        'tool-calls': z<boolean, boolean, "defined">;
+        statistics: z<boolean, boolean, "defined">;
+        'composer-pet': z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
+    appearance: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        canvas: z<string, string, "defined">;
+        sidebar: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        canvas: z<string, string, "defined">;
+        sidebar: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
+    fonts: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        uiLatin: z<string, string, "defined">;
+        uiCjk: z<string, string, "defined">;
+        code: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        uiLatin: z<string, string, "defined">;
+        uiCjk: z<string, string, "defined">;
+        code: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    debug: z<boolean, boolean, "volatile-defined">;
+    features: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        shell: z<boolean, boolean, "defined">;
+        sidebar: z<boolean, boolean, "defined">;
+        'new-session': z<boolean, boolean, "defined">;
+        conversation: z<boolean, boolean, "defined">;
+        'tool-calls': z<boolean, boolean, "defined">;
+        statistics: z<boolean, boolean, "defined">;
+        'composer-pet': z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        shell: z<boolean, boolean, "defined">;
+        sidebar: z<boolean, boolean, "defined">;
+        'new-session': z<boolean, boolean, "defined">;
+        conversation: z<boolean, boolean, "defined">;
+        'tool-calls': z<boolean, boolean, "defined">;
+        statistics: z<boolean, boolean, "defined">;
+        'composer-pet': z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
+    appearance: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        canvas: z<string, string, "defined">;
+        sidebar: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        canvas: z<string, string, "defined">;
+        sidebar: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
+    fonts: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        uiLatin: z<string, string, "defined">;
+        uiCjk: z<string, string, "defined">;
+        code: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        uiLatin: z<string, string, "defined">;
+        uiCjk: z<string, string, "defined">;
+        code: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Host half: the configuration surface the interface reads, plus the read-only
+ * session-log fold behind the statistics card.
+ *
+ * The card's numbers come from a projection unit of the host's own session
+ * projection seam (see `stats/unit.ts`) and are served over the host's
+ * authenticated fetch registry; nothing is written back to a profile, a
+ * session log, or any second state store.
+ *
+ * Registration follows the plugin switch alone: while the plugin is on, the
+ * fold and the route are live, so turning the statistics *feature* on in the
+ * settings page shows the card without a restart. Turning the plugin itself
+ * off costs the host nothing, because nothing is registered at all.
+ *
+ * @param ctx - host plugin context.
+ * @param config - resolved Host configuration cells (validated by the loader).
+ */
+export declare function apply(ctx: Context, config: unknown): void;

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

@@ -0,0 +1,38 @@
+/**
+ * Cross-session aggregation: many per-session fold results → one card snapshot.
+ *
+ * Pure and synchronous, so the numbers the card shows are testable without a
+ * host: the service layer owns the session listing, the cold reads and the
+ * transport, this file owns only the arithmetic.
+ *
+ * The card offers the reference's three ranges, and the reference computes all
+ * of them from the same per-day tables: a range is a lower date bound
+ * (`start = today - (days - 1)`) over days, messages and per-day model tokens,
+ * while each session is counted once when any of its active days falls inside
+ * the range. `Peak hour` is the one tile the reference leaves unfiltered — it
+ * reads that value from its unfiltered statistics — so the hour histogram here
+ * is all-time as well.
+ *
+ * The one bounded output is the shipped day list: the ranges count every
+ * active day, while `days` and `modelDays` carry only the most recent
+ * {@link STATS_DAY_LIMIT} days so a long-lived install cannot grow the
+ * response without limit.
+ */
+import { type StatsSessionUsage, type StatsSnapshot } from '../../shared/stats.ts';
+/** Counters the aggregate needs from outside the fold. */
+export interface AggregateOptions {
+    /** Computation time, epoch ms. */
+    readonly now: number;
+    /** Sessions still being folded. */
+    readonly pending: number;
+    /** Sessions whose logs could not be read. */
+    readonly missed: number;
+}
+/**
+ * Aggregate every session's fold result into the card's snapshot.
+ *
+ * @param values - one view per visible stored session.
+ * @param options - computation time and the service's progress counters.
+ * @returns the snapshot the route serves.
+ */
+export declare function aggregateUsage(values: Iterable<StatsSessionUsage>, options: AggregateOptions): StatsSnapshot;

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

@@ -0,0 +1,18 @@
+/**
+ * Read live session projections first, then durable checkpoints, then cold-fold
+ * missing checkpoints in the background. Failed sessions retry after cooldown.
+ * Aggregates are served through the host's authenticated connection.fetch route.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Mount the aggregation and its route, once the host services it needs exist.
+ *
+ * A plugin's `apply` runs as soon as its own fiber starts, which can be before
+ * the session projection registry and the connection carrier: the optional
+ * injection below waits for both, and a deployment that mounts neither simply
+ * never gets the card.
+ *
+ * @param ctx - host plugin context.
+ * @param isEnabled - current plugin switch, read at mount time.
+ */
+export declare function mountStatistics(ctx: Context, isEnabled: () => boolean): void;