@linxin666/dsh-pet 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.i18n.yaml +2 -2
  2. package/README.md +30 -3
  3. package/README.zh.md +30 -3
  4. package/lib/client.js +178 -62
  5. package/lib/client.js.map +1 -1
  6. package/lib/index.js +734 -26
  7. package/lib/live2d-vendor.js +129 -95
  8. package/lib/live2d-vendor.js.map +1 -1
  9. package/lib/types/announce.d.ts +16 -0
  10. package/lib/types/announce.d.ts.map +1 -1
  11. package/lib/types/announce.js +16 -0
  12. package/lib/types/client/PetDockEntry.d.ts +6 -0
  13. package/lib/types/client/PetDockEntry.d.ts.map +1 -1
  14. package/lib/types/client/PetDockEntry.js +1 -1
  15. package/lib/types/client/PetSettingsCard.d.ts +4 -0
  16. package/lib/types/client/PetSettingsCard.d.ts.map +1 -1
  17. package/lib/types/client/PetSettingsCard.js +16 -1
  18. package/lib/types/client/PetSprite.d.ts +7 -0
  19. package/lib/types/client/PetSprite.d.ts.map +1 -1
  20. package/lib/types/client/PetSprite.js +23 -13
  21. package/lib/types/client/index.d.ts.map +1 -1
  22. package/lib/types/client/index.js +43 -11
  23. package/lib/types/client/locales.d.ts +4 -0
  24. package/lib/types/client/locales.d.ts.map +1 -1
  25. package/lib/types/client/locales.js +4 -0
  26. package/lib/types/client/renderers/frames2d.d.ts +5 -3
  27. package/lib/types/client/renderers/frames2d.d.ts.map +1 -1
  28. package/lib/types/client/renderers/frames2d.js +139 -33
  29. package/lib/types/index.d.ts +14 -3
  30. package/lib/types/index.d.ts.map +1 -1
  31. package/lib/types/index.js +15 -2
  32. package/lib/types/panel-actions.d.ts +96 -0
  33. package/lib/types/panel-actions.d.ts.map +1 -0
  34. package/lib/types/panel-actions.js +134 -0
  35. package/lib/types/routes.d.ts.map +1 -1
  36. package/lib/types/routes.js +10 -0
  37. package/lib/types/service.d.ts +137 -9
  38. package/lib/types/service.d.ts.map +1 -1
  39. package/lib/types/service.js +151 -19
  40. package/package.json +26 -30
  41. package/src/announce.ts +17 -0
  42. package/src/client/PetDockEntry.test.tsx +1 -0
  43. package/src/client/PetDockEntry.tsx +7 -0
  44. package/src/client/PetSettingsCard.test.tsx +88 -0
  45. package/src/client/PetSettingsCard.tsx +31 -0
  46. package/src/client/PetSprite.test.tsx +197 -0
  47. package/src/client/PetSprite.tsx +56 -12
  48. package/src/client/index.test.tsx +74 -4
  49. package/src/client/index.ts +43 -11
  50. package/src/client/locales.ts +4 -0
  51. package/src/client/renderers/frames2d.test.ts +103 -1
  52. package/src/client/renderers/frames2d.ts +143 -30
  53. package/src/index.test.ts +22 -0
  54. package/src/index.ts +28 -2
  55. package/src/panel-actions.test.ts +130 -0
  56. package/src/panel-actions.ts +182 -0
  57. package/src/registry.test.ts +3 -2
  58. package/src/routes.ts +9 -0
  59. package/src/service.test.ts +128 -0
  60. package/src/service.ts +206 -22
  61. package/lib/invariant.js +0 -34
  62. package/lib/state-NvDEoCln.js +0 -455
  63. package/lib/types/invariant.d.ts +0 -10
  64. package/lib/types/invariant.d.ts.map +0 -1
  65. package/lib/types/invariant.js +0 -27
  66. package/src/invariant.ts +0 -40
