@linxin666/dsh-pet 0.3.6 → 0.3.9

package/lib/types/announce.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The pet announcement-bubble contract (dsh-usage linkage): a sibling plugin
+ * pushes one structured announcement through `pet.announce(...)`, the host
+ * validates it into a bounded payload, and the browser half renders it as a
+ * dedicated, specially styled bubble above the session bubble stack.
+ *
+ * The validation lives in this pure module so the wire contract has exactly
+ * one home and stays testable without the cordis service.
+ * @module @linxin666/dsh-pet/announce
+ */
+/** One plugin-authored announcement bubble. */
+export interface PetAnnouncement {
+    /** Authoring plugin's source tag (`dsh-usage` for the usage statistics). */
+    source: string;
+    /** Bubble content kind: a spend estimate, an account balance, or a plan-quota status. */
+    kind: 'balance' | 'cost' | 'plan';
+    /** Lead text (usually the provider display name). */
+    title: string;
+    /** Balance or today-spend amount, formatted for display (kinds `balance` and `cost`). */
+    amount?: string;
+    /** Plan usage percent 0-100 (kind `plan`). */
+    percent?: number;
+    /** ISO 8601 reset instant (kind `plan`). */
+    resetAt?: string;
+    /** Short trailing note (plan tier name, peak-period status, currency code, ...). */
+    note?: string;
+    /** Visual tone; drives the bubble's accent color. */
+    tone: 'ok' | 'warn' | 'low';
+    /** Freshness window in ms; an expired announcement stops rendering. */
+    ttlMs: number;
+    /** Epoch ms the announcement arrived. */
+    at: number;
+}
+/** Default freshness window. */
+export declare const ANNOUNCE_DEFAULT_TTL_MS = 10000;
+/**
+ * Hard TTL ceiling. A repeating announcer (dsh-usage) declares its poll
+ * cadence as the TTL, so an `always`-mode bubble stays continuous across
+ * polls; the ceiling means a source that dies unmounts its bubble within at
+ * most one missed refresh cycle rather than lingering forever.
+ */
+export declare const ANNOUNCE_MAX_TTL_MS = 7200000;
+/**
+ * Validate one announce payload. Unknown fields are dropped, oversized text
+ * is truncated, and anything structurally wrong resolves to undefined — a
+ * malformed announcement never reaches the pet's bubble surface.
+ * @param input - the payload a sibling plugin passed to `pet.announce`.
+ * @param now - epoch ms the announcement arrived.
+ */
+export declare function parseAnnouncement(input: unknown, now: number): PetAnnouncement | undefined;
+/** Whether an announcement is still fresh at `now`. */
+export declare function announcementFresh(announcement: PetAnnouncement, now: number): boolean;
+//# sourceMappingURL=announce.d.ts.map

package/lib/types/announce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../src/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;IACd,yFAAyF;IACzF,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;IACjC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,KAAK,CAAA;IAC3B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAA;CACX;AAED,gCAAgC;AAChC,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAAY,CAAA;AAc5C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAgC1F;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAErF"}

package/lib/types/announce.js

