@linxin666/dsh-pet 0.1.14 → 0.1.16

package/src/client/pet-store.ts

@@ -10,6 +10,7 @@ import { defineStore } from '@deepseek-ai/dsh-client-runtime/client'
 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 {
@@ -25,6 +26,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. */
@@ -37,6 +40,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. */
@@ -48,6 +53,7 @@ export function createPetStore(): EngineStoreHandle<PetUiState, PetUiActions> {
   return defineStore({
     init: (): PetUiState => ({
       snapshot: null,
+      pets: [],
       state: 'loading',
       error: null,
       feedback: null,
@@ -58,6 +64,9 @@ export function createPetStore(): EngineStoreHandle<PetUiState, PetUiActions> {
         draft.state = 'ready'
         draft.error = null
       },
+      setPets: (draft, pets) => {
+        draft.pets = pets
+      },
       setState: (draft, state, error) => {
         draft.state = state
         draft.error = error

package/src/client/settings-card.module.css

@@ -1,3 +1,4 @@
+/* Generated by scripts/sync-shared.mjs from shared/client/settings/settings-card.module.css. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs". */
 /* Plugin settings card chrome + staged form fields.
  * Aligned with the official ui-settings-plugins PluginCard / fields CSS:
  * same semantic tokens, radius, typography and states so family cards read
@@ -120,6 +121,9 @@
   margin: 0;
   font-size: 12px;
   line-height: 1.5;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  white-space: nowrap;
 }
 
 .discard,
@@ -229,6 +233,11 @@
   outline-offset: 2px;
 }
 
+.reset:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: 2px;
+}
+
 .input,
 .select {
   border: 1px solid var(--dsw-alias-border-l2);

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -19,6 +20,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
   /**
@@ -60,6 +69,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. */
@@ -86,12 +101,63 @@ interface StagedEdit {
 interface PlannedWrite {
   /** Field this entry writes. */
   field: string
+  /** The durable write this entry performs, described for a batched scope. */
+  op: BatchedWrite
   /** Perform the write and report whether the Host holds the staged value afterwards. */
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** 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
+}
+
+/** 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. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +165,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -116,19 +185,43 @@ 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.
+ */
+export function secretField(field: string): FieldSpec {
+  return { ...textField(field), secret: true }
+}
+
 /** A boolean field, edited through true/false draft text. */
 export function booleanField(field: string): FieldSpec {
   return {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -143,6 +236,7 @@ export class CardForm<T> {
   private readonly listeners = new Set<() => void>()
   private saving = false
   private failed = false
+  private failedReason: string | undefined
 
   /** @param scope - the bound settings scope for this card's namespace. */
   constructor(
@@ -172,6 +266,7 @@ export class CardForm<T> {
       invalid: plan.some(item => item.run === undefined),
       saving: this.saving,
       failed: this.failed,
+      ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
     }
   }
 
@@ -202,6 +297,7 @@ export class CardForm<T> {
         if (this.staged.size === 0 && !this.failed) return
         this.staged.clear()
         this.failed = false
+        this.failedReason = undefined
         this.publish()
       },
     }
@@ -209,25 +305,57 @@ export class CardForm<T> {
 
   /**
    * 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(): Promise<void> {
     const plan = this.plan()
-    const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
-    if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    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<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)
+      }
+    }
+    for (const field of fields) {
+      if (landed.has(field)) this.staged.delete(field)
     }
-    if (landed) this.staged.clear()
     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. */
+  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
@@ -240,14 +368,14 @@ 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, run: () => this.clear(field) })
+        if (this.stored(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 })
-      else if (write.kind === 'clear') plan.push({ field, run: () => this.clear(field) })
-      else plan.push({ field, run: () => this.store(field, write.value) })
+      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) })
     }
     return plan
   }
@@ -259,12 +387,18 @@ export class CardForm<T> {
 
   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.
+    if (this.specOf(field).secret) return true
     return this.userLayer()?.[field] === value
   }
 
   private stage(field: string, edit: StagedEdit): void {
     this.staged.set(field, edit)
     this.failed = false
+    this.failedReason = undefined
     this.publish()
   }
 

package/src/client/spritesheet.ts

@@ -1,57 +1,19 @@
 /**
- * Whale-girl spritesheet geometry and animation tracks.
- *
- * The atlas follows the Codex/hatch-pet contract: 8 columns × 9 rows of
- * 192×208 cells (1536×1872 total), rows in this order:
- *   0 idle, 1 running-right, 2 running-left, 3 waving, 4 jumping,
- *   5 failed, 6 waiting, 7 running, 8 review
- *
- * Frame counts and per-frame durations are per-track definitions below; the
- * whale-girl atlas is produced by the hatch-pet pipeline, so calibrate
- * `TRACKS` against the actual run (`pet_request.json` frame counts) when the
- * asset lands. Tracks that do not loop hand off to `fallback`.
+ * Spritesheet geometry helpers — parameterized by the pet definition the
+ * host serves over '/api/pet/pets', so the browser half renders any registry
+ * entry without per-pet code. The per-track tables (frames, durations, loop,
+ * fallback) also come from the registry; these helpers only place frames,
+ * guard track lengths, and map the fixed 9-row animation contract.
  * @module @linxin666/dsh-pet/client/spritesheet
  */
 
 import type { PetAnimation } from '../state.ts'
+import type { PetCell, PetTrackDef } from '../registry.ts'
 
-/** Atlas cell size in px (Codex contract). */
-export const FRAME_WIDTH = 192
-export const FRAME_HEIGHT = 208
-/** Columns per row (max frames per track). */
-export const FRAME_COLUMNS = 8
+/** Animation track shape the frame loop consumes. */
+export type TrackDef = PetTrackDef
 
-/** One animation track: frame indices into the row + per-frame durations. */
-export interface TrackDef {
-  /** Frame indices (columns) played in order; must be < FRAME_COLUMNS. */
-  frames: readonly number[]
-  /** Per-frame duration in ms; same length as frames. */
-  durations: readonly number[]
-  /** Whether the track loops; a non-looping track hands off to fallback. */
-  loop: boolean
-  /** Track to play after a non-looping track finishes. */
-  fallback?: PetAnimation
-}
-
-/**
- * Track definitions for the whale-girl. Durations are tuned for a soft,
- * slow-healing feel (roughly 2.5× the earlier fast draft — the pet should
- * breathe, not race); calibrate frame counts against the hatch-pet run when
- * the asset lands (rows may carry 4–8 frames).
- */
-export const TRACKS: Record<PetAnimation, TrackDef> = {
-  idle: { frames: [0, 1, 2, 3, 4, 5], durations: [400, 400, 500, 400, 400, 500], loop: true },
-  'running-right': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
-  'running-left': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
-  waving: { frames: [0, 1, 2, 3], durations: [350, 350, 350, 350], loop: true },
-  jumping: { frames: [0, 1, 2, 3, 4], durations: [300, 300, 300, 350, 350], loop: false, fallback: 'idle' },
-  failed: { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [450, 450, 450, 500, 550, 600, 450, 450], loop: false, fallback: 'idle' },
-  waiting: { frames: [0, 1, 2, 3, 4, 5], durations: [450, 450, 500, 450, 450, 500], loop: true },
-  running: { frames: [0, 1, 2, 3, 4, 5], durations: [250, 250, 250, 250, 250, 250], loop: true },
-  review: { frames: [0, 1, 2, 3, 4, 5], durations: [550, 550, 550, 550, 550, 550], loop: true },
-}
-
-/** Row index of one animation track (mirrors state.ts rowOf). */
+/** Row index of one animation track (the fixed 9-row contract). */
 export function rowOfTrack(animation: PetAnimation): number {
   const rows: Record<PetAnimation, number> = {
     idle: 0,
@@ -74,8 +36,8 @@ export function rowOfTrack(animation: PetAnimation): number {
  * atlas coordinates here would drift each frame by the scale factor and
  * render torn/overlapping frames.
  */
-export function framePosition(row: number, col: number, scale = 1): { x: number; y: number } {
-  return { x: -col * FRAME_WIDTH * scale, y: -row * FRAME_HEIGHT * scale }
+export function framePosition(cell: PetCell, columns: number, row: number, col: number, scale = 1): { x: number; y: number } {
+  return { x: -col * cell.width * scale, y: -row * cell.height * scale }
 }
 
 /** Total duration of one track, ms. */
@@ -84,51 +46,13 @@ export function trackDuration(track: TrackDef): number {
 }
 
 /**
- * Detect how many frames each row actually carries by scanning the decoded
- * atlas for non-transparent cells (hatch-pet rows may hold 4–8 frames; the
- * unused trailing cells are fully transparent). Rows whose every sample is
- * transparent report 0.
- * @param image - the fully decoded spritesheet (natural size 1536×1872).
- * @returns per-row frame counts, length 9.
- */
-export function detectFrameCounts(image: HTMLImageElement): number[] {
-  const canvas = document.createElement('canvas')
-  canvas.width = image.naturalWidth
-  canvas.height = image.naturalHeight
-  const ctx = canvas.getContext('2d')
-  if (ctx === null) return Array.from({ length: 9 }, () => FRAME_COLUMNS)
-  ctx.drawImage(image, 0, 0)
-  const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data
-  const counts: number[] = []
-  const stride = FRAME_COLUMNS * FRAME_WIDTH
-  const probeStep = 8
-  const margin = 12
-  for (let row = 0; row < 9; row++) {
-    let count = 0
-    for (let col = 0; col < FRAME_COLUMNS; col++) {
-      let hasContent = false
-      const x0 = col * FRAME_WIDTH
-      const y0 = row * FRAME_HEIGHT
-      for (let y = y0 + margin; y < y0 + FRAME_HEIGHT - margin && !hasContent; y += probeStep) {
-        for (let x = x0 + margin; x < x0 + FRAME_WIDTH - margin && !hasContent; x += probeStep) {
-          const idx = (y * stride + x) * 4
-          if ((data[idx + 3] ?? 0) > 8) hasContent = true
-        }
-      }
-      if (hasContent) count += 1
-    }
-    counts.push(count)
-  }
-  return counts
-}
-
-/**
- * Trim a track to the actual frame count of its row. A row with 0 detected
- * frames degrades to the first frame (the atlas is still loading or corrupt)
- * so the pet never renders blank.
+ * Trim a track to the actual frame count of its row (the manifest's per-row
+ * counts are authoritative; this is a last-line guard against a definition
+ * whose row count disagrees with its track table). A row with 0 detected
+ * frames degrades to the first frame so the pet never renders blank.
  */
 export function trimTrack(track: TrackDef, frameCount: number): TrackDef {
-  const n = Math.max(1, Math.min(frameCount, track.frames.length))
+  const n = Math.max(1, Math.min(frameCount, track.frames.length, track.durations.length))
   return {
     frames: track.frames.slice(0, n),
     durations: track.durations.slice(0, n),

package/src/dsh-home.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { join } from 'node:path'
+import { expandHome, resolveDshHome } from './dsh-home.ts'
+import { petHomeDir } from './persist.ts'
+
+describe('resolveDshHome', () => {
+  it('falls back to ~/.dsh when DSH_HOME is unset', () => {
+    const home = join('/home', 'tester')
+    expect(resolveDshHome({}, home)).toBe(join(home, '.dsh'))
+  })
+
+  it('prefers the DSH_HOME env override', () => {
+    const home = join('/home', 'tester')
+    expect(resolveDshHome({ DSH_HOME: '/custom/dsh' }, home)).toBe('/custom/dsh')
+  })
+
+  it('expands a leading ~ (and ~/) against the platform home', () => {
+    const home = join('/home', 'tester')
+    expect(resolveDshHome({ DSH_HOME: '~/data' }, home)).toBe(join(home, 'data'))
+    expect(expandHome('~', home)).toBe(home)
+  })
+
+  it('joins a relative DSH_HOME onto the working directory', () => {
+    const home = join('/home', 'tester')
+    const rel = resolveDshHome({ DSH_HOME: 'rel/dsh' }, home)
+    expect(rel).not.toBe('rel/dsh')
+    expect(rel).toBe(join(process.cwd(), 'rel/dsh'))
+  })
+})
+
+describe('petHomeDir delegates to the shared DSH_HOME resolution', () => {
+  it('returns the same value as dshHome under the same env', () => {
+    expect(petHomeDir).toBeTypeOf('function')
+  })
+})

package/src/dsh-home.ts

@@ -0,0 +1,36 @@
+// Generated by scripts/sync-shared.mjs from shared/host/dsh-home.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export function expandHome(path: string, home: string = homedir()): string {
+  if (path === '~') return home
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(home, path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  const raw = env.DSH_HOME
+  if (raw !== undefined && raw.trim() !== '') {
+    const expanded = expandHome(raw.trim(), home)
+    return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded)
+  }
+  return join(home, '.dsh')
+}
+
+/** Resolve the DSH home directory from the live environment. */
+export function dshHome(): string {
+  return resolveDshHome()
+}