dsh-draw 0.1.0

package/src/client/present.ts

@@ -0,0 +1,137 @@
+/**
+ * Pure presentation projections for the dsh-draw browser half: the tool
+ * result value and the settings snapshot are folded into view models that the
+ * React components render without further logic. Everything here is a pure
+ * function of its input, so tests pin the projections without a DOM.
+ *
+ * @module dsh-draw/client/present
+ */
+
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { DrawStatusSnapshot } from '../wire.ts'
+
+/** One image of the presented result card. */
+export interface PresentedImage {
+  attachmentId: string
+  name: string
+}
+
+/** The presented result card model. */
+export interface PresentedDrawResult {
+  /** Engine id that produced the images. */
+  engine: string
+  /** Engine model name. */
+  model: string
+  /** Whether an earlier engine failed first. */
+  fallbackUsed: boolean
+  /** Image names in result order. */
+  images: readonly PresentedImage[]
+  /** Quota line: generations and bytes used. */
+  quota: { generations: number; bytes: number }
+  /** Effective limits. */
+  limits: { maxGenerations: number; maxBytes: number }
+  /** Original tool args (the regenerate input); undefined while unknown. */
+  args: Record<string, unknown> | undefined
+}
+
+/**
+ * Project one settled `image_generate` tool block onto the card model.
+ *
+ * @param block - the frozen tool-call block (running or settled).
+ * @returns the presented model, or `undefined` when the block is not a settled
+ *   image_generate result.
+ */
+export function presentDrawResult(block: ToolCallBlock): PresentedDrawResult | undefined {
+  if (!('kind' in block) || block.kind !== 'tool-result' || block.isError) return undefined
+  if (block.call?.name !== 'image_generate') return undefined
+  const value = (block.meta as { engine?: unknown; model?: unknown; fallbackUsed?: unknown; images?: unknown; quota?: unknown; limits?: unknown } | undefined) ?? {}
+  const images: PresentedImage[] = []
+  if (Array.isArray(value.images)) {
+    for (const raw of value.images) {
+      const image = raw as { attachmentId?: unknown; name?: unknown }
+      if (typeof image?.attachmentId === 'string') {
+        images.push({ attachmentId: image.attachmentId, name: typeof image.name === 'string' ? image.name : 'image' })
+      }
+    }
+  }
+  const quota = (value.quota ?? {}) as { generations?: unknown; bytes?: unknown }
+  const limits = (value.limits ?? {}) as { maxGenerations?: unknown; maxBytes?: unknown }
+  let args: Record<string, unknown> | undefined
+  if (block.call?.argsRaw !== undefined && block.call.argsRaw !== '') {
+    try {
+      const parsed = JSON.parse(block.call.argsRaw) as unknown
+      args = typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : undefined
+    } catch {
+      args = undefined
+    }
+  }
+  return {
+    engine: typeof value.engine === 'string' ? value.engine : 'unknown',
+    model: typeof value.model === 'string' ? value.model : 'unknown',
+    fallbackUsed: value.fallbackUsed === true,
+    images,
+    quota: {
+      generations: typeof quota.generations === 'number' ? quota.generations : 0,
+      bytes: typeof quota.bytes === 'number' ? quota.bytes : 0,
+    },
+    limits: {
+      maxGenerations: typeof limits.maxGenerations === 'number' ? limits.maxGenerations : 0,
+      maxBytes: typeof limits.maxBytes === 'number' ? limits.maxBytes : 0,
+    },
+    args,
+  }
+}
+
+/** One engine row of the presented settings panel. */
+export interface PresentedEngineRow {
+  id: string
+  model: string
+  baseUrl: string
+  apiKeyRef: string
+  enabled: boolean
+  preferred: boolean
+  credentialConfigured: boolean
+  credentialSource?: string
+  credentialWritable: boolean
+  consecutiveFailures: number
+  coolingDown: boolean
+  lastError: string | null
+}
+
+/** The presented settings snapshot. */
+export interface PresentedDrawPanel {
+  pluginVersion: string
+  engines: readonly PresentedEngineRow[]
+  quota: { maxGenerationsPerSession: number; maxBytesPerSession: number }
+  requestTimeoutMs: number
+  maxImagesPerCall: number
+}
+
+/**
+ * Project the panel snapshot onto the settings row model.
+ *
+ * @param snapshot - the `draw/status` wire snapshot.
+ * @returns the presented panel model.
+ */
+export function presentDrawPanel(snapshot: DrawStatusSnapshot): PresentedDrawPanel {
+  return {
+    pluginVersion: snapshot.pluginVersion,
+    engines: snapshot.engines.map(engine => ({
+      id: engine.id,
+      model: engine.model,
+      baseUrl: engine.baseUrl,
+      apiKeyRef: engine.apiKeyRef,
+      enabled: engine.enabled,
+      preferred: engine.preferred,
+      credentialConfigured: engine.credential.configured,
+      ...(engine.credential.source !== undefined ? { credentialSource: engine.credential.source } : {}),
+      credentialWritable: engine.credential.writable,
+      consecutiveFailures: engine.health.consecutiveFailures,
+      coolingDown: engine.health.cooldownUntil !== null && engine.health.cooldownUntil > Date.now(),
+      lastError: engine.health.lastError,
+    })),
+    quota: { maxGenerationsPerSession: snapshot.quota.maxGenerationsPerSession, maxBytesPerSession: snapshot.quota.maxBytesPerSession },
+    requestTimeoutMs: snapshot.requestTimeoutMs,
+    maxImagesPerCall: snapshot.maxImagesPerCall,
+  }
+}