@@ -0,0 +1,80 @@
+/**
+ * The pet announcement-bubble contract (dsh-usage linkage): a sibling plugin
+ * pushes one structured announcement through `pet.announce(...)`, the host
+ * validates it into a bounded payload, and the browser half renders it as a
+ * dedicated, specially styled bubble above the session bubble stack.
+ *
+ * The validation lives in this pure module so the wire contract has exactly
+ * one home and stays testable without the cordis service.
+ * @module @linxin666/dsh-pet/announce
+ */
+/** Default freshness window. */
+export const ANNOUNCE_DEFAULT_TTL_MS = 10_000;
+/**
+ * Hard TTL ceiling. A repeating announcer (dsh-usage) declares its poll
+ * cadence as the TTL, so an `always`-mode bubble stays continuous across
+ * polls; the ceiling means a source that dies unmounts its bubble within at
+ * most one missed refresh cycle rather than lingering forever.
+ */
+export const ANNOUNCE_MAX_TTL_MS = 7_200_000;
+/** Hard bounds: lengths and the TTL range (1 s .. 60 s). */
+const TITLE_MAX = 80;
+const TEXT_MAX = 120;
+const SOURCE_MAX = 64;
+function boundedString(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return undefined;
+    return trimmed.length <= max ? trimmed : trimmed.slice(0, max);
+}
+/**
+ * Validate one announce payload. Unknown fields are dropped, oversized text
+ * is truncated, and anything structurally wrong resolves to undefined — a
+ * malformed announcement never reaches the pet's bubble surface.
+ * @param input - the payload a sibling plugin passed to `pet.announce`.
+ * @param now - epoch ms the announcement arrived.
+ */
+export function parseAnnouncement(input, now) {
+    if (typeof input !== 'object' || input === null)
+        return undefined;
+    const data = input;
+    const source = boundedString(data.source, SOURCE_MAX);
+    const title = boundedString(data.title, TITLE_MAX);
+    if (source === undefined || title === undefined)
+        return undefined;
+    const kind = data.kind === 'balance' || data.kind === 'cost' || data.kind === 'plan' ? data.kind : undefined;
+    if (kind === undefined)
+        return undefined;
+    const amount = boundedString(data.amount, TEXT_MAX);
+    const resetAt = boundedString(data.resetAt, TEXT_MAX);
+    const note = boundedString(data.note, TITLE_MAX);
+    const percent = typeof data.percent === 'number' && Number.isFinite(data.percent)
+        ? Math.max(0, Math.min(100, data.percent))
+        : undefined;
+    if ((kind === 'balance' || kind === 'cost') && amount === undefined)
+        return undefined;
+    if (kind === 'plan' && percent === undefined)
+        return undefined;
+    const tone = data.tone === 'warn' || data.tone === 'low' ? data.tone : 'ok';
+    const ttlMs = typeof data.ttlMs === 'number' && Number.isFinite(data.ttlMs)
+        ? Math.max(1000, Math.min(ANNOUNCE_MAX_TTL_MS, data.ttlMs))
+        : ANNOUNCE_DEFAULT_TTL_MS;
+    return {
+        source,
+        kind,
+        title,
+        ...(amount !== undefined ? { amount } : {}),
+        ...(percent !== undefined ? { percent } : {}),
+        ...(resetAt !== undefined ? { resetAt } : {}),
+        ...(note !== undefined ? { note } : {}),
+        tone,
+        ttlMs,
+        at: now,
+    };
+}
+/** Whether an announcement is still fresh at `now`. */
+export function announcementFresh(announcement, now) {
+    return now - announcement.at < announcement.ttlMs;
+}

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

