@linxin666/dsh-pet 0.1.1

package/src/client/index.ts

@@ -0,0 +1,261 @@
+/**
+ * dsh-pet browser half — registers the whale-girl into the conversation
+ * input selector row (the same every-phase row the git branch chip uses) and
+ * drives it from the host's same-origin `/api/pet/*` JSON endpoints: poll the
+ * host snapshot (~800 ms), forward interactions, persist drag positions. The
+ * row anchor mounts the floating pet via portal; when the pet is hidden the
+ * anchor becomes the summon button. Anchoring in the selector row (rather
+ * than the session-only composer dock band) keeps the pet floating on the
+ * new-conversation screen too, where no session exists to scope a slot by.
+ * @module @linxin666/dsh-pet/client
+ */
+
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/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 settings-surface Context merge (ctx.settingsScope).
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { PetDisplayConfig } from '../persist.ts'
+import type { PetInteractResult, PetStateView } from '../service.ts'
+import type { PetInteraction } from '../affinity.ts'
+import { createPetStore, type PetStoreInstance } from './pet-store.ts'
+import { PetDockEntry, type PetInjected } from './PetDockEntry.tsx'
+import { PetSettingsCard, PetSettingsCardController, type PetSettings } from './PetSettingsCard.tsx'
+import { NS, en, zh } from './locales.ts'
+
+/** The host pet API as the browser sees it (same-origin JSON endpoints). */
+interface PetHttpApi {
+  state(): Promise<PetStateView>
+  interact(kind: PetInteraction): Promise<PetInteractResult>
+  setVisible(visible: boolean): Promise<{ ok: true; display: PetDisplayConfig }>
+  setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }>
+  setName(name: string): Promise<{ ok: true; name: string } | { ok: false; error: string }>
+}
+
+/** Same-origin JSON fetch helper (GET without body, POST with JSON body). */
+async function petFetch<T>(path: string, body?: unknown): Promise<T> {
+  const response = await fetch(path, body === undefined
+    ? {}
+    : {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+  if (!response.ok) {
+    throw new Error(`pet ${path} failed: ${response.status}`)
+  }
+  return (await response.json()) as T
+}
+
+/** The live host API instance (always defined; failures surface per call). */
+const petApi: PetHttpApi = {
+  state: () => petFetch('/api/pet/state'),
+  interact: (kind) => petFetch('/api/pet/interact', { kind }),
+  setVisible: (visible) => petFetch('/api/pet/set-visible', { visible }),
+  setConfig: (patch) => petFetch('/api/pet/set-config', patch),
+  setName: (name) => petFetch('/api/pet/set-name', { name }),
+}
+
+/** Poll interval for the host snapshot. */
+const POLL_MS = 800
+
+/** Settings namespace the pet settings card edits (the Host plugin registers it). */
+const PET_SETTINGS_NS = 'pet'
+
+/** Required services. */
+export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote']
+
+/** Re-exported for consumers that type against the injected face. */
+export type { PetInjected, PetDockEntryProps } from './PetDockEntry.tsx'
+export type { PetUiState, PetFeedback } from './pet-store.ts'
+export type { PetSettingsCardFace, PetSettingsCardState } from './PetSettingsCard.tsx'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /**
+     * The child slot the Web UI plugin group declares; this card registers
+     * into the group instead of the top-level `settings.plugin.item` list.
+     * Spelled here with the same shape so this package can register without
+     * depending on the sibling UI package.
+     */
+    'web-ui.plugin.item': { kind: 'list'; scope: 'root'; owner: SettingsPluginItemOwnerProps }
+  }
+}
+
+/** Owner share of a plugin card (the group card supplies nothing). */
+export interface SettingsPluginItemOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+
+/**
+ * Client plugin body: register dictionaries, mount the dock entry and poll
+ * loop while the plugin is enabled, and seat the settings card in the Web UI
+ * plugin group.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'pet: dictionaries')
+
+  const settingsScope = ctx.settingsScope.bind<PetSettings>({ namespace: PET_SETTINGS_NS })
+  const enabled = (): boolean => {
+    const snapshot = settingsScope.getSnapshot()
+    return snapshot.status === 'ready'
+      ? snapshot.value?.enabled ?? true
+      : snapshot.status === 'unavailable'
+  }
+
+  // Plugin configuration card: one staged form over the `pet` settings
+  // namespace, contributed to the Web UI plugin group.
+  const petSettings = new PetSettingsCardController(settingsScope)
+  ctx.slots.inject('web-ui.plugin.item', () => ctx.slots.register({
+    name: 'web-ui.plugin.item',
+    id: 'pet-settings',
+    order: 140,
+    locale: NS,
+    inject: () => petSettings.inject(),
+  }, PetSettingsCard))
+
+  // The dock entry, its store, and the poll loop live while the plugin is
+  // enabled; toggling the setting off hides the pet and stops polling.
+  let disposeUi: (() => void) | undefined
+  const syncUi = (): void => {
+    if (enabled() && disposeUi === undefined) {
+      // ONE store instance for the whole app, owned by this apply body. The
+      // pet is host-global (state/display/interactions are /api/pet/*
+      // endpoints with no session dimension), so the slot system's per-session
+      // store scoping would only reset the pet on session switches and leave
+      // it stateless on the new-conversation screen (no session to scope by).
+      const petStore: PetStoreInstance = createPetStore().create()
+      const setSnapshot = petStore.actions.setSnapshot
+      const setState = petStore.actions.setState
+      const setFeedback = petStore.actions.setFeedback
+
+      const pollNow = (): void => {
+        petApi.state().then((snapshot) => {
+          setSnapshot(snapshot)
+        }, () => {
+          setState('error', 'pet.state transport error')
+        })
+      }
+
+      const disposePoll = ctx.effect(() => {
+        // Poll only while the tab is visible: the host snapshot does not
+        // change while the page is hidden, so a background interval would
+        // only burn RPCs (browser throttling is an unreliable backstop).
+        // Coming back to the tab refreshes the pet immediately instead of
+        // waiting out the next 800 ms cycle.
+        let timer: number | undefined
+        const stop = (): void => {
+          if (timer !== undefined) {
+            window.clearInterval(timer)
+            timer = undefined
+          }
+        }
+        const start = (): void => {
+          if (timer === undefined && document.visibilityState === 'visible') {
+            timer = window.setInterval(pollNow, POLL_MS)
+          }
+        }
+        const onVisibility = (): void => {
+          if (document.visibilityState === 'visible') {
+            pollNow()
+            start()
+          } else {
+            stop()
+          }
+        }
+        start()
+        document.addEventListener('visibilitychange', onVisibility)
+        return () => {
+          stop()
+          document.removeEventListener('visibilitychange', onVisibility)
+        }
+      }, 'pet: poll')
+
+      const injected = (): PetInjected => ({
+        store: petStore,
+        ensure: pollNow,
+        pet: () => {
+          petApi.interact('pet').then((result) => {
+            setFeedback({
+              text: result.reaction,
+              kind: 'pet',
+              at: Date.now(),
+            })
+          }, () => {
+            // Ignore transport errors on interactions; the next poll resyncs.
+          })
+        },
+        feed: () => {
+          petApi.interact('feed').then((result) => {
+            setFeedback({
+              text: result.reaction,
+              kind: 'feed',
+              at: Date.now(),
+            })
+          }, () => {
+            // Ignore transport errors on interactions; the next poll resyncs.
+          })
+        },
+        hide: () => {
+          petApi.setVisible(false).then(() => {
+            pollNow()
+          }, () => {
+            // Ignore; next poll resyncs.
+          })
+        },
+        summon: () => {
+          petApi.setVisible(true).then(() => {
+            pollNow()
+          }, () => {
+            // Ignore; next poll resyncs.
+          })
+        },
+        dragEnd: (right, bottom) => {
+          petApi.setConfig({ right, bottom }).then(() => {
+            pollNow()
+          }, () => {
+            // Ignore; next poll resyncs.
+          })
+        },
+        rename: (name) => {
+          petApi.setName(name).then((result) => {
+            if (result.ok) pollNow()
+          }, () => {
+            // Ignore; next poll resyncs.
+          })
+        },
+        feedbackDone: () => {
+          setFeedback(null)
+        },
+      })
+
+      // The input selector row mounts in EVERY conversation phase (cold
+      // start, blank-session hero, active seat) — the composer dock band
+      // only renders for an active session, which is why the pet used to
+      // vanish on the new-conversation screen.
+      const disposeDock = ctx.slots.inject('conversation.input.selector.context', () =>
+        ctx.slots.register({
+          name: 'conversation.input.selector.context',
+          id: 'pet',
+          order: 110,
+          inject: injected,
+          locale: NS,
+        }, PetDockEntry))
+
+      disposeUi = () => {
+        disposeDock()
+        disposePoll()
+        disposeUi = undefined
+      }
+    } else if (!enabled() && disposeUi !== undefined) {
+      disposeUi()
+      disposeUi = undefined
+    }
+  }
+  settingsScope.subscribe(syncUi)
+  syncUi()
+}

package/src/client/locales.ts

@@ -0,0 +1,108 @@
+/**
+ * dsh-pet locale dictionaries (zh/en).
+ * @module @linxin666/dsh-pet/client/locales
+ */
+
+/** Dictionary namespace this package registers. */
+export const NS = 'pet'
+
+/** Chinese copy. */
+export const zh = {
+  'pet.feed': '喂食',
+  'pet.hide': '隐藏',
+  'pet.rename': '改名',
+  'pet.confirm': '确定',
+  'pet.namePlaceholder': '输入新名字',
+  'pet.summon': '召唤{name}',
+  'pet.rank': '亲密度 {rank}',
+  'pet.points': '{points} 点',
+  'pet.treats': '小鱼干 ×{n}',
+  'pet.state.loading': '鲸鱼娘正在赶来…',
+  'pet.state.error': '鲸鱼娘迷路了（连接失败）',
+  // 插件设置卡片（settings.plugin.item 席位）。
+  'settings.title': '宠物',
+  'settings.description': '鲸鱼娘的显示布局与名字。',
+  'settings.enabled': '启用宠物',
+  'settings.enabledHint': '关闭后隐藏宠物并停止轮询，可在设置里重新启用。',
+  'settings.visible': '显示宠物',
+  'settings.visibleHint': '关闭后宠物隐藏，可从聊天输入区重新召唤。',
+  'settings.size': '大小（px）',
+  'settings.sizeHint': '精灵单元高度，范围 32–512。',
+  'settings.right': '距右侧（px）',
+  'settings.rightHint': '距视口右边缘的水平内缩距离。',
+  'settings.bottom': '距底部（px）',
+  'settings.bottomHint': '距视口底边的垂直内缩距离。',
+  'settings.name': '名字',
+  'settings.nameHint': '宠物显示名，1–20 个字符。',
+  'settings.inherit': '继承',
+  'settings.on': '开',
+  'settings.off': '关',
+  'settings.overridden': '已覆盖',
+  'settings.reset': '恢复默认',
+  'settings.readOnly': '当前部署的设置只读。',
+  'settings.expand': '展开设置',
+  'settings.collapse': '收起设置',
+  'settings.save': '保存',
+  'settings.saving': '保存中…',
+  'settings.discard': '放弃',
+  'settings.unsaved': '未保存',
+  'settings.saveFailed': '部署未接受这些值，已保留供你修改。',
+  'settings.invalidNumber': '请输入数字，留空则使用默认值。',
+} as const
+
+/** English copy. */
+export const en = {
+  'pet.feed': 'Feed',
+  'pet.hide': 'Hide',
+  'pet.rename': 'Rename',
+  'pet.confirm': 'OK',
+  'pet.namePlaceholder': 'Enter a new name',
+  'pet.summon': 'Summon {name}',
+  'pet.rank': 'Affinity {rank}',
+  'pet.points': '{points} pts',
+  'pet.treats': 'Treats ×{n}',
+  'pet.state.loading': 'The whale girl is on her way…',
+  'pet.state.error': 'The whale girl is lost (connection failed)',
+  // Plugin settings card (the `settings.plugin.item` seat).
+  'settings.title': 'Pet',
+  'settings.description': 'The whale girl\u2019s display layout and name.',
+  'settings.enabled': 'Enable the pet',
+  'settings.enabledHint': 'When off, the pet hides and polling stops; re-enable it here.',
+  'settings.visible': 'Show the pet',
+  'settings.visibleHint': 'When off, the pet hides; summon it again from the input row.',
+  'settings.size': 'Size (px)',
+  'settings.sizeHint': 'Sprite cell height, 32\u2013512.',
+  'settings.right': 'Right inset (px)',
+  'settings.rightHint': 'Horizontal inset from the viewport right edge.',
+  'settings.bottom': 'Bottom inset (px)',
+  'settings.bottomHint': 'Vertical inset from the viewport bottom edge.',
+  'settings.name': 'Name',
+  'settings.nameHint': 'The pet\u2019s display name, 1\u201320 characters.',
+  'settings.inherit': 'Inherit',
+  'settings.on': 'On',
+  'settings.off': 'Off',
+  'settings.overridden': 'Overridden',
+  'settings.reset': 'Reset to default',
+  'settings.readOnly': 'This deployment stores settings read-only.',
+  'settings.expand': 'Show settings',
+  'settings.collapse': 'Hide settings',
+  'settings.save': 'Save',
+  'settings.saving': 'Saving\u2026',
+  'settings.discard': 'Discard',
+  'settings.unsaved': 'Unsaved',
+  'settings.saveFailed': 'The deployment did not accept these values; they were left for you to correct.',
+  'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
+} as const
+
+/** Key union for this namespace. */
+export type PetKey = keyof typeof zh
+
+/** The settings-card slice of the pet dictionary. */
+export type SettingsCardKey = PetKey
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** dsh-pet UI copy. */
+    pet: PetKey
+  }
+}

