@iasiv5/dsh-quota-watch 0.1.18 → 0.1.20

package/README.md

@@ -14,7 +14,7 @@
 
 ## ✨ 功能一览
 
-- **🚀 悬浮胶囊（默认界面）**：一行「GLM 15% · Copilot 1.8%」常驻屏幕（默认右下角安全区），单击展开面板——胶囊上没有任何隐藏手势（右键 / 长按菜单已于 0.1.14 退役）。拖拽跟手（保持抓取点，transform 渲染）、任意位置停放、位置跨重启记忆、越界自动钳回视口（距边 8px 安全边距）；触摸设备直接拖拽（更宽的防误拖阈值）、点击热区 44px、自动避让 iPhone 刘海 / 小黑条（safe-area）。已用超过 80% 转橙、超过 95% 转红，任一 provider 超 95% 时轻微脉动（尊重系统「减少动态效果」设置）。悬停提示与 aria-label 实时给出摘要。
+- **🚀 悬浮胶囊（默认界面）**：一行「GLM 15% · Copilot 1.8%」常驻屏幕（默认右下角安全区），单击展开面板——胶囊上没有任何隐藏手势（右键 / 长按菜单已于 0.1.14 退役）。拖拽跟手（保持抓取点，transform 渲染）、任意位置停放、位置跨重启记忆、越界自动钳回视口（距边 8px 安全边距），并自动避开 Windows Desktop 壳顶部的标题栏拖拽带（0.1.20：该带按布局吞掉指针输入、无视 z-index，胶囊/面板落进去就再也点不到、拖不回——现与壳自家浮窗同款消费 `--dsh-windows-titlebar-height` 让位，历史卡死位置在启动时自动钳回带外；Web 无此变量，行为零漂移）；触摸设备直接拖拽（更宽的防误拖阈值）、点击热区 44px、自动避让 iPhone 刘海 / 小黑条（safe-area）。已用超过 80% 转橙、超过 95% 转红，任一 provider 超 95% 时轻微脉动（尊重系统「减少动态效果」设置）。悬停提示与 aria-label 实时给出摘要。
 - **🖥️ 详情面板**：半透明毛玻璃底，宽 `min(320px, 100vw−24px)`，靠边自动翻侧，滚动 / 缩放跟随；≤480px 窄屏自动改为底部弹层并避开 safe-area；Esc 或点击面板外关闭。概览列两个 provider 行，点击进入详情：
   - **GLM**：今日 Tokens / 调用次数双大数字 + 五列对齐窗口网格（MCP（月）→ 5 小时 → 每月 → 每周固定排序，周窗口未下发时显示「每周额度 · ♾️（无限）」占位）+ 分模型用量行；
   - **Copilot**：可用额度、本期已用（credits 消耗 + 弱化百分比）、重置时间三行。
@@ -23,7 +23,7 @@
 - **🧩 侧边栏卡片（可选，默认隐藏）**：胶囊是默认界面；需要侧栏卡片时从面板底部按钮开启（Web profile 侧栏底部区块存在时才出现该按钮）。卡片提供摘要行 + 行点击开面板 + 行首 provider 名称点击立即探测。侧栏收起（Web 窄栏）或容器过窄（<160px，跨 profile 通用判据）时自动隐藏，侧栏整体不存在（Desktop 收起态）同样自然缺席、无报错——入口始终由悬浮胶囊承载。
 - **🌏 语言跟随宿主**：界面文案跟随 DSH「设置 → 语言」——宿主 locale 特性把解析结果实时镜像到 `<html lang>`，插件监听该属性，切换即热重渲染（无需刷新页面）；宿主未同步时回退浏览器语言。
 - **🛟 降级与容错**：凭据缺失的 provider 不渲染摘要行与胶囊分段（两者皆缺时悬浮胶囊与卡片一并隐藏）；探测失败时保留最后一次成功数据并在行上加 ⚠ 过期标记（⚠ 只出现在面板与卡片行内，不在胶囊上显示）。
