@linxin666/dsh-usage 0.3.23 → 0.4.0

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

@@ -0,0 +1,55 @@
+/**
+ * Sidebar foot card: the compact usage glance seated below the shell sidebar's
+ * Settings row. It is deliberately a GLANCE, not the panel the 2026-09-18
+ * removal took out. Two states, persisted across reloads:
+ *
+ * - expanded (default): a price-first headline (today's estimated spend,
+ *   falling back to today's tokens when nothing priced was recorded), a
+ *   tokens/calls line, up to two configured-provider balances, and an
+ *   updated-at footer;
+ * - collapsed: a one-line strip with the gauge glyph, the spending
+ *   provider's name, the label and the headline value.
+ *
+ * The card body is one button that opens the settings panel on the usage
+ * section, so detail lives in exactly one place; the corner chevron toggles
+ * the collapse state (sibling buttons — buttons inside a button are invalid
+ * HTML).
+ *
+ * Data comes from the same shared store the settings section reads; the card
+ * runs its own relaxed poll loop (30 s, visible-tab only) because the sidebar
+ * foot is permanently mounted. The card disappears while the plugin is
+ * disabled (settings flag) or while the host serves no usage routes (a 404
+ * means the host half is off), matching the section's own gating.
+ * @module @linxin666/dsh-usage/client/UsageFootCard
+ */
+import { type ReactNode } from 'react';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type UsageSettings } from './UsageSectionCard.tsx';
+import type { UsageStoreInstance } from './usage-store.ts';
+/** Props the mount forwards into the React tree. */
+export interface UsageFootCardProps {
+    /** The shared overview store (section and card read the same snapshot). */
+    store: UsageStoreInstance;
+    /** Fetch one overview now. */
+    poll: () => void;
+    /** Card-body click: open the settings panel on the usage section. */
+    onOpen: () => void;
+    /** The shared settings form; the card hides while the plugin is disabled. */
+    settings: ConfigForm<UsageSettings>;
+    /** Locale-change source; the plain copy re-renders on a language switch. */
+    locale?: {
+        subscribe(listener: () => void): () => void;
+    };
+}
+/** Poll cadence of the permanently seated card; the section's 10 s loop stays its own. */
+export declare const FOOT_CARD_POLL_MS = 30000;
+/** localStorage key holding the collapsed flag ('1' = collapsed strip). */
+export declare const FOOT_CARD_COLLAPSED_KEY = "dsh-usage.foot-card.collapsed";
+/** Read the persisted collapsed flag (absent = expanded). */
+export declare function readFootCardCollapsed(): boolean;
+/**
+ * Render the foot card content for the current store snapshot.
+ * @param props - store, poller, settings form and open callback from the mount.
+ * @returns the card, or null while disabled / host-off.
+ */
+export declare function UsageFootCard(props: UsageFootCardProps): ReactNode;

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

