@iasiv5/dsh-quota-watch 0.1.9 → 0.1.11

package/README.md

@@ -6,11 +6,11 @@
 
 ## 功能
 
-- **悬浮胶囊**（0.1.1 起为唯一浮动形态，圆球已退役）：常驻屏幕右下角（距边 16px 起步），可整体拖拽到任意位置，位置跨重启记忆，越界自动钳回视口。胶囊一行显示「GLM 13% · Copilot 24%」，已用超过 80% 转橙、超过 95% 转红，任一 provider 超 95% 时胶囊轻微脉动（尊重系统「减少动态效果」设置，开启时不脉动）；颜色使用 DSH 主题语义变量，自动适配浅色 / 深色主题。悬停提示与 aria-label 实时给出摘要。
-- **面板**：点击球或胶囊展开浮动详情面板（半透明毛玻璃底，宽 `min(320px, 100vw−24px)`，靠边自动翻侧，滚动 / 缩放跟随），头部带标题与 ✕，Esc 或点击面板外关闭。概览列两个 provider 行，点击进入详情：GLM 为今日 Tokens / 调用次数双大数字 + 五列对齐窗口网格（MCP（月）→ 5 小时 → 每月 → 每周固定排序，周窗口未下发时显示「每周额度 · ♾️（无限）」占位）+ 分模型用量行；Copilot 为可用额度、本期已用（credits 消耗 + 弱化百分比）、重置时间三行。接口未下发有效 `remaining` / `percent_remaining` 时该行不渲染，`credits_used` 绝不用于推算余额。
+- **悬浮胶囊**（0.1.1 起为唯一浮动形态，圆球已退役）：拖拽松手后磁性贴靠左右屏幕边缘、完整可见（距边 8px），记住停靠边与纵向位置，跨重启恢复；数据文本变宽、窗口缩放或转屏后自动重新贴边。拖拽跟手（保持抓取点，transform 渲染）；触摸设备可直接拖拽（触摸阈值更宽防误拖）、长按 500ms 呼出菜单，点击热区扩展到 44px，自动避让 iPhone 刘海 / 小黑条（safe-area）。胶囊一行显示「GLM 13% · Copilot 24%」，已用超过 80% 转橙、超过 95% 转红，任一 provider 超 95% 时胶囊轻微脉动（尊重系统「减少动态效果」设置，开启时不脉动、贴边直落无动画）；颜色使用 DSH 主题语义变量，自动适配浅色 / 深色主题。悬停提示与 aria-label 实时给出摘要。
+- **面板**：点击胶囊展开浮动详情面板（半透明毛玻璃底，宽 `min(320px, 100vw−24px)`，靠边自动翻侧，滚动 / 缩放跟随；≤480px 窄屏自动改为底部弹层并避开 safe-area），头部带标题与 ✕，Esc 或点击面板外关闭。概览列两个 provider 行，点击进入详情：GLM 为今日 Tokens / 调用次数双大数字 + 五列对齐窗口网格（MCP（月）→ 5 小时 → 每月 → 每周固定排序，周窗口未下发时显示「每周额度 · ♾️（无限）」占位）+ 分模型用量行；Copilot 为可用额度、本期已用（credits 消耗 + 弱化百分比）、重置时间三行。接口未下发有效 `remaining` / `percent_remaining` 时该行不渲染，`credits_used` 绝不用于推算余额。
 - **侧边栏卡片（可选，默认隐藏）**：胶囊是默认界面；需要侧栏卡片时在胶囊右键菜单开启「显示侧边栏卡片」（Web profile 侧栏底部区块存在时才可选）。卡片显示时提供摘要行 + 行点击开面板 + 行首 provider 名称点击立即探测。侧栏收起（Web 窄栏）或容器过窄（<160px，跨 profile 通用判据）时卡片自动隐藏，侧栏整体不存在（Desktop 收起态）同样自然缺席、无报错——入口始终由悬浮胶囊承载。
 - **右键菜单**：显示 / 隐藏侧边栏卡片 · 立即刷新。菜单项随上下文增减（无侧栏卡片挂载点时只剩刷新项）。
-- 凭据缺失的 provider 不渲染摘要行与胶囊分段（两者皆缺时悬浮胶囊与卡片一并隐藏）；探测失败时保留最后一次成功数据并在行上加 ⚠ 过期标记（⚠ 只出现在面板与卡片行内，不上球）。
+- 凭据缺失的 provider 不渲染摘要行与胶囊分段（两者皆缺时悬浮胶囊与卡片一并隐藏）；探测失败时保留最后一次成功数据并在行上加 ⚠ 过期标记（⚠ 只出现在面板与卡片行内，不在胶囊上显示）。
 - 宿主默认每 60 秒探测（窗口 + 用量 + Copilot）；profile patch 可将 `pollIntervalSec` 设置在 30–3600 秒。浏览器页签可见时每 30 秒刷新视图，隐藏时暂停。
 
 ## 兼容与配置
@@ -47,4 +47,4 @@ dsh plugin --profile web add @iasiv5/dsh-quota-watch
 
 ## 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%, draggable anywhere with position remembered across restarts. 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. A sidebar card remains an opportunistic extra entry on web profiles (with a corner button to hide or restore the capsule) and silently disappears whenever the sidebar does — collapsed web sidebars and the desktop profile are covered by the floating capsule alone. A right-click menu offers card visibility, an immediate provider re-probe and a session-scoped capsule hide. 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. 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 the capsule magnetically docks to the nearest left/right screen edge after release — fully visible, with the docked edge and vertical offset remembered across restarts. Touch devices drag directly (wider slop against accidental drags), a 500ms long-press opens the context menu (iOS has no right-click), the hit area is padded to 44px and the dock 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. A sidebar card remains an opportunistic extra entry on web profiles, opt-in from the capsule's menu, and silently disappears whenever the sidebar does — collapsed web sidebars and the desktop profile are covered by the floating capsule alone. The right-click menu (long-press on touch) offers card visibility and an immediate provider re-probe. 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. Colors ride DSH semantic theme tokens with hardcoded fallbacks; all UI lives inside a shadow root (ADR 0001).

package/lib/client.js

@@ -82,35 +82,51 @@ function remainingToUsed(percentRemaining) {
 }
 
 // src/client/prefs.mjs
-var FLOAT_GEOMETRY_KEY = "dsh-quota-watch:float-geometry";
+var FLOAT_DOCK_KEY = "dsh-quota-watch:float-dock";
 var SURFACE_FLAGS_KEY = "dsh-quota-watch:surface-flags";
 var MARGIN = 8;
