dsh-subscriptions 0.1.0 → 0.1.2

package/lib/client/SubscriptionsSection.js

@@ -18,6 +18,8 @@ import { en } from './locales.js';
 import { ProviderAccountManager } from './ProviderAccountManager.js';
 import { ExternalUsageCards } from './ExternalUsageCards.js';
 import { CursorCard } from './CursorCard.js';
+import { UsageMeter } from './UsageMeter.js';
+import { displayUsedPercent } from './usage-pace.js';
 import { UsageBadgeDisplaySetting } from './UsageBadgeDisplaySetting.js';
 import { USAGE_BADGE_REFRESH_EVENT } from './usage-badge-preferences.js';
 import { subscriptionCardStyles as cardStyles } from './subscription-card-styles.js';
@@ -102,8 +104,6 @@ const styles = {
         font: 'inherit', fontSize: 14, lineHeight: '20px', cursor: 'pointer',
         color: 'var(--dsw-alias-state-warn-label)',
     },
-    usageTrack: cardStyles.usageTrack,
-    usageFill: cardStyles.usageFill,
     deviceCode: {
         marginTop: 4, display: 'flex', flexDirection: 'column', gap: 6,
         border: '1px solid var(--dsw-alias-border-l2)', borderRadius: 8,
@@ -183,14 +183,8 @@ function usageWindowLabel(t, window) {
         : window.kind === 'weekly' ? t('usageWeekly') : t('usageWindow');
     return window.scope !== undefined && window.scope !== '' ? `${base} · ${window.scope}` : base;
 }
-/** Bar fill color: success normally, warn from 80%, error from 95%. Shared with the composer badge. */
-export function usageBarColor(usedPercent) {
-    if (usedPercent >= 95)
-        return 'var(--dsw-alias-state-error-primary)';
-    if (usedPercent >= 80)
-        return 'var(--dsw-alias-state-warn-label)';
-    return 'var(--dsw-alias-state-success-primary)';
-}
+/** Meter fill color lives with the pace logic: fresh 90%+ is red, pace presets add a yellow lead threshold. */
+export { usageBarColor } from './usage-pace.js';
 /**
  * Derive one provider's default-effort section from its catalog and filter.
  * Pure so the collapsed-header counts and the filter stay testable without a
@@ -268,6 +262,7 @@ export function SubscriptionsSection(props) {
     const [copiedCode, setCopiedCode] = useState(undefined);
     /** Usage snapshots keyed `${provider}:${accountKey}` — every account tracks its own windows. */
     const [usages, setUsages] = useState({});
+    const [observedAt, setObservedAt] = useState({});
     const [usageErrors, setUsageErrors] = useState({});
     const [usageLoading, setUsageLoading] = useState({});
     const mountedRef = useRef(true);
@@ -377,6 +372,7 @@ export function SubscriptionsSection(props) {
             if (!mountedRef.current)
                 return;
             setUsages(prev => ({ ...prev, [key]: usage }));
+            setObservedAt(prev => ({ ...prev, [key]: usage.observedAt ?? Date.now() }));
             window.dispatchEvent(new Event(USAGE_BADGE_REFRESH_EVENT));
             setUsageErrors((prev) => {
                 const next = { ...prev };
@@ -535,9 +531,9 @@ export function SubscriptionsSection(props) {
                                                     if (!account.isDefault)
                                                         void setDefault(id, account.key);
                                                 }, children: account.isDefault ? '★' : '☆' }), _jsx("span", { style: styles.accountName, children: display }), account.plan !== undefined && (_jsx("span", { style: styles.usagePlan, children: account.plan })), account.expiresAt !== undefined && (_jsx("span", { style: styles.statusLine, children: t('accountExpires', { date: new Date(account.expiresAt).toLocaleString() }) })), _jsx("button", { type: "button", style: { ...styles.button, marginLeft: 'auto', flexShrink: 0 }, onClick: () => { void logout(id, account.key, display, name); }, children: t('logout') })] }), showUsage && (_jsxs("div", { style: styles.usage, children: [_jsxs("div", { style: styles.usageHeader, children: [_jsx("span", { style: styles.usageTitle, children: t('usageTitle') }), usage?.plan !== undefined && (_jsx("span", { style: styles.usagePlan, children: t('usagePlan', { plan: usage.plan }) })), _jsx("button", { type: "button", style: { ...styles.usageRefresh, ...usageLoading[usageKey] === true ? { opacity: 0.5, cursor: 'default' } : {} }, disabled: usageLoading[usageKey] === true, onClick: () => { void loadUsage(id, account.key, true); }, children: t('usageRefresh') })] }), usage === undefined && usageError === undefined && (_jsx("p", { style: styles.statusLine, children: t('usageLoading') })), usageError !== undefined && (_jsx("p", { style: styles.errorLine, children: t('usageError', { message: usageError }) })), usage?.windows !== undefined && usage.windows.length === 0 && (_jsx("p", { style: styles.statusLine, children: t('usageEmpty') })), (usage?.windows ?? []).map((window, index) => {
-                                                const percent = Math.min(100, Math.max(0, window.usedPercent));
-                                                return (_jsxs("div", { style: styles.usageRow, children: [_jsxs("div", { style: styles.usageMeta, children: [_jsx("span", { children: usageWindowLabel(t, window) }), _jsxs("span", { children: [`${String(Math.round(percent))}%`, window.resetsAt !== undefined
-                                                                            && ` · ${t('usageResets', { date: new Date(window.resetsAt).toLocaleString() })}`] })] }), _jsx("div", { style: styles.usageTrack, children: _jsx("div", { style: { ...styles.usageFill, width: `${String(percent)}%`, background: usageBarColor(percent) } }) })] }, index));
+                                                const percent = displayUsedPercent(window.usedPercent);
+                                                return (_jsxs("div", { style: styles.usageRow, children: [_jsxs("div", { style: styles.usageMeta, children: [_jsx("span", { children: usageWindowLabel(t, window) }), _jsxs("span", { children: [percent === undefined ? t('usageMeterInvalid') : `${percent}%`, window.resetsAt !== undefined
+                                                                            && ` · ${t('usageResets', { date: new Date(window.resetsAt).toLocaleString() })}`] })] }), _jsx(UsageMeter, { window: window, t: t, observedAt: observedAt[usageKey], stale: usageError !== undefined || usage.stale === true })] }, index));
                                             })] }))] }, account.key));
                         }), _jsxs("div", { style: styles.actions, children: [!busy && accounts.length === 0 && (_jsx("button", { type: "button", style: styles.button, onClick: () => { void login(id); }, children: t('login') })), !busy && accounts.length > 0 && id === 'claude' && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", style: styles.button, onClick: () => { void login(id, 'oauth'); }, children: t('addAccountOAuth') }), _jsx("button", { type: "button", style: styles.button, onClick: () => { void login(id, 'keychain'); }, children: t('addAccountKeychain') })] })), !busy && accounts.length > 0 && id !== 'claude' && (_jsx("button", { type: "button", style: styles.button, onClick: () => { void login(id); }, children: t('addAccount') })), _jsx("button", { type: "button", style: styles.button, "aria-haspopup": "dialog", onClick: () => setManagedProvider({ id, name }), children: t('accountsManage') }), busy && (_jsx("button", { type: "button", style: styles.button, onClick: () => { void cancel(id); }, children: t('cancel') }))] }), !busy && accounts.length > 0 && (_jsx("p", { style: styles.statusLine, children: t('addAccountHint') })), busy && deviceCode !== undefined && (_jsxs("div", { style: styles.deviceCode, children: [_jsx("span", { style: styles.statusLine, children: t('deviceCodePrompt') }), _jsx("span", { style: styles.deviceCodeText, children: deviceCode.userCode }), _jsxs("div", { style: styles.actions, children: [_jsx("button", { type: "button", style: styles.button, onClick: () => { copyDeviceCode(id, deviceCode.userCode); }, children: copiedCode === id ? t('deviceCodeCopied') : t('deviceCodeCopy') }), _jsx("button", { type: "button", style: styles.button, onClick: () => { window.open(deviceCode.verificationUrl, '_blank', 'noopener'); }, children: t('deviceCodeOpenPage') })] })] })), busy && deviceCode === undefined && (_jsxs("details", { style: styles.manual, children: [_jsx("summary", { children: t('manualSummary') }), _jsxs("div", { style: styles.manualRow, children: [_jsx("input", { style: styles.manualInput, value: manualDrafts[id], placeholder: t('manualPlaceholder'), onChange: event => setManualDrafts(prev => ({ ...prev, [id]: event.target.value })) }), _jsx("button", { type: "button", style: styles.button, onClick: () => { void submitManual(id); }, children: t('submit') })] })] }))] }, id));
             }), _jsx(CursorCard, { rpc: rpc, t: t }), _jsx(ExternalUsageCards, { rpc: rpc, t: t }), managedProvider && _jsx(ProviderAccountManager, { provider: managedProvider.id, name: managedProvider.name, rpc: rpc, t: t, onClose: () => setManagedProvider(undefined) })] }));

