dsh-packycode-api 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.2.5
+
+- Fixed generated-image clicks doing nothing in DSH desktop. The optional `nativeImageViewer` service is absent in the current desktop build, and its popup policy denies the previous `window.open(blob:...)` fallback. PackyCode now owns an in-app large-image overlay shared by main-chat and tool-detail results, with Escape/close, focus restoration and viewport fitting.
+- Added **Download original** immediately to the left of the overlay's Close button. It opens a save-location picker and transfers the preserved PNG rather than DSH's normalized chat preview. Desktop builds without File System Access use Electron's normal download/save-dialog routine without a preset destination. Cancellation does not become an error or start another download.
+- Original reads resolve native/PTC/Claude image evidence from a read-only session observation, accept no client-supplied paths and stay inside the plugin's original-image directory. The bounded chunk transfer checks the complete SHA-256 before writing; closing the viewer cancels pending reads, and missing/corrupt originals remain retryable without substituting the preview.
+- Validation, 2026-10-15: 411 offline tests, both bundles and the tarball; real-browser verification of the built client confirmed large-image opening, uncropped fitting, Download original left of Close, Escape and focus restoration. Save-picker invocation, cancellation, exact original-byte writes and interrupted/corrupt transfers are covered by automated regressions. Native save-dialog interaction remains a manual DSH check because the current computer-use interface cannot control the Codex app's native chooser. No paid image request or DSH restart was performed.
+
+## 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.5`.
 
 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.5`. 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.
 
@@ -156,6 +156,8 @@ Tool callers can set `model` and `quality` to `settings` to follow the saved pre
 
 Image 2 accepts `auto / low / medium / high`; both 2.5 models also accept `xhigh / max`. These are Images API `quality` values, separate from text reasoning effort. There is no automatic model substitution, quality downgrade or paid retry. Each call returns one PNG; original bytes are saved under `~/.dsh/packycode-api/images/` (following `DSH_HOME` when set), alongside the chat preview. References and optional PNG masks must belong to the current session; file paths cannot replace attachment references.
 
+Click a generated image to open the in-app large preview. **Download original**, immediately left of Close, opens a save-location picker for the complete preserved PNG. Cancelling is harmless; a moved or deleted original reports a retryable error instead of downloading the chat thumbnail. Saved conversations also support this as long as their original file is still on this host.
+
 After adding the image key, `node scripts/image-check.mjs --all --edit` checks all three engines and one edit. Use `--model <id> --edit` for generation and editing on a specific engine, adding `--quality xhigh` or `--quality max` to check a quality. This consumes image quota, saves outputs under `.artifacts/`, and prints only a masked key tail plus the gateway-reported model/quality.
 
 Live checks on 2026-10-15 passed generation and editing at `low` on all three engines. Sunburst also passed both operations at `xhigh` and `max`, with matching quality values in the responses. All 10 requests succeeded without retries and returned 1024×1024 PNGs; visual inspection confirmed the requested color edits with composition preserved. Generate/edit times were about 43/48 seconds at xhigh and 84/91 seconds at max. These are built-client gateway checks; no desktop conversation was created to verify the full chat flow in this run. See the [protocol research and gateway results](docs/research/image-api.md) for scope and evidence.

package/README.md

@@ -51,7 +51,7 @@
 dsh-packycode-api
 ```
 
-在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.3`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.5`。
 
 首次安装后**无需重启 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.5`。不要对 `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 自带的包，插件看起来像没装，见「常见问题」。已经那样装过的话，先卸载再按上面的方式重装。
 
@@ -156,6 +156,8 @@ Claude Code CLI → 本机临时 MCP web_search → 插件选定的 DeepSeek/GPT
 
 `gpt-image-2` 的质量为 `auto / low / medium / high`；两款 2.5 另支持 `xhigh / max`。质量按 Images API 的 `quality` 原样发送，不作为文字推理强度；不会自动换型号、降档或重试付费请求。输出先采用 PNG，每次一张，聊天预览之外的原图保存在 `~/.dsh/packycode-api/images/`（设置了 `DSH_HOME` 时跟随该目录）。参考图与可选 PNG mask 必须来自当前会话；不能用路径替代附件引用。
 