package/src/client/pet-store.ts

@@ -0,0 +1,80 @@
+/**
+ * Browser-side pet store: the pet state snapshot plus transient UI feedback
+ * (reaction bubbles), written only through the store's audit actions. The
+ * RPC polling and interactions live in the plugin apply body; components
+ * only ever read snapshots.
+ * @module @linxin666/dsh-pet/client/pet-store
+ */
+
+import { defineStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { EngineStoreHandle, EngineStoreInstance } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PetStateView } from '../service.ts'
+import type { PetInteraction } from '../affinity.ts'
+
+/** One transient reaction bubble on the pet. */
+export interface PetFeedback {
+  /** Bubble copy. */
+  text: string
+  /** Interaction kind driving the reaction animation. */
+  kind: PetInteraction | 'none'
+  /** Epoch ms when the bubble appeared (for expiry). */
+  at: number
+}
+
+/** Pet UI state as consumers see it. */
+export interface PetUiState {
+  /** Latest host snapshot; null before the first successful fetch. */
+  snapshot: PetStateView | null
+  /** Fetch lifecycle. */
+  state: 'loading' | 'ready' | 'error'
+  /** Transport error message (for the debug surface), when any. */
+  error: string | null
+  /** Active reaction bubble, if any. */
+  feedback: PetFeedback | null
+}
+
+/** Store write set. */
+export type PetUiActions = {
+  /** Replace the host snapshot (poll result). */
+  setSnapshot: (draft: PetUiState, snapshot: PetStateView) => void
+  /** Mark the fetch lifecycle. */
+  setState: (draft: PetUiState, state: PetUiState['state'], error: string | null) => void
+  /** Show a reaction bubble. */
+  setFeedback: (draft: PetUiState, feedback: PetFeedback | null) => void
+}
+
+/** Create the pet store handle (apply world only; never module-level). */
+export function createPetStore(): EngineStoreHandle<PetUiState, PetUiActions> {
+  return defineStore({
+    init: (): PetUiState => ({
+      snapshot: null,
+      state: 'loading',
+      error: null,
+      feedback: null,
+    }),
+    actions: {
+      setSnapshot: (draft, snapshot) => {
+        draft.snapshot = snapshot
+        draft.state = 'ready'
+        draft.error = null
+      },
+      setState: (draft, state, error) => {
+        draft.state = state
+        draft.error = error
+      },
+      setFeedback: (draft, feedback) => {
+        draft.feedback = feedback
+      },
+    },
+  })
+}
+
+export type { PetInteraction }
+
+/**
+ * A live pet store instance (one per host, owned by the plugin apply body —
+ * the pet itself is host-global, so its UI state must not ride the slot
+ * system's per-session store scoping).
+ */
+export type PetStoreInstance = EngineStoreInstance<PetUiState, PetUiActions>
+

