@dickpy/dsh-imagegen 1.0.0

package/src/client/SettingsCard.tsx

@@ -0,0 +1,373 @@
+/**
+ * The dsh-imagegen settings card: api_url, api_key (secret, display-only
+ * "set" state), and the plugin switches. Registers into the official
+ * `settings.plugin.item` slot (the Settings → Plugins → Configurable tab),
+ * independent of the dsh-web-ui family group, bound to the plugin's own
+ * bridge settings scope.
+ */
+
+import { useState } from 'react'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { CardForm, booleanField, secretField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
+import type { ImageGenScope } from './settings-scope.ts'
+import css from './settings-card.module.css'
+
+/** The fields this card edits (the namespace's full schema). */
+export interface ImageGenSettings {
+  enabled?: boolean
+  announceToAgent?: boolean
+  apiUrl?: string
+  apiKey?: string
+}
+
+/** What the card renders. */
+export interface ImageGenSettingsCardState extends CardShell {
+  /** Master switch. */
+  enabled: CardFieldState
+  /** System-prompt announcement flag. */
+  announceToAgent: CardFieldState
+  /** API base URL. */
+  apiUrl: CardFieldState
+  /** API key draft (the stored value is never rendered). */
+  apiKey: CardFieldState
+}
+
+/** The registration-side face the card's slot entry injects. */
+export interface ImageGenSettingsCardFace extends CardActions {
+  hooks: {
+    /** Card snapshot bound by the renderer as useImageGenSettingsCard. */
+    imageGenSettingsCard: SnapshotStore<ImageGenSettingsCardState>
+    /** Whether a secret (apiKey) is currently stored. */
+    imageGenKeySet: SnapshotStore<boolean>
+  }
+}
+
+/** Bridges the imagegen scope onto the card's staged form. */
+export class ImageGenSettingsCardController {
+  private readonly form: CardForm<ImageGenSettings>
+
+  /** @param scope - the bound bridge scope for the dsh-imagegen namespace. */
+  constructor(private readonly scope: ImageGenScope) {
+    this.form = new CardForm(scope, [
+      booleanField('enabled'),
+      booleanField('announceToAgent'),
+      textField('apiUrl'),
+      secretField('apiKey'),
+    ], {
+      // The redacted wire view never returns the key; a save's outcome is
+      // judged by the namespace's secrets sidecar instead.
+      secretSettled: () => this.scope.getKeySetSnapshot(),
+    })
+  }
+
+  private projection(): ImageGenSettingsCardState {
+    return {
+      ...this.form.shell(),
+      enabled: this.form.field('enabled'),
+      announceToAgent: this.form.field('announceToAgent'),
+      apiUrl: this.form.field('apiUrl'),
+      apiKey: this.form.field('apiKey'),
+    }
+  }
+
+  /**
+   * Build the face the card's slot registration injects.
+   * @returns the card's snapshot, the key-set flag, and the form actions.
+   */
+  inject(): ImageGenSettingsCardFace {
+    const cardStore = this.form.bind(() => this.projection())
+    const keySetStore = createSnapshotStore(this.scope.getKeySetSnapshot())
+    this.scope.subscribeKeySet(() => { keySetStore.set(this.scope.getKeySetSnapshot()) })
+    return {
+      hooks: {
+        imageGenSettingsCard: cardStore,
+        imageGenKeySet: keySetStore,
+      },
+      ...this.form.actions(),
+    }
+  }
+}
+
+/** Props the renderer binds for this card. */
+export type ImageGenSettingsCardProps =
+  PropsRuntime<'settings.plugin.item'>
+  & PropsLocale<'dsh-imagegen'>
+  & InjectFace<ImageGenSettingsCardFace>
+
+/**
+ * Render the card.
+ * @param props - locale copy, the card snapshot, and the form actions.
+ * @returns the card, or nothing while the namespace is still loading.
+ */
+export function ImageGenSettingsCard(props: ImageGenSettingsCardProps) {
+  const { t } = props
+  const state = props.useImageGenSettingsCard(snapshot => snapshot)
+  const keySet = props.useImageGenKeySet(snapshot => snapshot)
+  const [open, setOpen] = useState(false)
+  if (!state.available) return null
+  const title = t('settings.title')
+  const blocked = !state.dirty || state.invalid || state.saving
+  const disabled = !state.writable
+  const fieldProps = {
+    overriddenLabel: t('settings.overridden'),
+    resetLabel: t('settings.reset'),
+    invalidLabel: t('settings.invalidNumber'),
+    disabled,
+  }
+  if (!state.exposed) {
+    return (
+      <li className={css.card}>
+        <button
+          type="button"
+          className={css.header}
+          aria-expanded={open}
+          aria-label={`${t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`}
+          onClick={() => { setOpen(!open) }}
+        >
+          <span className={css.headText}>
+            <span className={css.name}>{title}</span>
+            <span className={css.description}>{t('settings.description')}</span>
+          </span>
+          <span className={open ? css.chevronOpen : css.chevron}>▾</span>
+        </button>
+        {open
+          ? (
+            <div className={css.body}>
+              <p className={css.notExposed} role="status">{t('settings.notExposed')}</p>
+            </div>
+          )
+          : null}
+      </li>
+    )
+  }
+  return (
+    <li className={css.card}>
+      <button
+        type="button"
+        className={css.header}
+        aria-expanded={open}
+        aria-label={`${t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`}
+        onClick={() => { setOpen(!open) }}
+      >
+        <span className={css.headText}>
+          <span className={css.name}>{title}</span>
+          <span className={css.description}>{t('settings.description')}</span>
+        </span>
+        {state.dirty ? <span className={css.pending}>{t('settings.unsaved')}</span> : null}
+        <span className={open ? css.chevronOpen : css.chevron}>▾</span>
+      </button>
+      {open
+        ? (
+          <div className={css.body}>
+            {!state.writable ? <p className={css.readOnly} role="status">{t('settings.readOnly')}</p> : null}
+            <ValueField
+              id="dsh-imagegen-settings-apikey"
+              label={t('settings.apiKey')}
+              hint={keySet ? t('settings.apiKeySet') : t('settings.apiKeyHint')}
+              placeholder="sk-…"
+              secret
+              {...fieldProps}
+              {...state.apiKey}
+              overridden={false}
+              onEdit={(text) => { props.edit('apiKey', text) }}
+              onReset={() => { props.resetField('apiKey') }}
+              clearLabel={t('settings.apiKeyClear')}
+              onClear={() => { props.resetField('apiKey') }}
+              canClear={keySet}
+            />
+            <ValueField
+              id="dsh-imagegen-settings-apiurl"
+              label={t('settings.apiUrl')}
+              hint={t('settings.apiUrlHint')}
+              placeholder="https://api.openai.com/v1"
+              {...fieldProps}
+              {...state.apiUrl}
+              onEdit={(text) => { props.edit('apiUrl', text) }}
+              onReset={() => { props.resetField('apiUrl') }}
+            />
+            <BooleanField
+              id="dsh-imagegen-settings-enabled"
+              label={t('settings.enabled')}
+              hint={t('settings.enabledHint')}
+              inheritLabel={t('settings.inherit')}
+              onLabel={t('settings.on')}
+              offLabel={t('settings.off')}
+              {...fieldProps}
+              {...state.enabled}
+              onEdit={(text) => { props.edit('enabled', text) }}
+              onReset={() => { props.resetField('enabled') }}
+            />
+            <BooleanField
+              id="dsh-imagegen-settings-announce"
+              label={t('settings.announceToAgent')}
+              hint={t('settings.announceToAgentHint')}
+              inheritLabel={t('settings.inherit')}
+              onLabel={t('settings.on')}
+              offLabel={t('settings.off')}
+              {...fieldProps}
+              {...state.announceToAgent}
+              onEdit={(text) => { props.edit('announceToAgent', text) }}
+              onReset={() => { props.resetField('announceToAgent') }}
+            />
+            <div className={css.footer}>
+              {state.failed ? <p className={css.failed} role="status">{t('settings.saveFailed')}</p> : null}
+              <button
+                type="button"
+                className={css.discard}
+                disabled={!state.dirty || state.saving}
+                onClick={props.discard}
+              >
+                {t('settings.discard')}
+              </button>
+              <button
+                type="button"
+                className={css.save}
+                disabled={blocked}
+                onClick={props.save}
+              >
+                {t(!state.saving ? 'settings.save' : 'settings.saving')}
+              </button>
+            </div>
+          </div>
+        )
+        : null}
+    </li>
+  )
+}
+
+/** Props every field control needs regardless of its value type. */
+interface FieldProps {
+  /** Stable id associating the label with its control. */
+  id: string
+  /** Visible label. */
+  label: string
+  /** One-line explanation rendered under the control. */
+  hint: string
+  /** Draft text this control renders. */
+  text: string
+  /** True when saving would leave a user-layer entry for this field. */
+  overridden: boolean
+  /** True when the draft is not a value this field accepts. */
+  invalid: boolean
+  /** Copy for the overridden badge. */
+  overriddenLabel: string
+  /** Copy for the reset control. */
+  resetLabel: string
+  /** Copy shown in place of the hint while the draft is invalid. */
+  invalidLabel: string
+  /** Disables every control (read-only document, or an unavailable namespace). */
+  disabled: boolean
+  /** Stage draft text. */
+  onEdit: (text: string) => void
+  /** Stage a clear so the field re-inherits the composition layer. */
+  onReset: () => void
+}
+
+/** A staged value field; `secret` renders a password control. */
+function ValueField(props: FieldProps & {
+  /** Render a password control. */
+  secret?: boolean
+  /** Placeholder shown while the draft is empty. */
+  placeholder?: string
+  /** Label of the dedicated clear control (secret fields). */
+  clearLabel?: string
+  /** Stage a clear of the stored secret. */
+  onClear?: () => void
+  /** Whether a stored secret exists (enables the clear control). */
+  canClear?: boolean
+}) {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+        {props.secret === true && props.canClear === true
+          ? (
+            <button
+              type="button"
+              className={css.reset}
+              disabled={props.disabled}
+              onClick={props.onClear}
+            >
+              {props.clearLabel ?? props.resetLabel}
+            </button>
+          )
+          : null}
+      </div>
+      <input
+        id={props.id}
+        className={props.invalid ? css.inputInvalid : css.input}
+        type={props.secret === true ? 'password' : 'text'}
+        autoComplete={props.secret === true ? 'off' : undefined}
+        {...props.invalid ? { 'aria-invalid': true } : {}}
+        value={props.text}
+        placeholder={props.placeholder ?? ''}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      />
+      <p className={props.invalid ? css.invalid : css.hint}>
+        {props.invalid ? props.invalidLabel : props.hint}
+      </p>
+    </div>
+  )
+}
+
+/** A staged boolean field: 继承 / 开 / 关. */
+function BooleanField(props: FieldProps & {
+  /** Copy for the inherit option. */
+  inheritLabel: string
+  /** Copy for the on option. */
+  onLabel: string
+  /** Copy for the off option. */
+  offLabel: string
+}) {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+      </div>
+      <select
+        id={props.id}
+        className={css.select}
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      >
+        <option value="">{props.inheritLabel}</option>
+        <option value="true">{props.onLabel}</option>
+        <option value="false">{props.offLabel}</option>
+      </select>
+      <p className={css.hint}>{props.hint}</p>
+    </div>
+  )
+}