@@ -4,10 +4,11 @@
  * it must not ride a session-scoped slot — on the new-conversation screen no
  * session exists to scope a slot by, and the pet would vanish (issue #48).
  * The client half therefore mounts this entry straight onto 'document.body'
- * (see index.ts): while visible it renders the floating PetSprite (a
- * portal), while hidden it renders a fixed-position summon button. Which
- * sprite renders is decided by the host snapshot's pet id resolved against
- * the registry list — no per-pet component exists.
+ * (see index.ts): while visible it renders the floating PetSprite (a portal
+ * into the plugin root, so the root owns the whole surface), while hidden it
+ * renders a fixed-position summon button. Which sprite renders is decided by
+ * the host snapshot's pet id resolved against the registry list — no per-pet
+ * component exists.
  * @module @linxin666/dsh-pet/client/PetDockEntry
  */
 import { type ReactElement } from 'react';
@@ -41,7 +42,15 @@ export interface PetInjected {
     gameplay: GameplayApi;
 }
 /** Composed props of the global pet entry (locale + injected; no slot runtime share). */
-export type PetDockEntryProps = PetInjected & PropsLocale<typeof NS>;
+export type PetDockEntryProps = PetInjected & PropsLocale<typeof NS> & {
+    /**
+     * DOM node the floating sprite chrome portals into. Defaults to
+     * document.body; the plugin apply passes its [data-dsh-plugin="pet"]
+     * root so root-keyed suppressors (the portrait mobile layer) and skins
+     * own the whole pet surface as one unit.
+     */
+    portalTarget?: Element;
+};
 /**
  * Dock entry: while the pet is visible, mount the floating PetSprite (it
  * portals itself onto document.body); while hidden, render the summon

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

@@ -1 +1 @@
-{"version":3,"file":"PetDockEntry.d.ts","sourceRoot":"","sources":["../../../src/client/PetDockEntry.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAItD,OAAO,EAAe,KAAK,WAAW,EAAoB,MAAM,oBAAoB,CAAA;AACpF,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,CAAA;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAA;IACf,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,2DAA2D;IAC3D,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,iCAAiC;IACjC,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,uGAAuG;IACvG,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAC3B,WAAW,GACT,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;AAI1B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAwFnE"}
+{"version":3,"file":"PetDockEntry.d.ts","sourceRoot":"","sources":["../../../src/client/PetDockEntry.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAItD,OAAO,EAAe,KAAK,WAAW,EAAoB,MAAM,oBAAoB,CAAA;AACpF,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,CAAA;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAA;IACf,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,2DAA2D;IAC3D,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,iCAAiC;IACjC,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,uGAAuG;IACvG,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAC3B,WAAW,GACT,WAAW,CAAC,OAAO,EAAE,CAAC,GACtB;IACA;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAIH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAyFnE"}

package/lib/types/client/PetDockEntry.js

@@ -5,10 +5,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * it must not ride a session-scoped slot — on the new-conversation screen no
  * session exists to scope a slot by, and the pet would vanish (issue #48).
  * The client half therefore mounts this entry straight onto 'document.body'
- * (see index.ts): while visible it renders the floating PetSprite (a
- * portal), while hidden it renders a fixed-position summon button. Which
- * sprite renders is decided by the host snapshot's pet id resolved against
- * the registry list — no per-pet component exists.
+ * (see index.ts): while visible it renders the floating PetSprite (a portal
+ * into the plugin root, so the root owns the whole surface), while hidden it
+ * renders a fixed-position summon button. Which sprite renders is decided by
+ * the host snapshot's pet id resolved against the registry list — no per-pet
+ * component exists.
  * @module @linxin666/dsh-pet/client/PetDockEntry
  */
 import { useEffect, useRef, useSyncExternalStore } from 'react';
@@ -46,7 +47,7 @@ export function PetDockEntry(props) {
     if (visible) {
         return (_jsx("span", { "data-pet-dock": true, "data-testid": "pet-dock", children: snapshot === null || definition === null
                 ? null
-                : (_jsx(PetRendererSwitch, { definition: definition, phase: snapshot?.phase ?? 'idle', onPet: props.pet, ...(aux === null ? {} : { drag: aux.drag, bus: aux.bus }), t: props.t, children: _jsx(PetSprite, { snapshot: snapshot, definition: definition, display: snapshot.display, feedback: feedback, onPet: props.pet, onFeed: props.feed, onHide: props.hide, onDragEnd: props.dragEnd, onRename: props.rename, onOpenSession: props.openSession, onFeedbackDone: props.feedbackDone, dragDisabled: snapshot.gameplay?.mode === 'work', ...(gameplay === undefined || aux === null
+                : (_jsx(PetRendererSwitch, { definition: definition, phase: snapshot?.phase ?? 'idle', onPet: props.pet, ...(aux === null ? {} : { drag: aux.drag, bus: aux.bus }), t: props.t, children: _jsx(PetSprite, { snapshot: snapshot, definition: definition, display: snapshot.display, feedback: feedback, onPet: props.pet, onFeed: props.feed, onHide: props.hide, onDragEnd: props.dragEnd, onRename: props.rename, onOpenSession: props.openSession, onFeedbackDone: props.feedbackDone, portalTarget: props.portalTarget, dragDisabled: snapshot.gameplay?.mode === 'work', ...(gameplay === undefined || aux === null
                             ? {}
                             : {
                                 onGameplayTap: (fx, fy) => aux.bus.tap?.(fx, fy),

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

@@ -8,7 +8,8 @@
  */
 import type { ReactNode } from 'react';
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
-import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import { type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts';
 /** The pet's settings fields this card edits (the namespace's full schema). */
 export interface PetSettings {

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

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

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

@@ -68,6 +68,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>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"PetSprite.d.ts","sourceRoot":"","sources":["../../../src/client/PetSprite.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAkE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGnH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAIjD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,8EAA8E;IAC9E,UAAU,EAAE,aAAa,CAAA;IACzB,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,CAAA;IACzB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9C,uDAAuD;IACvD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,4DAA4D;IAC5D,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;IAC3B,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,+CAA+C;IAC/C,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;CAC1B;AAgGD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CA6iB5D"}
+{"version":3,"file":"PetSprite.d.ts","sourceRoot":"","sources":["../../../src/client/PetSprite.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAkE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGnH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAIjD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,8EAA8E;IAC9E,UAAU,EAAE,aAAa,CAAA;IACzB,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,CAAA;IACzB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9C,uDAAuD;IACvD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,4DAA4D;IAC5D,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;IAC3B,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,+CAA+C;IAC/C,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;CAC1B;AA8ID;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAqjB5D"}

package/lib/types/client/PetSprite.js

@@ -12,6 +12,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import clsx from 'clsx';
+import { announcementFresh } from "../announce.js";
 import { framePosition, rowOfTrack, trimTrack } from "./spritesheet.js";
 import { sequenceFrameAt } from "./sequences.js";
 import { animationForPhase } from "../state.js";
@@ -108,6 +109,23 @@ function StatusOrnament(props) {
             backgroundPosition: '0px 0px',
         } }));
 }
+/**
+ * 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) {
+    const { announcement } = props;
+    const tone = announcement.tone === 'low'
+        ? styles.bubbleUsageLow
+        : announcement.tone === 'warn'
+            ? styles.bubbleUsageWarn
+            : styles.bubbleUsageOk;
+    return (_jsxs("div", { className: clsx(styles.bubble, styles.bubbleUsage, tone), role: "status", "aria-live": "polite", "data-dsh-pet-announcement": announcement.source, children: [_jsxs("span", { className: styles.bubbleUsageHead, children: [_jsx("span", { className: styles.bubbleUsageTitle, children: announcement.title }), (announcement.kind === 'balance' || announcement.kind === 'cost') && announcement.amount !== undefined && (_jsx("span", { className: styles.bubbleUsageValue, children: announcement.amount })), announcement.kind === 'plan' && announcement.percent !== undefined && (_jsx("span", { className: styles.bubbleUsageValue, children: Math.round(announcement.percent) + '%' }))] }), announcement.kind === 'plan' && announcement.percent !== undefined && (_jsx("span", { className: styles.bubbleUsageMeter, children: _jsx("span", { className: styles.bubbleUsageMeterFill, style: { width: Math.min(100, Math.max(0, announcement.percent)) + '%' } }) })), announcement.note !== undefined && (_jsx("span", { className: styles.bubbleUsageNote, children: announcement.note }))] }));
+}
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
  * with per-frame durations from the definition's tracks; the atlas image is
@@ -360,6 +378,13 @@ export function PetSprite(props) {
     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
@@ -367,7 +392,7 @@ export function PetSprite(props) {
     // 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;
@@ -447,7 +472,7 @@ export function PetSprite(props) {
                             }
                         }
                         props.onPet();
-                    }, role: "button", "aria-label": definition.displayName, children: props.visual }) }), props.hud, feedback !== null && (_jsx("div", { ref: bubbleRef, className: clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet), children: feedback.text }, feedback.at)), feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined) && (_jsxs("div", { ref: bubbleRef, className: styles.bubbleStack, onPointerEnter: () => setStackPeek(true), onPointerLeave: () => setStackPeek(false), children: [visibleSessions.map((session, index) => {
+                    }, role: "button", "aria-label": definition.displayName, children: props.visual }) }), props.hud, feedback !== null && (_jsx("div", { ref: bubbleRef, className: clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet), children: feedback.text }, feedback.at)), feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined) && (_jsxs("div", { ref: bubbleRef, className: styles.bubbleStack, onPointerEnter: () => setStackPeek(true), onPointerLeave: () => setStackPeek(false), children: [visibleSessions.map((session, index) => {
                         // A session's whisper rides ITS OWN bubble (the stack lead when
                         // the current session has one, any bubble when the stack is
                         // expanded). The key swap restarts the entrance animation so the
@@ -466,7 +491,7 @@ export function PetSprite(props) {
                                         e.stopPropagation();
                                         setStackPinned(open => !open);
                                     }, children: stackOpen ? '×' : '+' + String(sessionBubbles.length - 1) })] }, "primary"));
-                    }), sessionBubbles.length === 0 && statusBubble !== undefined && (_jsxs("div", { className: clsx(styles.bubble, styles.bubbleStatus), role: "status", "aria-live": "polite", children: [decoration !== undefined && (_jsx(StatusOrnament, { decoration: decoration, phase: phase })), statusBubble] }, "status"))] })), hovered && dragRef.current === null && (_jsx("div", { ref: panelRef, className: clsx(styles.panel, panelAbove && styles.panelAbove), "data-placement": panelAbove ? 'above' : 'below', style: panelAbove && panelLift > 0
+                    }), sessionBubbles.length === 0 && statusBubble !== undefined && (_jsxs("div", { className: clsx(styles.bubble, styles.bubbleStatus), role: "status", "aria-live": "polite", children: [decoration !== undefined && (_jsx(StatusOrnament, { decoration: decoration, phase: phase })), statusBubble] }, "status")), usageAnnouncement !== undefined && _jsx(UsageAnnouncementBubble, { announcement: usageAnnouncement })] })), hovered && dragRef.current === null && (_jsx("div", { ref: panelRef, className: clsx(styles.panel, panelAbove && styles.panelAbove), "data-placement": panelAbove ? 'above' : 'below', style: panelAbove && panelLift > 0
                     ? { marginBottom: panelLift }
                     : undefined, onPointerEnter: () => {
                     // Reaching the panel (or its bridge) must cancel any hide timer
@@ -511,5 +536,5 @@ export function PetSprite(props) {
                                         setNameDraft(displayName);
                                         setRenaming(true);
                                     }, children: panelLabel('rename', props.t('pet.rename')) })), panelShows('hide') && (_jsx("button", { type: "button", className: styles.action, onClick: props.onHide, children: panelLabel('hide', props.t('pet.hide')) })), props.onGameplayMenu !== undefined && (_jsx("button", { type: "button", className: styles.action, onClick: props.onGameplayMenu, children: props.t('pet.gameplay.menu') }))] })] })) }))] }));
-    return createPortal(float, document.body);
+    return createPortal(float, props.portalTarget ?? document.body);
 }

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

@@ -4,13 +4,16 @@
  * 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, SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client';
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client';
 /** Required services (sessions powers bubble-to-session navigation). */
 export declare const inject: string[];
 /** Re-exported for consumers that type against the injected face. */

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;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAwB,aAAa,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AA4EnI,wEAAwE;AACxE,eAAO,MAAM,MAAM,UAA2E,CAAA;AAE9F,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,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACpE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,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,CAgT9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnE,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAA;AA8ElG,wEAAwE;AACxE,eAAO,MAAM,MAAM,UAA2E,CAAA;AAE9F,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,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACpE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,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,CAoT9C"}

package/lib/types/client/index.js

@@ -4,10 +4,12 @@
  * 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 { createElement } from 'react';
@@ -325,7 +327,11 @@ export function apply(ctx) {
             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 = () => {
                 if (uiGone)

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

@@ -72,7 +72,7 @@ export declare const zh: {
     readonly 'settings.off': "关";
     readonly 'settings.overridden': "已覆盖";
     readonly 'settings.reset': "恢复默认";
-    readonly 'settings.notExposed': "当前 DSH 版本未向设置页暴露本插件的配置命名空间，表单不可用。可编辑 ~/.dsh/settings.yaml 直接配置，或为 dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES 白名单补充本命名空间后重启。";
+    readonly 'settings.notExposed': "当前 DSH 版本未向设置页暴露本插件的配置命名空间，表单不可用。可编辑 $DSH_HOME/settings.yaml 直接配置，或确认提供该命名空间的插件已挂载其设置域并重启。";
     readonly 'settings.readOnly': "当前部署的设置只读。";
     readonly 'settings.expand': "展开设置";
     readonly 'settings.collapse': "收起设置";
@@ -151,7 +151,7 @@ export declare const en: {
     readonly 'settings.off': "Off";
     readonly 'settings.overridden': "Overridden";
     readonly 'settings.reset': "Reset to default";
-    readonly '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.";
+    readonly '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.";
     readonly 'settings.readOnly': "This deployment stores settings read-only.";
     readonly 'settings.expand': "Show settings";
     readonly 'settings.collapse': "Hide settings";

package/lib/types/client/locales.js

@@ -74,7 +74,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': '收起设置',
@@ -155,7 +155,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/lib/types/client/pet-store.d.ts

@@ -5,7 +5,7 @@
  * only ever read snapshots.
  * @module @linxin666/dsh-pet/client/pet-store
  */
-import type { EngineStoreHandle, EngineStoreInstance } from '@deepseek-ai/dsh-client-runtime/client';
+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/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,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACvE,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;IACtE;;;;OAIG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAA;CACzE,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,iBAAiB,CAAC,UAAU,EAAE,YAAY,CAAC,CA8B5E;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,+BAA+B,CAAA;AAC3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACvE,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;IACtE;;;;OAIG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAA;CACzE,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,iBAAiB,CAAC,UAAU,EAAE,YAAY,CAAC,CA8B5E;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

@@ -5,7 +5,7 @@
  * only ever read snapshots.
  * @module @linxin666/dsh-pet/client/pet-store
  */
-import { defineStore } from '@deepseek-ai/dsh-client-runtime/client';
+import { defineStore } from '@deepseek-ai/dsh-client-store';
 /** Create the pet store handle (apply world only; never module-level). */
 export function createPetStore() {
     return defineStore({

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

@@ -6,7 +6,8 @@
  * each plugin's client bundle; mirrors the official ui-plugin-config
  * card-store pattern.
  */
-import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 /** The write one field's staged text performs when the card is saved. */
 export type FieldWrite = {
     kind: 'set';
@@ -21,9 +22,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. */
@@ -49,8 +52,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.
      */
@@ -83,7 +86,7 @@ export interface CardActions {
     /** Drop every staged edit. */
     discard: () => void;
 }
-/** 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;
@@ -92,28 +95,6 @@ export interface BatchedWrite {
     /** 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. */
@@ -128,8 +109,8 @@ 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.
+ * but a save never compares the redacted value back: the staged set is judged
+ * by the mutation settling (see {@link FieldSpec.secret}).
  */
 export declare function secretField(field: string): FieldSpec;
 /** A boolean field, edited through true/false draft text. */
@@ -171,19 +152,22 @@ export declare class CardForm<T> {
     /** The actions the card's slot registration injects. */
     actions(): CardActions;
     /**
-     * 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.
      */
     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
@@ -192,8 +176,16 @@ export declare class CardForm<T> {
      * @returns the planned writes, in the order the fields were staged.
      */
     private plan;
-    private clear;
-    private store;
+    /**
+     * Read-back judgment for a planned set: the user layer must hold the
+     * intended value once the mutation has settled.
+     */
+    private landedSet;
+    /**
+     * Read-back judgment for a planned unset: the field must be gone from the
+     * user layer once the mutation has settled.
+     */
+    private landedUnset;
     private stage;
     private specOf;
     private snapshotOf;