@linxin666/dsh-pet 0.1.15 → 0.1.16

package/lib/types/client/index.d.ts

@@ -1,11 +1,12 @@
 /**
- * dsh-pet browser half — mounts the whale-girl as a global floating surface
- * and drives it from the host's same-origin `/api/pet/*` JSON endpoints: 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
+ * dsh-pet browser half — mounts the selected pet as a global floating
+ * surface and drives it from the host's same-origin '/api/pet/*' JSON
+ * 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.
  * @module @linxin666/dsh-pet/client
  */
@@ -14,13 +15,15 @@ import type { ClientContext, SettingsScope, SettingsScopeSpec } from '@deepseek-
 export declare const inject: string[];
 /** Re-exported for consumers that type against the injected face. */
 export type { PetInjected, PetDockEntryProps } from './PetDockEntry.tsx';
+export type { PetSpriteProps } from './PetSprite.tsx';
 export type { PetUiState, PetFeedback } from './pet-store.ts';
 export type { PetSettingsCardFace, PetSettingsCardState } from './PetSettingsCard.tsx';
+export type { PetDefinition } from '../registry.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface SlotMap {
         /**
          * The child slot the Web UI plugin group declares; this card registers
-         * into the group instead of the top-level `settings.plugin.item` list.
+         * into the group instead of the top-level 'settings.plugin.item' list.
          * Spelled here with the same shape so this package can register without
          * depending on the sibling UI package.
          */

package/lib/types/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAwD7G,yBAAyB;AACzB,eAAO,MAAM,MAAM,UAA+D,CAAA;AAElF,qEAAqE;AACrE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACxE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAEtF,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,OAAO;QACf;;;;;WAKG;QACH,oBAAoB,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,4BAA4B,CAAA;SAAE,CAAA;KAC3F;CACF;AAED,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf;;;;WAIG;QACH,aAAa,CAAC,EAAE;YAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;SAAE,CAAA;KAC1E;CACF;AAGD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAoK9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AA6D7G,yBAAyB;AACzB,eAAO,MAAM,MAAM,UAA+D,CAAA;AAElF,qEAAqE;AACrE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACxE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,OAAO;QACf;;;;;WAKG;QACH,oBAAoB,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,4BAA4B,CAAA;SAAE,CAAA;KAC3F;CACF;AAED,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf;;;;WAIG;QACH,aAAa,CAAC,EAAE;YAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;SAAE,CAAA;KAC1E;CACF;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAmL9C"}

package/lib/types/client/index.js

@@ -1,11 +1,12 @@
 /**
- * dsh-pet browser half — mounts the whale-girl as a global floating surface
- * and drives it from the host's same-origin `/api/pet/*` JSON endpoints: 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
+ * dsh-pet browser half — mounts the selected pet as a global floating
+ * surface and drives it from the host's same-origin '/api/pet/*' JSON
+ * 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.
  * @module @linxin666/dsh-pet/client
  */
@@ -25,17 +26,19 @@ async function petFetch(path, body) {
             body: JSON.stringify(body),
         });
     if (!response.ok) {
-        throw new Error(`pet ${path} failed: ${response.status}`);
+        throw new Error('pet ' + path + ' failed: ' + response.status);
     }
     return (await response.json());
 }
 /** The live host API instance (always defined; failures surface per call). */
 const petApi = {
     state: () => petFetch('/api/pet/state'),
+    pets: () => petFetch('/api/pet/pets'),
     interact: (kind) => petFetch('/api/pet/interact', { kind }),
     setVisible: (visible) => petFetch('/api/pet/set-visible', { visible }),
     setConfig: (patch) => petFetch('/api/pet/set-config', patch),
     setName: (name) => petFetch('/api/pet/set-name', { name }),
+    setPet: (petId) => petFetch('/api/pet/set-pet', { petId }),
 };
 /** Poll interval for the host snapshot. */
 const POLL_MS = 2000;
@@ -59,8 +62,9 @@ export function apply(ctx) {
             ? snapshot.value?.enabled ?? true
             : snapshot.status === 'unavailable';
     };
