dsh-packycode-api 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.2.4
+
+- Added the current image key's remaining quota immediately after the Create image shortcut. Hovering or focusing it shows the key label, account name, remaining/used/total quota and update time. It shares the shortcut's visibility, refreshes every minute while mounted and after image-setting/key changes, and marks stale or failed reads without confusing them with zero credit. Real React lifecycle regressions cover provider switches, image availability, disabled/missing keys and late responses.
+- Removed the redundant "Separate image key" badge from the image settings header.
+- Image/account quota totals now use total remaining plus total used, as requested, rather than depending on the optional periodic `quota_limit` field. Non-resetting image keys therefore show their total even when no period cap is set. Per-key quota figures and progress bars use the same calculation. Missing balance components remain unknown, and unlimited keys retain their unlimited display.
+- Validation, 2026-10-15: 397 tests, both rebuilt bundles and the versioned tarball. Browser verification with real React and DSH 0.2.0-rc.2 composer CSS confirmed the balance sits to the right of Create image, the hover/focus details show the current key's quota, and provider switches, the image setting and the host's hidden toolbar hide both controls together. A read-only live image-key quota projection also confirmed the no-period-cap shape; no image generation was needed for these UI changes.
+
 ## 1.2.3
 
 - Fixed ordinary reference-only image edits failing with `PackyCode image mask must be a PNG smaller than 4 MB` when a model also fills the optional mask field with the same JPEG/WebP reference. Native `maskImage` and CLI `maskId` now explicitly accept `null`; the field descriptions distinguish sketch refinement from using an actual mask. Only an identical reference already resolved by the host as non-PNG is treated as a redundant non-mask. Reference bytes, edit endpoint, model and quality stay intact; real PNG masks and all distinct mask references still undergo format, size and dimension checks. Invalid mask-format errors now explain how to request editing without a mask. Added native and authenticated MCP regressions without paid calls.

package/README.en.md

@@ -51,7 +51,7 @@ Open the desktop application's **Plugins** page, click **Add plugin**, and enter
 dsh-packycode-api
 ```
 
-Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.2.3`.
+Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.2.4`.
 
 A **first install requires no DSH restart**: open **Settings → PackyCode** and add a key immediately. When updating an already loaded older version, follow the restart guidance in the **Plugin version** card.
 
@@ -70,7 +70,7 @@ Choose a model from the `PackyCode` group. `deepseek-flash`, `gpt-6.1-sol`, `gpt
 
 The **Plugins** page shows the installed state and version, and is also where you enable, disable, or uninstall.
 
-**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.2.3`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
+**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.2.4`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
 
 For a local checkout, keep the `link:` prefix: `dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`. **Do not pass a bare path or `file:`** — that install copies the whole checkout, `node_modules` included, into the profile, where it then shadows the packages the DSH installation itself provides and the plugin looks uninstalled; see the FAQ. If you already installed that way, uninstall first and reinstall as above.
 

package/README.md