-- **🔁 刷新节奏**：宿主默认每 60 秒探测（窗口 + 用量 + Copilot），profile 可配 30–3600 秒；浏览器页签可见时每 30 秒刷新视图，隐藏时暂停。所有 UI 收在 Shadow DOM 里（ADR 0001），颜色走 DSH 主题语义变量（含硬编码兜底），自动适配浅色 / 深色主题。
+- **🔁 刷新节奏**：宿主默认每 60 秒探测（窗口 + 用量 + Copilot），profile 可配 30–3600 秒；浏览器页签可见时每 30 秒刷新视图，隐藏时暂停。重启冷启动零等待：宿主 0 秒即发首轮探测（网络未就绪时以 5 秒冷重试直至拿到数据），客户端在无数据期间以 2 秒起步的指数退避快速重试、拿到数据后回到常规节奏——重启后数秒内胶囊即出现，不再有 ~30 秒空窗。所有 UI 收在 Shadow DOM 里（ADR 0001），颜色走 DSH 主题语义变量（含硬编码兜底），自动适配浅色 / 深色主题。
 
 ## 📸 界面巡礼
 
@@ -71,4 +71,4 @@ dsh plugin --profile desktop add @iasiv5/dsh-quota-watch  # desktop profile
 
 ## English summary
 
-DSH Quota Watch is a personal DSH quota monitor built around a persistent floating capsule: a one-line `GLM x% · Copilot y%` summary that turns amber past 80% and red past 95%. Dragging it is grab-accurate (transform-based, rAF-batched) and free to place anywhere on the screen, with position remembered across restarts and viewport boundaries automatically clamped. Touch devices drag directly (wider slop against accidental drags), the hit area is padded to 44px and placement respects `env(safe-area-inset-*)`. Clicking the capsule opens a floating glass panel whose overview reuses the classic 0.0.18 summary rows (label · bar · percent · extra · chevron) and whose detail pages replicate the 0.0.18 big numbers, window grid and per-model list; the panel closes via ✕, Esc or an outside click, and viewports ≤480px dock it to the bottom as a sheet. The panel footer holds two equal-width buttons — sidebar-card visibility and an immediate provider re-probe — replacing the retired right-click/long-press menu, so the capsule itself carries no hidden gestures. A sidebar card remains an opportunistic extra entry on web profiles, opted in from that footer button, and silently disappears whenever the sidebar does — collapsed web sidebars and the desktop profile are covered by the floating capsule alone. Credentials are resolved on every host-side probe, only normalized values reach the browser, no usage history is kept, and a Copilot balance is never inferred from credits used. UI copy follows the DSH language preference (mirrored live onto `<html lang>`, re-rendering on switch without a reload) and falls back to the browser language; window notes share one paren glyph per locale so the grid's left edges stay aligned. Colors ride DSH semantic theme tokens with hardcoded fallbacks; all UI lives inside a shadow root (ADR 0001).
+DSH Quota Watch is a personal DSH quota monitor built around a persistent floating capsule: a one-line `GLM x% · Copilot y%` summary that turns amber past 80% and red past 95%. Dragging it is grab-accurate (transform-based, rAF-batched) and free to place anywhere on the screen, with position remembered across restarts and viewport boundaries automatically clamped. Since 0.1.20 placement also steers clear of the Windows Desktop shell titlebar drag band (a layout-level `-webkit-app-region:drag` strip that swallows pointer input regardless of z-index — the same trap dsh-m fixed in 0.9.4; the capsule and the panel header consume `--dsh-windows-titlebar-height` the way the shell's own floats do, and positions saved while stuck self-heal below the band on boot; Web, without the variable, is byte-identical). Touch devices drag directly (wider slop against accidental drags), the hit area is padded to 44px and placement respects `env(safe-area-inset-*)`. Clicking the capsule opens a floating glass panel whose overview reuses the classic 0.0.18 summary rows (label · bar · percent · extra · chevron) and whose detail pages replicate the 0.0.18 big numbers, window grid and per-model list; the panel closes via ✕, Esc or an outside click, and viewports ≤480px dock it to the bottom as a sheet. The panel footer holds two equal-width buttons — sidebar-card visibility and an immediate provider re-probe — replacing the retired right-click/long-press menu, so the capsule itself carries no hidden gestures. A sidebar card remains an opportunistic extra entry on web profiles, opted in from that footer button, and silently disappears whenever the sidebar does — collapsed web sidebars and the desktop profile are covered by the floating capsule alone. Credentials are resolved on every host-side probe, only normalized values reach the browser, no usage history is kept, and a Copilot balance is never inferred from credits used. UI copy follows the DSH language preference (mirrored live onto `<html lang>`, re-rendering on switch without a reload) and falls back to the browser language; window notes share one paren glyph per locale so the grid's left edges stay aligned. Colors ride DSH semantic theme tokens with hardcoded fallbacks; all UI lives inside a shadow root (ADR 0001).

package/lib/client.js

@@ -107,6 +107,11 @@ function clampPoint(point, viewport, size = 0, insets = ZERO_INSETS) {
     y: Math.min(Math.max(point.y, minY), maxY)
   };
 }
