@dsh-plus/image-studio 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/image-studio",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "dsh-plus service+ui plugin: 图像工作室——OpenAI Images 协议文生图/图生图，全参数开关化，双预设体系，并发生图任务与可二次编辑画廊",
   "type": "module",
   "main": "lib/index.js",

package/src/api.ts

@@ -2,6 +2,7 @@
  * image-studio HTTP 端点（同源 webServer，与 usage-panel 同一暴露面约定）：
  * - POST generate / GET tasks|tasks/<id> / POST tasks/<id>/cancel
  * - GET gallery|gallery/<id> / DELETE gallery/<id> / GET images/<id>
+ * - POST uploads（本地文件上传原图）/ GET uploads|uploads/<id>（列表/缩略图流）
  * - GET|POST|DELETE credentials（describe/set/unset，值永不回传）
  * - GET providers（协议 registry + 参数目录，前端表单依据）
  * @module image-studio/api
@@ -12,6 +13,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type { GenerateRequest } from './dto.ts'
 import { ImageStudioError, statusOfCode } from './errors.ts'
+import { detectImageMime, mimeOfExt } from './images/mime.ts'
+import { UPLOAD_MAX_BYTES } from './limits.ts'
 import { PARAM_CATALOG } from './params/catalog.ts'
 import { ParamValidationError } from './params/spec.ts'
 import { listProtocols } from './provider/registry.ts'
@@ -19,6 +22,9 @@ import type { ImageStudioService } from './service.ts'
 
 const ROUTE_PREFIX = '/dsh-plus/image-studio'
 
+/** 上传文件名长度上限（仅展示用途，超长截断）。 */
+const UPLOAD_NAME_MAX = 200
+
 function sendJson(res: ServerResponse, status: number, body: unknown): void {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
   res.end(JSON.stringify(body))
@@ -33,6 +39,32 @@ function readBody(req: IncomingMessage): Promise<string> {
   })
 }
 
