@dickpy/dsh-imagegen 1.5.3 → 1.5.5

package/lib/index.js

@@ -1,12 +1,13 @@
+import { promises, readFileSync } from "node:fs";
+import path from "node:path";
 import * as settingsModule from "@deepseek-ai/dsh-settings";
 import { SettingsConflictError } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
-import { createHash, randomUUID } from "node:crypto";
-import { promises } from "node:fs";
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { createHash, createHmac, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawn } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/settings-compat.ts
 const compatModule = settingsModule;
@@ -40,7 +41,7 @@ function installSettingsSectionCompat(ctx, ns, schema, entry, hooks) {
 /** Settings namespace this plugin owns (host settings seam + bridge). */
 const IMAGEGEN_SETTINGS_NAMESPACE = "dsh-imagegen";
 /** Published package version shared by the host updater and the client UI. */
-const PLUGIN_VERSION = "1.5.3";
+const PLUGIN_VERSION = "1.5.5";
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 const SETTINGS_API = {
 	describe: "/api/dsh-imagegen/settings/describe",
@@ -74,6 +75,10 @@ const TASK_API = {
 	cancel: "/api/dsh-imagegen/tasks/cancel",
 	retry: "/api/dsh-imagegen/tasks/retry"
 };
+/** Reveal the host data directory (saved images) in the OS file manager. */
+const DATA_FOLDER_API = "/api/dsh-imagegen/data-folder/open";
+/** Probe the configured S3-compatible object storage. */
+const STORAGE_API = { test: "/api/dsh-imagegen/storage/test" };
 /** Host-mediated GitHub Release update routes. */
 const UPDATE_API = {
 	check: "/api/dsh-imagegen/update/check",
@@ -105,6 +110,17 @@ const GALLERY_API = {
 	tags: "/api/dsh-imagegen/gallery/tags",
 	image: "/api/dsh-imagegen/gallery/image"
 };
+/** Host-persisted infinite canvas projects and their content-addressed assets. */
+const CANVAS_API = {
+	list: "/api/dsh-imagegen/canvas/list",
+	create: "/api/dsh-imagegen/canvas/create",
+	read: "/api/dsh-imagegen/canvas/read",
+	save: "/api/dsh-imagegen/canvas/save",
+	remove: "/api/dsh-imagegen/canvas/remove",
+	assetUpload: "/api/dsh-imagegen/canvas/asset/upload",
+	assetImport: "/api/dsh-imagegen/canvas/asset/import",
+	asset: "/api/dsh-imagegen/canvas/asset"
+};
 /**
 * Same-origin route family for the prompt-template libraries. The library is
 * multi-source: every request names a source id from {@link TEMPLATE_SOURCES},
@@ -572,8 +588,13 @@ function requestSignal(source, timeoutMs) {
 		}
 	};
 }
-/** Content-type extension hints for URL-fetched images. */
-function mimeOfExtension(path) {
+/** Whether an error was produced by a requestSignal budget timeout. These can
+* surface from the fetch call itself or from reading the response body, so the
+* budget must stay armed until the body has been consumed. */
+function isBudgetTimeout(error) {
+	return (error instanceof DOMException || error instanceof Error) && error.name === "TimeoutError";
+}
+/** Content-type extension hints for URL-fetched images. */ function mimeOfExtension(path) {
 	const match = /\.([a-z0-9]+)$/i.exec(path);
 	if (match === null) return void 0;
 	switch (match[1].toLowerCase()) {
@@ -667,7 +688,7 @@ function effectiveCount(request) {
 	return clampCount(request.n);
 }
 /** Normalize one upstream data item into a base64 image. */
-async function normalizeItem(item, upstream) {
+async function normalizeItem(item, upstream, signal) {
 	const revisedPrompt = typeof item.revised_prompt === "string" ? item.revised_prompt : void 0;
 	if (typeof item.b64_json === "string" && item.b64_json.trim() !== "") {
 		const b64 = bareBase64(item.b64_json);
@@ -688,27 +709,168 @@ async function normalizeItem(item, upstream) {
 			revisedPrompt
 		};
 	}
-	const budget = requestSignal(void 0, IMAGE_FETCH_TIMEOUT_MS);
-	let response;
+	const budget = requestSignal(signal, IMAGE_FETCH_TIMEOUT_MS);
 	try {
-		response = await fetch(url, {
-			...isPresignedUrl(url) || upstream.apiKey === "" ? {} : { headers: { authorization: `Bearer ${upstream.apiKey}` } },
-			signal: budget.signal
-		});
-	} catch (error) {
-		throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`);
+		let response;
+		try {
+			response = await fetch(url, {
+				...isPresignedUrl(url) || upstream.apiKey === "" ? {} : { headers: { authorization: `Bearer ${upstream.apiKey}` } },
+				signal: budget.signal
+			});
+		} catch (error) {
+			throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!response.ok) throw new ImageGenError(`failed to fetch the generated image url: HTTP ${response.status}`);
+		const buffer = Buffer.from(await response.arrayBuffer());
+		const contentType = response.headers.get("content-type");
+		const mime = detectImageMime(buffer) ?? (contentType !== null && contentType !== "" ? contentType.split(";")[0].trim() : mimeOfExtension(url) ?? "image/png");
+		return {
+			b64: buffer.toString("base64"),
+			mime,
+			revisedPrompt
+		};
 	} finally {
 		budget.dispose();
 	}
-	if (!response.ok) throw new ImageGenError(`failed to fetch the generated image url: HTTP ${response.status}`);
-	const buffer = Buffer.from(await response.arrayBuffer());
-	const contentType = response.headers.get("content-type");
-	const mime = detectImageMime(buffer) ?? (contentType !== null && contentType !== "" ? contentType.split(";")[0].trim() : mimeOfExtension(url) ?? "image/png");
-	return {
-		b64: buffer.toString("base64"),
-		mime,
-		revisedPrompt
-	};
+}
+/** Expand a provider image item whose URL may be a string or an array. */
+function imageItemsOf(value) {
+	if (value === null || typeof value !== "object") return [];
+	const item = value;
+	if (Array.isArray(item.url)) return item.url.filter((url) => typeof url === "string" && url !== "").map((url) => ({
+		...item,
+		url
+	}));
+	return [item];
+}
+/** Return the data records from the response shapes shared by sync gateways. */
+function dataRecordsOf(payload) {
+	const data = Array.isArray(payload.data) ? payload.data : payload.data !== null && typeof payload.data === "object" ? [payload.data] : Array.isArray(payload.images) ? payload.images : Array.isArray(payload.output) ? payload.output : void 0;
+	if (data === void 0) return void 0;
+	return data.filter((entry) => entry !== null && typeof entry === "object");
+}
+const ASYNC_PENDING_STATUSES = /* @__PURE__ */ new Set([
+	"submitted",
+	"pending",
+	"processing",
+	"running",
+	"in_progress",
+	"queued"
+]);
+const ASYNC_COMPLETED_STATUSES = /* @__PURE__ */ new Set([
+	"completed",
+	"succeeded",
+	"success",
+	"done"
+]);
+const ASYNC_FAILED_STATUSES = /* @__PURE__ */ new Set([
+	"failed",
+	"failure",
+	"cancelled",
+	"canceled",
+	"error"
+]);
+const ASYNC_POLL_MAX_MS = 24e4;
+const ASYNC_POLL_REQUEST_TIMEOUT_MS = 3e4;
+/** Read a provider error message from the common nested locations. */
+function asyncErrorMessage(payload, fallback) {
+	if (payload !== null && typeof payload === "object") {
+		const record = payload;
+		const candidates = [record.message, record.error];
+		const data = record.data;
+		const entries = Array.isArray(data) ? data : [data];
+		for (const entry of entries) {
+			if (entry === null || typeof entry !== "object") continue;
+			const item = entry;
+			candidates.push(item.message, item.error);
+			const nested = item.error;
+			if (nested !== null && typeof nested === "object") candidates.push(nested.message);
+		}
+		for (const candidate of candidates) {
+			if (typeof candidate === "string" && candidate.trim() !== "") return candidate;
+			if (candidate !== null && typeof candidate === "object") {
+				const message = candidate.message;
+				if (typeof message === "string" && message.trim() !== "") return message;
+			}
+		}
+	}
+	return fallback;
+}
+/** Wait between async-provider polls, but wake immediately when cancelled. */
+function waitForPoll(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+		};
+		const done = () => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		};
+		const timer = setTimeout(done, ms);
+		timer.unref();
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Poll one apib/apimart-style provider task until it yields image records.
+* The total deadline is shared by every poll and the final image downloads;
+* local task cancellation propagates through every request and sleep.
+*/
+async function pollAsyncTask(baseUrl, upstream, taskId, signal) {
+	const deadline = Date.now() + ASYNC_POLL_MAX_MS;
+	let delay = 1e3;
+	while (Date.now() < deadline) {
+		const remaining = deadline - Date.now();
+		const budget = requestSignal(signal, Math.min(ASYNC_POLL_REQUEST_TIMEOUT_MS, remaining));
+		try {
+			let response;
+			try {
+				response = await fetch(`${baseUrl}/tasks/${encodeURIComponent(taskId)}`, {
+					method: "GET",
+					headers: { authorization: `Bearer ${upstream.apiKey.trim()}` },
+					signal: budget.signal
+				});
+			} catch (error) {
+				if (signal?.aborted === true) throw new ImageGenError("任务已取消", "cancelled");
+				if (isBudgetTimeout(error)) throw new ImageGenError("上游异步任务轮询超时", "upstream-timeout");
+				throw new ImageGenError(`无法轮询上游异步任务：${error instanceof Error ? error.message : String(error)}`, "upstream-unreachable");
+			}
+			let payload;
+			try {
+				payload = await response.json();
+			} catch (error) {
+				if (isBudgetTimeout(error)) throw new ImageGenError("上游异步任务轮询超时", "upstream-timeout");
+				throw new ImageGenError(`上游任务接口返回了非 JSON 响应（HTTP ${response.status}）`, "upstream-invalid");
+			}
+			if (!response.ok || payload === null || typeof payload !== "object") throw new ImageGenError(asyncErrorMessage(payload, `上游任务轮询失败（HTTP ${response.status}）`), "upstream-rejected");
+			const record = payload;
+			const data = record.data;
+			const statusRecord = Array.isArray(data) ? data[0] : data !== null && typeof data === "object" ? data : record;
+			const statusValue = statusRecord !== null && typeof statusRecord === "object" ? statusRecord.status : void 0;
+			const status = typeof statusValue === "string" ? statusValue.toLowerCase() : "";
+			if (ASYNC_FAILED_STATUSES.has(status)) throw new ImageGenError(asyncErrorMessage(payload, `上游异步任务失败（${status || "unknown"}）`), "upstream-rejected");
+			const nested = statusRecord !== null && typeof statusRecord === "object" ? statusRecord : record;
+			const result = nested.result ?? (nested.output !== null && typeof nested.output === "object" ? nested.output.result : void 0) ?? record.result;
+			const images = (result !== null && typeof result === "object" ? result : void 0)?.images ?? nested.images ?? record.images;
+			if (ASYNC_COMPLETED_STATUSES.has(status) || images !== void 0) {
+				const items = Array.isArray(images) ? images.flatMap(imageItemsOf) : imageItemsOf(images);
+				if (items.length > 0) return items;
+				if (ASYNC_COMPLETED_STATUSES.has(status)) throw new ImageGenError("上游异步任务完成但没有图片结果", "upstream-empty");
+			}
+			if (status !== "" && !ASYNC_PENDING_STATUSES.has(status) && !ASYNC_COMPLETED_STATUSES.has(status)) throw new ImageGenError(`上游返回了未知异步任务状态：${status}`, "upstream-invalid");
+		} finally {
+			budget.dispose();
+		}
+		await waitForPoll(Math.min(delay, Math.max(1, deadline - Date.now())), signal);
+		delay = Math.min(5e3, delay * 2);
+	}
+	throw new ImageGenError("上游异步任务轮询超时（240 秒）", "upstream-timeout");
 }
 /**
 * Issue one single-image request (never sends `n`). The response is kept as a
@@ -742,7 +904,7 @@ async function requestOneImage(baseUrl, upstream, request, params, signal) {
 			});
 		} else if (isNanoBanana(params.model)) {
 			const form = new FormData();
-			form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$2(parsed.mime)}`);
+			form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$3(parsed.mime)}`);
 			form.append("prompt", request.prompt);
 			form.append("model", params.model);
 			if (params.aspect_ratio !== void 0) form.append("aspect_ratio", params.aspect_ratio);
@@ -760,7 +922,7 @@ async function requestOneImage(baseUrl, upstream, request, params, signal) {
 			});
 		} else {
 			const form = new FormData();
-			form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$2(parsed.mime)}`);
+			form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$3(parsed.mime)}`);
 			form.append("prompt", request.prompt);
 			form.append("model", params.model);
 			if (params.size !== void 0) form.append("size", params.size);
@@ -776,37 +938,43 @@ async function requestOneImage(baseUrl, upstream, request, params, signal) {
 		});
 	}
 	const budget = requestSignal(signal, UPSTREAM_TIMEOUT_MS);
-	let response;
 	try {
-		const endpoint = request.mode === "edit" && !isSeedream(params.model) ? "/images/edits" : "/images/generations";
-		response = await fetch(`${baseUrl}${endpoint}`, {
-			method: "POST",
-			headers,
-			body,
-			signal: budget.signal
-		});
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		if (/aborter/i.test(message) || /timeout/i.test(message)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
-		throw new ImageGenError(`无法连接上游接口：${message}`, "upstream-unreachable");
+		let response;
+		try {
+			const endpoint = request.mode === "edit" && !isSeedream(params.model) ? "/images/edits" : "/images/generations";
+			response = await fetch(`${baseUrl}${endpoint}`, {
+				method: "POST",
+				headers,
+				body,
+				signal: budget.signal
+			});
+		} catch (error) {
+			if (isBudgetTimeout(error)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
+			if (signal?.aborted === true) throw new ImageGenError("任务已取消", "cancelled");
+			throw new ImageGenError(`无法连接上游接口：${error instanceof Error ? error.message : String(error)}`, "upstream-unreachable");
+		}
+		let payload;
+		try {
+			payload = await response.json();
+		} catch (error) {
+			if (isBudgetTimeout(error)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
+			if (signal?.aborted === true) throw new ImageGenError("任务已取消", "cancelled");
+			throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, "upstream-invalid");
+		}
+		if (!response.ok || payload === null || typeof payload !== "object") throw new ImageGenError(upstreamMessage(payload, response.status), "upstream-rejected");
+		const data = dataRecordsOf(payload);
+		if (data === void 0) throw new ImageGenError("上游响应缺少 data 数组", "upstream-invalid");
+		if (data.length === 0) throw new ImageGenError("上游返回了 0 张图片", "upstream-empty");
+		const asyncEntries = data.filter((entry) => typeof entry.task_id === "string" && entry.task_id.trim() !== "");
+		if (asyncEntries.length > 0) {
+			const asyncRecords = (await Promise.all(asyncEntries.map((entry) => pollAsyncTask(baseUrl, upstream, entry.task_id, signal)))).flat();
+			if (asyncRecords.length === 0) throw new ImageGenError("上游异步任务完成但没有图片结果", "upstream-empty");
+			return Promise.all(asyncRecords.flatMap(imageItemsOf).map((item) => normalizeItem(item, upstream, signal)));
+		}
+		return Promise.all(data.flatMap(imageItemsOf).map((item) => normalizeItem(item, upstream, signal)));
 	} finally {
 		budget.dispose();
 	}
-	let payload;
-	try {
-		payload = await response.json();
-	} catch {
-		throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, "upstream-invalid");
-	}
-	if (!response.ok || payload === null || typeof payload !== "object") throw new ImageGenError(upstreamMessage(payload, response.status), "upstream-rejected");
-	const record = payload;
-	const data = Array.isArray(record.data) ? record.data : Array.isArray(record.images) ? record.images : Array.isArray(record.output) ? record.output : void 0;
-	if (data === void 0) throw new ImageGenError("上游响应缺少 data 数组", "upstream-invalid");
-	if (data.length === 0) throw new ImageGenError("上游返回了 0 张图片", "upstream-empty");
-	return Promise.all(data.map(async (entry) => {
-		if (entry === null || typeof entry !== "object") throw new ImageGenError("上游响应包含无效的图片条目", "upstream-invalid");
-		return normalizeItem(entry, upstream);
-	}));
 }
 /**
 * Qwen-Image (DashScope native multimodal-generation): one chat-style request
@@ -840,50 +1008,54 @@ async function generateQwenImage(baseUrl, upstream, request, options) {
 		}
 	};
 	const budget = requestSignal(options.signal, UPSTREAM_TIMEOUT_MS);
-	let response;
 	try {
-		response = await fetch(`${baseUrl}/services/aigc/multimodal-generation/generation`, {
-			method: "POST",
-			headers: {
-				authorization: `Bearer ${upstream.apiKey.trim()}`,
-				"content-type": "application/json"
-			},
-			body: JSON.stringify(body),
-			signal: budget.signal
-		});
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		if (/aborter/i.test(message) || /timeout/i.test(message)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
-		throw new ImageGenError(`无法连接上游接口：${message}`, "upstream-unreachable");
+		let response;
+		try {
+			response = await fetch(`${baseUrl}/services/aigc/multimodal-generation/generation`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${upstream.apiKey.trim()}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(body),
+				signal: budget.signal
+			});
+		} catch (error) {
+			if (isBudgetTimeout(error)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
+			if (options.signal?.aborted === true) throw new ImageGenError("任务已取消", "cancelled");
+			throw new ImageGenError(`无法连接上游接口：${error instanceof Error ? error.message : String(error)}`, "upstream-unreachable");
+		}
+		let payload;
+		try {
+			payload = await response.json();
+		} catch (error) {
+			if (isBudgetTimeout(error)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
+			if (options.signal?.aborted === true) throw new ImageGenError("任务已取消", "cancelled");
+			throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, "upstream-invalid");
+		}
+		if (!response.ok || payload === null || typeof payload !== "object") throw new ImageGenError(upstreamMessage(payload, response.status), "upstream-rejected");
+		const output = payload.output;
+		const choices = output !== void 0 && Array.isArray(output.choices) ? output.choices : [];
+		const urls = [];
+		for (const choice of choices) {
+			const message = choice !== null && typeof choice === "object" ? choice.message : void 0;
+			const items = message !== null && typeof message === "object" && Array.isArray(message.content) ? message.content : [];
+			for (const item of items) if (item !== null && typeof item === "object") {
+				const image = item.image;
+				if (typeof image === "string" && image !== "") urls.push(image);
+			}
+		}
+		if (urls.length === 0) throw new ImageGenError("上游响应缺少图片内容", "upstream-empty");
+		return { images: await Promise.all(urls.map(async (url) => {
+			const normalized = await normalizeItem({ url }, upstream);
+			return {
+				b64: normalized.b64,
+				mime: normalized.mime
+			};
+		})) };
 	} finally {
 		budget.dispose();
 	}
-	let payload;
-	try {
-		payload = await response.json();
-	} catch {
-		throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, "upstream-invalid");
-	}
-	if (!response.ok || payload === null || typeof payload !== "object") throw new ImageGenError(upstreamMessage(payload, response.status), "upstream-rejected");
-	const output = payload.output;
-	const choices = output !== void 0 && Array.isArray(output.choices) ? output.choices : [];
-	const urls = [];
-	for (const choice of choices) {
-		const message = choice !== null && typeof choice === "object" ? choice.message : void 0;
-		const items = message !== null && typeof message === "object" && Array.isArray(message.content) ? message.content : [];
-		for (const item of items) if (item !== null && typeof item === "object") {
-			const image = item.image;
-			if (typeof image === "string" && image !== "") urls.push(image);
-		}
-	}
-	if (urls.length === 0) throw new ImageGenError("上游响应缺少图片内容", "upstream-empty");
-	return { images: await Promise.all(urls.map(async (url) => {
-		const normalized = await normalizeItem({ url }, upstream);
-		return {
-			b64: normalized.b64,
-			mime: normalized.mime
-		};
-	})) };
 }
 /**
 * Forward one generate request to the configured endpoint. The requested image
@@ -916,7 +1088,7 @@ function upstreamMessage(payload, status) {
 	return `上游接口拒绝请求（HTTP ${status}）`;
 }
 /** File extension for a MIME type (multipart reference image). */
-function extensionOf$2(mime) {
+function extensionOf$3(mime) {
 	switch (mime.split(";")[0].trim()) {
 		case "image/jpeg": return "jpg";
 		case "image/webp": return "webp";
@@ -925,6 +1097,87 @@ function extensionOf$2(mime) {
 	}
 }
 //#endregion
+//#region src/storage-sync.ts
+/**
+* Object-storage sync for saved images: one S3-compatible uploader (SigV4,
+* zero dependencies) that covers Tencent COS / Alibaba OSS / Qiniu S3 /
+* MinIO / R2 style endpoints, plus a fire-and-forget hook the image stores
+* call after a file lands on disk. The handler is registered by the plugin
+* root (it owns the live settings), so framework-free stores stay decoupled
+* from the settings seam.
+*
+* Object keys: `${prefix}/gallery/<file>` and `${prefix}/images/<file>` —
+* content-addressed file names dedupe re-uploads naturally.
+*/
+let uploadHandler;
+/** Register the live uploader (index.ts apply). Pass undefined to clear. */
+function setStorageSyncHandler(handler) {
+	uploadHandler = handler;
+}
+/** Fire-and-forget notification from the image stores after a file write. */
+function notifyImageSaved(kind, filePath) {
+	try {
+		uploadHandler?.(kind, filePath);
+	} catch {}
+}
+/** URL-encode per RFC 3986 (AWS SigV4 canonical forms). */
+function uriEncode(value, encodeSlash = true) {
+	return value.replace(/[^A-Za-z0-9-_.~]/g, (char) => {
+		return `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+	}).replace(/%2F/g, encodeSlash ? "%2F" : "/");
+}
+/** HMAC-SHA256 helper. */
+function hmac(key, data) {
+	return createHmac("sha256", key).update(data, "utf8").digest();
+}
+/**
+* PUT one object to an S3-compatible endpoint (SigV4, virtual-hosted or
+* path-style — the endpoint URL already includes the bucket). Returns the
+* elapsed milliseconds so the settings card can show a latency reading.
+*/
+async function putObject(config, key, data, contentType = "application/octet-stream") {
+	const endpoint = config.endpoint.trim().replace(/\/+$/, "");
+	if (endpoint === "" || config.accessKey.trim() === "" || config.secretKey.trim() === "") throw new Error("对象存储配置不完整：请填写接口地址与密钥");
+	const url = new URL(`${endpoint}/${key.split("/").map((part) => uriEncode(part)).join("/")}`);
+	const payloadHash = createHash("sha256").update(data).digest("hex");
+	const amzDate = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:-]|\.\d{3}/g, "")}`;
+	const dateStamp = amzDate.slice(0, 8);
+	const host = url.host;
+	const canonicalUri = url.pathname;
+	const canonicalHeaders = `content-type:${contentType}\nhost:${host}\nx-amz-content-sha256:${payloadHash}\nx-amz-date:${amzDate}\n`;
+	const signedHeaders = "content-type;host;x-amz-content-sha256;x-amz-date";
+	const canonicalRequest = `PUT\n${canonicalUri}\n\n${canonicalHeaders}\n${signedHeaders}\n${payloadHash}`;
+	const scope = `${dateStamp}/${config.region.trim() || "us-east-1"}/s3/aws4_request`;
+	const stringToSign = `AWS4-HMAC-SHA256\n${amzDate}\n${scope}\n${createHash("sha256").update(canonicalRequest, "utf8").digest("hex")}`;
+	const signature = createHmac("sha256", hmac(hmac(hmac(hmac(`AWS4${config.secretKey.trim()}`, dateStamp), config.region.trim() || "us-east-1"), "s3"), "aws4_request")).update(stringToSign, "utf8").digest("hex");
+	const authorization = `AWS4-HMAC-SHA256 Credential=${config.accessKey.trim()}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+	const started = Date.now();
+	const response = await fetch(url, {
+		method: "PUT",
+		headers: {
+			"content-type": contentType,
+			"x-amz-content-sha256": payloadHash,
+			"x-amz-date": amzDate,
+			authorization
+		},
+		body: new Uint8Array(data)
+	});
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`对象存储拒绝上传（HTTP ${response.status}）${text !== "" ? `：${text.slice(0, 200)}` : ""}`);
+	}
+	return { ms: Date.now() - started };
+}
+/** Upload a small probe object; used by the settings card's test button. */
+async function testStorage(config) {
+	const key = `${config.prefix.trim() || "dsh-imagegen"}/ping.txt`;
+	const { ms } = await putObject(config, key, Buffer.from("dsh-imagegen storage ok", "utf8"), "text/plain");
+	return {
+		ms,
+		key
+	};
+}
+//#endregion
 //#region src/history-store.ts
 /**
 * Host-persisted generation history: images are stored as individual files
@@ -945,7 +1198,7 @@ function mutateHistory(operation) {
 	return next;
 }
 /** File extension for a MIME type (image file names). */
