dsh-claude-desktop-theme 0.2.0

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

@@ -0,0 +1,16 @@
+import type { ImplementedFeature } from '../../contracts/feature.ts';
+/**
+ * Conversation page presentation. The transcript, its scroll behaviour, tool
+ * rows, approvals and the resident Composer are all DSH's; this module only
+ * adapts the header chrome, the transcript column and the message surfaces.
+ *
+ * The header keeps DSH's own View switcher: the host still owns which View is
+ * selected and how it is rendered, and this module only moves the tablist onto
+ * the title line and publishes the selected segment's geometry so the
+ * stylesheet can slide the thumb onto it.
+ *
+ * The transcript's own edge fade is published the same way: the host owns the
+ * scroll position, `compat/conversation-fade.ts` turns it into two attributes,
+ * and the stylesheet prints the stencil.
+ */
+export declare const conversationFeature: ImplementedFeature;

package/lib/types/client/features/model-controls/EffortPanel.d.ts

@@ -0,0 +1,14 @@
+import type { RefObject } from 'react';
+import type { EffortChoice } from './selection.ts';
+export interface EffortPanelProps {
+    readonly anchor: RefObject<HTMLButtonElement>;
+    readonly choices: readonly EffortChoice[];
+    readonly selected: number;
+    readonly disabled: boolean;
+    readonly busy: boolean;
+    readonly error: string | null;
+    readonly onCommit: (index: number) => void;
+    readonly onClose: () => void;
+}
+/** Presentation-only slider: continuous local preview, one supported choice on release. */
+export declare function EffortPanel({ anchor, choices, selected, disabled, busy, error, onCommit, onClose }: EffortPanelProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/types/client/features/model-controls/ModelControls.d.ts

@@ -0,0 +1,11 @@
+import type { ModelSelectInjected } from '@deepseek-ai/dsh-client-ui-model-selection/client';
+import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ModelSelection } from '@deepseek-ai/dsh-api-session-controller/types';
+export type ModelControlsProps = Omit<ModelSelectInjected, 'directory'> & PropsLocale<'model'> & {
+    readonly locked: boolean;
+    readonly useDirectory: () => ModelDirectoryState;
+    readonly selectEffort: (route: ModelSelection, effort: string | undefined) => void;
+};
+/** SDK-derived values/hooks and callbacks only; DSH retains all business state. */
+export declare function ModelControls({ locked, available, useDirectory, load, select, selectEffort, t }: ModelControlsProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/types/client/features/model-controls/mount.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { FeatureEnvironment } from '../../contracts/feature.ts';
+import type { CleanupScope } from '../../core/cleanup.ts';
+/** Register a presentation occupant over the native seat, sharing its official directory. */
+export declare function mountModelControls(ctx: Context, environment: FeatureEnvironment, cleanup: CleanupScope): void;

package/lib/types/client/features/model-controls/pixels.d.ts

@@ -0,0 +1,4 @@
+/** Pixel flow and magnetic/spring constants adapted from zanwei/claude-model-selector, MIT. */
+export declare const clamp: (value: number, min: number, max: number) => number;
+export declare function magnet(value: number): number;
+export declare function drawPixelField(canvas: HTMLCanvasElement, elapsed: number, reduced: boolean): void;

package/lib/types/client/features/model-controls/popup.d.ts

@@ -0,0 +1,10 @@
+import type { RefObject } from 'react';
+/** Viewport-clamped top-layer surface; focus and observers die with the panel. */
+export declare function usePopup(anchor: RefObject<HTMLButtonElement>, close: () => void): {
+    panel: RefObject<HTMLDivElement>;
+    position: {
+        left: number;
+        top: number;
+        visibility: 'hidden' | 'visible';
+    };
+};

package/lib/types/client/features/model-controls/selection.d.ts

@@ -0,0 +1,66 @@
+import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client';
+import type { ModelCatalogModel, ModelSelection } from '@deepseek-ai/dsh-api-session-controller/types';
+export interface EffortChoice {
+    readonly id: string | undefined;
+    readonly name: string;
+}
+/** What the Effort card derives from one catalog route and its saved selection. */
+export interface EffortView {
+    /** Slider stops: the advertised tiers in provider order; empty when the model advertises none. */
+    readonly choices: readonly EffortChoice[];
+    /** Stop the thumb rests on before any drag: the saved tier, else the provider's own tier, else the first stop. */
+    readonly preview: number;
+    /** Effective effort id: the saved tier, else the provider's advertised default. */
+    readonly effort: string | undefined;
+    /** Caption the trigger shows: the name of the stop `preview` marks, else the retained one, else the empty-catalog fallback. */
+    readonly caption: string | undefined;
+}
+/** The two captions the card cannot derive from the catalog alone. */
+export interface EffortViewCopy {
+    /** Fallback caption for a catalog that answers with no tier to name, read only where the trigger stays disabled. */
+    readonly defaultName: string;
+    /** Caption the directory retained for a route that left the catalog. */
+    readonly retainedEffort?: string | undefined;
+}
+/**
+ * Derive the commit-time validation domain of one route.
+ *
+ * The card's stops are the advertised tiers alone — see `effortView`, which
+ * lays the slider out — so this list is not what the panel shows. It is kept
+ * because `effortSelection` validates against it, and that domain is the
+ * historical one: a catalog naming no default still admits `undefined` as
+ * "follow the provider default" beside every tier it advertises.
+ *
+ * @param model - the route's catalog model.
+ * @param defaultName - caption the absent default is admitted under.
+ * @returns every id a commit may carry, in provider order.
+ */
+export declare function effortChoices(model: ModelCatalogModel | undefined, defaultName: string): EffortChoice[];
+/**
+ * Lay out the card's stops, the resting thumb, and the trigger caption.
+ *
+ * The stops are the model's advertised tiers in provider order: the provider
+ * default is a *position* on that track, never a stop of its own, so a catalog
+ * that names no default — or names one its tiers do not carry — has no position
+ * to mark rather than an extra stop to show. `preview` rests the thumb on the
+ * saved tier while the catalog still carries it, else on the tier the provider
+ * names as its default, else on the first stop: the historical resting place,
+ * now reached without a Default stop to fall back onto.
+ *
+ * The caption names the stop the thumb rests on, so the trigger can never
+ * advertise a tier the panel has no stop for. Two states stay outside that
+ * reading because the catalog cannot name them: a route that left the catalog
+ * keeps the directory's retained caption, and a route with nothing on the
+ * track keeps `copy.defaultName` — the host's own wording — as its only
+ * honest fallback, on a trigger that is disabled and opens no panel anyway.
+ *
+ * @param model - the route's catalog model.
+ * @param current - the saved selection of that same route.
+ * @param copy - the empty-catalog caption and the directory's retained one.
+ * @returns stops, the resting thumb, the effective effort id, and the trigger caption.
+ */
+export declare function effortView(model: ModelCatalogModel | undefined, current: ModelSelection | null, copy: EffortViewCopy): EffortView;
+/** Same-model picks retain effort; a different model starts at its own default. */
+export declare function modelSelection(provider: string, model: ModelCatalogModel, current: ModelSelection | null): ModelSelection;
+/** Read the latest directory at commit time so a stale drag cannot change another model. */
+export declare function effortSelection(state: ModelDirectoryState, route: ModelSelection, effort: string | undefined): ModelSelection | null;

package/lib/types/client/features/new-session/index.d.ts

@@ -0,0 +1,8 @@
+import type { ImplementedFeature } from '../../contracts/feature.ts';
+/**
+ * Blank-session page. DSH renders the Conversation shell in its `hero` phase
+ * here, so this module only moves what the reference moves — the greeting to
+ * the top of the column and the Composer block to the bottom — and leaves the
+ * phase transition itself to the host.
+ */
+export declare const newSessionFeature: ImplementedFeature;

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

@@ -0,0 +1,28 @@
+import type { ReactElement } from 'react';
+import type { ConfigFormPort, ThemePreferencePort } from '../../contracts/ports.ts';
+/** Translate one dictionary key; the locale seat supplies the real one. */
+export type SettingsTranslate = (key: string, params?: Record<string, unknown>) => string;
+/** Props the registration layer derives; the component never sees `ctx`. */
+export interface ConfigPageProps {
+    /** Page host's occurrence view: `summary` beside a row title, `page` for the form. */
+    readonly view?: string | undefined;
+    /** Locale seat synthesized from the registration's namespace. */
+    readonly t?: SettingsTranslate | undefined;
+    /** This plugin's own configuration form, passed by the assembly layer. */
+    readonly form: ConfigFormPort;
+    /** The native theme preference, or null when the theme service lacks it. */
+    readonly themePreference?: ThemePreferencePort | null | undefined;
+}
+/**
+ * The row configuration page registered for `plugins.row.config`.
+ *
+ * The page writes as you go: a switch, a colour, a chosen family or a settled
+ * text field is submitted immediately, so there is no save button and no draft
+ * to reconcile — the served configuration is the only state the controls read.
+ * Text fields keep a local buffer until they are left or confirmed, because a
+ * half-typed colour must not reach the settings boundary.
+ * @param props - Occurrence view, locale seat, the plugin's form and the
+ * features whose mounts are still planned.
+ * @returns The summary line or the configuration form.
+ */
+export declare function ConfigPage(props: ConfigPageProps): ReactElement;

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

@@ -0,0 +1,37 @@
+import type { ReactElement } from 'react';
+/**
+ * The installed-family menu behind a typeface row's select box.
+ *
+ * It is drawn by the plugin rather than by a native `<datalist>`: the native
+ * popup is an OS widget that ignores this page's styles and, in the desktop
+ * window, does not scroll with the wheel — with several hundred families that
+ * is unusable. The panel is positioned against the select box and closed by
+ * Escape, an outside click, a scroll or a resize.
+ */
+export interface FontMenuLabels {
+    readonly search: string;
+    readonly empty: string;
+    readonly count: (count: number) => string;
+    readonly unavailable: string;
+    /** Row offered for a family the list does not carry. */
+    readonly useTyped: (name: string) => string;
+}
+export interface FontMenuProps {
+    /** The select box this menu hangs from; the menu follows it while it scrolls. */
+    readonly anchor: HTMLElement;
+    /** Installed families; empty when the environment cannot provide them. */
+    readonly families: readonly string[];
+    /** The served family, marked in the list. */
+    readonly value: string;
+    readonly labels: FontMenuLabels;
+    readonly onSelect: (family: string) => void;
+    /** Commit a family the list does not carry, typed into the search field. */
+    readonly onUseText: (text: string) => void;
+    readonly onClose: () => void;
+}
+/**
+ * One open family menu.
+ * @param props - The anchor rectangle, the families, the served value and callbacks.
+ * @returns The searchable, scrollable panel.
+ */
+export declare function FontMenu(props: FontMenuProps): ReactElement;

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

@@ -0,0 +1,39 @@
+import type { SettingsPathOp } from '../../contracts/ports.ts';
+import type { SettingsKey } from './locales.ts';
+/**
+ * Field edits for a page that writes as you go.
+ *
+ * There is no draft: every control commits the moment its value is settled, so
+ * each helper below turns one settled input into the single operation the
+ * settings transport should carry — or into the reason it must not be sent.
+ */
+/** Per-field validation failures, keyed by dictionary label. */
+export type FieldErrors = Partial<Record<string, SettingsKey>>;
+/** One field write. */
+export declare function setOperation(path: readonly string[], value: unknown): SettingsPathOp;
+/** One field clear, restoring the schema default. */
+export declare function unsetOperation(path: readonly string[]): SettingsPathOp;
+export interface TextCommit {
+    /** The write to send, absent when nothing changed or the value is unusable. */
+    readonly op?: SettingsPathOp;
+    /** Why an unusable value was refused. */
+    readonly error?: SettingsKey;
+    /** The text the field should keep showing. */
+    readonly text: string;
+}
+/**
+ * Settle one colour field.
+ * @param path - the field's path inside the configuration section.
+ * @param raw - what the field currently shows.
+ * @param current - the served value it started from.
+ * @returns the write, the refusal, or nothing when the value already matches.
+ */
+export declare function commitColour(path: readonly string[], raw: string, current: string): TextCommit;
+/**
+ * Settle one typeface field.
+ * @param path - the field's path inside the configuration section.
+ * @param raw - what the field currently shows.
+ * @param current - the served value it started from.
+ * @returns the write, the refusal, or nothing when the value already matches.
+ */
+export declare function commitFont(path: readonly string[], raw: string, current: string): TextCommit;

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

@@ -0,0 +1,83 @@
+import type { MouseEvent, ReactElement } from 'react';
+import type { ThemePreference } from '../../contracts/ports.ts';
+import type { FontMenuLabels } from './FontMenu.tsx';
+export interface SwitchRowProps {
+    readonly id: string;
+    readonly label: string;
+    readonly hint?: string;
+    readonly checked: boolean;
+    readonly onChange: (checked: boolean) => void;
+}
+/**
+ * One boolean row: a labelled sliding switch, the shape the host's own settings
+ * rows use.
+ * @param props - Identity, copy, current value and the change callback.
+ * @returns The row.
+ */
+export declare function SwitchRow({ id, label, hint, checked, onChange }: SwitchRowProps): ReactElement;
+export interface ThemeOption {
+    readonly id: ThemePreference;
+    readonly label: string;
+}
+export interface ThemeRowProps {
+    readonly id: string;
+    readonly label: string;
+    readonly hint?: string;
+    /** The persisted preference, straight from the theme service snapshot. */
+    readonly value: ThemePreference;
+    readonly options: readonly ThemeOption[];
+    readonly onChange: (preference: ThemePreference) => void;
+}
+/**
+ * One theme row: a recessed track with one glyph per preference and the chosen
+ * segment raised, the shape the reference screenshot uses. The value is the
+ * service's own preference, never a local copy, so the control cannot disagree
+ * with the host's Appearance row.
+ * @param props - Identity, copy, current preference and the change callback.
+ * @returns The row.
+ */
+export declare function ThemeRow(props: ThemeRowProps): ReactElement;
+export interface ColourRowProps {
+    readonly id: string;
+    readonly label: string;
+    readonly hint?: string;
+    readonly value: string;
+    readonly placeholder: string;
+    readonly resetLabel: string;
+    readonly error?: string;
+    readonly onChange: (value: string) => void;
+    readonly onCommit: () => void;
+    readonly onReset: () => void;
+}
+/**
+ * One background-colour row: a bordered hex field, written when it is left.
+ * @param props - Identity, copy, current text and callbacks.
+ * @returns The row.
+ */
+export declare function ColourRow(props: ColourRowProps): ReactElement;
+export interface FontRowProps {
+    readonly id: string;
+    readonly label: string;
+    readonly hint?: string;
+    readonly value: string;
+    readonly placeholder: string;
+    readonly resetLabel: string;
+    readonly error?: string;
+    /** The open family menu's anchor box, or undefined while it is closed. */
+    readonly anchor: HTMLElement | undefined;
+    readonly families: readonly string[];
+    readonly menuLabels: FontMenuLabels;
+    readonly onToggle: (event: MouseEvent<HTMLButtonElement>) => void;
+    readonly onSelect: (family: string) => void;
+    readonly onUseText: (text: string) => void;
+    readonly onCloseMenu: () => void;
+    readonly onReset: () => void;
+}
+/**
+ * One typeface row: a select box that shows the served family and opens the
+ * installed-family menu; a family the list does not carry can be typed into
+ * that menu's search field.
+ * @param props - Identity, copy, current value, menu state and callbacks.
+ * @returns The row and, when open, its menu.
+ */
+export declare function FontRow(props: FontRowProps): ReactElement;

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

@@ -0,0 +1,40 @@
+/**
+ * System font families for the typeface rows.
+ *
+ * Chromium exposes installed fonts through the Local Font Access API
+ * (`window.queryLocalFonts()`, Chromium 103+). In the DSH desktop window the
+ * permission is granted without a prompt — the application's own permission
+ * handlers allow every non-media permission — while a plain browser either
+ * prompts or answers with an empty list; browsers without the API answer with
+ * nothing at all. All three outcomes collapse to "no list", and the rows keep
+ * accepting a typed family name.
+ *
+ * The query runs on first focus (a user gesture, which the permission needs)
+ * and the result is cached for the page session, so moving between rows or
+ * pages never asks twice.
+ */
+/** The slice of `FontData` this module reads. */
+export interface LocalFontLike {
+    readonly family?: unknown;
+}
+/**
+ * Collapse font faces into the family names a `font-family` value accepts.
+ * @param fonts - faces as the browser reported them.
+ * @returns unique, non-empty family names sorted for a Chinese interface.
+ */
+export declare function collectFamilies(fonts: readonly LocalFontLike[]): string[];
+/**
+ * Filter families for one query, case-insensitively.
+ * @param families - family names in their display order.
+ * @param query - what the user typed.
+ * @returns the matching families, order preserved.
+ */
+export declare function filterFamilies(families: readonly string[], query: string): string[];
+/**
+ * Read the installed font families once per page session.
+ * @returns the sorted families, or an empty array when the environment cannot
+ * provide them (no API, denied permission, or an empty answer).
+ */
+export declare function loadSystemFontFamilies(): Promise<string[]>;
+/** Test seam: forget the cached answer. */
+export declare function resetSystemFontFamilies(): void;

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

@@ -0,0 +1,61 @@
+/**
+ * Copy for the row configuration page.
+ *
+ * The page is the plugin's only owned surface with its own words: everything
+ * else mirrors a host label. The dictionary is registered through the locale
+ * service and the keys are merged into the slots' namespace table, so the `t`
+ * seat stays typed and follows the user's language without a remount.
+ */
+export declare const SETTINGS_NAMESPACE = "ccdSettings";
+/** Simplified Chinese dictionary; the key set is the source of truth. */
+export declare const zh: {
+    readonly summary: 'CCD 风格界面 · 外观 · 字体';
+    readonly 'section.general': '通用';
+    readonly 'section.features': '模块';
+    readonly 'section.appearance': '外观';
+    readonly 'section.fonts': '字体';
+    readonly 'field.enabled': '启用 CCD 风格界面';
+    readonly 'field.theme': '主题';
+    readonly 'theme.system': '跟随系统';
+    readonly 'theme.light': '浅色';
+    readonly 'theme.dark': '深色';
+    readonly 'field.canvas': '会话背景色';
+    readonly 'field.sidebar': '侧栏背景色';
+    readonly 'note.coloursApplyToLight': '自定义背景色只作用于浅色模式；深色模式使用内置深色调色板。';
+    readonly 'note.unknownBuild': '当前 DSH 构建未登记：它的宿主类名与插件记录的两套构建都不一致，界面样式不会生效，请按 host-builds.ts 的说明重新登记。';
+    readonly 'field.uiLatin': '界面字体';
+    readonly 'field.uiCjk': '界面中文字体';
+    readonly 'field.code': '代码与等宽字体';
+    readonly 'hint.fontListUnavailable': '当前环境不提供系统字体清单，请直接输入字体族名（例如 PingFang SC）。';
+    readonly 'placeholder.font': '留空使用系统字体';
+    readonly 'placeholder.colour': '#fcfcfb';
+    readonly 'action.reset': '恢复默认';
+    readonly 'picker.search': '搜索字体';
+    readonly 'picker.empty': '没有匹配的字体';
+    readonly 'picker.count': '共 {count} 个字体';
+    readonly 'picker.useTyped': '使用“{name}”';
+    readonly 'state.loading': '正在读取配置…';
+    readonly 'state.unavailable': '当前页面没有可写的配置（表单只在 DSH 桌面应用内可用）。';
+    readonly 'state.saving': '正在保存…';
+    readonly 'state.saved': '已保存';
+    readonly 'state.failed': '写入被拒绝：配置可能已被外部修改或不符合约束。';
+    readonly 'state.readonly': '当前配置不可写。';
+    readonly 'error.colour': '颜色需为 #rrggbb 或 #rgb';
+    readonly 'error.font': '字体名只能包含字母、数字、空格与 . _ -，且不超过 64 个字符';
+    readonly 'feature.shell': '窗口与分栏骨架';
+    readonly 'feature.sidebar': '侧栏';
+    readonly 'feature.new-session': '新建页';
+    readonly 'feature.conversation': '聊天页';
+    readonly 'feature.tool-calls': '工具调用展示';
+    readonly 'feature.statistics': '统计卡片';
+    readonly 'feature.composer-pet': '输入框小鲸鱼';
+};
+export type SettingsKey = keyof typeof zh;
+/** English dictionary; every Chinese key has a counterpart. */
+export declare const en: Record<SettingsKey, string>;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The row configuration page's copy. */
+        ccdSettings: SettingsKey;
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ConfigFormPort, DomPort, ThemePreferencePort } from '../../contracts/ports.ts';
+import type { CleanupScope } from '../../core/cleanup.ts';
+/**
+ * Register the configuration page for this plugin's own loader row.
+ *
+ * The page lives outside the activation scope on purpose: switching the
+ * interface off releases every style resource, and the page has to survive that
+ * to switch it back on.
+ * @param ctx - client context, injected for slots and the locale service.
+ * @param dom - style port owning the page's stylesheet.
+ * @param form - this plugin's configuration form.
+ * @param themePreference - the native theme preference face, or null when the
+ * theme service does not publish one.
+ * @param scope - scope owning the stylesheet, the dictionary and the registration.
+ */
+export declare function mountSettingsPage(ctx: Context, dom: DomPort, form: ConfigFormPort, themePreference: ThemePreferencePort | null, scope: CleanupScope): void;

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