+/**
+ * 读取二进制请求体（上传通道）：超限即中止并抛 upload-too-large。
+ * 限额内的字节在内存中聚合（魔数嗅探需完整头部判定，单文件 ≤50MB；
+ * 超限后不再累积，内存占用有界）。导出供单测用小限额直接驱动。
+ */
+export function readBinaryBody(
+  req: IncomingMessage,
+  maxBytes: number = UPLOAD_MAX_BYTES,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > maxBytes) {
+        // 不 destroy：让调用方统一结束响应（后续 data 事件继续被丢弃）。
+        reject(new ImageStudioError('upload-too-large', `文件超过 ${maxBytes} 字节上限`))
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks)))
+    req.on('error', reject)
+  })
+}
+
 /** 统一错误结算：ImageStudioError/ParamValidationError 按码映射，其余 500。 */
 function sendError(res: ServerResponse, error: unknown): void {
   if (error instanceof ImageStudioError) {
@@ -50,7 +82,15 @@ function sendError(res: ServerResponse, error: unknown): void {
 }
 
 /** 端点处理函数表（path 段 → handler）。 */
-type Handler = (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<void>
+type Handler = (req: IncomingMessage, res: ServerResponse, rest: string, url: URL) => Promise<void>
+
+/** 上传文件名（query 参数，仅展示用）：去控制字符并截断。 */
+function uploadNameOf(url: URL): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: 清洗用户文件名中的控制字符
+  const raw = (url.searchParams.get('name') ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  if (raw === '') return 'upload'
+  return raw.slice(0, UPLOAD_NAME_MAX)
+}
 
 function buildHandlers(service: ImageStudioService): Record<string, Handler> {
   return {
@@ -128,10 +168,50 @@ function buildHandlers(service: ImageStudioService): Record<string, Handler> {
         sendJson(res, 404, { error: 'not-found' })
         return
       }
-      const mime = bytes.ext === 'jpg' ? 'image/jpeg' : `image/${bytes.ext}`
+      const mime = mimeOfExt(bytes.ext)
       res.writeHead(200, { 'content-type': mime, 'cache-control': 'private, max-age=3600' })
       res.end(Buffer.from(bytes.data))
     },
+    async uploads(req, res, rest, url) {
+      // POST /uploads（raw body 流，query 携带原文件名）；GET /uploads 列表；
+      // GET /uploads/<id> 缩略图流（源图预览，与 images 同构）。
+      const uploadId = rest.replace(/\/$/, '')
+      if (method(req) === 'POST') {
+        if (uploadId !== '') throw new ImageStudioError('invalid-request', '未知路径')
+        const data = new Uint8Array(await readBinaryBody(req))
+        // 魔数嗅探：不信任声明的 content-type，非白名单位图一律拒绝。
+        const mime = detectImageMime(data)
+        if (mime === null) {
+          throw new ImageStudioError('unsupported-media', '只支持 PNG/JPEG/WebP/GIF 图片')
+        }
+        const entry = await service.saveUpload({
+          name: uploadNameOf(url),
+          mime,
+          data,
+        })
+        sendJson(res, 201, entry)
+        return
+      }
+      if (method(req) !== 'GET') {
+        sendJson(res, 405, { error: 'GET or POST only' })
+        return
+      }
+      if (uploadId === '') {
+        const items = await service.listUploads()
+        sendJson(res, 200, { items, total: items.length })
+        return
+      }
+      const bytes = await service.uploadBytes(uploadId)
+      if (bytes === null) {
+        sendJson(res, 404, { error: 'not-found' })
+        return
+      }
+      res.writeHead(200, {
+        'content-type': mimeOfExt(bytes.ext),
+        'cache-control': 'private, max-age=3600',
+      })
+      res.end(Buffer.from(bytes.data))
+    },
     async credentials(_req, res, rest) {
       const refName = rest.replace(/\/$/, '')
       if (refName.length === 0) {
@@ -206,7 +286,7 @@ export function registerImageStudioApi(ctx: Context, service: ImageStudioService
           sendJson(res, 404, { error: `unknown endpoint: ${head}` })
           return
         }
-        await handler(req, res, rest)
+        await handler(req, res, rest, url)
       })().catch((error: unknown) => sendError(res, error))
     },
   })

package/src/client/api.ts

@@ -13,6 +13,7 @@ import type {
   PresetsWire,
   ProvidersWire,
   TaskWire,
+  UploadEntry,
 } from '../dto.ts'
 
 const BASE = '/dsh-plus/image-studio'
@@ -60,6 +61,30 @@ export function imageUrl(imageId: string): string {
   return `${BASE}/images/${imageId}`
 }
 
+/** 上传原图 URL（缩略图直连，非 fetch）。 */
+export function uploadImageUrl(uploadId: string): string {
+  return `${BASE}/uploads/${uploadId}`
+}
+
+/** 上传本地图片：raw body 流（query 携带原文件名，仅展示用）。 */
+export async function uploadImage(file: File): Promise<UploadEntry> {
+  const query = new URLSearchParams({ name: file.name })
+  const res = await fetch(`${BASE}/uploads?${query.toString()}`, {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'content-type': 'application/octet-stream' },
+    body: file,
+  })
+  const body = (await res.json()) as UploadEntry & { error?: string; message?: string }
+  if (!res.ok) throw new Error(body.message ?? body.error ?? `HTTP ${res.status}`)
+  return body
+}
+
+/** 上传列表（最新在后；界面自行倒序）。 */
+export async function fetchUploads(): Promise<{ items: UploadEntry[]; total: number }> {
+  return getJson(`${BASE}/uploads`)
+}
+
 /** 凭据状态（describe，永不回传值）。 */
 export function fetchCredentialStatus(refName: string): Promise<CredentialStatusWire> {
   return getJson(`${BASE}/credentials/${refName}`)

package/src/client/card.tsx

@@ -59,6 +59,7 @@ interface Draft {
   requestTimeoutMs: string
   proxy: string
   galleryMaxItems: string
+  uploadTtlHours: string
 }
 
 /** 配置值 → 编辑草稿。 */
@@ -83,6 +84,7 @@ function draftOf(value: ImageStudioConfig): Draft {
     requestTimeoutMs: String(value.requestTimeoutMs),
     proxy: value.proxy,
     galleryMaxItems: String(value.galleryMaxItems),
+    uploadTtlHours: String(value.uploadTtlHours),
   }
 }
 