+function titlebarTopInset({ titlebar = false, fullscreen = false, height } = {}) {
+  if (!titlebar || fullscreen) return 0;
+  const value = Number.parseFloat(height);
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
 function loadFloatPosition(storage) {
   try {
     const raw = storage.getItem(FLOAT_POSITION_KEY);
@@ -470,7 +475,9 @@ function mountQuotaCard({
   doc = globalThis.document,
   win = globalThis.window,
   fetchImpl = globalThis.fetch,
-  pollIntervalMs = CLIENT_POLL_INTERVAL_MS
+  pollIntervalMs = CLIENT_POLL_INTERVAL_MS,
+  retryNoDataMs = 2e3,
+  retryBackoff = 2
 } = {}) {
   if (!doc?.body || typeof fetchImpl !== "function") return () => {
   };
@@ -549,11 +556,23 @@ function mountQuotaCard({
   const safeAreaProbe = text(doc, "div", "", "");
   safeAreaProbe.style.cssText = "position:fixed;visibility:hidden;pointer-events:none;width:0;height:0;overflow:hidden;padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);";
   floatRoot.append(safeAreaProbe);
+  const readTitlebarInset = () => {
+    try {
+      const html = doc.documentElement;
+      return titlebarTopInset({
+        titlebar: html.hasAttribute("data-windows-titlebar"),
+        fullscreen: html.hasAttribute("data-fullscreen"),
+        height: parseInset(win.getComputedStyle(html)?.getPropertyValue("--dsh-windows-titlebar-height"))
+      });
+    } catch {
+      return 0;
+    }
+  };
   const readInsets = () => {
     try {
       const style2 = win.getComputedStyle(safeAreaProbe);
       return {
-        top: parseInset(style2?.paddingTop),
+        top: Math.max(parseInset(style2?.paddingTop), readTitlebarInset()),
         right: parseInset(style2?.paddingRight),
         bottom: parseInset(style2?.paddingBottom),
         left: parseInset(style2?.paddingLeft)
@@ -670,11 +689,12 @@ function mountQuotaCard({
   let snapshot;
   let requestSequence = 0;
   let timer;
+  let noDataRetries = 0;
   let disposed = false;
   let queuedPlace = false;
   let openKey;
   let panelNav = false;
-  let dataHidden = false;
+  let dataHidden = true;
   let surfaceFlags = loadSurfaceFlags(win.localStorage);
   const setCardHidden = (hidden) => {
     surfaceFlags = { cardHidden: hidden };
@@ -915,7 +935,8 @@ function mountQuotaCard({
     if (left + width > viewWidth - 8) left = rect.left - width - 8;
     if (left + width > viewWidth - 8) left = viewWidth - width - 8;
     left = Math.max(8, left);
-    const top = Math.min(Math.max(rect.top, 8), Math.max(8, viewHeight - height - 8));
+    const minTop = MARGIN + readInsets().top;
+    const top = Math.min(Math.max(rect.top, minTop), Math.max(minTop, viewHeight - height - 8));
     panel.style.left = `${Math.round(left)}px`;
     panel.style.top = `${Math.round(top)}px`;
   };
@@ -1059,6 +1080,13 @@ function mountQuotaCard({
       if (sequence === requestSequence && !disposed) render(next);
     } catch {
       if (sequence === requestSequence && !disposed) showTransportError();
+    } finally {
+      if (timer === void 0 && sequence === requestSequence && !disposed && doc.visibilityState !== "hidden") {
+        timer = win.setTimeout(() => {
+          timer = void 0;
+          if (!disposed && doc.visibilityState !== "hidden") void poll();
+        }, nextPollDelay());
+      }
     }
   };
   const place = () => {
@@ -1089,16 +1117,23 @@ function mountQuotaCard({
     if (!disposed) renderAll();
   }) : null;
   langObserver?.observe(doc.documentElement, { attributeFilter: ["lang"] });
+  syncFloatVisibility();
   place();
+  const nextPollDelay = () => {
+    if (!dataHidden) {
+      noDataRetries = 0;
+      return pollIntervalMs;
+    }
+    const delay = retryNoDataMs * retryBackoff ** noDataRetries;
+    noDataRetries += 1;
+    return Math.min(delay, pollIntervalMs);
+  };
   const startPolling = () => {
     if (timer !== void 0 || doc.visibilityState === "hidden" || disposed) return;
     void poll();
-    timer = win.setInterval(() => {
-      void poll();
-    }, pollIntervalMs);
   };
   const stopPolling = () => {
-    if (timer !== void 0) win.clearInterval(timer);
+    if (timer !== void 0) win.clearTimeout(timer);
     timer = void 0;
   };
   const onVisibilityChange = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iasiv5/dsh-quota-watch",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "DSH Web sidebar monitor for GLM Coding Plan quotas and GitHub Copilot credits",
   "type": "module",
   "main": "./src/host.mjs",

package/src/client/prefs.mjs

@@ -31,6 +31,20 @@ export function clampPoint(point, viewport, size = 0, insets = ZERO_INSETS) {
   }
 }
 
+// Windows Desktop shell titlebar contract (0.1.20): the shell runs
+// `titleBarStyle:hidden + titleBarOverlay`, so the top strip of the window is a
+// full-width `-webkit-app-region:drag` band that swallows pointer input by
+// LAYOUT — z-index and paint order are irrelevant — and a capsule parked inside
+// it can never be grabbed or clicked again. The shell flags the band on
+// <html> with `data-windows-titlebar` + `--dsh-windows-titlebar-height` and
+// clears it under `data-fullscreen`; its own floats clamp to exactly this
+// value. Everything else (DSH Web, browsers, jsdom) yields 0 — zero drift.
+export function titlebarTopInset({ titlebar = false, fullscreen = false, height } = {}) {
+  if (!titlebar || fullscreen) return 0
+  const value = Number.parseFloat(height)
+  return Number.isFinite(value) && value > 0 ? value : 0
+}
+
 export function loadFloatPosition(storage) {
   try {
     const raw = storage.getItem(FLOAT_POSITION_KEY)

package/src/client.mjs

@@ -1,6 +1,6 @@
 import { CLIENT_POLL_INTERVAL_MS, CLIENT_ROUTES } from './shared.mjs'
 import { remainingToUsed } from './core/adapters.mjs'
-import { MARGIN, clampPoint, loadFloatPosition, loadSurfaceFlags, saveFloatPosition, saveSurfaceFlags } from './client/prefs.mjs'
+import { MARGIN, clampPoint, loadFloatPosition, loadSurfaceFlags, saveFloatPosition, saveSurfaceFlags, titlebarTopInset } from './client/prefs.mjs'
 import { DRAG_SLOP_MOUSE, DRAG_SLOP_TOUCH, parseInset, clampFrame, dragSlop, grabOffset } from './client/drag.mjs'
 
 export const name = 'quota-watch-client'
@@ -373,6 +373,8 @@ export function mountQuotaCard({
   win = globalThis.window,
   fetchImpl = globalThis.fetch,
   pollIntervalMs = CLIENT_POLL_INTERVAL_MS,
+  retryNoDataMs = 2_000,
+  retryBackoff = 2,
 } = {}) {
   if (!doc?.body || typeof fetchImpl !== 'function') return () => {}
   if (doc.querySelector(CARD_SELECTOR) || doc.querySelector(FLOAT_SELECTOR)) return () => {}
@@ -448,7 +450,8 @@ export function mountQuotaCard({
     const rect = surface.getBoundingClientRect()
     return rect.width > 0 ? { width: rect.width, height: rect.height } : FALLBACK_SIZE
   }
-  /** Position = user preferred {x, y} clamped to viewport & safe-area insets. */
+  /** Position = user preferred {x, y} clamped to viewport, safe-area insets
+   * and the Windows shell titlebar band. */
   const applyPosition = () => {
     const viewWidth = win.innerWidth ?? 1024
     const viewHeight = win.innerHeight ?? 768
@@ -469,13 +472,37 @@ export function mountQuotaCard({
   const safeAreaProbe = text(doc, 'div', '', '')
   safeAreaProbe.style.cssText = 'position:fixed;visibility:hidden;pointer-events:none;width:0;height:0;overflow:hidden;padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);'
   floatRoot.append(safeAreaProbe)
+  // Windows Desktop titlebar band (0.1.20): with `titleBarStyle:hidden +
+  // titleBarOverlay` the top strip of the window is the shell's full-width
+  // `-webkit-app-region:drag` band — it wins pointer input by layout, ignoring
+  // z-index, so a capsule dropped there is stuck for good (un-grabbable,
+  // un-clickable, and the persisted position kept re-parking it). Folding the
+  // band into the top inset routes it through every clamp path at once: live
+  // drag frames, release docking, persisted-position restore and the default
+  // dock — and mount-time clamping also self-heals positions saved by 0.1.19.
+  // Same contract the shell's own floats consume: `data-windows-titlebar` +
+  // `--dsh-windows-titlebar-height` on <html>, dropped under `data-fullscreen`.
+  // DSH Web / browsers have neither attribute nor variable → 0, zero drift.
+  const readTitlebarInset = () => {
+    try {
+      const html = doc.documentElement
+      return titlebarTopInset({
+        titlebar: html.hasAttribute('data-windows-titlebar'),
+        fullscreen: html.hasAttribute('data-fullscreen'),
+        height: parseInset(win.getComputedStyle(html)?.getPropertyValue('--dsh-windows-titlebar-height')),
+      })
+    } catch {
+      return 0
+    }
+  }
   /** Live env(safe-area-inset-*) reading — re-probed on every use, so window
-   * chrome changes (rotation, URL-bar collapse) need no explicit invalidation. */
+   * chrome changes (rotation, URL-bar collapse) need no explicit invalidation.
+   * `top` is the larger of the safe-area inset and the shell titlebar band. */
   const readInsets = () => {
     try {
       const style = win.getComputedStyle(safeAreaProbe)
       return {
-        top: parseInset(style?.paddingTop),
+        top: Math.max(parseInset(style?.paddingTop), readTitlebarInset()),
         right: parseInset(style?.paddingRight),
         bottom: parseInset(style?.paddingBottom),
         left: parseInset(style?.paddingLeft),
@@ -610,11 +637,15 @@ export function mountQuotaCard({
   let snapshot
   let requestSequence = 0
   let timer
+  let noDataRetries = 0
   let disposed = false
   let queuedPlace = false
   let openKey
   let panelNav = false
-  let dataHidden = false
+  // Cold until the first successful render: a mount whose first poll fails or
+  // stalls must behave like the documented no-data state (hidden shell, fast
+  // retries), not like a warm client showing an empty capsule.
+  let dataHidden = true
   let surfaceFlags = loadSurfaceFlags(win.localStorage)
   const setCardHidden = (hidden) => {
     surfaceFlags = { cardHidden: hidden }
@@ -886,7 +917,11 @@ export function mountQuotaCard({
     if (left + width > viewWidth - 8) left = rect.left - width - 8
     if (left + width > viewWidth - 8) left = viewWidth - width - 8
     left = Math.max(8, left)
-    const top = Math.min(Math.max(rect.top, 8), Math.max(8, viewHeight - height - 8))
+    // The panel header carries the close button: keep its top edge below the
+    // shell titlebar band (and safe-area top) for the same reason as the
+    // capsule — layout-level drag hits ignore z-index. Web fallback: 8px, as before.
+    const minTop = MARGIN + readInsets().top
+    const top = Math.min(Math.max(rect.top, minTop), Math.max(minTop, viewHeight - height - 8))
     panel.style.left = `${Math.round(left)}px`
     panel.style.top = `${Math.round(top)}px`
   }
@@ -1052,6 +1087,18 @@ export function mountQuotaCard({
       if (sequence === requestSequence && !disposed) render(next)
     } catch {
       if (sequence === requestSequence && !disposed) showTransportError()
+    } finally {
+      // Self-scheduling chain (replaces the fixed interval): every completed
+      // poll — success OR transport error — arms the next one, so the no-data
+      // backoff also covers a cold start whose first request fails outright.
+      // timer === undefined guards against a concurrent force poll forking a
+      // second chain; the already-armed timer keeps the cadence.
+      if (timer === undefined && sequence === requestSequence && !disposed && doc.visibilityState !== 'hidden') {
+        timer = win.setTimeout(() => {
+          timer = undefined
+          if (!disposed && doc.visibilityState !== 'hidden') void poll()
+        }, nextPollDelay())
+      }
     }
   }
 
@@ -1091,15 +1138,33 @@ export function mountQuotaCard({
     ? new win.MutationObserver(() => { if (!disposed) renderAll() })
     : null
   langObserver?.observe(doc.documentElement, { attributeFilter: ['lang'] })
+  // Cold until data lands: keep the shell hidden so a slow or failed first
+  // probe never flashes an empty capsule (startPolling arms the retry chain).
+  syncFloatVisibility()
   place()
 
+  /** Cold-start cadence: while no provider has rendered any data, re-poll on
+   * a shortening backoff (retryNoDataMs × retryBackoffⁿ, capped at
+   * pollIntervalMs) so a desktop cold start surfaces the capsule in seconds
+   * instead of waiting out the fixed interval. A successful render resets the
+   * chain to the normal cadence; a transport error keeps the previous
+   * dataHidden state, so a cold client keeps retrying fast and a warm one
+   * stays calm. */
+  const nextPollDelay = () => {
+    if (!dataHidden) {
+      noDataRetries = 0
+      return pollIntervalMs
+    }
+    const delay = retryNoDataMs * (retryBackoff ** noDataRetries)
+    noDataRetries += 1
+    return Math.min(delay, pollIntervalMs)
+  }
   const startPolling = () => {
     if (timer !== undefined || doc.visibilityState === 'hidden' || disposed) return
     void poll()
-    timer = win.setInterval(() => { void poll() }, pollIntervalMs)
   }
   const stopPolling = () => {
-    if (timer !== undefined) win.clearInterval(timer)
+    if (timer !== undefined) win.clearTimeout(timer)
     timer = undefined
   }
   const onVisibilityChange = () => {

package/src/host.mjs

@@ -311,7 +311,18 @@ export function createQuotaService(ctx, options = {}) {
     timer = setTimeout(async () => {
       timer = undefined
       await refresh()
-      schedule(pollIntervalSec * 1000)
+      // Cold-start retry: until at least one provider has reached ready/stale,
+      // a failed or still-loading round re-arms shortly instead of waiting a
+      // full interval — a desktop cold start with a slow network would
+      // otherwise stare at no capsule for up to a minute. (updatedAt alone
+      // cannot signal "cold": refresh() stamps it even when every probe
+      // failed.) All-'missing' (no credentials configured) and warm states
+      // keep the normal cadence, so nobody without credentials gets
+      // high-frequency probing.
+      const states = [...providers.values()].map((provider) => provider.status)
+      const retryable = states.some((status) => status === 'loading' || status === 'error')
+        && states.every((status) => status !== 'ready' && status !== 'stale')
+      schedule(retryable ? (options.coldRetryMs ?? 5_000) : pollIntervalSec * 1000)
     }, delayMs)
     timer.unref?.()
   }
@@ -321,7 +332,9 @@ export function createQuotaService(ctx, options = {}) {
     refresh,
     start() {
       if (disposed || timer !== undefined) return
-      schedule(2_000)
+      // Routes register synchronously in apply() before start(), so probing
+      // immediately is safe; the legacy 2s delay only padded the cold start.
+      schedule(0)
     },
     stop() {
       disposed = true