package/src/client/remote.ts

@@ -0,0 +1,44 @@
+/**
+ * The client-side Remote face of the `draw` namespace: the hand-written
+ * `TypertRemoteContribution` mounted through `ctx.remote.$mount`, plus the
+ * declaration merging that types `ctx.remote.draw`. The descriptor list is
+ * shared with the host `./typert` manifest (`../wire.ts`), so the two faces
+ * can never drift.
+ *
+ * @module dsh-draw/client/remote
+ */
+
+import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
+import { DRAW_INVOCATIONS } from '../wire.ts'
+import type { CredentialActionResult, DrawProbeResult, DrawRegenerateResult, DrawStatusSnapshot } from '../wire.ts'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface TypertRemoteNamespace$draw {
+    /** Read the panel snapshot (engines, health, credentials, quota). */
+    status: () => Promise<RemoteResult<DrawStatusSnapshot>>
+    /** Probe one engine's connectivity. */
+    probe: (engineId: string) => Promise<RemoteResult<DrawProbeResult>>
+    /** Store one API key under the engine's credential reference. */
+    setCredential: (engineId: string, value: string) => Promise<RemoteResult<CredentialActionResult>>
+    /** Remove a stored API key. */
+    unsetCredential: (engineId: string) => Promise<RemoteResult<CredentialActionResult>>
+    /** Re-run a generation from the result card (full drawer path). */
+    regenerate: (sessionId: string, args: Record<string, unknown>) => Promise<RemoteResult<DrawRegenerateResult>>
+  }
+  interface TypertRemoteMap {
+    'draw/status': () => Promise<RemoteResult<DrawStatusSnapshot>>
+    'draw/probe': (engineId: string) => Promise<RemoteResult<DrawProbeResult>>
+    'draw/setCredential': (engineId: string, value: string) => Promise<RemoteResult<CredentialActionResult>>
+    'draw/unsetCredential': (engineId: string) => Promise<RemoteResult<CredentialActionResult>>
+    'draw/regenerate': (sessionId: string, args: Record<string, unknown>) => Promise<RemoteResult<DrawRegenerateResult>>
+  }
+  interface TypertRemoteNamespaceMap {
+    draw: TypertRemoteNamespace$draw
+  }
+}
+
+/** The client Remote contribution for the `draw` namespace. */
+export const DRAW_REMOTE = Object.freeze({
+  package: 'dsh-draw',
+  descriptors: DRAW_INVOCATIONS,
+} satisfies TypertRemoteContribution)

package/src/client/styles.ts