package/lib/client/UsageBadgeDisplaySetting.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { setUsageBadgeMode, useUsageBadgeMode } from './usage-badge-preferences.js';
+import { isUsageColorPreset, setUsageColorPreset, useUsageColorPreset } from './usage-color-preferences.js';
 /** Browser-local display preference; never changes provider or account settings. */
 export function UsageBadgeDisplaySetting({ t }) {
     const mode = useUsageBadgeMode();
+    const preset = useUsageColorPreset();
     const [failed, setFailed] = useState(false);
     return (_jsxs("div", { style: styles.card, children: [_jsxs("label", { style: styles.field, children: [_jsx("span", { children: t('usageBadgeDisplay') }), _jsxs("select", { style: styles.select, "aria-label": t('usageBadgeDisplay'), value: mode, onChange: event => {
                             const value = event.currentTarget.value;
@@ -18,7 +20,22 @@ export function UsageBadgeDisplaySetting({ t }) {
                                     throw error;
                                 setFailed(true);
                             }
-                        }, children: [_jsx("option", { value: "recent", children: t('usageBadgeDisplayRecent') }), _jsx("option", { value: "hidden", children: t('usageBadgeDisplayHidden') })] })] }), _jsx("p", { style: styles.hint, children: t('usageBadgeDisplayHint') }), failed && _jsx("p", { role: "alert", style: { ...styles.hint, color: 'var(--dsw-alias-state-error-primary)' }, children: t('usageBadgeDisplaySaveFailed') })] }));
+                        }, children: [_jsx("option", { value: "recent", children: t('usageBadgeDisplayRecent') }), _jsx("option", { value: "hidden", children: t('usageBadgeDisplayHidden') })] })] }), _jsx("p", { style: styles.hint, children: t('usageBadgeDisplayHint') }), _jsxs("label", { style: styles.field, children: [_jsx("span", { children: t('usageColorLabel') }), _jsxs("select", { style: styles.select, "aria-label": t('usageColorLabel'), value: preset, onChange: event => {
+                            const value = event.currentTarget.value;
+                            if (!isUsageColorPreset(value))
+                                return;
+                            try {
+                                setUsageColorPreset(value);
+                                setFailed(false);
+                            }
+                            catch (error) {
+                                if (!(error instanceof DOMException) || !['SecurityError', 'QuotaExceededError'].includes(error.name))
+                                    throw error;
+                                setFailed(true);
+                            }
+                        }, children: [_jsx("option", { value: "standard", children: t('usageColorStandard') }), _jsx("option", { value: "relaxed", children: t('usageColorRelaxed') }), _jsx("option", { value: "remaining", children: t('usageColorRemaining') })] })] }), _jsx("p", { style: styles.hint, children: t(preset === 'remaining' ? 'usageColorRemainingHint' : 'usageColorPaceHint', {
+                    allowance: preset === 'relaxed' ? 15 : 10,
+                }) }), failed && _jsx("p", { role: "alert", style: { ...styles.hint, color: 'var(--dsw-alias-state-error-primary)' }, children: t('usageBadgeDisplaySaveFailed') })] }));
 }
 const styles = {
     card: {

package/lib/client/UsageMeter.d.ts

@@ -0,0 +1,8 @@
+import type { CSSProperties } from 'react';
+import type { UsageWindow, SubscriptionsSectionInjected } from './SubscriptionsSection.js';
+import type { UsageObservation } from './usage-pace.js';
+export declare function UsageMeter({ window: quota, t, style, observedAt, stale }: {
+    window: UsageWindow;
+    t: SubscriptionsSectionInjected['t'];
+    style?: CSSProperties;
+} & UsageObservation): import("react").JSX.Element;

package/lib/client/UsageMeter.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { elapsedPercent, isUsageFresh, resetCountdownParts, usageBarColor, usageColorState, validUsage } from './usage-pace.js';
+import { useUsageColorPreset } from './usage-color-preferences.js';
+/** Singular/plural locale keys per countdown unit (zh maps both to one string). */
+const UNIT_KEYS = {
+    day: ['usageUnitDay', 'usageUnitDays'],
+    hour: ['usageUnitHour', 'usageUnitHours'],
+    minute: ['usageUnitMinute', 'usageUnitMinutes'],
+};
+export function UsageMeter({ window: quota, t, style, observedAt, stale }) {
+    const preset = useUsageColorPreset();
+    const [now, setNow] = useState(Date.now);
+    useEffect(() => {
+        const timer = setInterval(() => setNow(Date.now()), 60_000);
+        return () => clearInterval(timer);
+    }, []);
+    // Use render time for new readings, without trusting a future observation timestamp.
+    const current = Math.max(now, Date.now());
+    const valid = validUsage(quota.usedPercent);
+    const used = valid ? quota.usedPercent : 0;
+    const fresh = isUsageFresh(quota, { observedAt, stale }, current);
+    const elapsed = fresh ? elapsedPercent(quota, current) : undefined;
+    const state = usageColorState(quota.usedPercent, elapsed, preset, fresh);
+    const lead = elapsed === undefined ? 0 : Math.round(used - elapsed);
+    const label = [
+        valid ? t('usageMeterUsed', { used: Math.round(used), remaining: Math.round(100 - used) }) : t('usageMeterInvalid'),
+        // An invalid reading already states unavailability; the stale line would repeat it.
+        !valid ? '' : !fresh ? t('usageMeterStale') : state === 'red' ? t('usageMeterNearLimit')
+            : elapsed === undefined && preset !== 'remaining' ? t('usageMeterUnknownTime')
+                : state === 'yellow' ? t('usageMeterAhead') : t('usageMeterNoWarning'),
+        elapsed === undefined ? '' : t('usageMeterPace', { elapsed: Math.round(elapsed) }),
+        elapsed === undefined ? '' : lead > 0 ? t('usageMeterPaceAhead', { points: lead })
+            : lead < 0 ? t('usageMeterPaceBehind', { points: -lead }) : t('usageMeterPaceEven'),
+        quota.resetsAt !== undefined && quota.resetsAt > current ? t('usageMeterReset', {
+            duration: resetCountdownParts(quota.resetsAt - current)
+                .map(part => t(UNIT_KEYS[part.unit][part.count === 1 ? 0 : 1], { count: part.count }))
+                .join(' '),
+        }) : '',
+    ].filter(Boolean).join(' · ');
+    return _jsxs("div", { role: "img", "aria-label": label, title: label, "data-usage-color": state, style: {
+            height: 6, borderRadius: 3, overflow: 'hidden',
+            background: 'var(--dsw-alias-bg-layer-1)', border: '1px solid var(--dsw-alias-border-l2)',
+            ...style, position: 'relative',
+        }, children: [_jsx("div", { style: { height: '100%', borderRadius: 'inherit', width: `${used}%`,
+                    background: usageBarColor(quota.usedPercent, elapsed, preset, fresh) } }), elapsed !== undefined && _jsx("span", { "aria-hidden": "true", "data-usage-time-marker": true, style: {
+                    position: 'absolute', left: `clamp(0px, calc(${elapsed}% - 1px), calc(100% - 2px))`,
+                    top: 0, bottom: 0, width: 2, background: 'var(--dsw-alias-label-primary)',
+                    boxShadow: '0 0 0 1px var(--dsw-alias-bg-layer-1)',
+                } })] });
+}

package/lib/client/host-contract.d.ts

@@ -83,7 +83,7 @@ export declare const HOST_CONTRACT: {
     /** Design tokens the client styles with; the host theme must define each one. */
     readonly tokens: {
         readonly package: "@deepseek-ai/dsh-client-ui-theme";
-        readonly names: readonly ["--dsw-alias-bg-layer-1", "--dsw-alias-bg-skeleton", "--dsw-alias-border-l2", "--dsw-alias-border-l2-darkmode-thin", "--dsw-alias-interactive-bg-hover", "--dsw-alias-interactive-bg-hover-solid", "--dsw-alias-label-dimmed", "--dsw-alias-label-primary", "--dsw-alias-label-secondary", "--dsw-alias-label-tertiary", "--dsw-alias-state-error-primary", "--dsw-alias-state-success-primary", "--dsw-alias-state-warn-label", "--dsw-elevation-prominent", "--dsw-specific-menu"];
+        readonly names: readonly ["--dsw-alias-bg-layer-1", "--dsw-alias-bg-skeleton", "--dsw-alias-border-l2", "--dsw-alias-border-l2-darkmode-thin", "--dsw-alias-interactive-bg-hover", "--dsw-alias-interactive-bg-hover-solid", "--dsw-alias-label-dimmed", "--dsw-alias-label-primary", "--dsw-alias-label-secondary", "--dsw-alias-label-tertiary", "--dsw-alias-state-error-primary", "--dsw-alias-state-success-primary", "--dsw-alias-state-warn-label", "--dsw-elevation-prominent", "--dsw-menu-backdrop-filter", "--dsw-specific-menu"];
     };
 };
 /** A glyph name listed in {@link HOST_CONTRACT}; hostIcon() accepts no other. */

package/lib/client/host-contract.js

@@ -95,6 +95,7 @@ export const HOST_CONTRACT = {
             '--dsw-alias-state-success-primary',
             '--dsw-alias-state-warn-label',
             '--dsw-elevation-prominent',
+            '--dsw-menu-backdrop-filter',
             '--dsw-specific-menu',
         ],
     },

package/lib/client/locales.d.ts

@@ -79,6 +79,30 @@ export declare const en: {
     usageMonthly: string;
     usageWindow: string;
     usageResets: string;
+    usageMeterUsed: string;
+    usageMeterPace: string;
+    usageMeterPaceAhead: string;
+    usageMeterPaceBehind: string;
+    usageMeterPaceEven: string;
+    usageMeterInvalid: string;
+    usageMeterStale: string;
+    usageMeterNearLimit: string;
+    usageMeterAhead: string;
+    usageMeterNoWarning: string;
+    usageMeterUnknownTime: string;
+    usageMeterReset: string;
+    usageUnitDay: string;
+    usageUnitDays: string;
+    usageUnitHour: string;
+    usageUnitHours: string;
+    usageUnitMinute: string;
+    usageUnitMinutes: string;
+    usageColorLabel: string;
+    usageColorStandard: string;
+    usageColorRelaxed: string;
+    usageColorRemaining: string;
+    usageColorPaceHint: string;
+    usageColorRemainingHint: string;
     usagePlan: string;
     externalUsageTitle: string;
     externalUsageConnected: string;
@@ -226,6 +250,30 @@ export declare const zh: {
     usageMonthly: string;
     usageWindow: string;
     usageResets: string;
+    usageMeterUsed: string;
+    usageMeterPace: string;
+    usageMeterPaceAhead: string;
+    usageMeterPaceBehind: string;
+    usageMeterPaceEven: string;
+    usageMeterInvalid: string;
+    usageMeterStale: string;
+    usageMeterNearLimit: string;
+    usageMeterAhead: string;
+    usageMeterNoWarning: string;
+    usageMeterUnknownTime: string;
+    usageMeterReset: string;
+    usageUnitDay: string;
+    usageUnitDays: string;
+    usageUnitHour: string;
+    usageUnitHours: string;
+    usageUnitMinute: string;
+    usageUnitMinutes: string;
+    usageColorLabel: string;
+    usageColorStandard: string;
+    usageColorRelaxed: string;
+    usageColorRemaining: string;
+    usageColorPaceHint: string;
+    usageColorRemainingHint: string;
     usagePlan: string;
     externalUsageTitle: string;
     externalUsageConnected: string;

package/lib/client/locales.js

@@ -79,6 +79,30 @@ export const en = {
     usageMonthly: 'Monthly',
     usageWindow: 'Window',
     usageResets: 'resets {date}',
+    usageMeterUsed: 'Used {used}% · Remaining {remaining}%',
+    usageMeterPace: 'Time elapsed {elapsed}% (vertical marker)',
+    usageMeterPaceAhead: '{points} points ahead of pace',
+    usageMeterPaceBehind: '{points} points behind pace',
+    usageMeterPaceEven: 'On pace',
+    usageMeterInvalid: 'Quota unavailable',
+    usageMeterStale: 'Reading is stale or unavailable; refresh to confirm',
+    usageMeterNearLimit: 'Near exhaustion',
+    usageMeterAhead: 'Usage ahead of pace',
+    usageMeterNoWarning: 'No quota warning',
+    usageMeterUnknownTime: 'Time progress unknown',
+    usageMeterReset: 'Resets in {duration}',
+    usageUnitDay: '{count} day',
+    usageUnitDays: '{count} days',
+    usageUnitHour: '{count} hour',
+    usageUnitHours: '{count} hours',
+    usageUnitMinute: '{count} minute',
+    usageUnitMinutes: '{count} minutes',
+    usageColorLabel: 'Usage coloring',
+    usageColorStandard: 'Standard (default · 10-point lead)',
+    usageColorRelaxed: 'Relaxed (15-point lead)',
+    usageColorRemaining: 'Remaining quota only (no yellow)',
+    usageColorPaceHint: 'Yellow when usage leads elapsed time by {allowance} points; red at 90% used takes priority. Saved in this browser; only colors change.',
+    usageColorRemainingHint: 'Red at 90% used; no yellow pace warnings. Reliable time markers remain visible. Saved in this browser.',
     usagePlan: 'Plan: {plan}',
     externalUsageTitle: 'Built-in provider usage',
     externalUsageConnected: 'API key configured',
@@ -226,6 +250,30 @@ export const zh = {
     usageMonthly: '每月',
     usageWindow: '窗口',
     usageResets: '{date} 重置',
+    usageMeterUsed: '已用 {used}% · 剩余 {remaining}%',
+    usageMeterPace: '时间已过 {elapsed}%（竖线标记）',
+    usageMeterPaceAhead: '领先时间进度 {points} 个百分点',
+    usageMeterPaceBehind: '落后时间进度 {points} 个百分点',
+    usageMeterPaceEven: '与时间进度一致',
+    usageMeterInvalid: '额度数据不可用',
+    usageMeterStale: '读数已陈旧或不可用，请刷新确认',
+    usageMeterNearLimit: '额度接近耗尽',
+    usageMeterAhead: '用量领先时间进度',
+    usageMeterNoWarning: '未触发额度警告',
+    usageMeterUnknownTime: '时间进度未知',
+    usageMeterReset: '{duration}后重置',
+    usageUnitDay: '{count} 天',
+    usageUnitDays: '{count} 天',
+    usageUnitHour: '{count} 小时',
+    usageUnitHours: '{count} 小时',
+    usageUnitMinute: '{count} 分钟',
+    usageUnitMinutes: '{count} 分钟',
+    usageColorLabel: '用量配色',
+    usageColorStandard: '标准（默认 · 领先 10 个百分点）',
+    usageColorRelaxed: '宽松（领先 15 个百分点）',
+    usageColorRemaining: '仅剩余额度（不显示黄色）',
+    usageColorPaceHint: '用量领先时间进度 {allowance} 个百分点时变黄；已用达到 90% 时优先变红。自动保存到当前浏览器，仅改变配色。',
+    usageColorRemainingHint: '已用达到 90% 时变红，不显示黄色节奏警告。可靠的时间标记仍保留，自动保存到当前浏览器。',
     usagePlan: '计划：{plan}',
     externalUsageTitle: '内置供应商用量',
     externalUsageConnected: '已配置 API 密钥',

package/lib/client/subscription-card-styles.js

@@ -45,9 +45,4 @@ export const subscriptionCardStyles = {
         display: 'flex', justifyContent: 'space-between', gap: 8,
         fontSize: 12, lineHeight: '18px', color: 'var(--dsw-alias-label-tertiary)',
     },
-    usageTrack: {
-        height: 6, borderRadius: 3, overflow: 'hidden',
-        background: 'var(--dsw-alias-bg-layer-1)', border: '1px solid var(--dsw-alias-border-l2)',
-    },
-    usageFill: { height: '100%', borderRadius: 3 },
 };

package/lib/client/usage-color-preferences.d.ts

@@ -0,0 +1,6 @@
+export type UsageColorPreset = 'standard' | 'relaxed' | 'remaining';
+export declare function isUsageColorPreset(value: unknown): value is UsageColorPreset;
+export declare function readUsageColorPreset(): UsageColorPreset;
+export declare function setUsageColorPreset(value: UsageColorPreset): void;
+export declare function subscribeUsageColorPreset(notify: () => void): () => void;
+export declare function useUsageColorPreset(): UsageColorPreset;

package/lib/client/usage-color-preferences.js

@@ -0,0 +1,38 @@
+import { useSyncExternalStore } from 'react';
+const KEY = 'dsh.subscriptions.usageColorPreset';
+const EVENT = 'dsh:subscriptions:usage-color-preset';
+export function isUsageColorPreset(value) {
+    return value === 'standard' || value === 'relaxed' || value === 'remaining';
+}
+export function readUsageColorPreset() {
+    if (typeof window === 'undefined')
+        return 'standard';
+    try {
+        const value = window.localStorage.getItem(KEY);
+        return isUsageColorPreset(value) ? value : 'standard';
+    }
+    catch (error) {
+        if (!(error instanceof DOMException) || error.name !== 'SecurityError')
+            throw error;
+        return 'standard';
+    }
+}
+export function setUsageColorPreset(value) {
+    if (!isUsageColorPreset(value))
+        throw new TypeError('Invalid usage coloring preset');
+    window.localStorage.setItem(KEY, value);
+    window.dispatchEvent(new Event(EVENT));
+}
+export function subscribeUsageColorPreset(notify) {
+    const storage = (event) => { if (event.key === KEY || event.key === null)
+        notify(); };
+    window.addEventListener(EVENT, notify);
+    window.addEventListener('storage', storage);
+    return () => {
+        window.removeEventListener(EVENT, notify);
+        window.removeEventListener('storage', storage);
+    };
+}
+export function useUsageColorPreset() {
+    return useSyncExternalStore(subscribeUsageColorPreset, readUsageColorPreset, () => 'standard');
+}

package/lib/client/usage-pace.d.ts

@@ -0,0 +1,29 @@
+import type { UsageWindow } from './SubscriptionsSection.js';
+import type { UsageColorPreset } from './usage-color-preferences.js';
+export interface UsageObservation {
+    observedAt?: number | undefined;
+    stale?: boolean | undefined;
+}
+export type UsageColorState = 'neutral' | 'red' | 'yellow' | 'green';
+export declare const USAGE_FRESHNESS_MS: number;
+export declare function validUsage(used: number): boolean;
+/**
+ * Rounded share for display, or undefined when the provider's number is
+ * unusable. Callers must show the unavailable state rather than clamp an
+ * out-of-range reading into 0% or 100%.
+ */
+export declare function displayUsedPercent(used: number): number | undefined;
+export interface CountdownPart {
+    unit: 'day' | 'hour' | 'minute';
+    count: number;
+}
+/**
+ * Reset countdown as the two largest nonzero whole units, rounded up so a
+ * window never announces zero remaining time. Always at least one minute.
+ */
+export declare function resetCountdownParts(ms: number): CountdownPart[];
+export declare function isUsageFresh(window: UsageWindow, observation: UsageObservation, now?: number): boolean;
+/** Only explicit intervals or provider-verified fixed durations support linear pace. */
+export declare function elapsedPercent(window: UsageWindow, now?: number): number | undefined;
+export declare function usageColorState(used: number, elapsed: number | undefined, preset: UsageColorPreset, fresh: boolean): UsageColorState;
+export declare function usageBarColor(used: number, elapsed?: number, preset?: UsageColorPreset, fresh?: boolean): string;

package/lib/client/usage-pace.js

@@ -0,0 +1,58 @@
+export const USAGE_FRESHNESS_MS = 5 * 60_000;
+export function validUsage(used) {
+    return Number.isFinite(used) && used >= 0 && used <= 100;
+}
+/**
+ * Rounded share for display, or undefined when the provider's number is
+ * unusable. Callers must show the unavailable state rather than clamp an
+ * out-of-range reading into 0% or 100%.
+ */
+export function displayUsedPercent(used) {
+    return validUsage(used) ? Math.round(used) : undefined;
+}
+/**
+ * Reset countdown as the two largest nonzero whole units, rounded up so a
+ * window never announces zero remaining time. Always at least one minute.
+ */
+export function resetCountdownParts(ms) {
+    const total = Math.max(1, Math.ceil(ms / 60_000));
+    const parts = [
+        { unit: 'day', count: Math.floor(total / 1440) },
+        { unit: 'hour', count: Math.floor((total % 1440) / 60) },
+        { unit: 'minute', count: total % 60 },
+    ];
+    return parts.filter(part => part.count > 0).slice(0, 2);
+}
+export function isUsageFresh(window, observation, now = Date.now()) {
+    return validUsage(window.usedPercent) && observation.stale !== true
+        && observation.observedAt !== undefined && Number.isFinite(observation.observedAt)
+        && observation.observedAt <= now && now - observation.observedAt <= USAGE_FRESHNESS_MS
+        && (window.resetsAt === undefined || Number.isFinite(window.resetsAt) && window.resetsAt > now);
+}
+/** Only explicit intervals or provider-verified fixed durations support linear pace. */
+export function elapsedPercent(window, now = Date.now()) {
+    const end = window.resetsAt;
+    if (end === undefined || !Number.isFinite(end) || end <= now)
+        return undefined;
+    const duration = window.windowDurationMs;
+    const start = window.startsAt ?? (window.fixedWindow === true && duration !== undefined && Number.isFinite(duration) && duration > 0 ? end - duration : undefined);
+    if (start === undefined || !Number.isFinite(start) || start >= end || start > now)
+        return undefined;
+    return Math.min(100, Math.max(0, (now - start) / (end - start) * 100));
+}
+export function usageColorState(used, elapsed, preset, fresh) {
+    if (!validUsage(used))
+        return 'neutral';
+    if (used >= 90)
+        return 'red';
+    // Missing pace or stale observations retain the last reported absolute color.
+    if (!fresh || preset === 'remaining' || elapsed === undefined)
+        return 'green';
+    return used - elapsed >= (preset === 'relaxed' ? 15 : 10) ? 'yellow' : 'green';
+}
+export function usageBarColor(used, elapsed, preset = 'standard', fresh = true) {
+    const state = usageColorState(used, elapsed, preset, fresh);
+    return state === 'red' ? 'var(--dsw-alias-state-error-primary)'
+        : state === 'yellow' ? 'var(--dsw-alias-state-warn-label)'
+            : 'var(--dsw-alias-state-success-primary)';
+}