+点击生成图可在应用内查看大图，右上角关闭按钮左侧的「下载原图」可选择保存位置，另存本机保留的完整 PNG。取消保存不会报错；若原图已被移走或删除，会提示失败，不会改为下载聊天缩略图。已有会话也可使用此功能，前提是记录对应的本机原图仍存在。
+
 用户填入图片 Key 后，可运行 `node scripts/image-check.mjs --all --edit` 验证三个型号与一次编辑；用 `--model <型号> --edit` 单独验证某个型号的生图和编辑，搭配 `--quality xhigh` 或 `--quality max` 验证质量。测试会消耗图片额度，输出写入 `.artifacts/`，日志只显示 Key 的掩码尾号，并记录网关回报的型号/质量。
 
 2026-10-15 实测：三个型号均通过 `low` 生图与编辑；Sunburst 额外通过 `xhigh`、`max` 生图与编辑，两档响应的 quality 均与请求一致。合计 10 次成功请求，无重试，全部返回 1024×1024 PNG；编辑正确改色并保留构图。xhigh 生成/编辑约 43/48 秒，max 约 84/91 秒。这是已构建图片 client 的网关验证；本轮未新建 DSH 对话验证完整聊天流程。完整范围和记录见[协议核查与网关实测](docs/research/image-api.md)。

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: "图片生成与编辑",
@@ -72,6 +74,11 @@ window.__ModuleLoader__.load({
 			imagesOpen: "打开图片",
 			imagesRetryPreview: "预览加载失败，点击重试",
 			imagesLoadingPreview: "正在加载图片…",
+			imagesViewerTitle: "图片预览",
+			imagesClosePreview: "关闭图片预览",
+			imagesDownloadOriginal: "下载原图",
+			imagesDownloadPreparing: "正在准备原图…",
+			imagesDownloadFailed: "原图保存失败。请确认本机原图仍存在，然后点击“下载原图”重试。",
 			refresh: "刷新",
 			refreshing: "刷新中…",
 			totalRemaining: "合计剩余",
@@ -215,9 +222,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",
@@ -247,6 +256,11 @@ window.__ModuleLoader__.load({
 			imagesOpen: "Open image",
 			imagesRetryPreview: "Preview failed; click to retry",
 			imagesLoadingPreview: "Loading image…",
+			imagesViewerTitle: "Image preview",
+			imagesClosePreview: "Close image preview",
+			imagesDownloadOriginal: "Download original",
+			imagesDownloadPreparing: "Preparing original…",
+			imagesDownloadFailed: "Could not save the original. Check that the original file still exists on this device, then try Download original again.",
 			refresh: "Refresh",
 			refreshing: "Refreshing…",
 			totalRemaining: "Total remaining",
@@ -409,9 +423,26 @@ 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}
+.pkc-image-backdrop{position:fixed;inset:0;z-index:1000;display:grid;place-items:center;padding:20px;background:rgba(0,0,0,.84);box-sizing:border-box}
+.pkc-image-viewer{display:flex;flex-direction:column;box-sizing:border-box;width:100%;height:100%;min-height:0;color:#f5f5f5;font:13px/1.5 var(--ds-font-family,system-ui,sans-serif)}
+.pkc-image-viewer-toolbar{display:flex;align-items:center;gap:8px;flex:0 0 auto;min-height:40px;margin-bottom:12px}
+.pkc-image-viewer-name{min-width:0;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:rgba(255,255,255,.75)}
+.pkc-image-viewer-button{display:inline-flex;align-items:center;justify-content:center;gap:7px;box-sizing:border-box;flex:none;height:36px;padding:0 12px;border:1px solid rgba(255,255,255,.18);border-radius:10px;background:rgba(255,255,255,.08);color:#f5f5f5;font:inherit;cursor:pointer;white-space:nowrap}
+.pkc-image-viewer-button:hover:not(:disabled){background:rgba(255,255,255,.18)}
+.pkc-image-viewer-button:focus-visible{outline:2px solid #a7c3ff;outline-offset:2px}
+.pkc-image-viewer-button:disabled{opacity:.55;cursor:wait}
+.pkc-image-viewer-close{width:36px;padding:0;border-color:transparent;background:transparent}
+.pkc-image-viewer-canvas{display:flex;align-items:center;justify-content:center;flex:1;min-height:0;overflow:hidden}
+.pkc-image-viewer-canvas img{display:block;width:100%;height:100%;min-width:0;min-height:0;object-fit:contain}
+.pkc-image-viewer-error{align-self:center;flex:none;margin:12px 0 0;padding:8px 12px;border-radius:8px;background:#4d2222;color:#ffd3d3;text-align:center}
 .pkc-form{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
 
 .pkc-chip{flex:none;padding:0 8px;border-radius:999px;font-size:11px;font-weight:500;line-height:18px;white-space:nowrap}
@@ -576,11 +607,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 +645,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 +685,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 +755,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 +765,357 @@ 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-image-download.js
+		/** Original PNG transfer. The chat preview is never used as the download source. */
+		const MAX_BYTES = 48 * 1024 * 1024;
+		const CHUNK_BYTES = 256 * 1024;
+		function imageDownloadName(attachment) {
+			const name = (typeof attachment?.name === "string" ? attachment.name : "packycode-generated.png").replace(/[<>:"/\\|?*\u0000-\u001f\u007f]/gu, "-").replace(/[. ]+$/u, "").trim().slice(0, 160);
+			return name === "" ? "packycode-generated.png" : name.replace(/\.(png|jpe?g|webp)$/iu, "") + ".png";
+		}
+		async function readOriginalImage(call, sessionId, attachmentId, { signal, onProgress } = {}) {
+			signal?.throwIfAborted();
+			const ref = await call("images/original", {
+				sessionId,
+				attachmentId
+			}, signal);
+			if (ref?.attachmentId !== attachmentId || ref?.mediaType !== "image/png" || !Number.isSafeInteger(ref.bytes) || ref.bytes < 24 || ref.bytes > MAX_BYTES || !/^[0-9a-f]{64}$/u.test(ref.sha256) || typeof ref.assetId !== "string") throw new Error("Original image metadata is invalid");
+			signal?.throwIfAborted();
+			const data = new Uint8Array(ref.bytes);
+			let offset = 0;
+			while (offset < data.length) {
+				signal?.throwIfAborted();
+				const chunk = await call("images/original/chunk", {
+					sessionId,
+					attachmentId,
+					assetId: ref.assetId,
+					offset
+				}, signal);
+				signal?.throwIfAborted();
+				if (chunk?.attachmentId !== attachmentId || chunk.assetId !== ref.assetId || chunk.offset !== offset || chunk.totalBytes !== ref.bytes || typeof chunk.encoded !== "string" || chunk.encoded.length === 0 || chunk.encoded.length > Math.ceil(CHUNK_BYTES / 3) * 4 || typeof chunk.done !== "boolean") throw new Error("Original image chunk is invalid");
+				const decoded = atob(chunk.encoded);
+				if (decoded.length === 0 || decoded.length > CHUNK_BYTES || offset + decoded.length > data.length) throw new Error("Original image chunk is invalid");
+				for (let index = 0; index < decoded.length; index += 1) data[offset + index] = decoded.charCodeAt(index);
+				offset += decoded.length;
+				if (chunk.done !== (offset === data.length)) throw new Error("Original image transfer is incomplete");
+				onProgress?.(Math.floor(offset / data.length * 100));
+			}
+			const digest = await crypto.subtle.digest("SHA-256", data);
+			signal?.throwIfAborted();
+			if ([...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("") !== ref.sha256) throw new Error("Original image integrity check failed");
+			return data;
+		}
+		async function saveOriginalImage(read, attachment, { signal, onProgress } = {}) {
+			const name = imageDownloadName(attachment);
+			let destination;
+			if (typeof window.showSaveFilePicker === "function") try {
+				destination = await window.showSaveFilePicker({
+					suggestedName: name,
+					excludeAcceptAllOption: true,
+					types: [{
+						description: "PNG",
+						accept: { "image/png": [".png"] }
+					}]
+				});
+			} catch (error) {
+				if (error?.name !== "NotSupportedError") throw error;
+			}
+			signal?.throwIfAborted();
+			const data = await read({
+				signal,
+				onProgress
+			});
+			signal?.throwIfAborted();
+			if (destination !== void 0) {
+				const stream = await destination.createWritable();
+				try {
+					signal?.throwIfAborted();
+					await stream.write(data);
+					signal?.throwIfAborted();
+					await stream.close();
+				} catch (error) {
+					await stream.abort().catch(() => void 0);
+					throw error;
+				}
+				return;
+			}
+			const url = URL.createObjectURL(new Blob([data], { type: "image/png" }));
+			const anchor = document.createElement("a");
+			anchor.href = url;
+			anchor.download = name;
+			document.body.append(anchor);
+			try {
+				anchor.click();
+			} finally {
+				anchor.remove();
+				window.setTimeout(() => URL.revokeObjectURL(url), 6e4);
+			}
+		}
+		//#endregion
+		//#region src/client-image-viewer.jsx
+		/** One plugin-owned overlay; independent of optional host image viewers. */
+		function createImageViewer() {
+			let image;
+			let revision = 0;
+			const listeners = /* @__PURE__ */ new Set();
+			const publish = (value) => {
+				image = value;
+				for (const listener of [...listeners]) listener();
+			};
+			return {
+				getSnapshot: () => image,
+				subscribe(listener) {
+					listeners.add(listener);
+					return () => listeners.delete(listener);
+				},
+				open: (request) => publish({
+					...request,
+					revision: ++revision
+				}),
+				close: () => publish(void 0),
+				dispose() {
+					publish(void 0);
+					listeners.clear();
+				}
+			};
+		}
+		function ImageDialog({ image, viewer, t }) {
+			const dialog = react.useRef(null);
+			const close = react.useRef(null);
+			const download = react.useRef();
+			const [busy, setBusy] = react.useState(false);
+			const [progress, setProgress] = react.useState(0);
+			const [error, setError] = react.useState(false);
+			react.useEffect(() => {
+				const overflow = document.body.style.overflow;
+				document.body.style.overflow = "hidden";
+				close.current?.focus();
+				const onKey = (event) => {
+					if (event.key === "Escape") {
+						event.preventDefault();
+						event.stopPropagation();
+						viewer.close();
+					}
+					if (event.key === "Tab") {
+						const buttons = [...dialog.current?.querySelectorAll("button:not(:disabled),[tabindex=\"0\"]") ?? []];
+						const first = buttons[0], last = buttons.at(-1);
+						if (event.shiftKey && document.activeElement === first) {
+							event.preventDefault();
+							last?.focus();
+						} else if (!event.shiftKey && document.activeElement === last) {
+							event.preventDefault();
+							first?.focus();
+						}
+					}
+				};
+				document.addEventListener("keydown", onKey, true);
+				return () => {
+					download.current?.abort();
+					document.body.style.overflow = overflow;
+					document.removeEventListener("keydown", onKey, true);
+					if (image.opener?.isConnected !== false) image.opener?.focus?.();
+				};
+			}, [image, viewer]);
+			const save = async () => {
+				if (download.current !== void 0) return;
+				const controller = new AbortController();
+				download.current = controller;
+				setBusy(true);
+				setError(false);
+				setProgress(0);
+				try {
+					await saveOriginalImage(image.readOriginal, image.attachment, {
+						signal: controller.signal,
+						onProgress: (value) => {
+							if (!controller.signal.aborted) setProgress(value);
+						}
+					});
+				} catch (failure) {
+					if (!controller.signal.aborted && failure?.name !== "AbortError") setError(true);
+				} finally {
+					if (!controller.signal.aborted) {
+						download.current = void 0;
+						setBusy(false);
+					}
+				}
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "pkc-image-backdrop",
+				onClick: (event) => {
+					if (event.target === event.currentTarget) viewer.close();
+				},
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "pkc-image-viewer",
+					role: "dialog",
+					"aria-modal": "true",
+					"aria-label": t("imagesViewerTitle"),
+					ref: dialog,
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "pkc-image-viewer-toolbar",
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "pkc-image-viewer-name",
+									children: image.attachment.name ?? t("imagesTitle")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+									type: "button",
+									className: "pkc-image-viewer-button",
+									disabled: busy,
+									onClick: save,
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+										width: "16",
+										height: "16",
+										viewBox: "0 0 24 24",
+										fill: "none",
+										stroke: "currentColor",
+										strokeWidth: "1.8",
+										"aria-hidden": "true",
+										children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M12 3v12m-5-5 5 5 5-5M4 16v5h16v-5" })
+									}), busy ? `${t("imagesDownloadPreparing")} ${progress}%` : t("imagesDownloadOriginal")]
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									ref: close,
+									type: "button",
+									className: "pkc-image-viewer-button pkc-image-viewer-close",
+									title: t("imagesClosePreview"),
+									"aria-label": t("imagesClosePreview"),
+									onClick: () => viewer.close(),
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+										width: "20",
+										height: "20",
+										viewBox: "0 0 24 24",
+										fill: "none",
+										stroke: "currentColor",
+										strokeWidth: "1.8",
+										"aria-hidden": "true",
+										children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "m6 6 12 12M18 6 6 18" })
+									})
+								})
+							]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "pkc-image-viewer-canvas",
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
+								src: image.src,
+								alt: image.attachment.name ?? t("imagesTitle")
+							})
+						}),
+						error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "pkc-image-viewer-error",
+							role: "alert",
+							children: t("imagesDownloadFailed")
+						})
+					]
+				})
+			});
+		}
+		function PackyCodeImageViewer({ viewer, t }) {
+			const image = react.useSyncExternalStore(viewer.subscribe, viewer.getSnapshot);
+			return image === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ImageDialog, {
+				image,
+				viewer,
+				t
+			}, image.revision);
+		}
+		//#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 +1194,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 +1204,7 @@ window.__ModuleLoader__.load({
 									readBalance(true);
 								},
 								children: balanceLoading ? t("refreshing") : t("refresh")
