dsh-packycode-api 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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.
+- Fixed native image results still missing from main chat in 1.2.2. DSH persists `tool/result.data.message` as a flat `ToolMessage`: the call identity is in `source.callId`, image/text parts are directly in `content`, and failure status is on the message. The gallery incorrectly looked for nested SDK `tool-result` blocks and discarded every successful native result. It now projects the actual message into the existing gallery view and retains the plugin metadata and durable image references.
+- Replaced the incorrect native fixtures with the real message structure and added a sanitized stored-session regression that fails against the published 1.2.2 parser. Added a built-client integration through real Cordis 4.0.4, DSH 0.2.0-rc.2 event/view/group and Slot registries, bound session feed and image cache, including plugin unload/reinstall and history reload. Native, nested PTC and Claude CLI image presentation each exercise the built bundle.
+- Browser comparison of the published 1.2.2 client and the corrected client with the same native ToolMessage: the old client renders zero main-chat images while the tool detail PNG loads; the corrected client renders one image with details collapsed and after history reload, with no console errors. `scripts/image-preview-check.mjs` supports `?protocol=native` or `?protocol=ptc` for focused replay. This uses a public PNG fixture without making paid API requests or changing existing sessions; it does not replace a physical Intel Mac retest.
+- Validation, 2026-10-15: 390 offline tests, both rebuilt bundles and the 1.2.3 tarball. The built host tool also passed a real local HTTP multipart replay for null and repeated non-PNG mask arguments: both requests used `/v1/images/edits`, retained the original JPEG and saved Sunburst `max` setting, and omitted the unused mask. No paid generation, existing-session rewrite or DSH restart was performed for these fixes.
+
 ## 1.2.2
 
 - Fixed the remaining missing-gallery bug in 1.2.1. Real native `tool/result` and nested `tool/ptc-dispatch` records do not have `data.turn`; keying image contexts by that missing field separated image evidence from the actual `turn/end` context. Image contexts now use the tool call ID (or CLI message sequence) and obtain the owning turn and completion boundary from DSH's engine-provided Match Location. Results appear as soon as available and stay visible when history later supplies missing boundaries.

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.2`.
+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.2`. 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.2`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `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.2`。不要对 `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/docs/research/image-api.md

@@ -32,6 +32,8 @@ Multipart 使用 `image`（单图）或重复的 `image[]`（多图），最多
 
 官方资料存在一个明确差异：`CreateImageEditRequest.mask` 要求 **小于 4 MB**；指南的 Mask requirements 则写图与 mask 格式、尺寸一致且小于 50 MB。实现建议采用更严格的 PNG mask <4 MB，并在需要 mask 时使用相同尺寸的 PNG 输入，直到实际网关验证更宽限制；不要把指南的 50 MB 直接当作 mask 已确认上限。[OpenAPI mask schema](https://github.com/openai/openai-openapi/blob/main/openapi.json)、[指南 Mask requirements](https://developers.openai.com/api/docs/guides/image-generation#mask-requirements)
 
+2026-10-15 再核对：[官方编辑 API 参考](https://developers.openai.com/api/reference/python/resources/images/methods/edit)仍将 `mask` 列为可选 PNG、与输入同尺寸且 <4 MB。用户随后报告“完善草图”触发同样的 mask 校验，并确认仅上传原图，没有单独遮罩。当前本机没有该报错会话的调用参数；离线回放可用“JPEG/WebP 参考图又被模型重复填到 mask 字段”复现完全相同的报错，不能据此声称已取得同事设备的原始参数。工具现支持 `maskImage: null` / CLI `maskId: null` 明确表示无遮罩，并只兼容宿主已验证的同一个非 PNG 参考附件被重复填入 mask 的情况。真实 PNG mask 和不同附件的 mask 保留原有检查；没有放宽 4 MB 限制，没有把编辑换成生图，也没有新增付费重试。
+
 JSON 编辑的字段为 `images: [{ image_url: "…" }]` 或 `images: [{ file_id: "…" }]`，每项二选一；`image_url` 可为完整 URL 或 data URL。JSON 的可选 mask 同样为图片引用对象。这是官方额外能力，不能据此假定 PackyCode 也支持它。[官方 OpenAPI：EditImageBodyJsonParam / ImageRefParam](https://github.com/openai/openai-openapi/blob/main/openapi.json)
 
 `gpt-image-2` 必须省略 `input_fidelity`，其图片输入始终按高保真处理。当前通用 schema 只明确为 GPT Image 1 / 1.5 声明可调 high/low，没有明确说明 2.5 两款可调；本次集成建议三款均省略此字段，不推断 2.5 的未记载行为。[官方高保真说明](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity)、[官方 OpenAPI：InputFidelity](https://github.com/openai/openai-openapi/blob/main/openapi.json)

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}
@@ -496,10 +505,18 @@ window.__ModuleLoader__.load({
 		const IMAGE_TOOLS = /* @__PURE__ */ new Set(["packycode_image_generate", "claude_code"]);
 		const hasImage = (content) => Array.isArray(content) && content.some((part) => part.type === "image" && part.attachment);
 		function successfulImages(event) {
-			if (event?.type === "tool/result" && event.data?.meta?.kind === "packycode-image") return (event.data.message?.content ?? []).filter((block) => block.type === "tool-result" && !block.isError && hasImage(block.content)).map((block) => ({
-				...block,
-				meta: event.data.meta
-			}));
+			if (event?.type === "tool/result" && event.data?.meta?.kind === "packycode-image") {
+				const message = event.data.message;
+				const toolCallId = message?.source?.callId;
+				if (message?.source?.kind !== "tool" || typeof toolCallId !== "string" || toolCallId === "" || message.isError === true || !hasImage(message.content)) return [];
+				return [{
+					type: "tool-result",
+					toolCallId,
+					content: message.content,
+					isError: false,
+					meta: event.data.meta
+				}];
+			}
 			if (event?.type === "tool/ptc-dispatch" && IMAGE_TOOLS.has(event.data?.name) && event.data.isError === false && typeof event.data.subCallId === "string" && hasImage(event.data.content)) return [{
 				type: "tool-result",
 				toolCallId: event.data.subCallId,
@@ -568,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 = {
@@ -598,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
@@ -639,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",
@@ -708,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) : "—"
 						})]
 					})
 				]
@@ -718,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. */
@@ -796,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,
@@ -810,7 +928,7 @@ window.__ModuleLoader__.load({
 									readBalance(true);
 								},
 								children: balanceLoading ? t("refreshing") : t("refresh")
-							})]
+							})
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
@@ -1020,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);
@@ -1038,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/lib/index.js

