dsh-balance-plugin 0.1.0 → 0.2.0

package/PUBLISHING.md

@@ -15,7 +15,7 @@ Step-by-step release manual for the two official distribution channels (both are
 
 ```sh
 cd ~/Documents/dsh-balance-plugin
-git remote add origin git@github.com:<you>/dsh-balance-plugin.git
+git remote add origin git@github.com:luokai-demo/dsh-plugins.git
 git push -u origin main
 ```
 

package/README.md

@@ -4,7 +4,7 @@ DeepSeek wallet balance at the sidebar foot — a [DeepSeek Harness](https://git
 
 English | [中文](README.zh.md)
 
-Shows your DeepSeek account balance as a **card icon + amount** in the sidebar footer (beside Settings), tinted by how much is left. Refreshes when a conversation turn ends, on click, and on mount — no polling.
+Shows your DeepSeek account balance as a **card icon + amount** in the sidebar footer (beside Settings), tinted by how much is left. Refreshes when a conversation turn ends, on click, and on mount — no polling. When the amount changes, a signed delta (`+¥3.14` / `-¥1.97`) floats up and fades next to it — every spend (or top-up) is visible at a glance.
 
 ![screenshot placeholder: sidebar foot showing `💳 ¥12.34` in green](docs/screenshot.png)
 
@@ -16,6 +16,7 @@ Shows your DeepSeek account balance as a **card icon + amount** in the sidebar f
   - zero or below: red
 - **Refresh on turn end**: the host pushes an SSE `refresh` event when any conversation turn ends — wallet spend settles with the turn.
 - **Click to refresh**; in-flight refreshes are deduped (a click or turn-end tick during a pending query is a no-op).
+- **Float delta**: on a visible amount change, a signed delta floats up and fades out — green when the balance rises, red when it falls. Zero or sub-cent changes are silent, the first load never floats, and the animation is suppressed under `prefers-reduced-motion`.
 - **Silent failure**: unconfigured credentials or a failed fetch render nothing — the readout is advisory and never surfaces an error.
 - **Original currencies**: balances are displayed as the provider reports them; no conversion, no summing.
 
@@ -29,20 +30,15 @@ Requires a DeepSeek account credential. The plugin resolves `DEEPSEEK_API_KEY` t
 dsh plugin --profile <name> add dsh-balance-plugin
 ```
 
-### From GitHub
+### From the GitHub Release (no npm account needed)
 
-```sh
-dsh plugin --profile <name> add github:<you>/dsh-balance-plugin#<commit-sha>
-```
-
-Git installs fetch source, so pnpm ≥ 10 refuses the install-time build until you allow it. Copy the exact package key pnpm prints into the profile's `pnpm-workspace.yaml`:
+Download `dsh-balance-plugin-<version>.tgz` from the [releases page](https://github.com/luokai-demo/dsh-plugins/releases), then:
 
-```yaml
-allowBuilds:
-  dsh-balance-plugin: true
+```sh
+dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz
 ```
 
-then re-run the `add` command. Only install packages whose source you trust, and pin the commit.
+Note: the plugin lives in the `plugins/` subdirectory of the `dsh-plugins` monorepo, so `dsh plugin add github:...` cannot target it — use the tarball (or npm).
 
 ## Configuration
 

package/README.zh.md

@@ -4,7 +4,7 @@
 
 [English](README.md) | 中文
 
-在侧边栏底部（设置按钮旁）以**信用卡图标 + 金额**显示你的 DeepSeek 账户余额，并按剩余额度着色。在对话结束时、点击时与挂载时刷新——无轮询。
+在侧边栏底部（设置按钮旁）以**信用卡图标 + 金额**显示你的 DeepSeek 账户余额，并按剩余额度着色。在对话结束时、点击时与挂载时刷新——无轮询。金额变动时，带符号的差额（`+¥3.14` / `-¥1.97`）会从余额旁上飘淡出——每次花费（或充值）都一目了然。
 
 ![截图占位：侧边栏底部显示绿色的 `💳 ¥12.34`](docs/screenshot.png)
 
@@ -16,6 +16,7 @@
   - 零或以下：红色
 - **对话结束自动刷新**：宿主在任何对话轮次结束时推送 SSE `refresh` 事件——消耗随轮次结算。
 - **点击刷新**；在途刷新去重（查询进行中时点击或轮次结束触发均为 no-op）。
+- **差额上飘**：金额发生可见变动时，带符号差额上飘淡出——余额上升为绿色、下降为红色。零变动与不足一分钱的变化静默，首次加载不上飘，且尊重系统 `prefers-reduced-motion`（减弱动态效果时停用动画）。
 - **失败静默**：凭证未配置或抓取失败时不渲染任何内容——读数仅供参考，绝不显示错误。
 - **原始币种**：余额按提供方报告显示；不换算、不加总。
 
@@ -29,20 +30,15 @@
 dsh plugin --profile <名字> add dsh-balance-plugin
 ```
 
-### 从 GitHub 安装
+### 从 GitHub Release 安装（无需 npm 账号）
 
-```sh
-dsh plugin --profile <名字> add github:<你>/dsh-balance-plugin#<commit-sha>
-```
-
-Git 安装取到的是源码，pnpm ≥ 10 会拒绝安装时的构建，直到你允许：把 pnpm 打印的包键复制进 profile 的 `pnpm-workspace.yaml`：
+从 [releases 页面](https://github.com/luokai-demo/dsh-plugins/releases) 下载 `dsh-balance-plugin-<版本>.tgz`，然后：
 
-```yaml
-allowBuilds:
-  dsh-balance-plugin: true
+```sh
+dsh plugin --profile <名字> add ./dsh-balance-plugin-<版本>.tgz
 ```
 
-然后重跑 `add`。只安装你信任源码的包，并钉住 commit。
+注意：插件位于 `dsh-plugins` monorepo 的 `plugins/` 子目录，`dsh plugin add github:...` 无法指向子目录——请使用 tarball（或 npm）。
 
 ## 配置
 

package/lib/client.js

@@ -28,10 +28,31 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 var import_react = require("react");
+
+// src/float.ts
+var FLOAT_EPSILON = 5e-3;
+function shouldFloat(prev, next, epsilon = FLOAT_EPSILON) {
+  if (prev === void 0 || !Number.isFinite(next)) return false;
+  return Math.abs(next - prev) >= epsilon;
+}
+function floatDelta(prev, next) {
+  return next - prev;
+}
+function formatFloat(delta, symbol) {
+  const sign = delta >= 0 ? "+" : "-";
+  return `${sign}${symbol}${Math.abs(delta).toFixed(2)}`;
+}
+function symbolOf(display) {
+  const match = /^\D+/.exec(display);
+  return match === null ? "" : match[0];
+}
+
+// src/client.tsx
 var name = "dsh-balance-plugin";
 var inject = ["slots"];
 var BALANCE_ENDPOINT = "/dsh-balance";
 var EVENTS_ENDPOINT = "/dsh-balance/events";
+var FLOAT_LIFETIME_MS = 1300;
 function CardIcon({ size }) {
   return (0, import_react.createElement)(
     "svg",
@@ -51,6 +72,7 @@ function CardIcon({ size }) {
 }
 var styles = {
   button: {
+    position: "relative",
     flex: "none",
     display: "inline-flex",
     alignItems: "center",
@@ -74,10 +96,37 @@ var styles = {
     fontVariantNumeric: "tabular-nums",
     lineHeight: 1
   },
+  floatLayer: {
+    position: "absolute",
+    top: -16,
+    left: 0,
+    right: 0,
+    display: "flex",
+    justifyContent: "center",
+    pointerEvents: "none"
+  },
+  float: {
+    fontSize: 13,
+    fontWeight: 700,
+    fontVariantNumeric: "tabular-nums",
+    lineHeight: 1,
+    whiteSpace: "nowrap",
+    animation: "dsh-balance-float-up 1.3s ease-out forwards"
+  },
   success: { color: "var(--dsw-alias-state-success-primary, #16a34a)" },
   warning: { color: "var(--dsw-static-amber-600, #d97706)" },
   danger: { color: "var(--dsw-alias-state-error-primary, #dc2626)" }
 };
+var FLOAT_CSS = `
+@keyframes dsh-balance-float-up {
+  from { transform: translateY(0); opacity: 1; }
+  70% { opacity: 1; }
+  to { transform: translateY(-26px); opacity: 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dsh-balance-float { display: none !important; }
+}
+`;
 function toneOf(readout) {
   if (readout.total >= readout.threshold) return "success";
   if (readout.total > 0) return "warning";
@@ -86,14 +135,33 @@ function toneOf(readout) {
 function BalanceAction({ wide }) {
   const [readout, setReadout] = (0, import_react.useState)(void 0);
   const [turnEpoch, setTurnEpoch] = (0, import_react.useState)(0);
+  const [floats, setFloats] = (0, import_react.useState)([]);
   const inFlight = (0, import_react.useRef)(false);
+  const floatSeq = (0, import_react.useRef)(0);
+  const readoutRef = (0, import_react.useRef)(void 0);
+  (0, import_react.useEffect)(() => {
+    readoutRef.current = readout;
+  }, [readout]);
+  const pushFloat = (0, import_react.useCallback)((delta, symbol) => {
+    const id = ++floatSeq.current;
+    setFloats((items) => [...items, { id, text: formatFloat(delta, symbol), tone: delta > 0 ? "success" : "danger" }]);
+    setTimeout(() => {
+      setFloats((items) => items.filter((item) => item.id !== id));
+    }, FLOAT_LIFETIME_MS);
+  }, []);
   const refresh = (0, import_react.useCallback)(() => {
     if (inFlight.current) return;
     inFlight.current = true;
-    fetch(BALANCE_ENDPOINT, { cache: "no-store" }).then((response) => response.json()).then(setReadout).catch(() => setReadout(void 0)).finally(() => {
+    fetch(BALANCE_ENDPOINT, { cache: "no-store" }).then((response) => response.json()).then((next) => {
+      const prev = readoutRef.current;
+      if (prev?.status === "ok" && next.status === "ok" && shouldFloat(prev.total, next.total)) {
+        pushFloat(floatDelta(prev.total, next.total), symbolOf(next.display));
+      }
+      setReadout(next);
+    }).catch(() => setReadout(void 0)).finally(() => {
       inFlight.current = false;
     });
-  }, []);
+  }, [pushFloat]);
   (0, import_react.useEffect)(() => {
     refresh();
   }, [refresh, turnEpoch]);
@@ -119,14 +187,32 @@ function BalanceAction({ wide }) {
       onClick: refresh
     },
     (0, import_react.createElement)(CardIcon, { size: wide ? 16 : 18 }),
-    wide ? (0, import_react.createElement)("span", { style: { ...styles.amount, ...styles[tone] } }, readout.display) : null
+    wide ? (0, import_react.createElement)("span", { style: { ...styles.amount, ...styles[tone] } }, readout.display) : null,
+    floats.length > 0 ? (0, import_react.createElement)(
+      "span",
+      { style: styles.floatLayer, "aria-hidden": true },
+      floats.map((item) => (0, import_react.createElement)(
+        "span",
+        { key: item.id, className: "dsh-balance-float", style: { ...styles.float, ...styles[item.tone] } },
+        item.text
+      ))
+    ) : null
   );
 }
 function apply(ctx) {
-  ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
-    name: "sidebar.footer.action",
-    id: "balance",
-    order: 0
-  }, BalanceAction));
+  ctx.slots.inject("sidebar.footer.action", () => {
+    const styleEl = document.createElement("style");
+    styleEl.textContent = FLOAT_CSS;
+    document.head.appendChild(styleEl);
+    const disposer = ctx.slots.register({
+      name: "sidebar.footer.action",
+      id: "balance",
+      order: 0
+    }, BalanceAction);
+    return () => {
+      disposer();
+      styleEl.remove();
+    };
+  });
 }
 return module.exports; } });