-							})]
+							})
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
@@ -1028,11 +1414,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 +1435,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 }) {
@@ -1156,26 +1552,31 @@ window.__ModuleLoader__.load({
 				}, block.toolCallId))
 			});
 		}
-		function installImagePresentation(ctx, t) {
+		function installImagePresentation(ctx, t, call) {
 			ctx.inject(["uiConversation"], (scope) => {
 				const conversation = scope.get("uiConversation");
 				if (typeof conversation?.events?.register !== "function" || typeof conversation?.imageUrl !== "function") return;
+				const viewer = createImageViewer();
+				scope.effect(() => () => viewer.dispose(), "packycode-api: image viewer");
+				scope.slots.inject("shell.overlay", () => scope.slots.register({
+					name: "shell.overlay",
+					id: "packycode-image-viewer",
+					order: 21,
+					inject: () => ({
+						viewer,
+						t
+					})
+				}, PackyCodeImageViewer));
 				const imageProps = (sessionId) => ({
 					t,
 					loadImage: (attachment) => conversation.imageUrl(sessionId, attachment),
 					openImage: (src, attachment, opener) => {
-						if (scope.get("nativeImageViewer")?.open?.({
-							items: [{
-								id: attachment.attachmentId,
-								src,
-								name: attachment.name ?? "packycode-generated.png",
-								width: attachment.width,
-								height: attachment.height
-							}],
+						viewer.open({
+							src,
+							attachment,
 							opener,
-							source: "packycode-generated"
-						}) === true) return;
-						window.open(src, "_blank", "noopener,noreferrer");
+							readOriginal: (options) => readOriginalImage(call, sessionId, attachment.attachmentId, options)
+						});
 					}
 				});
 				scope.effect(() => conversation.events.register(imageConversationNode), "packycode-api: image results in chat");
@@ -1235,7 +1636,7 @@ window.__ModuleLoader__.load({
 		* call carries an object.
 		*/
 		function channelCaller(rpc) {
-			return (endpoint, payload = {}) => rpc.call(CHANNEL, endpoint, payload).then((response) => {
+			return (endpoint, payload = {}, signal) => rpc.call(CHANNEL, endpoint, payload, signal).then((response) => {
 				if (!response?.ok) throw new Error(response?.error?.message ?? "PackyCode RPC failed");
 				return response.value;
 			});
@@ -2287,8 +2688,8 @@ window.__ModuleLoader__.load({
 			}, "packycode-api: style");
 			const connection = ctx.get("connection");
 			const t = ctx.locale.bind(NS);
-			installImagePresentation(ctx, t);
 			const call = channelCaller(connection.rpc);
+			installImagePresentation(ctx, t, call);
 			ctx.slots.inject("settings.section", () => ctx.slots.register({
 				name: "settings.section",
 				id: "packycode-api",

package/lib/index.js

@@ -1,11 +1,11 @@
-import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
-import { dirname, isAbsolute, join, posix, resolve, sep, win32 } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, resolve, sep, win32 } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { HarnessError, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, createUserMessage, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
-import { mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { credentialKey } from "@deepseek-ai/dsh-credentials";
@@ -4544,7 +4544,7 @@ const EDIT_MEDIA_TYPES = [
 	"image/webp"
 ];
 const SIGNATURE = "89504e470d0a1a0a";
-const ATTACHMENT_ID$1 = /^sha256:[0-9a-f]{64}$/u;
+const ATTACHMENT_ID$2 = /^sha256:[0-9a-f]{64}$/u;
 var ImageRequestError = class extends Error {};
 const nonempty = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
 /** Explicit absence, including zero-valued placeholders filled by some models. */
@@ -4746,13 +4746,13 @@ async function readReferences(values, attachments, messages, signal) {
 	const available = /* @__PURE__ */ new Map();
 	const visit = (content) => {
 		for (const block of content ?? []) {
-			if (block?.type === "image" && ATTACHMENT_ID$1.test(block.attachment?.attachmentId)) available.set(block.attachment.attachmentId, block.attachment);
+			if (block?.type === "image" && ATTACHMENT_ID$2.test(block.attachment?.attachmentId)) available.set(block.attachment.attachmentId, block.attachment);
 			if (block?.type === "tool-result" && Array.isArray(block.content)) visit(block.content);
 		}
 	};
 	for (const message of messages ?? []) if (Array.isArray(message?.content)) visit(message.content);
 	const ids = values.map((value) => value?.attachmentId);
-	if (ids.some((id) => typeof id !== "string" || !ATTACHMENT_ID$1.test(id) || !available.has(id))) throw new ImageRequestError("PackyCode image reference is missing from this session; use read_image and copy its complete attachment reference");
+	if (ids.some((id) => typeof id !== "string" || !ATTACHMENT_ID$2.test(id) || !available.has(id))) throw new ImageRequestError("PackyCode image reference is missing from this session; use read_image and copy its complete attachment reference");
 	if (new Set(ids).size !== ids.length) throw new ImageRequestError("PackyCode image references must not contain duplicates");
 	const images = [];
 	let total = 0;
@@ -4970,7 +4970,7 @@ const MAX_CLI_IMAGE_CALLS = 4;
 const MAX_SESSION_REFERENCES = 20;
 const PREVIEW_BYTES = 1024 * 1024;
 const PREVIEW_PIXELS = 1024 * 1024;
-const ATTACHMENT_ID = /^sha256:[0-9a-f]{64}$/u;
+const ATTACHMENT_ID$1 = /^sha256:[0-9a-f]{64}$/u;
 const FIELDS = [
 	"prompt",
 	"operation",
@@ -5050,7 +5050,7 @@ function createClaudeImageService({ sessionId, messages, client, attachments, ge
 	const visit = (content) => {
 		for (const block of content ?? []) {
 			const ref = block?.type === "image" ? block.attachment : void 0;
-			if (ATTACHMENT_ID.test(ref?.attachmentId)) {
+			if (ATTACHMENT_ID$1.test(ref?.attachmentId)) {
 				collected.delete(ref.attachmentId);
 				collected.set(ref.attachmentId, Object.fromEntries([
 					"attachmentId",
@@ -5644,6 +5644,185 @@ function createImageController({ ring, balance, readPreference, writePreference,
 	};
 }
 //#endregion
+//#region src/image-conversation.js
+/** Project this plugin's durable image results into chat without duplicating context. */
+const IMAGE_CHAT_KIND = "packycode-image-output";
+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") {
+		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,
+		content: event.data.content,
+		meta: { kind: "packycode-image" }
+	}];
+	const source = event?.data?.message?.source;
+	if (event?.type !== "assistant/message" || source?.kind !== "model" || source.provider !== "packycode" || !/^claude-/u.test(source.model ?? "")) return [];
+	return (event.data.message.content ?? []).flatMap((block, index) => block.type === "image" && block.attachment ? [{
+		type: "tool-result",
+		toolCallId: `packycode-cli-image-${event.seq}-${index}`,
+		content: [block]
+	}] : []);
+}
+const imageConversationNode = {
+	kind: IMAGE_CHAT_KIND,
+	target: "chat",
+	match(event) {
+		const images = successfulImages(event);
+		if (images.length === 0) return null;
+		const id = event.type === "assistant/message" ? `cli:${event.seq}` : event.data?.subCallId ?? event.data?.message?.source?.callId ?? images[0].toolCallId ?? `event:${event.seq}`;
+		return {
+			id: String(id),
+			role: "update"
+		};
+	},
+	start: () => ({}),
+	update: (context) => context.state ?? {},
+	buildViewNode(context) {
+		const results = context.matches.filter((match) => successfulImages(match.event).length > 0);
+		if (results.length === 0) return null;
+		const turn = (results.find((match) => match.location?.kind === "turn" || match.location?.kind === "step")?.location)?.turn;
+		const finished = turn?.end;
+		const blocks = [...new Map(results.flatMap(({ event }) => successfulImages(event).map((block) => [block.toolCallId, {
+			...block,
+			kind: "tool-result"
+		}]))).values()];
+		const answerSeq = turn?.steps?.at(-1)?.data.get("assistant-step")?.finalNode?.seq;
+		const lastImageSeq = Math.max(...results.map((match) => match.event.seq));
+		return {
+			key: context.key,
+			id: context.id,
+			kind: IMAGE_CHAT_KIND,
+			target: "chat",
+			location: { kind: "session" },
+			visibility: "visible",
+			anchorSeq: answerSeq > lastImageSeq ? answerSeq + .025 : finished === void 0 ? lastImageSeq + .025 : finished.seq - .025,
+			data: {
+				...turn === void 0 ? {} : { turn: turn.turn },
+				blocks
+			}
+		};
+	}
+};
+//#endregion
+//#region src/image-originals.js
+/** Session-authorized access to PNGs preserved before DSH normalizes previews. */
+const ORIGINAL_CHUNK_BYTES = 256 * 1024;
+const ATTACHMENT_ID = /^sha256:[0-9a-f]{64}$/u;
+const FILE_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.png$/u;
+const unavailable = () => /* @__PURE__ */ new Error("PackyCode original image is unavailable in this session");
+/** Read paths only from successful, host-recorded image events, never RPC input. */
+function originalFiles(events, attachmentId, directory) {
+	const files = [];
+	for (const event of events) {
+		if (imageConversationNode.match(event) === null) continue;
+		const content = event.type === "tool/ptc-dispatch" ? event.data.content : event.data.message.content;
+		let candidate;
+		for (const part of content) {
+			if (part.type === "text" || part.type === "thinking") for (const match of String(part.text ?? "").matchAll(/(?:^|\n)(?:Original PNG on the DSH host: |原图：)([^\r\n]+)/gu)) {
+				const path = match[1];
+				candidate = dirname(path) === directory && FILE_NAME.test(basename(path)) ? basename(path) : void 0;
+			}
+			if (part.type === "image") {
+				if (part.attachment?.attachmentId === attachmentId && candidate !== void 0) files.push(candidate);
+				candidate = void 0;
+			}
+		}
+	}
+	return files;
+}
+function createImageOriginalReader({ imageDirectory, getSessionEvents }) {
+	const directory = resolve(imageDirectory);
+	async function withFile(payload, signal, read, chunk = false) {
+		let file;
+		try {
+			signal?.throwIfAborted();
+			const allowed = chunk ? [
+				"sessionId",
+				"attachmentId",
+				"assetId",
+				"offset"
+			] : ["sessionId", "attachmentId"];
+			if (!payload || typeof payload !== "object" || Object.keys(payload).some((key) => !allowed.includes(key)) || typeof payload.sessionId !== "string" || payload.sessionId.length === 0 || payload.sessionId.length > 200 || !ATTACHMENT_ID.test(payload.attachmentId) || chunk && (!FILE_NAME.test(payload.assetId) || !Number.isSafeInteger(payload.offset) || payload.offset < 0)) throw unavailable();
+			const events = await getSessionEvents(payload.sessionId, signal);
+			if (!Array.isArray(events)) throw unavailable();
+			const candidates = originalFiles(events, payload.attachmentId, directory);
+			const name = chunk ? candidates.find((value) => value === payload.assetId) : candidates.at(-1);
+			if (name === void 0) throw unavailable();
+			const path = join(directory, name);
+			if ((await lstat(path)).isSymbolicLink()) throw unavailable();
+			file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+			const stat = await file.stat();
+			if (!stat.isFile() || stat.size < 24 || stat.size > 50331648) throw unavailable();
+			const header = Buffer.alloc(24);
+			await file.read(header, 0, header.length, 0);
+			const dimensions = pngDimensions(header);
+			const result = await read(file, name, stat, dimensions);
+			signal?.throwIfAborted();
+			const after = await file.stat();
+			if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) throw unavailable();
+			return result;
+		} catch {
+			throw unavailable();
+		} finally {
+			await file?.close().catch(() => void 0);
+		}
+	}
+	return {
+		info(payload, signal) {
+			return withFile(payload, signal, async (file, assetId, stat, dimensions) => {
+				const hash = createHash("sha256");
+				const buffer = Buffer.alloc(Math.min(ORIGINAL_CHUNK_BYTES, stat.size));
+				let offset = 0;
+				while (offset < stat.size) {
+					signal?.throwIfAborted();
+					const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, stat.size - offset), offset);
+					if (bytesRead === 0) throw unavailable();
+					hash.update(buffer.subarray(0, bytesRead));
+					offset += bytesRead;
+				}
+				return {
+					assetId,
+					attachmentId: payload.attachmentId,
+					name: `packycode-${assetId}`,
+					mediaType: "image/png",
+					bytes: stat.size,
+					...dimensions,
+					sha256: hash.digest("hex")
+				};
+			});
+		},
+		chunk(payload, signal) {
+			return withFile(payload, signal, async (file, assetId, stat) => {
+				if (payload.offset >= stat.size) throw unavailable();
+				const buffer = Buffer.alloc(Math.min(ORIGINAL_CHUNK_BYTES, stat.size - payload.offset));
+				const { bytesRead } = await file.read(buffer, 0, buffer.length, payload.offset);
+				if (bytesRead === 0) throw unavailable();
+				return {
+					assetId,
+					attachmentId: payload.attachmentId,
+					offset: payload.offset,
+					totalBytes: stat.size,
+					encoded: buffer.subarray(0, bytesRead).toString("base64"),
+					done: payload.offset + bytesRead === stat.size
+				};
+			}, true);
+		}
+	};
+}
+//#endregion
 //#region src/key-chooser.js
 /**
 * Which stored key a request runs with, and what happens when the gateway
@@ -6782,7 +6961,8 @@ function createRouteAdapter({ ring, keys, fallbackSessionId, resolveAttachments,
 * Every reply carries only what this plugin owns: key labels and state, the
 * balance and group projections the host built, host overrides, whether this
 * device has the Claude Code CLI, the plugin version, and the web search
-* preference and model visibility. Key material never crosses this boundary.
+* preference and model visibility, or bounded session-authorized original PNG
+* chunks. Key material never crosses this boundary.
 *
 * @module dsh-packycode-api/rpc
 */
@@ -6808,7 +6988,7 @@ const keyId = (payload) => String(payload?.id ?? "");
 *   web search controller (without one, its endpoints refuse).
 * @returns a handler for `connection.rpc.handle(CHANNEL, handler)`.
 */
-function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCli, pluginManager, search, modelSelection, images }) {
+function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCli, pluginManager, search, modelSelection, images, imageOriginals }) {
 	const need = (service, message) => {
 		if (service === void 0) throw new Error(message);
 		return service;
@@ -6819,6 +6999,7 @@ function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCl
 	const groupReader = () => need(groups, "PackyCode key groups are unavailable in this runtime");
 	const models = () => need(modelSelection, "PackyCode model selection is unavailable in this runtime");
 	const imageSupport = () => need(images, "PackyCode images are unavailable in this runtime");
+	const originals = () => need(imageOriginals, "PackyCode original images are unavailable in this runtime");
 	const status = async () => ({
 		...await ring.list(),
 		hosts: hosts(),
@@ -6892,6 +7073,8 @@ function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCl
 			force: payload?.force === true,
 			signal
 		}),
+		"images/original": (payload, signal) => originals().info(payload, signal),
+		"images/original/chunk": (payload, signal) => originals().chunk(payload, signal),
 		"images/update": (payload) => imageSupport().update(payload),
 		"images/keys/add": (payload) => imageSupport().mutate("add", {
 			key: payload?.key,
@@ -8105,7 +8288,26 @@ function apply(ctx, config) {
 		pluginManager: createPackyCodePluginManager(),
 		search,
 		modelSelection,
-		images
+		images,
+		imageOriginals: createImageOriginalReader({
+			imageDirectory: join(dshHome, "packycode-api", "images"),
+			getSessionEvents: async (sessionId, signal) => {
+				const query = ctx.get?.("sessionQuery");
+				if (typeof query?.observeSession === "function") {
+					const observation = await query.observeSession(sessionId, {
+						signal,
+						projectionMode: "none"
+					});
+					try {
+						return [...observation.events];
+					} finally {
+						observation[Symbol.dispose]();
+					}
+				}
+				if (typeof query?.readSession === "function") return (await query.readSession(sessionId)).events;
+				return [];
+			}
+		})
 	});
 	/**
 	* The shipped Connection getter retains its own service context, whose row

package/package.json

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