package/src/client/api.ts

@@ -0,0 +1,89 @@
+/**
+ * Browser-side API client for the /api/dsh-imagegen route family. The only
+ * 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'
+
+/** Error carrying the route's JSON error message. */
+export class ImageGenApiError extends Error {
+  /** Stable wire code from the host. */
+  readonly code: string
+
+  constructor(message: string, code = 'generate-failed') {
+    super(message)
+    this.name = 'ImageGenApiError'
+    this.code = code
+  }
+}
+
+/** Parse the { ok, ... } envelope or throw an ImageGenApiError. */
+async function readEnvelope<T>(response: Response): Promise<T> {
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    throw new ImageGenApiError(`HTTP ${response.status}: invalid JSON response`)
+  }
+  if (body === null || typeof body !== 'object') {
+    throw new ImageGenApiError(`HTTP ${response.status}: malformed response`)
+  }
+  const record = body as { ok?: unknown; message?: unknown; code?: unknown }
+  if (record.ok !== true) {
+    throw new ImageGenApiError(
+      typeof record.message === 'string' ? record.message : `HTTP ${response.status}`,
+      typeof record.code === 'string' ? record.code : 'generate-failed',
+    )
+  }
+  return body as T
+}
+
+/** The browser half's data entry point. */
+export class ImageGenApi {
+  /** Forward one generate request to the host proxy. */
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    const response = await fetch(GENERATE_API, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(request),
+    })
+    const body = await readEnvelope<{ ok: true; images: GenerateResult['images'] }>(response)
+    return { images: body.images }
+  }
+
+  /** List the host-persisted history (newest first). */
+  async historyList(): Promise<HistoryEntry[]> {
+    const response = await fetch(HISTORY_API.list, { method: 'POST' })
+    const body = await readEnvelope<{ ok: true; entries: HistoryEntry[] }>(response)
+    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, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id }),
+    })
+    const body = await readEnvelope<{ ok: true; entries: HistoryEntry[] }>(response)
+    return body.entries
+  }
+
+  /** Clear the entire history. */
+  async historyClear(): Promise<HistoryEntry[]> {
+    const response = await fetch(HISTORY_API.clear, { method: 'POST' })
+    const body = await readEnvelope<{ ok: true; entries: HistoryEntry[] }>(response)
+    return body.entries
+  }
+}

