@dickpy/dsh-imagegen 1.0.0 → 1.0.1

package/lib/index.js

@@ -1,5 +1,6 @@
 import { SettingsConflictError, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
+import { randomUUID } from "node:crypto";
 import { promises } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -260,6 +261,12 @@ function extensionOf$1(mime) {
 const HISTORY_DIR = path.join(homedir(), ".dsh", "dsh-imagegen");
 const INDEX_PATH = path.join(HISTORY_DIR, "index.json");
 const IMAGES_DIR = path.join(HISTORY_DIR, "images");
+let pendingMutation = Promise.resolve();
+function mutateHistory(operation) {
+	const next = pendingMutation.then(operation, operation);
+	pendingMutation = next.then(() => void 0, () => void 0);
+	return next;
+}
 /** File extension for a MIME type (image file names). */
 function extensionOf(mime) {
 	switch (mime.split(";")[0].trim()) {
@@ -351,52 +358,63 @@ async function listHistory() {
 }
 /** Append one generation, evicting the oldest beyond HISTORY_MAX. */
 async function appendHistory(input) {
-	await ensureDirs();
-	const prefix = safeId(input.id);
-	const storedImages = [];
-	for (let index = 0; index < input.images.length; index++) {
-		const image = input.images[index];
-		const file = `${prefix}-${index}.${extensionOf(image.mime)}`;
-		await promises.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, "base64"));
-		storedImages.push({
-			file,
-			mime: image.mime,
-			...image.revisedPrompt === void 0 ? {} : { revisedPrompt: image.revisedPrompt }
-		});
-	}
-	const merged = [{
-		id: input.id,
-		createdAt: input.createdAt,
-		mode: input.mode,
-		model: input.model,
-		prompt: input.prompt,
-		size: input.size,
-		quality: input.quality,
-		detail: input.detail,
-		n: input.n,
-		images: storedImages,
-		...input.refName === void 0 ? {} : { refName: input.refName }
-	}, ...await readIndex()];
-	const kept = merged.slice(0, 50);
-	for (const dropped of merged.slice(50)) await removeEntryFiles(dropped);
-	await writeIndex(kept);
-	return kept.map(toWire);
+	return mutateHistory(async () => {
+		await ensureDirs();
+		const prefix = safeId(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)}`;
+				await promises.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, "base64"));
+				storedImages.push({
+					file,
+					mime: image.mime,
+					...image.revisedPrompt === void 0 ? {} : { revisedPrompt: image.revisedPrompt }
+				});
+			}
+		} catch (error) {
+			await removeEntryFiles({ images: storedImages });
+			throw error;
+		}
+		const merged = [{
+			id: input.id,
+			createdAt: input.createdAt,
+			mode: input.mode,
+			model: input.model,
+			prompt: input.prompt,
+			size: input.size,
+			quality: input.quality,
+			detail: input.detail,
+			n: input.n,
+			images: storedImages,
+			...input.refName === void 0 ? {} : { refName: input.refName }
+		}, ...await readIndex()];
+		const kept = merged.slice(0, 50);
+		for (const dropped of merged.slice(50)) await removeEntryFiles(dropped);
+		await writeIndex(kept);
+		return kept.map(toWire);
+	});
 }
 /** Remove one entry (and its image files). */
 async function removeHistory(id) {
-	const previous = await readIndex();
-	const target = previous.find((entry) => entry.id === id);
-	if (target !== void 0) await removeEntryFiles(target);
-	const kept = previous.filter((entry) => entry.id !== id);
-	await writeIndex(kept);
-	return kept.map(toWire);
+	return mutateHistory(async () => {
+		const previous = await readIndex();
+		const target = previous.find((entry) => entry.id === id);
+		if (target !== void 0) await removeEntryFiles(target);
+		const kept = previous.filter((entry) => entry.id !== id);
+		await writeIndex(kept);
+		return kept.map(toWire);
+	});
 }
 /** Remove every entry (and all image files). */
 async function clearHistory() {
-	const previous = await readIndex();
-	for (const entry of previous) await removeEntryFiles(entry);
-	await writeIndex([]);
-	return [];
+	return mutateHistory(async () => {
+		const previous = await readIndex();
+		for (const entry of previous) await removeEntryFiles(entry);
+		await writeIndex([]);
+		return [];
+	});
 }
 /** Read one stored image file by its (validated) file name. */
 async function readHistoryImage(file) {
@@ -550,6 +568,13 @@ function failureOf(error) {
 * @returns the route registrations.
 */
 function makeRoutes(deps) {
+	const history = deps.history ?? {
+		list: listHistory,
+		append: appendHistory,
+		remove: removeHistory,
+		clear: clearHistory,
+		readImage: readHistoryImage
+	};
 	const guard = (req, res, method) => {
 		if (!isLoopbackRequest(req)) {
 			writeJson(res, 403, { error: "forbidden: loopback-only" });
@@ -661,13 +686,37 @@ function makeRoutes(deps) {
 					quality: typeof body.quality === "string" ? body.quality : "auto",
 					n: typeof body.n === "number" ? body.n : 1,
 					detail: typeof body.detail === "string" ? body.detail : "",
-					...typeof body.image === "string" && body.image !== "" ? { image: body.image } : {}
+					...typeof body.image === "string" && body.image !== "" ? { image: body.image } : {},
+					...typeof body.refName === "string" && body.refName !== "" ? { refName: body.refName } : {}
 				};
 				try {
-					writeJson(res, 200, {
-						ok: true,
-						...await generateImage(deps.resolve(), request)
-					});
+					const result = await generateImage(deps.resolve(), request);
+					try {
+						const entries = await history.append({
+							id: randomUUID(),
+							createdAt: Date.now(),
+							mode: request.mode,
+							model: request.model,
+							prompt: request.prompt,
+							size: request.size,
+							quality: request.quality,
+							detail: request.detail,
+							n: request.n,
+							images: result.images,
+							...request.refName === void 0 ? {} : { refName: request.refName }
+						});
+						writeJson(res, 200, {
+							ok: true,
+							...result,
+							history: entries
+						});
+					} catch (error) {
+						writeJson(res, 200, {
+							ok: true,
+							...result,
+							historyError: messageOf(error)
+						});
+					}
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					writeJson(res, 200, {
@@ -686,7 +735,7 @@ function makeRoutes(deps) {
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						entries: await listHistory()
+						entries: await history.list()
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -723,7 +772,7 @@ function makeRoutes(deps) {
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						entries: await appendHistory(entry)
+						entries: await history.append(entry)
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -752,7 +801,7 @@ function makeRoutes(deps) {
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						entries: await removeHistory(id)
+						entries: await history.remove(id)
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -771,7 +820,7 @@ function makeRoutes(deps) {
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						entries: await clearHistory()
+						entries: await history.clear()
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -799,7 +848,7 @@ function makeRoutes(deps) {
 					writeJson(res, 404, { error: "not found" });
 					return;
 				}
-				const found = await readHistoryImage(file);
+				const found = await history.readImage(file);
 				if (found === void 0) {
 					writeJson(res, 404, { error: "not found" });
 					return;
@@ -834,7 +883,7 @@ const DEFAULT_ANNOUNCE = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口；本地插件（源码位于 E:\\dsh-plugin，独立于 dsh-web-ui 插件全家桶）。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。";
+const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。";
 /**
 * Mount the settings section, routes, and announcement.
 * @param ctx - host plugin context carrying webServer/systemPrompt.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dickpy/dsh-imagegen",
   "description": "AI 生图 (image generation) plugin for the dsh web GUI: text-to-image and image-to-image through a configurable OpenAI-compatible endpoint (gpt-image-2 / gpt-image-1 / dall-e-3), with a settings card for api_url / api_key and a sidebar entry opening a split-pane generation studio.",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -51,6 +51,7 @@
     "lib",
     "src",
     "cordis.patch.yml",
+    "docs",
     "README.md"
   ],
   "license": "Apache-2.0",
@@ -63,4 +64,4 @@
     "watch": "tsdown --watch",
     "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/client/ImageGenPanel.tsx

@@ -13,7 +13,7 @@ import { createPortal } from 'react-dom'
 import { Button, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ImageGenApi } from './api.ts'
 import { errorMessage, tt } from './helpers.ts'
-import type { GeneratedImage, GenerateMode, GenerateRequest, HistoryEntry, HistoryEntryInput, HistoryImageRef } from '../protocol.ts'
+import type { GeneratedImage, GenerateMode, GenerateRequest, HistoryEntry, HistoryImageRef } from '../protocol.ts'
 import type { ImageGenConfig, ImageGenScope } from './settings-scope.ts'
 import css from './panel.module.css'
 
@@ -177,6 +177,7 @@ export function ImageGenPanel(props: {
       n: count,
       detail,
       ...mode === 'edit' && refImage !== null ? { image: refImage.dataUrl } : {},
+      ...mode === 'edit' && refImage !== null ? { refName: refImage.name } : {},
     }
     setGenerating(true)
     setError(null)
@@ -186,24 +187,8 @@ export function ImageGenPanel(props: {
       const result = await api.generate(request)
       setImages(result.images)
       setViewingHistoryId(null)
-      const entry: HistoryEntryInput = {
-        id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-        createdAt: Date.now(),
-        mode,
-        model,
-        prompt: promptText,
-        size,
-        quality,
-        detail,
-        n: count,
-        images: result.images,
-        ...mode === 'edit' && refImage !== null ? { refName: refImage.name } : {},
-      }
-      try {
-        setHistory(await api.historyAppend(entry))
-      } catch {
-        // Persisting history is best-effort; the images stay on the canvas.
-      }
+      if (result.history !== undefined) setHistory(result.history)
+      if (result.historyError !== undefined) setError(result.historyError)
     } catch (caught) {
       setError(errorMessage(caught))
     } finally {

package/src/client/api.ts

@@ -3,7 +3,7 @@
  * data access path the panel uses — plain fetch, same origin.
  */
 
-import { GENERATE_API, HISTORY_API, type GenerateRequest, type GenerateResult, type HistoryEntry, type HistoryEntryInput } from '../protocol.ts'
+import { GENERATE_API, HISTORY_API, type GenerateRequest, type GenerateResult, type HistoryEntry } from '../protocol.ts'
 
 /** Error carrying the route's JSON error message. */
 export class ImageGenApiError extends Error {
@@ -47,8 +47,12 @@ export class ImageGenApi {
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(request),
     })
-    const body = await readEnvelope<{ ok: true; images: GenerateResult['images'] }>(response)
-    return { images: body.images }
+    const body = await readEnvelope<{ ok: true; images: GenerateResult['images']; history?: HistoryEntry[]; historyError?: string }>(response)
+    return {
+      images: body.images,
+      ...body.history === undefined ? {} : { history: body.history },
+      ...body.historyError === undefined ? {} : { historyError: body.historyError },
+    }
   }
 
   /** List the host-persisted history (newest first). */
@@ -58,17 +62,6 @@ export class ImageGenApi {
     return body.entries
   }
 
-  /** Append one generation to the host-persisted history. */
-  async historyAppend(entry: HistoryEntryInput): Promise<HistoryEntry[]> {
-    const response = await fetch(HISTORY_API.append, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ entry }),
-    })
-    const body = await readEnvelope<{ ok: true; entries: HistoryEntry[] }>(response)
-    return body.entries
-  }
-
   /** Remove one history entry by id. */
   async historyRemove(id: string): Promise<HistoryEntry[]> {
     const response = await fetch(HISTORY_API.remove, {

package/src/client/locales.ts

@@ -168,7 +168,7 @@ export const en: Record<keyof typeof zh, string> = {
   'preview.prev': 'Previous',
   'preview.next': 'Next',
   'preview.index': '{index} / {total}',
-  'config.missing': 'API not configured: open "Settings → Web UI Plugins" and fill in api_url and api_key for AI Image.',
+  'config.missing': 'API not configured: open "Settings → Plugins → Configurable" and fill in api_url and api_key for AI Image.',
   'config.configured': 'Connected to {url}',
   'config.disabled': 'The plugin is disabled — re-enable it in Settings.',
   'settings.title': 'AI Image (dsh-imagegen)',

package/src/history-store.ts

@@ -17,6 +17,16 @@ const HISTORY_DIR = path.join(homedir(), '.dsh', 'dsh-imagegen')
 const INDEX_PATH = path.join(HISTORY_DIR, 'index.json')
 const IMAGES_DIR = path.join(HISTORY_DIR, 'images')
 
+// History mutations read and replace one shared index. Serialize them so
+// overlapping requests cannot each read an old index and lose the other's row.
+let pendingMutation: Promise<void> = Promise.resolve()
+
+function mutateHistory<T>(operation: () => Promise<T>): Promise<T> {
+  const next = pendingMutation.then(operation, operation)
+  pendingMutation = next.then(() => undefined, () => undefined)
+  return next
+}
+
 /** One image's on-disk record (file name + mime, never base64). */
 interface StoredImage {
   file: string
@@ -152,55 +162,66 @@ export async function listHistory(): Promise<HistoryEntry[]> {
 
 /** Append one generation, evicting the oldest beyond HISTORY_MAX. */
 export async function appendHistory(input: HistoryEntryInput): Promise<HistoryEntry[]> {
-  await ensureDirs()
-  const prefix = safeId(input.id)
-  const storedImages: StoredImage[] = []
-  for (let index = 0; index < input.images.length; index++) {
-    const image = input.images[index]!
-    const file = `${prefix}-${index}.${extensionOf(image.mime)}`
-    await fs.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, 'base64'))
-    storedImages.push({
-      file,
-      mime: image.mime,
-      ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
-    })
-  }
-  const entry: StoredEntry = {
-    id: input.id,
-    createdAt: input.createdAt,
-    mode: input.mode,
-    model: input.model,
-    prompt: input.prompt,
-    size: input.size,
-    quality: input.quality,
-    detail: input.detail,
-    n: input.n,
-    images: storedImages,
-    ...input.refName === undefined ? {} : { refName: input.refName },
-  }
-  const merged = [entry, ...await readIndex()]
-  const kept = merged.slice(0, HISTORY_MAX)
-  for (const dropped of merged.slice(HISTORY_MAX)) await removeEntryFiles(dropped)
-  await writeIndex(kept)
-  return kept.map(toWire)
+  return mutateHistory(async () => {
+    await ensureDirs()
+    const prefix = safeId(input.id)
+    const storedImages: StoredImage[] = []
+    try {
+      for (let index = 0; index < input.images.length; index++) {
+        const image = input.images[index]!
+        const file = `${prefix}-${index}.${extensionOf(image.mime)}`
+        await fs.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, 'base64'))
+        storedImages.push({
+          file,
+          mime: image.mime,
+          ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
+        })
+      }
+    } catch (error) {
+      await removeEntryFiles({ images: storedImages } as StoredEntry)
+      throw error
+    }
+    const entry: StoredEntry = {
+      id: input.id,
+      createdAt: input.createdAt,
+      mode: input.mode,
+      model: input.model,
+      prompt: input.prompt,
+      size: input.size,
+      quality: input.quality,
+      detail: input.detail,
+      n: input.n,
+      images: storedImages,
+      ...input.refName === undefined ? {} : { refName: input.refName },
+    }
+    const merged = [entry, ...await readIndex()]
+    const kept = merged.slice(0, HISTORY_MAX)
+    for (const dropped of merged.slice(HISTORY_MAX)) await removeEntryFiles(dropped)
+    await writeIndex(kept)
+    return kept.map(toWire)
+  })
 }
 
 /** Remove one entry (and its image files). */
 export async function removeHistory(id: string): Promise<HistoryEntry[]> {
-  const previous = await readIndex()
-  const target = previous.find(entry => entry.id === id)
-  if (target !== undefined) await removeEntryFiles(target)
-  const kept = previous.filter(entry => entry.id !== id)
-  await writeIndex(kept)
-  return kept.map(toWire)
+  return mutateHistory(async () => {
+    const previous = await readIndex()
+    const target = previous.find(entry => entry.id === id)
+    if (target !== undefined) await removeEntryFiles(target)
+    const kept = previous.filter(entry => entry.id !== id)
+    await writeIndex(kept)
+    return kept.map(toWire)
+  })
 }
 
 /** Remove every entry (and all image files). */
 export async function clearHistory(): Promise<HistoryEntry[]> {
-  const previous = await readIndex()
-  for (const entry of previous) await removeEntryFiles(entry)
-  await writeIndex([])
-  return []
+  return mutateHistory(async () => {
+    const previous = await readIndex()
+    for (const entry of previous) await removeEntryFiles(entry)
+    await writeIndex([])
+    return []
+  })
 }
 
 /** Read one stored image file by its (validated) file name. */

package/src/index.ts

@@ -57,7 +57,7 @@ const DEFAULT_ANNOUNCE = true
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口；本地插件（源码位于 E:\\dsh-plugin，独立于 dsh-web-ui 插件全家桶）。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。'
+export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。'
 
 /** Effective config (schema defaults applied). */
 interface EffectiveConfig {

package/src/protocol.ts

@@ -58,6 +58,8 @@ export interface GenerateRequest {
   detail: string
   /** Reference image as a data URL (edit mode only). */
   image?: string
+  /** Original reference-image name, retained in the history entry. */
+  refName?: string
 }
 
 /** One generated image, normalized host-side to base64 so the browser never
@@ -74,6 +76,10 @@ export interface GeneratedImage {
 /** Successful generate outcome. */
 export interface GenerateResult {
   images: GeneratedImage[]
+  /** Updated host-persisted history, when returned by the generate route. */
+  history?: HistoryEntry[]
+  /** Persistence failure after images were successfully generated. */
+  historyError?: string
 }
 
 /** One history image reference as the browser consumes it (a served URL). */

package/src/routes.ts

@@ -6,11 +6,12 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { randomUUID } from 'node:crypto'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import { generateImage, type UpstreamConfig } from './engine.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
-import { GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, type GeneratedImage, type GenerateRequest, type HistoryEntryInput } from './protocol.ts'
+import { GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -31,6 +32,14 @@ export interface ImageGenRoutesDeps {
   settings: SettingsSeam
   /** Resolve the current upstream config (composition entry + settings). */
   resolve: () => UpstreamConfig
+  /** Overrideable history backend, primarily for host integration tests. */
+  history?: {
+    list: () => Promise<HistoryEntry[]>
+    append: (entry: HistoryEntryInput) => Promise<HistoryEntry[]>
+    remove: (id: string) => Promise<HistoryEntry[]>
+    clear: () => Promise<HistoryEntry[]>
+    readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+  }
 }
 
 /** Loopback literal check plus browser same-origin markers (mirrors dsh-ssh). */
@@ -166,6 +175,13 @@ function failureOf(error: unknown): { ok: false; code: string; message: string }
  * @returns the route registrations.
  */
 export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
+  const history = deps.history ?? {
+    list: listHistory,
+    append: appendHistory,
+    remove: removeHistory,
+    clear: clearHistory,
+    readImage: readHistoryImage,
+  }
   const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
     if (!isLoopbackRequest(req)) {
       writeJson(res, 403, { error: 'forbidden: loopback-only' })
@@ -257,10 +273,28 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           n: typeof body.n === 'number' ? body.n : 1,
           detail: typeof body.detail === 'string' ? body.detail : '',
           ...typeof body.image === 'string' && body.image !== '' ? { image: body.image } : {},
+          ...typeof body.refName === 'string' && body.refName !== '' ? { refName: body.refName } : {},
         }
         try {
           const result = await generateImage(deps.resolve(), request)
-          writeJson(res, 200, { ok: true, ...result })
+          try {
+            const entries = await history.append({
+              id: randomUUID(),
+              createdAt: Date.now(),
+              mode: request.mode,
+              model: request.model,
+              prompt: request.prompt,
+              size: request.size,
+              quality: request.quality,
+              detail: request.detail,
+              n: request.n,
+              images: result.images,
+              ...request.refName === undefined ? {} : { refName: request.refName },
+            })
+            writeJson(res, 200, { ok: true, ...result, history: entries })
+          } catch (error) {
+            writeJson(res, 200, { ok: true, ...result, historyError: messageOf(error) })
+          }
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error)
           const code = error instanceof Error && 'code' in error && typeof (error as { code?: unknown }).code === 'string'
@@ -277,7 +311,7 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
         try {
-          writeJson(res, 200, { ok: true, entries: await listHistory() })
+          writeJson(res, 200, { ok: true, entries: await history.list() })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'history-failed', message: messageOf(error) })
         }
@@ -300,7 +334,7 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           return
         }
         try {
-          writeJson(res, 200, { ok: true, entries: await appendHistory(entry) })
+          writeJson(res, 200, { ok: true, entries: await history.append(entry) })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'history-failed', message: messageOf(error) })
         }
@@ -319,7 +353,7 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           return
         }
         try {
-          writeJson(res, 200, { ok: true, entries: await removeHistory(id) })
+          writeJson(res, 200, { ok: true, entries: await history.remove(id) })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'history-failed', message: messageOf(error) })
         }
@@ -332,7 +366,7 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
         try {
-          writeJson(res, 200, { ok: true, entries: await clearHistory() })
+          writeJson(res, 200, { ok: true, entries: await history.clear() })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'history-failed', message: messageOf(error) })
         }
@@ -356,7 +390,7 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           writeJson(res, 404, { error: 'not found' })
           return
         }
-        const found = await readHistoryImage(file)
+        const found = await history.readImage(file)
         if (found === undefined) {
           writeJson(res, 404, { error: 'not found' })
           return