@@ -8,13 +8,12 @@
  * @module @linxin666/dsh-usage/client/UsageSectionCard
  */
 import { type ReactNode } from 'react';
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { UsageStoreInstance } from './usage-store.ts';
 /** The settings fields this section edits (immediate-apply semantics). */
 export interface UsageSettings {
     enabled?: boolean;
     pollIntervalSec?: number;
-    bubbleMode?: string;
 }
 /** The registration-side face the section's slot entry injects. */
 export interface UsageSectionFace {
@@ -24,8 +23,8 @@ export interface UsageSectionFace {
     poll: () => void;
     /** Force a host probe cycle now (resolves with the fresh overview). */
     refresh: () => void;
-    /** Whether a forced refresh is in flight (component-local state mirrors it). */
-    settings: SettingsScope<UsageSettings>;
+    /** The shared configuration form this section's settings row reads and writes. */
+    settings: ConfigForm<UsageSettings>;
 }
 export interface UsageSectionProps extends UsageSectionFace {
     /** Close the settings panel (the shell owns the open state). */

package/lib/types/client/body-mutations.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One `document.body` MutationObserver per page, shared by every family
+ * plugin bundle.
+ *
+ * Family plugins that inject at the DOM level must notice when the shell
+ * re-renders around their injected node: the sidebar entry rows
+ * (sidebar-entry-core), the center-column panel containers
+ * (panel-mount-core), and the aggregate shell's column shims. Each consumer
+ * used to install its OWN `MutationObserver` on `document.body` with
+ * `{ childList: true, subtree: true }`, so a page carrying N family plugins
+ * paid N native observers and N callback invocations for EVERY mutation batch
+ * the app produced — chat token streaming alone produces many per second, and
+ * the count grows with the number of installed plugins.
+ *
+ * This module keeps exactly ONE body observer per page. The registry lives on
+ * `globalThis` under a `Symbol.for` key, so the per-package generated copies
+ * of this file (scripts/sync-shared.mjs) and separately bundled plugins all
+ * reach the same hub at runtime instead of one hub per module instance.
+ * Record subscribers receive the mutations accumulated since the last flush.
+ * Consumers that only re-check their DOM use subscribeBodyInvalidations:
+ * when all subscribers use that path, the hub retains no mutation records
+ * (or detached subtrees) while a background page's animation frames pause.
+ * Both paths run at most once per frame. The last subscriber disconnects the
+ * observer, cancels the pending frame and releases its records.
+ *
+ * Failure policy: without a DOM or `MutationObserver` the subscription is a
+ * no-op disposer (the same silence the per-consumer observers had), and when
+ * `requestAnimationFrame` is unavailable the flush runs synchronously so a
+ * subscriber is never silently dropped. A throwing subscriber cannot stop the
+ * others.
+ */
+/**
+ * Subscribe to a coalesced DOM re-check without retaining mutation records.
+ * The marked wrapper also works with an older hub, which delivers records
+ * that it simply ignores until a page reload picks up the updated hub.
+ */
+export declare function subscribeBodyInvalidations(subscriber: () => void): () => void;
+/**
+ * Subscribe to body-level childList mutations.
+ * @param subscriber - called at most once per animation frame with the records
+ *   collected since the previous flush; must be safe to run repeatedly.
+ * @returns the disposer removing this subscriber (and the observer when it was
+ *   the last one).
+ */
+export declare function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void;

package/lib/types/client/foot-card-mount.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sidebar foot card mounting.
+ *
+ * The foot's only slot (sidebar.footer.action) stacks ABOVE the Settings row
+ * and cannot host a block, so the card container is inserted into the shell's
+ * foot area directly above the Settings seat — keeping Settings the foot's
+ * terminal row instead of hanging a card off the sidebar floor. It self-heals
+ * with the page-wide body-mutation hub: a React re-render that displaces the
+ * container re-seats it on the next frame, and a whole-pane rebuild is noticed
+ * by the same body-level watcher the family entry rows use.
+ *
+ * The container is a plain div carrying its own React root, so it can never
+ * disturb the shell's reconciliation.
+ * @module @linxin666/dsh-usage/client/foot-card-mount
+ */
+import { type UsageFootCardProps } from './UsageFootCard.tsx';
+/** Stable data attribute identifying the injected card container. */
+export declare const FOOT_CARD_SELECTOR = "[data-dsh-usage-foot-card]";
+/**
+ * Open the settings panel on the usage section. The shell owns the panel's
+ * open state and exposes no service for it, so the card replays the user's
+ * own path: activate the sidebar Settings trigger, then pick the nav row
+ * carrying the section's (localized) label. Every step degrades silently —
+ * with the panel already open only the nav pick runs, and a missing row
+ * leaves the panel on its default section.
+ * @param label - the usage section's nav label in the active locale.
+ */
+export declare function openUsageSettings(label: () => string): void;
+/**
+ * Mount the sidebar foot card directly above the Settings row.
+ * @param props - the store/poll/settings/open inputs of the apply body.
+ * @returns disposer removing the container and its observers.
+ */
+export declare function mountUsageFootCard(props: UsageFootCardProps): () => void;

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

@@ -1,27 +1,40 @@
 /**
  * dsh-usage browser half — seats the first-level 使用统计 settings section
- * (below the Workshop entry) and polls the host overview only while the
- * section is open. All provider probing and credential handling happens in
- * the host half; this bundle only renders the overview document.
+ * (below the Workshop entry) plus the compact usage glance card below the
+ * sidebar's Settings row. The section polls the host overview only while it
+ * is open; the foot card runs its own relaxed loop because the sidebar foot
+ * is permanently mounted. All provider probing and credential handling
+ * happens in the host half; this bundle only renders the overview document.
  * @module @linxin666/dsh-usage/client
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import { type UsageSettings } from './UsageSectionCard.tsx';
 /** Required services. */
 export declare const inject: string[];
 export type { UsageSectionProps, UsageSectionFace } from './UsageSectionCard.tsx';
 export type { UsageUiState } from './usage-store.ts';
 export type { UsageSettings };
+/**
+ * One settings namespace a family card binds. The 0.1.7 client exports no spec
+ * type (the form controller takes it privately), so the binder's input shape is
+ * restated here.
+ */
+export interface UsageSettingsBindSpec<T> {
+    /** Settings namespace registered by the owning host plugin. */
+    namespace: string;
+    /** Narrow one wire section; undefined keeps the last accepted value. */
+    decode?: (section: unknown) => T | undefined;
+}
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /**
-         * Optional rc.6 compatibility binder provided by dsh-web-settings;
-         * absent when that group plugin is not installed, so callers fall back to
-         * the official settings scope.
+         * Optional family settings binder provided by dsh-web-settings; absent when
+         * that group plugin is not installed, so callers fall back to the native
+         * per-entry forms (`ctx.configForms`).
          */
         webUiSettings?: {
-            bind<S>(spec: SettingsScopeSpec<S>): SettingsScope<S>;
+            bind<S>(spec: UsageSettingsBindSpec<S>): ConfigForm<S>;
         };
     }
 }

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

