@dickpy/dsh-imagegen 1.0.6 → 1.0.9

package/src/client/TemplateLibrary.tsx

@@ -0,0 +1,336 @@
+/**
+ * Prompt-template library overlay: a searchable, category-filtered gallery of
+ * the bundled awesome-gpt-image-2 cases. The case list is served by the host
+ * (bundled snapshot, optionally refreshed online); reference images load
+ * lazily through the host's caching proxy, so browsing progressively mirrors
+ * the gallery onto the local disk. Picking a template hands its prompt back
+ * to the studio form.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ImageGenApi } from './api.ts'
+import { errorMessage, tt } from './helpers.ts'
+import { TEMPLATES_API, type TemplateCase, type TemplateListResult } from '../protocol.ts'
+import css from './templates.module.css'
+
+/** Concurrent image downloads while caching the whole gallery offline. */
+const CACHE_ALL_CONCURRENCY = 4
+
+/** Same-origin URL of one case's reference image (host caching proxy). */
+function imageUrlOf(item: TemplateCase): string {
+  return `${TEMPLATES_API.image}/${encodeURIComponent(item.image)}`
+}
+
+/** A card thumbnail that falls back to a placeholder when the proxy 404s. */
+function TemplateThumb(props: { item: TemplateCase }) {
+  const [failed, setFailed] = useState(false)
+  if (props.item.image === '' || failed) {
+    return (
+      <span className={css.thumbPlaceholder} aria-hidden="true">
+        <svg viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" strokeLinejoin="round"><rect x="3" y="3" width="18" height="18" rx="3"/><circle cx="8.5" cy="8.5" r="1.5"/><path d="M21 15l-5-5L5 21"/></svg>
+      </span>
+    )
+  }
+  return (
+    <img
+      className={css.thumb}
+      src={imageUrlOf(props.item)}
+      alt={props.item.title}
+      loading="lazy"
+      onError={() => { setFailed(true) }}
+    />
+  )
+}
+
+/** The template-library modal. Rendered through a portal above the studio. */
+export function TemplateLibrary(props: {
+  api: ImageGenApi
+  /** Hand a picked prompt back to the studio form and close the library. */
+  onUse: (prompt: string) => void
+  onClose: () => void
+}) {
+  const { api, onUse, onClose } = props
+  const [list, setList] = useState<TemplateListResult | null>(null)
+  const [loadError, setLoadError] = useState<string | null>(null)
+  const [query, setQuery] = useState('')
+  const [category, setCategory] = useState('')
+  const [selected, setSelected] = useState<TemplateCase | null>(null)
+  const [copied, setCopied] = useState(false)
+  const [refreshing, setRefreshing] = useState(false)
+  const [notice, setNotice] = useState<string | null>(null)
+  const [cacheAll, setCacheAll] = useState<{ running: boolean; done: number; total: number }>({ running: false, done: 0, total: 0 })
+  const searchRef = useRef<HTMLInputElement>(null)
+  const load = (): void => {
+    api.templatesList()
+      .then(result => { setList(result); setLoadError(null) })
+      .catch(caught => { setLoadError(errorMessage(caught)) })
+  }
+
+  // Load once on open; focus the search box for immediate typing.
+  useEffect(() => {
+    load()
+    searchRef.current?.focus()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const categories = useMemo(() => {
+    if (list === null) return [] as Array<{ key: string; label: string; count: number }>
+    const counts = new Map<string, { label: string; count: number }>()
+    for (const item of list.cases) {
+      const entry = counts.get(item.category) ?? { label: item.categoryZh || item.category, count: 0 }
+      entry.count += 1
+      counts.set(item.category, entry)
+    }
+    return [...counts.entries()].map(([key, value]) => ({ key, label: value.label, count: value.count }))
+  }, [list])
+
+  const filtered = useMemo(() => {
+    if (list === null) return [] as TemplateCase[]
+    const needle = query.trim().toLowerCase()
+    return list.cases.filter(item => {
+      if (category !== '' && item.category !== category) return false
+      if (needle === '') return true
+      return item.title.toLowerCase().includes(needle)
+        || item.prompt.toLowerCase().includes(needle)
+        || item.sourceLabel.toLowerCase().includes(needle)
+    })
+  }, [list, query, category])
+
+  // Escape backs out of the detail view first, then closes the modal.
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape') return
+      event.stopPropagation()
+      if (selected !== null) setSelected(null)
+      else onClose()
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [selected, onClose])
+
+  const refresh = async (): Promise<void> => {
+    if (refreshing) return
+    setRefreshing(true)
+    setNotice(null)
+    try {
+      const result = await api.templatesRefresh()
+      const reloaded = await api.templatesList()
+      setList(reloaded)
+      setLoadError(null)
+      setNotice(tt('templates.refreshed', { count: result.total }))
+    } catch (caught) {
+      setNotice(tt('templates.refreshFailed', { error: errorMessage(caught) }))
+    } finally {
+      setRefreshing(false)
+    }
+  }
+
+  /** Mirror every reference image through the host cache (offline browsing). */
+  const cacheAllImages = async (): Promise<void> => {
+    if (cacheAll.running || list === null) return
+    const files = [...new Set(list.cases.map(item => item.image).filter(name => name !== ''))]
+    setCacheAll({ running: true, done: 0, total: files.length })
+    let index = 0
+    const worker = async (): Promise<void> => {
+      while (index < files.length) {
+        const file = files[index]!
+        index += 1
+        try {
+          await fetch(`${TEMPLATES_API.image}/${encodeURIComponent(file)}`)
+        } catch { /* individual failures are retried on the next run */ }
+        setCacheAll(current => ({ ...current, done: current.done + 1 }))
+      }
+    }
+    await Promise.all(Array.from({ length: CACHE_ALL_CONCURRENCY }, () => worker()))
+    setCacheAll({ running: false, done: files.length, total: files.length })
+  }
+
+  const copyPrompt = async (text: string): Promise<void> => {
+    try {
+      if (navigator.clipboard?.writeText !== undefined) {
+        await navigator.clipboard.writeText(text)
+      } else {
+        const textarea = document.createElement('textarea')
+        textarea.value = text
+        textarea.style.position = 'fixed'
+        textarea.style.opacity = '0'
+        document.body.appendChild(textarea)
+        textarea.select()
+        const copiedOk = document.execCommand('copy')
+        textarea.remove()
+        if (!copiedOk) throw new Error('copy failed')
+      }
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, 1800)
+    } catch {
+      setCopied(false)
+    }
+  }
+
+  const originLabel = list === null ? '' : tt(list.origin === 'refreshed' ? 'templates.origin.refreshed' : 'templates.origin.bundled')
+
+  return createPortal(
+    <div className={css.overlay} role="dialog" aria-modal="true" aria-label={tt('templates.title')} onClick={onClose}>
+      <section className={css.shell} onClick={(event) => { event.stopPropagation() }}>
+        <header className={css.header}>
+          <span className={css.heading}>
+            <h3 className={css.title}>{tt('templates.title')}</h3>
+            {list !== null ? (
+              <span className={css.meta}>{tt('templates.meta', { count: list.total, origin: originLabel })}</span>
+            ) : null}
+          </span>
+          <span className={css.headerActions}>
+            <Button variant="outline" size="sm" disabled={refreshing || cacheAll.running} onClick={() => { void refresh() }}>
+              {refreshing ? tt('templates.refreshing') : tt('templates.refresh')}
+            </Button>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={list === null || cacheAll.running}
+              title={tt('templates.cacheAllHint')}
+              onClick={() => { void cacheAllImages() }}
+            >
+              {cacheAll.running
+                ? tt('templates.caching', { done: cacheAll.done, total: cacheAll.total })
+                : cacheAll.total > 0 && cacheAll.done === cacheAll.total
+                  ? tt('templates.cached')
+                  : tt('templates.cacheAll')}
+            </Button>
+            <button type="button" className={css.close} aria-label={tt('templates.close')} title={tt('templates.close')} onClick={onClose}>
+              <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>
+            </button>
+          </span>
+        </header>
+
+        <div className={css.toolbar}>
+          <input
+            ref={searchRef}
+            type="search"
+            className={css.search}
+            placeholder={tt('templates.search')}
+            value={query}
+            onChange={(event) => { setQuery(event.target.value) }}
+          />
+          <div className={css.categoryRow}>
+            <button
+              type="button"
+              className={css.categoryPill}
+              data-active={category === '' ? '' : undefined}
+              onClick={() => { setCategory('') }}
+            >
+              {tt('templates.all')}{list !== null ? ` ${list.total}` : ''}
+            </button>
+            {categories.map(entry => (
+              <button
+                key={entry.key}
+                type="button"
+                className={css.categoryPill}
+                data-active={category === entry.key ? '' : undefined}
+                onClick={() => { setCategory(entry.key) }}
+              >
+                {entry.label} {entry.count}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {notice !== null ? <div className={css.notice} role="status">{notice}</div> : null}
+
+        <div className={css.body}>
+          {list === null && loadError === null ? (
+            <div className={css.state} role="status">
+              <span className={css.spinner} />
+              <span>{tt('templates.loading')}</span>
+            </div>
+          ) : null}
+
+          {loadError !== null ? (
+            <div className={css.state} role="alert">
+              <span>{tt('templates.loadFailed', { error: loadError })}</span>
+              <Button variant="outline" size="sm" onClick={() => { setLoadError(null); setList(null); load() }}>
+                {tt('templates.retry')}
+              </Button>
+            </div>
+          ) : null}
+
+          {list !== null && filtered.length === 0 ? (
+            <div className={css.state}>{tt('templates.empty')}</div>
+          ) : null}
+
+          {list !== null && filtered.length > 0 ? (
+            <div className={css.grid}>
+              {filtered.map(item => (
+                <button
+                  key={item.id}
+                  type="button"
+                  className={css.card}
+                  onClick={() => { setSelected(item); setCopied(false) }}
+                >
+                  <span className={css.thumbWrap}>
+                    <TemplateThumb item={item} />
+                    {item.featured ? <span className={css.featuredBadge}>{tt('templates.featured')}</span> : null}
+                  </span>
+                  <span className={css.cardBody}>
+                    <span className={css.cardTitle}>{item.title}</span>
+                    <span className={css.cardMeta}>
+                      <span className={css.cardCategory}>{item.categoryZh || item.category}</span>
+                      {item.sourceLabel !== '' ? <span className={css.cardSource}>{item.sourceLabel}</span> : null}
+                    </span>
+                  </span>
+                </button>
+              ))}
+            </div>
+          ) : null}
+        </div>
+
+        <footer className={css.footer}>
+          <span className={css.attribution}>{tt('templates.attribution')}</span>
+          <a className={css.sourceLink} href="https://vibeui.top/" target="_blank" rel="noreferrer">
+            {tt('templates.source')}
+          </a>
+        </footer>
+      </section>
+
+      {selected !== null ? (
+        <div className={css.detailOverlay} onClick={() => { setSelected(null) }}>
+          <section className={css.detail} onClick={(event) => { event.stopPropagation() }}>
+            <div className={css.detailMedia}>
+              {selected.image !== '' ? (
+                <img className={css.detailImage} src={imageUrlOf(selected)} alt={selected.title} />
+              ) : (
+                <span className={css.thumbPlaceholder} aria-hidden="true" />
+              )}
+            </div>
+            <div className={css.detailInfo}>
+              <h4 className={css.detailTitle}>{selected.title}</h4>
+              <div className={css.detailMeta}>
+                <span className={css.cardCategory}>{selected.categoryZh || selected.category}</span>
+                {selected.sourceUrl !== '' ? (
+                  <a className={css.detailLink} href={selected.sourceUrl} target="_blank" rel="noreferrer">{selected.sourceLabel || selected.sourceUrl}</a>
+                ) : null}
+                {selected.githubUrl !== '' ? (
+                  <a className={css.detailLink} href={selected.githubUrl} target="_blank" rel="noreferrer">GitHub</a>
+                ) : null}
+              </div>
+              <pre className={css.detailPrompt}>{selected.prompt}</pre>
+              <div className={css.detailActions}>
+                <Button variant="primary" size="md" onClick={() => { onUse(selected.prompt) }}>
+                  {tt('templates.use')}
+                </Button>
+                <Button variant="outline" size="md" onClick={() => { void copyPrompt(selected.prompt) }}>
+                  {copied ? tt('templates.copied') : tt('templates.copy')}
+                </Button>
+                <Button variant="outline" size="md" onClick={() => { setSelected(null) }}>
+                  {tt('templates.back')}
+                </Button>
+              </div>
+            </div>
+          </section>
+        </div>
+      ) : null}
+    </div>,
+    document.body,
+  )
+}

package/src/client/api.ts

@@ -3,7 +3,7 @@
  * data access path the panel uses — plain fetch, same origin.
  */
 
-import { GENERATE_API, HISTORY_API, UPDATE_API, type GenerateRequest, type GenerateResult, type HistoryEntry, type UpdateInfo } from '../protocol.ts'
+import { GENERATE_API, HISTORY_API, TEMPLATES_API, UPDATE_API, type GenerateRequest, type GenerateResult, type HistoryEntry, type TemplateListResult, type TemplateRefreshResult, type UpdateInfo } from '../protocol.ts'
 
 /** Error carrying the route's JSON error message. */
 export class ImageGenApiError extends Error {
@@ -97,4 +97,24 @@ export class ImageGenApi {
     const body = await readEnvelope<{ ok: true; entries: HistoryEntry[] }>(response)
     return body.entries
   }
+
+  /** Fetch the prompt-template library (bundled snapshot or refreshed copy). */
+  async templatesList(): Promise<TemplateListResult> {
+    const response = await fetch(TEMPLATES_API.list, { method: 'POST' })
+    const body = await readEnvelope<TemplateListResult & { ok: true }>(response)
+    return {
+      cases: body.cases,
+      total: body.total,
+      origin: body.origin,
+      repository: body.repository,
+      fetchedAt: body.fetchedAt,
+    }
+  }
+
+  /** Re-download the template library from the upstream mirror (host-side). */
+  async templatesRefresh(): Promise<TemplateRefreshResult> {
+    const response = await fetch(TEMPLATES_API.refresh, { method: 'POST' })
+    const body = await readEnvelope<TemplateRefreshResult & { ok: true }>(response)
+    return { total: body.total, fetchedAt: body.fetchedAt }
+  }
 }

package/src/client/index.ts

@@ -1,127 +1,126 @@
-/**
- * Browser-half entry for the dsh-imagegen plugin — runs inside the dsh web
- * GUI.
- *
- * Registers the dsh-imagegen locale dictionaries, binds the plugin's own
- * settings scope (its bridge routes serve the namespace the official rc.6
- * allowlist would refuse), registers the settings card into the Web UI plugin
- * group slot, and mounts the two DOM surfaces: the sidebar entry row (toggles
- * the panel) and the generation studio in the center column. Failure policy:
- * DOM mounting problems are logged, never thrown — the web shell fails the
- * whole boot when a plugin apply throws, and an external plugin must not take
- * the GUI down.
- */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
-// Type-only: pulls the locale plugin's Context merge (ctx.locale).
-import type {} from '@deepseek-ai/dsh-client-locale/client'
-// Type-only: pulls the LocaleNamespaceMap merge table.
-import type {} from '@deepseek-ai/dsh-client-ui-slots'
-import { ImageGenApi } from './api.ts'
-import { ImageGenController } from './controller.ts'
-import { tt } from './helpers.ts'
-import { en, zh, type ImageGenKey } from './locales.ts'
-import { mountPanel } from './mount.tsx'
-import { mountSidebarEntry } from './sidebar-entry.ts'
-import { ImageGenSettingsCard, ImageGenSettingsCardController } from './SettingsCard.tsx'
-import { bindImageGenScope, type ImageGenScope } from './settings-scope.ts'
-
-/** Locale namespace this plugin owns. */
-const NS = 'dsh-imagegen'
-
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-  interface LocaleNamespaceMap {
-    /** dsh-imagegen surface copy. */
-    'dsh-imagegen': ImageGenKey
-  }
-
-  interface SlotMap {
-    /**
-     * The official plugin-configuration slot the Settings → Plugins →
-     * Configurable tab declares and renders. This card registers there as its
-     * own standalone card — independent of the dsh-web-ui family group — so
-     * this plugin never reads as part of that family. Spelled here with the
-     * same shape so this package can register without depending on the
-     * sibling UI package.
-     */
-    'settings.plugin.item': { kind: 'list'; scope: 'root'; owner: ImageGenPluginItemOwnerProps }
-  }
-}
-
-/** Owner share of a plugin card (the section supplies nothing). */
-export interface ImageGenPluginItemOwnerProps {
-  /** Marker field: card owner props are intentionally empty. */
-  children?: never
-}
-
-/** Required services (fiber inject waiting — the runtime must be up first). */
-export const inject = ['slots', 'locale', 'connection']
-
-/**
- * Mount the studio, its sidebar entry, and the settings card.
- * @param ctx - client root context (services: slots, locale, connection).
- */
-export function apply(ctx: ClientContext): void {
-  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-imagegen: dictionaries')
-
-  const connection = ctx.get('connection') as ConnectionHandle | undefined
-  const loopback = connection?.isLoopback === true
-  // The bridge routes are loopback-fenced; remote browsers get an unavailable
-  // scope (the card explains the gap) instead of failing fetches.
-  const scope: ImageGenScope = bindImageGenScope(loopback
-    ? (input, init) => fetch(input, init)
-    : () => { throw new Error('settings bridge is loopback-only') })
-
-  // Re-read the scope whenever the connection resets (same invalidation the
-  // official settings binder wires).
-  ctx.effect(() => {
-    const disposers = [
-      ctx.on('connection/reset', () => { void scope.load() }),
-    ]
-    return () => { for (const dispose of disposers) dispose() }
-  }, 'dsh-imagegen: settings scope invalidation')
-
-  // Plugin configuration card: one staged form over the `dsh-imagegen` scope,
-  // registered into the official plugin-configuration slot (Settings →
-  // Plugins → Configurable) as a standalone card.
-  const settingsCard = new ImageGenSettingsCardController(scope)
-  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
-    name: 'settings.plugin.item',
-    id: 'imagegen',
-    order: 30,
-    locale: NS,
-    inject: () => settingsCard.inject(),
-  }, ImageGenSettingsCard))
-
-  // The sidebar entry and studio mount once the settings scope settles; while
-  // the scope is still loading, the composition default is unknown, so nothing
-  // mounts yet. Only an unavailable scope falls back to the default (enabled).
-  let uiDisposer: (() => void) | undefined
-  const mountUi = (): void => {
-    if (uiDisposer !== undefined) return
-    const controller = new ImageGenController()
-    const api = new ImageGenApi()
-    const disposers: Array<() => void> = []
-    try {
-      disposers.push(mountSidebarEntry(controller, tt('entry.label'), tt('entry.tooltip')))
-      disposers.push(mountPanel(controller, api, scope))
-    } catch (error) {
-      // DOM failures degrade the studio, never the GUI.
-      console.warn('[dsh-imagegen] mount failed:', error)
-    }
-    uiDisposer = () => {
-      for (const dispose of disposers.splice(0)) dispose()
-      uiDisposer = undefined
-    }
-  }
-  const syncEnabled = (): void => {
-    const snapshot = scope.getSnapshot()
-    const enabled = snapshot.status === 'ready'
-      ? snapshot.value?.enabled ?? true
-      : snapshot.status === 'unavailable'
-    if (enabled) mountUi()
-    else uiDisposer?.()
-  }
-  scope.subscribe(syncEnabled)
-  syncEnabled()
-}
+/**
+ * Browser-half entry for the dsh-imagegen plugin — runs inside the dsh web
+ * GUI.
+ *
+ * Registers the dsh-imagegen locale dictionaries, binds the plugin's own
+ * settings scope (its bridge routes serve the namespace the official rc.6
+ * allowlist would refuse), registers the settings card into the Web UI plugin
+ * group slot, and mounts the two DOM surfaces: the sidebar entry row (toggles
+ * the panel) and the generation studio in the center column. Failure policy:
+ * DOM mounting problems are logged, never thrown — the web shell fails the
+ * whole boot when a plugin apply throws, and an external plugin must not take
+ * the GUI down.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: pulls the LocaleNamespaceMap merge table.
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import { ImageGenApi } from './api.ts'
+import { ImageGenController } from './controller.ts'
+import { tt } from './helpers.ts'
+import { en, zh, type ImageGenKey } from './locales.ts'
+import { mountPanel } from './mount.tsx'
+import { mountSidebarEntry } from './sidebar-entry.ts'
+import { ImageGenSettingsCard, ImageGenSettingsCardController } from './SettingsCard.tsx'
+import { bindImageGenScope, type ImageGenScope } from './settings-scope.ts'
+
+/** Locale namespace this plugin owns. */
+const NS = 'dsh-imagegen'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** dsh-imagegen surface copy. */
+    'dsh-imagegen': ImageGenKey
+  }
+
+  interface SlotMap {
+    /**
+     * The official plugin-configuration slot the Settings → Plugins →
+     * Configurable tab declares and renders. This card registers there as its
+     * own standalone card — independent of the dsh-web-ui family group — so
+     * this plugin never reads as part of that family. Spelled here with the
+     * same shape so this package can register without depending on the
+     * sibling UI package.
+     */
+    'settings.plugin.item': { kind: 'keyed'; scope: 'root'; owner: ImageGenPluginItemOwnerProps }
+  }
+}
+
+/** Owner share of a plugin card (the section supplies nothing). */
+export interface ImageGenPluginItemOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+
+/** Required services (fiber inject waiting — the runtime must be up first). */
+export const inject = ['slots', 'locale', 'connection']
+
+/**
+ * Mount the studio, its sidebar entry, and the settings card.
+ * @param ctx - client root context (services: slots, locale, connection).
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-imagegen: dictionaries')
+
+  const connection = ctx.get('connection') as ConnectionHandle | undefined
+  const loopback = connection?.isLoopback === true
+  // The bridge routes are loopback-fenced; remote browsers get an unavailable
+  // scope (the card explains the gap) instead of failing fetches.
+  const scope: ImageGenScope = bindImageGenScope(loopback
+    ? (input, init) => fetch(input, init)
+    : () => { throw new Error('settings bridge is loopback-only') })
+
+  // Re-read the scope whenever the connection resets (same invalidation the
+  // official settings binder wires).
+  ctx.effect(() => {
+    const disposers = [
+      ctx.on('connection/reset', () => { void scope.load() }),
+    ]
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'dsh-imagegen: settings scope invalidation')
+
+  // Plugin configuration card: one staged form over the `dsh-imagegen` scope,
+  // registered into the official plugin-configuration slot (Settings →
+  // Plugins → Configurable) as a standalone card.
+  const settingsCard = new ImageGenSettingsCardController(scope)
+  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
+    name: 'settings.plugin.item',
+    key: 'dsh-imagegen',
+    locale: NS,
+    inject: () => settingsCard.inject(),
+  }, ImageGenSettingsCard))
+
+  // The sidebar entry and studio mount once the settings scope settles; while
+  // the scope is still loading, the composition default is unknown, so nothing
+  // mounts yet. Only an unavailable scope falls back to the default (enabled).
+  let uiDisposer: (() => void) | undefined
+  const mountUi = (): void => {
+    if (uiDisposer !== undefined) return
+    const controller = new ImageGenController()
+    const api = new ImageGenApi()
+    const disposers: Array<() => void> = []
+    try {
+      disposers.push(mountSidebarEntry(controller, tt('entry.label'), tt('entry.tooltip')))
+      disposers.push(mountPanel(controller, api, scope))
+    } catch (error) {
+      // DOM failures degrade the studio, never the GUI.
+      console.warn('[dsh-imagegen] mount failed:', error)
+    }
+    uiDisposer = () => {
+      for (const dispose of disposers.splice(0)) dispose()
+      uiDisposer = undefined
+    }
+  }
+  const syncEnabled = (): void => {
+    const snapshot = scope.getSnapshot()
+    const enabled = snapshot.status === 'ready'
+      ? snapshot.value?.enabled ?? true
+      : snapshot.status === 'unavailable'
+    if (enabled) mountUi()
+    else uiDisposer?.()
+  }
+  scope.subscribe(syncEnabled)
+  syncEnabled()
+}