package/src/client/controller.ts

@@ -0,0 +1,46 @@
+/**
+ * Image-gen panel controller: the single owner of the panel's open/closed
+ * state. Framework-free so the DOM mounts and the React panel share one tiny
+ * subscription surface. The state lives only for the browser session.
+ */
+
+/** Immutable controller snapshot for UI subscriptions. */
+export interface ImageGenControllerSnapshot {
+  panelOpen: boolean
+}
+
+/** The panel state owner the sidebar entry toggles and the view renders from. */
+export class ImageGenController {
+  private panelOpen = false
+  private listeners = new Set<() => void>()
+
+  getSnapshot(): ImageGenControllerSnapshot {
+    return { panelOpen: this.panelOpen }
+  }
+
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  open(): void {
+    if (this.panelOpen) return
+    this.panelOpen = true
+    this.notify()
+  }
+
+  close(): void {
+    if (!this.panelOpen) return
+    this.panelOpen = false
+    this.notify()
+  }
+
+  toggle(): void {
+    if (this.panelOpen) this.close()
+    else this.open()
+  }
+
+  private notify(): void {
+    for (const fn of [...this.listeners]) fn()
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,5 @@
+/** CSS Modules type shim (the bundle inlines the compiled class map). */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/client/helpers.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared panel helpers: the active-dictionary pick (document-language based,
+ * dsh-ssh precedent) bound to the dsh-imagegen interpolator, plus a small
+ * error-message extractor. All copy stays in the locale dictionaries.
+ */
+
+import { en, zh, type ImageGenKey } from './locales.ts'
+
+/** Template values accepted by the interpolator. */
+export type TranslateValues = Record<string, string | number>
+
+/** Active dictionary, picked by the document language at call time. */
+export function dictionary(): Record<string, string> {
+  const lang = typeof document !== 'undefined' ? document.documentElement.lang : 'zh'
+  return lang.toLowerCase().startsWith('en') ? { ...en } : { ...zh }
+}
+
+/** Translate a key with optional {name} template params (current language). */
+export function tt(key: ImageGenKey, values?: TranslateValues): string {
+  const text = dictionary()[key] ?? key
+  if (values === undefined) return text
+  let rendered = text
+  for (const [name, value] of Object.entries(values)) {
+    rendered = rendered.replaceAll(`{${name}}`, String(value))
+  }
+  return rendered
+}
+
+/** Human-readable error text from an unknown thrown value. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}

package/src/client/index.ts

@@ -0,0 +1,127 @@
+/**
+ * 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()
+}