@@ -41,6 +41,12 @@ export interface PetInjected {
41
41
  dragEnd: (right: number, bottom: number) => void
42
42
  /** Rename the selected pet (persisted by the host). */
43
43
  rename: (name: string) => void
44
+ /**
45
+ * Report a click on one plugin-registered panel action (issue #6). The host
46
+ * dispatches it to the plugin that registered the action; the panel itself
47
+ * only renders the button the state snapshot served.
48
+ */
49
+ panelAction: (id: string) => void
44
50
  /** Navigate the GUI to the session a bubble reports on. */
45
51
  openSession: (sessionId: string) => void
46
52
  /** Clear the reaction bubble. */
@@ -116,6 +122,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
116
122
  onHide={props.hide}
117
123
  onDragEnd={props.dragEnd}
118
124
  onRename={props.rename}
125
+ onPanelAction={props.panelAction}
119
126
  onOpenSession={props.openSession}
120
127
  onFeedbackDone={props.feedbackDone}
121
128
  portalTarget={props.portalTarget}
@@ -41,6 +41,36 @@ function response(value: unknown, ok = true): Response {
41
41
  return { ok, status: ok ? 200 : 500, json: async () => value } as Response
42
42
  }
43
43
 
44
+ /**
45
+ * A Host-served pet namespace: the settings document, its user layer, and a
46
+ * mutate that applies the card's batch and publishes the settled view back,
47
+ * which is what the card's read-back judgment reads.
48
+ */
49
+ function readyForm(value: PetSettings) {
50
+ let section: PetSettings = { ...value }
51
+ // The Host document's user layer is keyed by field name, so the test seam
52
+ // writes through a record view of the same shape the form contract serves.
53
+ let user: Record<string, unknown> = {}
54
+ const listeners = new Set<() => void>()
55
+ const publish = () => { for (const listener of listeners) listener() }
56
+ const mutate = vi.fn(async (ops: ReadonlyArray<{ op: 'set' | 'unset'; path: string[]; value?: unknown }>) => {
57
+ for (const op of ops) {
58
+ const field = op.path[0] as string
59
+ if (op.op === 'set') user[field] = op.value
60
+ else delete user[field]
61
+ }
62
+ section = { ...value, ...user }
63
+ publish()
64
+ return true
65
+ })
66
+ const scope = {
67
+ getSnapshot: () => ({ status: 'ready', writable: true, value: section, base: value, user, revision: 1 }),
68
+ subscribe: (listener: () => void) => { listeners.add(listener); return () => { listeners.delete(listener) } },
69
+ mutate,
70
+ } as unknown as ConfigForm<PetSettings>
71
+ return { scope, mutate, value: () => ({ user }) }
72
+ }
73
+
44
74
  beforeAll(() => {
45
75
  document.documentElement.lang = 'zh'
46
76
  })
@@ -212,3 +242,61 @@ describe('pet settings card rendered without a Host settings form', () => {
212
242
  controller.dispose()
213
243
  })
214
244
  })
245
+
246
+ describe('the status bubble switch on the Host settings form', () => {
247
+ it('user switches the pet own bubbles off and the form writes the mode', async () => {
248
+ // Given a Host that serves the pet namespace with the shipped default
249
+ vi.useFakeTimers()
250
+ const { scope, value, mutate } = readyForm({ statusBubbles: 'auto' })
251
+ vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL) => {
252
+ const path = String(input)
253
+ if (path === '/api/pet/pets') return response([{ id: 'whale-girl', displayName: '鲸鱼娘' }])
254
+ if (path === '/api/pet/state') return response({ pet: { id: 'whale-girl' }, display: { visible: true } })
255
+ throw new Error('unexpected request: ' + path)
256
+ }))
257
+ const controller = new PetSettingsCardController(scope)
258
+ await vi.advanceTimersByTimeAsync(0)
259
+ const face = controller.inject()
260
+ const state = () => face.hooks.petSettingsCard.getSnapshot()
261
+
262
+ // When the card renders, the switch is on screen beside the other fields
263
+ render(
264
+ <PetSettingsCard
265
+ t={t}
266
+ usePetSettingsCard={select => useSyncExternalStore(face.hooks.petSettingsCard.subscribe, () => select(face.hooks.petSettingsCard.getSnapshot()))}
267
+ save={face.save}
268
+ discard={face.discard}
269
+ edit={face.edit}
270
+ resetField={face.resetField}
271
+ />,
272
+ )
273
+ expect(screen.getByLabelText(t('settings.statusBubbles'))).toBeTruthy()
274
+ expect(state()).toMatchObject({ statusBubbles: { text: 'auto', invalid: false } })
275
+
276
+ // When the user picks Off and saves
277
+ face.edit('statusBubbles', 'off')
278
+ expect(state()).toMatchObject({ dirty: true, statusBubbles: { text: 'off' } })
279
+ face.save()
280
+ await vi.waitFor(() => { expect(state().saving).toBe(false) })
281
+
282
+ // Then the settings document holds the mode, and the draft clears
283
+ expect(mutate).toHaveBeenCalledWith([{ op: 'set', path: ['statusBubbles'], value: 'off' }])
284
+ expect(value().user?.statusBubbles).toBe('off')
285
+ expect(state()).toMatchObject({ dirty: false, failed: false, statusBubbles: { text: 'off' } })
286
+ controller.dispose()
287
+ })
288
+
289
+ it('refuses a draft the switch does not accept instead of writing it', () => {
290
+ const { scope } = readyForm({ statusBubbles: 'auto' })
291
+ const face = new PetSettingsCardController(scope).inject()
292
+
293
+ face.edit('statusBubbles', 'maybe')
294
+
295
+ // The save stays blocked: a mode the host schema has no union member for
296
+ // must never reach the settings document.
297
+ expect(face.hooks.petSettingsCard.getSnapshot()).toMatchObject({
298
+ invalid: true,
299
+ statusBubbles: { text: 'maybe', invalid: true },
300
+ })
301
+ })
302
+ })
@@ -37,6 +37,8 @@ export interface PetSettings {
37
37
  petId?: string
38
38
  /** Status-decoration master switch (pet-center M5, #567). */
39
39
  decorationEnabled?: boolean
40
+ /** Whether the pet's own session/status bubbles render (issue #6). */
41
+ statusBubbles?: string
40
42
  }