@@ -51,7 +51,7 @@
 dsh-packycode-api
 ```
 
-在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.3`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.4`。
 
 首次安装后**无需重启 DSH**，可直接打开**设置 → PackyCode** 添加 Key。更新已加载的旧版时，按「插件版本」卡片的重启提示操作。
 
@@ -70,7 +70,7 @@ dsh-packycode-api
 
 桌面应用的**插件**页可以看到已安装状态与版本，也可以在那里启用、停用或卸载。
 
-**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.2.3`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
+**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.2.4`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
 
 本地开发要加 `link:` 前缀：`dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`。**不要直接写路径（或 `file:`）** —— 那样的安装会把整个仓库目录（连同 `node_modules`）复制进 profile，之后它会在 profile 内部挡住 DSH 自带的包，插件看起来像没装，见「常见问题」。已经那样装过的话，先卸载再按上面的方式重装。
 

package/lib/client.js

@@ -40,9 +40,11 @@ window.__ModuleLoader__.load({
 			intro: "填入 PackyCode（PackyAPI）的 API Key 即可使用内置模型路由。多个 Key 按顺序使用：额度用尽或失效时自动切到下一个；某个 Key 的分组用不了所选模型时，自动改用分组合适的 Key。",
 			accountsTitle: "账户与 Key",
 			imagesTitle: "图片生成与编辑",
-			imagesSeparateKey: "独立图片 Key",
 			imagesBalanceLoading: "正在读取图片 Key 余额…",
 			imagesBalanceFailed: "图片余额读取失败",
+			imagesComposerLabel: "图片剩余额度",
+			imagesBalanceKey: "当前图片 Key",
+			imagesBalanceReadAt: "更新于 {time}",
 			imagesBalanceHint: "仅汇总图片 Key 的额度，每分钟自动更新；也可手动刷新。与对话 Key 的余额分开统计。",
 			imagesIntro: "使用独立图片 Key 调用 PackyCode 图片接口。生成新图或上传图片后描述修改要求；图片模型独立于对话模型。原始 PNG 保存在本机，聊天中显示图片预览。",
 			imagesEnabled: "图片生成与编辑",
@@ -215,9 +217,11 @@ window.__ModuleLoader__.load({
 			intro: "Paste a PackyCode (PackyAPI) API key to use the built-in model route. Keys are used in order: an exhausted or rejected key hands over to the next one, and a key whose groups cannot reach the selected model is passed over for one whose groups can.",
 			accountsTitle: "Accounts and keys",
 			imagesTitle: "Image generation and editing",
-			imagesSeparateKey: "Separate image key",
 			imagesBalanceLoading: "Reading image key balances…",
 			imagesBalanceFailed: "Could not read image balances",
+			imagesComposerLabel: "Image balance",
+			imagesBalanceKey: "Current image key",
+			imagesBalanceReadAt: "Updated at {time}",
 			imagesBalanceHint: "Only image key quotas are counted here. Updates every minute, or use Refresh. Conversation key balances are separate.",
 			imagesIntro: "Use a dedicated image key with PackyCode’s Images API. Describe a new image or attach images with editing instructions. The image engine is independent of the conversation model. Original PNGs are saved locally and previews appear in chat.",
 			imagesEnabled: "Generate and edit images",
@@ -409,6 +413,11 @@ window.__ModuleLoader__.load({
 .pkc-input:disabled{opacity:.5}
 .pkc-image-choice{flex:none;width:100%;max-width:300px;cursor:pointer}
 .pkc-image-shortcut{display:inline-flex;align-items:center;gap:8px}
+.pkc-image-balance{position:relative;display:inline-flex;align-items:center}
+.pkc-image-balance-value{cursor:help;border-radius:var(--dsw-radius-xs,4px)}
+.pkc-image-balance-value:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary);outline-offset:2px}
+.pkc-image-balance-tooltip{position:absolute;bottom:calc(100% + 8px);left:0;z-index:100;box-sizing:border-box;width:max-content;max-width:min(320px,calc(100vw - 32px));padding:10px 12px;border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-md,12px);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);box-shadow:var(--dsw-shadow-lv1);font-size:12px;line-height:20px;white-space:pre-line;overflow-wrap:anywhere;visibility:hidden;opacity:0;pointer-events:none}
+.pkc-image-balance:hover>.pkc-image-balance-tooltip,.pkc-image-balance:focus-within>.pkc-image-balance-tooltip{visibility:visible;opacity:1}
 .pkc-image-result,.pkc-image-chat{display:flex;flex-direction:column;gap:10px;padding:8px 0}
 .pkc-generated-image{display:grid;place-items:center;align-self:flex-start;max-width:100%;width:320px;min-height:80px;padding:0;overflow:hidden;border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-md,12px);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-secondary);cursor:zoom-in}
 .pkc-generated-image img{display:block;max-width:100%;max-height:480px;object-fit:contain}
@@ -576,11 +585,19 @@ window.__ModuleLoader__.load({
 		* @module dsh-packycode-api/totals
 		*/
 		const amount = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+		/** Displayed key quota is remaining plus used, independent of a period cap. */
+		function quotaTotalUsd(usage) {
+			if (usage?.unlimitedQuota === true) return void 0;
+			const remaining = amount(usage?.availableUsd);
+			const used = amount(usage?.usedUsd);
+			if (remaining === void 0 || used === void 0) return void 0;
+			return amount(Number((remaining + used).toFixed(6)));
+		}
 		/**
 		* Add up the balance rows the host returned.
 		* @param rows - the `keys` array of a balance projection.
 		* @returns summed amounts plus the conditions that make a sum incomplete:
-		*   keys whose read failed, and keys with no quota limit at all.
+		*   keys whose read failed, and keys with unlimited quota.
 		*/
 		function sumBalances(rows) {
 			const total = {
@@ -606,11 +623,10 @@ window.__ModuleLoader__.load({
 				}
 				const remaining = amount(usage.availableUsd);
 				const used = amount(usage.usedUsd);
-				const limit = amount(usage.limitUsd);
 				if (remaining !== void 0) total.remainingUsd += remaining;
 				if (used !== void 0) total.usedUsd += used;
-				if (limit !== void 0) total.limitUsd += limit;
 			}
+			total.limitUsd = Number((total.remainingUsd + total.usedUsd).toFixed(6));
 			return total;
 		}
 		//#endregion
@@ -647,13 +663,14 @@ window.__ModuleLoader__.load({
 		/** The same quota presentation for conversation and image credential records. */
 		function KeyBalance({ row, t }) {
 			const usage = row?.usage;
+			const totalUsd = quotaTotalUsd(usage);
 			const figures = [
 				usage?.unlimitedQuota === true ? [t("keyRemaining"), t("keyUnlimited")] : usage?.availableUsd === void 0 ? void 0 : [t("keyRemaining"), formatUsd(usage.availableUsd)],
 				usage?.usedUsd === void 0 ? void 0 : [t("keyUsed"), formatUsd(usage.usedUsd)],
-				usage?.limitUsd === void 0 ? void 0 : [t("accountLimit"), formatUsd(usage.limitUsd)]
+				totalUsd === void 0 ? void 0 : [t("accountLimit"), formatUsd(totalUsd)]
 			].filter(Boolean);
 			const meta = [usage?.name === void 0 ? t("keyNameUnknown") : `${t("keyName")} ${usage.name}`, RESET_KEYS[usage?.resetPeriod] === void 0 ? void 0 : t(RESET_KEYS[usage.resetPeriod])].filter(Boolean).join(" · ");
-			const share = usage?.unlimitedQuota !== true && typeof usage?.limitUsd === "number" && usage.limitUsd > 0 && typeof usage.availableUsd === "number" ? Math.max(0, Math.min(1, usage.availableUsd / usage.limitUsd)) : void 0;
+			const share = usage?.unlimitedQuota !== true && totalUsd > 0 && typeof usage.availableUsd === "number" ? Math.max(0, Math.min(1, usage.availableUsd / totalUsd)) : void 0;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 					className: "pkc-meta",
@@ -716,7 +733,7 @@ window.__ModuleLoader__.load({
 							children: t("totalLimit")
 						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 							className: "pkc-stat-value",
-							children: totals.unlimited > 0 ? t("keyUnlimited") : known("limitUsd") ? formatUsd(totals.limitUsd) : "—"
+							children: totals.unlimited > 0 ? t("keyUnlimited") : known("availableUsd") && known("usedUsd") ? formatUsd(totals.limitUsd) : "—"
 						})]
 					})
 				]
@@ -726,6 +743,103 @@ window.__ModuleLoader__.load({
 			})] });
 		}
 		//#endregion
+		//#region src/client-image-balance.jsx
+		/** Mirror the host's next-usable image key using only its public balance rows. */
+		function currentImageKey(balance) {
+			const keys = balance?.keys ?? [];
+			const start = Math.max(0, keys.findIndex((row) => row.id === balance.activeId));
+			for (let offset = 0; offset < keys.length; offset += 1) {
+				const row = keys[(start + offset) % keys.length];
+				if (row.disabled !== true) return row;
+			}
+		}
+		/** Mounted inside the visible Create image shortcut, so its timer shares that lifetime. */
+		function ImageShortcutBalance({ call, t }) {
+			const [view, setView] = react.useState({ loading: true });
+			const refresh = react.useRef(() => {});
+			const tooltipId = react.useId();
+			react.useEffect(() => {
+				let live = true, generation = 0, pending = false;
+				const read = async (force = false, reset = false) => {
+					if (!live || pending && !force) return;
+					const current = ++generation;
+					pending = true;
+					setView((previous) => reset ? { loading: true } : {
+						...previous,
+						loading: true
+					});
+					try {
+						const balance = await call("images/balance", { force });
+						if (live && current === generation) setView({
+							balance,
+							loading: false
+						});
+					} catch {
+						if (live && current === generation) setView((previous) => ({
+							...previous,
+							loading: false,
+							failed: true
+						}));
+					} finally {
+						if (current === generation) pending = false;
+					}
+				};
+				refresh.current = read;
+				read();
+				const changed = () => {
+					read(true, true);
+				};
+				const timer = window.setInterval(() => {
+					read();
+				}, 6e4);
+				window.addEventListener("packycode-images-updated", changed);
+				return () => {
+					live = false;
+					generation += 1;
+					refresh.current = () => {};
+					window.clearInterval(timer);
+					window.removeEventListener("packycode-images-updated", changed);
+				};
+			}, [call]);
+			const row = currentImageKey(view.balance);
+			const usage = row?.usage;
+			const unlimited = usage?.unlimitedQuota === true;
+			const remaining = unlimited ? t("keyUnlimited") : formatUsd(usage?.availableUsd);
+			const stale = usage !== void 0 && (view.failed || row.stale !== void 0);
+			const display = remaining ?? (view.loading ? "…" : "—");
+			const details = [
+				t("imagesComposerLabel"),
+				row?.label ? `${t("imagesBalanceKey")}: ${row.label}` : void 0,
+				usage?.name ? `${t("keyName")}: ${usage.name}` : void 0,
+				`${t("keyRemaining")}: ${remaining ?? "—"}`,
+				`${t("keyUsed")}: ${formatUsd(usage?.usedUsd) ?? "—"}`,
+				`${t("accountLimit")}: ${unlimited ? t("keyUnlimited") : formatUsd(quotaTotalUsd(usage)) ?? "—"}`,
+				stale ? fill(t("composerStale"), { time: readTime(row.stale?.fetchedAt ?? view.balance?.fetchedAt) }) : view.failed || row?.error ? t("imagesBalanceFailed") : view.loading ? t("imagesBalanceLoading") : view.balance?.fetchedAt === void 0 ? void 0 : fill(t("imagesBalanceReadAt"), { time: readTime(view.balance.fetchedAt) })
+			].filter(Boolean).join("\n");
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+				className: "pkc-image-balance",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "pkc-composer pkc-image-balance-value",
+					role: "status",
+					tabIndex: 0,
+					"aria-label": `${t("imagesComposerLabel")}: ${stale ? "≈" : ""}${display}`,
+					"aria-describedby": tooltipId,
+					onMouseEnter: () => {
+						refresh.current();
+					},
+					onFocus: () => {
+						refresh.current();
+					},
+					children: stale ? `≈${display}` : display
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "pkc-image-balance-tooltip",
+					id: tooltipId,
+					role: "tooltip",
+					children: details
+				})]
+			});
+		}
+		//#endregion
 		//#region src/client-images.jsx
 		const imageModelLabel = (id) => id.replace("gpt-image-", "GPT Image ").replace("-flare", " Flare").replace("-sunburst", " Sunburst");
 		/** Only projections come back from the host; the password draft is cleared on success. */
@@ -804,13 +918,9 @@ window.__ModuleLoader__.load({
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
 							className: "pkc-title",
 							children: t("imagesTitle")
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 							className: "pkc-actions",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								className: "pkc-chip",
-								"data-tone": "neutral",
-								children: t("imagesSeparateKey")
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								className: "pkc-btn",
 								type: "button",
 								disabled: busy || balanceLoading,
@@ -818,7 +928,7 @@ window.__ModuleLoader__.load({
 									readBalance(true);
 								},
 								children: balanceLoading ? t("refreshing") : t("refresh")
-							})]
+							})
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
@@ -1028,11 +1138,14 @@ window.__ModuleLoader__.load({
 			const [error, setError] = react.useState();
 			react.useEffect(() => {
 				let live = true;
+				let generation = 0;
 				const refresh = () => {
-					if (active) call("images/status").then((value) => {
-						if (live) setReady(value.imageEnabled && value.available && value.keys.some((key) => !key.disabled));
+					if (!active) return;
+					const current = ++generation;
+					call("images/status").then((value) => {
+						if (live && current === generation) setReady(value.imageEnabled && value.available && value.keys.some((key) => !key.disabled));
 					}).catch(() => {
-						if (live) setReady(false);
+						if (live && current === generation) setReady(false);
 					});
 				};
 				setReady(false);
@@ -1046,24 +1159,31 @@ window.__ModuleLoader__.load({
 			if (!active || !ready) return null;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 				className: "pkc-image-shortcut",
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-					className: "pkc-btn",
-					type: "button",
-					title: t("imagesShortcutHint"),
-					onClick: () => {
-						try {
-							prepare(t("imagesDraft"));
-							setError(void 0);
-						} catch {
-							setError(t("imagesDraftBusy"));
-						}
-					},
-					children: t("imagesCreate")
-				}), error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-					className: "pkc-error",
-					role: "alert",
-					children: error
-				})]
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						className: "pkc-btn",
+						type: "button",
+						title: t("imagesShortcutHint"),
+						onClick: () => {
+							try {
+								prepare(t("imagesDraft"));
+								setError(void 0);
+							} catch {
+								setError(t("imagesDraftBusy"));
+							}
+						},
+						children: t("imagesCreate")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(ImageShortcutBalance, {
+						call,
+						t
+					}),
+					error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "pkc-error",
+						role: "alert",
+						children: error
+					})
+				]
 			});
 		}
 		function GeneratedImage({ attachment, loadImage, openImage, t }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-packycode-api",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Use PackyCode API keys in DeepSeek Harness with multi-protocol models, image generation and editing, separate key rings, and balance display",
   "type": "module",
   "main": "./lib/index.js",
@@ -100,6 +100,7 @@
     "packycode-host-v020-fixture": "file:tests/fixtures/host-v020",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "react-test-renderer": "18.3.1",
     "tsdown": "0.22.2",
     "yaml": "2.9.1"
   },