@@ -46,10 +46,7 @@ export declare const zh: {
     'usage.config.title': string;
     'usage.config.enabled': string;
     'usage.config.pollIntervalSec': string;
-    'usage.config.bubbleMode': string;
-    'usage.config.bubbleMode.always': string;
-    'usage.config.bubbleMode.change': string;
-    'usage.config.bubbleMode.off': string;
+    'usage.config.saveFailed': string;
     'usage.bank.title': string;
     'usage.bank.hint': string;
     'usage.bank.noUsage': string;
@@ -60,6 +57,11 @@ export declare const zh: {
     'usage.bank.save': string;
     'usage.bank.share': string;
     'usage.bank.drawError': string;
+    'usage.foot.cost': string;
+    'usage.foot.noData': string;
+    'usage.foot.open': string;
+    'usage.foot.collapse': string;
+    'usage.foot.expand': string;
 };
 /** English mirror; every zh key present. */
 export declare const en: Record<UsageKey, string>;

package/lib/types/core/provider-routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Alias folding for the enumerated provider routes. Kept in core because the
+ * rule is pure — the host enumerates routes and this decides which of two
+ * routes serving one adapter family survives.
+ * @module @linxin666/dsh-usage/core/provider-routes
+ */
+/** The facts alias folding needs about one enumerated provider route. */
+export interface FoldableRoute {
+    /** Provider route key (`deepseek`, `deepseek-official`, custom routes, ...). */
+    id: string;
+    /** Whether the LLM runtime serves requests on this route; a catalog-only entry is dormant. */
+    live: boolean;
+}
+/**
+ * Drop dormant catalog aliases that shadow a live route of the same adapter
+ * family. The pi-ai catalog ships route keys the runtime serves nothing on
+ * until a profile declares them: for DeepSeek the catalog entry `deepseek`
+ * sits beside the llm-deepseek runtime route `deepseek-official`, and both
+ * resolve the same credential (the family's `apiKeyEnv` fallback), so probing
+ * and rendering both turns one account into two identical balance rows.
+ *
+ * A family keeps every live route it has — two configured profiles are two
+ * real accounts, not aliases. A route with no adapter, or one whose family
+ * has no live route at all, is returned untouched.
+ */
+export declare function foldAliasRoutes<T extends FoldableRoute>(routes: readonly T[]): T[];

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

@@ -118,12 +118,25 @@ export interface ProviderSnapshotView {
 export interface UsageOverviewView {
     updatedAt: number;
     providers: ProviderSnapshotView[];
-    /** The provider the pet bubble and the header highlight; `source` says how it was picked. */
+    /** The provider the collapsed sidebar strip and the header highlight; `source` says how it was picked. */
     current: {
         provider?: string;
         model?: string;
         /** `live` — last request seen this boot; `default` — the agent default model. */
         source: 'live' | 'default';
+        /**
+         * Resolved display name (snapshot first, route-derived otherwise), so the
+         * strip needs no name-resolution of its own. Optional so an older host
+         * document still renders.
+         */
+        displayName?: string;
+        /**
+         * Today's ledger totals for the provider's adapter family (the route
+         * itself when adapter-less), carrying tokens, calls, and the priced cost.
+         * Absent on a day without usage; optional for the same older-host
+         * tolerance as displayName.
+         */
+        today?: UsageTokenTotals;
     };
     usage: {
         today: {

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

@@ -0,0 +1,17 @@
+/**
+ * Usage trust fence (issue #1592): loopback (the desktop) always passes, and a
+ * live paired-device cookie is an additional allow path when remote-web-ui is
+ * loaded — the same family fence the skill center uses. Without that service
+ * the fence stays loopback-only, so an unpaired LAN browser keeps its 403.
+ * The decision logic lives in the generated pair-access.ts copy (shared by
+ * git-graph / pet / skill-explorer).
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Whether this request may read the usage overview or trigger a refresh.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param request - the incoming HTTP request.
+ * @returns true for loopback, or a live paired-device cookie.
+ */
+export declare function isUsageAllowed(ctx: Context, request: IncomingMessage): boolean;

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

@@ -1,7 +1,9 @@
 /**
  * Shared JSON body/response helpers for the host route families: one strict
  * bounded body reader, one lenient bounded body reader, one JSON object
- * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
+ * were copy-pasted across the
  * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
  * family's route module) with drifting contracts: body caps ranging 4 KiB to
  * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
@@ -34,6 +36,21 @@ export declare function readJsonBody(req: IncomingMessage, opts?: {
 }): Promise<unknown | null>;
 /** Narrow a value to a JSON object, or undefined when it is not one. */
 export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Request init that asks a remote origin for an uncompressed body.
+ *
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
+ * `content-encoding` header and automatic decompression, so a plain fetch
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+ * consumer can read. Every host fetch that parses a remote body must request
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
+ * `identity` because a caller value has no decoder behind it in this host.
+ * @param init - the caller's request init (signal, headers, method, ...).
+ * @returns a copy with `accept-encoding: identity` merged in.
+ */
+export declare function withIdentityEncoding(init?: RequestInit): RequestInit;
 /**
  * Write one JSON response. Default headers are the family defaults
  * (content-type and referrer-policy); caller headers are appended or

package/lib/types/host/pair-access.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pairing trust fence shared by plugins that expose host routes: loopback
+ * (the desktop) always passes; a live paired-device cookie is an additional
+ * allow path when remote-web-ui is loaded. The consuming plugin never
+ * depends on that plugin — without the service the fence stays
+ * loopback-only.
+ *
+ * Per-package wrappers (access.ts) call this with their own name so each
+ * plugin keeps a self-describing export; the security decision lives only
+ * here.
+ */
+import type { IncomingMessage } from 'node:http';
+/** Structural pairing lookup (no package dependency on remote-web-ui). */
+interface PairingAccess {
+    isPairedDevice(request: IncomingMessage): boolean;
+}
+/**
+ * Structural host-context shape: shared sources carry no @deepseek-ai
+ * dependency (the shared package must typecheck standalone), so the fence
+ * reads only the two members it needs; cordis Context satisfies this.
+ * ctx.get is optional on the test harness; production Context always has it.
+ */
+interface LookupCtx {
+    get?(name: string, strict?: boolean): unknown;
+    remoteWebUiPairing?: PairingAccess;
+}
+/**
+ * Whether this request may enter the plugin's host routes.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param request - the incoming HTTP request.
+ * @returns true for loopback, or a live paired-device cookie.
+ */
+export declare function isPairedOrLoopbackAllowed(ctx: LookupCtx, request: IncomingMessage): boolean;
+export {};

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

@@ -1,14 +1,23 @@
+import type { Context } from '@deepseek-ai/cordis';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { UsageService } from './usage-service.ts';
 export declare const USAGE_API_PREFIX = "/api/dsh-usage";
 /**
- * Loopback-fenced overview route: provider balances, plan quotas, and token
- * usage totals. Personal account data, so the loopback fence mirrors
- * dsh-perf's stats surface; the browser runs on the same machine.
+ * Overview route: provider balances, plan quotas, and token usage totals.
+ * Personal account data behind the family trust fence — loopback always
+ * passes, and a live paired-device cookie passes too when remote-web-ui is
+ * loaded (issue #1592: the sidebar usage panel reads this from a paired LAN
+ * browser); every unpaired LAN request keeps its 403.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param service - the usage service.
+ * @returns the route.
  */
-export declare function makeUsageOverviewRoute(service: UsageService): WebRoute;
+export declare function makeUsageOverviewRoute(ctx: Context, service: UsageService): WebRoute;
 /**
- * Loopback-fenced manual refresh: forces one probe cycle now and answers
- * with the fresh overview.
+ * Manual refresh: forces one probe cycle now and answers with the fresh
+ * overview. Same trust fence as the overview route.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param service - the usage service.
+ * @returns the route.
  */
-export declare function makeUsageRefreshRoute(service: UsageService): WebRoute;
+export declare function makeUsageRefreshRoute(ctx: Context, service: UsageService): WebRoute;

package/lib/types/host/usage-service.d.ts

@@ -1,15 +1,13 @@
 /**
  * The dsh-usage host service: folds live session usage into the persistent
  * ledger, probes each configured provider's balance/coding-plan endpoint on
- * a poll cycle, and announces the current provider's status to the pet
- * bubble. Secrets stay in the host process; the browser only ever sees the
- * overview document.
+ * a poll cycle, and serves the current provider's strip-ready view inside
+ * the overview document. Secrets stay in the host process; the browser only
+ * ever sees the overview document.
  * @module @linxin666/dsh-usage/host/usage-service
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ProviderSnapshotView, UsageOverviewView, UsageTokenTotals } from '../core/types.ts';
-/** Source tag the plugin stamps onto pet announcements. */
-export declare const USAGE_ANNOUNCE_SOURCE = "dsh-usage";
+import type { UsageOverviewView } from '../core/types.ts';
 /**
  * Persisted accrual state for the official DeepSeek family's real spend:
  * consecutive observations of the official CNY balance, decreases counted
@@ -25,54 +23,11 @@ export interface SpendWatch {
     /** The balance the previous observation ended on, when one exists. */
     lastBalanceCny?: number;
 }
-/** Poll-loop and announce options; re-applied live on settings change. */
+/** Poll-loop options; re-applied live on settings change. */
 export interface UsageServiceOptions {
     pollIntervalSec: number;
-    bubbleMode: 'always' | 'change' | 'off';
     retainDays: number;
 }
-/** Format a balance for display: symbol prefix when known, code suffix otherwise. */
-export declare function formatMoney(currency: string, totalBalance: string): string;
-/** Map a used percent to the announcement tone. */
-export declare function planTone(percent: number): 'ok' | 'warn' | 'low';
-/** Announcement context the service computes per poll: today's family spend and the DeepSeek period. */
-export interface AnnounceContext {
-    /** Today's ledger spend for the announced provider's family (CNY; 0 = unpriced). */
-    todayCost?: number;
-    /** Whether DeepSeek peak pricing is in effect right now. */
-    peak?: boolean;
-}
-/**
- * Build the raw pet announce payload for one provider snapshot, or
- * undefined when nothing worth announcing exists. Pure: every payload this
- * returns satisfies the pet's `parseAnnouncement` contract — plan
- * announcements require a numeric percent, so percent-less windows never
- * announce (the pet validator would silently drop them). A priced family
- * (DeepSeek) with spend today announces a cost bubble first; balance-only
- * families announce the balance; plan families announce their tightest
- * percent window.
- */
-export declare function buildAnnouncement(snapshot: Pick<ProviderSnapshotView, 'displayName' | 'balance' | 'plan'>, context?: AnnounceContext): Record<string, unknown> | undefined;
-/**
- * Compact token-count display for the usage fallback bubble: `9805`,
- * `8.7万`, `1.2亿`. The host-authored bubble copy is zh (like every other
- * line this service speaks), so the magnitudes follow the zh convention.
- */
-export declare function formatTokens(count: number): string;
-/**
- * The usage fallback for the session's provider: today's token consumption
- * and call count, the one fact the ledger owns for every provider. Providers
- * without a readable balance/plan endpoint (relay stations, local runtimes,
- * token-plan vendors — and probeable providers whose probes are failing)
- * would otherwise leave the pet bubble permanently silent even while their
- * sessions run. Undefined when the provider has no usage today: a bubble
- * about nothing is noise, not information. Pure; the payload satisfies the
- * pet's `parseAnnouncement` contract.
- */
-export declare function buildLedgerAnnouncement(input: {
-    displayName: string;
-    totals: UsageTokenTotals;
-}): Record<string, unknown> | undefined;
 export declare class UsageService {
     private readonly ctx;
     private options;
@@ -85,7 +40,7 @@ export declare class UsageService {
     private spendWatch;
     /** Per-live-session route attribution (WeakMap: disposed sessions age out). */
     private readonly sessionRoutes;
-    /** The most recent route seen this boot; the pet bubble follows it. */
+    /** The most recent route seen this boot; the sidebar strip and the header highlight follow it. */
     private current;
     private sessionListenerDisposer;
     private pollTimer;
@@ -98,7 +53,6 @@ export declare class UsageService {
     /** True once loadPersisted finished; nothing may overwrite the files before that. */
     private loaded;
     private disposed;
-    private lastSignature;
     /** Last prune guard: once per local day, and whenever retention shrinks. */
     private lastPrune;
     constructor(ctx: Context, options: UsageServiceOptions);
@@ -106,22 +60,33 @@ export declare class UsageService {
     start(): void;
     /**
      * Stop timers and flush pending ledger writes. The returned promise
-     * resolves after the final flush lands, so a successor instance (quick
-     * disable → enable) can serialize its first load behind it.
+     * resolves after the final flush lands, so a successor instance (the Host
+     * reloads the profile row on a config change) can serialize its first load
+     * behind it.
      */
     stop(): Promise<void>;
-    /** Re-apply options live (settings change); retention shrink prunes now. */
+    /** Re-apply options to this running instance; retention shrink prunes now. */
     applyOptions(options: UsageServiceOptions): void;
     /** Force one poll now (manual refresh route); joins an in-flight cycle. */
     refresh(): Promise<void>;
     /** Assemble the overview document the browser section renders. */
     overview(): UsageOverviewView;
+    /**
+     * The strip-ready current-provider view: the resolved display name plus
+     * today's ledger totals for the provider's adapter family (the route
+     * itself when adapter-less). `today` is absent on a day without usage —
+     * a strip about nothing is noise, not information.
+     */
+    private currentView;
     /** One local day aggregated per provider. */
     private daySummary;
-    /** Today's ledger spend for one provider's adapter family (0 when unpriced). */
-    private familyCostToday;
-    /** Today's ledger totals for one provider route (the exact id, not the family). */
-    private providerUsageToday;
+    /**
+     * Today's ledger totals for one provider's adapter family — the exact
+     * route when adapter-less, the merged family otherwise, so aliased routes
+     * of one account (the deepseek catalog id and its runtime alias) fold
+     * together.
+     */
+    private familyUsageToday;
     /**
      * Accrue the official DeepSeek family's real spend from observed CNY
      * balance decreases; a balance rise is a top-up and never counts. The
@@ -134,7 +99,7 @@ export declare class UsageService {
     /**
      * The display name for a route key: the LLM runtime's first, then the
      * adapter's, then the id itself — the snapshot may not exist for
-     * adapter-less routes, yet the bubble still needs a legible title.
+     * adapter-less routes, yet the sidebar strip still needs a legible title.
      */
     private routeDisplayName;
     private onSessionEvent;
@@ -162,11 +127,17 @@ export declare class UsageService {
     private persistSnapshots;
     private rearmPoll;
     /**
-     * One poll cycle: enumerate routes, resolve credentials, probe, announce.
+     * One poll cycle: enumerate routes, resolve credentials, probe.
      * A call while a cycle is already running joins that cycle instead of
      * returning immediately, so a manual refresh always waits for real probes.
      */
     pollNow(): Promise<void>;
+    /**
+     * Every route the service probes and renders: the runtime's live providers
+     * plus the configurable directory's catalog entries, then alias-folded so a
+     * dormant catalog entry cannot shadow the live route of the same adapter
+     * family (see foldAliasRoutes).
+     */
     private listProviderRoutes;
     private probeRoute;
     /**
@@ -182,19 +153,4 @@ export declare class UsageService {
     private piAiProfile;
     /** The DeepSeek official adapter's credential reference name. */
     private deepseekApiKeyEnv;
-    /**
-     * Announce the current provider's spend, balance, or plan usage to the pet.
-     * In `change` mode only meaningful value changes re-announce; `off` skips.
-     * The TTL rides the poll interval (bubble_mode `always` re-announces every
-     * cycle, so a TTL of two cycles + margin keeps the bubble continuous
-     * across polls; the pet contract caps the ceiling). A route id the
-     * catalogs spell differently than the snapshot keys falls back to its
-     * adapter family's snapshot. When the provider has no announceable probe
-     * fact (no adapter, failing probes, percent-less windows) the bubble falls
-     * back to the provider's today ledger usage, and with neither fact nor
-     * usage it stays silent. Fully guarded: a malformed snapshot or a failing
-     * pet service must never break the poll loop, and a disposed service never
-     * announces.
-     */
-    private announceCurrent;
 }

package/lib/types/index.d.ts

@@ -4,13 +4,17 @@ import z from 'schemastery';
 import { type UsageServiceOptions } from './host/usage-service.ts';
 export declare const name = "dsh-usage";
 export declare const inject: string[];
+/**
+ * Family settings namespace this row serves. Since 0.1.7 the settings surface
+ * addresses one form per profile entry id and the Host generates this row's
+ * page from the Config schema below, so the namespace is only the alias the
+ * family settings bridge (dsh-web-settings) resolves onto this row's entry id.
+ */
 export declare const USAGE_SETTINGS_NAMESPACE: SettingsNamespace;
 export interface Config {
     enabled?: boolean;
     /** Provider probe cycle in seconds; 30-3600. */
     pollIntervalSec?: number;
-    /** Pet bubble mode: always (refreshes each poll), change (only on value change), off. */
-    bubbleMode?: string;
     /** Ledger retention in local days. */
     retainDays?: number;
 }
@@ -19,4 +23,12 @@ export interface ResolvedConfig extends UsageServiceOptions {
     enabled: boolean;
 }
 export declare function resolveConfig(config?: Config): ResolvedConfig;
+/**
+ * Host body. The plugin's own Config schema above is the settings document the
+ * 0.1.7 Host serves for this row; the effective config arrives here as the
+ * `config` argument the Loader resolved and the Host reloads the row when the
+ * user saves a change, so nothing in this body observes or writes settings.
+ * @param ctx - host root context.
+ * @param config - the row's resolved configuration.
+ */
 export declare const apply: (ctx: Context, config?: Config) => void;