41
43
 
42
44
  /** What the pet settings card renders. */
@@ -59,6 +61,8 @@ export interface PetSettingsCardState extends CardShell {
59
61
  petId: CardFieldState
60
62
  /** Status-decoration master switch. */
61
63
  decorationEnabled: CardFieldState
64
+ /** Whether the pet's own session/status bubbles render. */
65
+ statusBubbles: CardFieldState
62
66
  /** Pet choices (registry ids + display names), loaded from the host. */
63
67
  petChoices: readonly { value: string; label: string }[]
64
68
  }
@@ -71,6 +75,13 @@ export interface PetSettingsCardFace extends CardActions {
71
75
  }
72
76
  }
73
77
 
78
+ /**
79
+ * The bubble modes this card can write, in render order. Mirrors the host
80
+ * schema's union (see PetStatusBubbleMode); the browser half never imports the
81
+ * host module for a value, so the accepted set is spelled here as literals.
82
+ */
83
+ const STATUS_BUBBLE_CHOICES = ['auto', 'off'] as const
84
+
74
85
  /** One registry choice as served by '/api/pet/pets'. */
75
86
  interface PetChoice {
76
87
  id: string
@@ -128,6 +139,11 @@ export class PetSettingsCardController {
128
139
  this.form = new CardForm(scope, [
129
140
  booleanField('enabled'),
130
141
  booleanField('decorationEnabled'),
142
+ // The bubble switch is a two-value mode, not a boolean: 'off' is the
143
+ // opt-out, and a future mode (say, one that keeps only the current
144
+ // session's bubble) has to be able to join the same field without
145
+ // breaking every settings document already written.
146
+ choiceField('statusBubbles', STATUS_BUBBLE_CHOICES),
131
147
  booleanField('visible'),
132
148
  numberField('size'),
133
149
  numberField('right'),
@@ -268,6 +284,7 @@ export class PetSettingsCardController {
268
284
  petSelectionFallback: fallback,
269
285
  enabled: this.form.field('enabled'),
270
286
  decorationEnabled: this.form.field('decorationEnabled'),
287
+ statusBubbles: this.form.field('statusBubbles'),
271
288
  visible: fallback ? this.fallbackVisible() : this.form.field('visible'),
272
289
  size: this.form.field('size'),
273
290
  right: this.form.field('right'),
@@ -387,6 +404,20 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
387
404
  onEdit={(text) => { props.edit('decorationEnabled', text) }}
388
405
  onReset={() => { props.resetField('decorationEnabled') }}
389
406
  />}
407
+ {state.petSelectionFallback ? null : <ChoiceField
408
+ id="settings-pet-status-bubbles"
409
+ label={t('settings.statusBubbles')}
410
+ hint={t('settings.statusBubblesHint')}
411
+ inheritLabel={t('settings.inherit')}
412
+ {...fieldProps}
413
+ {...state.statusBubbles}
414
+ choices={[
415
+ { value: STATUS_BUBBLE_CHOICES[0], label: t('settings.on') },
416
+ { value: STATUS_BUBBLE_CHOICES[1], label: t('settings.off') },
417
+ ]}
418
+ onEdit={(text) => { props.edit('statusBubbles', text) }}
419
+ onReset={() => { props.resetField('statusBubbles') }}
420
+ />}
390
421
  <ChoiceField
391
422
  id="settings-pet-pet"
392
423
  label={t('settings.pet')}
@@ -9,6 +9,7 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
9
9
  import { PetSprite, type PetSpriteProps } from './PetSprite.tsx'
10
10
  import { t } from './locales.ts'
11
11
  import type { PetStateView } from '../service.ts'
12
+ import type { PetAnnouncement } from '../announce.ts'
12
13
  import type { PetDefinition, PetTrackDef } from '../registry.ts'
13
14
  import type { PetAnimation } from '../state.ts'
14
15
  import type { DecorationView } from '../contracts/status-decoration.ts'
@@ -104,6 +105,7 @@ function petProps(overrides: Partial<PetSpriteProps> = {}): PetSpriteProps {
104
105
  onHide: vi.fn(),
105
106
  onDragEnd: vi.fn(),
106
107
  onRename: vi.fn(),
108
+ onPanelAction: vi.fn(),
107
109
  onOpenSession: vi.fn(),
108
110
  onFeedbackDone: vi.fn(),
109
111
  t,
@@ -1202,3 +1204,198 @@ describe('PetSprite portal target', () => {
1202
1204
  })
1203
1205
  })
1204
1206
 
1207
+ describe('PetSprite plugin panel actions (issue #6)', () => {
1208
+ const withActions = (...ids: string[]): PetStateView => ({
1209
+ ...snapshot,
1210
+ panelActions: ids.map(id => ({ id, label: id === 'pet-quota-swap' ? '换装' : id, order: 0 })),
1211
+ })
1212
+
1213
+ it('renders no plugin action while nothing is registered', () => {
1214
+ renderPet()
1215
+ fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
1216
+ // The row is exactly the built-in one: a pet with no sibling plugin
1217
+ // showing an action would mean the extension point leaked a default.
1218
+ expect(screen.getByText('喂食')).toBeDefined()
1219
+ expect(document.querySelectorAll('[data-dsh-pet-panel-action]')).toHaveLength(0)
1220
+ })
1221
+
1222
+ it('renders a registered action after the built-in row and reports its id on click', () => {
1223
+ const onPanelAction = vi.fn()
1224
+ renderPet({ snapshot: withActions('pet-quota-swap'), onPanelAction })
1225
+
1226
+ fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
1227
+ const action = screen.getByText('换装')
1228
+ // The built-in row keeps its order; the extension follows it.
1229
+ const row = action.closest('[class*="actions"]')!
1230
+ expect(Array.from(row.children).map(child => child.textContent))
1231
+ .toEqual(['喂食', '改名', '隐藏', '换装'])
1232
+ expect(action.closest('button')?.getAttribute('data-dsh-pet-panel-action')).toBe('pet-quota-swap')
1233
+
1234
+ fireEvent.click(action)
1235
+ expect(onPanelAction).toHaveBeenCalledWith('pet-quota-swap')
1236
+ })
1237
+
1238
+ it('renders the plugin tooltip the registration declared', () => {
1239
+ renderPet({
1240
+ snapshot: {
1241
+ ...snapshot,
1242
+ panelActions: [{ id: 'pet-quota-swap', label: '换装', title: '切换到下一只宠物', order: 0 }],
1243
+ },
1244
+ })
1245
+ fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
1246
+ expect(screen.getByText('换装').closest('button')?.getAttribute('title')).toBe('切换到下一只宠物')
1247
+ })
1248
+
1249
+ it('shows a plugin action even when a voice pack hides every built-in action', () => {
1250
+ renderPet({
1251
+ definition: { ...petDefinition(), panel: { actions: [] } },
1252
+ snapshot: withActions('pet-quota-swap'),
1253
+ })
1254
+ fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
1255
+ expect(screen.queryByText('喂食')).toBeNull()
1256
+ expect(screen.getByText('换装')).toBeDefined()
1257
+ })
1258
+ })
1259
+
1260
+ describe('PetSprite status bubble switch (issue #6)', () => {
1261
+ const busy = (mode?: 'auto' | 'off'): PetStateView => ({
1262
+ ...snapshot,
1263
+ animation: 'running',
1264
+ phase: 'thinking',
1265
+ bubble: '正在思考',
1266
+ sessions: [
1267
+ { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考' },
1268
+ { sessionId: 's-b', animation: 'running-right', phase: 'tool', bubble: '正在使用 grep' },
1269
+ ],
1270
+ ...(mode === undefined ? {} : { statusBubbles: mode }),
1271
+ })
1272
+
1273
+ it('keeps the shipped bubbles for a host that serves no mode', () => {
1274
+ renderPet({ snapshot: busy() })
1275
+ expect(screen.queryAllByText('正在思考').length).toBeGreaterThan(0)
1276
+ })
1277
+
1278
+ it('hides the built-in session and status bubbles when they are switched off', () => {
1279
+ renderPet({ snapshot: busy('off') })
1280
+ // Neither the multi-session stack nor the legacy single status bubble.
1281
+ expect(screen.queryAllByText('正在思考')).toHaveLength(0)
1282
+ expect(screen.queryByText('正在使用 grep')).toBeNull()
1283
+ })
1284
+
1285
+ it('keeps a sibling plugin announcement bubble while the built-in ones are off', () => {
1286
+ renderPet({
1287
+ snapshot: {
1288
+ ...busy('off'),
1289
+ announcement: {
1290
+ source: 'dsh-pet-quota',
1291
+ kind: 'cost',
1292
+ title: 'DeepSeek',
1293
+ amount: '今日 1.2M tokens',
1294
+ tone: 'ok',
1295
+ ttlMs: 60_000,
1296
+ at: Date.now(),
1297
+ },
1298
+ },
1299
+ })
1300
+ // The point of the switch: the pet stops speaking for itself, and a plugin
1301
+ // that drives its own bubble surface still gets the row.
1302
+ expect(screen.queryAllByText('正在思考')).toHaveLength(0)
1303
+ expect(screen.queryByText('今日 1.2M tokens')).not.toBeNull()
1304
+ })
1305
+
1306
+ it('keeps the interaction feedback bubble while the built-in ones are off', () => {
1307
+ renderPet({ snapshot: busy('off'), feedback: { text: '摸摸成功', kind: 'pet', at: 1 } })
1308
+ expect(screen.queryByText('摸摸成功')).not.toBeNull()
1309
+ })
1310
+ })
1311
+
1312
+ describe('PetSprite announcement bubbles from several publishers (issue #1812)', () => {
1313
+ /** One publisher's announcement as the host serves it, `ageMs` old. */
1314
+ const from = (source: string, amount: string, ageMs = 0): PetAnnouncement => ({
1315
+ source,
1316
+ kind: 'cost',
1317
+ title: 'DeepSeek',
1318
+ amount,
1319
+ tone: 'ok',
1320
+ ttlMs: 60_000,
1321
+ at: Date.now() - ageMs,
1322
+ })
1323
+
1324
+ it('renders one bubble per publishing plugin', () => {
1325
+ renderPet({
1326
+ snapshot: {
1327
+ ...snapshot,
1328
+ announcements: [
1329
+ from('dsh-pet-quota', '今日 1.2M tokens'),
1330
+ from('dsh-pet-notices', '余额 ¥110.00'),
1331
+ ],
1332
+ },
1333
+ })
1334
+
1335
+ // The reported defect: one publisher used to erase the other's bubble.
1336
+ expect(screen.queryByText('今日 1.2M tokens')).not.toBeNull()
1337
+ expect(screen.queryByText('余额 ¥110.00')).not.toBeNull()
1338
+ })
1339
+
1340
+ it('stacks the publishers above the session bubbles in the served order', () => {
1341
+ renderPet({
1342
+ snapshot: {
1343
+ ...snapshot,
1344
+ bubble: '正在思考',
1345
+ sessions: [{ sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考' }],
1346
+ announcements: [
1347
+ from('dsh-pet-quota', '今日 1.2M tokens'),
1348
+ from('dsh-pet-notices', '余额 ¥110.00'),
1349
+ ],
1350
+ },
1351
+ })
1352
+
1353
+ // Each announcement carries its publisher's tag, so the DOM order is what
1354
+ // the bubble stack renders: session bubble first, publishers above it.
1355
+ const stack = screen.getByText('正在思考').closest('div')!
1356
+ const tags = Array.from(stack.querySelectorAll('[data-dsh-pet-announcement]'))
1357
+ .map(node => node.getAttribute('data-dsh-pet-announcement'))
1358
+ expect(tags).toEqual(['dsh-pet-quota', 'dsh-pet-notices'])
1359
+ })
1360
+
1361
+ it('renders the singular field alone for a host predating the per-source array', () => {
1362
+ renderPet({ snapshot: { ...snapshot, announcement: from('dsh-pet-quota', '今日 1.2M tokens') } })
1363
+
1364
+ // A rolling upgrade must not blank a publisher: the pre-#1812 host field is
1365
+ // still read when the array is absent.
1366
+ expect(screen.queryByText('今日 1.2M tokens')).not.toBeNull()
1367
+ })
1368
+
1369
+ it('drops a publisher whose ttl lapsed between polls', () => {
1370
+ renderPet({
1371
+ snapshot: {
1372
+ ...snapshot,
1373
+ announcements: [
1374
+ from('dsh-pet-quota', '今日 1.2M tokens', 61_000),
1375
+ from('dsh-pet-notices', '余额 ¥110.00'),
1376
+ ],
1377
+ },
1378
+ })
1379
+
1380
+ expect(screen.queryByText('今日 1.2M tokens')).toBeNull()
1381
+ expect(screen.queryByText('余额 ¥110.00')).not.toBeNull()
1382
+ })
1383
+
1384
+ it('yields the whole stack to interaction feedback', () => {
1385
+ renderPet({
1386
+ snapshot: {
1387
+ ...snapshot,
1388
+ announcements: [
1389
+ from('dsh-pet-quota', '今日 1.2M tokens'),
1390
+ from('dsh-pet-notices', '余额 ¥110.00'),
1391
+ ],
1392
+ },
1393
+ feedback: { text: '摸摸成功', kind: 'pet', at: 3 },
1394
+ })
1395
+
1396
+ expect(screen.queryByText('摸摸成功')).not.toBeNull()
1397
+ expect(screen.queryByText('今日 1.2M tokens')).toBeNull()
1398
+ expect(screen.queryByText('余额 ¥110.00')).toBeNull()
1399
+ })
1400
+ })
1401
+
@@ -50,6 +50,13 @@ export interface PetSpriteProps {
50
50
  onDraggingChange?: (dragging: boolean) => void
51
51
  /** Rename the selected pet (persisted by the host). */
52
52
  onRename: (name: string) => void
53
+ /**
54
+ * Report a click on one plugin-registered action (issue #6). The buttons
55
+ * themselves come from the state snapshot's `panelActions` slice, so the
56
+ * panel renders exactly the registrations the host serves and adds nothing
57
+ * of its own.
58
+ */
59
+ onPanelAction: (id: string) => void
53
60
  /** Navigate to the session one status bubble reports on. */
54
61
  onOpenSession: (sessionId: string) => void
55
62
  /** Clear the reaction bubble (after its CSS animation). */
@@ -616,20 +623,30 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
616
623
  // is hovered/pinned open. The legacy single 'bubble' is the fallback when
617
624
  // the host serves no per-session list. The hover panel normally sits below
618
625
  // the sprite, so the bubbles stay visible and clickable — no region swap.
619
- const sessionBubbles = snapshot?.sessions ?? []
626
+ // Whether the pet renders its OWN session/status bubbles (issue #6). Only
627
+ // these are gated: the interaction feedback bubble and a sibling plugin's
628
+ // announcement bubble are separate surfaces and keep rendering, so a plugin
629
+ // that drives its own bubble can switch the built-in ones off. A host that
630
+ // predates the field serves no mode at all, which reads as 'auto' — the
631
+ // behavior that shipped before the switch existed.
632
+ const statusBubblesOn = (snapshot?.statusBubbles ?? 'auto') !== 'off'
633
+ const sessionBubbles = statusBubblesOn ? (snapshot?.sessions ?? []) : []
620
634
  const stackOpen = stackPeek || stackPinned
621
635
  const collapsed = !stackOpen && sessionBubbles.length > 1
622
636
  const visibleSessions = collapsed ? sessionBubbles.slice(0, 1) : sessionBubbles
623
- const statusBubble = feedback === null && sessionBubbles.length === 0
637
+ const statusBubble = statusBubblesOn && feedback === null && sessionBubbles.length === 0
624
638
  ? snapshot?.bubble
625
639
  : undefined
626
- // The freshest plugin-authored announcement (dsh-usage linkage): a
627
- // dedicated, specially styled bubble above the session stack. The host
628
- // already TTL-filters; this client-side check covers the last poll tick.
629
- const announcement = snapshot?.announcement
630
- const usageAnnouncement = feedback === null && announcement !== undefined && announcementFresh(announcement, Date.now())
631
- ? announcement
632
- : undefined
640
+ // The plugin-authored announcements: one dedicated, specially styled bubble
641
+ // per publishing plugin above the session stack (issue #1812 — the contract
642
+ // used to hold a single slot, so a second publisher displaced the first).
643
+ // The host already TTL-filters; this client-side check covers the last poll
644
+ // tick. A host predating the array serves the singular field only, and a
645
+ // browser half predating it (this file, before the upgrade) renders the same
646
+ // one bubble, so neither side of a rolling upgrade loses a publisher.
647
+ const announced = snapshot?.announcements ?? (snapshot?.announcement !== undefined ? [snapshot.announcement] : [])
648
+ const now = Date.now()
649
+ const usageAnnouncements = feedback === null ? announced.filter(entry => announcementFresh(entry, now)) : []
633
650
  // Each session's inner whisper (碎碎念) rides its own bubble — short
634
651
  // inner-voice copy woken by that session's activity, never the model's or
635
652
  // another session's. Instead of a second bubble of its own, a fresh
@@ -637,7 +654,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
637
654
  // never wears two voices at once. Interaction feedback takes over the
638
655
  // whole bubble area while it plays, so whispers yield to it like status
639
656
  // copy.
640
- const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined
657
+ const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncements.length > 0
641
658
  const displayName = snapshot?.name ?? definition.displayName
642
659
  // The host-served status decoration (M5, #567); absent = text-only bubbles.
643
660
  const decoration = snapshot?.decoration
@@ -754,7 +771,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
754
771
  {feedback.text}
755
772
  </div>
756
773
  )}
757
- {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined) && (
774
+ {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncements.length > 0) && (
758
775
  <div
759
776
  ref={bubbleRef}
760
777
  className={styles.bubbleStack}
@@ -825,7 +842,16 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
825
842
  {statusBubble}
826
843
  </div>
827
844
  )}
828
- {usageAnnouncement !== undefined && <UsageAnnouncementBubble announcement={usageAnnouncement} />}
845
+ {/*
846
+ One bubble per publishing plugin, in the order the host serves
847
+ them. Keyed by `source`, not by arrival: a repeating publisher
848
+ updates its own bubble in place instead of remounting (which would
849
+ replay the entrance animation on every poll), and two publishers on
850
+ different cadences keep their positions.
851
+ */}
852
+ {usageAnnouncements.map(entry => (
853
+ <UsageAnnouncementBubble key={entry.source} announcement={entry} />
854
+ ))}
829
855
  </div>
830
856
  )}
831
857
  {hovered && dragRef.current === null && (
@@ -936,6 +962,24 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
936
962
  {props.t('pet.gameplay.menu')}
937
963
  </button>
938
964
  )}
965
+ {/*
966
+ Plugin-registered actions (issue #6). They follow the built-in
967
+ ones so the pet's own row keeps its fixed order, and they
968
+ carry their registration id as a data attribute so a test (or
969
+ a skin) can address one action without depending on its label.
970
+ */}
971
+ {(snapshot?.panelActions ?? []).map(action => (
972
+ <button
973
+ key={action.id}
974
+ type="button"
975
+ className={styles.action}
976
+ data-dsh-pet-panel-action={action.id}
977
+ {...(action.title === undefined ? {} : { title: action.title })}
978
+ onClick={() => { props.onPanelAction(action.id) }}
979
+ >
980
+ {action.label}
981
+ </button>
982
+ ))}
939
983
  </div>
940
984
  </>
941
985
  )}
@@ -65,10 +65,17 @@ interface FakeClientLifecycle {
65
65
  setEnabled(enabled: boolean): void
66
66
  /** Namespaces the family settings binder was asked for (empty without one). */
67
67
  boundNamespaces(): string[]
68
+ /** Namespaces the framework translate seat was bound for. */
69
+ localeSeats(): string[]
68
70
  /** Publish the family settings binder, as the aggregate's async mount does. */
69
71
  publishFamilyBinder(enabled: boolean): void
72
+ /** Move the shared mirror to another state and notify its subscribers. */
73
+ settleFallback(status: FallbackStatus): void
70
74
  }
71
75
 
76
+ /** The states the shared per-entry mirror can report for the pet namespace. */
77
+ type FallbackStatus = 'ready' | 'loading' | 'unavailable'
78
+
72
79
  const activeLifecycles: FakeClientLifecycle[] = []
73
80
 
74
81
  afterEach(() => {
@@ -85,8 +92,10 @@ interface FakeContextOptions {
85
92
  * What the shared per-entry form answers before any family binder exists.
86
93
  * The aggregate renames the pet row to 'web-ui-pet', so the family alias
87
94
  * 'pet' is never a served key there and the fallback reports unavailable.
95
+ * 'loading' is the state a host-persisted mirror starts in: it has published
96
+ * no view yet, so it answers nothing either way (#1813).
88
97
  */
89
- fallbackStatus?: 'ready' | 'unavailable'
98
+ fallbackStatus?: FallbackStatus
90
99
  }
91
100
 
92
101
  function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
@@ -94,11 +103,12 @@ function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
94
103
  const settingsListeners = new Set<() => void>()
95
104
  const sessionListeners = new Set<() => void>()
96
105
  const boundNamespaces: string[] = []
106
+ const localeSeats: string[] = []
97
107
  let settingsValue: { enabled?: boolean } | undefined = options.enabled === undefined ? undefined : { enabled: options.enabled }
98
108
  // The family binder is published later in the aggregate race; the shared form
99
109
  // answers 'unavailable' until then, exactly as the wrongly-keyed fallback does.
100
110
  let binderPublished = options.familyBinder === true
101
- const fallbackStatus = options.fallbackStatus ?? 'ready'
111
+ let fallbackStatus: FallbackStatus = options.fallbackStatus ?? 'ready'
102
112
  // The shared per-entry form a standalone install answers with: the plugin's
103
113
  // own row id IS served, so it carries the same values as the bound scope. A
104
114
  // test that sets fallbackStatus to 'unavailable' models the aggregate, where
@@ -115,7 +125,10 @@ function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
115
125
  mode: 'host',
116
126
  }
117
127
  : {
118
- status: 'unavailable',
128
+ // 'loading' and 'unavailable' carry no view: the first is the mirror
129
+ // before its first view, the second its answer for a key it never
130
+ // serves. Neither can answer, so neither is writable.
131
+ status: fallbackStatus,
119
132
  writable: false,
120
133
  value: undefined,
121
134
  base: undefined,
@@ -157,7 +170,17 @@ function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
157
170
  disposers.push(cleanup)
158
171
  return cleanup
159
172
  },
160
- locale: { register: () => () => {} },
173
+ locale: {
174
+ register: () => () => {},
175
+ // The framework translate seat for one namespace. The floating surface
176
+ // must be handed this function rather than the plugin's own zh/en
177
+ // dictionary, which resolves by <html lang> and sends every language
178
+ // except English to Chinese.
179
+ bind: (namespace: string) => {
180
+ localeSeats.push(namespace)
181
+ return (key: string) => 'seat:' + key
182
+ },
183
+ },
161
184
  // The family binder is optional (dsh-web-settings may be absent); both
162
185
  // answers are the shared per-entry form of this plugin's own profile entry.
163
186
  get: (name: string) => name === 'webUiSettings' && binderPublished ? familyBinder : undefined,
@@ -206,10 +229,15 @@ function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
206
229
  sessionsListenerCount: () => sessionListeners.size,
207
230
  setEnabled: (enabled: boolean) => { settingsValue = { enabled } },
208
231
  boundNamespaces: () => boundNamespaces,
232
+ localeSeats: () => localeSeats,
209
233
  publishFamilyBinder: (enabled: boolean) => {
210
234
  binderPublished = true
211
235
  settingsValue = { enabled }
212
236
  },
237
+ settleFallback: (status: FallbackStatus) => {
238
+ fallbackStatus = status
239
+ for (const listener of settingsListeners) listener()
240
+ },
213
241
  }
214
242
  activeLifecycles.push(lifecycle)
215
243
  return lifecycle
@@ -223,6 +251,15 @@ describe('pet client apply', () => {
223
251
  expect(root!.getAttribute('data-dsh-plugin')).toBe('pet')
224
252
  })
225
253
 
254
+ it('hands the floating entry the framework locale seat', () => {
255
+ const lifecycle = fakeContext()
256
+ apply(lifecycle.ctx)
257
+ // The floating surface has no session-scoped locale seat, so the mount has
258
+ // to bind the 'pet' namespace explicitly. Resolving copy from the plugin's
259
+ // own zh/en dictionary instead sent every language but English to Chinese.
260
+ expect(lifecycle.localeSeats()).toContain('pet')
261
+ })
262
+
226
263
  it('keeps one global pet root when two client factories overlap (#785)', () => {
227
264
  const first = fakeContext()
228
265
  apply(first.ctx)
@@ -334,6 +371,39 @@ describe('pet client apply', () => {
334
371
  vi.useRealTimers()
335
372
  })
336
373
 
374
+ it('keeps the retry window open while the shared form is still loading, then binds the late binder (#1813)', () => {
375
+ // Given a shared per-entry form that has published no view yet: on the
376
+ // loopback page the official per-row form starts out 'loading' for a
377
+ // host-persisted row, and 'loading' is no more an answer than 'unavailable'
378
+ // is — reading it as settled adopted the fallback on sight, armed no retry,
379
+ // and left the aggregate's binder unpicked forever.
380
+ vi.useFakeTimers()
381
+ const lifecycle = fakeContext({ fallbackStatus: 'loading' })
382
+
383
+ // When the pet client plugin applies inside that window
384
+ apply(lifecycle.ctx)
385
+
386
+ // Then no namespace was bound and the pet surface is not up yet
387
+ expect(lifecycle.boundNamespaces()).toEqual([])
388
+ expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(0)
389
+
390
+ // And when the mirror answers with the aggregate's view — which serves the
391
+ // renamed 'web-ui-pet' row only, so the 'pet' alias can never answer it —
392
+ // the window stays open instead of settling on a form that cannot answer.
393
+ lifecycle.settleFallback('unavailable')
394
+ vi.advanceTimersByTime(BINDER_RETRY_MS)
395
+ expect(lifecycle.boundNamespaces()).toEqual([])
396
+
397
+ // And when the aggregate finally publishes the binder, the form binds the
398
+ // real namespace and the pet surface comes up.
399
+ lifecycle.publishFamilyBinder(true)
400
+ vi.advanceTimersByTime(BINDER_RETRY_MS)
401
+
402
+ expect(lifecycle.boundNamespaces()).toEqual(['pet'])
403
+ expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
404
+ vi.useRealTimers()
405
+ })
406
+
337
407
  it('user gets the pet settings form through the family binder when the group plugin is mounted', () => {
338
408
  // Given a client context that provides the dsh-web-settings family binder
339
409
  // and answers 'disabled' through the form that binder returns