@@ -0,0 +1,17 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReactElement } from 'react';
+import type { RowConfigPageProps } from '../../compat/plugin-manager.ts';
+/**
+ * Register the configuration page for one plugin row.
+ *
+ * The page owns its copy through the locale service and its form through the
+ * plugin's own `configForms` handle, so it needs only the slots and locale
+ * services. Both are injected as a pair: without an installed locale face a
+ * registration that declares a namespace fails loud at render time, so a
+ * deployment that lacks the service keeps the page unmounted instead.
+ * @param ctx - client context.
+ * @param key - `<package>#<row id>` of the row whose configuration page this is.
+ * @param component - the bound page component.
+ * @returns the injected scope, released with `dispose()`.
+ */
+export declare function registerSettingsPage(ctx: Context, key: string, component: (props: RowConfigPageProps) => ReactElement | null): Pick<ReturnType<Context['inject']>, 'dispose'>;

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

@@ -0,0 +1,8 @@
+import type { ImplementedFeature } from '../../contracts/feature.ts';
+/**
+ * Window frame and column geometry: flat surfaces, the sidebar column and its
+ * divider. The three tracks stay entirely `ui-layout`'s solve, so resizing the
+ * sidebar with the handle moves the divider the pointer is on; the plugin only
+ * paints the columns.
+ */
+export declare const shellFeature: ImplementedFeature;

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