-function extensionOf$1(mime) {
+function extensionOf$2(mime) {
 	switch (mime.split(";")[0].trim()) {
 		case "image/jpeg": return "jpg";
 		case "image/webp": return "webp";
@@ -964,7 +1217,7 @@ function mimeOfFile$2(file) {
 	}
 }
 /** Sanitize an entry id for use as a file-name prefix. */
-function safeId$1(id) {
+function safeId$2(id) {
 	const cleaned = id.replace(/[^a-zA-Z0-9-]/g, "-");
 	return cleaned === "" ? "entry" : cleaned;
 }
@@ -1035,7 +1288,8 @@ function toWire$1(entry) {
 		...entry.projectId === void 0 ? {} : { projectId: entry.projectId },
 		...entry.projectName === void 0 ? {} : { projectName: entry.projectName },
 		...entry.slotKey === void 0 ? {} : { slotKey: entry.slotKey },
-		...entry.slotLabel === void 0 ? {} : { slotLabel: entry.slotLabel }
+		...entry.slotLabel === void 0 ? {} : { slotLabel: entry.slotLabel },
+		...entry.canvas === void 0 ? {} : { canvas: entry.canvas }
 	};
 }
 /** List the persisted history, newest first, as wire entries. */
@@ -1046,13 +1300,14 @@ async function listHistory() {
 async function appendHistory(input) {
 	return mutateHistory(async () => {
 		await ensureDirs$1();
-		const prefix = safeId$1(input.id);
+		const prefix = safeId$2(input.id);
 		const storedImages = [];
 		try {
 			for (let index = 0; index < input.images.length; index++) {
 				const image = input.images[index];
-				const file = `${prefix}-${index}.${extensionOf$1(image.mime)}`;
+				const file = `${prefix}-${index}.${extensionOf$2(image.mime)}`;
 				await promises.writeFile(path.join(IMAGES_DIR$1, file), Buffer.from(image.b64, "base64"));
+				notifyImageSaved("history", path.join(IMAGES_DIR$1, file));
 				storedImages.push({
 					file,
 					mime: image.mime,
@@ -1083,7 +1338,8 @@ async function appendHistory(input) {
 			...input.projectId === void 0 ? {} : { projectId: input.projectId },
 			...input.projectName === void 0 ? {} : { projectName: input.projectName },
 			...input.slotKey === void 0 ? {} : { slotKey: input.slotKey },
-			...input.slotLabel === void 0 ? {} : { slotLabel: input.slotLabel }
+			...input.slotLabel === void 0 ? {} : { slotLabel: input.slotLabel },
+			...input.canvas === void 0 ? {} : { canvas: input.canvas }
 		}, ...await readIndex$1()];
 		const kept = merged.slice(0, 50);
 		for (const dropped of merged.slice(50)) await removeEntryFiles$1(dropped);
@@ -1276,7 +1532,8 @@ var ImageGenerationRuntime = class {
 				...request.projectId === void 0 ? {} : { projectId: request.projectId },
 				...request.projectName === void 0 ? {} : { projectName: request.projectName },
 				...request.slotKey === void 0 ? {} : { slotKey: request.slotKey },
-				...request.slotLabel === void 0 ? {} : { slotLabel: request.slotLabel }
+				...request.slotLabel === void 0 ? {} : { slotLabel: request.slotLabel },
+				...request.canvas === void 0 ? {} : { canvas: request.canvas }
 			});
 			return {
 				...result,
@@ -1312,7 +1569,7 @@ function mutateGallery(operation) {
 	return next;
 }
 /** File extension for a MIME type (image file names). */
-function extensionOf(mime) {
+function extensionOf$1(mime) {
 	switch (mime.split(";")[0].trim()) {
 		case "image/jpeg": return "jpg";
 		case "image/webp": return "webp";
@@ -1331,7 +1588,7 @@ function mimeOfFile$1(file) {
 	}
 }
 /** Sanitize an entry id for use as a file-name prefix. */
-function safeId(id) {
+function safeId$1(id) {
 	const cleaned = id.replace(/[^a-zA-Z0-9-]/g, "-");
 	return cleaned === "" ? "entry" : cleaned;
 }
@@ -1407,7 +1664,8 @@ function toWire(entry) {
 		...entry.projectId === void 0 ? {} : { projectId: entry.projectId },
 		...entry.projectName === void 0 ? {} : { projectName: entry.projectName },
 		...entry.slotKey === void 0 ? {} : { slotKey: entry.slotKey },
-		...entry.slotLabel === void 0 ? {} : { slotLabel: entry.slotLabel }
+		...entry.slotLabel === void 0 ? {} : { slotLabel: entry.slotLabel },
+		...entry.canvas === void 0 ? {} : { canvas: entry.canvas }
 	};
 }
 /** List the persisted gallery, newest first, as wire entries. */
@@ -1428,13 +1686,14 @@ async function appendGallery(input) {
 				added: false
 			};
 		}
-		const prefix = safeId(input.id);
+		const prefix = safeId$1(input.id);
 		const storedImages = [];
 		try {
 			for (let index = 0; index < input.images.length; index++) {
 				const image = input.images[index];
-				const file = `${prefix}-${index}.${extensionOf(image.mime)}`;
+				const file = `${prefix}-${index}.${extensionOf$1(image.mime)}`;
 				await promises.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, "base64"));
+				notifyImageSaved("gallery", path.join(IMAGES_DIR, file));
 				storedImages.push({
 					file,
 					mime: image.mime,
@@ -1464,7 +1723,8 @@ async function appendGallery(input) {
 			...input.projectId === void 0 ? {} : { projectId: input.projectId },
 			...input.projectName === void 0 ? {} : { projectName: input.projectName },
 			...input.slotKey === void 0 ? {} : { slotKey: input.slotKey },
-			...input.slotLabel === void 0 ? {} : { slotLabel: input.slotLabel }
+			...input.slotLabel === void 0 ? {} : { slotLabel: input.slotLabel },
+			...input.canvas === void 0 ? {} : { canvas: input.canvas }
 		}, ...await readIndex()];
 		await writeIndex(merged);
 		return {
@@ -1517,6 +1777,349 @@ async function readGalleryImage(file) {
 	}
 }
 //#endregion
+//#region src/canvas-store.ts
+/** Host-persisted infinite canvas documents and content-addressed assets. */
+const DATA_ROOT = process.env.DSH_HOME?.trim() || path.join(homedir(), ".dsh");
+const CANVAS_ROOT = path.join(DATA_ROOT, "dsh-imagegen", "canvas");
+path.join(CANVAS_ROOT, "pages");
+path.join(CANVAS_ROOT, "assets");
+path.join(CANVAS_ROOT, "index.json");
+var CanvasConflictError = class extends Error {
+	code = "canvas-conflict";
+	constructor(message = "画布已在其他窗口更新，请重新加载后再保存。") {
+		super(message);
+		this.name = "CanvasConflictError";
+	}
+};
+function extensionOf(mime) {
+	switch (mime.split(";")[0].trim().toLowerCase()) {
+		case "image/jpeg": return "jpg";
+		case "image/webp": return "webp";
+		case "image/gif": return "gif";
+		default: return "png";
+	}
+}
+function mimeOf(file) {
+	switch (path.extname(file).toLowerCase()) {
+		case ".jpg":
+		case ".jpeg": return "image/jpeg";
+		case ".webp": return "image/webp";
+		case ".gif": return "image/gif";
+		default: return "image/png";
+	}
+}
+function safeId(value) {
+	const id = value.replace(/[^a-zA-Z0-9_-]/g, "-");
+	return id === "" ? randomUUID() : id;
+}
+async function writeJsonAtomic(file, value) {
+	await promises.mkdir(path.dirname(file), { recursive: true });
+	const temp = `${file}.tmp-${process.pid}-${randomUUID()}`;
+	await promises.writeFile(temp, `${JSON.stringify(value)}\n`, "utf8");
+	await promises.rename(temp, file);
+}
+async function readJson(file) {
+	try {
+		return JSON.parse(await promises.readFile(file, "utf8"));
+	} catch {
+		return;
+	}
+}
+function defaultDocument(id, title) {
+	const now = Date.now();
+	return {
+		version: 2,
+		id,
+		title,
+		revision: 1,
+		viewport: {
+			x: 0,
+			y: 0,
+			k: 1
+		},
+		background: "dots",
+		nodes: [],
+		connections: [],
+		createdAt: now,
+		updatedAt: now
+	};
+}
+function isAssetRef(value) {
+	if (value === null || typeof value !== "object") return false;
+	const asset = value;
+	return typeof asset.assetId === "string" && typeof asset.url === "string" && typeof asset.mime === "string" && typeof asset.width === "number" && typeof asset.height === "number";
+}
+function isNode(value) {
+	if (value === null || typeof value !== "object") return false;
+	const node = value;
+	if (typeof node.id !== "string" || typeof node.title !== "string" || typeof node.x !== "number" || typeof node.y !== "number" || typeof node.width !== "number" || typeof node.height !== "number") return false;
+	if (node.type !== "image" && node.type !== "text" && node.type !== "config") return false;
+	const metadata = node.metadata;
+	if (metadata !== void 0 && (metadata === null || typeof metadata !== "object")) return false;
+	const state = metadata ?? {};
+	if (node.type === "image") {
+		if (state.asset !== void 0 && !isAssetRef(state.asset)) return false;
+		return state.status === void 0 || state.status === "idle" || state.status === "generating" || state.status === "success" || state.status === "error";
+	}
+	if (node.type === "config") return state.prompt === void 0 || typeof state.prompt === "string";
+	return state.text === void 0 || typeof state.text === "string";
+}
+function isDocument(value) {
+	if (value === null || typeof value !== "object") return false;
+	const document = value;
+	return document.version === 2 && typeof document.id === "string" && typeof document.title === "string" && typeof document.revision === "number" && document.viewport !== null && typeof document.viewport === "object" && typeof document.viewport.x === "number" && typeof document.viewport.y === "number" && typeof document.viewport.k === "number" && (document.background === "dots" || document.background === "lines" || document.background === "blank") && Array.isArray(document.nodes) && document.nodes.every(isNode) && Array.isArray(document.connections);
+}
+/** Upgrade a v1 (image/text/annotation + edges) document to the v2 node-graph model.
+* Images and text notes keep their geometry; annotation prompt cards become plain
+* text notes carrying the prompt, and old edges survive only between surviving nodes. */
+function migrateLegacyDocument(input) {
+	const now = Date.now();
+	const legacyNodes = Array.isArray(input.nodes) ? input.nodes : [];
+	const nodes = [];
+	const annotationIds = /* @__PURE__ */ new Set();
+	for (const raw of legacyNodes) {
+		if (raw === null || typeof raw !== "object") continue;
+		const node = raw;
+		if (typeof node.id !== "string" || typeof node.x !== "number" || typeof node.y !== "number") continue;
+		const base = {
+			id: node.id,
+			title: typeof node.title === "string" ? node.title : "未命名节点",
+			x: node.x,
+			y: node.y,
+			width: typeof node.width === "number" ? node.width : 300,
+			height: typeof node.height === "number" ? node.height : 220
+		};
+		if (node.type === "image" && isAssetRef(node.asset)) {
+			const generation = node.generation ?? {};
+			nodes.push({
+				...base,
+				type: "image",
+				metadata: {
+					asset: node.asset,
+					status: typeof node.status === "string" && [
+						"idle",
+						"generating",
+						"success",
+						"error"
+					].includes(node.status) ? node.status : "success",
+					...typeof node.error === "string" ? { error: node.error } : {},
+					...typeof generation.prompt === "string" ? { prompt: generation.prompt } : {},
+					...typeof generation.model === "string" ? { model: generation.model } : {},
+					...typeof generation.taskId === "string" ? { taskId: generation.taskId } : {},
+					...typeof generation.sourceNodeId === "string" ? { sourceNodeId: generation.sourceNodeId } : {}
+				}
+			});
+		} else if (node.type === "text") nodes.push({
+			...base,
+			type: "text",
+			metadata: {
+				text: typeof node.text === "string" ? node.text : "",
+				...typeof node.fontSize === "number" ? { fontSize: node.fontSize } : {}
+			}
+		});
+		else if (node.type === "annotation") {
+			annotationIds.add(node.id);
+			const prompt = typeof node.prompt === "string" && node.prompt.trim() !== "" ? node.prompt : "（旧版标注，提示词见此）";
+			nodes.push({
+				...base,
+				type: "text",
+				title: "旧版标注",
+				metadata: { text: prompt }
+			});
+		}
+	}
+	nodes.sort((a, b) => {
+		const za = legacyNodes.find((item) => item?.id === a.id)?.zIndex;
+		const zb = legacyNodes.find((item) => item?.id === b.id)?.zIndex;
+		return (typeof za === "number" ? za : 0) - (typeof zb === "number" ? zb : 0);
+	});
+	const validIds = new Set(nodes.map((node) => node.id));
+	const seen = /* @__PURE__ */ new Set();
+	const connections = (Array.isArray(input.edges) ? input.edges : []).flatMap((raw) => {
+		if (raw === null || typeof raw !== "object") return [];
+		const edge = raw;
+		if (typeof edge.fromNodeId !== "string" || typeof edge.toNodeId !== "string") return [];
+		if (annotationIds.has(edge.fromNodeId) || annotationIds.has(edge.toNodeId)) return [];
+		if (!validIds.has(edge.fromNodeId) || !validIds.has(edge.toNodeId) || edge.fromNodeId === edge.toNodeId) return [];
+		const key = `${edge.fromNodeId}->${edge.toNodeId}`;
+		if (seen.has(key)) return [];
+		seen.add(key);
+		return [{
+			id: typeof edge.id === "string" ? edge.id : `edge-${randomUUID()}`,
+			fromNodeId: edge.fromNodeId,
+			toNodeId: edge.toNodeId
+		}];
+	});
+	const legacyViewport = input.viewport ?? {};
+	const background = input.background === "grid" ? "lines" : input.background === "blank" ? "blank" : "dots";
+	return {
+		version: 2,
+		id: typeof input.id === "string" ? input.id : randomUUID(),
+		title: typeof input.title === "string" ? input.title : "未命名画布",
+		revision: typeof input.revision === "number" ? input.revision : 1,
+		viewport: {
+			x: typeof legacyViewport.x === "number" ? legacyViewport.x : 0,
+			y: typeof legacyViewport.y === "number" ? legacyViewport.y : 0,
+			k: typeof legacyViewport.scale === "number" && legacyViewport.scale > 0 ? legacyViewport.scale : 1
+		},
+		background,
+		nodes,
+		connections,
+		createdAt: typeof input.createdAt === "number" ? input.createdAt : now,
+		updatedAt: typeof input.updatedAt === "number" ? input.updatedAt : now
+	};
+}
+/** Accept either the v2 document or a legacy v1 payload and return v2. */
+function coerceDocument(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const document = value;
+	if (document.version === 1) {
+		const migrated = migrateLegacyDocument(document);
+		return isDocument(migrated) ? migrated : void 0;
+	}
+	return isDocument(value) ? value : void 0;
+}
+let mutation = Promise.resolve();
+function serialize(operation) {
+	const next = mutation.then(operation, operation);
+	mutation = next.then(() => void 0, () => void 0);
+	return next;
+}
+var CanvasStore = class {
+	root;
+	constructor(root = CANVAS_ROOT) {
+		this.root = root;
+	}
+	pagesDir() {
+		return path.join(this.root, "pages");
+	}
+	assetsDir() {
+		return path.join(this.root, "assets");
+	}
+	indexPath() {
+		return path.join(this.root, "index.json");
+	}
+	async ensure() {
+		await promises.mkdir(this.pagesDir(), { recursive: true });
+		await promises.mkdir(this.assetsDir(), { recursive: true });
+	}
+	pagePath(id) {
+		return path.join(this.pagesDir(), `${safeId(id)}.json`);
+	}
+	assetPath(id) {
+		if (!/^[a-f0-9]{64}\.(png|jpg|jpeg|webp|gif)$/.test(id)) return void 0;
+		const target = path.join(this.assetsDir(), id);
+		const relative = path.relative(this.assetsDir(), target);
+		return relative.startsWith("..") || path.isAbsolute(relative) ? void 0 : target;
+	}
+	async readIndex() {
+		const value = await readJson(this.indexPath());
+		if (value === void 0 || typeof value !== "object" || !Array.isArray(value.projects)) return [];
+		return value.projects.filter((item) => {
+			if (item === null || typeof item !== "object") return false;
+			const project = item;
+			return typeof project.id === "string" && typeof project.title === "string" && typeof project.revision === "number" && typeof project.nodeCount === "number" && typeof project.createdAt === "number" && typeof project.updatedAt === "number";
+		});
+	}
+	async writeIndex(projects) {
+		await this.ensure();
+		await writeJsonAtomic(this.indexPath(), { projects });
+	}
+	async list() {
+		return this.readIndex();
+	}
+	async create(title = "未命名画布") {
+		return serialize(async () => {
+			await this.ensure();
+			const id = randomUUID();
+			const document = defaultDocument(id, title.trim() || "未命名画布");
+			await writeJsonAtomic(this.pagePath(id), document);
+			const projects = await this.readIndex();
+			await this.writeIndex([this.summaryOf(document), ...projects]);
+			return document;
+		});
+	}
+	async read(id) {
+		return coerceDocument(await readJson(this.pagePath(id)));
+	}
+	async save(document, expectedRevision) {
+		return serialize(async () => {
+			const incoming = coerceDocument(document);
+			if (incoming === void 0) throw new Error("malformed canvas document");
+			const current = await this.read(incoming.id);
+			if (current !== void 0 && expectedRevision !== void 0 && current.revision !== expectedRevision) throw new CanvasConflictError();
+			const next = {
+				...incoming,
+				revision: Math.max(current?.revision ?? 0, incoming.revision) + 1,
+				updatedAt: Date.now()
+			};
+			await this.ensure();
+			await writeJsonAtomic(this.pagePath(next.id), next);
+			const projects = (await this.readIndex()).filter((item) => item.id !== next.id);
+			await this.writeIndex([this.summaryOf(next), ...projects]);
+			return next;
+		});
+	}
+	async remove(id) {
+		return serialize(async () => {
+			try {
+				await promises.rm(this.pagePath(id), { force: true });
+			} catch {}
+			const projects = (await this.readIndex()).filter((item) => item.id !== id);
+			await this.writeIndex(projects);
+			return projects;
+		});
+	}
+	async putImage(input) {
+		if (!input.data.byteLength) throw new Error("image data is empty");
+		if (!/^image\/(png|jpeg|webp|gif)$/.test(input.mime)) throw new Error("unsupported image type");
+		if (!Number.isSafeInteger(input.width) || input.width < 1 || !Number.isSafeInteger(input.height) || input.height < 1) throw new Error("image dimensions are invalid");
+		await this.ensure();
+		const file = `${createHash("sha256").update(input.data).digest("hex")}.${extensionOf(input.mime)}`;
+		const target = path.join(this.assetsDir(), file);
+		try {
+			await promises.access(target);
+		} catch {
+			await promises.writeFile(target, input.data);
+		}
+		return {
+			assetId: file,
+			url: `/api/dsh-imagegen/canvas/asset/${file}`,
+			mime: input.mime,
+			bytes: input.data.byteLength,
+			width: input.width,
+			height: input.height,
+			origin: input.origin,
+			...input.originId === void 0 ? {} : { originId: input.originId },
+			...input.entryId === void 0 ? {} : { entryId: input.entryId },
+			...input.imageIndex === void 0 ? {} : { imageIndex: input.imageIndex }
+		};
+	}
+	async readAsset(file) {
+		const target = this.assetPath(file);
+		if (target === void 0) return void 0;
+		try {
+			return {
+				data: await promises.readFile(target),
+				mime: mimeOf(file)
+			};
+		} catch {
+			return;
+		}
+	}
+	summaryOf(document) {
+		return {
+			id: document.id,
+			title: document.title,
+			revision: document.revision,
+			nodeCount: document.nodes.length,
+			createdAt: document.createdAt,
+			updatedAt: document.updatedAt
+		};
+	}
+};
+const canvasStore = new CanvasStore();
+//#endregion
 //#region src/templates-store.ts
 /**
 * Prompt-template library store (multi-source).
@@ -2248,6 +2851,7 @@ function parseGenerateRequest(body) {
 	const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
 	if (prompt === "") return void 0;
 	const comparisonModels = Array.isArray(body.comparisonModels) ? [...new Set(body.comparisonModels.filter((model) => typeof model === "string").map((model) => model.trim()).filter(Boolean))] : [];
+	const canvas = parseCanvasMeta(body.canvas);
 	return {
 		mode: body.mode === "edit" ? "edit" : "text",
 		model: typeof body.model === "string" ? body.model : "",
@@ -2261,6 +2865,7 @@ function parseGenerateRequest(body) {
 		...typeof body.channelId === "string" && body.channelId !== "" ? { channelId: body.channelId } : {},
 		...typeof body.comparisonId === "string" && body.comparisonId !== "" ? { comparisonId: body.comparisonId } : {},
 		...comparisonModels.length > 1 ? { comparisonModels } : {},
+		...canvas === void 0 ? {} : { canvas },
 		...body.workflow === "ecommerce" ? { workflow: "ecommerce" } : {},
 		...typeof body.projectId === "string" && body.projectId !== "" ? { projectId: body.projectId } : {},
 		...typeof body.projectName === "string" && body.projectName !== "" ? { projectName: body.projectName } : {},
@@ -2268,6 +2873,18 @@ function parseGenerateRequest(body) {
 		...typeof body.slotLabel === "string" && body.slotLabel !== "" ? { slotLabel: body.slotLabel } : {}
 	};
 }
+function parseCanvasMeta(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const raw = value;
+	if (typeof raw.canvasId !== "string" || raw.canvasId.trim() === "") return void 0;
+	return {
+		canvasId: raw.canvasId.trim(),
+		...typeof raw.sourceNodeId === "string" && raw.sourceNodeId.trim() !== "" ? { sourceNodeId: raw.sourceNodeId.trim() } : {},
+		...typeof raw.annotationNodeId === "string" && raw.annotationNodeId.trim() !== "" ? { annotationNodeId: raw.annotationNodeId.trim() } : {},
+		...typeof raw.parentNodeId === "string" && raw.parentNodeId.trim() !== "" ? { parentNodeId: raw.parentNodeId.trim() } : {},
+		...raw.placement === "right" || raw.placement === "below" ? { placement: raw.placement } : {}
+	};
+}
 /** Validate a submitted history entry (images carry base64). */
 function parseHistoryEntryInput(body) {
 	const raw = body.entry;
@@ -2291,6 +2908,7 @@ function parseHistoryEntryInput(body) {
 		});
 	}
 	const comparisonModels = Array.isArray(entry.comparisonModels) ? [...new Set(entry.comparisonModels.filter((model) => typeof model === "string").map((model) => model.trim()).filter(Boolean))] : [];
+	const canvas = parseCanvasMeta(entry.canvas);
 	return {
 		id: entry.id,
 		createdAt: entry.createdAt,
@@ -2307,6 +2925,7 @@ function parseHistoryEntryInput(body) {
 		...typeof entry.channel === "string" ? { channel: entry.channel } : {},
 		...typeof entry.comparisonId === "string" ? { comparisonId: entry.comparisonId } : {},
 		...comparisonModels.length > 1 ? { comparisonModels } : {},
+		...canvas === void 0 ? {} : { canvas },
 		...entry.workflow === "ecommerce" ? { workflow: "ecommerce" } : {},
 		...typeof entry.projectId === "string" ? { projectId: entry.projectId } : {},
 		...typeof entry.projectName === "string" ? { projectName: entry.projectName } : {},
@@ -2411,6 +3030,7 @@ function makeRoutes(deps) {
 		updateTags: updateGalleryTags,
 		readImage: readGalleryImage
 	};
+	const canvas = deps.canvas ?? canvasStore;
 	const templates = deps.templates ?? {
 		list: listTemplates,
 		refresh: refreshTemplates,
@@ -3250,6 +3870,253 @@ function makeRoutes(deps) {
 				res.end(found.data);
 			}
 		},
+		{
+			kind: "exact",
+			path: CANVAS_API.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						projects: await canvas.list()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "canvas-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.create,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const title = typeof body?.title === "string" ? body.title : "未命名画布";
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						document: await canvas.create(title)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "canvas-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.read,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const id = typeof body?.id === "string" ? body.id : "";
+				const document = id === "" ? void 0 : await canvas.read(id);
+				if (document === void 0) writeJson(res, 200, {
+					ok: false,
+					code: "not-found",
+					message: "画布不存在"
+				});
+				else writeJson(res, 200, {
+					ok: true,
+					document
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.save,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const document = body?.document;
+				const expectedRevision = typeof body?.expectedRevision === "number" ? body.expectedRevision : void 0;
+				if (document === void 0 || typeof document !== "object") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "canvas document is required"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						document: await canvas.save(document, expectedRevision)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: error instanceof CanvasConflictError ? error.code : "canvas-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.remove,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const id = typeof body?.id === "string" ? body.id : "";
+				if (id === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "canvas id is required"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						projects: await canvas.remove(id)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "canvas-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.assetUpload,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req, MAX_HISTORY_BODY_BYTES);
+				const parsed = typeof body?.dataUrl === "string" ? imageDataUrl$1(body.dataUrl) : void 0;
+				const width = Number(body?.width);
+				const height = Number(body?.height);
+				if (parsed === void 0 || !Number.isSafeInteger(width) || width < 1 || !Number.isSafeInteger(height) || height < 1) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "image data and dimensions are required"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						asset: await canvas.putImage({
+							data: parsed.data,
+							mime: parsed.mediaType,
+							width,
+							height,
+							origin: body?.origin === "history" || body?.origin === "gallery" || body?.origin === "generated" ? body.origin : "upload",
+							...typeof body?.originId === "string" ? { originId: body.originId } : {},
+							...typeof body?.entryId === "string" ? { entryId: body.entryId } : {},
+							...Number.isSafeInteger(Number(body?.imageIndex)) ? { imageIndex: Number(body?.imageIndex) } : {}
+						})
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "canvas-asset-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: CANVAS_API.assetImport,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const source = body?.source === "history" || body?.source === "gallery" ? body.source : void 0;
+				const entryId = typeof body?.entryId === "string" ? body.entryId : "";
+				const imageIndex = Number(body?.imageIndex);
+				const width = Number(body?.width);
+				const height = Number(body?.height);
+				if (source === void 0 || entryId === "" || !Number.isSafeInteger(imageIndex) || imageIndex < 0 || !Number.isSafeInteger(width) || width < 1 || !Number.isSafeInteger(height) || height < 1) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "source, entryId, imageIndex and dimensions are required"
+					});
+					return;
+				}
+				try {
+					const backend = source === "history" ? history : gallery;
+					const image = (await backend.list()).find((item) => item.id === entryId)?.images[imageIndex];
+					if (image === void 0) {
+						writeJson(res, 200, {
+							ok: false,
+							code: "not-found",
+							message: "image not found"
+						});
+						return;
+					}
+					const base = source === "history" ? HISTORY_API.image : GALLERY_API.image;
+					const file = imageFileFrom(image.url, base);
+					const found = file === void 0 ? void 0 : await backend.readImage(file);
+					if (found === void 0) {
+						writeJson(res, 200, {
+							ok: false,
+							code: "not-found",
+							message: "image not found"
+						});
+						return;
+					}
+					writeJson(res, 200, {
+						ok: true,
+						asset: await canvas.putImage({
+							data: found.data,
+							mime: found.mime,
+							width,
+							height,
+							origin: source,
+							originId: entryId,
+							entryId,
+							imageIndex
+						})
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "canvas-asset-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "prefix",
+			path: CANVAS_API.asset,
+			handler: async (req, res) => {
+				if (!isLoopbackRequest(req)) {
+					writeJson(res, 403, { error: "forbidden: loopback-only" });
+					return;
+				}
+				if (req.method !== "GET") {
+					writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+					return;
+				}
+				const file = imageFileFrom(req.url, CANVAS_API.asset);
+				const found = file === void 0 ? void 0 : await canvas.readAsset(file);
+				if (found === void 0) {
+					writeJson(res, 404, { error: "not found" });
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": found.mime,
+					"content-length": found.data.length,
+					"cache-control": "private, max-age=3600"
+				});
+				res.end(found.data);
+			}
+		},
 		{
 			kind: "exact",
 			path: TEMPLATES_API.list,
@@ -3452,6 +4319,71 @@ function makeRoutes(deps) {
 					});
 				}
 			}
+		},
+		{
+			kind: "exact",
+			path: DATA_FOLDER_API,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const dir = path.join(homedir(), ".dsh", "dsh-imagegen");
+				try {
+					await mkdir(dir, { recursive: true });
+				} catch {}
+				if (body?.open === false) {
+					writeJson(res, 200, {
+						ok: true,
+						path: dir
+					});
+					return;
+				}
+				try {
+					spawn(process.platform === "win32" ? "explorer.exe" : process.platform === "darwin" ? "open" : "xdg-open", [dir], {
+						detached: true,
+						stdio: "ignore"
+					}).unref();
+					writeJson(res, 200, {
+						ok: true,
+						path: dir
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "data-folder-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: STORAGE_API.test,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const storage = deps.resolveStorage?.();
+				if (storage === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "storage-unavailable",
+						message: "存储配置不可用"
+					});
+					return;
+				}
+				try {
+					const result = await testStorage(storage);
+					writeJson(res, 200, {
+						ok: true,
+						ms: result.ms,
+						key: result.key
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "storage-test-failed",
+						message: messageOf(error)
+					});
+				}
+			}
 		}
 	];
 }
@@ -4005,6 +4937,16 @@ function registerEditImageCommand(ctx, runtime, resolve, pendingImages) {
 }
 //#endregion
 //#region src/index.ts
+/** Content type for a saved image file name (object uploads). */
+function mimeOfPath(filePath) {
+	switch (path.extname(filePath).toLowerCase()) {
+		case ".jpg":
+		case ".jpeg": return "image/jpeg";
+		case ".webp": return "image/webp";
+		case ".gif": return "image/gif";
+		default: return "image/png";
+	}
+}
 /** Stable cordis plugin name. */
 const name = "imagegen";
 /** Services required before the surfaces can mount. */
@@ -4034,6 +4976,14 @@ const Config = z.object({
 	promptApiUrl: z.string().default(""),
 	promptApiKey: z.string().role("secret").default(""),
 	promptModel: z.string().default(""),
+	storageEnabled: z.boolean().default(false),
+	storageEndpoint: z.string().default(""),
+	storageRegion: z.string().default(""),
+	storagePrefix: z.string().default("dsh-imagegen"),
+	storageAccessKey: z.string().default(""),
+	storageSecretKey: z.string().role("secret").default(""),
+	storageSyncGallery: z.boolean().default(true),
+	storageSyncHistory: z.boolean().default(false),
 	apiUrl: z.string().default(""),
 	apiKey: z.string().role("secret").default(""),
 	imageModels: z.array(z.string()).default([])
@@ -4134,7 +5084,17 @@ function apply(ctx, config) {
 			defaultChannelId,
 			promptApiUrl: typeof value.promptApiUrl === "string" ? value.promptApiUrl.trim() : "",
 			promptApiKey: typeof value.promptApiKey === "string" ? value.promptApiKey.trim() : "",
-			promptModel: typeof value.promptModel === "string" ? value.promptModel.trim() : ""
+			promptModel: typeof value.promptModel === "string" ? value.promptModel.trim() : "",
+			storage: {
+				enabled: value.storageEnabled ?? false,
+				endpoint: typeof value.storageEndpoint === "string" ? value.storageEndpoint.trim() : "",
+				region: typeof value.storageRegion === "string" ? value.storageRegion.trim() : "",
+				accessKey: typeof value.storageAccessKey === "string" ? value.storageAccessKey.trim() : "",
+				secretKey: typeof value.storageSecretKey === "string" ? value.storageSecretKey.trim() : "",
+				prefix: typeof value.storagePrefix === "string" && value.storagePrefix.trim() !== "" ? value.storagePrefix.trim() : "dsh-imagegen",
+				syncGallery: value.storageSyncGallery ?? true,
+				syncHistory: value.storageSyncHistory ?? false
+			}
 		};
 	};
 	const channelsView = () => {
@@ -4144,6 +5104,13 @@ function apply(ctx, config) {
 			defaultChannelId: value.defaultChannelId
 		};
 	};
+	setStorageSyncHandler((kind, filePath) => {
+		const storage = resolve().storage;
+		if (!storage.enabled || !storage.endpoint.trim() || storage.secretKey.trim() === "") return;
+		if (kind === "gallery" && !storage.syncGallery) return;
+		if (kind === "history" && !storage.syncHistory) return;
+		putObject(storage, `${storage.prefix}/${kind === "gallery" ? "gallery" : "images"}/${path.basename(filePath)}`, readFileSync(filePath), mimeOfPath(filePath)).catch(() => {});
+	});
 	const runtime = new ImageGenerationRuntime(channelsView);
 	const pendingConversationImages = /* @__PURE__ */ new Map();
 	ctx.inject(["settings", "attachments"], (sctx) => {
@@ -4175,7 +5142,8 @@ function apply(ctx, config) {
 				},
 				attachments: sctx.attachments,
 				pendingConversationImages,
-				runtime
+				runtime,
+				resolveStorage: () => resolve().storage
 			}).map((route) => ctx.webServer.register(route));
 			const TEMPLATE_SYNC_INITIAL_DELAY_MS = 3e4;
 			const TEMPLATE_SYNC_INTERVAL_MS = 720 * 60 * 1e3;
@@ -4244,6 +5212,9 @@ function apply(ctx, config) {
 		onChange: sync
 	});
 	sync();
+	return () => {
+		setStorageSyncHandler(void 0);
+	};
 }
 //#endregion
-export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, ImageGenerationRuntime, addTemplateFavorite, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateFavoritesMemo, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, latestSessionImage, listGallery, listTemplateFavorites, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, registerAgentImageTools, registerEditImageCommand, removeGallery, removeTemplateFavorite, sampleTemplates, syncAllTemplates, updateGalleryTags };
+export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, ImageGenerationRuntime, addTemplateFavorite, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateFavoritesMemo, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, latestSessionImage, listGallery, listTemplateFavorites, listTemplates, makeRoutes, name, profileFromProcess, putObject, readGalleryImage, readTemplateImage, refreshTemplates, registerAgentImageTools, registerEditImageCommand, removeGallery, removeTemplateFavorite, sampleTemplates, setStorageSyncHandler, syncAllTemplates, testStorage, updateGalleryTags };