-function clampPoint(point, viewport, size = 0) {
-  const minX = MARGIN;
-  const minY = MARGIN;
-  const maxX = Math.max(MARGIN, viewport.width - MARGIN - size);
-  const maxY = Math.max(MARGIN, viewport.height - MARGIN - size);
+var ZERO_INSETS = { left: 0, right: 0, top: 0, bottom: 0 };
+function normalizeSize(size) {
+  if (typeof size === "number") return { width: size, height: size };
+  const width = typeof size?.width === "number" ? size.width : 0;
+  const height = typeof size?.height === "number" ? size.height : 0;
+  return { width, height };
+}
+function clampPoint(point, viewport, size = 0, insets = ZERO_INSETS) {
+  const { width, height } = normalizeSize(size);
+  const insetLeft = Number.isFinite(insets?.left) ? insets.left : 0;
+  const insetRight = Number.isFinite(insets?.right) ? insets.right : 0;
+  const insetTop = Number.isFinite(insets?.top) ? insets.top : 0;
+  const insetBottom = Number.isFinite(insets?.bottom) ? insets.bottom : 0;
+  const minX = MARGIN + insetLeft;
+  const minY = MARGIN + insetTop;
+  const maxX = Math.max(minX, viewport.width - insetRight - MARGIN - width);
+  const maxY = Math.max(minY, viewport.height - insetBottom - MARGIN - height);
   return {
     x: Math.min(Math.max(point.x, minX), maxX),
     y: Math.min(Math.max(point.y, minY), maxY)
   };
 }
-function loadFloatGeometry(storage) {
+var DOCK_EDGES = /* @__PURE__ */ new Set(["left", "right"]);
+function loadFloatDock(storage) {
   try {
-    const raw = storage.getItem(FLOAT_GEOMETRY_KEY);
+    const raw = storage.getItem(FLOAT_DOCK_KEY);
     if (typeof raw !== "string" || raw === "") return null;
     const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null || !Number.isFinite(parsed.x) || !Number.isFinite(parsed.y)) {
+    if (typeof parsed !== "object" || parsed === null || !DOCK_EDGES.has(parsed.edge) || !Number.isFinite(parsed.offsetY)) {
       return null;
     }
-    return { x: parsed.x, y: parsed.y };
+    return { edge: parsed.edge, offsetY: parsed.offsetY };
   } catch {
     return null;
   }
 }
-function saveFloatGeometry(storage, point) {
+function saveFloatDock(storage, dock) {
+  if (typeof dock !== "object" || dock === null || !DOCK_EDGES.has(dock.edge) || !Number.isFinite(dock.offsetY)) {
+    throw new TypeError(`invalid float dock: ${JSON.stringify(dock)}`);
+  }
   try {
-    storage.setItem(FLOAT_GEOMETRY_KEY, JSON.stringify({ x: point.x, y: point.y }));
+    storage.setItem(FLOAT_DOCK_KEY, JSON.stringify({ edge: dock.edge, offsetY: dock.offsetY }));
   } catch {
   }
 }
@@ -134,14 +150,46 @@ function saveSurfaceFlags(storage, flags) {
   }
 }
 
+// src/client/drag.mjs
+var DRAG_SLOP_MOUSE = 6;
+var DRAG_SLOP_TOUCH = 10;
+var LONG_PRESS_MS = 500;
+function dragSlop(pointerType) {
+  return pointerType === "touch" || pointerType === "pen" ? DRAG_SLOP_TOUCH : DRAG_SLOP_MOUSE;
+}
+function grabOffset(point, rect) {
+  return { dx: point.x - rect.left, dy: point.y - rect.top };
+}
+function pillTopLeft(point, grab) {
+  return { x: point.x - grab.dx, y: point.y - grab.dy };
+}
+function clampFrame(point, grab, size, viewport, insets) {
+  return clampPoint(pillTopLeft(point, grab), viewport, size, insets);
+}
+function releaseDock(point, grab, size, viewport, insets) {
+  const topLeft = pillTopLeft(point, grab);
+  const centerX = topLeft.x + size.width / 2;
+  const edge = centerX < viewport.width / 2 ? "left" : "right";
+  return { edge, offsetY: clampPoint(topLeft, viewport, size, insets).y };
+}
+function dockX(edge, width, viewport, insets) {
+  const insetLeft = Number.isFinite(insets?.left) ? insets.left : 0;
+  const insetRight = Number.isFinite(insets?.right) ? insets.right : 0;
+  return edge === "left" ? MARGIN + insetLeft : viewport.width - insetRight - MARGIN - width;
+}
+function parseInset(computedValue) {
+  const value = Number.parseFloat(computedValue);
+  return Number.isFinite(value) ? value : 0;
+}
+
 // src/client.mjs
 var name = "quota-watch-client";
 var inject = [];
 var CARD_SELECTOR = "[data-dsh-quota-watch-card]";
 var FLOAT_SELECTOR = "[data-dsh-quota-watch-float]";
 var FETCH_TIMEOUT_MS = 15e3;
-var SURFACE_SIZE = 38;
-var SURFACE_MARGIN = 16;
+var FALLBACK_SIZE = { width: 38, height: 26 };
+var ZERO_INSETS2 = { left: 0, right: 0, top: 0, bottom: 0 };
 var CARD_MIN_WIDTH = 160;
 var COPY = {
   zh: {
@@ -238,16 +286,21 @@ var STYLE_TEXT = `
 `;
 var FLOAT_STYLE_TEXT = `
 :host { position: fixed; z-index: 2147483000; }
-.dqw-capsule { display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 10px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 999px; background: var(--dsw-alias-bg-base, rgba(128,128,128,.08)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(10px) saturate(1.2); backdrop-filter: blur(10px) saturate(1.2); box-shadow: 0 4px 14px rgba(0,0,0,.22); color: var(--dsw-alias-label-primary, inherit); font: inherit; font-size: 11px; line-height: 24px; cursor: pointer; user-select: none; white-space: nowrap; }
-.dqw-capsule:hover { border-color: var(--dsw-alias-border-primary, var(--dsw-alias-border-secondary, rgba(128,128,128,.35))); }
+.dqw-capsule { display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 10px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 999px; background: var(--dsw-alias-bg-base, rgba(128,128,128,.08)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(10px) saturate(1.2); backdrop-filter: blur(10px) saturate(1.2); box-shadow: 0 4px 14px rgba(0,0,0,.22); color: var(--dsw-alias-label-primary, inherit); font: inherit; font-size: 11px; line-height: 24px; cursor: grab; user-select: none; white-space: nowrap; position: relative; touch-action: none; -webkit-tap-highlight-color: transparent; -webkit-touch-callout: none; }
+.dqw-capsule::before { content: ''; position: absolute; inset: -9px; }
+.dqw-capsule:hover { border-color: var(--dsw-alias-border-primary, var(--dsw-alias-border-secondary, rgba(128,128,128,.35))); box-shadow: 0 6px 18px rgba(0,0,0,.28); }
+.dqw-capsule:active { transform: scale(.98); }
 .dqw-capsule:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary, #5b8def); outline-offset: 2px; }
 .dqw-capsule-sep { opacity: .5; }
 .dqw-capsule-glm, .dqw-capsule-copilot { font-variant-numeric: tabular-nums; font-weight: 600; }
 .dqw-capsule-glm.warn, .dqw-capsule-copilot.warn { color: var(--dsw-alias-label-warning, #d29922); }
 .dqw-capsule-glm.danger, .dqw-capsule-copilot.danger { color: var(--dsw-alias-label-danger, #c93c3c); }
 .dqw-capsule[hidden] { display: none; }
+.dqw-capsule--dragging { cursor: grabbing; -webkit-backdrop-filter: none; backdrop-filter: none; background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); will-change: transform; transition: none; }
 @media (prefers-reduced-motion: no-preference) {
   .dqw-capsule[data-alert] { animation: dqw-pulse 1.6s ease-in-out infinite; }
+  .dqw-capsule { transition: border-color .12s ease-out, box-shadow .12s ease-out; }
+  .dqw-capsule--snapping { transition: transform 150ms cubic-bezier(.2,.8,.2,1); }
 }
 @media print { :host { display: none !important; } }
 @keyframes dqw-pulse { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.06); } }
@@ -257,6 +310,7 @@ var FLOAT_STYLE_TEXT = `
 .dqw-menu-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
 .dqw-panel { position: fixed; z-index: 2147483000; min-width: 166px; max-width: min(320px, calc(100vw - 24px)); max-height: calc(100vh - 24px); overflow-y: auto; padding: 10px 12px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 10px; background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(14px) saturate(1.3); backdrop-filter: blur(14px) saturate(1.3); box-shadow: 0 8px 24px rgba(0,0,0,.25); color: var(--dsw-alias-label-primary, inherit); display: flex; flex-direction: column; gap: 8px; font: inherit; }
 @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) { .dqw-panel { background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); } }
+.dqw-panel--sheet { left:8px; right:8px; top:auto; bottom:calc(8px + env(safe-area-inset-bottom, 0px)); width:auto; max-width:none; max-height:calc(100dvh - 24px); }
 .dqw-panel[hidden] { display: none; }
 .dqw-panel *, .dqw-panel *::before, .dqw-panel *::after { box-sizing: border-box; }
 .dqw-panel-header { display: flex; align-items: center; gap: 6px; min-width: 0; }
@@ -276,7 +330,7 @@ var FLOAT_STYLE_TEXT = `
 .dqw-label { font-size: 11px; font-weight: 600; width: 52px; flex: none; }
 .dqw-label[data-action="refresh"] { cursor: pointer; border-radius: 4px; }
 .dqw-label[data-action="refresh"]:hover { opacity: .75; }
-.dqw-bar { display: block; flex: 0 0 auto; width: 120px; height: 4px; overflow: hidden; border-radius: 4px; background: var(--dsw-alias-bg-tertiary, rgba(128,128,128,.2)); }
+.dqw-bar { display: block; flex: 0 0 auto; width: 100px; height: 4px; overflow: hidden; border-radius: 4px; background: var(--dsw-alias-bg-tertiary, rgba(128,128,128,.2)); }
 .dqw-bar-fill { display: block; height: 100%; border-radius: inherit; background: var(--dsw-alias-button-primary-fill, #5b8def); }
 .dqw-bar-fill.warn { background: var(--dsw-alias-label-warning, #d29922); }
 .dqw-bar-fill.danger { background: var(--dsw-alias-label-danger, #c93c3c); }
@@ -486,19 +540,41 @@ function mountQuotaCard({
     floatHost.hidden = dataHidden;
   };
   doc.body.append(floatHost);
-  const applyFloatGeometry = () => {
+  const measureSurface = () => {
+    const rect = surface.getBoundingClientRect();
+    return rect.width > 0 ? { width: rect.width, height: rect.height } : FALLBACK_SIZE;
+  };
+  const applyDock = () => {
     const viewWidth = win.innerWidth ?? 1024;
     const viewHeight = win.innerHeight ?? 768;
-    const saved = loadFloatGeometry(win.localStorage);
-    const point = clampPoint(
-      saved ?? { x: viewWidth - SURFACE_MARGIN - SURFACE_SIZE, y: viewHeight - SURFACE_MARGIN - SURFACE_SIZE },
-      { width: viewWidth, height: viewHeight },
-      SURFACE_SIZE
-    );
-    floatHost.style.left = `${Math.round(point.x)}px`;
-    floatHost.style.top = `${Math.round(point.y)}px`;
+    const viewport = { width: viewWidth, height: viewHeight };
+    const size = measureSurface();
+    const dock = loadFloatDock(win.localStorage) ?? {
+      edge: "right",
+      offsetY: viewHeight - MARGIN - size.height
+    };
+    const insets = readInsets();
+    const top = clampPoint({ x: 0, y: dock.offsetY }, viewport, size, insets).y;
+    floatHost.style.left = `${Math.round(dockX(dock.edge, size.width, viewport, insets))}px`;
+    floatHost.style.top = `${Math.round(top)}px`;
+  };
+  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 readInsets = () => {
+    try {
+      const style2 = win.getComputedStyle(safeAreaProbe);
+      return {
+        top: parseInset(style2?.paddingTop),
+        right: parseInset(style2?.paddingRight),
+        bottom: parseInset(style2?.paddingBottom),
+        left: parseInset(style2?.paddingLeft)
+      };
+    } catch {
+      return ZERO_INSETS2;
+    }
   };
-  applyFloatGeometry();
+  applyDock();
   floatRoot.append(panel);
   const menu = doc.createElement("div");
   menu.className = "dqw-menu";
@@ -507,52 +583,145 @@ function mountQuotaCard({
   menu.hidden = true;
   floatRoot.append(menu);
   let suppressNextClick = false;
+  const scheduleFrame = (fn) => typeof win.requestAnimationFrame === "function" ? win.requestAnimationFrame.call(win, fn) : fn();
   const attachDrag = (surfaceEl) => {
     let dragging = false;
     let moved = false;
     let originX = 0;
     let originY = 0;
+    let slop = DRAG_SLOP_MOUSE;
+    let grab = { dx: 0, dy: 0 };
+    let dragSize = FALLBACK_SIZE;
+    let restX = 0;
+    let restY = 0;
+    let lastPoint = null;
+    let longPressTimer;
+    const clearLongPress = () => {
+      if (longPressTimer !== void 0) {
+        win.clearTimeout(longPressTimer);
+        longPressTimer = void 0;
+      }
+    };
+    const bindGesture = () => {
+      doc.addEventListener("pointermove", onPointerMove);
+      doc.addEventListener("pointerup", onPointerUp);
+      doc.addEventListener("pointercancel", onPointerCancel);
+    };
+    const unbindGesture = () => {
+      doc.removeEventListener("pointermove", onPointerMove);
+      doc.removeEventListener("pointerup", onPointerUp);
+      doc.removeEventListener("pointercancel", onPointerCancel);
+    };
     const onPointerDown = (event) => {
       if (event.button !== 0) return;
       dragging = true;
       moved = false;
       originX = event.clientX;
       originY = event.clientY;
+      slop = dragSlop(event.pointerType);
+      clearLongPress();
+      if (slop === DRAG_SLOP_TOUCH) {
+        longPressTimer = win.setTimeout(() => {
+          longPressTimer = void 0;
+          if (!dragging || moved) return;
+          try {
+            win.navigator.vibrate?.(10);
+          } catch {
+          }
+          openMenu();
+          suppressNextClick = true;
+        }, LONG_PRESS_MS);
+      }
+      const rect = surfaceEl.getBoundingClientRect();
+      grab = grabOffset({ x: event.clientX, y: event.clientY }, rect);
+      dragSize = rect.width > 0 ? { width: rect.width, height: rect.height } : FALLBACK_SIZE;
+      restX = Number.parseFloat(floatHost.style.left) || 0;
+      restY = Number.parseFloat(floatHost.style.top) || 0;
       surfaceEl.setPointerCapture?.(event.pointerId);
+      bindGesture();
     };
     const onPointerMove = (event) => {
       if (!dragging) return;
-      if (!moved && Math.hypot(event.clientX - originX, event.clientY - originY) < 6) return;
-      moved = true;
-      doc.body.style.userSelect = "none";
-      floatHost.style.left = `${Math.round(event.clientX)}px`;
-      floatHost.style.top = `${Math.round(event.clientY)}px`;
+      if (!moved) {
+        if (Math.hypot(event.clientX - originX, event.clientY - originY) < slop) return;
+        moved = true;
+        clearLongPress();
+        doc.body.style.userSelect = "none";
+        surfaceEl.classList.add("dqw-capsule--dragging");
+      }
+      lastPoint = { x: event.clientX, y: event.clientY };
+      scheduleFrame(() => {
+        if (!dragging || !lastPoint || disposed) return;
+        const viewWidth = win.innerWidth ?? 1024;
+        const viewHeight = win.innerHeight ?? 768;
+        const topLeft = clampFrame(lastPoint, grab, dragSize, { width: viewWidth, height: viewHeight }, ZERO_INSETS2);
+        const dx = topLeft.x - restX;
+        const dy = topLeft.y - restY;
+        surfaceEl.style.transform = `translate3d(${Math.round(dx)}px, ${Math.round(dy)}px, 0) scale(1.03)`;
+      });
+    };
+    const finishDragRelease = (dock) => {
+      surfaceEl.classList.remove("dqw-capsule--dragging", "dqw-capsule--snapping");
+      surfaceEl.style.transform = "";
+      saveFloatDock(win.localStorage, dock);
+      applyDock();
+      suppressNextClick = true;
     };
     const onPointerUp = (event) => {
       if (!dragging) return;
       dragging = false;
+      clearLongPress();
+      unbindGesture();
       doc.body.style.userSelect = "";
       if (!moved) return;
       const viewWidth = win.innerWidth ?? 1024;
       const viewHeight = win.innerHeight ?? 768;
-      const point = clampPoint(
+      const insets = readInsets();
+      const viewport = { width: viewWidth, height: viewHeight };
+      const dock = releaseDock(
         { x: event.clientX, y: event.clientY },
-        { width: viewWidth, height: viewHeight },
-        SURFACE_SIZE
+        grab,
+        dragSize,
+        viewport,
+        insets
       );
-      floatHost.style.left = `${Math.round(point.x)}px`;
-      floatHost.style.top = `${Math.round(point.y)}px`;
-      saveFloatGeometry(win.localStorage, point);
       suppressNextClick = true;
+      const motionAllowed = typeof win.matchMedia === "function" && win.matchMedia("(prefers-reduced-motion: no-preference)").matches;
+      if (motionAllowed) {
+        surfaceEl.classList.remove("dqw-capsule--dragging");
+        surfaceEl.classList.add("dqw-capsule--snapping");
+        const targetLeft = dockX(dock.edge, dragSize.width, viewport, insets);
+        surfaceEl.style.transform = `translate3d(${Math.round(targetLeft - restX)}px, ${Math.round(dock.offsetY - restY)}px, 0) scale(1)`;
+        let settled = false;
+        let snapTimer;
+        const settle = () => {
+          if (settled || disposed) return;
+          settled = true;
+          surfaceEl.removeEventListener("transitionend", settle);
+          win.clearTimeout(snapTimer);
+          finishDragRelease(dock);
+        };
+        surfaceEl.addEventListener("transitionend", settle);
+        snapTimer = win.setTimeout(settle, 200);
+      } else {
+        finishDragRelease(dock);
+      }
+    };
+    const onPointerCancel = () => {
+      if (!dragging) return;
+      dragging = false;
+      clearLongPress();
+      unbindGesture();
+      doc.body.style.userSelect = "";
+      surfaceEl.classList.remove("dqw-capsule--dragging", "dqw-capsule--snapping");
+      surfaceEl.style.transform = "";
     };
     surfaceEl.addEventListener("pointerdown", onPointerDown);
-    doc.addEventListener("pointermove", onPointerMove);
-    doc.addEventListener("pointerup", onPointerUp);
-    return () => {
+    const disposeDrag2 = () => {
       surfaceEl.removeEventListener("pointerdown", onPointerDown);
-      doc.removeEventListener("pointermove", onPointerMove);
-      doc.removeEventListener("pointerup", onPointerUp);
+      unbindGesture();
     };
+    return disposeDrag2;
   };
   let snapshot;
   let requestSequence = 0;
@@ -763,6 +932,13 @@ function mountQuotaCard({
     if (panel.hidden) return;
     const anchor = lastAnchor?.();
     if (!anchor || !anchor.isConnected) return;
+    if ((win.innerWidth ?? 1024) <= 480) {
+      panel.classList.add("dqw-panel--sheet");
+      panel.style.left = "";
+      panel.style.top = "";
+      return;
+    }
+    panel.classList.remove("dqw-panel--sheet");
     const rect = anchor.getBoundingClientRect();
     const viewWidth = win.innerWidth ?? 1024;
     const viewHeight = win.innerHeight ?? 768;
@@ -840,6 +1016,7 @@ function mountQuotaCard({
     const label = summary === "" ? copy.title : locale === "zh" ? `${copy.title}\uFF1A${summary}` : `${copy.title}: ${summary}`;
     surface.setAttribute("aria-label", label);
     surface.title = label;
+    applyDock();
   };
   const onSurfaceClick = () => {
     if (suppressNextClick) {
@@ -880,6 +1057,7 @@ function mountQuotaCard({
   };
   const onSurfaceContext = (event) => {
     event.preventDefault();
+    if (!menu.hidden) return;
     openMenu();
   };
   const onMenuClick = (event) => {
@@ -1046,21 +1224,19 @@ function mountQuotaCard({
     openKey = void 0;
     renderAll();
   };
+  let scrollFrameQueued = false;
   const onDocScroll = () => {
-    placePanel();
+    if (scrollFrameQueued || disposed) return;
+    scrollFrameQueued = true;
+    scheduleFrame(() => {
+      scrollFrameQueued = false;
+      if (!disposed) placePanel();
+    });
   };
   const onWinResize = () => {
     placePanel();
     syncCardVisibility();
-    const viewWidth = win.innerWidth ?? 1024;
-    const viewHeight = win.innerHeight ?? 768;
-    const x = parseFloat(floatHost.style.left);
-    const y = parseFloat(floatHost.style.top);
-    if (Number.isFinite(x) && Number.isFinite(y)) {
-      const point = clampPoint({ x, y }, { width: viewWidth, height: viewHeight }, SURFACE_SIZE);
-      floatHost.style.left = `${Math.round(point.x)}px`;
-      floatHost.style.top = `${Math.round(point.y)}px`;
-    }
+    applyDock();
   };
   const onDocKeydown = (event) => {
     if (event.key !== "Escape") return;
@@ -1112,6 +1288,7 @@ function mountQuotaCard({
     surface.removeEventListener("contextmenu", onSurfaceContext);
     menu.removeEventListener("click", onMenuClick);
     disposeDrag();
+    doc.body.style.userSelect = "";
     container.remove();
     panel.remove();
     floatHost.remove();

package/package.json

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

package/src/client/drag.mjs

@@ -0,0 +1,49 @@
+// DOM-free drag state machine for @iasiv5/dsh-quota-watch (ADR 0002).
+// Point/rect values come from the caller; nothing here touches the DOM, so the
+// math stays unit-testable under jsdom.
+
+import { MARGIN, clampPoint } from './prefs.mjs'
+
+export const DRAG_SLOP_MOUSE = 6
+export const DRAG_SLOP_TOUCH = 10
+export const LONG_PRESS_MS = 500
+
+/** Touch/pen gestures get the larger slop so taps win over drags. */
+export function dragSlop(pointerType) {
+  return pointerType === 'touch' || pointerType === 'pen' ? DRAG_SLOP_TOUCH : DRAG_SLOP_MOUSE
+}
+
+/** Offset between the pointer and the pill's top-left at grab time. */
+export function grabOffset(point, rect) {
+  return { dx: point.x - rect.left, dy: point.y - rect.top }
+}
+
+function pillTopLeft(point, grab) {
+  return { x: point.x - grab.dx, y: point.y - grab.dy }
+}
+
+/** Live clamp for the pill top-left while the gesture is active. */
+export function clampFrame(point, grab, size, viewport, insets) {
+  return clampPoint(pillTopLeft(point, grab), viewport, size, insets)
+}
+
+/** Rest dock for a release: nearest horizontal edge by pill center, vertical offset clamped. */
+export function releaseDock(point, grab, size, viewport, insets) {
+  const topLeft = pillTopLeft(point, grab)
+  const centerX = topLeft.x + size.width / 2
+  const edge = centerX < viewport.width / 2 ? 'left' : 'right'
+  return { edge, offsetY: clampPoint(topLeft, viewport, size, insets).y }
+}
+
+/** Resting x for a docked pill: always derived, never stored. */
+export function dockX(edge, width, viewport, insets) {
+  const insetLeft = Number.isFinite(insets?.left) ? insets.left : 0
+  const insetRight = Number.isFinite(insets?.right) ? insets.right : 0
+  return edge === 'left' ? MARGIN + insetLeft : viewport.width - insetRight - MARGIN - width
+}
+
+/** Computed-style padding value ("20px" | "" | "auto") → numeric inset or 0. */
+export function parseInset(computedValue) {
+  const value = Number.parseFloat(computedValue)
+  return Number.isFinite(value) ? value : 0
+}

package/src/client/prefs.mjs

@@ -1,46 +1,70 @@
 // Float-shell preferences for @iasiv5/dsh-quota-watch.
 // Pure logic: no DOM. `storage` is a localStorage-like object (getItem/setItem).
 
-export const FLOAT_GEOMETRY_KEY = 'dsh-quota-watch:float-geometry'
+export const FLOAT_DOCK_KEY = 'dsh-quota-watch:float-dock'
 export const SURFACE_FLAGS_KEY = 'dsh-quota-watch:surface-flags'
 
-const MARGIN = 8
+export const MARGIN = 8
 
-export function clampPoint(point, viewport, size = 0) {
-  const minX = MARGIN
-  const minY = MARGIN
-  const maxX = Math.max(MARGIN, viewport.width - MARGIN - size)
-  const maxY = Math.max(MARGIN, viewport.height - MARGIN - size)
+const ZERO_INSETS = { left: 0, right: 0, top: 0, bottom: 0 }
+
+function normalizeSize(size) {
+  if (typeof size === 'number') return { width: size, height: size }
+  const width = typeof size?.width === 'number' ? size.width : 0
+  const height = typeof size?.height === 'number' ? size.height : 0
+  return { width, height }
+}
+
+export function clampPoint(point, viewport, size = 0, insets = ZERO_INSETS) {
+  const { width, height } = normalizeSize(size)
+  const insetLeft = Number.isFinite(insets?.left) ? insets.left : 0
+  const insetRight = Number.isFinite(insets?.right) ? insets.right : 0
+  const insetTop = Number.isFinite(insets?.top) ? insets.top : 0
+  const insetBottom = Number.isFinite(insets?.bottom) ? insets.bottom : 0
+  const minX = MARGIN + insetLeft
+  const minY = MARGIN + insetTop
+  const maxX = Math.max(minX, viewport.width - insetRight - MARGIN - width)
+  const maxY = Math.max(minY, viewport.height - insetBottom - MARGIN - height)
   return {
     x: Math.min(Math.max(point.x, minX), maxX),
     y: Math.min(Math.max(point.y, minY), maxY),
   }
 }
 
-export function loadFloatGeometry(storage) {
+const DOCK_EDGES = new Set(['left', 'right'])
+
+export function loadFloatDock(storage) {
   try {
-    const raw = storage.getItem(FLOAT_GEOMETRY_KEY)
+    const raw = storage.getItem(FLOAT_DOCK_KEY)
     if (typeof raw !== 'string' || raw === '') return null
     const parsed = JSON.parse(raw)
     if (
       typeof parsed !== 'object' ||
       parsed === null ||
-      !Number.isFinite(parsed.x) ||
-      !Number.isFinite(parsed.y)
+      !DOCK_EDGES.has(parsed.edge) ||
+      !Number.isFinite(parsed.offsetY)
     ) {
       return null
     }
-    return { x: parsed.x, y: parsed.y }
+    return { edge: parsed.edge, offsetY: parsed.offsetY }
   } catch {
     return null
   }
 }
 
-export function saveFloatGeometry(storage, point) {
+export function saveFloatDock(storage, dock) {
+  if (
+    typeof dock !== 'object' ||
+    dock === null ||
+    !DOCK_EDGES.has(dock.edge) ||
+    !Number.isFinite(dock.offsetY)
+  ) {
+    throw new TypeError(`invalid float dock: ${JSON.stringify(dock)}`)
+  }
   try {
-    storage.setItem(FLOAT_GEOMETRY_KEY, JSON.stringify({ x: point.x, y: point.y }))
+    storage.setItem(FLOAT_DOCK_KEY, JSON.stringify({ edge: dock.edge, offsetY: dock.offsetY }))
   } catch {
-    /* storage unavailable; geometry stays session-only */
+    /* storage unavailable; dock stays session-only */
   }
 }
 

package/src/client.mjs

@@ -1,6 +1,7 @@
 import { CLIENT_POLL_INTERVAL_MS, CLIENT_ROUTES } from './shared.mjs'
 import { remainingToUsed } from './core/adapters.mjs'
-import { clampPoint, loadFloatGeometry, loadSurfaceFlags, saveFloatGeometry, saveSurfaceFlags } from './client/prefs.mjs'
+import { MARGIN, clampPoint, loadFloatDock, loadSurfaceFlags, saveFloatDock, saveSurfaceFlags } from './client/prefs.mjs'
+import { DRAG_SLOP_MOUSE, DRAG_SLOP_TOUCH, LONG_PRESS_MS, parseInset, clampFrame, dockX, dragSlop, grabOffset, releaseDock } from './client/drag.mjs'
 
 export const name = 'quota-watch-client'
 export const inject = []
@@ -8,8 +9,10 @@ export const inject = []
 const CARD_SELECTOR = '[data-dsh-quota-watch-card]'
 const FLOAT_SELECTOR = '[data-dsh-quota-watch-float]'
 const FETCH_TIMEOUT_MS = 15_000
-const SURFACE_SIZE = 38
-const SURFACE_MARGIN = 16
+// Measured-size fallback for environments where getBoundingClientRect reports
+// zeros (jsdom) or the capsule has not painted yet.
+const FALLBACK_SIZE = { width: 38, height: 26 }
+const ZERO_INSETS = { left: 0, right: 0, top: 0, bottom: 0 }
 // Below this a mounted card would clip into unreadable text (collapsed web
 // rails, squeezed desktop layouts) — hide it and let the capsule carry the
 // entry. clientWidth 0 (no layout yet, jsdom) counts as "unknown", not narrow.
@@ -117,16 +120,21 @@ const STYLE_TEXT = `
 // card shadow keeps its own copies for the sidebar rows.
 const FLOAT_STYLE_TEXT = `
 :host { position: fixed; z-index: 2147483000; }
-.dqw-capsule { display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 10px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 999px; background: var(--dsw-alias-bg-base, rgba(128,128,128,.08)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(10px) saturate(1.2); backdrop-filter: blur(10px) saturate(1.2); box-shadow: 0 4px 14px rgba(0,0,0,.22); color: var(--dsw-alias-label-primary, inherit); font: inherit; font-size: 11px; line-height: 24px; cursor: pointer; user-select: none; white-space: nowrap; }
-.dqw-capsule:hover { border-color: var(--dsw-alias-border-primary, var(--dsw-alias-border-secondary, rgba(128,128,128,.35))); }
+.dqw-capsule { display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 10px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 999px; background: var(--dsw-alias-bg-base, rgba(128,128,128,.08)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(10px) saturate(1.2); backdrop-filter: blur(10px) saturate(1.2); box-shadow: 0 4px 14px rgba(0,0,0,.22); color: var(--dsw-alias-label-primary, inherit); font: inherit; font-size: 11px; line-height: 24px; cursor: grab; user-select: none; white-space: nowrap; position: relative; touch-action: none; -webkit-tap-highlight-color: transparent; -webkit-touch-callout: none; }
+.dqw-capsule::before { content: ''; position: absolute; inset: -9px; }
+.dqw-capsule:hover { border-color: var(--dsw-alias-border-primary, var(--dsw-alias-border-secondary, rgba(128,128,128,.35))); box-shadow: 0 6px 18px rgba(0,0,0,.28); }
+.dqw-capsule:active { transform: scale(.98); }
 .dqw-capsule:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary, #5b8def); outline-offset: 2px; }
 .dqw-capsule-sep { opacity: .5; }
 .dqw-capsule-glm, .dqw-capsule-copilot { font-variant-numeric: tabular-nums; font-weight: 600; }
 .dqw-capsule-glm.warn, .dqw-capsule-copilot.warn { color: var(--dsw-alias-label-warning, #d29922); }
 .dqw-capsule-glm.danger, .dqw-capsule-copilot.danger { color: var(--dsw-alias-label-danger, #c93c3c); }
 .dqw-capsule[hidden] { display: none; }
+.dqw-capsule--dragging { cursor: grabbing; -webkit-backdrop-filter: none; backdrop-filter: none; background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); will-change: transform; transition: none; }
 @media (prefers-reduced-motion: no-preference) {
   .dqw-capsule[data-alert] { animation: dqw-pulse 1.6s ease-in-out infinite; }
+  .dqw-capsule { transition: border-color .12s ease-out, box-shadow .12s ease-out; }
+  .dqw-capsule--snapping { transition: transform 150ms cubic-bezier(.2,.8,.2,1); }
 }
 @media print { :host { display: none !important; } }
 @keyframes dqw-pulse { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.06); } }
@@ -136,6 +144,7 @@ const FLOAT_STYLE_TEXT = `
 .dqw-menu-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
 .dqw-panel { position: fixed; z-index: 2147483000; min-width: 166px; max-width: min(320px, calc(100vw - 24px)); max-height: calc(100vh - 24px); overflow-y: auto; padding: 10px 12px; border: 1px solid var(--dsw-alias-border-secondary, rgba(128,128,128,.35)); border-radius: 10px; background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); background: color-mix(in srgb, var(--dsw-alias-bg-base, #1f1f1f) 86%, transparent); -webkit-backdrop-filter: blur(14px) saturate(1.3); backdrop-filter: blur(14px) saturate(1.3); box-shadow: 0 8px 24px rgba(0,0,0,.25); color: var(--dsw-alias-label-primary, inherit); display: flex; flex-direction: column; gap: 8px; font: inherit; }
 @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) { .dqw-panel { background: var(--dsw-alias-bg-elevated, var(--dsw-alias-bg-base, #1f1f1f)); } }
+.dqw-panel--sheet { left:8px; right:8px; top:auto; bottom:calc(8px + env(safe-area-inset-bottom, 0px)); width:auto; max-width:none; max-height:calc(100dvh - 24px); }
 .dqw-panel[hidden] { display: none; }
 .dqw-panel *, .dqw-panel *::before, .dqw-panel *::after { box-sizing: border-box; }
 .dqw-panel-header { display: flex; align-items: center; gap: 6px; min-width: 0; }
@@ -155,7 +164,7 @@ const FLOAT_STYLE_TEXT = `
 .dqw-label { font-size: 11px; font-weight: 600; width: 52px; flex: none; }
 .dqw-label[data-action="refresh"] { cursor: pointer; border-radius: 4px; }
 .dqw-label[data-action="refresh"]:hover { opacity: .75; }
-.dqw-bar { display: block; flex: 0 0 auto; width: 120px; height: 4px; overflow: hidden; border-radius: 4px; background: var(--dsw-alias-bg-tertiary, rgba(128,128,128,.2)); }
+.dqw-bar { display: block; flex: 0 0 auto; width: 100px; height: 4px; overflow: hidden; border-radius: 4px; background: var(--dsw-alias-bg-tertiary, rgba(128,128,128,.2)); }
 .dqw-bar-fill { display: block; height: 100%; border-radius: inherit; background: var(--dsw-alias-button-primary-fill, #5b8def); }
 .dqw-bar-fill.warn { background: var(--dsw-alias-label-warning, #d29922); }
 .dqw-bar-fill.danger { background: var(--dsw-alias-label-danger, #c93c3c); }
@@ -428,22 +437,50 @@ export function mountQuotaCard({
   // fallbacks (broke the light theme). <body> is also transform-free, so
   // position:fixed stays viewport-anchored.
   doc.body.append(floatHost)
-  const applyFloatGeometry = () => {
+  /** Measured capsule size; zeros (jsdom / unpainted) fall back to the box. */
+  const measureSurface = () => {
+    const rect = surface.getBoundingClientRect()
+    return rect.width > 0 ? { width: rect.width, height: rect.height } : FALLBACK_SIZE
+  }
+  /** Rest position = docked edge + persisted offsetY; x is always derived (ADR 0002). */
+  const applyDock = () => {
     const viewWidth = win.innerWidth ?? 1024
     const viewHeight = win.innerHeight ?? 768
-    const saved = loadFloatGeometry(win.localStorage)
-    const point = clampPoint(
-      saved ?? { x: viewWidth - SURFACE_MARGIN - SURFACE_SIZE, y: viewHeight - SURFACE_MARGIN - SURFACE_SIZE },
-      { width: viewWidth, height: viewHeight },
-      SURFACE_SIZE,
-    )
-    floatHost.style.left = `${Math.round(point.x)}px`
-    floatHost.style.top = `${Math.round(point.y)}px`
+    const viewport = { width: viewWidth, height: viewHeight }
+    const size = measureSurface()
+    const dock = loadFloatDock(win.localStorage) ?? {
+      edge: 'right',
+      offsetY: viewHeight - MARGIN - size.height,
+    }
     // Deliberately NOT persisted here: a window that starts small (Electron
-    // restore, split-screen) must not clobber the user's preferred coordinates.
-    // The visual clamp above applies every mount; storage updates on drag only.
+    // restore, split-screen) must not clobber the user's stored dock — storage
+    // updates on drag release only; this is the visual clamp.
+    const insets = readInsets()
+    const top = clampPoint({ x: 0, y: dock.offsetY }, viewport, size, insets).y
+    floatHost.style.left = `${Math.round(dockX(dock.edge, size.width, viewport, insets))}px`
+    floatHost.style.top = `${Math.round(top)}px`
+  }
+  // Safe-area probe: env() insets ride computed padding; jsdom reports '' which
+  // parseInset normalizes to 0, so tests without a stub see zero insets.
+  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)
+  /** Live env(safe-area-inset-*) reading — re-probed on every use, so window
+   * chrome changes (rotation, URL-bar collapse) need no explicit invalidation. */
+  const readInsets = () => {
+    try {
+      const style = win.getComputedStyle(safeAreaProbe)
+      return {
+        top: parseInset(style?.paddingTop),
+        right: parseInset(style?.paddingRight),
+        bottom: parseInset(style?.paddingBottom),
+        left: parseInset(style?.paddingLeft),
+      }
+    } catch {
+      return ZERO_INSETS
+    }
   }
-  applyFloatGeometry()
+  applyDock()
   // Panel lives inside the float shadow root from now on (契约总表「归属时序」).
   floatRoot.append(panel)
   const menu = doc.createElement('div')
@@ -454,55 +491,168 @@ export function mountQuotaCard({
   floatRoot.append(menu)
 
   let suppressNextClick = false
-  /** Whole-surface drag: 6px threshold, top-left follows the pointer, clamp + persist on release.
-   * Move/up listen on `document` — pointer events always bubble there, in browsers and jsdom alike.
-   * Returns a dispose function. */
+  /** One rAF (or a synchronous fallback when the host has none) — drag frames
+   * and scroll re-placement share this gate so a burst of events costs one
+   * layout read/write per frame. */
+  const scheduleFrame = (fn) => (
+    typeof win.requestAnimationFrame === 'function' ? win.requestAnimationFrame.call(win, fn) : fn()
+  )
+  /** Grab-offset + transform drag (ADR 0002): the pill keeps its grab point
+   * under the cursor, moves via transform during the gesture (rAF-batched,
+   * live-clamped to the measured size), and the dock is persisted on release —
+   * optionally through a short snap transition when motion is allowed.
+   * Move/up listen on `document` — pointer events always bubble there, in
+   * browsers and jsdom alike. Returns a dispose function. */
   const attachDrag = (surfaceEl) => {
     let dragging = false
     let moved = false
     let originX = 0
     let originY = 0
+    let slop = DRAG_SLOP_MOUSE
+    let grab = { dx: 0, dy: 0 }
+    let dragSize = FALLBACK_SIZE
+    let restX = 0
+    let restY = 0
+    let lastPoint = null
+    let longPressTimer
+    const clearLongPress = () => {
+      if (longPressTimer !== undefined) {
+        win.clearTimeout(longPressTimer)
+        longPressTimer = undefined
+      }
+    }
+    /** Doc-level move/up/cancel are bound only while a gesture is active —
+     * the pill's resting state costs zero document-level listeners. */
+    const bindGesture = () => {
+      doc.addEventListener('pointermove', onPointerMove)
+      doc.addEventListener('pointerup', onPointerUp)
+      doc.addEventListener('pointercancel', onPointerCancel)
+    }
+    const unbindGesture = () => {
+      doc.removeEventListener('pointermove', onPointerMove)
+      doc.removeEventListener('pointerup', onPointerUp)
+      doc.removeEventListener('pointercancel', onPointerCancel)
+    }
     const onPointerDown = (event) => {
       if (event.button !== 0) return
       dragging = true
       moved = false
       originX = event.clientX
       originY = event.clientY
+      // Graded slop: touch/pen get 10px so taps win over drags (Task 6).
+      slop = dragSlop(event.pointerType)
+      // Long press opens the context menu on touch (iOS has no contextmenu);
+      // movement past the slop cancels it in favor of the drag.
+      clearLongPress()
+      if (slop === DRAG_SLOP_TOUCH) {
+        longPressTimer = win.setTimeout(() => {
+          longPressTimer = undefined
+          if (!dragging || moved) return
+          try { win.navigator.vibrate?.(10) } catch { /* vibration unavailable */ }
+          openMenu()
+          suppressNextClick = true
+        }, LONG_PRESS_MS)
+      }
+      const rect = surfaceEl.getBoundingClientRect()
+      grab = grabOffset({ x: event.clientX, y: event.clientY }, rect)
+      dragSize = rect.width > 0 ? { width: rect.width, height: rect.height } : FALLBACK_SIZE
+      restX = Number.parseFloat(floatHost.style.left) || 0
+      restY = Number.parseFloat(floatHost.style.top) || 0
       surfaceEl.setPointerCapture?.(event.pointerId)
+      bindGesture()
     }
     const onPointerMove = (event) => {
       if (!dragging) return
-      if (!moved && Math.hypot(event.clientX - originX, event.clientY - originY) < 6) return
-      moved = true
-      doc.body.style.userSelect = 'none'
-      floatHost.style.left = `${Math.round(event.clientX)}px`
-      floatHost.style.top = `${Math.round(event.clientY)}px`
+      if (!moved) {
+        if (Math.hypot(event.clientX - originX, event.clientY - originY) < slop) return
+        moved = true
+        clearLongPress()
+        doc.body.style.userSelect = 'none'
+        surfaceEl.classList.add('dqw-capsule--dragging')
+      }
+      lastPoint = { x: event.clientX, y: event.clientY }
+      scheduleFrame(() => {
+        if (!dragging || !lastPoint || disposed) return
+        const viewWidth = win.innerWidth ?? 1024
+        const viewHeight = win.innerHeight ?? 768
+        const topLeft = clampFrame(lastPoint, grab, dragSize, { width: viewWidth, height: viewHeight }, ZERO_INSETS)
+        const dx = topLeft.x - restX
+        const dy = topLeft.y - restY
+        surfaceEl.style.transform = `translate3d(${Math.round(dx)}px, ${Math.round(dy)}px, 0) scale(1.03)`
+      })
+    }
+    const finishDragRelease = (dock) => {
+      surfaceEl.classList.remove('dqw-capsule--dragging', 'dqw-capsule--snapping')
+      surfaceEl.style.transform = ''
+      saveFloatDock(win.localStorage, dock)
+      applyDock()
+      suppressNextClick = true
     }
     const onPointerUp = (event) => {
       if (!dragging) return
       dragging = false
+      clearLongPress()
+      unbindGesture()
       doc.body.style.userSelect = ''
       if (!moved) return
       const viewWidth = win.innerWidth ?? 1024
       const viewHeight = win.innerHeight ?? 768
-      const point = clampPoint(
+      const insets = readInsets()
+      const viewport = { width: viewWidth, height: viewHeight }
+      const dock = releaseDock(
         { x: event.clientX, y: event.clientY },
-        { width: viewWidth, height: viewHeight },
-        SURFACE_SIZE,
+        grab,
+        dragSize,
+        viewport,
+        insets,
       )
-      floatHost.style.left = `${Math.round(point.x)}px`
-      floatHost.style.top = `${Math.round(point.y)}px`
-      saveFloatGeometry(win.localStorage, point)
+      // The real click lands within ms of pointerup — suppression is armed
+      // synchronously here, never deferred to the animation's settle (E1-2).
       suppressNextClick = true
+      // jsdom has no matchMedia: the typeof guard keeps the release working
+      // (direct commit) where the motion query cannot be asked at all.
+      const motionAllowed = typeof win.matchMedia === 'function'
+        && win.matchMedia('(prefers-reduced-motion: no-preference)').matches
+      if (motionAllowed) {
+        surfaceEl.classList.remove('dqw-capsule--dragging')
+        surfaceEl.classList.add('dqw-capsule--snapping')
+        // Animate toward the NEW dock (delta from rest) — the host still sits
+        // at the old dock until settle commits it, so (0,0) would slide the
+        // pill backwards first and then teleport (E1-1).
+        const targetLeft = dockX(dock.edge, dragSize.width, viewport, insets)
+        surfaceEl.style.transform = `translate3d(${Math.round(targetLeft - restX)}px, ${Math.round(dock.offsetY - restY)}px, 0) scale(1)`
+        let settled = false
+        let snapTimer
+        const settle = () => {
+          if (settled || disposed) return
+          settled = true
+          surfaceEl.removeEventListener('transitionend', settle)
+          win.clearTimeout(snapTimer)
+          finishDragRelease(dock)
+        }
+        surfaceEl.addEventListener('transitionend', settle)
+        snapTimer = win.setTimeout(settle, 200)
+      } else {
+        finishDragRelease(dock)
+      }
+    }
+    /** A canceled pointer (scroll takeover, incoming call, palm) resets the
+     * gesture: no dock is persisted and the trailing click stays allowed. */
+    const onPointerCancel = () => {
+      if (!dragging) return
+      dragging = false
+      clearLongPress()
+      unbindGesture()
+      doc.body.style.userSelect = ''
+      surfaceEl.classList.remove('dqw-capsule--dragging', 'dqw-capsule--snapping')
+      surfaceEl.style.transform = ''
     }
     surfaceEl.addEventListener('pointerdown', onPointerDown)
-    doc.addEventListener('pointermove', onPointerMove)
-    doc.addEventListener('pointerup', onPointerUp)
-    return () => {
+    const disposeDrag = () => {
       surfaceEl.removeEventListener('pointerdown', onPointerDown)
-      doc.removeEventListener('pointermove', onPointerMove)
-      doc.removeEventListener('pointerup', onPointerUp)
+      unbindGesture()
     }
+    return disposeDrag
   }
   let snapshot
   let requestSequence = 0
@@ -735,6 +885,16 @@ export function mountQuotaCard({
     if (panel.hidden) return
     const anchor = lastAnchor?.()
     if (!anchor || !anchor.isConnected) return
+    if ((win.innerWidth ?? 1024) <= 480) {
+      // Narrow viewport (phones): dock the panel to the bottom instead of
+      // squeezing it beside the capsule — the sheet is CSS-positioned, so the
+      // inline anchor coordinates are dropped.
+      panel.classList.add('dqw-panel--sheet')
+      panel.style.left = ''
+      panel.style.top = ''
+      return
+    }
+    panel.classList.remove('dqw-panel--sheet')
     const rect = anchor.getBoundingClientRect()
     const viewWidth = win.innerWidth ?? 1024
     const viewHeight = win.innerHeight ?? 768
@@ -817,6 +977,9 @@ export function mountQuotaCard({
     const label = summary === '' ? copy.title : locale === 'zh' ? `${copy.title}：${summary}` : `${copy.title}: ${summary}`
     surface.setAttribute('aria-label', label)
     surface.title = label
+    // Re-derive the docked x every render: the pill's width follows its text,
+    // and the stored dock only knows the edge, not the pixel (ADR 0002).
+    applyDock()
   }
 
   const onSurfaceClick = () => {
@@ -859,6 +1022,9 @@ export function mountQuotaCard({
   }
   const onSurfaceContext = (event) => {
     event.preventDefault()
+    // Android fires the native contextmenu right after the long-press timer:
+    // an already-open menu is kept as-is instead of being rebuilt.
+    if (!menu.hidden) return
     openMenu()
   }
   const onMenuClick = (event) => {
@@ -1045,21 +1211,20 @@ export function mountQuotaCard({
     openKey = undefined
     renderAll()
   }
-  const onDocScroll = () => { placePanel() }
+  let scrollFrameQueued = false
+  const onDocScroll = () => {
+    // Coalesce scroll bursts into one placement per frame (mobile inertia).
+    if (scrollFrameQueued || disposed) return
+    scrollFrameQueued = true
+    scheduleFrame(() => {
+      scrollFrameQueued = false
+      if (!disposed) placePanel()
+    })
+  }
   const onWinResize = () => {
     placePanel()
     syncCardVisibility()
-    // Keep the capsule inside a shrunk viewport; storage keeps the user's
-    // preferred coordinates — only the visual position is clamped here.
-    const viewWidth = win.innerWidth ?? 1024
-    const viewHeight = win.innerHeight ?? 768
-    const x = parseFloat(floatHost.style.left)
-    const y = parseFloat(floatHost.style.top)
-    if (Number.isFinite(x) && Number.isFinite(y)) {
-      const point = clampPoint({ x, y }, { width: viewWidth, height: viewHeight }, SURFACE_SIZE)
-      floatHost.style.left = `${Math.round(point.x)}px`
-      floatHost.style.top = `${Math.round(point.y)}px`
-    }
+    applyDock()
   }
   const onDocKeydown = (event) => {
     if (event.key !== 'Escape') return
@@ -1112,6 +1277,8 @@ export function mountQuotaCard({
     surface.removeEventListener('contextmenu', onSurfaceContext)
     menu.removeEventListener('click', onMenuClick)
     disposeDrag()
+    // A dispose landing mid-gesture must not leave the body unselectable.
+    doc.body.style.userSelect = ''
     container.remove()
     panel.remove()
     floatHost.remove()