-    // Plugin configuration card: one staged form over the `pet` settings
-    // namespace, contributed to the Web UI plugin group.
+    // Plugin configuration card: one staged form over the 'pet' settings
+    // namespace, contributed to the Web UI plugin group. The controller loads
+    // the petId choices from the registry endpoint itself.
     const petSettings = new PetSettingsCardController(settingsScope);
     ctx.slots.inject('web-ui.plugin.item', () => ctx.slots.register({
         name: 'web-ui.plugin.item',
@@ -81,9 +85,23 @@ export function apply(ctx) {
             // it stateless on the new-conversation screen (no session to scope by).
             const petStore = createPetStore().create();
             const setSnapshot = petStore.actions.setSnapshot;
+            const setPets = petStore.actions.setPets;
             const setState = petStore.actions.setState;
             const setFeedback = petStore.actions.setFeedback;
+            // The registry list is fetched lazily with retries baked into the poll
+            // cycle: until it lands, the dock entry renders nothing and every 2s
+            // tick tries again. After it lands, one list feeds both the sprite and
+            // the settings card's choices.
+            let petsLoaded = false;
             const pollNow = () => {
+                if (!petsLoaded) {
+                    petApi.pets().then((list) => {
+                        petsLoaded = true;
+                        setPets(list);
+                    }, () => {
+                        // Retry on the next poll tick.
+                    });
+                }
                 petApi.state().then((snapshot) => {
                     setSnapshot(snapshot);
                 }, () => {
@@ -187,8 +205,8 @@ export function apply(ctx) {
             // for a global floating surface — the dock is session-scoped, so a pet
             // mounted there would vanish on the new-conversation screen (issue #48).
             // The entry therefore mounts straight onto document.body via a single
-            // React root for the page lifetime: WhalePet portals itself to body when
-            // visible, and the hidden-state summon button is fixed-positioned.
+            // React root for the page lifetime: PetSprite portals itself to body
+            // when visible, and the hidden-state summon button is fixed-positioned.
             const container = document.createElement('div');
             container.dataset.dshPetRoot = '';
             document.body.appendChild(container);

package/lib/types/client/locales.d.ts

@@ -15,10 +15,12 @@ export declare const zh: {
     readonly 'pet.rank': "亲密度 {rank}";
     readonly 'pet.points': "{points} 点";
     readonly 'pet.treats': "小鱼干 ×{n}";
-    readonly 'pet.state.loading': "鲸鱼娘正在赶来…";
-    readonly 'pet.state.error': "鲸鱼娘迷路了（连接失败）";
+    readonly 'pet.state.loading': "宠物正在赶来…";
+    readonly 'pet.state.error': "宠物迷路了（连接失败）";
     readonly 'settings.title': "宠物";
-    readonly 'settings.description': "鲸鱼娘的显示布局与名字。";
+    readonly 'settings.description': "选择宠物并调整它的显示布局。";
+    readonly 'settings.pet': "宠物";
+    readonly 'settings.petHint': "选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。";
     readonly 'settings.enabled': "启用宠物";
     readonly 'settings.enabledHint': "关闭后隐藏宠物并停止轮询，可在设置里重新启用。";
     readonly 'settings.visible': "显示宠物";
@@ -29,8 +31,6 @@ export declare const zh: {
     readonly 'settings.rightHint': "距视口右边缘的水平内缩距离。";
     readonly 'settings.bottom': "距底部（px）";
     readonly 'settings.bottomHint': "距视口底边的垂直内缩距离。";
-    readonly 'settings.name': "名字";
-    readonly 'settings.nameHint': "宠物显示名，1–20 个字符。";
     readonly 'settings.inherit': "继承";
     readonly 'settings.on': "开";
     readonly 'settings.off': "关";
@@ -58,10 +58,12 @@ export declare const en: {
     readonly 'pet.rank': "Affinity {rank}";
     readonly 'pet.points': "{points} pts";
     readonly 'pet.treats': "Treats ×{n}";
-    readonly 'pet.state.loading': "The whale girl is on her way…";
-    readonly 'pet.state.error': "The whale girl is lost (connection failed)";
+    readonly 'pet.state.loading': "The pet is on its way…";
+    readonly 'pet.state.error': "The pet is lost (connection failed)";
     readonly 'settings.title': "Pet";
-    readonly 'settings.description': "The whale girl’s display layout and name.";
+    readonly 'settings.description': "Pick a pet and tune its display layout.";
+    readonly 'settings.pet': "Pet";
+    readonly 'settings.petHint': "Choose which pet shows. Names are stored per pet; rename from the pet hover panel.";
     readonly 'settings.enabled': "Enable the pet";
     readonly 'settings.enabledHint': "When off, the pet hides and polling stops; re-enable it here.";
     readonly 'settings.visible': "Show the pet";
@@ -72,8 +74,6 @@ export declare const en: {
     readonly 'settings.rightHint': "Horizontal inset from the viewport right edge.";
     readonly 'settings.bottom': "Bottom inset (px)";
     readonly 'settings.bottomHint': "Vertical inset from the viewport bottom edge.";
-    readonly 'settings.name': "Name";
-    readonly 'settings.nameHint': "The pet’s display name, 1–20 characters.";
     readonly 'settings.inherit': "Inherit";
     readonly 'settings.on': "On";
     readonly 'settings.off': "Off";

package/lib/types/client/locales.js

@@ -15,11 +15,13 @@ export const zh = {
     'pet.rank': '亲密度 {rank}',
     'pet.points': '{points} 点',
     'pet.treats': '小鱼干 ×{n}',
-    'pet.state.loading': '鲸鱼娘正在赶来…',
-    'pet.state.error': '鲸鱼娘迷路了（连接失败）',
+    'pet.state.loading': '宠物正在赶来…',
+    'pet.state.error': '宠物迷路了（连接失败）',
     // 插件设置卡片（settings.plugin.item 席位）。
     'settings.title': '宠物',
-    'settings.description': '鲸鱼娘的显示布局与名字。',
+    'settings.description': '选择宠物并调整它的显示布局。',
+    'settings.pet': '宠物',
+    'settings.petHint': '选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。',
     'settings.enabled': '启用宠物',
     'settings.enabledHint': '关闭后隐藏宠物并停止轮询，可在设置里重新启用。',
     'settings.visible': '显示宠物',
@@ -30,8 +32,6 @@ export const zh = {
     'settings.rightHint': '距视口右边缘的水平内缩距离。',
     'settings.bottom': '距底部（px）',
     'settings.bottomHint': '距视口底边的垂直内缩距离。',
-    'settings.name': '名字',
-    'settings.nameHint': '宠物显示名，1–20 个字符。',
     'settings.inherit': '继承',
     'settings.on': '开',
     'settings.off': '关',
@@ -59,11 +59,13 @@ export const en = {
     'pet.rank': 'Affinity {rank}',
     'pet.points': '{points} pts',
     'pet.treats': 'Treats ×{n}',
-    'pet.state.loading': 'The whale girl is on her way…',
-    'pet.state.error': 'The whale girl is lost (connection failed)',
+    'pet.state.loading': 'The pet is on its way…',
+    'pet.state.error': 'The pet is lost (connection failed)',
     // Plugin settings card (the `settings.plugin.item` seat).
     'settings.title': 'Pet',
-    'settings.description': 'The whale girl\u2019s display layout and name.',
+    'settings.description': 'Pick a pet and tune its display layout.',
+    'settings.pet': 'Pet',
+    'settings.petHint': 'Choose which pet shows. Names are stored per pet; rename from the pet hover panel.',
     'settings.enabled': 'Enable the pet',
     'settings.enabledHint': 'When off, the pet hides and polling stops; re-enable it here.',
     'settings.visible': 'Show the pet',
@@ -74,8 +76,6 @@ export const en = {
     'settings.rightHint': 'Horizontal inset from the viewport right edge.',
     'settings.bottom': 'Bottom inset (px)',
     'settings.bottomHint': 'Vertical inset from the viewport bottom edge.',
-    'settings.name': 'Name',
-    'settings.nameHint': 'The pet\u2019s display name, 1\u201320 characters.',
     'settings.inherit': 'Inherit',
     'settings.on': 'On',
     'settings.off': 'Off',

package/lib/types/client/pet-store.d.ts

@@ -8,6 +8,7 @@
 import type { EngineStoreHandle, EngineStoreInstance } from '@deepseek-ai/dsh-client-runtime/client';
 import type { PetStateView } from '../service.ts';
 import type { PetInteraction } from '../affinity.ts';
+import type { PetDefinition } from '../registry.ts';
 /** One transient reaction bubble on the pet. */
 export interface PetFeedback {
     /** Bubble copy. */
@@ -21,6 +22,8 @@ export interface PetFeedback {
 export interface PetUiState {
     /** Latest host snapshot; null before the first successful fetch. */
     snapshot: PetStateView | null;
+    /** The registry list the host serves (atlas URLs + geometry + tracks). */
+    pets: PetDefinition[];
     /** Fetch lifecycle. */
     state: 'loading' | 'ready' | 'error';
     /** Transport error message (for the debug surface), when any. */
@@ -32,6 +35,8 @@ export interface PetUiState {
 export type PetUiActions = {
     /** Replace the host snapshot (poll result). */
     setSnapshot: (draft: PetUiState, snapshot: PetStateView) => void;
+    /** Replace the registry list. */
+    setPets: (draft: PetUiState, pets: PetDefinition[]) => void;
     /** Mark the fetch lifecycle. */
     setState: (draft: PetUiState, state: PetUiState['state'], error: string | null) => void;
     /** Show a reaction bubble. */

package/lib/types/client/pet-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pet-store.d.ts","sourceRoot":"","sources":["../../../src/client/pet-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAA;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,IAAI,EAAE,cAAc,GAAG,MAAM,CAAA;IAC7B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;CACX;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,uBAAuB;IACvB,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;IACpC,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;CAC7B;AAED,uBAAuB;AACvB,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;IAChE,gCAAgC;IAChC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvF,8BAA8B;IAC9B,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;CACvE,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,iBAAiB,CAAC,UAAU,EAAE,YAAY,CAAC,CAuB5E;AAED,YAAY,EAAE,cAAc,EAAE,CAAA;AAE9B;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA"}
+{"version":3,"file":"pet-store.d.ts","sourceRoot":"","sources":["../../../src/client/pet-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAA;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,IAAI,EAAE,cAAc,GAAG,MAAM,CAAA;IAC7B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;CACX;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,aAAa,EAAE,CAAA;IACrB,uBAAuB;IACvB,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;IACpC,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;CAC7B;AAED,uBAAuB;AACvB,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;IAChE,iCAAiC;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,IAAI,CAAA;IAC3D,gCAAgC;IAChC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvF,8BAA8B;IAC9B,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;CACvE,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,iBAAiB,CAAC,UAAU,EAAE,YAAY,CAAC,CA2B5E;AAED,YAAY,EAAE,cAAc,EAAE,CAAA;AAE9B;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA"}

package/lib/types/client/pet-store.js

@@ -11,6 +11,7 @@ export function createPetStore() {
     return defineStore({
         init: () => ({
             snapshot: null,
+            pets: [],
             state: 'loading',
             error: null,
             feedback: null,
@@ -21,6 +22,9 @@ export function createPetStore() {
                 draft.state = 'ready';
                 draft.error = null;
             },
+            setPets: (draft, pets) => {
+                draft.pets = pets;
+            },
             setState: (draft, state, error) => {
                 draft.state = state;
                 draft.error = error;

package/lib/types/client/settings-form.d.ts

@@ -18,6 +18,14 @@ export type FieldWrite = {
 export interface FieldSpec {
     /** Field name inside the namespace section. */
     field: string;
+    /**
+     * 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.
+     */
+    secret?: boolean;
     /** Render a stored value as draft text; the empty string when the section carries none. */
     format: (value: unknown) => string;
     /**
@@ -57,6 +65,12 @@ export interface CardShell {
     saving: boolean;
     /** Whether the last save did not land as staged; cleared by the next edit or save. */
     failed: boolean;
+    /**
+     * The rejection code/message the Host returned for the last failed save,
+     * surfaced next to the generic failure text. Undefined while no save has
+     * failed (or the failure carried no server reason).
+     */
+    failedReason?: string;
 }
 /** The write actions the card's slot entry injects. */
 export interface CardActions {
@@ -69,6 +83,37 @@ export interface CardActions {
     /** Drop every staged edit. */
     discard: () => void;
 }
+/** One durable write a batched settings scope performs. */
+export interface BatchedWrite {
+    /** Field this entry writes. */
+    field: string;
+    /** set stores a value; unset drops the leaf. */
+    op: 'set' | 'unset';
+    /** Value for op set (absent for unset). */
+    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;
+}
 /** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
 export interface NumberConstraints {
     /** The accepted value must be a whole number. */
@@ -80,6 +125,13 @@ export interface NumberConstraints {
 export declare function numberField(field: string, constraints?: NumberConstraints): FieldSpec;
 /** A free-text field. An empty draft clears the field. */
 export declare 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.
+ */
+export declare function secretField(field: string): FieldSpec;
 /** A boolean field, edited through true/false draft text. */
 export declare function booleanField(field: string): FieldSpec;
 /** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
@@ -99,6 +151,7 @@ export declare class CardForm<T> {
     private readonly listeners;
     private saving;
     private failed;
+    private failedReason;
     /** @param scope - the bound settings scope for this card's namespace. */
     constructor(scope: SettingsScope<T>, specs: FieldSpec[]);
     /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
@@ -111,9 +164,18 @@ export declare class CardForm<T> {
     actions(): CardActions;
     /**
      * Write every staged edit, then re-seed from what the Host accepted.
+     *
+     * When the scope carries the optional batch surface (the dsh-web-ui
+     * 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.
      */
     save(): Promise<void>;
+    /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
+    private batchedScope;
     /**
      * 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

package/lib/types/client/settings-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-form.d.ts","sourceRoot":"","sources":["../../../src/client/settings-form.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings-form.d.ts","sourceRoot":"","sources":["../../../src/client/settings-form.ts"],"names":[],"mappings":"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"}

package/lib/types/client/settings-form.js

@@ -40,6 +40,15 @@ export function textField(field) {
         },
     };
 }
+/**
+ * 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.
+ */
+export function secretField(field) {
+    return { ...textField(field), secret: true };
+}
 /** A boolean field, edited through true/false draft text. */
 export function booleanField(field) {
     return {
@@ -84,6 +93,7 @@ export class CardForm {
     listeners = new Set();
     saving = false;
     failed = false;
+    failedReason;
     /** @param scope - the bound settings scope for this card's namespace. */
     constructor(scope, specs) {
         this.scope = scope;
@@ -108,6 +118,7 @@ export class CardForm {
             invalid: plan.some(item => item.run === undefined),
             saving: this.saving,
             failed: this.failed,
+            ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
         };
     }
     /** Read one field's state from the effective section and its staged draft. */
@@ -137,37 +148,68 @@ export class CardForm {
                     return;
                 this.staged.clear();
                 this.failed = false;
+                this.failedReason = undefined;
                 this.publish();
             },
         };
     }
     /**
      * Write every staged edit, then re-seed from what the Host accepted.
+     *
+     * When the scope carries the optional batch surface (the dsh-web-ui
+     * 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.
      */
     async save() {
         const plan = this.plan();
-        const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run]);
-        if (plan.length === 0 || this.saving || writes.length !== plan.length)
+        const valid = plan.filter(item => item.run !== undefined);
+        if (plan.length === 0 || this.saving || valid.length !== plan.length)
             return;
+        const plannedWrites = valid.map(item => item.op);
         // Snapshot the fields this save writes, so edits staged while it is in
         // flight survive: only the staged keys this save actually wrote are cleared.
         const fields = new Set(plan.map(item => item.field));
         this.saving = true;
         this.failed = false;
+        this.failedReason = undefined;
         this.publish();
-        let landed = true;
-        for (const write of writes) {
-            landed = await write() && landed;
+        const landed = new Set();
+        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);
+            }
         }
-        if (landed) {
-            for (const field of fields)
+        for (const field of fields) {
+            if (landed.has(field))
                 this.staged.delete(field);
         }
         this.saving = false;
-        this.failed = !landed;
+        this.failed = landed.size !== fields.size;
         this.publish();
     }
+    /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
+    batchedScope() {
+        const candidate = this.scope;
+        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
@@ -181,18 +223,18 @@ export class CardForm {
             const spec = this.specOf(field);
             if (staged.clear) {
                 if (this.stored(field))
-                    plan.push({ field, run: () => this.clear(field) });
+                    plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) });
                 continue;
             }
             if (staged.text === spec.format(this.sectionValue(field)))
                 continue;
             const write = spec.parse(staged.text);
             if (write === undefined)
-                plan.push({ field, run: undefined });
+                plan.push({ field, op: { field, op: 'unset' }, run: undefined });
             else if (write.kind === 'clear')
-                plan.push({ field, run: () => this.clear(field) });
+                plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) });
             else
-                plan.push({ field, run: () => this.store(field, write.value) });
+                plan.push({ field, op: { field, op: 'set', value: write.value }, run: () => this.store(field, write.value) });
         }
         return plan;
     }
@@ -202,11 +244,18 @@ export class CardForm {
     }
     async store(field, value) {
         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.
+        if (this.specOf(field).secret)
+            return true;
         return this.userLayer()?.[field] === value;
     }
     stage(field, edit) {
         this.staged.set(field, edit);
         this.failed = false;
+        this.failedReason = undefined;
         this.publish();
     }
     specOf(field) {