@@ -4547,9 +4547,10 @@ const SIGNATURE = "89504e470d0a1a0a";
 const ATTACHMENT_ID$1 = /^sha256:[0-9a-f]{64}$/u;
 var ImageRequestError = class extends Error {};
 const nonempty = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
-/** Some model calls fill unused object fields with a zero-valued reference. */
+/** Explicit absence, including zero-valued placeholders filled by some models. */
 function emptyMaskReference(value) {
-	return value !== null && typeof value === "object" && (value.attachmentId === "" || value.attachmentId === `sha256:${"0".repeat(64)}`) && value.bytes === 0 && value.width === 0 && value.height === 0 && (value.name === void 0 || value.name === "") && (value.originalDimensions === void 0 || value.originalDimensions.width === 0 && value.originalDimensions.height === 0);
+	if (value === null) return true;
+	return value !== void 0 && typeof value === "object" && (value.attachmentId === "" || value.attachmentId === `sha256:${"0".repeat(64)}`) && value.bytes === 0 && value.width === 0 && value.height === 0 && (value.name === void 0 || value.name === "") && (value.originalDimensions === void 0 || value.originalDimensions.width === 0 && value.originalDimensions.height === 0);
 }
 /** A bounded reader applies to both successful payloads and error envelopes. */
 async function readJson(response, maximum, signal) {
@@ -4657,7 +4658,8 @@ function createPackyCodeImageClient({ resolveKey, getHost, fetchImpl = ambientFe
 				body.append("image[]", new Blob([image.data], { type: image.mediaType }), `reference-${index + 1}.${extension}`);
 			}
 			if (mask !== void 0) {
-				if (mask.mediaType !== "image/png" || !(mask.data instanceof Uint8Array) || mask.data.byteLength >= 4 * 1024 * 1024) throw new ImageRequestError("PackyCode image mask must be a PNG smaller than 4 MB");
+				if (mask.mediaType !== "image/png") throw new ImageRequestError("PackyCode maskImage must be a separate PNG mask, not an ordinary reference image; omit maskImage or set it to null for edits without a mask");
+				if (!(mask.data instanceof Uint8Array) || mask.data.byteLength === 0 || mask.data.byteLength >= 4 * 1024 * 1024) throw new ImageRequestError("PackyCode image mask must be a PNG smaller than 4 MB");
 				const dimensions = pngDimensions(mask.data);
 				if (dimensions.width !== images[0].width || dimensions.height !== images[0].height) throw new ImageRequestError("PackyCode image mask must match the first reference image dimensions");
 				body.append("mask", new Blob([mask.data], { type: "image/png" }), "mask.png");
@@ -4872,8 +4874,8 @@ function createPackyCodeImageTool({ client, attachments, getPreference, getSessi
 				description: "1-16 complete attachment references for editing. Omit or use [] for a new image. Paths and unrelated images are not accepted; never drop real references after an edit fails."
 			},
 			maskImage: {
-				...referenceSchema,
-				description: "Omit for new images and edits without a mask. Never invent a reference. Optional PNG mask from this session, matching the first reference and under 4 MB; alpha=0 marks the area to edit."
+				oneOf: [{ type: "null" }, referenceSchema],
+				description: "Omit or use null for new images and ordinary reference-image edits, including refining a sketch. Only supply an actual PNG mask provided for masking, matching the first reference and under 4 MB; alpha=0 marks the area to edit. Do not copy an ordinary reference into this field or invent a mask."
 			}
 		},
 		output: {
@@ -4906,7 +4908,9 @@ function createPackyCodeImageTool({ client, attachments, getPreference, getSessi
 				throw new ImageRequestError("PackyCode could not read the current session image references");
 			}
 			const images = editing ? await readReferences(args.referenceImages, attachments, messages, signal) : void 0;
-			const masks = maskImage === void 0 ? void 0 : await readReferences([maskImage], attachments, messages, signal);
+			const repeatedIndex = maskImage === void 0 ? -1 : args.referenceImages.findIndex((ref) => ref.attachmentId === maskImage.attachmentId);
+			const repeatedNonPng = repeatedIndex >= 0 && images[repeatedIndex].mediaType !== "image/png";
+			const masks = maskImage === void 0 || repeatedNonPng ? void 0 : await readReferences([maskImage], attachments, messages, signal);
 			if (!getPreference().imageEnabled) throw new ImageRequestError("PackyCode images are disabled in settings");
 			const result = await client.request({
 				...args,
@@ -5026,9 +5030,11 @@ const MCP_IMAGE_SCHEMA = Object.freeze({
 			description: "For edits use image handles from the session image catalog or a previous successful result in this run. Omit or [] for generation. Never invent handles or substitute files/URLs."
 		},
 		maskId: {
-			type: "string",
-			pattern: "^image_[1-9][0-9]*$",
-			description: "Optional session image handle for a PNG mask, matching the first reference. Omit when there is no mask."
+			oneOf: [{ type: "null" }, {
+				type: "string",
+				pattern: "^image_[1-9][0-9]*$"
+			}],
+			description: "Omit or use null for ordinary reference-image editing, including sketch refinement. Only use an actual PNG mask provided for masking, matching the first reference; never reuse an ordinary reference as a mask."
 		}
 	},
 	required: ["prompt"]
@@ -5086,7 +5092,8 @@ function createClaudeImageService({ sessionId, messages, client, attachments, ge
 		if (!Array.isArray(ids) || ids.length > 16 || new Set(ids).size !== ids.length || ids.some((id) => !references.has(id))) invalid("Use 1-16 distinct image handles from this run’s session catalog for an edit.");
 		if (value.operation === "edit" && ids.length === 0) invalid("Image edits require referenceIds; an edit will not be replaced with generation.");
 		if (value.operation === "generate" && ids.length > 0) invalid("Image generation cannot include referenceIds; use edit.");
-		if (value.maskId !== void 0 && (!references.has(value.maskId) || ids.length === 0)) invalid("A mask requires references and a valid session image handle.");
+		const maskId = value.maskId ?? void 0;
+		if (maskId !== void 0 && (!references.has(maskId) || ids.length === 0)) invalid("A mask requires references and a valid session image handle.");
 		const preference = getPreference();
 		const model = value.model === void 0 || value.model === "settings" ? preference.imageModel : value.model;
 		const quality = value.quality === void 0 || value.quality === "settings" ? preference.imageQuality : value.quality;
@@ -5099,7 +5106,7 @@ function createClaudeImageService({ sessionId, messages, client, attachments, ge
 		} catch (error) {
 			invalid(error.message);
 		}
-		const { referenceIds: _ids, maskId, ...args } = value;
+		const { referenceIds: _ids, maskId: _maskId, ...args } = value;
 		return {
 			...args,
 			model,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-packycode-api",
-  "version": "1.2.2",
+  "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"
   },