@@ -122,6 +124,7 @@ function payloadOf(draft: Draft): Record<string, unknown> {
     requestTimeoutMs: Math.max(10_000, Math.floor(Number(draft.requestTimeoutMs) || 300_000)),
     proxy: draft.proxy,
     galleryMaxItems: Math.max(0, Math.floor(Number(draft.galleryMaxItems) || 0)),
+    uploadTtlHours: Math.max(1, Math.floor(Number(draft.uploadTtlHours) || 24)),
   }
 }
 
@@ -579,6 +582,15 @@ export function StudioConfigCard(props: CardProps): ReactElement | null {
           onEdit={(v) => patch({ galleryMaxItems: v })}
         />
       </div>
+      <TextField
+        prefix="imsc"
+        id="imsc-upload-ttl"
+        label={t('card.uploadTtlHours')}
+        numeric
+        value={draft.uploadTtlHours}
+        disabled={disabled}
+        onEdit={(v) => patch({ uploadTtlHours: v })}
+      />
     </CardChrome>
   )
 }

package/src/client/i18n.ts

@@ -58,8 +58,15 @@ export const zh = {
   'sources.mask': '遮罩（可选）',
   'sources.maskPick': '选择遮罩',
   'sources.maskClear': '清除',
+  'sources.maskHint': '遮罩必须是与源图同尺寸的 PNG（透明区域为可重绘范围）',
+  'sources.uploaded': '本地文件上传',
+  'upload.pick': '上传图片',
+  'upload.empty': '暂无上传图片，点上方「上传图片」从本地选择',
+  'upload.failed': '上传失败：',
   'picker.empty': '画廊暂无图片',
   'picker.confirm': '使用所选（{n}）',
+  'picker.section.gallery': '画廊',
+  'picker.section.uploads': '本地上传',
   // 提交
   'generate.submit': '生成',
   'generate.submitted': '已提交任务 {id}，进度见下方任务条',
@@ -114,6 +121,7 @@ export const zh = {
   'card.requestTimeoutMs': '单请求超时（毫秒）',
   'card.proxy': '上游代理（空 = 直连）',
   'card.galleryMaxItems': '画廊保留上限（0 = 不清理）',
+  'card.uploadTtlHours': '上传原图保留时长（小时）',
   'card.specsInvalid': '参数表非法：',
   'card.idInvalid': 'ID 非法：',
   'card.save': '保存',
@@ -176,8 +184,16 @@ export const en: Record<DictKey, string> = {
   'sources.mask': 'Mask (optional)',
   'sources.maskPick': 'Pick mask',
   'sources.maskClear': 'Clear',
+  'sources.maskHint':
+    'The mask must be a PNG the same size as the source (transparent area is repainted)',
+  'sources.uploaded': 'Uploaded from disk',
+  'upload.pick': 'Upload image',
+  'upload.empty': 'No uploads yet — use "Upload image" above to pick a local file',
+  'upload.failed': 'Upload failed: ',
   'picker.empty': 'No images in the gallery yet',
   'picker.confirm': 'Use selected ({n})',
+  'picker.section.gallery': 'Gallery',
+  'picker.section.uploads': 'Uploads',
   'generate.submit': 'Generate',
   'generate.submitted': 'Task {id} submitted; progress in the task bar below',
   'generate.failed': 'Submit failed: ',
@@ -229,6 +245,7 @@ export const en: Record<DictKey, string> = {
   'card.requestTimeoutMs': 'Request timeout (ms)',
   'card.proxy': 'Upstream proxy (empty = direct)',
   'card.galleryMaxItems': 'Gallery retention (0 = keep all)',
+  'card.uploadTtlHours': 'Upload retention (hours)',
   'card.specsInvalid': 'Invalid param specs: ',
   'card.idInvalid': 'Invalid ID: ',
   'card.save': 'Save',

package/src/client/panel/controller.ts

@@ -5,13 +5,15 @@
  * @module image-studio/client/panel/controller
  */
 
+import type { SourceRef } from '../../dto.ts'
+
 /** 面板标签页。 */
 export type StudioTab = 'generation' | 'edit' | 'gallery'
 
 /** 二次编辑种子（画廊条目 → 图生图表单回填）。 */
 export interface EditSeed {
-  /** 源图 imageId 列表（≤16）。 */
-  sourceIds: string[]
+  /** 源图引用（≤16；画廊图片与本地上传混用）。 */
+  sources: SourceRef[]
   /** 历史提示词回填。 */
   prompt: string
   /** 历史请求参数回填（画廊条目 params 快照）。 */

package/src/client/panel/gallery.tsx

@@ -7,7 +7,7 @@ import { Modal } from '@deepseek-ai/dsh-client-ui-primitives'
 import { IconDownload, IconRefreshOutline16, IconTrashOutline16 } from '@dsh-plus/shared/client'
 import { type ReactElement, useState } from 'react'
 import type { GalleryItem } from '../../gallery/store.ts'
-import { deleteGalleryItem, imageUrl } from '../api.ts'
+import { deleteGalleryItem, imageUrl, uploadImageUrl } from '../api.ts'
 import type { Translate } from '../i18n.ts'
 
 interface GalleryViewProps {
@@ -98,7 +98,7 @@ function GalleryDetail(props: {
           <div className="ims-detailInfo">
             <h4 className="ims-detailLabel">{t('gallery.detail.prompt')}</h4>
             <p className="ims-detailPrompt">{item.prompt}</p>
-            {item.sourceIds.length > 0 ? (
+            {item.sourceIds.length + item.sourceUploads.length > 0 ? (
               <>
                 <h4 className="ims-detailLabel">{t('gallery.detail.sources')}</h4>
                 <div className="ims-sources">
@@ -107,6 +107,11 @@ function GalleryDetail(props: {
                       <img src={imageUrl(imageId)} alt="" />
                     </span>
                   ))}
+                  {item.sourceUploads.map((uploadId) => (
+                    <span key={uploadId} className="ims-thumb" title={t('sources.uploaded')}>
+                      <img src={uploadImageUrl(uploadId)} alt="" />
+                    </span>
+                  ))}
                 </div>
               </>
             ) : null}

package/src/client/panel/generator.tsx

@@ -3,19 +3,25 @@
  * - 提供商预设选择 + 凭据状态徽标 + inline 覆盖（凭据沿用预设）；
  * - 提示词编辑 + 预设插入/另存；
  * - 目录驱动的参数表单 + 参数预设应用/另存；
- * - 图生图追加源图（≤16）与可选遮罩选择（画廊取图）；
+ * - 图生图追加源图（≤16，画廊选择与本地文件上传混用）与可选遮罩；
  * - 提交 generate → 202 taskId 交由面板任务条轮询。
  * 预设另存走 settings RPC（scope/api 注入），成功后经 onPresetSaved 刷新快照。
  * @module image-studio/client/panel/generator
  */
-import { IconLayers, type NamespaceSettingsApi, type Scope } from '@dsh-plus/shared/client'
+import {
+  IconLayers,
+  IconPlusOutline16,
+  type NamespaceSettingsApi,
+  type Scope,
+} from '@dsh-plus/shared/client'
 import { type ReactElement, useEffect, useMemo, useRef, useState } from 'react'
-import type { GenerateRequest, PresetsWire, ProvidersWire } from '../../dto.ts'
+import type { GenerateRequest, PresetsWire, ProvidersWire, SourceRef } from '../../dto.ts'
 import type { GalleryItem } from '../../gallery/store.ts'
+import { MAX_SOURCE_IMAGES } from '../../limits.ts'
 import type { ParamEntry } from '../../params/catalog.ts'
 import { type ParamSpecMap, validateParamSpecs } from '../../params/spec.ts'
 import type { ImageEndpoint } from '../../provider/types.ts'
-import { fetchCredentialStatus, generate, imageUrl } from '../api.ts'
+import { fetchCredentialStatus, generate } from '../api.ts'
 import type { Translate } from '../i18n.ts'
 import type { EditSeed } from './controller.ts'
 import {
@@ -26,7 +32,8 @@ import {
   type ParamFormState,
 } from './param-state.ts'
 import { ParamsForm } from './params-form.tsx'
-import { ImagePicker } from './picker.tsx'
+import { ImagePicker, refUrl } from './picker.tsx'
+import { UploadButton, useUploads } from './uploads.tsx'
 
 interface GeneratorProps {
   t: Translate
@@ -71,8 +78,8 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
   const [credentialOk, setCredentialOk] = useState<boolean | null>(null)
   const [prompt, setPrompt] = useState('')
   const [form, setForm] = useState<ParamFormState>({})
-  const [sourceIds, setSourceIds] = useState<string[]>([])
-  const [maskId, setMaskId] = useState<string | null>(null)
+  const [sources, setSources] = useState<SourceRef[]>([])
+  const [mask, setMask] = useState<SourceRef | null>(null)
   const [picker, setPicker] = useState<'sources' | 'mask' | null>(null)
   const [naming, setNaming] = useState<{ kind: 'prompt' | 'params'; name: string } | null>(null)
   const [status, setStatus] = useState<Status>(IDLE)
@@ -81,6 +88,7 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
   const formReadyRef = useRef(false)
   /** 已消费的种子 nonce（防重复回填）。 */
   const seedRef = useRef(0)
+  const uploads = useUploads()
 
   // 目录到达后初始化参数表单。
   useEffect(() => {
@@ -95,7 +103,7 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
     if (seed === null || seed.nonce === seedRef.current || !formReadyRef.current) return
     seedRef.current = seed.nonce
     setPrompt(seed.prompt)
-    setSourceIds(seed.sourceIds)
+    setSources(seed.sources)
     setForm(applyParams(catalog, endpoint, seed.params))
     if (seed.providerPresetId !== null) setProviderId(seed.providerPresetId)
     setStatus(IDLE)
@@ -208,7 +216,7 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
       setStatus({ kind: 'error', text: t('generate.needPrompt') })
       return
     }
-    if (endpoint === 'edit' && sourceIds.length === 0) {
+    if (endpoint === 'edit' && sources.length === 0) {
       setStatus({ kind: 'error', text: t('generate.needSources') })
       return
     }
@@ -233,8 +241,8 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
       }
     }
     if (endpoint === 'edit') {
-      request.sourceIds = sourceIds
-      if (maskId !== null) request.maskId = maskId
+      request.sources = sources
+      if (mask !== null) request.mask = mask
     }
     setSubmitting(true)
     setStatus(IDLE)
@@ -379,39 +387,68 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
           <section className="ims-block">
             <h3 className="ims-blockTitle">{t('sources.label')}</h3>
             <div className="ims-sources">
-              {sourceIds.map((imageId) => (
-                <span key={imageId} className="ims-thumb">
-                  <img src={imageUrl(imageId)} alt="" />
+              {sources.map((ref) => (
+                <span key={`${ref.kind}:${ref.id}`} className="ims-thumb">
+                  <img src={refUrl(ref)} alt="" />
                   <button
                     type="button"
                     className="ims-thumbRemove"
                     aria-label={t('common.delete')}
                     onClick={() =>
-                      setSourceIds((current) => current.filter((id) => id !== imageId))
+                      setSources((current) =>
+                        current.filter((item) => !(item.kind === ref.kind && item.id === ref.id)),
+                      )
                     }
                   >
                     ×
                   </button>
                 </span>
               ))}
-              <button type="button" className="ims-thumbAdd" onClick={() => setPicker('sources')}>
+              <button
+                type="button"
+                className="ims-thumbAdd"
+                disabled={sources.length >= MAX_SOURCE_IMAGES}
+                onClick={() => setPicker('sources')}
+              >
                 <IconLayers size={18} />
                 <span>{t('sources.pick')}</span>
               </button>
+              <UploadButton
+                t={t}
+                uploads={uploads}
+                multiple
+                disabled={sources.length >= MAX_SOURCE_IMAGES}
+                className="ims-thumbAdd"
+                onUploaded={(entries) =>
+                  setSources((current) =>
+                    [
+                      ...current,
+                      ...entries.map((entry) => ({ kind: 'upload' as const, id: entry.id })),
+                    ].slice(0, MAX_SOURCE_IMAGES),
+                  )
+                }
+              >
+                <IconPlusOutline16 size={18} />
+                <span>{t('upload.pick')}</span>
+              </UploadButton>
             </div>
-            <p className="ims-hint">
-              {t('sources.count').replace('{n}', String(sourceIds.length))}
-            </p>
+            <p className="ims-hint">{t('sources.count').replace('{n}', String(sources.length))}</p>
+            {uploads.error !== null ? (
+              <p className="ims-status ims-statusError" role="alert">
+                {t('upload.failed')}
+                {uploads.error}
+              </p>
+            ) : null}
             <h3 className="ims-blockTitle">{t('sources.mask')}</h3>
             <div className="ims-sources">
-              {maskId !== null ? (
+              {mask !== null ? (
                 <span className="ims-thumb">
-                  <img src={imageUrl(maskId)} alt="" />
+                  <img src={refUrl(mask)} alt="" />
                   <button
                     type="button"
                     className="ims-thumbRemove"
                     aria-label={t('sources.maskClear')}
-                    onClick={() => setMaskId(null)}
+                    onClick={() => setMask(null)}
                   >
                     ×
                   </button>
@@ -422,6 +459,7 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
                 <span>{t('sources.maskPick')}</span>
               </button>
             </div>
+            <p className="ims-hint">{t('sources.maskHint')}</p>
           </section>
         ) : null}
       </div>
@@ -506,11 +544,12 @@ export function GeneratorForm(props: GeneratorProps): ReactElement {
           t={t}
           title={t(picker === 'sources' ? 'sources.label' : 'sources.mask')}
           items={gallery}
+          uploads={uploads}
           multiple={picker === 'sources'}
-          initial={picker === 'sources' ? sourceIds : []}
-          onConfirm={(ids) => {
-            if (picker === 'sources') setSourceIds(ids)
-            else setMaskId(ids[0] ?? null)
+          initial={picker === 'sources' ? sources : mask === null ? [] : [mask]}
+          onConfirm={(refs) => {
+            if (picker === 'sources') setSources(refs)
+            else setMask(refs[0] ?? null)
             setPicker(null)
           }}
           onClose={() => setPicker(null)}

package/src/client/panel/panel.tsx

@@ -188,7 +188,10 @@ export function StudioPanel(props: StudioPanelProps): ReactElement | null {
             onRefresh={reloadGallery}
             onEdit={(item) =>
               studio.seedEdit({
-                sourceIds: [...item.imageIds],
+                sources: [
+                  ...item.imageIds.map((id) => ({ kind: 'gallery' as const, id })),
+                  ...item.sourceUploads.map((id) => ({ kind: 'upload' as const, id })),
+                ],
                 prompt: item.prompt,
                 params: item.params,
                 providerPresetId: item.providerPresetId,

package/src/client/panel/params-form.tsx

@@ -2,11 +2,13 @@
  * 参数表单：按参数目录动态渲染（kind → 控件形态，advanced 折叠）。
  * - boolean 参数的开关即取值（启用 = true）；
  * - 其余参数：开关 + 值控件（enum 下拉 / integer 数字框 / string 文本框）；
+ * - 声明了结构化规则的参数（size）追加预设快捷项与即时校验提示，自由输入不受限；
  * - 每项附中文说明与代际标记（GPT Image / dall-e-3 / dall-e-2）。
  * @module image-studio/client/panel/params-form
  */
 import type { ReactElement } from 'react'
 import type { ParamEntry } from '../../params/catalog.ts'
+import { checkImageSize, SIZE_PRESETS } from '../../params/size.ts'
 import type { ImageEndpoint } from '../../provider/types.ts'
 import type { Translate } from '../i18n.ts'
 import { type ParamFormState, paramEntriesFor } from './param-state.ts'
@@ -19,7 +21,14 @@ interface ParamsFormProps {
   onChange(next: ParamFormState): void
 }
 
-/** 单参数行：开关 + 名称/说明 + 值控件。 */
+/** 结构化规则的即时提示：规则通过或取值未填时不占位。 */
+function ruleHint(entry: ParamEntry, value: string): string | null {
+  if (entry.rules !== 'image-size' || value.trim() === '') return null
+  const checked = checkImageSize(value)
+  return checked.ok ? null : checked.message
+}
+
+/** 单参数行：开关 + 名称/说明 + 值控件（+ 预设与校验提示）。 */
 function ParamRow(props: {
   t: Translate
   entry: ParamEntry
@@ -30,6 +39,10 @@ function ParamRow(props: {
   const field = form[entry.key] ?? { enabled: false, value: '' }
   const patch = (next: Partial<typeof field>): void =>
     onChange({ ...form, [entry.key]: { ...field, ...next } })
+  const text = String(field.value)
+  const hint = field.enabled ? ruleHint(entry, text) : null
+  /** size 预设：快捷填写，仍可自由改动输入框。 */
+  const presets = entry.rules === 'image-size' ? SIZE_PRESETS : []
 
   const control = (() => {
     if (entry.kind === 'boolean') return null
@@ -37,7 +50,7 @@ function ParamRow(props: {
       return (
         <select
           className="ims-input ims-paramControl"
-          value={String(field.value)}
+          value={text}
           disabled={!field.enabled}
           onChange={(event) => patch({ value: event.target.value })}
         >
@@ -57,7 +70,7 @@ function ParamRow(props: {
           inputMode="numeric"
           min={entry.min}
           max={entry.max}
-          value={String(field.value)}
+          value={text}
           disabled={!field.enabled}
           onChange={(event) => patch({ value: event.target.value })}
         />
@@ -65,10 +78,12 @@ function ParamRow(props: {
     }
     return (
       <input
-        className="ims-input ims-paramControl"
+        className={`ims-input ims-paramControl${hint !== null ? ' ims-inputInvalid' : ''}`}
         type="text"
-        value={String(field.value)}
+        list={presets.length > 0 ? `ims-size-options-${entry.key}` : undefined}
+        value={text}
         disabled={!field.enabled}
+        aria-invalid={hint !== null}
         onChange={(event) => patch({ value: event.target.value })}
       />
     )
@@ -99,8 +114,37 @@ function ParamRow(props: {
           ) : null}
         </span>
         <span className="ims-paramDesc">{entry.description}</span>
+        {hint !== null ? (
+          <span className="ims-paramWarn" role="alert">
+            {hint}
+          </span>
+        ) : null}
+      </div>
+      <div className="ims-paramValue">
+        {control}
+        {presets.length > 0 && field.enabled ? (
+          <span className="ims-paramPresets">
+            {presets.map((preset) => (
+              <button
+                key={preset.value}
+                type="button"
+                title={preset.label}
+                className={`ims-chip${preset.value === text ? ' ims-chipOn' : ''}`}
+                onClick={() => patch({ value: preset.value })}
+              >
+                {preset.value}
+              </button>
+            ))}
+          </span>
+        ) : null}
       </div>
-      {control}
+      {presets.length > 0 ? (
+        <datalist id={`ims-size-options-${entry.key}`}>
+          {presets.map((preset) => (
+            <option key={preset.value} value={preset.value} label={preset.label} />
+          ))}
+        </datalist>
+      ) : null}
     </div>
   )
 }