@linxin666/dsh-pet 0.3.23 → 0.3.25

package/src/client/index.test.tsx

@@ -63,6 +63,8 @@ interface FakeClientLifecycle {
   emitSettings(): void
   sessionsListenerCount(): number
   setEnabled(enabled: boolean): void
+  /** Namespaces the family settings binder was asked for (empty without one). */
+  boundNamespaces(): string[]
 }
 
 const activeLifecycles: FakeClientLifecycle[] = []
@@ -72,11 +74,19 @@ afterEach(() => {
   document.body.replaceChildren()
 })
 
-function fakeContext(): FakeClientLifecycle {
+interface FakeContextOptions {
+  /** Provide the dsh-web-settings family binder, as the group plugin does. */
+  familyBinder?: boolean
+  /** Initial value of the settings section the bound form answers with. */
+  enabled?: boolean
+}
+
+function fakeContext(options: FakeContextOptions = {}): FakeClientLifecycle {
   const disposers: (() => void)[] = []
   const settingsListeners = new Set<() => void>()
   const sessionListeners = new Set<() => void>()
-  let settingsValue: { enabled?: boolean } | undefined
+  const boundNamespaces: string[] = []
+  let settingsValue: { enabled?: boolean } | undefined = options.enabled === undefined ? undefined : { enabled: options.enabled }
   const scope = {
     getSnapshot: () => ({
       status: 'ready',
@@ -92,6 +102,12 @@ function fakeContext(): FakeClientLifecycle {
       return () => { settingsListeners.delete(listener) }
     },
   }
+  const familyBinder = {
+    bind: (spec: { namespace: string }) => {
+      boundNamespaces.push(spec.namespace)
+      return scope
+    },
+  }
   const ctx = {
     effect: (fn: () => unknown, _label?: string) => {
       const dispose = fn()
@@ -101,8 +117,10 @@ function fakeContext(): FakeClientLifecycle {
       return cleanup
     },
     locale: { register: () => () => {} },
-    get: () => undefined,
-    settingsScope: { bind: () => scope },
+    // The family binder is optional (dsh-web-settings may be absent); both
+    // answers are the shared per-entry form of this plugin's own profile entry.
+    get: (name: string) => name === 'webUiSettings' && options.familyBinder === true ? familyBinder : undefined,
+    configForms: { get: () => scope },
     slots: {
       // Cordis runs the factory when the slot mounts and its returned
       // disposer when the fiber disposes; mirror that so slot content
@@ -139,6 +157,7 @@ function fakeContext(): FakeClientLifecycle {
     },
     sessionsListenerCount: () => sessionListeners.size,
     setEnabled: (enabled: boolean) => { settingsValue = { enabled } },
+    boundNamespaces: () => boundNamespaces,
   }
   activeLifecycles.push(lifecycle)
   return lifecycle
@@ -236,4 +255,18 @@ describe('pet client apply', () => {
     expect(lifecycle.sessionsListenerCount()).toBe(1)
     expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
   })
+
+  it('user gets the pet settings form through the family binder when the group plugin is mounted', () => {
+    // Given a client context that provides the dsh-web-settings family binder
+    // and answers 'disabled' through the form that binder returns
+    const lifecycle = fakeContext({ familyBinder: true, enabled: false })
+
+    // When the pet client plugin applies
+    apply(lifecycle.ctx)
+
+    // Then the card bound the 'pet' namespace through that binder...
+    expect(lifecycle.boundNamespaces()).toEqual(['pet'])
+    // ...and the pet surface followed the form it answered (disabled -> hidden)
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(0)
+  })
 })

package/src/client/index.ts

@@ -16,15 +16,18 @@
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import type { ISessions } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
-import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/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).
+// Type-only: pulls the shared configuration forms Context merge (ctx.configForms).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls the ctx.slots merge (the renderer owns the slot registry since 0.1.2).
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+// Type-only: pulls the workspace plugin's Context merge (ctx.uiWorkspace), the
+// multi-instance navigation face that replaced ISessions.open().
+import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetGameplayVerbResult, PetInteractResult, PetStateView } from '../service.ts'
 import type { PetInteraction } from '../affinity.ts'
@@ -40,6 +43,7 @@ import { frames2dRenderer } from './renderers/frames2d.ts'
 import { registerPetUiTeardown, takeoverPetUiTeardown } from './ui-teardown.ts'
 import { PetSettingsSection, PetSettingsCardController, type PetSettings } from './PetSettingsCard.tsx'
 import { NS, en, zh, t } from './locales.ts'
+import { mainViewSessionId } from './main-session.ts'
 import { reportDailyHeartbeat } from './telemetry.ts'
 
 /** The host pet API as the browser sees it (same-origin JSON endpoints). */
@@ -54,7 +58,7 @@ interface PetHttpApi {
   setPet(petId: string): Promise<{ ok: true; petId: string } | { ok: false; error: string }>
   setSkin(skin?: string): Promise<{ ok: boolean; error?: string; skin?: string }>
   gameplayTouch(zone?: string): Promise<PetGameplayVerbResult>
-  gameplaySetMode(mode: 'work' | 'sleep' | null): Promise<PetGameplayVerbResult>
+  gameplaySetMode(mode: string | null): Promise<PetGameplayVerbResult>
   gameplayWorkTick(): Promise<PetGameplayVerbResult>
   gameplayBuy(item: string): Promise<PetGameplayVerbResult>
 }
@@ -94,11 +98,11 @@ const petApi: PetHttpApi = {
 /** Poll interval for the host snapshot. */
 const POLL_MS = 2000
 
-/** Settings namespace the pet settings card edits (the Host plugin registers it). */
+/** Settings namespace of the pet's settings page. It is the profile entry id the Host serves a form for. */
 const PET_SETTINGS_NS = 'pet'
 
 /** Required services (sessions powers bubble-to-session navigation). */
-export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote', 'sessions']
+export const inject = ['slots', 'locale', 'connection', 'configForms', 'remote', 'sessions', 'uiWorkspace']
 
 /** Re-exported for consumers that type against the injected face. */
 export type { PetInjected, PetDockEntryProps } from './PetDockEntry.tsx'
@@ -111,12 +115,49 @@ export type { PetDefinition } from '../registry.ts'
 declare module '@deepseek-ai/cordis' {
   interface Context {
     /**
-     * Optional rc.6 compatibility binder provided by dsh-web-settings;
-     * absent when that group plugin is not installed, so callers fall back to
-     * the official settings scope.
+     * Optional family binder provided by dsh-web-settings; absent when that
+     * group plugin is not installed, so callers fall back to the shared
+     * per-entry form.
      */
-    webUiSettings?: { bind<S>(spec: SettingsScopeSpec<S>): SettingsScope<S> }
+    webUiSettings?: {
+      bind<S>(spec: { namespace: string; decode?: (section: unknown) => S | undefined }): ConfigForm<S>
+    }
+  }
+}
+
+/**
+ * The configuration form the settings card stages and saves through: the
+ * family binder when dsh-web-settings is mounted, otherwise the shared form of
+ * this plugin's own profile entry.
+ *
+ * The two are not interchangeable by name. A plugin's settings ARE its own
+ * config on 0.1.7, so the form belongs to the profile entry that carries the
+ * plugin — and only the family binder knows which entry that is, because the
+ * family bundle renames child rows ('pet' becomes 'web-ui-pet' there) while a
+ * standalone install keeps the package's own id.
+ * @param ctx - client root context.
+ * @returns the form for the pet's settings page.
+ */
+const AGGREGATE_ENTRY_ID = 'web-ui-pet'
+const PET_ENTRY_IDS: readonly string[] = [AGGREGATE_ENTRY_ID, 'ui-pet', PET_SETTINGS_NS]
+
+function servedEntryId(forms: ConfigForms): string {
+  let served: readonly string[] | undefined
+  try {
+    served = forms.describe().getSnapshot().view?.namespaces.map(view => view.ns)
+  } catch {
+    served = undefined
+  }
+  if (!served || served.length === 0) return PET_SETTINGS_NS
+  return PET_ENTRY_IDS.find(id => served.includes(id)) ?? PET_SETTINGS_NS
+}
+
+function petSettingsForm(ctx: ClientContext): ConfigForm<PetSettings> {
+  const binder = ctx.get('webUiSettings')
+  if (binder !== undefined && typeof binder.bind === 'function') {
+    return binder.bind<PetSettings>({ namespace: PET_SETTINGS_NS })
   }
+  return ctx.configForms.get<PetSettings>(servedEntryId(ctx.configForms))
 }
 
 /**
@@ -158,24 +199,23 @@ export function apply(ctx: ClientContext): void {
   defaultPetRendererRegistry.register(live2dRenderer)
   defaultPetRendererRegistry.register(frames2dRenderer)
 
-  const binder = ctx.get('webUiSettings') ?? ctx.settingsScope
-  const settingsScope = binder.bind<PetSettings>({ namespace: PET_SETTINGS_NS })
+  const settingsForm = petSettingsForm(ctx)
   const enabled = (): boolean => {
-    const snapshot = settingsScope.getSnapshot()
+    const snapshot = settingsForm.getSnapshot()
     return snapshot.status === 'ready'
       ? snapshot.value?.enabled ?? true
       : snapshot.status === 'unavailable'
   }
 
-  // First-level settings section: one staged form over the 'pet' settings
-  // namespace, registered as a top-level settings page. The controller loads
-  // the petId choices from the registry endpoint itself — the registry lists
-  // the available pets (built-in assets plus user dirs), so the section only
-  // ever shows installed pets. Installing new pets happens in the Workshop
-  // store.
-  const petSettings = new PetSettingsCardController(settingsScope)
+  // First-level settings section: one staged form over the 'pet' profile
+  // entry's configuration, registered as a top-level settings page. The
+  // controller loads the petId choices from the registry endpoint itself — the
+  // registry lists the available pets (built-in assets plus user dirs), so the
+  // section only ever shows installed pets. Installing new pets happens in the
+  // Workshop store.
+  const petSettings = new PetSettingsCardController(settingsForm)
   // The section entry owns the controller: unregistering it (fiber disposal,
-  // hot reload) releases the scope subscription through petSettings.dispose.
+  // hot reload) releases the form subscription through petSettings.dispose.
   ctx.slots.inject('settings.section', () => {
     try {
       const unregister = ctx.slots.register({
@@ -224,19 +264,17 @@ export function apply(ctx: ClientContext): void {
       const setState = petStore.actions.setState
       const setFeedback = petStore.actions.setFeedback
 
-      // Clicking a session bubble jumps the GUI to that session; the same
-      // sessions face reports which session the user is currently on, so the
-      // host can lead the bubble stack with it. A bubble can outlive its
-      // disposed session by one poll tick, and the sessions service fails
-      // loud on unknown ids, so consult the live list first. The pet's type
-      // program also loads the host-side dsh-session package through the
-      // service types, whose Context merge declares a different 'sessions'
-      // face; pin the browser runtime's outward face here.
+      // Clicking a session bubble jumps the GUI to that session; the
+      // catalog's main-view ownership marker tells which session the main view
+      // holds (the multi-instance replacement for the removed list.current), so
+      // the host can lead the bubble stack with it. A bubble can outlive its
+      // disposed session by one poll tick, and navigation rejects unknown ids,
+      // so consult the live list first. The pet's type program also loads the
+      // host-side dsh-session package through the service types, whose Context
+      // merge declares a different 'sessions' face; pin the browser runtime's
+      // outward face here.
       const sessions = ctx.sessions as unknown as ISessions
-      const currentSessionId = (): string | undefined => {
-        const current = sessions.list.getSnapshot().current
-        return current === undefined ? undefined : String(current)
-      }
+      const currentSessionId = (): string | undefined => mainViewSessionId(sessions.list.getSnapshot().byId)
 
       // The registry list is fetched lazily with retries baked into the poll
       // cycle: until it lands, the dock entry renders nothing and every 2s
@@ -315,7 +353,9 @@ export function apply(ctx: ClientContext): void {
       const openSession = (sessionId: string): void => {
         const list = sessions.list.getSnapshot()
         if ((list.byId as any)[sessionId] === undefined) return
-        sessions.open(sessionId as never)
+        // Navigation belongs to the workspace UI since the multi-instance Client
+        // Session model; the Session Controller no longer opens one.
+        ctx.uiWorkspace.openSession(sessionId as never)
       }
 
       const injected = (): PetInjected => ({
@@ -456,7 +496,7 @@ export function apply(ctx: ClientContext): void {
   // (issue #785): disposal drops the subscription and tears the UI down
   // (terminal), so a hot-reloaded or re-injected bundle never leaves the
   // previous React root, container, or poll loop behind on document.body.
-  const unsubscribeSettings = settingsScope.subscribe(syncUi)
+  const unsubscribeSettings = settingsForm.subscribe(syncUi)
   ctx.effect(
     () => () => {
       unsubscribeSettings()

package/src/client/main-session.ts

@@ -0,0 +1,43 @@
+// Generated by scripts/sync-shared.mjs from shared/client/main-session.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Main-view Session derivation for the multi-instance Client Session model.
+ *
+ * The Client Session Controller carries no global "current" selection: view
+ * selection belongs to the workspace UI, which owns the main-area reference and
+ * publishes it through the catalog's per-source ownership counts
+ * (`SessionSummary.retainedBy.mainView`). A plugin that needs the Session the
+ * main view shows derives it from that marker instead of the removed
+ * `SessionListState.current` field.
+ *
+ * The marker describes view ownership, not authority. It is the right input for
+ * presentation and for deciding which view a navigation targets; it is not a
+ * business fallback, because source counts never imply visibility or success.
+ * @module dsh-web/shared/main-session
+ */
+
+/** The catalog row subset this helper reads (a `SessionSummary` projection). */
+export interface MainViewOwnedRow<Id extends string = string> {
+  /** Catalog row identity. */
+  readonly id: Id
+  /** Per-source local ownership counts; absent rows are never owned. */
+  readonly retainedBy?: Readonly<Partial<Record<string, number>>> | undefined
+}
+
+/**
+ * Resolve the Session the main view currently shows.
+ *
+ * Reads the catalog's rows rather than a per-id retain-info source: ownership
+ * counts ride the list snapshot, so this neither allocates observers nor opens
+ * history, and a subscription to the list still fires when the selection moves.
+ * @param byId - the session catalog's rows (`SessionListState.byId`), when available.
+ * @returns the main-view session id, or undefined when the main view shows none.
+ */
+export function mainViewSessionId<Id extends string>(
+  byId: Readonly<Record<Id, MainViewOwnedRow<Id> | undefined>> | undefined | null,
+): Id | undefined {
+  if (byId === undefined || byId === null) return undefined
+  for (const row of Object.values<MainViewOwnedRow<Id> | undefined>(byId)) {
+    if (row !== undefined && (row.retainedBy?.mainView ?? 0) > 0) return row.id
+  }
+  return undefined
+}

package/src/client/settings-form.ts

@@ -8,7 +8,7 @@
  * card-store pattern.
  */
 
-import type { SettingsScope, SettingsScopeSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 
@@ -114,7 +114,7 @@ interface PlannedWrite {
   judge: (() => boolean) | undefined
 }
 
-/** One durable write inside the save's atomic scope mutation. */
+/** One durable write inside the save's atomic form mutation. */
 export interface BatchedWrite {
   /** Field this entry writes. */
   field: string
@@ -211,34 +211,34 @@ export class CardForm<T> {
   private readonly specs: Map<string, FieldSpec>
   private readonly staged = new Map<string, StagedEdit>()
   private readonly listeners = new Set<() => void>()
-  /** The scope subscription installed in the constructor; released by dispose(). */
-  private readonly disposeScope: () => void
+  /** The form subscription installed in the constructor; released by dispose(). */
+  private readonly disposeForm: () => void
   private disposed = false
   private saving = false
   private failed = false
   private failedReason: string | undefined
 
-  /** @param scope - the bound settings scope for this card's namespace. */
+  /** @param scope - the bound configuration form for this card's namespace. */
   constructor(
-    private readonly scope: SettingsScope<T>,
+    private readonly scope: ConfigForm<T>,
     specs: FieldSpec[],
   ) {
     this.specs = new Map(specs.map(spec => [spec.field, spec]))
-    this.disposeScope = scope.subscribe(() => { this.publish() })
+    this.disposeForm = scope.subscribe(() => { this.publish() })
   }
 
   /**
-   * Release the scope subscription and every bound store listener. The card
+   * Release the form subscription and every bound store listener. The card
    * must call this on teardown; later calls are no-ops.
    */
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
-    this.disposeScope()
+    this.disposeForm()
     this.listeners.clear()
   }
 
-  /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+  /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
   bind<S>(project: () => S): SnapshotStore<S> {
     const store = createSnapshotStore(project())
     this.listeners.add(() => { store.set(project()) })
@@ -295,19 +295,19 @@ export class CardForm<T> {
   }
 
   /**
-   * Write every staged edit in one atomic scope mutation, then re-seed from
+   * Write every staged edit in one atomic form mutation, then re-seed from
    * what the Host accepted.
    *
    * The whole batch rides one mutate, so cross-field validate hooks
    * (baseURL+model) judge it as a unit: the Host either applies every write
-   * or refuses the batch. The 0.1.2 scope contract never rejects a refused
-   * mutation — the scope recovers with a fresh Host view and resolves — so
-   * resolution alone proves nothing: the outcome is judged by reading the
-   * settled snapshot back, one planned write at a time, and one missed write
-   * fails the whole save. A scope that still rejects on refusal (the dsh-web
-   * bridge scope) reports through the same failure path with its rejection
-   * message. A save that did not land keeps its drafts, so the user can
-   * correct them instead of retyping.
+   * or refuses the batch. The form contract answers a refusal or a skipped
+   * write with `false` (it recovers with a fresh Host view instead of
+   * throwing), so the outcome is judged twice: the answer itself, and then the
+   * settled snapshot read back one planned write at a time. One missed write
+   * fails the whole save. A transport that rejects instead (the dsh-web bridge
+   * controller on a dead connection) reports through the same failure path
+   * with its rejection message. A save that did not land keeps its drafts, so
+   * the user can correct them instead of retyping.
    * @returns settlement after the mutation and the read-back.
    */
   async save(): Promise<void> {
@@ -323,30 +323,33 @@ export class CardForm<T> {
     this.failed = false
     this.failedReason = undefined
     this.publish()
-    // One atomic namespace mutation: the 0.1.2 scope contract takes ordered
-    // path operations, so the whole staged batch is validated, persisted, and
+    // One atomic namespace mutation: the form contract takes ordered path
+    // operations, so the whole staged batch is validated, persisted, and
     // recovered together — either every write lands or none does.
     const ops: Array<{ op: 'set'; path: string[]; value: string | number | boolean } | { op: 'unset'; path: string[] }> = valid.map(item => item.op.op === 'set'
       ? { op: 'set', path: [item.field], value: (item.op as { value: string | number | boolean }).value }
       : { op: 'unset', path: [item.field] })
     let failedReason: string | undefined
+    let accepted = false
     try {
-      await this.scope.mutate(ops)
+      accepted = await this.scope.mutate(ops)
     } catch (error) {
       failedReason = error instanceof Error ? error.message : String(error)
     }
-    // The 0.1.2 scope resolves even a refused mutation (it recovers with a
-    // fresh view instead of throwing), so resolution alone proves nothing:
-    // judge every planned write against the settled snapshot. The mutation is
-    // atomic, so one missed write fails the whole save and keeps the drafts.
-    const landed = failedReason === undefined && valid.every(item => item.judge())
+    // `false` is the contract's refusal/skip answer, and the form still
+    // resolves after a refusal (it recovers with a fresh view), so the answer
+    // alone is not enough: judge every planned write against the settled
+    // snapshot as well. The mutation is atomic, so one missed write fails the
+    // whole save and keeps the drafts.
+    const landed = accepted && failedReason === undefined && valid.every(item => item.judge())
     for (const [field, before] of pending) {
       if (landed && this.staged.get(field) === before) this.staged.delete(field)
     }
     this.saving = false
     this.failed = !landed
-    // A read-back failure carries no server reason: the card surfaces its
-    // generic failure copy; a rejecting scope (the bridge) adds its message.
+    // A refused or unlanded batch carries no server reason: the card surfaces
+    // its generic failure copy; a rejecting transport (the bridge) adds its
+    // message.
     this.failedReason = failedReason
     this.publish()
   }
@@ -381,7 +384,7 @@ export class CardForm<T> {
    */
   private landedSet(field: string, value: unknown): boolean {
     // A redacted secret never appears in any wire view layer: the Host strips
-    // role('secret') fields and reports them through a sidecar the scope
+    // role('secret') fields and reports them through a sidecar the form
     // snapshot does not expose, so there is nothing to compare the draft
     // against. Settling is the only signal the form has; the rest of the
     // batch, when one exists, still carries the atomic verdict by read-back.
@@ -412,7 +415,7 @@ export class CardForm<T> {
     return spec
   }
 
-  private snapshotOf(): SettingsScopeSnapshot<T> {
+  private snapshotOf(): ConfigFormSnapshot<T> {
     return this.scope.getSnapshot()
   }
 

package/src/event-projection.ts

@@ -132,9 +132,11 @@ export function projectOfficialEvent(
       }
     }
     case 'tool/result': {
-      const block = event.data.message.content[0]
-      const callId = String(event.data.message.source.callId)
-      const failed = event.data.error !== undefined || block.isError === true
+      // Session format V4 moved the call identity and the outcome onto the
+      // tool-role message root; the content blocks no longer carry either.
+      const { message } = event.data
+      const callId = String(message.toolCallId)
+      const failed = event.data.error !== undefined || message.isError === true
       const wasTest = runtime.testCalls.delete(callId)
       runtime.activeTools.delete(callId)
       runtime.stepHadFailure ||= failed

package/src/gameplay.test.ts

@@ -8,8 +8,12 @@ import { parsePetManifest } from './manifest-v2.ts'
 import {
   applyGameplayEffects,
   clampGameplay,
+  declaredModes,
+  isDeclaredMode,
   drawLotteryTier,
   initialGameplayState,
+  modeRestoreOf,
+  modeStateOf,
   rollTouchBranch,
   rollWorkOutcome,
   settleGameplay,
@@ -28,7 +32,7 @@ function mikuManifest(gameplay: Record<string, unknown>): Record<string, unknown
     frames2d: {
       dir: 'thumb',
       tracks: {
-        idle: {}, drag: {}, standup: {}, sleep: {}, work: {}, success: {}, fail: {},
+        idle: {}, drag: {}, standup: {}, sleep: {}, work: {}, success: {}, fail: {}, bath: {},
         happy: {}, shy: {}, flirty: {}, angry: {}, scratch: {}, blink1: {}, blink2: {}, eat: {}, shop: {},
       },
       phases: { idle: 'idle', done: 'success', failed: 'fail' },
@@ -148,6 +152,94 @@ describe('gameplay manifest', () => {
     expect(parsePetManifest(bare, 'mem').ok).toBe(false)
   })
 
+  it('user declares extra named modes and sees them listed after sleep', () => {
+    // Given a manifest that adds two named modes; when it is parsed; then both
+    // modes survive and the declared list appends them after sleep.
+    const withModes = mikuManifest({
+      ...FULL_GAMEPLAY,
+      modes: {
+        bath: { state: 'bath', label: 'Bath', activeLabel: 'Bathing', restore: { stat: 'mood', amount: 3, intervalMs: 1000 } },
+        play: { state: 'happy' },
+      },
+    })
+    const result = parsePetManifest(withModes, 'mem')
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const gameplay = result.manifest.gameplay!
+    expect(gameplay.modes?.bath).toEqual({
+      state: 'bath', label: 'Bath', activeLabel: 'Bathing',
+      restore: { stat: 'mood', amount: 3, intervalMs: 1000 },
+    })
+    expect(gameplay.modes?.play).toEqual({ state: 'happy' })
+    expect(declaredModes(gameplay)).toEqual(['sleep', 'bath', 'play'])
+  })
+
+  it('user declares a roam block and malformed ones are rejected', () => {
+    // Given a valid roam block; when it is parsed; then it round-trips while
+    // malformed variants fail closed.
+    const roam = { state: 'happy', intervalMs: 12_000, probability: 0.5, distanceMin: 80, distanceMax: 220, speed: 90 }
+    const parsed = parsePetManifest(mikuManifest({ ...FULL_GAMEPLAY, roam }), 'mem')
+    expect(parsed.ok).toBe(true)
+    if (!parsed.ok) return
+    expect(parsed.manifest.gameplay?.roam).toEqual(roam)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, state: 'ghost' } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, distanceMin: 300, distanceMax: 100 } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, probability: 0 } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, speed: 0 } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, sparkle: true } }), 'mem').ok).toBe(false)
+  })
+
+  it('user restricts the roam directions to a declared subset', () => {
+    // Given a roam block; when directions are omitted or restricted; then the
+    // default four apply and a bad list fails closed.
+    const roam = { state: 'happy', intervalMs: 15_000, probability: 0.2, distanceMin: 80, distanceMax: 220, speed: 90 }
+    const plain = parsePetManifest(mikuManifest({ ...FULL_GAMEPLAY, roam }), 'mem')
+    expect(plain.ok).toBe(true)
+    if (!plain.ok) return
+    expect(plain.manifest.gameplay?.roam?.directions).toBeUndefined()
+    const restricted = parsePetManifest(mikuManifest({ ...FULL_GAMEPLAY, roam: { ...roam, directions: ['left', 'right'] } }), 'mem')
+    expect(restricted.ok).toBe(true)
+    if (!restricted.ok) return
+    expect(restricted.manifest.gameplay?.roam?.directions).toEqual(['left', 'right'])
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, directions: [] } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, directions: ['left', 'left'] } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ roam: { ...roam, directions: ['sideways'] } }), 'mem').ok).toBe(false)
+  })
+
+  it('user drops a persisted mode the manifest no longer declares', () => {
+    // Given a manifest with one extra mode; when the persisted ids are checked;
+    // then only declared ids (never prototype keys) count.
+    const parsed = parsePetManifest(mikuManifest({
+      ...FULL_GAMEPLAY,
+      modes: { bath: { state: 'happy' } },
+    }), 'mem')
+    expect(parsed.ok).toBe(true)
+    if (!parsed.ok) return
+    const def = parsed.manifest.gameplay!
+    expect(isDeclaredMode(def, 'work')).toBe(true)
+    expect(isDeclaredMode(def, 'sleep')).toBe(true)
+    expect(isDeclaredMode(def, 'bath')).toBe(true)
+    // A mode that was persisted before the manifest dropped it is not declared.
+    expect(isDeclaredMode(def, 'wash')).toBe(false)
+    expect(isDeclaredMode(def, 'ghost')).toBe(false)
+    // Object.prototype members must never count as declared modes.
+    expect(isDeclaredMode(def, 'constructor')).toBe(false)
+    expect(isDeclaredMode(def, 'toString')).toBe(false)
+    expect(modeStateOf(def, 'constructor')).toBeUndefined()
+    expect(modeRestoreOf(def, 'constructor')).toBeUndefined()
+  })
+
+  it('user cannot declare malformed or reserved extra modes', () => {
+    // Given reserved and malformed mode blocks; when each is parsed; then every
+    // one of them fails closed.
+    expect(parsePetManifest(mikuManifest({ modes: { sleep: { state: 'bath' } } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ modes: { work: { state: 'bath' } } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ modes: { bath: { state: 'ghost' } } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ modes: { bath: { state: 'bath', sparkle: true } } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ modes: { bath: { state: 'bath', restore: { stat: 'ghost', amount: 3, intervalMs: 1000 } } } }), 'mem').ok).toBe(false)
+    expect(parsePetManifest(mikuManifest({ modes: { bath: { state: 'bath', restore: { stat: 'mood', amount: 3, intervalMs: 10 } } } }), 'mem').ok).toBe(false)
+  })
+
   it('rejects bad ranges (tickMs, decay, zone slices, stateMs)', () => {
     const badTick = mikuManifest({ work: { state: 'work', successState: 'success', failState: 'fail', tickMs: 50, successProbability: 0.5 } })
     expect(parsePetManifest(badTick, 'mem').ok).toBe(false)
@@ -185,6 +277,51 @@ describe('gameplay engine', () => {
     expect(state.settledAt).toBe(600_000)
   })
 
+  it('user activates a declared extra mode and its restore ticks', () => {
+    // Given a manifest with a bath mode; when the pet sits in it; then the mode
+    // restore pays mood on its own interval.
+    const parsed = parsePetManifest(mikuManifest({
+      ...FULL_GAMEPLAY,
+      modes: { bath: { state: 'bath', label: 'Bath', restore: { stat: 'mood', amount: 3, intervalMs: 1000 } } },
+    }), 'mem')
+    if (!parsed.ok) throw new Error('fixture must parse')
+    const bathDef = parsed.manifest.gameplay!
+    expect(modeStateOf(bathDef, 'bath')).toBe('bath')
+    expect(modeRestoreOf(bathDef, 'bath')).toEqual({ stat: 'mood', amount: 3, intervalMs: 1000 })
+    expect(modeRestoreOf(bathDef, 'work')).toBeUndefined()
+    expect(modeRestoreOf(bathDef, null)).toBeUndefined()
+
+    const state = initialGameplayState(bathDef, 0)
+    state.stats.mood = 10
+    state.mode = 'bath'
+    // 5 s of bath: 5 x 3 mood, minus 5 s of the 0.5/min baseline decay
+    settleGameplay(state, bathDef, 5000, { sessionActive: true })
+    expect(state.stats.mood).toBeCloseTo(10 - (5 / 60) * 0.5 + 15, 4)
+  })
+
+  it('user keeps a 1 s mode cadence across a fast polling interval', () => {
+    // Given a fast 200 ms poll loop; when ten seconds elapse; then the mode
+    // still pays exactly ten ticks with no drift.
+    const parsed = parsePetManifest(mikuManifest({
+      ...FULL_GAMEPLAY,
+      modes: { bath: { state: 'bath', restore: { stat: 'mood', amount: 3, intervalMs: 1000 } } },
+    }), 'mem')
+    if (!parsed.ok) throw new Error('fixture must parse')
+    const bathDef = parsed.manifest.gameplay!
+    // Start above zero: a stat parked at 0 is exempt from decay, which would
+    // otherwise hide part of the decay side of the balance.
+    const state = initialGameplayState(bathDef, 0)
+    state.stats.mood = 50
+    state.mode = 'bath'
+    let now = 0
+    for (let i = 0; i < 50; i++) {
+      now += 200
+      settleGameplay(state, bathDef, now, { sessionActive: true })
+    }
+    // 10 s of 200 ms polls still pays exactly 10 x 3 mood (carry, no drift)
+    expect(state.stats.mood).toBeCloseTo(50 + 30 - (10 / 60) * 0.5, 4)
+  })
+
   it('preserves remainder carry across frequent polling intervals for passive income and sleep restore (#1478)', () => {
     const state = initialGameplayState(def, 0)
     state.stats.energy = 20