package/lib/float.js

@@ -0,0 +1,24 @@
+// src/float.ts
+var FLOAT_EPSILON = 5e-3;
+function shouldFloat(prev, next, epsilon = FLOAT_EPSILON) {
+  if (prev === void 0 || !Number.isFinite(next)) return false;
+  return Math.abs(next - prev) >= epsilon;
+}
+function floatDelta(prev, next) {
+  return next - prev;
+}
+function formatFloat(delta, symbol) {
+  const sign = delta >= 0 ? "+" : "-";
+  return `${sign}${symbol}${Math.abs(delta).toFixed(2)}`;
+}
+function symbolOf(display) {
+  const match = /^\D+/.exec(display);
+  return match === null ? "" : match[0];
+}
+export {
+  FLOAT_EPSILON,
+  floatDelta,
+  formatFloat,
+  shouldFloat,
+  symbolOf
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-balance-plugin",
-  "version": "0.1.0",
-  "description": "DeepSeek wallet-balance readout at the sidebar foot: card icon + amount, status-tinted, refreshed on turn end and on click",
+  "version": "0.2.0",
+  "description": "DeepSeek wallet-balance readout at the sidebar foot: card icon + amount, status-tinted, refreshed on turn end and on click, with a floating delta animation on change",
   "type": "module",
   "main": "lib/index.js",
   "exports": {