@@ -0,0 +1,44 @@
+/**
+ * Scoped inline stylesheet for the dsh-draw browser half. Standalone client
+ * bundles cannot use the in-repo CSS-module pipeline, so the styles live in
+ * one scoped `style` element; every class carries the `dshdraw-` prefix and
+ * the root node is the only position the stylesheet may leak from.
+ *
+ * @module dsh-draw/client/styles
+ */
+
+const STYLE_ID = 'dsh-draw-client-styles'
+
+/** Install the scoped stylesheet once; returns the removal disposer. */
+export function installDrawStyles(): () => void {
+  if (document.getElementById(STYLE_ID) !== null) return () => undefined
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+.dshdraw-card { display: flex; flex-direction: column; gap: 8px; padding: 4px 0; }
+.dshdraw-grid { display: flex; flex-wrap: wrap; gap: 8px; }
+.dshdraw-figure { display: flex; flex-direction: column; gap: 4px; max-width: 320px; }
+.dshdraw-figure img { max-width: 100%; border-radius: 6px; border: 1px solid var(--dsh-border, #d0d7de); }
+.dshdraw-figure figcaption { font-size: 11px; opacity: 0.75; overflow-wrap: anywhere; }
+.dshdraw-meta { font-size: 12px; opacity: 0.85; display: flex; flex-wrap: wrap; gap: 12px; }
+.dshdraw-actions { display: flex; gap: 8px; }
+.dshdraw-button {
+  border: 1px solid var(--dsh-border, #d0d7de); border-radius: 6px; background: transparent;
+  padding: 3px 10px; font-size: 12px; cursor: pointer; color: inherit;
+}
+.dshdraw-button:hover { background: var(--dsh-hover, rgba(0, 0, 0, 0.05)); }
+.dshdraw-panel { display: flex; flex-direction: column; gap: 14px; }
+.dshdraw-engine { border: 1px solid var(--dsh-border, #d0d7de); border-radius: 8px; padding: 10px 12px; display: flex; flex-direction: column; gap: 6px; }
+.dshdraw-engine h4 { margin: 0; }
+.dshdraw-row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; font-size: 12px; }
+.dshdraw-row label { opacity: 0.8; min-width: 110px; }
+.dshdraw-badge { border-radius: 999px; padding: 1px 8px; font-size: 11px; border: 1px solid var(--dsh-border, #d0d7de); }
+.dshdraw-badge.ok { color: #1a7f37; border-color: #1a7f37; }
+.dshdraw-badge.warn { color: #9a6700; border-color: #9a6700; }
+.dshdraw-input { flex: 1; min-width: 180px; border: 1px solid var(--dsh-border, #d0d7de); border-radius: 6px; padding: 4px 8px; font-size: 12px; background: transparent; color: inherit; }
+`
+  document.head.append(style)
+  return () => {
+    style.remove()
+  }
+}

package/src/config.ts

@@ -0,0 +1,358 @@
+/**
+ * Plugin configuration for `dsh-draw` and its explicit resolve step.
+ * `resolveConfig` re-judges every default and bound so programmatic
+ * construction that bypasses Schemastery normalization still fails loud
+ * instead of running with hidden defaults (the explicit-resolve contract).
+ *
+ * @module dsh-draw/config
+ */
+
+import z from '@deepseek-ai/schemastery'
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment'
+
+/** Default per-generation HTTP timeout in milliseconds. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 120_000
+
+/** Ceiling for one generation call: engines can take minutes per image. */
+export const MAX_REQUEST_TIMEOUT_MS = 600_000
+
+/** Default cap on images a single call may produce. */
+export const DEFAULT_MAX_IMAGES_PER_CALL = 4
+
+/** Ceiling on images a single call may produce. */
+export const MAX_IMAGES_PER_CALL = 10
+
+/** Default prompt length cap (characters). */
+export const DEFAULT_MAX_PROMPT_LENGTH = 4_000
+
+/** Ceiling on the prompt length cap. */
+export const MAX_PROMPT_LENGTH = 32_000
+
+/** Default per-session generation-call cap. */
+export const DEFAULT_MAX_GENERATIONS_PER_SESSION = 200
+
+/** Ceiling on the per-session generation-call cap. */
+export const MAX_GENERATIONS_PER_SESSION = 100_000
+
+/** Default per-session image-byte cap (200 MiB). */
+export const DEFAULT_MAX_BYTES_PER_SESSION = 200 * 1024 * 1024
+
+/** Ceiling on the per-session image-byte cap (4 GiB). */
+export const MAX_BYTES_PER_SESSION = 4 * 1024 * 1024 * 1024
+
+/** Default consecutive failures before an engine enters cooldown. */
+export const DEFAULT_FAILURE_THRESHOLD = 2
+
+/** Ceiling on the consecutive-failure threshold. */
+export const MAX_FAILURE_THRESHOLD = 10
+
+/** Default engine cooldown after the failure threshold trips (ms). */
+export const DEFAULT_COOLDOWN_MS = 60_000
+
+/** Ceiling on the engine cooldown. */
+export const MAX_COOLDOWN_MS = 3_600_000
+
+/** Standard size vocabulary mapped per engine through {@link EngineConfig.sizeMap}. */
+export type StandardSize = 'square' | 'landscape' | 'portrait' | 'auto'
+
+/** Per-engine mapping from the standard size vocabulary to concrete engine sizes. */
+export interface EngineSizeMap {
+  /** Square composition (the default). */
+  square: string
+  /** Wider-than-tall composition. */
+  landscape: string
+  /** Taller-than-wide composition. */
+  portrait: string
+  /** Engine-chosen composition; may alias one of the concrete sizes. */
+  auto: string
+}
+
+/** Whether generated images arrive as base64 payloads or downloadable URLs. */
+export type EngineResponseFormat = 'b64_json' | 'url'
+
+/** One OpenAI-compatible image-generation endpoint the router may use. */
+export interface EngineConfig {
+  /** Stable engine id used in tool args, results, and the settings panel. */
+  id: string
+  /** OpenAI-compatible API root, e.g. `https://api.openai.com/v1`; must not embed credentials. */
+  baseUrl: string
+  /** Engine model name sent in the request body, e.g. `gpt-image-1`. */
+  model: string
+  /** Credential reference (environment-variable name) the API key resolves from; never a literal key. */
+  apiKeyRef: string
+  /** Whether the router may use this engine (default true). */
+  enabled?: boolean
+  /** Standard-size → concrete-size translation (default: the OpenAI sizes). */
+  sizeMap?: EngineSizeMap
+  /** Whether the engine accepts the `quality` request field (default false). */
+  qualitySupported?: boolean
+  /** Whether the engine accepts the `style` request field (default false). */
+  styleSupported?: boolean
+  /** How generated bytes arrive: base64 in the response or a URL to download (default `b64_json`). */
+  responseFormat?: EngineResponseFormat
+  /** Declared media type of the bytes (default `image/png`). */
+  imageMediaType?: ImageMediaType
+}
+
+/** Plugin configuration. */
+export interface Config {
+  /** Ordered engine chain; the router walks it top-down and falls back on failure. */
+  engines?: EngineConfig[]
+  /** Engine id the router prefers; defaults to the first configured engine. Must name a configured engine. */
+  defaultEngine?: string
+  /** Per-generation HTTP timeout in milliseconds (default 120000). */
+  requestTimeoutMs?: number
+  /** Cap on images one call may produce (default 4). */
+  maxImagesPerCall?: number
+  /** Prompt length cap in characters (default 4000). */
+  maxPromptLength?: number
+  /** Per-session generation-call cap (default 200). */
+  maxGenerationsPerSession?: number
+  /** Per-session generated-image byte cap (default 209715200). */
+  maxBytesPerSession?: number
+  /** Consecutive failures before an engine enters cooldown (default 2). */
+  failureThreshold?: number
+  /** Engine cooldown in milliseconds after the failure threshold trips (default 60000). */
+  cooldownMs?: number
+}
+
+/** The two shipped engine presets: OpenAI Images and Zhipu CogView. */
+export const DEFAULT_ENGINES: ReadonlyArray<Required<EngineConfig>> = Object.freeze([
+  Object.freeze({
+    id: 'openai',
+    baseUrl: 'https://api.openai.com/v1',
+    model: 'gpt-image-1',
+    apiKeyRef: 'OPENAI_API_KEY',
+    enabled: true,
+    sizeMap: Object.freeze({ square: '1024x1024', landscape: '1536x1024', portrait: '1024x1536', auto: 'auto' }),
+    qualitySupported: true,
+    styleSupported: true,
+    responseFormat: 'b64_json',
+    imageMediaType: 'image/png',
+  }),
+  Object.freeze({
+    id: 'cogview',
+    baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+    model: 'cogview-3-flash',
+    apiKeyRef: 'ZHIPU_API_KEY',
+    enabled: true,
+    sizeMap: Object.freeze({ square: '1024x1024', landscape: '1344x768', portrait: '768x1344', auto: '1024x1024' }),
+    qualitySupported: false,
+    styleSupported: false,
+    responseFormat: 'url',
+    imageMediaType: 'image/png',
+  }),
+])
+
+/** Default size map for user-configured engines (the OpenAI vocabulary). */
+export const DEFAULT_SIZE_MAP: Readonly<EngineSizeMap> = Object.freeze({
+  square: '1024x1024',
+  landscape: '1536x1024',
+  portrait: '1024x1536',
+  auto: 'auto',
+})
+
+/** Fully resolved per-engine configuration. */
+export interface ResolvedEngineConfig {
+  /** Stable engine id. */
+  id: string
+  /** OpenAI-compatible API root without credentials. */
+  baseUrl: string
+  /** Engine model name. */
+  model: string
+  /** Credential reference the API key resolves from. */
+  apiKeyRef: string
+  /** Whether the router may use this engine. */
+  enabled: boolean
+  /** Standard-size → concrete-size translation. */
+  sizeMap: EngineSizeMap
+  /** Whether the engine accepts the `quality` request field. */
+  qualitySupported: boolean
+  /** Whether the engine accepts the `style` request field. */
+  styleSupported: boolean
+  /** How generated bytes arrive. */
+  responseFormat: EngineResponseFormat
+  /** Declared media type of the bytes. */
+  imageMediaType: ImageMediaType
+}
+
+/** Fully resolved configuration captured at plugin load. */
+export interface ResolvedConfig {
+  /** Ordered engine chain. */
+  engines: readonly ResolvedEngineConfig[]
+  /** Engine id the router prefers. */
+  defaultEngine: string
+  /** Per-generation HTTP timeout in milliseconds. */
+  requestTimeoutMs: number
+  /** Cap on images one call may produce. */
+  maxImagesPerCall: number
+  /** Prompt length cap in characters. */
+  maxPromptLength: number
+  /** Per-session generation-call cap. */
+  maxGenerationsPerSession: number
+  /** Per-session generated-image byte cap. */
+  maxBytesPerSession: number
+  /** Consecutive failures before an engine enters cooldown. */
+  failureThreshold: number
+  /** Engine cooldown in milliseconds after the failure threshold trips. */
+  cooldownMs: number
+}
+
+/** Schemastery schema for loader-validated configuration. */
+export const Config: z<Config> = z.object({
+  engines: z.array(z.object({
+    id: z.string().min(1).max(64),
+    baseUrl: z.string().min(1).max(2048),
+    model: z.string().min(1).max(128),
+    apiKeyRef: z.string().min(1).max(128),
+    enabled: z.boolean(),
+    sizeMap: z.object({
+      square: z.string().min(1).max(64),
+      landscape: z.string().min(1).max(64),
+      portrait: z.string().min(1).max(64),
+      auto: z.string().min(1).max(64),
+    }),
+    qualitySupported: z.boolean(),
+    styleSupported: z.boolean(),
+    responseFormat: z.union(['b64_json', 'url'] as const),
+    imageMediaType: z.union(['image/png', 'image/jpeg', 'image/webp', 'image/gif'] as const),
+  })).default([...DEFAULT_ENGINES]),
+  defaultEngine: z.string().min(1).max(64).default('openai'),
+  requestTimeoutMs: z.number().min(1_000).max(MAX_REQUEST_TIMEOUT_MS).default(DEFAULT_REQUEST_TIMEOUT_MS),
+  maxImagesPerCall: z.number().min(1).max(MAX_IMAGES_PER_CALL).default(DEFAULT_MAX_IMAGES_PER_CALL),
+  maxPromptLength: z.number().min(1).max(MAX_PROMPT_LENGTH).default(DEFAULT_MAX_PROMPT_LENGTH),
+  maxGenerationsPerSession: z.number().min(1).max(MAX_GENERATIONS_PER_SESSION).default(DEFAULT_MAX_GENERATIONS_PER_SESSION),
+  maxBytesPerSession: z.number().min(1024 * 1024).max(MAX_BYTES_PER_SESSION).default(DEFAULT_MAX_BYTES_PER_SESSION),
+  failureThreshold: z.number().min(1).max(MAX_FAILURE_THRESHOLD).default(DEFAULT_FAILURE_THRESHOLD),
+  cooldownMs: z.number().min(1_000).max(MAX_COOLDOWN_MS).default(DEFAULT_COOLDOWN_MS),
+})
+
+const ENGINE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u
+
+/** Credential references are environment-variable names (POSIX identifiers). */
+const API_KEY_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u
+
+/**
+ * Resolve raw config to the runtime policy, re-validating defaults and bounds
+ * plus the cross-field facts a per-field schema cannot see (duplicate engine
+ * ids, credential-bearing base URLs, an unknown default engine).
+ *
+ * @param config - raw loader config; `undefined` for a bare row.
+ * @returns the frozen resolved config.
+ * @throws on any invalid value (fail-loud at load).
+ */
+export function resolveConfig(config: Config | undefined): ResolvedConfig {
+  const rawEngines: readonly EngineConfig[] = config?.engines ?? DEFAULT_ENGINES
+  const engines: ResolvedEngineConfig[] = []
+  const seen = new Set<string>()
+  for (const engine of rawEngines) {
+    const id = typeof engine?.id === 'string' ? engine.id : ''
+    if (!ENGINE_ID_PATTERN.test(id)) {
+      throw new Error(`dsh-draw: engine id ${JSON.stringify(id)} must match ${ENGINE_ID_PATTERN}`)
+    }
+    if (seen.has(id)) throw new Error(`dsh-draw: duplicate engine id ${JSON.stringify(id)}`)
+    seen.add(id)
+    const baseUrl = engine.baseUrl ?? ''
+    let parsed: URL
+    try {
+      parsed = new URL(baseUrl)
+    } catch {
+      throw new Error(`dsh-draw: engine "${id}" baseUrl ${JSON.stringify(baseUrl)} is not a valid URL`)
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      throw new Error(`dsh-draw: engine "${id}" baseUrl must use http or https`)
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+      throw new Error(`dsh-draw: engine "${id}" baseUrl must not embed credentials — use the apiKeyRef credential reference instead`)
+    }
+    const model = typeof engine.model === 'string' && engine.model.length > 0 && engine.model.length <= 128 ? engine.model : ''
+    if (model === '') throw new Error(`dsh-draw: engine "${id}" model must be a non-empty string of at most 128 characters`)
+    const apiKeyRef = typeof engine.apiKeyRef === 'string' && API_KEY_REF_PATTERN.test(engine.apiKeyRef) ? engine.apiKeyRef : ''
+    if (apiKeyRef === '') throw new Error(`dsh-draw: engine "${id}" apiKeyRef ${JSON.stringify(engine.apiKeyRef)} must be an environment-variable name`)
+    const sizeMap = engine.sizeMap === undefined ? DEFAULT_SIZE_MAP : engine.sizeMap
+    for (const key of ['square', 'landscape', 'portrait', 'auto'] as const) {
+      const value = sizeMap[key]
+      if (typeof value !== 'string' || value.length === 0 || value.length > 64) {
+        throw new Error(`dsh-draw: engine "${id}" sizeMap.${key} must be a non-empty string of at most 64 characters`)
+      }
+    }
+    const enabled = engine.enabled ?? true
+    if (typeof enabled !== 'boolean') throw new TypeError(`dsh-draw: engine "${id}" enabled must be a boolean`)
+    const qualitySupported = engine.qualitySupported ?? false
+    if (typeof qualitySupported !== 'boolean') throw new TypeError(`dsh-draw: engine "${id}" qualitySupported must be a boolean`)
+    const styleSupported = engine.styleSupported ?? false
+    if (typeof styleSupported !== 'boolean') throw new TypeError(`dsh-draw: engine "${id}" styleSupported must be a boolean`)
+    const responseFormat = engine.responseFormat ?? 'b64_json'
+    if (responseFormat !== 'b64_json' && responseFormat !== 'url') {
+      throw new Error(`dsh-draw: engine "${id}" responseFormat must be "b64_json" or "url"`)
+    }
+    const imageMediaType = engine.imageMediaType ?? 'image/png'
+    if (imageMediaType !== 'image/png' && imageMediaType !== 'image/jpeg' && imageMediaType !== 'image/webp' && imageMediaType !== 'image/gif') {
+      throw new Error(`dsh-draw: engine "${id}" imageMediaType ${JSON.stringify(imageMediaType)} is not a supported raster type`)
+    }
+    engines.push({
+      id,
+      baseUrl: baseUrl.replace(/\/+$/u, ''),
+      model,
+      apiKeyRef,
+      enabled,
+      sizeMap: Object.freeze({ ...sizeMap }),
+      qualitySupported,
+      styleSupported,
+      responseFormat,
+      imageMediaType,
+    })
+  }
+  if (engines.length === 0) throw new Error('dsh-draw: at least one engine must be configured')
+
+  const defaultEngine = config?.defaultEngine ?? engines[0]!.id
+  if (!seen.has(defaultEngine)) {
+    throw new Error(`dsh-draw: defaultEngine ${JSON.stringify(defaultEngine)} does not name a configured engine`)
+  }
+
+  const requestTimeoutMs = config?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1_000 || requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+    throw new Error(`dsh-draw: config.requestTimeoutMs must be a finite number between 1000 and ${MAX_REQUEST_TIMEOUT_MS}`)
+  }
+  const maxImagesPerCall = config?.maxImagesPerCall ?? DEFAULT_MAX_IMAGES_PER_CALL
+  if (!Number.isInteger(maxImagesPerCall) || maxImagesPerCall < 1 || maxImagesPerCall > MAX_IMAGES_PER_CALL) {
+    throw new Error(`dsh-draw: config.maxImagesPerCall must be an integer between 1 and ${MAX_IMAGES_PER_CALL}`)
+  }
+  const maxPromptLength = config?.maxPromptLength ?? DEFAULT_MAX_PROMPT_LENGTH
+  if (!Number.isInteger(maxPromptLength) || maxPromptLength < 1 || maxPromptLength > MAX_PROMPT_LENGTH) {
+    throw new Error(`dsh-draw: config.maxPromptLength must be an integer between 1 and ${MAX_PROMPT_LENGTH}`)
+  }
+  const maxGenerationsPerSession = config?.maxGenerationsPerSession ?? DEFAULT_MAX_GENERATIONS_PER_SESSION
+  if (!Number.isInteger(maxGenerationsPerSession) || maxGenerationsPerSession < 1 || maxGenerationsPerSession > MAX_GENERATIONS_PER_SESSION) {
+    throw new Error(`dsh-draw: config.maxGenerationsPerSession must be an integer between 1 and ${MAX_GENERATIONS_PER_SESSION}`)
+  }
+  const maxBytesPerSession = config?.maxBytesPerSession ?? DEFAULT_MAX_BYTES_PER_SESSION
+  if (!Number.isInteger(maxBytesPerSession) || maxBytesPerSession < 1024 * 1024 || maxBytesPerSession > MAX_BYTES_PER_SESSION) {
+    throw new Error(`dsh-draw: config.maxBytesPerSession must be an integer between 1048576 and ${MAX_BYTES_PER_SESSION}`)
+  }
+  const failureThreshold = config?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD
+  if (!Number.isInteger(failureThreshold) || failureThreshold < 1 || failureThreshold > MAX_FAILURE_THRESHOLD) {
+    throw new Error(`dsh-draw: config.failureThreshold must be an integer between 1 and ${MAX_FAILURE_THRESHOLD}`)
+  }
+  const cooldownMs = config?.cooldownMs ?? DEFAULT_COOLDOWN_MS
+  if (!Number.isInteger(cooldownMs) || cooldownMs < 1_000 || cooldownMs > MAX_COOLDOWN_MS) {
+    throw new Error(`dsh-draw: config.cooldownMs must be an integer between 1000 and ${MAX_COOLDOWN_MS}`)
+  }
+
+  return Object.freeze({
+    engines: Object.freeze(engines),
+    defaultEngine,
+    requestTimeoutMs,
+    maxImagesPerCall,
+    maxPromptLength,
+    maxGenerationsPerSession,
+    maxBytesPerSession,
+    failureThreshold,
+    cooldownMs,
+  })
+}
+
+/** Engine id by which an engine is addressed, or `undefined` for an unknown id. */
+export function engineById(config: ResolvedConfig, id: string): ResolvedEngineConfig | undefined {
+  return config.engines.find(engine => engine.id === id)
+}