@linxin666/dsh-usage 0.3.23 → 0.3.24

package/lib/index.js

@@ -162,6 +162,10 @@ function toNum(value) {
 function str(value) {
 	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
 }
+/** Clamp a provider percentage into the renderable 0-100 band. */
+function clampPercent(value) {
+	return Math.max(0, Math.min(100, value));
+}
 /** Format a number to a fixed 2-decimal display string. */
 function money(value) {
 	return value.toFixed(2);
@@ -294,7 +298,28 @@ const KIMI_CODING = {
 		}
 	}
 };
-/** GLM Coding Plan quota; auth is the RAW key without a Bearer prefix. */
+/**
+* GLM Coding Plan quota windows, keyed by the provider's own `unit` code
+* rather than by row position so an added or reordered limit cannot shift a
+* window's meaning: 3 = the rolling 5-hour window, 6 = the weekly window,
+* 5 = the monthly one. Two row kinds carry quota — `TOKENS_LIMIT` (token
+* plans) and `CREDIT_LIMIT` (credit plans, whose exact ratio is
+* `currentValue` / `usage`) — while `TIME_LIMIT` is the MCP request cap and
+* is not a plan window at all. Auth is the RAW key without a Bearer prefix.
+*/
+const GLM_UNIT_KEYS = {
+	3: "5h",
+	5: "month",
+	6: "week"
+};
+/** Percent from a credit row's exact ratio, else the provider's own percentage. */
+function glmCreditPercent(row) {
+	const used = toNum(row.currentValue);
+	const limit = toNum(row.usage);
+	if (used !== void 0 && limit !== void 0 && limit > 0) return clampPercent(used / limit * 100);
+	const percentage = toNum(row.percentage);
+	return percentage === void 0 ? void 0 : clampPercent(percentage);
+}
 function glmPlan(host, ids) {
 	return {
 		ids,
@@ -319,11 +344,17 @@ function glmPlan(host, ids) {
 				for (const entry of limits) {
 					if (typeof entry !== "object" || entry === null) continue;
 					const row = entry;
-					const unit = toNum(row.unit);
-					const percent = toNum(row.percentage);
+					const kind = str(row.type);
+					if (kind === "TIME_LIMIT") continue;
+					const key = GLM_UNIT_KEYS[toNum(row.unit) ?? NaN];
+					if (key === void 0) continue;
+					if (kind !== "TOKENS_LIMIT" && kind !== "CREDIT_LIMIT") continue;
 					windows.push({
-						key: unit === 3 ? "5h" : unit === 6 ? "week" : unit !== void 0 ? `unit-${unit}` : "window",
-						percent: percent === void 0 ? void 0 : Math.max(0, Math.min(100, percent)),
+						key,
+						percent: kind === "CREDIT_LIMIT" ? glmCreditPercent(row) : (() => {
+							const percentage = toNum(row.percentage);
+							return percentage === void 0 ? void 0 : clampPercent(percentage);
+						})(),
 						resetsAt: toIso(row.nextResetTime)
 					});
 				}
@@ -537,7 +568,7 @@ const PROVIDER_ADAPTERS = [
 	moonshotBalance("api.moonshot.ai", "USD", ["moonshotai"]),
 	KIMI_CODING,
 	glmPlan("open.bigmodel.cn", ["zai-coding-cn"]),
-	glmPlan("api.z.ai", ["zai-coding"]),
+	glmPlan("api.z.ai", ["zai", "zai-coding"]),
 	OPENCODE_GO,
 	minimaxPlan("api.minimaxi.com", ["minimax-cn"]),
 	minimaxPlan("api.minimax.io", ["minimax"]),
@@ -574,6 +605,34 @@ function providerErrorMessage(status, body) {
 	return `HTTP ${status}${message === void 0 ? "" : `: ${message.slice(0, 120)}`}`;
 }
 //#endregion
+//#region src/core/provider-routes.ts
+/**
+* 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
+*/
+/**
+* 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.
+*/
+function foldAliasRoutes(routes) {
+	return routes.filter((route) => {
+		if (route.live) return true;
+		const family = adapterFor(route.id);
+		if (family === void 0) return true;
+		return !routes.some((other) => other.live && adapterFor(other.id) === family);
+	});
+}
+//#endregion
 //#region src/core/pricing.ts
 /** The published peak windows: weekday 09:00-12:00 and 14:00-18:00. */
 const PEAK_WINDOWS = [{
@@ -856,112 +915,15 @@ function deserializeLedger(value) {
 /**
 * 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
 */
-/** Source tag the plugin stamps onto pet announcements. */
-const USAGE_ANNOUNCE_SOURCE = "dsh-usage";
 /** Probe timeout per HTTP call. */
 const PROBE_TIMEOUT_MS = 1e4;
 /** Ledger flush debounce. */
 const FLUSH_DEBOUNCE_MS = 3e3;
-/** Currency symbols the bubble and section render inline; other codes render as `12.00 EUR`. */
-const CURRENCY_SYMBOLS = {
-	CNY: "¥",
-	USD: "$",
-	EUR: "€",
-	GBP: "£"
-};
-/** Format a balance for display: symbol prefix when known, code suffix otherwise. */
-function formatMoney(currency, totalBalance) {
-	const symbol = CURRENCY_SYMBOLS[currency.toUpperCase()];
-	if (symbol !== void 0) return symbol + totalBalance;
-	return `${totalBalance} ${currency.toUpperCase()}`;
-}
-/** Map a used percent to the announcement tone. */
-function planTone(percent) {
-	if (percent >= 90) return "low";
-	if (percent >= 70) return "warn";
-	return "ok";
-}
-/**
-* 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.
-*/
-function buildAnnouncement(snapshot, context) {
-	const todayCost = context?.todayCost ?? 0;
-	if (todayCost > 0) {
-		const peak = context?.peak ?? false;
-		const noteParts = [peak ? "高峰时段 计价×2" : "空闲时段 计价减半", ...snapshot.balance !== void 0 ? [`余额 ${formatMoney(snapshot.balance.currency, snapshot.balance.totalBalance)}`] : []];
-		return {
-			kind: "cost",
-			title: snapshot.displayName,
-			amount: `今日 ${formatMoney("CNY", todayCost.toFixed(2))}`,
-			...noteParts.length > 0 ? { note: noteParts.join(" · ") } : {},
-			tone: peak ? "warn" : "ok"
-		};
-	}
-	if (snapshot.balance !== void 0) return {
-		kind: "balance",
-		title: snapshot.displayName,
-		amount: formatMoney(snapshot.balance.currency, snapshot.balance.totalBalance),
-		tone: "ok"
-	};
-	if (snapshot.plan === void 0) return void 0;
-	const window = snapshot.plan.windows.filter((entry) => typeof entry.percent === "number").sort((a, b) => (b.percent ?? 0) - (a.percent ?? 0))[0];
-	if (window === void 0 || window.percent === void 0) return void 0;
-	return {
-		kind: "plan",
-		title: snapshot.displayName,
-		percent: window.percent,
-		...window.resetsAt !== void 0 ? { resetAt: window.resetsAt } : {},
-		...snapshot.plan.planName !== void 0 ? { note: snapshot.plan.planName } : {},
-		tone: planTone(window.percent)
-	};
-}
-/**
-* 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.
-*/
-function formatTokens(count) {
-	const compact = (value) => {
-		const rounded = Math.round(value * 10) / 10;
-		return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
-	};
-	if (count >= 1e8) return compact(count / 1e8) + "亿";
-	if (count >= 1e4) return compact(count / 1e4) + "万";
-	return String(count);
-}
-/**
-* 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.
-*/
-function buildLedgerAnnouncement(input) {
-	const total = totalTokens(input.totals);
-	if (input.totals.calls <= 0 || total <= 0) return void 0;
-	return {
-		kind: "cost",
-		title: input.displayName,
-		amount: `今日 ${formatTokens(total)} tokens`,
-		note: `${input.totals.calls} 次调用`,
-		tone: "ok"
-	};
-}
 /** Best-effort typed service read: absent services resolve to undefined at runtime. */
 function service(ctx, name) {
 	try {
@@ -1018,7 +980,7 @@ var UsageService = class {
 	spendWatch;
 	/** Per-live-session route attribution (WeakMap: disposed sessions age out). */
 	sessionRoutes = /* @__PURE__ */ new WeakMap();
-	/** 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. */
 	current = { source: "default" };
 	sessionListenerDisposer;
 	pollTimer;
@@ -1031,7 +993,6 @@ var UsageService = class {
 	/** True once loadPersisted finished; nothing may overwrite the files before that. */
 	loaded = false;
 	disposed = false;
-	lastSignature;
 	/** Last prune guard: once per local day, and whenever retention shrinks. */
 	lastPrune;
 	constructor(ctx, options) {
@@ -1098,7 +1059,7 @@ var UsageService = class {
 		return {
 			updatedAt: Date.now(),
 			providers,
-			current: { ...this.current },
+			current: this.currentView(),
 			usage: {
 				today: this.daySummary(todayKey),
 				days: days.map((date) => {
@@ -1126,6 +1087,33 @@ var UsageService = class {
 			}
 		};
 	}
+	/**
+	* 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.
+	*/
+	currentView() {
+		const provider = this.current.provider;
+		if (provider === void 0) return { ...this.current };
+		let snapshot = this.snapshots.get(provider);
+		if (snapshot === void 0) {
+			const family = adapterFor(provider);
+			if (family !== void 0) {
+				for (const [id, candidate] of this.snapshots) if (adapterFor(id) === family) {
+					snapshot = candidate;
+					break;
+				}
+			}
+		}
+		const displayName = snapshot?.displayName ?? this.routeDisplayName(provider);
+		const today = this.familyUsageToday(provider);
+		return {
+			...this.current,
+			displayName,
+			...today.calls > 0 && totalTokens(today) > 0 ? { today } : {}
+		};
+	}
 	/** One local day aggregated per provider. */
 	daySummary(dateKey) {
 		const { totals, providers } = summarizeDays([this.ledger.days[dateKey] ?? {}]);
@@ -1135,17 +1123,17 @@ var UsageService = class {
 			providers
 		};
 	}
-	/** Today's ledger spend for one provider's adapter family (0 when unpriced). */
-	familyCostToday(provider) {
+	/**
+	* 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.
+	*/
+	familyUsageToday(provider) {
 		const family = adapterFor(provider);
-		if (family === void 0) return 0;
-		let cost = 0;
-		for (const row of this.daySummary(localDateKey(Date.now())).providers) if (adapterFor(row.provider) === family) cost += row.totals.cost;
-		return cost;
-	}
-	/** Today's ledger totals for one provider route (the exact id, not the family). */
-	providerUsageToday(provider) {
-		return this.daySummary(localDateKey(Date.now())).providers.find((entry) => entry.provider === provider)?.totals ?? emptyTotals();
+		let merged = emptyTotals();
+		for (const row of this.daySummary(localDateKey(Date.now())).providers) if (family === void 0 ? row.provider === provider : adapterFor(row.provider) === family) merged = addTotals(merged, row.totals);
+		return merged;
 	}
 	/**
 	* Accrue the official DeepSeek family's real spend from observed CNY
@@ -1177,7 +1165,7 @@ var UsageService = class {
 	/**
 	* 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.
 	*/
 	routeDisplayName(provider) {
 		return this.listProviderRoutes().find((entry) => entry.id === provider)?.displayName || adapterFor(provider)?.displayName || provider;
@@ -1326,7 +1314,7 @@ var UsageService = class {
 		}, delayMs);
 	}
 	/**
-	* 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.
 	*/
@@ -1350,7 +1338,6 @@ var UsageService = class {
 				if (this.disposed) return;
 				this.accrueDeepSeekSpend();
 				await this.persistSnapshots();
-				this.announceCurrent();
 			} finally {
 				this.pollInFlight = false;
 				this.pollPromise = void 0;
@@ -1359,17 +1346,28 @@ var UsageService = class {
 		this.pollPromise = cycle;
 		return cycle;
 	}
+	/**
+	* 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).
+	*/
 	listProviderRoutes() {
 		const routes = /* @__PURE__ */ new Map();
 		const runtime = service(this.ctx, "llm");
 		if (runtime !== void 0) try {
-			for (const provider of runtime.listProviders()) if (provider.id !== "") routes.set(provider.id, provider.name);
-			for (const provider of runtime.listConfigurableProviders()) if (!routes.has(provider.provider)) routes.set(provider.provider, provider.displayName);
+			for (const provider of runtime.listProviders()) if (provider.id !== "") routes.set(provider.id, {
+				id: provider.id,
+				displayName: provider.name,
+				live: true
+			});
+			for (const provider of runtime.listConfigurableProviders()) if (!routes.has(provider.provider)) routes.set(provider.provider, {
+				id: provider.provider,
+				displayName: provider.displayName,
+				live: false
+			});
 		} catch {}
-		return [...routes].map(([id, displayName]) => ({
-			id,
-			displayName
-		}));
+		return foldAliasRoutes([...routes.values()]);
 	}
 	async probeRoute(route, adapter) {
 		const credential = await this.resolveCredential(route.id);
@@ -1486,66 +1484,6 @@ var UsageService = class {
 	deepseekApiKeyEnv() {
 		return readNamespace(this.ctx, "llm-deepseek")?.apiKeyEnv ?? "DEEPSEEK_API_KEY";
 	}
-	/**
-	* 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.
-	*/
-	announceCurrent() {
-		if (this.disposed || this.options.bubbleMode === "off") return;
-		try {
-			let provider = this.current.provider;
-			if (provider === void 0) {
-				const fallback = readNamespace(this.ctx, "agent-default-model");
-				if (fallback?.provider !== void 0) {
-					provider = fallback.provider;
-					this.current = {
-						provider: fallback.provider,
-						model: fallback.model,
-						source: "default"
-					};
-				} else return;
-			}
-			let snapshot = this.snapshots.get(provider);
-			if (snapshot === void 0) {
-				const family = adapterFor(provider);
-				if (family !== void 0) {
-					for (const [id, candidate] of this.snapshots) if (adapterFor(id) === family) {
-						snapshot = candidate;
-						break;
-					}
-				}
-			}
-			const displayName = snapshot?.displayName ?? this.routeDisplayName(provider);
-			let announcement = snapshot !== void 0 ? buildAnnouncement(snapshot, {
-				todayCost: this.familyCostToday(provider),
-				peak: deepseekPeriodAt(Date.now()).peak
-			}) : void 0;
-			if (announcement === void 0) announcement = buildLedgerAnnouncement({
-				displayName,
-				totals: this.providerUsageToday(provider)
-			});
-			if (announcement === void 0) return;
-			const signature = JSON.stringify(announcement);
-			if (this.options.bubbleMode === "change" && signature === this.lastSignature) return;
-			this.lastSignature = signature;
-			const ttlMs = Math.min(72e5, this.options.pollIntervalSec * 2e3 + 3e4);
-			service(this.ctx, "pet")?.announce({
-				source: USAGE_ANNOUNCE_SOURCE,
-				ttlMs,
-				...announcement
-			});
-		} catch {}
-	}
 };
 //#endregion
 //#region src/host/loopback.ts
@@ -1593,6 +1531,33 @@ function isLoopbackRequest(request) {
 	}
 }
 //#endregion
+//#region src/host/pair-access.ts
+/**
+* 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.
+*/
+function isPairedOrLoopbackAllowed(ctx, request) {
+	if (isLoopbackRequest(request)) return true;
+	const fromGet = typeof ctx.get === "function" ? ctx.get("remoteWebUiPairing", false) : void 0;
+	return (isPairingAccess(fromGet) ? fromGet : ctx.remoteWebUiPairing)?.isPairedDevice(request) === true;
+}
+function isPairingAccess(value) {
+	return value !== void 0 && value !== null && typeof value.isPairedDevice === "function";
+}
+//#endregion
+//#region src/host/access.ts
+/**
+* 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.
+*/
+function isUsageAllowed(ctx, request) {
+	return isPairedOrLoopbackAllowed(ctx, request);
+}
+//#endregion
 //#region src/host/http.ts
 /** Family-default JSON response headers; callers may append or override. */
 const JSON_HEADERS = {
@@ -1615,16 +1580,21 @@ function writeJson(res, status, body, headers = {}) {
 //#endregion
 //#region src/host/routes.ts
 /**
-* 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.
 */
-function makeUsageOverviewRoute(service) {
+function makeUsageOverviewRoute(ctx, service) {
 	return {
 		kind: "exact",
 		path: "/api/dsh-usage/overview",
 		handler: async (req, res) => {
-			if (!isLoopbackRequest(req)) {
+			if (!isUsageAllowed(ctx, req)) {
 				writeJson(res, 403, {
 					ok: false,
 					error: "forbidden: loopback-only"
@@ -1636,15 +1606,18 @@ function makeUsageOverviewRoute(service) {
 	};
 }
 /**
-* 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.
 */
-function makeUsageRefreshRoute(service) {
+function makeUsageRefreshRoute(ctx, service) {
 	return {
 		kind: "exact",
 		path: "/api/dsh-usage/refresh",
 		handler: async (req, res) => {
-			if (!isLoopbackRequest(req)) {
+			if (!isUsageAllowed(ctx, req)) {
 				writeJson(res, 403, {
 					ok: false,
 					error: "forbidden: loopback-only"
@@ -1679,15 +1652,12 @@ const USAGE_SETTINGS_NAMESPACE = "dsh-usage";
 const Config = z.object({
 	enabled: z.boolean().default(true),
 	pollIntervalSec: z.number().min(30).max(3600).default(60),
-	bubbleMode: z.string().default("always"),
 	retainDays: z.number().min(7).max(730).default(180)
 });
 function resolveConfig(config) {
-	const bubbleMode = config?.bubbleMode === "change" || config?.bubbleMode === "off" ? config.bubbleMode : "always";
 	return {
 		enabled: config?.enabled ?? true,
 		pollIntervalSec: typeof config?.pollIntervalSec === "number" ? config.pollIntervalSec : 60,
-		bubbleMode,
 		retainDays: typeof config?.retainDays === "number" ? config.retainDays : 180
 	};
 }
@@ -1711,7 +1681,7 @@ const apply = mountOnce("@linxin666/dsh-usage", (ctx, config) => {
 			const begin = () => {
 				if (service !== next) return;
 				next.start();
-				const disposers = [makeUsageOverviewRoute(next), makeUsageRefreshRoute(next)].map((route) => ctx.webServer.register(route));
+				const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)].map((route) => ctx.webServer.register(route));
 				disposeRoutes = () => {
 					for (const dispose of disposers) try {
 						dispose();

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

@@ -14,7 +14,6 @@ import type { UsageStoreInstance } from './usage-store.ts';
 export interface UsageSettings {
     enabled?: boolean;
     pollIntervalSec?: number;
-    bubbleMode?: string;
 }
 /** The registration-side face the section's slot entry injects. */
 export interface UsageSectionFace {

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

@@ -0,0 +1,34 @@
+/**
+ * Sidebar usage panel (issue #1592): the usage body seated directly under the
+ * sidebar entry row. The row carries the panel's controls (refresh, collapse
+ * chevron), so this component renders only the content: expanded, plan
+ * providers show their quota windows and balance-only providers their
+ * remaining amount; collapsed, a one-line strip shows the current session
+ * provider's today usage (tokens, calls, and cost when priced) from the same
+ * /api/dsh-usage/overview document the settings section renders. The open
+ * state lives in the mount (persisted to localStorage) and arrives through
+ * the open face; polling runs at 10s expanded, 30s collapsed, and pauses
+ * while the page is hidden.
+ * @module @linxin666/dsh-usage/client/UsageSidebarPanel
+ */
+import { type ReactNode } from 'react';
+import type { UsageStoreInstance } from './usage-store.ts';
+/** Expanded-state face the owning mount supplies (subscribe + current value). */
+export interface OpenStateSource {
+    subscribe(listener: () => void): () => void;
+    isOpen(): boolean;
+}
+/** Props of the sidebar panel (the apply body supplies the store and poller). */
+export interface UsageSidebarPanelProps {
+    store: UsageStoreInstance;
+    /** Fetch one overview now. */
+    poll: () => void;
+    /** Expanded state owned by the mount; false renders nothing and pauses polling. */
+    open: OpenStateSource;
+}
+/**
+ * Render the sidebar usage panel body.
+ * @param props - store, the poll callback, and the mount's open-state face.
+ * @returns the panel content, or null while collapsed.
+ */
+export declare function UsageSidebarPanel(props: UsageSidebarPanelProps): ReactNode;

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/locales.d.ts

@@ -46,10 +46,6 @@ 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.bank.title': string;
     'usage.bank.hint': string;
     'usage.bank.noUsage': string;
@@ -60,6 +56,15 @@ export declare const zh: {
     'usage.bank.save': string;
     'usage.bank.share': string;
     'usage.bank.drawError': string;
+    'usage.sidebar.entry.label': string;
+    'usage.sidebar.entry.tooltip': string;
+    'usage.sidebar.toggle.collapse': string;
+    'usage.sidebar.toggle.expand': string;
+    'usage.sidebar.empty': string;
+    'usage.sidebar.error': string;
+    'usage.sidebar.loading': string;
+    'usage.sidebar.balanceLeft': string;
+    'usage.sidebar.todayUsage': string;
 };
 /** English mirror; every zh key present. */
 export declare const en: Record<UsageKey, string>;