@linxin666/dsh-pet 0.3.6 → 0.3.9

package/src/client/PetSprite.tsx

@@ -16,6 +16,7 @@ import clsx from 'clsx'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetStateView } from '../service.ts'
+import { announcementFresh, type PetAnnouncement } from '../announce.ts'
 import type { PetDefinition } from '../registry.ts'
 import type { DecorationView } from '../contracts/status-decoration.ts'
 import type { PetFeedback } from './pet-store.ts'
@@ -78,6 +79,14 @@ export interface PetSpriteProps {
   onGameplayMenu?: () => void
   /** Disable the drag gesture (gameplay work mode blocks dragging). */
   dragDisabled?: boolean
+  /**
+   * DOM node the floating chrome portals into. Defaults to document.body
+   * (the legacy behavior); the plugin apply passes its owning root (the
+   * [data-dsh-plugin="pet"] container) so the root owns the whole surface
+   * and a root-keyed suppressor (the portrait mobile layer) hides the pet
+   * as one unit instead of missing the portaled sprite.
+   */
+  portalTarget?: Element
   /** Locale translate seat (namespace-bound). */
   t: TranslateNS<typeof NS>
 }
@@ -176,6 +185,52 @@ function StatusOrnament(props: { decoration: DecorationView; phase: ActivityPhas
   )
 }
 
+/**
+ * The announcement bubble (dsh-usage linkage): a dedicated, specially
+ * designed surface for sibling-plugin facts — a balance or today-spend pill,
+ * or a plan-quota card with a tone-tinted accent, a mini meter for percent
+ * windows, and the reset instant. It rides the top of the session bubble
+ * stack (column-reverse puts the DOM-last child farthest from the sprite)
+ * and persists for its TTL instead of the short feedback pop.
+ */
+function UsageAnnouncementBubble(props: { announcement: PetAnnouncement }): ReactNode {
+  const { announcement } = props
+  const tone = announcement.tone === 'low'
+    ? styles.bubbleUsageLow
+    : announcement.tone === 'warn'
+      ? styles.bubbleUsageWarn
+      : styles.bubbleUsageOk
+  return (
+    <div
+      className={clsx(styles.bubble, styles.bubbleUsage, tone)}
+      role="status"
+      aria-live="polite"
+      data-dsh-pet-announcement={announcement.source}
+    >
+      <span className={styles.bubbleUsageHead}>
+        <span className={styles.bubbleUsageTitle}>{announcement.title}</span>
+        {(announcement.kind === 'balance' || announcement.kind === 'cost') && announcement.amount !== undefined && (
+          <span className={styles.bubbleUsageValue}>{announcement.amount}</span>
+        )}
+        {announcement.kind === 'plan' && announcement.percent !== undefined && (
+          <span className={styles.bubbleUsageValue}>{Math.round(announcement.percent) + '%'}</span>
+        )}
+      </span>
+      {announcement.kind === 'plan' && announcement.percent !== undefined && (
+        <span className={styles.bubbleUsageMeter}>
+          <span
+            className={styles.bubbleUsageMeterFill}
+            style={{ width: Math.min(100, Math.max(0, announcement.percent)) + '%' }}
+          />
+        </span>
+      )}
+      {announcement.note !== undefined && (
+        <span className={styles.bubbleUsageNote}>{announcement.note}</span>
+      )}
+    </div>
+  )
+}
+
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
  * with per-frame durations from the definition's tracks; the atlas image is
@@ -432,6 +487,13 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const statusBubble = feedback === null && sessionBubbles.length === 0
     ? snapshot?.bubble
     : undefined
+  // The freshest plugin-authored announcement (dsh-usage linkage): a
+  // dedicated, specially styled bubble above the session stack. The host
+  // already TTL-filters; this client-side check covers the last poll tick.
+  const announcement = snapshot?.announcement
+  const usageAnnouncement = feedback === null && announcement !== undefined && announcementFresh(announcement, Date.now())
+    ? announcement
+    : undefined
   // Each session's inner whisper (碎碎念) rides its own bubble — short
   // inner-voice copy woken by that session's activity, never the model's or
   // another session's. Instead of a second bubble of its own, a fresh