package/src/client/pet.module.css

@@ -0,0 +1,185 @@
+.float {
+  position: fixed;
+  pointer-events: auto;
+  user-select: none;
+  -webkit-user-select: none;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.sprite {
+  position: relative;
+  image-rendering: auto;
+  touch-action: none;
+}
+
+.bubble {
+  position: absolute;
+  bottom: 100%;
+  margin-bottom: 6px;
+  white-space: nowrap;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 12px;
+  line-height: 1.4;
+  color: #fff;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  animation: pet-bubble-pop 2.6s ease-out forwards;
+  pointer-events: none;
+}
+
+.bubblePet {
+  background: rgba(244, 114, 182, 0.92);
+}
+
+.bubbleFeed {
+  background: rgba(56, 189, 248, 0.92);
+}
+
+@keyframes pet-bubble-pop {
+  0% {
+    opacity: 0;
+    transform: translateY(6px) scale(0.85);
+  }
+  15% {
+    opacity: 1;
+    transform: translateY(0) scale(1.05);
+  }
+  25% {
+    transform: translateY(0) scale(1);
+  }
+  75% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+    transform: translateY(-8px) scale(0.95);
+  }
+}
+
+.panel {
+  position: absolute;
+  bottom: calc(100% + 4px);
+  background: rgba(15, 23, 42, 0.92);
+  border: 1px solid rgba(148, 163, 184, 0.35);
+  border-radius: 10px;
+  padding: 8px 10px;
+  color: #e2e8f0;
+  font-size: 12px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.35);
+  backdrop-filter: blur(6px);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 132px;
+}
+
+.rankRow {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+  white-space: nowrap;
+}
+
+.nameCell {
+  font-weight: 600;
+}
+
+.renameRow {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+
+.nameInput {
+  flex: 1;
+  min-width: 0;
+  border: 1px solid rgba(125, 211, 252, 0.5);
+  border-radius: 6px;
+  background: rgba(30, 41, 59, 0.9);
+  color: #e2e8f0;
+  font-size: 12px;
+  padding: 3px 6px;
+  outline: none;
+}
+
+.nameInput:focus {
+  border-color: #38bdf8;
+  /* 2px accent ring (theme-agnostic) replacing the removed default outline. */
+  box-shadow: 0 0 0 2px rgba(56, 189, 248, 0.45);
+}
+
+.actions {
+  display: flex;
+  gap: 6px;
+}
+
+.action {
+  flex: 1;
+  border: none;
+  border-radius: 6px;
+  padding: 4px 8px;
+  font-size: 12px;
+  cursor: pointer;
+  color: #0f172a;
+  background: linear-gradient(180deg, #7dd3fc, #38bdf8);
+  transition: filter 120ms ease, box-shadow 120ms ease;
+}
+
+.action:hover {
+  filter: brightness(1.08);
+}
+
+.action:active {
+  filter: brightness(0.94);
+}
+
+.action:focus-visible {
+  outline: none;
+  /* 2px accent ring on the pet's own palette; stays visible on the dark
+     glass panel regardless of the GUI theme (theme-agnostic). */
+  box-shadow: 0 0 0 2px rgba(56, 189, 248, 0.85);
+}
+
+.summon {
+  border: 1px dashed rgba(125, 211, 252, 0.6);
+  background: rgba(15, 23, 42, 0.75);
+  color: #7dd3fc;
+  border-radius: 999px;
+  padding: 2px 10px;
+  font-size: 11px;
+  cursor: pointer;
+  transition: border-color 120ms ease, color 120ms ease,
+    background 120ms ease, box-shadow 120ms ease;
+}
+
+.summon:hover {
+  border-color: rgba(125, 211, 252, 0.95);
+  color: #bae6fd;
+  background: rgba(15, 23, 42, 0.9);
+}
+
+.summon:active {
+  color: #7dd3fc;
+  border-color: rgba(125, 211, 252, 0.8);
+}
+
+.summon:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px rgba(56, 189, 248, 0.85);
+}
+
+/* Reduced motion: freeze the reaction bubble and kill the overlay transitions
+   so the pet's motion is static or minimal without hiding interaction. */
+@media (prefers-reduced-motion: reduce) {
+  .bubble {
+    animation: none;
+    opacity: 1;
+  }
+
+  .action,
+  .summon {
+    transition: none;
+  }
+}