@@ -0,0 +1,14 @@
+import type { ImplementedFeature } from '../../contracts/feature.ts';
+/**
+ * Sidebar presentation: compact navigation rows, flat project groups and a
+ * calmer foot. Every entry DSH registers — New Session, the global panel list,
+ * the workspace browser and Settings — stays exactly where the host put it; the
+ * account menu is reshaped, never re-authored.
+ *
+ * The one list policy this module owns is the provisional New Session row: DSH
+ * creates the Session as soon as New Session is used, and the host marks that
+ * row `blank` until the first message. The column keeps the row out of the list
+ * (see `compat/blank-session-rows.ts`), so the entry appears with the first sent
+ * message rather than with the click that opened the page.
+ */
+export declare const sidebarFeature: ImplementedFeature;

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

@@ -0,0 +1,34 @@
+/**
+ * The card's footer sentence: the reference's book comparison.
+ *
+ * The numbers are the reference's own, recovered from its bundle: ten titles
+ * with a token count each, and two message shapes. The rule is
+ *
+ * ```
+ * eligible = books the total already exceeds          (none → the line is hidden)
+ * book     = eligible[floor(random * eligible.length)] (drawn once per mount)
+ * times    = floor(total / book.tokens)
+ * times >= 2 → "You've used ~{times}× more tokens than {book}."
+ * otherwise  → "You've used about as many tokens as {book}."
+ * ```
+ *
+ * Only the sentence is copied; nothing is fetched and no book text is
+ * involved. The copy stays English, exactly as the reference writes it —
+ * including its typographic apostrophe and multiplication sign.
+ */
+/** One comparable book: the title as printed, and the tokens it would take. */
+export interface Book {
+    readonly name: string;
+    readonly tokens: number;
+}
+/** The reference's list, in its own order. */
+export declare const BOOKS: readonly Book[];
+/**
+ * Build the footer sentence for one token total.
+ *
+ * @param totalTokens - all-time token total at the provider's scale.
+ * @param random - one draw in `[0, 1)`; callers pass a value that is stable for
+ *   the lifetime of a mount, so the sentence does not change between polls.
+ * @returns the sentence, or null while no book is smaller than the total.
+ */
+export declare function bookNote(totalTokens: number, random: () => number): string | null;