@@ -439,7 +501,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   // never wears two voices at once. Interaction feedback takes over the
   // whole bubble area while it plays, so whispers yield to it like status
   // copy.
-  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined
+  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined
   const displayName = snapshot?.name ?? definition.displayName
   // The host-served status decoration (M5, #567); absent = text-only bubbles.
   const decoration = snapshot?.decoration
@@ -549,7 +611,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           {feedback.text}
         </div>
       )}
-      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined) && (
+      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined) && (
         <div
           ref={bubbleRef}
           className={styles.bubbleStack}
@@ -620,6 +682,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               {statusBubble}
             </div>
           )}
+          {usageAnnouncement !== undefined && <UsageAnnouncementBubble announcement={usageAnnouncement} />}
         </div>
       )}
       {hovered && dragRef.current === null && (
@@ -738,5 +801,5 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
     </div>
   )
 
-  return createPortal(float, document.body)
+  return createPortal(float, props.portalTarget ?? document.body)
 }

package/src/client/gameplay-hud.test.tsx

@@ -9,7 +9,7 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
 // __ModuleLoader__ (not importable under vitest); provide the defineStore
 // the pet store needs (same fake-store pattern as PetDockEntry.test.tsx).
-vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
+vi.mock('@deepseek-ai/dsh-client-store', () => ({
   defineStore: (spec: {
     init: () => unknown
     actions: Record<string, (draft: never, ...args: never[]) => void>

package/src/client/index.test.tsx

@@ -12,7 +12,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
 // __ModuleLoader__ (not importable under vitest); provide defineStore /
 // createSnapshotStore (same fake-store pattern as the settings-card tests).
-vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
+vi.mock('@deepseek-ai/dsh-client-store', () => ({
   defineStore: (spec: {
     init: () => unknown
     actions: Record<string, (draft: never, ...args: never[]) => void>
@@ -48,7 +48,7 @@ vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
     }
   },
 }))
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import { apply } from './index.ts'
 
 beforeAll(() => {

package/src/client/index.ts

@@ -4,19 +4,26 @@
  * endpoints: fetch the registry list once, poll the host snapshot (~2 s),
  * forward interactions, persist drag positions. The pet is host-global (no
  * session dimension), so it mounts directly onto 'document.body' via a
- * single React root rather than a session-scoped slot — on the
- * new-conversation screen no session exists, and a dock-mounted pet would
- * vanish there (issue #48). When the pet is hidden the entry becomes a
- * fixed-position summon button.
+ * single React root — the [data-dsh-plugin="pet"] container — rather than a
+ * session-scoped slot: on the new-conversation screen no session exists, and
+ * a dock-mounted pet would vanish there (issue #48). The sprite chrome
+ * portals into that same root, so the root owns the whole surface and a
+ * root-keyed suppressor can hide it as one unit. When the pet is hidden the
+ * entry becomes a fixed-position summon button.
  * @module @linxin666/dsh-pet/client
  */
 
-import type { ClientContext, ISessions, SessionId, SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client'
+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'
 // 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'
+// 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'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetGameplayVerbResult, PetInteractResult, PetStateView } from '../service.ts'
@@ -381,7 +388,11 @@ export function apply(ctx: ClientContext): void {
       container.dataset.dshPlugin = 'pet'
       document.body.appendChild(container)
       const petRoot = createRoot(container)
-      petRoot.render(createElement(PetDockEntry, { ...injected(), t }))
+      // The sprite chrome portals into THIS root (not document.body): the
+      // root then owns the whole surface, so a root-keyed suppressor (the
+      // portrait mobile layer, which hides [data-dsh-plugin="pet"]) really
+      // hides the sprite instead of missing the portaled float.
+      petRoot.render(createElement(PetDockEntry, { ...injected(), t, portalTarget: container }))
 
       let uiGone = false
       disposeUi = () => {

package/src/client/locales.ts

@@ -76,7 +76,7 @@ export const zh = {
   'settings.off': '关',
   'settings.overridden': '已覆盖',
   'settings.reset': '恢复默认',
-  'settings.notExposed': '当前 DSH 版本未向设置页暴露本插件的配置命名空间，表单不可用。可编辑 ~/.dsh/settings.yaml 直接配置，或为 dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES 白名单补充本命名空间后重启。',
+  'settings.notExposed': '当前 DSH 版本未向设置页暴露本插件的配置命名空间，表单不可用。可编辑 $DSH_HOME/settings.yaml 直接配置，或确认提供该命名空间的插件已挂载其设置域并重启。',
   'settings.readOnly': '当前部署的设置只读。',
   'settings.expand': '展开设置',
   'settings.collapse': '收起设置',
@@ -158,7 +158,7 @@ export const en = {
   'settings.off': 'Off',
   'settings.overridden': 'Overridden',
   'settings.reset': 'Reset to default',
-  'settings.notExposed': 'This DSH version does not expose this plugin\'s settings namespace to the configuration page, so the form is unavailable. Edit ~/.dsh/settings.yaml directly, or add the namespace to dsh-host-apiproxy\'s WEB_SETTINGS_NAMESPACES allowlist and restart.',
+  'settings.notExposed': 'This DSH version does not expose this plugin\'s settings namespace to the configuration page, so the form is unavailable. Edit $DSH_HOME/settings.yaml directly, or confirm that the plugin owning the namespace is mounted with its settings domain and restart.',
   'settings.readOnly': 'This deployment stores settings read-only.',
   'settings.expand': 'Show settings',
   'settings.collapse': 'Hide settings',

package/src/client/pet-store.ts

@@ -6,8 +6,8 @@
  * @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 { defineStore } from '@deepseek-ai/dsh-client-store'
+import type { EngineStoreHandle, EngineStoreInstance } from '@deepseek-ai/dsh-client-store'
 import type { PetGameplayStateView, PetStateView } from '../service.ts'
 import type { PetInteraction } from '../affinity.ts'
 import type { PetDefinition } from '../registry.ts'

package/src/client/pet.module.css

@@ -604,3 +604,107 @@
   }
 }
 
+
+/* 公告气泡（dsh-usage 联动）：兄弟插件推送的结构化事实（余额 / 套餐用量）。
+   与状态气泡同一片蓝黑玻璃家族，但自有版式：标题 + 数值两端对齐，
+   套餐窗口带微型计量条，色调按 ok/warn/low 染描边与计量条。
+   自带长驻动画（进场后保持），不走 2.6s 反馈气泡的淡出轨道。 */
+.bubbleUsage {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 3px;
+  min-width: 128px;
+  max-width: min(280px, calc(100vw - 24px));
+  padding: 6px 12px;
+  white-space: nowrap;
+  background: linear-gradient(160deg, rgba(19, 28, 54, 0.92), rgba(7, 11, 26, 0.95));
+  border: 1px solid rgba(126, 152, 255, 0.45);
+  box-shadow:
+    0 4px 12px rgba(2, 6, 23, 0.35),
+    inset 0 1px 0 rgba(226, 232, 255, 0.1),
+    0 0 12px rgba(77, 107, 254, 0.18);
+  backdrop-filter: blur(8px);
+  letter-spacing: 0.02em;
+  animation: pet-usage-in 280ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.bubbleUsageHead {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.bubbleUsageTitle {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  opacity: 0.85;
+}
+
+.bubbleUsageValue {
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  flex-shrink: 0;
+}
+
+.bubbleUsageNote {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 10px;
+  opacity: 0.55;
+}
+
+.bubbleUsageMeter {
+  display: block;
+  height: 4px;
+  border-radius: 999px;
+  background: rgba(226, 232, 255, 0.14);
+  overflow: hidden;
+}
+
+.bubbleUsageMeterFill {
+  display: block;
+  height: 100%;
+  border-radius: 999px;
+  background: #6ee7b7;
+  transition: width 300ms ease;
+}
+
+/* 色调：ok 沿用品牌蓝描边；warn 琥珀、low 珊瑚红，染描边与计量条。 */
+.bubbleUsageOk {
+  border-color: rgba(126, 152, 255, 0.45);
+}
+
+.bubbleUsageWarn {
+  border-color: rgba(251, 191, 36, 0.55);
+}
+
+.bubbleUsageWarn .bubbleUsageMeterFill {
+  background: #fbbf24;
+}
+
+.bubbleUsageLow {
+  border-color: rgba(248, 113, 113, 0.6);
+}
+
+.bubbleUsageLow .bubbleUsageMeterFill {
+  background: #f87171;
+}
+
+@keyframes pet-usage-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bubbleUsage {
+    animation: none;
+  }
+}

package/src/client/settings-form.ts

@@ -8,8 +8,9 @@
  * card-store pattern.
  */
 
-import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsScope, SettingsScopeSnapshot } 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'
 
 /** The write one field's staged text performs when the card is saved. */
 export type FieldWrite =
@@ -23,9 +24,11 @@ export interface FieldSpec {
   /**
    * Whether the Host treats this field as a secret and redacts its value from
    * the read-back (role('secret') in the section schema). Redacted secrets are
-   * never compared against the draft on save; the field lands when the scope
-   * reports the write succeeded (its secret-set marker under the bridge), so
-   * a successful secret save is not misreported as failed.
+   * never compared against the draft on save: the Host strips them from every
+   * wire view layer, so the settled snapshot carries nothing to read back. A
+   * staged secret set is judged by the mutation settling; the rest of its
+   * batch, when one exists, is still judged by read-back, and the atomic
+   * mutation lands every write or none.
    */
   secret?: boolean
   /** Render a stored value as draft text; the empty string when the section carries none. */
@@ -53,8 +56,8 @@ export interface CardShell {
   available: boolean
   /**
    * Whether the namespace is actually served to this client. False when the
-   * Host deployment does not expose it (e.g. the official apiproxy settings
-   * allowlist omits third-party namespaces): the card renders an explanation
+   * Host deployment does not expose it (e.g. the owning plugin's settings
+   * domain is not mounted): the card renders an explanation
    * instead of its form, so a missing namespace never looks like a missing
    * plugin.
    */
@@ -101,13 +104,17 @@ interface StagedEdit {
 interface PlannedWrite {
   /** Field this entry writes. */
   field: string
-  /** The durable write this entry performs, described for a batched scope. */
+  /** The durable write this entry performs, inside the save's one atomic mutation. */
   op: BatchedWrite
-  /** Perform the write and report whether the Host holds the staged value afterwards. */
-  run: (() => Promise<boolean>) | undefined
+  /**
+   * Read the settled snapshot back and report whether the Host holds this
+   * write's effect. Undefined when the draft is not a value the field
+   * accepts: there is nothing to write, and the entry blocks the save.
+   */
+  judge: (() => boolean) | undefined
 }
 
-/** One durable write a batched settings scope performs. */
+/** One durable write inside the save's atomic scope mutation. */
 export interface BatchedWrite {
   /** Field this entry writes. */
   field: string
@@ -117,36 +124,6 @@ export interface BatchedWrite {
   value?: unknown
 }
 
-/** Per-field outcome of one batched scope write. */
-export interface BatchedFieldResult {
-  /** Field this entry writes. */
-  field: string
-  /** Whether the Host accepted this field's write (per the read-back view). */
-  landed: boolean
-}
-
-/**
- * Result of a batched scope write. The bridge scope posts every planned write
- * in one /mutate so the Host validate hook judges baseURL+model together; a
- * batched refusal fails the whole save rather than per-field.
- */
-export interface BatchResult {
-  /** Whether the whole mutate was accepted. */
-  ok: boolean
-  /** Per-field success, in the request order (always present when ok). */
-  fields: BatchedFieldResult[]
-  /** Host rejection code (mutate refused). */
-  code?: string
-  /** Host rejection message (mutate refused). */
-  message?: string
-}
-
-/** The optional batch surface the bridge scope adds over the SettingsScope contract. */
-interface BatchedSettingsScope {
-  /** Write every operation in one scope mutation, reporting per-field success. */
-  mutate: (writes: BatchedWrite[]) => Promise<BatchResult>
-}
-
 /** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
 export interface NumberConstraints {
   /** The accepted value must be a whole number. */
@@ -188,8 +165,8 @@ export function textField(field: string): FieldSpec {
 /**
  * A free-text field the Host treats as a secret and redacts from the read-back
  * (role('secret') in the section schema). The card still edits it like text,
- * but a save never compares the redacted value back and relies on the scope
- * reporting the write landed.
+ * but a save never compares the redacted value back: the staged set is judged
+ * by the mutation settling (see {@link FieldSpec.secret}).
  */
 export function secretField(field: string): FieldSpec {
   return { ...textField(field), secret: true }
@@ -277,7 +254,7 @@ export class CardForm<T> {
       exposed: snapshot.status === 'ready',
       writable: snapshot.writable,
       dirty: plan.length > 0,
-      invalid: plan.some(item => item.run === undefined),
+      invalid: plan.some(item => item.judge === undefined),
       saving: this.saving,
       failed: this.failed,
       ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
@@ -318,21 +295,25 @@ export class CardForm<T> {
   }
 
   /**
-   * Write every staged edit, then re-seed from what the Host accepted.
+   * Write every staged edit in one atomic scope mutation, then re-seed from
+   * what the Host accepted.
    *
-   * When the scope carries the optional batch surface (the dsh-web
-   * bridge scope), every planned write rides one mutation so cross-field
-   * validate hooks (baseURL+model) judge the batch as a unit instead of
-   * deadlocking on per-field writes. Otherwise the per-field loop runs.
-   * A field lands only when the Host reports it held the staged value; a
-   * landed field's draft is dropped, a failed one stays staged for the user.
-   * @returns settlement after every write and the read-back.
+   * 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.
+   * @returns settlement after the mutation and the read-back.
    */
   async save(): Promise<void> {
     const plan = this.plan()
-    const valid = plan.filter(item => item.run !== undefined)
+    const valid = plan.filter((item): item is PlannedWrite & { judge: () => boolean } => item.judge !== undefined)
     if (plan.length === 0 || this.saving || valid.length !== plan.length) return
-    const plannedWrites = valid.map(item => item.op)
     // Snapshot the staged entries this save writes, so an edit staged while it
     // is in flight (which replaces the same key) survives: only delete the key
     // when the entry is still the one this save started from.
@@ -342,36 +323,34 @@ export class CardForm<T> {
     this.failed = false
     this.failedReason = undefined
     this.publish()
-    const landed = new Set<string>()
-    const batch = this.batchedScope()
-    if (batch !== undefined) {
-      const result = await batch.mutate(plannedWrites)
-      if (result.ok) {
-        for (const field of result.fields) {
-          if (field.landed) landed.add(field.field)
-        }
-      } else {
-        this.failedReason = result.message
-      }
-    } else {
-      for (const item of valid) {
-        if (await item.run!()) landed.add(item.field)
-      }
+    // One atomic namespace mutation: the 0.1.2 scope 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
+    try {
+      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())
     for (const [field, before] of pending) {
-      if (landed.has(field) && this.staged.get(field) === before) this.staged.delete(field)
+      if (landed && this.staged.get(field) === before) this.staged.delete(field)
     }
     this.saving = false
-    this.failed = landed.size !== pending.size
+    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.
+    this.failedReason = failedReason
     this.publish()
   }
 
-  /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
-  private batchedScope(): BatchedSettingsScope | undefined {
-    const candidate = this.scope as unknown as BatchedSettingsScope | undefined
-    return typeof candidate?.mutate === 'function' ? candidate : undefined
-  }
-
   /**
    * Every staged edit a save would write. An entry whose draft is not a value
    * its field accepts carries no write: the form is still dirty, and the save
@@ -384,33 +363,40 @@ export class CardForm<T> {
     for (const [field, staged] of this.staged) {
       const spec = this.specOf(field)
       if (staged.clear) {
-        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
+        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
         continue
       }
       if (staged.text === spec.format(this.sectionValue(field))) continue
       const write = spec.parse(staged.text)
-      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, run: undefined })
-      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
-      else plan.push({ field, op: { field, op: 'set', value: write.value }, run: () => this.store(field, write.value) })
+      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, judge: undefined })
+      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
+      else plan.push({ field, op: { field, op: 'set', value: write.value }, judge: () => this.landedSet(field, write.value) })
     }
     return plan
   }
 
-  private async clear(field: string): Promise<boolean> {
-    await this.scope.unset(field)
-    return !this.stored(field)
-  }
-
-  private async store(field: string, value: unknown): Promise<boolean> {
-    await this.scope.set(field, value)
-    // A redacted secret never appears in the user layer read-back; judging it
-    // by value would misreport a successful secret save as failed. The bridge
-    // reports secret writes through its secret-set markers (batch path); on
-    // the per-field path the scope resolved, so the write is landed.
+  /**
+   * Read-back judgment for a planned set: the user layer must hold the
+   * intended value once the mutation has settled.
+   */
+  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
+    // 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.
     if (this.specOf(field).secret) return true
     return this.userLayer()?.[field] === value
   }
 
+  /**
+   * Read-back judgment for a planned unset: the field must be gone from the
+   * user layer once the mutation has settled.
+   */
+  private landedUnset(field: string): boolean {
+    return !this.stored(field)
+  }
+
   private stage(field: string, edit: StagedEdit): void {
     this.staged.set(field, edit)
     this.failed = false

package/src/dsh-home.ts

@@ -39,4 +39,4 @@ export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: strin
 /** Resolve the DSH home directory from the live environment. */
 export function dshHome(): string {
   return resolveDshHome()
-}
+}

package/src/index.ts

@@ -12,7 +12,7 @@
  */
 
 import { Context } from '@deepseek-ai/cordis'
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import z from 'schemastery'
 import { PetService, PET_SETTINGS_NAMESPACE, type PetConfig, type PetSettingsSection } from './service.ts'
@@ -189,20 +189,22 @@ function applyImpl(ctx: Context, config: PetConfig = {}): void {
       disposeRoutes = undefined
     }
   }
-  installSettingsSection(
-    ctx,
-    settingsNamespace(PET_SETTINGS_NAMESPACE),
-    makePetSettingsSchema(service.selectedPetId()),
-    base,
-    {
-      setSource: (source) => { current = source },
-      onChange: () => {
-        const section = current()
-        service.applySettingsSection(section)
-        service.setEnabled(section.enabled ?? true)
-        syncRoutes()
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(
+      ctx,
+      PET_SETTINGS_NAMESPACE as SettingsNamespace,
+      makePetSettingsSchema(service.selectedPetId()),
+      base,
+      {
+        setSource: (source) => { current = source },
+        onChange: () => {
+          const section = current()
+          service.applySettingsSection(section)
+          service.setEnabled(section.enabled ?? true)
+          syncRoutes()
+        },
       },
-    },
-  )
+    )
+  })
   syncRoutes()
 }