@linxin666/dsh-pet 0.1.15 → 0.1.16

package/src/client/PluginSettingsCard.tsx

@@ -138,7 +138,13 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
             {!state.writable ? <p className={css.readOnly} role="status">{props.t('settings.readOnly')}</p> : null}
             {props.children}
             <div className={css.footer}>
-              {state.failed ? <p className={css.failed} role="status">{props.t('settings.saveFailed')}</p> : null}
+              {state.failed
+                ? (
+                  <p className={css.failed} role="status">
+                    {props.t('settings.saveFailed')}{state.failedReason ? ' - ' + state.failedReason : ''}
+                  </p>
+                )
+                : null}
               <button
                 type="button"
                 className={css.discard}

package/src/client/index.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
  */
@@ -20,6 +21,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetInteractResult, PetStateView } from '../service.ts'
 import type { PetInteraction } from '../affinity.ts'
+import type { PetDefinition } from '../registry.ts'
 import { createElement } from 'react'
 import { createRoot } from 'react-dom/client'
 import { createPetStore, type PetStoreInstance } from './pet-store.ts'
@@ -30,10 +32,12 @@ import { NS, en, zh, t } from './locales.ts'
 /** The host pet API as the browser sees it (same-origin JSON endpoints). */
 interface PetHttpApi {
   state(): Promise<PetStateView>
+  pets(): Promise<PetDefinition[]>
   interact(kind: PetInteraction): Promise<PetInteractResult>
   setVisible(visible: boolean): Promise<{ ok: true; display: PetDisplayConfig }>
   setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }>
   setName(name: string): Promise<{ ok: true; name: string } | { ok: false; error: string }>
+  setPet(petId: string): Promise<{ ok: true; petId: string } | { ok: false; error: string }>
 }
 
 /** Same-origin JSON fetch helper (GET without body, POST with JSON body). */
@@ -46,7 +50,7 @@ async function petFetch<T>(path: string, body?: unknown): Promise<T> {
         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()) as T
 }
@@ -54,10 +58,12 @@ async function petFetch<T>(path: string, body?: unknown): Promise<T> {
 /** The live host API instance (always defined; failures surface per call). */
 const petApi: PetHttpApi = {
   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. */
@@ -71,14 +77,16 @@ export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote
 
 /** 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.
      */
@@ -103,7 +111,6 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
-
 /**
  * Client plugin body: register dictionaries, mount the global pet entry and
  * poll loop while the plugin is enabled, and seat the settings card in the
@@ -122,8 +129,9 @@ export function apply(ctx: ClientContext): void {
       : 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',
@@ -145,10 +153,24 @@ export function apply(ctx: ClientContext): void {
       // it stateless on the new-conversation screen (no session to scope by).
       const petStore: PetStoreInstance = 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 = (): void => {
+        if (!petsLoaded) {
+          petApi.pets().then((list) => {
+            petsLoaded = true
+            setPets(list)
+          }, () => {
+            // Retry on the next poll tick.
+          })
+        }
         petApi.state().then((snapshot) => {
           setSnapshot(snapshot)
         }, () => {
@@ -253,8 +275,8 @@ export function apply(ctx: ClientContext): void {
       // 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/src/client/locales.ts

@@ -17,11 +17,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': '显示宠物',
@@ -32,8 +34,6 @@ export const zh = {
   'settings.rightHint': '距视口右边缘的水平内缩距离。',
   'settings.bottom': '距底部（px）',
   'settings.bottomHint': '距视口底边的垂直内缩距离。',
-  'settings.name': '名字',
-  'settings.nameHint': '宠物显示名，1–20 个字符。',
   'settings.inherit': '继承',
   'settings.on': '开',
   'settings.off': '关',
@@ -62,11 +62,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',
@@ -77,8 +79,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/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

@@ -121,6 +121,9 @@
   margin: 0;
   font-size: 12px;
   line-height: 1.5;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  white-space: nowrap;
 }
 
 .discard,

package/src/client/settings-form.ts

@@ -20,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
   /**
@@ -61,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. */
@@ -87,10 +101,52 @@ 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
 }
 
+/** 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. */
@@ -129,6 +185,16 @@ 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 {
@@ -170,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(
@@ -199,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 },
     }
   }
 
@@ -229,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()
       },
     }
@@ -236,30 +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)
+      }
     }
-    if (landed) {
-      for (const field of fields) this.staged.delete(field)
+    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. */
+  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
@@ -272,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
   }
@@ -291,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/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { makePetSettingsSchema } from './index.ts'
+
+describe('makePetSettingsSchema', () => {
+  it('resolves the selected pet and display defaults from an empty section', () => {
+    const schema = makePetSettingsSchema('whale-girl')
+    expect(schema({})).toMatchObject({
+      petId: 'whale-girl',
+      visible: true,
+      size: 160,
+      right: 24,
+      bottom: 20,
+      enabled: true,
+    })
+  })
+
+  it('accepts any petId string so a removed pet cannot brick the namespace', () => {
+    // The service clamps the value against the registry; the schema must
+    // never reject a stale stored selection outright.
+    const schema = makePetSettingsSchema('whale-girl')
+    expect(schema({ petId: 'dragon' }).petId).toBe('dragon')
+  })
+})